@velion-la/onboarding-sdk-react-native 1.0.0-beta.2

package/README.md

@@ -0,0 +1,803 @@
+# Velion Onboarding SDK — React Native
+
+`@velion-la/onboarding-sdk-react-native` is the native React Native SDK that
+runs the complete Velion KYC flow inside an iOS or Android app:
+
+- Device fingerprint.
+- Personal / legal information forms.
+- Email and SMS OTP.
+- Sworn declaration and terms & conditions.
+- Document OCR (front + back) with a native camera.
+- Active liveness with face mesh challenges.
+- Face match against the captured ID document.
+- Optional map-assisted address picker.
+
+The SDK uses the same Onboarding backend contract (REST + SSE events + step
+state machine) as Velion's web SDK and adds a fully native UI and camera.
+
+## Table of contents
+
+- [Quickstart](#quickstart)
+- [Installation](#installation)
+- [Native setup](#native-setup)
+- [Permissions](#permissions)
+- [Using the component](#using-the-component)
+- [`VelionConfig`](#velionconfig)
+- [Callbacks](#callbacks)
+- [Theming](#theming)
+- [Locales](#locales)
+- [Errors](#errors)
+- [Assisted address mode (Google Maps)](#assisted-address-mode-google-maps)
+- [Supported steps](#supported-steps)
+- [Stack and architecture](#stack-and-architecture)
+- [Local development](#local-development)
+- [Publishing](#publishing)
+- [License](#license)
+
+---
+
+## Quickstart
+
+```tsx
+import { VelionOnboardingScreen } from '@velion-la/onboarding-sdk-react-native';
+
+export function KycScreen({ navigation }) {
+  return (
+    <VelionOnboardingScreen
+      config={{
+        sessionId: 'ses_abc123',                 // returned by your backend
+        sessionToken: 'eyJ...',                  // returned by your backend
+        apiUrl: 'https://api.velion.la/gateway/api/v1/onboarding/public/sdk',
+        locale: 'es',
+        colorMode: 'auto',
+        onSuccess: (result) => console.log('done', result.status),
+        onError: (err) => console.error(err.code, err.message),
+      }}
+      onComplete={(result) => navigation.replace('Home', { kyc: result })}
+      onFail={() => navigation.goBack()}
+    />
+  );
+}
+```
+
+The component is full-screen and takes care of:
+
+1. Loading the session (`GET /sessions/:id`).
+2. Opening the SSE stream for backend-driven events.
+3. Rendering each step requested by the backend in order.
+4. Resolving the flow at the end (`onSuccess` / `onError`).
+
+---
+
+## Installation
+
+### 1. The SDK
+
+```bash
+npm install @velion-la/onboarding-sdk-react-native
+```
+
+### 2. Required peer dependencies
+
+```bash
+npm install \
+  react-native-vision-camera \
+  react-native-svg \
+  react-native-sse \
+  expo-application expo-crypto expo-device expo-image-manipulator expo-keep-awake expo-location \
+  @noble/hashes
+```
+
+### 3. Optional peer dependencies (assisted address mode)
+
+```bash
+npm install react-native-maps
+```
+
+When `react-native-maps` is not installed, the `ADDRESS_INFO` step falls back
+to a manual form and nothing else is required. The SDK does **not** depend on
+`react-native-google-places-autocomplete`; the address search uses the
+OS-native geocoder via `expo-location`.
+
+### Supported versions
+
+| Package | Minimum | Tested against |
+|---|---|---|
+| `react` | `>=19.0.0` | `19.1.0` |
+| `react-native` | `>=0.81.0` | `0.81.5` |
+| `expo` | `>=54.0.0` | `~54.0.34` |
+| `react-native-vision-camera` | `>=4.6.0` | `4.7.x` |
+
+---
+
+## Native setup
+
+Vision Camera **does not run inside Expo Go**. Your app must have the `ios/`
+and `android/` folders generated (either a bare React Native project or
+`npx expo prebuild`).
+
+### Expo plugins (`app.json` / `app.config.js`)
+
+```jsonc
+{
+  "expo": {
+    "plugins": [
+      "expo-dev-client",
+      [
+        "react-native-vision-camera",
+        {
+          "cameraPermissionText": "$(PRODUCT_NAME) needs access to your camera to capture your ID document and run the liveness check.",
+          "enableMicrophonePermission": false,
+          "enableCodeScanner": false
+        }
+      ],
+      [
+        "expo-location",
+        {
+          "locationWhenInUsePermission": "We use your location to suggest your home address."
+        }
+      ]
+    ]
+  }
+}
+```
+
+> Do **not** include `"expo-image-manipulator"` in `plugins[]`. From Expo SDK
+> 54 onwards it is a runtime-only module, not a config plugin.
+
+Then run:
+
+```bash
+npx expo prebuild --clean
+npx expo run:ios     # or run:android
+```
+
+### Bare React Native (no Expo)
+
+Follow each library's own setup guide:
+
+- Vision Camera: <https://react-native-vision-camera.com/docs/guides>
+- React Native Maps (only if used): <https://github.com/react-native-maps/react-native-maps#installation>
+- Expo modules inside a bare project: <https://docs.expo.dev/bare/installing-expo-modules/>
+
+---
+
+## Permissions
+
+### iOS — `Info.plist`
+
+```xml
+<key>NSCameraUsageDescription</key>
+<string>We need access to your camera to capture your ID document and run the liveness check.</string>
+
+<!-- Only when googleMapsApiKey is set -->
+<key>NSLocationWhenInUseUsageDescription</key>
+<string>We use your location to suggest your home address.</string>
+```
+
+With Expo, the Vision Camera and `expo-location` plugins inject these
+automatically from `app.json`.
+
+### Android — `AndroidManifest.xml`
+
+```xml
+<uses-permission android:name="android.permission.CAMERA" />
+
+<!-- Only when googleMapsApiKey is set -->
+<uses-permission android:name="android.permission.ACCESS_COARSE_LOCATION" />
+<uses-permission android:name="android.permission.ACCESS_FINE_LOCATION" />
+```
+
+With Expo, declare them in `app.json`:
+
+```jsonc
+{
+  "expo": {
+    "android": {
+      "permissions": [
+        "android.permission.CAMERA",
+        "android.permission.ACCESS_COARSE_LOCATION",
+        "android.permission.ACCESS_FINE_LOCATION"
+      ]
+    }
+  }
+}
+```
+
+---
+
+## Using the component
+
+```tsx
+import {
+  VelionOnboardingScreen,
+  type VelionConfig,
+  type OnboardingResult,
+  type SdkError,
+} from '@velion-la/onboarding-sdk-react-native';
+
+const config: VelionConfig = {
+  sessionId: '<sessionId from your backend>',
+  sessionToken: '<sessionToken from your backend>',
+  apiUrl: 'https://<your-host>/public/sdk',
+  locale: 'es',
+  colorMode: 'auto',
+  onSuccess: (result) => { /* flow completed */ },
+  onError: (err) => { /* flow failed */ },
+  onStepChange: (step, idx) => { /* analytics */ },
+  onStepComplete: (step) => { /* analytics */ },
+  onSessionEvent: (evt) => { /* raw SSE events */ },
+};
+
+<VelionOnboardingScreen
+  config={config}
+  onComplete={(result) => navigation.replace('Home')}
+  onFail={(err) => navigation.goBack()}
+/>
+```
+
+### Lifecycle
+
+| Event | When it fires |
+|---|---|
+| Mount | The SDK opens the session, connects SSE, and starts the first step. |
+| `onStepChange` | The orchestrator transitions into a new step. |
+| `onStepComplete` | The current step was successfully submitted. |
+| `onSessionEvent` | Every SSE event received (useful for debugging). |
+| `onSuccess` / `onComplete` | The flow finished: `APPROVED`, `MANUAL_REVIEW`, `REJECTED` or `DECLINED`. |
+| `onError` / `onFail` | Unrecoverable error (token expired, fatal network error, backend decline, …). |
+| Unmount | The SDK aborts in-flight requests, closes SSE, and releases the camera. |
+
+> Use the component props `onComplete` / `onFail` **or** the config callbacks
+> `onSuccess` / `onError`. Both do the same thing. The config callbacks are
+> exposed for imperative integrations as well.
+
+### Manual dismissal (modal usage)
+
+```tsx
+function KycModal({ visible, onClose }) {
+  return (
+    <Modal visible={visible} onRequestClose={onClose}>
+      <VelionOnboardingScreen config={config} onComplete={onClose} onFail={onClose} />
+    </Modal>
+  );
+}
+```
+
+When the modal unmounts, the SDK runs its internal cleanup automatically
+(aborts in-flight `fetch` calls, closes SSE, releases the camera).
+
+### Imperative usage (advanced)
+
+If you need to control the lifecycle outside React (custom navigation
+container, headless mode, etc.):
+
+```tsx
+import { VelionOnboarding } from '@velion-la/onboarding-sdk-react-native';
+
+const sdk = new VelionOnboarding(config);
+sdk.attachView({
+  setLoading:  (text) => /* show overlay */,
+  setStepNode: (node) => /* render the step UI */,
+  setError:    (err)  => /* show error */,
+  setResult:   (r)    => /* show result */,
+});
+await sdk.start();
+// …later:
+sdk.destroy();
+```
+
+`<VelionOnboardingScreen>` is a thin wrapper over this API.
+
+### Mount once per session
+
+`<VelionOnboardingScreen>` opens an SSE stream and drives a state machine on
+mount. If React unmounts and remounts the component, the SDK starts a fresh
+session, re-opens SSE, and discards in-memory progress. To avoid this:
+
+- Keep `config.sessionId` and `config.apiUrl` stable. The SDK uses them as
+  identity; changing either tears down the inner instance and starts over
+  (intentional, to support session rotation).
+- Don't declare component wrappers (Provider, layout, frame) inside the body
+  of your screen. A new function on each render is a new component type for
+  React and forces the entire subtree to unmount.
+- If your `config` includes dynamic callbacks, memoize it with `useMemo` or
+  stash the callbacks in a `useRef` to avoid identity churn.
+- Don't pass a `key` that changes per render.
+
+```tsx
+import { useMemo, useRef } from 'react';
+import { VelionOnboardingScreen } from '@velion-la/onboarding-sdk-react-native';
+
+export function KycScreen({ sessionId, sessionToken, navigation }) {
+  const navRef = useRef(navigation);
+  navRef.current = navigation;
+
+  const config = useMemo(
+    () => ({
+      sessionId,
+      sessionToken,
+      locale: 'es',
+      onSuccess: (result) => navRef.current.replace('Home', { kyc: result }),
+      onError: () => navRef.current.goBack(),
+    }),
+    [sessionId, sessionToken],
+  );
+
+  return <VelionOnboardingScreen config={config} />;
+}
+```
+
+Symptom of a misconfigured mount: repeated `[SSE] Opening stream` log lines
+every few hundred milliseconds, or the first step (typically
+`DEVICE_FINGERPRINT`) never completing.
+
+---
+
+## `VelionConfig`
+
+```ts
+interface VelionConfig {
+  // Session
+  sessionId: string;             // generated by your backend
+  sessionToken: string;          // bearer token for this session
+  apiUrl: string;                // base URL ending in `/public/sdk`
+  expiresAt?: string;            // ISO-8601, optional client-side check
+
+  // UI
+  locale?: 'es' | 'en';
+  colorMode?: 'light' | 'dark' | 'auto';
+  theme?: VelionTheme;
+  showProgressBar?: boolean;
+  showFinalResultScreen?: boolean;
+  finalResultScreenTexts?: VelionFinalResultScreenTexts;
+  sessionDeclinedReasonTexts?: VelionSessionDeclinedReasonTexts;
+
+  // Liveness
+  livenessShowIntro?: boolean;       // default true
+  livenessShowBackButton?: boolean;  // default true
+
+  // Address (assisted)
+  googleMapsApiKey?: string;
+
+  // Fingerprint
+  fingerprintEndpoint?: string;
+  fingerprintApiKey?: string;
+  fingerprintTimeoutMs?: number;
+
+  // Debug
+  debug?: boolean;
+
+  // Callbacks
+  onSuccess?:        (result: OnboardingResult) => void;
+  onError?:          (err: SdkError) => void;
+  onStepChange?:     (step: OnboardingStep, index: number) => void;
+  onStepComplete?:   (step: OnboardingStep) => void;
+  onSessionEvent?:   (event: OnboardingSessionEvent) => void;
+  onFinalResultScreenDismiss?: () => void;
+}
+```
+
+### Critical fields
+
+- **`apiUrl`** must be HTTPS (or `http://localhost:*` for development). The
+  SDK refuses insecure URLs so the `sessionToken` is never sent in cleartext.
+- **`sessionId` + `sessionToken`** are issued by your backend when the
+  session is created. The token is single-use for that session.
+- **`apiUrl`** must end with `/public/sdk`; all relative endpoints are
+  resolved against it.
+
+---
+
+## Callbacks
+
+```ts
+onSuccess: (result: OnboardingResult) => void;
+```
+
+```ts
+interface OnboardingResult {
+  sessionId: string;
+  completedAt: string;       // ISO-8601
+  status: 'APPROVED' | 'MANUAL_REVIEW' | 'REJECTED' | 'DECLINED';
+  referenceId?: string;      // for support / audit trail
+  terminalReason?: string;   // backend-supplied reason
+}
+```
+
+```ts
+onError: (err: SdkError) => void;
+```
+
+```ts
+interface SdkError {
+  code: SdkErrorCode;
+  message: string;
+  declineReason?: string;    // when code === SESSION_DECLINED
+  stepCode?: string;
+  declineTitle?: string;     // localized copy
+  declineMessage?: string;
+  cameraCode?: CameraErrorCode;
+  httpStatus?: number;
+  cause?: unknown;
+}
+```
+
+Possible `SdkErrorCode` values:
+
+| Code | When |
+|---|---|
+| `SESSION_INVALID` | Token rejected (403). |
+| `SESSION_EXPIRED` | Token expired (401) — request a fresh one. |
+| `SESSION_FETCH_FAILED` | Could not load the initial session. |
+| `SESSION_DECLINED` | Backend sent `SESSION_DECLINED` over SSE. |
+| `FINGERPRINT_FAILED` | Visitor id could not be generated. |
+| `DOCUMENT_UPLOAD_FAILED` | `PUT` to the signed URL or `verify` step failed. |
+| `LIVENESS_FAILED` | Liveness service closed the WebSocket with a terminal warning. |
+| `LIVENESS_INIT_FAILED` | `/liveness-init` failed. |
+| `CAMERA_ERROR` | Camera denied or unavailable. |
+| `NETWORK_ERROR` | Connectivity lost. |
+| `API_ERROR` | Backend returned 5xx or an unexpected response. |
+| `ALREADY_STARTED`, `INSTANCE_DESTROYED` | Lifecycle misuse. |
+| `UNKNOWN` | Anything else. |
+
+```ts
+onStepChange: (step: OnboardingStep, index: number) => void;
+```
+
+`step` is one of `'DEVICE_FINGERPRINT' | 'HUMAN_BASIC_INFO' | 'EMAIL_OTP' | …`
+(see [Supported steps](#supported-steps)).
+
+```ts
+onSessionEvent: (event: OnboardingSessionEvent) => void;
+```
+
+You receive every raw SSE event for analytics or debugging. The SDK already
+handles everything internally; this callback is optional.
+
+---
+
+## Theming
+
+```ts
+import type { VelionTheme } from '@velion-la/onboarding-sdk-react-native';
+
+const theme: VelionTheme = {
+  primaryColor: '#0052CC',
+  secondaryColor: '#1D4ED8',
+  backgroundColor: '#FFFFFF',
+  textColor: '#111827',
+  textSecondaryColor: '#6B7280',
+  errorColor: '#DC2626',
+  successColor: '#16A34A',
+  warningColor: '#D97706',
+  borderColor: '#E5E7EB',
+  borderRadius: '8px',
+  fontFamily: 'System',
+  hideStepIcons: false,    // hide the colored round icon next to step titles
+  hideProgressBar: false,  // hide the sticky top progress bar
+};
+```
+
+### Layout switches
+
+`VelionTheme` exposes two layout flags controlled alongside the visual theme:
+
+```tsx
+config={{
+  ...config,
+  theme: {
+    ...theme,
+    hideStepIcons: true,
+    hideProgressBar: true,
+  },
+}}
+```
+
+Equivalences:
+
+- `theme.hideProgressBar = true` and `config.showProgressBar = false` both
+  hide the bar.
+- `theme.hideStepIcons = true` hides the per-step icons (no equivalent in
+  `VelionConfig`; theme-only).
+
+### Step header icons
+
+Each step renders a themed icon (Material Icons) inside a circle of
+`primaryColor` next to the title. They come from `@expo/vector-icons`, which
+Expo SDK 54+ ships by default. In bare React Native projects without Expo,
+install it separately (`npm install @expo/vector-icons`) or enable
+`hideStepIcons` to skip the dependency.
+
+### Color mode
+
+```tsx
+<VelionOnboardingScreen
+  config={{ ...config, theme, colorMode: 'light' }}
+/>
+```
+
+With `colorMode: 'auto'` (default), the SDK follows `useColorScheme()` from
+the system. `'light'` or `'dark'` force the mode.
+
+If you pass a `theme` whose `backgroundColor` has the opposite luminance to
+the active `colorMode`, the SDK detects the conflict and switches its icons
+and SVGs to the correct tone. This avoids the case where
+`colorMode: 'light'` + `backgroundColor: '#0B1220'` leaves dark icons on a
+dark background.
+
+### Reduced motion
+
+The SDK honours `AccessibilityInfo.isReduceMotionEnabled()` automatically.
+There is nothing to configure — animations are disabled when the OS asks for
+reduced motion.
+
+---
+
+## Locales
+
+`locale: 'es' | 'en'`. Any other value falls back to `'es'`.
+
+To override specific copy (e.g. the final result screen for
+`SESSION_DECLINED`):
+
+```tsx
+config={{
+  ...config,
+  finalResultScreenTexts: {
+    approved: { title: 'Done!', message: 'Your account is active.' },
+    manualReview: { title: 'Under review', message: 'We will reach out within 24h.' },
+  },
+  sessionDeclinedReasonTexts: {
+    LIVENESS_FAILED: {
+      es: { title: 'No pudimos verificarte', message: 'Probá de nuevo con buena luz.' },
+      en: { title: 'We could not verify you', message: 'Please retry under good light.' },
+    },
+  },
+}}
+```
+
+---
+
+## Errors
+
+```tsx
+import { SdkErrorCode, CameraErrorCode } from '@velion-la/onboarding-sdk-react-native';
+
+onError: (err) => {
+  if (err.code === SdkErrorCode.SESSION_EXPIRED) {
+    refreshSessionToken().then((newConfig) => remountSdk(newConfig));
+    return;
+  }
+  if (err.code === SdkErrorCode.SESSION_DECLINED) {
+    // err.declineTitle / declineMessage already come localized
+    showDeclineScreen(err);
+    return;
+  }
+  if (err.code === SdkErrorCode.CAMERA_ERROR) {
+    if (err.cameraCode === CameraErrorCode.PERMISSION_DENIED) {
+      showCameraPermissionDialog();
+    }
+    return;
+  }
+  // Fallback
+  showRetry(err.message);
+};
+```
+
+---
+
+## Assisted address mode (map + search)
+
+`ADDRESS_INFO` has two modes:
+
+- **Manual** (default fallback): full structured form (country, state, city,
+  district, neighbourhood, street, number, postal code, floor, apartment,
+  references).
+- **Assisted**: fullscreen map with a floating search bar on top and a
+  floating "Next" button on the bottom. The user searches for their address
+  by typing, picks a suggestion, or drags the pin manually. On confirm, the
+  structured fields are filled automatically and `lat`/`lng` are added to
+  the payload.
+
+### Map provider per platform
+
+| Platform | Map provider | API key required? |
+|---|---|---|
+| **iOS** | Apple Maps (system) | **No.** No GCP setup, no `AirGoogleMaps` target, no extra plugin. |
+| **Android** | Google Maps SDK | **Yes.** Maps SDK for Android, application restriction `Android apps` + package + SHA-1. |
+
+### Geocoding and search — fully OS-native, no Google REST
+
+The SDK does **not** call Google's HTTP APIs (Geocoding / Places Web
+Service) from the client. Those APIs do not honour application restrictions
+(bundle ID / package + SHA-1), so a tightly restricted key would fail with
+`REQUEST_DENIED` on mobile. Instead:
+
+- **Reverse geocoding** (pin → street / number / postal code / city /
+  state / country) uses `expo-location.reverseGeocodeAsync`. On iOS that is
+  `CLGeocoder` (Apple Maps); on Android it is `android.location.Geocoder`
+  (Google Play Services on-device). No key, no quota, no external Google
+  network call.
+- **Search bar** uses `expo-location.geocodeAsync` with a 400 ms debounce,
+  plus a reverse-geocode fan-out on the top 5 candidates to build the
+  visible label ("Av. Corrientes 1234, CABA, Argentina"). Suggestions
+  appear when the user pauses typing.
+
+### When the assisted mode activates
+
+```
+1) Is `react-native-maps` linked?
+     no  → manual
+     yes → ↓
+2) Platform?
+     iOS     → assisted (Apple Maps, no key)
+     Android → is `googleMapsApiKey` set in VelionConfig?
+                 yes → assisted (Google Maps with that key)
+                 no  → manual (Android MapView without a key renders blank)
+3) Does the MapView throw at runtime?
+     yes → manual (an error boundary captures it and falls back)
+```
+
+In practice:
+
+- On **iOS** it is enough to have `react-native-maps` installed.
+  `googleMapsApiKey` can be omitted.
+- On **Android** you need `googleMapsApiKey` in `VelionConfig` **and** the
+  same key declared in `AndroidManifest.xml` (Expo handles this via
+  `app.config.js` → `android.config.googleMaps.apiKey`). Google Maps SDK
+  reads the key from the manifest, not from JS, so both places are required.
+
+### Google Cloud setup (Android only)
+
+If you want assisted mode on Android:
+
+1. Enable **`Maps SDK for Android`** on your GCP project.
+2. **Application restriction**: `Android apps`. Add your package name plus
+   the SHA-1 fingerprint of the signing certificate. For debug builds:
+   ```bash
+   cd example/android && ./gradlew signingReport
+   # look for "Variant: debug" → SHA1
+   ```
+3. **API restriction**: restrict the key to `Maps SDK for Android` (do not
+   leave it as "Don't restrict key").
+4. **Billing enabled** on the GCP project (required even for the free tier).
+
+### Extra permissions (assisted mode only)
+
+- iOS: `NSLocationWhenInUseUsageDescription`.
+- Android: `ACCESS_COARSE_LOCATION` + `ACCESS_FINE_LOCATION`.
+
+If the user rejects location, the map opens at a default centre and the
+user can move the pin or use the search bar — the flow is not broken.
+
+### Automatic fallback when something fails
+
+When mounting `ADDRESS_INFO`, the SDK checks:
+
+1. That `react-native-maps` is importable. If not → manual.
+2. On Android, that `googleMapsApiKey` is in `VelionConfig`. If not →
+   manual. Additionally, when `expo-constants` is available, the SDK checks
+   that the same key is declared in the Expo config; otherwise the
+   `MapView` would crash natively. If missing → manual with an
+   `[address]` warning explaining the fix.
+3. The `<MapAddressPicker>` is wrapped in an error boundary that catches a
+   throwing `MapView` at runtime (typical example: `AirGoogleMaps dir must
+   be added` on iOS if someone forces `provider="google"`). If it fires →
+   manual.
+
+In every fallback path the SDK logs a warning prefixed with `[address]` and
+renders the manual form. The user keeps completing the address, just
+without `lat`/`lng`.
+
+---
+
+## Supported steps
+
+| Step | Backend endpoint | UI |
+|---|---|---|
+| `DEVICE_FINGERPRINT` | `POST /sessions/:id/fingerprint` | Loading overlay |
+| `HUMAN_BASIC_INFO` | `POST /basic-info/human` | Form |
+| `LEGAL_BASIC_INFO` | `POST /basic-info/legal` | Form |
+| `HUMAN_EXTENDED_INFO` | `POST /extended-info/human` | Form (fields per `stepConfig`) |
+| `LEGAL_EXTENDED_INFO` | `POST /extended-info/legal` | Form (date + country) |
+| `EMAIL_CONTACT` | `POST /contact/email` | Form |
+| `PHONE_CONTACT` | `POST /contact/phone` | Form (E.164) |
+| `EMAIL_OTP` | `POST /email/send-otp` + `verify-otp` | Two-stage form |
+| `PHONE_OTP` | `POST /phone/send-otp` + `verify-otp` | Two-stage form |
+| `TAX_INFO` | `POST /tax-info` | Form (selects from `stepConfig`) |
+| `SWORN_DECLARATION` | `POST /sworn-declaration` | Cards with checkbox |
+| `TERMS_AND_CONDITIONS` | `POST /terms-and-conditions` | Checkbox list + link |
+| `ADDRESS_INFO` | `POST /address-info` | Manual or assisted (Maps) |
+| `DOCUMENTS_OCR` | `POST /documents-init` + `PUT` × 2 + `verify` | Camera + intro tips |
+| `LIVENESS_MATCH` | `POST /liveness-init` + WebSocket + `verify` | Front camera + oval mask |
+| `FACE_MATCH` | (backend-only, no POST) | Loading + poll |
+
+The order is determined dynamically by the backend via `current_step` and
+the SSE `ROUTING_COMMAND` events. The SDK does no client-side routing.
+
+---
+
+## Stack and architecture
+
+```
+┌─────────────────────────────────────────────────────────────────────────┐
+│                  <VelionOnboardingScreen config />                      │
+│  ┌──────────────────────────────────────────────────────────────────┐   │
+│  │  ThemeProvider                                                   │   │
+│  │  ┌────────────────────────────────────────────────────────────┐  │   │
+│  │  │  ProgressBar (sticky top)                                  │  │   │
+│  │  │  ┌──────────────────────────────────────────────────────┐  │  │   │
+│  │  │  │           Step slot (driven by orchestrator)         │  │  │   │
+│  │  │  │  HumanBasicInfo / EmailOtp / Documents / Liveness…   │  │  │   │
+│  │  │  └──────────────────────────────────────────────────────┘  │  │   │
+│  │  │  LoadingOverlay / RetryDialog                              │  │   │
+│  │  └────────────────────────────────────────────────────────────┘  │   │
+│  └──────────────────────────────────────────────────────────────────┘   │
+└────────────────────────────┬────────────────────────────────────────────┘
+                             │
+              VelionOnboarding (orchestrator, plain TS)
+                             │
+        ┌────────────────────┼────────────────────────────┐
+        │                    │                            │
+   ApiCaller (fetch)    SSE (react-native-sse)    Liveness WS (binary + HMAC)
+```
+
+- **Types**: shipped inside the package (`lib/typescript/`). They mirror
+  the Onboarding backend contract.
+- **Build**: `react-native-builder-bob` emits CommonJS, ESM and TypeScript
+  declarations.
+- **No `Buffer`**: base64 helpers use `btoa` / `atob` globals (Hermes-
+  compatible).
+- **HMAC-SHA256**: pure JavaScript via `@noble/hashes`, no native bridge.
+
+---
+
+## Local development
+
+```bash
+git clone <repo>
+cd onboarding-sdk-react-native
+npm install
+npm run typecheck            # both workspaces
+npm run build                # build the SDK with bob → sdk/lib/
+
+# Demo on a simulator (vision-camera requires prebuild, no Expo Go)
+npm run prebuild
+npm run ios                  # or npm run android
+```
+
+The `example/` app consumes the SDK by path resolution (via the
+`react-native` field in `package.json`); there is no need for `npm link` or
+`npm pack` while iterating.
+
+---
+
+## Publishing
+
+```bash
+cd sdk
+
+# 1. Inspect what would be published
+npm pack --dry-run
+
+# 2. Publish
+npm publish
+```
+
+The `prepare` script runs `bob build` automatically, so a fresh build is
+guaranteed before publishing.
+
+To bump the version:
+
+```bash
+cd sdk
+npm version patch    # or minor / major
+```
+
+---
+
+## License
+
+Proprietary. This package is distributed under a commercial agreement with
+Velion. Contact `dev@velion.la` for licensing terms.