react-native-usesense 1.0.0 → 2.1.0

package/lib/module/index.js

@@ -1,172 +1,235 @@
-import { NativeModules, NativeEventEmitter } from 'react-native';
-const {
-  UseSenseModule
-} = NativeModules;
+import { NativeModules, NativeEventEmitter, Platform } from 'react-native';
+const LINKING_ERROR = `react-native-usesense: 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: ''
+}) + `\n\nIf you're using Expo, the plugin must be consumed through a development build; it does not support Expo Go because it wraps a native camera SDK.`;
+const UseSenseModule = NativeModules.UseSenseModule;
 if (!UseSenseModule) {
-  throw new Error('react-native-usesense: NativeModule not found. Make sure you have linked the library correctly.\n' + 'iOS: Run `cd ios && pod install`\n' + 'Android: Rebuild the app after installing the package.');
+  throw new Error(LINKING_ERROR);
 }
 
-// ─── Types ───────────────────────────────────────────────────────────
+// ─── Types ───────────────────────────────────────────────────────────────
 
-/** Environment for the UseSense API. */
+/**
+ * Target environment for the UseSense API. `auto` asks the native SDK
+ * to detect from the API key prefix (`sk_sandbox_*` → sandbox,
+ * `sk_prod_*` → production).
+ */
 
-/** Session type for verification. */
+/** Type of verification session. */
 
-/** Challenge policy controlling verification difficulty. */
+/**
+ * Decision returned by the native SDK.
+ *
+ * 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.
+ */
 
-/** Decision returned by the verification engine. */
+/**
+ * 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.
+ */
 
-/** Processing stage during server-side analysis. */
+/**
+ * Configuration for `UseSense.initialize`. The minimum required
+ * field is the API key; every other field has a sensible default.
+ */
 
 /**
- * Configuration for initializing the UseSense plugin.
- *
- * @example
- * ```ts
- * await UseSense.initialize({
- *   apiKey: 'your_api_key',
- *   environment: 'sandbox',
- * });
- * ```
+ * Request to start a verification session.
  */
 
 /**
- * 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.
  */
 
 /**
- * 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.
  */
 
 /**
- * Events emitted during the verification session lifecycle.
+ * Lifecycle event types emitted by the native SDK during a
+ * verification session.
  */
 
-/** Options for starting a verification session. */
+/** Single event emitted during a session. */
 
-/** Status of a verification session. */
+/** Handle returned by `UseSense.addListener`. */
 
-/** Subscription handle returned by {@link UseSense.addListener}. */
-
-// ─── Implementation ──────────────────────────────────────────────────
+// ─── Implementation ──────────────────────────────────────────────────────
 
 const eventEmitter = new NativeEventEmitter(UseSenseModule);
 
 /**
  * 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 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 async initialize(config) {
     if (!config.apiKey) {
-      throw {
+      const err = {
         code: 'invalid_config',
-        message: 'apiKey is required'
+        message: 'apiKey is required',
+        isRetryable: false
       };
+      throw err;
     }
     return UseSenseModule.initialize({
       apiKey: config.apiKey,
-      environment: config.environment ?? 'sandbox',
-      organizationId: config.organizationId,
-      sessionType: config.sessionType ?? 'enrollment',
-      identityId: config.identityId,
-      challengePolicy: config.challengePolicy ?? 'standard',
-      enableAudio: config.enableAudio ?? false,
-      timeout: config.timeout ?? 60000,
-      metadata: config.metadata
+      environment: config.environment ?? 'auto',
+      apiEndpoint: config.apiEndpoint,
+      branding: config.branding,
+      antispoofOnDeviceEnabled: config.antispoofOnDeviceEnabled ?? false,
+      liveSenseV4Enabled: config.liveSenseV4Enabled ?? false
     });
   }
 
   /**
-   * 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 async startSession(options) {
-    return UseSenseModule.startSession(options ?? {});
+  static async startVerification(request) {
+    return UseSenseModule.startVerification({
+      sessionType: request.sessionType,
+      externalUserId: request.externalUserId,
+      identityId: request.identityId,
+      metadata: request.metadata
+    });
   }
 
   /**
-   * 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 async cancelSession() {
-    return UseSenseModule.cancelSession();
+  static addListener(callback) {
+    const subscription = eventEmitter.addListener('UseSenseEvent', raw => {
+      callback(raw);
+    });
+    return {
+      remove: () => subscription.remove()
+    };
   }
 
   /**
-   * 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 async getSessionStatus(sessionId) {
-    return UseSenseModule.getSessionStatus(sessionId);
+  static async reset() {
+    return UseSenseModule.reset();
   }
 
   /**
-   * 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) {
-    UseSenseModule.subscribeToEvents();
-    const subscription = eventEmitter.addListener('UseSenseEvent', callback);
-    return {
-      remove: () => {
-        subscription.remove();
-        UseSenseModule.unsubscribeFromEvents();
-      }
-    };
+  static async isInitialized() {
+    return UseSenseModule.isInitialized();
   }
 
+  // ─── LiveSense v4 ─────────────────────────────────────────────────────
+  // Phase 1 ticket R-1.
+  //
+  // v4 runs the perspective-distortion zoom-motion capture. Passthrough
+  // to the native SDK's startV4Session (iOS) / startV4Verification
+  // (Android). The returned promise resolves with the opaque verdict;
+  // sub-scores and pillar verdicts are never exposed.
+
   /**
-   * 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() {
-    return UseSenseModule.getSdkVersion();
+  static async startV4Verification(request) {
+    return UseSenseModule.startV4Verification({
+      sessionId: request.sessionId,
+      sessionToken: request.sessionToken,
+      nonce: request.nonce,
+      apiBaseUrl: request.apiBaseUrl,
+      environment: request.environment ?? 'production',
+      displayName: request.displayName,
+      brandPrimaryColor: request.brandPrimaryColor
+    });
   }
 }
+
+// ─── LiveSense v4 types (R-1) ─────────────────────────────────────────────
+
+/**
+ * Opaque verdict from POST /v1/sessions/:id/result. Matches the server
+ * contract exactly; no sub-scores leak through.
+ */
+
 export default UseSense;
