@myazahq/kyc-sdk-react-native 2.0.1 → 2.1.0

package/src/MyazaKYC.tsx

@@ -1,4 +1,4 @@
-import React, { useCallback, useMemo, useRef, useState } from 'react';
+import React, { useCallback, useEffect, useMemo, useRef, useState } from 'react';
 import { Modal, Platform } from 'react-native';
 
 // iOS presents the flow as a swipe-down card sheet (the RN equivalent of
@@ -12,7 +12,10 @@ const MODAL_PRESENTATION = Platform.OS === 'ios' ? 'pageSheet' : 'fullScreen';
 const MODAL_ANIMATION = 'slide';
 
 import type { KYCStep, MyazaKYCConfig, SupportedCountry } from './types/config';
-import { KycRuntimeProvider, useKycStore } from './components/runtime';
+import { KycRuntimeProvider, MyazaThemeProvider } from './components/runtime';
+import { WorkflowGate } from './components/WorkflowGate';
+import { useWorkflowMount } from './components/useWorkflowMount';
+import { safeReportError } from './services/errors';
 import { KycFlow, type BackResult } from './components/KycFlow';
 import { MyazaButton } from './components/MyazaButton';
 
@@ -62,10 +65,13 @@ export function MyazaKYC<C extends SupportedCountry = SupportedCountry>(
   // The provider wraps BOTH the trigger and the modal so the built-in trigger
   // button can read the theme. The store is created once and `reset()` on each
   // open for a fresh run.
+  // The theme provider wraps the trigger so the built-in button is branded
+  // before anything is resolved; the flow's own provider (with the resolved
+  // workflow's appearance) is mounted inside the modal by the gate.
   return (
-    <KycRuntimeProvider config={config}>
+    <MyazaThemeProvider appearance={config.appearance}>
       <MyazaKYCTrigger config={config} label={children} disabled={disabled} />
-    </KycRuntimeProvider>
+    </MyazaThemeProvider>
   );
 }
 
@@ -78,23 +84,49 @@ function MyazaKYCTrigger({
   label?: string;
   disabled?: boolean;
 }): React.ReactElement {
-  const store = useKycStore();
-  const [open, setOpen] = useState(false);
+  const [wantOpen, setWantOpen] = useState(false);
   // Idempotent close — the X button, Android back, and iOS swipe-down dismiss can
   // each fire; `onClose` must run at most once per open.
   const closedRef = useRef(true);
   const backRef = useRef<(() => BackResult) | null>(null);
 
+  // Resolution happens HERE, outside the modal, and starts on mount rather than
+  // on press. The modal is only presented once it has settled, so its very
+  // first frame carries the workflow's own appearance instead of coming up in
+  // the default brand and recolouring underneath the user.
+  const { state, retry, refresh } = useWorkflowMount(config);
+  const settled = state.status !== 'resolving';
+  const open = wantOpen && settled;
+
+  // Reported only once the user has actually tried to start. Prefetching must
+  // not fire a consumer's error handler for a flow they never opened.
+  const reportedRef = useRef(false);
+  useEffect(() => {
+    if (!wantOpen || state.status !== 'error' || reportedRef.current) return;
+    reportedRef.current = true;
+    safeReportError(config.onError, state.error);
+  }, [wantOpen, state, config]);
+
+  const retryFlow = useCallback(() => {
+    reportedRef.current = false;
+    retry();
+  }, [retry]);
+
+  // Each open mounts a fresh gate → provider → store, so there is no state to
+  // reset; the previous run's store is discarded with its provider.
   const openFlow = useCallback(() => {
     closedRef.current = false;
-    store.getState().reset();
-    setOpen(true);
-  }, [store]);
+    // Re-resolve on every open: the mount-time prefetch is a warm-up, not a
+    // cache, so a workflow published since the app started is still picked up.
+    reportedRef.current = false;
+    refresh();
+    setWantOpen(true);
+  }, [refresh]);
 
   const close = useCallback(() => {
     if (closedRef.current) return;
     closedRef.current = true;
-    setOpen(false);
+    setWantOpen(false);
     config.onClose?.();
   }, [config]);
 
