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

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';
 
@@ -134,6 +142,12 @@ export interface MyazaKYCConfig<C extends SupportedCountry = SupportedCountry> {
      * mirroring the web SDK.
      */
     businessName?: string;
+    /**
+     * The applicant's email, when you already hold it. Not asked for in the flow:
+     * it is submitted so your organisation can have the applicant emailed about a
+     * decision, for example once their verification is approved.
+     */
+    email?: string;
   };
 
   /** Enable the live-selfie capture step. */
@@ -149,6 +163,15 @@ export interface MyazaKYCConfig<C extends SupportedCountry = SupportedCountry> {
    */
   allowDocumentUpload?: boolean;
 
+  /**
+   * Allow photographing the document with the live camera. Default `true`.
+   * When `false`, the document step never asks for camera access: the
+   * applicant chooses a photo of each side from the device instead. At least
+   * one of this and `allowDocumentUpload` stays on, so a config that switches
+   * both off keeps the camera.
+   */
+  allowDocumentScan?: boolean;
+
   /** Enable liveness detection during selfie capture. Default `true`. */
   enableLiveness?: boolean;
 
@@ -164,15 +187,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 +246,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 +333,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) ───────────────────────────────────────────────────