@smileid/usesmileid 12.0.0-beta01

package/src/core/exception/invalid_document_capture_config_exception.ts

@@ -0,0 +1,22 @@
+import { UseSmileIDBuilderException } from "./use_smile_id_builder_exception";
+import { UseSmileIDErrorCode } from "./use_smile_id_error_code";
+
+/**
+ * `captureType` is `document` but the `document { }` configuration
+ * block is missing or otherwise incomplete. The optional `reason` is
+ * appended to the message when supplied so the partner sees the
+ * specific field that is off.
+ */
+export class InvalidDocumentCaptureConfigException extends UseSmileIDBuilderException {
+  readonly errorCode = UseSmileIDErrorCode.Builder.InvalidDocumentCaptureConfig;
+
+  constructor(args: { reason?: string } = {}) {
+    const reasonSuffix = args.reason ? `: ${args.reason}` : "";
+    super({
+      message: `Document capture type selected but document { } configuration is missing${reasonSuffix}`,
+      suggestedFix:
+        "Add the document { } block inside capture { } when captureType is document",
+      errorDetails: args.reason ? { reason: args.reason } : undefined,
+    });
+  }
+}

package/src/core/exception/invalid_field_value_exception.ts

@@ -0,0 +1,21 @@
+import { UseSmileIDErrorCode } from "./use_smile_id_error_code";
+import { UseSmileIDValidationException } from "./use_smile_id_validation_exception";
+
+/**
+ * A field carries an invalid value. The `errorCode` is
+ * `Validation.InvalidInput` (not a Builder code) because the failure
+ * is a value-level constraint violation, not a missing-block one.
+ * Extends `UseSmileIDValidationException` directly rather than going
+ * through `UseSmileIDBuilderException` to match Android's hierarchy.
+ */
+export class InvalidFieldValueException extends UseSmileIDValidationException {
+  readonly errorCode = UseSmileIDErrorCode.Validation.InvalidInput;
+
+  constructor(args: { fieldName: string; reason: string }) {
+    super({
+      message: `Invalid value for field '${args.fieldName}': ${args.reason}`,
+      suggestedFix: "Provide a valid value for the field.",
+      errorDetails: { fieldName: args.fieldName, reason: args.reason },
+    });
+  }
+}

package/src/core/exception/invalid_job_type_screen_config_exception.ts

@@ -0,0 +1,70 @@
+import { JobType } from "../../core/models/job_type";
+import { UseSmileIDBuilderException } from "./use_smile_id_builder_exception";
+import { UseSmileIDErrorCode } from "./use_smile_id_error_code";
+
+/**
+ * The screen sequence is incompatible with the configured `jobType`.
+ * Surfaced when a non-capture job (Enhanced KYC, BVN) includes a
+ * Capture / Preview / Instructions screen, when its flow is missing
+ * a required Processing or consent step, or when Enhanced KYC is
+ * configured without an `enhancedKYCParams` payload.
+ *
+ * Two construction shapes are supported so both call patterns produce
+ * the same partner-visible message string:
+ * - The default constructor takes the fully-formed `message` directly
+ *   (used by the non-capture / screen-order rules).
+ * - [InvalidJobTypeScreenConfigException.forJob] takes a [JobType] +
+ *   `reason` + `suggestedFix` and synthesises
+ *   `"Invalid configuration for {jobTypeName}: {reason}"`, matching the
+ *   Android and iOS exception shapes.
+ */
+export class InvalidJobTypeScreenConfigException extends UseSmileIDBuilderException {
+  readonly errorCode = UseSmileIDErrorCode.Builder.InvalidJobTypeScreenConfig;
+
+  constructor(args: { message: string; suggestedFix?: string | undefined }) {
+    super({
+      message: args.message,
+      suggestedFix:
+        args.suggestedFix ??
+        "Adjust the screens block to match the configured jobType.",
+    });
+  }
+
+  /**
+   * Synthesises an `"Invalid configuration for {jobTypeName}: {reason}"`
+   * message. Partner tooling regex-matches on the `{reason}` substring,
+   * so the exact wording is part of the public contract.
+   */
+  static forJob(args: {
+    jobType: JobType;
+    reason: string;
+    suggestedFix?: string;
+  }): InvalidJobTypeScreenConfigException {
+    const name = jobTypeName(args.jobType);
+    return new InvalidJobTypeScreenConfigException({
+      message: `Invalid configuration for ${name}: ${args.reason}`,
+      suggestedFix: args.suggestedFix,
+    });
+  }
+}
+
+/**
+ * Stable display label for a `JobType` enum value, used as the
+ * `{jobTypeName}` token in the synthesised message. The DSL-facing
+ * `JobType` keys are camelCase; this map supplies the PascalCase label
+ * carried in partner-visible copy.
+ */
+const JOB_TYPE_NAMES: ReadonlyMap<JobType, string> = new Map<JobType, string>([
+  [JobType.biometricKyc, "BiometricKyc"],
+  [JobType.smartSelfieAuthentication, "SmartSelfieAuthentication"],
+  [JobType.smartSelfieEnrollment, "SmartSelfieEnrollment"],
+  [JobType.enhancedKyc, "EnhancedKyc"],
+  [JobType.documentVerification, "DocumentVerification"],
+  [JobType.bvn, "BVN"],
+  [JobType.enhancedDocumentVerification, "EnhancedDocumentVerification"],
+  [JobType.unknown, "Unknown"],
+]);
+
+function jobTypeName(jobType: JobType): string {
+  return JOB_TYPE_NAMES.get(jobType) ?? "Unknown";
+}

