@incodetech/core 2.1.1 → 2.2.0-rc.0

package/dist/idCaptureManager-BjU-Wyow.d.ts

@@ -0,0 +1,429 @@
+import { A as StateMachine, i as ActorRefFrom, l as AnyStateMachine } from "./spawn-D9jgw9pW.js";
+import "./StateMachine-EDpYWy0i.js";
+import { t as Manager } from "./Manager-CQQ99QOI.js";
+import "./Actor-iTq7YY48.js";
+import { t as IVisibilityObserverCapability } from "./IVisibilityObserverCapability-D4tvIB5v.js";
+import "./index-B8weJxmL.js";
+import { t as CameraStream } from "./camera-9wWD-pwg.js";
+import { a as RegulationTypes } from "./types-KPvmag_B.js";
+import { n as PermissionStatus } from "./types-BEwVKkLJ.js";
+import { t as DeepsightService } from "./deepsightService-DLVQS_RH.js";
+import { i as Pdf417DecodeResult, n as IIdCaptureCapability, t as DetectionOrientation } from "./IIdCaptureCapability-DHTT3FC2.js";
+import { A as ManualUploadSide, C as RecordingSession, T as IAnalyticsCapability, a as DetectionArea, c as IdCaptureConfig, d as IdCaptureEvent, g as IdCaptureOutput, h as IdCaptureOnlyConfig, j as ManualUploadTab, l as IdCaptureContext, m as IdCaptureMode, n as CaptureIdResponse, o as DetectionStatus, p as IdCaptureInput, t as AddBarcodeV3Response, u as IdCaptureDependencies, w as UploadIdResponse, x as IdErrorCode, y as IdDocumentType } from "./types-M6eb82ra2.js";
+//#region src/modules/id/idCaptureStateMachine.d.ts
+declare const idCaptureMachine: AnyStateMachine;
+type IdCaptureMachine = StateMachine<IdCaptureContext, IdCaptureEvent, any, any, any, any, any, any, any, IdCaptureInput, any, any, any, any>;
+//#endregion
+//#region src/modules/id/idCaptureActor.d.ts
+type CreateIdCaptureActorOptions = {
+  config: IdCaptureConfig;
+  dependencies?: IdCaptureDependencies;
+};
+type IdCaptureActor = ActorRefFrom<IdCaptureMachine>;
+declare function createIdCaptureActor(options: CreateIdCaptureActorOptions): IdCaptureActor;
+//#endregion
+//#region src/modules/id/idCaptureOnlyStateMachine.d.ts
+type IdCaptureOnlyContext = IdCaptureContext;
+type IdCaptureOnlyEvent = IdCaptureEvent;
+type IdCaptureOnlyInput = IdCaptureInput;
+/**
+ * ID capture state machine variant for the captureOnly flow. Shares the full
+ * base ID-capture state tree (chooser, tutorial, permissions, capture,
+ * front/back finished, processing, finished); only the upload, process, and
+ * recording steps are local instead of remote.
+ */
+declare const idCaptureOnlyMachine: AnyStateMachine;
+type IdCaptureOnlyMachine = StateMachine<IdCaptureOnlyContext, IdCaptureOnlyEvent, any, any, any, any, any, any, any, IdCaptureOnlyInput, any, any, any, any>;
+//#endregion
+//#region src/modules/id/idCaptureOnlyActor.d.ts
+type CreateIdCaptureOnlyActorOptions = {
+  config: IdCaptureOnlyConfig;
+  dependencies?: IdCaptureDependencies;
+};
+type IdCaptureOnlyActor = ActorRefFrom<IdCaptureOnlyMachine>;
+declare function createIdCaptureOnlyActor(options: CreateIdCaptureOnlyActorOptions): IdCaptureOnlyActor;
+//#endregion
+//#region src/modules/id/idCaptureServices.d.ts
+type IdCaptureInitResult = {
+  stream: CameraStream;
+  provider: IIdCaptureCapability;
+  captureResolution?: string;
+  cameraFallbackLevel?: number;
+};
+type InitializeIdCaptureParams = {
+  config: IdCaptureConfig;
+  deepsightService?: DeepsightService;
+  stream?: CameraStream;
+  cameraFallbackLevel?: number;
+};
+declare function initializeIdCapture(params: InitializeIdCaptureParams): Promise<IdCaptureInitResult>;
+declare function stopStream(stream: CameraStream): void;
+type UploadIdImageParams = {
+  image: string;
+  type: 'front' | 'back';
+  sendBase64?: boolean;
+  isSecondId?: boolean;
+  onlyFront?: boolean;
+  glare?: number;
+  sharpness?: number;
+  shouldSkipGlareBack?: boolean;
+  shouldSkipGlareFront?: boolean;
+  captureType?: string;
+  ageAssurance?: boolean;
+  onProgress?: (progress: number) => void;
+  metadata?: string;
+  signal?: AbortSignal;
+  analyticsProvider?: IAnalyticsCapability;
+  imageData?: ImageData;
+  /**
+   * [ENG-44176] When `false`, attaches `extractIdFace=false` as a query param
+   * to `POST /omni/add/front-id/v2` so the backend skips biometric face
+   * extraction. Forwarded only for `type === 'front'`. Omitted / `true` is a
+   * no-op on the wire (backend default is extraction on).
+   */
+  extractIdFace?: boolean;
+};
+type ValidationError = {
+  error: boolean;
+  message: string;
+  messageDescription?: string;
+  errorKey: IdErrorCode;
+};
+declare function validateUploadResponse(response: UploadIdResponse & {
+  failReason?: string;
+  side?: 'front' | 'back';
+}, sessionState?: {
+  skipGlareFront?: boolean;
+  skipGlareBack?: boolean;
+}): ValidationError | undefined;
+declare function uploadIdImage(params: UploadIdImageParams): Promise<CaptureIdResponse>;
+type StartRecordingParams = {
+  config: IdCaptureConfig;
+  stream: CameraStream;
+  existing?: RecordingSession;
+  type: 'frontId' | 'backId';
+};
+declare function preloadIdRecordingProvider(config: IdCaptureConfig): void;
+declare function startRecordingSession(params: StartRecordingParams): Promise<RecordingSession | undefined>;
+declare function stopRecording(session: RecordingSession): void;
+declare function processId(isSecondId?: boolean, queueName?: string, signal?: AbortSignal): Promise<{
+  isDocumentExpired: boolean;
+}>;
+type UploadManualIdFileParams = {
+  side: 'front' | 'back' | 'passport';
+  /**
+   * Raw base64 payload (no `data:<mime>;base64,` prefix). Callers must strip
+   * the data-URL prefix — the v2 backend rejects data URLs with
+   * `IllegalArgumentException: Illegal base64 character 3a`.
+   */
+  base64Image: string;
+  retry?: boolean;
+  onlyFront?: boolean;
+  signal?: AbortSignal;
+  isSecondId?: boolean;
+  /**
+   * [ENG-44176] When `false`, attaches `extractIdFace=false` to the upload
+   * so the backend skips biometric face extraction. Forwarded only for the
+   * `front` and `passport` sides; back uploads ignore it. Omitted / `true`
+   * is a no-op on the wire.
+   */
+  extractIdFace?: boolean;
+};
+/**
+ * Upload a user-selected image as front / back / passport ID.
+ *
+ * Uses the same request shape as the live-camera path (`uploadIdImage`):
+ * JSON body `{ base64Image }` with default application/json Content-Type,
+ * `captureType=UPLOAD` query param, `retry=true` when retrying.
+ * Back is POSTed to `/omni/add/back-id/v2` (or `/omni/add/back-second-id/v2`
+ * when `isSecondId`); front and passport go to `/omni/add/front-id/v2` (or
+ * `/omni/add/front-second-id/v2` when `isSecondId`).
+ *
+ * The v2 endpoints reject raw `image/jpeg` bodies with 415, so the caller
+ * must convert the File to base64 before calling this service.
+ */
+declare function uploadManualIdFile(params: UploadManualIdFileParams): Promise<UploadIdResponse>;
+/**
+ * UTF-8-safe base64 encoding of a decoded barcode payload. Uses the browser
+ * `TextEncoder` + `btoa` (always available in the SDK's target environment) so
+ * non-ASCII payloads survive `btoa`, which only accepts Latin-1.
+ */
+declare function barcodeToBase64(raw: string): string;
+type AddBarcodeParams = {
+  rawBarcode: string;
+  /** When true (default), the server processes the ID from the barcode. */
+  processId?: boolean;
+  /** PDF417 decode-quality metrics forwarded to the server (best-effort). */
+  metrics?: Pdf417DecodeResult | null;
+  signal?: AbortSignal;
+};
+/**
+ * US Smart Capture: submits a decoded PDF417 barcode to
+ * `POST /omni/add/barcode/v3`. The response drives the downstream front-capture
+ * and Process ID skips (`forceFrontIdCapture` / `idValidationCompleted`).
+ * Mirrors SDK 1's `addBarcode`. Throws (carrying `status`/`data`) on a non-OK
+ * response so the caller can fall back to a full-frame upload. The
+ * hardware-id token is injected by the shared `api` layer, as in `uploadIdImage`.
+ */
+declare function addBarcode(params: AddBarcodeParams): Promise<AddBarcodeV3Response>;
+//#endregion
+//#region src/modules/id/digitalUpload/types.d.ts
+type DigitalUploadFailReason = 'DIGITAL_ID_REQUESTED_BUT_OTHER_PROVIDED' | 'ID_TYPE_UNACCEPTABLE' | 'FILE_CHANGED_ERROR' | 'INVALID_FILE_TYPE' | 'NETWORK_ERROR' | 'GENERIC';
+//#endregion
+//#region src/internal/idCapture/idCaptureManagerFactory.d.ts
+type CaptureStatus = 'initializing' | 'detecting' | 'capturing' | 'holdOn' | 'resultPreview' | 'uploading' | 'uploadError' | 'success';
+type IdCaptureIdleState = {
+  status: 'idle';
+};
+type IdCaptureChooserState = {
+  status: 'chooser';
+  availableDocumentTypes: IdDocumentType[];
+};
+type IdCaptureLoadingState = {
+  status: 'loading';
+};
+type IdCaptureTutorialState = {
+  status: 'tutorial';
+  selectedDocumentType: IdDocumentType | undefined;
+  currentMode: IdCaptureMode;
+};
+type IdCaptureAgeVerificationState = {
+  status: 'ageVerification';
+};
+type IdCapturePermissionsState = {
+  status: 'permissions';
+  permissionStatus: PermissionStatus;
+};
+type IdCaptureCaptureState = {
+  status: 'capture';
+  captureStatus: CaptureStatus;
+  stream: CameraStream | undefined;
+  detectionStatus: DetectionStatus;
+  attemptsRemaining: number;
+  uploadError: IdErrorCode | undefined;
+  currentMode: IdCaptureMode;
+  counterValue: number;
+  orientation: DetectionOrientation | undefined;
+  idType: string | undefined;
+  previewImageUrl?: string;
+  /**
+   * Barcode fast-path success — render the checkmark "Successfully processed!"
+   * screen with NO captured image (the grabbed frame is a backend signal only;
+   * `previewImageUrl` is cleared for this path). See the "after barcode capture
+   * (no image)" design.
+   */
+  barcodeFastPathCaptured: boolean;
+  uploadProgress?: number;
+  ageAssurance: boolean;
+  captureFeedbackMode: 'countdown' | 'result-preview';
+  uploadErrorMessage?: string;
+  uploadErrorDescription?: string;
+  /** Whether back capture is needed after front capture completes */
+  needsBackCapture: boolean;
+  /** Whether front capture is needed after back capture (usSmartCapture + forceFrontIdCapture) */
+  needsFrontCapture: boolean;
+  showCaptureButtonInAuto: boolean;
+  /** Whether retry is available (attemptsRemaining > 0) */
+  canRetry: boolean;
+};
+type IdCaptureMandatoryConsentState = {
+  status: 'mandatoryConsent';
+  regulationType: RegulationTypes;
+};
+type IdCaptureSideFinishedState = {
+  /** Just-captured photo (uxp_idc_exp07), preserved across the side-switch
+   *  reset so the flip screen can render it. Undefined if none was stashed. */
+  previewImageUrl?: string;
+  orientation: DetectionOrientation | undefined;
+  mode: 'id' | 'passport';
+};
+type IdCaptureFrontFinishedState = IdCaptureSideFinishedState & {
+  status: 'frontFinished';
+};
+type IdCaptureBackFinishedState = IdCaptureSideFinishedState & {
+  status: 'backFinished';
+};
+type IdCaptureProcessingState = {
+  status: 'processing';
+};
+type IdCaptureExpiredState = {
+  status: 'expired';
+  /**
+   * Remaining attempts after this expired result. Mirrors V1's
+   * `idv2.capture.processing.attemptsRemainingLabel` counter and Figma's
+   * "X attempts remaining" line on `1-9-11-id-documenterror`.
+   */
+  attemptsRemaining: number;
+  /** Which side just expired — drives the back-specific subtitle in the UI. */
+  currentMode: IdCaptureMode;
+};
+type IdCaptureExpiredExhaustedState = {
+  status: 'expiredExhausted';
+};
+type IdCaptureFinishedState = {
+  status: 'finished';
+  /**
+   * Terminal output of the ID machine — the downstream module-skip signal
+   * (e.g. `skipFaceMatch` for the US Smart Capture "no front, no match" path).
+   * UI-driven modules don't auto-propagate machine output to the orchestrator,
+   * so the UI forwards this to `flowManager.completeModule(output)` on finish.
+   */
+  output?: IdCaptureOutput;
+};
+type IdCaptureClosedState = {
+  status: 'closed';
+};
+type IdCaptureErrorState = {
+  status: 'error';
+  error: string;
+};
+type ManualUploadUploadingSide = ManualUploadSide;
+type IdCaptureManualUploadState = {
+  status: 'manualUpload';
+  phase: 'selecting' | 'uploading' | 'exhausted';
+  /** Which side is currently uploading (undefined in `selecting`/`exhausted`). */
+  uploadingSide: ManualUploadUploadingSide | undefined;
+  activeTab: ManualUploadTab;
+  showIdTab: boolean;
+  showPassportTab: boolean;
+  /** Whether the ID tab should render a back-of-ID slot. */
+  showBackSlot: boolean;
+  frontFileName: string | undefined;
+  backFileName: string | undefined;
+  passportFileName: string | undefined;
+  frontUploaded: boolean;
+  backUploaded: boolean;
+  passportUploaded: boolean;
+  canContinue: boolean;
+  retriesLeft: number;
+  /** i18n key for the current error message, if any. */
+  errorKey: string | null;
+  errorSide: ManualUploadSide | null;
+};
+type IdCaptureDigitalUploadState = {
+  status: 'digitalIdUpload';
+  phase: 'tutorial' | 'selecting' | 'reviewing' | 'uploading' | 'holding' | 'success' | 'error' | 'fileTooLarge' | 'exhausted';
+  file: File | null;
+  fileName: string | undefined;
+  failReason: DigitalUploadFailReason | null;
+  attemptsRemaining: number;
+  uploadProgress: number;
+  pickerRequestId: number;
+};
+type IdCaptureState = IdCaptureIdleState | IdCaptureChooserState | IdCaptureLoadingState | IdCaptureTutorialState | IdCaptureAgeVerificationState | IdCapturePermissionsState | IdCaptureCaptureState | IdCaptureMandatoryConsentState | IdCaptureFrontFinishedState | IdCaptureBackFinishedState | IdCaptureProcessingState | IdCaptureExpiredState | IdCaptureExpiredExhaustedState | IdCaptureFinishedState | IdCaptureClosedState | IdCaptureErrorState | IdCaptureManualUploadState | IdCaptureDigitalUploadState;
+/**
+ * Union of all `idCaptureMachine` variants' actor types. Variants share the
+ * same state tree and context shape, so the manager helpers
+ * (`mapState`, `createApi`) work uniformly for either flavor at runtime.
+ */
+type AnyIdCaptureActor = IdCaptureActor | IdCaptureOnlyActor;
+/**
+ * Builds the public ID capture manager from an already-created actor.
+ * Used by both `createIdCaptureManager` and `createIdCaptureOnlyManager`.
+ *
+ * The internal cast to `IdCaptureActor` narrows the union for `createManager`,
+ * which is typed against the regular machine. Variants produced via
+ * `idCaptureMachine.provide({...})` share the same context and event types,
+ * so the cast is sound at runtime — only the actor implementation differs.
+ *
+ * `visibilityObserver` defaults to the browser `document.visibilitychange`
+ * provider so first-party and BYO-actor callers get foreground/background
+ * events without extra wiring. Construction lives here — a documented,
+ * narrow deviation from "never `new` a provider inside Core" (see
+ * `docs/patterns/CAPABILITY.md`). Pass a fake/no-op to override (tests do).
+ */
+declare function createIdCaptureManagerFromActor(actor: AnyIdCaptureActor, visibilityObserver?: IVisibilityObserverCapability): Manager<IdCaptureState> & {
+  load(): void;
+  selectDocument(documentType: IdDocumentType): void;
+  nextStep(): Promise<void>;
+  /**
+   * Advances out of `resultPreview`. Deliberately untracked: this fires from
+   * the UI's own dwell timer / animationend, not a user action, so it must not
+   * emit an `elementClicked`.
+   */
+  completeResultPreview(): void;
+  requestPermission(): void;
+  goToLearnMore(): void;
+  back(): void;
+  close(): void;
+  reset(): void;
+  retryCapture(): void;
+  continueExhausted(): void;
+  continueFromError(): void;
+  capture(): void;
+  switchToManualCapture(): void;
+  continueToBack(): void;
+  continueToFront(): void;
+  skipBack(): void;
+  acceptMandatoryConsent(): void;
+  cancelMandatoryConsent(): void;
+  /**
+   * Updates the detection area used for WASM geometry calculation.
+   * Call this when the UI detection area dimensions change (e.g., on resize or orientation change).
+   */
+  updateDetectionArea(detectionArea: DetectionArea): void;
+  /**
+   * Manual upload: tab change (ID / Passport). Resets per-tab file selections.
+   * Note: there is intentionally no `switchToManualUpload` method — entry to
+   * the manual-upload flow is gated by config + Chooser to prevent a
+   * dev-console bypass of live camera capture.
+   */
+  manualUploadChangeTab(tab: ManualUploadTab): void;
+  manualUploadSelectFile(side: ManualUploadSide, file: File): void;
+  manualUploadContinue(): void;
+  manualUploadReset(): void;
+  digitalUploadNextStep(): void;
+  digitalUploadPickFile(file: File): void;
+  digitalUploadConfirm(): void;
+  digitalUploadReplace(): void;
+  digitalUploadRetry(): void;
+  digitalUploadScanInstead(): void;
+  digitalUploadChooseAnother(): void;
+};
+type IdCaptureManager = ReturnType<typeof createIdCaptureManagerFromActor>;
+//#endregion
+//#region src/modules/id/idCaptureManager.d.ts
+/**
+ * Creates a manager for the regular ID capture flow. The shared
+ * `mapState`/`createApi`/state-types live in
+ * `internal/idCapture/idCaptureManagerFactory.ts`; this file is a thin
+ * wrapper that creates the actor and delegates to the factory.
+ *
+ * For the captureOnly flow (rich payload delivered locally via `onCapture`),
+ * use `createIdCaptureOnlyManager`.
+ */
+declare function createIdCaptureManager(options: CreateIdCaptureActorOptions): Manager<IdCaptureState> & {
+  load(): void;
+  selectDocument(documentType: IdDocumentType): void;
+  nextStep(): Promise<void>;
+  completeResultPreview(): void;
+  requestPermission(): void;
+  goToLearnMore(): void;
+  back(): void;
+  close(): void;
+  reset(): void;
+  retryCapture(): void;
+  continueExhausted(): void;
+  continueFromError(): void;
+  capture(): void;
+  switchToManualCapture(): void;
+  continueToBack(): void;
+  continueToFront(): void;
+  skipBack(): void;
+  acceptMandatoryConsent(): void;
+  cancelMandatoryConsent(): void;
+  updateDetectionArea(detectionArea: DetectionArea): void;
+  manualUploadChangeTab(tab: ManualUploadTab): void;
+  manualUploadSelectFile(side: ManualUploadSide, file: File): void;
+  manualUploadContinue(): void;
+  manualUploadReset(): void;
+  digitalUploadNextStep(): void;
+  digitalUploadPickFile(file: File): void;
+  digitalUploadConfirm(): void;
+  digitalUploadReplace(): void;
+  digitalUploadRetry(): void;
+  digitalUploadScanInstead(): void;
+  digitalUploadChooseAnother(): void;
+};
+//#endregion
+export { createIdCaptureActor as A, CreateIdCaptureOnlyActorOptions as C, idCaptureOnlyMachine as D, IdCaptureOnlyMachine as E, idCaptureMachine as M, CreateIdCaptureActorOptions as O, validateUploadResponse as S, createIdCaptureOnlyActor as T, startRecordingSession as _, AddBarcodeParams as a, uploadIdImage as b, StartRecordingParams as c, ValidationError as d, addBarcode as f, processId as g, preloadIdRecordingProvider as h, createIdCaptureManagerFromActor as i, IdCaptureMachine as j, IdCaptureActor as k, UploadIdImageParams as l, initializeIdCapture as m, IdCaptureManager as n, IdCaptureInitResult as o, barcodeToBase64 as p, IdCaptureState as r, InitializeIdCaptureParams as s, createIdCaptureManager as t, UploadManualIdFileParams as u, stopRecording as v, IdCaptureOnlyActor as w, uploadManualIdFile as x, stopStream as y };