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

package/src/store/kycStore.ts

@@ -22,13 +22,43 @@ import { INITIAL_SERVER_CONFIG, describeConfigError, type ServerConfigState } fr
 import {
   EMPTY_BUSINESS,
   EMPTY_BUSINESS_APPLICATION,
+  EMPTY_BUSINESS_CHECK,
   type KYCSubmissionResult,
   type KycState,
   type KycStore,
 } from './state';
 import { nextStepAfter, nfcDecision, previousStepBefore } from './derive';
+
+/** The steps that make up ONE ID's evidence. Leaving this set is what ends a
+ *  multi-ID check — the leg has several exits depending on the ID. */
+const ID_EVIDENCE_STEPS = new Set<KYCStep>(['id-input', 'document-capture', 'nfc']);
+
+/** The 1-based check the applicant is on, or undefined outside a multi-ID run.
+ *  Only emitted once a slot has been COMMITTED — on an ordinary run the field
+ *  would be a constant 1 on every entry, which is noise. */
+function multiIdSlotOf(s: KycState): number | undefined {
+  return s.multiIdSlots.length > 0 ? s.multiIdSlots.length + 1 : undefined;
+}
+
+/** The ID selected at this moment — see StepLogEntry.idType. */
+function selectedIdTypeOf(s: KycState): string | undefined {
+  return s.selectedIdType ?? undefined;
+}
+
+/** The active multi-ID plan for the store's current state, or null. */
+function multiIdPlanFor(s: KycState): ReturnType<typeof multiIdPlan> {
+  return multiIdPlan(
+    { ...s.config, country: s.selectedCountry ?? s.config.country },
+    { multiIdSlotIndex: s.multiIdSlotIndex, multiIdSlots: s.multiIdSlots },
+    s.serverConfig.status === 'ready' ? s.serverConfig.idTypes : [],
+  );
+}
 import { recordStep, resetStepLog } from '../lib/step-log';
+import { multiIdPlan } from '../lib/multi-id';
+import { resolveIdTypeDefinition } from '../config/idTypes';
 import { buildVerifyRequest } from './submit';
+import { resetBusinessCheck, runBusinessCheck } from './businessCheck';
+import { startAttemptSession, watchSessionProgress } from './session';
 import { applicantMediaCaptured, buildApplicantVerifyRequest } from './submitApplicant';
 
 export * from './state';