package/src/core/exception/invalid_missing_capture_type_exception.ts

@@ -0,0 +1,19 @@
+import { UseSmileIDBuilderException } from "./use_smile_id_builder_exception";
+import { UseSmileIDErrorCode } from "./use_smile_id_error_code";
+
+/**
+ * The `capture { }` block was declared but `captureType` was never
+ * assigned — the orchestrator has no way to pick between selfie /
+ * document downstream.
+ */
+export class InvalidMissingCaptureTypeException extends UseSmileIDBuilderException {
+  readonly errorCode = UseSmileIDErrorCode.Builder.MissingCaptureType;
+
+  constructor() {
+    super({
+      message: "captureType is missing in capture { } configuration",
+      suggestedFix:
+        "Set captureType inside capture { } to either selfie or document",
+    });
+  }
+}

package/src/core/exception/invalid_screen_order_exception.ts

@@ -0,0 +1,28 @@
+import { IssueSeverity } from "./issue_severity";
+import { UseSmileIDBuilderException } from "./use_smile_id_builder_exception";
+import { UseSmileIDErrorCode } from "./use_smile_id_error_code";
+
+/**
+ * The `screens { }` block declares screens in an order the SDK cannot
+ * orchestrate. Severity defaults to `warning` for soft recommendations;
+ * callers pass `error` for hard ordering violations that block the
+ * build.
+ */
+export class InvalidScreenOrderException extends UseSmileIDBuilderException {
+  readonly errorCode = UseSmileIDErrorCode.Builder.InvalidScreenOrder;
+
+  constructor(args: {
+    description: string;
+    severity?: IssueSeverity;
+    suggestedFix?: string;
+  }) {
+    super({
+      message: `Invalid screen order: ${args.description}`,
+      severity: args.severity ?? IssueSeverity.warning,
+      suggestedFix:
+        args.suggestedFix ??
+        "Recommended screen order: consent (first, if present) → instructions → capture → preview → processing (last, if present)",
+      errorDetails: { description: args.description },
+    });
+  }
+}

package/src/core/exception/invalid_selfie_capture_config_exception.ts

