@velion-la/onboarding-sdk-web 1.1.0-beta.8 → 1.2.0-beta.0

This diff represents the content of publicly available package versions that have been released to one of the supported registries. The information contained in this diff is provided for informational purposes only and reflects changes between package versions as they appear in their respective public registries.
package/dist/index.d.ts CHANGED
@@ -1 +1,1470 @@
1
+ /** POST /sessions/:id/address-info — SubmitAddressInfoRequestDto. */
2
+ export declare interface AddressInfoPayload {
3
+ type: string;
4
+ country: string;
5
+ state: string;
6
+ city: string;
7
+ district?: string;
8
+ neighborhood?: string;
9
+ street: string;
10
+ number: string;
11
+ floor?: string;
12
+ apartment?: string;
13
+ details?: string;
14
+ zip_code: string;
15
+ latitude?: number;
16
+ longitude?: number;
17
+ }
18
+
19
+ /** STEP config for ADDRESS_INFO. */
20
+ export declare interface AddressInfoStepConfig {
21
+ address_type?: {
22
+ id?: string;
23
+ display_value?: string;
24
+ };
25
+ fields?: Partial<Record<'state' | 'city' | 'district' | 'neighborhood' | 'postal_code' | 'street' | 'number', StepFieldRule>>;
26
+ /**
27
+ * Optional ISO 3166-1 alpha-2 allowlist for the country selector. Only
28
+ * consumed by the manual-entry form (when the SDK is configured without a
29
+ * Google Maps key). When unset, every country is offered.
30
+ */
31
+ country_allow?: string[];
32
+ }
33
+
34
+ /**
35
+ * Granular error codes for camera/hardware failures.
36
+ * Allows consumers to display localized, actionable messages to end-users.
37
+ */
38
+ export declare enum CameraErrorCode {
39
+ /** User explicitly denied camera access in the browser permission dialog. */
40
+ PERMISSION_DENIED = "CAMERA_PERMISSION_DENIED",
41
+ /** No camera device was detected on the system. */
42
+ DEVICE_NOT_FOUND = "CAMERA_DEVICE_NOT_FOUND",
43
+ /**
44
+ * The camera could not be opened for reading (often in use by another app,
45
+ * or blocked at the OS level). Maps to `NotReadableError` / `TrackStartError`.
46
+ */
47
+ DEVICE_NOT_READABLE = "CAMERA_DEVICE_NOT_READABLE",
48
+ /**
49
+ * The page is served over HTTP (not HTTPS) in a production environment.
50
+ * `getUserMedia` is blocked by the browser's Secure Context policy.
51
+ */
52
+ INSECURE_CONTEXT = "CAMERA_INSECURE_CONTEXT",
53
+ /**
54
+ * Browser policy blocked camera (e.g. cross-origin iframe without permission,
55
+ * or `Permissions-Policy` / Feature-Policy denying camera). Maps to `SecurityError`
56
+ * from `getUserMedia` — distinct from {@link INSECURE_CONTEXT} (non-HTTPS).
57
+ */
58
+ POLICY_BLOCKED = "CAMERA_POLICY_BLOCKED",
59
+ /** The browser or WebView does not support the `getUserMedia` API. */
60
+ NOT_SUPPORTED = "CAMERA_NOT_SUPPORTED",
61
+ /**
62
+ * Camera access is blocked by a WebView policy (common in in-app browsers
63
+ * on iOS/Android that restrict hardware access).
64
+ */
65
+ WEBVIEW_BLOCKED = "CAMERA_WEBVIEW_BLOCKED",
66
+ /** The requested video constraints (resolution, facing mode) are not satisfiable. */
67
+ CONSTRAINT_ERROR = "CAMERA_CONSTRAINT_ERROR",
68
+ /** An unclassified camera error occurred. Check `cause` for details. */
69
+ UNKNOWN = "CAMERA_UNKNOWN_ERROR"
70
+ }
71
+
72
+ /** Default CDN base URL for the onboarding app (no trailing slash). */
73
+ export declare const DEFAULT_CDN_URL: string;
74
+
75
+ /**
76
+ * How the user can provide document images in the DOCUMENTS_OCR step.
77
+ * - `'camera'`: Only "Take photo" (opens camera on supported devices).
78
+ * - `'file'`: Only "Choose file" (file picker).
79
+ * - `'both'`: Both options; implementer can style via theme.
80
+ *
81
+ * @default 'both'
82
+ */
83
+ export declare type DocumentCaptureMode = 'camera' | 'file' | 'both';
84
+
85
+ /**
86
+ * Orientation of the document capture cutout / crop frame.
87
+ * - `'landscape'`: Horizontal card (default — standard ID-1 cards).
88
+ * - `'portrait'`: Vertical card (e.g. some passports, residence permits).
89
+ *
90
+ * @default 'landscape'
91
+ */
92
+ declare type DocumentOrientation = 'landscape' | 'portrait';
93
+
94
+ /**
95
+ * Optional overrides for document OCR UI (not part of `VelionConfig`; used internally).
96
+ */
97
+ export declare interface DocumentsConfig {
98
+ /**
99
+ * When true (default), the document camera preview is mirrored (like selfie mode).
100
+ * Set to false if the back camera shows the document inverted.
101
+ *
102
+ * @default true
103
+ */
104
+ mirrorDocumentVideo?: boolean;
105
+ /**
106
+ * Orientation of the document capture frame and crop.
107
+ * - `'landscape'`: Horizontal card (default — standard ID-1 cards).
108
+ * - `'portrait'`: Vertical card.
109
+ *
110
+ * @default 'landscape'
111
+ */
112
+ documentOrientation?: DocumentOrientation;
113
+ }
114
+
115
+ /** Which face of the ID document is being captured. */
116
+ export declare type DocumentSide = 'FRONT' | 'BACK';
117
+
118
+ /**
119
+ * Request body for POST /sessions/:sessionId/documents-init.
120
+ * Allowed values are defined by the backend; the SDK currently sends a fixed type until
121
+ * the session exposes selectable document types.
122
+ */
123
+ export declare interface DocumentsInitRequest {
124
+ document_type: string;
125
+ }
126
+
127
+ /**
128
+ * Response from POST /sessions/:sessionId/documents-init.
129
+ * Backend returns signed upload URLs so the SDK can PUT each document side
130
+ * directly to storage (e.g. GCS) without routing bytes through the backend.
131
+ */
132
+ /**
133
+ * Response of `POST /sessions/:id/documents-init`.
134
+ *
135
+ * Each URL is a GCS V4 signed PUT issued by the Velion CDN, valid for about
136
+ * two minutes, and signed over `host`, `content-type` and
137
+ * `x-goog-content-length-range`. The PUT must therefore send
138
+ * `Content-Type: image/jpeg` **and** `x-goog-content-length-range:
139
+ * 0,<max_file_size_bytes>` byte for byte, or GCS answers 400
140
+ * `MalformedSecurityHeader` (OSDKW-5). Request the URLs right before the
141
+ * upload, never ahead of the capture.
142
+ */
143
+ export declare interface DocumentsInitResponse {
144
+ /** Pre-signed URL to upload the front side (PUT, see the interface docs for the required headers). */
145
+ front_side_upload_url: string;
146
+ /** Pre-signed URL to upload the back side (PUT, see the interface docs for the required headers). */
147
+ back_side_upload_url: string;
148
+ /**
149
+ * Upper bound the URLs were signed for; the exact number that goes into the
150
+ * `x-goog-content-length-range` header. Also usable to reject oversize
151
+ * captures before the PUT.
152
+ */
153
+ max_file_size_bytes?: number;
154
+ }
155
+
156
+ /** STEP config for DOCUMENTS_OCR. */
157
+ export declare interface DocumentsOcrStepConfig {
158
+ country_allow?: string[];
159
+ capture_methods?: {
160
+ camera_scan?: boolean;
161
+ upload?: boolean;
162
+ };
163
+ /** Crop frame orientation for document camera capture. */
164
+ document_orientation?: DocumentOrientation;
165
+ /**
166
+ * Force the document camera preview mirroring. When absent the SDK decides
167
+ * from the camera the browser opened: front mirrored, rear not. Only the
168
+ * preview is affected; the uploaded crop is never mirrored.
169
+ */
170
+ mirror_document_video?: boolean;
171
+ }
172
+
173
+ /**
174
+ * A single selectable economic activity presented in the
175
+ * `ECONOMIC_ACTIVITY_DECLARATION` step. Mirrors the backend `EconomicActivityItem`
176
+ * (`code` + `display_name`); `code` is unique within the list and is what the SDK
177
+ * submits. There is no global catalog — each workflow declares its own list.
178
+ */
179
+ export declare interface EconomicActivityItem {
180
+ /** Machine-readable activity code (e.g. an AFIP/CLAE code) — unique within the list. */
181
+ code: string;
182
+ /** Human-readable label shown to the user. */
183
+ display_name: string;
184
+ }
185
+
186
+ /**
187
+ * POST /sessions/:id/economic-activity — EconomicActivitySelectionDto.
188
+ *
189
+ * Carries the `code` of the single economic activity the user selected for the
190
+ * `ECONOMIC_ACTIVITY_DECLARATION` step. The Worker validates it asynchronously
191
+ * against the configured items; an invalid code surfaces over SSE as
192
+ * `RETRY_STEP` (re-mounts the step) or `SESSION_DECLINED`, never as an HTTP error.
193
+ */
194
+ export declare interface EconomicActivitySelectionPayload {
195
+ /** `code` of the selected EconomicActivityItem. */
196
+ code: string;
197
+ }
198
+
199
+ /** STEP config for ECONOMIC_ACTIVITY_DECLARATION (`current_step.config`). */
200
+ export declare interface EconomicActivityStepConfig {
201
+ /** Selectable activities; always non-empty when the step is active. */
202
+ items?: EconomicActivityItem[];
203
+ }
204
+
205
+ /** POST /sessions/:id/contact/email — SubmitEmailContactRequestDto. */
206
+ export declare interface EmailContactPayload {
207
+ email: string;
208
+ }
209
+
210
+ /**
211
+ * Payload for POST /sessions/:sessionId/basic-info/human (HUMAN_BASIC_INFO step).
212
+ * Matches backend SubmitHumanBasicInfoRequestDto (snake_case in JSON).
213
+ */
214
+ export declare interface HumanBasicInfoPayload {
215
+ first_name: string;
216
+ middle_name?: string;
217
+ last_name: string;
218
+ second_last_name?: string;
219
+ identification_type: string;
220
+ identification_id: string;
221
+ }
222
+
223
+ /** STEP config for HUMAN_BASIC_INFO. */
224
+ export declare interface HumanBasicInfoStepConfig {
225
+ accepted_country_documents?: Array<{
226
+ country_code: string;
227
+ document_types: Array<{
228
+ id: string;
229
+ display_value?: string;
230
+ }>;
231
+ }>;
232
+ }
233
+
234
+ /** POST /sessions/:id/extended-info/human — SubmitHumanExtendedInfoRequestDto. */
235
+ export declare interface HumanExtendedInfoPayload {
236
+ gender?: string;
237
+ civil_status?: string;
238
+ birth_date?: string;
239
+ birth_country?: string;
240
+ citizenship?: string;
241
+ residence_country?: string;
242
+ }
243
+
244
+ /** STEP config for HUMAN_EXTENDED_INFO. */
245
+ export declare interface HumanExtendedInfoStepConfig {
246
+ /** Optional top-level lists sent by backend for select fields. */
247
+ gender_options?: StepFieldOption[];
248
+ civil_status_options?: StepFieldOption[];
249
+ fields?: Partial<Record<'gender' | 'civil_status' | 'birth_date' | 'birth_country' | 'citizenship' | 'residence_country', StepFieldRuleWithOptions>>;
250
+ }
251
+
252
+ /**
253
+ * Payload for POST /sessions/:sessionId/basic-info/legal (LEGAL_BASIC_INFO step).
254
+ * Matches backend SubmitLegalBasicInfoRequestDto (snake_case in JSON).
255
+ */
256
+ export declare interface LegalBasicInfoPayload {
257
+ legal_name: string;
258
+ legal_form: string;
259
+ identification_type: string;
260
+ identification_id: string;
261
+ }
262
+
263
+ /** POST /sessions/:id/extended-info/legal — SubmitLegalExtendedInfoRequestDto. */
264
+ export declare interface LegalExtendedInfoPayload {
265
+ incorporation_date: string;
266
+ incorporation_country: string;
267
+ }
268
+
269
+ /**
270
+ * Response from `POST /sessions/:sessionId/liveness-init`.
271
+ * The backend returns the Iris session details the SDK needs to open the WebSocket
272
+ * and stream frames. Credentials are not used: Iris owns the session lifecycle.
273
+ */
274
+ export declare interface LivenessSessionResponse {
275
+ /** Iris session identifier. */
276
+ liveness_session_id?: string;
277
+ /** Full WebSocket URL the SDK must connect to (e.g. wss://iris.host/ws/iris/{id}). */
278
+ websocket_url?: string;
279
+ /** ISO-8601 expiry of the Iris session. */
280
+ expires_at?: string;
281
+ /** Effective Iris challenge identifiers in order (TURN_LEFT, SMILE, …). */
282
+ challenges?: string[];
283
+ /** Optional JWT for the WebSocket handshake when Iris auth is enabled. */
284
+ connection_token?: string;
285
+ /**
286
+ * Optional base64 HMAC-SHA256 key. When present, the SDK signs every JPEG
287
+ * frame in a JSON envelope (canonical line: `sessionId\nframeId\nts\nsha256hex(jpeg)`).
288
+ */
289
+ frame_integrity_key_base64?: string;
290
+ /**
291
+ * Signed PUT URL the SDK uses to upload the locally-recorded liveness video
292
+ * directly to the onboarding GCS bucket. `null` (or absent) when video
293
+ * recording is disabled or the signing failed — the SDK skips the upload
294
+ * silently (liveness still works without the video; only the back-office
295
+ * loses the playback evidence).
296
+ */
297
+ video_upload?: VideoUpload | null;
298
+ }
299
+
300
+ /**
301
+ * Optional body of `POST /liveness-verify`. The SDK only includes it when the
302
+ * recorded video uploaded successfully (HTTP 200 from GCS). When omitted, the
303
+ * backend completes liveness based on the Iris score only.
304
+ */
305
+ export declare interface LivenessVerifyVideoMeta {
306
+ /** MIME type that was sent in the PUT `Content-Type` header (e.g. `video/mp4`, `video/webm`). */
307
+ content_type: string;
308
+ /** Recorded video duration in milliseconds, or `null` if it could not be determined. */
309
+ duration_ms: number | null;
310
+ }
311
+
312
+ /**
313
+ * Payload delivered to the optional `onLivenessVideoUploaded` callback after a
314
+ * successful upload of the liveness video. Best-effort: the callback only
315
+ * fires when the GCS PUT returned 200.
316
+ */
317
+ export declare interface LivenessVideoRef {
318
+ /** Signed `upload_url` the SDK PUT the video to. */
319
+ upload_url: string;
320
+ /** MIME type used in the PUT. */
321
+ content_type: string;
322
+ /** Recorded video duration in milliseconds, or `null` when unknown. */
323
+ duration_ms: number | null;
324
+ /** Recorded file size in bytes, or `null` when unknown. */
325
+ size_bytes: number | null;
326
+ }
327
+
328
+ /**
329
+ * Backend session/onboarding DTO (OnboardingDto). Returned by GET /sessions/:sessionId.
330
+ * The SDK maps this to SessionState for the step machine.
331
+ */
332
+ export declare interface OnboardingDtoResponse {
333
+ id?: string;
334
+ related_id?: string;
335
+ onboarding_type?: string;
336
+ status?: string;
337
+ current_step?: {
338
+ code?: string;
339
+ status?: string;
340
+ config?: Record<string, unknown>;
341
+ /**
342
+ * Previously-captured data for this step, present when a reverse navigation
343
+ * re-opened a completed step. The SDK uses it as editable prefill.
344
+ */
345
+ result?: Record<string, unknown>;
346
+ /** Intrinsic per-step reversibility (prefill / SSE-derivation only). */
347
+ reversible?: boolean;
348
+ };
349
+ steps?: OnboardingStepDto[];
350
+ created_at?: string;
351
+ updated_at?: string;
352
+ completed_at?: string;
353
+ metadata?: Record<string, unknown>;
354
+ /**
355
+ * Whether the SDK should render the "back" control on the current step.
356
+ * Computed server-side from the workflow graph (barrier model): `true` when
357
+ * there is a previous reversible step to re-open, OR when the current step is
358
+ * the first reversible step (back exits the flow via `BACK_EXIT`). The SDK
359
+ * uses **this** — not a step's intrinsic `reversible` flag — to decide whether
360
+ * to show the back button.
361
+ */
362
+ can_go_back?: boolean;
363
+ /**
364
+ * Origins (scheme + host + port) authorized by the customer to embed the SDK.
365
+ * The iframe validates `event.origin` of the loader's first VELION_INIT against
366
+ * this list and aborts with INSECURE_EMBED otherwise. Backend must also enforce
367
+ * server-side via the `Origin` header on every API call.
368
+ */
369
+ allowed_parent_origins?: string[];
370
+ }
371
+
372
+ /**
373
+ * Why the onboarding flow ended without a terminal verdict, delivered to
374
+ * {@link VelionCallbacks.onExit}.
375
+ *
376
+ * Triggers:
377
+ * - `BACK_EXIT`: the user tapped "back" on the first reversible step, where
378
+ * there is no earlier step to return to, so the SDK left the flow and
379
+ * returned control to the host.
380
+ * - `RETRY_CANCELLED`: the user tapped "Cancel" on the retry dialog shown after
381
+ * a `ROUTING_COMMAND / RETRY_STEP`. The backend session stays `IN_PROGRESS`
382
+ * (there is no cancellation endpoint); the host may re-open it later via
383
+ * `GET /sessions/:id`.
384
+ */
385
+ export declare interface OnboardingExit {
386
+ /** The reason the flow exited. */
387
+ reason: 'BACK_EXIT' | 'RETRY_CANCELLED';
388
+ /** The step the user exited from (when the backend provides `step_code`). */
389
+ step?: OnboardingStep;
390
+ }
391
+
392
+ /**
393
+ * Shape of the final result the SDK hands to `onSuccess` once the session
394
+ * reaches a terminal status. Built from the terminal SSE event and the
395
+ * `GET /sessions/:sessionId` snapshot (the backend exposes no separate
396
+ * `/result` endpoint).
397
+ */
398
+ export declare interface OnboardingResult {
399
+ /** The session ID that was completed. Matches `VelionConfig.sessionId`. */
400
+ sessionId: string;
401
+ /** ISO 8601 timestamp of when the backend finalized the session. */
402
+ completedAt: string;
403
+ /**
404
+ * The final KYC verdict.
405
+ * - `APPROVED`: All checks passed automatically.
406
+ * - `MANUAL_REVIEW`: Flagged for human review (common in AML flows). Backend `IN_REVIEW` maps here.
407
+ * - `REJECTED`: Automatically rejected (fraud signals, liveness failure, etc.).
408
+ * - `DECLINED`: Session ended in a declined state (matches GET session `status: DECLINED`).
409
+ */
410
+ status: 'APPROVED' | 'MANUAL_REVIEW' | 'REJECTED' | 'DECLINED';
411
+ /** An optional tracking reference for support and audit trails. */
412
+ referenceId?: string;
413
+ /**
414
+ * When the terminal outcome came from SSE, optional backend `reason` (e.g.
415
+ * `LIVENESS_SCORE_IN_REVIEW_RANGE` on SESSION_MANUAL_REVIEW) for localized final-screen copy.
416
+ */
417
+ terminalReason?: string;
418
+ }
419
+
420
+ /**
421
+ * SSE event payload (OnboardingSessionEvent). Matches the backend record
422
+ * la.velion.onboarding.api...sdk.OnboardingSessionEventDto (snake_case in JSON).
423
+ *
424
+ * Received on GET /public/sdk/sessions/:sessionId/events. The backend sends
425
+ * ServerSentEvent with id = event_id (epoch millis) for Last-Event-ID replay.
426
+ *
427
+ * Event types (event_type):
428
+ * - STEP_UPDATED — a workflow step changed status (step_code, step_status)
429
+ * - ROUTING_COMMAND — next/retry/terminate instruction (action: NEXT_STEP | RETRY_STEP | TERMINATE)
430
+ * - SESSION_APPROVED — all checks passed; session_status = APPROVED
431
+ * - SESSION_MANUAL_REVIEW — manual review required; session_status = MANUAL_REVIEW
432
+ * - SESSION_DECLINED — session ended with decline (step_code, session_status DECLINED, reason)
433
+ */
434
+ export declare interface OnboardingSessionEvent {
435
+ /** Onboarding session identifier (Long in backend). */
436
+ session_id?: number;
437
+ /** Discriminator: STEP_UPDATED | ROUTING_COMMAND | SESSION_APPROVED | SESSION_MANUAL_REVIEW | SESSION_DECLINED */
438
+ event_type?: string;
439
+ /** Present for STEP_UPDATED or ROUTING_COMMAND (next step code). */
440
+ step_code?: string;
441
+ /** Present for STEP_UPDATED; e.g. COMPLETED. */
442
+ step_status?: string;
443
+ /** Present for terminal events; e.g. APPROVED | MANUAL_REVIEW | REJECTED. */
444
+ session_status?: string;
445
+ /**
446
+ * For ROUTING_COMMAND: NEXT_STEP | RETRY_STEP (render step_code), TERMINATE
447
+ * (end flow), PREVIOUS_STEP (reverse navigation — re-open step_code with
448
+ * step_result as prefill), or BACK_EXIT (user backed out of the first
449
+ * reversible step — leave the flow and notify the host via `onExit`).
450
+ */
451
+ action?: string;
452
+ /** For SESSION_DECLINED / SESSION_MANUAL_REVIEW or ROUTING_COMMAND TERMINATE; e.g. UNREADABLE_DOCUMENT. */
453
+ reason?: string;
454
+ /** Step-specific config sent with ROUTING_COMMAND NEXT_STEP / PREVIOUS_STEP. */
455
+ step_config?: Record<string, unknown>;
456
+ /**
457
+ * Previously-captured data for the re-opened step, sent with ROUTING_COMMAND
458
+ * PREVIOUS_STEP. Applied by the SDK as editable prefill.
459
+ */
460
+ step_result?: Record<string, unknown>;
461
+ /**
462
+ * Whether the step the user is landing on can itself go back further. Carried
463
+ * on ROUTING_COMMAND when the backend computes it; when absent the SDK derives
464
+ * it from the cached workflow reversibility map.
465
+ */
466
+ can_go_back?: boolean;
467
+ /** Epoch millis; used as SSE id for Last-Event-ID on reconnect. */
468
+ event_id?: number;
469
+ }
470
+
471
+ /**
472
+ * @fileoverview Public TypeScript contracts for the Velion Onboarding SDK.
473
+ *
474
+ * Design principle: All types exported from this file constitute the public API.
475
+ * Internal implementation types should live alongside their respective modules.
476
+ */
477
+ /**
478
+ * The complete set of onboarding steps the backend can require.
479
+ * The SDK dynamically receives the active subset for each session.
480
+ *
481
+ * @remarks
482
+ * - `DEVICE_FINGERPRINT`: Silently collects device entropy via FingerprintJS.
483
+ * - `DOCUMENTS_OCR`: Renders a UI for ID document image capture and upload.
484
+ * - `LIVENESS_MATCH`: Drives the Velion Iris active-liveness flow over WebSocket (HUMAN only).
485
+ * - `EMAIL_OTP` / `PHONE_OTP`: Contact verification via one-time passwords.
486
+ * - `HUMAN_BASIC_INFO`: Natural-person identification data (HUMAN only).
487
+ * - `LEGAL_BASIC_INFO`: Legal-entity identification data (LEGAL only).
488
+ * - `EMAIL_CONTACT` / `PHONE_CONTACT`: contact collection without OTP.
489
+ * - `TAX_INFO`, `HUMAN_EXTENDED_INFO`, `LEGAL_EXTENDED_INFO`, `ADDRESS_INFO`, `SWORN_DECLARATION`: form steps.
490
+ * - `ECONOMIC_ACTIVITY_DECLARATION`: pick exactly one economic activity from a searchable list.
491
+ * - `TERMS_AND_CONDITIONS`: accept configured T&amp;C items.
492
+ * - `FACE_MATCH`: server-side face comparison after liveness (no user input; SDK waits).
493
+ * - `AML_SCREENING`: server-side PEP / sanctions screening (no user input; never routed to
494
+ * the SDK as `NEXT_STEP`, only visible in `steps[]` and `STEP_UPDATED`).
495
+ */
496
+ export declare 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' | 'ECONOMIC_ACTIVITY_DECLARATION' | 'DOCUMENTS_OCR' | 'LIVENESS_MATCH' | 'FACE_MATCH' | 'AML_SCREENING' | 'TERMS_AND_CONDITIONS';
497
+
498
+ /**
499
+ * Backend step DTO (OnboardingStepDto). GET session returns an array of these.
500
+ */
501
+ export declare interface OnboardingStepDto {
502
+ code: string;
503
+ name?: string;
504
+ description?: string;
505
+ order?: number;
506
+ status?: string;
507
+ /**
508
+ * Machine-readable cause of the current `status` when it is `FAILED` or
509
+ * `MANUAL_REVIEW` (backend `StepStatusDetailCode`, VON-54 / VON-56). Examples:
510
+ * `DOC_UNREADABLE`, `DOC_MRZ_NOT_READABLE`, `DOC_EXPIRED`, `DOC_AGE_EXCLUSION`,
511
+ * `LIVENESS_BELOW_THRESHOLD`, `LIVENESS_SPOOF_SUSPECTED`,
512
+ * `FACE_MATCH_BELOW_THRESHOLD`, `FINGERPRINT_BOT_DETECTED`,
513
+ * `TAX_ARCA_VALIDATION_FAILED`, `TERMS_NOT_ACCEPTED`,
514
+ * `ECONOMIC_ACTIVITY_INVALID_SELECTION`, `STEP_UNEXPECTED_ERROR`. Hosts may
515
+ * use it for analytics or support tooling; the SDK derives its user-facing
516
+ * copy from the step, never from this code.
517
+ */
518
+ status_detail?: string;
519
+ required?: boolean;
520
+ /** Step-specific payload (e.g. OCR fields, fingerprint, T&amp;C items). */
521
+ result?: Record<string, unknown>;
522
+ /** Raw workflow config for this step (thresholds, accepted documents, …). */
523
+ config?: Record<string, unknown>;
524
+ /**
525
+ * Whether the user may navigate back INTO this step after completing it
526
+ * (intrinsic per-step flag the backend stamps from the workflow). Used only
527
+ * to derive `can_go_back` for steps reached via SSE (which doesn't carry the
528
+ * flag) and for prefill — NOT to decide whether to render the back button.
529
+ * @see OnboardingDtoResponse.can_go_back
530
+ */
531
+ reversible?: boolean;
532
+ }
533
+
534
+ /**
535
+ * Status of an individual onboarding step (matches backend OnboardingStepStatus).
536
+ */
537
+ export declare type OnboardingStepStatus = 'PENDING' | 'IN_PROGRESS' | 'COMPLETED' | 'SKIPPED' | 'FAILED';
538
+
539
+ /**
540
+ * Type of onboarding session (matches backend OnboardingType).
541
+ * Constrains which steps are valid: HUMAN allows biometric steps, LEGAL uses entity data.
542
+ */
543
+ export declare type OnboardingType = 'HUMAN' | 'LEGAL';
544
+
545
+ /** POST /sessions/:id/contact/phone — SubmitPhoneContactRequestDto. */
546
+ export declare interface PhoneContactPayload {
547
+ phone: string;
548
+ }
549
+
550
+ /**
551
+ * A structured, machine-readable error object emitted by the SDK.
552
+ *
553
+ * @example
554
+ * ```typescript
555
+ * const sdk = new VelionOnboarding({
556
+ * onError: (err) => {
557
+ * if (err.code === SdkErrorCode.CAMERA_ERROR &&
558
+ * err.cameraCode === CameraErrorCode.PERMISSION_DENIED) {
559
+ * showCameraPermissionDialog();
560
+ * }
561
+ * }
562
+ * });
563
+ * ```
564
+ */
565
+ export declare interface SdkError {
566
+ /** Primary SDK-level error classification. */
567
+ readonly code: SdkErrorCode;
568
+ /** Human-readable English description for developer logging. */
569
+ readonly message: string;
570
+ /** Present when `code === SdkErrorCode.SESSION_DECLINED` (SSE `reason`). */
571
+ readonly declineReason?: string;
572
+ /**
573
+ * Step the error refers to. For `SESSION_DECLINED` it is the SSE `step_code`;
574
+ * for `ROUTING_TIMEOUT` it is the step that was completed and never routed.
575
+ */
576
+ readonly stepCode?: string;
577
+ /**
578
+ * Localized headline resolved by the SDK for SESSION_DECLINED.
579
+ * Useful when hosts hide the built-in final result screen but still want
580
+ * the same user-facing text in custom UI.
581
+ */
582
+ readonly declineTitle?: string;
583
+ /**
584
+ * Localized body message resolved by the SDK for SESSION_DECLINED.
585
+ * Mirrors the text shown in the built-in final result screen.
586
+ */
587
+ readonly declineMessage?: string;
588
+ /** Present when `code === SdkErrorCode.CAMERA_ERROR`. Provides camera-specific detail. */
589
+ readonly cameraCode?: CameraErrorCode;
590
+ /** HTTP status code when the error originated from an API call. */
591
+ readonly httpStatus?: number;
592
+ /**
593
+ * The original caught value for debugging.
594
+ * Not guaranteed to be an `Error` instance — could be a DOMException or string.
595
+ */
596
+ readonly cause?: unknown;
597
+ }
598
+
599
+ /**
600
+ * Top-level SDK error codes covering all failure scenarios in the onboarding flow.
601
+ */
602
+ export declare enum SdkErrorCode {
603
+ /** The sessionToken was rejected by the backend (401/403). */
604
+ SESSION_INVALID = "SESSION_INVALID",
605
+ /** The sessionToken has expired (typically a 401 after initial validation). */
606
+ SESSION_EXPIRED = "SESSION_EXPIRED",
607
+ /** Could not fetch the initial session state from the backend. */
608
+ SESSION_FETCH_FAILED = "SESSION_FETCH_FAILED",
609
+ /** Backend sent SESSION_DECLINED over SSE; session ended before completion. */
610
+ SESSION_DECLINED = "SESSION_DECLINED",
611
+ /**
612
+ * A step was completed but the backend did not route the session to the
613
+ * next one within `routingTimeoutMs` (default 120 s): no `ROUTING_COMMAND`
614
+ * arrived over SSE and `GET /sessions/:id` kept reporting the completed
615
+ * step. The session is still alive on the backend; `stepCode` names the
616
+ * completed step. Typical cause: a delayed or stalled onboarding worker.
617
+ */
618
+ ROUTING_TIMEOUT = "ROUTING_TIMEOUT",
619
+ /** FingerprintJS failed to generate the visitor ID. */
620
+ FINGERPRINT_FAILED = "FINGERPRINT_FAILED",
621
+ /** One or more document images failed to upload successfully. */
622
+ DOCUMENT_UPLOAD_FAILED = "DOCUMENT_UPLOAD_FAILED",
623
+ /** The liveness check did not pass or returned an unexpected result. */
624
+ LIVENESS_FAILED = "LIVENESS_FAILED",
625
+ /** The Liveness module failed to initialize (e.g., could not create the Iris session). */
626
+ LIVENESS_INIT_FAILED = "LIVENESS_INIT_FAILED",
627
+ /**
628
+ * The recorded liveness session video could not be uploaded to storage.
629
+ * Best-effort only: this never fails the liveness step — it is logged so the
630
+ * back-office knows the playback evidence is missing for the session.
631
+ */
632
+ LIVENESS_VIDEO_UPLOAD_FAILED = "LIVENESS_VIDEO_UPLOAD_FAILED",
633
+ /**
634
+ * A camera-related error occurred. Inspect `cameraCode` for the specific reason.
635
+ * @see CameraErrorCode
636
+ */
637
+ CAMERA_ERROR = "CAMERA_ERROR",
638
+ /** A network-level failure (no internet, CORS, DNS). */
639
+ NETWORK_ERROR = "NETWORK_ERROR",
640
+ /** The backend returned a non-2xx HTTP status. */
641
+ API_ERROR = "API_ERROR",
642
+ /** The `containerId` provided in the config does not exist in the DOM. */
643
+ CONTAINER_NOT_FOUND = "CONTAINER_NOT_FOUND",
644
+ /** `start()` was called on an SDK instance that is already running. */
645
+ ALREADY_STARTED = "ALREADY_STARTED",
646
+ /** `start()` was called after `destroy()`. The instance is no longer usable. */
647
+ INSTANCE_DESTROYED = "INSTANCE_DESTROYED",
648
+ /**
649
+ * The page is running inside an iframe and embedding was not explicitly allowed.
650
+ * Configure Content-Security-Policy: frame-ancestors or X-Frame-Options on the
651
+ * page that hosts the SDK, or set allowEmbedded: true if embedding is intentional.
652
+ */
653
+ INSECURE_EMBED = "INSECURE_EMBED",
654
+ /**
655
+ * The CDN-served runtime failed verification: the manifest could not be
656
+ * downloaded or its Ed25519 signature did not verify against the loader's
657
+ * embedded public key; the signed manifest is for another major, older than the
658
+ * minimum runtime the loader accepts (rollback) or does not name its entry
659
+ * digest; or the entry HTML or one of its scripts does not match the manifest.
660
+ * The loader refuses to mount the iframe to prevent execution of
661
+ * tampered/unsigned bundles. Also raised by the mounted runtime when data it
662
+ * reads from its CDN after boot (the country subdivisions of `ADDRESS_INFO`)
663
+ * does not match the digest pinned in its bundle; the flow then stops.
664
+ */
665
+ INTEGRITY_FAILED = "INTEGRITY_FAILED",
666
+ /**
667
+ * The browser cannot verify the CDN manifest signature at all (no WebCrypto
668
+ * `crypto.subtle`, typically an insecure `http://` context). Unlike
669
+ * `INTEGRITY_FAILED` this is not a tampering signal; the loader still refuses
670
+ * to mount the iframe because the runtime cannot be verified.
671
+ */
672
+ UNSUPPORTED_BROWSER = "UNSUPPORTED_BROWSER",
673
+ /**
674
+ * The runtime could not be started or was lost:
675
+ * - the iframe loaded but the runtime never reported `VELION_READY` within
676
+ * `runtimeReadyTimeoutMs` (default 30 s). Typical causes: the CDN serves an
677
+ * `index.html` whose hashed assets are missing (deploy under the wrong
678
+ * prefix), a Content-Security-Policy on the host blocking the runtime's
679
+ * scripts, or the runtime crashing before it could boot. Without this the
680
+ * host saw a blank iframe and no callback at all;
681
+ * - the loader could not download the entry or its scripts to verify them;
682
+ * - the iframe reloaded after the session started. The loader does not resend
683
+ * the session token to a document it did not verify; a new instance resumes
684
+ * from the backend's current step.
685
+ */
686
+ RUNTIME_LOAD_FAILED = "RUNTIME_LOAD_FAILED",
687
+ UNKNOWN = "UNKNOWN"
688
+ }
689
+
690
+ /**
691
+ * All possible states of the SDK's internal lifecycle.
692
+ * Transitions are strictly unidirectional (no going back to IDLE once started).
693
+ *
694
+ * @internal
695
+ */
696
+ export declare type SdkStatus = 'IDLE' | 'INITIALIZING' | 'RUNNING' | 'STEP_PROCESSING' | 'COMPLETED' | 'EXITED' | 'ERROR' | 'DESTROYED';
697
+
698
+ /**
699
+ * Response from session creation (POST from your backend). Use sessionId and
700
+ * sessionToken when instantiating VelionOnboarding; pass expiresAt for optional
701
+ * client-side expiration checks.
702
+ */
703
+ export declare interface SessionCreationResponse {
704
+ session_id: string;
705
+ session_token: string;
706
+ expires_at: string;
707
+ status?: string;
708
+ }
709
+
710
+ /**
711
+ * Session state used by the SDK step machine. Derived from GET /sessions/:sessionId
712
+ * (OnboardingDto): steps sorted by order → requiredSteps, first non-completed index → currentStepIndex.
713
+ */
714
+ export declare interface SessionState {
715
+ /** Current runnable step reported by backend session state. */
716
+ currentStep?: OnboardingStep;
717
+ /** Step-specific config for `currentStep` from GET /sessions/:id `current_step.config`. */
718
+ currentStepConfig?: Record<string, unknown>;
719
+ /** Cached configs discovered from GET session and SSE `step_config`. */
720
+ stepConfigs?: StepConfigMap;
721
+ /** Session type (HUMAN or LEGAL). Constrains which steps are applicable. */
722
+ onboardingType?: OnboardingType;
723
+ /**
724
+ * Whether the SDK should render the "back" control on `currentStep`. Mapped
725
+ * from GET `can_go_back` (workflow-graph computed). When absent (e.g. a step
726
+ * reached via SSE, which doesn't carry the flag) the orchestrator derives it
727
+ * from {@link stepReversibility}.
728
+ */
729
+ canGoBack?: boolean;
730
+ /**
731
+ * Per-step intrinsic reversibility in workflow order, cached from the initial
732
+ * GET so the orchestrator can derive `can_go_back` for steps reached via SSE:
733
+ * a step can go back when any earlier step is reversible, or the step itself
734
+ * is the first reversible one (back exits the flow).
735
+ */
736
+ stepReversibility?: Array<{
737
+ code: OnboardingStep;
738
+ reversible: boolean;
739
+ }>;
740
+ /**
741
+ * Previously-captured data for `currentStep`, present when a reverse
742
+ * navigation re-opened a completed step (GET reflects it on
743
+ * `current_step.result`). Applied by the SDK as editable prefill.
744
+ */
745
+ currentStepResult?: Record<string, unknown>;
746
+ /** Arbitrary session metadata the backend may attach. */
747
+ metadata?: Record<string, unknown>;
748
+ /**
749
+ * Customer-registered allowlist of origins authorized to embed the SDK.
750
+ * When provided, the SDK validates the loader's parent origin against this list.
751
+ */
752
+ allowedParentOrigins?: string[];
753
+ }
754
+
755
+ /**
756
+ * No-op when using the loader: OpenCV is loaded inside the CDN app.
757
+ * Kept for API compatibility; configure OpenCV in the CDN app build if needed.
758
+ */
759
+ export declare function setOpenCVBaseUrl(_url: string): void;
760
+
761
+ /** Generic per-step runtime config map carried by session state and SSE. */
762
+ export declare type StepConfigMap = Partial<Record<OnboardingStep, Record<string, unknown>>>;
763
+
764
+ /** Select option used by configurable step fields (e.g. HUMAN_EXTENDED_INFO gender/civil_status). */
765
+ declare interface StepFieldOption {
766
+ id: string;
767
+ display_value?: string;
768
+ }
769
+
770
+ /** Generic visible/required field toggle used by workflow step configs. */
771
+ export declare interface StepFieldRule {
772
+ visible: boolean;
773
+ required: boolean;
774
+ }
775
+
776
+ /** Field rule with optional selectable options. */
777
+ declare interface StepFieldRuleWithOptions extends StepFieldRule {
778
+ options?: StepFieldOption[];
779
+ }
780
+
781
+ /** POST /sessions/:id/sworn-declaration — SubmitSwornDeclarationRequestDto. */
782
+ export declare interface SwornDeclarationPayload {
783
+ is_pep: boolean;
784
+ is_ssoo: boolean;
785
+ is_fatca: boolean;
786
+ is_ocde: boolean;
787
+ }
788
+
789
+ /** STEP config for SWORN_DECLARATION. */
790
+ export declare interface SwornDeclarationStepConfig {
791
+ ask_pep?: boolean;
792
+ ask_obligated_subject?: boolean;
793
+ ask_fatca?: boolean;
794
+ ask_ocde?: boolean;
795
+ on_declared_pep?: string;
796
+ on_declared_obligated_subject?: string;
797
+ on_declared_fatca?: string;
798
+ on_declared_ocde?: string;
799
+ }
800
+
801
+ /** One country block in TAX_INFO step config (GET session `current_step.config`). */
802
+ declare interface TaxInfoAcceptedCountryRow {
803
+ country_code: string;
804
+ identification_types?: TaxInfoConfigOptionRow[];
805
+ /** Options for the "Categoría fiscal" / taxpayer category select. */
806
+ taxpayer_categories?: TaxInfoConfigOptionRow[];
807
+ }
808
+
809
+ /**
810
+ * Resolved selectable lists for the TAX_INFO step UI (from `accepted_tax_information` only; no SDK defaults).
811
+ */
812
+ export declare interface TaxInfoConfig {
813
+ /**
814
+ * Fiscal regime / category options (e.g. Monotributo). The chosen `id` is sent as `taxpayer_type`.
815
+ */
816
+ taxpayerCategories: TaxInfoOption[];
817
+ /**
818
+ * Tax identification scheme options (e.g. CUIT). The chosen `id` is sent as `taxpayer_id_type`.
819
+ */
820
+ fiscalIdentifierTypes: TaxInfoOption[];
821
+ }
822
+
823
+ /**
824
+ * One selectable option row from TAX_INFO `accepted_tax_information` (backend GET session).
825
+ * Prefer `code` as the value sent in POST tax-info; `id` is supported for older payloads.
826
+ */
827
+ declare interface TaxInfoConfigOptionRow {
828
+ code?: string;
829
+ id?: string;
830
+ display_value?: string;
831
+ tax_code?: string;
832
+ }
833
+
834
+ /**
835
+ * Single selectable option for tax category or fiscal identifier type (TAX_INFO step).
836
+ * `id` is submitted to the API; `description` is the user-visible label.
837
+ */
838
+ export declare interface TaxInfoOption {
839
+ id: string;
840
+ description: string;
841
+ }
842
+
843
+ /** POST /sessions/:id/tax-info — SubmitTaxInfoRequestDto. */
844
+ export declare interface TaxInfoPayload {
845
+ /** Selected fiscal category value (`code` from step config `taxpayer_categories`). */
846
+ taxpayer_type: string;
847
+ /** Selected fiscal identifier kind id (e.g. `CUIT` from step config `identification_types`). */
848
+ taxpayer_id_type: string;
849
+ /** Tax identification number for the chosen type. */
850
+ taxpayer_id: string;
851
+ }
852
+
853
+ /** STEP config for TAX_INFO. */
854
+ export declare interface TaxInfoStepConfig {
855
+ /** Identification types + taxpayer categories per country. */
856
+ accepted_tax_information?: TaxInfoAcceptedCountryRow[];
857
+ }
858
+
859
+ /** POST /sessions/:id/terms-and-conditions — SubmitTermsAndConditionsRequestDto. */
860
+ export declare interface TermsAndConditionsAcceptancePayload {
861
+ item_id: string;
862
+ accepted: boolean;
863
+ }
864
+
865
+ /**
866
+ * A single T&amp;C line item (matches backend TermsAndConditionsItemDto / domain record).
867
+ */
868
+ export declare interface TermsAndConditionsItem {
869
+ id: string;
870
+ description: string;
871
+ /** Optional URL to the full document. */
872
+ link?: string;
873
+ }
874
+
875
+ /** STEP config for TERMS_AND_CONDITIONS. */
876
+ export declare interface TermsAndConditionsStepConfig {
877
+ terms?: Array<{
878
+ title?: string;
879
+ url?: string;
880
+ }>;
881
+ }
882
+
883
+ export declare interface TermsAndConditionsSubmitPayload {
884
+ acceptances: TermsAndConditionsAcceptancePayload[];
885
+ }
886
+
887
+ export declare const VELION_MSG_ERROR: "VELION_ERROR";
888
+
889
+ /**
890
+ * Iframe → parent: the user left the flow via back on the first reversible step
891
+ * (`ROUTING_COMMAND / BACK_EXIT`). The loader forwards this to the host's
892
+ * `onExit` callback so it can dismiss the SDK surface.
893
+ */
894
+ export declare const VELION_MSG_EXIT: "VELION_EXIT";
895
+
896
+ /** Message type: parent (loader) sends config to iframe (CDN app). */
897
+ export declare const VELION_MSG_INIT: "VELION_INIT";
898
+
899
+ /**
900
+ * Iframe → parent: the LIVENESS_MATCH step uploaded the recorded session video
901
+ * (GCS PUT returned 200). The loader forwards the {@link LivenessVideoRef} to
902
+ * the host's `onLivenessVideoUploaded` callback. Best-effort: never sent when
903
+ * recording was disabled or the upload failed.
904
+ */
905
+ export declare const VELION_MSG_LIVENESS_VIDEO_UPLOADED: "VELION_LIVENESS_VIDEO_UPLOADED";
906
+
907
+ /** Message types: iframe (CDN app) sends to parent (loader). */
908
+ export declare const VELION_MSG_READY: "VELION_READY";
909
+
910
+ export declare const VELION_MSG_STEP_CHANGE: "VELION_STEP_CHANGE";
911
+
912
+ export declare const VELION_MSG_STEP_COMPLETE: "VELION_STEP_COMPLETE";
913
+
914
+ export declare const VELION_MSG_SUCCESS: "VELION_SUCCESS";
915
+
916
+ /** Message type: parent sends new token to iframe after VELION_TOKEN_EXPIRED. */
917
+ export declare const VELION_MSG_TOKEN: "VELION_TOKEN";
918
+
919
+ export declare const VELION_MSG_TOKEN_EXPIRED: "VELION_TOKEN_EXPIRED";
920
+
921
+ /**
922
+ * The complete set of lifecycle callbacks the host application can subscribe to.
923
+ * All callbacks are optional. The SDK is still functional without any of them,
924
+ * but `onError` and `onSuccess` are strongly recommended for production.
925
+ */
926
+ export declare interface VelionCallbacks {
927
+ /**
928
+ * Fires when the entire onboarding flow has been completed successfully
929
+ * and the backend has confirmed the session as resolved.
930
+ *
931
+ * @param result - Final onboarding verdict from the backend.
932
+ */
933
+ onSuccess?: (result: OnboardingResult) => void;
934
+ /**
935
+ * Fires when an unrecoverable error terminates the onboarding flow.
936
+ * Any terminal failure (camera error, document capture failure, upload failure,
937
+ * liveness failure, API error, etc.) is delivered here so the host can notify the user.
938
+ * After this callback, the SDK instance is in an error state.
939
+ * Call `sdk.destroy()` and re-instantiate to retry.
940
+ *
941
+ * @param error - Structured error with a machine-readable code (e.g. CAMERA_ERROR, DOCUMENT_UPLOAD_FAILED).
942
+ */
943
+ onError?: (error: SdkError) => void;
944
+ /**
945
+ * Fires each time the active step changes during the flow.
946
+ * Useful for updating a custom step indicator in the host UI.
947
+ *
948
+ * The required step list is resolved dynamically by the backend, so the SDK
949
+ * does not know the total step count up front. Callers that need a progress
950
+ * indicator should rely on the SDK's built-in progress bar (or the trickling
951
+ * counter in `stepIndex`).
952
+ *
953
+ * @param step - The step that just became active.
954
+ * @param stepIndex - Zero-based index of the current step.
955
+ */
956
+ onStepChange?: (step: OnboardingStep, stepIndex: number) => void;
957
+ /**
958
+ * Fires immediately after a step succeeds, before advancing to the next one.
959
+ * Useful for analytics or triggering intermediate UI transitions.
960
+ *
961
+ * @param step - The step that was just completed.
962
+ */
963
+ onStepComplete?: (step: OnboardingStep) => void;
964
+ /**
965
+ * Fires for each SSE event from GET /sessions/:sessionId/events
966
+ * (e.g. STEP_UPDATED, SESSION_APPROVED).
967
+ */
968
+ onSessionEvent?: (event: OnboardingSessionEvent) => void;
969
+ /**
970
+ * Called when the user taps the dismiss control on the final result screen
971
+ * (only when the final result screen is shown). `onSuccess` has already run.
972
+ */
973
+ onFinalResultScreenDismiss?: () => void;
974
+ /**
975
+ * Fires when the LIVENESS_MATCH step successfully uploaded the recorded
976
+ * session video to the onboarding storage (GCS PUT returned 200). Best-effort:
977
+ * if the upload failed, timed out, or the session had no `video_upload` URL,
978
+ * the callback is not invoked — liveness still completes normally.
979
+ *
980
+ * @param ref - URL and metadata of the uploaded video.
981
+ */
982
+ onLivenessVideoUploaded?: (ref: LivenessVideoRef) => void;
983
+ /**
984
+ * Fires when the user leaves the onboarding flow without a terminal verdict —
985
+ * either by tapping "back" on the first reversible step (`BACK_EXIT`) or
986
+ * "Cancel" on the retry dialog shown after a `RETRY_STEP` (`RETRY_CANCELLED`).
987
+ * In both cases the backend told the SDK to leave the flow and hand control
988
+ * back to the host; the SDK has already torn down its UI.
989
+ *
990
+ * Distinct from `onSuccess` (a terminal verdict) and `onError` (a failure):
991
+ * the host should typically dismiss/close the SDK surface when this fires.
992
+ *
993
+ * @param exit - Why the flow exited and the step it exited from.
994
+ */
995
+ onExit?: (exit: OnboardingExit) => void;
996
+ }
997
+
998
+ /**
999
+ * Root configuration object for the `VelionOnboarding` class.
1000
+ *
1001
+ * @example
1002
+ * ```typescript
1003
+ * const sdk = new VelionOnboarding({
1004
+ * containerId: 'velion-root',
1005
+ * sessionId: 'ses_abc123',
1006
+ * sessionToken: 'eyJhbGciOiJIUzI1NiIsInR5cCI6IkpXVCJ9...',
1007
+ * apiUrl: 'https://api.velion.la/v1',
1008
+ * theme: { primaryColor: '#0052CC' },
1009
+ * onSuccess: (result) => console.log('Done!', result),
1010
+ * onError: (err) => console.error('SDK Error:', err),
1011
+ * });
1012
+ *
1013
+ * await sdk.start();
1014
+ * ```
1015
+ */
1016
+ export declare interface VelionConfig extends VelionCallbacks {
1017
+ /**
1018
+ * The `id` of an existing DOM element where the SDK will render its UI.
1019
+ * The element **must** be present in the document at the time `start()` is called.
1020
+ *
1021
+ * @example `'velion-kyc-container'`
1022
+ */
1023
+ containerId: string;
1024
+ /**
1025
+ * The unique session identifier generated by your backend for this
1026
+ * onboarding session. Used to scope all API calls.
1027
+ *
1028
+ * @example `'ses_9f8d7c6b5a4e3f2d'`
1029
+ */
1030
+ sessionId: string;
1031
+ /**
1032
+ * A short-lived, opaque authorization token (e.g. HS256 JWT) issued by your
1033
+ * backend when creating the session. Sent as `Authorization: Bearer <sessionToken>`
1034
+ * on every SDK request. Required for all endpoints behind the gateway.
1035
+ *
1036
+ * **Security note:** This token is held in memory only (never in localStorage
1037
+ * or cookies) and is automatically discarded on `destroy()`.
1038
+ */
1039
+ sessionToken: string;
1040
+ /**
1041
+ * ISO-8601 expiry timestamp of the sessionToken. If provided, the SDK may
1042
+ * check expiration before requests and emit SESSION_EXPIRED without a round-trip.
1043
+ * When the backend returns 401/403, the SDK emits SESSION_EXPIRED anyway.
1044
+ */
1045
+ expiresAt?: string;
1046
+ /**
1047
+ * Base URL of the Velion onboarding edge. Must **not** include a trailing slash.
1048
+ * SDK paths are relative to this (e.g. GET `/sessions/{sessionId}`).
1049
+ *
1050
+ * Defaults to the public production edge `https://sdk.velion.la/onboarding`.
1051
+ * Override only for staging or self-hosted environments.
1052
+ */
1053
+ apiUrl?: string;
1054
+ /**
1055
+ * Optional white-labeling theme. If omitted, SDK renders with Velion defaults.
1056
+ */
1057
+ theme?: VelionTheme;
1058
+ /**
1059
+ * Global visual mode for SDK overlays and controls.
1060
+ * - `'light'`: Light translucent surfaces.
1061
+ * - `'dark'`: Dark translucent surfaces.
1062
+ *
1063
+ * @default 'light'
1064
+ */
1065
+ colorMode?: 'light' | 'dark';
1066
+ /**
1067
+ * BCP 47 locale tag for SDK UI copy (labels, instructions, error messages).
1068
+ *
1069
+ * @default 'es'
1070
+ */
1071
+ locale?: string;
1072
+ /**
1073
+ * When `true`, after the backend returns a terminal verdict the SDK shows a
1074
+ * full-screen summary (APPROVED, MANUAL_REVIEW, REJECTED) inside the container,
1075
+ * styled with `theme` and `colorMode`. `onSuccess` still fires with the result.
1076
+ *
1077
+ * @default true
1078
+ */
1079
+ showFinalResultScreen?: boolean;
1080
+ /**
1081
+ * When `true` (default), the SDK renders a thin progress bar at the top of
1082
+ * the container that advances as the user moves through steps. Disable for
1083
+ * embedded experiences that already provide their own progress UI.
1084
+ *
1085
+ * @default true
1086
+ */
1087
+ showProgressBar?: boolean;
1088
+ /**
1089
+ * Overrides for default titles, messages, and dismiss button on the final result screen.
1090
+ * Only used when the final result screen is shown (`showFinalResultScreen` is not `false`).
1091
+ */
1092
+ finalResultScreenTexts?: VelionFinalResultScreenTexts;
1093
+ /**
1094
+ * Optional copy for SESSION_DECLINED SSE screens, keyed by backend `reason`.
1095
+ * Merged with SDK defaults (e.g. `TAX_INFO_FAILED`) for `locale` `en` / `es`.
1096
+ */
1097
+ sessionDeclinedReasonTexts?: VelionSessionDeclinedReasonTexts;
1098
+ /**
1099
+ * Optional copy for the retry dialog (`ROUTING_COMMAND / RETRY_STEP`), keyed by
1100
+ * step code (e.g. `LIVENESS_MATCH`). Merged with SDK per-step defaults for
1101
+ * `locale` `en` / `es`; unspecified steps fall back to generic retry copy.
1102
+ */
1103
+ retryStepTexts?: VelionRetryStepTexts;
1104
+ /**
1105
+ * When `true` (default), shows the Velion preparation screen (face icon, tips,
1106
+ * "Start verification") before connecting to Iris. When `false`, skips it and
1107
+ * starts the camera + Iris session immediately on step entry.
1108
+ *
1109
+ * @default true
1110
+ */
1111
+ livenessShowIntro?: boolean;
1112
+ /**
1113
+ * When `false`, hides the "Atrás" / "Back" button on the liveness preparation
1114
+ * screen. The button is only present in the intro; once the camera capture
1115
+ * begins the user must complete the Iris challenges to leave the step.
1116
+ *
1117
+ * @default true
1118
+ */
1119
+ livenessShowBackButton?: boolean;
1120
+ /**
1121
+ * If true, allows the SDK to run when the page is inside an iframe.
1122
+ * Only set to true if you have configured Content-Security-Policy: frame-ancestors
1123
+ * or X-Frame-Options on the HTTP response of the page that hosts the SDK.
1124
+ * If false (default) and the page is embedded in an iframe, the SDK emits
1125
+ * INSECURE_EMBED and does not start.
1126
+ *
1127
+ * @default false
1128
+ */
1129
+ allowEmbedded?: boolean;
1130
+ /**
1131
+ * Internal — set by the Velion CDN entry (`cdn-main.ts`) to the `event.origin`
1132
+ * captured from the loader's first VELION_INIT message. The SDK validates it
1133
+ * against `allowed_parent_origins` returned by the backend and refuses to start
1134
+ * if the origin is not in the customer's registered allowlist.
1135
+ *
1136
+ * Direct integrators (running VelionOnboarding without the loader iframe)
1137
+ * should leave this unset.
1138
+ *
1139
+ * @internal
1140
+ */
1141
+ iframeParentOrigin?: string;
1142
+ /**
1143
+ * Fingerprint Pro API endpoint (custom subdomain). Used by the DEVICE_FINGERPRINT
1144
+ * step to load and identify visitors. Only set this when using a custom Fingerprint
1145
+ * subdomain or proxy; otherwise the default Velion endpoint is used.
1146
+ *
1147
+ * @default 'https://fp.velion.la'
1148
+ */
1149
+ fingerprintEndpoint?: string;
1150
+ /**
1151
+ * Fingerprint Pro public API key. Used by the DEVICE_FINGERPRINT step to
1152
+ * identify visitors. Defaults to the shared Velion public key — set this
1153
+ * only when your tenant has its own Fingerprint workspace.
1154
+ *
1155
+ * @default Velion's shared public key
1156
+ */
1157
+ fingerprintApiKey?: string;
1158
+ /**
1159
+ * Hard ceiling, in milliseconds, for the DEVICE_FINGERPRINT step (agent
1160
+ * load + identification). The Fingerprint agent has its own internal
1161
+ * timeout, but with tracker blockers or a blackholed endpoint it can hang
1162
+ * well past it; the SDK races against this value so the step fails with
1163
+ * `FINGERPRINT_FAILED` instead of leaving the user on a blank screen.
1164
+ *
1165
+ * @default 15000
1166
+ */
1167
+ fingerprintTimeoutMs?: number;
1168
+ /**
1169
+ * Total wait, in milliseconds, for the backend to route the session after a
1170
+ * step is completed. The SDK waits for the SSE `ROUTING_COMMAND` and falls
1171
+ * back to `GET /sessions/:id` every 30 s; when the backend keeps reporting
1172
+ * the completed step (delayed or stalled worker) those cycles used to repeat
1173
+ * for ever. Past this bound the flow fails with `ROUTING_TIMEOUT` so the host
1174
+ * gets a callback instead of an endless spinner.
1175
+ *
1176
+ * @default 120000
1177
+ */
1178
+ routingTimeoutMs?: number;
1179
+ /**
1180
+ * Google Maps Platform API key (Maps JavaScript API + Places). Required for the
1181
+ * {@code ADDRESS_INFO} step to show the map, search, and geocoding. Omit only if
1182
+ * your flow never reaches that step.
1183
+ */
1184
+ googleMapsApiKey?: string;
1185
+ /**
1186
+ * Optional calibration tag forwarded to Iris for the LIVENESS_MATCH step.
1187
+ * When the Iris worker is running with `CALIBRATION_BACKEND=fs|gcs`, every
1188
+ * frame of this session is mirrored to the dataset bucket with the tag in
1189
+ * `metadata.json`, so we can build labeled training sets for the spoof /
1190
+ * liveness models. Does NOT affect the score.
1191
+ *
1192
+ * Suggested values (must match the worker's known labels — see
1193
+ * `iris-worker` README): `REAL_GOOD_LIGHT`, `REAL_BAD_LIGHT`, `REAL_BACKLIT`,
1194
+ * `REAL_BUSY_BG`, `REAL_NEUTRAL_BG`, `REAL_GLASSES`, `REAL_OUTDOOR`,
1195
+ * `FAKE_PHONE_PHOTO`, `FAKE_PHONE_VIDEO`, `FAKE_TABLET_VIDEO`,
1196
+ * `FAKE_MONITOR_VIDEO`, `FAKE_PRINT`, `FAKE_MASK`, `UNKNOWN`, `EDGE_CASE`.
1197
+ *
1198
+ * Leave undefined for normal user-facing sessions.
1199
+ */
1200
+ livenessCalibrationLabel?: string;
1201
+ /**
1202
+ * When true, the SDK enables verbose `console.info` logging at runtime even in
1203
+ * production builds. Useful when reproducing customer issues. Independent of the
1204
+ * build-time `__DEBUG__` flag, which already gates dev-server logs.
1205
+ *
1206
+ * @default false
1207
+ */
1208
+ debug?: boolean;
1209
+ }
1210
+
1211
+ /** Payload for VELION_EXIT (mirrors {@link OnboardingExit}). */
1212
+ export declare type VelionExitPayload = OnboardingExit;
1213
+
1214
+ /**
1215
+ * Configurable copy for the built-in final result screen (`showFinalResultScreen`).
1216
+ * Omitted fields fall back to SDK defaults for the active `locale`.
1217
+ */
1218
+ export declare interface VelionFinalResultScreenTexts {
1219
+ approved?: VelionFinalResultStatusCopy;
1220
+ manualReview?: VelionFinalResultStatusCopy;
1221
+ rejected?: VelionFinalResultStatusCopy;
1222
+ /** Copy when {@link OnboardingResult.status} is `DECLINED`. */
1223
+ declined?: VelionFinalResultStatusCopy;
1224
+ /** Primary button label (e.g. "Entendido" / "Got it"). */
1225
+ dismissLabel?: string;
1226
+ }
1227
+
1228
+ /**
1229
+ * Optional title and body for one terminal verdict on the final result screen.
1230
+ */
1231
+ export declare interface VelionFinalResultStatusCopy {
1232
+ title?: string;
1233
+ message?: string;
1234
+ }
1235
+
1236
+ /** Payload for VELION_INIT: full config (iframe runs with containerId overwritten to root id). */
1237
+ export declare type VelionInitPayload = VelionConfig;
1238
+
1239
+ /** Payload for VELION_LIVENESS_VIDEO_UPLOADED (mirrors {@link LivenessVideoRef}). */
1240
+ export declare type VelionLivenessVideoUploadedPayload = LivenessVideoRef;
1241
+
1242
+ /** Loader config: VelionConfig plus optional CDN URL and token refresh callback. */
1243
+ export declare interface VelionLoaderConfig extends VelionConfig {
1244
+ /**
1245
+ * Base URL of the CDN where the onboarding app is served (e.g. https://static.velion.la/sdk).
1246
+ * The loader fetches `${cdnUrl}/manifest.json` (signed with Ed25519), verifies the
1247
+ * signature against the loader's embedded public key, and only then loads the
1248
+ * iframe entry named in the manifest.
1249
+ * @default 'https://static.velion.la/sdk'
1250
+ */
1251
+ cdnUrl?: string;
1252
+ /**
1253
+ * When `true`, lets the loader proceed against a CDN that does not yet expose a
1254
+ * signed `manifest.json` — for staging or migration windows. Has NO effect when
1255
+ * the loader carries an embedded pubkey AND the manifest exists but signature
1256
+ * verification fails (that case is always fatal).
1257
+ *
1258
+ * Default `false`: production loaders refuse to mount the iframe without a
1259
+ * verified manifest once the pubkey has been provisioned.
1260
+ *
1261
+ * @default false
1262
+ */
1263
+ allowUnverifiedCdn?: boolean;
1264
+ /**
1265
+ * Called when the iframe requests a new session token (e.g. after SESSION_EXPIRED).
1266
+ * Return the new token and optional expiresAt; the CDN app will continue the flow.
1267
+ */
1268
+ onTokenExpired?: () => Promise<{
1269
+ sessionToken: string;
1270
+ expiresAt?: string;
1271
+ }>;
1272
+ /**
1273
+ * How long to wait, after the iframe document loaded, for the runtime to
1274
+ * report `VELION_READY`. Past it the loader emits `RUNTIME_LOAD_FAILED`
1275
+ * instead of leaving the host with a blank iframe and no callback (e.g.
1276
+ * when the CDN entry points at assets that 404).
1277
+ *
1278
+ * @default 30000
1279
+ */
1280
+ runtimeReadyTimeoutMs?: number;
1281
+ }
1282
+
1283
+ /** Envelope for all loader ↔ iframe messages. Both sides must validate origin. */
1284
+ export declare interface VelionMessage<T = unknown> {
1285
+ type: VelionMessageType;
1286
+ payload: T;
1287
+ }
1288
+
1289
+ export declare 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_EXIT | typeof VELION_MSG_LIVENESS_VIDEO_UPLOADED | typeof VELION_MSG_TOKEN;
1290
+
1291
+ export declare class VelionOnboarding {
1292
+ private readonly config;
1293
+ private status;
1294
+ private iframe;
1295
+ private container;
1296
+ private messageHandler;
1297
+ private containerResizeObserver;
1298
+ private iframeHeightWindowResizeHandler;
1299
+ private cdnOrigin;
1300
+ /** Armed when VELION_INIT is sent; cleared by VELION_READY or destroy(). */
1301
+ private readyTimer;
1302
+ /** Set once VELION_INIT (and with it the session token) has been posted. */
1303
+ private initSent;
1304
+ /**
1305
+ * Set when the iframe loads a second document after INIT. From then on nothing
1306
+ * from the iframe is trusted: it is no longer the document the loader verified.
1307
+ */
1308
+ private iframeReloaded;
1309
+ private clearReadyTimer;
1310
+ private armReadyTimer;
1311
+ constructor(config: VelionLoaderConfig);
1312
+ start(): Promise<void>;
1313
+ /**
1314
+ * Reacts to a second `load` of the iframe after `VELION_INIT` was posted.
1315
+ *
1316
+ * The session is not restarted: that would mean posting the session token to a
1317
+ * document the loader never verified (the integrity check covers the bytes it
1318
+ * downloaded before the first navigation, not whatever a reload brings). Failing
1319
+ * costs little, because the backend owns the session state: a new instance
1320
+ * re-verifies the CDN and resumes from the current step.
1321
+ */
1322
+ private handleIframeReload;
1323
+ /**
1324
+ * Applies the anti-rollback policy to a signed manifest and verifies the entry HTML
1325
+ * and its scripts. Emits onError and returns `false` when the runtime must not be
1326
+ * mounted.
1327
+ */
1328
+ private verifyRuntime;
1329
+ /**
1330
+ * Fetches and verifies the CDN manifest. Returns `null` and emits onError when
1331
+ * the manifest is missing in production mode, or when the signature is invalid.
1332
+ * `synthesized` marks the stand-in used for a legacy CDN without a manifest.
1333
+ */
1334
+ private resolveManifest;
1335
+ /**
1336
+ * Keep the iframe exactly as tall as the host container so integrators do not need
1337
+ * `height: 100%` on the iframe or flex hacks—only a definite block-size on the
1338
+ * container (e.g. `height: 700px` or `height: 100vh`), similar to Sumsub WebSDK.
1339
+ *
1340
+ * Until the container has a non-zero `clientHeight`, apply an internal fallback
1341
+ * height so the SDK is usable even before layout or if only `min-height` is set.
1342
+ */
1343
+ private attachIframeHeightSync;
1344
+ private detachIframeHeightSync;
1345
+ private sendToIframe;
1346
+ getStatus(): SdkStatus;
1347
+ static getVersion(): string;
1348
+ destroy(): void;
1349
+ }
1350
+
1351
+ /**
1352
+ * Per-step overrides for the retry dialog shown when the backend emits a
1353
+ * `ROUTING_COMMAND / RETRY_STEP` (the step failed but the retry quota is not
1354
+ * exhausted). Keyed by step code (e.g. `LIVENESS_MATCH`, `DOCUMENTS_OCR`).
1355
+ * Unspecified steps fall back to SDK per-step defaults, then generic copy.
1356
+ *
1357
+ * Note: the SDK intentionally ignores the backend `reason` for this dialog —
1358
+ * it is a diagnostic string (e.g. `"STEP_FAILED_RETRY_ALLOWED (attempt 1/3)"`),
1359
+ * not user-facing localized copy. The copy is derived from the step instead.
1360
+ */
1361
+ export declare type VelionRetryStepTexts = Record<string, VelionSessionDeclinedReasonMessages>;
1362
+
1363
+ /**
1364
+ * Localized title/body for one `reason` on the SESSION_DECLINED screen.
1365
+ * Keys match backend `reason` (e.g. `TAX_INFO_FAILED`).
1366
+ */
1367
+ export declare interface VelionSessionDeclinedReasonMessages {
1368
+ en?: VelionFinalResultStatusCopy;
1369
+ es?: VelionFinalResultStatusCopy;
1370
+ }
1371
+
1372
+ /**
1373
+ * Per-reason overrides for the built-in SESSION_DECLINED screen (`showFinalResultScreen` not false).
1374
+ * Unspecified reasons fall back to SDK defaults when available, then generic copy.
1375
+ */
1376
+ export declare type VelionSessionDeclinedReasonTexts = Record<string, VelionSessionDeclinedReasonMessages>;
1377
+
1378
+ /** Payload for VELION_STEP_CHANGE. */
1379
+ export declare interface VelionStepChangePayload {
1380
+ step: OnboardingStep;
1381
+ stepIndex: number;
1382
+ }
1383
+
1384
+ /** Payload for VELION_STEP_COMPLETE. */
1385
+ export declare interface VelionStepCompletePayload {
1386
+ step: OnboardingStep;
1387
+ }
1388
+
1389
+ /**
1390
+ * White-labeling theme configuration.
1391
+ * Each property maps to a CSS custom property injected on the SDK container,
1392
+ * making all SDK UI elements styleable via `--vl-*` variables.
1393
+ *
1394
+ * @example
1395
+ * ```typescript
1396
+ * const theme: VelionTheme = {
1397
+ * primaryColor: '#0052CC', // → --vl-primary-color
1398
+ * borderRadius: '12px', // → --vl-border-radius
1399
+ * fontFamily: 'Inter, sans-serif'// → --vl-font-family
1400
+ * };
1401
+ * ```
1402
+ */
1403
+ export declare interface VelionTheme {
1404
+ /** Primary brand color. Used for buttons, progress indicators, and accents. */
1405
+ primaryColor?: string;
1406
+ /** Secondary color. Used for hover states and secondary actions. */
1407
+ secondaryColor?: string;
1408
+ /** Background color of the SDK container. */
1409
+ backgroundColor?: string;
1410
+ /** Main body text color. */
1411
+ textColor?: string;
1412
+ /** Secondary text color for subtitles, captions, and de-emphasized copy. */
1413
+ textSecondaryColor?: string;
1414
+ /** Border radius for cards, buttons, and inputs. */
1415
+ borderRadius?: string;
1416
+ /** Font family string. Must be available in the host page's CSS context. */
1417
+ fontFamily?: string;
1418
+ /** Color used for error states and destructive actions. */
1419
+ errorColor?: string;
1420
+ /** Color used for success confirmations. */
1421
+ successColor?: string;
1422
+ /** Color used for warnings and informational alerts. */
1423
+ warningColor?: string;
1424
+ /** Border color for input fields and separators. */
1425
+ borderColor?: string;
1426
+ /** Box shadow definition for elevated elements (cards, modals). */
1427
+ cardShadow?: string;
1428
+ /**
1429
+ * When `true`, the round icon that sits above each step's title is hidden.
1430
+ * Only the title and subtitle are rendered. Useful when the host UI already
1431
+ * provides its own visual identity per step or when a denser layout is
1432
+ * preferred.
1433
+ *
1434
+ * @default false
1435
+ */
1436
+ hideStepIcons?: boolean;
1437
+ /**
1438
+ * When `true`, the thin progress bar at the top of the SDK container is
1439
+ * hidden. Equivalent to setting `VelionConfig.showProgressBar: false` —
1440
+ * either flag is enough to disable it (whichever is more convenient given
1441
+ * how the host configures the SDK). Disable when your host UI already
1442
+ * surfaces its own progress indicator.
1443
+ *
1444
+ * @default false
1445
+ */
1446
+ hideProgressBar?: boolean;
1447
+ }
1448
+
1449
+ /** Payload for VELION_TOKEN (token refresh response from parent to iframe). */
1450
+ export declare interface VelionTokenPayload {
1451
+ sessionToken: string;
1452
+ expiresAt?: string;
1453
+ }
1454
+
1455
+ /**
1456
+ * Signed-upload payload returned by `POST /liveness-init`. Mirrors the backend
1457
+ * `LivenessInitResponseDto.VideoUpload`. The SDK PUTs the recorded video bytes
1458
+ * to `upload_url` (Content-Type matching the recorded container) before calling
1459
+ * `POST /liveness-verify` with the resulting metadata.
1460
+ */
1461
+ export declare interface VideoUpload {
1462
+ /** Absolute https://storage.googleapis.com/... URL with V4 signature params. */
1463
+ upload_url: string;
1464
+ /** ISO-8601 instant after which GCS rejects the signature. */
1465
+ expires_at: string;
1466
+ /** HTTP method to use. Always `"PUT"` today; future-proofing. */
1467
+ method: 'PUT' | string;
1468
+ }
1469
+
1
1470
  export { }