@smileid/usesmileid 12.0.1 → 12.1.0

package/src/core/exception/use_smile_id_network_exception.ts

@@ -1,279 +0,0 @@
-import { isAxiosError, type AxiosError } from "axios";
-
-import { UseSmileIDErrorCode } from "./use_smile_id_error_code";
-import { UseSmileIDException } from "./use_smile_id_exception";
-
-type NetworkCode =
-  (typeof UseSmileIDErrorCode.Network)[keyof typeof UseSmileIDErrorCode.Network];
-
-/**
- * Category base for network / submission failures (timeout, 4xx, 5xx,
- * parse error). Concrete subclasses ship as the network stack
- * surfaces typed failures into `onResult`.
- *
- * Partners can `instanceof UseSmileIDNetworkException` to catch every
- * network-category failure with one check, or branch on the concrete
- * subclass with `if (e instanceof NetworkTimeoutException) ...` for
- * type-narrowed handling. The case distribution mirrors a
- * discriminated union shape:
- *
- * - [NetworkTransportException] / [NetworkTimeoutException] — request
- *   never reached the server (DNS, TLS, socket-read timeout).
- * - [NetworkServerException] — request reached the server and got a
- *   non-2xx HTTP response; `statusCode` preserved.
- * - [NetworkResponseParseException] — got 2xx but the body did not
- *   decode into the expected `JobSubmissionResponse`.
- * - [NetworkRequestBuildException] — request never went on the wire
- *   because the SDK could not assemble it.
- * - [NetworkUnknownException] — fallback when the cause does not match
- *   any of the above; inspect `cause` for triage.
- */
-export abstract class UseSmileIDNetworkException extends UseSmileIDException {}
-
-/**
- * Server returned a non-2xx HTTP response. Carries the wire status
- * code so partners can branch on `if (e.statusCode === 401) { ... }`,
- * and `errorDetails` preserves the server's `code` / `message`
- * payload + the raw response body for triage.
- */
-export class NetworkServerException extends UseSmileIDNetworkException {
-  readonly errorCode: NetworkCode;
-  readonly statusCode: number;
-
-  constructor({
-    statusCode,
-    cause,
-    message,
-    errorDetails,
-  }: {
-    readonly statusCode: number;
-    readonly cause?: unknown;
-    readonly message?: string;
-    readonly errorDetails?: Readonly<Record<string, unknown>>;
-  }) {
-    super({
-      message: message ?? `HTTP ${statusCode}`,
-      suggestedFix:
-        "Inspect the server response body and retry if the failure is transient.",
-      cause,
-      errorDetails,
-    });
-    this.statusCode = statusCode;
-    this.errorCode = statusToErrorCode(statusCode);
-  }
-}
-
-/** Network reachability / DNS / TLS / socket failure — never reached the server. */
-export class NetworkTransportException extends UseSmileIDNetworkException {
-  readonly errorCode: NetworkCode =
-    UseSmileIDErrorCode.Network.ConnectionFailed;
-
-  constructor({
-    cause,
-    message = "Network transport failure.",
-    errorDetails,
-  }: {
-    readonly cause?: unknown;
-    readonly message?: string;
-    readonly errorDetails?: Readonly<Record<string, unknown>>;
-  } = {}) {
-    super({
-      message,
-      suggestedFix:
-        "Check the device's network connection and verify the configured base URL is reachable.",
-      cause,
-      errorDetails,
-    });
-  }
-}
-
-/** Request exceeded the configured timeout. Specialised transport failure. */
-export class NetworkTimeoutException extends UseSmileIDNetworkException {
-  readonly errorCode: NetworkCode = UseSmileIDErrorCode.Network.Timeout;
-
-  constructor({
-    cause,
-    message = "The request timed out.",
-    errorDetails,
-  }: {
-    readonly cause?: unknown;
-    readonly message?: string;
-    readonly errorDetails?: Readonly<Record<string, unknown>>;
-  } = {}) {
-    super({
-      message,
-      suggestedFix:
-        "Increase the timeout via `n.timeouts(...)` if appropriate, or retry once connectivity recovers.",
-      cause,
-      errorDetails,
-    });
-  }
-}
-
-/** Got a 2xx response but the body could not be parsed. */
-export class NetworkResponseParseException extends UseSmileIDNetworkException {
-  readonly errorCode: NetworkCode =
-    UseSmileIDErrorCode.Network.ResponseParseError;
-
-  constructor({
-    cause,
-    message = "Failed to parse response body.",
-    errorDetails,
-  }: {
-    readonly cause?: unknown;
-    readonly message?: string;
-    readonly errorDetails?: Readonly<Record<string, unknown>>;
-  } = {}) {
-    super({
-      message,
-      suggestedFix:
-        "Confirm the SDK version matches the backend's response schema.",
-      cause,
-      errorDetails,
-    });
-  }
-}
-
-/**
- * Request could not be assembled — fires before the wire (malformed
- * multipart, missing required URL component). Distinct from
- * [NetworkServerException] so partners can tell "we couldn't ask"
- * from "we asked and the server said no".
- */
-export class NetworkRequestBuildException extends UseSmileIDNetworkException {
-  readonly errorCode: NetworkCode = UseSmileIDErrorCode.Network.RequestFailed;
-
-  constructor({
-    cause,
-    message = "Failed to build request.",
-    errorDetails,
-  }: {
-    readonly cause?: unknown;
-    readonly message?: string;
-    readonly errorDetails?: Readonly<Record<string, unknown>>;
-  } = {}) {
-    super({
-      message,
-      suggestedFix:
-        "Verify the request payload satisfies the multipart / URL contract before submission.",
-      cause,
-      errorDetails,
-    });
-  }
-}
-
-/** Fallback when no other concrete subclass fits. Inspect `cause` for triage. */
-export class NetworkUnknownException extends UseSmileIDNetworkException {
-  readonly errorCode: NetworkCode = UseSmileIDErrorCode.Network.RequestFailed;
-
-  constructor({
-    cause,
-    message = "Unknown network error.",
-    errorDetails,
-  }: {
-    readonly cause?: unknown;
-    readonly message?: string;
-    readonly errorDetails?: Readonly<Record<string, unknown>>;
-  } = {}) {
-    super({
-      message,
-      suggestedFix:
-        "Log the wrapped `cause` for triage — anything reaching this branch represents a gap in error mapping.",
-      cause,
-      errorDetails,
-    });
-  }
-}
-
-function statusToErrorCode(statusCode: number): NetworkCode {
-  if (statusCode === 401) return UseSmileIDErrorCode.Network.Unauthorized;
-  if (statusCode === 403) return UseSmileIDErrorCode.Network.Forbidden;
-  if (statusCode === 404) return UseSmileIDErrorCode.Network.NotFound;
-  if (statusCode === 429) return UseSmileIDErrorCode.Network.RateLimit;
-  if (statusCode >= 500 && statusCode < 600) {
-    return UseSmileIDErrorCode.Network.ServerError;
-  }
-  return UseSmileIDErrorCode.Network.RequestFailed;
-}
-
-/**
- * Translate axios's catch-all `AxiosError` onto the typed
- * [UseSmileIDNetworkException] hierarchy. Repositories call this so
- * the raw `AxiosError` never leaks past their boundary — partners can
- * branch on `e instanceof NetworkTimeoutException` etc. instead of
- * sniffing `error.code` strings.
- *
- * Maps:
- * - `AxiosError.code === "ECONNABORTED"` → [NetworkTimeoutException]
- *   (axios's signal for both connect and read timeouts).
- * - `AxiosError` with no `response` → [NetworkTransportException]
- *   (DNS / TLS / socket-level failure; request never reached the
- *   server).
- * - `AxiosError` with `response` → [NetworkServerException] carrying
- *   the wire status code; status routing via [statusToErrorCode]
- *   covers 401/403/404/429/5xx + a generic fallback.
- * - Already-typed [UseSmileIDNetworkException] → pass-through so the
- *   mapper is safe to call idempotently across retry / wrap paths.
- * - Anything else → [NetworkUnknownException] with the underlying
- *   value preserved as `cause` for triage.
- */
-export function mapAxiosError(error: unknown): UseSmileIDNetworkException {
-  if (error instanceof UseSmileIDNetworkException) {
-    return error;
-  }
-  if (isAxiosError(error)) {
-    return mapTypedAxiosError(error);
-  }
-  if (error instanceof Error) {
-    return new NetworkUnknownException({
-      message: error.message,
-      cause: error,
-    });
-  }
-  return new NetworkUnknownException({
-    message: String(error),
-    cause: error,
-  });
-}
-
-function mapTypedAxiosError(error: AxiosError): UseSmileIDNetworkException {
-  // axios refuses to send the request and tags the error with one of
-  // these codes when the request itself is malformed: invalid URL,
-  // invalid axios config value, or missing required option. Surface
-  // these as NetworkRequestBuildException so partners can distinguish
-  // "couldn't send" from "sent and failed".
-  if (
-    error.code === "ERR_BAD_OPTION" ||
-    error.code === "ERR_BAD_OPTION_VALUE" ||
-    error.code === "ERR_INVALID_URL"
-  ) {
-    return new NetworkRequestBuildException({
-      message: error.message,
-      cause: error,
-    });
-  }
-  // axios surfaces timeouts with `code === "ECONNABORTED"` and
-  // network-unreachable failures with `code === "ERR_NETWORK"` /
-  // missing `response`.
-  if (error.code === "ECONNABORTED") {
-    return new NetworkTimeoutException({
-      message: error.message,
-      cause: error,
-    });
-  }
-  if (!error.response) {
-    return new NetworkTransportException({
-      message: error.message,
-      cause: error,
-    });
-  }
-  const status = error.response.status;
-  const data = error.response.data as
-    | { code?: string; message?: string }
-    | undefined;
-  return new NetworkServerException({
-    statusCode: status,
-    message: data?.message ?? `HTTP ${status}: ${error.message}`,
-    cause: error,
-  });
-}