@@ -0,0 +1,22 @@
+import { UseSmileIDBuilderException } from "./use_smile_id_builder_exception";
+import { UseSmileIDErrorCode } from "./use_smile_id_error_code";
+
+/**
+ * `captureType` is `selfie` but the `selfie { }` configuration block
+ * is missing or otherwise incomplete. The optional `reason` is
+ * appended to the message when supplied so the partner sees the
+ * specific field that is off.
+ */
+export class InvalidSelfieCaptureConfigException extends UseSmileIDBuilderException {
+  readonly errorCode = UseSmileIDErrorCode.Builder.InvalidSelfieCaptureConfig;
+
+  constructor(args: { reason?: string } = {}) {
+    const reasonSuffix = args.reason ? `: ${args.reason}` : "";
+    super({
+      message: `Selfie capture type selected but selfie { } configuration is missing${reasonSuffix}`,
+      suggestedFix:
+        "Add the selfie { } block inside capture { } when captureType is selfie",
+      errorDetails: args.reason ? { reason: args.reason } : undefined,
+    });
+  }
+}

package/src/core/exception/issue_severity.ts

@@ -0,0 +1,14 @@
+/**
+ * Severity tier carried by every `UseSmileIDException`.
+ *
+ * - `error` — blocks the operation. `b.build()` throws on the first
+ *   one; the validator returns it in `state.issues`.
+ * - `warning` — advisory only. The build proceeds; tooling may
+ *   surface the issue.
+ */
+export const IssueSeverity = {
+  error: "error",
+  warning: "warning",
+} as const;
+
+export type IssueSeverity = (typeof IssueSeverity)[keyof typeof IssueSeverity];

package/src/core/exception/job_validation_exceptions.ts

@@ -0,0 +1,11 @@
+/**
+ * Re-export barrel for job / network / ML-block validation
+ * exceptions. Each concrete class lives in its own file; this module
+ * keeps the legacy import path stable.
+ */
+export { MissingMLConfigurationBlockException } from "./missing_ml_configuration_block_exception";
+export { MissingNetworkConfigurationBlockException } from "./missing_network_configuration_block_exception";
+export { MissingJobTypeException } from "./missing_job_type_exception";
+export { MissingRequiredFieldException } from "./missing_required_field_exception";
+export { InvalidJobTypeScreenConfigException } from "./invalid_job_type_screen_config_exception";
+export { InvalidFieldValueException } from "./invalid_field_value_exception";

package/src/core/exception/liveness_frame_count_exception.ts

@@ -0,0 +1,21 @@
+import { UseSmileIDValidationException } from "./use_smile_id_validation_exception";
+import { UseSmileIDErrorCode } from "./use_smile_id_error_code";
+
+/**
+ * A submission carried the wrong number of liveness frames. The capture
+ * pipeline must produce exactly [expected] frames; [actual] is what was
+ * collected. Surfaced before the request goes on the wire so a malformed
+ * frame set never reaches the server.
+ */
+export class LivenessFrameCountException extends UseSmileIDValidationException {
+  readonly errorCode = UseSmileIDErrorCode.Validation.ConstraintViolation;
+
+  constructor(args: { expected: number; actual: number }) {
+    super({
+      message: `Expected exactly ${args.expected} liveness images, got ${args.actual}`,
+      suggestedFix:
+        "Recapture the selfie so the pipeline collects the full liveness frame set.",
+      errorDetails: { expected: args.expected, actual: args.actual },
+    });
+  }
+}

package/src/core/exception/missing_capture_for_preview_exception.ts

@@ -0,0 +1,24 @@
+import { UseSmileIDBuilderException } from "./use_smile_id_builder_exception";
+import { UseSmileIDErrorCode } from "./use_smile_id_error_code";
+
+/**
+ * A `preview { }` screen appeared without a preceding `capture { }`
+ * screen — the preview surface has nothing to render. The
+ * `previewIndex` is preserved when known so partner UIs can highlight
+ * the offending screen.
+ */
+export class MissingCaptureForPreviewException extends UseSmileIDBuilderException {
+  readonly errorCode = UseSmileIDErrorCode.Builder.MissingCaptureForPreview;
+
+  constructor(args: { previewIndex?: number } = {}) {
+    const hasIndex = args.previewIndex !== undefined;
+    super({
+      message: hasIndex
+        ? `Preview screen at index ${args.previewIndex} has no preceding Capture screen`
+        : "Flow contains a Preview screen without a preceding Capture screen",
+      suggestedFix:
+        "Add a capture screen before the preview screen in the screens { } block",
+      errorDetails: hasIndex ? { previewIndex: args.previewIndex } : undefined,
+    });
+  }
+}

