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

package/src/store/session.ts

@@ -0,0 +1,227 @@
+import type { KycState, KycStore } from './state';
+import { collectDeviceMetadata } from '../services/deviceMetadata';
+import { restoreAddress } from './address';
+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';
+import { openingStep } from './derive';
+
+// ---------------------------------------------------------------------------
+// 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 } : {}),
+        // What this phone is, sent up front: the dashboard's in-progress row
+        // shows Device and Source from the moment the SDK loads.
+        device: collectDeviceMetadata() as unknown as Record<string, unknown>,
+      }),
+    );
+    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) } }
+      : {}),
+    // The pin restores only when it is a real pin — a partial snapshot must
+    // degrade to restoring less, never to a shape the step cannot read.
+    ...((() => {
+      const a = d['address'] as Record<string, unknown> | undefined;
+      if (!a || typeof a['lat'] !== 'number' || typeof a['lng'] !== 'number') return {};
+      return { address: restoreAddress(a) };
+    })()),
+    ...(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,
+      address: s.address ?? undefined,
+    },
+  };
+}
+
+/**
+ * Nothing here needs saving until they move off the opening screen. Judged
+ * against the flow's OPENING step ('consent' unless the workflow switched it
+ * off, then the first real step), or a consent-less flow would save on mount
+ * and every opened link would read "In progress" on the dashboard.
+ */
+export function isUntouchedProgress(payload: Record<string, unknown>, opening: string = 'consent'): boolean {
+  if (payload['step'] !== opening) 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, openingStep(s))) 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);
+  };
+}

package/src/store/state.ts

@@ -9,7 +9,7 @@ import type { FlashHole } from '../components/flashHoleGeometry';
 
 import type { StoreApi } from 'zustand/vanilla';
 
-import type { KYCApi, KeyPersonInvite } from '../services/api';
+import type { BusinessCompanyRecord, KYCApi, KeyPersonInvite, RegistryOfficer } from '../services/api';
 import type { IdType, KYCStep, ResolvedKYCConfig } from '../types/config';
 import type { PoaDocumentType } from '../types/workflow';
 import type { ApplicantRole } from '../types/business';
@@ -21,10 +21,13 @@ import type { ServerConfigState } from './serverConfig';
 import type { CaptureIntegrity } from '../liveness/integritySignals';
 import type { MrzScan } from '../mrz/parse';
 import type { EmrtdReadResult } from '../emrtd';
