@myazahq/kyc-sdk-react-native 2.0.0

package/expo-module.config.json

@@ -0,0 +1,6 @@
+{
+  "platforms": ["ios"],
+  "ios": {
+    "podName": "KycSdkReactNative"
+  }
+}

package/ios/HybridMyazaFaceDetector.swift

@@ -0,0 +1,233 @@
+import Foundation
+import Vision
+import CoreMedia
+import CoreVideo
+import VisionCamera
+import NitroModules
+
+// ---------------------------------------------------------------------------
+// HybridMyazaFaceDetector — the iOS half of the Myaza KYC face detector, now a
+// VisionCamera v5 **Nitro** HybridObject (the v4 FrameProcessorPlugin +
+// VISION_EXPORT_SWIFT_FRAME_PROCESSOR macro are gone). Implements the nitrogen-
+// generated `HybridMyazaFaceDetectorSpec` from src/specs/MyazaFaceDetector.nitro.ts.
+// The Android half is HybridMyazaFaceDetector.kt (Google ML Kit). Both return the
+// SAME `FaceResult` shape the TS liveness flow consumes (see liveness/types.ts):
+//
+//     headEulerAngleX/Y/Z, smilingProbability,
+//     leftEyeOpenProbability, rightEyeOpenProbability,
+//     faceSizeRatio, faceCount   (faceCount == 0 means "no face")
+//
+// Direct port of the old v4 plugin's Apple Vision logic. The frame's CVPixelBuffer
+// is reached by casting `any HybridFrameSpec` to VisionCamera's public
+// `NativeFrame` protocol (→ `sampleBuffer` → image buffer).
+//
+// Heuristic note (unchanged from v4 — tune on a physical iPhone): yaw/pitch/roll
+// come from Vision; eye-open and smile are derived from landmark geometry and
+// mapped to ML Kit's 0–1 scale; the `.upMirrored` orientation and the nod pitch
+// sign are conservative starting points.
+// ---------------------------------------------------------------------------
+
+final class HybridMyazaFaceDetector: HybridMyazaFaceDetectorSpec {
+  func detectFace(frame: any HybridFrameSpec) throws -> FaceResult {
+    guard
+      let nativeFrame = frame as? NativeFrame,
+      let sampleBuffer = nativeFrame.sampleBuffer,
+      let pixelBuffer = CMSampleBufferGetImageBuffer(sampleBuffer)
+    else {
+      return Self.noFace(brightness: 128)
+    }
+
+    // Mean frame luma (0–255) for the low-light gate — computed every frame,
+    // independent of whether a face is found, so the dark/bright warning shows
+    // even before the user is in frame.
+    let brightness = Self.averageLuma(pixelBuffer)
+
+    // Front camera, portrait. VisionCamera v5 delivers the buffer rotated 90°
+    // vs the v4/Flutter pipeline: `.upMirrored` here gives roll ≈ −105° (face
+    // sideways), which scrambles the landmark-derived smile/eye/pitch signals.
+    // `.leftMirrored` adds the missing +90°-family rotation so the face lands
+    // upright (roll ≈ 0) while keeping the front-camera mirror (yaw stays
+    // correct). Tune on device if roll is still off.
+    let orientation: CGImagePropertyOrientation = .leftMirrored
+
+    let request = VNDetectFaceLandmarksRequest()
+    let handler = VNImageRequestHandler(
+      cvPixelBuffer: pixelBuffer, orientation: orientation, options: [:]
+    )
+
+    do {
+      try handler.perform([request])
+    } catch {
+      return Self.noFace(brightness: brightness)
+    }
+
+    guard
+      let faces = request.results, !faces.isEmpty,
+      let face = faces.max(by: {
+        ($0.boundingBox.width * $0.boundingBox.height)
+          < ($1.boundingBox.width * $1.boundingBox.height)
+      })
+    else {
+      return Self.noFace(brightness: brightness)
+    }
+
+    let toDeg = 180.0 / Double.pi
+    let yawDeg = (face.yaw?.doubleValue ?? 0) * toDeg
+    let rollDeg = (face.roll?.doubleValue ?? 0) * toDeg
+
+    // Pitch: Vision's `face.pitch` is iOS 15+ and frequently returns nil/0 for
+    // VNDetectFaceLandmarksRequest. Derive a proxy from landmark geometry when
+    // it does — looking down pushes the nose UP in normalized landmark space, so
+    // we negate to match ML Kit's convention (headEulerAngleX < 0 == down).
+    var pitchDeg = 0.0
+    if #available(iOS 15.0, *), let p = face.pitch?.doubleValue, p != 0 {
+      pitchDeg = p * toDeg
+    } else {
+      pitchDeg = Self.pitchFromLandmarks(face.landmarks)
+    }
+
+    let leftOpen = Self.openProbability(fromEAR: Self.eyeAspectRatio(face.landmarks?.leftEye))
+    let rightOpen = Self.openProbability(fromEAR: Self.eyeAspectRatio(face.landmarks?.rightEye))
+    let smile = Self.smileProbability(face.landmarks)
+    let faceSizeRatio = Double(face.boundingBox.width)
+
+    return FaceResult(
+      headEulerAngleX: pitchDeg,
+      headEulerAngleY: yawDeg,
+      headEulerAngleZ: rollDeg,
+      smilingProbability: smile,
+      leftEyeOpenProbability: leftOpen,
+      rightEyeOpenProbability: rightOpen,
+      faceSizeRatio: faceSizeRatio,
+      // Number of faces in frame — the TS liveness flow pauses on > 1.
+      faceCount: Double(faces.count),
+      brightness: brightness
+    )
+  }
+
+  // "No face" sentinel — faceCount 0 (the worklet maps this to onNoFace), but
+  // still carries the frame brightness so the low-light gate works pre-face.
+  private static func noFace(brightness: Double) -> FaceResult {
+    FaceResult(
+      headEulerAngleX: 0, headEulerAngleY: 0, headEulerAngleZ: 0,
+      smilingProbability: 0, leftEyeOpenProbability: 1, rightEyeOpenProbability: 1,
+      faceSizeRatio: 0, faceCount: 0, brightness: brightness
+    )
+  }
+
+  /// Mean luma (0–255) of the frame, sampled on a coarse ~64×48 grid for speed.
+  /// For a YUV (4:2:0) buffer the first plane IS luma; for non-planar buffers we
+  /// approximate from the green channel. Mirrors the Flutter `_BrightnessSampler`.
+  private static func averageLuma(_ pixelBuffer: CVPixelBuffer) -> Double {
+    CVPixelBufferLockBaseAddress(pixelBuffer, .readOnly)
+    defer { CVPixelBufferUnlockBaseAddress(pixelBuffer, .readOnly) }
+
+    if CVPixelBufferGetPlaneCount(pixelBuffer) > 0,
+       let base = CVPixelBufferGetBaseAddressOfPlane(pixelBuffer, 0) {
+      let w = CVPixelBufferGetWidthOfPlane(pixelBuffer, 0)
+      let h = CVPixelBufferGetHeightOfPlane(pixelBuffer, 0)
+      let rowBytes = CVPixelBufferGetBytesPerRowOfPlane(pixelBuffer, 0)
+      let ptr = base.assumingMemoryBound(to: UInt8.self)
+      let stepX = max(1, w / 64)
+      let stepY = max(1, h / 48)
+      var sum = 0.0
+      var count = 0
+      var y = 0
+      while y < h {
+        let row = ptr + y * rowBytes
+        var x = 0
+        while x < w {
+          sum += Double(row[x])
+          count += 1
+          x += stepX
+        }
+        y += stepY
+      }
+      return count > 0 ? sum / Double(count) : 128
+    }
+
+    // Non-planar (e.g. BGRA) fallback — sample the green byte as a luma proxy.
+    guard let base = CVPixelBufferGetBaseAddress(pixelBuffer) else { return 128 }
+    let w = CVPixelBufferGetWidth(pixelBuffer)
+    let h = CVPixelBufferGetHeight(pixelBuffer)
+    let rowBytes = CVPixelBufferGetBytesPerRow(pixelBuffer)
+    let ptr = base.assumingMemoryBound(to: UInt8.self)
+    let stepX = max(1, w / 64)
+    let stepY = max(1, h / 48)
+    var sum = 0.0
+    var count = 0
+    var y = 0
+    while y < h {
+      let row = ptr + y * rowBytes
+      var x = 0
+      while x < w {
+        sum += Double(row[x * 4 + 1]) // BGRA → green
+        count += 1
+        x += stepX
+      }
+      y += stepY
+    }
+    return count > 0 ? sum / Double(count) : 128
+  }
+
+  // MARK: - Landmark heuristics (tune on device)
+
+  private static func eyeAspectRatio(_ region: VNFaceLandmarkRegion2D?) -> Double {
+    guard let pts = region?.normalizedPoints, pts.count >= 4 else { return 0.3 }
+    var minX = Double.greatestFiniteMagnitude
+    var maxX = -Double.greatestFiniteMagnitude
+    var minY = Double.greatestFiniteMagnitude
+    var maxY = -Double.greatestFiniteMagnitude
+    for p in pts {
+      minX = min(minX, Double(p.x)); maxX = max(maxX, Double(p.x))
+      minY = min(minY, Double(p.y)); maxY = max(maxY, Double(p.y))
+    }
+    let w = maxX - minX
+    let h = maxY - minY
+    return w > 0 ? h / w : 0.3
+  }
+
+  /// EAR → eye-open probability. EAR ≈ 0.10 (closed) → 0, ≈ 0.30 (open) → 1.
+  private static func openProbability(fromEAR ear: Double) -> Double {
+    let v = (ear - 0.10) / (0.30 - 0.10)
+    return min(max(v, 0.0), 1.0)
+  }
+
+  /// Smile from outer-lip width relative to the face. Input band (0.40→0.50):
+  /// a neutral mouth sits near 0, a clear smile lands well above the threshold.
+  private static func smileProbability(_ landmarks: VNFaceLandmarks2D?) -> Double {
+    guard let pts = landmarks?.outerLips?.normalizedPoints, pts.count >= 4 else {
+      return 0.0
+    }
+    var minX = Double.greatestFiniteMagnitude
+    var maxX = -Double.greatestFiniteMagnitude
+    for p in pts {
+      minX = min(minX, Double(p.x)); maxX = max(maxX, Double(p.x))
+    }
+    let width = maxX - minX
+    let score = (width - 0.40) / (0.50 - 0.40)
+    return min(max(score, 0.0), 1.0)
+  }
+
+  /// Pitch (nod) proxy from landmark geometry, used when Vision's `face.pitch`
+  /// is unavailable. Compares the nose vertical position to the eye line in the
+  /// face's normalized landmark space (origin bottom-left, y up). Looking DOWN
+  /// shrinks the eye→nose gap; mapped to a signed pseudo-degree, negated so down
+  /// yields a negative angle — matching ML Kit's headEulerAngleX convention.
+  private static func pitchFromLandmarks(_ landmarks: VNFaceLandmarks2D?) -> Double {
+    guard let lm = landmarks else { return 0 }
+    func meanY(_ r: VNFaceLandmarkRegion2D?) -> Double? {
+      guard let pts = r?.normalizedPoints, !pts.isEmpty else { return nil }
+      return pts.reduce(0.0) { $0 + Double($1.y) } / Double(pts.count)
+    }
+    let noseY = meanY(lm.noseCrest) ?? meanY(lm.nose)
+    let leftEyeY = meanY(lm.leftEye)
+    let rightEyeY = meanY(lm.rightEye)
+    guard let n = noseY, let le = leftEyeY, let re = rightEyeY else { return 0 }
+    let eyeY = (le + re) / 2.0
+    let gap = eyeY - n
+    let neutralGap = 0.18
+    let degPerUnit = 220.0
+    return (gap - neutralGap) * degPerUnit
+  }
+}

