@smileid/usesmileid 12.0.0 → 12.0.2

package/src/camera/__tests__/use_smile_id_frame_stream_hook.test.tsx

@@ -0,0 +1,229 @@
+import { describe, expect, it, vi } from "vitest";
+import * as React from "react";
+import { create as createRenderer, act } from "react-test-renderer";
+import type {
+  DocumentScanResult,
+  FaceScanResult,
+} from "@smileid/usesmileid_bridge";
+import { FrameProcessingException } from "@smileid/usesmileid_bridge";
+
+import {
+  useSmileIDFrameStream,
+  type UseSmileIDFrameStream,
+} from "../use_smile_id_frame_stream";
+
+/**
+ * React-level companion to `use_smile_id_frame_stream.test.ts` (which
+ * pins the pure dispatcher). These tests mount the hook so the ref
+ * plumbing — analyzer / callback swaps between renders, the mounted
+ * gate, and the memoised handle identity — is actually exercised.
+ */
+
+const validFaceWirePayload = {
+  output: { faces: [], brightness: 0.5 },
+  state: { type: "initial" },
+  capturedEvents: [],
+};
+
+const validDocumentWirePayload = {
+  output: { documents: [], brightness: 0.5 },
+  state: { type: "found" },
+  capturedEvents: [],
+};
+
+type FaceAnalyzerStub = Parameters<typeof useSmileIDFrameStream>[0];
+
+const faceAnalyzer = { kind: "face" } as unknown as FaceAnalyzerStub;
+const documentAnalyzer = { kind: "document" } as unknown as FaceAnalyzerStub;
+
+type HarnessProps = {
+  readonly analyzer: FaceAnalyzerStub;
+  readonly onResult: (result: FaceScanResult) => void;
+  readonly onError?: (error: unknown) => void;
+  readonly onHandle: (handle: UseSmileIDFrameStream) => void;
+};
+
+function Harness({ analyzer, onResult, onError, onHandle }: HarnessProps) {
+  const handle = useSmileIDFrameStream(
+    analyzer,
+    onResult,
+    onError !== undefined ? { onError } : undefined,
+  );
+  onHandle(handle);
+  return null;
+}
+
+type Rendered = {
+  readonly tree: ReturnType<typeof createRenderer>;
+  readonly handles: UseSmileIDFrameStream[];
+  readonly latest: () => UseSmileIDFrameStream;
+};
+
+function mount(props: Omit<HarnessProps, "onHandle">): Rendered {
+  const handles: UseSmileIDFrameStream[] = [];
+  let tree!: ReturnType<typeof createRenderer>;
+  act(() => {
+    tree = createRenderer(
+      <Harness {...props} onHandle={(handle) => handles.push(handle)} />,
+    );
+  });
+  return {
+    tree,
+    handles,
+    latest: () => handles[handles.length - 1] as UseSmileIDFrameStream,
+  };
+}
+
+function update(
+  rendered: Rendered,
+  props: Omit<HarnessProps, "onHandle">,
+): void {
+  act(() => {
+    rendered.tree.update(
+      <Harness
+        {...props}
+        onHandle={(handle) => rendered.handles.push(handle)}
+      />,
+    );
+  });
+}
+
+describe("useSmileIDFrameStream", () => {
+  it("validates the raw wire payload and forwards the typed face result", () => {
+    const onResult = vi.fn();
+    const rendered = mount({ analyzer: faceAnalyzer, onResult });
+
+    act(() => {
+      rendered.latest().onFrameResult(validFaceWirePayload);
+    });
+
+    expect(onResult).toHaveBeenCalledTimes(1);
+    const result = onResult.mock.calls[0]?.[0] as FaceScanResult;
+    expect(result.state.type).toBe("initial");
+  });
+
+  it("parses against the document schema when the analyzer is a document one", () => {
+    const onResult = vi.fn();
+    const rendered = mount({
+      analyzer: documentAnalyzer,
+      onResult: onResult as unknown as (result: FaceScanResult) => void,
+    });
+
+    act(() => {
+      rendered.latest().onFrameResult(validDocumentWirePayload);
+    });
+
+    const result = onResult.mock.calls[0]?.[0] as DocumentScanResult;
+    expect(result.state.type).toBe("found");
+  });
+
+  it("keeps a stable handle across re-renders so the frame processor is not rebuilt", () => {
+    const onResult = vi.fn();
+    const rendered = mount({ analyzer: faceAnalyzer, onResult });
+    const first = rendered.latest();
+
+    update(rendered, { analyzer: faceAnalyzer, onResult: vi.fn() });
+
+    expect(rendered.latest()).toBe(first);
+    expect(rendered.latest().onFrameResult).toBe(first.onFrameResult);
+  });
+
+  it("routes results to the latest onResult after a swap", () => {
+    const first = vi.fn();
+    const second = vi.fn();
+    const rendered = mount({ analyzer: faceAnalyzer, onResult: first });
+
+    update(rendered, { analyzer: faceAnalyzer, onResult: second });
+    act(() => {
+      rendered.latest().onFrameResult(validFaceWirePayload);
+    });
+
+    expect(first).not.toHaveBeenCalled();
+    expect(second).toHaveBeenCalledTimes(1);
+  });
+
+  it("stops dispatching once the analyzer is detached", () => {
+    const onResult = vi.fn();
+    const rendered = mount({ analyzer: faceAnalyzer, onResult });
+
+    update(rendered, { analyzer: null, onResult });
+    act(() => {
+      rendered.latest().onFrameResult(validFaceWirePayload);
+    });
+
+    expect(onResult).not.toHaveBeenCalled();
+  });
+
+  it("reports a native error marker through the latest onError", () => {
+    const onResult = vi.fn();
+    const firstOnError = vi.fn();
+    const secondOnError = vi.fn();
+    const rendered = mount({
+      analyzer: faceAnalyzer,
+      onResult,
+      onError: firstOnError,
+    });
+
+    update(rendered, {
+      analyzer: faceAnalyzer,
+      onResult,
+      onError: secondOnError,
+    });
+    act(() => {
+      rendered.latest().onFrameResult({ error: "session crashed" });
+    });
+
+    expect(firstOnError).not.toHaveBeenCalled();
+    expect(secondOnError).toHaveBeenCalledTimes(1);
+    expect(secondOnError.mock.calls[0]?.[0]).toBeInstanceOf(
+      FrameProcessingException,
+    );
+    expect(onResult).not.toHaveBeenCalled();
+  });
+
+  it("swallows a schema rejection when no error handler is supplied", () => {
+    const onResult = vi.fn();
+    const rendered = mount({ analyzer: faceAnalyzer, onResult });
+
+    expect(() => {
+      act(() => {
+        rendered.latest().onFrameResult({ nonsense: true });
+      });
+    }).not.toThrow();
+    expect(onResult).not.toHaveBeenCalled();
+  });
+
+  it("drops results that arrive after unmount", () => {
+    const onResult = vi.fn();
+    const onError = vi.fn();
+    const rendered = mount({ analyzer: faceAnalyzer, onResult, onError });
+    const handle = rendered.latest();
+
+    act(() => {
+      rendered.tree.unmount();
+    });
+    handle.onFrameResult(validFaceWirePayload);
+    handle.onFrameResult({ error: "late failure" });
+
+    expect(onResult).not.toHaveBeenCalled();
+    expect(onError).not.toHaveBeenCalled();
+  });
+
+  it("gates re-entrant dispatch while a frame is in flight", () => {
+    const seen: string[] = [];
+    let handle: UseSmileIDFrameStream | null = null;
+    const onResult = vi.fn(() => {
+      seen.push("outer");
+      // A second frame arriving mid-dispatch must be dropped, not recursed into.
+      handle?.onFrameResult(validFaceWirePayload);
+    });
+    const rendered = mount({ analyzer: faceAnalyzer, onResult });
+    handle = rendered.latest();
+
+    act(() => {
+      handle?.onFrameResult(validFaceWirePayload);
+    });
+
+    expect(seen).toEqual(["outer"]);
+  });
+});

