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

package/src/lib/selfie-upload-wait.ts

@@ -0,0 +1,79 @@
+// ─── Waiting for the selfie upload from a later step ────────────────────────
+//
+// With the selfie review hidden (the biometric scopes' default), the liveness
+// step hands over the moment the capture ring has closed rather than when the
+// upload lands, so the person sees ONE loading screen from the shutter to the
+// verdict instead of three. The upload keeps running in the background and
+// reports to the store (`selfieUpload`, written by liveness/useSelfieUpload);
+// the submitted step waits on that record before it submits. Pure and
+// injectable, like the result wait: the screen owns nothing but the rendering.
+
+export type SelfieUploadStatus = 'idle' | 'uploading' | 'done' | 'failed';
+
+export interface SelfieUploadState {
+  status: SelfieUploadStatus;
+  /** The failure message, set only on `failed`. */
+  message: string | null;
+}
+
+export const IDLE_SELFIE_UPLOAD: SelfieUploadState = { status: 'idle', message: null };
+
+export type SelfieUploadWait = { ok: true } | { ok: false; message: string };
+
+export interface SelfieUploadSnapshot {
+  selfieUpload: SelfieUploadState;
+  /** `mediaIds.selfie`: the durable proof the selfie is on the server. */
+  selfieMediaId: string | undefined;
+}
+
+export const SELFIE_UPLOAD_WAIT_MS = 90 * 1000;
+
+const TIMED_OUT = 'Your selfie could not be sent. Check your connection and try again.';
+
+/**
+ * Whether the upload has settled, and how. A restored session carries the
+ * media id with the status still `idle` (nothing uploaded this visit), which
+ * counts as settled; an `idle` record with no media id is an upload that has
+ * not started yet, so the caller keeps waiting.
+ */
+export function selfieUploadSettled(snapshot: SelfieUploadSnapshot): SelfieUploadWait | null {
+  const { status, message } = snapshot.selfieUpload;
+  if (status === 'failed') return { ok: false, message: message ?? TIMED_OUT };
+  if (status === 'done' || (status === 'idle' && !!snapshot.selfieMediaId)) return { ok: true };
+  return null;
+}
+
+export interface AwaitSelfieUploadDeps {
+  read: () => SelfieUploadSnapshot;
+  /** Fires the listener on every store change; returns the unsubscribe. */
+  subscribe: (listener: () => void) => () => void;
+  timeoutMs?: number;
+  setTimer?: (fn: () => void, ms: number) => unknown;
+  clearTimer?: (handle: unknown) => void;
+}
+
+/** Resolve once the upload has settled, or with a failure at the deadline. */
+export function awaitSelfieUpload(deps: AwaitSelfieUploadDeps): Promise<SelfieUploadWait> {
+  const settled = selfieUploadSettled(deps.read());
+  if (settled) return Promise.resolve(settled);
+  const setTimer = deps.setTimer ?? ((fn, ms) => setTimeout(fn, ms));
+  const clearTimer = deps.clearTimer ?? ((h) => clearTimeout(h as ReturnType<typeof setTimeout>));
+  return new Promise((resolve) => {
+    let done = false;
+    const finish = (result: SelfieUploadWait) => {
+      if (done) return;
+      done = true;
+      unsubscribe();
+      clearTimer(timer);
+      resolve(result);
+    };
+    const unsubscribe = deps.subscribe(() => {
+      const next = selfieUploadSettled(deps.read());
+      if (next) finish(next);
+    });
+    const timer = setTimer(() => finish({ ok: false, message: TIMED_OUT }), deps.timeoutMs ?? SELFIE_UPLOAD_WAIT_MS);
+    // The store may have moved between the first read and the subscription.
+    const again = selfieUploadSettled(deps.read());
+    if (again) finish(again);
+  });
+}

package/src/lib/step-log.ts

