@myazahq/kyc-sdk-react-native 2.0.0

package/KycSdkReactNative.podspec

@@ -0,0 +1,32 @@
+require 'json'
+
+package = JSON.parse(File.read(File.join(__dir__, 'package.json')))
+
+Pod::Spec.new do |s|
+  s.name           = 'KycSdkReactNative'
+  s.version        = package['version']
+  s.summary        = package['description']
+  s.license        = package['license']
+  s.author         = 'Myaza'
+  s.homepage       = 'https://github.com/myazahq/kyc-sdk-react-native'
+  s.platforms      = { :ios => '15.1' }
+  s.swift_version  = '5.9'
+  s.source         = { :git => 'https://github.com/myazahq/kyc-sdk-react-native.git', :tag => "#{s.version}" }
+
+  # Apple Vision face-detector — a VisionCamera v5 Nitro HybridObject
+  # (ios/HybridMyazaFaceDetector.swift), generated from
+  # src/specs/MyazaFaceDetector.nitro.ts. No GoogleMLKit pod — iOS uses Vision,
+  # so the SDK still builds on Apple-Silicon iOS simulators.
+  s.source_files = 'ios/**/*.{h,m,mm,swift}'
+
+  s.dependency 'React-Core'
+  s.dependency 'VisionCamera'
+
+  # Add all files generated by Nitrogen (the C++/Swift specs, the Swift↔C++
+  # bridge, and the C++20 / SWIFT_OBJC_INTEROP_MODE=objcxx build settings the
+  # Nitro HybridObject needs) and the NitroModules dependency. Registration is
+  # handled by Nitro autolinking — no ObjC `+load` macro, so the old `-ObjC`
+  # dead-strip workaround is gone.
+  load 'nitrogen/generated/ios/KycSdkReactNative+autolinking.rb'
+  add_nitrogen_files(s)
+end

package/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 Flitstack Technologies Inc.
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

package/README.md

