@myazahq/kyc-sdk-react-native 2.4.0 → 2.6.0

package/src/lib/address-flow.ts

@@ -0,0 +1,172 @@
+import type { KYCStep } from '../types/config';
+
+// ---------------------------------------------------------------------------
+// The address flow as REAL steps: find it (search) → confirm it (pin, with the
+// details sheet) → show it (entrance) → commit it (review + attest fix). The
+// progress bar advances through them and back/forward is ordinary step
+// navigation, not a machine hidden inside one screen. KYB keeps the single
+// premises step — its pin + directions ARE the capture, and the KYB flow
+// already has its own section rhythm.
+//
+// 'address-collection' is the PIN step and keeps the original wire name, so
+// session progress saved by older builds restores cleanly and the server's
+// step-log titles stay meaningful. Do not "fix" it to 'address-pin'.
+//
+// A MIRROR of the web SDK's steps/address/flow-steps.ts and the Flutter port —
+// the same numbers and the same decisions, or one platform strands an
+// applicant the others do not. Keep all three in lockstep.
+// ---------------------------------------------------------------------------
+
+/**
+ * SANDBOX mirrors the web SDK's stubbed vendor treatment (user decision
+ * 2026-09-03): placeholder map, canned labels, no search loads — the server's
+ * sandbox verdicts are canned anyway, so live vendor calls on test keys spend
+ * quota for nothing. DEVELOPMENT keeps the real surfaces (the platform's
+ * dev-is-real rule); an unknown environment counts as live.
+ */
+export function addressVendorsStubbed(facts: { environment?: string | null }): boolean {
+  return facts.environment === 'SANDBOX';
+}
+
+/** The canned pin label every stubbed surface shows — obviously a sample,
+ *  never a real place. Keep in lockstep with the web SDK. */
+export const SAMPLE_ADDRESS_LINE = '12 Sample Street, Sample City';
+
+export interface AddressFlowOptions {
+  /** A search backend is available AND we are not in builder preview. */
+  searchAvailable: boolean;
+  /** The entrance-photo mode ('off' hides that capture). */
+  photoMode: 'off' | 'optional' | 'required';
+  /** Street View framing is offered (workflow on + a browser key in-document). */
+  streetViewOffered: boolean;
+}
+
+/** The individual flow's address steps, in order. */
+export function addressFlowSteps(o: AddressFlowOptions): KYCStep[] {
+  const steps: KYCStep[] = [];
+  if (o.searchAvailable) steps.push('address-search');
+  steps.push('address-collection');
+  if (o.photoMode !== 'off' || o.streetViewOffered) steps.push('address-entrance');
+  steps.push('address-review');
+  return steps;
+}
+
+const ADDRESS_STEPS: ReadonlySet<KYCStep> = new Set<KYCStep>([
+  'address-search',
+  'address-collection',
+  'address-entrance',
+  'address-review',
+]);
+
+/** Whether `step` belongs to the address flow. */
+export function isAddressStep(step: KYCStep): boolean {
+  return ADDRESS_STEPS.has(step);
+}
+
+export function nextAddressStep(steps: KYCStep[], current: KYCStep): KYCStep | null {
+  const i = steps.indexOf(current);
+  return i >= 0 && i + 1 < steps.length ? steps[i + 1]! : null;
+}
+
+export function prevAddressStep(steps: KYCStep[], current: KYCStep): KYCStep | null {
+  const i = steps.indexOf(current);
+  return i > 0 ? steps[i - 1]! : null;
+}
+
+/**
+ * Derive the flow options from raw config facts — ONE place, read by the step
+ * hook AND the flow-order builder, so the two can never disagree about which
+ * screens exist. A mirror of the web SDK's addressFlowOptions.
+ *
+ * `hasGoogleKey` is always false on mobile (the key describes an in-document
+ * browser surface). Street View reaches a phone the same way the framed map
+ * does: the hosted /embed/street-view page in a WebView on the app grant,
+ * which is `hasStreetViewFrame` — the server minted a maps frame URL AND
+ * `react-native-webview` is installed. Absent either, the entrance step is
+ * photo-only, exactly as it was before 2026-09-06.
+ */
+export function addressFlowOptions(facts: {
+  photo?: 'off' | 'optional' | 'required';
+  streetView?: 'off' | 'optional' | 'required';
+  serverSearch: boolean;
+  previewMode: boolean;
+  hasGoogleKey: boolean;
+  /** A maps frame URL this install can render: the framed
+   *  /embed/street-view page carries the panorama for it. */
+  hasStreetViewFrame: boolean;
+}): AddressFlowOptions {
+  const photoMode = facts.photo ?? 'optional';
+  return {
+    searchAvailable: facts.serverSearch && !facts.previewMode,
+    photoMode,
+    // ON by default: offered unless the workflow opted out, and wherever a
+    // Google surface exists.
+    streetViewOffered:
+      facts.streetView !== 'off' && (facts.hasGoogleKey || facts.hasStreetViewFrame),
+  };
+}
+
+/** Great-circle metres between two points (small-distance haversine). */
+export function metersBetween(
+  a: { lat: number; lng: number },
+  b: { lat: number; lng: number },
+): number {
+  const R = 6371000;
+  const toRad = (d: number) => (d * Math.PI) / 180;
+  const dLat = toRad(b.lat - a.lat);
+  const dLng = toRad(b.lng - a.lng);
+  const h =
+    Math.sin(dLat / 2) ** 2 +
+    Math.cos(toRad(a.lat)) * Math.cos(toRad(b.lat)) * Math.sin(dLng / 2) ** 2;
+  return 2 * R * Math.asin(Math.sqrt(h));
+}
+
+/**
+ * A map settle within about a metre of the current pin is the tile roundtrip
+ * drifting, not a move. Acting on it rebuilt the address WITHOUT its label, and
+ * the reverse geocoder then overwrote a searched-and-picked address with the
+ * area line. BOTH axes must be inside the epsilon for a move to be ignored.
+ */
+export const PIN_EPSILON = 1e-5;
+
+/**
+ * How far a pin may move from the spot a label was PICKED for before the label
+ * stops credibly naming it. The pick names the property; the nudge refines
+ * where its roof is — same scale as the server's at-address tolerance. Beyond
+ * this, keeping the picked name would be a lie.
+ */
+export const KEEP_PICKED_LABEL_RADIUS_M = 250;
+
+/** Below this, a pin move is roof refinement — keep the picked label silently;
+ *  asking would be noise. */
+export const LABEL_PROMPT_MIN_MOVE_M = 25;
+
+/** Debounce before reverse-geocoding a moved pin. */
+export const REVERSE_DEBOUNCE_MS = 700;
+
+/** Places autocomplete: debounce, and the floor below which nothing is asked. */
+export const AUTOCOMPLETE_DEBOUNCE_MS = 300;
+export const SEARCH_MIN_QUERY_LENGTH = 3;
+
+/**
+ * Whether the pin screen should ASK "keep the selected address?" — the
+ * applicant decides the label's fate, never a silent discard. Ask once past the
+ * refinement threshold; a prior "keep" stands until the pin crosses the
+ * credibility radius, where setPin resets it so the question returns exactly
+ * once. A DERIVED label (no pickedAt anchor) is never questioned: those
+ * re-derive freely on every move.
+ */
+export function shouldAskLabelDecision(address: {
+  lat: number;
+  lng: number;
+  label?: string;
+  pickedAt?: { lat: number; lng: number };
+  labelKept?: boolean;
+}): boolean {
+  if (!address.pickedAt || !address.label || address.labelKept) return false;
+  return metersBetween(address.pickedAt, address) > LABEL_PROMPT_MIN_MOVE_M;
+}
+
+// The displayed address line lives next door (200-line rule), re-exported so
+// every importer of this file keeps working.
+export { displayAddressLine } from './address-line';