package/package.json

@@ -0,0 +1,84 @@
+{
+  "name": "@myazahq/kyc-sdk-react-native",
+  "version": "2.0.0",
+  "description": "Myaza KYC SDK for React Native (Expo) — ID verification, liveness detection, and document capture",
+  "repository": {
+    "type": "git",
+    "url": "https://github.com/myazahq/kyc-sdk-react-native.git"
+  },
+  "homepage": "https://github.com/myazahq/kyc-sdk-react-native#readme",
+  "bugs": {
+    "url": "https://github.com/myazahq/kyc-sdk-react-native/issues"
+  },
+  "main": "src/index.ts",
+  "types": "src/index.ts",
+  "files": [
+    "src",
+    "android",
+    "ios",
+    "app.plugin.js",
+    "expo-module.config.json",
+    "react-native.config.js",
+    "KycSdkReactNative.podspec"
+  ],
+  "publishConfig": {
+    "access": "public"
+  },
+  "scripts": {
+    "typecheck": "tsc --noEmit",
+    "test": "jest",
+    "specs": "nitrogen"
+  },
+  "keywords": [
+    "kyc",
+    "identity",
+    "verification",
+    "liveness",
+    "expo",
+    "react-native"
+  ],
+  "license": "MIT",
+  "peerDependencies": {
+    "expo": ">=56",
+    "react": ">=19",
+    "react-native": ">=0.83",
+    "react-native-nitro-image": ">=0.15",
+    "react-native-nitro-modules": ">=0.35",
+    "react-native-safe-area-context": ">=4",
+    "react-native-svg": ">=15",
+    "react-native-vision-camera-worklets": ">=5",
+    "react-native-worklets": ">=0.8"
+  },
+  "dependencies": {
+    "@expo-google-fonts/karla": "^0.4.2",
+    "@expo-google-fonts/space-grotesk": "^0.4.1",
+    "@expo/ui": "~56.0.16",
+    "@expo/vector-icons": "^14.0.4",
+    "country-flag-icons": "^1.6.17",
+    "expo-application": "~56.0.3",
+    "expo-crypto": "~56.0.4",
+    "expo-device": "~56.0.4",
+    "expo-font": "~56.0.5",
+    "expo-glass-effect": "~56.0.4",
+    "expo-image-manipulator": "~56.0.17",
+    "expo-image-picker": "~56.0.16",
+    "expo-localization": "~56.0.6",
+    "expo-speech": "~56.0.3",
+    "lucide-react-native": "^1.17.0",
+    "react-native-compressor": "^1.19.0",
+    "react-native-vision-camera": "^5.0.11",
+    "zustand": "^5.0.2"
+  },
+  "devDependencies": {
+    "@types/jest": "^29.5.12",
+    "@types/node": "^22.10.2",
+    "@types/react": "~19.2.2",
+    "expo": "~56.0.9",
+    "jest": "^29.7.0",
+    "nitrogen": "0.35.9",
+    "react": "19.2.3",
+    "react-native": "0.85.3",
+    "ts-jest": "^29.2.5",
+    "typescript": "^5.6.3"
+  }
+}

