@smileid/usesmileid 12.0.1 → 12.0.2

package/src/presentation/flow/validation/user_details_validator.ts

@@ -0,0 +1,53 @@
+import type { UserDetails } from "../../../core/models/params";
+import { InvalidFieldValueException } from "../../../core/exception/job_validation_exceptions";
+import type { TokenPayload } from "../../../data/model/token_payload";
+import type { ValidationIssue } from "./validation_state";
+
+/**
+ * Field-union rule shared by the content validator and the job-type required
+ * rule: a field is covered when the token binds it or the builder supplies it.
+ */
+export function missingUserDetailsFieldIssues(
+  userDetails: UserDetails | undefined,
+  tokenPayload: TokenPayload | undefined,
+): ValidationIssue[] {
+  const issues: ValidationIssue[] = [];
+  const fieldReason =
+    tokenPayload === undefined
+      ? "must not be blank"
+      : "not bound by the token and not supplied on the builder";
+  const tokenBindsField = {
+    givenNames: tokenPayload?.hasGivenNames === true,
+    lastName: tokenPayload?.hasLastName === true,
+  } as const;
+  for (const field of ["givenNames", "lastName"] as const) {
+    if (tokenBindsField[field]) continue;
+    const value = userDetails?.[field];
+    if (!value || !value.trim()) {
+      issues.push(
+        new InvalidFieldValueException({
+          fieldName: `userDetails.${field}`,
+          reason: fieldReason,
+        }),
+      );
+    }
+  }
+  // email and phoneNumber are each optional, but one must come from the builder or the token.
+  const hasEmail = !!userDetails?.email && userDetails.email.trim().length > 0;
+  const hasPhone =
+    !!userDetails?.phoneNumber && userDetails.phoneNumber.trim().length > 0;
+  const tokenHasContact =
+    tokenPayload?.hasEmail === true || tokenPayload?.hasPhoneNumber === true;
+  if (!hasEmail && !hasPhone && !tokenHasContact) {
+    issues.push(
+      new InvalidFieldValueException({
+        fieldName: "userDetails",
+        reason:
+          tokenPayload === undefined
+            ? "at least one of email or phoneNumber must be non blank"
+            : "at least one contact field must be bound by the token or supplied on the builder",
+      }),
+    );
+  }
+  return issues;
+}

package/src/presentation/screen/__tests__/feedback_copy_table.test.ts