@@ -65,9 +95,15 @@ export function createKycStore(
       api,
 
       currentStep: 'consent',
+      sessionId: null,
+      sessionUrl: null,
+      businessCheck: { ...EMPTY_BUSINESS_CHECK },
       selectedCountry: null,
       selectedIdType: null,
       idNumber: null,
+      multiIdSlotIndex: 0,
+      multiIdSlots: [],
+      multiIdRestored: null,
       mediaIds: {},
       submissionResult: null,
       serverConfig: serverConfig ?? INITIAL_SERVER_CONFIG,
@@ -106,6 +142,7 @@ export function createKycStore(
               status: 'ready',
               idTypes: res.idTypes,
               branding,
+              geoCountry: res.geoCountry,
               environment: res.environment,
               fatal: false,
             },
@@ -122,11 +159,90 @@ export function createKycStore(
         // Changing country invalidates the ID choice: the same key can mean a
         // different document (or none) elsewhere, so it is cleared rather than
         // silently carried across.
-        set((s) => ({
-          selectedCountry: country,
-          selectedIdType: s.selectedCountry === country ? s.selectedIdType : null,
-          idNumber: s.selectedCountry === country ? s.idNumber : null,
-        }));
+        set((s) => {
+          const same = s.selectedCountry === country;
+          return {
+            selectedCountry: country,
+            selectedIdType: same ? s.selectedIdType : null,
+            idNumber: same ? s.idNumber : null,
+            // A multi-ID run's committed slots belong to the country they were
+            // picked in; carrying them into a new one would offer an ID no
+            // register there can verify.
+            multiIdSlotIndex: same ? s.multiIdSlotIndex : 0,
+            multiIdSlots: same ? s.multiIdSlots : [],
+            multiIdRestored: same ? s.multiIdRestored : null,
+          };
+        });
+      },
+
+      commitMultiIdSlot(nextStep, previews) {
+        set((s) => {
+          if (!s.selectedIdType) return {};
+          const slot = {
+            idType: s.selectedIdType,
+            ...(s.idNumber ? { idNumber: s.idNumber } : {}),
+            ...(s.mediaIds.documentFront ? { documentFront: s.mediaIds.documentFront } : {}),
+            ...(s.mediaIds.documentBack ? { documentBack: s.mediaIds.documentBack } : {}),
+            ...(s.mediaIds.documentFrontVideo
+              ? { documentFrontVideo: s.mediaIds.documentFrontVideo }
+              : {}),
+            ...(s.mediaIds.documentBackVideo
+              ? { documentBackVideo: s.mediaIds.documentBackVideo }
+              : {}),
+            ...(s.chipData ? { chipData: s.chipData } : {}),
+            ...(previews?.front ? { documentFrontImage: previews.front } : {}),
+            ...(previews?.back ? { documentBackImage: previews.back } : {}),
+          };
+          // The working evidence is cleared for the next check; the SELFIE and
+          // its video are run-level and deliberately untouched.
+          return {
+            multiIdSlots: [...s.multiIdSlots, slot],
+            multiIdSlotIndex: s.multiIdSlotIndex + 1,
+            selectedIdType: null,
+            idNumber: null,
+            multiIdRestored: null,
+            mediaIds: {
+              ...s.mediaIds,
+              documentFront: undefined,
+              documentBack: undefined,
+              documentFrontVideo: undefined,
+              documentBackVideo: undefined,
+            },
+            // The chip belongs to the check just committed; the next one reads
+            // its own document (or none).
+            chipData: null,
+            documentScanPhase: 'front' as const,
+            currentStep: nextStep,
+          };
+        });
+      },
+
+      uncommitMultiIdSlot(step) {
+        set((s) => {
+          const last = s.multiIdSlots[s.multiIdSlots.length - 1];
+          if (!last) return {};
+          // Restore what that check captured — changing an earlier ID must not
+          // mean re-photographing a document that is still perfectly good.
+          return {
+            multiIdSlots: s.multiIdSlots.slice(0, -1),
+            multiIdSlotIndex: Math.max(s.multiIdSlots.length - 1, 0),
+            selectedIdType: last.idType,
+            idNumber: last.idNumber ?? null,
+            multiIdRestored: {
+              ...(last.documentFrontImage ? { front: last.documentFrontImage } : {}),
+              ...(last.documentBackImage ? { back: last.documentBackImage } : {}),
+            },
+            mediaIds: {
+              ...s.mediaIds,
+              documentFront: last.documentFront,
+              documentBack: last.documentBack,
+              documentFrontVideo: last.documentFrontVideo,
+              documentBackVideo: last.documentBackVideo,
+            },
+            chipData: last.chipData ?? null,
+            currentStep: step,
+          };
+        });
       },
 
       setIdType(idType) {
@@ -163,11 +279,29 @@ export function createKycStore(
       },
 
       setContactVerified(channel, destination, token) {
+        set((s) => {
+          // A fresh proof clears its channel's "server refused this" flag.
+          const expired = (s.contact.expired ?? []).filter((c) => c !== channel);
+          return {
+            contact:
+              channel === 'email'
+                ? { ...s.contact, emailAddress: destination, emailToken: token, expired }
+                : { ...s.contact, phoneNumber: destination, phoneToken: token, expired },
+          };
+        });
+      },
+
+      clearContactProofs(channels) {
+        // The server refused these proofs at submit (single-use tokens expire
+        // ~30 min after the OTP check, and session restore can resurrect a
+        // dead one). Drop the tokens, keep the destinations, flag the steps.
         set((s) => ({
-          contact:
-            channel === 'email'
-              ? { ...s.contact, emailAddress: destination, emailToken: token }
-              : { ...s.contact, phoneNumber: destination, phoneToken: token },
+          contact: {
+            ...s.contact,
+            ...(channels.includes('email') ? { emailToken: undefined } : {}),
+            ...(channels.includes('phone') ? { phoneToken: undefined } : {}),
+            expired: channels,
+          },
         }));
       },
 
@@ -180,14 +314,54 @@ export function createKycStore(
         }));
       },
 