package/react-native.config.js

@@ -0,0 +1,23 @@
+// React Native CLI autolinking config.
+//
+// The Android side of this SDK is a plain RN native module that exposes a
+// `ReactPackage` (`MyazaFaceDetectorPackage`, which registers the VisionCamera
+// "detectFace" frame-processor plugin). RN CLI autolinking — NOT Expo modules
+// autolinking — is what discovers `ReactPackage`s, so the Android project is
+// declared here. (Expo's `expo-module.config.json` is iOS-only for this package;
+// a `ReactPackage` is not an Expo `Module` and can't be registered there.)
+//
+// iOS autolinking finds the pod via the `*.podspec` at the package root, so no
+// iOS entry is needed here.
+
+module.exports = {
+  dependency: {
+    platforms: {
+      android: {
+        sourceDir: 'android',
+        packageImportPath: 'import co.myazahq.kyc.rn.MyazaFaceDetectorPackage;',
+        packageInstance: 'new MyazaFaceDetectorPackage()',
+      },
+    },
+  },
+};

package/src/MyazaKYC.tsx

@@ -0,0 +1,235 @@
+import React, { useCallback, 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
+// Flutter's showModalBottomSheet); Android uses a full-screen page (matching
+// Flutter's Android MaterialPageRoute).
+const MODAL_PRESENTATION = Platform.OS === 'ios' ? 'pageSheet' : 'fullScreen';
+
+// 'slide' drives the present animation: on iOS the native pageSheet slides up and
+// keeps its native drag-to-dismiss; on Android the full-screen page slides up.
+// ('none' suppresses the present transition, leaving no slide-up and no drag.)
+const MODAL_ANIMATION = 'slide';
+
+import type { KYCStep, MyazaKYCConfig, SupportedCountry } from './types/config';
+import { KycRuntimeProvider, useKycStore } from './components/runtime';
+import { KycFlow, type BackResult } from './components/KycFlow';
+import { MyazaButton } from './components/MyazaButton';
+
+/**
+ * Builds the `<Modal onRequestClose>` handler (Android hardware back / TV menu).
+ * It first asks the flow's back handler (via `backRef`) to navigate a step back;
+ * only when the flow is at its first step ('close') and close isn't disabled
+ * does it actually close. This is why back walks the flow backward instead of
+ * dismissing the whole SDK. Falls back to `close()` if the flow hasn't wired a
+ * handler yet (e.g. before first paint).
+ */
+function makeRequestClose(
+  backRef: React.MutableRefObject<(() => BackResult) | null>,
+  close: () => void,
+  blockDismiss: boolean,
+): () => void {
+  return () => {
+    const result = backRef.current?.();
+    if (result === 'navigated' || result === 'blocked') return;
+    // result === 'close' (first step, close allowed) or no handler yet.
+    if (!blockDismiss) close();
+  };
+}
+
+// ---------------------------------------------------------------------------
+// Public entry points — `<MyazaKYC />` (trigger + modal) and `useMyazaKYC()`
+// (custom trigger). Mirrors the web SDK's component + hook API, adapted to React
+// Native's `<Modal>` (the RN equivalent of the web modal/portal).
+// ---------------------------------------------------------------------------
+
+export interface MyazaKYCProps<C extends SupportedCountry = SupportedCountry> extends MyazaKYCConfig<C> {
+  /** Custom trigger label (defaults to "Verify with {companyName}" / "Verify Identity"). */
+  children?: string;
+  /** Disable the built-in trigger button. */
+  disabled?: boolean;
+}
+
+function defaultTriggerLabel(config: MyazaKYCConfig): string {
+  const name = config.appearance?.companyName;
+  return name ? `Verify with ${name}` : 'Verify Identity';
+}
+
+export function MyazaKYC<C extends SupportedCountry = SupportedCountry>(
+  props: MyazaKYCProps<C>,
+): React.ReactElement {
+  const { children, disabled, ...config } = props;
+  // 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.
+  return (
+    <KycRuntimeProvider config={config}>
+      <MyazaKYCTrigger config={config} label={children} disabled={disabled} />
+    </KycRuntimeProvider>
+  );
+}
+
+function MyazaKYCTrigger({
+  config,
+  label,
+  disabled,
+}: {
+  config: MyazaKYCConfig;
+  label?: string;
+  disabled?: boolean;
+}): React.ReactElement {
+  const store = useKycStore();
+  const [open, setOpen] = 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);
+
+  const openFlow = useCallback(() => {
+    closedRef.current = false;
+    store.getState().reset();
+    setOpen(true);
+  }, [store]);
+
+  const close = useCallback(() => {
+    if (closedRef.current) return;
+    closedRef.current = true;
+    setOpen(false);
+    config.onClose?.();
+  }, [config]);
+
+  // `disableClose` presents full-screen on iOS (kills the swipe-down drag). The
+  // Android hardware back goes through `onRequestClose`, which walks the flow
+  // back a step (or closes from the first step, unless disableClose).
+  const blockDismiss = config.disableClose === true;
+  const presentation = blockDismiss ? 'fullScreen' : MODAL_PRESENTATION;
+  const onRequestClose = useCallback(
+    () => makeRequestClose(backRef, close, blockDismiss)(),
+    [close, blockDismiss],
+  );
+
+  return (
+    <>
+      <MyazaButton
+        label={label ?? defaultTriggerLabel(config)}
+        disabled={disabled}
+        fullWidth={false}
+        onPress={openFlow}
+      />
+      <Modal
+        visible={open}
+        animationType={MODAL_ANIMATION}
+        presentationStyle={presentation}
+        statusBarTranslucent
+        navigationBarTranslucent
+        onRequestClose={onRequestClose}
+        onDismiss={blockDismiss ? undefined : close}
+      >
+        {open ? <KycFlow onClose={close} backRef={backRef} /> : null}
+      </Modal>
+    </>
+  );
+}
+
+// ---------------------------------------------------------------------------
+// useMyazaKYC — for fully custom triggers. Returns the controller plus a bound
+// `MyazaKYCModal` host element to render once in your tree. The consumer's own
+// trigger element is plain (no theme dependency); the modal carries its own
+// provider, mounted fresh on each open.
+// ---------------------------------------------------------------------------
+
+export interface UseMyazaKYCReturn {
+  open: () => void;
+  close: () => void;
+  isOpen: boolean;
+  currentStep: KYCStep | null;
+  /** Render this once in your component tree (RN has no implicit portal). */
+  MyazaKYCModal: React.FC;
+}
+
+export function useMyazaKYC<C extends SupportedCountry = SupportedCountry>(
+  config: MyazaKYCConfig<C>,
+): UseMyazaKYCReturn {
+  const [isOpen, setIsOpen] = useState(false);
+  const [currentStep, setCurrentStep] = useState<KYCStep | null>(null);
+  const closedRef = useRef(true);
+
+  // Consumers pass an inline config object, so its identity changes on every
+  // render of their component. Keep the LATEST config in a ref and read it from
+  // the (stable) callbacks below. This is what keeps `wrappedConfig` and the
+  // `MyazaKYCModal` element stable across re-renders — otherwise a step change
+  // (which re-renders the consumer) would rebuild the modal subtree, and on iOS
+  // a remounted presented <Modal> fires onDismiss → an unwanted close().
+  const configRef = useRef(config);
+  configRef.current = config;
+  const backRef = useRef<(() => BackResult) | null>(null);
+
+  const open = useCallback(() => {
+    closedRef.current = false;
+    setIsOpen(true);
+  }, []);
+  const close = useCallback(() => {
+    if (closedRef.current) return;
+    closedRef.current = true;
+    setIsOpen(false);
+    setCurrentStep(null);
+    configRef.current.onClose?.();
+  }, []);
+
+  // Stable wrapped config: spreads the latest config but overrides onStepChange
+  // to surface the live step to the consumer. Built once (the spread reads the
+  // ref at call time via the wrapped callbacks), so the modal's provider/store
+  // isn't recreated on each render.
+  const wrappedConfig = useMemo<MyazaKYCConfig<C>>(
+    () => ({
+      ...configRef.current,
+      onStart: () => configRef.current.onStart?.(),
+      onStepChange: (step: KYCStep) => {
+        setCurrentStep(step);
+        configRef.current.onStepChange?.(step);
+      },
+      onSubmit: (submission) => configRef.current.onSubmit?.(submission),
+      onError: (error) => configRef.current.onError?.(error),
+      onClose: () => configRef.current.onClose?.(),
+    }),
+    [],
+  );
+
+  // 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
+  // closes from the first step, unless disableClose) — same as the trigger
+  // component. Read once from the ref so the modal element stays stable; the
+  // flag isn't expected to flip mid-session.
+  const blockDismiss = configRef.current.disableClose === true;
+  const onRequestClose = useCallback(
+    () => makeRequestClose(backRef, close, blockDismiss)(),
+    [close, blockDismiss],
+  );
+
+  // Stable modal element — depends only on open/close state, never on the
+  // changing consumer config (see configRef above).
+  const MyazaKYCModal = useCallback<React.FC>(
+    () => (
+      <Modal
+        visible={isOpen}
+        animationType={MODAL_ANIMATION}
+        presentationStyle={blockDismiss ? 'fullScreen' : MODAL_PRESENTATION}
+        statusBarTranslucent
+        navigationBarTranslucent
+        onRequestClose={onRequestClose}
+        onDismiss={blockDismiss ? undefined : close}
+      >
+        {/* Fresh provider/store per open. */}
+        {isOpen ? (
+          <KycRuntimeProvider config={wrappedConfig}>
+            <KycFlow onClose={close} backRef={backRef} />
+          </KycRuntimeProvider>
+        ) : null}
+      </Modal>
+    ),
+    [wrappedConfig, isOpen, close, blockDismiss, onRequestClose],
+  );
+
+  return { open, close, isOpen, currentStep, MyazaKYCModal };
+}

