@myazahq/kyc-sdk-react-native 2.0.0 → 2.0.2

package/README.md

@@ -1,39 +1,67 @@
 # @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)
+active **on-device** liveness. 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.
+is delivered asynchronously via webhook — the SDK is **fire-and-forget**.
+
+## Requirements
+
+This library ships **native code** (an Apple Vision + Google ML Kit face detector,
+built as a [react-native-vision-camera](https://react-native-vision-camera.com) v5 /
+Nitro module), so it needs a **custom native build** and **does not run in Expo Go**.
+
+| Requirement | Minimum |
+| --- | --- |
+| **iOS** deployment target | **15.1** |
+| **Android** `minSdkVersion` | **24** (Android 7.0) · `compileSdk` 34 · NDK 27.1 |
+| **Expo SDK** | **56** (React 19, React Native 0.85) |
+| **React Native** | **0.83+**, with the **New Architecture enabled** (VisionCamera v5 / Nitro requires it; Expo SDK 56 enables it by default) |
+| **Build toolchain** | Xcode + CocoaPods (iOS) · **JDK 17** for Android Gradle builds |
+| **Runtime** | A **dev client** or bare build — **not Expo Go** |
+
+**Peer dependencies** to install in your app:
+
+| Package | Range | Purpose |
+| --- | --- | --- |
+| `expo` | `>=56` | Expo module runtime (the SDK uses several `expo-*` modules) |
+| `react` / `react-native` | `>=19` / `>=0.83` | — |
+| `react-native-vision-camera` | `^5` | Camera preview + capture |
+| `react-native-vision-camera-worklets` | `>=5` | Frame-processor worklet runtime |
+| `react-native-worklets` | `>=0.8` | Worklet `runOnJS` bridge for liveness |
+| `react-native-nitro-modules` | `>=0.35` | Native module runtime for the face detector |
+| `react-native-nitro-image` | `>=0.15` | Frame → image interop used by the detector |
+| `react-native-safe-area-context` | `>=4` | Safe-area insets for the modal |
+| `react-native-svg` | `>=15` | Liveness/overlay graphics |
 
-## 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.
+> Voice guidance is **text-to-speech output only** — the SDK never records audio,
+> so **no microphone permission** is requested or required.
 
-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).
+## Installation
 
 ### 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