@@ -0,0 +1,164 @@
+# @myazahq/kyc-sdk-react-native
+
+Myaza KYC SDK for **React Native (Expo)** — ID verification, document capture, and
+active liveness detection. Mirrors the [web](https://www.npmjs.com/package/@myazahq/kyc-sdk-react)
+and Flutter SDKs feature-for-feature and calls the same Myaza KYC API server.
+
+The SDK is a **thin UI layer**: it captures the user's data (ID number, document
+photos, a live selfie), uploads the media, and submits a verification request.
+All verification (OCR, facial comparison, gov-DB checks) happens server-side and
+is delivered asynchronously via webhook — the SDK is fire-and-forget.
+
+## Install
+
+This library ships **native code** (an Apple Vision + Google ML Kit face-detector
+VisionCamera frame-processor plugin), so it needs a custom native build. It does
+**not** run in Expo Go. Pick your setup below.
+
+Peer dependencies (both setups): `react-native-vision-camera`,
+`react-native-worklets-core`, `react-native-svg`, and `expo` (the SDK uses several
+`expo-*` modules — see *Bare React Native* if you're not on a managed Expo app).
+
+### Expo app (managed / prebuild — recommended)
+
+```sh
+npx expo install @myazahq/kyc-sdk-react-native \
+  react-native-vision-camera react-native-worklets-core react-native-svg
+```
+
+Add the config plugins to `app.json` (the SDK's plugin adds the iOS camera usage
+string + Android `CAMERA`/`INTERNET` permissions; the VisionCamera plugin wires up
+the camera + frame processors):
+
+```jsonc
+// app.json
+{
+  "expo": {
+    "plugins": [
+      ["react-native-vision-camera", { "enableMicrophonePermission": false }],
+      "@myazahq/kyc-sdk-react-native"
+    ]
+  }
+}
+```
+
+Then build a dev client (regenerates the native projects):
+
+```sh
+npx expo prebuild
+npx expo run:ios       # or: npx expo run:android
+```
+
+> The SDK plugin accepts an optional custom camera prompt:
+> `["@myazahq/kyc-sdk-react-native", { "cameraPermission": "Your message…" }]`.
+
+### Bare React Native app (no Expo prebuild)
+
+The SDK depends on a handful of `expo-*` modules, so install **`expo`** (the
+package — you don't need the managed workflow) and let it autolink:
+
+```sh
+# 1. Add the Expo module runtime to your bare app (one-time):
+npx install-expo-modules@latest
+
+# 2. Install the SDK + peers:
+npm install @myazahq/kyc-sdk-react-native \
+  react-native-vision-camera react-native-worklets-core react-native-svg \
+  expo expo-image-manipulator expo-image-picker expo-speech expo-font \
+  expo-glass-effect expo-application expo-crypto expo-device expo-localization
+
+# 3. iOS pods:
+cd ios && pod install && cd ..
+```
+
+Then add the native permissions yourself (the Expo config plugin only runs under
+prebuild):
+
+- **iOS** — add to `ios/<App>/Info.plist`:
+  ```xml
+  <key>NSCameraUsageDescription</key>
+  <string>We use the camera to photograph your ID and capture a live selfie.</string>
+  ```
+- **Android** — add to `android/app/src/main/AndroidManifest.xml`:
+  ```xml
+  <uses-permission android:name="android.permission.CAMERA" />
+  <uses-permission android:name="android.permission.INTERNET" />
+  ```
+- Enable VisionCamera frame processors (it needs `react-native-worklets-core`,
+  installed above) — see the
+  [VisionCamera setup docs](https://react-native-vision-camera.com/docs/guides).
+
+The face-detector native module (podspec + Android Gradle project + the
+`detectFace` frame-processor plugin) is autolinked via React Native / Expo
+autolinking — no manual linking required.
+
+> Voice guidance is **text-to-speech output only** — the SDK never records audio,
+> so **no microphone permission** is requested or required
+> (`enableMicrophonePermission: false`).
+
+## Usage
+
+```tsx
+import { MyazaKYC } from '@myazahq/kyc-sdk-react-native';
+
+export default function Screen() {
+  return (
+    <MyazaKYC
+      apiKey="pk_test_xxx"          // prefix selects the env: pk_test_ → sandbox
+      country="NG"
+      idTypes={['bvn', 'nin', 'passport']}
+      enableDocumentCapture
+      enableLiveness
+      appearance={{ primaryColor: '#5645F5', companyName: 'Myaza', theme: 'light' }}
+      onSubmit={(s) => console.log('submitted', s.verificationId)}
+      onError={(e) => console.warn(e.code, e.message)}
+    />
+  );
+}
+```
+
+Or drive the flow from your own trigger with the hook:
+
+```tsx
+import { useMyazaKYC } from '@myazahq/kyc-sdk-react-native';
+
+const { open, close, isOpen, currentStep } = useMyazaKYC({ apiKey, country: 'NG' });
+```
+
+## Environment
+
+The base URL is auto-detected from the API key prefix — there is **no**
+`environment` prop:
+
+| Prefix     | Environment | Base URL                          |
+| ---------- | ----------- | --------------------------------- |
+| `pk_dev_`  | development | `http://localhost:3001` (override with `devUrl`) |
+| `pk_test_` | sandbox     | `https://sandbox.identity.myaza.app` |
+| `pk_live_` | production  | `https://identity.myaza.app`      |
+
+## Liveness
+
+Active, challenge-based liveness (nod / turn / blink / smile — 2 randomly chosen
+per session). Face detection runs **on-device, natively**:
+
+- **iOS** — Apple Vision (`VNDetectFaceLandmarksRequest`).
+- **Android** — Google ML Kit (native Gradle dep, Android-only — so no
+  cross-platform ML Kit iOS pod, and the SDK still builds on Apple-Silicon iOS
+  simulators).
+
+Both run as a [react-native-vision-camera](https://github.com/mrousavy/react-native-vision-camera)
+frame-processor plugin: the camera frame never crosses the JS bridge. The selfie
+is **auto-captured** once challenges pass (anti-spoofing), and a short liveness
+video is recorded and uploaded best-effort.
+
+## Callbacks
+
+`onSubmit(submission)` fires the moment the server accepts the request
+(`status: 'pending'`). `onError(KYCError)` fires for **technical** errors only
+(`network_error`, `invalid_api_key`, `insufficient_credits`, `upload_failed`,
+`camera_permission_denied`, `feature_disabled`). Verification *outcomes* arrive
+asynchronously via webhook / `GET /api/kyc/status/:id` — never through `onError`.
+
+## License
+
+UNLICENSED — © Myaza.

package/android/CMakeLists.txt

@@ -0,0 +1,29 @@
+project(KycSdkReactNative)
+cmake_minimum_required(VERSION 3.9.0)
+
+set(PACKAGE_NAME KycSdkReactNative)
+set(CMAKE_CXX_STANDARD 20)
+
+# Our only hand-written C++: the JNI_OnLoad that registers the Nitro HybridObjects.
+add_library(${PACKAGE_NAME} SHARED
+        src/main/cpp/cpp-adapter.cpp
+)
+
+# Add the nitrogen-generated specs + autolinking (adds sources, includes, and links
+# fbjni / ReactAndroid / react-native-nitro-modules to ${PACKAGE_NAME}).
+include(${CMAKE_SOURCE_DIR}/../nitrogen/generated/android/KycSdkReactNative+autolinking.cmake)
+
+# Our Nitro spec's `Frame` type comes from VisionCamera, so the generated C++
+# includes <VisionCamera/HybridFrameSpec.hpp> — link VisionCamera's prefab to put
+# its headers on the include path. (Nitrogen doesn't auto-link external-module
+# prefabs, so we add it by hand.)
+find_package(react-native-vision-camera REQUIRED CONFIG)
+
+find_library(LOG_LIB log)
+
+target_link_libraries(
+        ${PACKAGE_NAME}
+        ${LOG_LIB}
+        android
+        react-native-vision-camera::VisionCamera
+)

package/android/build.gradle

@@ -0,0 +1,110 @@
+// Gradle build for the Myaza KYC RN SDK's Android native piece — the Google ML Kit
+// face detector, now a VisionCamera v5 **Nitro** HybridObject (was a v4
+// FrameProcessorPlugin). Mirrors react-native-nitro-modules' Android build pattern:
+// the nitrogen-generated C++ specs are compiled into a shared lib (KycSdkReactNative)
+// via CMake, and the Kotlin impl (HybridMyazaFaceDetector) backs it.
+//
+// ML Kit stays Android-only (Gradle) — no GoogleMLKit CocoaPod on iOS — so the SDK
+// still builds on Apple-Silicon iOS simulators (iOS uses Apple Vision).
+
+buildscript {
+  ext.kotlin_version = ext.has('kotlinVersion') ? ext.kotlinVersion : '1.9.24'
+  repositories {
+    google()
+    mavenCentral()
+  }
+  dependencies {
+    classpath "org.jetbrains.kotlin:kotlin-gradle-plugin:$kotlin_version"
+  }
+}
+
+def reactNativeArchitectures() {
+  def value = rootProject.getProperties().get("reactNativeArchitectures")
+  return value ? value.split(",") : ["armeabi-v7a", "x86", "x86_64", "arm64-v8a"]
+}
+
+apply plugin: 'com.android.library'
+apply plugin: 'kotlin-android'
+// Adds the nitrogen-generated Kotlin sources (HybridMyazaFaceDetectorSpec, FaceResult, …).
+apply from: '../nitrogen/generated/android/KycSdkReactNative+autolinking.gradle'
+
+def safeExtGet(prop, fallback) {
+  rootProject.ext.has(prop) ? rootProject.ext.get(prop) : fallback
+}
+
+android {
+  namespace 'co.myazahq.kyc.rn'
+  compileSdk safeExtGet('compileSdkVersion', 34)
+  ndkVersion safeExtGet('ndkVersion', '27.1.12297006')
+
+  defaultConfig {
+    minSdk safeExtGet('minSdkVersion', 24)
+    targetSdk safeExtGet('targetSdkVersion', 34)
+
+    externalNativeBuild {
+      cmake {
+        cppFlags "-frtti -fexceptions -Wall -Wextra -fstack-protector-all"
+        arguments "-DANDROID_STL=c++_shared"
+        abiFilters(*reactNativeArchitectures())
+      }
+    }
+  }
+
+  externalNativeBuild {
+    cmake {
+      path "CMakeLists.txt"
+    }
+  }
+
+  buildFeatures {
+    prefab true
+    buildConfig true
+  }
+
+  // Don't bundle the shared libs already provided by the host app / RN.
+  packagingOptions {
+    excludes = [
+      "META-INF",
+      "META-INF/**",
+      "**/libc++_shared.so",
+      "**/libfbjni.so",
+      "**/libjsi.so",
+      "**/libreactnative.so",
+      "**/libreactnativejni.so",
+    ]
+  }
+
+  compileOptions {
+    sourceCompatibility JavaVersion.VERSION_17
+    targetCompatibility JavaVersion.VERSION_17
+  }
+
+  kotlinOptions {
+    jvmTarget = '17'
+  }
+}
+
+repositories {
+  google()
+  mavenCentral()
+}
+
+dependencies {
+  implementation "org.jetbrains.kotlin:kotlin-stdlib:$kotlin_version"
+  implementation 'com.facebook.react:react-android'
+
+  // Nitro core — provides the HybridObject base + the NitroModules prefab the
+  // generated CMake links against (find_package(react-native-nitro-modules)).
+  implementation project(':react-native-nitro-modules')
+
+  // VisionCamera — provides the Nitro `HybridFrameSpec` + `NativeFrame` (ImageProxy)
+  // the detector reads, plus its C++ prefab (headers for the generated spec).
+  // `implementation` (not compileOnly) so the prefab is consumable by our CMake.
+  implementation project(':react-native-vision-camera')
+
+  // CameraX core — for the ImageProxy / ExperimentalGetImage APIs.
+  compileOnly 'androidx.camera:camera-core:1.3.4'
+
+  // Google ML Kit face detection — Android only. Same version as the Flutter SDK.
+  implementation 'com.google.mlkit:face-detection:16.1.6'
+}

package/android/src/main/AndroidManifest.xml

@@ -0,0 +1,12 @@
+<manifest xmlns:android="http://schemas.android.com/apk/res/android">
+  <!--
+    The ML Kit face-detection model is downloaded on demand by Play Services.
+    This meta-data tells Play Services to fetch it at install time so the first
+    liveness session doesn't pay the download cost. Mirrors the Flutter SDK.
+  -->
+  <application>
+    <meta-data
+      android:name="com.google.mlkit.vision.DEPENDENCIES"
+      android:value="face" />
+  </application>
+</manifest>

package/android/src/main/cpp/cpp-adapter.cpp

@@ -0,0 +1,12 @@
+#include <jni.h>
+#include <fbjni/fbjni.h>
+#include "KycSdkReactNativeOnLoad.hpp"
+
+// Loaded via System.loadLibrary("KycSdkReactNative") (KycSdkReactNativeOnLoad.kt).
+// Registers all nitrogen-generated HybridObjects (MyazaFaceDetector) so the JS
+// `NitroModules.createHybridObject('MyazaFaceDetector')` resolves to the Kotlin impl.
+JNIEXPORT jint JNICALL JNI_OnLoad(JavaVM* vm, void*) {
+  return facebook::jni::initialize(vm, []() {
+    margelo::nitro::myazakyc::registerAllNatives();
+  });
+}

package/android/src/main/java/co/myazahq/kyc/rn/MyazaFaceDetectorPackage.kt

@@ -0,0 +1,36 @@
+package co.myazahq.kyc.rn
+
+import com.facebook.react.ReactPackage
+import com.facebook.react.bridge.NativeModule
+import com.facebook.react.bridge.ReactApplicationContext
+import com.facebook.react.uimanager.ViewManager
+import com.margelo.nitro.myazakyc.KycSdkReactNativeOnLoad
+
+/**
+ * Loads the SDK's Nitro C++ library (`libKycSdkReactNative.so`) at app startup.
+ * The library's JNI_OnLoad (`src/main/cpp/cpp-adapter.cpp`) registers the
+ * MyazaFaceDetector HybridObject, so JS
+ * `NitroModules.createHybridObject('MyazaFaceDetector')` resolves to the Kotlin
+ * impl (`com.margelo.nitro.myazakyc.HybridMyazaFaceDetector`).
+ *
+ * VisionCamera v5 dropped the FrameProcessorPluginRegistry model — Nitro
+ * HybridObjects replace it — so this package no longer registers a frame
+ * processor. It exists only so RN CLI autolinking (`react-native.config.js`)
+ * instantiates it on the host app's PackageList, triggering the library load
+ * (and therefore the HybridObject registration) before the liveness screen runs.
+ * It exposes no React Native modules or views.
+ */
+class MyazaFaceDetectorPackage : ReactPackage {
+  init {
+    KycSdkReactNativeOnLoad.initializeNative()
+  }
+
+  // MyazaStatusBarModule themes the modal's (Dialog window's) status/nav bars —
+  // something JS StatusBar/SystemBars can't reach. A native module (not a view
+  // manager) because legacy view managers aren't instantiated under Fabric.
+  override fun createNativeModules(reactContext: ReactApplicationContext): List<NativeModule> =
+    listOf(MyazaStatusBarModule(reactContext))
+
+  override fun createViewManagers(reactContext: ReactApplicationContext): List<ViewManager<*, *>> =
+    emptyList()
+}

package/android/src/main/java/co/myazahq/kyc/rn/MyazaStatusBarModule.kt

@@ -0,0 +1,64 @@
+package co.myazahq.kyc.rn
+
+import android.util.Log
+import androidx.core.view.ViewCompat
+import com.facebook.react.bridge.ReactApplicationContext
+import com.facebook.react.bridge.ReactContextBaseJavaModule
+import com.facebook.react.bridge.ReactMethod
+import com.facebook.react.bridge.UiThreadUtil
+import com.facebook.react.uimanager.UIManagerHelper
+
+/**
+ * Themes the status/navigation-bar ICON appearance of the SDK modal's window.
+ *
+ * The SDK flow renders inside a React Native `<Modal>`, which runs in its own
+ * native **Dialog window**. JS `StatusBar`/`SystemBars` only reach the **activity**
+ * window, so they can't theme the modal's bars. A native **view-manager** can't
+ * either — on the New Architecture, Fabric renders unregistered legacy view
+ * managers as a blank "unimplemented view". Native **modules**, however, work fine
+ * on Fabric, so this module resolves a view by tag (a view the SDK rendered INSIDE
+ * the modal) and applies the bar appearance to THAT view's window — i.e. the Dialog.
+ */
+class MyazaStatusBarModule(reactContext: ReactApplicationContext) :
+  ReactContextBaseJavaModule(reactContext) {
+
+  override fun getName(): String = NAME
+
+  /**
+   * @param viewTag a React tag of a view rendered inside the modal (its window is
+   *   the modal Dialog).
+   * @param light   true → light glyphs (dark background); false → dark glyphs.
+   */
+  @ReactMethod
+  fun setBarStyle(viewTag: Double, light: Boolean) {
+    val tag = viewTag.toInt()
+    val ctx = reactApplicationContext
+    UiThreadUtil.runOnUiThread {
+      val view = try {
+        UIManagerHelper.getUIManagerForReactTag(ctx, tag)?.resolveView(tag)
+      } catch (e: Exception) {
+        Log.w(TAG, "resolveView($tag) failed: ${e.message}")
+        null
+      } ?: ctx.currentActivity?.window?.decorView
+
+      if (view == null) {
+        Log.w(TAG, "no view/window to theme")
+        return@runOnUiThread
+      }
+
+      val controller = ViewCompat.getWindowInsetsController(view)
+      if (controller == null) {
+        Log.w(TAG, "insets controller is null for tag=$tag")
+        return@runOnUiThread
+      }
+      // isAppearanceLightStatusBars = true → dark glyphs; false → light glyphs.
+      controller.isAppearanceLightStatusBars = !light
+      controller.isAppearanceLightNavigationBars = !light
+    }
+  }
+
+  companion object {
+    const val NAME = "MyazaStatusBarModule"
+    private const val TAG = "MyazaStatusBar"
+  }
+}

package/android/src/main/java/com/margelo/nitro/myazakyc/HybridMyazaFaceDetector.kt

@@ -0,0 +1,134 @@
+package com.margelo.nitro.myazakyc
+
+import androidx.camera.core.ExperimentalGetImage
+import androidx.camera.core.ImageProxy
+import com.margelo.nitro.camera.HybridFrameSpec
+import com.margelo.nitro.camera.public.NativeFrame
+import com.google.mlkit.vision.common.InputImage
+import com.google.mlkit.vision.face.Face
+import com.google.mlkit.vision.face.FaceDetection
+import com.google.mlkit.vision.face.FaceDetector
+import com.google.mlkit.vision.face.FaceDetectorOptions
+import java.util.concurrent.CountDownLatch
+import java.util.concurrent.TimeUnit
+
+/**
+ * Android half of the Myaza KYC on-device face detector — now a VisionCamera v5
+ * **Nitro** HybridObject (the v4 FrameProcessorPlugin + FrameProcessorPluginRegistry
+ * model is gone). Implements the nitrogen-generated `HybridMyazaFaceDetectorSpec`
+ * from src/specs/MyazaFaceDetector.nitro.ts. The iOS half is
+ * HybridMyazaFaceDetector.swift (Apple Vision). Both return the SAME `FaceResult`
+ * shape the TS liveness flow consumes (see liveness/types.ts).
+ *
+ * Google ML Kit returns head pose + smile + eye-open DIRECTLY (no landmark math),
+ * so these map 1:1 onto LivenessFaceData and need no device tuning — unlike the iOS
+ * Vision heuristics. Direct port of the old v4 plugin's ML Kit logic, plus the
+ * frame-brightness signal (for the low-light gate) computed like the iOS side.
+ *
+ * The Nitro worklet calls detectFace synchronously, so we run ML Kit's async
+ * detector and await the result on the worklet thread with a short bound (FAST mode
+ * is well under a frame interval, so this doesn't stall the camera pipeline).
+ */
+class HybridMyazaFaceDetector : HybridMyazaFaceDetectorSpec() {
+  private val detector: FaceDetector = FaceDetection.getClient(
+    FaceDetectorOptions.Builder()
+      .setClassificationMode(FaceDetectorOptions.CLASSIFICATION_MODE_ALL)
+      .setPerformanceMode(FaceDetectorOptions.PERFORMANCE_MODE_FAST)
+      .enableTracking()
+      .setMinFaceSize(0.15f)
+      .build(),
+  )
+
+  @ExperimentalGetImage
+  override fun detectFace(frame: HybridFrameSpec): FaceResult {
+    // Same access pattern as iOS (cast to the public NativeFrame): VisionCamera's
+    // frame → CameraX ImageProxy → the underlying android.media.Image for ML Kit.
+    val proxy: ImageProxy = (frame as? NativeFrame)?.image ?: return noFace(128.0)
+    val brightness = averageLuma(proxy)
+    val mediaImage = proxy.image ?: return noFace(brightness)
+
+    val rotation = proxy.imageInfo.rotationDegrees
+    val input = InputImage.fromMediaImage(mediaImage, rotation)
+
+    var result: FaceResult? = null
+    val latch = CountDownLatch(1)
+    detector.process(input)
+      .addOnSuccessListener { faces ->
+        val face = faces.maxByOrNull { it.boundingBox.width() * it.boundingBox.height() }
+        result = face?.let { toResult(it, mediaImage.width, mediaImage.height, rotation, faces.size, brightness) }
+        latch.countDown()
+      }
+      .addOnFailureListener { latch.countDown() }
+
+    latch.await(200, TimeUnit.MILLISECONDS)
+    return result ?: noFace(brightness)
+  }
+
+  private fun toResult(
+    face: Face,
+    imageWidth: Int,
+    imageHeight: Int,
+    rotation: Int,
+    faceCount: Int,
+    brightness: Double,
+  ): FaceResult {
+    // After rotation the frame is upright; when rotated 90/270 the stored width/
+    // height are swapped, so the smaller dimension is the upright "width".
+    val frameWidth = if (rotation == 90 || rotation == 270) imageHeight else imageWidth
+    val ratio = (face.boundingBox.width().toDouble() / frameWidth).coerceIn(0.0, 1.0)
+    return FaceResult(
+      headEulerAngleX = face.headEulerAngleX.toDouble(),
+      headEulerAngleY = face.headEulerAngleY.toDouble(),
+      headEulerAngleZ = face.headEulerAngleZ.toDouble(),
+      smilingProbability = face.smilingProbability?.toDouble() ?: 0.0,
+      leftEyeOpenProbability = face.leftEyeOpenProbability?.toDouble() ?: 0.0,
+      rightEyeOpenProbability = face.rightEyeOpenProbability?.toDouble() ?: 0.0,
+      faceSizeRatio = ratio,
+      faceCount = faceCount.toDouble(),
+      brightness = brightness,
+    )
+  }
+
+  /** Mean luma (0–255) sampled on a coarse ~64×48 grid from the Y plane. */
+  private fun averageLuma(image: ImageProxy): Double {
+    val plane = image.planes.getOrNull(0) ?: return 128.0
+    val buffer = plane.buffer
+    val rowStride = plane.rowStride
+    val pixelStride = plane.pixelStride
+    val w = image.width
+    val h = image.height
+    val stepX = maxOf(1, w / 64)
+    val stepY = maxOf(1, h / 48)
+    var sum = 0.0
+    var count = 0
+    var y = 0
+    while (y < h) {
+      val rowStart = y * rowStride
+      var x = 0
+      while (x < w) {
+        val idx = rowStart + x * pixelStride
+        if (idx < buffer.limit()) {
+          sum += (buffer.get(idx).toInt() and 0xFF)
+          count++
+        }
+        x += stepX
+      }
+      y += stepY
+    }
+    return if (count > 0) sum / count else 128.0
+  }
+
+  // "No face" sentinel — faceCount 0 (the worklet maps this to onNoFace), still
+  // carrying the frame brightness so the low-light gate works pre-face.
+  private fun noFace(brightness: Double) = FaceResult(
+    headEulerAngleX = 0.0,
+    headEulerAngleY = 0.0,
+    headEulerAngleZ = 0.0,
+    smilingProbability = 0.0,
+    leftEyeOpenProbability = 1.0,
+    rightEyeOpenProbability = 1.0,
+    faceSizeRatio = 0.0,
+    faceCount = 0.0,
+    brightness = brightness,
+  )
+}

package/app.plugin.js

@@ -0,0 +1,55 @@
+const { withInfoPlist, withAndroidManifest, createRunOncePlugin, AndroidConfig } = require('expo/config-plugins');
+
+const pkg = require('./package.json');
+
+// ---------------------------------------------------------------------------
+// Expo config plugin for @myazahq/kyc-sdk-react-native.
+//
+// The native face-detector frame-processor plugin (iOS Apple Vision / Android
+// ML Kit) is autolinked via expo-module.config.json (the podspec + the Android
+// Gradle project + MyazaFaceDetectorPackage). This config plugin only handles
+// the things that must be written into the HOST app's native config:
+//
+//   • iOS  — NSCameraUsageDescription (document scan + selfie liveness).
+//            NOTE: voice guidance is TTS OUTPUT only, so NO microphone usage
+//            string and no NSMicrophoneUsageDescription are added.
+//   • Android — CAMERA + INTERNET permissions.
+//
+// Camera *preview/capture* itself comes from react-native-vision-camera; add its
+// own config plugin too (it injects the VisionCamera frame-processor build flag).
+// This plugin is intentionally minimal and idempotent (createRunOncePlugin).
+// ---------------------------------------------------------------------------
+
+const CAMERA_USAGE =
+  'We use the camera to photograph your ID document and to capture a live selfie for identity verification.';
+
+function withIosCameraUsage(config, customMessage) {
+  return withInfoPlist(config, (cfg) => {
+    if (!cfg.modResults.NSCameraUsageDescription) {
+      cfg.modResults.NSCameraUsageDescription = customMessage || CAMERA_USAGE;
+    }
+    return cfg;
+  });
+}
+
+function withAndroidCameraPermissions(config) {
+  return withAndroidManifest(config, (cfg) => {
+    AndroidConfig.Permissions.ensurePermissions(cfg.modResults, [
+      'android.permission.CAMERA',
+      'android.permission.INTERNET',
+    ]);
+    return cfg;
+  });
+}
+
+/**
+ * @param {object} config
+ * @param {{ cameraPermission?: string }} [props]
+ */
+function withMyazaKyc(config, props = {}) {
+  config = withIosCameraUsage(config, props.cameraPermission);
+  config = withAndroidCameraPermissions(config);
+  return config;
+}
+
+module.exports = createRunOncePlugin(withMyazaKyc, pkg.name, pkg.version);