@@ -11,6 +11,20 @@
 export interface StepLogEntry {
   step: string;
   at: string;
+  /**
+   * Which multi-ID check the applicant was on (1-based). Absent on ordinary
+   * runs and on the first check.
+   *
+   * The SERVER cannot tell a slot advance from a back-press: a multi-ID run
+   * legitimately returns to the ID picker for its next ID, and by step name
+   * that is identical to pressing Back. Only the client knows a slot was
+   * committed, so only the client can say.
+   */
+  slot?: number;
+  /** The ID type selected AT THAT MOMENT — a slot's final pick is not what the
+   *  applicant was doing earlier in it (pick one ID, go back, settle on
+   *  another, and the earlier step would be named for an ID not yet chosen). */
+  idType?: string;
 }
 
 export interface StepLog {
@@ -29,10 +43,17 @@ export function resetStepLog(): void {
 
 /** Records a step visit. Consecutive duplicates are collapsed; back-and-forth
  *  navigation is kept — repeat visits are honest journey data. */
-export function recordStep(step: string): void {
+export function recordStep(step: string, slot?: number, idType?: string): void {
   if (entries.length >= MAX_ENTRIES) return;
-  if (entries[entries.length - 1]?.step === step) return;
-  entries.push({ step, at: new Date().toISOString() });
+  const last = entries[entries.length - 1];
+  // A revisit on a NEW check, or on a DIFFERENT ID, is a different visit.
+  if (last?.step === step && last.slot === slot && last.idType === idType) return;
+  entries.push({
+    step,
+    at: new Date().toISOString(),
+    ...(slot ? { slot } : {}),
+    ...(idType ? { idType } : {}),
+  });
 }
 
 /** Snapshot attached to the verify submission. Null when nothing was recorded

package/src/lib/street-view-fov.ts

@@ -0,0 +1,42 @@
+// The Street View entrance frame's maths. A mirror of the web SDK's
+// StreetViewFramer `frameFov` and the Flutter street_view_fov.dart; keep the
+// three in lockstep.
+
+export const clamp = (v: number, lo: number, hi: number): number => Math.min(hi, Math.max(lo, v));
+
+/** The frame the applicant captured: coordinates only, so the server fetches
+ *  the image with its own key. */
+export interface StreetViewFrame {
+  panoId: string;
+  heading: number;
+  pitch: number;
+  fov: number;
+}
+
+/**
+ * The field of view a centred sub-frame of the viewport actually subtends.
+ * The frame is entrance-sized guidance, so the STORED image must be what the
+ * frame showed, not the whole panorama — otherwise "fit your gate in the
+ * frame" captures a streetscape with the gate somewhere in it. Exact
+ * projection maths (a perspective view is a flat plane, so a width fraction
+ * maps through tan, not linearly).
+ */
+export function frameFov(viewportFovDeg: number, widthFraction: number): number {
+  const fraction = clamp(widthFraction, 0.1, 1);
+  const half = (viewportFovDeg * Math.PI) / 360;
+  return (2 * Math.atan(fraction * Math.tan(half)) * 180) / Math.PI;
+}
+
+/** The frame to store for a reported view: the slice the frame subtends when
+ *  both widths are known, else the whole view; fov 10..120, pitch ±90. */
+export function captureStreetViewFrame(
+  pov: { panoId: string; heading: number; pitch: number; viewFov: number },
+  frameWidth: number,
+  viewWidth: number,
+): StreetViewFrame {
+  const fov =
+    frameWidth > 0 && viewWidth > 0
+      ? clamp(frameFov(pov.viewFov, frameWidth / viewWidth), 10, 120)
+      : clamp(pov.viewFov, 10, 120);
+  return { panoId: pov.panoId, heading: pov.heading, pitch: clamp(pov.pitch, -90, 90), fov };
+}

package/src/lib/use-multi-id-plan.ts

@@ -0,0 +1,29 @@
+import { useMemo } from 'react';
+
+import { multiIdPlan, type MultiIdPlan } from './multi-id';
+import { useEffectiveCountry, useKyc, useKycConfig } from '../components/runtime';
+
+/**
+ * The active multi-ID plan for the current state, or null on an ordinary run.
+ *
+ * One hook so the picker and the position strip cannot disagree about which
+ * check the applicant is on or what it may offer — the server validates the
+ * pick sequence, so two answers here means submissions it rejects.
+ */
+export function useMultiIdPlan(): MultiIdPlan | null {
+  const config = useKycConfig();
+  const country = useEffectiveCountry();
+  const multiIdSlotIndex = useKyc((s) => s.multiIdSlotIndex);
+  const multiIdSlots = useKyc((s) => s.multiIdSlots);
+  const serverConfig = useKyc((s) => s.serverConfig);
+
+  return useMemo(
+    () =>
+      multiIdPlan(
+        { ...config, country },
+        { multiIdSlotIndex, multiIdSlots },
+        serverConfig.status === 'ready' ? serverConfig.idTypes : [],
+      ),
+    [config, country, multiIdSlotIndex, multiIdSlots, serverConfig],
+  );
+}

package/src/lib/webview-available.ts

@@ -0,0 +1,47 @@
+import type React from 'react';
+
+import { tryRequire } from '../services/fingerprint-sources';
+
+// `react-native-webview` is an OPTIONAL peer. Absent, every surface that
+// would ride it (the framed Google map, the framed Street View) degrades to
+// its dependency-free path (the OSM picker, the entrance photo), and the
+// FLOW MODEL must know that too, or it would offer a step the phone cannot
+// render. Resolved once and cached: a require that failed will fail again.
+
+export interface WebViewLike {
+  injectJavaScript(script: string): void;
+}
+
+export type WebViewComponent = React.ComponentType<{
+  ref?: React.Ref<WebViewLike>;
+  source: { uri: string };
+  style?: object;
+  javaScriptEnabled?: boolean;
+  /** Android: ask a parent ScrollView not to intercept the WebView's drags. */
+  nestedScrollEnabled?: boolean;
+  onMessage?: (event: { nativeEvent: { data: string } }) => void;
+  onError?: () => void;
+}>;
+
+let resolved: WebViewComponent | null | undefined;
+
+export function loadWebView(): WebViewComponent | null {
+  if (resolved === undefined) {
+    const mod = tryRequire<{ WebView?: WebViewComponent; default?: WebViewComponent }>(() =>
+      // eslint-disable-next-line @typescript-eslint/no-require-imports
+      require('react-native-webview'),
+    );
+    resolved = mod?.WebView ?? mod?.default ?? null;
+  }
+  return resolved;
+}
+
+/** Whether a WebView can be rendered on this install. */
+export function webViewAvailable(): boolean {
+  return loadWebView() != null;
+}
+
+/** Test seam: forget the cached answer. */
+export function __resetWebViewAvailability(): void {
+  resolved = undefined;
+}

package/src/liveness/useLiveness.ts

@@ -562,7 +562,12 @@ export function useLiveness(opts: UseLivenessOptions = {}): UseLivenessReturn {
     setState((s) => ({
       ...s,
       phase: 'complete',
-      instruction: 'Capture complete',
+      // No line at all. The ring closing green on the same frame as the
+      // shutter IS the completion signal, and the review screen follows within
+      // the beat — narrating the upload over it said nothing the user needed
+      // and read as a delay. The instruction also drives the voice guidance,
+      // so an empty one is silent as well as blank.
+      instruction: '',
       activeChallenge: null,
       positionGuidance: null,
     }));

package/src/liveness/useModelReady.ts

@@ -0,0 +1,65 @@
+import { useEffect, useRef, useState } from 'react';
+
+import { isFaceModelReady, primeFaceModel } from './visionCameraFaceDetector';
+
+// ─── Face-model readiness gate ────────────────────────────────────────────────
+//
+// Android fetches ML Kit's face model through Play Services rather than bundling
+// it, which keeps ~8 MB per device out of the APK but leaves a window where
+// detection 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. `detectFace` reports through
+// `FaceResult`, where a missing model and an empty frame are both
+// `faceCount: 0` — so gating on the per-frame result would strand the user on
+// "position your face" indefinitely, with the SDK unable to say why. That is the
+// single failure mode this whole gate exists to prevent.
+//
+// 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 the model before calling it unavailable. */
+const MODEL_WAIT_MS = 20_000;
+/** Gap between readiness polls while the download is in flight. */
+const POLL_INTERVAL_MS = 500;
+
+/**
+ * Tracks whether on-device face detection can run.
+ *
+ * Returns `'preparing'` while Play Services fetches the model, `'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 liveness this is normally already `'ready'` and no waiting screen
+ * is ever shown.
+ */
+export function useFaceModelReady(): ModelReadyState {
+  const [state, setState] = useState<ModelReadyState>(() =>
+    isFaceModelReady() ? 'ready' : 'preparing',
+  );
+  const startedAt = useRef(Date.now());
+
+  useEffect(() => {
+    if (state !== 'preparing') return;
+
+    // Re-prime rather than assume the open-time call ran: the step can be
+    // reached directly in a resumed flow, and prepareModel() is a no-op once
+    // the model is present.
+    primeFaceModel();
+
+    const id = setInterval(() => {
+      if (isFaceModelReady()) {
+        setState('ready');
+      } else if (Date.now() - startedAt.current > MODEL_WAIT_MS) {
+        setState('unavailable');
+      }
+    }, POLL_INTERVAL_MS);
+
+    return () => clearInterval(id);
+  }, [state]);
+
+  return state;
+}

package/src/liveness/visionCameraFaceDetector.ts

@@ -45,6 +45,41 @@ const boxedDetector: BoxedHybridObject<MyazaFaceDetector> | null = detector
   ? NitroModules.box(detector)
   : null;
 
+/**
+ * Start fetching the face model, so it is warm by the time liveness runs.
+ *
+ * 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 on
+ * first launch where detection cannot work. Priming at flow start puts that
+ * download behind the consent and ID-type screens instead of in front of the
+ * camera.
+ *
+ * Best-effort and non-blocking, exactly like the web SDK's `primeFaceMesh()`:
+ * a failure here is not fatal, because {@link isFaceModelReady} is what the
+ * liveness step actually gates on. iOS resolves immediately (Apple Vision is a
+ * system framework).
+ */
+export function primeFaceModel(): void {
+  detector?.prepareModel().catch(() => {
+    /* best-effort: isFaceModelReady() is the real gate */
+  });
+}
+
+/**
+ * Whether face detection can run right now.
+ *
+ * Checked BEFORE the camera opens. `detectFace` cannot answer this — a missing
+ * model and an empty frame are both `faceCount: 0`, so gating on the per-frame
+ * result would strand the user on "position your face" with no explanation.
+ *
+ * `true` when the native module is absent entirely (Expo Go), because that path
+ * already degrades to the existing camera-unavailable screen and should not be
+ * reported as a model problem.
+ */
+export function isFaceModelReady(): boolean {
+  return detector?.isModelReady() ?? true;
+}
+
 /**
  * Maps the native {@link FaceResult} to a {@link LivenessFaceData}, or `null`
  * when no face is present (`faceCount === 0`). A worklet — runs on the camera

package/src/presence/background-math.ts

@@ -0,0 +1,100 @@
+// ---------------------------------------------------------------------------
+// Pure maths for the background (OS geofence) presence tier. A geofence hands
+// us ENTER/EXIT moments; the watch wants per-day aggregates — so a dwell SPAN
+// is folded into the local calendar days it touched, each with its minutes
+// and whether the span overlapped that day's night hours (20:00 to 05:59,
+// the same definition the foreground reporter and the server use).
+//
+// THREE implementations of this fold exist — this file, the Flutter plugin's
+// PresenceFold.kt (Android) and PresenceFold.swift (iOS) — because the
+// killed-app flush must fold natively. All three are pinned to ONE vector
+// file, packages/kyc-sdk-flutter/test/presence_fold_vectors.json, which is
+// why the maths is integer arithmetic on an EXPLICIT UTC offset rather than
+// platform date APIs: identical inputs must fold identically in every
+// language. The offset is captured once per fold (east-positive minutes), a
+// fixed-offset approximation that ignores a DST transition inside one span —
+// at most an hour of dwell attribution shifts, and cross-platform parity is
+// worth more than that edge.
+// ---------------------------------------------------------------------------
+
+export interface DayAggregate {
+  day: string;
+  dwellMinutes: number;
+  nightPresent: boolean;
+}
+
+/**
+ * The longest span one fold will credit. A missed EXIT event (the OS dropped
+ * it, the app was killed mid-fence) would otherwise fabricate days of dwell
+ * from one stale ENTER timestamp — a fence can fail to close, so the credit
+ * from any single span is bounded to one day's worth.
+ */
+export const MAX_SPAN_MS = 24 * 60 * 60 * 1000;
+
+const DAY_MS = 24 * 60 * 60 * 1000;
+const HOUR_MS = 60 * 60 * 1000;
+const NIGHT_END_H = 6;
+const NIGHT_START_H = 20;
+
+/** The device's UTC offset in east-positive minutes (Lagos = +60). JS's
+ *  getTimezoneOffset() is west-positive, hence the sign flip. */
+export const deviceUtcOffsetMinutes = (atMs: number): number =>
+  -new Date(atMs).getTimezoneOffset();
+
+/** Civil date for a day index (days since 1970-01-01), as YYYY-MM-DD.
+ *  Howard Hinnant's civil_from_days — pure integers, no date API, so the
+ *  Kotlin and Swift mirrors are line-for-line identical. */
+export function civilFromDays(z: number): string {
+  const zz = z + 719468;
+  const era = Math.floor(zz / 146097);
+  const doe = zz - era * 146097;
+  const yoe = Math.floor((doe - Math.floor(doe / 1460) + Math.floor(doe / 36524) - Math.floor(doe / 146096)) / 365);
+  const y = yoe + era * 400;
+  const doy = doe - (365 * yoe + Math.floor(yoe / 4) - Math.floor(yoe / 100));
+  const mp = Math.floor((5 * doy + 2) / 153);
+  const d = doy - Math.floor((153 * mp + 2) / 5) + 1;
+  const m = mp < 10 ? mp + 3 : mp - 9;
+  const year = m <= 2 ? y + 1 : y;
+  const pad = (n: number) => String(n).padStart(2, '0');
+  return `${year}-${pad(m)}-${pad(d)}`;
+}
+
+/**
+ * Fold one dwell span into per-local-day aggregates. `offsetMinutes` is the
+ * device's UTC offset (east-positive); it defaults to the device's own so
+ * ordinary callers never think about it. An inverted span yields nothing.
+ */
+export function foldSpanIntoDays(
+  enterMs: number,
+  exitMs: number,
+  offsetMinutes: number = deviceUtcOffsetMinutes(enterMs),
+): DayAggregate[] {
+  if (!Number.isFinite(enterMs) || !Number.isFinite(exitMs)) return [];
+  if (exitMs <= enterMs) return [];
+  const offsetMs = offsetMinutes * 60_000;
+  const cappedExit = Math.min(exitMs, enterMs + MAX_SPAN_MS);
+
+  const out: DayAggregate[] = [];
+  let cursor = enterMs;
+  while (cursor < cappedExit) {
+    const shifted = cursor + offsetMs;
+    const dayIndex = Math.floor(shifted / DAY_MS);
+    // The real-clock moment this local day ends.
+    const dayEnd = (dayIndex + 1) * DAY_MS - offsetMs;
+    const sliceEnd = Math.min(dayEnd, cappedExit);
+    // Night = [00:00, 06:00) plus [20:00, 24:00) of this local day. Exact
+    // interval overlap — no sampling — so all three languages agree at the
+    // boundaries: a slice ENDING exactly at 20:00 has not touched the night.
+    const dayStartShifted = dayIndex * DAY_MS;
+    const nightPresent =
+      shifted < dayStartShifted + NIGHT_END_H * HOUR_MS ||
+      sliceEnd + offsetMs > dayStartShifted + NIGHT_START_H * HOUR_MS;
+    out.push({
+      day: civilFromDays(dayIndex),
+      dwellMinutes: Math.max(1, Math.round((sliceEnd - cursor) / 60_000)),
+      nightPresent,
+    });
+    cursor = sliceEnd;
+  }
+  return out;
+}

package/src/presence/background-store.ts

@@ -0,0 +1,82 @@
+// Persistence for the background geofence tier: the open ENTER timestamp,
+// the unflushed per-day queue, and the wire config the headless task needs
+// (it runs with no React context, so apiKey/devUrl are persisted beside the
+// pin — the key is publishable by design). Kept apart from the pin store so
+// each file stays small and the pin's own lifecycle rules stay untangled
+// from flush bookkeeping.
+
+import { readJsonFile, writeJsonFile } from './fs';
+import type { WireObservation } from './post';
+
+const FILE_NAME = 'myaza-kyc-presence-bg.json';
+
+interface BgRecord {
+  enterAt?: number | null;
+  pending?: WireObservation[];
+  config?: { apiKey: string; devUrl?: string };
+  serviceUser?: string;
+}
+
+/** The foreground-service tier serves ONE user at a time (one notification,
+ *  one location stream), and its task carries no region identifier the way a
+ *  geofence event does — so the user it samples for is remembered under this
+ *  reserved key, which no org user reference can collide with. */
+const SERVICE_USER_KEY = '__service_user__';
+
+function readAll(): Record<string, BgRecord> {
+  return readJsonFile(FILE_NAME) as Record<string, BgRecord>;
+}
+
+function write(userId: string, patch: Partial<BgRecord>): void {
+  const all = readAll();
+  all[userId] = { ...all[userId], ...patch };
+  writeJsonFile(FILE_NAME, all as Record<string, unknown>);
+}
+
+export function saveEnterAt(userId: string, at: number | null): void {
+  write(userId, { enterAt: at });
+}
+
+export function loadEnterAt(userId: string): number | null {
+  const at = readAll()[userId]?.enterAt;
+  return typeof at === 'number' ? at : null;
+}
+
+export function pendingObservations(userId: string): WireObservation[] {
+  const pending = readAll()[userId]?.pending;
+  return Array.isArray(pending) ? pending : [];
+}
+
+export function replacePending(userId: string, next: WireObservation[]): void {
+  write(userId, { pending: next });
+}
+
+/** Append fresh aggregates through the caller's merge (same-day spans fold). */
+export function queueObservations(
+  userId: string,
+  fresh: WireObservation[],
+  merge: (existing: WireObservation[], fresh: WireObservation[]) => WireObservation[],
+): void {
+  write(userId, { pending: merge(pendingObservations(userId), fresh) });
+}
+
+export function saveReporterConfig(userId: string, config: { apiKey: string; devUrl?: string }): void {
+  write(userId, { config });
+}
+
+export function loadReporterConfig(userId: string): { apiKey: string; devUrl?: string } | null {
+  const cfg = readAll()[userId]?.config;
+  return cfg && typeof cfg.apiKey === 'string' ? cfg : null;
+}
+
+export function saveServiceUser(userId: string | null): void {
+  const all = readAll();
+  if (userId == null) delete all[SERVICE_USER_KEY];
+  else all[SERVICE_USER_KEY] = { serviceUser: userId };
+  writeJsonFile(FILE_NAME, all as Record<string, unknown>);
+}
+
+export function loadServiceUser(): string | null {
+  const id = readAll()[SERVICE_USER_KEY]?.serviceUser;
+  return typeof id === 'string' && id.length > 0 ? id : null;
+}