@velion-la/onboarding-sdk-react-native 1.0.0-beta.2

package/src/utils/EventEmitter.ts

@@ -0,0 +1,155 @@
+/**
+ * @fileoverview Typed, memory-safe EventEmitter for internal SDK communication.
+ *
+ * Design rationale:
+ * - Fully typed via generics — no `any` escapes at the call sites.
+ * - All `on()` calls return an unsubscribe function, which is the preferred
+ *   modern pattern over imperative `off()` calls. This makes cleanup trivial
+ *   via a collected array of disposables.
+ * - Listeners that throw are caught and logged, preventing one bad subscriber
+ *   from silently breaking the entire event chain.
+ * - `removeAllListeners()` is explicitly called in `VelionOnboarding.destroy()`
+ *   to prevent memory leaks in long-lived single-page applications.
+ */
+
+/** A strongly-typed listener function for a given event payload. */
+type Listener<TPayload> = (payload: TPayload) => void;
+
+/** A function returned by `on()` that removes the registered listener when called. */
+export type Unsubscribe = () => void;
+
+/**
+ * A generic, compile-time safe EventEmitter.
+ *
+ * @typeParam TEventMap - An object type mapping event names to their payload types.
+ *
+ * @example
+ * ```typescript
+ * interface MyEvents {
+ *   'data:ready': { records: string[] };
+ *   'error': Error;
+ * }
+ *
+ * const emitter = new TypedEventEmitter<MyEvents>();
+ *
+ * const unsub = emitter.on('data:ready', ({ records }) => {
+ *   // `records` is correctly typed as string[]
+ *   console.log(records);
+ * });
+ *
+ * emitter.emit('data:ready', { records: ['a', 'b'] });
+ * unsub(); // Clean up
+ * ```
+ */
+export class TypedEventEmitter<TEventMap extends Record<string, unknown>> {
+  /**
+   * Internal store. Using a `Map<K, Set<Listener>>` gives O(1) lookups and
+   * avoids duplicate listeners with zero extra checks (Set semantics).
+   */
+  private readonly _listeners = new Map<
+    keyof TEventMap,
+    Set<Listener<unknown>>
+  >();
+
+  /**
+   * Registers a listener for the given event. The listener will be invoked
+   * synchronously every time `emit(event, payload)` is called.
+   *
+   * @param event - The event name to subscribe to.
+   * @param listener - The callback to invoke. Receives the typed payload.
+   * @returns An unsubscribe function. Call it to remove this specific listener.
+   */
+  on<K extends keyof TEventMap>(
+    event: K,
+    listener: Listener<TEventMap[K]>,
+  ): Unsubscribe {
+    if (!this._listeners.has(event)) {
+      this._listeners.set(event, new Set());
+    }
+    const listeners = this._listeners.get(event);
+    if (listeners) listeners.add(listener as Listener<unknown>);
+
+    return () => this.off(event, listener);
+  }
+
+  /**
+   * Registers a one-time listener. The listener is automatically removed
+   * after the first time the event fires.
+   *
+   * @param event - The event name to subscribe to.
+   * @param listener - The callback to invoke once.
+   * @returns An unsubscribe function. Call it to cancel before the event fires.
+   */
+  once<K extends keyof TEventMap>(
+    event: K,
+    listener: Listener<TEventMap[K]>,
+  ): Unsubscribe {
+    const wrapper: Listener<TEventMap[K]> = (payload) => {
+      listener(payload);
+      this.off(event, wrapper);
+    };
+    return this.on(event, wrapper);
+  }
+
+  /**
+   * Emits an event, synchronously invoking all registered listeners.
+   * Errors thrown by individual listeners are caught and logged to prevent
+   * cascading failures.
+   *
+   * @param event - The event name to emit.
+   * @param payload - The data to pass to each listener.
+   */
+  emit<K extends keyof TEventMap>(event: K, payload: TEventMap[K]): void {
+    const set = this._listeners.get(event);
+    if (!set || set.size === 0) return;
+
+    for (const listener of set) {
+      try {
+        (listener as Listener<TEventMap[K]>)(payload);
+      } catch (err) {
+        console.error(
+          `[VelionSDK] Uncaught error in listener for event "${String(event)}":`,
+          err,
+        );
+      }
+    }
+  }
+
+  /**
+   * Removes a specific listener for an event.
+   *
+   * @param event - The event name.
+   * @param listener - The exact listener function reference to remove.
+   */
+  off<K extends keyof TEventMap>(
+    event: K,
+    listener: Listener<TEventMap[K]>,
+  ): void {
+    this._listeners.get(event)?.delete(listener as Listener<unknown>);
+  }
+
+  /**
+   * Removes all listeners, optionally scoped to a single event.
+   * Called by `VelionOnboarding.destroy()` to prevent memory leaks.
+   *
+   * @param event - If provided, only clears listeners for that event.
+   *                If omitted, clears ALL listeners on ALL events.
+   */
+  removeAllListeners(event?: keyof TEventMap): void {
+    if (event !== undefined) {
+      this._listeners.delete(event);
+    } else {
+      this._listeners.clear();
+    }
+  }
+
+  /**
+   * Returns the number of registered listeners for a given event.
+   * Useful for debugging and testing assertions.
+   *
+   * @param event - The event name to check.
+   */
+  listenerCount(event: keyof TEventMap): number {
+    return this._listeners.get(event)?.size ?? 0;
+  }
+}