package/src/lib/address-helpers.ts

@@ -0,0 +1,48 @@
+// ---------------------------------------------------------------------------
+// Address state shaping — the pure half of "the pin moved".
+//
+// Split from address-flow.ts (the step model + the label rules) per the
+// 200-line rule, and a MIRROR of the web SDK's steps/address-helpers.ts.
+//
+// The device fixes themselves live in services/location.ts, which owns the
+// expo-location calls; nothing here touches hardware.
+// ---------------------------------------------------------------------------
+
+/**
+ * The address state after picking a search candidate: the pin lands on the
+ * hit, the applicant's typed fields survive, and the house number prefills
+ * ONLY when they have not typed one (their word always beats the map's).
+ *
+ * The shape is FIXED on purpose. Spreading it as the new address DROPS
+ * `label`, `parts`, `pickedAt`, `labelKept`, `streetView` and the device
+ * fields, so a caller that wants one of those back has to re-add it
+ * explicitly rather than carrying a stale label to a new spot by accident.
+ */
+export function pickedAddressState(
+  prev:
+    | { directions?: string; propertyName?: string; propertyNumber?: string; street?: string }
+    | null
+    | undefined,
+  hit: { lat: number; lng: number; houseNumber: string | null },
+): {
+  lat: number;
+  lng: number;
+  accuracy: null;
+  directions: string;
+  propertyName: string;
+  propertyNumber: string;
+  street: string | undefined;
+} {
+  return {
+    lat: hit.lat,
+    lng: hit.lng,
+    accuracy: null,
+    directions: prev?.directions ?? '',
+    propertyName: prev?.propertyName ?? '',
+    propertyNumber: prev?.propertyNumber?.trim() ? prev.propertyNumber : (hit.houseNumber ?? ''),
+    // Undefined, not '': the details sheet reads '' as "deliberately cleared"
+    // and undefined as "never touched" — initialising with '' suppressed the
+    // resolved-street prefill forever.
+    street: prev?.street,
+  };
+}