package/src/core/exception/missing_job_type_exception.ts

@@ -0,0 +1,20 @@
+import { UseSmileIDBuilderException } from "./use_smile_id_builder_exception";
+import { UseSmileIDErrorCode } from "./use_smile_id_error_code";
+
+/**
+ * The `network { config { } }` block is present but `jobType` was
+ * never set — the orchestrator can't pick a submission path without
+ * it.
+ */
+export class MissingJobTypeException extends UseSmileIDBuilderException {
+  readonly errorCode = UseSmileIDErrorCode.Builder.MissingJobType;
+
+  constructor() {
+    super({
+      message:
+        "jobType is not set — it must be configured explicitly in the network { config { } } block",
+      suggestedFix:
+        "Set config.jobType in the network { config { } } block, e.g. config.jobType = JobType.DocumentVerification",
+    });
+  }
+}

package/src/core/exception/missing_ml_configuration_block_exception.ts

@@ -0,0 +1,21 @@
+import { IssueSeverity } from "./issue_severity";
+import { UseSmileIDBuilderException } from "./use_smile_id_builder_exception";
+import { UseSmileIDErrorCode } from "./use_smile_id_error_code";
+
+/**
+ * The flow declares a Capture screen but no `ml { }` block.
+ * Severity is `warning` — the flow still builds; ML features just
+ * won't run at runtime.
+ */
+export class MissingMLConfigurationBlockException extends UseSmileIDBuilderException {
+  readonly errorCode = UseSmileIDErrorCode.Builder.MissingMLConfiguration;
+
+  constructor() {
+    super({
+      message: "Flow contains a Capture screen but the ml { } block is missing",
+      severity: IssueSeverity.warning,
+      suggestedFix:
+        "Add the ml { } block to your UseSmileID builder configuration",
+    });
+  }
+}

package/src/core/exception/missing_network_configuration_block_exception.ts

@@ -0,0 +1,22 @@
+import { IssueSeverity } from "./issue_severity";
+import { UseSmileIDBuilderException } from "./use_smile_id_builder_exception";
+import { UseSmileIDErrorCode } from "./use_smile_id_error_code";
+
+/**
+ * The flow declares a Processing screen but no `network { }` block.
+ * Severity is `warning` — the flow still builds; network submission
+ * just won't run at runtime.
+ */
+export class MissingNetworkConfigurationBlockException extends UseSmileIDBuilderException {
+  readonly errorCode = UseSmileIDErrorCode.Builder.MissingNetworkConfiguration;
+
+  constructor() {
+    super({
+      message:
+        "Flow contains a Processing screen but the network { } block is missing",
+      severity: IssueSeverity.warning,
+      suggestedFix:
+        "Add the network { } block to your UseSmileID builder configuration",
+    });
+  }
+}

package/src/core/exception/missing_partner_config_exception.ts

@@ -0,0 +1,38 @@
+import { UseSmileIDBuilderException } from "./use_smile_id_builder_exception";
+import { UseSmileIDErrorCode } from "./use_smile_id_error_code";
+
+/**
+ * A `network { }` block was provided but a required partner-configuration
+ * field (`partnerId` or the auth `token`) was missing or blank.
+ *
+ * Thrown when the networking client is constructed so an unauthenticated
+ * request can never reach the wire (empty credentials are rejected at
+ * client construction).
+ */
+export class MissingPartnerConfigException extends UseSmileIDBuilderException {
+  readonly errorCode = UseSmileIDErrorCode.Builder.InvalidConfiguration;
+
+  private constructor(args: { message: string; fieldName: string }) {
+    super({
+      message: args.message,
+      suggestedFix: `Configure the missing field '${args.fieldName}' in the network config block.`,
+      errorDetails: { fieldName: args.fieldName },
+    });
+  }
+
+  /** The `partnerId` was missing or blank. */
+  static missingPartnerId(): MissingPartnerConfigException {
+    return new MissingPartnerConfigException({
+      message: "Partner ID is required but was not configured",
+      fieldName: "partnerId",
+    });
+  }
+
+  /** The auth `token` was missing or blank. */
+  static missingAuthToken(): MissingPartnerConfigException {
+    return new MissingPartnerConfigException({
+      message: "Auth token is required but was not configured",
+      fieldName: "authToken",
+    });
+  }
+}