@@ -0,0 +1,145 @@
+import { describe, expect, it } from "vitest";
+
+import {
+  documentFeedbackKeyFor,
+  resolveFeedbackCopy,
+  selfieFeedbackKeyFor,
+} from "../helpers/capture_screen_helpers";
+import { UseSmileIDOverlayState } from "../../state/use_smile_id_overlay_state";
+import { UseSmileIDLocalizations } from "../../../l10n/use_smile_id_localizations";
+import { enStrings, type SiKey } from "../../../l10n/strings_en";
+
+/**
+ * The feedback-key → copy table is the single seam between the capture
+ * overlay's stable `si_*` keys and the partner's localization instance.
+ * Every entry must resolve to the canonical English default and must
+ * honour a partner override, otherwise a translated build silently
+ * shows English (or the wrong string) mid-capture.
+ */
+
+const loc = new UseSmileIDLocalizations({});
+
+// Every key the capture surface can emit as feedback.
+const FEEDBACK_KEYS: readonly SiKey[] = [
+  "si_capture_initial_instruction",
+  "si_start_capture_instruction",
+  "si_capture_too_close",
+  "si_capture_too_far",
+  "si_capture_center_face",
+  "si_capture_multiple_faces",
+  "si_capture_low_light",
+  "si_capture_bright_light",
+  "si_capture_rotate_device",
+  "si_capture_smile",
+  "si_capture_move_left",
+  "si_capture_move_right",
+  "si_capture_move_higher",
+  "si_capture_move_lower",
+  "si_capture_ready",
+  "si_capture_hold_steady",
+  "si_capture_timeout",
+  "si_capturing",
+  "si_selfie_capture_complete",
+  "si_selfie_capture_timeout",
+  "si_selfie_capture_unsatisfied",
+  "si_ess_capture_initial_instruction",
+  "si_ess_hold_still",
+  "si_ess_look_left",
+  "si_ess_look_right",
+  "si_ess_look_up",
+  "si_ess_look_at_camera",
+  "si_document_initial_instruction",
+  "si_document_ready",
+  "si_document_capturing",
+  "si_document_capture_complete",
+  "si_document_capture_unsatisfied",
+  "si_document_capture_timeout",
+  "si_document_too_close",
+  "si_document_too_far",
+  "si_document_center",
+  "si_document_hold_still",
+  "si_document_gallery_image_too_small",
+  "si_document_gallery_image_failed",
+];
+
+describe("resolveFeedbackCopy", () => {
+  for (const key of FEEDBACK_KEYS) {
+    it(`resolves ${key} to its canonical English default`, () => {
+      expect(resolveFeedbackCopy(key, loc)).toBe(enStrings[key]);
+    });
+  }
+
+  it("honours a partner override for every feedback key", () => {
+    const overrides = Object.fromEntries(
+      FEEDBACK_KEYS.map((key) => [key, `translated:${key}`]),
+    );
+    const translated = new UseSmileIDLocalizations(overrides);
+
+    for (const key of FEEDBACK_KEYS) {
+      expect(resolveFeedbackCopy(key, translated)).toBe(`translated:${key}`);
+    }
+  });
+
+  it("falls back to the initial instruction for a key outside the table", () => {
+    // `si_consent_title` is a real key that the capture surface never emits.
+    expect(resolveFeedbackCopy("si_consent_title" as SiKey, loc)).toBe(
+      loc.siCaptureInitialInstruction,
+    );
+  });
+});
+
+describe("documentFeedbackKeyFor", () => {
+  it("maps each document guidance state to its stable key", () => {
+    expect(
+      documentFeedbackKeyFor(UseSmileIDOverlayState.DOCUMENT_TOO_CLOSE),
+    ).toBe("si_document_too_close");
+    expect(
+      documentFeedbackKeyFor(UseSmileIDOverlayState.DOCUMENT_TOO_FAR),
+    ).toBe("si_document_too_far");
+    expect(
+      documentFeedbackKeyFor(UseSmileIDOverlayState.DOCUMENT_NOT_CENTERED),
+    ).toBe("si_document_center");
+    expect(
+      documentFeedbackKeyFor(UseSmileIDOverlayState.DOCUMENT_HOLD_STILL),
+    ).toBe("si_document_hold_still");
+  });
+
+  it("returns null for lifecycle states that carry no guidance", () => {
+    expect(
+      documentFeedbackKeyFor(UseSmileIDOverlayState.INSTRUCTION),
+    ).toBeNull();
+    expect(
+      documentFeedbackKeyFor(UseSmileIDOverlayState.DOCUMENT_READY),
+    ).toBeNull();
+    expect(documentFeedbackKeyFor(UseSmileIDOverlayState.CAPTURING)).toBeNull();
+    // A selfie-only guidance state must not leak into the document table.
+    expect(documentFeedbackKeyFor(UseSmileIDOverlayState.TOO_CLOSE)).toBeNull();
+  });
+
+  it("resolves every document key it emits through the copy table", () => {
+    const states = [
+      UseSmileIDOverlayState.DOCUMENT_TOO_CLOSE,
+      UseSmileIDOverlayState.DOCUMENT_TOO_FAR,
+      UseSmileIDOverlayState.DOCUMENT_NOT_CENTERED,
+      UseSmileIDOverlayState.DOCUMENT_HOLD_STILL,
+    ];
+    for (const state of states) {
+      const key = documentFeedbackKeyFor(state);
+      expect(key).not.toBeNull();
+      expect(resolveFeedbackCopy(key as SiKey, loc)).toBe(
+        enStrings[key as SiKey],
+      );
+    }
+  });
+});
+
+describe("selfieFeedbackKeyFor", () => {
+  it("returns null for the document-only states", () => {
+    expect(
+      selfieFeedbackKeyFor(UseSmileIDOverlayState.DOCUMENT_TOO_CLOSE),
+    ).toBeNull();
+    expect(
+      selfieFeedbackKeyFor(UseSmileIDOverlayState.DOCUMENT_HOLD_STILL),
+    ).toBeNull();
+  });
+});