package/src/lib/address-line.ts

@@ -0,0 +1,76 @@
+// The address line the flow SHOWS. Split from address-flow.ts (200-line
+// rule); a mirror of the web SDK's displayAddressLine and the Flutter
+// address_flow.dart twin. Keep the three in lockstep.
+
+/**
+ * The address line the flow SHOWS (pin summary + review heading) — the client
+ * mirror of the server's composed-line rules, so what the applicant confirms is
+ * what the org later reads. A typed number REPLACES a differing picked number
+ * (living at 8 when only 11 was listed is not "8, 11 Bassey Street"); a typed
+ * street the label does not carry leads the line.
+ */
+export function displayAddressLine(address: {
+  lat: number;
+  lng: number;
+  label?: string | null;
+  propertyNumber?: string | null;
+  street?: string | null;
+  unit?: string | null;
+  neighbourhood?: string | null;
+  city?: string | null;
+  state?: string | null;
+  postcode?: string | null;
+}): string {
+  const number = address.propertyNumber?.trim() || null;
+  const typed = address.street?.trim() || null;
+  const label = address.label?.trim() || null;
+  const unit = address.unit?.trim() || null;
+  // Edit-details corrections ride the tail through a part-wise dedupe,
+  // mirroring the server's composed line: identical values vanish, a
+  // correction appends beside the map's own answer.
+  const withClaims = (parts: string[]): string => {
+    const out = unit ? [unit, ...parts] : [...parts];
+    const seen = (v: string) => out.some((p) => p.toLowerCase() === v.toLowerCase());
+    for (const claim of [address.neighbourhood, address.city, address.state, address.postcode]) {
+      const t = claim?.trim();
+      if (t && !seen(t)) out.push(t);
+    }
+    return out.join(', ');
+  };
+  if (!label) {
+    if (typed) return withClaims([number ? `${number} ${typed}` : typed]);
+    const claimed = withClaims([]);
+    if (claimed) return claimed;
+    // NEVER coordinates. A moved pin has no line until the reverse geocode
+    // answers, and "4.93240, 8.32540" is not an address: it read as one, for
+    // the second or so before the real line arrived. Empty means "nothing
+    // human-readable yet", and the caller shows that it is still coming.
+    return '';
+  }
+  const segs = label
+    .split(', ')
+    .map((t) => t.trim())
+    .filter(Boolean);
+  if (typed && !label.toLowerCase().includes(typed.toLowerCase())) {
+    return withClaims([number ? `${number} ${typed}` : typed, ...segs]);
+  }
+  if (number) {
+    const first = segs[0] ?? '';
+    const firstTokens = first.toLowerCase().split(/\s+/);
+    const leading = firstTokens[0] ?? '';
+    if (/^\d+[a-z]?$/i.test(leading) && leading !== number.toLowerCase()) {
+      segs[0] = [number, ...first.split(/\s+/).slice(1)].join(' ');
+    } else if (!firstTokens.includes(number.toLowerCase())) {
+      return withClaims([number, ...segs]);
+    }
+  }
+  return withClaims(segs);
+}
+
+/** Read to assistive tech while the reverse geocode is out: the pin has a
+ *  line coming, and a lat/lng pair is not it. Sighted users see a skeleton
+ *  line in its place (components/LineSkeleton), never a spinner. Mirrored on
+ *  the web and Flutter SDKs. */
+export const ADDRESS_LINE_PENDING = 'Finding the address…';
+/** Shown when the geocode came back with nothing. Still not coordinates. */
+export const ADDRESS_LINE_UNAVAILABLE = 'No address found for this spot';

