@myazahq/kyc-sdk-react-native 2.0.0

package/src/specs/MyazaFaceDetector.nitro.ts

@@ -0,0 +1,44 @@
+import type { HybridObject } from 'react-native-nitro-modules';
+import type { Frame } from 'react-native-vision-camera';
+
+// ---------------------------------------------------------------------------
+// Nitro spec for the on-device face detector (VisionCamera v5).
+//
+// v5 replaced the old `FrameProcessorPlugin` + `VISION_EXPORT_SWIFT_FRAME_PROCESSOR`
+// macro / `FrameProcessorPluginRegistry` model with **Nitro HybridObjects**. This
+// `.nitro.ts` spec is the single source of truth: nitrogen generates the Swift
+// (`HybridMyazaFaceDetectorSpec`) and Kotlin (`HybridMyazaFaceDetectorSpec`) base
+// classes from it, and `nitro.json` autolinks the concrete impls
+// (`HybridMyazaFaceDetector`) — iOS = Apple Vision, Android = Google ML Kit.
+//
+// The detector runs inside the camera-thread worklet (`useFrameOutput`): the
+// boxed HybridObject is unboxed in the worklet and `detectFace(frame)` is called
+// synchronously per frame (the frame never crosses the JS bridge).
+// ---------------------------------------------------------------------------
+
+/**
+ * Per-frame face signals, identical in shape to {@link LivenessFaceData} in
+ * `../liveness/types`. `faceCount === 0` means "no face" (the worklet maps that
+ * to `onNoFace()` — Nitro return types are non-nullable, so we use the count as
+ * the presence signal rather than returning `null`).
+ */
+export interface FaceResult {
+  headEulerAngleX: number; // pitch (nod), degrees; negative = down
+  headEulerAngleY: number; // yaw (turn), degrees; positive = left
+  headEulerAngleZ: number; // roll, degrees
+  smilingProbability: number; // 0–1
+  leftEyeOpenProbability: number; // 0–1
+  rightEyeOpenProbability: number; // 0–1
+  faceSizeRatio: number; // face width / frame width (0–1)
+  faceCount: number; // # faces in frame; 0 = no face
+  brightness: number; // mean luma of the frame (0–255), for the low-light gate
+}
+
+export interface MyazaFaceDetector extends HybridObject<{ ios: 'swift'; android: 'kotlin' }> {
+  /**
+   * Detect the dominant face in a camera {@link Frame} and return its gesture
+   * signals. Called per-frame from the VisionCamera worklet. Returns
+   * `faceCount: 0` when no face is present.
+   */
+  detectFace(frame: Frame): FaceResult;
+}

package/src/store/kycStore.ts