package/src/core/exception/use_smile_id_validation_exception.ts

@@ -1,12 +0,0 @@
-import { UseSmileIDException } from "./use_smile_id_exception";
-
-/**
- * Marker base for build-time validation failures. Partners can do
- * `instanceof UseSmileIDValidationException` to catch every
- * validator-emitted issue with one check, or pivot on the concrete
- * subclass for rule-specific narrowing.
- *
- * The class is intentionally a thin marker — every concrete
- * subclass holds its own `errorCode` / message / structured details.
- */
-export abstract class UseSmileIDValidationException extends UseSmileIDException {}

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

@@ -1,43 +0,0 @@
-import { describe, expect, it } from "vitest";
-import {
-  DEFAULT_ACTIVATE_MANUAL_AFTER_MS,
-  DocumentCaptureMode,
-} from "../document_capture_mode";
-
-describe("DocumentCaptureMode presets", () => {
-  it("AutoCapture and ManualCapture are frozen tagged singletons", () => {
-    expect(DocumentCaptureMode.AutoCapture).toEqual({ kind: "autoCapture" });
-    expect(DocumentCaptureMode.ManualCapture).toEqual({
-      kind: "manualCapture",
-    });
-    expect(Object.isFrozen(DocumentCaptureMode.AutoCapture)).toBe(true);
-    expect(Object.isFrozen(DocumentCaptureMode.ManualCapture)).toBe(true);
-  });
-});
-
-describe("DocumentCaptureMode.AutoCaptureWithManualFallback", () => {
-  it("defaults the fallback delay to 10000ms", () => {
-    expect(DEFAULT_ACTIVATE_MANUAL_AFTER_MS).toBe(10_000);
-    expect(DocumentCaptureMode.AutoCaptureWithManualFallback()).toEqual({
-      kind: "autoCaptureWithManualFallback",
-      activateManualAfterMs: 10_000,
-    });
-  });
-
-  it("honours an explicit fallback delay", () => {
-    expect(
-      DocumentCaptureMode.AutoCaptureWithManualFallback({
-        activateManualAfterMs: 8000,
-      }),
-    ).toEqual({
-      kind: "autoCaptureWithManualFallback",
-      activateManualAfterMs: 8000,
-    });
-  });
-
-  it("returns a frozen value", () => {
-    expect(
-      Object.isFrozen(DocumentCaptureMode.AutoCaptureWithManualFallback()),
-    ).toBe(true);
-  });
-});

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