package/src/__tests__/cardCrop.test.ts

@@ -0,0 +1,39 @@
+import { cardCropRect } from '../services/cardCrop';
+import { CARD_GUIDE_ASPECT, PASSPORT_GUIDE_ASPECT } from '../config/idTypes';
+
+describe('cardCropRect', () => {
+  it('produces a crop whose aspect equals the guide aspect', () => {
+    const r = cardCropRect(4000, 3000, CARD_GUIDE_ASPECT);
+    expect(r.width / r.height).toBeCloseTo(CARD_GUIDE_ASPECT, 3);
+  });
+
+  it('stays within the image bounds', () => {
+    for (const [w, h] of [
+      [4000, 3000], // landscape sensor
+      [3000, 4000], // portrait sensor
+      [1920, 1080], // 16:9
+    ] as const) {
+      const r = cardCropRect(w, h, CARD_GUIDE_ASPECT);
+      expect(r.originX).toBeGreaterThanOrEqual(0);
+      expect(r.originY).toBeGreaterThanOrEqual(0);
+      expect(r.originX + r.width).toBeLessThanOrEqual(w + 0.01);
+      expect(r.originY + r.height).toBeLessThanOrEqual(h + 0.01);
+    }
+  });
+
+  it('centres the crop within the cover-fit 3:4 slice (landscape sensor)', () => {
+    // 4000×3000 → visible slice is 2250×3000 centred at x=875.
+    const r = cardCropRect(4000, 3000, CARD_GUIDE_ASPECT);
+    const sliceCentreX = 875 + 2250 / 2;
+    expect(r.originX + r.width / 2).toBeCloseTo(sliceCentreX, 3);
+    expect(r.originY + r.height / 2).toBeCloseTo(3000 / 2, 3); // vertically centred (no shift)
+  });
+
+  it('gives passports a taller crop (smaller aspect) than ID cards', () => {
+    const card = cardCropRect(4000, 3000, CARD_GUIDE_ASPECT);
+    const passport = cardCropRect(4000, 3000, PASSPORT_GUIDE_ASPECT);
+    expect(passport.height).toBeGreaterThan(card.height);
+    expect(passport.width).toBeCloseTo(card.width, 3); // same 88% width
+    expect(passport.width / passport.height).toBeCloseTo(PASSPORT_GUIDE_ASPECT, 3);
+  });
+});

