@smileid/usesmileid 12.0.0-beta01

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

@@ -0,0 +1,1163 @@
+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("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();
+  });
+});