package/src/utils/base64.ts

@@ -0,0 +1,44 @@
+/**
+ * Base64 helpers without `Buffer` (RN does not ship a Buffer global) and
+ * without leaning on `react-native-quick-base64`. Hermes provides `btoa` /
+ * `atob`, which take Latin-1 strings — we wrap them with byte arrays so
+ * callers don't have to think about the in-between.
+ */
+
+/**
+ * Encodes a `Uint8Array` to a standard base64 string.
+ *
+ * Implementation note: `btoa` requires a Latin-1 string. We convert the byte
+ * array to one char per byte via `String.fromCharCode`, in chunks to avoid
+ * blowing the JS argument-list limit on large frames (~1 MB JPEG).
+ */
+export function bytesToBase64(bytes: Uint8Array): string {
+  const CHUNK = 0x8000; // 32 KiB — well below the spread-args limit.
+  let binary = '';
+  for (let i = 0; i < bytes.length; i += CHUNK) {
+    const slice = bytes.subarray(i, i + CHUNK);
+    binary += String.fromCharCode(...slice);
+  }
+  // `btoa` is part of the WHATWG spec and is available on Hermes (RN ≥ 0.74).
+  return globalThis.btoa(binary);
+}
+
+/** Decodes a standard base64 string into a `Uint8Array`. */
+export function base64ToBytes(b64: string): Uint8Array {
+  const binary = globalThis.atob(b64);
+  const bytes = new Uint8Array(binary.length);
+  for (let i = 0; i < binary.length; i += 1) {
+    bytes[i] = binary.charCodeAt(i);
+  }
+  return bytes;
+}
+
+/** Lowercase hex (`'a1f3…'`) — matches the canonical Iris HMAC format. */
+export function bytesToHexLower(bytes: Uint8Array): string {
+  let out = '';
+  for (let i = 0; i < bytes.length; i += 1) {
+    const v = bytes[i] ?? 0;
+    out += v.toString(16).padStart(2, '0');
+  }
+  return out;
+}

package/src/utils/deviceFingerprint.ts

