@myazahq/kyc-sdk-react-native 2.5.0 → 3.0.0

package/src/lib/map-tiles.ts

@@ -0,0 +1,143 @@
+// Web Mercator math for the dependency-free map pin picker. Pure and
+// unit-tested — the picker is a thin gesture shell over these.
+//
+// Deliberately NOT react-native-maps: that means native modules, per-platform
+// setup and a Google Maps API key per org for what the picker needs — pan,
+// zoom, one pin. The standard slippy-map maths below is ~60 lines, fully
+// testable, and the tiles are plain <Image>s.
+//
+// A MIRROR of the web SDK's lib/map-tiles.ts — keep the two in lockstep.
+
+export const TILE_SIZE = 256;
+export const MIN_ZOOM = 3;
+export const MAX_ZOOM = 19;
+
+// Web Mercator's poles — beyond this the projection diverges.
+const MAX_LAT = 85.05112878;
+
+export interface LatLng {
+  lat: number;
+  lng: number;
+}
+
+export function clampLat(lat: number): number {
+  return Math.max(-MAX_LAT, Math.min(MAX_LAT, lat));
+}
+
+function wrapLng(lng: number): number {
+  let l = lng;
+  while (l > 180) l -= 360;
+  while (l < -180) l += 360;
+  return l;
+}
+
+/** World size in pixels at a zoom level. */
+export function worldSize(zoom: number): number {
+  return TILE_SIZE * 2 ** zoom;
+}
+
+/** Project a coordinate to world pixels at a zoom level. */
+export function latLngToWorld(point: LatLng, zoom: number): { x: number; y: number } {
+  const size = worldSize(zoom);
+  const lat = clampLat(point.lat);
+  const sin = Math.sin((lat * Math.PI) / 180);
+  // Clamped into the world: at the pole cap the log term lands a float
+  // epsilon outside [0, size], which would render as a phantom tile row.
+  const y = (0.5 - Math.log((1 + sin) / (1 - sin)) / (4 * Math.PI)) * size;
+  return {
+    x: ((wrapLng(point.lng) + 180) / 360) * size,
+    y: Math.min(size, Math.max(0, y)),
+  };
+}
+
+/** Unproject world pixels back to a coordinate. */
+export function worldToLatLng(x: number, y: number, zoom: number): LatLng {
+  const size = worldSize(zoom);
+  const n = Math.PI - (2 * Math.PI * y) / size;
+  return {
+    lat: (180 / Math.PI) * Math.atan(0.5 * (Math.exp(n) - Math.exp(-n))),
+    lng: wrapLng((x / size) * 360 - 180),
+  };
+}
+
+export interface TilePlacement {
+  key: string;
+  url: string;
+  /** CSS position relative to the viewport's top-left corner. */
+  left: number;
+  top: number;
+}
+
+/**
+ * The OSM tiles covering a viewport centred on `center`. Tiles outside the
+ * world (above/below the poles) are skipped; longitude wraps.
+ */
+export function visibleTiles(
+  center: LatLng,
+  zoom: number,
+  width: number,
+  height: number,
+): TilePlacement[] {
+  const world = latLngToWorld(center, zoom);
+  const tiles: TilePlacement[] = [];
+  const tileCount = 2 ** zoom;
+  const originX = world.x - width / 2;
+  const originY = world.y - height / 2;
+  const first = { x: Math.floor(originX / TILE_SIZE), y: Math.floor(originY / TILE_SIZE) };
+  const last = {
+    x: Math.floor((originX + width) / TILE_SIZE),
+    y: Math.floor((originY + height) / TILE_SIZE),
+  };
+  for (let ty = first.y; ty <= last.y; ty += 1) {
+    if (ty < 0 || ty >= tileCount) continue;
+    for (let tx = first.x; tx <= last.x; tx += 1) {
+      const wrappedX = ((tx % tileCount) + tileCount) % tileCount;
+      tiles.push({
+        key: `${zoom}/${tx}/${ty}`,
+        url: `https://tile.openstreetmap.org/${zoom}/${wrappedX}/${ty}.png`,
+        left: tx * TILE_SIZE - originX,
+        top: ty * TILE_SIZE - originY,
+      });
+    }
+  }
+  return tiles;
+}
+
+/** The centre after a drag of (dx, dy) viewport pixels. */
+export function panCenter(center: LatLng, zoom: number, dx: number, dy: number): LatLng {
+  const world = latLngToWorld(center, zoom);
+  const next = worldToLatLng(world.x - dx, world.y - dy, zoom);
+  return { lat: clampLat(next.lat), lng: next.lng };
+}
+
+/** Sensible starting views: gov-DB countries at country zoom, else a world view. */
+const COUNTRY_CENTERS: Record<string, LatLng> = {
+  NG: { lat: 9.06, lng: 8.68 },
+  GH: { lat: 7.95, lng: -1.02 },
+  KE: { lat: 0.02, lng: 37.9 },
+  ZA: { lat: -28.48, lng: 24.68 },
+  CI: { lat: 7.54, lng: -5.55 },
+};
+
+export function defaultMapView(country: string | undefined): { center: LatLng; zoom: number } {
+  const center = country ? COUNTRY_CENTERS[country.toUpperCase()] : undefined;
+  return center ? { center, zoom: 6 } : { center: { lat: 6.5, lng: 12 }, zoom: 3 };
+}
+
+/**
+ * The height of the map surface on the pin step, from the viewport.
+ *
+ * A phone gets 40% of its height, clamped to 240–360: on a phone the map
+ * owns every touch, so the taller it is the less page is left to scroll on,
+ * and Continue has to stay reachable. From a tablet-class width (the web
+ * SDK's `sm` breakpoint) it is a flat 420. Mirrors the web SDK's
+ * `h-[40vh] min-h-[240px] max-h-[360px] sm:h-[420px]` on AddressCollectionStep
+ * and the Flutter `mapSurfaceHeight`; keep the three in lockstep.
+ */
+export const MAP_SURFACE = { phoneFraction: 0.4, phoneMin: 240, phoneMax: 360, wideBreakpoint: 640, wide: 420 } as const;
+
+export function mapSurfaceHeight(viewport: { width: number; height: number }): number {
+  if (viewport.width >= MAP_SURFACE.wideBreakpoint) return MAP_SURFACE.wide;
+  const fraction = Math.round(viewport.height * MAP_SURFACE.phoneFraction);
+  return Math.min(MAP_SURFACE.phoneMax, Math.max(MAP_SURFACE.phoneMin, fraction));
+}

