react-native-usesense 1.0.0 → 2.1.0

package/lib/typescript/src/index.d.ts

@@ -1,196 +1,268 @@
-/** Environment for the UseSense API. */
-export type UseSenseEnvironment = 'production' | 'sandbox';
-/** Session type for verification. */
+/**
+ * Target environment for the UseSense API. `auto` asks the native SDK
+ * to detect from the API key prefix (`sk_sandbox_*` → sandbox,
+ * `sk_prod_*` → production).
+ */
+export type UseSenseEnvironment = 'sandbox' | 'production' | 'auto';
+/** Type of verification session. */
 export type SessionType = 'enrollment' | 'authentication';
-/** Challenge policy controlling verification difficulty. */
-export type ChallengePolicy = 'standard' | 'enhanced' | 'adaptive';
-/** Decision returned by the verification engine. */
-export type UseSenseDecision = 'approved' | 'rejected' | 'manual_review';
-/** Processing stage during server-side analysis. */
-export type ProcessingStage = 'deepsense' | 'livesense' | 'matchsense' | 'fusion';
 /**
- * Configuration for initializing the UseSense plugin.
+ * Decision returned by the native SDK.
  *
- * @example
- * ```ts
- * await UseSense.initialize({
- *   apiKey: 'your_api_key',
- *   environment: 'sandbox',
- * });
- * ```
+ * These values come straight from the server's verdict and are
+ * exposed to the integrator for UI feedback only. The definitive
+ * verdict arrives at your backend via an HMAC-signed webhook; never
+ * trust the client-side decision for access-control.
+ */
+export type Decision = 'APPROVE' | 'REJECT' | 'MANUAL_REVIEW';
+/**
+ * Branding overrides applied to the native camera UI.
+ *
+ * - `logoUrl`, `primaryColor`, `buttonRadius`, `fontFamily` are
+ *   honoured on both iOS and Android.
+ * - `displayName`, `redirectUrl` are Android-only fields. They're
+ *   accepted on iOS for cross-platform API parity but ignored.
+ */
+export interface BrandingConfig {
+    logoUrl?: string;
+    primaryColor?: string;
+    buttonRadius?: number;
+    fontFamily?: string;
+    displayName?: string;
+    redirectUrl?: string;
+}
+/**
+ * Configuration for `UseSense.initialize`. The minimum required
+ * field is the API key; every other field has a sensible default.
  */
 export interface UseSenseConfig {
-    /** API key from the UseSense dashboard. */
+    /** API key from watchtower.usesense.ai. */
     apiKey: string;
-    /** Target environment. Defaults to `'sandbox'`. */
+    /** Target environment. Defaults to `auto` (detected from key prefix). */
     environment?: UseSenseEnvironment;
-    /** Your organization ID (optional, inferred from API key). */
-    organizationId?: string;
-    /** Default session type. Defaults to `'enrollment'`. */
-    sessionType?: SessionType;
-    /** Identity ID for authentication sessions. */
+    /**
+     * Override the API endpoint. Defaults to `https://api.usesense.ai/v1`.
+     * Only set this if you're pointing at a staging or self-hosted
+     * proxy. Maps to `apiEndpoint` on iOS and `baseUrl` on Android
+     * under the hood.
+     */
+    apiEndpoint?: string;
+    /** SDK-level branding overrides. */
+    branding?: BrandingConfig;
+    /**
+     * Opt in to the on-device antispoof classifier (v4.2). When enabled the
+     * native layer runs the bundled CelebA-Spoof model during capture and
+     * attaches per-frame spoof probabilities to the uploaded metadata. When
+     * disabled (default), the watchtower backend runs the classifier server-side.
+     * See `docs/sdk-specs/antispoof-classifier-sdk-spec.md` in the watchtower
+     * repo for the rollout plan and crosscheck policy.
+     */
+    antispoofOnDeviceEnabled?: boolean;
+    /**
+     * Opt the session into the LiveSense v4 capture flow. When true the native
+     * layer:
+     *   - sends `x-usesense-sdk-version: v4` on session creation
+     *   - inserts a constitutive zoom-motion phase between baseline and the
+     *     active challenge (additive, not a replacement)
+     *   - tags every captured frame with its capture phase
+     * The org must also have `livesense_v4_enabled` set in its features map
+     * server-side.
+     */
+    liveSenseV4Enabled?: boolean;
+}
+/**
+ * Request to start a verification session.
+ */
+export interface VerificationRequest {
+    sessionType: SessionType;
+    /** Your internal user identifier (optional, stored in session metadata). */
+    externalUserId?: string;
+    /**
+     * Required for `authentication` sessions. The previously-enrolled
+     * identity you're verifying against.
+     */
     identityId?: string;
-    /** Challenge difficulty policy. Defaults to `'standard'`. */
-    challengePolicy?: ChallengePolicy;
-    /** Enable audio capture for voice deepfake detection. Defaults to `false`. */
-    enableAudio?: boolean;
-    /** Maximum session duration in milliseconds. Defaults to `60000`. */
-    timeout?: number;
     /** Custom key-value pairs attached to the session. */
-    metadata?: Record<string, string>;
+    metadata?: Record<string, string | number | boolean>;
 }
 /**
- * Result returned when a verification session completes.
+ * Redacted decision object returned when a session completes.
  *
- * **Important:** This result is for UI feedback only.
- * The definitive verdict arrives at your backend via HMAC-signed webhook.
+ * This is the ONLY shape the plugin exposes to React Native. Pillar
+ * scores (channel trust, liveness, matchsense risk) are intentionally
+ * not included — the native SDKs strip those fields before returning
+ * across the bridge to prevent reverse-engineering of the server-side
+ * scoring logic. If you need full scoring details, consume the signed
+ * webhook delivered to your backend.
  */
 export interface UseSenseResult {
-    /** Unique session identifier. */
     sessionId: string;
-    /** Verification decision. */
-    decision: UseSenseDecision;
-    /** DeepSense channel trust score (0-100). */
-    channelTrustScore: number;
-    /** LiveSense liveness score (0-100). */
-    livenessScore: number;
-    /** MatchSense risk score (0-100). Lower is better. */
-    matchSenseRiskScore: number;
-    /** Fused presence confidence score (0-100). */
-    presenceConfidence: number;
-    /** Reasons contributing to the decision. */
-    reasons: string[];
-    /** Rule that triggered the decision, if any. */
-    ruleTriggered?: string;
-    /** Recommended action for the integrator. */
-    recommendedAction?: string;
-    /** Cryptographic signature for result verification. */
-    sessionSignature: string;
+    sessionType: string | null;
+    identityId: string | null;
+    decision: Decision;
+    timestamp: string;
+    /** Convenience: `decision === 'APPROVE'`. */
+    isApproved: boolean;
+    /** Convenience: `decision === 'REJECT'`. */
+    isRejected: boolean;
+    /** Convenience: `decision === 'MANUAL_REVIEW'`. */
+    isPendingReview: boolean;
 }
 /**
- * Error returned when a verification session fails.
+ * Error thrown when a verification session fails.
+ *
+ * Matches the native SDKs' error shape: machine-readable code,
+ * human-readable message, retry hint.
  */
 export interface UseSenseError {
-    /** Machine-readable error code. */
+    /**
+     * Machine-readable error code. One of
+     * `CAMERA_UNAVAILABLE`, `CAMERA_PERMISSION_DENIED`,
+     * `MIC_PERMISSION_DENIED`, `NETWORK_ERROR`, `NETWORK_TIMEOUT`,
+     * `SESSION_EXPIRED`, `UNAUTHORIZED`, `INVALID_TOKEN`,
+     * `SESSION_NOT_FOUND`, `IDENTITY_NOT_FOUND`, `INVALID_REQUEST`,
+     * `INVALID_CONFIG`, `QUOTA_EXCEEDED`, `USER_CANCELLED`,
+     * `session_cancelled`, `sdk_not_initialized`, `no_view_controller`,
+     * `CAPTURE_FAILED`, `ENCODING_FAILED`, `UPLOAD_FAILED`,
+     * `FACE_NOT_DETECTED`, `LOW_LIGHT`, `TIMEOUT`, `SERVER_ERROR`,
+     * `SERVICE_UNAVAILABLE`, `TOKEN_EXPIRED`, `TOKEN_ALREADY_USED`,
+     * `INSUFFICIENT_CREDITS`, `NONCE_MISMATCH`, `UNKNOWN_ERROR`.
+     */
     code: string;
     /** Human-readable error message. */
     message: string;
-    /** Additional error details. */
-    details?: Record<string, any>;
+    /** Whether the operation can be retried. */
+    isRetryable?: boolean;
+    /** Server-specific error code, if any. */
+    serverCode?: string;
 }
 /**
- * Events emitted during the verification session lifecycle.
+ * Lifecycle event types emitted by the native SDK during a
+ * verification session.
  */