@@ -0,0 +1,184 @@
+/**
+ * @fileoverview Device Fingerprint via Fingerprint Pro RN SDK.
+ *
+ * Uses the official `@fingerprintjs/fingerprintjs-pro-react-native` agent
+ * class to identify the device.
+ *
+ * Why a real SDK and not a hand-rolled hash:
+ *   - The backend (`PublicSdkSessionController.fingerprint`) reads only
+ *     `request_id` and `sealed_result` from the body. A custom `visitor_id`
+ *     field is silently dropped and the AML enrichment lookup never runs.
+ *   - Fingerprint Pro returns a stable `requestId` (lookup key against the
+ *     Fingerprint server) and a `sealedResult` (encrypted payload the
+ *     backend decrypts with its private key for server-side identification).
+ *
+ * The Fingerprint Pro RN SDK is loaded **dynamically** so it stays an
+ * optional peer dep: hosts that don't ship the fingerprint module get a
+ * clear `FINGERPRINT_FAILED` error instead of a hard module-resolution
+ * crash at app boot. (The Velion example app installs it; third-party
+ * consumers without a Fingerprint workspace can swap defaults via
+ * `fingerprintApiKey` / `fingerprintEndpoint` in `VelionConfig`.)
+ */
+
+import { SdkErrorCode, type SdkError } from '../types';
+
+/** Public shape of the result. */
+export interface DeviceFingerprintResult {
+  request_id: string;
+  sealed_result?: string;
+}
+
+export interface DeviceFingerprintOptions {
+  /** Custom endpoint subdomain (proxied through Velion infra). */
+  endpoint: string;
+  /** Optional override for the public Fingerprint Pro key. */
+  apiKey?: string;
+  /** Hard ceiling for the call (ms). The SDK's own timeout can hang past this; we Promise.race against it. */
+  timeoutMs?: number;
+}
+
+/**
+ * Fingerprint Pro public API key for the shared Velion workspace. Hardcoded
+ * by design — Fingerprint distinguishes public keys (safe to ship in client
+ * code; bound to your domain/bundle ID at the Fingerprint dashboard) from
+ * secret keys (server-only, used by the worker to decrypt sealedResult or
+ * call the Server API). This constant is the *public* one.
+ */
+const VELION_FP_PUBLIC_KEY = 'GU2vrZByydGqG9HYUaz2';
+
+/**
+ * Loaded once per process. We resolve the optional native module lazily so
+ * its absence is reported as a clean SDK error rather than crashing the
+ * Metro bundler at startup with "Unable to resolve module".
+ */
+type FingerprintAgentLike = {
+  getVisitorData: (
+    tags?: Record<string, unknown> | undefined,
+    linkedId?: string | undefined,
+  ) => Promise<{ requestId?: string; sealedResult?: string }>;
+};
+
+type FingerprintAgentCtor = new (config: {
+  apiKey: string;
+  region?: 'us' | 'eu' | 'ap';
+  endpointUrl?: string | string[];
+  /** Used by the SDK if the primary endpoint fails or times out. */
+  fallbackEndpointUrls?: string[];
+  extendedResponseFormat?: boolean;
+  /** Per-request defaults; overridden by the third arg of getVisitorData(). */
+  requestOptions?: { timeout?: number };
+}) => FingerprintAgentLike;
+
+function loadAgentCtor(): FingerprintAgentCtor {
+  // Avoid bundler hoisting at build time so missing optional dep doesn't
+  // crash the host app at boot.
+  // eslint-disable-next-line @typescript-eslint/no-require-imports
+  const mod = require('@fingerprintjs/fingerprintjs-pro-react-native') as {
+    FingerprintJsProAgent?: FingerprintAgentCtor;
+  };
+  if (typeof mod.FingerprintJsProAgent !== 'function') {
+    throw new Error(
+      'Module @fingerprintjs/fingerprintjs-pro-react-native is installed ' +
+        'but does not export FingerprintJsProAgent. Upgrade to v3+ of the package.',
+    );
+  }
+  return mod.FingerprintJsProAgent;
+}
+
+/**
+ * Calls Fingerprint Pro RN to obtain `requestId` + optional `sealedResult`,
+ * the only two pieces of data the Velion backend cares about. Throws a
+ * shaped `SdkError` on any failure (missing module, agent init error,
+ * network).
+ */
+export async function generateDeviceFingerprint(
+  options: DeviceFingerprintOptions,
+): Promise<DeviceFingerprintResult> {
+  let AgentCtor: FingerprintAgentCtor;
+  try {
+    AgentCtor = loadAgentCtor();
+  } catch (err) {
+    throw {
+      code: SdkErrorCode.FINGERPRINT_FAILED,
+      message:
+        'Fingerprint Pro RN module is not installed. Add ' +
+        '`@fingerprintjs/fingerprintjs-pro-react-native` to your app ' +
+        '(and re-run `expo prebuild`) to enable the DEVICE_FINGERPRINT step.',
+      cause: err,
+    } satisfies SdkError;
+  }
+
+  const trimmedEndpoint = options.endpoint.replace(/\/$/, '').trim();
+  // An empty string is treated as "no custom endpoint" — the SDK falls through
+  // to its built-in public endpoint (api.fpjs.io). This is useful for
+  // diagnosing whether a custom proxy (e.g. fp.velion.la) is the cause of a
+  // ClientTimeout when the public path works.
+  const useCustomEndpoint = trimmedEndpoint.length > 0;
+  const apiKey = options.apiKey?.trim() || VELION_FP_PUBLIC_KEY;
+  // Internal cap for the call. The Fingerprint SDK has its own retry/timeout
+  // logic that on iOS occasionally hangs past 30s without surfacing the error
+  // to the JS layer; we Promise.race against this to guarantee a clean failure.
+  const timeoutMs = Math.max(6000, options.timeoutMs ?? 15000);
+
+  const agent = new AgentCtor({
+    apiKey,
+    region: 'us',
+    ...(useCustomEndpoint && {
+      endpointUrl: trimmedEndpoint,
+      // If the custom endpoint is unreachable (proxy misconfigured, DNS, etc.)
+      // the SDK falls back to the public Fingerprint Pro endpoint so the step
+      // still completes during development.
+      fallbackEndpointUrls: ['https://api.fpjs.io'],
+    }),
+    extendedResponseFormat: true,
+    requestOptions: { timeout: Math.floor(timeoutMs * 0.75) },
+  });
+
+  let visitorData: { requestId?: string; sealedResult?: string };
+  let timeoutHandle: ReturnType<typeof setTimeout> | null = null;
+  try {
+    visitorData = await Promise.race([
+      agent.getVisitorData(),
+      new Promise<never>((_resolve, reject) => {
+        timeoutHandle = setTimeout(
+          () =>
+            reject(
+              new Error(
+                `Fingerprint Pro getVisitorData() did not return within ${timeoutMs}ms`,
+              ),
+            ),
+          timeoutMs,
+        );
+      }),
+    ]);
+  } catch (err) {
+    throw {
+      code: SdkErrorCode.FINGERPRINT_FAILED,
+      message:
+        'No pudimos completar el reconocimiento del dispositivo. ' +
+        'Probá nuevamente; si el problema persiste, verificá tu conexión ' +
+        '(sin VPN ni proxies) o que el bundle ID de la app esté habilitado ' +
+        'en el dashboard de Fingerprint Pro.',
+      cause: err,
+    } satisfies SdkError;
+  } finally {
+    if (timeoutHandle !== null) clearTimeout(timeoutHandle);
+  }
+
+  const requestId = visitorData.requestId;
+  if (typeof requestId !== 'string' || requestId.length === 0) {
+    throw {
+      code: SdkErrorCode.FINGERPRINT_FAILED,
+      message:
+        'Fingerprint Pro did not return a requestId — backend cannot ' +
+        'enrich the session without it.',
+      cause: undefined,
+    } satisfies SdkError;
+  }
+
+  const result: DeviceFingerprintResult = { request_id: requestId };
+  if (typeof visitorData.sealedResult === 'string' && visitorData.sealedResult.length > 0) {
+    result.sealed_result = visitorData.sealedResult;
+  }
+  return result;
+}