package/src/lib/model-ready.ts

@@ -0,0 +1,82 @@
+import { useEffect, useRef, useState } from 'react';
+
+// ─── The on-device model readiness gate ───────────────────────────────────────
+//
+// Android fetches ML Kit's models through Play Services rather than bundling
+// them, which keeps ~18.5 MB per device out of the APK but leaves a window
+// where a detector cannot run: first launch before the download lands, or a
+// device with no Google Play Services at all.
+//
+// This has to be answered BEFORE the camera opens, and neither detector can
+// answer it itself. The face detector reports through `FaceResult`, where a
+// missing model and an empty frame are both `faceCount: 0`; the text recogniser
+// reports through `TextResult`, where both are an empty `lines` array. Gating on
+// the per-frame result would strand the user on "position your face", or aiming
+// at a passport that never reads, with the SDK unable to say why. That single
+// failure mode is the whole reason this gate exists.
+//
+// Shared by both because the rule and the reasoning are identical — a copy per
+// detector would be two places for one decision to drift.
+//
+// iOS is always ready (Apple Vision is a system framework), so this resolves on
+// the first tick there and costs nothing.
+
+export type ModelReadyState = 'ready' | 'preparing' | 'unavailable';
+
+/**
+ * How long to wait for a model before calling it unavailable. Generous on
+ * purpose: the text model is about 10 MB, the native side requests it as an
+ * urgent install, and a slow connection is the common case. The cost is that a
+ * phone with no Play Services at all waits the full minute before being told;
+ * the bundled build (`myazaKycBundledMlKit`) is the answer for those fleets.
+ */
+const MODEL_WAIT_MS = 60_000;
+/** Gap between readiness polls while the download is in flight. */
+const POLL_INTERVAL_MS = 500;
+
+/**
+ * Tracks whether an on-device model can run.
+ *
+ * Returns `'preparing'` while Play Services fetches it, `'ready'` once it can
+ * run, and `'unavailable'` when it could not be obtained within
+ * {@link MODEL_WAIT_MS} — no Play Services, no network, or a declined install.
+ *
+ * The flow primes the download at open (see `MyazaKYC.tsx`), so by the time the
+ * user reaches the step this is normally already `'ready'` and no waiting screen
+ * is ever shown.
+ *
+ * @param isReady whether the model can run right now
+ * @param prime starts the download; called again here because the step can be
+ *   reached directly in a resumed flow, and priming is a no-op once ready
+ */
+export function useNativeModelReady(
+  isReady: () => boolean,
+  prime: () => void,
+): ModelReadyState {
+  const [state, setState] = useState<ModelReadyState>(() =>
+    isReady() ? 'ready' : 'preparing',
+  );
+  const startedAt = useRef(Date.now());
+  // Refs, not deps: a caller passing inline arrows would otherwise restart the
+  // poll, and the wait clock with it, on every render.
+  const fns = useRef({ isReady, prime });
+  fns.current = { isReady, prime };
+
+  useEffect(() => {
+    if (state !== 'preparing') return;
+
+    fns.current.prime();
+
+    const id = setInterval(() => {
+      if (fns.current.isReady()) {
+        setState('ready');
+      } else if (Date.now() - startedAt.current > MODEL_WAIT_MS) {
+        setState('unavailable');
+      }
+    }, POLL_INTERVAL_MS);
+
+    return () => clearInterval(id);
+  }, [state]);
+
+  return state;
+}

