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

package/src/store/kycStore.ts

@@ -62,6 +62,7 @@ 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 {
@@ -102,7 +103,10 @@ export function createKycStore(
       businessCheck: { ...EMPTY_BUSINESS_CHECK },
       selectedCountry: null,
       countryAutoPicked: false,
-      selectedIdType: null,
+      // 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: [],
@@ -122,6 +126,7 @@ export function createKycStore(
       contactChallenge: null,
       business: EMPTY_BUSINESS,
       businessApplication: EMPTY_BUSINESS_APPLICATION,
+      supportingDocuments: [],
       applicantKeyPersonId: null,
       keyPeopleInvites: [],
       captureIntegrity: null,
@@ -419,6 +424,20 @@ export function createKycStore(
         }));
       },
 
+      setSupportingDocument(doc) {
+        set((s) => ({
+          // One upload per document, like the business slots: re-uploading
+          // replaces rather than appends.
+          supportingDocuments: [...s.supportingDocuments.filter((d) => d.type !== doc.type), doc],
+        }));
+      },
+
+      removeSupportingDocument(type) {
+        set((s) => ({
+          supportingDocuments: s.supportingDocuments.filter((d) => d.type !== type),
+        }));
+      },
+
       removeBusinessDocument(type) {
         set((s) => ({
           businessApplication: {
@@ -661,7 +680,9 @@ export function createKycStore(
           currentStep: opening,
           selectedCountry: null,
           countryAutoPicked: false,
-          selectedIdType: null,
+          // 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: [],

package/src/store/session.ts

@@ -90,6 +90,17 @@ export function restoreAttemptProgress(
   const s = store.getState();
   const d = (progress.data ?? {}) as Record<string, unknown>;
 
+  // Validate-and-drop: a snapshot written by an older build must degrade to
+  // restoring less, never to breaking the flow.
+  const restoredDocs = Array.isArray(d['supportingDocuments'])
+    ? (d['supportingDocuments'] as unknown[]).filter(
+        (doc): doc is { type: string; mediaId: string } =>
+          !!doc &&
+          typeof doc === 'object' &&
+          typeof (doc as { type?: unknown }).type === 'string' &&
+          typeof (doc as { mediaId?: unknown }).mediaId === 'string',
+      )
+    : null;
   const app = d['businessApplication'] as
     | (Partial<KycState['businessApplication']> & { keyPeople?: Array<Record<string, unknown>> })
     | undefined;
@@ -116,6 +127,7 @@ export function restoreAttemptProgress(
     ...(d['business'] && typeof d['business'] === 'object'
       ? { business: { ...s.business, ...(d['business'] as object) } }
       : {}),
+    ...(restoredDocs ? { supportingDocuments: restoredDocs } : {}),
     ...(app
       ? {
           businessApplication: {
@@ -180,6 +192,12 @@ export function progressFromState(s: ReturnType<KycStore['getState']>): Record<s
       idNumber: s.idNumber || undefined,
       business: s.business,
       businessApplication: s.businessApplication,
+      // The uploads without their preview names: a restored attempt shows the
+      // slot as uploaded, which is what the mediaId is for.
+      supportingDocuments:
+        s.supportingDocuments.length > 0
+          ? s.supportingDocuments.map((d) => ({ type: d.type, mediaId: d.mediaId }))
+          : undefined,
       contact: s.contact,
       questionnaireAnswers: s.questionnaireAnswers,
       address: s.address ?? undefined,

package/src/store/state.ts

@@ -402,6 +402,24 @@ export interface KycState {
   business: BusinessState;
   /** The rest of the KYB application: people, documents, applicant role. */
   businessApplication: BusinessApplicationState;
+
+  /**
+   * Supporting documents the person uploaded — artefacts the org holds on
+   * file, not the identity evidence this verification is decided on.
+   * `fileName` is display only and never rides the wire or session progress.
+   */
+  supportingDocuments: Array<{
+    type: string;
+    mediaId: string;
+    fileName?: string;
+    /**
+     * Local URI of the picked image, for the card's thumbnail. Display only,
+     * like `fileName`: it never rides the wire or session progress, so a
+     * restored attempt shows the slot uploaded without a preview.
+     */
+    previewUri?: string;
+    isPdf?: boolean;
+  }>;
   /**
    * Set by a KYB submission that requires applicant verification — the
    * KeyPerson id the applicant's own individual check links back to.
@@ -500,6 +518,14 @@ export interface KycState {
   setUboUnidentifiable: (checked: boolean) => void;
   setBusinessDocument: (doc: BusinessDocumentUpload) => void;
   removeBusinessDocument: (type: string) => void;
+  setSupportingDocument: (doc: {
+    type: string;
+    mediaId: string;
+    fileName?: string;
+    previewUri?: string;
+    isPdf?: boolean;
+  }) => void;
+  removeSupportingDocument: (type: string) => void;
   setApplicant: (role: ApplicantRole, name: string, keyPersonIndex?: number | null) => void;
   setCaptureIntegrity: (integrity: CaptureIntegrity) => void;
   setMrzScan: (scan: MrzScan) => void;

package/src/store/submit.ts

@@ -99,6 +99,17 @@ export function buildVerifyRequest(
       : state.mediaIds,
   ...(state.config.workflowId ? { workflowId: state.config.workflowId } : {}),
   ...(state.poaDocumentType ? { proofOfAddressType: state.poaDocumentType } : {}),
+  // Supporting documents — artefacts held on file. The server validates them
+  // against the resolved workflow's request list and drops anything it did
+  // not ask for. File names are display only and never ride the wire.
+  ...(state.supportingDocuments.length > 0
+    ? {
+        supportingDocuments: state.supportingDocuments.map((d) => ({
+          type: d.type,
+          mediaId: d.mediaId,
+        })),
+      }
+    : {}),
   // 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.

package/src/types/config.ts

@@ -22,6 +22,7 @@ import type {
   NfcConfig,
   PhoneVerificationConfig,
   ProofOfAddressConfig,
+  SupportingDocumentsConfig,
   QuestionnaireConfig,
   WorkflowCountry,
   MultiIdConfig,
@@ -57,6 +58,7 @@ export type KYCStep =
   | 'applicant-role'
   | 'liveness'
   | 'proof-of-address'
+  | 'supporting-documents'
   // 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.
@@ -142,6 +144,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. */
@@ -157,6 +165,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;
 
@@ -231,6 +248,14 @@ export interface MyazaKYCConfig<C extends SupportedCountry = SupportedCountry> {
   /** Proof-of-address document check, after capture. */
   proofOfAddress?: ProofOfAddressConfig;
 
+  /**
+   * Supporting documents: artefacts the org holds ON FILE, which are NOT the
+   * identity evidence the verification is decided on. The org names each one
+   * and writes the guidance under it; the result of any check never changes
+   * the verification's own status.
+   */
+  supportingDocuments?: SupportingDocumentsConfig;
+
   /** Address Intelligence: a map-pin smart address (+ optional door photo and
    *  directions), corroborated server-side. KYC AND KYB (premises pin). */
   addressCollection?: AddressCollectionConfig;

package/src/types/workflow.ts

@@ -24,6 +24,45 @@ export type PoaDocumentType =
  *  server; read here only to word the step. */
 export type PoaNameRule = 'required' | 'optional' | 'off';
 
+/**
+ * One requested supporting document. There is no catalogue: the organisation
+ * names its own, so the SDK renders the title and guidance the workflow sent.
+ */
+export interface SupportingDocumentRequest {
+  /** The organisation's own slug — the wire `type` this upload submits as. */
+  key: string;
+  /** The title the applicant reads. A document without one is not asked for. */
+  label?: string;
+  /** Guidance under the slot: which document, and what it has to show. */
+  description?: string;
+  /** Server-side only: what the document is corroborated against. */
+  checks?: Array<'id_number' | 'name'>;
+  /**
+   * The named values the server will read off it. The SDK reads the NAMES
+   * alone, to tell the applicant what the document is being taken for; the
+   * reading itself is entirely server-side.
+   */
+  fields?: Array<{ key: string; label?: string }>;
+  required?: boolean;
+  /** Which verified IDs it is asked for, as "CC/idType". Absent = every ID. */
+  idTypes?: string[];
+  /**
+   * Offer it on every flow, whatever ID was verified, so `idTypes` decides only
+   * who MUST provide it rather than who sees the slot. Absent = the scope hides
+   * it from everybody else, which is the default.
+   */
+  alwaysAsk?: boolean;
+}
+
+export interface SupportingDocumentsConfig {
+  enabled?: boolean;
+  types?: SupportingDocumentRequest[];
+  /** Server-side only. */
+  retentionDays?: number;
+  /** Server-side only. */
+  returnedData?: string[];
+}
+
 export interface ProofOfAddressConfig {
   /** Adds the Proof of Address step (after capture, before the questionnaire). */
   enabled?: boolean;

package/src/MyazaBiometricAuth.tsx

@@ -1,119 +0,0 @@
-import React, { useCallback, useState } from 'react';
-import { Modal, Platform } from 'react-native';
-
-import { KycRuntimeProvider, MyazaThemeProvider } from './components/runtime';
-import { MyazaButton } from './components/MyazaButton';
-import { BiometricAuthFlow } from './screens/biometric/BiometricAuthFlow';
-import { primeFaceModel } from './liveness/visionCameraFaceDetector';
-import { defaultReauthLabel } from './lib/biometric-auth';
-import type { KYCAppearance, ResolvedKYCConfig, SupportedCountry } from './types/config';
-import type { KYCError } from './types/verification';
-import type { BiometricAuthResponse } from './services/api-types-biometric';
-
-// ---------------------------------------------------------------------------
-// MyazaBiometricAuth — returning-user face re-authentication ("prove it's
-// still you"). Mirrors the web SDK's MyazaBiometricAuth: a verified user
-// re-authenticates with a live selfie matched 1:1 against their enrollment
-// reference (no gov-DB call, no re-KYC). Self-contained: its own trigger +
-// modal, hosting the SDK's real liveness step inside a scoped runtime.
-// ---------------------------------------------------------------------------
-
-export interface MyazaBiometricAuthProps {
-  /** Publishable API key (`pk_…`). The environment is derived from its prefix. */
-  apiKey: string;
-  /** Dev-only base-URL override for `pk_dev_` keys. */
-  devUrl?: string;
-  /** The org's user reference (Entity.externalUserId) to re-authenticate. */
-  externalUserId: string;
-  /** Presence Intelligence method (default 'gestures'). */
-  livenessMode?: 'gestures' | 'flash' | 'both';
-  flashSequenceLength?: number;
-  appearance?: KYCAppearance;
-  disableClose?: boolean;
-  /** Open the modal on mount (no trigger button is rendered). */
-  defaultOpen?: boolean;
-  /** Custom trigger label (default "Verify it's you"). */
-  children?: string;
-  disabled?: boolean;
-  onOpen?: () => void;
-  /** The user re-authenticated. `token` is a single-use proof — verify it from
-   *  your backend with a secret key at `/biometric/verify-proof`. */
-  onAuthenticated?: (result: { attemptId: string; confidence: number | null; token?: string }) => void;
-  /** The check ran but the user did not pass (no match / liveness failed). */
-  onFailed?: (result: { status: BiometricAuthResponse['status']; attemptId: string; confidence: number | null }) => void;
-  /** A technical error (network, not enrolled, insufficient credits, …). */
-  onError?: (error: KYCError) => void;
-  onClose?: () => void;
-}
-
-const MODAL_PRESENTATION = Platform.OS === 'ios' ? 'pageSheet' : 'fullScreen';
-
-export function MyazaBiometricAuth(props: MyazaBiometricAuthProps): React.ReactElement {
-  const { children, disabled, defaultOpen, onOpen, onAuthenticated, onFailed, onError, onClose } = props;
-  const [open, setOpen] = useState(defaultOpen === true);
-
-  // The liveness step reads exactly the keys a KYC flow's config carries; the
-  // scope parks the step order on consent → liveness → submitted, and the
-  // flow only ever mounts the middle one. `country` is required by the
-  // resolved shape but nothing on this path reads it.
-  const config: ResolvedKYCConfig = {
-    apiKey: props.apiKey,
-    devUrl: props.devUrl,
-    country: 'NG' as SupportedCountry,
-    scope: 'biometric-authentication',
-    enableSelfie: true,
-    livenessMode: props.livenessMode ?? 'gestures',
-    flashSequenceLength: props.flashSequenceLength,
-    appearance: props.appearance,
-    disableClose: props.disableClose,
-    userId: props.externalUserId,
-    onError,
-  };
-
-  const openFlow = useCallback(() => {
-    void primeFaceModel();
-    setOpen(true);
-    onOpen?.();
-  }, [onOpen]);
-  const close = useCallback(() => {
-    setOpen(false);
-    onClose?.();
-  }, [onClose]);
-  const blockDismiss = props.disableClose === true;
-
-  return (
-    <MyazaThemeProvider appearance={props.appearance}>
-      {defaultOpen !== true && (
-        <MyazaButton
-          label={children ?? defaultReauthLabel(props.appearance?.companyName)}
-          disabled={disabled}
-          fullWidth={false}
-          onPress={openFlow}
-        />
-      )}
-      <Modal
-        visible={open}
-        animationType="slide"
-        presentationStyle={blockDismiss ? 'fullScreen' : MODAL_PRESENTATION}
-        statusBarTranslucent
-        navigationBarTranslucent
-        onRequestClose={blockDismiss ? () => undefined : close}
-        onDismiss={blockDismiss ? undefined : close}
-      >
-        {open ? (
-          // A fresh store per open: the runtime provider creates it once per
-          // mount, and the modal's children mount once per open.
-          <KycRuntimeProvider config={config}>
-            <BiometricAuthFlow
-              externalUserId={props.externalUserId}
-              onAuthenticated={(r) => onAuthenticated?.({ attemptId: r.attemptId, confidence: r.confidence, token: r.token })}
-              onFailed={(r) => onFailed?.({ status: r.status, attemptId: r.attemptId, confidence: r.confidence })}
-              onError={onError}
-              onClose={close}
-            />
-          </KycRuntimeProvider>
-        ) : null}
-      </Modal>
-    </MyazaThemeProvider>
-  );
-}

package/src/components/icon-map.ts

@@ -1,176 +0,0 @@
-import {
-  Info, BadgeCheck, BookUser, Building2, Stamp, Calendar, Camera, CameraOff, ChevronDown,
-  ChevronLeft, ChevronRight, Car, Check, CircleAlert, Contact, CreditCard, Fingerprint,
-  FileText, FlaskConical, IdCard, Image as ImageIcon, Landmark, Lightbulb, LocateFixed, MapPin,
-  MapPinHouse, MapPinCheck, MapPinned, Radar, BellRing, SlidersHorizontal, Minus, Globe, House,
-  Mail, Maximize2, Lock, MessageCircle, MessageSquare, Moon, MoveLeft, Nfc, Filter, Pencil,
-  PencilLine, Smartphone, RefreshCw, RefreshCcw, ScanFace, ScanLine, Search, Zap, ZapOff,
-  CircleDashed, CircleCheck, CircleHelp, CircleX, ShieldCheck, Sun, Timer, Upload, Plus,
-  UserRound, UserRoundPlus, Link2, Copy, Share2, UsersRound, VideoOff, Vote, X,
-  type LucideIcon
-} from 'lucide-react-native';
-
-// Centralised icon set — the SAME Lucide icons the Flutter SDK uses
-// (`lucide_icons_flutter`) and the web SDK uses (`lucide-react`), so the
-// glyphs are pixel-identical across all three platforms. The component that
-// draws them is Icon.tsx (200-line split).
-
-export type IconName =
-  // chrome
-  | 'close'
-  | 'back'
-  | 'moon'
-  | 'sun'
-  | 'check'
-  | 'lock'
-  | 'alert'
-  | 'flask'
-  | 'refresh'
-  | 'refresh-ccw'
-  | 'maximize'
-  | 'calendar'
-  | 'image'
-  | 'chevron-left'
-  | 'chevron-right'
-  | 'chevron-down'
-  // consent hero + process steps
-  | 'shield'
-  | 'badge-check'
-  | 'circle-dashed'
-  | 'circle-check'
-  | 'circle-help'
-  | 'circle-x'
-  | 'building-2'
-  | 'stamp'
-  | 'user'
-  | 'user-plus'
-  | 'plus'
-  | 'info'
-  | 'users'
-  | 'scan-line'
-  | 'scan-face'
-  | 'nfc'
-  | 'filter'
-  | 'pencil'
-  | 'pencil-line'
-  | 'search'
-  | 'zap'
-  | 'link'
-  | 'copy'
-  | 'share'
-  | 'zap-off'
-  | 'timer'
-  // id-type glyphs
-  | 'fingerprint'
-  | 'credit-card'
-  | 'globe'
-  | 'car'
-  | 'vote'
-  | 'file-text'
-  | 'house'
-  | 'landmark'
-  | 'id-card'
-  | 'contact'
-  | 'passport'
-  | 'camera'
-  | 'camera-off'
-  | 'video-off'
-  | 'upload'
-  | 'x'
-  // address collection (map picker + the presence milestone track)
-  | 'map-pin'
-  | 'map-pin-house'
-  | 'map-pin-check'
-  | 'map-pinned'
-  | 'radar'
-  | 'bell-ring'
-  | 'sliders'
-  | 'locate'
-  | 'minus'
-  | 'lightbulb'
-  // contact verification (OTP channels + step footer)
-  | 'mail'
-  | 'smartphone'
-  | 'message-square'
-  | 'message-circle';
-
-// Maps each name to its Lucide component. Names mirror the Flutter SDK exactly:
-//   shieldCheck · badgeCheck · userRound · scanLine · scanFace · fingerprint ·
-//   creditCard · globe · car · vote · fileText  (+ chrome: X / ArrowLeft /
-//   Moon / Sun / Check / Lock / CircleAlert / RefreshCw / Camera).
-export const ICONS: Record<IconName, LucideIcon> = {
-  close: X,
-  back: MoveLeft, // longer-shaft left arrow, matching Flutter's keyboard_backspace
-  moon: Moon,
-  sun: Sun,
-  check: Check,
-  lock: Lock,
-  alert: CircleAlert,
-  // The environment banner's mark, shared with the web SDK (same lucide glyph)
-  // and mirrored by Flutter's Icons.science_outlined.
-  flask: FlaskConical,
-  refresh: RefreshCw,
-  'refresh-ccw': RefreshCcw,
-  maximize: Maximize2,
-  calendar: Calendar,
-  image: ImageIcon,
-  'chevron-left': ChevronLeft,
-  'chevron-right': ChevronRight,
-  'chevron-down': ChevronDown,
-  shield: ShieldCheck,
-  'badge-check': BadgeCheck,
-  'circle-dashed': CircleDashed,
-  'circle-check': CircleCheck,
-  'circle-help': CircleHelp,
-  'circle-x': CircleX,
-  'building-2': Building2,
-  stamp: Stamp,
-  user: UserRound,
-  info: Info,
-  'user-plus': UserRoundPlus,
-  plus: Plus,
-  link: Link2,
-  copy: Copy,
-  share: Share2,
-  users: UsersRound,
-  'scan-line': ScanLine,
-  'scan-face': ScanFace,
-  nfc: Nfc,
-  filter: Filter,
-  pencil: Pencil,
-  'pencil-line': PencilLine,
-  search: Search,
-  zap: Zap,
-  'zap-off': ZapOff,
-  timer: Timer,
-  fingerprint: Fingerprint,
-  'credit-card': CreditCard,
-  globe: Globe,
-  car: Car,
-  vote: Vote,
-  'file-text': FileText,
-  house: House,
-  landmark: Landmark,
-  'map-pin': MapPin,
-  'map-pin-house': MapPinHouse,
-  'map-pin-check': MapPinCheck,
-  'map-pinned': MapPinned,
-  radar: Radar,
-  'bell-ring': BellRing,
-  sliders: SlidersHorizontal,
-  locate: LocateFixed,
-  minus: Minus,
-  'id-card': IdCard,
-  contact: Contact,
-  passport: BookUser,
-  camera: Camera,
-  'camera-off': CameraOff,
-  'video-off': VideoOff,
-  upload: Upload,
-  x: X,
-  lightbulb: Lightbulb,
-  mail: Mail,
-  smartphone: Smartphone,
-  'message-square': MessageSquare,
-  'message-circle': MessageCircle,
-};

package/src/lib/biometric-auth.ts

@@ -1,52 +0,0 @@
-import { KYCApiError } from '../services/api';
-import { KYCError } from '../types/verification';
-import type { BiometricAuthResponse } from '../services/api-types-biometric';
-
-// ---------------------------------------------------------------------------
-// Biometric re-authentication — the pure half. Mirrors the web SDK's
-// MyazaBiometricAuth error mapping and outcome shapes (keep in lockstep).
-// ---------------------------------------------------------------------------
-
-export type BiometricAuthOutcome =
-  | { kind: 'success'; result: BiometricAuthResponse }
-  | { kind: 'failed'; result: BiometricAuthResponse }
-  | { kind: 'error'; message: string };
-
-export interface BiometricAuthenticated {
-  attemptId: string;
-  confidence: number | null;
-  /** Single-use proof; verify from your backend at `/biometric/verify-proof`. */
-  token?: string;
-}
-
-export interface BiometricAuthFailed {
-  status: BiometricAuthResponse['status'];
-  attemptId: string;
-  confidence: number | null;
-}
-
-/** A technical failure, in the SDK's typed vocabulary + a message a person
- *  can read. Never the server's own wording — that is an internal contract. */
-export function mapAuthError(err: unknown): KYCError {
-  if (err instanceof KYCApiError) {
-    if (err.statusCode === 404 && err.code === 'not_enrolled') {
-      return new KYCError('unknown', "You're not set up for face verification yet.");
-    }
-    if (err.statusCode === 402) {
-      return new KYCError('insufficient_credits', 'Face verification is temporarily unavailable.');
-    }
-    if (err.statusCode === 401 || err.statusCode === 403) {
-      return new KYCError('invalid_api_key', 'This app is not authorised for face verification.');
-    }
-  }
-  return new KYCError('network_error', 'Something went wrong. Please try again.');
-}
-
-/** The verdict as the callbacks and the result screen read it. */
-export function outcomeOf(result: BiometricAuthResponse): BiometricAuthOutcome {
-  return result.authenticated ? { kind: 'success', result } : { kind: 'failed', result };
-}
-
-export function defaultReauthLabel(companyName?: string): string {
-  return companyName ? `Verify it's you with ${companyName}` : "Verify it's you";
-}