package/src/utils/documentTypeOptions.ts

@@ -0,0 +1,31 @@
+/**
+ * Default identification document option for HUMAN_BASIC_INFO when the backend
+ * does not send `accepted_country_documents` (same label keys as legacy UI).
+ */
+
+const DOCUMENT_TYPE_LABELS_BY_PRESET = {
+  es: {
+    ARG_DNI: 'DNI (Argentina)',
+  },
+  en: {
+    ARG_DNI: 'DNI (Argentina)',
+  },
+  ar: {
+    ARG_DNI: 'DNI (Argentina)',
+  },
+} as const;
+
+type PresetLocale = keyof typeof DOCUMENT_TYPE_LABELS_BY_PRESET;
+
+/**
+ * Fallback list for the HUMAN_BASIC_INFO identification type selector when step config
+ * does not include document types from the backend.
+ */
+export function resolveDocumentTypeOptions(
+  uiLocale: string,
+): Array<{ value: string; label: string }> {
+  const labelLocale: PresetLocale =
+    uiLocale === 'en' ? 'en' : uiLocale === 'ar' ? 'ar' : 'es';
+  const labelMap = DOCUMENT_TYPE_LABELS_BY_PRESET[labelLocale];
+  return [{ value: 'ARG_DNI', label: labelMap.ARG_DNI }];
+}

