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

package/src/store/derive.ts

@@ -7,14 +7,19 @@
 // keeps a single answer to each of those questions.
 // ---------------------------------------------------------------------------
 
+import { configScope } from '../lib/scope';
 import { requiresDocumentCapture, supportsNfcChip } from '../config/idTypes';
 import {
+  buildStepOrder,
   getStepProgress,
   nextStepInOrder,
   previousStepInOrder,
   type StepOrderOptions,
 } from '../config/stepOrder';
 import { hasProofOfAddressStep } from '../config/proofOfAddress';
+import { addressFlowFor, hasAddressCollectionStep } from '../config/addressCollection';
+import { webViewAvailable } from '../lib/webview-available';
+import { addressVendorsStubbed } from '../lib/address-flow';
 import { businessProductsForCountry, isBusinessFlow } from '../config/business';
 import {
   hasApplicantVerification,
@@ -22,6 +27,7 @@ import {
   hasKeyPeopleCollection,
 } from '../config/businessSteps';
 import { hasActiveQuestionnaire } from '../config/questionnaire';
+import { hasConsentStep, openingStepOf } from '../config/consentStep';
 import { applicantSelfCountry, keyPeoplePayload } from '../config/keyPeople';
 import { featuresFor } from './serverConfig';
 import type { VerifyRequest } from '../services/api';
@@ -58,6 +64,7 @@ export function stepOrderOptions(state: KycState): StepOrderOptions {
   const idType = state.selectedIdType;
   return {
     isBusiness: isBusinessFlow(config),
+    scope: configScope(config),
     business: config.business,
     hasDocCapture: idType ? requiresDocumentCapture(idType) : true,
     hasNfc: nfcEnabled(state),
@@ -72,9 +79,20 @@ export function stepOrderOptions(state: KycState): StepOrderOptions {
     hasCountrySelect:
       countrySelectOptions(state).length > 1 &&
       applicantSelfCountry(state.businessApplication) === null,
+    hasConsent: hasConsentStep(config),
     hasEmailVerification: config.emailVerification?.enabled === true,
     hasPhoneVerification: config.phoneVerification?.enabled === true,
     hasPoa: hasProofOfAddressStep(config.proofOfAddress),
+    hasAddressCollection: hasAddressCollectionStep(config.addressCollection),
+    // An absent search flag means no search SCREEN, never an error: the
+    // applicant places the pin by hand, the fallback every address failure
+    // degrades to.
+    addressFlow: addressFlowFor(
+      config,
+      state.serverConfig.addressSearch === true,
+      addressVendorsStubbed({ environment: state.serverConfig.environment }),
+      Boolean(state.serverConfig.mapsFrameUrl) && webViewAvailable(),
+    ),
     hasQuestionnaire: hasActiveQuestionnaire(config.questionnaire),
     // Present only on a session a reviewer sent back. Narrows the order to the
     // steps they ticked, so somebody fixing one blurry photo is not walked
@@ -237,11 +255,18 @@ export function previousStepBefore(step: KYCStep, state: KycState): KYCStep {
   return previousStepInOrder(step, stepOrderOptions(state));
 }
 
+/**
+ * The step this flow OPENS on: 'consent', or the first real step when the
+ * workflow switched the consent screen off (`consentStep: false`). The store
+ * starts and resets here, the progress watcher judges "untouched" against it,
+ * and the flow hides Back on it. Never depends on anything the applicant has
+ * yet to choose: only later steps do.
+ */
+export function openingStep(state: KycState): KYCStep {
+  return openingStepOf(buildStepOrder(stepOrderOptions(state)));
+}
+
 /** Percentage complete, for the sheet's progress indicator. */
 export function stepProgress(step: KYCStep, state: KycState): number {
   return getStepProgress(step, stepOrderOptions(state));
 }
-
-// ---------------------------------------------------------------------------
-// Store factory
-// ---------------------------------------------------------------------------

package/src/store/kycStore.ts

@@ -27,7 +27,7 @@ import {
   type KycState,
   type KycStore,
 } from './state';
-import { nextStepAfter, nfcDecision, previousStepBefore } from './derive';
+import { nextStepAfter, nfcDecision, openingStep, 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. */
@@ -54,12 +54,15 @@ function multiIdPlanFor(s: KycState): ReturnType<typeof multiIdPlan> {
   );
 }
 import { recordStep, resetStepLog } from '../lib/step-log';
+import { resetAutoLocate, resetCurrentFix } from '../lib/address-current-location';
 import { multiIdPlan } from '../lib/multi-id';
 import { resolveIdTypeDefinition } from '../config/idTypes';
 import { buildVerifyRequest } from './submit';
+import { IDLE_SELFIE_UPLOAD } from '../lib/selfie-upload-wait';
 import { resetBusinessCheck, runBusinessCheck } from './businessCheck';
 import { startAttemptSession, watchSessionProgress } from './session';
 import { applicantMediaCaptured, buildApplicantVerifyRequest } from './submitApplicant';
+import { keptIdType } from '../lib/resubmit';
 
 export * from './state';
 export {
@@ -99,11 +102,17 @@ export function createKycStore(
       sessionUrl: null,
       businessCheck: { ...EMPTY_BUSINESS_CHECK },
       selectedCountry: null,
-      selectedIdType: null,
+      countryAutoPicked: false,
+      // A send-back that did not ask for the ID keeps the original one: the
+      // ID steps are narrowed out, so the kept ID is selected here instead.
+      // A restored session only overwrites it with a saved pick.
+      selectedIdType: keptIdType(config.resubmit) as KycState['selectedIdType'],
       idNumber: null,
       multiIdSlotIndex: 0,
       multiIdSlots: [],
       multiIdRestored: null,
+      selfiePreviewUri: null,
+      selfieUpload: IDLE_SELFIE_UPLOAD,
       mediaIds: {},
       submissionResult: null,
       serverConfig: serverConfig ?? INITIAL_SERVER_CONFIG,
@@ -124,6 +133,11 @@ export function createKycStore(
       chipData: null,
       poaDocumentType: null,
       poaFileName: null,
+      address: null,
+      addressPhotoPreview: null,
+      addressIntroSeen: false,
+      addressEntranceFraming: false,
+      addressSandboxOutcome: null,
       isLoading: false,
       error: null,
 
@@ -137,16 +151,27 @@ export function createKycStore(
           const branding = res.branding
             ? { ...res.branding, logo: normalizeDevAssetUrl(res.branding.logo, baseUrl) }
             : res.branding;
+          // The facts that just landed can add a step AHEAD of the one the flow
+          // opened on (the address search step, on a consent-less address
+          // flow). Someone still standing on the placeholder's opening step,
+          // having done nothing, is moved to the real one; anyone who has
+          // moved is left alone. Mirrors Flutter's _loadServerConfig.
+          const before = openingStep(get());
           set({
             serverConfig: {
               status: 'ready',
               idTypes: res.idTypes,
               branding,
               geoCountry: res.geoCountry,
+              addressSearch: res.addressSearch,
+              addressSearchMode: res.addressSearchMode,
+              mapsFrameUrl: res.mapsFrameUrl ?? null,
               environment: res.environment,
               fatal: false,
             },
           });
+          const after = openingStep(get());
+          if (get().currentStep === before && after !== before) set({ currentStep: after });
         } catch (err) {
           const described = describeConfigError(err);
           set((s) => ({
@@ -163,6 +188,7 @@ export function createKycStore(
           const same = s.selectedCountry === country;
           return {
             selectedCountry: country,
+            countryAutoPicked: false,
             selectedIdType: same ? s.selectedIdType : null,
             idNumber: same ? s.idNumber : null,
             // A multi-ID run's committed slots belong to the country they were
@@ -175,6 +201,11 @@ export function createKycStore(
         });
       },
 
+      setCountryAuto(country) {
+        get().setCountry(country);
+        if (!get().countryAutoPicked) set({ countryAutoPicked: true });
+      },
+
       commitMultiIdSlot(nextStep, previews) {
         set((s) => {
           if (!s.selectedIdType) return {};
@@ -257,6 +288,22 @@ export function createKycStore(
         set((s) => ({ mediaIds: { ...s.mediaIds, [key]: mediaId } }));
       },
 
+      setSelfiePreview(uri) {
+        set({ selfiePreviewUri: uri });
+      },
+
+      clearSelfie() {
+        set((s) => ({
+          selfiePreviewUri: null,
+          selfieUpload: IDLE_SELFIE_UPLOAD,
+          mediaIds: { ...s.mediaIds, selfie: undefined, livenessVideo: undefined },
+        }));
+      },
+
+      setSelfieUpload(upload) {
+        set({ selfieUpload: upload });
+      },
+
       setDocumentMediaId(mediaId, side) {
         set((s) => ({
           mediaIds: {
@@ -423,6 +470,41 @@ export function createKycStore(
         });
       },
 
+      setAddress(address) {
+        set({ address });
+      },
+
+      setAddressSandboxOutcome(addressSandboxOutcome) {
+        set({ addressSandboxOutcome });
+      },
+
+      setAddressPhoto(mediaId) {
+        set((s) => {
+          if (mediaId) return { mediaIds: { ...s.mediaIds, addressPhoto: mediaId } };
+          const { addressPhoto: _dropped, ...rest } = s.mediaIds;
+          return { mediaIds: rest };
+        });
+      },
+
+      setAddressPhotoPreview(uri) {
+        set({ addressPhotoPreview: uri });
+      },
+
+      markAddressIntroSeen() {
+        set({ addressIntroSeen: true });
+      },
+
+      setAddressEntranceFraming(framing) {
+        if (get().addressEntranceFraming !== framing) set({ addressEntranceFraming: framing });
+      },
+
+      clearAddress() {
+        set((s) => {
+          const { addressPhoto: _dropped, ...rest } = s.mediaIds;
+          return { address: null, mediaIds: rest, addressPhotoPreview: null };
+        });
+      },
+
       setDocumentCapturePhase(phase) {
         if (get().documentCapturePhase !== phase) set({ documentCapturePhase: phase });
       },
@@ -569,15 +651,29 @@ export function createKycStore(
         // already sitting on 'consent' (the subscribe below only fires on
         // change, and recordStep dedupes if it fires too).
         resetStepLog();
-        recordStep('consent', multiIdSlotOf(get()), selectedIdTypeOf(get()));
+        // The cached GPS fix and the once-per-verification auto-locate are
+        // scoped to ONE verification: an app session spans many opens of the
+        // SDK, and a fix taken an hour ago would drop the pin at wherever the
+        // phone was then.
+        resetCurrentFix();
+        resetAutoLocate();
+        // The opening step never depends on the fields reset below (only later
+        // steps do), so it is safe to read before the write.
+        const opening = openingStep(get());
+        recordStep(opening, multiIdSlotOf(get()), selectedIdTypeOf(get()));
         set({
-          currentStep: 'consent',
+          currentStep: opening,
           selectedCountry: null,
-          selectedIdType: null,
+          countryAutoPicked: false,
+          // Same kept ID as at creation: the narrowed flow has no picker to
+          // choose it again.
+          selectedIdType: keptIdType(config.resubmit) as KycState['selectedIdType'],
           idNumber: null,
           multiIdSlotIndex: 0,
           multiIdSlots: [],
           multiIdRestored: null,
+          selfiePreviewUri: null,
+          selfieUpload: IDLE_SELFIE_UPLOAD,
           mediaIds: {},
           submissionResult: null,
           documentScanPhase: 'front',
@@ -599,6 +695,11 @@ export function createKycStore(
           chipData: null,
           poaDocumentType: null,
           poaFileName: null,
+          address: null,
+          addressPhotoPreview: null,
+          addressIntroSeen: false,
+      addressEntranceFraming: false,
+      addressSandboxOutcome: null,
           isLoading: false,
           error: null,
         });
@@ -622,6 +723,20 @@ export function createKycStore(
   // subscription above only fires on CHANGE, and a new store already sits on
   // 'consent').
   resetStepLog();
+  // The module-level GPS cache and the auto-locate latch are scoped to ONE
+  // verification, and this — not reset() — is where a verification begins.
+  // Clearing them only in reset() left both alive across modal launches, so a
+  // second verification in the same app session dropped its pin wherever the
+  // phone had been on the first (possibly hours and a city away) and skipped
+  // the automatic locate entirely, since the latch was already spent.
+  resetCurrentFix();
+  resetAutoLocate();
+  // A workflow that switched the consent screen off opens on its first real
+  // step; the literal 'consent' above is only the shape before the config is
+  // consulted. Set BEFORE the journey is recorded, so the log opens where the
+  // person does.
+  const opening = openingStep(store.getState());
+  if (opening !== store.getState().currentStep) store.setState({ currentStep: opening });
   recordStep(
     store.getState().currentStep,
     multiIdSlotOf(store.getState()),

package/src/store/serverConfig.ts

@@ -21,6 +21,24 @@ export interface ServerConfigState {
   branding?: SdkConfigBranding;
   /** The visitor's country from their IP — a default, never evidence. */
   geoCountry?: string | null;
+  /**
+   * Whether the platform has a forward-search backend, and which one. Absent
+   * means the address flow simply has no search screen: the applicant places
+   * the pin by hand, which is the fallback every address failure degrades to.
+   *
+   * The Google KEY itself never rides here (it is the hosted page's alone);
+   * the framed picker reaches this SDK as a URL instead — see mapsFrameUrl.
+   * Street View entrance framing still does not exist on mobile.
+   */
+  addressSearch?: boolean;
+  addressSearchMode?: 'autocomplete' | 'basic';
+  /**
+   * The framed Google-map picker page for a WebView (`react-native-webview`,
+   * an optional peer): our hosted /embed/map plus a signed APP grant. Null or
+   * absent ⇒ the built-in OSM picker, which is also the fallback when the
+   * page never reports ready.
+   */
+  mapsFrameUrl?: string | null;
   environment?: 'DEVELOPMENT' | 'SANDBOX' | 'PRODUCTION';
   /** HTTP status of a failed config fetch (if any). */
   statusCode?: number;

package/src/store/session.ts

@@ -1,8 +1,11 @@
 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.
@@ -52,6 +55,9 @@ export function startAttemptSession(store: KycStore): void {
         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);
@@ -140,6 +146,13 @@ export function restoreAttemptProgress(
     ...(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: {
@@ -169,13 +182,19 @@ export function progressFromState(s: ReturnType<KycStore['getState']>): Record<s
       businessApplication: s.businessApplication,
       contact: s.contact,
       questionnaireAnswers: s.questionnaireAnswers,
+      address: s.address ?? undefined,
     },
   };
 }
 
-/** 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;
+/**
+ * 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;
 }
 
@@ -193,7 +212,7 @@ export function watchSessionProgress(store: KycStore): () => void {
       const s = store.getState();
       if (!s.sessionId) return;
       const payload = progressFromState(s);
-      if (isUntouchedProgress(payload)) return;
+      if (isUntouchedProgress(payload, openingStep(s))) return;
       const fingerprint = JSON.stringify(payload);
       if (fingerprint === lastSaved) return;
       lastSaved = fingerprint;

package/src/store/state.ts

@@ -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;
@@ -196,6 +199,70 @@ export interface ContactState {
   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. */
 export type DocumentCapturePhase = 'front' | 'front-preview' | 'back' | 'review';
 
@@ -248,6 +315,13 @@ export interface KycState {
    * 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;
   /**
@@ -266,6 +340,22 @@ export interface KycState {
    * 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;
@@ -337,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
@@ -351,6 +461,9 @@ 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
@@ -359,6 +472,12 @@ export interface KycState {
   /** 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;
@@ -387,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;

package/src/store/submit.ts

@@ -12,11 +12,13 @@
 // unconfigured contact proof must not claim a check that never ran.
 // ---------------------------------------------------------------------------
 
+import { configScope, SCOPE_ID_TYPES } from '../lib/scope';
 import { collectDeviceMetadata } from '../services/deviceMetadata';
 import { generateRequestId } from '../utils/uuid';
 import { hasActiveQuestionnaire, questionnairePayload } from '../config/questionnaire';
 import { multiIdWireSlots } from '../lib/multi-id';
 import { isBusinessFlow } from '../config/business';
+import { addressPayload } from '../config/addressCollection';
 import { businessSubmission, effectiveCountry } from './derive';
 import type { ClientFingerprint } from '../services/fingerprint';
 import type { VerifyRequest } from '../services/api';
@@ -66,7 +68,13 @@ export function buildVerifyRequest(
 
   return {
   country: business ? business.country : effectiveCountry(state),
-  idType: business ? business.product : (primary?.idType ?? state.selectedIdType ?? ''),
+  // Scoped flows carry the scope's transport marker instead of a picked ID —
+  // the server requires a published workflow of the matching scope for it.
+  idType: business
+    ? business.product
+    : configScope(state.config)
+      ? SCOPE_ID_TYPES[configScope(state.config)!]
+      : (primary?.idType ?? state.selectedIdType ?? ''),
   idNumber: business ? undefined : (primary?.idNumber ?? state.idNumber ?? undefined),
   ...(multiSlots
     ? {
@@ -91,6 +99,10 @@ export function buildVerifyRequest(
       : state.mediaIds,
   ...(state.config.workflowId ? { workflowId: state.config.workflowId } : {}),
   ...(state.poaDocumentType ? { proofOfAddressType: state.poaDocumentType } : {}),
+  // The smart address, when the step gathered one. Sent on individual AND
+  // business submissions (a KYB flow's pin is the business premises) — the
+  // server validates it against the workflow either way.
+  ...(state.address ? { address: addressPayload(state.address, state.config.addressCollection) } : {}),
   ...(state.contact.emailToken || state.contact.phoneToken
     ? {
         contact: {
@@ -136,6 +148,11 @@ export function buildVerifyRequest(
     ...(business && state.business.sandboxOutcome
       ? { sandboxOutcome: state.business.sandboxOutcome }
       : {}),
+    // The address flow's Test-result pick (dev/sandbox tabs on the review
+    // step) — same contract, same key, no clash: business flows never set it.
+    ...(!business && state.addressSandboxOutcome
+      ? { sandboxOutcome: state.addressSandboxOutcome }
+      : {}),
     requestId: generateRequestId(),
     device: {
       ...(collectDeviceMetadata() as unknown as Record<string, unknown>),