package/src/lib/poa-country-gate.ts

@@ -0,0 +1,27 @@
+// ---------------------------------------------------------------------------
+// The Proof of Address step's country gate.
+//
+// On the ADDRESS scope the declared country is the applicant's own claim about
+// their market: it picks the document kinds on offer, the PoA vendor market and
+// rides the submission as the verification's country, and the scope seeds none
+// (see AddressCountryControl). A document uploaded with no country behind it is
+// not yet a complete answer, so Continue holds until one is declared (user
+// decision 2026-09-08). Elsewhere the flow's own country stands and the gate
+// never bites; an org that accepts exactly ONE country has the control show it
+// as a settled fact, which counts as declared.
+//
+// A THREE-WAY MIRROR of the web SDK's lib/poa-country-gate.ts and Flutter's
+// config/poa_country_gate.dart; change the rule in one and change all three.
+// ---------------------------------------------------------------------------
+
+/** Whether the Proof of Address step may continue as far as the COUNTRY is
+ *  concerned (the upload has its own gate). */
+export function poaCountryDeclared(facts: {
+  scope: string | null;
+  selectedCountry: string | null | undefined;
+  offered: readonly string[];
+}): boolean {
+  if (facts.scope !== 'address') return true;
+  if (facts.selectedCountry?.trim()) return true;
+  return facts.offered.length === 1;
+}

package/src/lib/prime-models.ts

@@ -0,0 +1,50 @@
+import { useEffect, useRef } from 'react';
+
+import { primeFaceModel } from '../liveness/visionCameraFaceDetector';
+import { primeLivenessAvatars } from '../liveness/avatarSource';
+import { primeTextModel } from '../mrz/textRecognizer';
+
+// ─── Warming the on-device work the flow is about to need ────────────────────
+//
+// Android fetches ML Kit's models through Play Services rather than bundling
+// them, and the gesture animations are served rather than shipped. All three
+// are wanted in front of a camera, which is the worst possible moment to start
+// a download — so they start the moment the flow opens instead, overlapping
+// the screens the user is already reading (consent, ID type, the document
+// step). Mirrors the web SDK's primeFaceMesh().
+//
+// Best-effort throughout: every step still gates on its own readiness, so a
+// failure here costs a head start and nothing else.
+//
+// SHARED BY BOTH ENTRY POINTS, and that is the whole point of the file. This
+// effect used to live inside the <MyazaKYC/> trigger component, so a consumer
+// using useMyazaKYC() — the hook the SDK's own example uses, and the one
+// documented for programmatic control — primed NOTHING. The face model was
+// first requested when the liveness step mounted, in front of a camera the
+// user was already looking at, and the gesture GIFs were fetched at the same
+// moment. On a device that had never downloaded the model (a fresh install,
+// the common case for a real applicant) that is a ~8 MB wait with the camera
+// already up. A warm device hides it completely, which is why it survived:
+// isModelReady() answers true on the first call and every path looks correct.
+//
+// The text model is the exception that proves it — useAutoCapture primes it at
+// the document step, so it kept a head start on both paths regardless.
+export function usePrimeModels(
+  wantOpen: boolean,
+  apiKey: string,
+  devUrl?: string,
+): void {
+  // Once per open sequence: priming is idempotent, but re-running it on every
+  // render would ask Play Services the same question a few times a second.
+  const primedRef = useRef(false);
+  useEffect(() => {
+    if (!wantOpen || primedRef.current) return;
+    primedRef.current = true;
+    primeFaceModel();
+    // The larger of the two, and wanted EARLIER in the flow than the face one
+    // (the document step comes before liveness), so it has the least time to
+    // arrive and the most to gain from the head start.
+    primeTextModel();
+    primeLivenessAvatars(apiKey, devUrl);
+  }, [wantOpen, apiKey, devUrl]);
+}