+      setSessionId(sessionId, sessionUrl) {
+        set({ sessionId, ...(sessionUrl !== undefined ? { sessionUrl } : {}) });
+      },
+
+      async checkBusiness() {
+        return runBusinessCheck(get, set);
+      },
+
       setBusinessField(key, value) {
-        set((s) => ({ business: { ...s.business, [key]: value } }));
+        // Any change to WHICH company this is about invalidates the answer we
+        // hold, so the check never describes one business while the field names
+        // another. Everything the previous register told us about the old
+        // company goes with it — only what the REGISTER wrote: an applicant who
+        // typed their own address meant it. Clearing it also unblocks the next
+        // lookup, whose prefill only ever writes into an empty field, so
+        // leftovers were not merely stale, they were suppressing the real
+        // answer. Mirrors the web SDK's setDetails.
+        const identityChanged =
+          key === 'registrationNumber' || key === 'country' || key === 'product';
+        set((s) => {
+          const business = { ...s.business, [key]: value };
+          if (identityChanged) {
+            for (const prefilledKey of s.businessCheck.prefilled) {
+              if (prefilledKey !== key) (business as Record<string, unknown>)[prefilledKey] = '';
+            }
+          }
+          return { business };
+        });
+        if (identityChanged) resetBusinessCheck(set);
+      },
+
+      applyBusinessPrefill(patch, prefilled) {
+        set((s) => ({
+          business: { ...s.business, ...patch },
+          businessCheck: { ...s.businessCheck, prefilled },
+        }));
       },
 
       setKeyPeople(rows) {
         set((s) => ({ businessApplication: { ...s.businessApplication, keyPeople: rows } }));
       },
 