package/src/presentation/screen/__tests__/use_smile_id_capture_screen.test.tsx

@@ -476,6 +476,18 @@ describe("UseSmileIDCaptureScreen", () => {
     expect(mockedSetBrightness).toHaveBeenCalledWith(1);
   });
 
+  it("asks for dark status-bar content, matching the white capture scrim", () => {
+    const { root } = render(
+      <UseSmileIDCaptureScreen
+        analyzer={fakeAnalyzer}
+        captureType={CaptureType.selfie}
+      />,
+    );
+    expect(root.findAllByType(StatusBar)[0]!.props.barStyle).toBe(
+      "dark-content",
+    );
+  });
+
   it("renders a translucent status bar so the preview is edge-to-edge", () => {
     // Translucent status bar = full-bleed window = full-screen oval reference.
     const { root } = render(
@@ -777,4 +789,340 @@ describe("session-boundary epoch reset — debouncer regression", () => {
       expect(mockedTakePhoto).toHaveBeenCalledTimes(1);
     });
   });
+
+  describe("selfie capture timeout recovery", () => {
+    function renderSelfieScreen() {
+      return render(
+        <UseSmileIDCaptureScreen
+          analyzer={fakeAnalyzer}
+          captureType={CaptureType.selfie}
+        />,
+      );
+    }
+
+    function startCapture(root: ReactTestInstance) {
+      act(() => {
+        findByTestID(root, "si_capture_start_button")!.props.onClick();
+      });
+    }
+
+    function emit(state: UseSmileIDScanState) {
+      expect(capturedOnResult).not.toBeNull();
+      act(() => {
+        capturedOnResult!({
+          output: { faces: [], brightness: 0 },
+          state,
+          capturedEvents: [],
+        });
+      });
+    }
+
+    it("offers Start again after a timeout", () => {
+      const { root } = renderSelfieScreen();
+      startCapture(root);
+
+      emit({ type: UseSmileIDScanStateType.Timeout });
+
+      const start = findByTestID(root, "si_capture_start_button");
+      expect(start).not.toBeNull();
+      expect(start!.props.enabled).toBe(true);
+    });
+
+    it("resets the native session when Start is tapped after a timeout", async () => {
+      const { root } = renderSelfieScreen();
+      startCapture(root);
+      emit({ type: UseSmileIDScanStateType.Timeout });
+      fakeAnalyzer.reset.mockClear();
+
+      startCapture(root);
+      await act(async () => {
+        await Promise.resolve();
+      });
+
+      // The native session is terminal after a timeout — without a reset the
+      // first retry frame re-reports Timeout and re-latches the error.
+      expect(fakeAnalyzer.reset).toHaveBeenCalledTimes(1);
+    });
+
+    it("restarts the session when Start is tapped after a timeout", () => {
+      const onStartCapture = vi.fn();
+      const { root } = render(
+        <UseSmileIDCaptureScreen
+          analyzer={fakeAnalyzer}
+          captureType={CaptureType.selfie}
+          onStartCapture={onStartCapture}
+        />,
+      );
+      startCapture(root);
+      emit({ type: UseSmileIDScanStateType.Timeout });
+
+      startCapture(root);
+
+      expect(onStartCapture).toHaveBeenCalledTimes(2);
+    });
+
+    it("still delivers a capture that completes on the retry", async () => {
+      const onCaptureComplete = vi.fn();
+      const { root } = render(
+        <UseSmileIDCaptureScreen
+          analyzer={fakeAnalyzer}
+          captureType={CaptureType.selfie}
+          onCaptureComplete={onCaptureComplete}
+        />,
+      );
+      startCapture(root);
+      emit({ type: UseSmileIDScanStateType.Timeout });
+      startCapture(root);
+
+      emit({ type: UseSmileIDScanStateType.Finished });
+      await act(async () => {
+        await Promise.resolve();
+        await Promise.resolve();
+      });
+
+      expect(onCaptureComplete).toHaveBeenCalledTimes(1);
+    });
+
+    it("drops a capture that lands after the timeout was already reported", async () => {
+      const onCaptureComplete = vi.fn();
+      const onCaptureTimeout = vi.fn();
+      const { root } = render(
+        <UseSmileIDCaptureScreen
+          analyzer={fakeAnalyzer}
+          captureType={CaptureType.selfie}
+          onCaptureComplete={onCaptureComplete}
+          onCaptureTimeout={onCaptureTimeout}
+        />,
+      );
+      startCapture(root);
+
+      emit({ type: UseSmileIDScanStateType.Timeout });
+      emit({ type: UseSmileIDScanStateType.Finished });
+      await act(async () => {
+        await Promise.resolve();
+        await Promise.resolve();
+      });
+
+      expect(onCaptureTimeout).toHaveBeenCalledTimes(1);
+      expect(onCaptureComplete).not.toHaveBeenCalled();
+    });
+
+    it("does not pad the retry with frames banked before the timeout", async () => {
+      const onCaptureComplete = vi.fn();
+      const { root } = render(
+        <UseSmileIDCaptureScreen
+          analyzer={fakeAnalyzer}
+          captureType={CaptureType.selfie}
+          onCaptureComplete={onCaptureComplete}
+        />,
+      );
+      startCapture(root);
+      act(() => {
+        capturedOnResult!({
+          output: { faces: [], brightness: 0 },
+          state: { type: UseSmileIDScanStateType.Found },
+          capturedEvents: [
+            {
+              kind: CaptureReadyEventKind.Liveness,
+              captureIndex: 0,
+              url: "file:///stale.jpg",
+            },
+          ] as CaptureReadyEvent[],
+        });
+      });
+      emit({ type: UseSmileIDScanStateType.Timeout });
+
+      startCapture(root);
+      act(() => {
+        capturedOnResult!({
+          output: { faces: [], brightness: 0 },
+          state: { type: UseSmileIDScanStateType.Found },
+          capturedEvents: [
+            {
+              kind: CaptureReadyEventKind.Selfie,
+              captureIndex: 0,
+              url: "file:///fresh.jpg",
+            },
+          ] as CaptureReadyEvent[],
+        });
+      });
+      emit({ type: UseSmileIDScanStateType.Finished });
+      await act(async () => {
+        await Promise.resolve();
+        await Promise.resolve();
+      });
+
+      expect(onCaptureComplete).toHaveBeenCalledTimes(1);
+      const [delivered] = onCaptureComplete.mock.calls[0] as [
+        readonly CaptureReadyEvent[],
+      ];
+      expect(delivered.map((event) => event.url)).toEqual([
+        "file:///fresh.jpg",
+      ]);
+    });
+
+    it("reports the timeout to the partner exactly once", () => {
+      const onCaptureTimeout = vi.fn();
+      const { root } = render(
+        <UseSmileIDCaptureScreen
+          analyzer={fakeAnalyzer}
+          captureType={CaptureType.selfie}
+          onCaptureTimeout={onCaptureTimeout}
+        />,
+      );
+      startCapture(root);
+
+      emit({ type: UseSmileIDScanStateType.Timeout });
+      emit({ type: UseSmileIDScanStateType.Timeout });
+
+      expect(onCaptureTimeout).toHaveBeenCalledTimes(1);
+    });
+  });
+
+  describe("no camera frames at all", () => {
+    beforeEach(() => {
+      vi.useFakeTimers();
+    });
+
+    afterEach(() => {
+      vi.useRealTimers();
+    });
+
+    function renderAndStart() {
+      const tree = render(
+        <UseSmileIDCaptureScreen
+          analyzer={fakeAnalyzer}
+          captureType={CaptureType.selfie}
+        />,
+      );
+      act(() => {
+        findByTestID(tree.root, "si_capture_start_button")!.props.onClick();
+      });
+      return tree;
+    }
+
+    function elapseFirstFrameWait() {
+      act(() => {
+        vi.advanceTimersByTime(10_000);
+      });
+    }
+
+    it("names the cause instead of sitting on the initial instruction", () => {
+      const { root } = renderAndStart();
+
+      elapseFirstFrameWait();
+
+      expect(collectText(findByTestID(root, "si_capture_feedback_text")!)).toBe(
+        enStrings.si_capture_camera_unavailable,
+      );
+    });
+
+    it("leaves the user a way to retry", () => {
+      const { root } = renderAndStart();
+
+      elapseFirstFrameWait();
+
+      const start = findByTestID(root, "si_capture_start_button");
+      expect(start).not.toBeNull();
+      expect(start!.props.enabled).toBe(true);
+    });
+
+    it("reports a terminal timeout so the flow is not left waiting", () => {
+      const onCaptureTimeout = vi.fn();
+      const tree = render(
+        <UseSmileIDCaptureScreen
+          analyzer={fakeAnalyzer}
+          captureType={CaptureType.selfie}
+          onCaptureTimeout={onCaptureTimeout}
+        />,
+      );
+      act(() => {
+        findByTestID(tree.root, "si_capture_start_button")!.props.onClick();
+      });
+
+      elapseFirstFrameWait();
+
+      expect(onCaptureTimeout).toHaveBeenCalledTimes(1);
+    });
+
+    it("drops the stall copy once a frame finally arrives", () => {
+      const { root } = renderAndStart();
+      elapseFirstFrameWait();
+      expect(collectText(findByTestID(root, "si_capture_feedback_text")!)).toBe(
+        enStrings.si_capture_camera_unavailable,
+      );
+
+      act(() => {
+        capturedOnResult!({
+          output: { faces: [], brightness: 0 },
+          state: { type: UseSmileIDScanStateType.Initial },
+          capturedEvents: [],
+        });
+      });
+
+      expect(
+        collectText(findByTestID(root, "si_capture_feedback_text")!),
+      ).not.toBe(enStrings.si_capture_camera_unavailable);
+    });
+
+    it("still fires when the partner passes an inline callback", () => {
+      const onCaptureTimeout = vi.fn();
+      const screen = (
+        <UseSmileIDCaptureScreen
+          analyzer={fakeAnalyzer}
+          captureType={CaptureType.selfie}
+          onCaptureTimeout={(state) => onCaptureTimeout(state)}
+        />
+      );
+      const tree = render(screen);
+      act(() => {
+        findByTestID(tree.root, "si_capture_start_button")!.props.onClick();
+      });
+
+      for (let step = 0; step < 4; step += 1) {
+        act(() => {
+          tree.update(
+            <UseSmileIDCaptureScreen
+              analyzer={fakeAnalyzer}
+              captureType={CaptureType.selfie}
+              onCaptureTimeout={(state) => onCaptureTimeout(state)}
+            />,
+          );
+        });
+        act(() => {
+          vi.advanceTimersByTime(3_000);
+        });
+      }
+
+      expect(onCaptureTimeout).toHaveBeenCalledTimes(1);
+    });
+
+    it("stays quiet once a frame has been analyzed", () => {
+      const onCaptureTimeout = vi.fn();
+      const tree = render(
+        <UseSmileIDCaptureScreen
+          analyzer={fakeAnalyzer}
+          captureType={CaptureType.selfie}
+          onCaptureTimeout={onCaptureTimeout}
+        />,
+      );
+      act(() => {
+        findByTestID(tree.root, "si_capture_start_button")!.props.onClick();
+      });
+      act(() => {
+        capturedOnResult!({
+          output: { faces: [], brightness: 0 },
+          state: { type: UseSmileIDScanStateType.Initial },
+          capturedEvents: [],
+        });
+      });
+
+      elapseFirstFrameWait();
+
+      expect(onCaptureTimeout).not.toHaveBeenCalled();
+      expect(
+        collectText(findByTestID(tree.root, "si_capture_feedback_text")!),
+      ).not.toBe(enStrings.si_capture_camera_unavailable);
+    });
+  });
 });