@@ -0,0 +1,288 @@
+// ---------------------------------------------------------------------------
+// kycStore — the main flow/state store (mirrors Flutter's KYCNotifier + KYCState).
+//
+// One store is created per modal instance via `createKycStore(config)` so the
+// flow state (and the resolved API client) is scoped to a single launch. The
+// React layer (Step 2) exposes it through context + a `useStore` selector hook.
+// ---------------------------------------------------------------------------
+
+import { createStore, type StoreApi } from 'zustand/vanilla';
+
+import { createKYCApi, type KYCApi, type VerifyRequest } from '../services/api';
+import { resolveBaseUrl, normalizeDevAssetUrl } from '../services/resolveUrl';
+import { withRetry } from '../services/retry';
+import { collectDeviceMetadata } from '../services/deviceMetadata';
+import { requiresDocumentCapture } from '../config/idTypes';
+import { generateRequestId } from '../utils/uuid';
+import type { IdType, KYCStep, MyazaKYCConfig } from '../types/config';
+import {
+  INITIAL_SERVER_CONFIG,
+  describeConfigError,
+  featuresFor,
+  type ServerConfigState,
+} from './serverConfig';
+
+export interface KYCMediaIds {
+  documentFront?: string;
+  documentBack?: string;
+  selfie?: string;
+  documentFrontVideo?: string;
+  documentBackVideo?: string;
+  livenessVideo?: string;
+}
+
+export interface KYCSubmissionResult {
+  verificationId: string;
+  status: 'pending';
+}
+
+export type DocumentScanPhase = 'front' | 'back' | 'complete';
+
+/** Document-capture sub-phase — drives the sheet header title/description. */
+export type DocumentCapturePhase = 'front' | 'front-preview' | 'back' | 'review';
+
+/** The mediaIds keys settable via `setMediaId`. */
+export type MediaIdKey = keyof KYCMediaIds;
+
+export interface KycState {
+  config: MyazaKYCConfig;
+  api: KYCApi;
+
+  currentStep: KYCStep;
+  selectedIdType: IdType | null;
+  idNumber: string | null;
+  mediaIds: KYCMediaIds;
+  submissionResult: KYCSubmissionResult | null;
+  serverConfig: ServerConfigState;
+  documentScanPhase: DocumentScanPhase;
+  /** Sub-phase of the document-capture step — synced by the screen so the header
+   *  title/description can be phase-aware (mirrors Flutter's docReviewPhase). */
+  documentCapturePhase: DocumentCapturePhase;
+  isLoading: boolean;
+  error: string | null;
+
+  // Actions
+  loadServerConfig: () => Promise<void>;
+  setIdType: (idType: IdType) => void;
+  setIdNumber: (idNumber: string) => void;
+  setMediaId: (key: MediaIdKey, mediaId: string) => void;
+  setDocumentMediaId: (mediaId: string, side: 'front' | 'back') => void;
+  setDocumentCapturePhase: (phase: DocumentCapturePhase) => void;
+  nextStep: () => void;
+  previousStep: () => void;
+  goToStep: (step: KYCStep) => void;
+  submitAsync: (onRetry?: (attempt: number, total: number) => void) => Promise<KYCSubmissionResult>;
+  reset: () => void;
+}
+
+export type KycStore = StoreApi<KycState>;
+
+// ---------------------------------------------------------------------------
+// Flow navigation — single source of truth for the 5-step sequence.
+// ---------------------------------------------------------------------------
+
+function livenessEnabled(state: KycState): boolean {
+  // Consumer baseline: liveness is on unless explicitly disabled.
+  if (state.config.enableLiveness === false) return false;
+  const idType = state.selectedIdType;
+  if (!idType) return true;
+  // Server flag wins when present; otherwise keep the consumer baseline (on).
+  const features = featuresFor(state.serverConfig, state.config.country, idType);
+  return features ? features.livenessCheck : true;
+}
+
+/** The step that follows `step`, given the current selection + flags. */
+function nextStepAfter(step: KYCStep, state: KycState): KYCStep {
+  switch (step) {
+    case 'consent':
+      return 'id-type';
+    case 'id-type':
+      return state.selectedIdType && requiresDocumentCapture(state.selectedIdType)
+        ? 'document-capture'
+        : 'id-input';
+    case 'document-capture':
+    case 'id-input':
+      return livenessEnabled(state) ? 'liveness' : 'submitted';
+    case 'liveness':
+      return 'submitted';
+    case 'submitted':
+      return 'submitted';
+    default:
+      return step;
+  }
+}
+
+/** The step before `step` (for the back button). */
+function previousStepBefore(step: KYCStep, state: KycState): KYCStep {
+  switch (step) {
+    case 'id-type':
+      return 'consent';
+    case 'document-capture':
+    case 'id-input':
+      return 'id-type';
+    case 'liveness':
+      return state.selectedIdType && requiresDocumentCapture(state.selectedIdType)
+        ? 'document-capture'
+        : 'id-input';
+    case 'submitted':
+      // Submitted is terminal; back is a no-op in practice.
+      return livenessEnabled(state) ? 'liveness' : step;
+    case 'consent':
+    default:
+      return 'consent';
+  }
+}
+
+// ---------------------------------------------------------------------------
+// Store factory
+// ---------------------------------------------------------------------------
+
+export function createKycStore(config: MyazaKYCConfig): KycStore {
+  const baseUrl = resolveBaseUrl(config.apiKey, config.devUrl);
+  const api = createKYCApi(baseUrl, config.apiKey);
+
+  return createStore<KycState>((set, get) => {
+    function emitStepChange(step: KYCStep): void {
+      config.onStepChange?.(step);
+    }
+
+    return {
+      config,
+      api,
+
+      currentStep: 'consent',
+      selectedIdType: null,
+      idNumber: null,
+      mediaIds: {},
+      submissionResult: null,
+      serverConfig: INITIAL_SERVER_CONFIG,
+      documentScanPhase: 'front',
+      documentCapturePhase: 'front',
+      isLoading: false,
+      error: null,
+
+      async loadServerConfig() {
+        set((s) => ({ serverConfig: { ...s.serverConfig, status: 'loading' } }));
+        try {
+          const res = await api.config();
+          // Make a local dev server's hardcoded `localhost` logo URL reachable on
+          // the Android emulator (rewrites the origin to the SDK base; no-op for
+          // production CDN URLs).
+          const branding = res.branding
+            ? { ...res.branding, logo: normalizeDevAssetUrl(res.branding.logo, baseUrl) }
+            : res.branding;
+          set({
+            serverConfig: {
+              status: 'ready',
+              idTypes: res.idTypes,
+              branding,
+              environment: res.environment,
+              fatal: false,
+            },
+          });
+        } catch (err) {
+          const described = describeConfigError(err);
+          set((s) => ({
+            serverConfig: { ...s.serverConfig, status: 'error', ...described },
+          }));
+        }
+      },
+
+      setIdType(idType) {
+        set({ selectedIdType: idType });
+      },
+
+      setIdNumber(idNumber) {
+        set({ idNumber });
+      },
+
+      setMediaId(key, mediaId) {
+        set((s) => ({ mediaIds: { ...s.mediaIds, [key]: mediaId } }));
+      },
+
+      setDocumentMediaId(mediaId, side) {
+        set((s) => ({
+          mediaIds: {
+            ...s.mediaIds,
+            [side === 'front' ? 'documentFront' : 'documentBack']: mediaId,
+          },
+          documentScanPhase: side === 'front' ? 'back' : 'complete',
+        }));
+      },
+
+      setDocumentCapturePhase(phase) {
+        if (get().documentCapturePhase !== phase) set({ documentCapturePhase: phase });
+      },
+
+      nextStep() {
+        const next = nextStepAfter(get().currentStep, get());
+        if (next !== get().currentStep) {
+          set({ currentStep: next });
+          emitStepChange(next);
+        }
+      },
+
+      previousStep() {
+        const prev = previousStepBefore(get().currentStep, get());
+        if (prev !== get().currentStep) {
+          set({ currentStep: prev });
+          emitStepChange(prev);
+        }
+      },
+
+      goToStep(step) {
+        if (step !== get().currentStep) {
+          set({ currentStep: step });
+          emitStepChange(step);
+        }
+      },
+
+      async submitAsync(onRetry) {
+        set({ isLoading: true, error: null });
+        const state = get();
+        const request: VerifyRequest = {
+          country: state.config.country,
+          idType: state.selectedIdType ?? '',
+          idNumber: state.idNumber ?? undefined,
+          userData: state.config.userData,
+          mediaIds: state.mediaIds,
+          metadata: {
+            requestId: generateRequestId(),
+            device: collectDeviceMetadata() as unknown as Record<string, unknown>,
+            ...(state.config.metadata ?? {}),
+          },
+        };
+        try {
+          const res = await withRetry(() => api.verify(request), { onRetry });
+          const result: KYCSubmissionResult = {
+            verificationId: res.verificationId,
+            status: 'pending',
+          };
+          set({ submissionResult: result, isLoading: false });
+          return result;
+        } catch (err) {
+          set({ isLoading: false, error: err instanceof Error ? err.message : 'Submission failed' });
+          throw err;
+        }
+      },
+
+      reset() {
+        set({
+          currentStep: 'consent',
+          selectedIdType: null,
+          idNumber: null,
+          mediaIds: {},
+          submissionResult: null,
+          documentScanPhase: 'front',
+          documentCapturePhase: 'front',
+          isLoading: false,
+          error: null,
+        });
+      },
+    };
+  });
+}
+
+// Re-export the flow helpers for tests + screens that need to reason about
+// navigation without mutating the store.
+export { livenessEnabled, nextStepAfter, previousStepBefore };