+
+// Slice 5d: Flows. A parallel surface to Sessions — host apps choose one
+// per call. See guides/flows/sessions-vs-flows in the API docs.
+export { UseSenseFlows, FlowError } from './flows';
 //# sourceMappingURL=index.js.map

package/lib/module/index.js.map

@@ -1 +1 @@
-{"version":3,"names":["NativeModules","NativeEventEmitter","UseSenseModule","Error","eventEmitter","UseSense","initialize","config","apiKey","code","message","environment","organizationId","sessionType","identityId","challengePolicy","enableAudio","timeout","metadata","startSession","options","cancelSession","getSessionStatus","sessionId","addListener","callback","subscribeToEvents","subscription","remove","unsubscribeFromEvents","getSdkVersion"],"sourceRoot":"../../src","sources":["index.ts"],"mappings":"AAAA,SAASA,aAAa,EAAEC,kBAAkB,QAAQ,cAAc;AAEhE,MAAM;EAAEC;AAAe,CAAC,GAAGF,aAAa;AAExC,IAAI,CAACE,cAAc,EAAE;EACnB,MAAM,IAAIC,KAAK,CACb,mGAAmG,GACjG,oCAAoC,GACpC,wDACJ,CAAC;AACH;;AAEA;;AAEA;;AAGA;;AAGA;;AAGA;;AAGA;;AAGA;AACA;AACA;AACA;AACA;AACA;AACA;AACA;AACA;AACA;AACA;;AAsBA;AACA;AACA;AACA;AACA;AACA;;AAwBA;AACA;AACA;;AAUA;AACA;AACA;;AASA;;AAQA;;AAQA;;AAMA;;AAEA,MAAMC,YAAY,GAAG,IAAIH,kBAAkB,CAACC,cAAc,CAAC;;AAE3D;AACA;AACA;AACA;AACA;AACA;AACA;AACA;AACA;AACA;AACA;AACA;AACA;AACA;AACA;AACA,OAAO,MAAMG,QAAQ,CAAC;EACpB;AACF;AACA;AACA;AACA;AACA;EACE,aAAaC,UAAUA,CAACC,MAAsB,EAAiB;IAC7D,IAAI,CAACA,MAAM,CAACC,MAAM,EAAE;MAClB,MAAM;QAAEC,IAAI,EAAE,gBAAgB;QAAEC,OAAO,EAAE;MAAqB,CAAC;IACjE;IACA,OAAOR,cAAc,CAACI,UAAU,CAAC;MAC/BE,MAAM,EAAED,MAAM,CAACC,MAAM;MACrBG,WAAW,EAAEJ,MAAM,CAACI,WAAW,IAAI,SAAS;MAC5CC,cAAc,EAAEL,MAAM,CAACK,cAAc;MACrCC,WAAW,EAAEN,MAAM,CAACM,WAAW,IAAI,YAAY;MAC/CC,UAAU,EAAEP,MAAM,CAACO,UAAU;MAC7BC,eAAe,EAAER,MAAM,CAACQ,eAAe,IAAI,UAAU;MACrDC,WAAW,EAAET,MAAM,CAACS,WAAW,IAAI,KAAK;MACxCC,OAAO,EAAEV,MAAM,CAACU,OAAO,IAAI,KAAK;MAChCC,QAAQ,EAAEX,MAAM,CAACW;IACnB,CAAC,CAAC;EACJ;;EAEA;AACF;AACA;AACA;AACA;AACA;AACA;AACA;AACA;AACA;EACE,aAAaC,YAAYA,CAACC,OAA6B,EAA2B;IAChF,OAAOlB,cAAc,CAACiB,YAAY,CAACC,OAAO,IAAI,CAAC,CAAC,CAAC;EACnD;;EAEA;AACF;AACA;AACA;AACA;AACA;EACE,aAAaC,aAAaA,CAAA,EAAkB;IAC1C,OAAOnB,cAAc,CAACmB,aAAa,CAAC,CAAC;EACvC;;EAEA;AACF;AACA;AACA;AACA;AACA;EACE,aAAaC,gBAAgBA,CAACC,SAAiB,EAA0B;IACvE,OAAOrB,cAAc,CAACoB,gBAAgB,CAACC,SAAS,CAAC;EACnD;;EAEA;AACF;AACA;AACA;AACA;AACA;AACA;AACA;AACA;AACA;AACA;AACA;AACA;AACA;AACA;AACA;AACA;EACE,OAAOC,WAAWA,CAACC,QAAwC,EAAwB;IACjFvB,cAAc,CAACwB,iBAAiB,CAAC,CAAC;IAClC,MAAMC,YAAY,GAAGvB,YAAY,CAACoB,WAAW,CAAC,eAAe,EAAEC,QAAQ,CAAC;IACxE,OAAO;MACLG,MAAM,EAAEA,CAAA,KAAM;QACZD,YAAY,CAACC,MAAM,CAAC,CAAC;QACrB1B,cAAc,CAAC2B,qBAAqB,CAAC,CAAC;MACxC;IACF,CAAC;EACH;;EAEA;AACF;AACA;AACA;AACA;EACE,OAAOC,aAAaA,CAAA,EAAW;IAC7B,OAAO5B,cAAc,CAAC4B,aAAa,CAAC,CAAC;EACvC;AACF;AAEA,eAAezB,QAAQ","ignoreList":[]}
+{"version":3,"names":["NativeModules","NativeEventEmitter","Platform","LINKING_ERROR","select","ios","android","default","UseSenseModule","Error","eventEmitter","UseSense","initialize","config","apiKey","err","code","message","isRetryable","environment","apiEndpoint","branding","antispoofOnDeviceEnabled","liveSenseV4Enabled","startVerification","request","sessionType","externalUserId","identityId","metadata","addListener","callback","subscription","raw","remove","reset","isInitialized","startV4Verification","sessionId","sessionToken","nonce","apiBaseUrl","displayName","brandPrimaryColor","UseSenseFlows","FlowError"],"sourceRoot":"../../src","sources":["index.ts"],"mappings":"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","ignoreList":[]}

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