package/src/lib/address-pin-move.ts

@@ -0,0 +1,97 @@
+import { pickedAddressState } from './address-helpers';
+import { KEEP_PICKED_LABEL_RADIUS_M, PIN_EPSILON, metersBetween } from './address-flow';
+import type { AddressState } from '../store/state';
+
+// ---------------------------------------------------------------------------
+// What the address becomes when the pin moves.
+//
+// Pure, so the rules that decide whether a human-confirmed label survives can
+// be read and tested without a map, a store, or a GPS. The hook does the
+// dispatching; these decide.
+//
+// A MIRROR of the web SDK's setPin / applyCurrentFix / adoptPinAddress bodies.
+// ---------------------------------------------------------------------------
+
+/** Where a pin move lands. `ignore` means the map settled, it did not move. */
+export type PinMove =
+  | { kind: 'ignore' }
+  /** The picked label stands: only the coordinates (and the keep flag) change,
+   *  and NO reverse geocode is wanted. */
+  | { kind: 'keep-label'; address: AddressState }
+  /** The address is rebuilt around the new spot and wants a fresh label. */
+  | { kind: 'rebuild'; address: AddressState };
+
+export function pinMove(
+  cur: AddressState | null,
+  next: { lat: number; lng: number },
+  accuracy: number | null,
+): PinMove {
+  // A map settle within about a metre of the current pin is the tile roundtrip
+  // drifting, not a move. Acting on it rebuilt the address WITHOUT its label,
+  // and the reverse geocoder then overwrote a searched-and-picked address with
+  // the area line. BOTH axes must be inside the epsilon.
+  if (
+    cur &&
+    Math.abs(cur.lat - next.lat) < PIN_EPSILON &&
+    Math.abs(cur.lng - next.lng) < PIN_EPSILON
+  ) {
+    return { kind: 'ignore' };
+  }
+
+  // A PICKED label names the property; the pin refines where its roof is, so
+  // the label survives the move and the applicant decides its fate. Crossing
+  // the credibility radius only resets a prior "keep", so the question is
+  // asked again exactly once out there.
+  if (cur?.pickedAt && cur.label) {
+    const beyond = metersBetween(cur.pickedAt, next) > KEEP_PICKED_LABEL_RADIUS_M;
+    return {
+      kind: 'keep-label',
+      address: {
+        ...cur,
+        lat: next.lat,
+        lng: next.lng,
+        accuracy,
+        ...(beyond && cur.labelKept ? { labelKept: false } : {}),
+      },
+    };
+  }
+
+  // Typed fields AND a captured Street View frame survive a re-pin; the
+  // coordinates always win. A DERIVED label dies with the old spot.
+  return {
+    kind: 'rebuild',
+    address: {
+      ...pickedAddressState(cur, { lat: next.lat, lng: next.lng, houseNumber: null }),
+      accuracy,
+      ...(cur?.streetView ? { streetView: cur.streetView } : {}),
+    },
+  };
+}
+
+/**
+ * The address after landing on the device's current fix — the bootstrap
+ * override, used while no address exists yet.
+ *
+ * It sets NO `pickedAt`, so the resulting label counts as DERIVED and
+ * re-derives freely on the next move. A fix is where the phone is, not a
+ * property the applicant named.
+ */
+export function fixApplied(
+  cur: AddressState | null,
+  fix: { lat: number; lng: number; accuracy: number | null; label: string | null; parts?: unknown },
+): AddressState {
+  return {
+    ...pickedAddressState(cur, { lat: fix.lat, lng: fix.lng, houseNumber: null }),
+    accuracy: fix.accuracy,
+    ...(cur?.streetView ? { streetView: cur.streetView } : {}),
+    ...(fix.label ? { label: fix.label } : {}),
+    ...(fix.parts ? { parts: fix.parts as AddressState['parts'] } : {}),
+  };
+}
+
+/** The address with the human-confirmed label dropped, ready to be relabelled
+ *  from the pin. */
+export function withoutPickedLabel(cur: AddressState): AddressState {
+  const { label: _l, parts: _p, pickedAt: _a, labelKept: _k, ...rest } = cur;
+  return rest;
+}

