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

package/src/store/submit.ts

@@ -12,15 +12,44 @@
 // 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';
 import type { KycState } from './state';
 
+/** The chip payload as the wire wants it. One builder, so a slot's chip and a
+ *  single-ID run's are byte-identical to the server. */
+export function nfcPayload(
+  chip: NonNullable<KycState['chipData']>,
+): NonNullable<VerifyRequest['nfc']> {
+  return {
+    dg1: chip.dg1,
+    ...(chip.sod ? { sod: chip.sod } : {}),
+    ...(chip.dg2 ? { dg2: chip.dg2 } : {}),
+    ...(chip.dg7 ? { dg7: chip.dg7 } : {}),
+    ...(chip.dg11 ? { dg11: chip.dg11 } : {}),
+    ...(chip.dg12 ? { dg12: chip.dg12 } : {}),
+    ...(chip.dg15 ? { dg15: chip.dg15 } : {}),
+    ...(chip.aaSignature ? { aaSignature: chip.aaSignature } : {}),
+    ...(chip.aaChallengeId ? { aaChallengeId: chip.aaChallengeId } : {}),
+    chipAuth: chip.chipAuth,
+    // The PACE diagnostic. Read on every session and, until now, dropped here:
+    // every RN chip read reached the server with paceOutcome null, so the one
+    // question the field exists to answer — did this chip decline PACE, or did
+    // ours fail? — was unanswerable for the whole install base. Flutter has
+    // always sent it.
+    ...(chip.paceOutcome ? { paceOutcome: chip.paceOutcome } : {}),
+    ...(chip.paceDetail ? { paceDetail: chip.paceDetail } : {}),
+  };
+}
+
 export function buildVerifyRequest(
   state: KycState,
   fingerprint: ClientFingerprint | undefined,
@@ -30,17 +59,50 @@ export function buildVerifyRequest(
   // capture media at all.
   const business = isBusinessFlow(state.config) ? businessSubmission(state) : null;
 
+  // Multi-ID: every check was committed as a slot, and the whole run submits as
+  // ONE verification the server judges by the workflow's pass policy. The FIRST
+  // slot fills the single-ID fields, so anything reading a verification's own
+  // idType/idNumber keeps one meaning.
+  const multiSlots = !business && state.multiIdSlots.length >= 2 ? state.multiIdSlots : null;
+  const primary = multiSlots?.[0];
+
   return {
   country: business ? business.country : effectiveCountry(state),
-  idType: business ? business.product : (state.selectedIdType ?? ''),
-  idNumber: business ? undefined : (state.idNumber ?? undefined),
+  // 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
+    ? {
+        idChecks: multiIdWireSlots(multiSlots).map((wire, i) => {
+          const chip = multiSlots[i]?.chipData;
+          return chip ? { ...wire, nfc: nfcPayload(chip) } : wire;
+        }),
+      }
+    : {}),
   ...(business ? { business: business.payload } : {}),
   // The org's user reference (becomes Entity.externalUserId at the KYC seam).
   ...(state.config.userId ? { userId: state.config.userId } : {}),
   userData: business ? undefined : state.config.userData,
-  mediaIds: business ? {} : state.mediaIds,
+  // Multi-ID: the slot documents ride idChecks; only the RUN-level media (the
+  // one selfie and its video) sit at the top level. Sending a slot's document
+  // here too would file the last ID's capture as though it were the
+  // verification's own.
+  mediaIds: business
+    ? {}
+    : multiSlots
+      ? { ...state.mediaIds, documentFront: undefined, documentBack: undefined }
+      : 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: {
@@ -60,16 +122,9 @@ export function buildVerifyRequest(
   // Omitted entirely when absent rather than sent empty: the server treats a
   // present-but-hollow block as a failed read, which is not the same as a
   // document whose chip was never scanned.
-  ...(state.chipData
-    ? {
-        nfc: {
-          dg1: state.chipData.dg1,
-          ...(state.chipData.sod ? { sod: state.chipData.sod } : {}),
-          ...(state.chipData.dg2 ? { dg2: state.chipData.dg2 } : {}),
-          chipAuth: state.chipData.chipAuth,
-        },
-      }
-    : {}),
+  // Multi-ID: the chip rides its OWN check (above) — a top-level payload could
+  // only ever be attributed to the primary one.
+  ...(!multiSlots && state.chipData ? { nfc: nfcPayload(state.chipData) } : {}),
   // Only sent when the flow actually asked — an inactive questionnaire
   // must not put an empty object on the verification record.
   ...(hasActiveQuestionnaire(state.config.questionnaire)
@@ -80,12 +135,24 @@ export function buildVerifyRequest(
         ),
       }
     : {}),
+  // The attempt session this run happened under: the verification adopts its
+  // id, and any registry check paid at selection is not paid again at submit.
+  ...(state.sessionId ? { sessionId: state.sessionId } : {}),
   // `metadata` is free-form passthrough. The SDK-owned keys (`requestId` —
   // the server's idempotency key — and `device`) are written AFTER the
   // caller's metadata so consumer keys can never clobber them. The user
   // reference is the top-level `userId` above. Identical on web + Flutter.
   metadata: {
     ...(state.config.metadata ?? {}),
+    // Ignored by production, so it is safe to send whenever it is set.
+    ...(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/store/submitApplicant.ts

@@ -14,6 +14,7 @@ import { collectDeviceMetadata } from '../services/deviceMetadata';
 import { generateRequestId } from '../utils/uuid';
 import { splitFullName } from '../config/keyPeople';
 import { effectiveCountry } from './derive';
+import { nfcPayload } from './submit';
 import type { ClientFingerprint } from '../services/fingerprint';
 import type { VerifyRequest } from '../services/api';
 import type { KycState } from './state';
@@ -53,17 +54,10 @@ export function buildApplicantVerifyRequest(
     ...(userData ? { userData } : {}),
     mediaIds: state.mediaIds,
     // The chip read, when the leg ran the NFC step (an overlaid applicant
-    // workflow can enable it). Same block as the individual flow's builder.
-    ...(state.chipData
-      ? {
-          nfc: {
-            dg1: state.chipData.dg1,
-            ...(state.chipData.sod ? { sod: state.chipData.sod } : {}),
-            ...(state.chipData.dg2 ? { dg2: state.chipData.dg2 } : {}),
-            chipAuth: state.chipData.chipAuth,
-          },
-        }
-      : {}),
+    // workflow can enable it). Built by the SHARED builder, not a second copy
+    // of the block: a hand-rolled twin drifts silently, and the applicant's
+    // chip must reach the server in the same shape as everyone else's.
+    ...(state.chipData ? { nfc: nfcPayload(state.chipData) } : {}),
     // NO top-level `userId` here on purpose: the server prefers it over
     // metadata.userId, so sending the org's own user ref would sever the
     // KeyPerson link this submission exists to make.

package/src/types/business.ts

@@ -17,8 +17,21 @@ export type KeyPersonRole = 'director' | 'beneficial_owner' | 'signatory' | 'sha
  *  plus 'authorized_representative' (someone filing on the company's behalf). */
 export type ApplicantRole = KeyPersonRole | 'authorized_representative';
 
-/** Supporting-document kinds a KYB workflow can request from the applicant. */
-export const COMPANY_INFO_FIELDS = ['address', 'email', 'phone', 'website'] as const;
+/** Company-profile fields a KYB workflow can ask for. The last five are
+ *  registry facts the applicant STATES (asked as their own answer rather than
+ *  filled from the register, because where the two differ that is the
+ *  finding). Mirrors the web SDK's CompanyInfoField exactly. */
+export const COMPANY_INFO_FIELDS = [
+  'address',
+  'email',
+  'phone',
+  'website',
+  'dateOfIncorporation',
+  'taxId',
+  'vatNumber',
+  'companyType',
+  'natureOfBusiness',
+] as const;
 export type CompanyInfoField = (typeof COMPANY_INFO_FIELDS)[number];
 export type CompanyInfoMode = 'off' | 'optional' | 'required';
 
@@ -55,12 +68,20 @@ export interface WorkflowKeyPeopleConfig {
   requirement?: 'all_in_scope' | 'ubos_only' | 'advisory';
   /** Per-role verification depth overrides (win over `level`). */
   perRole?: Partial<Record<KeyPersonRole, KeyPeopleLevel>>;
+  /** Emails are mandatory for the roles that are sent a verification link. */
+  requireEmail?: boolean;
+  /** Explicit override of WHICH roles must carry an email. */
+  requireEmailRoles?: KeyPersonRole[];
   /** Invite distribution for full-KYC people. */
   invite?: {
     channel?: string;
     /** The KYC workflow the per-person invite links run through. */
     workflowId?: string;
   };
+  /** Nested KYB: a corporate shareholder is invited into its OWN business
+   *  application (the server mints the link; the SDK only tells the applicant
+   *  the truth about what happens to a company they list). */
+  corporateKyb?: { enabled?: boolean; workflowId?: string };
 }
 
 /**

package/src/types/config.ts

@@ -1,3 +1,4 @@
+import type { ResubmitConfig } from '../lib/resubmit';
 // ---------------------------------------------------------------------------
 // The SDK's public configuration.
 //
@@ -6,7 +7,7 @@
 // `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,
@@ -23,6 +24,8 @@ import type {
   ProofOfAddressConfig,
   QuestionnaireConfig,
   WorkflowCountry,
+  MultiIdConfig,
+  AddressCollectionConfig,
 } from './workflow';
 
 export type * from './workflow';
@@ -54,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';
 
@@ -155,16 +165,49 @@ export interface MyazaKYCConfig<C extends SupportedCountry = SupportedCountry> {
    * reflection flash, or both. Workflow-driven.
    */
   livenessMode?: LivenessMode;
+  /**
+   * KYB success screen: after submitting with key people still to verify,
+   * tapping Done offers the session's own web page so the applicant can reach
+   * the invite links again after the app closes. Default true.
+   */
+  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;
@@ -175,6 +218,10 @@ export interface MyazaKYCConfig<C extends SupportedCountry = SupportedCountry> {
    */
   countries?: WorkflowCountry[];
 
+  /** Multi-ID policy: several ID checks in one run, judged by a pass policy.
+   *  KYC only — publish rejects it on a KYB workflow. */
+  multiId?: MultiIdConfig;
+
   /** Email OTP possession check, right after consent. */
   emailVerification?: EmailVerificationConfig;
 
@@ -184,9 +231,22 @@ 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;
 
+  /**
+   * A reviewer sent this attempt back to redo specific steps.
+   *
+   * Never set by a consumer and never part of a published workflow — it is
+   * stamped onto ONE session's config snapshot when somebody clicks "Send back".
+   * Absent means the ordinary full flow.
+   */
+  resubmit?: ResubmitConfig;
+
   /** eMRTD chip read for chip-capable documents. */
   nfc?: NfcConfig;
 
@@ -255,9 +315,17 @@ export interface MyazaKYCConfig<C extends SupportedCountry = SupportedCountry> {
   onStepChange?: (step: KYCStep) => void;
   /**
    * Fires immediately after the user submits. The submission is always
-   * status: 'pending' — results arrive async via webhook.
+   * 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,9 +2,21 @@
 // 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: 'pending';
+  status: 'processing';
   metadata: Record<string, string>;
   submittedAt: string;
 }

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) ───────────────────────────────────────────────────
@@ -141,11 +237,26 @@ export interface WorkflowCountry {
   idTypes?: string[];
   /** Per-ID validation toggles — restrict-only; they never widen a grant. */
   idOptions?: Record<string, WorkflowIdOption>;
+  /** Multi-ID: which IDs THIS country offers for each verification in the run.
+   *  A pinned slot keeps its list; an absent entry offers everything. */
+  multiIdSlots?: Array<{ idTypes?: string[] }>;
   govDbCheck?: boolean;
   documentIntelligence?: boolean;
 }
 
 // ── Liveness ────────────────────────────────────────────────────────────────
 
+/**
+ * Multi-ID: several ID checks in ONE run, one selfie, one verification. The
+ * POLICY is workflow-level; WHICH IDs each verification offers is per country
+ * (`WorkflowCountry.multiIdSlots`), so multi-region flows work.
+ */
+export interface MultiIdConfig {
+  /** How many IDs the applicant completes (2–3). */
+  count: number;
+  /** How many must pass for the verification to be VERIFIED. */
+  minPassed: number;
+}
+
 /** Gestures (default), screen-reflection flash, or both. */
 export type LivenessMode = 'gestures' | 'flash' | 'both';