package/src/lib/resubmit.ts

@@ -17,6 +17,30 @@ export interface ResubmitConfig {
   steps: string[];
   /** Reviewer's note to the applicant. */
   message?: string | null;
+  /**
+   * The ID the verification being redone used, when the server CARRIES it.
+   *
+   * A redo keeps the verification id, so a reviewer who did not tick the ID
+   * has asked for nothing about it: the server keeps the original number,
+   * document photos, typed name and chip read, and says so by sending the
+   * idType here. Present only on an individual, single-ID send-back whose
+   * reviewer did not tick 'id-type'. Absent (an older server, a business redo,
+   * a multi-ID run, or the ID was ticked) keeps the old behaviour.
+   */
+  idType?: string | null;
+}
+
+/**
+ * The ID a redo keeps, or null when the applicant must name one again.
+ *
+ * Read defensively rather than trusted: an idType beside a plan that ticks the
+ * ID picker, or beside no plan at all, is not an instruction to skip it.
+ */
+export function keptIdType(resubmit: ResubmitConfig | undefined | null): string | null {
+  const asked = resubmit?.steps;
+  if (!asked?.length || asked.includes('id-type')) return null;
+  const idType = resubmit?.idType;
+  return typeof idType === 'string' && idType.trim().length > 0 ? idType : null;
 }
 
 /**
@@ -48,10 +72,12 @@ const EVIDENCE: KYCStep[] = ['id-input', 'document-capture', 'nfc'];
  * Steps a narrowed flow keeps regardless, because without them it cannot
  * produce a submission at all.
  *
- * A resubmission is a NEW verification on a FRESH session: nothing is carried
- * forward from the one being redone, so the applicant must still say which ID
- * this is and supply it. `POST /verify` requires an `idType`, and a number-only
- * ID requires the number with it.
+ * Unless the server carries the original ID (`keptIdType`), nothing is carried
+ * forward from the attempt being redone, so the applicant must still say which
+ * ID this is and supply it. `POST /verify` requires an `idType`, and a
+ * number-only ID requires the number with it. When the ID IS carried, the
+ * identity steps drop out: the SDK preselects the kept ID and the server fills
+ * in the number, the document photos and the chip read.
  *
  * So narrowing removes the things arranged AROUND the identity — liveness,
  * proof of address, the questionnaire, contact checks — and never the identity
@@ -93,9 +119,12 @@ export function applyResubmitSteps(
 
   const wanted = new Set<string>(asked);
   if (wantsEvidence) for (const step of EVIDENCE) wanted.add(step);
-  for (const step of order.includes('business-details') ? BUSINESS_REQUIRED : INDIVIDUAL_REQUIRED) {
-    wanted.add(step);
-  }
+  // A kept ID needs no picker and, unless the reviewer asked for the evidence,
+  // no evidence step either: the redo is only what was ticked. KYB never keeps
+  // an ID (the server never sends one for a business redo), so it stays as is.
+  const isBusiness = order.includes('business-details');
+  const required = isBusiness ? BUSINESS_REQUIRED : keptIdType(resubmit) ? [] : INDIVIDUAL_REQUIRED;
+  for (const step of required) wanted.add(step);
 
   const narrowed = order.filter((step) => wanted.has(step) || ALWAYS.includes(step));
 

package/src/lib/result-copy.ts

@@ -0,0 +1,116 @@
+import type { VerificationOutcome } from './result-wait';
+import type { BiometricCopyText } from '../config/biometricOptions';
+
+// ─── What the terminal screens say ──────────────────────────────────────────
+//
+// Pure so it is testable without React. The server's own reason wins on a
+// decline or an error when it sent one: it is written for the applicant.
+// UK English, no em dashes (user-facing copy rule).
+
+export type ResultTone = 'success' | 'error' | 'info';
+
+export interface ResultCopy {
+  tone: ResultTone;
+  title: string;
+  description: string;
+}
+
+export interface WaitingCopy {
+  title: string;
+  description: string;
+}
+
+/**
+ * The ONE loading screen after the capture. On a re-authentication that waits
+ * for its verdict it spans the selfie upload, the submission and the poll, so
+ * it names the check rather than any of the three steps behind it. A retry in
+ * flight replaces the description, never the title: the person is still
+ * waiting for the same thing. `override` is the org's own words for the
+ * screen (lib/biometric-copy.ts), field by field over the default.
+ */
+export function describeWaiting(opts: {
+  scope: string | null;
+  waitsForResult: boolean;
+  retry?: { attempt: number; total: number } | null;
+  override?: BiometricCopyText | null;
+}): WaitingCopy {
+  const base = withOverride(waitingCopyFor(opts.scope, opts.waitsForResult), opts.override);
+  if (opts.retry) {
+    return { title: base.title, description: `Connection issue, retrying (${opts.retry.attempt}/${opts.retry.total}).` };
+  }
+  return base;
+}
+
+function waitingCopyFor(scope: string | null, waitsForResult: boolean): WaitingCopy {
+  if (scope === 'biometric-authentication') {
+    return waitsForResult
+      ? { title: "Checking it's you", description: 'Matching your selfie against the photo on record. This usually takes a few seconds.' }
+      : { title: 'Sending your face check', description: 'This only takes a moment.' };
+  }
+  if (scope === 'biometric-enrollment') {
+    return { title: 'Saving your selfie', description: 'It becomes the reference for your future face checks.' };
+  }
+  return { title: 'Submitting your verification', description: 'Please wait a moment.' };
+}
+
+/** The org's own words for a screen, over the default, field by field. */
+function withOverride<T extends { title: string; description: string }>(base: T, override?: BiometricCopyText | null): T {
+  if (!override) return base;
+  return {
+    ...base,
+    ...(override.title ? { title: override.title } : {}),
+    ...(override.description ? { description: override.description } : {}),
+  };
+}
+
+/** What the person is told, per outcome. The server's own reason wins on a
+ *  decline or an error when it sent one; it is written for the applicant.
+ *  `copy` is the org's own words for the two verdict screens: on a decline
+ *  its description wins even over the server's reason, since the org chose
+ *  to say that. */
+export function describeOutcome(
+  outcome: VerificationOutcome,
+  copy?: { verified?: BiometricCopyText | null; declined?: BiometricCopyText | null },
+): ResultCopy {
+  if (outcome.kind === 'timeout') {
+    return {
+      tone: 'info',
+      title: 'Still checking',
+      description: "This is taking longer than usual. You'll be notified as soon as it's done.",
+    };
+  }
+  switch (outcome.status) {
+    case 'approved':
+      return withOverride(
+        { tone: 'success', title: "You're verified", description: 'Your face matched the photo on record.' },
+        copy?.verified,
+      );
+    case 'declined':
+      return withOverride(
+        {
+          tone: 'error',
+          title: "We couldn't confirm it's you",
+          description: outcome.reason ?? "Your face didn't match the photo on record.",
+        },
+        copy?.declined,
+      );
+    case 'in_review':
+      return {
+        tone: 'info',
+        title: 'Under review',
+        description: "A reviewer will take a look. You'll be notified of the outcome.",
+      };
+    case 'error':
+      return {
+        tone: 'error',
+        title: 'Something went wrong',
+        description: outcome.reason ?? "We couldn't complete your check. Please try again in a moment.",
+      };
+    default:
+      return {
+        tone: 'info',
+        title: 'Check submitted',
+        description: "You'll be notified of the result.",
+      };
+  }
+}