@@ -0,0 +1,72 @@
+/**
+ * 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' | ...
+ *     }
+ *   }
+ */
+/**
+ * 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';
+/** Result returned to the host app's `runFlow` promise on terminal state. */
+export interface FlowRunResult {
+    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 declare class FlowError extends Error {
+    readonly code: FlowErrorCode;
+    constructor(code: FlowErrorCode, message: string);
+}
+/** 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 declare 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.
+     */
+    runFlow(options: RunFlowOptions): Promise<FlowRunResult>;
+};
+//# sourceMappingURL=flows.d.ts.map

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

@@ -0,0 +1 @@
+{"version":3,"file":"flows.d.ts","sourceRoot":"","sources":["../../../src/flows.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;;;;;GAmBG;AAoBH;;;GAGG;AACH,MAAM,MAAM,YAAY,GACpB,SAAS,GACT,aAAa,GACb,SAAS,GACT,iBAAiB,GACjB,WAAW,GACX,SAAS,GACT,WAAW,GACX,WAAW,CAAC;AAEhB,sCAAsC;AACtC,MAAM,MAAM,WAAW,GAAG,SAAS,GAAG,QAAQ,GAAG,eAAe,CAAC;AAEjE;;;GAGG;AACH,MAAM,MAAM,aAAa,GACrB,eAAe,GACf,eAAe,GACf,qBAAqB,GACrB,mBAAmB,GACnB,sBAAsB,GACtB,WAAW,GACX,oBAAoB;AACtB;;4EAE4E;GAC1E,eAAe,GACf,SAAS,CAAC;AAoBd,6EAA6E;AAC7E,MAAM,WAAW,aAAa;IAC5B,SAAS,EAAE,MAAM,CAAC;IAClB,KAAK,EAAE,YAAY,CAAC;IACpB,OAAO,EAAE,WAAW,GAAG,IAAI,CAAC;CAC7B;AAQD;;;;GAIG;AACH,qBAAa,SAAU,SAAQ,KAAK;IAClC,QAAQ,CAAC,IAAI,EAAE,aAAa,CAAC;gBACjB,IAAI,EAAE,aAAa,EAAE,OAAO,EAAE,MAAM;CAKjD;AAED,2CAA2C;AAC3C,MAAM,WAAW,cAAc;IAC7B,SAAS,EAAE,MAAM,CAAC;IAClB,QAAQ,EAAE,MAAM,CAAC;IACjB,6CAA6C;IAC7C,UAAU,CAAC,EAAE,MAAM,CAAC;CACrB;AAED;;;GAGG;AACH,eAAO,MAAM,aAAa;IACxB;;;;;OAKG;qBACoB,cAAc,GAAG,OAAO,CAAC,aAAa,CAAC;CAoB/D,CAAC"}