@sekyro/web 0.1.0-rc.3 → 0.1.0-rc.31
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/CHANGELOG.md +433 -0
- package/LICENSE +25 -16
- package/README.md +157 -62
- package/THIRD-PARTY-NOTICES.txt +154 -0
- package/dist/background-monitor-A7FKJOAG.js +1 -0
- package/dist/barcode-detect-C5IOXMKI.js +1 -0
- package/dist/camera-trait-V4UAOPIQ.js +1 -0
- package/dist/capture-constraints-CVqpMNGA.d.cts +48 -0
- package/dist/capture-constraints-CVqpMNGA.d.ts +48 -0
- package/dist/capture-session-doc-2LIRRKFX.js +1 -0
- package/dist/{capture-session-v3-COIO_F2w.d.cts → capture-session-v3-Fbj-X2Ij.d.ts} +259 -13
- package/dist/{capture-session-v3-CvIfcwST.d.ts → capture-session-v3-XtBrXpoW.d.cts} +259 -13
- package/dist/challenge-frame-YAQJ5YMB.js +1 -0
- package/dist/chunk-2LDOXGY3.js +1 -0
- package/dist/chunk-2MX4J26D.js +3 -0
- package/dist/chunk-33KKMPJ5.js +1 -0
- package/dist/chunk-3K3A7O7J.js +1 -0
- package/dist/chunk-53POX7U4.js +1 -0
- package/dist/chunk-6ERQTXMY.js +1 -0
- package/dist/chunk-6Z4MIKGF.js +1 -0
- package/dist/chunk-7QZWBDI5.js +1 -0
- package/dist/chunk-CJHMFPL6.js +1 -0
- package/dist/chunk-CMXN4SOZ.js +1 -0
- package/dist/chunk-CPUECYAJ.js +1 -0
- package/dist/chunk-DFTCAWMP.js +1 -0
- package/dist/chunk-DK5YPBDQ.js +1 -0
- package/dist/chunk-FPXL63KZ.js +1 -0
- package/dist/chunk-FSSMUAKC.js +1 -0
- package/dist/chunk-G6LKLN4U.js +1 -0
- package/dist/chunk-GFJATPUR.js +1 -0
- package/dist/chunk-GI3UFGRQ.js +1 -0
- package/dist/chunk-GXL6ZD4I.js +1 -0
- package/dist/chunk-JLVZ35QK.js +2 -0
- package/dist/chunk-MD4YXLPK.js +1 -0
- package/dist/chunk-OUC57KMS.js +1 -0
- package/dist/chunk-POIQGEZM.js +1 -0
- package/dist/chunk-R3JMNYW5.js +1 -0
- package/dist/chunk-RI3E7GBN.js +1 -0
- package/dist/chunk-SMKCBUJL.js +1 -0
- package/dist/chunk-SUANHBF4.js +1 -0
- package/dist/chunk-SX7TUC3V.js +1 -0
- package/dist/chunk-TN4JWBFJ.js +1 -0
- package/dist/chunk-TSA6GHUG.js +1 -0
- package/dist/chunk-VWGKUQ3C.js +1 -0
- package/dist/chunk-XFDWFJLY.js +1 -0
- package/dist/chunk-ZKF2XMNX.js +1 -0
- package/dist/client/index.cjs +1 -357
- package/dist/client/index.d.cts +6 -37
- package/dist/client/index.d.ts +6 -37
- package/dist/client/index.js +1 -15
- package/dist/clip-inspect-DLJXVKV6.js +1 -0
- package/dist/core/index.cjs +1 -1606
- package/dist/core/index.d.cts +5 -4
- package/dist/core/index.d.ts +5 -4
- package/dist/core/index.js +1 -139
- package/dist/core/ocr/worker.bundle.js +42 -0
- package/dist/core/ocr/worker.cjs +42 -0
- package/dist/core/ocr/worker.d.cts +84 -0
- package/dist/core/ocr/worker.d.ts +84 -0
- package/dist/core/ocr/worker.js +41 -0
- package/dist/core/v3/detect-worker.cjs +1 -392
- package/dist/core/v3/detect-worker.d.cts +1 -1
- package/dist/core/v3/detect-worker.d.ts +1 -1
- package/dist/core/v3/detect-worker.js +1 -13
- package/dist/create-document-capture-X35M4UAK.js +1 -0
- package/dist/create-portrait-capture-5VGYZUOK.js +1 -0
- package/dist/create-verification-RdG6qv51.d.ts +3732 -0
- package/dist/create-verification-lXGU3ac4.d.cts +3732 -0
- package/dist/{detect-worker-CKXHlXx9.d.ts → detect-worker-CHqsPJoM.d.cts} +25 -2
- package/dist/{detect-worker-CKXHlXx9.d.cts → detect-worker-CHqsPJoM.d.ts} +25 -2
- package/dist/detector-scanic-KMAVOHGF.js +1 -0
- package/dist/icao-gate-Cp1C4IEZ.d.ts +578 -0
- package/dist/icao-gate-DVNkPclI.d.cts +578 -0
- package/dist/icao-gate-T3BTOKFJ.js +1 -0
- package/dist/icao-policy-CcrwfsVr.d.ts +80 -0
- package/dist/icao-policy-c2Ykm9r2.d.cts +80 -0
- package/dist/icao-tuning-4ETMF53W.js +1 -0
- package/dist/index.cjs +3 -2649
- package/dist/index.d.cts +138 -5
- package/dist/index.d.ts +138 -5
- package/dist/index.js +1 -28
- package/dist/internal/index.cjs +3 -4179
- package/dist/internal/index.d.cts +390 -371
- package/dist/internal/index.d.ts +390 -371
- package/dist/internal/index.js +1 -647
- package/dist/keyframe-rank-YAJLYJYF.js +1 -0
- package/dist/landmarker-KB7LVXAU.js +1 -0
- package/dist/mrz-band-VYHOTDHY.js +1 -0
- package/dist/plan-runner-T2ZTSBI4.js +1 -0
- package/dist/popup/index.cjs +1 -76
- package/dist/popup/index.d.cts +9 -3
- package/dist/popup/index.d.ts +9 -3
- package/dist/popup/index.js +1 -11
- package/dist/print-SEWS3VHQ.js +1 -0
- package/dist/scanic-ml-stub-KW7IZHUT.js +1 -0
- package/dist/segmenter-USLNBX65.js +1 -0
- package/dist/types-B47mZ5TT.d.cts +2107 -0
- package/dist/types-B47mZ5TT.d.ts +2107 -0
- package/dist/upload-file-EGXXM6TQ.js +1 -0
- package/package.json +30 -11
- package/sbom.cdx.json +349 -0
- package/dist/capture-constraints-BujkZcfb.d.cts +0 -21
- package/dist/capture-constraints-BujkZcfb.d.ts +0 -21
- package/dist/chunk-7TC6TOZ4.js +0 -1095
- package/dist/chunk-7TC6TOZ4.js.map +0 -1
- package/dist/chunk-FIXX2AXC.js +0 -864
- package/dist/chunk-FIXX2AXC.js.map +0 -1
- package/dist/chunk-MWNFSNMP.js +0 -52
- package/dist/chunk-MWNFSNMP.js.map +0 -1
- package/dist/chunk-NILNKLK6.js +0 -50
- package/dist/chunk-NILNKLK6.js.map +0 -1
- package/dist/chunk-NWF46H7K.js +0 -359
- package/dist/chunk-NWF46H7K.js.map +0 -1
- package/dist/chunk-WY6U7AIK.js +0 -193
- package/dist/chunk-WY6U7AIK.js.map +0 -1
- package/dist/chunk-YVFF4Q4G.js +0 -327
- package/dist/chunk-YVFF4Q4G.js.map +0 -1
- package/dist/client/index.cjs.map +0 -1
- package/dist/client/index.js.map +0 -1
- package/dist/core/index.cjs.map +0 -1
- package/dist/core/index.js.map +0 -1
- package/dist/core/v3/detect-worker.cjs.map +0 -1
- package/dist/core/v3/detect-worker.js.map +0 -1
- package/dist/create-verification-CP18eq1Q.d.cts +0 -348
- package/dist/create-verification-CswF2As-.d.ts +0 -348
- package/dist/detector-scanic-4C6IEW2K.js +0 -787
- package/dist/detector-scanic-4C6IEW2K.js.map +0 -1
- package/dist/hosted-client-BpvBqu9f.d.cts +0 -408
- package/dist/hosted-client-BpvBqu9f.d.ts +0 -408
- package/dist/index.cjs.map +0 -1
- package/dist/index.js.map +0 -1
- package/dist/internal/index.cjs.map +0 -1
- package/dist/internal/index.js.map +0 -1
- package/dist/popup/index.cjs.map +0 -1
- package/dist/popup/index.js.map +0 -1
- package/dist/scanic-ml-stub-S2OZ6HEF.js +0 -10
- package/dist/scanic-ml-stub-S2OZ6HEF.js.map +0 -1
|
@@ -0,0 +1,2107 @@
|
|
|
1
|
+
/** Server-tunable thresholds (`capture.icao.backgroundCheck`); defaults below. */
|
|
2
|
+
interface BackgroundCheckTuning {
|
|
3
|
+
/** Run the check at all (ICAO on). Default `true`. */
|
|
4
|
+
enabled: boolean;
|
|
5
|
+
/** Measurements per second (the face gate runs faster). Default 3. */
|
|
6
|
+
hz: number;
|
|
7
|
+
/** The segmenter must load within this window, else the strip fallback. Default 8000 ms. */
|
|
8
|
+
segmenterTimeoutMs: number;
|
|
9
|
+
/** A segmentation slower than this (moving average) switches to the strip fallback. Default 120 ms. */
|
|
10
|
+
segmenterBudgetMs: number;
|
|
11
|
+
/** Person confidence at or above this is the person (excluded). Default 0.5. */
|
|
12
|
+
maskThreshold: number;
|
|
13
|
+
/** Max RMS colour standard deviation (0..255). Default 28. */
|
|
14
|
+
maxColorStd: number;
|
|
15
|
+
/** Max share of textured neighbour pairs (0..1). Default 0.08. */
|
|
16
|
+
maxEdgeDensity: number;
|
|
17
|
+
/** Luma step (0..255) that counts as an edge. Default 24. */
|
|
18
|
+
edgeLuma: number;
|
|
19
|
+
/** Max left/right or top/bottom brightness difference (0..1). Default 0.18. */
|
|
20
|
+
maxGradient: number;
|
|
21
|
+
/** Fewer background pixels than this = not measurable (never blocks). Default 300. */
|
|
22
|
+
minPixels: number;
|
|
23
|
+
/** A non-uniform background holds the shot at most this long, then the shot proceeds. Default 4000 ms. */
|
|
24
|
+
timeoutMs: number;
|
|
25
|
+
}
|
|
26
|
+
/** Person confidence per pixel (0..1 floats, or 0..255 bytes), any resolution (scaled to the frame). */
|
|
27
|
+
interface PersonMask {
|
|
28
|
+
data: Float32Array | Uint8Array | Uint8ClampedArray;
|
|
29
|
+
width: number;
|
|
30
|
+
height: number;
|
|
31
|
+
}
|
|
32
|
+
/** One measurement — numbers only (telemetry and the `gate` block). */
|
|
33
|
+
interface BackgroundUniformity {
|
|
34
|
+
method: "segmenter" | "strip";
|
|
35
|
+
uniform: boolean;
|
|
36
|
+
colorStd: number;
|
|
37
|
+
edgeDensity: number;
|
|
38
|
+
gradient: number;
|
|
39
|
+
/** Background pixels measured (after sampling). */
|
|
40
|
+
pixels: number;
|
|
41
|
+
}
|
|
42
|
+
|
|
43
|
+
/** The device (coaching) limits of each profile — the server limits moved towards strict. */
|
|
44
|
+
declare const ICAO_DEVICE_LIMITS: {
|
|
45
|
+
readonly id_document: {
|
|
46
|
+
readonly pose: {
|
|
47
|
+
readonly yawDeg: 7;
|
|
48
|
+
readonly pitchDeg: 7;
|
|
49
|
+
readonly rollDeg: 5;
|
|
50
|
+
readonly pitchOffsetDeg: 4;
|
|
51
|
+
};
|
|
52
|
+
readonly eyes: {
|
|
53
|
+
readonly relativeMin: 0.62;
|
|
54
|
+
readonly blinkMax: 0.48;
|
|
55
|
+
readonly lowerEyeMin: 0.32;
|
|
56
|
+
};
|
|
57
|
+
readonly mouth: {
|
|
58
|
+
readonly jawOpenMax: 0.13;
|
|
59
|
+
readonly smileMax: 0.28;
|
|
60
|
+
readonly puckerMax: 0.48;
|
|
61
|
+
};
|
|
62
|
+
readonly lighting: {
|
|
63
|
+
readonly faceLuma: readonly [95, 185];
|
|
64
|
+
readonly halfRatio: readonly [0.77, 1.31];
|
|
65
|
+
readonly clippedMax: 0.015;
|
|
66
|
+
};
|
|
67
|
+
readonly background: {
|
|
68
|
+
readonly required: true;
|
|
69
|
+
readonly lumaMin: 165;
|
|
70
|
+
readonly lumaSdMax: 20;
|
|
71
|
+
};
|
|
72
|
+
readonly resolution: {
|
|
73
|
+
readonly minIodPx: 110;
|
|
74
|
+
readonly minWidth: 480;
|
|
75
|
+
readonly minHeight: 640;
|
|
76
|
+
};
|
|
77
|
+
};
|
|
78
|
+
readonly selfie: {
|
|
79
|
+
readonly pose: {
|
|
80
|
+
readonly yawDeg: 7;
|
|
81
|
+
readonly pitchDeg: 7;
|
|
82
|
+
readonly rollDeg: 7;
|
|
83
|
+
readonly pitchOffsetDeg: 4;
|
|
84
|
+
};
|
|
85
|
+
readonly eyes: {
|
|
86
|
+
readonly relativeMin: 0.62;
|
|
87
|
+
readonly blinkMax: 0.48;
|
|
88
|
+
readonly lowerEyeMin: 0.32;
|
|
89
|
+
};
|
|
90
|
+
readonly mouth: {
|
|
91
|
+
readonly jawOpenMax: 0.13;
|
|
92
|
+
readonly smileMax: 0.28;
|
|
93
|
+
readonly puckerMax: 0.28;
|
|
94
|
+
};
|
|
95
|
+
readonly lighting: {
|
|
96
|
+
readonly faceLuma: readonly [95, 185];
|
|
97
|
+
readonly halfRatio: readonly [0.77, 1.31];
|
|
98
|
+
readonly clippedMax: 0.015;
|
|
99
|
+
};
|
|
100
|
+
readonly background: {
|
|
101
|
+
readonly required: false;
|
|
102
|
+
readonly lumaMin: 165;
|
|
103
|
+
readonly lumaSdMax: 20;
|
|
104
|
+
};
|
|
105
|
+
readonly resolution: {
|
|
106
|
+
readonly minIodPx: 100;
|
|
107
|
+
readonly minWidth: 480;
|
|
108
|
+
readonly minHeight: 640;
|
|
109
|
+
};
|
|
110
|
+
};
|
|
111
|
+
};
|
|
112
|
+
|
|
113
|
+
/** The ICAO threshold set (`id_document`: ID photo; `selfie`: no background rule). */
|
|
114
|
+
type IcaoProfile = keyof typeof ICAO_DEVICE_LIMITS;
|
|
115
|
+
/** `capture.icao` as the server sends it (every field optional on the wire). */
|
|
116
|
+
interface IcaoCaptureTuning {
|
|
117
|
+
/** The threshold set these limits come from (default `id_document`; it also picks the fallbacks). */
|
|
118
|
+
profile?: "id_document" | "selfie";
|
|
119
|
+
yawDeg?: number;
|
|
120
|
+
pitchDeg?: number;
|
|
121
|
+
/**
|
|
122
|
+
* Subtracted from the measured pitch before `pitchDeg` applies (degrees). Where
|
|
123
|
+
* "looking straight" sits relative to the Landmarker's zero; kyc-portrait applies the
|
|
124
|
+
* same `PORTRAIT_POSE_PITCH_OFFSET_DEG`, so keep them equal (D9a, 2026-10-22).
|
|
125
|
+
*/
|
|
126
|
+
pitchOffsetDeg?: number;
|
|
127
|
+
rollDeg?: number;
|
|
128
|
+
holdMs?: number;
|
|
129
|
+
/** `alert` policy: the clip starts this long after the face was accepted even if the ICAO gate is not ready (default 3000). */
|
|
130
|
+
alertGraceMs?: number;
|
|
131
|
+
eyes?: {
|
|
132
|
+
relativeMin?: number;
|
|
133
|
+
blinkMax?: number;
|
|
134
|
+
lowerEyeMin?: number;
|
|
135
|
+
earMin?: number;
|
|
136
|
+
};
|
|
137
|
+
mouth?: {
|
|
138
|
+
jawOpenMax?: number;
|
|
139
|
+
smileMax?: number;
|
|
140
|
+
puckerMax?: number;
|
|
141
|
+
};
|
|
142
|
+
lighting?: {
|
|
143
|
+
faceLuma?: [number, number];
|
|
144
|
+
halfRatio?: [number, number];
|
|
145
|
+
clippedMax?: number;
|
|
146
|
+
};
|
|
147
|
+
/** `required: false` (the `selfie` profile): the background is not evaluated, coached or reported. */
|
|
148
|
+
background?: {
|
|
149
|
+
required?: boolean;
|
|
150
|
+
lumaMin?: number;
|
|
151
|
+
lumaSdMax?: number;
|
|
152
|
+
};
|
|
153
|
+
resolution?: {
|
|
154
|
+
minIodPx?: number;
|
|
155
|
+
minWidth?: number;
|
|
156
|
+
minHeight?: number;
|
|
157
|
+
};
|
|
158
|
+
/** Client-only knobs (no server field today; read when the server adds them). */
|
|
159
|
+
holdFrames?: number;
|
|
160
|
+
cadenceHz?: number;
|
|
161
|
+
baseline?: {
|
|
162
|
+
windowMs?: number;
|
|
163
|
+
minSamples?: number;
|
|
164
|
+
percentile?: number;
|
|
165
|
+
};
|
|
166
|
+
sharpnessMin?: number;
|
|
167
|
+
glare?: {
|
|
168
|
+
specularMax?: number;
|
|
169
|
+
};
|
|
170
|
+
softGraceMs?: number;
|
|
171
|
+
cropMargin?: number;
|
|
172
|
+
camera?: {
|
|
173
|
+
width?: number;
|
|
174
|
+
height?: number;
|
|
175
|
+
};
|
|
176
|
+
/**
|
|
177
|
+
* The client background-uniformity check (ID mode; defaults in
|
|
178
|
+
* core/portrait/background-uniformity.ts `BACKGROUND_CHECK_DEFAULTS`).
|
|
179
|
+
* Skipped entirely when `background.required` is false.
|
|
180
|
+
*/
|
|
181
|
+
backgroundCheck?: Partial<BackgroundCheckTuning>;
|
|
182
|
+
}
|
|
183
|
+
/** Fully resolved limits the gate runs on. */
|
|
184
|
+
interface ResolvedIcaoTuning {
|
|
185
|
+
profile: IcaoProfile;
|
|
186
|
+
yawDeg: number;
|
|
187
|
+
pitchDeg: number;
|
|
188
|
+
pitchOffsetDeg: number;
|
|
189
|
+
rollDeg: number;
|
|
190
|
+
holdMs: number;
|
|
191
|
+
alertGraceMs: number;
|
|
192
|
+
eyes: {
|
|
193
|
+
relativeMin: number;
|
|
194
|
+
blinkMax: number;
|
|
195
|
+
lowerEyeMin: number;
|
|
196
|
+
};
|
|
197
|
+
mouth: {
|
|
198
|
+
jawOpenMax: number;
|
|
199
|
+
smileMax: number;
|
|
200
|
+
puckerMax: number;
|
|
201
|
+
};
|
|
202
|
+
lighting: {
|
|
203
|
+
faceLuma: [number, number];
|
|
204
|
+
halfRatio: [number, number];
|
|
205
|
+
clippedMax: number;
|
|
206
|
+
};
|
|
207
|
+
background: {
|
|
208
|
+
required: boolean;
|
|
209
|
+
lumaMin: number;
|
|
210
|
+
lumaSdMax: number;
|
|
211
|
+
};
|
|
212
|
+
resolution: {
|
|
213
|
+
minIodPx: number;
|
|
214
|
+
minWidth: number;
|
|
215
|
+
minHeight: number;
|
|
216
|
+
};
|
|
217
|
+
holdFrames: number;
|
|
218
|
+
cadenceHz: number;
|
|
219
|
+
baseline: {
|
|
220
|
+
windowMs: number;
|
|
221
|
+
minSamples: number;
|
|
222
|
+
percentile: number;
|
|
223
|
+
};
|
|
224
|
+
sharpnessMin: number;
|
|
225
|
+
glare: {
|
|
226
|
+
specularMax: number;
|
|
227
|
+
};
|
|
228
|
+
softGraceMs: number;
|
|
229
|
+
cropMargin: number;
|
|
230
|
+
camera: {
|
|
231
|
+
width: number;
|
|
232
|
+
height: number;
|
|
233
|
+
};
|
|
234
|
+
backgroundCheck: BackgroundCheckTuning;
|
|
235
|
+
/** The server's `capture.tuningVersion`, echoed on submit (`null` when absent). */
|
|
236
|
+
tuningVersion: string | null;
|
|
237
|
+
}
|
|
238
|
+
/** Bundled fallbacks: the `id_document` device limits (never looser than the server). */
|
|
239
|
+
declare const ICAO_FALLBACK: Omit<ResolvedIcaoTuning, "tuningVersion">;
|
|
240
|
+
/**
|
|
241
|
+
* Resolve `capture.icao` (any shape, possibly absent) over {@link ICAO_FALLBACK},
|
|
242
|
+
* field by field: an out-of-range or malformed field keeps its fallback.
|
|
243
|
+
*/
|
|
244
|
+
declare function resolveIcaoTuning(raw: unknown, tuningVersion?: unknown): ResolvedIcaoTuning;
|
|
245
|
+
|
|
246
|
+
/**
|
|
247
|
+
* Session lifecycle status (session outcome model 2026-11-08): a finished session is
|
|
248
|
+
* `verified` or `not_verified`; a `not_verified` one says why in {@link SessionReason},
|
|
249
|
+
* and every finished one says who or what closed it in {@link ClosedBy}.
|
|
250
|
+
*/
|
|
251
|
+
type SessionStatus = "created" | "in_progress" | "review_pending" | "verified" | "not_verified";
|
|
252
|
+
/**
|
|
253
|
+
* Why a `not_verified` session was not verified (verification-session.schema.ts
|
|
254
|
+
* `SESSION_REASONS`): a verdict against the person (`rejected`), no verdict
|
|
255
|
+
* (`inconclusive`), the check could not run (`unavailable`), the person started but the
|
|
256
|
+
* session expired before a result (`abandoned`), the link was sent but the session expired
|
|
257
|
+
* before it was opened (`not_opened`), a flow rule (`policy`), the organization cancelled
|
|
258
|
+
* it (`cancelled`), a newer session took its review over (`superseded`).
|
|
259
|
+
*/
|
|
260
|
+
type SessionReason = "rejected" | "inconclusive" | "unavailable" | "abandoned" | "not_opened" | "policy" | "cancelled" | "superseded";
|
|
261
|
+
/** Who or what closed a finished session (verification-session.schema.ts `CLOSED_BY`). */
|
|
262
|
+
type ClosedBy = "automatic" | "reviewer" | "deadline" | "expiry" | "organization";
|
|
263
|
+
/**
|
|
264
|
+
* What a step's last counted attempt said (verification-session.schema.ts `STEP_RESULTS`);
|
|
265
|
+
* absent before the first counted attempt.
|
|
266
|
+
*/
|
|
267
|
+
type StepResult = "passed" | "rejected" | "inconclusive" | "unreadable" | "unavailable" | "review";
|
|
268
|
+
/** The step that decided a `not_verified` session: its node id and its service. */
|
|
269
|
+
interface SessionDecidingStep {
|
|
270
|
+
id: string;
|
|
271
|
+
service: string;
|
|
272
|
+
}
|
|
273
|
+
/**
|
|
274
|
+
* What a finished session proved: `1` Contact, `2` Human, `3` Identity; `0`
|
|
275
|
+
* when nothing was proven.
|
|
276
|
+
*/
|
|
277
|
+
type VerificationLevel = 0 | 1 | 2 | 3;
|
|
278
|
+
/**
|
|
279
|
+
* How a session's {@link VerificationLevel} was proved, weakest first. Level 1
|
|
280
|
+
* Contact: `device_only`, `contact_email`, `contact_phone`, `unbound_identity`
|
|
281
|
+
* (identity data with no live face matched to it). Level 2 Human: `live_only`,
|
|
282
|
+
* `live_unique`. Level 3 Identity: `supplied_biometric`, `document_biometric`,
|
|
283
|
+
* `eid_authenticated`, `chip_biometric`, `registry_biometric`. To require a
|
|
284
|
+
* particular proof, compare with a list of accepted values on your server.
|
|
285
|
+
*/
|
|
286
|
+
type VerificationAssurance = "device_only" | "contact_email" | "contact_phone" | "unbound_identity" | "live_only" | "live_unique" | "supplied_biometric" | "document_biometric" | "eid_authenticated" | "chip_biometric" | "registry_biometric";
|
|
287
|
+
/** Per-check seven-state machine (spec §4.3). */
|
|
288
|
+
type CheckState = "pending" | "input_required" | "processing" | "passed" | "failed" | "review" | "skipped";
|
|
289
|
+
/**
|
|
290
|
+
* The frozen check-type vocabulary (CHECK_TYPES). `phone_otp` joined in Task 13;
|
|
291
|
+
* `nfc_chip` (M-nfc) is read by the native SDKs only; `email_otp` (Plan 8,
|
|
292
|
+
* profile v2 §4.6.5) confirms an email address with a one-time code;
|
|
293
|
+
* `eid_auth` (SDK spec §3.2) is the national eID sign-in (Houwiyeti in MR).
|
|
294
|
+
*/
|
|
295
|
+
type CheckType = "liveness" | "face_match" | "doc_ocr" | "population_registry" | "phone_otp" | "nfc_chip" | "email_otp" | "portrait_icao" | "eid_auth"
|
|
296
|
+
/** Spec 2026-11-14 §14: the Form step (the person's declared answers and the client's consents). */
|
|
297
|
+
| "form"
|
|
298
|
+
/** Spec 2026-11-10 §5: the proof of address step (a bill or statement, images or one PDF). */
|
|
299
|
+
| "poa";
|
|
300
|
+
type LivenessReason = "no_face" | "media_unreadable" | "clip_too_short" | "spoof_detected" | "review_band" | "liveness_inconclusive" | "device_integrity_failed" | "mobile_required" | "capture_back_camera" | "capture_not_upright" | "capture_front_camera" | "multiple_faces" | "camera_unavailable";
|
|
301
|
+
type PopulationReason = "registry_record_not_found" | "nni_not_found" | "id_number_invalid" | "nni_invalid" | "registry_unavailable" | "nationality_not_allowed" | "underage" | "age_unverifiable" | "name_mismatch" | "birth_date_mismatch" | "nationality_mismatch" | "id_number_recheck" | "nni_recheck";
|
|
302
|
+
type FaceMatchReason = "no_face_source" | "no_face_reference" | "low_quality_reference" | "below_threshold" | "review_band" | "match_inconclusive" | "subject_revoked" | "probe_not_from_liveness" | "prior_review_approved";
|
|
303
|
+
type DocReason = "side_missing" | "mrz_checksum_failed" | "unreadable" | "expired_document" | "authenticity_review" | "document_authenticity" | "registry_mismatch" | "document_id_number_mismatch" | "document_nni_mismatch" | "nationality_unreadable" | "document_type_not_accepted" | "nationality_not_allowed" | "underage" | "age_unverifiable" | "document_type_not_supported" | "name_mismatch" | "birth_date_mismatch" | "nationality_mismatch" | "document_number_mismatch" | "document_sides_mismatch" | "document_photo_mismatch";
|
|
304
|
+
/**
|
|
305
|
+
* Profile v2 step 3 matching reasons: a field the partner sent at session
|
|
306
|
+
* create (`subject`) differs from the reference identity (document or
|
|
307
|
+
* registry). All four are final. `document_number_mismatch` is `doc_ocr` only.
|
|
308
|
+
*/
|
|
309
|
+
type MatchReason = "name_mismatch" | "birth_date_mismatch" | "nationality_mismatch" | "document_number_mismatch";
|
|
310
|
+
/**
|
|
311
|
+
* Profile v2 step 4 decision-mode reasons (the app decides automatically
|
|
312
|
+
* instead of sending the case to human review). These park the step at
|
|
313
|
+
* `input_required` while attempts remain: `liveness_inconclusive` /
|
|
314
|
+
* `match_inconclusive` (middle score band) and `document_authenticity`
|
|
315
|
+
* (retake the original card). `mobile_required` is kept for compatibility:
|
|
316
|
+
* the backend now answers a non-phone capture with a request-level
|
|
317
|
+
* `409 mobile_required` (continue on a phone; nothing used, not billed).
|
|
318
|
+
*/
|
|
319
|
+
type DecisionReason = "liveness_inconclusive" | "match_inconclusive" | "document_authenticity" | "mobile_required";
|
|
320
|
+
/**
|
|
321
|
+
* phone_otp reasons (Task 13). All transient — the caller fixes them by
|
|
322
|
+
* re-entering / resending: `otp_mismatch` (wrong or missing code),
|
|
323
|
+
* `otp_expired` (code lapsed or no active send), `otp_send_failed` (the OTP
|
|
324
|
+
* service was unreachable / a send returned no token).
|
|
325
|
+
*/
|
|
326
|
+
type PhoneOtpReason = "otp_mismatch" | "otp_expired" | "otp_send_failed" | "otp_channel_unavailable" | "otp_destination_not_allowed" | "otp_rate_limited" | "otp_resend_limit" | "otp_destination_unknown" | "otp_number_invalid" | "otp_number_not_mobile" | "otp_daily_cap_reached" | "payment_method_required" | "spend_cap_reached" | "insufficient_balance";
|
|
327
|
+
/**
|
|
328
|
+
* email_otp reasons (Plan 8, profile v2 §4.6.5). All transient: a wrong or
|
|
329
|
+
* expired code, a send outage, too many sends, an address that cannot receive
|
|
330
|
+
* mail (`email_invalid`), or a disposable address the app blocks
|
|
331
|
+
* (`email_disposable`) — the person enters another address or resends.
|
|
332
|
+
*/
|
|
333
|
+
type EmailOtpReason = "otp_mismatch" | "otp_expired" | "otp_send_failed" | "otp_rate_limited" | "otp_resend_limit" | "email_invalid" | "email_disposable" | "otp_daily_cap_reached" | "payment_method_required" | "spend_cap_reached" | "insufficient_balance" | "account_verification_required";
|
|
334
|
+
/**
|
|
335
|
+
* nfc_chip reasons (M-nfc, SDK spec §4.3). Native SDKs read the chip; the web
|
|
336
|
+
* never does — on web the step arrives `skipped` (`platform_unsupported`) or
|
|
337
|
+
* the session shows `reasonCode: 'platform_unsupported'`.
|
|
338
|
+
*/
|
|
339
|
+
type NfcChipReason = "chip_read_failed" | "chip_access_denied" | "chip_parse_failed" | "chip_not_present" | "nfc_unavailable" | "chip_document_mismatch" | "chip_integrity_failed" | "registry_mismatch" | "document_id_number_mismatch" | "document_nni_mismatch" | "platform_unsupported" | "document_photo_mismatch";
|
|
340
|
+
/**
|
|
341
|
+
* eid_auth reasons (SDK spec §3.2, generic national eID; Houwiyeti in MR).
|
|
342
|
+
* Retryable: `eid_identifier_invalid` (re-enter the number), `eid_code_invalid`
|
|
343
|
+
* (re-enter the code, see `eid.codeAttemptsRemaining`), `eid_code_expired`
|
|
344
|
+
* (ask for a new code), `eid_unavailable` (the provider is down; try again or
|
|
345
|
+
* use the camera), `eid_resend_too_soon` (wait for `eid.resendAvailableAt`),
|
|
346
|
+
* `eid_resend_limit` (no more codes; type the last code received).
|
|
347
|
+
* Final: `eid_locked` (too many wrong codes), `eid_not_enrolled` (the number
|
|
348
|
+
* has no account in the provider's app).
|
|
349
|
+
* With `eid_not_enrolled`, `eid_unavailable` or `eid_locked` the person may
|
|
350
|
+
* switch to the camera path when the session offers it.
|
|
351
|
+
*/
|
|
352
|
+
type EidReason = "eid_identifier_invalid" | "eid_code_invalid" | "eid_code_expired" | "eid_locked" | "eid_not_enrolled" | "eid_unavailable" | "eid_resend_too_soon" | "eid_resend_limit";
|
|
353
|
+
/**
|
|
354
|
+
* Reasons of the age check (selfie) step (`age_estimation`, run by the server after the liveness step):
|
|
355
|
+
* `age_uncertain` (the estimate did not settle the minimum age) and `age_unavailable` (the estimate could not run)
|
|
356
|
+
* step up to the document path when the flow has one; `underage_estimated` (clearly under the flow's minimum age)
|
|
357
|
+
* is final and ends the session.
|
|
358
|
+
*/
|
|
359
|
+
type AgeEstimationReason = "age_uncertain" | "age_unavailable" | "underage_estimated";
|
|
360
|
+
/**
|
|
361
|
+
* Reasons of the proof of address step (`poa`, spec 2026-11-10 §5.3), in the server's decision order:
|
|
362
|
+
* `provider_unavailable` (the document could not be checked now; retry), `unreadable` (a sharper, complete copy),
|
|
363
|
+
* `pdf_protected` (the PDF has a password, scripts, attachments or forms), `document_kind_not_accepted` and
|
|
364
|
+
* `document_too_old` (the step's rule for the document's country says what is accepted: `proofOfAddress.rule`),
|
|
365
|
+
* `document_date_invalid` (a date in the future), `document_tampered` (final), `name_mismatch`,
|
|
366
|
+
* `holder_letter_required` (the bill is in another person's name: the step asks for the holder's letter,
|
|
367
|
+
* `proofOfAddress.phase: "holder_letter"`), `holder_letter_missing` (the letter is incomplete) and `address_mismatch`
|
|
368
|
+
* (the address differs from the one the partner supplied).
|
|
369
|
+
*/
|
|
370
|
+
type PoaReason = "provider_unavailable" | "unreadable" | "pdf_protected" | "document_kind_not_accepted" | "document_date_invalid" | "document_too_old" | "document_tampered" | "name_mismatch" | "holder_letter_required" | "holder_letter_missing" | "address_mismatch";
|
|
371
|
+
/**
|
|
372
|
+
* Any frozen reason code. The backend declares the field `string`, but the
|
|
373
|
+
* taxonomy is frozen (do-not-drift) — the union IS the contract. NB: liveness
|
|
374
|
+
* and face_match both carry `review_band`.
|
|
375
|
+
*/
|
|
376
|
+
type CheckReason = LivenessReason | PopulationReason | FaceMatchReason | DocReason | PhoneOtpReason | EmailOtpReason | NfcChipReason | PortraitIcaoReason | EidReason | PoaReason
|
|
377
|
+
/**
|
|
378
|
+
* Spec 2026-10-27 (Sandbox testers), tester-bound sessions only:
|
|
379
|
+
* `tester_document_mismatch` (doc_ocr, nfc_chip) when the document read is
|
|
380
|
+
* not the bound tester's; `tester_phone_mismatch` (phone_otp) when the
|
|
381
|
+
* number is not the one the tester enrolled with.
|
|
382
|
+
*/
|
|
383
|
+
| "tester_document_mismatch" | "tester_phone_mismatch"
|
|
384
|
+
/**
|
|
385
|
+
* Review ends, on any reviewed step: `superseded_by_retry` (a newer attempt of the
|
|
386
|
+
* same person took the review over; the session is `not_verified` with reason
|
|
387
|
+
* `superseded`) and `review_split` (two reviewers disagreed and nobody settled it
|
|
388
|
+
* before the review deadline; the session is `not_verified` with reason `inconclusive`).
|
|
389
|
+
*/
|
|
390
|
+
| "superseded_by_retry" | "review_split"
|
|
391
|
+
/**
|
|
392
|
+
* Session outcome model §2.4: `review_timeout` (the review deadline passed, written on the
|
|
393
|
+
* reviewed step; the session is `not_verified` with reason `inconclusive`) and
|
|
394
|
+
* `inference_unavailable` (the model service could not run the check; the step's `result`
|
|
395
|
+
* is `unavailable`).
|
|
396
|
+
*/
|
|
397
|
+
| "review_timeout" | "inference_unavailable";
|
|
398
|
+
/**
|
|
399
|
+
* Session-level failure reasons: the session was stopped by a policy gate,
|
|
400
|
+
* not by a failed check. All are terminal (no retry on this session):
|
|
401
|
+
* - `location_not_allowed` / `anonymizer_blocked` (profile v2 step 2): the
|
|
402
|
+
* person's IP location is not allowed, or an anonymizer (VPN / proxy / Tor)
|
|
403
|
+
* was detected while the app blocks them;
|
|
404
|
+
* - `capture_tampered` (step 4): the device reported a tampered capture
|
|
405
|
+
* (virtual camera, hooking, emulator…) while the app blocks it;
|
|
406
|
+
* - `device_velocity_exceeded` (step 4): this device already verified too
|
|
407
|
+
* many different people while the app blocks it;
|
|
408
|
+
* - `device_cooldown` (step 4): this device had too many rejected sessions —
|
|
409
|
+
* {@link HostedSessionView.retryAfter} says when it may try again;
|
|
410
|
+
* - `platform_unsupported` (M-nfc): a chip read is required and this client
|
|
411
|
+
* can't read one (web); the session stays open for a native app;
|
|
412
|
+
* - `blocked_by_org`: one of the organization's blocks stopped the session.
|
|
413
|
+
*/
|
|
414
|
+
type SessionFailureReason = "location_not_allowed" | "anonymizer_blocked" | "capture_tampered" | "device_velocity_exceeded" | "device_cooldown" | "platform_unsupported" | "blocked_by_org" | "starter_credit_claimed";
|
|
415
|
+
/**
|
|
416
|
+
* Why the person has no camera (spec 2026-10-29 §3.4, 2026-10-30): `denied` when the camera permission was refused,
|
|
417
|
+
* `no_camera` when there is no usable camera (none found, an insecure page or a browser that cannot capture).
|
|
418
|
+
*/
|
|
419
|
+
type CameraUnavailableCause = "denied" | "no_camera";
|
|
420
|
+
/**
|
|
421
|
+
* A capture failure the page showed (`POST /hosted/capture-issue`, 2026-11-04): a diagnostic record on the session that
|
|
422
|
+
* never changes it, never bills and never counts as an attempt. No personal data, no free text: `name` is a thrown
|
|
423
|
+
* error's `name` (letters only, at most 40 characters).
|
|
424
|
+
*/
|
|
425
|
+
interface CaptureIssueReport {
|
|
426
|
+
/**
|
|
427
|
+
* The step whose camera failed (`portrait`: the portrait step's own camera, 2026-11-05), or `attestation`: the
|
|
428
|
+
* challenge frame produced no token (`kind: 'unavailable'`, the `ChallengeErrorCode` in `engineKind`).
|
|
429
|
+
*/
|
|
430
|
+
check: "liveness" | "document" | "portrait" | "attestation";
|
|
431
|
+
/** The public capture error kind shown, or `unavailable` (the SDK reason then rides in `engineKind`). */
|
|
432
|
+
kind: "permission" | "notfound" | "inuse" | "insecure" | "unsupported" | "generic" | "unavailable";
|
|
433
|
+
name?: string;
|
|
434
|
+
phase?: "preflight" | "acquiring" | "models" | "recording" | "keyframes" | "upload";
|
|
435
|
+
/** The engine kind before the public collapse, or the `unavailable` reason code (lower case, at most 32 characters). */
|
|
436
|
+
engineKind?: string;
|
|
437
|
+
/**
|
|
438
|
+
* Which capture attempt of the page failed (0 = the first); for `attestation`, which failed challenge of the page. The
|
|
439
|
+
* client reports one issue per attempt and cause.
|
|
440
|
+
*/
|
|
441
|
+
attempt?: number;
|
|
442
|
+
formFactor?: "phone" | "tablet" | "desktop";
|
|
443
|
+
/** `attestation`: Cloudflare's numeric error code, when the challenge reported one (incident 2026-11-13). */
|
|
444
|
+
detail?: string;
|
|
445
|
+
/** `attestation`: milliseconds from the challenge request to its failure (the frame client's own retry included). */
|
|
446
|
+
challengeMs?: number;
|
|
447
|
+
/** `attestation`: milliseconds from inserting the challenge frame to its `ready`; absent when it never answered. */
|
|
448
|
+
readyMs?: number;
|
|
449
|
+
/** `attestation`: the page runs in an app's WebView (a user-agent heuristic, as the device header's `inApp`). */
|
|
450
|
+
inApp?: boolean;
|
|
451
|
+
}
|
|
452
|
+
/**
|
|
453
|
+
* How the person proves their identity when the app makes the document
|
|
454
|
+
* optional for registry nationals (profile v2 step 3): type their national
|
|
455
|
+
* number (NNI) and skip the document, or photograph their document.
|
|
456
|
+
* `document_chip` is offered only to native clients with NFC (M-nfc).
|
|
457
|
+
* `national_eid` (SDK spec §3.2) signs in with the country's national eID
|
|
458
|
+
* (Houwiyeti in MR) instead of the camera path — see
|
|
459
|
+
* {@link MethodChoiceView.nationalEid}.
|
|
460
|
+
*/
|
|
461
|
+
type IdentityMethod = "national_number" | "document_photo" | "document_chip" | "national_eid";
|
|
462
|
+
/**
|
|
463
|
+
* The national eID provider a session offers (`MethodChoiceView.nationalEid`).
|
|
464
|
+
* `provider` is `{ISO2}.{provider}` (e.g. `MR.houwiyeti`); `providerName` is
|
|
465
|
+
* the display name ("Houwiyeti").
|
|
466
|
+
*/
|
|
467
|
+
interface NationalEidOption {
|
|
468
|
+
provider: string;
|
|
469
|
+
providerName: string;
|
|
470
|
+
/** ISO 3166-1 alpha-2 country of the provider. */
|
|
471
|
+
country: string;
|
|
472
|
+
/**
|
|
473
|
+
* What follows a passed eID (flow model 2026-10-23): `end` (the session ends,
|
|
474
|
+
* the default) or `continue` (the live photo follows). Absent on older APIs = `end`.
|
|
475
|
+
*/
|
|
476
|
+
afterPass?: EidAfterPass;
|
|
477
|
+
}
|
|
478
|
+
/** What follows a passed national eID (`nationalEid.afterPass`). */
|
|
479
|
+
type EidAfterPass = "end" | "continue";
|
|
480
|
+
/**
|
|
481
|
+
* The section a step belongs to (flow model 2026-10-23, SDK spec §3.7): Step 1
|
|
482
|
+
* `contact`, Step 2 `identity`, Step 3 `live_photo`; `documents` holds the proof
|
|
483
|
+
* of address (spec 2026-11-10). Open: a value this SDK does not know is kept as
|
|
484
|
+
* is, so a client still places the step.
|
|
485
|
+
*/
|
|
486
|
+
type StepSection = "contact" | "identity" | "live_photo" | "screening" | "documents" | "form" | (string & {});
|
|
487
|
+
/** A contact channel of a contact choice (`phone_otp` → `phone`, `email_otp` → `email`). */
|
|
488
|
+
type ContactChannel = "phone" | "email";
|
|
489
|
+
/**
|
|
490
|
+
* @deprecated Sekyro flows: the contact choice is `plan.choice` (kind `contact`,
|
|
491
|
+
* {@link PlanChoiceView}); the view no longer carries this shape.
|
|
492
|
+
*/
|
|
493
|
+
interface OtpChoiceView {
|
|
494
|
+
options: ContactChannel[];
|
|
495
|
+
selected: ContactChannel | null;
|
|
496
|
+
locked: boolean;
|
|
497
|
+
}
|
|
498
|
+
/** The flow version a session runs (`HostedSessionView.flow`). */
|
|
499
|
+
interface HostedFlowRef {
|
|
500
|
+
id: string;
|
|
501
|
+
slug: string;
|
|
502
|
+
version: number;
|
|
503
|
+
}
|
|
504
|
+
/** The kind of a choice node (Sekyro flows §7.4); a newer server's kind is kept as is. */
|
|
505
|
+
type PlanChoiceKind = "identity_method" | "contact" | "generic" | (string & {});
|
|
506
|
+
/** One option of a choice node, in the server's display order. */
|
|
507
|
+
interface PlanChoiceOption {
|
|
508
|
+
/** The option id sent back with {@link HostedClient.choose} (`document`, `registry`, `phone`, …). */
|
|
509
|
+
id: string;
|
|
510
|
+
/** The service of the option's lane (`document`, `nfc`, `population_registry`, `national_eid`, `phone_otp`, `email_otp`, …). */
|
|
511
|
+
service: string;
|
|
512
|
+
/** Unavailable options are omitted by the server; always `true` when listed. */
|
|
513
|
+
available: boolean;
|
|
514
|
+
/** `national_eid` options: the provider ("Verify with Houwiyeti"); absent or `null` otherwise and on older APIs. */
|
|
515
|
+
nationalEid?: NationalEidOption | null;
|
|
516
|
+
/**
|
|
517
|
+
* `phone_otp` options (flow UX refresh 2026-11-05): the step's channels in display order (informative: the contact
|
|
518
|
+
* choice stays Phone vs Email, the phone step offers the channels as equal buttons). Absent = SMS only or an older API.
|
|
519
|
+
*/
|
|
520
|
+
channels?: ("whatsapp" | "sms")[];
|
|
521
|
+
}
|
|
522
|
+
/** `plan.choice`: the choice the person makes now (or may still switch, while `locked` is false). */
|
|
523
|
+
interface PlanChoiceView {
|
|
524
|
+
nodeId: string;
|
|
525
|
+
kind: PlanChoiceKind;
|
|
526
|
+
/** The chosen option id, `null` before a pick. */
|
|
527
|
+
selected: string | null;
|
|
528
|
+
/** The choice can no longer change (a submission into the chosen lane, or the option settled). */
|
|
529
|
+
locked: boolean;
|
|
530
|
+
options: PlanChoiceOption[];
|
|
531
|
+
}
|
|
532
|
+
/** Submissions used on a step and its cap (remaining = `max - used`). */
|
|
533
|
+
interface PlanAttempts {
|
|
534
|
+
used: number;
|
|
535
|
+
max: number;
|
|
536
|
+
}
|
|
537
|
+
/**
|
|
538
|
+
* A step of the plan (a visited node or the current one, never an untaken lane):
|
|
539
|
+
* its node id, service and state plus today's per-type extras (`otp`, `emailOtp`,
|
|
540
|
+
* `eid`, `nfc`, `docCapture`, `nniFromDocument`, `reason`, `icao`, `requiresMobile`, …).
|
|
541
|
+
* A node with two checks yields two steps (`n_live` liveness, `n_live.icao` the ICAO portrait).
|
|
542
|
+
*/
|
|
543
|
+
interface PlanStepView extends Omit<HostedStepView, "checkType" | "attemptsRemaining" | "section"> {
|
|
544
|
+
/** The node id (`n_doc`), stable across views; `<node>.icao` for the ICAO portrait of a liveness node. */
|
|
545
|
+
id: string;
|
|
546
|
+
/** The catalog service of the node (`document`, `liveness`, `summary_confirm`, …). */
|
|
547
|
+
service: string;
|
|
548
|
+
/** The check this step submits (`doc_ocr`, `portrait_icao`, `identity_confirm`, …). */
|
|
549
|
+
checkType: CheckType | (string & {});
|
|
550
|
+
section: StepSection;
|
|
551
|
+
attempts: PlanAttempts;
|
|
552
|
+
/**
|
|
553
|
+
* Who acts on the step: `person` (a screen) or `server` (the backend runs it while the person waits). Sent by
|
|
554
|
+
* newer servers; a client renders an unknown `server` step as processing instead of asking for an update.
|
|
555
|
+
*/
|
|
556
|
+
interaction?: "person" | "server";
|
|
557
|
+
}
|
|
558
|
+
/** A segment of the progress bar (`plan.sections`): the sections still possible on any remaining path. */
|
|
559
|
+
interface PlanSectionView {
|
|
560
|
+
id: StepSection;
|
|
561
|
+
state: "done" | "current" | "upcoming";
|
|
562
|
+
}
|
|
563
|
+
/** `HostedSessionView.plan` (Sekyro flows §8.1). */
|
|
564
|
+
interface HostedPlanView {
|
|
565
|
+
/** A choice node id (`plan.choice.nodeId`) or a step id; `null` while nothing waits on the person. */
|
|
566
|
+
current: string | null;
|
|
567
|
+
/** Present while `current` is a choice (and, on newer servers, while its lane can still be switched). */
|
|
568
|
+
choice?: PlanChoiceView;
|
|
569
|
+
steps: PlanStepView[];
|
|
570
|
+
sections: PlanSectionView[];
|
|
571
|
+
}
|
|
572
|
+
/** Where the identity summary's data came from. */
|
|
573
|
+
type IdentitySummarySource = "registry" | "document" | "chip";
|
|
574
|
+
/**
|
|
575
|
+
* Step 2b summary and confirm (`HostedSessionView.identitySummary`): the
|
|
576
|
+
* identity data read so far, shown to the person before the live photo. Only
|
|
577
|
+
* on the session-token view and only while the confirmation is pending; masks
|
|
578
|
+
* keep the last 4 characters. Never log or store these values.
|
|
579
|
+
*/
|
|
580
|
+
interface IdentitySummaryView {
|
|
581
|
+
/**
|
|
582
|
+
* `full` (document / chip: the record and the photo) or `partial` (the
|
|
583
|
+
* registry from a typed number: the short name, the birth year, the number's
|
|
584
|
+
* last 4, no photo).
|
|
585
|
+
*/
|
|
586
|
+
kind: "full" | "partial" | (string & {});
|
|
587
|
+
source: IdentitySummarySource | (string & {});
|
|
588
|
+
/** The full name (`full`), or the short form "Mohamed S." (`partial`). */
|
|
589
|
+
fullName?: string;
|
|
590
|
+
/** `YYYY-MM-DD` (`full`). */
|
|
591
|
+
birthDate?: string;
|
|
592
|
+
/** `YYYY` (`partial`). */
|
|
593
|
+
birthYear?: string;
|
|
594
|
+
/** ISO 3166-1 alpha-2 (or alpha-3) nationality. */
|
|
595
|
+
nationality?: string;
|
|
596
|
+
documentType?: string;
|
|
597
|
+
documentNumberMasked?: string;
|
|
598
|
+
/** The bound ID number, masked (last 4). @deprecated Read `idNumberMasked` (the server sends both). */
|
|
599
|
+
nniMasked?: string;
|
|
600
|
+
/** The bound ID number, masked (last 4). Absent from servers before person data Task A9: read `nniMasked` then. */
|
|
601
|
+
idNumberMasked?: string;
|
|
602
|
+
/** `YYYY-MM-DD`. */
|
|
603
|
+
expiryDate?: string;
|
|
604
|
+
/** A portrait can be fetched ({@link HostedClient.identityPortrait}). */
|
|
605
|
+
portrait: {
|
|
606
|
+
available: boolean;
|
|
607
|
+
};
|
|
608
|
+
/** A retake is still possible (attempts left, not a `supplied` summary). */
|
|
609
|
+
retakeAvailable: boolean;
|
|
610
|
+
/** What a retake re-opens. */
|
|
611
|
+
retakeTarget?: "document" | "national_number" | (string & {});
|
|
612
|
+
}
|
|
613
|
+
/** The answer to the identity summary ({@link HostedClient.confirmIdentity}). */
|
|
614
|
+
type IdentityConfirmDecision = "confirm" | "retake";
|
|
615
|
+
/**
|
|
616
|
+
* The pending identity-method choice in the 0.1 vocabulary, read from
|
|
617
|
+
* `plan.choice` (`kind: identity_method`): `document` → `document_photo`,
|
|
618
|
+
* `nfc` → `document_chip`, `population_registry` → `national_number`,
|
|
619
|
+
* `national_eid` → `national_eid`. See {@link Verification.methodChoice}.
|
|
620
|
+
*/
|
|
621
|
+
interface MethodChoiceView {
|
|
622
|
+
/** The session offers the choice (the app's document mode is `optional`). */
|
|
623
|
+
available: boolean;
|
|
624
|
+
/** The chosen method, or `null` while the person has not chosen. */
|
|
625
|
+
selected: IdentityMethod | null;
|
|
626
|
+
/** The methods to offer, in display order (`national_eid` first when offered). */
|
|
627
|
+
options: IdentityMethod[];
|
|
628
|
+
/**
|
|
629
|
+
* The national eID provider behind the `national_eid` option ("Verify with
|
|
630
|
+
* Houwiyeti"). Absent when the option is not offered (and on older APIs).
|
|
631
|
+
*/
|
|
632
|
+
nationalEid?: NationalEidOption;
|
|
633
|
+
}
|
|
634
|
+
/**
|
|
635
|
+
* A document type the backend reads (kyc-docs-v2 vocabulary; `carte_identite` = identity card of any issuer).
|
|
636
|
+
* `drivers_license` (spec 2026-11-10 §6): a driving licence, two faces, no MRZ, offered only when the flow lists it
|
|
637
|
+
* (`"*"` never includes it).
|
|
638
|
+
*/
|
|
639
|
+
type AcceptedDocumentType = "carte_identite" | "passport" | "residence_permit" | "drivers_license";
|
|
640
|
+
/**
|
|
641
|
+
* Accepted document types per issuing country (profile v2 §5.3a): an issuer
|
|
642
|
+
* uses `byIssuer[iso2] ?? default`; `"*"` = every type.
|
|
643
|
+
*/
|
|
644
|
+
interface HostedAcceptedDocuments {
|
|
645
|
+
default: "*" | AcceptedDocumentType[];
|
|
646
|
+
byIssuer?: Record<string, AcceptedDocumentType[]>;
|
|
647
|
+
}
|
|
648
|
+
/**
|
|
649
|
+
* phone_otp DISPLAY-SAFE surface (Task 16). The backend stashes the OTP
|
|
650
|
+
* service `verifToken` on the check's persisted outputs (the doc_ocr partial
|
|
651
|
+
* mechanism), but that token is NEVER projected here — only the fields the
|
|
652
|
+
* hosted OTP step renders. `numberSource` (org-authored config) drives the
|
|
653
|
+
* send-phase UI (prefilled display vs entry); the rest appear ONLY once a send
|
|
654
|
+
* has parked the check (`sentToMasked` present ⇒ verify phase).
|
|
655
|
+
*/
|
|
656
|
+
interface HostedOtpView {
|
|
657
|
+
/**
|
|
658
|
+
* Per-step `config.numberSource` — drives the send-phase UI (prefilled
|
|
659
|
+
* display vs entry). Narrowed to the frontend contract; the backend field is
|
|
660
|
+
* `string` (dynamic config) but the projection only ever emits these three.
|
|
661
|
+
*/
|
|
662
|
+
numberSource?: "prefilled" | "user_entered" | "prefilled_or_entered";
|
|
663
|
+
/** Masked target the last send went to (e.g. `+222 ** ** 34 56`); absent pre-send. */
|
|
664
|
+
sentToMasked?: string;
|
|
665
|
+
/** Delivery channel of the last send. */
|
|
666
|
+
channel?: "sms" | "whatsapp";
|
|
667
|
+
/** ISO-8601 OTP expiry from the last send — drives the verify-phase countdown. */
|
|
668
|
+
expiresAt?: string;
|
|
669
|
+
/**
|
|
670
|
+
* Profile v2 §4.6.4: the channels the person may choose from, in display
|
|
671
|
+
* order (WhatsApp first; a channel the org or app turned off is absent).
|
|
672
|
+
* Absent on a session created before channel choice (no picker; SMS).
|
|
673
|
+
*/
|
|
674
|
+
channels?: ("whatsapp" | "sms")[];
|
|
675
|
+
/**
|
|
676
|
+
* ISO-8601 end of the server-side resend cooldown (after a send; 30 s since the flow UX refresh 2026-11-05). It
|
|
677
|
+
* holds a resend to the same number only: a changed number is sent at once.
|
|
678
|
+
*/
|
|
679
|
+
resendAvailableAt?: string;
|
|
680
|
+
/**
|
|
681
|
+
* Flow UX refresh 2026-11-05: the code goes to the number the partner supplied: show `otp.prefilledNotice` instead
|
|
682
|
+
* of the number field, and no "Change number". Absent otherwise.
|
|
683
|
+
*/
|
|
684
|
+
prefilled?: true;
|
|
685
|
+
}
|
|
686
|
+
/**
|
|
687
|
+
* email_otp DISPLAY-SAFE surface (Plan 8, profile v2 §4.6.5): never the
|
|
688
|
+
* provider handle, never the address (only its mask).
|
|
689
|
+
*/
|
|
690
|
+
interface HostedEmailOtpView {
|
|
691
|
+
/** Where the address comes from; drives the send-phase UI (notice vs entry). */
|
|
692
|
+
emailSource?: "prefilled" | "user_entered" | "prefilled_or_entered";
|
|
693
|
+
/** Masked target of the last send (e.g. `a•••@e•••.com`); absent pre-send. */
|
|
694
|
+
sentToMasked?: string;
|
|
695
|
+
/** ISO-8601 code expiry from the last send. */
|
|
696
|
+
expiresAt?: string;
|
|
697
|
+
/** ISO-8601 end of the server-side resend cooldown (after a send; holds a resend to the same address only). */
|
|
698
|
+
resendAvailableAt?: string;
|
|
699
|
+
/** Flow UX refresh 2026-11-05: the code goes to the address the partner supplied (`emailOtp.prefilledNotice`). */
|
|
700
|
+
prefilled?: true;
|
|
701
|
+
}
|
|
702
|
+
/**
|
|
703
|
+
* portrait_icao reasons (SDK spec §4.9, ID mode). The first failing ICAO
|
|
704
|
+
* criterion; every one is retryable (re-run only the ICAO gate).
|
|
705
|
+
* `media_unreadable` (no report) is shared with liveness.
|
|
706
|
+
*/
|
|
707
|
+
type PortraitIcaoReason = "icao_pose" | "icao_eyes" | "icao_mouth" | "icao_occlusion" | "icao_lighting" | "icao_background" | "icao_resolution" | "portrait_not_from_liveness" | "portrait_morph_suspected" | "portrait_reference_mismatch" | "portrait_declined_fix" | "portrait_fix_review" | "capture_front_camera";
|
|
708
|
+
/** One ICAO criterion of the server's portrait report (SDK spec §4.9). */
|
|
709
|
+
type IcaoCriterion = "pose" | "eyes" | "mouth" | "occlusion" | "glare" | "lighting" | "background" | "resolution";
|
|
710
|
+
/** The ICAO policy of a session's selfie (spec 2026-10-24 selfie ICAO policy §10). */
|
|
711
|
+
interface HostedIcaoPolicy {
|
|
712
|
+
/** `reject`: the gate blocks and the server asks for retakes; `alert`: coaching only, never blocking. */
|
|
713
|
+
policy: "reject" | "alert";
|
|
714
|
+
/** The threshold set: `id_document` (ID photo, uniform background) or `selfie` (no background rule). */
|
|
715
|
+
profile: "id_document" | "selfie";
|
|
716
|
+
}
|
|
717
|
+
/** `HostedSessionView.portrait`. */
|
|
718
|
+
type HostedPortraitView = NonNullable<HostedSessionView["portrait"]>;
|
|
719
|
+
/**
|
|
720
|
+
* Where the photo of the ID document step or the portrait step may come from (2026-11-05): `camera` (the camera
|
|
721
|
+
* screen; an upload only once the server offers it, after the camera could not open), `upload` (the upload screen at
|
|
722
|
+
* once) or `choice` (the person picks "Take a photo" or "Upload a photo", unless they already did for this step).
|
|
723
|
+
*/
|
|
724
|
+
type PhotoSource = "camera" | "upload" | "choice";
|
|
725
|
+
/** Where a submitted photo came from (2026-11-05): the camera, or a photo picked from the device. Also the person's pick under `choice`. */
|
|
726
|
+
type PhotoSourcePick = "camera" | "upload";
|
|
727
|
+
/**
|
|
728
|
+
* The delivered photo's format (design 2026-11-04 §6.2): `icao_9303` (the 480×640 token image), `photo_35x45_300dpi`
|
|
729
|
+
* or `square_600`.
|
|
730
|
+
*/
|
|
731
|
+
type PortraitOutputFormat = "icao_9303" | "photo_35x45_300dpi" | "square_600";
|
|
732
|
+
/**
|
|
733
|
+
* A fix the server applied to a portrait (design 2026-11-04 §6.4 step 2): geometry (`crop`, `scale`, `straighten`)
|
|
734
|
+
* for every output, plus `background`, `exposure` and `white_balance` for the photo formats other than `icao_9303`.
|
|
735
|
+
* The face itself is never changed. A newer server may name others: show the names it sends.
|
|
736
|
+
*/
|
|
737
|
+
type PortraitFix = "crop" | "scale" | "straighten" | "background" | "exposure" | "white_balance";
|
|
738
|
+
/**
|
|
739
|
+
* `HostedSessionView.portrait.pendingFix` (design 2026-11-04 §6.4 step 4): the server adjusted the photo and waits for
|
|
740
|
+
* the person to accept it (`fixReview: confirm`). Both URLs are short-lived presigned GETs (until `expiresAt`); `fixes`
|
|
741
|
+
* lists what was changed, in the server's words ({@link PortraitFix}).
|
|
742
|
+
*/
|
|
743
|
+
interface HostedPortraitPendingFix {
|
|
744
|
+
originalUrl: string;
|
|
745
|
+
fixedUrl: string;
|
|
746
|
+
fixes: string[];
|
|
747
|
+
expiresAt: string;
|
|
748
|
+
}
|
|
749
|
+
/** One row of the portrait_icao report: the server's measurement — coaching only. */
|
|
750
|
+
interface IcaoReportEntry {
|
|
751
|
+
criterion: IcaoCriterion;
|
|
752
|
+
value: number | null;
|
|
753
|
+
threshold: number | string | null;
|
|
754
|
+
pass: boolean;
|
|
755
|
+
}
|
|
756
|
+
/**
|
|
757
|
+
* eid_auth DISPLAY-SAFE surface (SDK spec §3.2): never the identifier, never
|
|
758
|
+
* the code. `awaiting` drives the screen: `identifier` (type the national
|
|
759
|
+
* number, unless `identifierBound`) → `code` (type the code shown in the
|
|
760
|
+
* provider's app).
|
|
761
|
+
*/
|
|
762
|
+
interface HostedEidView {
|
|
763
|
+
/** `{ISO2}.{provider}`, e.g. `MR.houwiyeti`. */
|
|
764
|
+
provider: string;
|
|
765
|
+
/** Display name, e.g. "Houwiyeti". */
|
|
766
|
+
providerName: string;
|
|
767
|
+
/** ISO 3166-1 alpha-2 country of the provider. */
|
|
768
|
+
country: string;
|
|
769
|
+
/** `app_code`: the provider's app shows a code the person types here (the only challenge today). */
|
|
770
|
+
challenge: "app_code";
|
|
771
|
+
awaiting: "identifier" | "code";
|
|
772
|
+
/** The session is bound to the national number — `start` sends no identifier. */
|
|
773
|
+
identifierBound: boolean;
|
|
774
|
+
/** ISO-8601 expiry of the current code. */
|
|
775
|
+
expiresAt?: string;
|
|
776
|
+
/** ISO-8601 time from which a new code may be asked for. */
|
|
777
|
+
resendAvailableAt?: string;
|
|
778
|
+
/** New codes the person may still ask for in this session. */
|
|
779
|
+
resendsRemaining?: number;
|
|
780
|
+
/** Wrong codes left before `eid_locked`. */
|
|
781
|
+
codeAttemptsRemaining?: number;
|
|
782
|
+
/** What follows a pass (flow model 2026-10-23); absent = `end`. */
|
|
783
|
+
afterPass?: EidAfterPass;
|
|
784
|
+
}
|
|
785
|
+
/** `nfc_chip` step hints (M-nfc). `chipHint` is UI copy only, never a gate. */
|
|
786
|
+
interface NfcStepView {
|
|
787
|
+
mode: "preferred" | "mandatory";
|
|
788
|
+
access: ("PACE" | "BAC")[];
|
|
789
|
+
optionalDataGroups: ("DG11" | "DG12" | "DG13")[];
|
|
790
|
+
chipHint: {
|
|
791
|
+
default: Record<string, true | "unknown">;
|
|
792
|
+
byIssuer: Record<string, Record<string, true | "unknown">>;
|
|
793
|
+
};
|
|
794
|
+
/**
|
|
795
|
+
* Sekyro flows §7.7: where the chip key's MRZ comes from — `capture` (an
|
|
796
|
+
* MRZ-only scan before the chip read) or `document` (the earlier document step).
|
|
797
|
+
*/
|
|
798
|
+
mrz?: {
|
|
799
|
+
source: "capture" | "document" | (string & {});
|
|
800
|
+
};
|
|
801
|
+
}
|
|
802
|
+
/**
|
|
803
|
+
* Liveness v7 §5.2: the retake hint's closed set (service `pipeline/retake_hint.py`, backend
|
|
804
|
+
* provenance picklist, copy keys `hints.*`): `appearance` (pad, deepfake, temporal signals),
|
|
805
|
+
* `motion` (no parallax or a high motion residual), `lighting` (low face luminance),
|
|
806
|
+
* `framing` (a small or clipped face box).
|
|
807
|
+
*/
|
|
808
|
+
type RetakeHint = "appearance" | "motion" | "lighting" | "framing";
|
|
809
|
+
/**
|
|
810
|
+
* Per-check projection in a {@link HostedSessionView} — the spec'd hosted step
|
|
811
|
+
* shape. NEVER carries `calibratedScore` or the raw check `outputs`; the only
|
|
812
|
+
* output-derived data is the phone_otp `HostedOtpView` display subset
|
|
813
|
+
* (masked number/channel/expiry — never the verifToken).
|
|
814
|
+
*/
|
|
815
|
+
interface HostedStepView {
|
|
816
|
+
checkType: CheckType;
|
|
817
|
+
state: CheckState;
|
|
818
|
+
/** Frozen-taxonomy reason code explaining a `failed`/`review` state. */
|
|
819
|
+
reason?: CheckReason;
|
|
820
|
+
/** What the last counted attempt said ({@link StepResult}); absent before the first one. */
|
|
821
|
+
result?: StepResult;
|
|
822
|
+
/**
|
|
823
|
+
* Liveness v7 §5.2: what to change for the next capture, on a liveness step parked at
|
|
824
|
+
* `input_required` (the signal that weighed most in the inconclusive score). Absent on older
|
|
825
|
+
* APIs, on decisive results and on the other checks: then the reason's generic copy applies.
|
|
826
|
+
*/
|
|
827
|
+
retakeHint?: RetakeHint;
|
|
828
|
+
/**
|
|
829
|
+
* Spec 2026-10-27: a Sandbox check answered by simulation (no provider or
|
|
830
|
+
* model ran). Absent on Live, on real Sandbox checks and on older APIs.
|
|
831
|
+
*/
|
|
832
|
+
simulated?: boolean;
|
|
833
|
+
/**
|
|
834
|
+
* Submissions the page may still make for this check (`max(0, cap - attempts)`).
|
|
835
|
+
* Meaningful only while the check is executable — a finalized check may still
|
|
836
|
+
* report more than 0, but re-submitting it 409s regardless.
|
|
837
|
+
*/
|
|
838
|
+
attemptsRemaining: number;
|
|
839
|
+
/** doc_ocr only: sides already accepted into the partial accumulator (['recto'] or ['verso']). */
|
|
840
|
+
acceptedSides?: ("recto" | "verso")[];
|
|
841
|
+
/** phone_otp only: the display-safe OTP send/config surface (never the verifToken). */
|
|
842
|
+
otp?: HostedOtpView;
|
|
843
|
+
/** email_otp only: the display-safe email send surface (never the handle or the address). */
|
|
844
|
+
emailOtp?: HostedEmailOtpView;
|
|
845
|
+
/** Counted attempts and the cap (`used >= max`: no try is left). */
|
|
846
|
+
attempts?: PlanAttempts;
|
|
847
|
+
/**
|
|
848
|
+
* population_registry only: the session is not bound to an NNI, but the
|
|
849
|
+
* document step already read a valid one — the page submits the registry
|
|
850
|
+
* check with an EMPTY input (no NNI field) and the backend uses the
|
|
851
|
+
* document's number. Absent on older APIs.
|
|
852
|
+
* @deprecated Read `idNumberFromDocument` (the server sends both).
|
|
853
|
+
*/
|
|
854
|
+
nniFromDocument?: boolean;
|
|
855
|
+
/**
|
|
856
|
+
* population_registry only: the twin of `nniFromDocument` (person data spec §5.6),
|
|
857
|
+
* both present or both absent. Absent from servers before person data Task A9.
|
|
858
|
+
*/
|
|
859
|
+
idNumberFromDocument?: boolean;
|
|
860
|
+
/**
|
|
861
|
+
* phone_otp only (person data spec Q16, Task A9): the countries the number may be
|
|
862
|
+
* from, ISO alpha-2, the first the default of the country picker. Absent from an
|
|
863
|
+
* older server: the person types a full international number.
|
|
864
|
+
*/
|
|
865
|
+
phoneCountries?: string[];
|
|
866
|
+
/**
|
|
867
|
+
* phone_otp only (phone rules spec 2026-11-02 §2.1): one rule per `phoneCountries` entry, same order. Absent
|
|
868
|
+
* from an older server: the field then blocks nothing and groups nothing.
|
|
869
|
+
*/
|
|
870
|
+
phoneRules?: PhoneCountryRule[];
|
|
871
|
+
/** phone_otp only (phone rules spec §2.1): numbers from other countries are accepted, through a free international field. */
|
|
872
|
+
phoneInternational?: true;
|
|
873
|
+
/**
|
|
874
|
+
* Spec 2026-11-06 §3.1: the step's camera runs on a phone only, in every decision mode. Set on `liveness` and
|
|
875
|
+
* `face_match`, and on `doc_ocr` / `portrait_icao` whose photo source is `camera` or `choice` (under `choice` the
|
|
876
|
+
* upload stays on the desktop). A desktop page hands the camera over to a phone instead of opening the webcam; a
|
|
877
|
+
* camera capture from a desktop answers `409 mobile_required`. Absent on `upload` steps and steps without a camera.
|
|
878
|
+
*/
|
|
879
|
+
requiresMobile?: boolean;
|
|
880
|
+
/**
|
|
881
|
+
* Native-only capture (spec 2026-11-15): this camera step runs in a native app only (the partner's app or the
|
|
882
|
+
* Sekyro AI app). A browser shows the way there; a submission from it answers `409 native_app_required`.
|
|
883
|
+
*/
|
|
884
|
+
requiresNativeApp?: boolean;
|
|
885
|
+
/** nfc_chip only (M-nfc). */
|
|
886
|
+
nfc?: NfcStepView;
|
|
887
|
+
/** portrait_icao only (SDK spec §4.9): the last attempt's per-criterion report. */
|
|
888
|
+
icao?: {
|
|
889
|
+
report: IcaoReportEntry[];
|
|
890
|
+
};
|
|
891
|
+
/** eid_auth only (SDK spec §3.2): the display-safe eID surface. */
|
|
892
|
+
eid?: HostedEidView;
|
|
893
|
+
/**
|
|
894
|
+
* The section of the flow this step belongs to (flow model 2026-10-23).
|
|
895
|
+
* Absent on older APIs (derive it from the check type).
|
|
896
|
+
*/
|
|
897
|
+
section?: StepSection;
|
|
898
|
+
/**
|
|
899
|
+
* doc_ocr only, on an open step: the client reads the chip next, so the MRZ is
|
|
900
|
+
* read on device for the chip key (`mrz_for_chip`). Native NFC clients only.
|
|
901
|
+
*/
|
|
902
|
+
docCapture?: {
|
|
903
|
+
mode: "mrz_for_chip" | (string & {});
|
|
904
|
+
};
|
|
905
|
+
/**
|
|
906
|
+
* form only (spec 2026-11-14 §14): the questions of the open Form step in the language chosen for the person
|
|
907
|
+
* (§8), and the prefill (§10). Absent before the session token is presented and once the step is submitted.
|
|
908
|
+
*/
|
|
909
|
+
form?: HostedFormView;
|
|
910
|
+
}
|
|
911
|
+
/** A hosted language of a Form step's own text (spec 2026-11-14 §8). */
|
|
912
|
+
type FormLocale = "ar" | "fr" | "en" | "es" | "pt" | "de";
|
|
913
|
+
/** A ready-made Form field (spec 2026-11-14 §5): label, input, help and errors are Sekyro's, in the person's language. */
|
|
914
|
+
type FormFieldName = "full_name" | "birth_date" | "email" | "phone" | "address" | "country" | "occupation";
|
|
915
|
+
/** A custom Form question type (spec 2026-11-14 §5). */
|
|
916
|
+
type FormQuestionType = "short_text" | "long_text" | "single_choice" | "multiple_choice" | "yes_no" | "date" | "number";
|
|
917
|
+
/**
|
|
918
|
+
* The open Form step (`plan.steps[].form`, spec 2026-11-14 §14): one screen, questions in the client's order, then
|
|
919
|
+
* the consents. Every client text is already in `locale`; render it with that `lang` (and its direction), whatever the
|
|
920
|
+
* page language. Sekyro's own text (ready-made labels, buttons, errors) stays in the page language.
|
|
921
|
+
*/
|
|
922
|
+
interface HostedFormView {
|
|
923
|
+
/** The language of the client's text (§8: the person's language when complete, else the default, else the source). */
|
|
924
|
+
locale: FormLocale | (string & {});
|
|
925
|
+
title?: string;
|
|
926
|
+
intro?: string;
|
|
927
|
+
questions: FormQuestionView[];
|
|
928
|
+
consents: FormConsentView[];
|
|
929
|
+
/** Prefilled answers by question id (§10); the person can change every one. Consents are never prefilled. */
|
|
930
|
+
prefill?: Record<string, FormAnswerValue>;
|
|
931
|
+
}
|
|
932
|
+
/** A question of the Form step: a ready-made field or a custom question. */
|
|
933
|
+
type FormQuestionView = FormFieldQuestionView | FormCustomQuestionView;
|
|
934
|
+
/** A ready-made field (`id` is the field name). */
|
|
935
|
+
interface FormFieldQuestionView {
|
|
936
|
+
kind: "field";
|
|
937
|
+
id: FormFieldName | (string & {});
|
|
938
|
+
field: FormFieldName | (string & {});
|
|
939
|
+
required: boolean;
|
|
940
|
+
}
|
|
941
|
+
/** A custom question, its text in the view's `locale`. */
|
|
942
|
+
interface FormCustomQuestionView {
|
|
943
|
+
kind: "custom";
|
|
944
|
+
id: string;
|
|
945
|
+
type: FormQuestionType | (string & {});
|
|
946
|
+
required: boolean;
|
|
947
|
+
label: string;
|
|
948
|
+
help?: string;
|
|
949
|
+
/** single_choice and multiple_choice: 2 to 12 choices, in order. */
|
|
950
|
+
choices?: FormChoiceView[];
|
|
951
|
+
/** date: `min` / `max` (`YYYY-MM-DD`) or `period`; number: `min` / `max` / `integer`. */
|
|
952
|
+
options?: FormQuestionOptions;
|
|
953
|
+
}
|
|
954
|
+
interface FormChoiceView {
|
|
955
|
+
value: string;
|
|
956
|
+
label: string;
|
|
957
|
+
}
|
|
958
|
+
/** The bounds of a date or number question. */
|
|
959
|
+
interface FormQuestionOptions {
|
|
960
|
+
min?: string | number;
|
|
961
|
+
max?: string | number;
|
|
962
|
+
period?: "past" | "future";
|
|
963
|
+
integer?: boolean;
|
|
964
|
+
}
|
|
965
|
+
/** A consent checkbox of the client's (spec 2026-11-14 §5); `required` ones must be ticked to continue. */
|
|
966
|
+
interface FormConsentView {
|
|
967
|
+
id: string;
|
|
968
|
+
required: boolean;
|
|
969
|
+
text: string;
|
|
970
|
+
link?: {
|
|
971
|
+
url: string;
|
|
972
|
+
label: string;
|
|
973
|
+
};
|
|
974
|
+
}
|
|
975
|
+
/** The address answer (the shape of the person address: country, city, 1 to 4 lines, postcode). */
|
|
976
|
+
interface FormAddressValue {
|
|
977
|
+
/** ISO 3166-1 alpha-2. */
|
|
978
|
+
country: string;
|
|
979
|
+
city: string;
|
|
980
|
+
lines: string[];
|
|
981
|
+
postcode?: string;
|
|
982
|
+
}
|
|
983
|
+
/**
|
|
984
|
+
* One answer: text, a choice value, a list of choice values, a boolean (yes / no), `YYYY-MM-DD`, a number, E.164 (phone),
|
|
985
|
+
* ISO alpha-2 (country) or an address.
|
|
986
|
+
*/
|
|
987
|
+
type FormAnswerValue = string | string[] | boolean | number | FormAddressValue;
|
|
988
|
+
/**
|
|
989
|
+
* `form` executor input (spec 2026-11-14 §14): answers by question id (an optional question left empty is left out)
|
|
990
|
+
* and every consent by id (`true` = ticked). A refused submit answers 422 `form_answers_invalid` with one
|
|
991
|
+
* `details.errors[]` entry per question id (`{ id, code }`, the server's code; the verification maps it to a
|
|
992
|
+
* {@link FormIssueCode}); it does not use an attempt.
|
|
993
|
+
*/
|
|
994
|
+
interface FormInput {
|
|
995
|
+
answers: Record<string, FormAnswerValue>;
|
|
996
|
+
consents: Record<string, boolean>;
|
|
997
|
+
}
|
|
998
|
+
/**
|
|
999
|
+
* Why an answer was refused (the `code` of a `form_answers_invalid` issue). The client checks the same rules before
|
|
1000
|
+
* sending; `card_number` comes only from the server (a Luhn-valid card number typed into a text answer, §17).
|
|
1001
|
+
*/
|
|
1002
|
+
type FormIssueCode = "required" | "too_long" | "too_short" | "email_invalid" | "phone_invalid" | "date_invalid" | "date_not_past" | "date_not_future" | "date_too_early" | "date_too_late" | "number_invalid" | "number_not_integer" | "number_decimals" | "number_too_small" | "number_too_large" | "choice_invalid" | "address_invalid" | "card_number" | "consent_required";
|
|
1003
|
+
/** A locale the Sekyro AI-hosted voice clips are recorded in. */
|
|
1004
|
+
type HostedVoiceLocale = "ar" | "fr" | "en";
|
|
1005
|
+
/**
|
|
1006
|
+
* The session's Sekyro AI-hosted voice-guidance clips (the active clip set).
|
|
1007
|
+
*
|
|
1008
|
+
* `clips[locale]` maps a voice key (`fcv3.*`, the `@sekyro/react` voice-key
|
|
1009
|
+
* namespace) to an ABSOLUTE URL on the Sekyro AI assets host
|
|
1010
|
+
* (`https://assets.sekyro.ai/voice/<setId>/<locale>/<name>.mp3`). URLs are immutable per `setId`. A locale or key
|
|
1011
|
+
* may be missing — the player falls back to the device voice for it.
|
|
1012
|
+
*
|
|
1013
|
+
* A page with a Content-Security-Policy must allow the assets origin in
|
|
1014
|
+
* `media-src` for the clips to play (see the partner web-SDK guide, CSP note).
|
|
1015
|
+
*/
|
|
1016
|
+
interface HostedVoiceView {
|
|
1017
|
+
/** Identifier of the active clip set (part of every clip URL). */
|
|
1018
|
+
setId: string;
|
|
1019
|
+
/** Per-locale map of voice key (`fcv3.*`) → absolute clip URL. */
|
|
1020
|
+
clips: {
|
|
1021
|
+
readonly [L in HostedVoiceLocale]?: Readonly<Record<string, string>>;
|
|
1022
|
+
};
|
|
1023
|
+
}
|
|
1024
|
+
/**
|
|
1025
|
+
* A branding colour key (each value is `#rrggbb`).
|
|
1026
|
+
*
|
|
1027
|
+
* Status colours (`danger`, `success`, `warning`) are no longer part of partner
|
|
1028
|
+
* branding: they are standard on every partner page since 0.1.0-rc.15 and
|
|
1029
|
+
* follow the partner surface automatically.
|
|
1030
|
+
*/
|
|
1031
|
+
type HostedBrandingColorKey = "brand" | "brandFg" | "bg" | "surface" | "fg" | "fgMuted";
|
|
1032
|
+
/**
|
|
1033
|
+
* The org / app branding of a session (`HostedSessionView.branding`): only the
|
|
1034
|
+
* fields set in the dashboard, merged per field (app over org). A field the
|
|
1035
|
+
* org and app left unset is ABSENT — keep your default for it; the whole
|
|
1036
|
+
* object is absent when nothing is set. `logoUrl` is a short-lived signed URL
|
|
1037
|
+
* (15 minutes).
|
|
1038
|
+
*/
|
|
1039
|
+
interface HostedBranding {
|
|
1040
|
+
/** Signed URL of the logo (PNG or sanitized SVG); absent when none is set. */
|
|
1041
|
+
logoUrl?: string;
|
|
1042
|
+
/** Colours as `#rrggbb`. */
|
|
1043
|
+
colors?: Partial<Record<HostedBrandingColorKey, string>>;
|
|
1044
|
+
/** Corner radius step. */
|
|
1045
|
+
radius?: "none" | "sm" | "md" | "lg" | "full";
|
|
1046
|
+
/** Font choice (system fallbacks when the font is not installed). */
|
|
1047
|
+
fontFamily?: "system" | "inter" | "ibm-plex-sans-arabic" | "noto-sans-arabic" | "roboto";
|
|
1048
|
+
/**
|
|
1049
|
+
* Spec 2026-10-29 D16: the org hides the "Verified by Sekyro AI" attribution (hosted frame and SDK footer).
|
|
1050
|
+
* Present (true) only then; absent on older APIs.
|
|
1051
|
+
*/
|
|
1052
|
+
hideAttribution?: boolean;
|
|
1053
|
+
}
|
|
1054
|
+
/**
|
|
1055
|
+
* Token-addressed hosted-page bootstrap (`GET /hosted/session`). A separate
|
|
1056
|
+
* shape from the partner `SessionView`: `sessionId` instead of `id`,
|
|
1057
|
+
* hosted step hints, the consent flag, and the org display name (may be `''`
|
|
1058
|
+
* when the org lookup degrades).
|
|
1059
|
+
*/
|
|
1060
|
+
/**
|
|
1061
|
+
* Server-delivered capture tuning (`HostedSessionView.capture`, SDK spec §3.5).
|
|
1062
|
+
* Coaching values only. `@sekyro/web` does not apply it yet (its built-in v3
|
|
1063
|
+
* values stay in force until the adopting minor release); native SDKs apply it
|
|
1064
|
+
* field by field over their bundled fallbacks and ignore unknown fields.
|
|
1065
|
+
*/
|
|
1066
|
+
interface HostedCaptureTuning {
|
|
1067
|
+
tuningVersion?: string;
|
|
1068
|
+
liveness?: HostedLivenessCaptureTuning;
|
|
1069
|
+
document?: Record<string, unknown>;
|
|
1070
|
+
/** SDK spec §5.4 ID mode: the strict ICAO gate's coaching limits (present with `portrait`). */
|
|
1071
|
+
icao?: IcaoCaptureTuning;
|
|
1072
|
+
/**
|
|
1073
|
+
* Step 3 one-capture live photo (flow model 2026-10-23): one camera session
|
|
1074
|
+
* records the clip AND a full-resolution still (long side at least
|
|
1075
|
+
* `still.minLongSidePx`, JPEG `still.jpegQuality`).
|
|
1076
|
+
*/
|
|
1077
|
+
livePhoto?: HostedLivePhotoTuning;
|
|
1078
|
+
/**
|
|
1079
|
+
* Who films the face, set in the flow (always present on current backends):
|
|
1080
|
+
* - `self` — the person films themselves: front camera only, no camera
|
|
1081
|
+
* choice, phone held upright;
|
|
1082
|
+
* - `assisted` — another person films the person: back camera only, phone
|
|
1083
|
+
* held upright.
|
|
1084
|
+
* `@sekyro/web` enforces it on a capture bound to the session; an absent
|
|
1085
|
+
* value falls back to {@link HostedCaptureTuning.cameraSwitch}, then `self`.
|
|
1086
|
+
*/
|
|
1087
|
+
mode?: CaptureMode;
|
|
1088
|
+
/**
|
|
1089
|
+
* Spec 2026-11-06 §3.4, under `mode: 'choice'` only: the latest mode a camera attempt of this session ran in
|
|
1090
|
+
* (`self` / `assisted`). Open the camera in it (a reloaded page), with the switch still offered. Absent before the
|
|
1091
|
+
* first attempt and on older servers.
|
|
1092
|
+
*/
|
|
1093
|
+
pick?: ResolvedCaptureMode;
|
|
1094
|
+
/**
|
|
1095
|
+
* @deprecated Mirror of `mode === 'assisted'`, kept for older clients. Read
|
|
1096
|
+
* {@link HostedCaptureTuning.mode}.
|
|
1097
|
+
*/
|
|
1098
|
+
cameraSwitch?: boolean;
|
|
1099
|
+
}
|
|
1100
|
+
/**
|
|
1101
|
+
* Who films the face (`HostedSessionView.capture.mode`, a flow setting):
|
|
1102
|
+
* `self` (the person, front camera), `assisted` (an agent, back camera) or
|
|
1103
|
+
* `choice` (the liveness camera opens in `self` and the person can switch to
|
|
1104
|
+
* `assisted` and back on the camera view; each attempt runs in one
|
|
1105
|
+
* {@link ResolvedCaptureMode}).
|
|
1106
|
+
*/
|
|
1107
|
+
type CaptureMode = "self" | "assisted" | "choice";
|
|
1108
|
+
/** The mode a camera runs in: the session's {@link CaptureMode}, or the person's pick under `choice`. */
|
|
1109
|
+
type ResolvedCaptureMode = "self" | "assisted";
|
|
1110
|
+
/** `capture.livePhoto` (flow model 2026-10-23, Step 3). */
|
|
1111
|
+
interface HostedLivePhotoTuning {
|
|
1112
|
+
oneCapture: boolean;
|
|
1113
|
+
still: {
|
|
1114
|
+
minLongSidePx: number;
|
|
1115
|
+
jpegQuality: number;
|
|
1116
|
+
};
|
|
1117
|
+
}
|
|
1118
|
+
/**
|
|
1119
|
+
* `capture.liveness`: the face gate's coaching values (open; web keeps its built-in v3 values) and, from liveness v7,
|
|
1120
|
+
* the screen-ramp challenge the web SDK renders while the clip records.
|
|
1121
|
+
*/
|
|
1122
|
+
interface HostedLivenessCaptureTuning {
|
|
1123
|
+
[field: string]: unknown;
|
|
1124
|
+
/**
|
|
1125
|
+
* Liveness v7 §4.4: the server-issued screen-ramp challenge of this session. Absent (older backends, assisted
|
|
1126
|
+
* sessions, the ramp switched off): no ramp is rendered and the submit carries no `screenRamp`.
|
|
1127
|
+
*/
|
|
1128
|
+
screenRamp?: ScreenRampChallenge;
|
|
1129
|
+
}
|
|
1130
|
+
/** A screen-ramp palette colour (ramp v2: four saturated colours). */
|
|
1131
|
+
type ScreenRampColour = 'magenta' | 'yellow' | 'green' | 'blue';
|
|
1132
|
+
/** What the screen-ramp layer shows: a palette colour, `'dark'` (black, the dark-gap arm) or `null` (cleared). */
|
|
1133
|
+
type ScreenRampPaint = ScreenRampColour | 'dark' | null;
|
|
1134
|
+
/**
|
|
1135
|
+
* The screen-ramp challenge issued per session (ramp v2; liveness v7 §4.4, §4.5 item 1): the client paints the whole
|
|
1136
|
+
* screen `colours[i]` from `onsetsMs[i]` on the clip's own timeline for `holdMs` (black for the rest of the slot when
|
|
1137
|
+
* that is shorter than the gap to the next onset), clears it at `endMs`, and records at least `clipMs`. The backend
|
|
1138
|
+
* issues three distinct colours in 650 ms slots after an 800 to 850 ms settle, and a 3.0 s clip. The
|
|
1139
|
+
* client renders exactly this and reports what it rendered ({@link ScreenRampReport}); the backend forwards the issued
|
|
1140
|
+
* challenge to the model service, which reads the order of the colours the face took.
|
|
1141
|
+
*/
|
|
1142
|
+
interface ScreenRampChallenge {
|
|
1143
|
+
/** Ties the report to the issued challenge (echoed in {@link ScreenRampReport.nonce}). */
|
|
1144
|
+
nonce: string;
|
|
1145
|
+
/** One to eight palette colours (the backend issues five). */
|
|
1146
|
+
colours: ScreenRampColour[];
|
|
1147
|
+
/** Ms on the clip timeline, strictly ascending, one per colour. */
|
|
1148
|
+
onsetsMs: number[];
|
|
1149
|
+
/** How long each colour shows from its onset (ms). */
|
|
1150
|
+
holdMs: number;
|
|
1151
|
+
/** The layer clears here (ms on the clip timeline). */
|
|
1152
|
+
endMs: number;
|
|
1153
|
+
/** The clip records at least this long (ms, at most 8,000). */
|
|
1154
|
+
clipMs: number;
|
|
1155
|
+
/** The palette the colours were drawn from (informational; the client renders `colours`). */
|
|
1156
|
+
palette: ScreenRampColour[];
|
|
1157
|
+
}
|
|
1158
|
+
/** One rendered colour change: `tMs` on the clip timeline (whole ms, ≥ 0). */
|
|
1159
|
+
interface ScreenRampRendered {
|
|
1160
|
+
tMs: number;
|
|
1161
|
+
colour: ScreenRampColour;
|
|
1162
|
+
}
|
|
1163
|
+
/** `LivenessCaptureInput.screenRamp`: what the SDK rendered against the issued {@link ScreenRampChallenge}. */
|
|
1164
|
+
interface ScreenRampReport {
|
|
1165
|
+
nonce: string;
|
|
1166
|
+
/** In render order, one per painted colour (never the dark gap), at most one per issued colour. */
|
|
1167
|
+
rendered: ScreenRampRendered[];
|
|
1168
|
+
}
|
|
1169
|
+
/**
|
|
1170
|
+
* `LivenessCaptureInput.provenance` (liveness v7 §4.5 item 2): how the web capture was made. Signals only, no media,
|
|
1171
|
+
* no raw device identifiers. The backend allowlists it into the capture metadata; the model service turns it into
|
|
1172
|
+
* the `virtual_camera | capture_tampered | replay_suspected` signals with its own thresholds and label list.
|
|
1173
|
+
*/
|
|
1174
|
+
interface CaptureProvenance {
|
|
1175
|
+
/** The selected video track's `getSettings()`; `deviceIdHash` is the first 16 hex of SHA-256(deviceId). */
|
|
1176
|
+
trackSettings: {
|
|
1177
|
+
facingMode?: 'user' | 'environment' | 'left' | 'right';
|
|
1178
|
+
frameRate?: number;
|
|
1179
|
+
width?: number;
|
|
1180
|
+
height?: number;
|
|
1181
|
+
deviceIdHash?: string;
|
|
1182
|
+
};
|
|
1183
|
+
/** `MediaStreamTrack.getCapabilities` exists on this browser (absent on Firefox; virtual stacks often lack it). */
|
|
1184
|
+
capabilitiesPresent: boolean;
|
|
1185
|
+
/**
|
|
1186
|
+
* The track label against the SDK's small list of virtual-camera products (`known_virtual`), the platform's own
|
|
1187
|
+
* camera naming (`platform`), or anything else, an empty label included (`unknown`).
|
|
1188
|
+
*/
|
|
1189
|
+
labelClass: 'known_virtual' | 'unknown' | 'platform';
|
|
1190
|
+
/**
|
|
1191
|
+
* `requestVideoFrameCallback` statistics over the recording: frames seen, mean and standard deviation of the
|
|
1192
|
+
* inter-frame gap (ms), and the mean `presentationTime - captureTime` (ms) when the browser reports `captureTime`
|
|
1193
|
+
* (null otherwise). All zero with `n: 0` when the browser has no `requestVideoFrameCallback`.
|
|
1194
|
+
*/
|
|
1195
|
+
rvfc: {
|
|
1196
|
+
n: number;
|
|
1197
|
+
meanGapMs: number;
|
|
1198
|
+
stdGapMs: number;
|
|
1199
|
+
captureLatencyMs: number | null;
|
|
1200
|
+
};
|
|
1201
|
+
/** `getUserMedia` and `MediaStreamTrack.prototype.getSettings` are still native code (not replaced by a page script). */
|
|
1202
|
+
prototypesIntact: boolean;
|
|
1203
|
+
/**
|
|
1204
|
+
* The engine ran this capture with a screen-ramp painter: a self capture handed the session's challenge with a
|
|
1205
|
+
* `ramp` listener bound. `false` for a host that never binds `ramp`, an assisted capture, a keyframe-only capture
|
|
1206
|
+
* or a session without a challenge. The backend keys `ramp_missing` on this flag, not on the SDK version: a
|
|
1207
|
+
* `true` capture without `screenRamp` is missing, a `false` one is a client without the ramp.
|
|
1208
|
+
*/
|
|
1209
|
+
rampPainter: boolean;
|
|
1210
|
+
}
|
|
1211
|
+
/**
|
|
1212
|
+
* {@link HostedCaptureTuning} with the native-only document fields typed. The wire shape is
|
|
1213
|
+
* the same; `HostedSessionView.capture` stays the open {@link HostedCaptureTuning} so existing
|
|
1214
|
+
* consumers keep compiling. Narrow it where the typed fields are read:
|
|
1215
|
+
* `const capture = view.capture as HostedNativeCaptureTuning | undefined`.
|
|
1216
|
+
*/
|
|
1217
|
+
interface HostedNativeCaptureTuning extends HostedCaptureTuning {
|
|
1218
|
+
document?: HostedDocumentCaptureTuning;
|
|
1219
|
+
}
|
|
1220
|
+
/**
|
|
1221
|
+
* `capture.document`. Only the native-only fields the SDKs share a name for are typed;
|
|
1222
|
+
* the rest (gate, aspect, upload, …) stay open. Web ignores the whole block.
|
|
1223
|
+
*/
|
|
1224
|
+
interface HostedDocumentCaptureTuning {
|
|
1225
|
+
[field: string]: unknown;
|
|
1226
|
+
/** Native document scan machine thresholds (web does not read them). */
|
|
1227
|
+
scan?: HostedDocumentScanTuning;
|
|
1228
|
+
/** Native on-device OCR tuning (web ignores it; SDK spec §5.2). */
|
|
1229
|
+
ocr?: HostedOcrTuning;
|
|
1230
|
+
}
|
|
1231
|
+
/** `capture.document.scan` — native scan thresholds; only the blur gate is typed here. */
|
|
1232
|
+
interface HostedDocumentScanTuning {
|
|
1233
|
+
[field: string]: unknown;
|
|
1234
|
+
/** Blur gate: a captured photo whose native sharpness is under this is refused and retaken. */
|
|
1235
|
+
blurRefuseSharpnessMax?: number;
|
|
1236
|
+
}
|
|
1237
|
+
/** `capture.document.ocr` — native on-device OCR tuning (web ignores it; SDK spec §5.2). */
|
|
1238
|
+
interface HostedOcrTuning {
|
|
1239
|
+
enabledOnline?: boolean;
|
|
1240
|
+
enabledOffline?: boolean;
|
|
1241
|
+
warmup?: boolean;
|
|
1242
|
+
maxDeviceLatencyMs?: number;
|
|
1243
|
+
deviceTimeoutMs?: number;
|
|
1244
|
+
minAvailMemoryMb?: number;
|
|
1245
|
+
minConfidenceForRetake?: number;
|
|
1246
|
+
minSegmentsForRetake?: number;
|
|
1247
|
+
submitGraceMs?: number;
|
|
1248
|
+
reportSampleRate?: number;
|
|
1249
|
+
readBudgetMs?: number;
|
|
1250
|
+
classifyBudgetMs?: number;
|
|
1251
|
+
deferArabicOnline?: boolean;
|
|
1252
|
+
detectorLimit?: number;
|
|
1253
|
+
detectorThreadsMax?: number;
|
|
1254
|
+
recognizerThreads?: number;
|
|
1255
|
+
recognitionWorkersMax?: number;
|
|
1256
|
+
linesInFlight?: number;
|
|
1257
|
+
widestLineFirst?: boolean;
|
|
1258
|
+
scriptRouting?: boolean;
|
|
1259
|
+
arabicColumnFirst?: boolean;
|
|
1260
|
+
confidentLatinScore?: number;
|
|
1261
|
+
minLatinLetters?: number;
|
|
1262
|
+
arabicColumnStart?: number;
|
|
1263
|
+
arabicOnlyScore?: number;
|
|
1264
|
+
portraitProbeLimit?: number;
|
|
1265
|
+
}
|
|
1266
|
+
/** Native device attestation parameters (`HostedSessionView.integrity`, SDK spec §6.7). Web ignores it. */
|
|
1267
|
+
interface HostedIntegrity {
|
|
1268
|
+
mode: "off" | "signal" | "enforce";
|
|
1269
|
+
android?: {
|
|
1270
|
+
cloudProjectNumber: number;
|
|
1271
|
+
};
|
|
1272
|
+
ios?: {
|
|
1273
|
+
appAttest: true;
|
|
1274
|
+
};
|
|
1275
|
+
}
|
|
1276
|
+
/** `HostedSessionView.challenge`: where the browser obtains its attestation token (spec 2026-11-10 §4.3). */
|
|
1277
|
+
interface HostedChallengeView {
|
|
1278
|
+
/** The challenge frame (`<hosted origin>/challenge`, always the platform host, never a custom domain). */
|
|
1279
|
+
url: string;
|
|
1280
|
+
/** The Turnstile site key the frame renders. */
|
|
1281
|
+
siteKey: string;
|
|
1282
|
+
}
|
|
1283
|
+
interface HostedSessionView {
|
|
1284
|
+
sessionId: string;
|
|
1285
|
+
status: SessionStatus;
|
|
1286
|
+
/** `not_verified` only: why ({@link SessionReason}). */
|
|
1287
|
+
reason?: SessionReason;
|
|
1288
|
+
/**
|
|
1289
|
+
* The detailed code behind `reason`, when one exists (`spoof_detected`, `match_inconclusive`,
|
|
1290
|
+
* `device_cooldown`, ...). Also a stop the page shows on a session that stays open:
|
|
1291
|
+
* `platform_unsupported` (a required chip read this client cannot do) and
|
|
1292
|
+
* `starter_credit_claimed` (an owner check of a person who already earned the credit).
|
|
1293
|
+
*/
|
|
1294
|
+
reasonCode?: string;
|
|
1295
|
+
/** Finished sessions: who or what closed it ({@link ClosedBy}). */
|
|
1296
|
+
closedBy?: ClosedBy;
|
|
1297
|
+
/** `not_verified` only: the step that decided it, when one did. */
|
|
1298
|
+
step?: SessionDecidingStep;
|
|
1299
|
+
/** ISO-8601 timestamp (Date on the server, string on the wire). */
|
|
1300
|
+
expiresAt: string;
|
|
1301
|
+
consentRecorded: boolean;
|
|
1302
|
+
orgName: string;
|
|
1303
|
+
/**
|
|
1304
|
+
* Website demo spec 2026-11-13 §4.5: present (`true`) on a website demo session whose `orgName`
|
|
1305
|
+
* is the visitor's own name. The hosted page shows "Demo by Sekyro AI" under it; SDK surfaces
|
|
1306
|
+
* ignore it.
|
|
1307
|
+
*/
|
|
1308
|
+
demo?: true;
|
|
1309
|
+
/**
|
|
1310
|
+
* The FIRST allowlisted web-SDK origin of the owning org (Task 12), or null
|
|
1311
|
+
* when none is registered. The hosted page posts the SDK popup postMessage
|
|
1312
|
+
* events (event name, sessionId and the level when known) to exactly this origin — never `'*'`.
|
|
1313
|
+
* The backend declares it required (`string | null`); optional here so
|
|
1314
|
+
* pre-Task-12 consumers/fixtures stay valid (additive field, always on the
|
|
1315
|
+
* wire from Task 12 onward).
|
|
1316
|
+
*/
|
|
1317
|
+
sdkOrigin?: string | null;
|
|
1318
|
+
/**
|
|
1319
|
+
* The Sekyro challenge frame the browser asks for an attestation token before it submits `liveness` (spec
|
|
1320
|
+
* 2026-11-10 §4.3): the platform's Turnstile widget runs inside a hidden frame at `url`, so the host page needs
|
|
1321
|
+
* only `frame-src <origin of url>`. On a Sandbox session `siteKey` is Cloudflare's always-passing test key, so the
|
|
1322
|
+
* same code runs in both environments. `null` only on a Live deployment without Turnstile: the SDK sends no token
|
|
1323
|
+
* and the server decides.
|
|
1324
|
+
*/
|
|
1325
|
+
challenge: HostedChallengeView | null;
|
|
1326
|
+
/**
|
|
1327
|
+
* A Sandbox (test) session: the hosted page marks it as a test session.
|
|
1328
|
+
* Optional: absent on an older backend.
|
|
1329
|
+
*/
|
|
1330
|
+
sandbox?: boolean;
|
|
1331
|
+
/** Spec 2026-10-27: this session enrolls a Sandbox tester (the hosted page shows the removal link at the end). */
|
|
1332
|
+
testerEnrollment?: boolean;
|
|
1333
|
+
/**
|
|
1334
|
+
* Spec 2026-11-09 §3.3: present only while the flow should offer "Run real checks as a tester" (a simulated Sandbox
|
|
1335
|
+
* session, nothing captured yet, gates left, and the organization has an active tester). `attemptsLeft`: gates left
|
|
1336
|
+
* on this session. Absent in Live and once a tester is recognised (the session then runs real checks).
|
|
1337
|
+
*/
|
|
1338
|
+
testerGate?: HostedTesterGateView;
|
|
1339
|
+
/**
|
|
1340
|
+
* The session was minted with a server-bound NNI (`POST /sessions`
|
|
1341
|
+
* `input.nni`, Plan A Task 2): `population_registry` is submitted with an
|
|
1342
|
+
* EMPTY input and the backend reads the sealed value. `false` means the
|
|
1343
|
+
* person must supply the NNI (hosted population form); the SDK never submits
|
|
1344
|
+
* the registry check on an unbound session. The VALUE is never exposed. The
|
|
1345
|
+
* backend declares it required; optional here so pre-Task-8 fixtures stay
|
|
1346
|
+
* valid (additive field, always on the wire from Task 8 onward).
|
|
1347
|
+
* Registry-scoped: an MR national ID number the registry can look up.
|
|
1348
|
+
*/
|
|
1349
|
+
nniBound?: boolean;
|
|
1350
|
+
/**
|
|
1351
|
+
* Person data spec §5.6: the generic name of `nniBound`, with the same meaning:
|
|
1352
|
+
* the session holds an ID number the registry step can look up, so the step is
|
|
1353
|
+
* submitted with an empty input. A bound passport or another country's number is
|
|
1354
|
+
* not registry-bound. Absent from servers before person data Task A9.
|
|
1355
|
+
*/
|
|
1356
|
+
idNumberBound?: boolean;
|
|
1357
|
+
/**
|
|
1358
|
+
* The Sekyro AI-hosted voice-guidance clips of this session, or `null` when no
|
|
1359
|
+
* clip set is active (the device voice is used). Optional: older APIs omit
|
|
1360
|
+
* the field — treat absent like `null`.
|
|
1361
|
+
*/
|
|
1362
|
+
voice?: HostedVoiceView | null;
|
|
1363
|
+
/**
|
|
1364
|
+
* The document types the person may pick, resolved for issuer `MR`,
|
|
1365
|
+
* `carte_identite`/`passport` only (older pickers). Absent on older APIs —
|
|
1366
|
+
* treat absent as both.
|
|
1367
|
+
*/
|
|
1368
|
+
acceptedDocumentTypes?: AcceptedDocumentType[];
|
|
1369
|
+
/**
|
|
1370
|
+
* Accepted document types per issuing country — drives the issuer-first
|
|
1371
|
+
* picker. Absent on older APIs (fall back to `acceptedDocumentTypes` for MR).
|
|
1372
|
+
*/
|
|
1373
|
+
acceptedDocuments?: HostedAcceptedDocuments;
|
|
1374
|
+
/**
|
|
1375
|
+
* The person's country as detected from the IP address the session started
|
|
1376
|
+
* from (ISO 3166-1 alpha-2). The document country picker lists it first when
|
|
1377
|
+
* the session accepts a document from it. Absent when unknown (and on older
|
|
1378
|
+
* APIs).
|
|
1379
|
+
*/
|
|
1380
|
+
detectedCountry?: string;
|
|
1381
|
+
/**
|
|
1382
|
+
* ISO-8601 time from which this device may verify again, set with
|
|
1383
|
+
* `reasonCode: 'device_cooldown'` (profile v2 step 4). Absent otherwise.
|
|
1384
|
+
*/
|
|
1385
|
+
retryAfter?: string;
|
|
1386
|
+
/**
|
|
1387
|
+
* What the session proved, once it is terminal (spec 2026-10-29 §3.2);
|
|
1388
|
+
* `null` while it runs. Absent on older APIs.
|
|
1389
|
+
*/
|
|
1390
|
+
level?: VerificationLevel | null;
|
|
1391
|
+
/** How the level was proved, once terminal; `null` while it runs. Absent on older APIs. */
|
|
1392
|
+
assurance?: VerificationAssurance | null;
|
|
1393
|
+
/**
|
|
1394
|
+
* A returning-user session (profile v2 step 5): the person verified before
|
|
1395
|
+
* and this session only confirms it is still them — liveness and a face
|
|
1396
|
+
* match against their stored photo. Hosts read it to say "Confirm it's
|
|
1397
|
+
* you". Absent on full sessions (and on older APIs).
|
|
1398
|
+
*/
|
|
1399
|
+
returning?: true;
|
|
1400
|
+
/**
|
|
1401
|
+
* The org / app branding (settings spec §5.1). Absent on older APIs — keep
|
|
1402
|
+
* the default theme. Map it with `brandingToTheme()` from `@sekyro/react`.
|
|
1403
|
+
*/
|
|
1404
|
+
branding?: HostedBranding;
|
|
1405
|
+
/** Capture coaching tuning (SDK spec §3.5). Absent on older APIs. */
|
|
1406
|
+
capture?: HostedCaptureTuning;
|
|
1407
|
+
/** Native device attestation parameters; absent for web-only apps and on older APIs. */
|
|
1408
|
+
integrity?: HostedIntegrity;
|
|
1409
|
+
/**
|
|
1410
|
+
* Native-only capture (spec 2026-11-15): present when the session's flow takes its photos in a native app only.
|
|
1411
|
+
* Its camera steps carry `requiresNativeApp`; a browser shows the way to the partner's app (and the Sekyro AI app
|
|
1412
|
+
* when `sekyroApp`) instead of opening the camera. Absent on flows that take photos on any device.
|
|
1413
|
+
*/
|
|
1414
|
+
nativeApp?: HostedNativeAppView;
|
|
1415
|
+
/**
|
|
1416
|
+
* SDK spec §3.5: present when the session runs the ICAO portrait step — the
|
|
1417
|
+
* client runs the ICAO gate (read it with `icaoPolicyOf`). `icao` is absent on
|
|
1418
|
+
* older servers, which send `{ purpose: "id_document" }` alone (= `reject`, `id_document`).
|
|
1419
|
+
*/
|
|
1420
|
+
portrait?: {
|
|
1421
|
+
purpose: "id_document";
|
|
1422
|
+
/** Present whenever a `portrait_icao` step runs (absent on older servers): `reject` / `id_document`. */
|
|
1423
|
+
icao?: HostedIcaoPolicy;
|
|
1424
|
+
/**
|
|
1425
|
+
* 2026-11-05: where the portrait step's photo may come from. Absent on older servers and on a portrait that
|
|
1426
|
+
* rides the liveness capture (= `camera`).
|
|
1427
|
+
*/
|
|
1428
|
+
source?: PhotoSource;
|
|
1429
|
+
/** The person's pick under `choice`, once made for this step (do not ask again: a retry). */
|
|
1430
|
+
sourcePick?: PhotoSourcePick;
|
|
1431
|
+
/**
|
|
1432
|
+
* An upload would be accepted now (`upload`, or `choice` without a camera pick; never on a camera step).
|
|
1433
|
+
* Absent on older servers (= `false`).
|
|
1434
|
+
*/
|
|
1435
|
+
uploadOffered?: boolean;
|
|
1436
|
+
/** The server adjusts a nearly compliant photo (crop, scale, straighten; more for the photo formats). */
|
|
1437
|
+
fixes?: boolean;
|
|
1438
|
+
/** `confirm`: the person accepts an adjusted photo before it is used ({@link HostedPortraitPendingFix}). */
|
|
1439
|
+
fixReview?: "confirm" | "silent";
|
|
1440
|
+
/** The delivered photo's format. */
|
|
1441
|
+
output?: PortraitOutputFormat;
|
|
1442
|
+
/** The adjusted photo waiting for the person's answer (`portrait_icao` with `{ fixReview: { accept } }`). */
|
|
1443
|
+
pendingFix?: HostedPortraitPendingFix;
|
|
1444
|
+
/**
|
|
1445
|
+
* Design 2026-11-04 §4, §6.3: the portrait step's own capture mode when it has its own screen (`self` /
|
|
1446
|
+
* `assisted`; under `choice` the person's pick once made, else `choice`: ask who takes the photo). Absent = the
|
|
1447
|
+
* still rides the liveness capture (one capture), whatever `capture.livePhoto.oneCapture` says.
|
|
1448
|
+
*/
|
|
1449
|
+
captureMode?: CaptureMode;
|
|
1450
|
+
/**
|
|
1451
|
+
* Design 2026-11-04 §6.6: a returning person's earlier photo is waiting to be bound to today's liveness: submit
|
|
1452
|
+
* `portrait_icao` with `{}` (no photo). A dropped reuse clears it and the step asks for a photo.
|
|
1453
|
+
*/
|
|
1454
|
+
reuse?: {
|
|
1455
|
+
pending: true;
|
|
1456
|
+
};
|
|
1457
|
+
} | {
|
|
1458
|
+
/** A verification selfie checked against the ICAO selfie rules (selfie ICAO policy). */
|
|
1459
|
+
purpose: "verification";
|
|
1460
|
+
icao: HostedIcaoPolicy;
|
|
1461
|
+
/** As on `id_document` (design 2026-11-04 §6.2): newer servers send the step's settings with either purpose. */
|
|
1462
|
+
source?: PhotoSource;
|
|
1463
|
+
sourcePick?: PhotoSourcePick;
|
|
1464
|
+
uploadOffered?: boolean;
|
|
1465
|
+
fixes?: boolean;
|
|
1466
|
+
fixReview?: "confirm" | "silent";
|
|
1467
|
+
output?: PortraitOutputFormat;
|
|
1468
|
+
pendingFix?: HostedPortraitPendingFix;
|
|
1469
|
+
captureMode?: CaptureMode;
|
|
1470
|
+
reuse?: {
|
|
1471
|
+
pending: true;
|
|
1472
|
+
};
|
|
1473
|
+
};
|
|
1474
|
+
/** The flow version the session runs (Sekyro flows §9.2). */
|
|
1475
|
+
flow?: HostedFlowRef;
|
|
1476
|
+
/**
|
|
1477
|
+
* What the person does now (Sekyro flows §8.1), the only source of the
|
|
1478
|
+
* steps: render `plan.current`. Absent on an active session only from a
|
|
1479
|
+
* backend older than the flows release (the SDK then asks for an update).
|
|
1480
|
+
*/
|
|
1481
|
+
plan?: HostedPlanView;
|
|
1482
|
+
/** Step 2b identity summary, present only while its confirmation is pending. */
|
|
1483
|
+
identitySummary?: IdentitySummaryView;
|
|
1484
|
+
/**
|
|
1485
|
+
* Spec 2026-10-29 §6.7: the copy set the session's screens use: `human` (the person proves they are a real person:
|
|
1486
|
+
* one intro line, the short Human consent terms) or `identity`. Absent on older APIs: treat as `identity`.
|
|
1487
|
+
*/
|
|
1488
|
+
purpose?: "human" | "identity";
|
|
1489
|
+
/**
|
|
1490
|
+
* Spec 2026-10-29 §3.4: `true` when a flow fallback takes over a missing camera at the live step
|
|
1491
|
+
* (`POST /hosted/camera-unavailable` continues the session instead of ending it). Absent otherwise and on
|
|
1492
|
+
* older APIs. Offer "continue without a camera" only then, or on a `human` session.
|
|
1493
|
+
*/
|
|
1494
|
+
cameraUnavailableHandled?: true;
|
|
1495
|
+
/**
|
|
1496
|
+
* Sandbox DX spec 2026-11-06 §8: present only on a simulated session (never Live, never bound to a tester), so the
|
|
1497
|
+
* flow can say that nothing is sent and offer to skip the camera steps. Absent otherwise and on older APIs.
|
|
1498
|
+
*/
|
|
1499
|
+
simulation?: HostedSimulationView;
|
|
1500
|
+
/**
|
|
1501
|
+
* 2026-11-05: where the ID document step's photo may come from. Absent when the open document step is camera only
|
|
1502
|
+
* with no upload offered (and on older APIs): `{ source: "camera", uploadOffered: false }`.
|
|
1503
|
+
*/
|
|
1504
|
+
documents?: HostedDocumentsView;
|
|
1505
|
+
/**
|
|
1506
|
+
* Spec 2026-11-10 §5.4, §7.4: the open proof of address step's settings (the accepted kinds for the best known
|
|
1507
|
+
* country, the name rule, the phase, the photo source, the upload limits). Present only while a `poa` step is open;
|
|
1508
|
+
* absent on older APIs.
|
|
1509
|
+
*/
|
|
1510
|
+
proofOfAddress?: HostedProofOfAddressView;
|
|
1511
|
+
/**
|
|
1512
|
+
* Spec 2026-10-29 D12: where the hosted completion screen sends the person (`returnUrl`, checked at session
|
|
1513
|
+
* create against the app's web origins or native scheme) and the partner's opaque `state`. Never the result.
|
|
1514
|
+
* Absent when the session has no return link (and on older APIs).
|
|
1515
|
+
*/
|
|
1516
|
+
link?: {
|
|
1517
|
+
returnUrl?: string;
|
|
1518
|
+
state?: string;
|
|
1519
|
+
};
|
|
1520
|
+
/**
|
|
1521
|
+
* Custom domains (spec 2026-11-02 §5.4): `origin` = where this session's link was minted, `hosts` = the
|
|
1522
|
+
* hostnames allowed to serve it (the platform host, then the org's active custom hostnames). Absent on older
|
|
1523
|
+
* APIs; the SDK does not need it.
|
|
1524
|
+
*/
|
|
1525
|
+
hosted?: {
|
|
1526
|
+
origin: string;
|
|
1527
|
+
hosts: string[];
|
|
1528
|
+
};
|
|
1529
|
+
}
|
|
1530
|
+
/** {@link HostedSessionView.nativeApp}: where a browser sends the person when the flow takes photos in an app only. */
|
|
1531
|
+
interface HostedNativeAppView {
|
|
1532
|
+
/** The session's app allows verification in the Sekyro AI app. */
|
|
1533
|
+
sekyroApp: boolean;
|
|
1534
|
+
/** This session's link (`https://…/<code>`): on a phone with the Sekyro AI app it opens the app. */
|
|
1535
|
+
link?: string;
|
|
1536
|
+
/** `sekyro://verify/<code>`: opens this session in the Sekyro AI app. Only with `sekyroApp`. */
|
|
1537
|
+
sekyroAppLink?: string;
|
|
1538
|
+
}
|
|
1539
|
+
/** `POST /hosted/consent` result — 201 on first record, 200 `{alreadyRecorded: true}` on replay. */
|
|
1540
|
+
/**
|
|
1541
|
+
* `POST /hosted/consent` answer (Sekyro flows §8.2): the hosted view with
|
|
1542
|
+
* `consentRecorded: true`, plus whether consent was already on record.
|
|
1543
|
+
*/
|
|
1544
|
+
type HostedConsentView = HostedSessionView & RecordConsentResult;
|
|
1545
|
+
interface RecordConsentResult {
|
|
1546
|
+
alreadyRecorded: boolean;
|
|
1547
|
+
}
|
|
1548
|
+
/**
|
|
1549
|
+
* Consent locale: the page's `[locale]` URL segment echoed back (HostedConsentSchema picklist). The six end-user
|
|
1550
|
+
* locales (spec 2026-10-29 §9); a backend older than Plan C accepts ar/fr/en only.
|
|
1551
|
+
*/
|
|
1552
|
+
type ConsentLocale = "ar" | "fr" | "en" | "es" | "pt" | "de";
|
|
1553
|
+
/** Per-check projection in a {@link SessionView} — enum/id only, never civil data. */
|
|
1554
|
+
interface SessionStepView {
|
|
1555
|
+
checkType: CheckType;
|
|
1556
|
+
state: CheckState;
|
|
1557
|
+
reason?: CheckReason;
|
|
1558
|
+
/**
|
|
1559
|
+
* Spec 2026-10-27: a Sandbox check answered by simulation (no provider or
|
|
1560
|
+
* model ran). Absent on Live, on real Sandbox checks and on older APIs.
|
|
1561
|
+
*/
|
|
1562
|
+
simulated?: boolean;
|
|
1563
|
+
calibratedScore?: number;
|
|
1564
|
+
/** What the last counted attempt said ({@link StepResult}); absent before the first one. */
|
|
1565
|
+
result?: StepResult;
|
|
1566
|
+
/** Counted attempts and the cap. */
|
|
1567
|
+
attempts?: PlanAttempts;
|
|
1568
|
+
/** portrait_icao only (SDK spec §4.9): the last attempt's per-criterion report. */
|
|
1569
|
+
report?: IcaoReportEntry[];
|
|
1570
|
+
}
|
|
1571
|
+
/**
|
|
1572
|
+
* Client-facing session projection returned by
|
|
1573
|
+
* `POST /sessions/:id/checks/:checkType`. Whitelist-only — never the client token.
|
|
1574
|
+
*/
|
|
1575
|
+
interface SessionView {
|
|
1576
|
+
id: string;
|
|
1577
|
+
status: SessionStatus;
|
|
1578
|
+
/** `not_verified` only: why ({@link SessionReason}). */
|
|
1579
|
+
reason?: SessionReason;
|
|
1580
|
+
/** `not_verified` only: the detailed code behind `reason`, when one exists. */
|
|
1581
|
+
reasonCode?: string;
|
|
1582
|
+
/** Finished sessions: who or what closed it ({@link ClosedBy}). */
|
|
1583
|
+
closedBy?: ClosedBy;
|
|
1584
|
+
/** `not_verified` only: the step that decided it, when one did. */
|
|
1585
|
+
step?: SessionDecidingStep;
|
|
1586
|
+
steps: SessionStepView[];
|
|
1587
|
+
/** ISO-8601 timestamp (Date on the server, string on the wire). */
|
|
1588
|
+
expiresAt: string;
|
|
1589
|
+
/** ISO-8601 timestamp (Date on the server, string on the wire). */
|
|
1590
|
+
createdAt?: string;
|
|
1591
|
+
}
|
|
1592
|
+
/** Media class — selects size cap, MIME allowlist and promoted prefix (media.policy.ts). */
|
|
1593
|
+
type MediaKind = "image" | "clip" | "document_file";
|
|
1594
|
+
/**
|
|
1595
|
+
* Body of `POST /sessions/:id/media`. `contentType`/`contentLength` are the
|
|
1596
|
+
* exact values SIGNED into the presigned PUT — the PUT must send them verbatim.
|
|
1597
|
+
* Allowlists (media.policy.ts): image → image/jpeg | image/png (5 MB cap);
|
|
1598
|
+
* clip → video/webm | video/mp4 (15 MB cap); document_file → application/pdf (10 MB cap, the proof of address
|
|
1599
|
+
* step's upload only, spec 2026-11-10 §7.1). BARE types only — no `;codecs=` params.
|
|
1600
|
+
*/
|
|
1601
|
+
interface PresignRequest {
|
|
1602
|
+
kind: MediaKind;
|
|
1603
|
+
contentType: string;
|
|
1604
|
+
contentLength: number;
|
|
1605
|
+
/** D8: the live-camera capture proof (image / clip from the SDK capture flows only). */
|
|
1606
|
+
capture?: CaptureProof;
|
|
1607
|
+
/**
|
|
1608
|
+
* Design 2026-11-04 §5.2: `upload` = a photo of the document picked from the device (`image` only, no capture
|
|
1609
|
+
* proof). Accepted only while the session's document step accepts an upload (else 400 `document_upload_not_allowed`);
|
|
1610
|
+
* the promoted key can then only be submitted as `doc_ocr` with `source: "upload"` (else 400
|
|
1611
|
+
* `uploaded_media_not_allowed`).
|
|
1612
|
+
*/
|
|
1613
|
+
source?: "upload";
|
|
1614
|
+
}
|
|
1615
|
+
/**
|
|
1616
|
+
* D8 — the proof a live-camera image / clip presign carries: a single-use nonce
|
|
1617
|
+
* from `POST /sessions/:id/media/capture-nonces`, plus the capture engine and how
|
|
1618
|
+
* long the capture took. A picked file (or a client without the capture flow)
|
|
1619
|
+
* sends none; the backend then flags (or, in `enforce`, refuses) the upload.
|
|
1620
|
+
*/
|
|
1621
|
+
interface CaptureProof {
|
|
1622
|
+
nonce: string;
|
|
1623
|
+
engine?: string;
|
|
1624
|
+
captureMs?: number;
|
|
1625
|
+
}
|
|
1626
|
+
/** D8: `POST /sessions/:id/media/capture-nonces` response. */
|
|
1627
|
+
interface CaptureNoncesResult {
|
|
1628
|
+
nonces: string[];
|
|
1629
|
+
/** Seconds each nonce stays usable. */
|
|
1630
|
+
expiresIn: number;
|
|
1631
|
+
}
|
|
1632
|
+
/** D8: what a capture flow knows about its capture when it presigns. */
|
|
1633
|
+
interface CaptureContext {
|
|
1634
|
+
/** Capture engine id (`v1` / `v3` liveness, `document`, `portrait`). */
|
|
1635
|
+
engine?: string;
|
|
1636
|
+
/** How long the camera capture took, ms (→ `captureMs`; informational). */
|
|
1637
|
+
durationMs?: number;
|
|
1638
|
+
}
|
|
1639
|
+
/** Result of a presign — the presigned PUT URL plus the pending object key. */
|
|
1640
|
+
interface PresignUploadResult {
|
|
1641
|
+
key: string;
|
|
1642
|
+
uploadUrl: string;
|
|
1643
|
+
/** Presign TTL in seconds (900 = 15 min). */
|
|
1644
|
+
expiresIn: number;
|
|
1645
|
+
}
|
|
1646
|
+
/** Result of `POST /sessions/:id/media/complete` — the PROMOTED (class-prefixed) key. */
|
|
1647
|
+
interface CompleteMediaResult {
|
|
1648
|
+
ready: true;
|
|
1649
|
+
/** e.g. `clips/{sessionId}/{uuid}` or `doc-images/{sessionId}/{uuid}` — submit THIS key, not the pending one. */
|
|
1650
|
+
key: string;
|
|
1651
|
+
}
|
|
1652
|
+
/**
|
|
1653
|
+
* Liveness attestation bag (attestation-verifier.service.ts). The web SDK sends
|
|
1654
|
+
* `{channel: 'hosted_web', turnstileToken}` in both environments, or
|
|
1655
|
+
* `{channel: 'hosted_web'}` when the challenge produced no token (the server's
|
|
1656
|
+
* attestation rules decide). The token comes from the Sekyro challenge frame
|
|
1657
|
+
* ({@link HostedChallengeView}) and is bound to the session and the page's
|
|
1658
|
+
* origin. Native SDKs use platform attestation.
|
|
1659
|
+
*/
|
|
1660
|
+
interface AttestationInput {
|
|
1661
|
+
signature?: string;
|
|
1662
|
+
channel?: "hosted_web";
|
|
1663
|
+
turnstileToken?: string;
|
|
1664
|
+
}
|
|
1665
|
+
/**
|
|
1666
|
+
* liveness executor input: a promoted `clips/…` key + optional attestation.
|
|
1667
|
+
* `faceMatch` (v2 latency §3.2) carries the already-promoted `doc-images/…`
|
|
1668
|
+
* keyframe so the backend can run face_match IN THE SAME submission when its
|
|
1669
|
+
* bundle flag is on and `face_match` is the next pending step. Backends that
|
|
1670
|
+
* do not bundle ignore it (the input bag is an open record) — the SDK then
|
|
1671
|
+
* submits `face_match` itself with the same key (see liveness-flow.ts).
|
|
1672
|
+
*/
|
|
1673
|
+
interface LivenessInput {
|
|
1674
|
+
clipKey: string;
|
|
1675
|
+
attestation?: AttestationInput;
|
|
1676
|
+
/** Declared capture channel, reported only (stored with the capture metadata): the server decides a desktop from
|
|
1677
|
+
* the request headers, never from this field. */
|
|
1678
|
+
captureChannel?: 'mobile' | 'desktop';
|
|
1679
|
+
/** Capture metadata (engine, dimensions, clip length, face-capture timing)
|
|
1680
|
+
* — the backend's allowlisted, non-PII `capture` block (session insights). */
|
|
1681
|
+
capture?: LivenessCaptureInput;
|
|
1682
|
+
/** The promoted face_match probe key, for a bundled liveness + face_match run. */
|
|
1683
|
+
faceMatch?: {
|
|
1684
|
+
imageKey: string;
|
|
1685
|
+
};
|
|
1686
|
+
/**
|
|
1687
|
+
* Step 3 one-capture live photo (flow model 2026-10-23): the ICAO still of the
|
|
1688
|
+
* same capture — exactly the `portrait_icao` body. When `portrait_icao` is the
|
|
1689
|
+
* next pending step the server runs it in parallel with liveness.
|
|
1690
|
+
*/
|
|
1691
|
+
portraitIcao?: PortraitIcaoInput;
|
|
1692
|
+
}
|
|
1693
|
+
/** `LivenessInput.capture`: what the SDK's `captured` event measured. All ms are whole, ≥ 0. */
|
|
1694
|
+
interface LivenessCaptureInput {
|
|
1695
|
+
engine?: 'v1' | 'v3';
|
|
1696
|
+
width?: number;
|
|
1697
|
+
height?: number;
|
|
1698
|
+
/** The clip's duration (ms), read from its container when the SDK could. */
|
|
1699
|
+
clipMs?: number;
|
|
1700
|
+
/** Video frames in the clip. */
|
|
1701
|
+
clipFrames?: number;
|
|
1702
|
+
/** The clip's frame rate (frames over its duration). */
|
|
1703
|
+
fps?: number;
|
|
1704
|
+
/** Silent re-recordings of the clip (0 or 1). */
|
|
1705
|
+
clipRetakes?: number;
|
|
1706
|
+
/** The clip's codec, from the recorder's type. */
|
|
1707
|
+
codec?: string;
|
|
1708
|
+
cameraReadyMs?: number;
|
|
1709
|
+
faceAcquireMs?: number;
|
|
1710
|
+
captureMs?: number;
|
|
1711
|
+
/** Uploads settled → attestation token in hand (the challenge frame on the web), ms. */
|
|
1712
|
+
attestationMs?: number;
|
|
1713
|
+
/**
|
|
1714
|
+
* Why the web challenge produced no token (a `ChallengeErrorCode`: `challenge_frame_blocked`, `timeout`, ...),
|
|
1715
|
+
* lower case, at most 32 characters. Absent when the token was obtained.
|
|
1716
|
+
*/
|
|
1717
|
+
attestationError?: string;
|
|
1718
|
+
/** Browser checks this page ran before the submitted token (2026-11-15), at most 50. */
|
|
1719
|
+
attestationChecks?: number;
|
|
1720
|
+
/** The submitted token's check: start to token, ms (2026-11-15). */
|
|
1721
|
+
attestationChallengeMs?: number;
|
|
1722
|
+
/** The camera the clip was filmed with (`environment` = back). */
|
|
1723
|
+
facingMode?: 'user' | 'environment';
|
|
1724
|
+
/**
|
|
1725
|
+
* The capture mode the SDK applied: the session's `capture.mode`, or under `choice` the person's pick
|
|
1726
|
+
* (`Verification.chooseCaptureMode`). The server checks the pick is one the session allows.
|
|
1727
|
+
*/
|
|
1728
|
+
mode?: 'self' | 'assisted';
|
|
1729
|
+
/** The device kind. With `mode` set, the server applies the upright requirement (`capture_not_upright`) to `phone` only. */
|
|
1730
|
+
formFactor?: 'phone' | 'tablet' | 'desktop';
|
|
1731
|
+
/**
|
|
1732
|
+
* Liveness v7 §4.5 item 1: the screen ramp the SDK rendered against the session's issued challenge. Absent when no
|
|
1733
|
+
* challenge was issued, in an assisted capture, in a keyframe-only capture, or when no host painted the ramp.
|
|
1734
|
+
*/
|
|
1735
|
+
screenRamp?: ScreenRampReport;
|
|
1736
|
+
/** Liveness v7 §4.5 item 2: how the capture was made. Sent whenever the engine had a camera track. */
|
|
1737
|
+
provenance?: CaptureProvenance;
|
|
1738
|
+
}
|
|
1739
|
+
/**
|
|
1740
|
+
* population_registry adapter input. `idNumber` is the national number the
|
|
1741
|
+
* person typed on an UNBOUND session; a session minted with `subject.idNumber`
|
|
1742
|
+
* is BOUND to it: the browser submits `{}` and the backend reads the sealed
|
|
1743
|
+
* value. Sending a DIFFERENT number on a bound session answers 409
|
|
1744
|
+
* `id_number_locked` (formerly `nni_locked`). `nni` is the former name of
|
|
1745
|
+
* `idNumber` (both accepted; both with different values is `400 validation_error`).
|
|
1746
|
+
*/
|
|
1747
|
+
interface PopulationInput {
|
|
1748
|
+
idNumber?: string;
|
|
1749
|
+
/** @deprecated Send `idNumber`. */
|
|
1750
|
+
nni?: string;
|
|
1751
|
+
}
|
|
1752
|
+
/**
|
|
1753
|
+
* face_match executor input: a promoted `doc-images/…` key (the source selfie frame).
|
|
1754
|
+
* The same key may already have ridden along as {@link LivenessInput.faceMatch}.
|
|
1755
|
+
*/
|
|
1756
|
+
interface FaceMatchInput {
|
|
1757
|
+
imageKey: string;
|
|
1758
|
+
}
|
|
1759
|
+
/** Document side (docs.types.ts DocSide). */
|
|
1760
|
+
type DocSide = "recto" | "verso" | "single";
|
|
1761
|
+
/** The hosted view's `testerGate` block (spec 2026-11-09 §3.3). */
|
|
1762
|
+
interface HostedTesterGateView {
|
|
1763
|
+
offered: true;
|
|
1764
|
+
/** Gates left on this session (3 at most). */
|
|
1765
|
+
attemptsLeft: number;
|
|
1766
|
+
}
|
|
1767
|
+
/** Body `input` of `POST /hosted/tester-gate`: the liveness clip of the gate, in the liveness step's input shape. */
|
|
1768
|
+
interface TesterGateInput {
|
|
1769
|
+
clipKey: string;
|
|
1770
|
+
attestation?: AttestationInput;
|
|
1771
|
+
captureChannel?: "mobile" | "desktop";
|
|
1772
|
+
capture?: LivenessCaptureInput;
|
|
1773
|
+
}
|
|
1774
|
+
/** Answer of `POST /hosted/tester-gate`: the hosted view after the gate, and whether an enrolled tester was recognised. */
|
|
1775
|
+
type TesterGateResponse = HostedSessionView & {
|
|
1776
|
+
bound: boolean;
|
|
1777
|
+
};
|
|
1778
|
+
/**
|
|
1779
|
+
* Why a Sandbox session ran on simulated test data instead of real checks:
|
|
1780
|
+
* - `no_testers`: the organization has no active Sandbox tester;
|
|
1781
|
+
* - `tester_gate_not_used`: testers exist, and nobody ran the tester check at the start of the session;
|
|
1782
|
+
* - `tester_gate_missed`: the tester check ran and recognized nobody.
|
|
1783
|
+
*/
|
|
1784
|
+
type SandboxSimulatedReason = "no_testers" | "tester_gate_not_used" | "tester_gate_missed";
|
|
1785
|
+
/**
|
|
1786
|
+
* A Sandbox session that ran on simulated test data, and why: the `sandbox` object of `GET /sessions/{id}` and of the
|
|
1787
|
+
* session webhooks. Never present in Live, nor on a session an enrolled tester ran.
|
|
1788
|
+
*/
|
|
1789
|
+
interface SandboxSimulation {
|
|
1790
|
+
/** Always `true`. */
|
|
1791
|
+
simulated: true;
|
|
1792
|
+
reason: SandboxSimulatedReason;
|
|
1793
|
+
}
|
|
1794
|
+
/** The hosted view's `simulation` block (Sandbox DX spec 2026-11-06 §8): what a simulated session tells the flow. */
|
|
1795
|
+
interface HostedSimulationView {
|
|
1796
|
+
/** The code that passes the phone, email and national eID code screens: render it, nothing is delivered. */
|
|
1797
|
+
otpCode: string;
|
|
1798
|
+
/** The server takes {@link SimulatedCaptureInput} on the document, chip, liveness and portrait steps. */
|
|
1799
|
+
skipCapture: boolean;
|
|
1800
|
+
/**
|
|
1801
|
+
* Why no enrolled Sandbox tester ran the session; the result screen says it. Absent on an older API and on a session
|
|
1802
|
+
* a tester had bound before being removed.
|
|
1803
|
+
*/
|
|
1804
|
+
reason?: SandboxSimulatedReason;
|
|
1805
|
+
}
|
|
1806
|
+
/**
|
|
1807
|
+
* The input of a camera step skipped in a simulated session (`doc_ocr`, `nfc_chip`, `liveness`, `face_match`,
|
|
1808
|
+
* `portrait_icao`), with no media. Any other session answers `403 simulated_capture_forbidden`.
|
|
1809
|
+
*/
|
|
1810
|
+
interface SimulatedCaptureInput {
|
|
1811
|
+
/** Always `true`. */
|
|
1812
|
+
simulatedCapture: true;
|
|
1813
|
+
}
|
|
1814
|
+
/** The hosted view's `documents` block (2026-11-05): where the ID document step's photo may come from. */
|
|
1815
|
+
interface HostedDocumentsView {
|
|
1816
|
+
/** The step's setting ({@link PhotoSource}). */
|
|
1817
|
+
source: PhotoSource;
|
|
1818
|
+
/** The person's pick under `choice`, once made for this step (do not ask again: a retry, the back side). */
|
|
1819
|
+
sourcePick?: PhotoSourcePick;
|
|
1820
|
+
/**
|
|
1821
|
+
* An upload would be accepted now: `upload`, or `choice` without a camera pick. Never on a camera step, even when
|
|
1822
|
+
* the person's camera cannot open (the step's source is final).
|
|
1823
|
+
*/
|
|
1824
|
+
uploadOffered: boolean;
|
|
1825
|
+
}
|
|
1826
|
+
/** The document kinds a proof of address may be (spec §5.2). */
|
|
1827
|
+
type PoaKind = "utility_bill" | "telecom_bill" | "bank_statement" | "tax_notice" | "rental_agreement" | "government_certificate" | "insurance_statement";
|
|
1828
|
+
/**
|
|
1829
|
+
* How the name on the document is matched: `exact_person` (the person's own name), `family_name` (the same family
|
|
1830
|
+
* name), `third_party_letter` (another holder, with a signed letter from that holder).
|
|
1831
|
+
*/
|
|
1832
|
+
type PoaNameMatchMode = "exact_person" | "family_name" | "third_party_letter";
|
|
1833
|
+
/**
|
|
1834
|
+
* Where the step's rule came from: the flow's rule for the country (`flow_country`), the flow's default rule
|
|
1835
|
+
* (`flow_default`), Sekyro's preset for the country (`preset_country`) or the global preset (`preset_global`).
|
|
1836
|
+
*/
|
|
1837
|
+
type PoaRuleSource = "flow_country" | "flow_default" | "preset_country" | "preset_global";
|
|
1838
|
+
/** One accepted kind of the step's rule. */
|
|
1839
|
+
interface HostedPoaRuleKindView {
|
|
1840
|
+
kind: PoaKind;
|
|
1841
|
+
/** How old the document of this kind may be, in days. */
|
|
1842
|
+
maxAgeDays: number;
|
|
1843
|
+
/** ISO day: today minus `maxAgeDays`, computed by the server so every client says the same date. */
|
|
1844
|
+
earliestIssueDate: string;
|
|
1845
|
+
}
|
|
1846
|
+
/** The accepted documents the step shows (spec §5.4 "person-facing list"), resolved by the server. */
|
|
1847
|
+
interface HostedPoaRuleView {
|
|
1848
|
+
/** The country the rule was resolved for (ISO 3166-1 alpha-2); `null` = the global entry. */
|
|
1849
|
+
country: string | null;
|
|
1850
|
+
/**
|
|
1851
|
+
* How that country was chosen: the identity document's issuer, else the IP country, else global; after a
|
|
1852
|
+
* `document_kind_not_accepted` or `document_too_old` failure, the failed document's own country (`document`).
|
|
1853
|
+
*/
|
|
1854
|
+
countryFrom: "identity_document" | "ip" | "document" | "global";
|
|
1855
|
+
source: PoaRuleSource;
|
|
1856
|
+
kinds: HostedPoaRuleKindView[];
|
|
1857
|
+
}
|
|
1858
|
+
/** The open proof of address step (`HostedSessionView.proofOfAddress`). */
|
|
1859
|
+
interface HostedProofOfAddressView {
|
|
1860
|
+
rule: HostedPoaRuleView;
|
|
1861
|
+
nameMatch: PoaNameMatchMode;
|
|
1862
|
+
/** `holder_letter` once the bill was read under `third_party_letter` and the step waits for the holder's letter. */
|
|
1863
|
+
phase: "document" | "holder_letter";
|
|
1864
|
+
/** Where the pages come from ({@link PhotoSource}). */
|
|
1865
|
+
source: PhotoSource;
|
|
1866
|
+
/** The person's pick under `choice`, once made for this step. */
|
|
1867
|
+
sourcePick?: PhotoSourcePick;
|
|
1868
|
+
/** An upload would be accepted now. */
|
|
1869
|
+
uploadOffered: boolean;
|
|
1870
|
+
/** Pages per document, at most. */
|
|
1871
|
+
maxPages: 3;
|
|
1872
|
+
/** A PDF upload's limits. */
|
|
1873
|
+
pdf: {
|
|
1874
|
+
maxBytes: number;
|
|
1875
|
+
maxPages: 3;
|
|
1876
|
+
};
|
|
1877
|
+
/**
|
|
1878
|
+
* Spec 2026-11-10 §5.3 licence shortcut: the step accepts the address of the driving licence read earlier in the
|
|
1879
|
+
* session, so the person may continue without a document ({@link PoaLicenceInput}). Present only in the `document`
|
|
1880
|
+
* phase.
|
|
1881
|
+
*/
|
|
1882
|
+
licenceAddressAccepted?: true;
|
|
1883
|
+
}
|
|
1884
|
+
/**
|
|
1885
|
+
* `poa` executor input (spec 2026-11-10 §7): the document (or, in the `holder_letter` phase, the holder's letter) as
|
|
1886
|
+
* 1 to 3 promoted page images, or as one promoted PDF (`document_file` media kind).
|
|
1887
|
+
*/
|
|
1888
|
+
type PoaInput = PoaImagesInput | PoaPdfInput | PoaLicenceInput;
|
|
1889
|
+
/**
|
|
1890
|
+
* The licence shortcut (spec 2026-11-10 §5.3): no media; the server decides from the driving licence read earlier in
|
|
1891
|
+
* the session. Only while the view's `proofOfAddress.licenceAddressAccepted` is set.
|
|
1892
|
+
*/
|
|
1893
|
+
interface PoaLicenceInput {
|
|
1894
|
+
part: "document";
|
|
1895
|
+
}
|
|
1896
|
+
/** The pages as images, in order. */
|
|
1897
|
+
interface PoaImagesInput {
|
|
1898
|
+
part: "document" | "holder_letter";
|
|
1899
|
+
source: PhotoSourcePick;
|
|
1900
|
+
/** 1 to 3 promoted `image` keys. */
|
|
1901
|
+
imageKeys: string[];
|
|
1902
|
+
}
|
|
1903
|
+
/** The document as one PDF (always picked from the device). */
|
|
1904
|
+
interface PoaPdfInput {
|
|
1905
|
+
part: "document" | "holder_letter";
|
|
1906
|
+
source: "upload";
|
|
1907
|
+
/** The promoted `document_file` key. */
|
|
1908
|
+
pdfKey: string;
|
|
1909
|
+
}
|
|
1910
|
+
/** doc_ocr executor input: a promoted `doc-images/…` key + which side it shows. */
|
|
1911
|
+
interface DocOcrInput {
|
|
1912
|
+
imageKey: string;
|
|
1913
|
+
side: DocSide;
|
|
1914
|
+
/**
|
|
1915
|
+
* Web live MRZ (spec 2026-10-21 D6): the device-read HINT of a live-MRZ capture — where the MRZ is in the uploaded
|
|
1916
|
+
* image and that every hard check digit validated on the device. Geometry, a format, counts and a salted digest
|
|
1917
|
+
* only (never MRZ text); the server re-reads the pixels and decides. Omitted when not ready at POST time.
|
|
1918
|
+
*/
|
|
1919
|
+
deviceRead?: DocDeviceRead;
|
|
1920
|
+
/**
|
|
1921
|
+
* 2026-11-05: `upload` when the photo was picked from the device instead of taken with the camera (only while the
|
|
1922
|
+
* view's `documents.uploadOffered`; else 400 `document_upload_not_allowed`). Absent = `camera`.
|
|
1923
|
+
*/
|
|
1924
|
+
source?: PhotoSourcePick;
|
|
1925
|
+
/**
|
|
1926
|
+
* The document type the person picked (spec 2026-11-11 D11 rule 1). The server refuses a document that is not the
|
|
1927
|
+
* one picked; `drivers_license` also routes both faces to its document reader (spec 2026-11-10 §6.2).
|
|
1928
|
+
*/
|
|
1929
|
+
documentType?: AcceptedDocumentType;
|
|
1930
|
+
/** The issuing country the person picked, ISO 3166-1 alpha-2. Sent with `documentType`. */
|
|
1931
|
+
documentCountry?: string;
|
|
1932
|
+
}
|
|
1933
|
+
/** The `doc_ocr` device-read hint (identity-backend DeviceReadSchema; strict, text-free). */
|
|
1934
|
+
interface DocDeviceRead {
|
|
1935
|
+
engine: string;
|
|
1936
|
+
source: "live_mrz";
|
|
1937
|
+
format: "TD1" | "TD2" | "TD3";
|
|
1938
|
+
lineCount: number;
|
|
1939
|
+
checkDigitsValid: true;
|
|
1940
|
+
stillConfirmed?: boolean;
|
|
1941
|
+
/** [x, y, w, h] normalized to the uploaded image. */
|
|
1942
|
+
band: [number, number, number, number];
|
|
1943
|
+
/** sha256("sekyro-mrz-1\0" + sessionId + "\0" + canonical MRZ lines), 64 hex. */
|
|
1944
|
+
digest: string;
|
|
1945
|
+
framesToValid: number;
|
|
1946
|
+
msToValid: number;
|
|
1947
|
+
}
|
|
1948
|
+
/** How the digits of a national number group while typing (phone rules spec 2026-11-02 §2.1). */
|
|
1949
|
+
interface PhoneFormat {
|
|
1950
|
+
/** A pattern over the national digits, matched anchored at the start. */
|
|
1951
|
+
leading: string;
|
|
1952
|
+
/** Digits per block; the sum is one of the rule's `lengths`. */
|
|
1953
|
+
groups: number[];
|
|
1954
|
+
}
|
|
1955
|
+
/** The numbering plan of one accepted country, derived from libphonenumber metadata on the server (spec §2.1). */
|
|
1956
|
+
interface PhoneCountryRule {
|
|
1957
|
+
/** ISO alpha-2, an entry of the step's `phoneCountries`. */
|
|
1958
|
+
code: string;
|
|
1959
|
+
/** The calling code's digits, without `+`. */
|
|
1960
|
+
dial: string;
|
|
1961
|
+
/** National prefix a person may type first and the client drops; absent when the country has none. */
|
|
1962
|
+
trunk?: string;
|
|
1963
|
+
/** The valid national number lengths, ascending. */
|
|
1964
|
+
lengths: number[];
|
|
1965
|
+
/** Digit grouping; absent when the plan has too many formats or none usable. */
|
|
1966
|
+
formats?: PhoneFormat[];
|
|
1967
|
+
}
|
|
1968
|
+
/**
|
|
1969
|
+
* phone_otp executor input (Task 13): a two-phase check. `send` dispatches (or
|
|
1970
|
+
* resends) an OTP — resolving the number from the trusted server-side prefill
|
|
1971
|
+
* or the user-entered `phone` per the step's `numberSource`; `verify` checks
|
|
1972
|
+
* the entered `code` against the parked token. `phone` is IGNORED for a
|
|
1973
|
+
* `prefilled` step (a client number is never trusted as "prefilled").
|
|
1974
|
+
*/
|
|
1975
|
+
interface PhoneOtpInput {
|
|
1976
|
+
/** Phase selector: `send` dispatches/resends, `verify` checks the code. Defaults to `send`. */
|
|
1977
|
+
action: "send" | "verify";
|
|
1978
|
+
/** USER-entered E.164 number (`user_entered` / `prefilled_or_entered` sends only). */
|
|
1979
|
+
phone?: string;
|
|
1980
|
+
/** The code the user typed — `verify` only. */
|
|
1981
|
+
code?: string;
|
|
1982
|
+
/**
|
|
1983
|
+
* Phone rules spec 2026-11-02 §2.3: this client applied the server's rules and understands
|
|
1984
|
+
* `otp_number_invalid` and `otp_number_not_mobile`. `send` only.
|
|
1985
|
+
*/
|
|
1986
|
+
phoneRules?: 1;
|
|
1987
|
+
/**
|
|
1988
|
+
* The channel the person chose for `send`. Must be one of the step's
|
|
1989
|
+
* `otp.channels` when the view lists them; a session without channels
|
|
1990
|
+
* defaults to `sms`.
|
|
1991
|
+
*/
|
|
1992
|
+
channel?: "sms" | "whatsapp";
|
|
1993
|
+
/** OTP message locale override for `send`. */
|
|
1994
|
+
locale?: "ar" | "fr" | "en";
|
|
1995
|
+
}
|
|
1996
|
+
/**
|
|
1997
|
+
* email_otp executor input (Plan 8, profile v2 §4.6.5): `send` emails a code to
|
|
1998
|
+
* the trusted prefill or the user-entered `email` (per `emailOtp.emailSource`;
|
|
1999
|
+
* ignored for `prefilled`), `verify` checks the entered `code`.
|
|
2000
|
+
*/
|
|
2001
|
+
interface EmailOtpInput {
|
|
2002
|
+
/** Phase selector: `send` dispatches/resends, `verify` checks the code. */
|
|
2003
|
+
action: "send" | "verify";
|
|
2004
|
+
/** USER-entered address (`user_entered` / `prefilled_or_entered` sends only). */
|
|
2005
|
+
email?: string;
|
|
2006
|
+
/** The code the user typed — `verify` only. */
|
|
2007
|
+
code?: string;
|
|
2008
|
+
/** Email copy locale override for `send`. */
|
|
2009
|
+
locale?: "ar" | "fr" | "en";
|
|
2010
|
+
}
|
|
2011
|
+
/**
|
|
2012
|
+
* portrait_icao executor input (SDK spec §4.9): the ICAO gate's frame
|
|
2013
|
+
* (uploaded as media kind `image`). The server re-runs every criterion; only the
|
|
2014
|
+
* eye baselines (0–1, the user's own eye openness) are used.
|
|
2015
|
+
*/
|
|
2016
|
+
interface PortraitIcaoInput {
|
|
2017
|
+
media: {
|
|
2018
|
+
portrait: string;
|
|
2019
|
+
};
|
|
2020
|
+
gate?: {
|
|
2021
|
+
baselineEyeOpenness?: number;
|
|
2022
|
+
/** The baseline of each eye, both or neither: the server then judges each eye against its own. */
|
|
2023
|
+
baselineEyeOpennessLeft?: number;
|
|
2024
|
+
baselineEyeOpennessRight?: number;
|
|
2025
|
+
/**
|
|
2026
|
+
* The device verdict on the submitted still, with the server's criterion names
|
|
2027
|
+
* (`framing` folds into `resolution`; unmeasured criteria are omitted, and
|
|
2028
|
+
* `background` when the profile does not require it). Compared with the server
|
|
2029
|
+
* report, never trusted. Values are booleans keyed by {@link IcaoCriterion}
|
|
2030
|
+
* (the 0.1 type is kept: the public API only grows).
|
|
2031
|
+
*/
|
|
2032
|
+
criteria?: Record<string, unknown>;
|
|
2033
|
+
/** The client background-uniformity measurement (numbers only; telemetry — the server decides). */
|
|
2034
|
+
backgroundCheck?: Record<string, unknown>;
|
|
2035
|
+
};
|
|
2036
|
+
tuningVersion?: string;
|
|
2037
|
+
/**
|
|
2038
|
+
* Design 2026-11-04 §6.2: `camera` for a photo the portrait camera took, `upload` for a photo picked from the device
|
|
2039
|
+
* (presigned as a declared upload, no capture proof). Absent = `camera`.
|
|
2040
|
+
*/
|
|
2041
|
+
source?: PhotoSourcePick;
|
|
2042
|
+
/**
|
|
2043
|
+
* Camera only: the capture mode the portrait camera ran in (the step's, or the person's pick under `choice`) and the
|
|
2044
|
+
* camera the photo was taken with. An `assisted` photo on the front camera is refused with `capture_front_camera`.
|
|
2045
|
+
*/
|
|
2046
|
+
capture?: {
|
|
2047
|
+
mode: ResolvedCaptureMode;
|
|
2048
|
+
facingMode?: 'user' | 'environment';
|
|
2049
|
+
};
|
|
2050
|
+
}
|
|
2051
|
+
/**
|
|
2052
|
+
* eid_auth executor input (SDK spec §3.2): `start` asks the provider for a
|
|
2053
|
+
* code (with the person's `identifier` — the NNI in MR — unless the session is
|
|
2054
|
+
* bound to it), `verify` checks the typed `code`, `resend` asks for a new code.
|
|
2055
|
+
* On a bound session a different `identifier` answers 409 `nni_locked`.
|
|
2056
|
+
*/
|
|
2057
|
+
interface EidAuthInput {
|
|
2058
|
+
action: "start" | "verify" | "resend";
|
|
2059
|
+
/** `start` only: the national number, omitted on a bound session. */
|
|
2060
|
+
identifier?: string;
|
|
2061
|
+
/** `verify` only: the code shown in the provider's app. */
|
|
2062
|
+
code?: string;
|
|
2063
|
+
}
|
|
2064
|
+
/**
|
|
2065
|
+
* The person's answer to an adjusted portrait (design 2026-11-04 §6.4 step 4), submitted as `portrait_icao` while
|
|
2066
|
+
* `HostedSessionView.portrait.pendingFix` is present: `accept: true` uses the adjusted photo, `false` ends the attempt
|
|
2067
|
+
* (`portrait_declined_fix`, not billed).
|
|
2068
|
+
*/
|
|
2069
|
+
interface PortraitFixReviewInput {
|
|
2070
|
+
fixReview: {
|
|
2071
|
+
accept: boolean;
|
|
2072
|
+
};
|
|
2073
|
+
}
|
|
2074
|
+
/** Per-check-type submission input shapes, keyed by the frozen vocabulary. */
|
|
2075
|
+
interface CheckInputByType {
|
|
2076
|
+
liveness: LivenessInput;
|
|
2077
|
+
face_match: FaceMatchInput;
|
|
2078
|
+
doc_ocr: DocOcrInput;
|
|
2079
|
+
population_registry: PopulationInput;
|
|
2080
|
+
phone_otp: PhoneOtpInput;
|
|
2081
|
+
/** M-nfc: read and submitted by the native SDKs only — the web never submits it. */
|
|
2082
|
+
nfc_chip: never;
|
|
2083
|
+
email_otp: EmailOtpInput;
|
|
2084
|
+
/** SDK spec §4.9: the web ICAO gate ships with M1b; the shape is ready for headless use. */
|
|
2085
|
+
portrait_icao: PortraitIcaoInput;
|
|
2086
|
+
/** SDK spec §3.2: the national eID sign-in. */
|
|
2087
|
+
eid_auth: EidAuthInput;
|
|
2088
|
+
/** Spec 2026-11-10 §5: the proof of address pages or PDF. */
|
|
2089
|
+
poa: PoaInput;
|
|
2090
|
+
/** Spec 2026-11-14 §14: the Form step's answers and consents. */
|
|
2091
|
+
form: FormInput;
|
|
2092
|
+
}
|
|
2093
|
+
/**
|
|
2094
|
+
* Body of `POST /sessions/:id/checks/:checkType` (SubmitCheckSchema).
|
|
2095
|
+
* `forceOutcome` is SANDBOX-ONLY (plan D-C) — a live session rejects it with
|
|
2096
|
+
* 403 `force_outcome_forbidden`.
|
|
2097
|
+
*/
|
|
2098
|
+
interface SubmitCheckBody {
|
|
2099
|
+
input?: Record<string, unknown>;
|
|
2100
|
+
/**
|
|
2101
|
+
* `age_over | age_uncertain | age_under | age_unavailable` (liveness submit only) pick what the age check
|
|
2102
|
+
* (selfie) step that follows the liveness step decides in a sandbox session.
|
|
2103
|
+
*/
|
|
2104
|
+
forceOutcome?: "pass" | "fail" | "age_over" | "age_uncertain" | "age_under" | "age_unavailable";
|
|
2105
|
+
}
|
|
2106
|
+
|
|
2107
|
+
export { type HostedNativeAppView as $, type AcceptedDocumentType as A, type FormFieldName as B, type CaptureContext as C, type DecisionReason as D, type EidAfterPass as E, type FaceMatchInput as F, type FormFieldQuestionView as G, type FormInput as H, type FormIssueCode as I, type FormLocale as J, type FormQuestionOptions as K, type FormQuestionType as L, type FormQuestionView as M, type HostedAcceptedDocuments as N, type HostedCaptureTuning as O, type HostedChallengeView as P, type HostedConsentView as Q, type HostedDocumentCaptureTuning as R, type HostedDocumentScanTuning as S, type HostedDocumentsView as T, type HostedEidView as U, type HostedEmailOtpView as V, type HostedFlowRef as W, type HostedFormView as X, type HostedIcaoPolicy as Y, type HostedIntegrity as Z, type HostedLivePhotoTuning as _, type AttestationInput as a, type SandboxSimulation as a$, type HostedNativeCaptureTuning as a0, type HostedOcrTuning as a1, type HostedOtpView as a2, type HostedPlanView as a3, type HostedPoaRuleKindView as a4, type HostedPoaRuleView as a5, type HostedPortraitPendingFix as a6, type HostedPortraitView as a7, type HostedProofOfAddressView as a8, type HostedSessionView as a9, type PhotoSourcePick as aA, type PlanAttempts as aB, type PlanChoiceKind as aC, type PlanChoiceOption as aD, type PlanChoiceView as aE, type PlanSectionView as aF, type PlanStepView as aG, type PoaImagesInput as aH, type PoaInput as aI, type PoaKind as aJ, type PoaLicenceInput as aK, type PoaNameMatchMode as aL, type PoaPdfInput as aM, type PoaReason as aN, type PoaRuleSource as aO, type PopulationInput as aP, type PopulationReason as aQ, type PortraitFix as aR, type PortraitFixReviewInput as aS, type PortraitIcaoInput as aT, type PortraitIcaoReason as aU, type PortraitOutputFormat as aV, type PresignRequest as aW, type PresignUploadResult as aX, type RecordConsentResult as aY, type ResolvedCaptureMode as aZ, type SandboxSimulatedReason as a_, type HostedSimulationView as aa, type HostedStepView as ab, type HostedTesterGateView as ac, type HostedVoiceLocale as ad, type HostedVoiceView as ae, type IcaoCriterion as af, type IcaoReportEntry as ag, type IdentityConfirmDecision as ah, type IdentityMethod as ai, type IdentitySummarySource as aj, type IdentitySummaryView as ak, type LivenessCaptureInput as al, type LivenessInput as am, type LivenessReason as an, type MatchReason as ao, type MediaKind as ap, type MethodChoiceView as aq, type NationalEidOption as ar, type NfcChipReason as as, type NfcStepView as at, type OtpChoiceView as au, type PhoneCountryRule as av, type PhoneFormat as aw, type PhoneOtpInput as ax, type PhoneOtpReason as ay, type PhotoSource as az, type CaptureMode as b, type SessionDecidingStep as b0, type SessionFailureReason as b1, type SessionReason as b2, type SessionStatus as b3, type SessionStepView as b4, type SessionView as b5, type SimulatedCaptureInput as b6, type StepResult as b7, type StepSection as b8, type SubmitCheckBody as b9, type TesterGateInput as ba, type TesterGateResponse as bb, type VerificationAssurance as bc, type VerificationLevel as bd, type ScreenRampColour as be, type AgeEstimationReason as bf, type CameraUnavailableCause as bg, type CaptureIssueReport as bh, type CaptureProvenance as bi, type HostedBranding as bj, type HostedBrandingColorKey as bk, type HostedLivenessCaptureTuning as bl, type IcaoCaptureTuning as bm, type RetakeHint as bn, type ScreenRampChallenge as bo, type ScreenRampPaint as bp, type ScreenRampRendered as bq, type ScreenRampReport as br, ICAO_FALLBACK as bs, type IcaoProfile as bt, type ResolvedIcaoTuning as bu, resolveIcaoTuning as bv, type PersonMask as bw, type BackgroundUniformity as bx, type CaptureNoncesResult as c, type CaptureProof as d, type CheckInputByType as e, type CheckReason as f, type CheckState as g, type CheckType as h, type ClosedBy as i, type CompleteMediaResult as j, type ConsentLocale as k, type ContactChannel as l, type DocDeviceRead as m, type DocOcrInput as n, type DocReason as o, type DocSide as p, type EidAuthInput as q, type EidReason as r, type EmailOtpInput as s, type EmailOtpReason as t, type FaceMatchReason as u, type FormAddressValue as v, type FormAnswerValue as w, type FormChoiceView as x, type FormConsentView as y, type FormCustomQuestionView as z };
|