+  react-native-vision-camera react-native-vision-camera-worklets \
+  react-native-worklets react-native-nitro-modules react-native-nitro-image \
+  react-native-safe-area-context react-native-svg
 ```
 
-Add the config plugins to `app.json` (the SDK's plugin adds the iOS camera usage
+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):
+the camera + frame processors. Make sure the **New Architecture** is on (it is by
+default on Expo SDK 56):
 
 ```jsonc
 // app.json
 {
   "expo": {
+    "newArchEnabled": true,
     "plugins": [
       ["react-native-vision-camera", { "enableMicrophonePermission": false }],
       "@myazahq/kyc-sdk-react-native"
@@ -46,7 +74,8 @@ Then build a dev client (regenerates the native projects):
 
 ```sh
 npx expo prebuild
-npx expo run:ios       # or: npx expo run:android
+npx expo run:ios                                  # iOS
+JAVA_HOME=/path/to/jdk-17 npx expo run:android    # Android — needs JDK 17
 ```
 
 > The SDK plugin accepts an optional custom camera prompt:
@@ -63,7 +92,9 @@ 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 \
+  react-native-vision-camera react-native-vision-camera-worklets \
+  react-native-worklets react-native-nitro-modules react-native-nitro-image \
+  react-native-safe-area-context 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
 
@@ -84,57 +115,284 @@ prebuild):
   <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
+- Ensure the **New Architecture** is enabled (`newArchEnabled=true` in
+  `android/gradle.properties`; `RCT_NEW_ARCH_ENABLED=1` for the iOS Podfile install),
+  and enable VisionCamera frame processors / the worklets babel plugin — 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`).
+The face-detector native module (Nitro HybridObject + Android lib loader) is
+autolinked via React Native / Expo autolinking — no manual linking required.
 
 ## Usage
 
+`<MyazaKYC />` renders a "Verify Identity" trigger plus the full modal flow. Pass
+`children` (a string) to relabel it. For a fully custom trigger, use the
+[`useMyazaKYC()` hook](#trigger-component--hook).
+
 ```tsx
 import { MyazaKYC } from '@myazahq/kyc-sdk-react-native';
 
-export default function Screen() {
+export default function VerifyScreen() {
   return (
     <MyazaKYC
-      apiKey="pk_test_xxx"          // prefix selects the env: pk_test_ → sandbox
+      apiKey="pk_live_xxx"          // prefix selects the env: pk_test_ → sandbox
       country="NG"
-      idTypes={['bvn', 'nin', 'passport']}
+      idTypes={['passport', 'drivers-license', 'bvn', 'nin', 'pvc']}
+      userData={{ firstName: 'Jane', lastName: 'Doe' }}
+      enableSelfie
       enableDocumentCapture
       enableLiveness
-      appearance={{ primaryColor: '#5645F5', companyName: 'Myaza', theme: 'light' }}
-      onSubmit={(s) => console.log('submitted', s.verificationId)}
-      onError={(e) => console.warn(e.code, e.message)}
-    />
+      showThemeToggle
+      appearance={{
+        primaryColor: '#5645F5',
+        companyName: 'Myaza',
+        logo: 'default',
+        theme: 'dark',
+      }}
+      consent={{
+        title: 'Welcome, {firstName}',
+        description: "A quick check to confirm it's really you.",
+      }}
+      success={{
+        title: "You're all set, {firstName}!",
+        description: "We'll email you once your verification is reviewed.",
+      }}
+      metadata={{ userId: 'test_user_123' }}
+      onStart={() => console.log('KYC started')}
+      onStepChange={(step) => console.log('Step:', step)}
+      onSubmit={(submission) => {
+        // Fires as soon as the server accepts the request.
+        // submission.status is always 'pending' — the result arrives later via
+        // webhook to your backend (or poll GET /api/kyc/status/:id).
+        console.log('Submitted!', submission.verificationId);
+      }}
+      onClose={() => console.log('Modal closed')}
+      onError={(err) => console.warn('SDK error:', err.code, err.message)}
+    >
+      Verify my identity
+    </MyazaKYC>
   );
 }
 ```
 
-Or drive the flow from your own trigger with the hook:
+## Props
+
+| Prop                    | Type                                      | Default             | Description                                                                                                          |
+| ----------------------- | ----------------------------------------- | ------------------- | -------------------------------------------------------------------------------------------------------------------- |
+| `apiKey`                | `string`                                  | —                   | **Required.** Sent as `Authorization: Bearer`. The **environment is derived from the key prefix** (`pk_test_…` → sandbox, `pk_live_…` → production); an unrecognized prefix throws. |
+| `country`               | `'NG' \| 'GH' \| 'KE' \| 'ZA' \| 'CI'`    | —                   | **Required.** Country whose ID types are offered.                                                                    |
+| `idTypes`               | `IdType[]`                                | all allowed for org | Subset of ID types to offer; must be valid for `country`.                                                            |
+| `userData`              | `{ firstName?, lastName?, dateOfBirth? }` | —                   | Pre-fills the user's details.                                                                                        |
+| `enableSelfie`          | `boolean`                                 | `true`              | Capture a selfie during liveness.                                                                                    |
+| `enableDocumentCapture` | `boolean`                                 | `true`              | Enable the document-scan step for document IDs.                                                                      |
+| `allowDocumentUpload`   | `boolean`                                 | `true`              | Allow picking a document photo from the gallery as an alternative to the camera. `false` hides every "upload instead" affordance (it's still offered on the camera-permission-denied screen as an escape hatch). |
+| `enableLiveness`        | `boolean`                                 | `true`              | Run the liveness challenge step. The server can still disable it per ID type.                                        |
+| `voiceGuidance`         | `boolean \| { enabled?, language? }`      | `true`              | Spoken liveness instructions (accessibility, TTS **output** — no microphone). `false` mutes it; pass `{ language: 'fr-FR' }` to set the voice. See [Robustness & error handling](#robustness--error-handling). |
+| `showThemeToggle`       | `boolean`                                 | `true`              | Show a light/dark toggle inside the modal header. When `false`, the flow stays on `appearance.theme`.                |
+| `disableClose`          | `boolean`                                 | `false`             | Hide the close (X) and block **all** user dismissal (X, Android back, iOS swipe-down). The flow can then only be closed programmatically via `useMyazaKYC().close()`. |
+| `appearance`            | `KYCAppearance`                           | brand defaults      | Brand & theme the modal — colors, logo, light/dark. See [Appearance & theming](#appearance--theming).                |
+| `consent`               | `KYCConsentContent`                       | built-in copy       | Override the consent/welcome screen `title` and `description`. See [Consent screen copy](#consent-screen-copy).      |
+| `success`               | `KYCSuccessContent`                       | built-in copy       | Override the success/submitted screen `title` and `description`. See [Success screen copy](#success-screen-copy).    |
+| `metadata`              | `Record<string, string>`                  | —                   | Forwarded with every verify request.                                                                                 |
+| `onStart`               | `() => void`                              | —                   | Called when the flow opens.                                                                                          |
+| `onStepChange`          | `(step: KYCStep) => void`                 | —                   | Called on each step transition.                                                                                      |
+| `onSubmit`              | `(submission: KYCSubmission) => void`     | —                   | Called when the server accepts the verification. `status` is always `'pending'`.                                     |
+| `onError`               | `(error: KYCError) => void`               | —                   | Called for **technical** errors only. Receives a typed [`KYCError`](#robustness--error-handling). Verification outcomes never come through here. |
+| `onClose`               | `() => void`                              | —                   | Called when the user closes the flow.                                                                                |
+| `children`              | `string`                                  | `Verify Identity`   | Trigger label. Defaults to `Verify with {companyName}` when `companyName` is set, else `Verify Identity`.            |
+| `disabled`              | `boolean`                                 | `false`             | Disable the trigger.                                                                                                 |
+
+## Environment
+
+There is **no `environment` prop** — the SDK derives the environment (and the
+base URL) from the API key prefix, the single source of truth:
+
+| Prefix     | Environment | Base URL                          |
+| ---------- | ----------- | --------------------------------- |
+| `pk_test_` | sandbox     | `https://identity.myaza.app`      |
+| `pk_live_` | production  | `https://identity.myaza.app`      |
+
+An unrecognized or malformed key throws at setup (it never silently defaults).
+
+## Trigger component & hook
+
+`<MyazaKYC />` renders a styled trigger that opens the modal. Beyond the config
+props it accepts `children` (a string label) and `disabled`:
+
+```tsx
+<MyazaKYC {...config} disabled={!ready}>
+  Start verification
+</MyazaKYC>
+```
+
+For a **fully custom** trigger (your own `Pressable`, an icon, a list row, or to
+open the flow programmatically), use the `useMyazaKYC()` hook:
 
 ```tsx
+import { Pressable, Text } from 'react-native';
 import { useMyazaKYC } from '@myazahq/kyc-sdk-react-native';
 
-const { open, close, isOpen, currentStep } = useMyazaKYC({ apiKey, country: 'NG' });
+function CustomTrigger() {
+  const { open, close, isOpen, currentStep } = useMyazaKYC({
+    apiKey: 'pk_live_xxx',
+    country: 'NG',
+    onSubmit: (s) => console.log('submitted', s.verificationId),
+  });
+
+  return (
+    <Pressable onPress={open}>
+      <Text>Verify your identity</Text>
+    </Pressable>
+  );
+}
 ```
 
-## Environment
+`useMyazaKYC(config)` returns `{ open, close, isOpen, currentStep }`. `close()` is
+the only way to dismiss the flow when `disableClose` is set.
 
-The base URL is auto-detected from the API key prefix — there is **no**
-`environment` prop:
+## Appearance & theming
 
-| 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`      |
+Pass an `appearance` object to brand the flow. Because the UI is token-driven,
+setting one color cascades to all of its shades (hover/selected/focus states
+included). Unset colors keep the built-in light/dark defaults.
+
+| Field              | Type                | Description                                                                      |
+| ------------------ | ------------------- | -------------------------------------------------------------------------------- |
+| `primaryColor`     | `string`            | Brand color — buttons, selected states, progress, the shield hero. Defaults to `#5645F5`. |
+| `primaryTextColor` | `string`            | Text/icons rendered on top of `primaryColor` (e.g. button labels).               |
+| `accentColor`      | `string`            | Subtle hover/active surfaces.                                                    |
+| `backgroundColor`  | `string`            | Modal background.                                                                |
+| `surfaceColor`     | `string`            | Cards & panels.                                                                  |
+| `borderColor`      | `string`            | Borders and input outlines.                                                      |
+| `textColor`        | `string`            | Primary text color.                                                              |
+| `companyName`      | `string`            | Used on the verify trigger ("Verify with …") and the persistent header.          |
+| `logo`             | `string`            | Image URL, or `'default'` to use your org's logo. See below.                     |
+| `theme`            | `'light' \| 'dark'` | Initial mode (defaults to `'light'`). With `showThemeToggle`, users can flip it. |
+
+### Logo
+
+The org logo renders as a small circular avatar in the modal header (top-left),
+persistent on every step, alongside `companyName`.
+
+- `logo: 'https://…/logo.png'` — uses that image directly.
+- `logo: 'default'` — pulls your organization's logo configured in the **Myaza dashboard**
+  (returned by the server on mount). If your org has no logo set, or the image fails
+  to load, the avatar is hidden.
+- omitted — no header logo.
+
+```tsx
+appearance={{
+  primaryColor: '#0F7B6C',
+  primaryTextColor: '#FFFFFF',
+  surfaceColor: '#F4F7F6',
+  borderColor: '#D7E3E0',
+  logo: 'default',
+  theme: 'light',
+}}
+```
+
+## Consent screen copy
+
+The welcome/consent step shows a heading and a short description. Override either
+through the `consent` prop:
+
+| Field         | Type     | Description                                                                                           |
+| ------------- | -------- | ----------------------------------------------------------------------------------------------------- |
+| `title`       | `string` | Heading. Defaults to `Welcome, {firstName}` when a first name is known, else `Identity Verification`. |
+| `description` | `string` | Sub-text under the heading. Defaults to the built-in regulatory copy.                                 |
+
+Both fields support `{firstName}` and `{lastName}` tokens, replaced with the values
+from `userData` (empty string when absent), so a custom title can still greet the
+user by name.
+
+```tsx
+consent={{
+  title: 'Welcome, {firstName}',
+  description: "We just need to confirm it's really you. This takes about a minute.",
+}}
+```
+
+## Success screen copy
+
+After the user submits, the final screen shows a confirmation heading and
+description. Override either through the `success` prop:
+
+| Field         | Type     | Description                                                                |
+| ------------- | -------- | -------------------------------------------------------------------------- |
+| `title`       | `string` | Heading. Defaults to `Verification Submitted!`.                            |
+| `description` | `string` | Sub-text under the heading. Defaults to the built-in "submitted for review" copy. |
+
+Both fields support the same `{firstName}` / `{lastName}` tokens as `consent`.
+
+```tsx
+success={{
+  title: "You're all set, {firstName}!",
+  description: "We'll email you once your verification is reviewed.",
+}}
+```
+
+## Robustness & error handling
+
+The SDK is resilient to flaky networks, denied permissions, and poor capture
+conditions, and reports technical failures through `onError` with a typed code.
+
+### Typed errors (`onError`)
+
+`onError` receives a `KYCError` with a typed `code`, a human-readable `message`,
+and optional `details`. The codes are **identical to the web and Flutter SDKs**:
+
+```tsx
+import { MyazaKYC, type KYCError } from '@myazahq/kyc-sdk-react-native';
+
+<MyazaKYC
+  {...config}
+  onError={(error: KYCError) => {
+    switch (error.code) {
+      case 'camera_permission_denied': /* ask the user to allow the camera */ break;
+      case 'insufficient_credits':     /* error.details = { required, balance, currency } */ break;
+      case 'network_error':
+      case 'upload_failed':            /* shown only after automatic retries */ break;
+    }
+  }}
+/>
+```
+
+| `code`                     | When it fires                                                        |
+| -------------------------- | ------------------------------------------------------------------- |
+| `network_error`            | Connection failure / timeout, **after retries are exhausted**.      |
+| `invalid_api_key`          | Server returned `401`.                                              |
+| `insufficient_credits`     | Server returned `402`. `details = { required, balance, currency }`. |
+| `upload_failed`            | A media upload failed, **after retries are exhausted**.            |
+| `camera_permission_denied` | The user denied (or the OS blocks) camera access.                  |
+| `feature_disabled`         | Server returned `403` (ID type / feature not enabled for the org). |
+| `unknown`                  | Anything else.                                                      |
+
+> Verification *outcomes* (identity not found, document mismatch, …) never come
+> through `onError` — they arrive asynchronously via webhook / `GET /api/kyc/status/:id`.
+
+### Network resilience
+
+Media uploads and the verify submission are wrapped in exponential-backoff retry
+(with jitter), retrying only *transient* failures (network / timeout / `5xx`);
+terminal `4xx` surface immediately. The UI shows a top toast while retrying, and
+`onError` fires **only after retries are exhausted** (`upload_failed` for uploads,
+`network_error` for connectivity).
+
+### Camera permission
+
+If the user denies camera access, the SDK shows a clear "camera access needed"
+screen (with an **Open Settings** action) instead of hanging, and reports
+`camera_permission_denied` to `onError`. Document capture additionally offers a
+gallery-upload fallback unless `allowDocumentUpload` is `false`.
+
+### Liveness quality guards
+
+- **Multiple faces** — if more than one face is in frame, the challenge pauses
+  ("Make sure only your face is visible") and resumes automatically when only one
+  face remains. This guards capture quality and a class of spoofing.
+- **Lighting** — too-dark *and* too-bright (glare) conditions are detected live
+  during liveness; the SDK shows guidance ("Move to a brighter area" / "Too bright
+  — reduce glare") and blocks auto-capture until lighting is acceptable.
 
 ## Liveness
 
@@ -147,18 +405,14 @@ per session). Face detection runs **on-device, natively**:
   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.
+v5 Nitro frame processor: the camera frame never crosses the JS bridge. The selfie
+is **auto-captured** once challenges pass (anti-spoofing — never user-triggered),
+and a short liveness video is recorded and uploaded best-effort.
 
-## Callbacks
+## Documentation
 
-`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`.
+Full documentation, configuration options, and webhook setup: **[identity.myaza.co/documentation/sdks](https://identity.myaza.co/documentation/sdks)**.
 
 ## License
 
-UNLICENSED — © Myaza.
+MIT © Flitstack Technologies Inc.

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@myazahq/kyc-sdk-react-native",
-  "version": "2.0.0",
+  "version": "2.0.2",
   "description": "Myaza KYC SDK for React Native (Expo) — ID verification, liveness detection, and document capture",
   "repository": {
     "type": "git",

package/src/__tests__/resolveUrl.test.ts

@@ -19,8 +19,8 @@ describe('detectEnvironment', () => {
 
 describe('resolveBaseUrl', () => {
   it('uses the hardcoded sandbox/production URLs and ignores devUrl', () => {
-    expect(resolveBaseUrl('pk_test_abc')).toBe('https://sandbox.identity.myaza.app');
-    expect(resolveBaseUrl('pk_test_abc', 'http://example.test')).toBe('https://sandbox.identity.myaza.app');
+    expect(resolveBaseUrl('pk_test_abc')).toBe('https://identity.myaza.app');
+    expect(resolveBaseUrl('pk_test_abc', 'http://example.test')).toBe('https://identity.myaza.app');
     expect(resolveBaseUrl('pk_live_abc')).toBe('https://identity.myaza.app');
   });
 
@@ -53,7 +53,7 @@ describe('normalizeDevAssetUrl', () => {
       'https://cdn.myaza.app/logo.png',
     );
     // https base (sandbox/prod) → never rewrites, even a localhost asset.
-    expect(normalizeDevAssetUrl('http://localhost:3001/logo.png', 'https://sandbox.identity.myaza.app')).toBe(
+    expect(normalizeDevAssetUrl('http://localhost:3001/logo.png', 'https://identity.myaza.app')).toBe(
       'http://localhost:3001/logo.png',
     );
   });

package/src/components/CameraPermissionView.tsx

@@ -21,11 +21,14 @@ interface ScaffoldProps {
   message: string;
   /** When true (default), vertically centers; false flows top-down below a heading. */
   centered?: boolean;
+  /** Accent color for the icon + its circle (defaults to the error tint). */
+  tint?: string;
   children: React.ReactNode; // action buttons
 }
 
-function CameraErrorScaffold({ icon, title, message, centered = true, children }: ScaffoldProps): React.ReactElement {
+function CameraErrorScaffold({ icon, title, message, centered = true, tint, children }: ScaffoldProps): React.ReactElement {
   const { colors } = useTheme();
+  const accent = tint ?? colors.error;
   return (
     <View
       style={
@@ -39,12 +42,12 @@ function CameraErrorScaffold({ icon, title, message, centered = true, children }
           width: 80,
           height: 80,
           borderRadius: radius.full,
-          backgroundColor: `${colors.error}1A`,
+          backgroundColor: `${accent}1A`,
           alignItems: 'center',
           justifyContent: 'center',
         }}
       >
-        <Icon name={icon} size={38} color={colors.error} />
+        <Icon name={icon} size={38} color={accent} />
       </View>
       <View style={{ height: spacing.lg }} />
       <MyazaText variant="heading2" style={{ textAlign: 'center' }}>
@@ -96,6 +99,39 @@ export function CameraPermissionView({ message, onRetry, onUpload, centered = tr
   );
 }
 
+// ── Permission primer (before the OS prompt) ─────────────────────────────────
+
+const DEFAULT_PRIMING_MESSAGE =
+  'When prompted, allow camera access to continue your verification.';
+
+export interface CameraPermissionPrimingViewProps {
+  message?: string;
+  /** Fires when the user taps "Grant access" — triggers the real OS prompt. */
+  onGrant: () => void;
+  centered?: boolean;
+}
+
+/**
+ * "Allow camera access" priming screen, shown right before the native OS camera
+ * permission prompt (mirrors Stripe Identity). The actual `requestPermission()`
+ * only fires once the user taps "Grant access". Distinct from
+ * `CameraPermissionView`, which is shown *after* a denial.
+ */
+export function CameraPermissionPrimingView({ message, onGrant, centered = true }: CameraPermissionPrimingViewProps): React.ReactElement {
+  const { colors } = useTheme();
+  return (
+    <CameraErrorScaffold
+      icon="camera"
+      title="Allow camera access"
+      message={message ?? DEFAULT_PRIMING_MESSAGE}
+      centered={centered}
+      tint={colors.primary}
+    >
+      <MyazaButton label="Grant access" onPress={onGrant} />
+    </CameraErrorScaffold>
+  );
+}
+
 // ── Camera unavailable (no device / init failure) ────────────────────────────
 
 const DEFAULT_UNAVAILABLE_MESSAGE =

package/src/config/idTypes.ts

@@ -8,6 +8,8 @@ import type { IdTypesByCountry } from '../types/config';
 export const ID_TYPES: IdTypesByCountry = {
   NG: [
     { key: 'bvn',             label: 'BVN',                            digits: 11,                    requiresDocumentCapture: false },
+    { key: 'bvn-premium',     label: 'BVN Premium',                    digits: 11,                    requiresDocumentCapture: false },
+    { key: 'tax-id',          label: 'Tax ID', inputLabel: 'NIN',      digits: 11,                    requiresDocumentCapture: false },
     { key: 'nin',             label: 'NIN',                            digits: 11,                    requiresDocumentCapture: false },
     { key: 'vnin',            label: 'Virtual NIN (vNIN)',             digits: 16,                    requiresDocumentCapture: false },
     { key: 'passport',        label: 'International Passport',          pattern: /^[A-Z]\d{8}$/,       requiresDocumentCapture: true, scanSides: 'front_only'     },

package/src/screens/DocumentCaptureStep.tsx

@@ -17,7 +17,7 @@ import { MyazaButton } from '../components/MyazaButton';
 import { useToast } from '../components/toast';
 import { MyazaPulseLoader } from '../components/MyazaPulseLoader';
 import { CameraViewfinder } from '../components/CameraViewfinder';
-import { CameraPermissionView, CameraUnavailableView } from '../components/CameraPermissionView';
+import { CameraPermissionView, CameraUnavailableView, CameraPermissionPrimingView } from '../components/CameraPermissionView';
 import { DocumentCropper } from '../components/DocumentCropper';
 import { Icon } from '../components/Icon';
 
@@ -100,9 +100,13 @@ export function DocumentCaptureStep(): React.ReactElement {
   // `perm` is derived from the ASYNC requestPermission result, not synchronously
   // from `hasPermission` — otherwise the brief window while the OS prompt is open
   // (hasPermission still false) would read as "denied" and fire onError early.
+  // 'priming' shows the "Allow camera access" screen BEFORE the OS prompt
+  // (Stripe-style); the prompt only fires (→ 'requesting') once the user taps
+  // "Grant access".
   const { hasPermission, requestPermission } = useCameraPermission();
-  const [perm, setPerm] = useState<'checking' | 'granted' | 'denied'>(hasPermission ? 'granted' : 'checking');
-  const askedRef = useRef(false);
+  const [perm, setPerm] = useState<'priming' | 'requesting' | 'granted' | 'denied'>(
+    hasPermission ? 'granted' : 'priming',
+  );
   const permReportedRef = useRef(false);
 
   // ── Camera availability ─────────────────────────────────────────────────────
@@ -123,19 +127,25 @@ export function DocumentCaptureStep(): React.ReactElement {
   // No camera hardware at all → "Camera not available" (regardless of what the
   // permission API says — on a camera-less sim it may even report denied).
   const cameraUnavailable = cameraGrace && !device;
+  const showPrimer = perm === 'priming' && !!device;
 
+  // Reflect an externally-granted permission.
   useEffect(() => {
-    if (hasPermission) {
-      setPerm('granted');
-      return;
-    }
-    if (askedRef.current) return;
-    askedRef.current = true;
+    if (hasPermission) setPerm('granted');
+  }, [hasPermission]);
+
+  // Fire the real OS prompt only after the user taps "Grant access" (or retry).
+  useEffect(() => {
+    if (perm !== 'requesting') return;
+    let cancelled = false;
     void (async () => {
       const granted = await requestPermission();
-      setPerm(granted ? 'granted' : 'denied');
+      if (!cancelled) setPerm(granted ? 'granted' : 'denied');
     })();
-  }, [hasPermission, requestPermission]);
+    return () => {
+      cancelled = true;
+    };
+  }, [perm, requestPermission]);
 
   // A *genuine* permission denial requires a camera to exist but be blocked. On a
   // camera-less sim the OS may report denied — that's "not available", not a
@@ -156,8 +166,7 @@ export function DocumentCaptureStep(): React.ReactElement {
   }, [permissionDenied, config.onError]);
 
   const retryPermission = useCallback(() => {
-    askedRef.current = false;
-    setPerm('checking');
+    setPerm('requesting');
   }, []);
 
   // ── Capture → compress → store for the current side ────────────────────────
@@ -303,6 +312,18 @@ export function DocumentCaptureStep(): React.ReactElement {
         </>
       );
     }
+    if (showPrimer) {
+      // Primer before the OS prompt — camera not started yet.
+      return (
+        <>
+          {cropper}
+          <CameraPermissionPrimingView
+            message="When prompted, allow camera access to photograph your document."
+            onGrant={() => setPerm('requesting')}
+          />
+        </>
+      );
+    }
     if (permissionDenied) {
       // A real camera exists but the OS blocked access.
       return (

package/src/screens/IdInputStep.tsx

@@ -14,10 +14,12 @@ import { MyazaButton } from '../components/MyazaButton';
 // IdInputScreen. Client-side format validation only; no OCR pre-fill. The step
 // title/description live in the header.
 
-function hintFor(def: { label: string; digits?: number } | null): string {
+function hintFor(def: { label: string; inputLabel?: string; digits?: number } | null): string {
   if (!def) return 'Enter your ID number';
-  if (def.digits != null) return `Enter ${def.digits}-digit ${def.label}`;
-  return `Enter your ${def.label}`;
+  // e.g. Tax ID is looked up by the person's NIN — ask for what they type.
+  const label = def.inputLabel ?? def.label;
+  if (def.digits != null) return `Enter ${def.digits}-digit ${label}`;
+  return `Enter your ${label}`;
 }
 
 export function IdInputStep(): React.ReactElement {
@@ -59,7 +61,7 @@ export function IdInputStep(): React.ReactElement {
     <View>
       {def ? (
         <MyazaText variant="label" style={{ marginBottom: spacing.sm }}>
-          {def.label}
+          {def.inputLabel ?? def.label}
         </MyazaText>
       ) : null}
       <MyazaInput

package/src/screens/LivenessStep.tsx

@@ -29,7 +29,7 @@ import {
 } from '../config/captureSettings';
 import { Icon } from '../components/Icon';
 import { useToast } from '../components/toast';
-import { CameraPermissionView, CameraUnavailableView } from '../components/CameraPermissionView';
+import { CameraPermissionView, CameraUnavailableView, CameraPermissionPrimingView } from '../components/CameraPermissionView';
 import { LivenessAvatar } from './LivenessAvatar';
 import { detectFaceOnFrame } from '../liveness/visionCameraFaceDetector';
 import {
@@ -85,10 +85,14 @@ export function LivenessStep(): React.ReactElement {
   });
   const videoRecorder = useVideoRecorder(videoOutput, !!device);
 
-  const [perm, setPerm] = useState<'checking' | 'granted' | 'denied'>(
-    hasPermission ? 'granted' : 'checking',
+  // 'priming' shows the "Allow camera access" screen BEFORE the OS prompt
+  // (Stripe-style); the prompt only fires (→ 'requesting') once the user taps
+  // "Grant access". `perm` is driven by the async requestPermission result, not
+  // synchronously from `hasPermission` — otherwise the window while the OS prompt
+  // is open (hasPermission still false) would read as "denied" and fire onError.
+  const [perm, setPerm] = useState<'priming' | 'requesting' | 'granted' | 'denied'>(
+    hasPermission ? 'granted' : 'priming',
   );
-  const askedRef = useRef(false);
   const permReportedRef = useRef(false);
 
   // Camera-availability grace (a simulator has no front camera).
@@ -98,20 +102,26 @@ export function LivenessStep(): React.ReactElement {
     return () => clearTimeout(t);
   }, []);
   const cameraUnavailable = cameraGrace && !device;
+  const showPrimer = perm === 'priming' && !!device;
   const permissionDenied = perm === 'denied' && !!device;
 
+  // Reflect an externally-granted permission.
   useEffect(() => {
-    if (hasPermission) {
-      setPerm('granted');
-      return;
-    }
-    if (askedRef.current) return;
-    askedRef.current = true;
+    if (hasPermission) setPerm('granted');
+  }, [hasPermission]);
+
+  // Fire the real OS prompt only after the user taps "Grant access" (or retry).
+  useEffect(() => {
+    if (perm !== 'requesting') return;
+    let cancelled = false;
     void (async () => {
       const granted = await requestPermission();
-      setPerm(granted ? 'granted' : 'denied');
+      if (!cancelled) setPerm(granted ? 'granted' : 'denied');
     })();
-  }, [hasPermission, requestPermission]);
+    return () => {
+      cancelled = true;
+    };
+  }, [perm, requestPermission]);
 
   useEffect(() => {
     if (permissionDenied && !permReportedRef.current) {
@@ -270,15 +280,11 @@ export function LivenessStep(): React.ReactElement {
   if (cameraUnavailable) {
     return <CameraUnavailableView />;
   }
+  if (showPrimer) {
+    return <CameraPermissionPrimingView onGrant={() => setPerm('requesting')} />;
+  }
   if (permissionDenied) {
-    return (
-      <CameraPermissionView
-        onRetry={() => {
-          askedRef.current = false;
-          setPerm('checking');
-        }}
-      />
-    );
+    return <CameraPermissionView onRetry={() => setPerm('requesting')} />;
   }
 
   // ── Review (selfie captured) ─────────────────────────────────────────────────

package/src/services/deviceMetadata.ts

@@ -14,7 +14,7 @@ export type DeviceType = 'mobile' | 'tablet' | 'desktop' | 'unknown';
  * Single source of truth for the SDK version — also used by `services/api.ts`
  * for the `X-SDK-Version` header. Keep in sync with `package.json`.
  */
-export const SDK_VERSION = '2.0.0';
+export const SDK_VERSION = '2.0.2';
 
 export interface ReactNativeDeviceMetadata {
   sdkType: 'react-native';

package/src/services/resolveUrl.ts

@@ -19,7 +19,8 @@ export type SdkEnvironment = 'development' | 'sandbox' | 'production';
 
 /** Canonical base URLs for the non-development environments. */
 const BASE_URLS: Record<Exclude<SdkEnvironment, 'development'>, string> = {
-  sandbox: 'https://sandbox.identity.myaza.app',
+  // Sandbox and production share the same host; the key prefix selects the env.
+  sandbox: 'https://identity.myaza.app',
   production: 'https://identity.myaza.app',
 };
 

package/src/services/validators.ts

@@ -34,6 +34,9 @@ function matchesPattern(value: string, pattern: RegExp, label: string, hint: str
 const validators: Record<string, (value: string) => ValidationResult> = {
   // Nigeria
   bvn: (v) => digitsExact(v, 11, 'BVN'),
+  'bvn-premium': (v) => digitsExact(v, 11, 'BVN'),
+  // Tax ID lookups are keyed off the person's NIN — the typed number is a NIN.
+  'tax-id': (v) => digitsExact(v, 11, 'NIN'),
   nin: (v) => digitsExact(v, 11, 'NIN'),
   vnin: (v) => {
     if (v.length !== 16) {

package/src/types/config.ts

@@ -6,7 +6,7 @@ import type { KYCSubmission, KYCError } from './verification';
 
 export type SupportedCountry = 'NG' | 'GH' | 'KE' | 'ZA' | 'CI';
 
-export type NigeriaIdType = 'bvn' | 'nin' | 'vnin' | 'passport' | 'drivers-license' | 'pvc';
+export type NigeriaIdType = 'bvn' | 'bvn-premium' | 'nin' | 'vnin' | 'tax-id' | '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';
@@ -31,6 +31,11 @@ export type IdTypeForCountry<C extends SupportedCountry> =
 export interface IdTypeDefinition {
   key: IdType;
   label: string;
+  /**
+   * What the user actually types when it differs from the ID's name — e.g.
+   * Tax ID lookups are keyed off the person's NIN, so the input asks for a NIN.
+   */
+  inputLabel?: string;
   digits?: number;
   pattern?: RegExp;
   /** Whether this ID type requires photographing/uploading a physical document. */