package/src/lib/result-wait.ts

@@ -0,0 +1,53 @@
+import type { SessionStatus, VerificationStatusResponse } from '../services/api-types';
+
+// ─── Waiting for a verdict in the flow ──────────────────────────────────────
+//
+// The platform is fire-and-forget: /verify answers in milliseconds and the
+// worker settles the check afterwards. A re-authentication is the one flow
+// whose verdict the person is waiting for RIGHT THERE, so the submitted step
+// polls the publishable status endpoint (state + reason, never result data)
+// until the check leaves its pending states. Pure and injectable, like the
+// presence watch wait: the screen owns nothing but the rendering.
+
+export const RESULT_WAIT_MS = 60 * 1000;
+export const RESULT_POLL_MS = 1500;
+
+/** The states a submitted check passes through before it settles. */
+const PENDING: ReadonlySet<SessionStatus> = new Set(['not_started', 'in_progress', 'processing']);
+
+export type VerificationOutcome =
+  | { kind: 'settled'; status: SessionStatus; reason: string | null; reasonCode: string | null }
+  | { kind: 'timeout' };
+
+export interface AwaitOutcomeDeps {
+  /** One status read; null on any failure (the wait keeps going). */
+  fetchStatus: () => Promise<VerificationStatusResponse | null>;
+  sleep?: (ms: number) => Promise<void>;
+  now?: () => number;
+  waitMs?: number;
+  pollMs?: number;
+}
+
+export function isPendingStatus(status: SessionStatus): boolean {
+  return PENDING.has(status);
+}
+
+/**
+ * Poll until the check settles or the budget runs out. A failed read is not
+ * a verdict: it is skipped and the next poll tries again, so a network blip
+ * mid-wait never reads as an outcome.
+ */
+export async function awaitVerificationOutcome(deps: AwaitOutcomeDeps): Promise<VerificationOutcome> {
+  const sleep = deps.sleep ?? ((ms) => new Promise<void>((resolve) => setTimeout(resolve, ms)));
+  const now = deps.now ?? Date.now;
+  const deadline = now() + (deps.waitMs ?? RESULT_WAIT_MS);
+  const pollMs = deps.pollMs ?? RESULT_POLL_MS;
+  for (;;) {
+    const read = await deps.fetchStatus();
+    if (read && !isPendingStatus(read.status)) {
+      return { kind: 'settled', status: read.status, reason: read.reason ?? null, reasonCode: read.reasonCode ?? null };
+    }
+    if (now() >= deadline) return { kind: 'timeout' };
+    await sleep(pollMs);
+  }
+}