package/src/lib/address-step-recovery.ts

@@ -0,0 +1,63 @@
+import { isAddressStep } from './address-flow';
+import type { KYCStep } from '../types/config';
+
+// ---------------------------------------------------------------------------
+// Recovering an attempt resumed onto an address step the flow no longer has.
+//
+// The address flow is the only part of the SDK whose SHAPE depends on something
+// other than the workflow the applicant is walking: `searchAvailable` comes from
+// a server flag that arrives after the session restore has already written the
+// step it was saved on. Add a republish that drops the entrance photo, and a
+// resumed applicant can be sitting on a screen the current order does not
+// contain — where Continue has nothing to advance to and Back has no
+// predecessor, so the flow is simply stuck.
+//
+// The rule is FORWARD: a step the flow no longer has is a capture it is no
+// longer asking for, so the applicant carries on rather than being sent back to
+// redo work they had already finished.
+// ---------------------------------------------------------------------------
+
+/** The address flow's four screens, in the order they are always walked. */
+const CANONICAL: readonly KYCStep[] = [
+  'address-search',
+  'address-collection',
+  'address-entrance',
+  'address-review',
+];
+
+/**
+ * The step that follows the address region in an order that CONTAINS it — where
+ * an applicant belongs when the workflow has dropped address collection
+ * altogether. Computed from the real order rather than guessed, so it is the
+ * step they would have reached had they finished.
+ */
+export function addressExitStep(orderWithAddress: readonly KYCStep[]): KYCStep | null {
+  for (let i = orderWithAddress.length - 1; i >= 0; i -= 1) {
+    if (isAddressStep(orderWithAddress[i]!)) return orderWithAddress[i + 1] ?? null;
+  }
+  return null;
+}
+
+/**
+ * Where to send an applicant sitting on an address step this flow does not
+ * contain, or null when there is nothing wrong.
+ *
+ * `inFlow` is the address steps the CURRENT order has, in order; `exit` is where
+ * to go when it has none left (see `addressExitStep`).
+ */
+export function recoverAddressStep(
+  current: KYCStep,
+  inFlow: readonly KYCStep[],
+  exit: KYCStep | null,
+): KYCStep | null {
+  if (!isAddressStep(current) || inFlow.includes(current)) return null;
+  const from = CANONICAL.indexOf(current);
+  for (let i = from + 1; i < CANONICAL.length; i += 1) {
+    const step = CANONICAL[i]!;
+    if (inFlow.includes(step)) return step;
+  }
+  // Nothing after it either: the last screen the flow does have (KYB resumed
+  // onto a review it never renders belongs on its premises pin), else out of
+  // the address flow entirely.
+  return inFlow[inFlow.length - 1] ?? exit;
+}

package/src/lib/authed-image.ts