package/src/utils/googleMapsPreflight.ts

@@ -0,0 +1,72 @@
+/**
+ * Pre-flight checks for the assisted address flow.
+ *
+ * The SDK no longer calls any Google REST API from the client — reverse
+ * geocoding goes through the OS native geocoder (see `osGeocoder.ts`). What
+ * we still need to verify is:
+ *   1. `react-native-maps` is linked.
+ *   2. On Android, the Google Maps key is declared in `AndroidManifest.xml`
+ *      as `<meta-data android:name="com.google.android.geo.API_KEY" .../>`.
+ *      Without that, mounting `<MapView>` throws a native
+ *      `IllegalStateException` from the Fabric UI manager — a JS error
+ *      boundary cannot catch it because the throw happens in a native
+ *      thread during the UI commit.
+ *
+ * Note that these probes cannot catch the iOS-specific case where
+ * `react-native-maps` IS installed but the `AirGoogleMaps` sub-target was
+ * never added to the Xcode project — that one only surfaces at render time
+ * and is handled by `MapFallbackBoundary`.
+ */
+
+import { Platform } from 'react-native';
+import { log } from './log';
+
+/**
+ * Returns true when `react-native-maps` is importable and exposes the
+ * MapView component we need.
+ */
+export function isReactNativeMapsAvailable(): boolean {
+  try {
+    // eslint-disable-next-line @typescript-eslint/no-require-imports, @typescript-eslint/no-var-requires
+    const mod = require('react-native-maps');
+    return typeof mod?.default === 'function' || typeof mod?.MapView === 'function';
+  } catch (err) {
+    log.warn('[gmaps-preflight] react-native-maps unavailable', err);
+    return false;
+  }
+}
+
+/**
+ * Best-effort probe for the Android `com.google.android.geo.API_KEY` meta-data
+ * in the host's `AndroidManifest.xml`.
+ *
+ * Returns:
+ *   - `true`  on iOS (the check does not apply — Apple Maps needs no key).
+ *   - `true`  when we can confirm the key is wired via the Expo config
+ *             (`android.config.googleMaps.apiKey`). Expo prebuild copies that
+ *             into the manifest, so its presence in `expoConfig` is a reliable
+ *             proxy for the real meta-data.
+ *   - `false` when `expo-constants` is available AND the Expo config does not
+ *             declare the key — we know prebuild produced a manifest without
+ *             the meta-data, so mounting `<MapView>` would crash.
+ *   - `undefined` when `expo-constants` is not installed (bare RN). We cannot
+ *             probe the manifest without a custom native module; the caller
+ *             should default to the previous behaviour (trust the integrator
+ *             when they pass `googleMapsApiKey` via `VelionConfig`).
+ */
+export function isAndroidGoogleMapsKeyInManifest(): boolean | undefined {
+  if (Platform.OS !== 'android') return true;
+  let Constants: unknown;
+  try {
+    // eslint-disable-next-line @typescript-eslint/no-require-imports, @typescript-eslint/no-var-requires
+    const mod = require('expo-constants');
+    Constants = mod?.default ?? mod;
+  } catch {
+    return undefined;
+  }
+  const expoConfig = (Constants as { expoConfig?: unknown } | undefined)?.expoConfig as
+    | { android?: { config?: { googleMaps?: { apiKey?: unknown } } } }
+    | undefined;
+  const key = expoConfig?.android?.config?.googleMaps?.apiKey;
+  return typeof key === 'string' && key.trim().length > 0;
+}

