@velion-la/onboarding-sdk-react-native 1.0.0-beta.2

package/src/types/index.ts

@@ -0,0 +1,1198 @@
+/**
+ * @fileoverview Public TypeScript contracts for the Velion Onboarding SDK.
+ *
+ * Design principle: All types exported from this file constitute the public API.
+ * Internal implementation types should live alongside their respective modules.
+ */
+
+// ─────────────────────────────────────────────────────────────────────────────
+// STEP & FLOW TYPES
+// ─────────────────────────────────────────────────────────────────────────────
+
+/**
+ * The complete set of onboarding steps the backend can require.
+ * The SDK dynamically receives the active subset for each session.
+ *
+ * @remarks
+ * - `DEVICE_FINGERPRINT`: Silently collects device entropy via FingerprintJS.
+ * - `DOCUMENTS_OCR`: Renders a UI for ID document image capture and upload.
+ * - `LIVENESS_MATCH`: Drives the Velion Iris active-liveness flow over WebSocket (HUMAN only).
+ * - `EMAIL_OTP` / `PHONE_OTP`: Contact verification via one-time passwords.
+ * - `HUMAN_BASIC_INFO`: Natural-person identification data (HUMAN only).
+ * - `LEGAL_BASIC_INFO`: Legal-entity identification data (LEGAL only).
+ * - `EMAIL_CONTACT` / `PHONE_CONTACT`: contact collection without OTP.
+ * - `TAX_INFO`, `HUMAN_EXTENDED_INFO`, `LEGAL_EXTENDED_INFO`, `ADDRESS_INFO`, `SWORN_DECLARATION`: form steps.
+ * - `TERMS_AND_CONDITIONS`: accept configured T&C items.
+ * - `FACE_MATCH`: server-side face comparison after liveness (no user input; SDK waits).
+ */
+export type OnboardingStep =
+  | 'DEVICE_FINGERPRINT'
+  | 'HUMAN_BASIC_INFO'
+  | 'LEGAL_BASIC_INFO'
+  | 'EMAIL_OTP'
+  | 'EMAIL_CONTACT'
+  | 'PHONE_OTP'
+  | 'PHONE_CONTACT'
+  | 'TAX_INFO'
+  | 'HUMAN_EXTENDED_INFO'
+  | 'LEGAL_EXTENDED_INFO'
+  | 'ADDRESS_INFO'
+  | 'SWORN_DECLARATION'
+  | 'DOCUMENTS_OCR'
+  | 'LIVENESS_MATCH'
+  | 'FACE_MATCH'
+  | 'TERMS_AND_CONDITIONS';
+
+/**
+ * Status of an individual onboarding step (matches backend OnboardingStepStatus).
+ */
+export type OnboardingStepStatus =
+  | 'PENDING'
+  | 'IN_PROGRESS'
+  | 'COMPLETED'
+  | 'SKIPPED'
+  | 'FAILED';
+
+/**
+ * Type of onboarding session (matches backend OnboardingType).
+ * Constrains which steps are valid: HUMAN allows biometric steps, LEGAL uses entity data.
+ */
+export type OnboardingType = 'HUMAN' | 'LEGAL';
+
+/** Which face of the ID document is being captured. */
+export type DocumentSide = 'FRONT' | 'BACK';
+
+/**
+ * How the user can provide document images in the DOCUMENTS_OCR step.
+ * - `'camera'`: Only "Take photo" (opens camera on supported devices).
+ * - `'file'`: Only "Choose file" (file picker).
+ * - `'both'`: Both options; implementer can style via theme.
+ *
+ * @default 'both'
+ */
+export type DocumentCaptureMode = 'camera' | 'file' | 'both';
+
+/**
+ * Orientation of the document capture cutout / crop frame.
+ * - `'landscape'`: Horizontal card (default — standard ID-1 cards).
+ * - `'portrait'`: Vertical card (e.g. some passports, residence permits).
+ *
+ * @default 'landscape'
+ */
+export type DocumentOrientation = 'landscape' | 'portrait';
+
+/** Generic visible/required field toggle used by workflow step configs. */
+export interface StepFieldRule {
+  visible: boolean;
+  required: boolean;
+}
+
+/** Select option used by configurable step fields (e.g. HUMAN_EXTENDED_INFO gender/civil_status). */
+export interface StepFieldOption {
+  id: string;
+  display_value?: string;
+}
+
+/** Field rule with optional selectable options. */
+export interface StepFieldRuleWithOptions extends StepFieldRule {
+  options?: StepFieldOption[];
+}
+
+/** STEP config for HUMAN_BASIC_INFO. */
+export interface HumanBasicInfoStepConfig {
+  accepted_country_documents?: Array<{
+    country_code: string;
+    document_types: Array<{ id: string; display_value?: string }>;
+  }>;
+}
+
+/**
+ * One selectable option row from TAX_INFO `accepted_tax_information` (backend GET session).
+ * Prefer `code` as the value sent in POST tax-info; `id` is supported for older payloads.
+ */
+export interface TaxInfoConfigOptionRow {
+  code?: string;
+  id?: string;
+  display_value?: string;
+  tax_code?: string;
+}
+
+/** One country block in TAX_INFO step config (GET session `current_step.config`). */
+export interface TaxInfoAcceptedCountryRow {
+  country_code: string;
+  identification_types?: TaxInfoConfigOptionRow[];
+  /** Options for the "Categoría fiscal" / taxpayer category select. */
+  taxpayer_categories?: TaxInfoConfigOptionRow[];
+}
+
+/** STEP config for TAX_INFO. */
+export interface TaxInfoStepConfig {
+  /** Identification types + taxpayer categories per country. */
+  accepted_tax_information?: TaxInfoAcceptedCountryRow[];
+}
+
+/** STEP config for HUMAN_EXTENDED_INFO. */
+export interface HumanExtendedInfoStepConfig {
+  /** Optional top-level lists sent by backend for select fields. */
+  gender_options?: StepFieldOption[];
+  civil_status_options?: StepFieldOption[];
+  fields?: Partial<
+    Record<
+      'gender' | 'civil_status' | 'birth_date' | 'birth_country' | 'citizenship' | 'residence_country',
+      StepFieldRuleWithOptions
+    >
+  >;
+}
+
+/** STEP config for ADDRESS_INFO. */
+export interface AddressInfoStepConfig {
+  address_type?: { id?: string; display_value?: string };
+  fields?: Partial<
+    Record<
+      'state' | 'city' | 'district' | 'neighborhood' | 'postal_code' | 'street' | 'number',
+      StepFieldRule
+    >
+  >;
+  /**
+   * Optional ISO 3166-1 alpha-2 allowlist for the country selector. Only
+   * consumed by the manual-entry form (when the SDK is configured without a
+   * Google Maps key). When unset, every country is offered.
+   */
+  country_allow?: string[];
+}
+
+/** STEP config for SWORN_DECLARATION. */
+export interface SwornDeclarationStepConfig {
+  ask_pep?: boolean;
+  ask_obligated_subject?: boolean;
+  ask_fatca?: boolean;
+  ask_ocde?: boolean;
+  on_declared_pep?: string;
+  on_declared_obligated_subject?: string;
+  on_declared_fatca?: string;
+  on_declared_ocde?: string;
+}
+
+/** STEP config for DOCUMENTS_OCR. */
+export interface DocumentsOcrStepConfig {
+  country_allow?: string[];
+  capture_methods?: {
+    camera_scan?: boolean;
+    upload?: boolean;
+  };
+  /** Crop frame orientation for document camera capture. */
+  document_orientation?: DocumentOrientation;
+  /** [RN: ignored] Mirror preview in document camera. La cámara back de vision-camera no espeja y enviar JPEG espejado rompe Iris/OCR. */
+  mirror_document_video?: boolean;
+}
+
+/** STEP config for TERMS_AND_CONDITIONS. */
+export interface TermsAndConditionsStepConfig {
+  terms?: Array<{ title?: string; url?: string }>;
+}
+
+/** Generic per-step runtime config map carried by session state and SSE. */
+export type StepConfigMap = Partial<Record<OnboardingStep, Record<string, unknown>>>;
+
+/**
+ * Request body for POST /sessions/:sessionId/documents-init.
+ * Allowed values are defined by the backend; the SDK currently sends a fixed type until
+ * the session exposes selectable document types.
+ */
+export interface DocumentsInitRequest {
+  document_type: string;
+}
+
+/**
+ * Response from POST /sessions/:sessionId/documents-init.
+ * Backend returns signed upload URLs so the SDK can PUT each document side
+ * directly to storage (e.g. GCS) without routing bytes through the backend.
+ */
+export interface DocumentsInitResponse {
+  /** Pre-signed URL to upload the front side. Use PUT with body = image, Content-Type: image/jpeg. */
+  front_side_upload_url: string;
+  /** Pre-signed URL to upload the back side. Use PUT with body = image, Content-Type: image/jpeg. */
+  back_side_upload_url: string;
+  /** Optional max file size in bytes; client may validate before uploading. */
+  max_file_size_bytes?: number;
+}
+
+// ─────────────────────────────────────────────────────────────────────────────
+// ERROR TYPES
+// ─────────────────────────────────────────────────────────────────────────────
+
+/**
+ * Granular error codes for camera/hardware failures.
+ * Allows consumers to display localized, actionable messages to end-users.
+ */
+export enum CameraErrorCode {
+  /** User explicitly denied camera access in the browser permission dialog. */
+  PERMISSION_DENIED = 'CAMERA_PERMISSION_DENIED',
+  /** No camera device was detected on the system. */
+  DEVICE_NOT_FOUND = 'CAMERA_DEVICE_NOT_FOUND',
+  /**
+   * The camera could not be opened for reading (often in use by another app,
+   * or blocked at the OS level). Maps to `NotReadableError` / `TrackStartError`.
+   */
+  DEVICE_NOT_READABLE = 'CAMERA_DEVICE_NOT_READABLE',
+  /**
+   * The page is served over HTTP (not HTTPS) in a production environment.
+   * `getUserMedia` is blocked by the browser's Secure Context policy.
+   */
+  INSECURE_CONTEXT = 'CAMERA_INSECURE_CONTEXT',
+  /**
+   * Browser policy blocked camera (e.g. cross-origin iframe without permission,
+   * or `Permissions-Policy` / Feature-Policy denying camera). Maps to `SecurityError`
+   * from `getUserMedia` — distinct from {@link INSECURE_CONTEXT} (non-HTTPS).
+   */
+  POLICY_BLOCKED = 'CAMERA_POLICY_BLOCKED',
+  /** The browser or WebView does not support the `getUserMedia` API. */
+  NOT_SUPPORTED = 'CAMERA_NOT_SUPPORTED',
+  /**
+   * Camera access is blocked by a WebView policy (common in in-app browsers
+   * on iOS/Android that restrict hardware access).
+   */
+  WEBVIEW_BLOCKED = 'CAMERA_WEBVIEW_BLOCKED',
+  /** The requested video constraints (resolution, facing mode) are not satisfiable. */
+  CONSTRAINT_ERROR = 'CAMERA_CONSTRAINT_ERROR',
+  /** An unclassified camera error occurred. Check `cause` for details. */
+  UNKNOWN = 'CAMERA_UNKNOWN_ERROR',
+}
+
+/**
+ * Top-level SDK error codes covering all failure scenarios in the onboarding flow.
+ */
+export enum SdkErrorCode {
+  // ── Session ──────────────────────────────────────────────────────────────
+  /** The sessionToken was rejected by the backend (401/403). */
+  SESSION_INVALID = 'SESSION_INVALID',
+  /** The sessionToken has expired (typically a 401 after initial validation). */
+  SESSION_EXPIRED = 'SESSION_EXPIRED',
+  /** Could not fetch the initial session state from the backend. */
+  SESSION_FETCH_FAILED = 'SESSION_FETCH_FAILED',
+  /** Backend sent SESSION_DECLINED over SSE; session ended before completion. */
+  SESSION_DECLINED = 'SESSION_DECLINED',
+
+  // ── Modules ──────────────────────────────────────────────────────────────
+  /** FingerprintJS failed to generate the visitor ID. */
+  FINGERPRINT_FAILED = 'FINGERPRINT_FAILED',
+  /** One or more document images failed to upload successfully. */
+  DOCUMENT_UPLOAD_FAILED = 'DOCUMENT_UPLOAD_FAILED',
+  /** The liveness check did not pass or returned an unexpected result. */
+  LIVENESS_FAILED = 'LIVENESS_FAILED',
+  /** The Liveness module failed to initialize (e.g., could not create the Iris session). */
+  LIVENESS_INIT_FAILED = 'LIVENESS_INIT_FAILED',
+
+  // ── Camera ───────────────────────────────────────────────────────────────
+  /**
+   * A camera-related error occurred. Inspect `cameraCode` for the specific reason.
+   * @see CameraErrorCode
+   */
+  CAMERA_ERROR = 'CAMERA_ERROR',
+
+  // ── Network & API ────────────────────────────────────────────────────────
+  /** A network-level failure (no internet, CORS, DNS). */
+  NETWORK_ERROR = 'NETWORK_ERROR',
+  /** The backend returned a non-2xx HTTP status. */
+  API_ERROR = 'API_ERROR',
+
+  // ── Configuration ────────────────────────────────────────────────────────
+  /** The `containerId` provided in the config does not exist in the DOM. */
+  CONTAINER_NOT_FOUND = 'CONTAINER_NOT_FOUND',
+  /** `start()` was called on an SDK instance that is already running. */
+  ALREADY_STARTED = 'ALREADY_STARTED',
+  /** `start()` was called after `destroy()`. The instance is no longer usable. */
+  INSTANCE_DESTROYED = 'INSTANCE_DESTROYED',
+
+  /**
+   * The page is running inside an iframe and embedding was not explicitly allowed.
+   * Configure Content-Security-Policy: frame-ancestors or X-Frame-Options on the
+   * page that hosts the SDK, or set allowEmbedded: true if embedding is intentional.
+   */
+  INSECURE_EMBED = 'INSECURE_EMBED',
+
+  /**
+   * The CDN-served manifest could not be downloaded or its Ed25519 signature did
+   * not verify against the loader's embedded public key. The loader refuses to
+   * mount the iframe to prevent execution of tampered/unsigned bundles.
+   */
+  INTEGRITY_FAILED = 'INTEGRITY_FAILED',
+
+  UNKNOWN = 'UNKNOWN',
+}
+
+/**
+ * A structured, machine-readable error object emitted by the SDK.
+ *
+ * @example
+ * ```typescript
+ * const sdk = new VelionOnboarding({
+ *   onError: (err) => {
+ *     if (err.code === SdkErrorCode.CAMERA_ERROR &&
+ *         err.cameraCode === CameraErrorCode.PERMISSION_DENIED) {
+ *       showCameraPermissionDialog();
+ *     }
+ *   }
+ * });
+ * ```
+ */
+export interface SdkError {
+  /** Primary SDK-level error classification. */
+  readonly code: SdkErrorCode;
+  /** Human-readable English description for developer logging. */
+  readonly message: string;
+  /** Present when `code === SdkErrorCode.SESSION_DECLINED` (SSE `reason`). */
+  readonly declineReason?: string;
+  /** Present when `code === SdkErrorCode.SESSION_DECLINED` (SSE `step_code`). */
+  readonly stepCode?: string;
+  /**
+   * Localized headline resolved by the SDK for SESSION_DECLINED.
+   * Useful when hosts hide the built-in final result screen but still want
+   * the same user-facing text in custom UI.
+   */
+  readonly declineTitle?: string;
+  /**
+   * Localized body message resolved by the SDK for SESSION_DECLINED.
+   * Mirrors the text shown in the built-in final result screen.
+   */
+  readonly declineMessage?: string;
+  /** Present when `code === SdkErrorCode.CAMERA_ERROR`. Provides camera-specific detail. */
+  readonly cameraCode?: CameraErrorCode;
+  /** HTTP status code when the error originated from an API call. */
+  readonly httpStatus?: number;
+  /**
+   * The original caught value for debugging.
+   * Not guaranteed to be an `Error` instance — could be a DOMException or string.
+   */
+  readonly cause?: unknown;
+}
+
+// ─────────────────────────────────────────────────────────────────────────────
+// THEMING
+// ─────────────────────────────────────────────────────────────────────────────
+
+/**
+ * White-labeling theme configuration.
+ * Each property maps to a CSS custom property injected on the SDK container,
+ * making all SDK UI elements styleable via `--vl-*` variables.
+ *
+ * @example
+ * ```typescript
+ * const theme: VelionTheme = {
+ *   primaryColor: '#0052CC',      // → --vl-primary-color
+ *   borderRadius: '12px',          // → --vl-border-radius
+ *   fontFamily: 'Inter, sans-serif'// → --vl-font-family
+ * };
+ * ```
+ */
+export interface VelionTheme {
+  /** Primary brand color. Used for buttons, progress indicators, and accents. */
+  primaryColor?: string;
+  /** Secondary color. Used for hover states and secondary actions. */
+  secondaryColor?: string;
+  /** Background color of the SDK container. */
+  backgroundColor?: string;
+  /** Main body text color. */
+  textColor?: string;
+  /** Secondary text color for subtitles, captions, and de-emphasized copy. */
+  textSecondaryColor?: string;
+  /** Border radius for cards, buttons, and inputs. */
+  borderRadius?: string;
+  /** Font family string. Must be available in the host page's CSS context. */
+  fontFamily?: string;
+  /** Color used for error states and destructive actions. */
+  errorColor?: string;
+  /** Color used for success confirmations. */
+  successColor?: string;
+  /** Color used for warnings and informational alerts. */
+  warningColor?: string;
+  /** Border color for input fields and separators. */
+  borderColor?: string;
+  /** Box shadow definition for elevated elements (cards, modals). */
+  cardShadow?: string;
+  /**
+   * When true, the SDK omits the round colored icon next to each step's
+   * title — only the title + subtitle are rendered. Useful for hosts that
+   * prefer a denser, all-text layout.
+   *
+   * @default false
+   */
+  hideStepIcons?: boolean;
+  /**
+   * When true, the sticky top progress bar is hidden across the whole flow.
+   * Equivalent to setting `VelionConfig.showProgressBar = false` — both
+   * paths are honored, so hosts can pick either depending on whether they
+   * model the choice as configuration (lifecycle) or theming (visual).
+   *
+   * @default false
+   */
+  hideProgressBar?: boolean;
+}
+
+/**
+ * Optional title and body for one terminal verdict on the final result screen.
+ */
+export interface VelionFinalResultStatusCopy {
+  title?: string;
+  message?: string;
+}
+
+/**
+ * Configurable copy for the built-in final result screen (`showFinalResultScreen`).
+ * Omitted fields fall back to SDK defaults for the active `locale`.
+ */
+export interface VelionFinalResultScreenTexts {
+  approved?: VelionFinalResultStatusCopy;
+  manualReview?: VelionFinalResultStatusCopy;
+  rejected?: VelionFinalResultStatusCopy;
+  /** Copy when {@link OnboardingResult.status} is `DECLINED`. */
+  declined?: VelionFinalResultStatusCopy;
+  /** Primary button label (e.g. "Entendido" / "Got it"). */
+  dismissLabel?: string;
+}
+
+/**
+ * Localized title/body for one `reason` on the SESSION_DECLINED screen.
+ * Keys match backend `reason` (e.g. `TAX_INFO_FAILED`).
+ */
+export interface VelionSessionDeclinedReasonMessages {
+  en?: VelionFinalResultStatusCopy;
+  es?: VelionFinalResultStatusCopy;
+}
+
+/**
+ * Per-reason overrides for the built-in SESSION_DECLINED screen (`showFinalResultScreen` not false).
+ * Unspecified reasons fall back to SDK defaults when available, then generic copy.
+ */
+export type VelionSessionDeclinedReasonTexts = Record<
+  string,
+  VelionSessionDeclinedReasonMessages
+>;
+
+// ─────────────────────────────────────────────────────────────────────────────
+// CALLBACKS
+// ─────────────────────────────────────────────────────────────────────────────
+
+/**
+ * The complete set of lifecycle callbacks the host application can subscribe to.
+ * All callbacks are optional. The SDK is still functional without any of them,
+ * but `onError` and `onSuccess` are strongly recommended for production.
+ */
+export interface VelionCallbacks {
+  /**
+   * Fires when the entire onboarding flow has been completed successfully
+   * and the backend has confirmed the session as resolved.
+   *
+   * @param result - Final onboarding verdict from the backend.
+   */
+  onSuccess?: (result: OnboardingResult) => void;
+
+  /**
+   * Fires when an unrecoverable error terminates the onboarding flow.
+   * Any terminal failure (camera error, document capture failure, upload failure,
+   * liveness failure, API error, etc.) is delivered here so the host can notify the user.
+   * After this callback, the SDK instance is in an error state.
+   * Call `sdk.destroy()` and re-instantiate to retry.
+   *
+   * @param error - Structured error with a machine-readable code (e.g. CAMERA_ERROR, DOCUMENT_UPLOAD_FAILED).
+   */
+  onError?: (error: SdkError) => void;
+
+  /**
+   * Fires each time the active step changes during the flow.
+   * Useful for updating a custom step indicator in the host UI.
+   *
+   * The required step list is resolved dynamically by the backend, so the SDK
+   * does not know the total step count up front. Callers that need a progress
+   * indicator should rely on the SDK's built-in progress bar (or the trickling
+   * counter in `stepIndex`).
+   *
+   * @param step - The step that just became active.
+   * @param stepIndex - Zero-based index of the current step.
+   */
+  onStepChange?: (step: OnboardingStep, stepIndex: number) => void;
+
+  /**
+   * Fires immediately after a step succeeds, before advancing to the next one.
+   * Useful for analytics or triggering intermediate UI transitions.
+   *
+   * @param step - The step that was just completed.
+   */
+  onStepComplete?: (step: OnboardingStep) => void;
+
+  /**
+   * Fires for each SSE event from GET /sessions/:sessionId/events
+   * (e.g. STEP_UPDATED, SESSION_APPROVED).
+   */
+  onSessionEvent?: (event: OnboardingSessionEvent) => void;
+
+  /**
+   * Called when the user taps the dismiss control on the final result screen
+   * (only when the final result screen is shown). `onSuccess` has already run.
+   */
+  onFinalResultScreenDismiss?: () => void;
+}
+
+// ─────────────────────────────────────────────────────────────────────────────
+// MAIN CONFIGURATION
+// ─────────────────────────────────────────────────────────────────────────────
+
+/**
+ * Root configuration object for the `VelionOnboarding` class.
+ *
+ * @example
+ * ```typescript
+ * const sdk = new VelionOnboarding({
+ *   containerId: 'velion-root',
+ *   sessionId: 'ses_abc123',
+ *   sessionToken: 'eyJhbGciOiJIUzI1NiIsInR5cCI6IkpXVCJ9...',
+ *   apiUrl: 'https://api.velion.la/v1',
+ *   theme: { primaryColor: '#0052CC' },
+ *   onSuccess: (result) => console.log('Done!', result),
+ *   onError: (err) => console.error('SDK Error:', err),
+ * });
+ *
+ * await sdk.start();
+ * ```
+ */
+export interface VelionConfig extends VelionCallbacks {
+  /**
+   * The `id` of an existing DOM element where the SDK will render its UI.
+   * The element **must** be present in the document at the time `start()` is called.
+   *
+   * @example `'velion-kyc-container'`
+   */
+  containerId: string;
+
+  /**
+   * The unique session identifier generated by your backend for this
+   * onboarding session. Used to scope all API calls.
+   *
+   * @example `'ses_9f8d7c6b5a4e3f2d'`
+   */
+  sessionId: string;
+
+  /**
+   * A short-lived, opaque authorization token (e.g. HS256 JWT) issued by your
+   * backend when creating the session. Sent as `Authorization: Bearer <sessionToken>`
+   * on every SDK request. Required for all endpoints behind the gateway.
+   *
+   * **Security note:** This token is held in memory only (never in localStorage
+   * or cookies) and is automatically discarded on `destroy()`.
+   */
+  sessionToken: string;
+
+  /**
+   * ISO-8601 expiry timestamp of the sessionToken. If provided, the SDK may
+   * check expiration before requests and emit SESSION_EXPIRED without a round-trip.
+   * When the backend returns 401/403, the SDK emits SESSION_EXPIRED anyway.
+   */
+  expiresAt?: string;
+
+  /**
+   * Base URL of the Velion onboarding edge. Must **not** include a trailing slash.
+   * SDK paths are relative to this (e.g. GET `/sessions/{sessionId}`).
+   *
+   * Defaults to the public production edge `https://sdk.velion.la/onboarding`.
+   * Override only for staging or self-hosted environments.
+   */
+  apiUrl?: string;
+
+  /**
+   * Optional white-labeling theme. If omitted, SDK renders with Velion defaults.
+   */
+  theme?: VelionTheme;
+
+  /**
+   * Global visual mode for SDK overlays and controls.
+   * - `'light'`: Light translucent surfaces.
+   * - `'dark'`: Dark translucent surfaces.
+   *
+   * @default 'light'
+   */
+  colorMode?: 'light' | 'dark';
+
+  /**
+   * BCP 47 locale tag for SDK UI copy (labels, instructions, error messages).
+   *
+   * @default 'es'
+   */
+  locale?: string;
+
+  /**
+   * When `true`, after the backend returns a terminal verdict the SDK shows a
+   * full-screen summary (APPROVED, MANUAL_REVIEW, REJECTED) inside the container,
+   * styled with `theme` and `colorMode`. `onSuccess` still fires with the result.
+   *
+   * @default true
+   */
+  showFinalResultScreen?: boolean;
+
+  /**
+   * When `true` (default), the SDK renders a thin progress bar at the top of
+   * the container that advances as the user moves through steps. Disable for
+   * embedded experiences that already provide their own progress UI.
+   *
+   * @default true
+   */
+  showProgressBar?: boolean;
+
+  /**
+   * Overrides for default titles, messages, and dismiss button on the final result screen.
+   * Only used when the final result screen is shown (`showFinalResultScreen` is not `false`).
+   */
+  finalResultScreenTexts?: VelionFinalResultScreenTexts;
+
+  /**
+   * Optional copy for SESSION_DECLINED SSE screens, keyed by backend `reason`.
+   * Merged with SDK defaults (e.g. `TAX_INFO_FAILED`) for `locale` `en` / `es`.
+   */
+  sessionDeclinedReasonTexts?: VelionSessionDeclinedReasonTexts;
+
+  /**
+   * When `true` (default), shows the Velion preparation screen (face icon, tips,
+   * "Start verification") before connecting to Iris. When `false`, skips it and
+   * starts the camera + Iris session immediately on step entry.
+   *
+   * @default true
+   */
+  livenessShowIntro?: boolean;
+
+  /**
+   * When `false`, hides the "Atrás" / "Back" button on the liveness preparation
+   * screen. The button is only present in the intro; once the camera capture
+   * begins the user must complete the Iris challenges to leave the step.
+   *
+   * @default true
+   */
+  livenessShowBackButton?: boolean;
+
+  /**
+   * If true, allows the SDK to run when the page is inside an iframe.
+   * Only set to true if you have configured Content-Security-Policy: frame-ancestors
+   * or X-Frame-Options on the HTTP response of the page that hosts the SDK.
+   * If false (default) and the page is embedded in an iframe, the SDK emits
+   * INSECURE_EMBED and does not start.
+   *
+   * @default false
+   */
+  allowEmbedded?: boolean;
+
+  /**
+   * Internal — set by the Velion CDN entry (`cdn-main.ts`) to the `event.origin`
+   * captured from the loader's first VELION_INIT message. The SDK validates it
+   * against `allowed_parent_origins` returned by the backend and refuses to start
+   * if the origin is not in the customer's registered allowlist.
+   *
+   * Direct integrators (running VelionOnboarding without the loader iframe)
+   * should leave this unset.
+   *
+   * @internal
+   */
+  iframeParentOrigin?: string;
+
+  /**
+   * Fingerprint Pro API endpoint (custom subdomain). Used by the DEVICE_FINGERPRINT
+   * step to load and identify visitors. Only set this when using a custom Fingerprint
+   * subdomain or proxy; otherwise the default Velion endpoint is used.
+   *
+   * @default 'https://fp.velion.la'
+   */
+  fingerprintEndpoint?: string;
+
+  /**
+   * Override the public Fingerprint Pro API key used by the DEVICE_FINGERPRINT step.
+   * Useful if the integrator has its own Fingerprint workspace and bundle-ID
+   * authorisation. When omitted, the SDK uses Velion's shared public key.
+   */
+  fingerprintApiKey?: string;
+
+  /**
+   * Hard ceiling for the Fingerprint identify call (ms). The native SDK has its
+   * own internal timeout which on iOS occasionally hangs past the documented
+   * limit; the SDK races against this value to guarantee a clean failure path.
+   *
+   * @default 15000
+   */
+  fingerprintTimeoutMs?: number;
+
+  /**
+   * Google Maps Platform API key (Maps JavaScript API + Places). Required for the
+   * {@code ADDRESS_INFO} step to show the map, search, and geocoding. Omit only if
+   * your flow never reaches that step.
+   */
+  googleMapsApiKey?: string;
+
+  /**
+   * Optional calibration tag forwarded to Iris for the LIVENESS_MATCH step.
+   * When the Iris worker is running with `CALIBRATION_BACKEND=fs|gcs`, every
+   * frame of this session is mirrored to the dataset bucket with the tag in
+   * `metadata.json`, so we can build labeled training sets for the spoof /
+   * liveness models. Does NOT affect the score.
+   *
+   * Suggested values (must match the worker's known labels — see
+   * `iris-worker` README): `REAL_GOOD_LIGHT`, `REAL_BAD_LIGHT`, `REAL_BACKLIT`,
+   * `REAL_BUSY_BG`, `REAL_NEUTRAL_BG`, `REAL_GLASSES`, `REAL_OUTDOOR`,
+   * `FAKE_PHONE_PHOTO`, `FAKE_PHONE_VIDEO`, `FAKE_TABLET_VIDEO`,
+   * `FAKE_MONITOR_VIDEO`, `FAKE_PRINT`, `FAKE_MASK`, `UNKNOWN`, `EDGE_CASE`.
+   *
+   * Leave undefined for normal user-facing sessions.
+   */
+  livenessCalibrationLabel?: string;
+
+  /**
+   * When true, the SDK enables verbose `console.info` logging at runtime even in
+   * production builds. Useful when reproducing customer issues. Independent of the
+   * build-time `__DEBUG__` flag, which already gates dev-server logs.
+   *
+   * @default false
+   */
+  debug?: boolean;
+}
+
+// ─────────────────────────────────────────────────────────────────────────────
+// BACKEND RESPONSE SHAPES
+// ─────────────────────────────────────────────────────────────────────────────
+
+/**
+ * Backend step DTO (OnboardingStepDto). GET session returns an array of these.
+ */
+export interface OnboardingStepDto {
+  code: string;
+  name?: string;
+  description?: string;
+  order?: number;
+  status?: string;
+  required?: boolean;
+  /** Step-specific payload (e.g. OCR fields, fingerprint, T&amp;C items). */
+  result?: Record<string, unknown>;
+}
+
+/**
+ * Backend session/onboarding DTO (OnboardingDto). Returned by GET /sessions/:sessionId.
+ * The SDK maps this to SessionState for the step machine.
+ */
+export interface OnboardingDtoResponse {
+  id?: string;
+  related_id?: string;
+  onboarding_type?: string;
+  status?: string;
+  current_step?: {
+    code?: string;
+    status?: string;
+    config?: Record<string, unknown>;
+  };
+  steps?: OnboardingStepDto[];
+  created_at?: string;
+  updated_at?: string;
+  completed_at?: string;
+  metadata?: Record<string, unknown>;
+  /**
+   * Origins (scheme + host + port) authorized by the customer to embed the SDK.
+   * The iframe validates `event.origin` of the loader's first VELION_INIT against
+   * this list and aborts with INSECURE_EMBED otherwise. Backend must also enforce
+   * server-side via the `Origin` header on every API call.
+   */
+  allowed_parent_origins?: string[];
+}
+
+/**
+ * Session state used by the SDK step machine. Derived from GET /sessions/:sessionId
+ * (OnboardingDto): steps sorted by order → requiredSteps, first non-completed index → currentStepIndex.
+ */
+export interface SessionState {
+  /** Current runnable step reported by backend session state. */
+  currentStep?: OnboardingStep;
+  /** Step-specific config for `currentStep` from GET /sessions/:id `current_step.config`. */
+  currentStepConfig?: Record<string, unknown>;
+  /** Cached configs discovered from GET session and SSE `step_config`. */
+  stepConfigs?: StepConfigMap;
+  /** Session type (HUMAN or LEGAL). Constrains which steps are applicable. */
+  onboardingType?: OnboardingType;
+  /** Arbitrary session metadata the backend may attach. */
+  metadata?: Record<string, unknown>;
+  /**
+   * Customer-registered allowlist of origins authorized to embed the SDK.
+   * When provided, the SDK validates the loader's parent origin against this list.
+   */
+  allowedParentOrigins?: string[];
+}
+
+/**
+ * A single T&amp;C line item (matches backend TermsAndConditionsItemDto / domain record).
+ */
+export interface TermsAndConditionsItem {
+  id: string;
+  description: string;
+  /** Optional URL to the full document. */
+  link?: string;
+}
+
+/**
+ * Response from session creation (POST from your backend). Use sessionId and
+ * sessionToken when instantiating VelionOnboarding; pass expiresAt for optional
+ * client-side expiration checks.
+ */
+export interface SessionCreationResponse {
+  session_id: string;
+  session_token: string;
+  expires_at: string;
+  status?: string;
+}
+
+/**
+ * Shape of the final result returned by `GET /sessions/:sessionId/result`
+ * once all steps are complete.
+ */
+export interface OnboardingResult {
+  /** The session ID that was completed. Matches `VelionConfig.sessionId`. */
+  sessionId: string;
+  /** ISO 8601 timestamp of when the backend finalized the session. */
+  completedAt: string;
+  /**
+   * The final KYC verdict.
+   * - `APPROVED`: All checks passed automatically.
+   * - `MANUAL_REVIEW`: Flagged for human review (common in AML flows). Backend `IN_REVIEW` maps here.
+   * - `REJECTED`: Automatically rejected (fraud signals, liveness failure, etc.).
+   * - `DECLINED`: Session ended in a declined state (matches GET session `status: DECLINED`).
+   */
+  status: 'APPROVED' | 'MANUAL_REVIEW' | 'REJECTED' | 'DECLINED';
+  /** An optional tracking reference for support and audit trails. */
+  referenceId?: string;
+  /**
+   * When the terminal outcome came from SSE, optional backend `reason` (e.g.
+   * `LIVENESS_SCORE_IN_REVIEW_RANGE` on SESSION_MANUAL_REVIEW) for localized final-screen copy.
+   */
+  terminalReason?: string;
+}
+
+/**
+ * Response from `POST /sessions/:sessionId/liveness-init`.
+ * The backend returns the Iris session details the SDK needs to open the WebSocket
+ * and stream frames. Credentials are not used: Iris owns the session lifecycle.
+ */
+export interface LivenessSessionResponse {
+  /** Iris session identifier. */
+  liveness_session_id?: string;
+  /** Full WebSocket URL the SDK must connect to (e.g. wss://iris.host/ws/iris/{id}). */
+  websocket_url?: string;
+  /** ISO-8601 expiry of the Iris session. */
+  expires_at?: string;
+  /** Effective Iris challenge identifiers in order (TURN_LEFT, SMILE, …). */
+  challenges?: string[];
+  /** Optional JWT for the WebSocket handshake when Iris auth is enabled. */
+  connection_token?: string;
+  /**
+   * Optional base64 HMAC-SHA256 key. When present, the SDK signs every JPEG
+   * frame in a JSON envelope (canonical line: `sessionId\nframeId\nts\nsha256hex(jpeg)`).
+   */
+  frame_integrity_key_base64?: string;
+}
+
+/**
+ * Payload for POST /sessions/:sessionId/basic-info/human (HUMAN_BASIC_INFO step).
+ * Matches backend SubmitHumanBasicInfoRequestDto (snake_case in JSON).
+ */
+export interface HumanBasicInfoPayload {
+  first_name: string;
+  middle_name?: string;
+  last_name: string;
+  second_last_name?: string;
+  identification_type: string;
+  identification_id: string;
+}
+
+/**
+ * Payload for POST /sessions/:sessionId/basic-info/legal (LEGAL_BASIC_INFO step).
+ * Matches backend SubmitLegalBasicInfoRequestDto (snake_case in JSON).
+ */
+export interface LegalBasicInfoPayload {
+  legal_name: string;
+  legal_form: string;
+  identification_type: string;
+  identification_id: string;
+}
+
+/**
+ * Single selectable option for tax category or fiscal identifier type (TAX_INFO step).
+ * `id` is submitted to the API; `description` is the user-visible label.
+ */
+export interface TaxInfoOption {
+  id: string;
+  description: string;
+}
+
+/**
+ * Resolved selectable lists for the TAX_INFO step UI (from `accepted_tax_information` only; no SDK defaults).
+ */
+export interface TaxInfoConfig {
+  /**
+   * Fiscal regime / category options (e.g. Monotributo). The chosen `id` is sent as `taxpayer_type`.
+   */
+  taxpayerCategories: TaxInfoOption[];
+  /**
+   * Tax identification scheme options (e.g. CUIT). The chosen `id` is sent as `taxpayer_id_type`.
+   */
+  fiscalIdentifierTypes: TaxInfoOption[];
+}
+
+/** POST /sessions/:id/tax-info — SubmitTaxInfoRequestDto. */
+export interface TaxInfoPayload {
+  /** Selected fiscal category value (`code` from step config `taxpayer_categories`). */
+  taxpayer_type: string;
+  /** Selected fiscal identifier kind id (e.g. `CUIT` from step config `identification_types`). */
+  taxpayer_id_type: string;
+  /** Tax identification number for the chosen type. */
+  taxpayer_id: string;
+}
+
+/** POST /sessions/:id/extended-info/human — SubmitHumanExtendedInfoRequestDto. */
+export interface HumanExtendedInfoPayload {
+  gender?: string;
+  civil_status?: string;
+  birth_date?: string;
+  birth_country?: string;
+  citizenship?: string;
+  residence_country?: string;
+}
+
+/** POST /sessions/:id/extended-info/legal — SubmitLegalExtendedInfoRequestDto. */
+export interface LegalExtendedInfoPayload {
+  incorporation_date: string;
+  incorporation_country: string;
+}
+
+/** POST /sessions/:id/address-info — SubmitAddressInfoRequestDto. */
+export interface AddressInfoPayload {
+  type: string;
+  country: string;
+  state: string;
+  city: string;
+  district?: string;
+  neighborhood?: string;
+  street: string;
+  number: string;
+  floor?: string;
+  apartment?: string;
+  details?: string;
+  zip_code: string;
+  latitude?: number;
+  longitude?: number;
+}
+
+/** POST /sessions/:id/sworn-declaration — SubmitSwornDeclarationRequestDto. */
+export interface SwornDeclarationPayload {
+  is_pep: boolean;
+  is_ssoo: boolean;
+  is_fatca: boolean;
+  is_ocde: boolean;
+}
+
+/** POST /sessions/:id/contact/email — SubmitEmailContactRequestDto. */
+export interface EmailContactPayload {
+  email: string;
+}
+
+/** POST /sessions/:id/contact/phone — SubmitPhoneContactRequestDto. */
+export interface PhoneContactPayload {
+  phone: string;
+}
+
+/** POST /sessions/:id/terms-and-conditions — SubmitTermsAndConditionsRequestDto. */
+export interface TermsAndConditionsAcceptancePayload {
+  item_id: string;
+  accepted: boolean;
+}
+
+export interface TermsAndConditionsSubmitPayload {
+  acceptances: TermsAndConditionsAcceptancePayload[];
+}
+
+/**
+ * SSE event payload (OnboardingSessionEvent). Matches the backend record
+ * la.velion.onboarding.api...sdk.OnboardingSessionEventDto (snake_case in JSON).
+ *
+ * Received on GET /public/sdk/sessions/:sessionId/events. The backend sends
+ * ServerSentEvent with id = event_id (epoch millis) for Last-Event-ID replay.
+ *
+ * Event types (event_type):
+ * - STEP_UPDATED — a workflow step changed status (step_code, step_status)
+ * - ROUTING_COMMAND — next/retry/terminate instruction (action: NEXT_STEP | RETRY_STEP | TERMINATE)
+ * - SESSION_APPROVED — all checks passed; session_status = APPROVED
+ * - SESSION_MANUAL_REVIEW — manual review required; session_status = MANUAL_REVIEW
+ * - SESSION_DECLINED — session ended with decline (step_code, session_status DECLINED, reason)
+ */
+export interface OnboardingSessionEvent {
+  /** Onboarding session identifier (Long in backend). */
+  session_id?: number;
+  /** Discriminator: STEP_UPDATED | ROUTING_COMMAND | SESSION_APPROVED | SESSION_MANUAL_REVIEW | SESSION_DECLINED */
+  event_type?: string;
+  /** Present for STEP_UPDATED or ROUTING_COMMAND (next step code). */
+  step_code?: string;
+  /** Present for STEP_UPDATED; e.g. COMPLETED. */
+  step_status?: string;
+  /** Present for terminal events; e.g. APPROVED | MANUAL_REVIEW | REJECTED. */
+  session_status?: string;
+  /** For ROUTING_COMMAND: NEXT_STEP | RETRY_STEP (render step_code) or TERMINATE (end flow). */
+  action?: string;
+  /** For SESSION_DECLINED / SESSION_MANUAL_REVIEW or ROUTING_COMMAND TERMINATE; e.g. UNREADABLE_DOCUMENT. */
+  reason?: string;
+  /** Step-specific config sent with ROUTING_COMMAND NEXT_STEP. */
+  step_config?: Record<string, unknown>;
+  /** Epoch millis; used as SSE id for Last-Event-ID on reconnect. */
+  event_id?: number;
+}
+
+// ─────────────────────────────────────────────────────────────────────────────
+// BACKEND COMMANDS (Listen & Obey)
+// ─────────────────────────────────────────────────────────────────────────────
+
+/**
+ * Backend command: advance to a specific step. The SDK must render that step's
+ * screen without evaluating business rules locally.
+ */
+export interface BackendCommandGoToStep {
+  action: 'GO_TO_STEP';
+  stepCode: OnboardingStep;
+}
+
+/**
+ * Backend command: show an error message to the user. The SDK displays the
+ * message and does not advance (backend owns the decision).
+ */
+export interface BackendCommandShowError {
+  action: 'SHOW_ERROR';
+  message: string;
+}
+
+/**
+ * Backend command: flow is complete. SDK should fetch final result and fire onSuccess.
+ */
+export interface BackendCommandFlowComplete {
+  action: 'FLOW_COMPLETE';
+}
+
+/**
+ * Backend command: retry the current step (e.g. after transient failure).
+ */
+export interface BackendCommandRetry {
+  action: 'RETRY';
+}
+
+/**
+ * Strict command payload the backend may return in a synchronous HTTP response
+ * or send via SSE. The SDK never makes routing decisions; it only obeys these commands.
+ */
+export type BackendCommand =
+  | BackendCommandGoToStep
+  | BackendCommandShowError
+  | BackendCommandFlowComplete
+  | BackendCommandRetry;
+
+/**
+ * Raw response body that may contain a backend command (e.g. POST submit response).
+ */
+export interface BackendCommandResponse {
+  action?: string;
+  stepCode?: string;
+  message?: string;
+}
+
+// ─────────────────────────────────────────────────────────────────────────────
+// INTERNAL STATE MACHINE TYPES (exported for module authors)
+// ─────────────────────────────────────────────────────────────────────────────
+
+/**
+ * All possible states of the SDK's internal lifecycle.
+ * Transitions are strictly unidirectional (no going back to IDLE once started).
+ *
+ * @internal
+ */
+export type SdkStatus =
+  | 'IDLE'           // Instantiated, not yet started
+  | 'INITIALIZING'   // Fetching session state from backend
+  | 'RUNNING'        // Orchestrating steps
+  | 'STEP_PROCESSING'// A module is actively running
+  | 'COMPLETED'      // All steps done, onSuccess fired
+  | 'ERROR'          // Unrecoverable error, onError fired
+  | 'DESTROYED';     // destroy() was called, instance is a no-op
+
+/**
+ * Internal event bus event names. Typed via `SdkEventMap`.
+ * @internal
+ */
+export type SdkEventName =
+  | 'step:change'
+  | 'step:complete'
+  | 'session:loaded'
+  | 'flow:complete'
+  | 'error'
+  | 'status:change';
+
+/**
+ * Maps each internal event name to its payload type.
+ * Used by the `TypedEventEmitter` for compile-time safety.
+ * @internal
+ */
+export interface SdkEventMap extends Record<string, unknown> {
+  'step:change': { step: OnboardingStep; index: number };
+  'step:complete': { step: OnboardingStep };
+  'session:loaded': SessionState;
+  'flow:complete': OnboardingResult;
+  'error': SdkError;
+  'status:change': SdkStatus;
+}
+
+// ─────────────────────────────────────────────────────────────────────────────
+// LOADER ↔ CDN APP POSTMESSAGE PROTOCOL (Sumsub-style)
+// ─────────────────────────────────────────────────────────────────────────────
+
+/** Message type: parent (loader) sends config to iframe (CDN app). */
+export const VELION_MSG_INIT = 'VELION_INIT' as const;
+
+/** Message types: iframe (CDN app) sends to parent (loader). */
+export const VELION_MSG_READY = 'VELION_READY' as const;
+export const VELION_MSG_SUCCESS = 'VELION_SUCCESS' as const;
+export const VELION_MSG_ERROR = 'VELION_ERROR' as const;
+export const VELION_MSG_STEP_CHANGE = 'VELION_STEP_CHANGE' as const;
+export const VELION_MSG_STEP_COMPLETE = 'VELION_STEP_COMPLETE' as const;
+export const VELION_MSG_TOKEN_EXPIRED = 'VELION_TOKEN_EXPIRED' as const;
+
+/** Message type: parent sends new token to iframe after VELION_TOKEN_EXPIRED. */
+export const VELION_MSG_TOKEN = 'VELION_TOKEN' as const;
+
+export type VelionMessageType =
+  | typeof VELION_MSG_INIT
+  | typeof VELION_MSG_READY
+  | typeof VELION_MSG_SUCCESS
+  | typeof VELION_MSG_ERROR
+  | typeof VELION_MSG_STEP_CHANGE
+  | typeof VELION_MSG_STEP_COMPLETE
+  | typeof VELION_MSG_TOKEN_EXPIRED
+  | typeof VELION_MSG_TOKEN;
+
+/** Envelope for all loader ↔ iframe messages. Both sides must validate origin. */
+export interface VelionMessage<T = unknown> {
+  type: VelionMessageType;
+  payload: T;
+}
+
+/** Payload for VELION_INIT: full config (iframe runs with containerId overwritten to root id). */
+export type VelionInitPayload = VelionConfig;
+
+/** Payload for VELION_STEP_CHANGE. */
+export interface VelionStepChangePayload {
+  step: OnboardingStep;
+  stepIndex: number;
+}
+
+/** Payload for VELION_STEP_COMPLETE. */
+export interface VelionStepCompletePayload {
+  step: OnboardingStep;
+}
+
+/** Payload for VELION_TOKEN (token refresh response from parent to iframe). */
+export interface VelionTokenPayload {
+  sessionToken: string;
+  expiresAt?: string;
+}