@smileid/usesmileid 12.0.0-beta01

package/src/core/exception/use_smile_id_network_exception.ts

@@ -0,0 +1,279 @@
+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

@@ -0,0 +1,12 @@
+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

@@ -0,0 +1,43 @@
+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

@@ -0,0 +1,64 @@
+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, two-sided document", () => {
+    expect(DocumentType.SouthAfricaGreenBook).toEqual({
+      kind: "southAfricaGreenBook",
+      displayName: "Green Book",
+      hasBackSide: true,
+      orientation: "Portrait",
+    });
+  });
+
+  it("Passport is a portrait, single-sided document", () => {
+    expect(DocumentType.Passport).toEqual({
+      kind: "passport",
+      displayName: "Passport",
+      hasBackSide: false,
+      orientation: "Portrait",
+    });
+  });
+
+  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__/job_type.test.ts

@@ -0,0 +1,48 @@
+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

@@ -0,0 +1,36 @@
+/**
+ * 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;
+};

package/src/core/models/document_capture_mode.ts

@@ -0,0 +1,46 @@
+/**
+ * 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;

package/src/core/models/document_type.ts

@@ -0,0 +1,77 @@
+/**
+ * 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: true,
+  orientation: "Portrait",
+});
+
+const PASSPORT: DocumentType = Object.freeze({
+  kind: "passport",
+  displayName: "Passport",
+  hasBackSide: false,
+  orientation: "Portrait",
+});
+
+/** 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, two-sided, portrait. */
+  SouthAfricaGreenBook: SOUTH_AFRICA_GREEN_BOOK,
+  /** Passport — single data page, no back side, portrait (provisional values). */
+  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;
+}

package/src/core/models/flow_step.ts

@@ -0,0 +1,17 @@
+/**
+ * Discrete steps a UseSmileID flow can stop on.
+ *
+ * Order is significant — the orchestrator advances forward through this
+ * list; back-navigation goes backward. Add new steps in their natural
+ * flow position, never at the end "for compatibility".
+ */
+export const FlowStep = [
+  "instructions",
+  "consent",
+  "permission",
+  "capture",
+  "preview",
+  "processing",
+] as const;
+
+export type FlowStep = (typeof FlowStep)[number];

package/src/core/models/head_turn_direction.ts

@@ -0,0 +1,15 @@
+/**
+ * Head-turn direction enum. Drives the direction-specific Enhanced
+ * Smart Selfie liveness animation and the scan-state transitioner's
+ * expected-direction tracking.
+ *
+ * Order is significant — used by the head-turn validator and surfaced
+ * to analytics dashboards.
+ */
+export const HEAD_TURN_DIRECTIONS = [
+  "look_left",
+  "look_right",
+  "look_up",
+] as const;
+
+export type HeadTurnDirection = (typeof HEAD_TURN_DIRECTIONS)[number];