+import type { SelfieUploadState } from '../lib/selfie-upload-wait';
 
 export interface KYCMediaIds {
   /** Proof-of-address document (image or PDF). */
   proofOfAddress?: string;
+  /** Address Intelligence door photo (image only). */
+  addressPhoto?: string;
   documentFront?: string;
   documentBack?: string;
   selfie?: string;
@@ -35,7 +38,7 @@ export interface KYCMediaIds {
 
 export interface KYCSubmissionResult {
   verificationId: string;
-  status: 'pending';
+  status: 'processing';
 }
 
 export type DocumentScanPhase = 'front' | 'back' | 'complete';
@@ -48,12 +51,69 @@ export interface BusinessState {
   product: string | null;
   registrationNumber: string;
   registrationName: string;
+  /** Dev/sandbox only: pins the canned outcome served instead of calling the
+   *  register. Sent as metadata.sandboxOutcome; production ignores it. */
+  sandboxOutcome: string;
+  /** ISO 3166-2 registry region, for the four countries whose register is
+   *  split by state or emirate. Empty for everywhere else. Rides the search
+   *  and the selection-time check; the submission relies on the prepaid
+   *  record, mirroring the web SDK. */
+  subdivisionCode: string;
   /** Where key-people invite links are emailed. */
   contactEmail: string;
   address: string;
   email: string;
   phone: string;
   website: string;
+  /** Registry facts the applicant states; submitted as their own answer. */
+  dateOfIncorporation: string;
+  taxId: string;
+  vatNumber: string;
+  companyType: string;
+  natureOfBusiness: string;
+}
+
+/**
+ * The registry check run when the applicant confirms their company.
+ *
+ * `skipped` and `limit_reached` are normal outcomes, not failures: the
+ * organisation could not be charged (or this application has spent its lookup
+ * budget), so the flow carries on and the check happens at submission instead.
+ * Mirrors the web SDK's BusinessCheckState — keep the two in lockstep.
+ */
+export interface BusinessCheckState {
+  status: 'idle' | 'checking' | 'found' | 'not_found' | 'skipped' | 'unavailable' | 'limit_reached';
+  /** What the register holds, when it answered. */
+  company: BusinessCompanyRecord | null;
+  /** The officers on file — what makes the key-people question a confirmation. */
+  officers: RegistryOfficer[];
+  /** Which company was checked (normalised), so a changed number re-runs it. */
+  checkedNumber: string | null;
+  /**
+   * Which form fields the REGISTER filled, as opposed to the applicant.
+   *
+   * Kept so that changing which company this is can clear exactly those and
+   * nothing else. Without it, switching company left the previous register's
+   * address and email sitting in the form under the new company's name — and
+   * because the prefill only writes into empty fields, those leftovers also
+   * blocked the new register's real values from ever landing.
+   */
+  prefilled: (keyof BusinessState)[];
+}
+
+export const EMPTY_BUSINESS_CHECK: BusinessCheckState = {
+  status: 'idle',
+  company: null,
+  officers: [],
+  checkedNumber: null,
+  prefilled: [],
+};
+
+/** What `checkBusiness` resolves with. Only a definitive "not on the register"
+ *  stops the flow; the company record is handed back for the prefill. */
+export interface BusinessCheckResult {
+  canContinue: boolean;
+  company: BusinessCompanyRecord | null;
 }
 
 /** One uploaded supporting document. */
@@ -83,6 +143,13 @@ export interface BusinessApplicationState {
    * one screening, no duplicate invite.
    */
   applicantKeyPersonIndex: number | null;
+  /**
+   * The applicant attests that no natural person qualifies as a UBO (public
+   * share structures, complex trusts, nominee arrangements) - the FATF
+   * fallback. An attestation the server records and the org can branch on,
+   * never a verdict; the registry lookup still says what it says.
+   */
+  uboUnidentifiable: boolean;
 }
 
 export const EMPTY_BUSINESS_APPLICATION: BusinessApplicationState = {
@@ -91,6 +158,7 @@ export const EMPTY_BUSINESS_APPLICATION: BusinessApplicationState = {
   applicantRole: null,
   applicantName: '',
   applicantKeyPersonIndex: null,
+  uboUnidentifiable: false,
 };
 
 export const EMPTY_BUSINESS: BusinessState = {
@@ -98,11 +166,18 @@ export const EMPTY_BUSINESS: BusinessState = {
   product: null,
   registrationNumber: '',
   registrationName: '',
+  sandboxOutcome: '',
+  subdivisionCode: '',
   contactEmail: '',
   address: '',
   email: '',
   phone: '',
   website: '',
+  dateOfIncorporation: '',
+  taxId: '',
+  vatNumber: '',
+  companyType: '',
+  natureOfBusiness: '',
 };
 
 export interface ContactState {
@@ -112,6 +187,80 @@ export interface ContactState {
   emailToken?: string;
   /** Single-use proof from a passed phone check. */
   phoneToken?: string;
+  /**
+   * Channels whose proof the SERVER refused at submit (422
+   * contact_verification_required). Proofs are single-use and expire ~30
+   * minutes after the OTP check, but they ride session progress and are
+   * restored on resume — so a resumed attempt can carry a dead proof while
+   * the step still shows "verified". This routes the person back to
+   * re-verify instead of a retry that resubmits the same dead token forever;
+   * setContactVerified clears its channel.
+   */
+  expired?: Array<'email' | 'phone'>;
+}
+
+/**
+ * The smart address the address-collection step gathers. The pin is the map
+ * centre the user settled on; the device* fields are the one-shot attest fix
+ * taken at Continue (a CLAIM the server evaluates, never a verdict).
+ */
+export interface AddressState {
+  lat: number;
+  lng: number;
+  accuracy: number | null;
+  directions: string;
+  /** Building or estate name — back on the edit-details form (user decision
+   *  2026-08-31: everything editable, OkHi-style). */
+  propertyName: string;
+  propertyNumber: string;
+  /** A street the applicant TYPED. Prefilled from the map's answer in the
+   *  edit-details sheet; stored only once the applicant edits it, so an
+   *  untouched prefill is never submitted as their claim. */
+  street?: string;
+  /** The rest of the OkHi-style edit-details form: unit + area/region
+   *  corrections. All applicant claims, stored only when typed; the server
+   *  never feeds them into corroboration. undefined = never touched (the
+   *  map's prefill shows), '' = cleared. */
+  unit?: string;
+  neighbourhood?: string;
+  city?: string;
+  state?: string;
+  postcode?: string;
+  /**
+   * The pin's human-readable line, from a search pick or a reverse geocode.
+   * Shown in the flow AND sent with the submission as the applicant-confirmed
+   * line: the server prefers it over its own weaker derivation.
+   */
+  label?: string;
+  /** Where the label was PICKED for. Presence means the label is
+   *  human-confirmed, so it survives pin nudges instead of being re-derived on
+   *  every drag. Absent = the label came from a reverse geocode. Display
+   *  bookkeeping — never on the wire. */
+  pickedAt?: { lat: number; lng: number };
+  /** The applicant explicitly chose to KEEP the picked label after moving the
+   *  pin. Reset when the pin crosses the credibility radius, so the question
+   *  is asked again exactly once out there. Never on the wire. */
+  labelKept?: boolean;
+  /** The label broken down — what the details sheet shows as structured rows.
+   *  Display only, like label's own anchor fields. */
+  parts?: {
+    street?: string | null;
+    area?: string | null;
+    city?: string | null;
+    state?: string | null;
+    postcode?: string | null;
+    /** The pin's own ISO-2, from the geocoder; never a sheet row. */
+    country?: string | null;
+  };
+  /** Street View entrance frame: coordinates only, so the server fetches the
+   *  image with its own key. Captured here through the framed
+   *  /embed/street-view page in a WebView (FramedStreetView), and also
+   *  restored from a session begun on a hosted page. */
+  streetView?: { panoId: string; heading: number; pitch: number; fov: number };
+  deviceLat?: number;
+  deviceLng?: number;
+  deviceAccuracy?: number;
+  capturedAt?: string;
 }
 
 /** Document-capture sub-phase — drives the sheet header title/description. */
@@ -120,18 +269,93 @@ export type DocumentCapturePhase = 'front' | 'front-preview' | 'back' | 'review'
 /** The mediaIds keys settable via `setMediaId`. */
 export type MediaIdKey = keyof KYCMediaIds;
 
+/** One committed multi-ID check. `documentFront/Back` are mediaIds; the
+ *  `*Image` fields are LOCAL previews and never reach the wire. */
+export interface MultiIdSlot {
+  idType: IdType;
+  idNumber?: string;
+  documentFront?: string;
+  documentBack?: string;
+  /** Each check records its OWN document capture. The row's flat
+   *  documentFrontVideo column holds one, so a multi-ID run keeps them per
+   *  check or loses all but one. */
+  documentFrontVideo?: string;
+  documentBackVideo?: string;
+  /** This check's own chip read. The chip belongs to a PARTICULAR document, so
+   *  sending it top-level attributed it to the primary check — which is how a
+   *  passport's chip read was dropped for being submitted alongside a BVN. */
+  chipData?: EmrtdReadResult | null;
+  documentFrontImage?: string;
+  documentBackImage?: string;
+}
+
 export interface KycState {
   config: ResolvedKYCConfig;
   api: KYCApi;
 
   currentStep: KYCStep;
+  /**
+   * The attempt SESSION this run is recorded under (`/session/start`). Null
+   * when minting failed or preview — verifying is never conditional on it. It
+   * rides the /verify body so the verification adopts the session's id, and it
+   * is what the registry check at selection anchors its charge on.
+   */
+  sessionId: string | null;
+  /** The session's own hosted web page (see SessionStartResponse.url). */
+  sessionUrl: string | null;
+  /**
+   * What the register said about the company the applicant identified — the
+   * paid check run at SELECTION (`/business/select`), so the officer list is
+   * already here by the time the key-people step asks for it. `officers` is
+   * the prefill's input; `checkedNumber` stops a re-check of the same company.
+   */
+  businessCheck: BusinessCheckState;
   /**
    * The country picked on the multi-region country-select step. Null on a
    * single-country flow, where `config.country` is the answer.
    */
   selectedCountry: string | null;
+  /**
+   * The declared country was GUESSED (the address scope's IP default, or a
+   * geocode adopted from the applicant's fix) rather than picked, so later
+   * evidence may correct it; an explicit pick clears it. Mirrors the web
+   * SDK's `countryAutoPicked`. See lib/country-adoption.ts.
+   */
+  countryAutoPicked: boolean;
   selectedIdType: IdType | null;
   idNumber: string | null;
+  /**
+   * Multi-ID: which check the applicant is on (0-based), and the ones already
+   * committed. A committed slot keeps its LOCAL preview images as well as its
+   * mediaIds, so stepping back into it restores what was captured rather than
+   * asking for a document that is still perfectly good.
+   */
+  multiIdSlotIndex: number;
+  multiIdSlots: MultiIdSlot[];
+  /**
+   * Capture previews handed back when stepping BACK into a committed slot.
+   *
+   * RN keeps document previews in the capture screen's own state, so a restored
+   * slot has to hand them somewhere the remounting screen can read them. Null
+   * on the forward journey.
+   */
+  multiIdRestored: { front?: string; back?: string } | null;
+  /**
+   * The captured selfie's local file path, kept CENTRALLY (the liveness
+   * screen's own state dies with it on unmount) so leaving the step and
+   * returning restores the review screen instead of re-running the whole
+   * gesture check. mediaIds.selfie beside it is the durable record; on a
+   * restored session the path may be gone while the mediaId survives.
+   */
+  selfiePreviewUri: string | null;
+  /**
+   * Where the selfie (and its liveness video) upload has got to. The liveness
+   * step kicks the upload off and, with the review hidden, hands over BEFORE
+   * it lands; the submitted step waits on this record rather than on the
+   * step that started it (lib/selfie-upload-wait.ts). mediaIds.selfie beside
+   * it is the durable proof; this is the in-flight state.
+   */
+  selfieUpload: SelfieUploadState;
   mediaIds: KYCMediaIds;
   submissionResult: KYCSubmissionResult | null;
   serverConfig: ServerConfigState;
@@ -203,6 +427,26 @@ export interface KycState {
   poaDocumentType: PoaDocumentType | null;
   /** Its file name, so the uploaded state can name what it has. */
   poaFileName: string | null;
+  /** The smart address, when the address-collection step gathered one. */
+  address: AddressState | null;
+  /** Local URI of the uploaded entrance photo, so the review step can show it.
+   *  A display artefact — never serialised, never restored (a resumed session
+   *  holds the mediaId but not the bytes). */
+  addressPhotoPreview: string | null;
+  /** The presence "how it works" primer was acknowledged this session. */
+  addressIntroSeen: boolean;
+  /** The entrance step is showing the Street View framer, so the sheet
+   *  header says so. Transient: never serialised, never restored. */
+  addressEntranceFraming: boolean;
+  /** Dev/sandbox only: the pinned address RESULT outcome (the web SDK's
+   *  Test-result tabs). Null = the server default. Rides
+   *  metadata.sandboxOutcome at submit; production ignores it. */
+  addressSandboxOutcome:
+    | 'address_attested'
+    | 'address_corroborated'
+    | 'address_collected'
+    | 'address_mismatch'
+    | null;
   /**
    * Contact-verification results. The proofs are single-use and ride the
    * /verify submission; the addresses are kept so returning to the step (or a
@@ -217,15 +461,43 @@ export interface KycState {
   // Actions
   loadServerConfig: () => Promise<void>;
   setCountry: (country: string) => void;
+  /** Declare a GUESSED country: the same reset as `setCountry`, flagged so
+   *  later evidence may correct it. Mirrors the web SDK's SET_COUNTRY_AUTO. */
+  setCountryAuto: (country: string) => void;
   setIdType: (idType: IdType) => void;
   setIdNumber: (idNumber: string) => void;
+  /** Commit the current slot's evidence and move to the next check. The
+   *  previews come from the capture screen, which owns them. */
+  commitMultiIdSlot: (nextStep: KYCStep, previews?: { front?: string; back?: string }) => void;
+  /** Step BACK into the previous slot, restoring what it captured. */
+  uncommitMultiIdSlot: (step: KYCStep) => void;
   setMediaId: (key: MediaIdKey, mediaId: string) => void;
+  /** Record the captured selfie's local path (null on retake). */
+  setSelfiePreview: (uri: string | null) => void;
+  /** Retake: drop the selfie preview + its uploaded media ids in one set. */
+  clearSelfie: () => void;
+  /** The upload hook's progress report (see `selfieUpload`). */
+  setSelfieUpload: (upload: SelfieUploadState) => void;
   setDocumentMediaId: (mediaId: string, side: 'front' | 'back') => void;
   setQuestionnaireAnswer: (key: string, value: QuestionnaireAnswerValue | undefined) => void;
   setContactVerified: (channel: 'email' | 'phone', destination: string, token: string) => void;
   setContactDestination: (channel: 'email' | 'phone', destination: string) => void;
+  /** The server refused these channels' proofs at submit — drop the tokens and
+   *  flag the channels so their steps re-verify then resubmit. */
+  clearContactProofs: (channels: Array<'email' | 'phone'>) => void;
   setBusinessField: <K extends keyof BusinessState>(key: K, value: BusinessState[K]) => void;
+  /** Writes the register's answers into empty fields + records which ones it
+   *  filled, in one set — so a company change can clear exactly those. */
+  applyBusinessPrefill: (
+    patch: Partial<BusinessState>,
+    prefilled: (keyof BusinessState)[],
+  ) => void;
+  setSessionId: (sessionId: string, sessionUrl?: string | null) => void;
+  /** Run the paid registry check for the typed company. Never blocks the flow. */
+  checkBusiness: () => Promise<BusinessCheckResult>;
   setKeyPeople: (rows: KeyPersonEntry[]) => void;
+  /** The UBO-exemption attestation (FATF fallback) — see BusinessApplicationState. */
+  setUboUnidentifiable: (checked: boolean) => void;
   setBusinessDocument: (doc: BusinessDocumentUpload) => void;
   removeBusinessDocument: (type: string) => void;
   setApplicant: (role: ApplicantRole, name: string, keyPersonIndex?: number | null) => void;
@@ -234,6 +506,21 @@ export interface KycState {
   setChipData: (data: EmrtdReadResult) => void;
   setProofOfAddress: (mediaId: string, docType: PoaDocumentType, fileName: string) => void;
   clearProofOfAddress: () => void;
+  /** Set / update the smart address (null clears it). */
+  setAddress: (address: AddressState | null) => void;
+  setAddressSandboxOutcome: (outcome: KycState['addressSandboxOutcome']) => void;
+  /** Attach / remove the door photo (null removes it). */
+  setAddressPhoto: (mediaId: string | null) => void;
+  /** Remember the local URI of the picked entrance photo (null on remove). */
+  setAddressPhotoPreview: (uri: string | null) => void;
+  /** The applicant acknowledged the presence primer. */
+  markAddressIntroSeen: () => void;
+  /** The entrance step is (or stops) showing the Street View framer. */
+  setAddressEntranceFraming: (framing: boolean) => void;
+  /** Drop the pin, its uploaded photo and that photo's preview together — a
+   *  half-cleared address would show an entrance for a building nobody
+   *  pinned. */
+  clearAddress: () => void;
   setDocumentCapturePhase: (phase: DocumentCapturePhase) => void;
   setContactChallenge: (challenge: ContactChallenge | null) => void;
   setImmersiveCapture: (immersive: boolean) => void;