-export type UseSenseEvent = {
-    type: 'session_started';
-    sessionId: string;
-} | {
-    type: 'challenge_presented';
-    challengeType: string;
-} | {
-    type: 'challenge_completed';
-    challengeType: string;
-} | {
-    type: 'processing';
-    stage: ProcessingStage;
-} | {
-    type: 'session_completed';
-    result: UseSenseResult;
-} | {
-    type: 'session_error';
-    error: UseSenseError;
-};
-/** Options for starting a verification session. */
-export interface StartSessionOptions {
-    /** Session type. Overrides the value set in {@link UseSenseConfig}. */
-    sessionType?: SessionType;
-    /** Identity ID for authentication sessions. */
-    identityId?: string;
+export type UseSenseEventType = 'SESSION_CREATED' | 'PERMISSIONS_REQUESTED' | 'PERMISSIONS_GRANTED' | 'PERMISSIONS_DENIED' | 'CAPTURE_STARTED' | 'FRAME_CAPTURED' | 'CAPTURE_COMPLETED' | 'AUDIO_RECORD_STARTED' | 'AUDIO_RECORD_COMPLETED' | 'CHALLENGE_STARTED' | 'CHALLENGE_COMPLETED' | 'UPLOAD_STARTED' | 'UPLOAD_PROGRESS' | 'UPLOAD_COMPLETED' | 'COMPLETE_STARTED' | 'DECISION_RECEIVED' | 'IMAGE_QUALITY_CHECK' | 'ERROR' | 'UNKNOWN';
+/** Single event emitted during a session. */
+export interface UseSenseEvent {
+    type: UseSenseEventType;
+    /** Unix epoch milliseconds. */
+    timestamp: number;
+    /** Event-specific payload. Opaque strings; never contains scoring data. */
+    data?: Record<string, string>;
 }
-/** Status of a verification session. */
-export interface SessionStatus {
-    /** Current session status. */
-    status: string;
-    /** Result, if the session has completed. */
-    result?: UseSenseResult;
-}
-/** Subscription handle returned by {@link UseSense.addListener}. */
+/** Handle returned by `UseSense.addListener`. */
 export interface UseSenseSubscription {
-    /** Remove the event listener. */
-    remove: () => void;
+    remove(): void;
 }
 /**
  * UseSense React Native plugin.
  *
- * Provides human presence verification by wrapping the native UseSense
- * iOS and Android SDKs into a single cross-platform API.
+ * Human presence verification wrapping the native iOS and Android
+ * UseSense SDKs. Every session runs inside a full-screen native
+ * camera activity; the plugin is a thin bridge that forwards
+ * initialization, verification requests, and lifecycle events to
+ * the platform SDK and returns a redacted decision object.
  *
  * @example
  * ```ts
  * import { UseSense } from 'react-native-usesense';
  *
- * await UseSense.initialize({ apiKey: 'your_key', environment: 'sandbox' });
- * const result = await UseSense.startSession({ sessionType: 'enrollment' });
- * console.log(result.decision);
+ * await UseSense.initialize({
+ *   apiKey: 'sk_sandbox_...',
+ *   environment: 'sandbox',
+ * });
+ *
+ * const unsubscribe = UseSense.addListener((event) => {
+ *   console.log(event.type, event.data);
+ * });
+ *
+ * try {
+ *   const result = await UseSense.startVerification({
+ *     sessionType: 'enrollment',
+ *   });
+ *   console.log(result.decision); // 'APPROVE' | 'REJECT' | 'MANUAL_REVIEW'
+ * } finally {
+ *   unsubscribe.remove();
+ * }
  * ```
  */
 export declare class UseSense {
     /**
-     * Initialize the UseSense plugin. Must be called once before any other method.
+     * Initialize the UseSense plugin. Must be called before any other
+     * method. Calling again with a different API key or environment
+     * replaces the previous configuration.
      *
-     * @param config - Plugin configuration including API key and environment.
-     * @throws {UseSenseError} If the API key is invalid or configuration is malformed.
+     * @throws {UseSenseError} If the API key is empty or initialization
+     * fails on the native side.
      */
     static initialize(config: UseSenseConfig): Promise<void>;
     /**
-     * Start a verification session. Presents a full-screen native camera UI.
-     *
-     * The returned promise resolves when the session completes and the modal
-     * dismisses, or rejects if an error occurs.
-     *
-     * @param options - Optional overrides for session type and identity ID.
-     * @returns The verification result (for UI feedback only).
-     * @throws {UseSenseError} On failure or cancellation.
+     * Start a verification session. Presents a full-screen native
+     * camera activity. The returned promise resolves when the session
+     * completes or rejects with a `UseSenseError` (including the
+     * `USER_CANCELLED` / `session_cancelled` cases when the user
+     * dismisses the camera screen).
      */
-    static startSession(options?: StartSessionOptions): Promise<UseSenseResult>;
+    static startVerification(request: VerificationRequest): Promise<UseSenseResult>;
     /**
-     * Cancel an in-progress verification session.
+     * Subscribe to real-time lifecycle events emitted by the native
+     * SDK during a verification session. Call this **before**
+     * `startVerification` so the subscription captures the earliest
+     * events (`SESSION_CREATED`, `PERMISSIONS_REQUESTED`).
      *
-     * The camera UI is dismissed and the `startSession` promise rejects
-     * with a `session_cancelled` error.
+     * Returns a subscription handle; call `.remove()` to stop
+     * receiving events.
      */
-    static cancelSession(): Promise<void>;
+    static addListener(callback: (event: UseSenseEvent) => void): UseSenseSubscription;
     /**
-     * Get the status of a verification session by ID.
-     *
-     * @param sessionId - The session ID to query.
-     * @returns The current status and optional result.
+     * Clear all event listeners and release native resources. Does not
+     * need to be called explicitly during normal usage; the plugin
+     * cleans up on process teardown. Useful when you want to re-
+     * initialize against a different API key or during test teardown.
      */
-    static getSessionStatus(sessionId: string): Promise<SessionStatus>;
+    static reset(): Promise<void>;
     /**
-     * Subscribe to real-time events during the verification lifecycle.
-     *
-     * Call this before `startSession()` to receive all events.
-     *
-     * @param callback - Function invoked for each event.
-     * @returns A subscription handle with a `remove()` method.
-     *
-     * @example
-     * ```ts
-     * const listener = UseSense.addListener((event) => {
-     *   console.log(event.type);
-     * });
-     * // Later:
-     * listener.remove();
-     * ```
+     * Whether the native plugin has an active `UseSense` client. Set
+     * to `true` after a successful `initialize` and `false` after
+     * `reset`. Useful for feature-flagging UI that should only show
+     * when the SDK is ready.
      */
-    static addListener(callback: (event: UseSenseEvent) => void): UseSenseSubscription;
+    static isInitialized(): Promise<boolean>;
     /**
-     * Get the native SDK version string.
+     * Start a LiveSense v4 session.
      *
-     * @returns Version string in semver format (e.g. `"1.0.0"`).
+     * The session must already have been created on your backend and the
+     * session_token + nonce forwarded to the client. The native SDK drives
+     * the camera, signs the frame hash chain with the platform-attested
+     * key, uploads, and returns the opaque verdict.
      */
-    static getSdkVersion(): string;
+    static startV4Verification(request: V4VerificationRequest): Promise<V4Verdict>;
+}
+export interface V4VerificationRequest {
+    sessionId: string;
+    sessionToken: string;
+    nonce: string;
+    apiBaseUrl: string;
+    environment?: UseSenseEnvironment;
+    displayName?: string;
+    brandPrimaryColor?: string;
+}
+export type V4Decision = 'pass' | 'fail' | 'review';
+export type V4Confidence = 'high' | 'medium' | 'low';
+export type V4AssuranceLevel = 'mobile_hardware' | 'web_attested' | 'web_unattested';
+export type V4CaptureChannel = 'ios' | 'android' | 'rn' | 'flutter' | 'web';
+/**
+ * Opaque verdict from POST /v1/sessions/:id/result. Matches the server
+ * contract exactly; no sub-scores leak through.
+ */
+export interface V4Verdict {
+    session_id: string;
+    verdict: V4Decision;
+    confidence: V4Confidence;
+    assurance_level_achieved: V4AssuranceLevel;
+    capture_channel: V4CaptureChannel;
+    match_sense_embedding_id: string | null;
+    timestamp: string;
 }
 export default UseSense;
+export { UseSenseFlows, FlowError, type FlowErrorCode, type FlowOutcome, type FlowRunResult, type FlowRunState, type RunFlowOptions, } from './flows';
 //# sourceMappingURL=index.d.ts.map

package/lib/typescript/src/index.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"index.d.ts","sourceRoot":"","sources":["../../../src/index.ts"],"names":[],"mappings":"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"}
+{"version":3,"file":"index.d.ts","sourceRoot":"","sources":["../../../src/index.ts"],"names":[],"mappings":"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"}

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "react-native-usesense",
-  "version": "1.0.0",
+  "version": "2.1.0",
   "description": "React Native plugin for human presence verification. Wraps the native UseSense iOS and Android SDKs.",
   "main": "lib/commonjs/index.js",
   "module": "lib/module/index.js",