package/src/core/exception/missing_required_field_exception.ts

@@ -0,0 +1,19 @@
+import { UseSmileIDBuilderException } from "./use_smile_id_builder_exception";
+import { UseSmileIDErrorCode } from "./use_smile_id_error_code";
+
+/**
+ * A required scalar field on a configuration object was not provided.
+ * The `fieldName` identifies the offending property so partner
+ * tooling can surface it directly in the UI.
+ */
+export class MissingRequiredFieldException extends UseSmileIDBuilderException {
+  readonly errorCode = UseSmileIDErrorCode.Builder.MissingRequiredField;
+
+  constructor(args: { fieldName: string }) {
+    super({
+      message: `Required field '${args.fieldName}' is missing`,
+      suggestedFix: "Provide a value for the required field.",
+      errorDetails: { fieldName: args.fieldName },
+    });
+  }
+}

package/src/core/exception/screen_config_validation_exceptions.ts

@@ -0,0 +1,10 @@
+/**
+ * Re-export barrel for screen-configuration validation exceptions.
+ * Each concrete class lives in its own file so partner tooling can
+ * deep-import the exact rule it cares about without dragging the
+ * sibling rules into the bundle.
+ */
+export { EmptyScreensBlockException } from "./empty_screens_block_exception";
+export { InvalidScreenOrderException } from "./invalid_screen_order_exception";
+export { MissingCaptureForPreviewException } from "./missing_capture_for_preview_exception";
+export { DuplicateScreenTypeException } from "./duplicate_screen_type_exception";

package/src/core/exception/use_smile_id_attestation_exception.ts

@@ -0,0 +1,11 @@
+import { UseSmileIDException } from "./use_smile_id_exception";
+
+/**
+ * Category base for device-attestation failures (warmup, init,
+ * request). Concrete subclasses ship when the attestation surface
+ * lands — see [docs/Architecture.md § Rollout].
+ *
+ * Partners can `instanceof UseSmileIDAttestationException` to catch
+ * every attestation-category failure with one check.
+ */
+export abstract class UseSmileIDAttestationException extends UseSmileIDException {}

package/src/core/exception/use_smile_id_builder_exception.ts

@@ -0,0 +1,18 @@
+import { UseSmileIDValidationException } from "./use_smile_id_validation_exception";
+
+/**
+ * Category base for builder / configuration validation failures.
+ *
+ * Builder exceptions are emitted by `b.validate()` and thrown by
+ * `b.build()` when the configuration violates an invariant. Concrete
+ * subclasses live in:
+ *
+ *   - `screen_config_validation_exceptions.ts`
+ *   - `consent_validation_exceptions.ts`
+ *   - `job_validation_exceptions.ts`
+ *
+ * The class is a thin marker — partners doing
+ * `instanceof UseSmileIDBuilderException` catch every builder
+ * failure with one check.
+ */
+export abstract class UseSmileIDBuilderException extends UseSmileIDValidationException {}

package/src/core/exception/use_smile_id_camera_exception.ts

@@ -0,0 +1,12 @@
+import { UseSmileIDException } from "./use_smile_id_exception";
+
+/**
+ * Category base for camera / capture-surface failures (permission
+ * denied, hardware unavailable, capture failed). Concrete subclasses
+ * ship as the orchestrator wires the camera surface — see
+ * [docs/Architecture.md § Rollout].
+ *
+ * Partners can `instanceof UseSmileIDCameraException` to catch every
+ * camera-category failure with one check.
+ */
+export abstract class UseSmileIDCameraException extends UseSmileIDException {}

