fix(otp): fall back to email for foreign phone numbers

The SMS gateway is domestic-only, but OTP sends fanned out to any phone
on the account - a foreign number meant a code queued into the void
while the response claimed success. isDomesticPhone (+2519/+2517 E.164)
now gates SMS: dual-channel sends with a foreign phone go email-only
(the phone stays on the row so verify still matches it), and a
phone-only foreign target still tries SMS as the only route. The
staff-triggered reset exposes phoneIsDomestic so the backoffice disables
the SMS channel with an explanation, and the API refuses the channel
directly for foreign numbers.

EDRFREIGHT-186

apps/edr-freight-api/src/modules/otp/otp.service.ts

@@ -46,6 +46,16 @@ function normalizePhone(rawPhone: string): string {
   return digits.length >= 11 ? `+${digits}` : raw;
 }
 
+/**
+ * Whether a phone is an Ethiopian mobile the SMS gateway can actually reach —
+ * the carrier integration is domestic-only, so a send to anything else is
+ * queued and silently lost. Callers use this to fall back to email instead of
+ * pretending an SMS is on its way.
+ */
+export function isDomesticPhone(rawPhone: string): boolean {
+  return /^\+251[79]\d{8}$/.test(normalizePhone(rawPhone));
+}
+
 /**
  * Canonicalise every channel present on the target. Each field is normalised
  * independently — a dual-channel target must end up with both halves in their
@@ -143,6 +153,20 @@ export class OtpService {
       // /otp/verify routes (a NestJS ThrottlerGuard / @Throttle) — none exists
       // in the codebase yet.
 
+      // A foreign number is unreachable by the domestic-only SMS gateway; when
+      // email is also on the target, go email-only rather than queueing an SMS
+      // that will never arrive. With no email the SMS attempt stays — it is the
+      // only route there is.
+      const smsPhone =
+        target.phone && (!target.email || isDomesticPhone(target.phone))
+          ? target.phone
+          : null;
+      if (target.phone && !smsPhone) {
+        this.logger.warn(
+          `otp.dispatch.sms-skipped target=${label} — non-domestic phone, delivering via email only`,
+        );
+      }
+
       // Fan out to every channel the target has, independently: one transport
       // being down must not suppress the other, which is the whole point of
       // sending to both. Each helper swallows its own failure so a rejected
@@ -150,7 +174,7 @@ export class OtpService {
       const outcomes = (
         await Promise.all([
           target.email ? this.dispatchEmail(target.email, otp) : null,
-          target.phone ? this.dispatchSms(target.phone, otp) : null,
+          smsPhone ? this.dispatchSms(smsPhone, otp) : null,
         ])
       ).filter((outcome): outcome is DispatchOutcome => outcome !== null);