@smileid/usesmileid 12.0.1 → 12.1.0

package/src/presentation/flow/__tests__/flow_navigation_manager.test.ts

@@ -1,1212 +0,0 @@
-import { describe, expect, it, vi } from "vitest";
-import {
-  FlowNavigationManager,
-  type CapturedArtifacts,
-  type FlowExitReason,
-  type FlowExitHandler,
-} from "../flow_navigation_manager";
-import {
-  CaptureType,
-  ScreensBuilder,
-  type ScreensConfig,
-} from "../dsl/builder/screens_builder";
-import type { FlowConfigurationSnapshot } from "../dsl/use_smile_id_flow_builder";
-import type { JobRequest } from "../../../data/model/job_request";
-import type { UseSmileIDRepository } from "../../../data/repository/use_smile_id_repository";
-import type { JobSubmissionResponse } from "../../../data/model/job_submission_response";
-import {
-  failure,
-  success,
-  type UseSmileIDResult,
-} from "../../../core/models/result";
-import { JobType } from "../../../core/models/job_type";
-import { DocumentType } from "../../../core/models/document_type";
-import { MissingRequiredFieldException } from "../../../core/exception";
-import type { UseSmileIDAnalyticsEvent } from "../analytics/use_smile_id_analytics_event";
-
-function buildScreens(block: (s: ScreensBuilder) => void): ScreensConfig {
-  const sb = new ScreensBuilder();
-  block(sb);
-  return sb.build();
-}
-
-function buildConfig(
-  screens: ScreensConfig,
-  overrides: Partial<FlowConfigurationSnapshot> = {},
-): FlowConfigurationSnapshot {
-  return {
-    screens,
-    onResult: () => {},
-    ...overrides,
-  };
-}
-
-function makeManager(
-  screens: ScreensConfig,
-  onExit: FlowExitHandler = vi.fn(),
-  extra: Partial<FlowConfigurationSnapshot> = {},
-  repository?: UseSmileIDRepository,
-): FlowNavigationManager {
-  return new FlowNavigationManager({
-    configuration: buildConfig(screens, extra),
-    onExit,
-    ...(repository ? { repository } : {}),
-  });
-}
-
-const consentInfo = Object.freeze({
-  granted: true,
-  grantedAt: "2026-04-30T00:00:00.000Z",
-  noticeLanguage: "EN",
-  noticePrivacyPolicyUrl: "https://example.test/privacy",
-});
-
-const SAMPLE_USER_DETAILS = Object.freeze({
-  givenNames: "Jane",
-  lastName: "Doe",
-  email: "jane@example.test",
-  phoneNumber: "+2348000000000",
-});
-
-describe("FlowNavigationManager — navigation primitives", () => {
-  it("seeds the path with the first configured screen", () => {
-    const manager = makeManager(
-      buildScreens((screens) => {
-        screens.instructions();
-        screens.capture((c) => {
-          c.captureType = CaptureType.selfie;
-        });
-      }),
-    );
-    expect(manager.currentDepth).toBe(0);
-    expect(manager.navigationPath.length).toBe(1);
-    expect(manager.currentScreen?.kind).toBe("instructions");
-    expect(manager.isFirstScreen).toBe(true);
-    expect(manager.isLastScreen).toBe(false);
-  });
-
-  it("navigateToNext() pushes the next configured screen onto the path and notifies subscribers", () => {
-    const onExit = vi.fn();
-    const listener = vi.fn();
-    const manager = makeManager(
-      buildScreens((screens) => {
-        screens.instructions();
-        screens.preview();
-        screens.processing();
-      }),
-      onExit,
-    );
-    manager.subscribe(listener);
-
-    manager.navigateToNext();
-    expect(manager.currentDepth).toBe(1);
-    expect(manager.navigationPath.length).toBe(2);
-    expect(manager.currentScreen?.kind).toBe("preview");
-    expect(listener).toHaveBeenCalledTimes(1);
-
-    manager.navigateToNext();
-    expect(manager.currentDepth).toBe(2);
-    expect(manager.navigationPath.length).toBe(3);
-    expect(manager.currentScreen?.kind).toBe("processing");
-    expect(listener).toHaveBeenCalledTimes(2);
-
-    expect(onExit).not.toHaveBeenCalled();
-  });
-
-  it("navigateToNext() from the last screen calls onExit with completed reason", () => {
-    // Concrete scenario: partner taps "Continue" on the processing
-    // screen (the last screen). The orchestrator submits + notifies
-    // via onResult — pinned via the `completed` exit reason here.
-    const onExit = vi.fn<(reason: FlowExitReason) => void>();
-    const manager = makeManager(
-      buildScreens((screens) => {
-        screens.instructions();
-      }),
-      onExit,
-    );
-    manager.navigateToNext();
-    // No submission in this flow → empty fields on the carrier; the
-    // exit reason still marks the flow as completed.
-    expect(onExit).toHaveBeenCalledWith({
-      kind: "completed",
-      job: { userId: "", jobId: "", status: "", message: "" },
-    });
-    // Path stays at the last screen — the orchestrator drives
-    // unmount, the manager just notifies.
-    expect(manager.currentDepth).toBe(0);
-    expect(manager.navigationPath.length).toBe(1);
-    expect(manager.currentScreen?.kind).toBe("instructions");
-  });
-
-  it("navigateBack() pops the path and notifies subscribers", () => {
-    const manager = makeManager(
-      buildScreens((screens) => {
-        screens.instructions();
-        screens.preview();
-      }),
-    );
-    const listener = vi.fn();
-    manager.subscribe(listener);
-
-    manager.navigateToNext(); // path: [instructions, preview]
-    listener.mockClear();
-    manager.navigateBack();
-
-    expect(manager.currentDepth).toBe(0);
-    expect(manager.navigationPath.length).toBe(1);
-    expect(manager.currentScreen?.kind).toBe("instructions");
-    expect(listener).toHaveBeenCalledTimes(1);
-  });
-
-  it("navigateBack() from the first screen calls onExit with cancelled reason", () => {
-    // Concrete scenario: partner presses Android hardware back on
-    // the first screen. The orchestrator pops out of the flow with
-    // a cancelled result — partner-app router takes over.
-    const onExit = vi.fn<(reason: FlowExitReason) => void>();
-    const manager = makeManager(
-      buildScreens((screens) => {
-        screens.instructions();
-        screens.capture((c) => {
-          c.captureType = CaptureType.selfie;
-        });
-      }),
-      onExit,
-    );
-    manager.navigateBack();
-    expect(onExit).toHaveBeenCalledWith({ kind: "cancelled" });
-    // Path is the source of truth — back at root must leave the path
-    // intact (single-element, depth 0). The orchestrator drives
-    // unmount; the manager must not pop the path empty.
-    expect(manager.currentDepth).toBe(0);
-    expect(manager.navigationPath.length).toBe(1);
-    expect(manager.currentScreen?.kind).toBe("instructions");
-  });
-
-  it("navigateToStart() collapses the path to just the first configured screen", () => {
-    // Concrete scenario: a terminal failure prompts the partner to
-    // restart the flow without tearing down the manager (e.g. retry
-    // selfie capture from the beginning). The path must reset to a
-    // single-element stack pointing at the first configured screen,
-    // regardless of how deep the user was.
-    const manager = makeManager(
-      buildScreens((screens) => {
-        screens.instructions();
-        screens.preview();
-        screens.processing();
-      }),
-    );
-    manager.navigateToNext(); // path: [instructions, preview]
-    manager.navigateToNext(); // path: [instructions, preview, processing]
-    expect(manager.currentDepth).toBe(2);
-
-    const listener = vi.fn();
-    manager.subscribe(listener);
-    manager.navigateToStart();
-
-    expect(manager.currentDepth).toBe(0);
-    expect(manager.navigationPath.length).toBe(1);
-    expect(manager.currentScreen?.kind).toBe("instructions");
-    expect(listener).toHaveBeenCalledTimes(1);
-  });
-
-  it("navigateToStart() from the first screen is a no-op on path state", () => {
-    // Already at the start — calling navigateToStart() must keep the
-    // path at a single-element stack pointing at the first screen.
-    const manager = makeManager(
-      buildScreens((screens) => {
-        screens.instructions();
-        screens.preview();
-      }),
-    );
-    manager.navigateToStart();
-    expect(manager.currentDepth).toBe(0);
-    expect(manager.navigationPath.length).toBe(1);
-    expect(manager.currentScreen?.kind).toBe("instructions");
-  });
-
-  it("exit() calls onExit immediately with the supplied reason", () => {
-    const onExit = vi.fn<(reason: FlowExitReason) => void>();
-    const manager = makeManager(
-      buildScreens((screens) => {
-        screens.processing();
-      }),
-      onExit,
-    );
-    const error = new Error("submission failed");
-    manager.exit({ kind: "failed", error });
-    expect(onExit).toHaveBeenCalledWith({ kind: "failed", error });
-  });
-
-  it("exit() with no argument defaults to cancelled", () => {
-    const onExit = vi.fn<(reason: FlowExitReason) => void>();
-    const manager = makeManager(
-      buildScreens((screens) => {
-        screens.instructions();
-      }),
-      onExit,
-    );
-    manager.exit();
-    expect(onExit).toHaveBeenCalledWith({ kind: "cancelled" });
-  });
-});
-
-describe("FlowNavigationManager — captured artifacts", () => {
-  it("starts with empty livenessPaths and no other artifacts", () => {
-    const manager = makeManager(
-      buildScreens((screens) => screens.instructions()),
-    );
-    expect(manager.captured).toEqual<CapturedArtifacts>({
-      livenessPaths: [],
-    });
-  });
-
-  it("records selfie + liveness paths atomically and freezes the array", () => {
-    // Concrete scenario: a future refactor that mutates
-    // `livenessPaths` after capture would silently change the
-    // submitted images mid-flow. The frozen array is the contract
-    // — the orchestrator sees a stable snapshot.
-    const manager = makeManager(
-      buildScreens((screens) =>
-        screens.capture((c) => {
-          c.captureType = CaptureType.selfie;
-        }),
-      ),
-    );
-    const liveness = ["file:///a.jpg", "file:///b.jpg"];
-    manager.setCapturedSelfie("file:///selfie.jpg", liveness);
-    expect(manager.captured.selfiePath).toBe("file:///selfie.jpg");
-    expect(manager.captured.livenessPaths).toEqual(liveness);
-    expect(Object.isFrozen(manager.captured.livenessPaths)).toBe(true);
-  });
-
-  it("records front + back document paths separately", () => {
-    const manager = makeManager(
-      buildScreens((screens) =>
-        screens.capture((c) => {
-          c.captureType = CaptureType.document;
-        }),
-      ),
-    );
-    manager.setCapturedFrontDocument("file:///front.jpg");
-    expect(manager.captured.frontDocumentPath).toBe("file:///front.jpg");
-    expect(manager.captured.backDocumentPath).toBeUndefined();
-    manager.setCapturedBackDocument("file:///back.jpg");
-    expect(manager.captured.backDocumentPath).toBe("file:///back.jpg");
-    // Front not clobbered.
-    expect(manager.captured.frontDocumentPath).toBe("file:///front.jpg");
-  });
-
-  it("records consent without affecting other artifacts", () => {
-    const manager = makeManager(buildScreens((screens) => screens.consent()));
-    manager.setCapturedSelfie("file:///selfie.jpg", []);
-    manager.setConsent(consentInfo);
-    expect(manager.captured.consentInformation).toEqual(consentInfo);
-    expect(manager.captured.selfiePath).toBe("file:///selfie.jpg");
-  });
-
-  it("notifies subscribers on each artifact recording", () => {
-    const manager = makeManager(
-      buildScreens((screens) =>
-        screens.capture((c) => {
-          c.captureType = CaptureType.selfie;
-        }),
-      ),
-    );
-    const listener = vi.fn();
-    manager.subscribe(listener);
-    manager.setCapturedSelfie("file:///s.jpg", []);
-    manager.setCapturedFrontDocument("file:///f.jpg");
-    manager.setConsent(consentInfo);
-    expect(listener).toHaveBeenCalledTimes(3);
-  });
-});
-
-describe("FlowNavigationManager — subscribe / dispose", () => {
-  it("subscribe() returns an unsubscribe function", () => {
-    const manager = makeManager(
-      buildScreens((screens) => {
-        screens.instructions();
-        screens.processing();
-      }),
-    );
-    const listener = vi.fn();
-    const unsubscribe = manager.subscribe(listener);
-    manager.navigateToNext();
-    expect(listener).toHaveBeenCalledTimes(1);
-    unsubscribe();
-    manager.navigateBack();
-    // Listener should NOT fire after unsubscribe.
-    expect(listener).toHaveBeenCalledTimes(1);
-  });
-
-  it("dispose() drops all listeners and makes navigation methods no-op", () => {
-    // Concrete scenario: the orchestrator unmounts mid-flow (partner
-    // navigated away). After dispose, any in-flight async path
-    // (camera frame, network response) trying to call `navigateToNext()`
-    // must not fire listeners against a stale manager.
-    const onExit = vi.fn();
-    const manager = makeManager(
-      buildScreens((screens) => {
-        screens.instructions();
-        screens.processing();
-      }),
-      onExit,
-    );
-    const listener = vi.fn();
-    manager.subscribe(listener);
-    manager.dispose();
-
-    manager.navigateToNext();
-    manager.navigateBack();
-    manager.exit();
-    manager.setCapturedSelfie("file:///s.jpg", []);
-
-    expect(listener).not.toHaveBeenCalled();
-    expect(onExit).not.toHaveBeenCalled();
-  });
-
-  it("listener errors do not break the dispatch chain", () => {
-    // Concrete scenario: a partner-supplied listener (custom screen
-    // hook) throws on a particular state. The remaining listeners
-    // (including the orchestrator's re-render trigger) must still
-    // fire so the flow keeps running.
-    const manager = makeManager(
-      buildScreens((screens) => {
-        screens.instructions();
-        screens.preview();
-      }),
-    );
-    const buggy = vi.fn(() => {
-      throw new Error("partner listener bug");
-    });
-    const healthy = vi.fn();
-    manager.subscribe(buggy);
-    manager.subscribe(healthy);
-    expect(() => manager.navigateToNext()).not.toThrow();
-    expect(buggy).toHaveBeenCalledTimes(1);
-    expect(healthy).toHaveBeenCalledTimes(1);
-  });
-});
-
-// Submission lifecycle ---------------------------------------------------
-
-const RESPONSE: JobSubmissionResponse = Object.freeze({
-  jobId: "job-1",
-  userId: "user-1",
-  status: "completed",
-  message: "Job completed successfully",
-});
-
-class StubRepository implements UseSmileIDRepository {
-  readonly received: JobRequest[] = [];
-  result: UseSmileIDResult<JobSubmissionResponse> = success(RESPONSE);
-  /** Pending promise so tests can drive the async state transition. */
-  private _resolver:
-    | ((r: UseSmileIDResult<JobSubmissionResponse>) => void)
-    | null = null;
-  /** When true, `submit` returns a manual-resolve promise instead of `result`. */
-  manual = false;
-
-  submit(
-    request: JobRequest,
-  ): Promise<UseSmileIDResult<JobSubmissionResponse>> {
-    this.received.push(request);
-    if (this.manual) {
-      return new Promise((resolve) => {
-        this._resolver = resolve;
-      });
-    }
-    return Promise.resolve(this.result);
-  }
-
-  resolve(result: UseSmileIDResult<JobSubmissionResponse>): void {
-    if (!this._resolver) throw new Error("no pending submit to resolve");
-    const resolver = this._resolver;
-    this._resolver = null;
-    resolver(result);
-  }
-}
-
-describe("FlowNavigationManager — submission lifecycle", () => {
-  it("starts in notAttempted state", () => {
-    const manager = makeManager(
-      buildScreens((screens) => screens.processing()),
-    );
-    expect(manager.jobSubmissionState.kind).toBe("notAttempted");
-  });
-
-  it("beginSubmissionIfNeeded fails with a configured-message when no repository was supplied", async () => {
-    // Concrete scenario: partner mounts <UseSmileIDBuilder> for a
-    // capture-only smoke test (no `b.network(...)`). The processing
-    // screen surfaces the configuration gap rather than spinning
-    // forever.
-    const manager = makeManager(
-      buildScreens((screens) => screens.processing()),
-    );
-    manager.beginSubmissionIfNeeded();
-    await flushMicrotasks();
-    expect(manager.jobSubmissionState.kind).toBe("failure");
-    if (manager.jobSubmissionState.kind === "failure") {
-      expect(manager.jobSubmissionState.error.message).toMatch(
-        /not configured/i,
-      );
-    }
-  });
-
-  it("beginSubmissionIfNeeded transitions notAttempted → loading → success", async () => {
-    const repository = new StubRepository();
-    repository.manual = true;
-    const manager = makeManager(
-      buildScreens((screens) => screens.processing()),
-      vi.fn(),
-      {
-        enhancedKYCParams: {
-          idType: "PASSPORT",
-          idNumber: "X123",
-          country: "NG",
-        },
-        userDetails: SAMPLE_USER_DETAILS,
-        network: {
-          config: {
-            jobType: JobType.enhancedKyc,
-            token: "k",
-            partnerConfig: {
-              partnerId: "p",
-              callbackUrl: "",
-              useSandbox: true,
-            },
-          },
-        },
-      },
-      repository,
-    );
-
-    manager.beginSubmissionIfNeeded();
-    // Synchronous transition to loading happens inside the
-    // microtask-triggering `_submit` before the first await.
-    await flushMicrotasks();
-    expect(manager.jobSubmissionState.kind).toBe("loading");
-
-    repository.resolve(success(RESPONSE));
-    await flushMicrotasks();
-
-    expect(manager.jobSubmissionState.kind).toBe("success");
-    expect(repository.received).toHaveLength(1);
-    expect(repository.received[0]?.jobType).toBe(JobType.enhancedKyc);
-  });
-
-  it("transitions loading → failure on repository error", async () => {
-    const repository = new StubRepository();
-    repository.result = failure(new Error("[503] service unavailable"));
-    const manager = makeManager(
-      buildScreens((screens) => screens.processing()),
-      vi.fn(),
-      {
-        enhancedKYCParams: {
-          idType: "BVN",
-          idNumber: "1",
-          country: "NG",
-        },
-        userDetails: SAMPLE_USER_DETAILS,
-        network: {
-          config: {
-            jobType: JobType.enhancedKyc,
-            token: "k",
-            partnerConfig: {
-              partnerId: "p",
-              callbackUrl: "",
-              useSandbox: true,
-            },
-          },
-        },
-      },
-      repository,
-    );
-
-    manager.beginSubmissionIfNeeded();
-    await flushMicrotasks();
-    expect(manager.jobSubmissionState.kind).toBe("failure");
-  });
-
-  it("beginSubmissionIfNeeded is idempotent — second call while loading is a no-op", async () => {
-    const repository = new StubRepository();
-    repository.manual = true;
-    const manager = makeManager(
-      buildScreens((screens) => screens.processing()),
-      vi.fn(),
-      {
-        enhancedKYCParams: {
-          idType: "BVN",
-          idNumber: "1",
-          country: "NG",
-        },
-        userDetails: SAMPLE_USER_DETAILS,
-        network: {
-          config: {
-            jobType: JobType.enhancedKyc,
-            token: "k",
-            partnerConfig: {
-              partnerId: "p",
-              callbackUrl: "",
-              useSandbox: true,
-            },
-          },
-        },
-      },
-      repository,
-    );
-
-    manager.beginSubmissionIfNeeded();
-    manager.beginSubmissionIfNeeded(); // second call must be ignored
-    await flushMicrotasks();
-    expect(repository.received).toHaveLength(1);
-  });
-
-  it("retrySubmission resets state and re-fires the request", async () => {
-    const repository = new StubRepository();
-    repository.result = failure(new Error("transient"));
-    const manager = makeManager(
-      buildScreens((screens) => screens.processing()),
-      vi.fn(),
-      {
-        enhancedKYCParams: {
-          idType: "BVN",
-          idNumber: "1",
-          country: "NG",
-        },
-        userDetails: SAMPLE_USER_DETAILS,
-        network: {
-          config: {
-            jobType: JobType.enhancedKyc,
-            token: "k",
-            partnerConfig: {
-              partnerId: "p",
-              callbackUrl: "",
-              useSandbox: true,
-            },
-          },
-        },
-      },
-      repository,
-    );
-
-    manager.beginSubmissionIfNeeded();
-    await flushMicrotasks();
-    expect(manager.jobSubmissionState.kind).toBe("failure");
-
-    repository.result = success(RESPONSE);
-    manager.retrySubmission();
-    await flushMicrotasks();
-
-    expect(repository.received).toHaveLength(2);
-    expect(manager.jobSubmissionState.kind).toBe("success");
-  });
-
-  it("retrySubmission double-trigger fires exactly one new submission", async () => {
-    // Concrete scenario: the processing screen's retry button is
-    // double-tapped after a failed submission. The second tap must not
-    // reset the in-flight `loading` latch and launch a duplicate job.
-    const repository = new StubRepository();
-    repository.result = failure(new Error("transient"));
-    const manager = makeManager(
-      buildScreens((screens) => screens.processing()),
-      vi.fn(),
-      {
-        enhancedKYCParams: {
-          idType: "BVN",
-          idNumber: "1",
-          country: "NG",
-        },
-        userDetails: SAMPLE_USER_DETAILS,
-        network: {
-          config: {
-            jobType: JobType.enhancedKyc,
-            token: "k",
-            partnerConfig: {
-              partnerId: "p",
-              callbackUrl: "",
-              useSandbox: true,
-            },
-          },
-        },
-      },
-      repository,
-    );
-
-    // Initial attempt fails, leaving the retry affordance visible.
-    manager.beginSubmissionIfNeeded();
-    await flushMicrotasks();
-    expect(manager.jobSubmissionState.kind).toBe("failure");
-    expect(repository.received).toHaveLength(1);
-
-    // The retried submission stays in flight so both taps land while
-    // the request is loading.
-    repository.manual = true;
-    manager.retrySubmission();
-    manager.retrySubmission(); // double-tap — ignored while in flight
-
-    await flushMicrotasks();
-    expect(manager.jobSubmissionState.kind).toBe("loading");
-    // Exactly one new submission: the initial failure plus one retry.
-    expect(repository.received).toHaveLength(2);
-  });
-
-  it("does not update state if the manager is disposed mid-submission", async () => {
-    const repository = new StubRepository();
-    repository.manual = true;
-    const manager = makeManager(
-      buildScreens((screens) => screens.processing()),
-      vi.fn(),
-      {
-        enhancedKYCParams: {
-          idType: "BVN",
-          idNumber: "1",
-          country: "NG",
-        },
-        userDetails: SAMPLE_USER_DETAILS,
-        network: {
-          config: {
-            jobType: JobType.enhancedKyc,
-            token: "k",
-            partnerConfig: {
-              partnerId: "p",
-              callbackUrl: "",
-              useSandbox: true,
-            },
-          },
-        },
-      },
-      repository,
-    );
-
-    manager.beginSubmissionIfNeeded();
-    await flushMicrotasks();
-    expect(manager.jobSubmissionState.kind).toBe("loading");
-
-    manager.dispose();
-    repository.resolve(success(RESPONSE));
-    await flushMicrotasks();
-    // State frozen at loading — no use-after-dispose write.
-    expect(manager.jobSubmissionState.kind).toBe("loading");
-  });
-
-  it("transitions to failure when the configured job type is unset", async () => {
-    const repository = new StubRepository();
-    const manager = makeManager(
-      buildScreens((screens) => screens.processing()),
-      vi.fn(),
-      {
-        // network present (so repository is wired) but jobType omitted
-        network: {
-          config: {
-            token: "k",
-            partnerConfig: {
-              partnerId: "p",
-              callbackUrl: "",
-              useSandbox: true,
-            },
-          },
-        },
-      },
-      repository,
-    );
-    manager.beginSubmissionIfNeeded();
-    await flushMicrotasks();
-    expect(manager.jobSubmissionState.kind).toBe("failure");
-    expect(repository.received).toHaveLength(0);
-  });
-});
-
-describe("FlowNavigationManager — request assembly per JobType", () => {
-  function assembleRequest(
-    jobType: JobType,
-    extraConfig: Partial<FlowConfigurationSnapshot> = {},
-    seedManager: (m: FlowNavigationManager) => void = () => {},
-  ): JobRequest {
-    const repository = new StubRepository();
-    const manager = makeManager(
-      buildScreens((screens) => screens.processing()),
-      vi.fn(),
-      {
-        ...extraConfig,
-        network: {
-          config: {
-            jobType,
-            token: "k",
-            partnerConfig: {
-              partnerId: "p",
-              callbackUrl: "",
-              useSandbox: true,
-            },
-          },
-        },
-      },
-      repository,
-    );
-    seedManager(manager);
-    manager.beginSubmissionIfNeeded();
-    return repository.received[0]!;
-  }
-
-  it("smartSelfieEnrollment uses captured selfie + liveness", () => {
-    const request = assembleRequest(
-      JobType.smartSelfieEnrollment,
-      { userDetails: SAMPLE_USER_DETAILS },
-      (m) => {
-        m.setCapturedSelfie("file:///selfie.jpg", ["file:///l1.jpg"]);
-        m.setConsent(consentInfo);
-      },
-    );
-    expect(request.jobType).toBe(JobType.smartSelfieEnrollment);
-    if (request.jobType === JobType.smartSelfieEnrollment) {
-      expect(request.selfieImage).toBe("file:///selfie.jpg");
-      expect(request.livenessImages).toEqual(["file:///l1.jpg"]);
-      expect(request.consent).toEqual(consentInfo);
-      expect(request.userDetails).toEqual(SAMPLE_USER_DETAILS);
-    }
-  });
-
-  it("smartSelfieAuthentication uses captured selfie + liveness", () => {
-    const request = assembleRequest(
-      JobType.smartSelfieAuthentication,
-      { userDetails: SAMPLE_USER_DETAILS, userId: "prior-enrollment-user-id" },
-      (m) => m.setCapturedSelfie("file:///s.jpg", []),
-    );
-    expect(request.jobType).toBe(JobType.smartSelfieAuthentication);
-    if (request.jobType === JobType.smartSelfieAuthentication) {
-      expect(request.userDetails).toEqual(SAMPLE_USER_DETAILS);
-      expect(request.userId).toBe("prior-enrollment-user-id");
-    }
-  });
-
-  it("documentVerification carries front + back paths, country, idType, and userDetails", () => {
-    const request = assembleRequest(
-      JobType.documentVerification,
-      {
-        documentVerificationParams: { country: "KE", idType: "NATIONAL_ID" },
-        userDetails: SAMPLE_USER_DETAILS,
-      },
-      (m) => {
-        m.setCapturedSelfie("file:///s.jpg", []);
-        m.setCapturedFrontDocument("file:///front.jpg");
-        m.setCapturedBackDocument("file:///back.jpg");
-      },
-    );
-    expect(request.jobType).toBe(JobType.documentVerification);
-    if (request.jobType === JobType.documentVerification) {
-      expect(request.frontDocument).toBe("file:///front.jpg");
-      expect(request.backDocument).toBe("file:///back.jpg");
-      expect(request.country).toBe("KE");
-      expect(request.idType).toBe("NATIONAL_ID");
-      expect(request.userDetails).toEqual(SAMPLE_USER_DETAILS);
-    }
-  });
-
-  it("documentVerification omits idType when the params leave it unset", () => {
-    const request = assembleRequest(
-      JobType.documentVerification,
-      {
-        documentVerificationParams: { country: "KE" },
-        userDetails: SAMPLE_USER_DETAILS,
-      },
-      (m) => {
-        m.setCapturedSelfie("file:///s.jpg", []);
-        m.setCapturedFrontDocument("file:///front.jpg");
-      },
-    );
-    expect(request.jobType).toBe(JobType.documentVerification);
-    if (request.jobType === JobType.documentVerification) {
-      expect(request.idType).toBeUndefined();
-      expect(request.country).toBe("KE");
-    }
-  });
-
-  it("enhancedDocumentVerification produces a distinct request kind with required idType", () => {
-    // Parity with Android / iOS / Flutter — the enhanced variant lands
-    // on its own JobRequest kind (and its own repository dispatch case)
-    // rather than discriminating via a boolean flag on the base kind.
-    const request = assembleRequest(
-      JobType.enhancedDocumentVerification,
-      {
-        enhancedDocumentVerificationParams: {
-          country: "ZA",
-          idType: "PASSPORT",
-        },
-        userDetails: SAMPLE_USER_DETAILS,
-      },
-      (m) => {
-        m.setCapturedSelfie("file:///s.jpg", []);
-        m.setCapturedFrontDocument("file:///front.jpg");
-      },
-    );
-    expect(request.jobType).toBe(JobType.enhancedDocumentVerification);
-    if (request.jobType === JobType.enhancedDocumentVerification) {
-      expect(request.frontDocument).toBe("file:///front.jpg");
-      expect(request.backDocument).toBeUndefined();
-      expect(request.country).toBe("ZA");
-      expect(request.idType).toBe("PASSPORT");
-      expect(request.userDetails).toEqual(SAMPLE_USER_DETAILS);
-    }
-  });
-
-  it("biometricKyc carries id fields and top-level userDetails", () => {
-    const request = assembleRequest(
-      JobType.biometricKyc,
-      {
-        biometricKYCParams: {
-          idType: "PASSPORT",
-          idNumber: "P1",
-          country: "NG",
-          useEnrolledImage: false,
-        },
-        userDetails: {
-          givenNames: "Jane",
-          lastName: "Doe",
-          email: "jane@example.test",
-          phoneNumber: "+2348000000000",
-        },
-      },
-      (m) => m.setCapturedSelfie("file:///s.jpg", []),
-    );
-    expect(request.jobType).toBe(JobType.biometricKyc);
-    if (request.jobType === JobType.biometricKyc) {
-      expect(request.params.idNumber).toBe("P1");
-      expect(request.params.country).toBe("NG");
-      expect(request.userDetails.givenNames).toBe("Jane");
-      expect(request.userDetails.email).toBe("jane@example.test");
-    }
-  });
-
-  it("enhancedKyc carries enhancedKYCParams plus top-level userDetails", () => {
-    const request = assembleRequest(JobType.enhancedKyc, {
-      enhancedKYCParams: {
-        idType: "PASSPORT",
-        idNumber: "X1",
-        country: "NG",
-      },
-      userDetails: SAMPLE_USER_DETAILS,
-    });
-    expect(request.jobType).toBe(JobType.enhancedKyc);
-    if (request.jobType === JobType.enhancedKyc) {
-      expect(request.params.idType).toBe("PASSPORT");
-      expect(request.userDetails).toEqual(SAMPLE_USER_DETAILS);
-    }
-  });
-
-  it("bvn dispatches through a dedicated `bvn` request variant", () => {
-    // Concrete scenario: BVN no longer auto-maps onto the
-    // `/v3/enhanced_kyc` endpoint. The flow navigation manager now
-    // emits a dedicated `bvn` request kind; the repository rejects it
-    // with "BVN submission is not yet supported" until the dedicated
-    // endpoint lands.
-    const request = assembleRequest(JobType.bvn, {
-      enhancedKYCParams: {
-        idType: "BVN",
-        idNumber: "12345678901",
-        country: "NG",
-      },
-      userDetails: SAMPLE_USER_DETAILS,
-    });
-    expect(request.jobType).toBe(JobType.bvn);
-    if (request.jobType === JobType.bvn) {
-      expect(request.params.idType).toBe("BVN");
-      expect(request.params.country).toBe("NG");
-    }
-  });
-
-  it("captured consent wins over configuration-supplied consent", () => {
-    const configured = Object.freeze({
-      granted: false,
-      grantedAt: "2026-01-01T00:00:00.000Z",
-      noticeLanguage: "FR",
-      noticePrivacyPolicyUrl: "https://configured.test/privacy",
-    });
-    const request = assembleRequest(
-      JobType.enhancedKyc,
-      {
-        consentInformation: configured,
-        enhancedKYCParams: {
-          idType: "BVN",
-          idNumber: "1",
-          country: "NG",
-        },
-        userDetails: SAMPLE_USER_DETAILS,
-      },
-      (m) => m.setConsent(consentInfo),
-    );
-    expect(request.consent).toEqual(consentInfo);
-  });
-});
-
-describe("FlowNavigationManager — typed missing-field validation (parity)", () => {
-  // Drives a submission to its failure state and returns the surfaced
-  // error so we can assert the typed `MissingRequiredFieldException`
-  // (with the right `fieldName`) reaches `onResult.failure` — matching
-  // the native SDKs, which throw the typed class for every missing field.
-  async function failureError(
-    jobType: JobType,
-    extraConfig: Partial<FlowConfigurationSnapshot> = {},
-    seedManager: (m: FlowNavigationManager) => void = () => {},
-  ): Promise<unknown> {
-    const repository = new StubRepository();
-    const manager = makeManager(
-      buildScreens((screens) => screens.processing()),
-      vi.fn(),
-      {
-        ...extraConfig,
-        network: {
-          config: {
-            jobType,
-            token: "k",
-            partnerConfig: {
-              partnerId: "p",
-              callbackUrl: "",
-              useSandbox: true,
-            },
-          },
-        },
-      },
-      repository,
-    );
-    seedManager(manager);
-    manager.beginSubmissionIfNeeded();
-    await flushMicrotasks();
-    const state = manager.jobSubmissionState;
-    if (state.kind !== "failure") {
-      throw new Error(`expected failure state, got ${state.kind}`);
-    }
-    expect(repository.received).toHaveLength(0);
-    return state.error;
-  }
-
-  it("missing enhancedKYCParams → MissingRequiredFieldException(enhancedKYCParams)", async () => {
-    const error = await failureError(JobType.enhancedKyc, {
-      userDetails: SAMPLE_USER_DETAILS,
-    });
-    expect(error).toBeInstanceOf(MissingRequiredFieldException);
-    expect((error as MissingRequiredFieldException).errorDetails).toEqual({
-      fieldName: "enhancedKYCParams",
-    });
-  });
-
-  it("missing userDetails → MissingRequiredFieldException(userDetails)", async () => {
-    const error = await failureError(JobType.enhancedKyc, {
-      enhancedKYCParams: { idType: "PASSPORT", idNumber: "X1", country: "NG" },
-    });
-    expect(error).toBeInstanceOf(MissingRequiredFieldException);
-    expect((error as MissingRequiredFieldException).errorDetails).toEqual({
-      fieldName: "userDetails",
-    });
-  });
-
-  it("missing selfie → MissingRequiredFieldException(selfieImage)", async () => {
-    const error = await failureError(JobType.biometricKyc, {
-      biometricKYCParams: {
-        idType: "PASSPORT",
-        idNumber: "P1",
-        country: "NG",
-        useEnrolledImage: false,
-      },
-      userDetails: SAMPLE_USER_DETAILS,
-    });
-    expect(error).toBeInstanceOf(MissingRequiredFieldException);
-    expect((error as MissingRequiredFieldException).errorDetails).toEqual({
-      fieldName: "selfieImage",
-    });
-  });
-
-  it("missing front document → MissingRequiredFieldException(frontDocument)", async () => {
-    const error = await failureError(JobType.documentVerification, {}, (m) =>
-      m.setCapturedSelfie("file:///s.jpg", []),
-    );
-    expect(error).toBeInstanceOf(MissingRequiredFieldException);
-    expect((error as MissingRequiredFieldException).errorDetails).toEqual({
-      fieldName: "frontDocument",
-    });
-  });
-
-  it("missing documentVerificationParams → MissingRequiredFieldException(documentVerificationParams)", async () => {
-    const error = await failureError(
-      JobType.documentVerification,
-      { userDetails: SAMPLE_USER_DETAILS },
-      (m) => {
-        m.setCapturedSelfie("file:///s.jpg", []);
-        m.setCapturedFrontDocument("file:///front.jpg");
-      },
-    );
-    expect(error).toBeInstanceOf(MissingRequiredFieldException);
-    expect((error as MissingRequiredFieldException).errorDetails).toEqual({
-      fieldName: "documentVerificationParams",
-    });
-  });
-
-  it("missing enhancedDocumentVerificationParams → MissingRequiredFieldException(enhancedDocumentVerificationParams)", async () => {
-    const error = await failureError(
-      JobType.enhancedDocumentVerification,
-      { userDetails: SAMPLE_USER_DETAILS },
-      (m) => {
-        m.setCapturedSelfie("file:///s.jpg", []);
-        m.setCapturedFrontDocument("file:///front.jpg");
-      },
-    );
-    expect(error).toBeInstanceOf(MissingRequiredFieldException);
-    expect((error as MissingRequiredFieldException).errorDetails).toEqual({
-      fieldName: "enhancedDocumentVerificationParams",
-    });
-  });
-});
-
-describe("FlowNavigationManager — analytics (parity)", () => {
-  function captureEvents(): {
-    readonly events: UseSmileIDAnalyticsEvent[];
-    readonly manager: FlowNavigationManager;
-  } {
-    const events: UseSmileIDAnalyticsEvent[] = [];
-    const manager = makeManager(
-      buildScreens((screens) => {
-        screens.instructions();
-        screens.capture((c) => {
-          c.captureType = CaptureType.selfie;
-        });
-        screens.processing();
-      }),
-      vi.fn(),
-      { onAnalyticsEvent: (event) => events.push(event) },
-    );
-    return { events, manager };
-  }
-
-  it("emits flow_started then screen_viewed on construction, each with session_id + timestamp", () => {
-    const { events } = captureEvents();
-    expect(events.map((e) => e.type)).toEqual([
-      "flow_started",
-      "screen_viewed",
-    ]);
-    expect(events[0]?.extras.job_type).toBeDefined();
-    expect(events[1]?.extras.screen_name).toBe("instructions");
-    for (const event of events) {
-      expect(event.extras.session_id).toBeTruthy();
-      expect(event.extras.timestamp).toBeTruthy();
-    }
-  });
-
-  it("emits consent_captured / selfie_captured / screen_viewed at the lifecycle points", () => {
-    const { events, manager } = captureEvents();
-    events.length = 0;
-
-    manager.setConsent({
-      granted: true,
-      grantedAt: "2026-01-01T00:00:00.000Z",
-      noticeLanguage: "EN",
-      noticePrivacyPolicyUrl: "",
-    });
-    manager.setCapturedSelfie("file:///s.jpg", [
-      "file:///l1.jpg",
-      "file:///l2.jpg",
-    ]);
-    manager.navigateToNext();
-
-    const consent = events.find((e) => e.type === "consent_captured");
-    expect(consent?.extras.decision).toBe("granted");
-    const selfie = events.find((e) => e.type === "selfie_captured");
-    expect(selfie?.extras.liveness_image_count).toBe("2");
-    const viewed = events.find(
-      (e) => e.type === "screen_viewed" && e.extras.screen_name === "capture",
-    );
-    expect(viewed).toBeDefined();
-  });
-
-  it("emits flow_completed=failure with error_message on a failed exit", () => {
-    const { events, manager } = captureEvents();
-    events.length = 0;
-    manager.exit({ kind: "failed", error: new Error("boom") });
-    const completed = events.find((e) => e.type === "flow_completed");
-    expect(completed?.extras.result).toBe("failure");
-    expect(completed?.extras.error_message).toBe("boom");
-  });
-
-  it("emits flow_completed=success with job_id on a completed exit", () => {
-    const { events, manager } = captureEvents();
-    events.length = 0;
-    manager.exit({
-      kind: "completed",
-      job: { userId: "u", jobId: "job-9", status: "ok", message: "" },
-    });
-    const completed = events.find((e) => e.type === "flow_completed");
-    expect(completed?.extras.result).toBe("success");
-    expect(completed?.extras.job_id).toBe("job-9");
-  });
-
-  it("emits no flow_completed on a cancelled exit (parity with native)", () => {
-    const { events, manager } = captureEvents();
-    events.length = 0;
-    manager.exit({ kind: "cancelled" });
-    expect(events.some((e) => e.type === "flow_completed")).toBe(false);
-  });
-});
-
-// Microtask flusher — vitest's default scheduler runs Promise.resolve()
-// jobs synchronously when awaited. Two passes covers chains like
-// `_submit` (sets loading → awaits repo → sets success), so by the
-// second flush both transitions have committed.
-async function flushMicrotasks(): Promise<void> {
-  await Promise.resolve();
-  await Promise.resolve();
-}
-
-describe("FlowNavigationManager.enhancedLivenessEnabled", () => {
-  it("is false when no selfie capture step enables enhanced liveness", () => {
-    const manager = makeManager(
-      buildScreens((s) => {
-        s.instructions();
-        s.capture((c) => c.selfie(() => {}));
-      }),
-    );
-    expect(manager.enhancedLivenessEnabled).toBe(false);
-  });
-
-  it("is true when a selfie capture step enables enhanced liveness", () => {
-    const manager = makeManager(
-      buildScreens((s) => {
-        s.capture((c) =>
-          c.selfie((selfie) => {
-            selfie.enableEnhancedLiveness = true;
-          }),
-        );
-      }),
-    );
-    expect(manager.enhancedLivenessEnabled).toBe(true);
-  });
-
-  it("is false for a document-only flow", () => {
-    const manager = makeManager(
-      buildScreens((s) => {
-        s.capture((c) => c.document(() => {}));
-      }),
-    );
-    expect(manager.enhancedLivenessEnabled).toBe(false);
-  });
-
-  it("documentType reflects the document capture step's configured type", () => {
-    const manager = makeManager(
-      buildScreens((s) => {
-        s.capture((c) => {
-          c.captureType = CaptureType.document;
-          c.document((d) => {
-            d.documentType = DocumentType.SouthAfricaGreenBook;
-          });
-        });
-      }),
-    );
-    expect(manager.documentType).toBe(DocumentType.SouthAfricaGreenBook);
-  });
-
-  it("documentType is undefined for a selfie-only flow", () => {
-    const manager = makeManager(
-      buildScreens((s) => {
-        s.capture((c) => c.selfie(() => {}));
-      }),
-    );
-    expect(manager.documentType).toBeUndefined();
-  });
-});