package/src/presentation/screen/__tests__/use_smile_id_document_back_instructions.test.tsx

@@ -62,7 +62,9 @@ describe("UseSmileIDDocumentBackInstructions", () => {
       />,
     );
     expect(findByTestID(root, "si_document_back_instructions")).not.toBeNull();
-    expect(findTextNode(root, "Flip your Green Book")).not.toBeNull();
+    expect(
+      findTextNode(root, "Flip your \u2068Green Book\u2069"),
+    ).not.toBeNull();
   });
 
   it("invokes onCaptureBack from the primary button", () => {

package/src/presentation/screen/__tests__/use_smile_id_permission_screen.test.tsx

@@ -0,0 +1,68 @@
+import { describe, it, expect } from "vitest";
+import * as React from "react";
+import { create as createRenderer, act } from "react-test-renderer";
+import { UseSmileIDPermissionScreen } from "../use_smile_id_permission_screen";
+import { UseSmileIDThemeProvider } from "../../theme/theme_context";
+import { defaultDarkTheme, defaultLightTheme } from "../../theme/theme";
+
+function render(element: React.ReactElement) {
+  let tree!: ReturnType<typeof createRenderer>;
+  act(() => {
+    tree = createRenderer(element);
+  });
+  return tree;
+}
+
+function rootStyle(
+  tree: ReturnType<typeof createRenderer>,
+): Record<string, unknown> {
+  const json = tree.toJSON() as { props: { style: Record<string, unknown> } };
+  return json.props.style;
+}
+
+describe("UseSmileIDPermissionScreen", () => {
+  it("shows a default camera rationale when the partner supplies none", () => {
+    const tree = render(
+      <UseSmileIDPermissionScreen theme={defaultLightTheme} />,
+    );
+
+    expect(JSON.stringify(tree.toJSON())).toContain(
+      "Camera permission required",
+    );
+  });
+
+  it("shows the partner's rationale when one is supplied", () => {
+    const tree = render(
+      <UseSmileIDPermissionScreen
+        theme={defaultLightTheme}
+        cameraRationale="Acme needs your camera to verify your ID"
+      />,
+    );
+
+    const text = JSON.stringify(tree.toJSON());
+    expect(text).toContain("Acme needs your camera to verify your ID");
+    expect(text).not.toContain("Camera permission required");
+  });
+
+  it("paints on the theme background from the theme prop", () => {
+    const tree = render(
+      <UseSmileIDPermissionScreen theme={defaultDarkTheme} />,
+    );
+
+    expect(rootStyle(tree).backgroundColor).toBe(
+      defaultDarkTheme.colors.background,
+    );
+  });
+
+  it("falls back to the theme from context when no theme prop is given", () => {
+    const tree = render(
+      <UseSmileIDThemeProvider value={defaultDarkTheme}>
+        <UseSmileIDPermissionScreen />
+      </UseSmileIDThemeProvider>,
+    );
+
+    expect(rootStyle(tree).backgroundColor).toBe(
+      defaultDarkTheme.colors.background,
+    );
+  });
+});

package/src/presentation/screen/helpers/capture_screen_helpers.ts

@@ -83,6 +83,7 @@ const FEEDBACK_COPY: Partial<
   si_capture_ready: (loc) => loc.siCaptureReady,
   si_capture_hold_steady: (loc) => loc.siCaptureHoldSteady,
   si_capture_timeout: (loc) => loc.siCaptureTimeout,
+  si_capture_camera_unavailable: (loc) => loc.siCaptureCameraUnavailable,
   si_capturing: (loc) => loc.siCapturing,
   si_selfie_capture_complete: (loc) => loc.siSelfieCaptureComplete,
   si_selfie_capture_timeout: (loc) => loc.siSelfieCaptureTimeout,