@@ -60,6 +60,7 @@
     "react-native": ">=0.73.0"
   },
   "devDependencies": {
+    "@types/jest": "^29.5.14",
     "@types/react": "^18.2.0",
     "@typescript-eslint/eslint-plugin": "^7.0.0",
     "@typescript-eslint/parser": "^7.0.0",
@@ -69,6 +70,7 @@
     "react": "^18.2.0",
     "react-native": "^0.73.0",
     "react-native-builder-bob": "^0.23.0",
+    "ts-jest": "^29.4.11",
     "typescript": "^5.3.0"
   },
   "codegenConfig": {

package/react-native-usesense.podspec

@@ -11,7 +11,9 @@ Pod::Spec.new do |s|
   s.authors      = { "UseSense Technologies Ltd." => "support@usesense.ai" }
   s.source       = { :git => package["repository"]["url"], :tag => "v#{s.version}" }
 
-  s.platforms    = { :ios => "14.0" }
+  # Minimum iOS 15.0 to match the native UseSense iOS SDK's floor
+  # (v4.x uses SwiftUI features that require iOS 15.0 and up).
+  s.platforms    = { :ios => "15.0" }
   s.swift_version = "5.9"
 
   s.source_files = "ios/**/*.{swift,h,m}"
@@ -19,6 +21,10 @@ Pod::Spec.new do |s|
   # React Native dependency (supports both old and new architecture)
   install_modules_dependencies(s)
 
-  # Native UseSense iOS SDK
-  s.dependency "UseSenseSDK", "~> 1.0"
+  # Native UseSense iOS SDK. Minimum 4.2.2 — earlier 4.x releases had
+  # terminal-screen centering bugs, and the 1.x series used a pre-
+  # redaction result type with a completely different UseSenseConfig
+  # init signature. See CHANGELOG [2.0.0] for the full rewrite
+  # rationale.
+  s.dependency "UseSenseSDK", "~> 4.3"
 end

package/src/flows.ts

@@ -0,0 +1,159 @@
+/**
+ * React Native wrapper for the UseSense Flows runner.
+ *
+ * Coexists with the existing Sessions API (`UseSense.startSession`, etc.);
+ * this is a parallel surface, not a replacement. See `guides/flows/sessions-vs-flows`
+ * in the API docs for when to use which.
+ *
+ * Usage:
+ *
+ *   import { UseSenseFlows, FlowError } from 'react-native-usesense';
+ *
+ *   try {
+ *     const result = await UseSenseFlows.runFlow({ flowRunId, sdkToken });
+ *     console.log(result.outcome); // 'APPROVE' | 'REJECT' | 'MANUAL_REVIEW' | null
+ *   } catch (e) {
+ *     if (e instanceof FlowError) {
+ *       // e.code: 'token_expired' | 'token_invalid' | ...
+ *     }
+ *   }
+ */
+
+import { NativeModules, Platform } from 'react-native';
+
+const LINKING_ERROR =
+  `react-native-usesense (flows): the native module could not be found.\n\n` +
+  Platform.select({
+    ios: `iOS: run \`cd ios && pod install\` and rebuild the app.`,
+    android: `Android: rebuild the app after installing the package.`,
+    default: '',
+  });
+
+// Lazy lookup so this module doesn't throw at import time on platforms that
+// haven't been re-linked yet. The Sessions module mirrors this pattern.
+function nativeModule() {
+  const m = NativeModules.UseSenseFlowsModule;
+  if (!m) throw new Error(LINKING_ERROR);
+  return m as { runFlow: (flowRunId: string, sdkToken: string, apiBaseUrl: string | null) => Promise<NativeFlowRunResult> };
+}
+
+/**
+ * Server-driven flow run state. Host apps see only the terminal ones via
+ * `FlowRunResult`; intermediate states drive the runner internally.
+ */
+export type FlowRunState =
+  | 'pending'
+  | 'in_progress'
+  | 'stalled'
+  | 'awaiting_review'
+  | 'completed'
+  | 'errored'
+  | 'abandoned'
+  | 'cancelled';
+
+/** Terminal outcome of a flow run. */
+export type FlowOutcome = 'APPROVE' | 'REJECT' | 'MANUAL_REVIEW';
+
+/**
+ * Uniform error taxonomy across every SDK. See `guides/flows/errors` in the
+ * API docs for per-code recovery patterns.
+ */
+export type FlowErrorCode =
+  | 'token_expired'
+  | 'token_invalid'
+  | 'network_unavailable'
+  | 'permission_denied'
+  | 'provider_unavailable'
+  | 'cancelled'
+  | 'unsupported_action'
+  /** Server form validation failed. The native runner handles this inline
+   *  (per-field highlights) and never reports terminal — but if a host app
+   *  drives advance() outside the runner, the 422 surfaces with this code. */
+  | 'invalid_input'
+  | 'unknown';
+
+const FLOW_ERROR_CODES: readonly FlowErrorCode[] = [
+  'token_expired',
+  'token_invalid',
+  'network_unavailable',
+  'permission_denied',
+  'provider_unavailable',
+  'cancelled',
+  'unsupported_action',
+  'invalid_input',
+  'unknown',
+] as const;
+
+function normaliseCode(code: unknown): FlowErrorCode {
+  return typeof code === 'string' && (FLOW_ERROR_CODES as readonly string[]).includes(code)
+    ? (code as FlowErrorCode)
+    : 'unknown';
+}
+
+/** Result returned to the host app's `runFlow` promise on terminal state. */
+export interface FlowRunResult {
+  flowRunId: string;
+  state: FlowRunState;
+  outcome: FlowOutcome | null;
+}
+
+interface NativeFlowRunResult {
+  flowRunId: string;
+  state: FlowRunState;
+  outcome: FlowOutcome | null;
+}
+
+/**
+ * Typed error thrown by `runFlow` when the native runner reports a failure.
+ * Mirrors the web / iOS / Android / Flutter SDKs so host apps catch one
+ * taxonomy regardless of platform.
+ */
+export class FlowError extends Error {
+  readonly code: FlowErrorCode;
+  constructor(code: FlowErrorCode, message: string) {
+    super(message);
+    this.name = 'FlowError';
+    this.code = code;
+  }
+}
+
+/** Options for `UseSenseFlows.runFlow`. */
+export interface RunFlowOptions {
+  flowRunId: string;
+  sdkToken: string;
+  /** Defaults to `https://api.usesense.ai`. */
+  apiBaseUrl?: string;
+}
+
+/**
+ * Public entry point for the Flows runner. Sessions APIs are untouched;
+ * this is a parallel namespace.
+ */
+export const UseSenseFlows = {
+  /**
+   * Run an operator-authored Flow inside the host app. Resolves with a
+   * [FlowRunResult] when the run reaches a terminal state (completed,
+   * cancelled, errored, abandoned). Rejects with a [FlowError] on transport
+   * / token / unsupported-action faults.
+   */
+  async runFlow(options: RunFlowOptions): Promise<FlowRunResult> {
+    try {
+      const native = await nativeModule().runFlow(
+        options.flowRunId,
+        options.sdkToken,
+        options.apiBaseUrl ?? null,
+      );
+      return {
+        flowRunId: native.flowRunId,
+        state: native.state,
+        outcome: native.outcome,
+      };
+    } catch (e) {
+      // RN bridge errors are surfaced as `Error` with `.code` and `.message`
+      // properties when the native side calls `reject(code, message, null)`.
+      const code = normaliseCode((e as { code?: string }).code);
+      const message = (e as { message?: string }).message ?? 'Flow failed';
+      throw new FlowError(code, message);
+    }
+  },
+};