react-native-usesense 2.0.0 → 2.1.0

package/src/index.ts

@@ -72,6 +72,27 @@ export interface UseSenseConfig {
   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;
 }
 
 /**
@@ -241,6 +262,8 @@ export class UseSense {
       environment: config.environment ?? 'auto',
       apiEndpoint: config.apiEndpoint,
       branding: config.branding,
+      antispoofOnDeviceEnabled: config.antispoofOnDeviceEnabled ?? false,
+      liveSenseV4Enabled: config.liveSenseV4Enabled ?? false,
     });
   }
 
@@ -304,6 +327,79 @@ export class UseSense {
   static async isInitialized(): Promise<boolean> {
     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.
+
+  /**
+   * Start a LiveSense v4 session.
+   *
+   * 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 async startV4Verification(
+    request: V4VerificationRequest,
+  ): Promise<V4Verdict> {
+    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) ─────────────────────────────────────────────
+
+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;
+
+// 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,
+  type FlowErrorCode,
+  type FlowOutcome,
+  type FlowRunResult,
+  type FlowRunState,
+  type RunFlowOptions,
+} from './flows';