+      setUboUnidentifiable(checked) {
+        set((s) => ({
+          businessApplication: { ...s.businessApplication, uboUnidentifiable: checked },
+        }));
+      },
+
       setBusinessDocument(doc) {
         set((s) => ({
           businessApplication: {
@@ -276,6 +450,26 @@ export function createKycStore(
 
       nextStep() {
         const next = nextStepAfter(get().currentStep, get());
+
+        // Multi-ID: the run walks the capture leg once PER ID. Intercepted here
+        // rather than in each screen because it is one rule — "the applicant
+        // finished this check" — and the leg has several exits (a number-only
+        // ID leaves from id-input, a document ID from document-capture or the
+        // chip read after it).
+        const plan = multiIdPlanFor(get());
+        if (plan && ID_EVIDENCE_STEPS.has(get().currentStep) && !ID_EVIDENCE_STEPS.has(next)) {
+          const previews = get().multiIdRestored ?? undefined;
+          if (!plan.last) {
+            // Another ID to go: commit this one and hand the picker back.
+            get().commitMultiIdSlot('id-type', previews);
+            emitStepChange('id-type');
+            return;
+          }
+          // The final check: commit it, then carry on to the shared selfie.
+          get().commitMultiIdSlot(next, previews);
+          emitStepChange(next);
+          return;
+        }
         // Leaving document capture is the moment the chip step either appears or
         // silently does not. Four independent gates can remove it and a missing
         // step looks the same however it went missing, so say which one.
@@ -294,6 +488,22 @@ export function createKycStore(
       },
 
       previousStep() {
+        // Multi-ID: stepping back from the picker means re-doing the PREVIOUS
+        // check, not leaving the flow. The slot is uncommitted so its ID number
+        // and captures come back — changing an earlier ID must not mean
+        // re-photographing a document that is still perfectly good.
+        const slots = get().multiIdSlots;
+        if (get().currentStep === 'id-type' && slots.length > 0) {
+          const last = slots[slots.length - 1]!;
+          const def = resolveIdTypeDefinition(
+            get().selectedCountry ?? get().config.country ?? '',
+            last.idType,
+          );
+          const step: KYCStep = def?.requiresDocumentCapture === false ? 'id-input' : 'document-capture';
+          get().uncommitMultiIdSlot(step);
+          emitStepChange(step);
+          return;
+        }
         const prev = previousStepBefore(get().currentStep, get());
         if (prev !== get().currentStep) {
           set({ currentStep: prev, immersiveCapture: false, navDirection: 'back' });
@@ -322,7 +532,7 @@ export function createKycStore(
           const res = await withRetry(() => api.verify(request), { onRetry });
           const result: KYCSubmissionResult = {
             verificationId: res.verificationId,
-            status: 'pending',
+            status: 'processing',
           };
           set({
             submissionResult: result,
@@ -359,18 +569,24 @@ export function createKycStore(
         // already sitting on 'consent' (the subscribe below only fires on
         // change, and recordStep dedupes if it fires too).
         resetStepLog();
-        recordStep('consent');
+        recordStep('consent', multiIdSlotOf(get()), selectedIdTypeOf(get()));
         set({
           currentStep: 'consent',
           selectedCountry: null,
           selectedIdType: null,
           idNumber: null,
+          multiIdSlotIndex: 0,
+          multiIdSlots: [],
+          multiIdRestored: null,
           mediaIds: {},
           submissionResult: null,
           documentScanPhase: 'front',
           documentCapturePhase: 'front',
           immersiveCapture: false,
           flashPaint: null,
+          sessionId: null,
+          sessionUrl: null,
+          businessCheck: { ...EMPTY_BUSINESS_CHECK },
           questionnaireAnswers: {},
           contact: {},
           contactChallenge: null,
@@ -395,7 +611,9 @@ export function createKycStore(
   // collapses consecutive duplicates). Rides the submission as
   // metadata.device.stepLog for the dashboard timeline.
   store.subscribe((s, prev) => {
-    if (s.currentStep !== prev.currentStep) recordStep(s.currentStep);
+    if (s.currentStep !== prev.currentStep) {
+      recordStep(s.currentStep, multiIdSlotOf(s), selectedIdTypeOf(s));
+    }
   });
 
   // A fresh store IS a fresh session: the runtime provider creates one per
@@ -404,7 +622,16 @@ export function createKycStore(
   // subscription above only fires on CHANGE, and a new store already sits on
   // 'consent').
   resetStepLog();
-  recordStep(store.getState().currentStep);
+  recordStep(
+    store.getState().currentStep,
+    multiIdSlotOf(store.getState()),
+    selectedIdTypeOf(store.getState()),
+  );
+
+  // The attempt session: minted at launch (a fresh store IS a fresh attempt),
+  // with progress written as the user moves. Both best-effort by contract.
+  startAttemptSession(store);
+  watchSessionProgress(store);
 
   return store;
 }

package/src/store/serverConfig.ts

@@ -19,6 +19,8 @@ export interface ServerConfigState {
   status: ServerConfigStatus;
   idTypes: SdkConfigIdType[];
   branding?: SdkConfigBranding;
+  /** The visitor's country from their IP — a default, never evidence. */
+  geoCountry?: string | null;
   environment?: 'DEVELOPMENT' | 'SANDBOX' | 'PRODUCTION';
   /** HTTP status of a failed config fetch (if any). */
   statusCode?: number;

package/src/store/session.ts

@@ -0,0 +1,208 @@
+import type { KycState, KycStore } from './state';
+import { getStepLog } from '../lib/step-log';
+import { emptyKeyPerson, type KeyPersonEntry } from '../config/keyPeople';
+import type { SessionStartResponse } from '../services/api-types';
+import { persistentDeviceId } from '../services/fingerprint-sources';
+
+// ---------------------------------------------------------------------------
+// The attempt SESSION: minting at launch, and progress writes as the user moves.
+//
+// Ported from the web SDK (MyazaKYC.tsx beginSession + useSessionProgress),
+// with the same contracts:
+//
+//   Best-effort throughout. Sessions power resumability, the dashboard's live
+//   attempt view, session webhooks, and the registry check at selection —
+//   verifying is never conditional on one existing, so every failure here is
+//   swallowed.
+//
+//   Untouched progress is never written. The presence of stored progress IS
+//   "they started"; a save-on-mount would make every opened flow look started,
+//   and the server tells an abandoned first screen from a worked-through form
+//   by exactly this absence.
+//
+//   A remount RESTORES the user to where they were, like web: the resumed
+//   session's stored progress hydrates the store (restoreAttemptProgress),
+//   so their step, captures and typed data survive an app restart.
+// ---------------------------------------------------------------------------
+
+const SAVE_DEBOUNCE_MS = 800;
+
+// Collapses concurrent mints into one request per launch (mirrors the web
+// SDK's start-session-once). Dev-mode double-invocation fired /session/start
+// twice ~600ms apart; without an externalUserId the server has nothing to
+// resume by, so the second call minted a SECOND session — the flow adopted one
+// and the orphan sat on the org's list forever as "Not started". Short window
+// on purpose: it collapses a double-invoke, never caches sessions, and a
+// failure clears immediately so a retry is a real retry.
+const inflightStarts = new Map<string, Promise<SessionStartResponse>>();
+
+/** Mint (or resume) the attempt session and remember its id. Fire-and-forget. */
+export function startAttemptSession(store: KycStore): void {
+  const s = store.getState();
+  if (s.sessionId) return;
+  const externalUserId = s.config.userId ?? s.config.metadata?.['userId'];
+  const key = `${s.config.apiKey}|${s.config.workflowId ?? ''}|${externalUserId ?? ''}`;
+  let start = inflightStarts.get(key);
+  if (!start) {
+    // The device id is the anonymous-mount resume fallback: without a userId
+    // the server has nothing else to find the previous attempt by, and every
+    // app relaunch minted a fresh session. Hashed server-side before storage.
+    start = persistentDeviceId().then((deviceRef) =>
+      s.api.startSession({
+        externalUserId,
+        ...(deviceRef ? { deviceRef } : {}),
+        ...(s.config.workflowId ? { workflowId: s.config.workflowId } : {}),
+      }),
+    );
+    inflightStarts.set(key, start);
+    start.then(
+      () => setTimeout(() => inflightStarts.delete(key), 2000),
+      () => inflightStarts.delete(key),
+    );
+  }
+  void start
+    .then((res) => {
+      store.getState().setSessionId(res.sessionId, res.url ?? null);
+      // Resuming: put the user back where they were, exactly as web does.
+      // Media references are pruned server-side of anything expired, so a
+      // restored capture slot is one whose bytes genuinely still exist.
+      if (res.progress) restoreAttemptProgress(store, res.progress);
+    })
+    .catch(() => undefined);
+}
+
+/**
+ * Hydrate the store from a resumed session's stored progress — the RN mirror
+ * of the web reducer's RESTORE_PROGRESS. Only fields the snapshot carries are
+ * touched; everything else keeps its launch value, so a partial or old
+ * snapshot degrades to restoring less, never to breaking the flow.
+ */
+export function restoreAttemptProgress(
+  store: KycStore,
+  progress: NonNullable<SessionStartResponse['progress']>,
+): void {
+  const s = store.getState();
+  const d = (progress.data ?? {}) as Record<string, unknown>;
+
+  const app = d['businessApplication'] as
+    | (Partial<KycState['businessApplication']> & { keyPeople?: Array<Record<string, unknown>> })
+    | undefined;
+
+  store.setState({
+    // The terminal step is a RESULT, not a position. A submission that FAILED
+    // still writes `submitted` as the last step reached, so resuming there
+    // submits again, fails the same way and writes it again: closing the app
+    // and reopening lands straight back on the error with no way forward.
+    // Starting the flow again also re-resolves the workflow, so an applicant
+    // caught mid-flight across a republish walks the CURRENT steps rather than
+    // submitting against rules they were never shown.
+    ...(typeof progress.step === 'string' && progress.step !== 'submitted'
+      ? { currentStep: progress.step as KycState['currentStep'] }
+      : {}),
+    ...(progress.mediaIds ? { mediaIds: { ...s.mediaIds, ...progress.mediaIds } } : {}),
+    ...(typeof d['selectedCountry'] === 'string'
+      ? { selectedCountry: d['selectedCountry'] as string }
+      : {}),
+    ...(typeof d['selectedIdType'] === 'string'
+      ? { selectedIdType: d['selectedIdType'] as KycState['selectedIdType'] }
+      : {}),
+    ...(typeof d['idNumber'] === 'string' ? { idNumber: d['idNumber'] as string } : {}),
+    ...(d['business'] && typeof d['business'] === 'object'
+      ? { business: { ...s.business, ...(d['business'] as object) } }
+      : {}),
+    ...(app
+      ? {
+          businessApplication: {
+            ...s.businessApplication,
+            ...app,
+            // Rows saved BEFORE the sectioned redesign predate `roles`, `title`
+            // and `owners`; a restored attempt must not hand the cards a shape
+            // they cannot read. Same normalization as web's RESTORE_PROGRESS.
+            ...(app.keyPeople
+              ? {
+                  keyPeople: app.keyPeople.map((row) => ({
+                    ...emptyKeyPerson(),
+                    ...row,
+                    roles:
+                      Array.isArray(row['roles']) && (row['roles'] as unknown[]).length > 0
+                        ? (row['roles'] as KeyPersonEntry['roles'])
+                        : [(row['role'] as KeyPersonEntry['role']) ?? 'director'],
+                    title: typeof row['title'] === 'string' ? (row['title'] as string) : '',
+                    owners: Array.isArray(row['owners'])
+                      ? (row['owners'] as KeyPersonEntry['owners'])
+                      : [],
+                  })),
+                }
+              : {}),
+          } as KycState['businessApplication'],
+        }
+      : {}),
+    ...(d['contact'] && typeof d['contact'] === 'object'
+      ? { contact: { ...s.contact, ...(d['contact'] as object) } }
+      : {}),
+    ...(d['questionnaireAnswers'] && typeof d['questionnaireAnswers'] === 'object'
+      ? {
+          questionnaireAnswers: {
+            ...s.questionnaireAnswers,
+            ...(d['questionnaireAnswers'] as object),
+          },
+        }
+      : {}),
+  });
+}
+
+/** The progress snapshot the server stores — mirrors the web SDK's shape, so
+ *  the dashboard's attempt page reads both without branching. */
+export function progressFromState(s: ReturnType<KycStore['getState']>): Record<string, unknown> {
+  const mediaIds = Object.fromEntries(
+    Object.entries(s.mediaIds ?? {}).filter(([, v]) => typeof v === 'string' && v),
+  );
+  return {
+    step: s.currentStep,
+    stepLog: getStepLog(),
+    mediaIds,
+    data: {
+      selectedCountry: s.selectedCountry ?? undefined,
+      selectedIdType: s.selectedIdType ?? undefined,
+      idNumber: s.idNumber || undefined,
+      business: s.business,
+      businessApplication: s.businessApplication,
+      contact: s.contact,
+      questionnaireAnswers: s.questionnaireAnswers,
+    },
+  };
+}
+
+/** Nothing here needs saving until they move off the opening screen. */
+export function isUntouchedProgress(payload: Record<string, unknown>): boolean {
+  if (payload['step'] !== 'consent') return false;
+  return Object.keys((payload['mediaIds'] as object) ?? {}).length === 0;
+}
+
+/**
+ * Persist progress as the user advances. Debounced, deduped by snapshot, and
+ * a no-op until the session exists.
+ */
+export function watchSessionProgress(store: KycStore): () => void {
+  let timer: ReturnType<typeof setTimeout> | null = null;
+  let lastSaved = '';
+
+  const unsubscribe = store.subscribe(() => {
+    if (timer) clearTimeout(timer);
+    timer = setTimeout(() => {
+      const s = store.getState();
+      if (!s.sessionId) return;
+      const payload = progressFromState(s);
+      if (isUntouchedProgress(payload)) return;
+      const fingerprint = JSON.stringify(payload);
+      if (fingerprint === lastSaved) return;
+      lastSaved = fingerprint;
+      void s.api.saveProgress(s.sessionId, payload).catch(() => undefined);
+    }, SAVE_DEBOUNCE_MS);
+  });
+
+  return () => {
+    unsubscribe();
+    if (timer) clearTimeout(timer);
+  };
+}