@@ -0,0 +1,78 @@
+import { useEffect, useState } from 'react';
+
+// ─── Server-side pictures, fetched with the SDK's own bearer ────────────────
+//
+// The review card's two pictures (the static map, the framed Street View)
+// come through OUR server, so the request has to carry the SDK's bearer.
+// React Native's <Image> accepts `source.headers` for exactly this and honours
+// it on iOS; on Android (RN 0.85, new architecture) the header never leaves
+// the device: the server answered 401 to every thumbnail request and the card
+// drew an empty bordered box where the entrance should have been (Galaxy S24,
+// 2026-09-07). So the bytes are fetched with the same `fetch` the API client
+// uses, which carries headers on both platforms, and <Image> is handed a data
+// URI it cannot get wrong. The bytes are base64-encoded here rather than via
+// Blob + FileReader, which RN's fetch cannot supply (see bytesToBase64).
+
+export interface AuthedImageSource {
+  uri: string;
+  headers: Record<string, string>;
+}
+
+const B64 = 'ABCDEFGHIJKLMNOPQRSTUVWXYZabcdefghijklmnopqrstuvwxyz0123456789+/';
+
+/** Plain base64, in JS. React Native's `Response.blob()` cannot build a Blob
+ *  from the ArrayBuffer its own fetch holds ("Creating blobs from
+ *  'ArrayBuffer' … are not supported"), so Blob and FileReader are out; a
+ *  thumbnail is tens of kilobytes and this loop is nothing. */
+export function bytesToBase64(bytes: Uint8Array): string {
+  let out = '';
+  for (let i = 0; i < bytes.length; i += 3) {
+    const a = bytes[i] ?? 0;
+    const b = bytes[i + 1] ?? 0;
+    const c = bytes[i + 2] ?? 0;
+    const triple = (a << 16) | (b << 8) | c;
+    out += B64.charAt((triple >> 18) & 63) + B64.charAt((triple >> 12) & 63);
+    out += i + 1 < bytes.length ? B64.charAt((triple >> 6) & 63) : '=';
+    out += i + 2 < bytes.length ? B64.charAt(triple & 63) : '=';
+  }
+  return out;
+}
+
+export async function fetchImageDataUri(source: AuthedImageSource, signal?: AbortSignal): Promise<string> {
+  const res = await fetch(source.uri, { headers: source.headers, signal });
+  if (!res.ok) throw new Error(`HTTP ${res.status}`);
+  const mime = res.headers.get('content-type')?.split(';')[0]?.trim() || 'image/jpeg';
+  const bytes = new Uint8Array(await res.arrayBuffer());
+  return `data:${mime};base64,${bytesToBase64(bytes)}`;
+}
+
+export interface AuthedImage {
+  /** The picture as a data URI once it has arrived. */
+  uri: string | null;
+  /** It never will: the request was refused or the bytes were unreadable. */
+  failed: boolean;
+}
+
+const IDLE: AuthedImage = { uri: null, failed: false };
+
+/** One server picture, keyed on its URL; `label` names it in the dev log. */
+export function useAuthedImage(source: AuthedImageSource | null, label: string): AuthedImage {
+  const [state, setState] = useState<AuthedImage>(IDLE);
+  const key = source?.uri ?? null;
+  useEffect(() => {
+    setState(IDLE);
+    if (!source) return undefined;
+    const controller = new AbortController();
+    fetchImageDataUri(source, controller.signal)
+      .then((uri) => setState({ uri, failed: false }))
+      .catch((err: unknown) => {
+        if (controller.signal.aborted) return;
+        if (__DEV__) console.warn(`${label} failed to load`, err);
+        setState({ uri: null, failed: true });
+      });
+    return () => controller.abort();
+    // The headers are the SDK's own and never change; the URL is the picture.
+    // eslint-disable-next-line react-hooks/exhaustive-deps
+  }, [key]);
+  return state;
+}

package/src/lib/biometric-auth.ts