@@ -1,66 +0,0 @@
-import { describe, expect, it } from "vitest";
-import { DocumentType } from "../document_type";
-
-// The preset field values are a cross-SDK contract (displayName / hasBackSide
-// / orientation drive both copy and capture behaviour). Pin them exactly so a
-// change forces a deliberate decision here and in the sibling SDKs.
-describe("DocumentType presets", () => {
-  it("SouthAfricaGreenBook is a portrait, single-sided document", () => {
-    expect(DocumentType.SouthAfricaGreenBook).toEqual({
-      kind: "southAfricaGreenBook",
-      displayName: "Green Book",
-      hasBackSide: false,
-      orientation: "Portrait",
-      knownAspectRatio: 320 / 428,
-    });
-  });
-
-  it("Passport is a landscape, two-sided document", () => {
-    expect(DocumentType.Passport).toEqual({
-      kind: "passport",
-      displayName: "Passport",
-      hasBackSide: true,
-      orientation: "Landscape",
-      knownAspectRatio: 356 / 272,
-    });
-  });
-
-  it("presets are frozen so the shared values cannot be mutated", () => {
-    expect(Object.isFrozen(DocumentType.SouthAfricaGreenBook)).toBe(true);
-    expect(Object.isFrozen(DocumentType.Passport)).toBe(true);
-  });
-});
-
-describe("DocumentType.GenericDocument", () => {
-  it("defaults to a landscape, two-sided 'Document' with no aspect ratio", () => {
-    const document = DocumentType.GenericDocument();
-    expect(document).toEqual({
-      kind: "genericDocument",
-      displayName: "Document",
-      hasBackSide: true,
-      orientation: "Landscape",
-    });
-    // Omitted rather than set to undefined (exactOptionalPropertyTypes).
-    expect("knownAspectRatio" in document).toBe(false);
-  });
-
-  it("overrides each field when supplied", () => {
-    const document = DocumentType.GenericDocument({
-      displayName: "National ID",
-      hasBackSide: false,
-      orientation: "Portrait",
-      knownAspectRatio: 1.586,
-    });
-    expect(document).toEqual({
-      kind: "genericDocument",
-      displayName: "National ID",
-      hasBackSide: false,
-      orientation: "Portrait",
-      knownAspectRatio: 1.586,
-    });
-  });
-
-  it("returns a frozen value", () => {
-    expect(Object.isFrozen(DocumentType.GenericDocument())).toBe(true);
-  });
-});

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

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

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

