@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 +1469 -0
- package/dist/velion-sdk.es.js +1 -1
- package/dist/velion-sdk.es.js.map +1 -1
- package/dist/velion-sdk.umd.js +1 -1
- package/dist/velion-sdk.umd.js.map +1 -1
- package/package.json +5 -7
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&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&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&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 { }
|