package/src/camera/camera_defaults.ts

@@ -12,6 +12,9 @@ export const CameraDefaults = {
   /** Document analysis resolution (16:9, matched to the visible preview so the guide-rect crop stays aligned). */
   documentAnalysisResolution: { width: 1280, height: 720 } as const,
 
+  /** How long a streaming capture waits for its first analyzed frame before reporting the camera unavailable. */
+  firstFrameTimeoutMs: 10_000,
+
   /** Longest-edge ceiling (px) for an imported document image; downscale-only. */
   documentMaxDimension: 1600,
   /** JPEG quality (0–1) for imported document images. */

package/src/core/exception/__tests__/builder_validation_exceptions.test.ts

@@ -0,0 +1,81 @@
+import { describe, expect, it } from "vitest";
+
+import { DuplicateScreenTypeException } from "../duplicate_screen_type_exception";
+import { InvalidMissingCaptureTypeException } from "../invalid_missing_capture_type_exception";
+import { InvalidSelfieCaptureConfigException } from "../invalid_selfie_capture_config_exception";
+import { LivenessFrameCountException } from "../liveness_frame_count_exception";
+import { UseSmileIDErrorCode } from "../use_smile_id_error_code";
+
+/** Typed builder/validation exceptions: pin `errorCode`, message, and `errorDetails`. */
+describe("DuplicateScreenTypeException", () => {
+  it("names the duplicated type + indices and freezes the details", () => {
+    const exception = new DuplicateScreenTypeException({
+      screenType: "consent",
+      indices: [0, 3],
+    });
+
+    expect(exception).toBeInstanceOf(Error);
+    expect(exception.errorCode).toBe(
+      UseSmileIDErrorCode.Builder.DuplicateScreenType,
+    );
+    expect(exception.message).toContain("consent");
+    expect(exception.message).toContain("0, 3");
+    expect(exception.errorDetails).toEqual({
+      screenType: "consent",
+      indices: [0, 3],
+    });
+    expect(Object.isFrozen(exception.errorDetails?.["indices"])).toBe(true);
+  });
+});
+
+describe("LivenessFrameCountException", () => {
+  it("reports expected vs actual frame counts", () => {
+    const exception = new LivenessFrameCountException({
+      expected: 8,
+      actual: 3,
+    });
+
+    expect(exception.errorCode).toBe(
+      UseSmileIDErrorCode.Validation.ConstraintViolation,
+    );
+    expect(exception.message).toContain("8");
+    expect(exception.message).toContain("3");
+    expect(exception.errorDetails).toEqual({ expected: 8, actual: 3 });
+  });
+});
+
+describe("InvalidSelfieCaptureConfigException", () => {
+  it("omits the reason suffix and details when no reason is given", () => {
+    const exception = new InvalidSelfieCaptureConfigException();
+
+    expect(exception.errorCode).toBe(
+      UseSmileIDErrorCode.Builder.InvalidSelfieCaptureConfig,
+    );
+    expect(exception.message).toContain("configuration is missing");
+    expect(exception.errorDetails).toBeUndefined();
+  });
+
+  it("appends the reason and carries it in details when provided", () => {
+    const exception = new InvalidSelfieCaptureConfigException({
+      reason: "minConfidence out of range",
+    });
+
+    expect(exception.message).toContain("minConfidence out of range");
+    expect(exception.errorDetails).toEqual({
+      reason: "minConfidence out of range",
+    });
+  });
+});
+
+describe("InvalidMissingCaptureTypeException", () => {
+  it("carries the missing-capture-type code and an actionable fix", () => {
+    const exception = new InvalidMissingCaptureTypeException();
+
+    expect(exception).toBeInstanceOf(Error);
+    expect(exception.errorCode).toBe(
+      UseSmileIDErrorCode.Builder.MissingCaptureType,
+    );
+    expect(exception.message).toContain("captureType is missing");
+    expect(exception.suggestedFix).toContain("selfie or document");
+  });
+});

package/src/core/exception/agent_mode_with_enhanced_liveness_exception.ts

@@ -0,0 +1,20 @@
+import { UseSmileIDBuilderException } from "./use_smile_id_builder_exception";
+import { UseSmileIDErrorCode } from "./use_smile_id_error_code";
+
+/**
+ * Agent mode was combined with enhanced liveness. The head-turn challenge is
+ * validated for front-camera capture only, so the two options are mutually
+ * exclusive.
+ */
+export class AgentModeWithEnhancedLivenessException extends UseSmileIDBuilderException {
+  readonly errorCode =
+    UseSmileIDErrorCode.Builder.AgentModeWithEnhancedLiveness;
+
+  constructor() {
+    super({
+      message: "allowAgentMode is not supported with enableEnhancedLiveness",
+      suggestedFix:
+        "Disable one of them inside selfie { }: allowAgentMode for rear-camera agent capture, or enableEnhancedLiveness for the head-turn challenge",
+    });
+  }
+}

package/src/core/exception/capture_validation_exceptions.ts

@@ -3,6 +3,7 @@
  * Each concrete class lives in its own file; this module keeps the
  * legacy import path stable.
  */
+export { AgentModeWithEnhancedLivenessException } from "./agent_mode_with_enhanced_liveness_exception";
 export { InvalidSelfieCaptureConfigException } from "./invalid_selfie_capture_config_exception";
 export { InvalidDocumentCaptureConfigException } from "./invalid_document_capture_config_exception";
 export { InvalidMissingCaptureTypeException } from "./invalid_missing_capture_type_exception";

package/src/core/exception/flow_exceptions.test.ts

@@ -36,4 +36,14 @@ describe("ProcessingCancelledException", () => {
     expect(error).toBeInstanceOf(UseSmileIDException);
     expect(error).toBeInstanceOf(Error);
   });
+
+  it("carries an underlying cause when one is supplied", () => {
+    const underlying = new Error("upload aborted");
+    const error = new ProcessingCancelledException({ cause: underlying });
+    expect(error.cause).toBe(underlying);
+  });
+
+  it("leaves cause unset when none is supplied", () => {
+    expect(new ProcessingCancelledException().cause).toBeUndefined();
+  });
 });