@@ -1,48 +0,0 @@
-import { describe, expect, it } from "vitest";
-import {
-  JobType,
-  jobTypeFromValue,
-  requiresDocument,
-  requiresSelfie,
-} from "../job_type";
-
-describe("jobTypeFromValue", () => {
-  it("returns the matching job type for a known wire value", () => {
-    expect(jobTypeFromValue(1)).toBe(JobType.biometricKyc);
-    expect(jobTypeFromValue(11)).toBe(JobType.enhancedDocumentVerification);
-  });
-
-  it("returns unknown for an unrecognised wire value", () => {
-    expect(jobTypeFromValue(999)).toBe(JobType.unknown);
-  });
-});
-
-// The capture-requirement sets are a cross-SDK contract; pin the exact
-// membership so adding a job type forces a deliberate decision here.
-describe("requiresSelfie", () => {
-  it("is true exactly for the selfie-capturing jobs", () => {
-    expect(requiresSelfie(JobType.biometricKyc)).toBe(true);
-    expect(requiresSelfie(JobType.smartSelfieAuthentication)).toBe(true);
-    expect(requiresSelfie(JobType.smartSelfieEnrollment)).toBe(true);
-
-    expect(requiresSelfie(JobType.enhancedKyc)).toBe(false);
-    expect(requiresSelfie(JobType.documentVerification)).toBe(false);
-    expect(requiresSelfie(JobType.bvn)).toBe(false);
-    expect(requiresSelfie(JobType.enhancedDocumentVerification)).toBe(false);
-    expect(requiresSelfie(JobType.unknown)).toBe(false);
-  });
-});
-
-describe("requiresDocument", () => {
-  it("is true exactly for the document-capturing jobs", () => {
-    expect(requiresDocument(JobType.biometricKyc)).toBe(true);
-    expect(requiresDocument(JobType.documentVerification)).toBe(true);
-    expect(requiresDocument(JobType.enhancedDocumentVerification)).toBe(true);
-
-    expect(requiresDocument(JobType.smartSelfieAuthentication)).toBe(false);
-    expect(requiresDocument(JobType.smartSelfieEnrollment)).toBe(false);
-    expect(requiresDocument(JobType.enhancedKyc)).toBe(false);
-    expect(requiresDocument(JobType.bvn)).toBe(false);
-    expect(requiresDocument(JobType.unknown)).toBe(false);
-  });
-});

package/src/core/models/config.ts

