@smileid/usesmileid 12.0.0-beta01

package/src/presentation/flow/flow_navigation_manager.ts

@@ -0,0 +1,985 @@
+import type { ScreenSpec } from "./dsl/builder/screens_builder";
+import type { FlowConfigurationSnapshot } from "./dsl/use_smile_id_flow_builder";
+import type { JobSubmissionState } from "./job_submission_state";
+import type {
+  DocumentVerificationRequest,
+  EnhancedDocumentVerificationRequest,
+  JobRequest,
+} from "../../data/model/job_request";
+import type { UseSmileIDRepository } from "../../data/repository/use_smile_id_repository";
+import type {
+  ConsentInformation,
+  DocumentVerificationParams,
+  EnhancedDocumentVerificationParams,
+  UserDetails,
+} from "../../core/models/params";
+import { JobType } from "../../core/models/job_type";
+import { CaptureType } from "../../core/models/ml_config";
+import type { DocumentType } from "../../core/models/document_type";
+import type { JobSubmissionResponse } from "../../data/model/job_submission_response";
+import { MissingRequiredFieldException } from "../../core/exception/job_validation_exceptions";
+import {
+  UseSmileIDAnalyticsEventTypes,
+  UseSmileIDAnalyticsParamKeys,
+  UseSmileIDAnalyticsScreenNames,
+  type UseSmileIDAnalyticsEventType,
+} from "./analytics/use_smile_id_analytics_event";
+import type {
+  MetadataEntry,
+  UseSmileIDMetadata,
+} from "../../metadata/use_smile_id_metadata";
+import {
+  UseSmileIDMetadataFactory,
+  type MetadataProvider,
+} from "../../metadata/use_smile_id_metadata_factory";
+import {
+  DOCUMENT_BACK_IMAGE_ORIGIN_KEY,
+  DOCUMENT_FRONT_IMAGE_ORIGIN_KEY,
+  type DocumentImageOrigin,
+} from "../../metadata/document_image_origin";
+import type { SdkConfig } from "../../data/model/sdk_config";
+import { numSamplesOverride } from "../../data/model/sdk_config";
+import { decodeSmileIDToken } from "../../data/util/use_smile_id_token_decoder";
+import {
+  DocumentSide,
+  EnhancedSmartSelfieConfig,
+} from "@smileid/usesmileid_bridge";
+import { ScanPerformanceProfile } from "@smileid/usesmileid_bridge";
+
+/**
+ * Internal flow navigation manager — owns the screen cursor, captured
+ * artifacts, navigation primitives, job submission lifecycle, and a
+ * subscribe pattern for React re-renders.
+ *
+ * Custom (not Expo Router / React Navigation) because screens are
+ * partner-configurable via the DSL, not file-based routes; forcing a
+ * routing library would conflict with the partner's own app routing.
+ */
+type Listener = () => void;
+
+export type CapturedArtifacts = {
+  readonly selfiePath?: string;
+  readonly livenessPaths: readonly string[];
+  readonly frontDocumentPath?: string;
+  readonly backDocumentPath?: string;
+  readonly consentInformation?: ConsentInformation;
+};
+
+export type FlowExitReason =
+  | { readonly kind: "completed"; readonly job: JobSubmissionResponse }
+  | { readonly kind: "cancelled" }
+  | { readonly kind: "failed"; readonly error: unknown };
+
+export type FlowExitHandler = (reason: FlowExitReason) => void;
+
+export type FlowNavigationManagerOptions = {
+  readonly configuration: FlowConfigurationSnapshot;
+  readonly onExit: FlowExitHandler;
+  /**
+   * Dispatches the assembled `JobRequest`. Optional so capture-only /
+   * UI-only harnesses (no `b.network(...)`) can still mount. When
+   * absent, `beginSubmissionIfNeeded()` goes straight to a descriptive
+   * `failure` rather than spinning forever.
+   */
+  readonly repository?: UseSmileIDRepository;
+  /**
+   * Per-flow metadata provider; each `JobRequest` carries a fresh
+   * `metadata` snapshot via `make()`. Optional — capture-only harnesses
+   * fall back to a default factory. Production passes the same provider
+   * the networking factory created so `session_id` stays stable across
+   * every submission in the flow.
+   */
+  readonly metadataProvider?: MetadataProvider;
+};
+
+const DEFAULT_CONSENT: ConsentInformation = Object.freeze({
+  granted: false,
+  grantedAt: "",
+  noticeLanguage: "",
+  noticePrivacyPolicyUrl: "",
+});
+
+export class FlowNavigationManager {
+  /**
+   * Navigation stack and source of truth — top is the active screen.
+   * Active screen + first/last predicates derive from this path (no
+   * parallel index). Mutated only via the navigate* methods.
+   */
+  private _navigationPath: ScreenSpec[] = [];
+  private _captured: CapturedArtifacts = { livenessPaths: [] };
+  /**
+   * Set once the partner skips the document back side via the flip
+   * interstitial. Routes `getNextScreen()` past the back capture's preview so
+   * submission proceeds with `backDocument` unset. Cleared when the front is
+   * retaken.
+   */
+  private _documentBackSkipped = false;
+  /**
+   * How each captured document side was produced (auto / manual / gallery).
+   * Emitted as `DocumentFront/BackImageOrigin` submission metadata; an entry is
+   * removed when its side is retaken.
+   */
+  private readonly _documentImageOrigins = new Map<
+    DocumentSide,
+    DocumentImageOrigin
+  >();
+  private _jobSubmissionState: JobSubmissionState = { kind: "notAttempted" };
+  private readonly _listeners = new Set<Listener>();
+  private readonly _steps: readonly ScreenSpec[];
+  private readonly _configuration: FlowConfigurationSnapshot;
+  private readonly _repository: UseSmileIDRepository | undefined;
+  private readonly _metadataProvider: MetadataProvider;
+  private readonly _onExit: FlowExitHandler;
+  private _disposed = false;
+  private _submissionResponse: JobSubmissionResponse | undefined;
+
+  /**
+   * Decoded `sdk_config` JWT claim, resolved once at construction.
+   * `undefined` for offline mode / no token / no valid claim — SDK
+   * defaults apply throughout the flow in those cases.
+   */
+  readonly resolvedSdkConfig: SdkConfig | undefined;
+
+  /** Stable per-flow session id, stamped into every analytics event's `session_id`. */
+  private readonly _sessionId: string;
+
+  /** Submission attempts so far — stamped into `job_submitted` as `attempt`. */
+  private _submissionAttemptCount = 0;
+
+  constructor(options: FlowNavigationManagerOptions) {
+    this._configuration = options.configuration;
+    this._steps = options.configuration.screens.steps;
+    this._onExit = options.onExit;
+    this._repository = options.repository;
+    // Fall back to a fresh factory so capture-only harnesses still build
+    // well-formed requests; the factory reads expo-device lazily and
+    // degrades to empty values when the peer dep is absent.
+    this._metadataProvider =
+      options.metadataProvider ?? new UseSmileIDMetadataFactory();
+    this._sessionId = this._metadataProvider.sessionId;
+    this.resolvedSdkConfig = FlowNavigationManager._decodeSdkConfig(
+      options.configuration,
+    );
+    // Seed the path with the first screen so currentScreen/renderer have a
+    // deterministic start. Empty path → host renders the "no screens"
+    // sentinel (validation rejects empty screens at build time anyway).
+    const firstScreen = this._steps[0];
+    if (firstScreen) {
+      this._navigationPath = [firstScreen];
+    }
+    this._logEvent(UseSmileIDAnalyticsEventTypes.flowStarted, {
+      [UseSmileIDAnalyticsParamKeys.jobType]: this._jobTypeName(),
+    });
+    if (firstScreen) {
+      this._logEvent(UseSmileIDAnalyticsEventTypes.screenViewed, {
+        [UseSmileIDAnalyticsParamKeys.screenName]:
+          this._screenAnalyticsName(firstScreen),
+      });
+    }
+  }
+
+  get configuration(): FlowConfigurationSnapshot {
+    return this._configuration;
+  }
+
+  /** Whether any selfie step enabled Enhanced Smart Selfie (drives the instructions hero swap and oval-progress suppression). */
+  get enhancedLivenessEnabled(): boolean {
+    return this._steps.some(
+      (step) =>
+        step.kind === "capture" &&
+        step.config.selfieConfig?.enableEnhancedLiveness === true,
+    );
+  }
+
+  /** Document type from the flow's document capture step, if any (drives the instructions document variant). */
+  get documentType(): DocumentType | undefined {
+    for (const step of this._steps) {
+      if (
+        step.kind === "capture" &&
+        step.config.captureType === CaptureType.document
+      ) {
+        return step.config.documentConfig?.documentType;
+      }
+    }
+    return undefined;
+  }
+
+  // --- navigation path --------------------------------------------------
+
+  /** Read-only navigation stack; top is the active screen. */
+  get navigationPath(): readonly ScreenSpec[] {
+    return this._navigationPath;
+  }
+
+  /** Active screen (top of the path); `undefined` only when no screens are configured. */
+  get currentScreen(): ScreenSpec | undefined {
+    return this._navigationPath[this._navigationPath.length - 1];
+  }
+
+  /**
+   * Depth of the active screen — stable id for React view identity so
+   * stack frames at the same configured-screen position stay distinct.
+   */
+  get currentDepth(): number {
+    return this._navigationPath.length - 1;
+  }
+
+  get isFirstScreen(): boolean {
+    return this._navigationPath.length <= 1;
+  }
+
+  get isLastScreen(): boolean {
+    return this.getNextScreen() === undefined;
+  }
+
+  /** Next screen `navigateToNext()` would land on; `undefined` at the terminal screen. */
+  getNextScreen(): ScreenSpec | undefined {
+    const current = this.currentScreen;
+    if (!current) return undefined;
+    const currentIdx = this._steps.indexOf(current);
+    if (currentIdx < 0) return undefined;
+
+    // Per-side document loop: after previewing the FRONT, route back to the
+    // document capture step to capture the BACK. Gated so it fires only on a
+    // document preview with the back still pending and not skipped — the back
+    // preview (back already captured) falls through to the linear next step.
+    if (
+      current.kind === "preview" &&
+      this._precedingStepIsDocumentCapture(currentIdx) &&
+      this.documentCapturesBack() &&
+      this._captured.backDocumentPath === undefined &&
+      !this._documentBackSkipped
+    ) {
+      const documentCapture = this._steps[currentIdx - 1];
+      if (documentCapture !== undefined) return documentCapture;
+    }
+
+    // Back skipped at the interstitial: skip the document preview that would
+    // otherwise follow the capture and advance past it (no back to preview).
+    if (
+      current.kind === "capture" &&
+      current.config.captureType === CaptureType.document &&
+      this._documentBackSkipped
+    ) {
+      const next = this._steps[currentIdx + 1];
+      if (next?.kind === "preview") return this._steps[currentIdx + 2];
+    }
+
+    return this._steps[currentIdx + 1];
+  }
+
+  /**
+   * Advance to the next screen. Past the last screen, exits via `onExit`
+   * `{ kind: 'completed', job }` (job is the successful response, or an
+   * empty-fields stand-in for flows with no processing screen).
+   *
+   * Advancing into a `processing` screen sets `loading` synchronously
+   * before the async submit, closing the race with the screen's
+   * mount-time `beginSubmissionIfNeeded()` so it never flashes
+   * `notAttempted`.
+   */
+  navigateToNext(): void {
+    if (this._disposed) return;
+    const nextScreen = this.getNextScreen();
+    if (!nextScreen) {
+      // Past the last screen: deliver the stored success response,
+      // surface a failure, else the empty-fields completed carrier
+      // (flows with no processing screen still get `completed`).
+      const state = this._jobSubmissionState;
+      if (this._submissionResponse) {
+        this._finishFlow({ kind: "completed", job: this._submissionResponse });
+        return;
+      }
+      if (state.kind === "failure") {
+        this._finishFlow({ kind: "failed", error: state.error });
+        return;
+      }
+      const job: JobSubmissionResponse =
+        state.kind === "success"
+          ? state.response
+          : { userId: "", jobId: "", status: "", message: "" };
+      this._finishFlow({ kind: "completed", job });
+      return;
+    }
+    this._navigationPath = [...this._navigationPath, nextScreen];
+    this._logEvent(UseSmileIDAnalyticsEventTypes.screenViewed, {
+      [UseSmileIDAnalyticsParamKeys.screenName]:
+        this._screenAnalyticsName(nextScreen),
+    });
+    // Mark loading synchronously so the processing screen's mount-time
+    // beginSubmissionIfNeeded() sees the transition has started — guards
+    // the brief notAttempted flash before the async submit is scheduled.
+    if (
+      nextScreen.kind === "processing" &&
+      this._jobSubmissionState.kind === "notAttempted" &&
+      this._repository !== undefined
+    ) {
+      this._jobSubmissionState = { kind: "loading" };
+    }
+    this._notify();
+    if (
+      nextScreen.kind === "processing" &&
+      this._jobSubmissionState.kind === "loading" &&
+      this._repository !== undefined
+    ) {
+      // Macrotask defer so React paints the loading processing screen
+      // before _submit blocks the JS thread with request assembly +
+      // signing. The pre-set loading keeps beginSubmissionIfNeeded() a
+      // no-op, so it still submits exactly once.
+      setTimeout(() => {
+        if (this._disposed) return;
+        void this._submit();
+      }, 0);
+    }
+  }
+
+  /** Pop the active screen; from the first screen, exits via `onExit` `{ kind: 'cancelled' }`. */
+  navigateBack(): void {
+    if (this._disposed) return;
+    if (this.isFirstScreen) {
+      this._onExit({ kind: "cancelled" });
+      return;
+    }
+    // Going back from a non-first screen is a retake of the prior step.
+    this._logEvent(UseSmileIDAnalyticsEventTypes.retakeRequested);
+    this._navigationPath = this._navigationPath.slice(0, -1);
+    this._notify();
+  }
+
+  /** Reset the path to the first screen (flow restart after terminal failure, manager kept alive). */
+  navigateToStart(): void {
+    if (this._disposed) return;
+    const firstScreen = this._steps[0];
+    this._navigationPath = firstScreen ? [firstScreen] : [];
+    this._notify();
+  }
+
+  /** Exit the flow with a partner-supplied reason (processing onExit, consent denied, etc.). */
+  exit(reason: FlowExitReason = { kind: "cancelled" }): void {
+    if (this._disposed) return;
+    this._finishFlow(reason);
+  }
+
+  // --- captured artifacts -----------------------------------------------
+
+  get captured(): CapturedArtifacts {
+    return this._captured;
+  }
+
+  setCapturedSelfie(
+    selfiePath: string,
+    livenessPaths: readonly string[],
+  ): void {
+    if (this._disposed) return;
+    this._captured = {
+      ...this._captured,
+      selfiePath,
+      livenessPaths: Object.freeze([...livenessPaths]),
+    };
+    this._logEvent(UseSmileIDAnalyticsEventTypes.selfieCaptured, {
+      [UseSmileIDAnalyticsParamKeys.livenessImageCount]: String(
+        livenessPaths.length,
+      ),
+    });
+    this._notify();
+  }
+
+  setCapturedFrontDocument(path: string): void {
+    if (this._disposed) return;
+    this._captured = { ...this._captured, frontDocumentPath: path };
+    this._logEvent(UseSmileIDAnalyticsEventTypes.documentCaptured, {
+      [UseSmileIDAnalyticsParamKeys.documentSide]: "front",
+    });
+    this._notify();
+  }
+
+  setCapturedBackDocument(path: string): void {
+    if (this._disposed) return;
+    this._captured = { ...this._captured, backDocumentPath: path };
+    // `both` is the single completion-event value for a two-sided capture.
+    this._logEvent(UseSmileIDAnalyticsEventTypes.documentCaptured, {
+      [UseSmileIDAnalyticsParamKeys.documentSide]: "both",
+    });
+    this._notify();
+  }
+
+  // --- document per-side preview loop -----------------------------------
+
+  /** Whether the configured document capture asks for a back side. */
+  documentCapturesBack(): boolean {
+    for (const step of this._steps) {
+      if (
+        step.kind === "capture" &&
+        step.config.captureType === CaptureType.document
+      ) {
+        const documentConfig = step.config.documentConfig;
+        return (
+          documentConfig?.documentType?.hasBackSide === true &&
+          (documentConfig?.captureBothSides ?? false)
+        );
+      }
+    }
+    return false;
+  }
+
+  /** Whether a `preview {}` immediately follows the document capture step. */
+  documentPreviewFollowsCapture(): boolean {
+    const index = this._steps.findIndex(
+      (step) =>
+        step.kind === "capture" &&
+        step.config.captureType === CaptureType.document,
+    );
+    if (index < 0) return false;
+    return this._steps[index + 1]?.kind === "preview";
+  }
+
+  /** Whether the active preview previews a document side (vs the selfie). */
+  currentPreviewIsDocument(): boolean {
+    const current = this.currentScreen;
+    if (!current || current.kind !== "preview") return false;
+    return this._precedingStepIsDocumentCapture(this._steps.indexOf(current));
+  }
+
+  /** Path of the document side under review: the back if captured, else the front. */
+  currentDocumentPreviewPath(): string | undefined {
+    return this._captured.backDocumentPath ?? this._captured.frontDocumentPath;
+  }
+
+  /**
+   * Discard the side under review for re-capture: the back if captured,
+   * else the front (which also un-skips the back). Does not navigate.
+   */
+  retakeCurrentDocumentSide(): void {
+    if (this._disposed) return;
+    const next: {
+      -readonly [K in keyof CapturedArtifacts]: CapturedArtifacts[K];
+    } = { ...this._captured };
+    if (next.backDocumentPath !== undefined) {
+      delete next.backDocumentPath;
+      this._documentImageOrigins.delete(DocumentSide.Back);
+    } else {
+      delete next.frontDocumentPath;
+      this._documentImageOrigins.delete(DocumentSide.Front);
+      this._documentBackSkipped = false;
+    }
+    this._captured = next;
+    this._notify();
+  }
+
+  /** Skip the document back side from the flip interstitial ("Skip"). */
+  skipDocumentBack(): void {
+    if (this._disposed) return;
+    this._documentBackSkipped = true;
+    this._notify();
+  }
+
+  /**
+   * Record how a side was produced (→ `DocumentFront/BackImageOrigin`
+   * metadata). Metadata-only, so it intentionally does not `_notify()`.
+   */
+  recordDocumentImageOrigin(
+    side: DocumentSide,
+    origin: DocumentImageOrigin,
+  ): void {
+    if (this._disposed) return;
+    this._documentImageOrigins.set(side, origin);
+  }
+
+  /** Per-side document origin wire entries (front then back; omitted when unset). */
+  private _documentImageOriginEntries(): MetadataEntry[] {
+    const entries: MetadataEntry[] = [];
+    const front = this._documentImageOrigins.get(DocumentSide.Front);
+    if (front !== undefined) {
+      entries.push({ name: DOCUMENT_FRONT_IMAGE_ORIGIN_KEY, value: front });
+    }
+    const back = this._documentImageOrigins.get(DocumentSide.Back);
+    if (back !== undefined) {
+      entries.push({ name: DOCUMENT_BACK_IMAGE_ORIGIN_KEY, value: back });
+    }
+    return entries;
+  }
+
+  private _precedingStepIsDocumentCapture(index: number): boolean {
+    const preceding = this._steps[index - 1];
+    return (
+      preceding?.kind === "capture" &&
+      preceding.config.captureType === CaptureType.document
+    );
+  }
+
+  setConsent(info: ConsentInformation): void {
+    if (this._disposed) return;
+    this._captured = { ...this._captured, consentInformation: info };
+    this._logEvent(UseSmileIDAnalyticsEventTypes.consentCaptured, {
+      [UseSmileIDAnalyticsParamKeys.decision]: "granted",
+    });
+    this._notify();
+  }
+
+  // --- job submission ---------------------------------------------------
+
+  get jobSubmissionState(): JobSubmissionState {
+    return this._jobSubmissionState;
+  }
+
+  /**
+   * Idempotent submission entry point (called on processing-screen
+   * mount). The `notAttempted` guard prevents re-mounts re-firing.
+   */
+  beginSubmissionIfNeeded(): void {
+    if (this._disposed) return;
+    if (this._jobSubmissionState.kind !== "notAttempted") return;
+    void this._submit();
+  }
+
+  /** Reset to `notAttempted` and re-fire submission (processing screen's onRetry). */
+  retrySubmission(): void {
+    if (this._disposed) return;
+    this._setSubmissionState({ kind: "notAttempted" });
+    this.beginSubmissionIfNeeded();
+  }
+
+  private _setSubmissionState(state: JobSubmissionState): void {
+    if (this._disposed) return;
+    this._jobSubmissionState = state;
+    this._notify();
+  }
+
+  /**
+   * Build the request, dispatch via repository, update state. Errors
+   * from `_assembleJob` (missing captures / bad job type) map to the
+   * `failure` state rather than propagating as unhandled rejections.
+   */
+  private async _submit(): Promise<void> {
+    if (!this._repository) {
+      this._setSubmissionState({
+        kind: "failure",
+        error: new Error(
+          "Job submission not configured — no network/repository was " +
+            "supplied to <UseSmileIDBuilder>. Call `b.network((n) => n.config((c) => " +
+            "{ c.token = ...; c.partnerConfig((p) => { p.partnerId = ...; }); }))`.",
+        ),
+      });
+      return;
+    }
+
+    let request: JobRequest;
+    try {
+      request = this._assembleJob();
+    } catch (error) {
+      this._setSubmissionState({
+        kind: "failure",
+        error: error instanceof Error ? error : new Error(String(error)),
+      });
+      return;
+    }
+
+    this._setSubmissionState({ kind: "loading" });
+    this._submissionAttemptCount += 1;
+    this._logEvent(UseSmileIDAnalyticsEventTypes.jobSubmitted, {
+      [UseSmileIDAnalyticsParamKeys.jobType]: this._jobTypeName(),
+      [UseSmileIDAnalyticsParamKeys.attempt]: String(
+        this._submissionAttemptCount,
+      ),
+    });
+    const result = await this._repository.submit(request);
+    if (this._disposed) return;
+    if (result.status === "success") {
+      // Cache so a later navigateToNext() past the last screen can
+      // deliver the result without rebuilding the request (capture
+      // artifacts may have been released by then).
+      this._submissionResponse = result.value;
+      this._setSubmissionState({ kind: "success", response: result.value });
+    } else if (result.status === "failure") {
+      // `result.error` is `unknown`; coerce defensively in case a
+      // mock/partner repository hands back a non-Error.
+      const error =
+        result.error instanceof Error
+          ? result.error
+          : new Error(String(result.error));
+      this._setSubmissionState({ kind: "failure", error });
+    }
+    // No `cancelled` branch: that outcome comes only from a user-initiated exit.
+  }
+
+  /**
+   * Build a typed `JobRequest` from `jobType` + captured artifacts.
+   * Throws a descriptive message when a required capture is missing.
+   */
+  private _assembleJob(): JobRequest {
+    const config = this._configuration;
+    const jobType = config.network?.config?.jobType ?? JobType.unknown;
+    const consent =
+      this._captured.consentInformation ??
+      config.consentInformation ??
+      DEFAULT_CONSENT;
+    // Build the per-submission metadata snapshot so it travels on the
+    // request (API layer serializes `request.metadata` directly).
+    // Dynamic fields (orientation, locale, timezone) re-resolve per
+    // make() so a mid-flow rotation is captured. resolvedSdkConfig drives
+    // sdk_config_source + image_width/height provenance.
+    const baseMetadata = this._metadataProvider.make(this.resolvedSdkConfig);
+    const originEntries = this._documentImageOriginEntries();
+    const metadata =
+      originEntries.length > 0
+        ? baseMetadata.withAdditionalEntries(originEntries)
+        : baseMetadata;
+
+    switch (jobType) {
+      // enableEnhancedLiveness is a screen-level capture flag, not a
+      // distinct job type — enrollment still hits /v3/registration.
+      case JobType.smartSelfieEnrollment: {
+        const selfie = this._requireSelfie();
+        const userDetails = this._requireUserDetails(config);
+        return {
+          jobType: JobType.smartSelfieEnrollment,
+          selfieImage: selfie.selfiePath,
+          livenessImages: selfie.livenessPaths,
+          userDetails,
+          consent,
+          metadata,
+          enhanced: false,
+          expectedLivenessImageCount: this._expectedLivenessImageCount(),
+        };
+      }
+
+      case JobType.smartSelfieAuthentication: {
+        const selfie = this._requireSelfie();
+        const userDetails = this._requireUserDetails(config);
+        const userId = this._requireUserId(config);
+        return {
+          jobType: JobType.smartSelfieAuthentication,
+          selfieImage: selfie.selfiePath,
+          livenessImages: selfie.livenessPaths,
+          userDetails,
+          userId,
+          consent,
+          metadata,
+          enhanced: false,
+          expectedLivenessImageCount: this._expectedLivenessImageCount(),
+        };
+      }
+
+      case JobType.biometricKyc: {
+        const selfie = this._requireSelfie();
+        const params = config.biometricKYCParams;
+        if (!params) {
+          throw new MissingRequiredFieldException({
+            fieldName: "biometricKYCParams",
+          });
+        }
+        const userDetails = this._requireUserDetails(config);
+        return {
+          jobType: JobType.biometricKyc,
+          selfieImage: selfie.selfiePath,
+          livenessImages: selfie.livenessPaths,
+          params,
+          userDetails,
+          consent,
+          metadata,
+          expectedLivenessImageCount: this._expectedLivenessImageCount(),
+        };
+      }
+
+      case JobType.documentVerification: {
+        const selfie = this._requireSelfie();
+        const front = this._requireFrontDocument();
+        const params = config.documentVerificationParams;
+        if (!params) {
+          throw new MissingRequiredFieldException({
+            fieldName: "documentVerificationParams",
+          });
+        }
+        const userDetails = this._requireUserDetails(config);
+        return this._buildDocumentRequest(
+          selfie,
+          front,
+          params,
+          userDetails,
+          consent,
+          metadata,
+        );
+      }
+
+      case JobType.enhancedDocumentVerification: {
+        const selfie = this._requireSelfie();
+        const front = this._requireFrontDocument();
+        const params = config.enhancedDocumentVerificationParams;
+        if (!params) {
+          throw new MissingRequiredFieldException({
+            fieldName: "enhancedDocumentVerificationParams",
+          });
+        }
+        const userDetails = this._requireUserDetails(config);
+        return this._buildEnhancedDocumentRequest(
+          selfie,
+          front,
+          params,
+          userDetails,
+          consent,
+          metadata,
+        );
+      }
+
+      case JobType.enhancedKyc: {
+        const params = config.enhancedKYCParams;
+        if (!params) {
+          throw new MissingRequiredFieldException({
+            fieldName: "enhancedKYCParams",
+          });
+        }
+        const userDetails = this._requireUserDetails(config);
+        return {
+          jobType: JobType.enhancedKyc,
+          params,
+          userDetails,
+          consent,
+          metadata,
+        };
+      }
+
+      case JobType.bvn: {
+        // Dedicated `bvn` request kind; the repository rejects it with
+        // "BVN submission is not yet supported" until the endpoint lands.
+        // Deliberately not silently mapped onto /v3/enhanced_kyc so
+        // partners see the unsupported state explicitly.
+        const params = config.enhancedKYCParams;
+        if (!params) {
+          throw new MissingRequiredFieldException({
+            fieldName: "enhancedKYCParams",
+          });
+        }
+        const userDetails = this._requireUserDetails(config);
+        return {
+          jobType: JobType.bvn,
+          params,
+          userDetails,
+          consent,
+          metadata,
+        };
+      }
+
+      case JobType.unknown:
+      default:
+        throw new Error(
+          "Job type not configured — call `b.network((n) => n.config((c) => { c.jobType = JobType.<...>; }))` " +
+            "before mounting <UseSmileIDBuilder>.",
+        );
+    }
+  }
+
+  private _requireSelfie(): {
+    readonly selfiePath: string;
+    readonly livenessPaths: readonly string[];
+  } {
+    const { selfiePath, livenessPaths } = this._captured;
+    if (!selfiePath) {
+      throw new MissingRequiredFieldException({ fieldName: "selfieImage" });
+    }
+    return { selfiePath, livenessPaths };
+  }
+
+  private _requireUserDetails(config: FlowConfigurationSnapshot): UserDetails {
+    const userDetails = config.userDetails;
+    if (!userDetails) {
+      throw new MissingRequiredFieldException({ fieldName: "userDetails" });
+    }
+    return userDetails;
+  }
+
+  /**
+   * Resolve `b.userId` for smartSelfieAuthentication —
+   * `/v3/authentication` requires the prior-enrollment `user_id` to
+   * match the attempt. Throws `MissingRequiredFieldException` if blank.
+   */
+  private _requireUserId(config: FlowConfigurationSnapshot): string {
+    const userId = config.userId?.trim();
+    if (!userId) {
+      throw new MissingRequiredFieldException({ fieldName: "userId" });
+    }
+    return userId;
+  }
+
+  private _requireFrontDocument(): string {
+    const { frontDocumentPath } = this._captured;
+    if (!frontDocumentPath) {
+      throw new MissingRequiredFieldException({ fieldName: "frontDocument" });
+    }
+    return frontDocumentPath;
+  }
+
+  private _buildDocumentRequest(
+    selfie: {
+      readonly selfiePath: string;
+      readonly livenessPaths: readonly string[];
+    },
+    frontDocument: string,
+    params: DocumentVerificationParams,
+    userDetails: UserDetails,
+    consent: ConsentInformation,
+    metadata: UseSmileIDMetadata,
+  ): DocumentVerificationRequest {
+    const { backDocumentPath } = this._captured;
+    return {
+      jobType: JobType.documentVerification,
+      selfieImage: selfie.selfiePath,
+      livenessImages: selfie.livenessPaths,
+      frontDocument,
+      ...(backDocumentPath ? { backDocument: backDocumentPath } : {}),
+      country: params.country,
+      // Optional — omit when unset so the server classifies the document.
+      ...(params.idType ? { idType: params.idType } : {}),
+      userDetails,
+      consent,
+      metadata,
+      expectedLivenessImageCount: this._expectedLivenessImageCount(),
+    };
+  }
+
+  private _buildEnhancedDocumentRequest(
+    selfie: {
+      readonly selfiePath: string;
+      readonly livenessPaths: readonly string[];
+    },
+    frontDocument: string,
+    params: EnhancedDocumentVerificationParams,
+    userDetails: UserDetails,
+    consent: ConsentInformation,
+    metadata: UseSmileIDMetadata,
+  ): EnhancedDocumentVerificationRequest {
+    const { backDocumentPath } = this._captured;
+    return {
+      jobType: JobType.enhancedDocumentVerification,
+      selfieImage: selfie.selfiePath,
+      livenessImages: selfie.livenessPaths,
+      frontDocument,
+      ...(backDocumentPath ? { backDocument: backDocumentPath } : {}),
+      country: params.country,
+      idType: params.idType,
+      userDetails,
+      consent,
+      metadata,
+      expectedLivenessImageCount: this._expectedLivenessImageCount(),
+    };
+  }
+
+  // --- analytics --------------------------------------------------------
+
+  /** Emit terminal `flow_completed` (completed/failed only; not cancelled), then exit via `onExit`. */
+  private _finishFlow(reason: FlowExitReason): void {
+    if (reason.kind === "completed") {
+      const extras: Record<string, string> = {
+        [UseSmileIDAnalyticsParamKeys.result]: "success",
+      };
+      if (reason.job.jobId) {
+        extras[UseSmileIDAnalyticsParamKeys.jobId] = reason.job.jobId;
+      }
+      this._logEvent(UseSmileIDAnalyticsEventTypes.flowCompleted, extras);
+    } else if (reason.kind === "failed") {
+      this._logEvent(UseSmileIDAnalyticsEventTypes.flowCompleted, {
+        [UseSmileIDAnalyticsParamKeys.result]: "failure",
+        [UseSmileIDAnalyticsParamKeys.errorMessage]:
+          reason.error instanceof Error
+            ? reason.error.message
+            : String(reason.error),
+      });
+    }
+    this._onExit(reason);
+  }
+
+  /** Forward a lifecycle event to `onAnalyticsEvent`, adding `session_id` + `timestamp`. No-op without a callback. */
+  private _logEvent(
+    type: UseSmileIDAnalyticsEventType,
+    extras: Readonly<Record<string, string>> = {},
+  ): void {
+    const onAnalyticsEvent = this._configuration.onAnalyticsEvent;
+    if (!onAnalyticsEvent) return;
+    onAnalyticsEvent({
+      type,
+      extras: {
+        ...extras,
+        [UseSmileIDAnalyticsParamKeys.sessionId]: this._sessionId,
+        [UseSmileIDAnalyticsParamKeys.timestamp]: String(Date.now()),
+      },
+    });
+  }
+
+  private _jobTypeName(): string {
+    return String(
+      this._configuration.network?.config?.jobType ?? JobType.unknown,
+    );
+  }
+
+  private _screenAnalyticsName(screen: ScreenSpec): string {
+    const names: Record<ScreenSpec["kind"], string> = {
+      consent: UseSmileIDAnalyticsScreenNames.consent,
+      instructions: UseSmileIDAnalyticsScreenNames.instructions,
+      capture: UseSmileIDAnalyticsScreenNames.capture,
+      preview: UseSmileIDAnalyticsScreenNames.preview,
+      processing: UseSmileIDAnalyticsScreenNames.processing,
+    };
+    return names[screen.kind];
+  }
+
+  // --- subscription -----------------------------------------------------
+
+  /** Subscribe to state changes; returns an unsubscribe (safe after `dispose()`). */
+  subscribe(listener: Listener): () => void {
+    this._listeners.add(listener);
+    return () => {
+      this._listeners.delete(listener);
+    };
+  }
+
+  /** Tear down — drop listeners, make methods no-ops (orchestrator's useEffect cleanup). */
+  dispose(): void {
+    this._disposed = true;
+    this._listeners.clear();
+  }
+
+  /**
+   * Expected liveness image count: ESS uses its fixed count (head-turn
+   * flow self-manages); else the token's livenessImageCount override;
+   * else the ScanPerformanceProfile default (`numSamples - 1`).
+   */
+  private _expectedLivenessImageCount(): number {
+    const isEnhancedLiveness = this.enhancedLivenessEnabled;
+    if (isEnhancedLiveness) {
+      return EnhancedSmartSelfieConfig.EXPECTED_LIVENESS_IMAGE_COUNT;
+    }
+    const override = numSamplesOverride(this.resolvedSdkConfig);
+    if (override !== undefined) {
+      // numSamplesOverride = livenessImageCount + 1; subtract the selfie.
+      return override - 1;
+    }
+    // Profile numSamples (default Balanced = 8) minus the reference selfie.
+    const profileNumSamples =
+      this._configuration.ml?.analyzers.selfieConfig?.numSamples ??
+      ScanPerformanceProfile.Balanced.numSamples;
+    return profileNumSamples - 1;
+  }
+
+  /**
+   * Decode the `sdk_config` JWT claim. `undefined` for offline mode,
+   * no token, or no valid claim — SDK defaults apply in those cases.
+   */
+  private static _decodeSdkConfig(
+    configuration: FlowConfigurationSnapshot,
+  ): SdkConfig | undefined {
+    if (configuration.config?.allowOfflineMode) return undefined;
+    const token = configuration.network?.config?.token;
+    if (!token || token.length === 0) return undefined;
+    return decodeSmileIDToken(token)?.sdkConfig;
+  }
+
+  private _notify(): void {
+    for (const listener of this._listeners) {
+      try {
+        listener();
+      } catch {
+        // Swallow so one bad listener can't poison the dispatch chain;
+        // the orchestrator-level boundary handles crash reporting.
+      }
+    }
+  }
+}