@@ -113,6 +145,10 @@ function MyazaKYCTrigger({
       <MyazaButton
         label={label ?? defaultTriggerLabel(config)}
         disabled={disabled}
+        // Pressed, but the workflow has not arrived yet. Without this the press
+        // would look ignored — gating the modal on a resolved config trades a
+        // wrong colour for a dead button unless the wait is shown.
+        loading={wantOpen && !settled}
         fullWidth={false}
         onPress={openFlow}
       />
@@ -125,7 +161,15 @@ function MyazaKYCTrigger({
         onRequestClose={onRequestClose}
         onDismiss={blockDismiss ? undefined : close}
       >
-        {open ? <KycFlow onClose={close} backRef={backRef} /> : null}
+        {open ? (
+          <WorkflowGate config={config} state={state} onRetry={retryFlow} onClose={close}>
+            {(mount) => (
+              <KycRuntimeProvider config={mount.config} serverConfig={mount.serverConfig}>
+                <KycFlow onClose={close} backRef={backRef} />
+              </KycRuntimeProvider>
+            )}
+          </WorkflowGate>
+        ) : null}
       </Modal>
     </>
   );
@@ -142,6 +186,15 @@ export interface UseMyazaKYCReturn {
   open: () => void;
   close: () => void;
   isOpen: boolean;
+  /**
+   * Opening was requested but the workflow has not resolved yet.
+   *
+   * Show a spinner on your trigger while this is true. The modal is deliberately
+   * withheld until the config has settled so it opens in the right brand rather
+   * than recolouring underneath the user — which means the press has to be
+   * acknowledged somewhere, or it looks ignored.
+   */
+  isPreparing: boolean;
   currentStep: KYCStep | null;
   /** Render this once in your component tree (RN has no implicit portal). */
   MyazaKYCModal: React.FC;
@@ -150,7 +203,7 @@ export interface UseMyazaKYCReturn {
 export function useMyazaKYC<C extends SupportedCountry = SupportedCountry>(
   config: MyazaKYCConfig<C>,
 ): UseMyazaKYCReturn {
-  const [isOpen, setIsOpen] = useState(false);
+  const [wantOpen, setWantOpen] = useState(false);
   const [currentStep, setCurrentStep] = useState<KYCStep | null>(null);
   const closedRef = useRef(true);
 
@@ -164,14 +217,23 @@ export function useMyazaKYC<C extends SupportedCountry = SupportedCountry>(
   configRef.current = config;
   const backRef = useRef<(() => BackResult) | null>(null);
 
+  // `refresh` is defined further down (it needs `wrappedConfig`), so it is
+  // reached through a ref rather than reordering the component around it.
+  const refreshRef = useRef<() => void>(() => undefined);
+  // Only reported once the consumer has actually tried to start — prefetching
+  // must not fire their error handler for a flow they never opened.
+  const reportedRef = useRef(false);
   const open = useCallback(() => {
     closedRef.current = false;
-    setIsOpen(true);
+    // Re-resolve on every open — see the trigger above.
+    reportedRef.current = false;
+    refreshRef.current();
+    setWantOpen(true);
   }, []);
   const close = useCallback(() => {
     if (closedRef.current) return;
     closedRef.current = true;
-    setIsOpen(false);
+    setWantOpen(false);
     setCurrentStep(null);
     configRef.current.onClose?.();
   }, []);
@@ -195,6 +257,24 @@ export function useMyazaKYC<C extends SupportedCountry = SupportedCountry>(
     [],
   );
 
+  // Resolution runs outside the modal and starts on mount, so the modal's first
+  // frame already carries the workflow's appearance.
+  const { state, retry, refresh } = useWorkflowMount(wrappedConfig);
+  refreshRef.current = refresh;
+  const settled = state.status !== 'resolving';
+  const presenting = wantOpen && settled;
+
+  useEffect(() => {
+    if (!wantOpen || state.status !== 'error' || reportedRef.current) return;
+    reportedRef.current = true;
+    safeReportError(configRef.current.onError, state.error);
+  }, [wantOpen, state]);
+
+  const retryFlow = useCallback(() => {
+    reportedRef.current = false;
+    retry();
+  }, [retry]);
+
   // disableClose blocks user-initiated dismissal — only the returned close()
   // can dismiss. Present full-screen (no iOS swipe-down). The Android hardware
   // back goes through onRequestClose, which walks the flow back a step (or
@@ -212,7 +292,7 @@ export function useMyazaKYC<C extends SupportedCountry = SupportedCountry>(
   const MyazaKYCModal = useCallback<React.FC>(
     () => (
       <Modal
-        visible={isOpen}
+        visible={presenting}
         animationType={MODAL_ANIMATION}
         presentationStyle={blockDismiss ? 'fullScreen' : MODAL_PRESENTATION}
         statusBarTranslucent
@@ -220,16 +300,29 @@ export function useMyazaKYC<C extends SupportedCountry = SupportedCountry>(
         onRequestClose={onRequestClose}
         onDismiss={blockDismiss ? undefined : close}
       >
-        {/* Fresh provider/store per open. */}
-        {isOpen ? (
-          <KycRuntimeProvider config={wrappedConfig}>
-            <KycFlow onClose={close} backRef={backRef} />
-          </KycRuntimeProvider>
+        {/* Fresh gate/provider/store per open. */}
+        {presenting ? (
+          <WorkflowGate config={wrappedConfig} state={state} onRetry={retryFlow} onClose={close}>
+            {(mount) => (
+              <KycRuntimeProvider config={mount.config} serverConfig={mount.serverConfig}>
+                <KycFlow onClose={close} backRef={backRef} />
+              </KycRuntimeProvider>
+            )}
+          </WorkflowGate>
         ) : null}
       </Modal>
     ),
-    [wrappedConfig, isOpen, close, blockDismiss, onRequestClose],
+    [wrappedConfig, presenting, state, retryFlow, close, blockDismiss, onRequestClose],
   );
 
-  return { open, close, isOpen, currentStep, MyazaKYCModal };
+  // `isOpen` stays the consumer's intent, not the presentation state — a
+  // trigger disabled on it must stay disabled through the preparing window.
+  return {
+    open,
+    close,
+    isOpen: wantOpen,
+    isPreparing: wantOpen && !settled,
+    currentStep,
+    MyazaKYCModal,
+  };
 }

package/src/capture/documentIdentity.ts

@@ -0,0 +1,153 @@
+import { detectDocumentType, hasDocumentSignals, hasMrzLines } from './documentSignals';
+
+// ---------------------------------------------------------------------------
+// Document identity.
+//
+// "Is the thing in frame the document the user picked?" — answered from
+// recognized text, so a capture clears the same bar on both platforms.
+//
+// Text ALONE cannot answer it either: the word "passport" appears in prose, in
+// code, and on any screen showing KYC documentation — which is exactly how a
+// laptop screen full of text once identified as a passport and fired.
+//
+// So identity is deliberately strict about the one document that can prove
+// itself: an MRZ. Only travel documents carry one, it is always on the page a
+// passport capture is meant to frame, and it validates by check digit — so for
+// passports the machine-readable zone, not the printed word, is the proof.
+// ---------------------------------------------------------------------------
+
+/**
+ * What to actually tell the user. The gate rejects for several distinct
+ * reasons, and collapsing them into one "align your ID" message left people
+ * stuck: the commonest failure is holding the document TOO CLOSE, where the
+ * instinct is to move nearer still.
+ */
+export type DocumentHint =
+  | 'searching'
+  | 'moreLight'
+  | 'wrongDocument'
+  | 'moveCloser'
+  /** Overflowing — corners are cut. THIS is the one users cannot guess. */
+  | 'moveBack'
+  | 'centre'
+  /**
+   * Passport only: the page is readable but the machine-readable strip is not
+   * in frame. Auto-capture waits for it (it is the chip's key and the proof the
+   * page is a passport), so a generic "move closer" sends the user the wrong way.
+   */
+  | 'showMrz'
+  | 'holdStill'
+  | 'captured';
+
+export type DocumentFraming =
+  | 'none'
+  | 'wrongShape'
+  | 'adjust'
+  | 'holding'
+  | 'ready';
+
+export interface DocumentGuidance {
+  framing: DocumentFraming;
+  hint: DocumentHint;
+}
+
+export interface DocumentIdentityResult {
+  identified: boolean;
+  /** Meaningful only when `identified` is false. */
+  hint: DocumentHint;
+}
+
+/** ID types whose page always carries a machine-readable zone. */
+export function documentCarriesMrz(idType: string): boolean {
+  return idType === 'passport';
+}
+
+export interface VerifyIdentityOptions {
+  country: string;
+  idType: string;
+  /**
+   * Which face of the document is being photographed. Identity KEYWORDS live
+   * on the FRONT — the branding, the document name, the issuer. The back of a
+   * card (a PVC's barcode-and-address side, a licence's magstripe side)
+   * carries none of them, so demanding them there means the back can never
+   * auto-capture. By the time the back is up, the user has captured and
+   * confirmed the front of the right document seconds ago — identity is
+   * established; the back only has to be framed, text-bearing and still.
+   */
+  side?: 'front' | 'back';
+  /** The chip step needs the MRZ as a key, so demand a check-digit-valid read. */
+  requireValidMrz?: boolean;
+  hasValidMrz?: boolean;
+  /** The key is already stored from an earlier frame. */
+  mrzAlreadyCaptured?: boolean;
+  minConfidence?: number;
+  wrongTypeMargin?: number;
+}
+
+/** Verifies that `lines` identify the document the user picked. */
+export function verifyDocumentIdentity(
+  lines: string[],
+  {
+    country,
+    idType,
+    side = 'front',
+    requireValidMrz = false,
+    hasValidMrz = false,
+    mrzAlreadyCaptured = false,
+    minConfidence = 0.34,
+    wrongTypeMargin = 0.34,
+  }: VerifyIdentityOptions,
+): DocumentIdentityResult {
+  if (lines.length === 0) return { identified: false, hint: 'searching' };
+  const isBack = side === 'back';
+
+  // ── The MRZ rule ────────────────────────────────────────────────────────
+  // For an MRZ-bearing document the zone must actually be in frame. This is
+  // what rejects a screen, a printout, or a page that merely mentions the word.
+  // Front only: the strip lives on the photo page.
+  if (!isBack && documentCarriesMrz(idType) && !hasValidMrz && !hasMrzLines(lines)) {
+    // Say WHICH problem it is. Text that already reads as the expected document
+    // is most likely the real thing with the strip cropped off the bottom edge
+    // — the commonest passport framing mistake — and telling that user "wrong
+    // document" sends them hunting for a different one.
+    const looksRight = detectDocumentType(lines, country).type === idType;
+    return { identified: false, hint: looksRight ? 'showMrz' : 'wrongDocument' };
+  }
+
+  // ── Keyword identity ────────────────────────────────────────────────────
+  // Only where signals exist: most Global Documents countries have no curated
+  // list, and there we must not block on a check we cannot perform.
+  if (hasDocumentSignals(country, idType)) {
+    const match = detectDocumentType(lines, country);
+    const expected = match.type === idType ? match.confidence : 0;
+
+    // Reading clearly as a DIFFERENT document — the server would reject this
+    // after upload as `document_type_mismatch`, so say so now. This arm runs
+    // for the back too: its keywords are absent from card backs, so a hit
+    // means a different document's FRONT swapped into the frame.
+    if (match.type != null && match.type !== idType && match.confidence >= expected + wrongTypeMargin) {
+      return { identified: false, hint: 'wrongDocument' };
+    }
+
+    // Two independent keyword hits identify the document, whatever the length
+    // of its synonym list. Confidence alone is a ratio, so a type with a
+    // thorough list is HARDER to recognise than a sparse one. REQUIRED on the
+    // front only — the back carries no branding to match.
+    const identifiedByCount = match.type === idType && match.matched >= 2;
+    if (!isBack && !identifiedByCount && expected < minConfidence) {
+      return { identified: false, hint: lines.length < 5 ? 'searching' : 'moveCloser' };
+    }
+  }
+
+  // ── Chip key ────────────────────────────────────────────────────────────
+  // Firing before the MRZ validates means the chip step has to scan the same
+  // document a second time, which is the whole reason this gate exists.
+  // Front only: the strip cannot appear on the back.
+  if (!isBack && requireValidMrz && !hasValidMrz && !mrzAlreadyCaptured) {
+    // The document is identified; only the strip is missing. "Move closer"
+    // would push the user to crop it off entirely.
+    return { identified: false, hint: 'showMrz' };
+  }
+
+  return { identified: true, hint: 'holdStill' };
+}

package/src/capture/documentSignals.ts

@@ -0,0 +1,177 @@
+// ---------------------------------------------------------------------------
+// Document identity signals.
+//
+// "Is the thing in frame actually the document the user picked?" — answered
+// from recognized text alone.
+//
+// Geometry cannot answer it: an aspect ratio cannot tell a passport from a
+// driver's licence. Text can, and more specifically — a passport page says
+// PASSPORT and carries an MRZ; a Nigerian licence says FRSC.
+//
+// Deliberately mirrors the SERVER's DOCUMENT_SIGNALS / detectDocumentType
+// (kyc-core src/lib/ocr-parser.ts). The server rejects a mismatched document
+// AFTER upload with `document_type_mismatch`, so matching its vocabulary here
+// means the camera refuses to shoot exactly what the server would later throw
+// away. Keep the lists in sync when either changes — and with the Flutter SDK's
+// document_type_signals.dart, which is the direct counterpart.
+// ---------------------------------------------------------------------------
+
+/** Keyword signals per country → ID type. Uppercase; matched as substrings. */
+export const DOCUMENT_SIGNALS: Record<string, Record<string, string[]>> = {
+  NG: {
+    passport: ['PASSPORT', 'TRAVEL DOCUMENT', 'P<NGA'],
+    'drivers-license': [
+      'DRIVER', 'LICENSE', 'FRSC', 'FEDERAL ROAD SAFETY', 'DRIVING LICENCE',
+    ],
+    pvc: [
+      'VOTER', "VOTER'S CARD", 'PVC', 'INEC', 'INDEPENDENT NATIONAL ELECTORAL',
+      'PERMANENT VOTER', 'ELECTORAL COMMISSION', 'VIN',
+    ],
+  },
+  GH: {
+    passport: ['PASSPORT', 'REPUBLIC OF GHANA', 'P<GHA'],
+    'ghana-card': ['GHANA CARD', 'NATIONAL IDENTIFICATION AUTHORITY', 'NIA', 'GHA-'],
+    voters: ['VOTER', 'ELECTORAL COMMISSION', 'EC OF GHANA'],
+    'drivers-license': ['DRIVER', 'LICENSE', 'DVLA', 'DRIVING AND VEHICLE'],
+    ssnit: ['SSNIT', 'SOCIAL SECURITY', 'NATIONAL INSURANCE'],
+  },
+  KE: {
+    passport: ['PASSPORT', 'REPUBLIC OF KENYA', 'P<KEN'],
+    'national-id': [
+      'REPUBLIC OF KENYA', 'NATIONAL ID', 'JAMHURI YA KENYA', 'IDENTITY CARD',
+    ],
+  },
+  ZA: {
+    passport: ['PASSPORT', 'P<ZAF'],
+    'national-id': [
+      'REPUBLIC OF SOUTH AFRICA', 'IDENTITY', 'ID NUMBER', 'REPUBLIEK VAN SUID-AFRIKA',
+    ],
+  },
+  CI: {
+    cni: ['CARTE NATIONALE', 'IDENTITE', 'REPUBLIQUE DE COTE', 'CNI'],
+    'residence-card': ['CARTE DE SEJOUR', 'RESIDENCE', 'TITRE DE SEJOUR'],
+  },
+};
+
+/**
+ * Words that identify a passport in ANY country — an MRZ, or the word itself in
+ * English or French. Global Documents means most countries have no curated
+ * list, and a passport is the one document that identifies itself everywhere.
+ */
+const UNIVERSAL_PASSPORT_WORDS = ['PASSPORT', 'PASSEPORT'];
+
+/**
+ * True when `lines` contain two or more machine-readable-zone lines. A cheap
+ * STRUCTURAL check — no check-digit validation, which `extractMrz` does.
+ */
+export function hasMrzLines(lines: string[]): boolean {
+  let count = 0;
+  for (const line of lines) {
+    const stripped = line.toUpperCase().replace(/[^A-Z0-9<]/g, '');
+    if (stripped.length >= 40 && stripped.includes('<')) count += 1;
+  }
+  return count >= 2;
+}
+
+export interface DocumentTypeMatch {
+  /** The ID type the text matches best, or null when nothing matched. */
+  type: string | null;
+  /**
+   * 0..1 share of that type's keywords present.
+   *
+   * A RATIO, so it shrinks as a type's synonym list grows — which is why it
+   * cannot be the only bar for "is this the right document". See `matched`.
+   */
+  confidence: number;
+  /**
+   * How many keywords actually hit.
+   *
+   * The evidence that matters when deciding the document IS the expected one:
+   * two independent hits mean the same thing whether the type lists three
+   * synonyms or eight, where `confidence` would call the same evidence 0.67 or
+   * 0.25. Kept alongside rather than replacing it — the wrong-type comparison
+   * still wants a ratio, so two types are weighed on one scale.
+   */
+  matched: number;
+}
+
+const NO_MATCH: DocumentTypeMatch = { type: null, confidence: 0, matched: 0 };
+
+/**
+ * True when we have signals to verify this (country, idType) at all. When
+ * false the caller CANNOT check identity and must not block on it — most
+ * Global Documents countries have no curated list.
+ */
+export function hasDocumentSignals(country: string, idType: string): boolean {
+  if (DOCUMENT_SIGNALS[country]?.[idType]) return true;
+  // A passport identifies itself in any country.
+  return idType === 'passport';
+}
+
+function isShortAcronym(keyword: string): boolean {
+  return keyword.length <= 4 && /^[A-Z]+$/.test(keyword);
+}
+
+/**
+ * How many of `keywords` appear in `upper`.
+ *
+ * Short acronyms match on WORD BOUNDARIES, not as bare substrings. `VIN` sits
+ * inside "driVINg", so a Nigerian driver's licence would otherwise score a
+ * voter-card hit — harmless while every score is diluted by the keyword count,
+ * and a false identification the moment anything counts hits directly.
+ */
+export function countSignalHits(upper: string, keywords: string[]): number {
+  let hits = 0;
+  for (const keyword of keywords) {
+    if (isShortAcronym(keyword)) {
+      if (new RegExp(`\\b${keyword.replace(/[.*+?^${}()|[\]\\]/g, '\\$&')}\\b`).test(upper)) {
+        hits += 1;
+      }
+    } else if (upper.includes(keyword)) {
+      hits += 1;
+    }
+  }
+  return hits;
+}
+
+/** Best-matching document type for the recognized `lines` within `country`. */
+export function detectDocumentType(lines: string[], country: string): DocumentTypeMatch {
+  if (lines.length === 0) return NO_MATCH;
+  const upper = lines.join('\n').toUpperCase();
+  const signals = DOCUMENT_SIGNALS[country] ?? {};
+
+  let bestType: string | null = null;
+  let bestConfidence = 0;
+  let bestMatched = 0;
+
+  for (const [type, keywords] of Object.entries(signals)) {
+    if (keywords.length === 0) continue;
+    const matched = countSignalHits(upper, keywords);
+    const confidence = matched / keywords.length;
+    if (confidence > bestConfidence) {
+      bestConfidence = confidence;
+      bestMatched = matched;
+      bestType = type;
+    }
+  }
+
+  // Universal passport fallback — an MRZ is worth a lot on its own, since only
+  // travel documents carry one.
+  const mrz = hasMrzLines(lines);
+  const saysPassport = UNIVERSAL_PASSPORT_WORDS.some((w) => upper.includes(w));
+  if (mrz || saysPassport) {
+    const keywords = signals.passport ?? [];
+    const matched = countSignalHits(upper, keywords);
+    const base = keywords.length === 0 ? 0 : matched / keywords.length;
+    const confidence = Math.min(1, Math.max(0, base + (mrz ? 0.5 : 0.25)));
+    if (confidence > bestConfidence) {
+      bestConfidence = confidence;
+      bestMatched = matched + 1; // the MRZ / the word itself is evidence too
+      bestType = 'passport';
+    }
+  }
+
+  return bestType == null
+    ? NO_MATCH
+    : { type: bestType, confidence: bestConfidence, matched: bestMatched };
+}