package/src/store/serverConfig.ts

@@ -0,0 +1,78 @@
+// ---------------------------------------------------------------------------
+// Server-driven config state (GET /api/kyc/config) — mirrors the Flutter SDK's
+// serverConfig handling on KYCState. Holds the org's allowed (country, idType)
+// list, per-ID feature flags, branding, and an error classification.
+// ---------------------------------------------------------------------------
+
+import { KYCApiError } from '../services/api';
+import type { SdkConfigBranding, SdkConfigIdType } from '../services/api';
+
+export type ServerConfigStatus = 'loading' | 'ready' | 'error';
+
+export interface IdTypeFeatures {
+  documentVerification: boolean;
+  livenessCheck: boolean;
+  govDbCheck: boolean;
+}
+
+export interface ServerConfigState {
+  status: ServerConfigStatus;
+  idTypes: SdkConfigIdType[];
+  branding?: SdkConfigBranding;
+  environment?: 'DEVELOPMENT' | 'SANDBOX' | 'PRODUCTION';
+  /** HTTP status of a failed config fetch (if any). */
+  statusCode?: number;
+  /** A fatal failure (401/403) blocks the flow; non-fatal falls back to the prop list. */
+  fatal: boolean;
+  /** User-facing message for a fatal failure. */
+  message?: string;
+}
+
+export const INITIAL_SERVER_CONFIG: ServerConfigState = {
+  status: 'loading',
+  idTypes: [],
+  fatal: false,
+};
+
+/**
+ * Returns the per-ID feature flags for a `(country, idType)` pair, or `null`
+ * when the ID isn't granted or config hasn't loaded. Mirrors Flutter's
+ * `featuresFor` — callers must NOT replicate precedence logic elsewhere.
+ */
+export function featuresFor(
+  config: ServerConfigState,
+  country: string,
+  idType: string,
+): IdTypeFeatures | null {
+  if (config.status !== 'ready') return null;
+  const match = config.idTypes.find((t) => t.country === country && t.idType === idType);
+  return match ? match.features : null;
+}
+
+/**
+ * Classifies a config-fetch error. 401 (invalid key) and 403 (not permitted) are
+ * FATAL — they block the flow and report to onError once. Everything else
+ * (network blips, 5xx) is non-fatal — the SDK trusts the consumer's `idTypes`
+ * prop and the server still 403s anything actually disabled. Mirrors Flutter's
+ * `_describeConfigError`.
+ */
+export function describeConfigError(err: unknown): Pick<ServerConfigState, 'statusCode' | 'fatal' | 'message'> {
+  if (err instanceof KYCApiError) {
+    if (err.statusCode === 401) {
+      return {
+        statusCode: 401,
+        fatal: true,
+        message: 'Invalid API key. Please contact support.',
+      };
+    }
+    if (err.statusCode === 403) {
+      return {
+        statusCode: 403,
+        fatal: true,
+        message: "Your organization isn't permitted to start verification. Contact your administrator.",
+      };
+    }
+    return { statusCode: err.statusCode, fatal: false };
+  }
+  return { fatal: false };
+}