package/src/core/exception/flow_exceptions.ts

@@ -27,16 +27,17 @@ export class ConsentDeniedException extends UseSmileIDGeneralException {
  *
  * Surfaced through `onResult.failure` so partners can distinguish a
  * user-initiated cancellation from a submission error, mirroring the
- * native SDKs' `ProcessingCancelledException`.
+ * native SDKs' `ProcessingCancelledException`. An optional `cause` carries a submission failure that preceded the exit.
  */
 export class ProcessingCancelledException extends UseSmileIDGeneralException {
   readonly errorCode = UseSmileIDErrorCode.General.OperationFailed;
 
-  constructor() {
+  constructor(args: { cause?: unknown } = {}) {
     super({
       message: "Processing was cancelled",
       suggestedFix:
         "The user exited the processing screen before submission completed.",
+      ...(args.cause !== undefined ? { cause: args.cause } : {}),
     });
   }
 }

package/src/core/exception/index.ts

@@ -43,6 +43,7 @@ export { MissingCaptureForPreviewException } from "./missing_capture_for_preview
 export { DuplicateScreenTypeException } from "./duplicate_screen_type_exception";
 
 // Capture-config validation (`capture { }` block).
+export { AgentModeWithEnhancedLivenessException } from "./agent_mode_with_enhanced_liveness_exception";
 export { InvalidSelfieCaptureConfigException } from "./invalid_selfie_capture_config_exception";
 export { InvalidDocumentCaptureConfigException } from "./invalid_document_capture_config_exception";
 export { InvalidMissingCaptureTypeException } from "./invalid_missing_capture_type_exception";

package/src/core/exception/missing_job_type_exception.ts

@@ -2,9 +2,7 @@ import { UseSmileIDBuilderException } from "./use_smile_id_builder_exception";
 import { UseSmileIDErrorCode } from "./use_smile_id_error_code";
 
 /**
- * The `network { config { } }` block is present but `jobType` was
- * never set — the orchestrator can't pick a submission path without
- * it.
+ * `jobType` was never set, or was set to a value that is not one of the SDK's job types.
  */
 export class MissingJobTypeException extends UseSmileIDBuilderException {
   readonly errorCode = UseSmileIDErrorCode.Builder.MissingJobType;
@@ -12,7 +10,7 @@ export class MissingJobTypeException extends UseSmileIDBuilderException {
   constructor() {
     super({
       message:
-        "jobType is not set — it must be configured explicitly in the network { config { } } block",
+        "jobType is not set to one of the SDK's job types — it must be configured explicitly in the network { config { } } block",
       suggestedFix:
         "Set config.jobType in the network { config { } } block, e.g. config.jobType = JobType.DocumentVerification",
     });

package/src/core/exception/use_smile_id_error_code.ts

@@ -24,6 +24,7 @@ export const UseSmileIDErrorCode = {
     MissingScreenConfiguration: "BUILDER_MISSING_SCREEN_CONFIG",
     DuplicateScreenType: "BUILDER_DUPLICATE_SCREEN",
     InvalidSelfieCaptureConfig: "BUILDER_INVALID_SELFIE_CONFIG",
+    AgentModeWithEnhancedLiveness: "BUILDER_AGENT_MODE_WITH_ENHANCED_LIVENESS",
     InvalidDocumentCaptureConfig: "BUILDER_INVALID_DOCUMENT_CONFIG",
     MissingMLConfiguration: "BUILDER_MISSING_ML_CONFIG",
     MissingNetworkConfiguration: "BUILDER_MISSING_NETWORK_CONFIG",

package/src/core/models/__tests__/document_type.test.ts

@@ -15,11 +15,11 @@ describe("DocumentType presets", () => {
     });
   });
 
-  it("Passport is a landscape, single-sided document", () => {
+  it("Passport is a landscape, two-sided document", () => {
     expect(DocumentType.Passport).toEqual({
       kind: "passport",
       displayName: "Passport",
-      hasBackSide: false,
+      hasBackSide: true,
       orientation: "Landscape",
       knownAspectRatio: 356 / 272,
     });

package/src/core/models/__tests__/flow_models.test.ts

@@ -0,0 +1,26 @@
+import { describe, expect, it } from "vitest";
+
+import { FlowStep } from "../flow_step";
+import { HEAD_TURN_DIRECTIONS } from "../head_turn_direction";
+
+/** FlowStep + head-turn direction order is load-bearing (nav advances through it); pin it. */
+describe("flow model constants", () => {
+  it("FlowStep lists the steps in forward-navigation order", () => {
+    expect(FlowStep).toEqual([
+      "instructions",
+      "consent",
+      "permission",
+      "capture",
+      "preview",
+      "processing",
+    ]);
+  });
+
+  it("HEAD_TURN_DIRECTIONS enumerates the three challenge directions in order", () => {
+    expect(HEAD_TURN_DIRECTIONS).toEqual([
+      "look_left",
+      "look_right",
+      "look_up",
+    ]);
+  });
+});

package/src/core/models/config.ts

@@ -1,3 +1,6 @@
+import type * as ScreenOrientation from "expo-screen-orientation";
+import type { GlobalPrivacyControl } from "./global_privacy_control";
+
 /**
  * Global SDK configuration flags. Snapshot produced by
  * `UseSmileIDConfigBuilder.build()` — every field is populated, with
@@ -33,4 +36,23 @@ export type ConfigOptions = {
    * `docs/Architecture.md § Rollout`.
    */
   readonly allowOfflineMode: boolean;
+
+  /**
+   * Partner-declared consent posture (`global_privacy_control`).
+   * `GlobalPrivacyControl.OptOut` (the default) forces the opt-out consent
+   * layout universally; `OptIn` keeps the legacy regional mechanics.
+   */
+  readonly globalPrivacyControl: GlobalPrivacyControl;
+
+  /**
+   * Orientation lock the SDK applies when a capture screen leaves the screen.
+   * Defaults to `PORTRAIT_UP`, the posture most hosts pin at their root
+   * layout; multi-orientation hosts set `DEFAULT` so the flow releases the
+   * clamp instead of leaving the app portrait-only after verification.
+   *
+   * Optional so a hand-written `ConfigOptions` literal still compiles; the
+   * builder always populates it, and an absent value takes the same
+   * `PORTRAIT_UP` default at the capture screen.
+   */
+  readonly exitOrientations?: ScreenOrientation.OrientationLock;
 };

package/src/core/models/document_type.ts

@@ -34,7 +34,7 @@ const SOUTH_AFRICA_GREEN_BOOK: DocumentType = Object.freeze({
 const PASSPORT: DocumentType = Object.freeze({
   kind: "passport",
   displayName: "Passport",
-  hasBackSide: false,
+  hasBackSide: true,
   orientation: "Landscape",
   knownAspectRatio: 356 / 272,
 });
@@ -51,7 +51,7 @@ export type GenericDocumentArgs = {
 export const DocumentType = {
   /** South Africa Green Book — booklet-style, single-side, portrait. */
   SouthAfricaGreenBook: SOUTH_AFRICA_GREEN_BOOK,
-  /** Passport — single data page, no back side, landscape. */
+  /** Passport — landscape data page followed by a back-side capture. */
   Passport: PASSPORT,
   /** Catch-all without a preset; defaults to a landscape, two-sided "Document". */
   GenericDocument(args: GenericDocumentArgs = {}): DocumentType {

package/src/core/models/global_privacy_control.ts

@@ -0,0 +1,45 @@
+/**
+ * Partner-declared Global Privacy Control posture for the consent screen
+ * (`global_privacy_control` on the wire).
+ *
+ * Native mobile platforms expose no OS-level equivalent of the web's GPC
+ * signal, so the SDK performs no runtime user-signal tracking: the partner
+ * declares the posture once at initialization
+ * (`b.config((c) => { c.globalPrivacyControl = ...; })`) and it governs
+ * every session.
+ *
+ * Const-object pattern (see `KameraEventType`-style types): enum ergonomics,
+ * string wire format.
+ */
+export const GlobalPrivacyControl = {
+  /**
+   * Default. Forces the opt-out consent layout universally: consent starts
+   * granted (pre-selected) for every session regardless of region — the
+   * user unticks to opt out. Regional detection is never consulted.
+   */
+  OptOut: "opt-out",
+
+  /**
+   * Legacy regional mechanics: consent starts granted outside the EU and
+   * starts ungranted (explicit opt-in required) when the device locale is
+   * an EU member state.
+   */
+  OptIn: "opt-in",
+} as const;
+export type GlobalPrivacyControl =
+  (typeof GlobalPrivacyControl)[keyof typeof GlobalPrivacyControl];
+
+/** Configuration key this setting is transported under. */
+export const GLOBAL_PRIVACY_CONTROL_WIRE_KEY = "global_privacy_control";
+
+/**
+ * Parses a wire value ("opt-out" / "opt-in"); anything else falls back to
+ * the `OptOut` baseline default.
+ */
+export function globalPrivacyControlFromWire(
+  value: string | null | undefined,
+): GlobalPrivacyControl {
+  return value === GlobalPrivacyControl.OptIn
+    ? GlobalPrivacyControl.OptIn
+    : GlobalPrivacyControl.OptOut;
+}

package/src/core/models/network_config.ts

@@ -97,10 +97,10 @@ export type CacheConfig = {
 };
 
 /**
- * Retry strategy.
+ * Retry strategy. `none` is the default.
+ *   - `none`: one attempt, no retry — `maxAttempts` is forced to 1
  *   - `exponential`: `delay = min(initialDelay × multiplier^attempt, maxDelay)` plus `±jitter`
  *   - `fixed`: constant `fixedDelay` between attempts
- *   - `none`: no retry (`maxAttempts: 1`)
  */
 export enum RetryStrategy {
   exponential = "exponential",