@@ -0,0 +1,52 @@
+import { KYCApiError } from '../services/api';
+import { KYCError } from '../types/verification';
+import type { BiometricAuthResponse } from '../services/api-types-biometric';
+
+// ---------------------------------------------------------------------------
+// Biometric re-authentication — the pure half. Mirrors the web SDK's
+// MyazaBiometricAuth error mapping and outcome shapes (keep in lockstep).
+// ---------------------------------------------------------------------------
+
+export type BiometricAuthOutcome =
+  | { kind: 'success'; result: BiometricAuthResponse }
+  | { kind: 'failed'; result: BiometricAuthResponse }
+  | { kind: 'error'; message: string };
+
+export interface BiometricAuthenticated {
+  attemptId: string;
+  confidence: number | null;
+  /** Single-use proof; verify from your backend at `/biometric/verify-proof`. */
+  token?: string;
+}
+
+export interface BiometricAuthFailed {
+  status: BiometricAuthResponse['status'];
+  attemptId: string;
+  confidence: number | null;
+}
+
+/** A technical failure, in the SDK's typed vocabulary + a message a person
+ *  can read. Never the server's own wording — that is an internal contract. */
+export function mapAuthError(err: unknown): KYCError {
+  if (err instanceof KYCApiError) {
+    if (err.statusCode === 404 && err.code === 'not_enrolled') {
+      return new KYCError('unknown', "You're not set up for face verification yet.");
+    }
+    if (err.statusCode === 402) {
+      return new KYCError('insufficient_credits', 'Face verification is temporarily unavailable.');
+    }
+    if (err.statusCode === 401 || err.statusCode === 403) {
+      return new KYCError('invalid_api_key', 'This app is not authorised for face verification.');
+    }
+  }
+  return new KYCError('network_error', 'Something went wrong. Please try again.');
+}
+
+/** The verdict as the callbacks and the result screen read it. */
+export function outcomeOf(result: BiometricAuthResponse): BiometricAuthOutcome {
+  return result.authenticated ? { kind: 'success', result } : { kind: 'failed', result };
+}
+
+export function defaultReauthLabel(companyName?: string): string {
+  return companyName ? `Verify it's you with ${companyName}` : "Verify it's you";
+}

package/src/lib/biometric-copy.ts

@@ -0,0 +1,51 @@
+import { configScope } from './scope';
+import { fillTokens } from '../utils/tokens';
+import type { BiometricCopy, BiometricCopyText } from '../config/biometricOptions';
+import type { MyazaKYCConfig } from '../types/config';
+
+// ─── The org's copy on the biometric screens, ready to render ───────────────
+//
+// Pure. Resolves `config.biometric.copy` for the screens: tokens filled from
+// `userData` exactly as the consent and success copy are, a field that empties
+// out once its tokens resolve treated as absent (the default shows rather than
+// a blank title), and everything null off the biometric scopes, where the
+// block never applies. The screens hand the result to describeWaiting /
+// describeOutcome (lib/result-copy.ts) as overrides. Mirrors the web SDK's
+// lib/biometric-copy.ts and Flutter's config/biometric_copy.dart; keep the
+// three in lockstep.
+
+export interface ResolvedBiometricCopy {
+  waiting: BiometricCopyText | null;
+  verified: BiometricCopyText | null;
+  declined: BiometricCopyText | null;
+}
+
+export const NO_BIOMETRIC_COPY: ResolvedBiometricCopy = { waiting: null, verified: null, declined: null };
+
+type CopyConfigLike = {
+  scope?: string;
+  biometric?: { copy?: BiometricCopy } | null;
+  userData?: MyazaKYCConfig['userData'];
+};
+
+export function biometricCopyFor(config: CopyConfigLike): ResolvedBiometricCopy {
+  const scope = configScope(config);
+  if (scope !== 'biometric-authentication' && scope !== 'biometric-enrollment') return NO_BIOMETRIC_COPY;
+  const copy = config.biometric?.copy;
+  if (!copy) return NO_BIOMETRIC_COPY;
+  const fill = (text: BiometricCopyText | undefined): BiometricCopyText | null => {
+    if (!text) return null;
+    const title = text.title ? fillTokens(text.title, config.userData) : '';
+    const description = text.description ? fillTokens(text.description, config.userData) : '';
+    const out: BiometricCopyText = {};
+    if (title) out.title = title;
+    if (description) out.description = description;
+    return Object.keys(out).length > 0 ? out : null;
+  };
+  return {
+    waiting: fill(copy.waiting),
+    // Enrolment shows no verdict, so a stray key there has no screen to land on.
+    verified: scope === 'biometric-authentication' ? fill(copy.verified) : null,
+    declined: scope === 'biometric-authentication' ? fill(copy.declined) : null,
+  };
+}