package/src/core/exception/use_smile_id_error_code.ts

@@ -0,0 +1,83 @@
+/**
+ * Stable error codes for typed exception narrowing.
+ *
+ * Codes are UPPER_SNAKE_CASE strings prefixed by category
+ * (`BUILDER_*`, `CAMERA_*`, `NETWORK_*`, `VALIDATION_*`,
+ * `GENERAL_*`). The literal string values are part
+ * of the wire-format contract — partners pivot on the literal value
+ * when forwarding to telemetry, and partner code that switches on
+ * `errorCode` is exhaustive at compile time via TypeScript's
+ * literal-type narrowing.
+ *
+ * Adding a new code rotates the partner-visible code set; never rename
+ * or remove an entry once shipped.
+ */
+export const UseSmileIDErrorCode = {
+  /** Builder / configuration validation. */
+  Builder: {
+    ValidationError: "BUILDER_VALIDATION_ERROR",
+    InvalidConfiguration: "BUILDER_INVALID_CONFIG",
+    MissingRequiredField: "BUILDER_MISSING_FIELD",
+    InvalidConsentConfig: "BUILDER_INVALID_CONSENT_CONFIG",
+    MissingCaptureType: "BUILDER_MISSING_CAPTURE_TYPE",
+    EmptyScreensBlock: "BUILDER_EMPTY_SCREENS",
+    MissingScreenConfiguration: "BUILDER_MISSING_SCREEN_CONFIG",
+    DuplicateScreenType: "BUILDER_DUPLICATE_SCREEN",
+    InvalidSelfieCaptureConfig: "BUILDER_INVALID_SELFIE_CONFIG",
+    InvalidDocumentCaptureConfig: "BUILDER_INVALID_DOCUMENT_CONFIG",
+    MissingMLConfiguration: "BUILDER_MISSING_ML_CONFIG",
+    MissingNetworkConfiguration: "BUILDER_MISSING_NETWORK_CONFIG",
+    MissingJobType: "BUILDER_MISSING_JOB_TYPE",
+    MissingCaptureForPreview: "BUILDER_MISSING_CAPTURE_FOR_PREVIEW",
+    InvalidScreenOrder: "BUILDER_INVALID_SCREEN_ORDER",
+    ConfigurationBlockFailed: "BUILDER_CONFIG_BLOCK_FAILED",
+    InvalidConsentInformation: "BUILDER_INVALID_CONSENT_INFORMATION",
+    InvalidJobTypeScreenConfig: "BUILDER_INVALID_JOB_TYPE_SCREEN_CONFIG",
+  },
+  /** Camera / capture surface. */
+  Camera: {
+    InitializationFailed: "CAMERA_INIT_FAILED",
+    PermissionDenied: "CAMERA_PERMISSION_DENIED",
+    CaptureFailed: "CAMERA_CAPTURE_FAILED",
+    UseCaseNotSupported: "CAMERA_USE_CASE_NOT_SUPPORTED",
+    Unknown: "CAMERA_UNKNOWN_ERROR",
+  },
+  /** Network / submission. */
+  Network: {
+    ConnectionFailed: "NETWORK_CONNECTION_FAILED",
+    Timeout: "NETWORK_TIMEOUT",
+    RequestFailed: "NETWORK_REQUEST_FAILED",
+    ResponseParseError: "NETWORK_PARSE_ERROR",
+    Unauthorized: "NETWORK_UNAUTHORIZED",
+    Forbidden: "NETWORK_FORBIDDEN",
+    NotFound: "NETWORK_NOT_FOUND",
+    RateLimit: "NETWORK_RATE_LIMIT",
+    ServerError: "NETWORK_SERVER_ERROR",
+  },
+  /** Generic input / state validation. */
+  Validation: {
+    InvalidInput: "VALIDATION_INVALID_INPUT",
+    InvalidState: "VALIDATION_INVALID_STATE",
+    ConstraintViolation: "VALIDATION_CONSTRAINT_VIOLATION",
+  },
+  /** Catch-all for failures that don't fit a category. */
+  General: {
+    Unknown: "GENERAL_UNKNOWN_ERROR",
+    InvalidState: "GENERAL_INVALID_STATE",
+    OperationFailed: "GENERAL_OPERATION_FAILED",
+  },
+} as const;
+
+type UseSmileIDErrorCodeNamespace = typeof UseSmileIDErrorCode;
+
+/**
+ * Union of every error-code literal. Partners can write
+ * `switch (e.errorCode) { case UseSmileIDErrorCode.Builder.EmptyScreensBlock: ... }`
+ * and TypeScript narrows exhaustively.
+ */
+export type UseSmileIDErrorCode =
+  | UseSmileIDErrorCodeNamespace["Builder"][keyof UseSmileIDErrorCodeNamespace["Builder"]]
+  | UseSmileIDErrorCodeNamespace["Camera"][keyof UseSmileIDErrorCodeNamespace["Camera"]]
+  | UseSmileIDErrorCodeNamespace["Network"][keyof UseSmileIDErrorCodeNamespace["Network"]]
+  | UseSmileIDErrorCodeNamespace["Validation"][keyof UseSmileIDErrorCodeNamespace["Validation"]]
+  | UseSmileIDErrorCodeNamespace["General"][keyof UseSmileIDErrorCodeNamespace["General"]];