@@ -1,58 +0,0 @@
-import type * as ScreenOrientation from "expo-screen-orientation";
-import type { GlobalPrivacyControl } from "./global_privacy_control";
-
-/**
- * Global SDK configuration flags. Snapshot produced by
- * `UseSmileIDConfigBuilder.build()` — every field is populated, with
- * defaults applied at the builder when the partner omits them.
- */
-export type ConfigOptions = {
-  /**
-   * Enable Sentry-based crash reporting for the SDK. Defaults to
-   * `true`. The SDK initialises an isolated Sentry hub on flow mount
-   * and routes its own uncaught JavaScript errors to the Smile ID
-   * Sentry project. Does NOT touch the partner's `Sentry.init()`
-   * global hub.
-   *
-   * Set `false` to opt out — e.g. on internal builds or when the
-   * partner runs their own Sentry and does not want a second client.
-   */
-  readonly enableCrashReporting: boolean;
-
-  /**
-   * Show a validation error overlay on flow build failure. Defaults
-   * to `false`.
-   *
-   * Stub note: not yet honoured by the orchestrator — see
-   * `docs/Architecture.md § Rollout`.
-   */
-  readonly enableDebugMode: boolean;
-
-  /**
-   * Allow the flow to run without a network connection. Defaults to
-   * `false`.
-   *
-   * Stub note: not yet honoured by the (un-wired) network stack — see
-   * `docs/Architecture.md § Rollout`.
-   */
-  readonly allowOfflineMode: boolean;
-
-  /**
-   * Partner-declared consent posture (`global_privacy_control`).
-   * `GlobalPrivacyControl.OptOut` (the default) forces the opt-out consent
-   * layout universally; `OptIn` keeps the legacy regional mechanics.
-   */
-  readonly globalPrivacyControl: GlobalPrivacyControl;
-
-  /**
-   * Orientation lock the SDK applies when a capture screen leaves the screen.
-   * Defaults to `PORTRAIT_UP`, the posture most hosts pin at their root
-   * layout; multi-orientation hosts set `DEFAULT` so the flow releases the
-   * clamp instead of leaving the app portrait-only after verification.
-   *
-   * Optional so a hand-written `ConfigOptions` literal still compiles; the
-   * builder always populates it, and an absent value takes the same
-   * `PORTRAIT_UP` default at the capture screen.
-   */
-  readonly exitOrientations?: ScreenOrientation.OrientationLock;
-};

package/src/core/models/document_capture_mode.ts

@@ -1,73 +0,0 @@
-/**
- * How the document capture screen decides when to take the photo. Replaces the
- * earlier `autoCapture` + `autoCaptureTimeout` pair; defaults to
- * {@link DocumentCaptureMode.AutoCaptureWithManualFallback}.
- */
-export type DocumentCaptureMode =
-  | { readonly kind: "autoCapture" }
-  | { readonly kind: "manualCapture" }
-  | {
-      readonly kind: "autoCaptureWithManualFallback";
-      /** Milliseconds to wait before surfacing the manual shutter button. */
-      readonly activateManualAfterMs: number;
-    };
-
-/** Default wait before the manual shutter is offered as a fallback. */
-export const DEFAULT_ACTIVATE_MANUAL_AFTER_MS = 10_000;
-
-const AUTO_CAPTURE: DocumentCaptureMode = Object.freeze({
-  kind: "autoCapture",
-});
-const MANUAL_CAPTURE: DocumentCaptureMode = Object.freeze({
-  kind: "manualCapture",
-});
-
-/** Configurable fields for {@link DocumentCaptureMode.AutoCaptureWithManualFallback}. */
-export type AutoCaptureWithManualFallbackArgs = {
-  readonly activateManualAfterMs?: number;
-};
-
-/** Preset values and the `AutoCaptureWithManualFallback` factory for {@link DocumentCaptureMode}. */
-export const DocumentCaptureMode = {
-  /** Capture fires automatically once the document is well-framed. */
-  AutoCapture: AUTO_CAPTURE,
-  /** The shutter button is always shown; capture fires on tap. */
-  ManualCapture: MANUAL_CAPTURE,
-  /** Auto-capture, but surface a manual shutter button after `activateManualAfterMs`. */
-  AutoCaptureWithManualFallback(
-    args: AutoCaptureWithManualFallbackArgs = {},
-  ): DocumentCaptureMode {
-    return Object.freeze({
-      kind: "autoCaptureWithManualFallback",
-      activateManualAfterMs:
-        args.activateManualAfterMs ?? DEFAULT_ACTIVATE_MANUAL_AFTER_MS,
-    });
-  },
-} as const;
-
-/**
- * The wire token the server expects for the `auto_capture_enabled` builder-configuration field,
- * keyed off the mode's `kind`. Lives with {@link DocumentCaptureMode} — its single source of
- * truth — so the metadata layer maps the partner's typed choice straight onto the wire without a
- * parallel enum. These exact strings are the server contract; changing them is a wire-breaking
- * change. Not part of the public package surface (not re-exported from `index.ts`).
- */
-export function autoCaptureWireValue(
-  mode: DocumentCaptureMode | undefined,
-): string {
-  switch (mode?.kind) {
-    case "autoCapture":
-      return "auto_capture_only";
-    case "manualCapture":
-      return "manual";
-    case "autoCaptureWithManualFallback":
-    case undefined:
-      return "autocapture_default";
-    default: {
-      // Exhaustiveness guard: a new DocumentCaptureMode kind fails to compile here
-      // until it's handled above (`mode` narrows to `never` once all kinds are covered).
-      const exhaustive: never = mode;
-      return exhaustive;
-    }
-  }
-}