package/src/__tests__/deviceMetadata.test.ts

@@ -0,0 +1,34 @@
+import { collectDeviceMetadata, inferDeviceType } from '../services/deviceMetadata';
+
+// expo-device's DeviceType enum: UNKNOWN=0, PHONE=1, TABLET=2, DESKTOP=3, TV=4.
+describe('inferDeviceType', () => {
+  it('maps the expo-device DeviceType enum to the dashboard classes', () => {
+    expect(inferDeviceType({ deviceType: 1 })).toBe('mobile'); // PHONE
+    expect(inferDeviceType({ deviceType: 2 })).toBe('tablet'); // TABLET
+    expect(inferDeviceType({ deviceType: 3 })).toBe('desktop'); // DESKTOP
+    expect(inferDeviceType({ deviceType: 4 })).toBe('unknown'); // TV
+    expect(inferDeviceType({ deviceType: 0 })).toBe('unknown'); // UNKNOWN
+  });
+
+  it('falls back to the platform when expo-device is unavailable (Node → ios → mobile)', () => {
+    expect(inferDeviceType(undefined)).toBe('mobile');
+    expect(inferDeviceType({ deviceType: null })).toBe('mobile');
+  });
+});
+
+describe('collectDeviceMetadata', () => {
+  it('always sets a device.type (never the empty dashboard "—")', () => {
+    const meta = collectDeviceMetadata();
+    expect(meta.device.type).toBeDefined();
+    expect(['mobile', 'tablet', 'desktop', 'unknown']).toContain(meta.device.type);
+  });
+
+  it('keeps sdkType react-native and includes the device sub-object', () => {
+    const meta = collectDeviceMetadata();
+    expect(meta.sdkType).toBe('react-native');
+    // Under the Node test runner expo-device isn't resolvable, so the type comes
+    // from the platform fallback (ios → mobile) and brand/vendor are omitted.
+    expect(meta.device.type).toBe('mobile');
+    expect(meta.device).toHaveProperty('type');
+  });
+});