package/src/core/exception/use_smile_id_exception.ts

@@ -0,0 +1,52 @@
+import type { UseSmileIDErrorCode } from "./use_smile_id_error_code";
+import { IssueSeverity } from "./issue_severity";
+
+/**
+ * Root exception type for the SDK.
+ *
+ * Concrete subclasses fix the `errorCode` (and may carry rule- or
+ * category-specific structured data via `errorDetails`). Partner
+ * tooling pivots on `errorCode` / `severity` to triage failures.
+ */
+export abstract class UseSmileIDException extends Error {
+  /** Stable category-prefixed code — see `UseSmileIDErrorCode`. */
+  abstract readonly errorCode: UseSmileIDErrorCode;
+
+  /** Whether the exception blocks the current operation. */
+  readonly severity: IssueSeverity;
+
+  /** Concrete remediation hint — usually quotes the offending property. */
+  readonly suggestedFix: string;
+
+  /** Optional structured payload (e.g. `{ index, field }`). */
+  readonly errorDetails?: Readonly<Record<string, unknown>> | undefined;
+
+  protected constructor(args: {
+    message: string;
+    suggestedFix: string;
+    severity?: IssueSeverity | undefined;
+    errorDetails?: Readonly<Record<string, unknown>> | undefined;
+    cause?: unknown;
+  }) {
+    super(args.message);
+    this.name = new.target.name;
+    this.severity = args.severity ?? IssueSeverity.error;
+    this.suggestedFix = args.suggestedFix;
+    this.errorDetails = args.errorDetails;
+    if (args.cause !== undefined) {
+      // `cause` is part of ES2022 `Error`. Define it
+      // non-enumerably so bundlers targeting older engines don't
+      // leak it into `JSON.stringify(error)` payloads on partner
+      // telemetry pipelines.
+      Object.defineProperty(this, "cause", {
+        value: args.cause,
+        writable: true,
+        configurable: true,
+        enumerable: false,
+      });
+    }
+    // Restore prototype — required when transpiling to ES5 so
+    // `instanceof` works across exception subclasses.
+    Object.setPrototypeOf(this, new.target.prototype);
+  }
+}

package/src/core/exception/use_smile_id_general_exception.ts

@@ -0,0 +1,12 @@
+import { UseSmileIDException } from "./use_smile_id_exception";
+
+/**
+ * Catch-all category base for failures that don't fit the more
+ * specific buckets (Builder, Camera, Network, Attestation,
+ * Validation). Concrete subclasses ship as needed — see
+ * [docs/Architecture.md § Rollout].
+ *
+ * Partners can `instanceof UseSmileIDGeneralException` to catch
+ * every general-category failure with one check.
+ */
+export abstract class UseSmileIDGeneralException extends UseSmileIDException {}