package/src/core/models/document_type.ts

@@ -1,79 +0,0 @@
-/**
- * Identifies the kind of identity document being captured. Behaviour falls out
- * of the typed fields, never `displayName`. Use a preset, or
- * {@link DocumentType.GenericDocument} otherwise.
- */
-
-/** Capture orientation for a {@link DocumentType}. */
-export type DocumentOrientation = "Landscape" | "Portrait";
-
-type DocumentTypeFields = {
-  /** Name shown in the instructions title emphasis. */
-  readonly displayName: string;
-  /** Whether there is a back side to capture (drives the flip interstitial). */
-  readonly hasBackSide: boolean;
-  readonly orientation: DocumentOrientation;
-  /** Fixed capture-frame aspect ratio; takes precedence over the DSL `knownIdAspectRatio`. */
-  readonly knownAspectRatio?: number;
-};
-
-/** Closed set of document types; the `kind` tag keeps a `switch` exhaustive. */
-export type DocumentType =
-  | ({ readonly kind: "southAfricaGreenBook" } & DocumentTypeFields)
-  | ({ readonly kind: "passport" } & DocumentTypeFields)
-  | ({ readonly kind: "genericDocument" } & DocumentTypeFields);
-
-const SOUTH_AFRICA_GREEN_BOOK: DocumentType = Object.freeze({
-  kind: "southAfricaGreenBook",
-  displayName: "Green Book",
-  hasBackSide: false,
-  orientation: "Portrait",
-  knownAspectRatio: 320 / 428,
-});
-
-const PASSPORT: DocumentType = Object.freeze({
-  kind: "passport",
-  displayName: "Passport",
-  hasBackSide: true,
-  orientation: "Landscape",
-  knownAspectRatio: 356 / 272,
-});
-
-/** Configurable fields for {@link DocumentType.GenericDocument}. */
-export type GenericDocumentArgs = {
-  readonly displayName?: string;
-  readonly hasBackSide?: boolean;
-  readonly orientation?: DocumentOrientation;
-  readonly knownAspectRatio?: number;
-};
-
-/** Preset values and the `GenericDocument` factory for {@link DocumentType}. */
-export const DocumentType = {
-  /** South Africa Green Book — booklet-style, single-side, portrait. */
-  SouthAfricaGreenBook: SOUTH_AFRICA_GREEN_BOOK,
-  /** Passport — landscape data page followed by a back-side capture. */
-  Passport: PASSPORT,
-  /** Catch-all without a preset; defaults to a landscape, two-sided "Document". */
-  GenericDocument(args: GenericDocumentArgs = {}): DocumentType {
-    return Object.freeze({
-      kind: "genericDocument",
-      displayName: args.displayName ?? "Document",
-      hasBackSide: args.hasBackSide ?? true,
-      orientation: args.orientation ?? "Landscape",
-      ...(args.knownAspectRatio !== undefined
-        ? { knownAspectRatio: args.knownAspectRatio }
-        : {}),
-    });
-  },
-} as const;
-
-/**
- * Capture-frame width:height ratio when neither {@link DocumentType.knownAspectRatio}
- * nor a partner `knownIdAspectRatio` is set. Landscape ≈ ID-1 card (1.586);
- * portrait a tall booklet / passport (0.65).
- */
-export function defaultFrameAspectRatio(
-  orientation: DocumentOrientation,
-): number {
-  return orientation === "Portrait" ? 0.65 : 1.586;
-}