package/src/utils/hmac.ts

@@ -0,0 +1,61 @@
+/**
+ * @fileoverview HMAC-SHA256 over JPEG frames for the Iris liveness flow.
+ *
+ * React Native's WebCrypto support is incomplete in Hermes (no `subtle.sign`),
+ * so we lean on `@noble/hashes` — pure JavaScript, ~10 KB, no native code.
+ *
+ * Canonical message (must match the Iris orchestrator exactly):
+ *   `${sessionId}\n${frameId}\n${ts}\n${sha256hex(jpeg)}`
+ *
+ * Output: lowercase hex MAC, sent in the JSON envelope's `mac` field.
+ */
+
+import { hmac } from '@noble/hashes/hmac';
+import { sha256 } from '@noble/hashes/sha256';
+import { base64ToBytes, bytesToHexLower } from './base64';
+
+export interface HmacKey {
+  readonly raw: Uint8Array;
+}
+
+/** Decode the base64 frame_integrity_key from `/liveness-init`. */
+export function importHmacKey(base64: string): HmacKey {
+  return { raw: base64ToBytes(base64) };
+}
+
+/**
+ * Build the signed envelope sent over the Iris WebSocket. Mirrors
+ * `LivenessModule.buildSignedEnvelope`:
+ *   1. Compute SHA-256 of the JPEG bytes (hex, lowercase).
+ *   2. Build the canonical message.
+ *   3. HMAC-SHA256 with the imported key.
+ *   4. Wrap into `{ type: 'FRAME', frameId, timestamp, image, mac }`.
+ *
+ * Returns the JSON string ready to `ws.send`.
+ */
+export function buildSignedFrameEnvelope(args: {
+  key: HmacKey;
+  sessionId: string;
+  frameId: number;
+  jpegBytes: Uint8Array;
+  jpegBase64: string;
+  /** Defaults to `Date.now()`. */
+  timestamp?: number;
+}): { json: string; timestamp: number } {
+  const ts = args.timestamp ?? Date.now();
+  const digest = sha256(args.jpegBytes);
+  const digestHex = bytesToHexLower(digest);
+  const canonical = `${args.sessionId}\n${args.frameId}\n${ts}\n${digestHex}`;
+  const mac = hmac(sha256, args.key.raw, new TextEncoder().encode(canonical));
+  const macHex = bytesToHexLower(mac);
+  return {
+    json: JSON.stringify({
+      type: 'FRAME',
+      frameId: args.frameId,
+      timestamp: ts,
+      image: args.jpegBase64,
+      mac: macHex,
+    }),
+    timestamp: ts,
+  };
+}

package/src/utils/iso3166Countries.ts