package/src/lib/review-map-surface.ts

@@ -0,0 +1,26 @@
+// The review card's map falls back in the SAME order on every SDK: the picture
+// (the Maps Static API through the server), then the framed Google map the pin
+// step drew, then the built-in tiles. Pure, so a test can pin the order — the
+// Flutter card skipped the middle rung and confirmed the address on
+// OpenStreetMap where RN confirmed it on Google (user report 2026-09-08).
+// Mirrors kyc-sdk-flutter's reviewMapSurface; keep the two in lockstep.
+
+export type ReviewMapSurface = 'stub' | 'picture' | 'pending' | 'framed' | 'builtIn';
+
+export function reviewMapSurface(facts: {
+  vendorsStubbed: boolean;
+  /** The picture's bytes have landed. */
+  hasStaticMap: boolean;
+  /** The picture was refused (a project without the Static API 404s). */
+  staticMapFailed: boolean;
+  /** A server-minted maps frame URL this install can render. */
+  hasFrame: boolean;
+}): ReviewMapSurface {
+  if (facts.vendorsStubbed) return 'stub';
+  if (facts.hasStaticMap) return 'picture';
+  // Nothing to draw yet and no verdict either: hold the picture's space rather
+  // than flashing the live map for the half second before the bytes land.
+  if (!facts.staticMapFailed) return 'pending';
+  if (facts.hasFrame) return 'framed';
+  return 'builtIn';
+}

package/src/lib/scope.ts

@@ -0,0 +1,31 @@
+// Workflow SCOPE — what a flow verifies about the subject (mirror of the
+// server's lib/workflows/scope.ts and the web SDK's lib/scope.ts; keep the
+// three in lockstep). Absent = the full verification.
+
+export type WorkflowScope =
+  | 'address'
+  | 'biometric-authentication'
+  | 'biometric-enrollment'
+  | 'questionnaire'
+  | 'contact';
+
+/** The marker idType a scoped submission carries (the KYB product-in-idType
+ *  convention — the server requires the matching published workflow). */
+export const SCOPE_ID_TYPES: Record<WorkflowScope, string> = {
+  address: 'address',
+  'biometric-authentication': 'biometric-auth',
+  'biometric-enrollment': 'biometric-enroll',
+  questionnaire: 'questionnaire',
+  contact: 'contact',
+};
+
+export function configScope(config: { scope?: WorkflowScope | string }): WorkflowScope | null {
+  const value = config.scope;
+  return value && value in SCOPE_ID_TYPES ? (value as WorkflowScope) : null;
+}
+
+/** The biometric scopes run the liveness capture; every other scope has no
+ *  camera step at all. */
+export function isFaceScope(scope: WorkflowScope | null): boolean {
+  return scope === 'biometric-authentication' || scope === 'biometric-enrollment';
+}