package/src/types/config.ts

@@ -0,0 +1,239 @@
+import type { KYCSubmission, KYCError } from './verification';
+
+// ---------------------------------------------------------------------------
+// Supported countries & ID types  (identical set to the web + Flutter SDKs)
+// ---------------------------------------------------------------------------
+
+export type SupportedCountry = 'NG' | 'GH' | 'KE' | 'ZA' | 'CI';
+
+export type NigeriaIdType = 'bvn' | 'nin' | 'vnin' | 'passport' | 'drivers-license' | 'pvc';
+export type GhanaIdType = 'ghana-card' | 'voters' | 'drivers-license' | 'ssnit' | 'passport';
+export type KenyaIdType = 'national-id' | 'passport';
+export type SouthAfricaIdType = 'national-id';
+export type IvoryCoastIdType = 'cni' | 'residence-card';
+
+export type IdType =
+  | NigeriaIdType
+  | GhanaIdType
+  | KenyaIdType
+  | SouthAfricaIdType
+  | IvoryCoastIdType;
+
+/** Maps a country code to the ID types available in that country. */
+export type IdTypeForCountry<C extends SupportedCountry> =
+  C extends 'NG' ? NigeriaIdType :
+  C extends 'GH' ? GhanaIdType :
+  C extends 'KE' ? KenyaIdType :
+  C extends 'ZA' ? SouthAfricaIdType :
+  C extends 'CI' ? IvoryCoastIdType :
+  never;
+
+export interface IdTypeDefinition {
+  key: IdType;
+  label: string;
+  digits?: number;
+  pattern?: RegExp;
+  /** Whether this ID type requires photographing/uploading a physical document. */
+  requiresDocumentCapture: boolean;
+  /**
+   * How many sides of the document need to be scanned. Only present when
+   * `requiresDocumentCapture` is true.
+   * - `front_only` — single scan (passports, data-page only)
+   * - `front_and_back` — both sides required
+   */
+  scanSides?: 'front_only' | 'front_and_back';
+}
+
+export type IdTypesByCountry = {
+  [K in SupportedCountry]: readonly IdTypeDefinition[];
+};
+
+// ---------------------------------------------------------------------------
+// KYC flow steps
+// ---------------------------------------------------------------------------
+
+export type KYCStep =
+  | 'consent'
+  | 'id-type'
+  | 'id-input'
+  | 'document-capture'
+  | 'liveness'
+  | 'submitted';
+
+// ---------------------------------------------------------------------------
+// Appearance / theming
+// ---------------------------------------------------------------------------
+
+export interface KYCAppearance {
+  /** Brand color — drives buttons, selected states, focus rings. */
+  primaryColor?: string;
+  /** Text/icon color rendered on top of `primaryColor` (e.g. button labels). */
+  primaryTextColor?: string;
+  /** Accent color for subtle hover/active surfaces. */
+  accentColor?: string;
+  /** Modal/sheet background color. */
+  backgroundColor?: string;
+  /** Elevated surface color for cards/panels. */
+  surfaceColor?: string;
+  /** Border + input outline color. */
+  borderColor?: string;
+  /** Primary text color. */
+  textColor?: string;
+  companyName?: string;
+  /**
+   * Logo to show in the flow.
+   * - An image URL renders that logo.
+   * - The literal `'default'` renders the org's own logo from the server config
+   *   response (falls back to the built-in shield if the org has none set).
+   * - Omitted renders the built-in shield badge.
+   */
+  logo?: string;
+  /** Initial light/dark mode. Applied on mount; the theme toggle can flip it. */
+  theme?: 'light' | 'dark';
+}
+
+// ---------------------------------------------------------------------------
+// Consent / success screen content
+// ---------------------------------------------------------------------------
+
+export interface KYCConsentContent {
+  /** Consent heading. Supports `{firstName}` / `{lastName}` tokens. */
+  title?: string;
+  /** Sub-text under the heading. Same tokens. */
+  description?: string;
+}
+
+export interface KYCSuccessContent {
+  /** Success heading. Supports `{firstName}` / `{lastName}` tokens. */
+  title?: string;
+  /** Sub-text under the heading. Same tokens. */
+  description?: string;
+}
+
+// ---------------------------------------------------------------------------
+// Voice guidance (spoken liveness instructions — TTS output only, no mic)
+// ---------------------------------------------------------------------------
+
+/**
+ * Configuration for the spoken liveness instructions. TTS **output** for
+ * accessibility — it never records audio, so no microphone permission is
+ * involved. An object (not a bare boolean) so a `language` can be added later
+ * without a breaking change.
+ */
+export interface VoiceGuidanceConfig {
+  /** Whether spoken guidance plays. Default `true`. */
+  enabled?: boolean;
+  /** BCP-47 voice tag (e.g. `'en-US'`, `'fr-FR'`). Default `'en-US'`. */
+  language?: string;
+}
+
+/** Accepts a bare boolean for ergonomics or the full {@link VoiceGuidanceConfig}. */
+export type VoiceGuidanceOption = boolean | VoiceGuidanceConfig;
+
+// ---------------------------------------------------------------------------
+// Client-side SDK config  (MyazaKYC.show() / useMyazaKYC options)
+// ---------------------------------------------------------------------------
+
+export interface MyazaKYCConfig<C extends SupportedCountry = SupportedCountry> {
+  /**
+   * Bearer token. The key prefix is the single source of truth for the
+   * environment — the SDK derives it (and the base URL) automatically:
+   * `pk_dev_…` → development, `pk_test_…` → sandbox, `pk_live_…` → production.
+   * An unrecognized prefix throws.
+   */
+  apiKey: string;
+
+  /**
+   * Dev-only base-URL override. Only applied for **development** keys
+   * (`pk_dev_…`); defaults to a platform-aware localhost (`10.0.2.2:3001` on
+   * Android emulators, `localhost:3001` elsewhere). Ignored for sandbox /
+   * production keys.
+   */
+  devUrl?: string;
+
+  /** Two-letter country code. */
+  country: C;
+
+  /** Subset of ID types to offer. Only types valid for the country are accepted. */
+  idTypes?: IdTypeForCountry<C>[];
+
+  /** Pre-populated user data. Fields provided here won't be collected again. */
+  userData?: {
+    firstName?: string;
+    lastName?: string;
+    dateOfBirth?: string;
+  };
+
+  /** Enable the live-selfie capture step. */
+  enableSelfie?: boolean;
+
+  /** Enable the document-photo capture step. */
+  enableDocumentCapture?: boolean;
+
+  /**
+   * Allow picking a document photo from the device gallery as an alternative to
+   * the live camera capture. Default `true`. When `false`, the "upload a photo
+   * instead" affordances are hidden during normal capture.
+   */
+  allowDocumentUpload?: boolean;
+
+  /** Enable liveness detection during selfie capture. Default `true`. */
+  enableLiveness?: boolean;
+
+  /**
+   * Spoken liveness instructions (accessibility). `true`/omitted = on,
+   * `false` = off, or a {@link VoiceGuidanceConfig}. TTS output only — no
+   * microphone is used. Default: on.
+   */
+  voiceGuidance?: VoiceGuidanceOption;
+
+  /** Show a light/dark mode toggle button inside the modal header. Default `true`. */
+  showThemeToggle?: boolean;
+
+  /**
+   * Hide the close (X) button and block all user-initiated dismissal of the
+   * sheet — the X button, Android hardware back, and the iOS swipe-down drag.
+   * When `true`, the flow can only be closed programmatically via the `close()`
+   * returned by {@link useMyazaKYC}. Default `false`. The terminal "Submitted"
+   * step is already non-dismissible regardless of this flag.
+   */
+  disableClose?: boolean;
+
+  /** Visual customisation. */
+  appearance?: KYCAppearance;
+
+  /** Override the consent (welcome) screen copy. */
+  consent?: KYCConsentContent;
+
+  /** Override the success (submitted) screen copy. */
+  success?: KYCSuccessContent;
+
+  /** Arbitrary metadata forwarded with every verification request. */
+  metadata?: Record<string, string>;
+
+  // Callbacks
+  onStart?: () => void;
+  onStepChange?: (step: KYCStep) => void;
+  /**
+   * Fires immediately after the user submits. The submission is always
+   * status: 'pending' — results arrive async via webhook.
+   */
+  onSubmit?: (submission: KYCSubmission) => void;
+  onClose?: () => void;
+  /**
+   * Fires for technical errors only. Receives a {@link KYCError} carrying a
+   * typed `code`. Verification *outcomes* never come through here.
+   */
+  onError?: (error: KYCError) => void;
+}
+
+// ---------------------------------------------------------------------------
+// useMyazaKYC() hook return type
+// ---------------------------------------------------------------------------
+
+export interface UseMyazaKYCReturn {
+  open: () => void;
+  close: () => void;
+  isOpen: boolean;
+  currentStep: KYCStep | null;
+}

package/src/types/country-flag-icons.d.ts

@@ -0,0 +1,6 @@
+// country-flag-icons ships no types for its per-country `string/3x2/*` modules.
+// Each default-exports the raw SVG markup as a string.
+declare module 'country-flag-icons/string/3x2/*' {
+  const svg: string;
+  export default svg;
+}