@@ -0,0 +1,111 @@
+/**
+ * ISO 3166-1 alpha-2 country list with localized display names.
+ *
+ * Strategy:
+ *   1. If `Intl.DisplayNames` is available (full ICU build, polyfilled
+ *      Hermes, native iOS runtime, …), use it — it covers every BCP-47
+ *      locale and stays current with ICU updates.
+ *   2. Otherwise fall back to a built-in map covering all 249 ISO 3166-1
+ *      alpha-2 codes in `es` and `en`. The names match the official
+ *      Spanish convention (es. wikipedia.org/wiki/ISO_3166-1) and the ISO
+ *      English short name. Hermes default builds (which ship without
+ *      `Intl.DisplayNames`) get full localized names without needing
+ *      `@formatjs/intl-displaynames`.
+ */
+
+import ISO_CODES from '../data/iso3166Alpha2Codes.json';
+import COUNTRY_NAMES from '../data/iso3166CountryNames.json';
+import { log } from './log';
+
+export interface Iso3166CountryOption {
+  readonly code: string;
+  readonly name: string;
+}
+
+function intlLocaleTag(locale: string): string {
+  if (locale === 'en') return 'en';
+  /** Rioplatense UI uses Spanish country names with regional formatting. */
+  if (locale === 'ar') return 'es-AR';
+  return 'es';
+}
+
+interface DisplayNameResolver {
+  of(code: string): string | undefined;
+}
+
+interface IntlWithDisplayNames {
+  DisplayNames?: new (
+    locales: string | string[],
+    options: { type: 'region' | 'language' | 'script' | 'currency' | 'calendar' | 'dateTimeField' },
+  ) => DisplayNameResolver;
+}
+
+let didWarnAboutFallback = false;
+const NAMES_MAP = COUNTRY_NAMES as Record<string, ReadonlyArray<string>>;
+
+function fallbackName(code: string, lang: 'es' | 'en'): string {
+  const entry = NAMES_MAP[code.toUpperCase()];
+  if (!entry || entry.length === 0) return code;
+  // [0] = es, [1] = en. Fall through to ES (or to the code itself) if the
+  // requested locale is missing.
+  return (lang === 'en' ? entry[1] : entry[0]) ?? entry[0] ?? code;
+}
+
+function buildResolver(localeTag: string): DisplayNameResolver {
+  const lang: 'es' | 'en' = localeTag.toLowerCase().startsWith('en') ? 'en' : 'es';
+  const intl = (globalThis as { Intl?: IntlWithDisplayNames }).Intl;
+  if (intl && typeof intl.DisplayNames === 'function') {
+    try {
+      const dn = new intl.DisplayNames([localeTag], { type: 'region' });
+      // Wrap so unknown codes still fall back to the built-in map.
+      return {
+        of: (code) => dn.of(code) ?? fallbackName(code, lang),
+      };
+    } catch (err) {
+      // Some Hermes builds expose DisplayNames but throw on construction —
+      // fall through to the built-in map.
+      log.warn('[iso3166] Intl.DisplayNames threw, falling back', err);
+    }
+  }
+  if (!didWarnAboutFallback) {
+    didWarnAboutFallback = true;
+    log.info(
+      '[iso3166] Using built-in ISO 3166-1 country names (Intl.DisplayNames unavailable). ' +
+        'All 249 alpha-2 codes resolved via the bundled map.',
+    );
+  }
+  return { of: (code) => fallbackName(code, lang) };
+}
+
+/**
+ * Returns all ISO 3166-1 alpha-2 countries sorted by localized display name.
+ */
+export function listIso3166CountriesForUi(locale: string): Iso3166CountryOption[] {
+  const tag = intlLocaleTag(locale);
+  const codes = ISO_CODES as string[];
+  const dn = buildResolver(tag);
+  const collator = (globalThis as { Intl?: { Collator?: new (locale: string, options: Intl.CollatorOptions) => Intl.Collator } })
+    .Intl?.Collator;
+  return codes
+    .map((code) => ({ code, name: dn.of(code) ?? code }))
+    .sort((a, b) => {
+      if (collator) {
+        return new collator(tag, { sensitivity: 'base' }).compare(a.name, b.name);
+      }
+      return a.name.localeCompare(b.name);
+    });
+}
+
+/**
+ * Filters by country name or code (case-insensitive).
+ */
+export function filterIso3166Countries(
+  options: readonly Iso3166CountryOption[],
+  query: string,
+): Iso3166CountryOption[] {
+  const q = query.trim().toLowerCase();
+  if (q.length === 0) return [...options];
+  return options.filter(
+    (o) => o.code.toLowerCase().includes(q) || o.name.toLowerCase().includes(q),
+  );
+}