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

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>),

package/src/types/config.ts

@@ -7,7 +7,7 @@ import type { ResubmitConfig } from '../lib/resubmit';
 // `types/config` remains the single import for consumers.
 // ---------------------------------------------------------------------------
 
-import type { KYCSubmission, KYCError } from './verification';
+import type { KYCSubmission, KYCError, KYCResult } from './verification';
 import type { IdType, IdTypeForCountry, SupportedCountry } from './id-types';
 import type {
   KYCAppearance,
@@ -25,6 +25,7 @@ import type {
   QuestionnaireConfig,
   WorkflowCountry,
   MultiIdConfig,
+  AddressCollectionConfig,
 } from './workflow';
 
 export type * from './workflow';
@@ -56,6 +57,13 @@ export type KYCStep =
   | 'applicant-role'
   | 'liveness'
   | 'proof-of-address'
+  // The address flow, in order: find it (search) → confirm it (the PIN step,
+  // which keeps the original 'address-collection' wire name so older session
+  // progress restores cleanly) → show it (entrance photo) → commit it.
+  | 'address-search'
+  | 'address-collection'
+  | 'address-entrance'
+  | 'address-review'
   | 'questionnaire'
   | 'submitted';
 
@@ -164,15 +172,42 @@ export interface MyazaKYCConfig<C extends SupportedCountry = SupportedCountry> {
    */
   keyPeopleLinkRecovery?: boolean;
 
+  /**
+   * Show the consent (welcome) screen as the flow's first step. Default true.
+   * `false` is for a host app that has already collected the person's
+   * consent: the flow then opens straight on its first real step (the contact
+   * codes, the country picker, the ID list, the business form, or a scoped
+   * flow's own check). Normally set by a workflow. It does not change what
+   * the organisation attests to the verification provider.
+   */
+  consentStep?: boolean;
+
   /** Colours in the flash sequence (2–5, default 4). Flash modes only. */
   flashSequenceLength?: number;
 
+  /**
+   * The biometric scopes' flow options (workflow-driven, or passed here on a
+   * prop-configured mount): `selfieReview` shows the captured selfie with
+   * Retake and Continue before submitting (off by default on both biometric
+   * scopes); `resultDelivery` says where a re-authentication's verdict lands,
+   * 'both' (the default: the SDK holds the person on one loading screen until
+   * the check settles, and the org's webhook receives it too), 'app' (the
+   * same wait, but the server sends no webhook for the check) or 'webhook'
+   * (fire-and-forget); `doneButton` (default true) hides the final screen's Done
+   * when the host app closes the flow itself from `onResult`. A flow key wins
+   * per field. See config/biometricOptions.
+   */
+  biometric?: import('../config/biometricOptions').BiometricFlowConfig;
+
   // ── Workflow-driven blocks ────────────────────────────────────────────────
   // Authored in the dashboard's workflow builder, not usually in consumer code.
   // A resolved flow always wins over a prop of the same name.
 
   /** What this flow verifies. Absent = 'individual' (classic KYC). */
   subjectType?: SubjectType;
+  /** Workflow scope — what this flow verifies (absent = full verification).
+   *  Only ever set by a resolved workflow config / hosted session snapshot. */
+  scope?: import('../lib/scope').WorkflowScope;
 
   /** KYB registry configuration. Required when `subjectType` is 'business'. */
   business?: WorkflowBusinessConfig;
@@ -196,6 +231,10 @@ export interface MyazaKYCConfig<C extends SupportedCountry = SupportedCountry> {
   /** Proof-of-address document check, after capture. */
   proofOfAddress?: ProofOfAddressConfig;
 
+  /** Address Intelligence: a map-pin smart address (+ optional door photo and
+   *  directions), corroborated server-side. KYC AND KYB (premises pin). */
+  addressCollection?: AddressCollectionConfig;
+
   /** Compliance declarations asked just before submission. */
   questionnaire?: QuestionnaireConfig;
 
@@ -279,6 +318,14 @@ export interface MyazaKYCConfig<C extends SupportedCountry = SupportedCountry> {
    * status: 'processing' — results arrive async via webhook.
    */
   onSubmit?: (submission: KYCSubmission) => void;
+  /**
+   * Fires once with the verdict when the flow WAITS for it in-app (a
+   * biometric re-authentication on `resultDelivery: 'both'`, the default, or 'app').
+   * Never fires on a fire-and-forget flow, and never on a wait that timed out:
+   * the webhook stays the record either way. Carries state and reason only,
+   * never result data.
+   */
+  onResult?: (result: KYCResult) => void;
   onClose?: () => void;
   /**
    * Fires for technical errors only. Receives a {@link KYCError} carrying a

package/src/types/verification.ts

@@ -2,6 +2,18 @@
 // Submission callback payload (returned to onSubmit)
 // ---------------------------------------------------------------------------
 
+/**
+ * The verdict a flow that waited for it hands to `onResult`: the same state
+ * vocabulary `GET /api/kyc/status/:id` serves, plus the reason pair. No result
+ * data (scores, biodata) ever rides here; that stays behind the secret key.
+ */
+export interface KYCResult {
+  verificationId: string;
+  status: import('../services/api-types').SessionStatus;
+  reason: string | null;
+  reasonCode: string | null;
+}
+
 export interface KYCSubmission {
   verificationId: string;
   status: 'processing';

package/src/types/workflow.ts

@@ -13,7 +13,16 @@
 
 // ── Proof of Address ────────────────────────────────────────────────────────
 
-export type PoaDocumentType = 'utility_bill' | 'bank_statement' | 'tenancy_agreement' | 'other';
+export type PoaDocumentType =
+  | 'utility_bill'
+  | 'bank_statement'
+  | 'tenancy_agreement'
+  | 'government_document'
+  | 'other';
+
+/** Whether the applicant's name must appear on the document — judged by the
+ *  server; read here only to word the step. */
+export type PoaNameRule = 'required' | 'optional' | 'off';
 
 export interface ProofOfAddressConfig {
   /** Adds the Proof of Address step (after capture, before the questionnaire). */
@@ -24,6 +33,93 @@ export interface ProofOfAddressConfig {
   otherLabel?: string;
   /** Recency window the server checks the document date against (default 90). */
   maxAgeDays?: number;
+  /**
+   * The org's accepted countries (absent/empty = all). On the ADDRESS SCOPE
+   * this is exactly what the declared-country picker offers; on a full flow it
+   * gates the step client-side (the server stays soft).
+   */
+  countries?: string[];
+  /**
+   * Per-country document-kind overrides (ISO-2 → kinds). A present entry
+   * REPLACES `documentTypes` for that country.
+   */
+  countryDocuments?: Record<string, PoaDocumentType[]>;
+  /** The default name rule for every country and kind (absent = required). */
+  nameMatch?: PoaNameRule;
+  /** Per-country, per-kind exceptions to `nameMatch` (ISO-2 → kind → rule). */
+  countryNameMatch?: Record<string, Partial<Record<PoaDocumentType, PoaNameRule>>>;
+}
+
+// ── Address Intelligence (smart-address capture) ────────────────────────────
+
+export interface AddressCollectionConfig {
+  /** Adds the address-collection step (after Proof of Address; on KYB flows it
+   *  collects the business premises pin). */
+  enabled?: boolean;
+  /** Block Continue without a confirmed pin (the server 422s without one too). */
+  requirePin?: boolean;
+  /** Whether the door-photo input is offered/required (default optional). */
+  photo?: 'off' | 'optional' | 'required';
+  /** Whether the directions field is offered/required (default optional). */
+  directions?: 'off' | 'optional' | 'required';
+  /**
+   * The GROUP default for the typed details-sheet fields: `'off'` hides them
+   * all, `'optional'` (the default) offers them, `'required'` requires the
+   * house or flat NUMBER (the building name stays optional). Resolved per
+   * field by lib/address-field-modes.ts, the mirror of the server's rule; the
+   * pin step holds Continue and the review holds Confirm until every required
+   * field shows a value, because the server 422s a submission that arrives
+   * without one.
+   */
+  propertyFields?: 'off' | 'optional' | 'required';
+  /**
+   * Per-field overrides on the group default, keyed by the typed field
+   * (`propertyName`, `propertyNumber`, `street`, `unit`, `neighbourhood`,
+   * `city`, `state`, `postcode`). A `'required'` field the applicant leaves on
+   * its map prefill is submitted as displayed: they saw it and confirmed by
+   * continuing.
+   */
+  fields?: Partial<
+    Record<
+      'propertyName' | 'propertyNumber' | 'street' | 'unit' | 'neighbourhood' | 'city' | 'state' | 'postcode',
+      'off' | 'optional' | 'required'
+    >
+  >;
+  /**
+   * Street View entrance framing. Default 'optional' (on wherever coverage
+   * exists, with the photo as the fallback); 'required' is a client-UX gate
+   * that removes the Skip affordance while coverage exists — no-coverage
+   * still falls back to the photo, and the server never refuses over it.
+   *
+   * Offered on mobile through the hosted /embed/street-view page in a
+   * WebView on the app grant, the way the framed map is (needs the server's
+   * maps frame URL and the optional `react-native-webview` peer); without
+   * either the entrance step is photo-only. See addressFlowOptions.
+   */
+  streetView?: 'off' | 'optional' | 'required';
+  /**
+   * Take a one-shot device GPS fix when the pin is confirmed, so the server
+   * can judge "captured at the claimed address" (the `attested` tier). The fix
+   * is a CLAIM the server evaluates, never a verdict.
+   */
+  attestPresence?: boolean;
+  /**
+   * Phase 2: multi-day presence verification. When enabled, the SDK stores the
+   * confirmed pin ON-DEVICE so later `reportAddressPresence()` calls can
+   * evaluate the fence locally — coordinates never leave the phone after
+   * capture. `background` is reserved for the org-opt-in OS-geofence tier.
+   */
+  presence?: {
+    enabled?: boolean;
+    windowDays?: number;
+    minNights?: number;
+    minDays?: number;
+    dwellFloorMinutes?: number;
+    background?: boolean;
+    /** OkHi-style always-on monitoring: the server renews each
+     *  resolved cycle, and the on-device pin never self-expires. */
+    alwaysOn?: boolean;
+  };
 }
 
 // ── NFC chip read (eMRTD) ───────────────────────────────────────────────────