@sekyro/node 0.1.0-rc.1 → 0.1.0-rc.11

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.
@@ -0,0 +1,1848 @@
1
+ /**
2
+ * Wire-level enums and shapes of the Sekyro AI partner API (`/api/v2`). These
3
+ * mirror the backend's frozen partner contract; they are plain string unions so
4
+ * a newer API value never throws at runtime — it simply widens the type in the
5
+ * next SDK release.
6
+ *
7
+ * @packageDocumentation
8
+ */
9
+ /** Session lifecycle status. @public */
10
+ type SessionStatus = "created" | "in_progress" | "review_pending" | "completed" | "expired" | "failed";
11
+ /**
12
+ * Terminal verdict, orthogonal to {@link SessionStatus}. `null` until the session
13
+ * reaches a terminal status; `review` when a human reviewer must adjudicate.
14
+ * `superseded` (status `completed`): the session waited for a review and a newer
15
+ * attempt of the same person took that review over (`session.superseded`); read
16
+ * the newer session for the verdict.
17
+ * @public
18
+ */
19
+ type SessionOutcome = "approved" | "review" | "rejected" | "superseded";
20
+ /**
21
+ * What a finished session proved: `1` a live, real person (human), `2` that
22
+ * person's identity (document, chip, registry or supplied data bound to the
23
+ * face), `3` an identity corroborated by an independent source. `0` on a
24
+ * rejected session.
25
+ * @public
26
+ */
27
+ type VerificationLevel = 0 | 1 | 2 | 3;
28
+ /**
29
+ * How a session's {@link VerificationLevel} was proved: `live_only` (liveness
30
+ * only), `live_unique` (liveness plus a duplicate search), and the
31
+ * `*_biometric` values, where a face match bound the person to a document,
32
+ * its chip, the registry record or partner-supplied identity data, and
33
+ * `eid_authenticated`, where the person signed in with a national digital
34
+ * identity (level 3 without a Sekyro selfie).
35
+ * @public
36
+ */
37
+ type VerificationAssurance = "live_only" | "live_unique" | "document_biometric" | "chip_biometric" | "registry_biometric" | "supplied_biometric" | "eid_authenticated";
38
+ /** The one billing unit a finished session consumed. @public */
39
+ type VerificationUnit = "human_verification" | "identity_verification";
40
+ /** The lowest and highest {@link VerificationLevel} the session's flow can reach. @public */
41
+ interface LevelTarget {
42
+ min: VerificationLevel;
43
+ max: VerificationLevel;
44
+ }
45
+ /**
46
+ * Device and network risk facts of a finished session (booleans and a level
47
+ * word, never scores).
48
+ * @public
49
+ */
50
+ interface ResultRisk {
51
+ level: "low" | "medium" | "high";
52
+ vpn: boolean;
53
+ ipDocumentMismatch: boolean;
54
+ deviceTampered: boolean;
55
+ }
56
+ /**
57
+ * What the liveness step verified about the capture itself: the device
58
+ * attestation, the capture proof and the injection signals.
59
+ * @public
60
+ */
61
+ interface ResultCheckProofs {
62
+ attestation: "verified" | "missing" | "failed";
63
+ captureProof: "verified" | "missing";
64
+ injectionSignals: "clear" | "flagged";
65
+ }
66
+ /**
67
+ * How a session proved the person's minimum age: `estimated` (the age check
68
+ * (selfie) step estimated the face over the threshold by a safety margin), or
69
+ * from identity data: `document`, `chip`, `registry` or `eid`.
70
+ * @public
71
+ */
72
+ type AgeMethod = "estimated" | "document" | "chip" | "registry" | "eid";
73
+ /**
74
+ * The age answer of a session whose flow sets a minimum age. `over` is the
75
+ * flow's minimum age (the threshold), never the person's age. `estimate`
76
+ * (years, one decimal) and `sigma` (its spread in years) are present only on
77
+ * the API session and webhooks, and only when the age check (selfie) step's
78
+ * "Keep and show the estimated age" setting is on; the result token never
79
+ * carries them.
80
+ * @public
81
+ */
82
+ interface AgeResult {
83
+ over: number;
84
+ method: AgeMethod;
85
+ estimate?: number;
86
+ sigma?: number;
87
+ }
88
+ /** Another subject the person's face already matched (duplicate search). @public */
89
+ interface ResultDuplicate {
90
+ subjectId: string;
91
+ externalRef?: string;
92
+ }
93
+ /**
94
+ * How a `subject.reuse` session runs: `recheck` verifies the same person
95
+ * again (liveness and face match against the stored photo), `step_up` raises
96
+ * the subject to identity level with a flow that proves level 2 on every path.
97
+ * @public
98
+ */
99
+ type SubjectReuseMode = "recheck" | "step_up";
100
+ /**
101
+ * Where the hosted flow sends the person when the session ends: an `https`
102
+ * URL on one of the app's web origins, or the app's `sekyro-<slug>://` scheme.
103
+ * `state` (up to 256 characters) is echoed back on the redirect.
104
+ * @public
105
+ */
106
+ interface SessionLinkInput {
107
+ returnUrl?: string;
108
+ state?: string;
109
+ }
110
+ /**
111
+ * How the person proves their identity on an optional-document app: type the
112
+ * national number, or photograph the document (`document_chip`: native NFC clients only).
113
+ * `national_eid`: the country's national eID (e.g. Houwiyeti for Mauritania),
114
+ * offered when the app's profile turns the national eID on.
115
+ * @public
116
+ */
117
+ type IdentityMethod = "national_number" | "document_photo" | "document_chip" | "national_eid";
118
+ /** The verification checks a flow may contain. @public */
119
+ type CheckType = "liveness" | "face_match" | "doc_ocr" | "population_registry" | "phone_otp" | "nfc_chip" | "email_otp" | "portrait_icao" | "eid_auth";
120
+ /** Per-check execution state within a session. @public */
121
+ type CheckState = "pending" | "input_required" | "processing" | "passed" | "failed" | "review" | "skipped";
122
+ /**
123
+ * Why a session was stopped by a profile-v2 policy gate rather than by a
124
+ * failed check:
125
+ * - `location_not_allowed` — the end user's IP location is not allowed for the app;
126
+ * - `anonymizer_blocked` — an anonymizer (VPN / proxy / Tor) was detected while the app blocks them;
127
+ * - `capture_tampered` — the device reported a tampered capture (virtual
128
+ * camera, hooking, emulator…) while the app's `device.tamper` is `block`;
129
+ * - `device_velocity_exceeded` — the device already verified more different
130
+ * people than `device.velocity` allows, with `action: 'block'`;
131
+ * - `device_cooldown` — the device had too many rejected sessions
132
+ * (`cooldown` tiers); {@link Session.retryAfter} says when it may try again.
133
+ * Not billed.
134
+ * @public
135
+ */
136
+ type SessionFailureReason = "location_not_allowed" | "anonymizer_blocked" | "capture_tampered" | "device_velocity_exceeded" | "device_cooldown";
137
+ /**
138
+ * Profile-v2 decision-mode reasons a check's {@link SessionStep.reason} may
139
+ * carry when the app decides automatically (`decisions.mode: 'automatic'`)
140
+ * instead of routing to human review. All are retryable within the step's
141
+ * attempts: `liveness_inconclusive` (liveness middle band),
142
+ * `match_inconclusive` (face match middle band on every reference),
143
+ * `document_authenticity` (doc_ocr authenticity warning — retake the original)
144
+ * and `mobile_required` (liveness captured on a desktop — continue on a phone;
145
+ * not billed). Every inconclusive attempt is billed.
146
+ * @public
147
+ */
148
+ type DecisionReason = "liveness_inconclusive" | "match_inconclusive" | "document_authenticity" | "mobile_required";
149
+ /**
150
+ * Profile-v2 eligibility reasons a check's {@link SessionStep.reason} may carry:
151
+ * `document_type_not_accepted` (doc_ocr; the person may pick another
152
+ * document), `nationality_not_allowed` and `underage` (doc_ocr or
153
+ * population_registry; terminal), and `age_unverifiable` (the app sets a
154
+ * minimum age but the birth date could not be read — doc_ocr: retryable with
155
+ * a clearer photo; population_registry: terminal).
156
+ * @public
157
+ */
158
+ type EligibilityReason = "document_type_not_accepted" | "nationality_not_allowed" | "underage" | "age_unverifiable" | "underage_estimated";
159
+ /**
160
+ * Why a profile-v2 policy ended a session: a session-level
161
+ * {@link SessionFailureReason} (location / anonymizer gate), or the failed
162
+ * check's policy reason — an {@link EligibilityReason} or
163
+ * `document_id_number_mismatch` (the document belongs to someone other than the
164
+ * ID number the session was created for; `document_nni_mismatch` is its former
165
+ * name, still sent until the API switches to the new names), or `camera_unavailable` (spec 2026-10-29 §3.4: the person had no usable camera,
166
+ * so the live step ended without a capture; the session is rejected at level 0 unless your flow has a fallback).
167
+ * @public
168
+ */
169
+ type PolicyFailureReason = SessionFailureReason | EligibilityReason | "document_id_number_mismatch" | "document_nni_mismatch" | "camera_unavailable";
170
+ /**
171
+ * The ID-number reasons a check's {@link SessionStep.reason} may carry (person data
172
+ * spec Appendix A.2), each under its generic name and its former Mauritanian name:
173
+ * `id_number_invalid` (`nni_invalid`: the number fails its country's rule),
174
+ * `registry_record_not_found` (`nni_not_found`: no registry record for the number),
175
+ * `id_number_recheck` (`nni_recheck`: the number must be checked again) and
176
+ * `document_id_number_mismatch` (`document_nni_mismatch`). The API sends the former
177
+ * names until it switches to the generic ones; handle both.
178
+ * @public
179
+ */
180
+ type IdNumberReason = "id_number_invalid" | "nni_invalid" | "registry_record_not_found" | "nni_not_found" | "id_number_recheck" | "nni_recheck" | "document_id_number_mismatch" | "document_nni_mismatch";
181
+ /**
182
+ * Why the person had no camera (spec 2026-10-29 §3.4, 2026-10-30), when the SDK said: `denied` (the
183
+ * person refused camera access) or `no_camera` (no usable camera: none found, an insecure page or a
184
+ * browser that cannot capture). A detail under `failureReason: "camera_unavailable"`, never a reason of its own.
185
+ * @public
186
+ */
187
+ type CameraUnavailableCause = "denied" | "no_camera";
188
+ /**
189
+ * Profile-v2 matching reasons a check's {@link SessionStep.reason} may carry
190
+ * when the data you sent in {@link CreateSessionInput.subject} differs from the
191
+ * reference identity: `name_mismatch`, `birth_date_mismatch`,
192
+ * `nationality_mismatch` (doc_ocr or population_registry) and
193
+ * `document_number_mismatch` (doc_ocr). All are final.
194
+ * @public
195
+ */
196
+ type MatchReason = "name_mismatch" | "birth_date_mismatch" | "nationality_mismatch" | "document_number_mismatch";
197
+ /**
198
+ * Reasons a `face_match` {@link SessionStep.reason} carries when an earlier
199
+ * human review of the same person, reference photo and face settled the match
200
+ * score instead of a new review: `prior_review_approved` (the step passed;
201
+ * final) and `prior_review_rejected` (the step failed; retryable, a better
202
+ * capture sends the session to a reviewer again). Both are billed like
203
+ * `review_band`. The step's {@link SessionStep.decision} has
204
+ * `source: "prior_review"` and names your earlier session.
205
+ * @public
206
+ */
207
+ type PriorReviewReason = "prior_review_approved" | "prior_review_rejected";
208
+ /**
209
+ * Review outcome reasons any reviewable step may carry: `superseded_by_retry`
210
+ * (a newer attempt of the same person took the review over; the session ends
211
+ * with outcome `superseded`) and `review_split` (two reviewers disagreed and
212
+ * nobody settled it before the review deadline; the session is rejected).
213
+ * Both are billed and retryable: the person may verify again. Neither counts
214
+ * toward the device cooldown.
215
+ * @public
216
+ */
217
+ type ReviewOutcomeReason = "superseded_by_retry" | "review_split";
218
+ /**
219
+ * What a review decision is about, on {@link SessionStepDecision.reasons}: the
220
+ * part that failed on a rejection (several may apply), or the check the
221
+ * reviewer overrode on an approval.
222
+ * @public
223
+ */
224
+ type ReviewReason = "document_authenticity" | "liveness" | "face_match" | "data_mismatch" | "other";
225
+ /**
226
+ * How a person decided a step: a reviewer (`source: "review"`), or an earlier
227
+ * review of the same person, reference photo and face that was reused
228
+ * (`source: "prior_review"`). Counts and enums only: never a reviewer's
229
+ * identity and never an individual vote.
230
+ * @public
231
+ */
232
+ interface SessionStepDecision {
233
+ source: "review" | "prior_review";
234
+ /** One reviewer (`single`) or two independent reviewers (`dual`). */
235
+ mode: "single" | "dual";
236
+ /** How many reviewer votes formed the decision (a third vote settles a dual split). */
237
+ votes: 1 | 2 | 3;
238
+ /** Dual review only: whether the first two reviewers agreed. */
239
+ agreement?: boolean;
240
+ /** What the decision was about ({@link ReviewReason}). */
241
+ reasons: ReviewReason[];
242
+ /** ISO 8601: when the decision was made. */
243
+ decidedAt: string;
244
+ /** `prior_review` only: your earlier session whose review decided this one. */
245
+ sessionId?: string;
246
+ }
247
+ /**
248
+ * A failure identification match (terminal sessions, when the flow's
249
+ * identify-failures setting is on and the search found one): who the face
250
+ * matches when the face match did not prove the claimed identity against a
251
+ * registry portrait. A signal, never a decision: the session state is
252
+ * unchanged. Ids, enums and numbers only, never a name or an ID number.
253
+ *
254
+ * `kind`: `presenter` (the live person is most likely the matched record),
255
+ * `shown_face` (the photo or screen shown carries the matched record, a
256
+ * possible victim) or `other_identity`. `other_identity` is informational
257
+ * only: the registry also knows this face under another record. The person may
258
+ * legitimately hold more than one identity document, for example a foreign
259
+ * passport, an older document, a second nationality or a residence permit. Do
260
+ * not treat this signal alone as fraud: use it as a lead for your own process.
261
+ * @public
262
+ */
263
+ interface FailureIdentification {
264
+ kind: "presenter" | "shown_face" | "other_identity";
265
+ /** The search scope: your verified persons (`org`) or the whole registry index (`registry`). */
266
+ scope: "org" | "registry";
267
+ match: {
268
+ /** Your verified subject for the matched person, when you hold one. */
269
+ subjectId?: string;
270
+ /** An opaque reference of the matched person when you hold no verified subject for it, scoped to your organisation. */
271
+ reference?: string;
272
+ /** The registry photo that matched (an opaque id, scoped to your organisation). */
273
+ photoId?: string;
274
+ /** The grade of that photo: `1` or `2` registry, `3` an older bulk import photo. */
275
+ tier: 1 | 2 | 3;
276
+ /** Calibrated similarity on the face match scale, in [0, 1]. */
277
+ score: number;
278
+ band: "strong" | "moderate";
279
+ };
280
+ /** With `other_identity`: the reference the session passed against. */
281
+ referenceSource?: "registry" | "chip" | "document" | "subject" | "org_supplied";
282
+ }
283
+ /**
284
+ * Face-match probe-binding reason a `face_match` {@link SessionStep.reason} may
285
+ * carry (SDK spec §4.10): `probe_not_from_liveness` — the face image isn't the
286
+ * person in the liveness clip. Retryable within the step's attempts (the
287
+ * person re-takes the liveness capture); billed.
288
+ * @public
289
+ */
290
+ type ProbeBindingReason = "probe_not_from_liveness";
291
+ /**
292
+ * The languages the person being verified sees (hosted flow and SDK screens; spec 2026-10-29 §9). `ar`, `fr` and `en`
293
+ * carry every screen; `es`, `pt` and `de` carry the Human verification screens and show English elsewhere. SMS and
294
+ * email messages stay in `ar`, `fr` or `en` (English for the three others).
295
+ * @public
296
+ */
297
+ type Locale = "ar" | "fr" | "en" | "es" | "pt" | "de";
298
+ /** The environment a webhook was emitted from. @public */
299
+ type SekyroEnvironment = "sandbox" | "live";
300
+ /**
301
+ * One check of a session, as the partner API projects it: enum/id fields only,
302
+ * never civil data.
303
+ * @public
304
+ */
305
+ interface SessionStep {
306
+ checkType: CheckType;
307
+ state: CheckState;
308
+ /** Sekyro flows: the flow node this check belongs to (e.g. `n_live`). */
309
+ nodeId?: string;
310
+ /** Sekyro flows: the service of that node. */
311
+ service?: ServiceId;
312
+ /** Sekyro flows: the check failed and the flow's fallback took over. */
313
+ handled?: true;
314
+ /** Machine-readable failure/review reason, when the check has one. */
315
+ reason?: string;
316
+ /** With reason `camera_unavailable`: why, when the SDK said (`denied` or `no_camera`). */
317
+ reasonDetail?: CameraUnavailableCause;
318
+ /** Calibrated model score in [0, 1] for scored checks (liveness, face match). */
319
+ calibratedScore?: number;
320
+ /** The check failed after using all of its attempts. */
321
+ attemptsExhausted?: boolean;
322
+ /**
323
+ * `portrait_icao` only (ID mode): the per-criterion ICAO report of the last
324
+ * attempt — numbers and enums only, never the image.
325
+ */
326
+ report?: PortraitReportEntry[];
327
+ /**
328
+ * `face_match` only: the probe-quality measurement of the selfie that was
329
+ * matched (occlusion, head pose, eye openness, sharpness). Recorded for
330
+ * information only: it never changes the step's state or reason.
331
+ */
332
+ probeQuality?: ProbeQuality;
333
+ /**
334
+ * How a person decided this step ({@link SessionStepDecision}); absent when
335
+ * no person decided it.
336
+ */
337
+ decision?: SessionStepDecision;
338
+ }
339
+ /**
340
+ * The probe-quality measurement on a `face_match` step. Numbers only; `null`
341
+ * means the value could not be measured. Informational: no threshold applies.
342
+ * @public
343
+ */
344
+ interface ProbeQuality {
345
+ /** Share of the inner face that is covered (a hand, a mask, a phone), in [0, 1]. */
346
+ occlusion: number | null;
347
+ /** Head pose in degrees. */
348
+ pose: {
349
+ yaw: number | null;
350
+ pitch: number | null;
351
+ roll: number | null;
352
+ };
353
+ /** Openness of the less-open eye, in [0, 1]. */
354
+ eyesOpen: number | null;
355
+ /** Sharpness of the face region (higher is sharper; no fixed scale). */
356
+ sharpness: number | null;
357
+ }
358
+ /**
359
+ * One row of the `portrait_icao` report (ID mode): the server's measurement of
360
+ * one ICAO criterion and the threshold that applied.
361
+ * @public
362
+ */
363
+ interface PortraitReportEntry {
364
+ criterion: "pose" | "eyes" | "mouth" | "occlusion" | "glare" | "lighting" | "background" | "resolution";
365
+ value: number | null;
366
+ threshold: number | string | null;
367
+ pass: boolean;
368
+ }
369
+ /**
370
+ * A short-lived link to a session's ICAO portrait (480×640 JPEG), from
371
+ * {@link SessionsApi.portrait}. Download it before `expiresAt`; never store the URL.
372
+ * @public
373
+ */
374
+ interface SessionPortraitLink {
375
+ url: string;
376
+ /** ISO 8601 (about 5 minutes after the call). */
377
+ expiresAt: string;
378
+ }
379
+ /**
380
+ * Out-of-band delivery of the session's hosted link, sent by Sekyro AI after the
381
+ * session is created. Best effort: a failed send never fails the create.
382
+ * @public
383
+ */
384
+ interface DeliverOptions {
385
+ /** Delivery channel. */
386
+ channel: "sms" | "whatsapp";
387
+ /** E.164 phone number of the recipient (`+` and the country code). */
388
+ to: string;
389
+ }
390
+ /**
391
+ * An ID number of the person (person data spec §4.1): the document type, the
392
+ * issuing country (ISO 3166-1 alpha-2; alpha-3 is accepted and normalized) and
393
+ * the number (1 to 40 characters, then the issuing country's rule, e.g. the
394
+ * check digit of a Mauritanian national ID number).
395
+ * @public
396
+ */
397
+ interface SubjectIdNumber {
398
+ type: "national_id" | "passport" | "residence_permit";
399
+ issuingCountry: string;
400
+ number: string;
401
+ }
402
+ /**
403
+ * The person's name in one script (ISO 15924 code, e.g. `Latn` or `Arab`).
404
+ * @public
405
+ */
406
+ interface SubjectName {
407
+ script: string;
408
+ /** 1 to 100 characters. */
409
+ given: string;
410
+ /** 1 to 100 characters. */
411
+ family: string;
412
+ /** Optional, 1 to 100 characters. */
413
+ patronymic?: string;
414
+ }
415
+ /**
416
+ * What you already know about the person (`subject` at session create). A
417
+ * closed object: unknown keys are refused (`400`). Every field is optional;
418
+ * `null` or blank counts as absent.
419
+ *
420
+ * The flow decides whether these are checked or believed: in a flow that checks
421
+ * identity from a document or a registry, they are a prefill compared with what
422
+ * the person shows; in a flow that verifies identity from your data (the
423
+ * response's `subjectUse: "reference"`), `idNumber`, `birthDate`, `photo` and
424
+ * `fetchedAt` are required and the record is the reference. `idNumber` binds the
425
+ * session to that identity in both cases: the hosted flow may omit it but cannot
426
+ * substitute another number.
427
+ * @public
428
+ */
429
+ interface SessionSubjectInput {
430
+ /** The person's ID number. Binds the session. */
431
+ idNumber?: SubjectIdNumber;
432
+ /**
433
+ * @deprecated Use `idNumber: { type: "national_id", issuingCountry: "MR", number }`.
434
+ * A Mauritanian national ID number (10 digits), as a string.
435
+ */
436
+ nni?: string;
437
+ /** E.164 phone number (`+` and the country code). */
438
+ phone?: string;
439
+ /** Email address, for the email OTP step. */
440
+ email?: string;
441
+ /** Full name, 1 to 200 characters, any script. */
442
+ fullName?: string;
443
+ /** The name per script, at most 4 entries, one per script. */
444
+ names?: SubjectName[];
445
+ /** ISO 8601 date (`YYYY-MM-DD`). */
446
+ birthDate?: string;
447
+ /** Place of birth, 1 to 120 characters, any script (kept only with a reference record). */
448
+ birthPlace?: string;
449
+ /** `M`, `F` or `X` (ICAO 9303 values; kept only with a reference record). */
450
+ sex?: "M" | "F" | "X";
451
+ /** ISO 3166-1 alpha-2. */
452
+ nationality?: string;
453
+ /**
454
+ * @deprecated Use `idNumber` with the document's `type` and `issuingCountry`.
455
+ * Identity-document number (1 to 40 characters).
456
+ */
457
+ documentNumber?: string;
458
+ /**
459
+ * Base64 JPEG or PNG (optional data-URL prefix, at most 1 MB decoded): the
460
+ * face-match reference of a reference record. Refused in a flow that uses the
461
+ * data as a prefill (`422 subject_photo_not_used`).
462
+ */
463
+ photo?: string;
464
+ /** ISO 8601 date (`YYYY-MM-DD`) of the photo. */
465
+ photoDate?: string;
466
+ /**
467
+ * ISO 8601 date-time: when YOUR system obtained this data. Required with a
468
+ * reference record; at most 24 h old (`422 subject_record_stale`).
469
+ */
470
+ fetchedAt?: string;
471
+ /**
472
+ * Your own id for this person (1–128 characters). Echoed on the session and
473
+ * its webhooks, and searchable on the subjects API.
474
+ */
475
+ externalRef?: string;
476
+ /**
477
+ * Returning user (profile v2 step 5): verify this already-verified subject
478
+ * again with liveness + face match only, against the reference photo stored
479
+ * on the subject. Name exactly one target. Errors at create:
480
+ * `404 subject_not_found`, `409 subject_revoked`, `409 subject_no_reference`,
481
+ * `409 subject_stale` (older than the flow's `returning.maxAgeMonths`),
482
+ * `409 reuse_disabled` (the flow turns returning-user sessions off) and
483
+ * `400` / `409 reuse_target_ambiguous`.
484
+ */
485
+ reuse?: SubjectReuseTarget;
486
+ }
487
+ /**
488
+ * An identity document for {@link SubjectReuseTarget}: the document type, the
489
+ * issuing country (ISO 3166-1 alpha-2 or alpha-3) and its number.
490
+ * @public
491
+ */
492
+ interface SubjectReuseDocument {
493
+ type: "national_id" | "passport" | "residence_permit";
494
+ issuingCountry: string;
495
+ number: string;
496
+ }
497
+ /**
498
+ * Which subject a returning-user session re-verifies: exactly ONE of the
499
+ * subject id, your own `externalRef` (must match a single subject) or the
500
+ * `idNumber` the person verified with. `nni` and `document` are the deprecated
501
+ * names of the `idNumber` target: an `nni` is an `idNumber` of type
502
+ * `national_id` issued by `MR`; a `document` has the same three parts.
503
+ * @public
504
+ */
505
+ type SubjectReuseTarget = ({
506
+ subjectId: string;
507
+ externalRef?: never;
508
+ nni?: never;
509
+ document?: never;
510
+ idNumber?: never;
511
+ } | {
512
+ externalRef: string;
513
+ subjectId?: never;
514
+ nni?: never;
515
+ document?: never;
516
+ idNumber?: never;
517
+ } | {
518
+ /** @deprecated Use `idNumber` with type `national_id` and issuing country `MR`. */
519
+ nni: string;
520
+ subjectId?: never;
521
+ externalRef?: never;
522
+ document?: never;
523
+ idNumber?: never;
524
+ } | {
525
+ /** @deprecated Use `idNumber` (the same three parts). */
526
+ document: SubjectReuseDocument;
527
+ subjectId?: never;
528
+ externalRef?: never;
529
+ nni?: never;
530
+ idNumber?: never;
531
+ } | {
532
+ idNumber: SubjectIdNumber;
533
+ subjectId?: never;
534
+ externalRef?: never;
535
+ nni?: never;
536
+ document?: never;
537
+ }) & {
538
+ /**
539
+ * `recheck` (default) or `step_up` ({@link SubjectReuseMode}). `step_up` on
540
+ * a flow that does not prove level 2 on every path answers
541
+ * `400 step_up_flow_too_weak`.
542
+ */
543
+ mode?: SubjectReuseMode;
544
+ };
545
+ /** A document type the backend reads (kyc-docs-v2 vocabulary; `carte_identite` = identity card of any issuer). @public */
546
+ type ProfileDocumentType = "carte_identite" | "passport" | "residence_permit";
547
+ /**
548
+ * The services a Sekyro flow is built from. A session's steps
549
+ * ({@link SessionStep.service}) and {@link FlowOverrides.services} use these
550
+ * ids; one service may run several checks (e.g. `liveness` with an ICAO
551
+ * portrait).
552
+ * @public
553
+ */
554
+ type ServiceId = "device_network" | "phone_otp" | "email_otp" | "national_eid" | "document" | "nfc" | "population_registry" | "supplied_identity" | "summary_confirm" | "liveness" | "face_match" | "aml_screening" | "face_dedup" | "age_estimation";
555
+ /**
556
+ * The general settings of a flow that a session may override (the flow's
557
+ * `link`, `language` and override policy are not overridable). Country codes
558
+ * are ISO 3166-1 alpha-2 (`MR`). Used through {@link FlowOverrides.settings}.
559
+ * @public
560
+ */
561
+ interface FlowOverridableSettings {
562
+ /** Who may be verified. */
563
+ eligibility: {
564
+ /** Accepted nationalities: `'*'` or a list, optionally per IP location. */
565
+ nationalities: {
566
+ default: "*" | string[];
567
+ byLocation?: Record<string, "*" | string[]>;
568
+ };
569
+ /** Minimum age in years (1–120), or `null` for none. */
570
+ minAge: number | null;
571
+ };
572
+ /** Automatic decisions instead of human review (`retryConfidentRejects` lets confident rejects retry). */
573
+ decisions?: {
574
+ mode: "automatic" | "review";
575
+ retryConfidentRejects: boolean;
576
+ };
577
+ /** Data consistency across sources. */
578
+ fraud: {
579
+ /** Comparison of your `subject` data with the reference identity. */
580
+ nameMatch?: {
581
+ level: "strict" | "standard" | "lenient";
582
+ onMismatch: "fail" | "signal";
583
+ };
584
+ };
585
+ /** Returning-user sessions (`subject.reuse`). */
586
+ returning: {
587
+ /** `false`: returning-user sessions are refused (`409 reuse_disabled`). */
588
+ enabled: boolean;
589
+ /** Maximum age in months (1–120) of the subject's last verification; `null` = no limit. */
590
+ maxAgeMonths: number | null;
591
+ };
592
+ /** Identity-document rules. */
593
+ documents: {
594
+ /** Accepted document types: `'*'` (all) or a list, optionally per issuing country. */
595
+ accepted: {
596
+ default: "*" | ProfileDocumentType[];
597
+ byIssuer?: Record<string, ProfileDocumentType[]>;
598
+ };
599
+ /** Expired documents: refused, allowed, or allowed for `graceDays` (1–365) after expiry. */
600
+ expired: "reject" | "allow" | {
601
+ graceDays: number;
602
+ };
603
+ authenticity: "standard" | "off";
604
+ };
605
+ }
606
+ /**
607
+ * Document substitution: the portrait a `document` or `nfc` step produces is
608
+ * compared with the registry portrait (or the chip with the printed photo).
609
+ * `signal` records a risk signal on a clear mismatch, `review` also sends the
610
+ * session to review, `off` compares nothing. `failBelow` is the mismatch bound
611
+ * in (0, 1), absent = the platform bound.
612
+ * @public
613
+ */
614
+ interface DocumentSubstitutionSettings {
615
+ mode: "off" | "signal" | "review";
616
+ failBelow?: number;
617
+ }
618
+ /**
619
+ * The per-service settings a session may override, by {@link ServiceId}.
620
+ * `attempts` limits are per step (absent = the platform default).
621
+ * @public
622
+ */
623
+ interface FlowServiceSettings {
624
+ /** Device & Network Intelligence: IP location, anonymizers, cooldown, device and capture postures. */
625
+ device_network: {
626
+ /** Where the end user may be (IP location). */
627
+ locations: {
628
+ mode: "all";
629
+ } | {
630
+ mode: "only" | "all_except";
631
+ countries: string[];
632
+ };
633
+ /** VPN / proxy / Tor. */
634
+ anonymizers: "allow" | "block";
635
+ /** Device cooldown after repeated rejections (at most 5 tiers; `[]` = off). */
636
+ cooldown?: {
637
+ tiers: Array<{
638
+ rejectedSessions: number;
639
+ windowHours: number;
640
+ waitMinutes: number;
641
+ }>;
642
+ };
643
+ /** Device tamper and velocity actions. */
644
+ device?: {
645
+ tamper: "block" | "signal";
646
+ velocity: {
647
+ maxIdentitiesPerDevice: number;
648
+ windowDays: number;
649
+ action: "signal" | "block";
650
+ };
651
+ };
652
+ attestation?: "off" | "signal" | "enforce";
653
+ captureIntegrity?: "off" | "signal" | "enforce";
654
+ };
655
+ phone_otp: {
656
+ /** Where the number comes from: your `subject.phone` / `input.phone`, the person, or either. */
657
+ numberSource: "prefilled" | "user_entered" | "prefilled_or_entered";
658
+ /** Narrow the channels the person may choose from (absent = every channel the org has on). */
659
+ channels?: Array<"whatsapp" | "sms">;
660
+ /** Which countries codes may be sent to (absent = the flow's allowed `locations`). */
661
+ destinations?: "locations" | "any" | {
662
+ countries: string[];
663
+ };
664
+ attempts?: number;
665
+ };
666
+ email_otp: {
667
+ /** Where the address comes from: your `input.email`, the person, or either. */
668
+ emailSource: "prefilled" | "user_entered" | "prefilled_or_entered";
669
+ /** Disposable (temporary) addresses: allowed, flagged as a risk signal (default), or refused. */
670
+ disposable?: "allow" | "signal" | "block";
671
+ attempts?: number;
672
+ };
673
+ national_eid: {
674
+ /**
675
+ * `'org'` (every national eID the org can use, resolved at session create)
676
+ * or provider ids (`{country}.{provider}`, e.g. `MR.houwiyeti`).
677
+ */
678
+ providers: "org" | string[];
679
+ /** The eID portrait is the face-match reference. */
680
+ portraitReference: boolean;
681
+ };
682
+ document: {
683
+ attempts?: number;
684
+ /** Compare the document photo with the registry photo (absent = the platform default). */
685
+ documentSubstitution?: DocumentSubstitutionSettings;
686
+ };
687
+ /** The chip read (its MRZ source is derived from the flow and is not overridable). */
688
+ nfc: {
689
+ maxAttempts?: number;
690
+ /** Compare the chip photo with the registry photo (absent = the platform default). */
691
+ documentSubstitution?: DocumentSubstitutionSettings;
692
+ };
693
+ population_registry: {
694
+ /** `'org'` (every registry the org can use, resolved at session create) or registry ids. */
695
+ sources: "org" | Array<"MR.anrpts">;
696
+ /**
697
+ * @deprecated Use `idNumberSource` (same values). Both with different values is
698
+ * `400 override_invalid`.
699
+ */
700
+ nniSource: "auto" | "typed" | "bound_only";
701
+ /** Where the ID number comes from: `auto`, `typed` (the person types it) or `bound_only` (your `subject.idNumber`). */
702
+ idNumberSource: "auto" | "typed" | "bound_only";
703
+ onUncovered: "skip";
704
+ attempts?: number;
705
+ };
706
+ supplied_identity: Record<string, never>;
707
+ summary_confirm: {
708
+ /** Offer « Reprendre » (re-open the identity source). */
709
+ retake: boolean;
710
+ };
711
+ liveness: {
712
+ /** `off`, selfie ICAO `alert` / `reject`, or `id_document` (ID-photo portrait, always rejects). */
713
+ icao: "off" | "alert" | "reject" | "id_document";
714
+ attempts?: number;
715
+ };
716
+ face_match: {
717
+ reference: "auto" | "document" | "registry";
718
+ attempts?: number;
719
+ };
720
+ aml_screening: {
721
+ lists: Array<"sanctions" | "pep" | "adverse_media">;
722
+ onHit: "review" | "fail";
723
+ };
724
+ face_dedup: {
725
+ scope: "app" | "org";
726
+ onDuplicate: "review" | "fail";
727
+ };
728
+ /** The age check (selfie); the threshold is the flow's `eligibility.minAge`. */
729
+ age_estimation: {
730
+ /** Keep and show the estimated age ({@link AgeResult.estimate}) on the API session and webhooks. Default `false`. */
731
+ showEstimatedAge?: boolean;
732
+ };
733
+ }
734
+ /**
735
+ * `T` with every property optional, recursively. Arrays are replaced as a
736
+ * whole, never merged element by element.
737
+ * @public
738
+ */
739
+ type DeepPartial<T> = T extends readonly unknown[] ? T : T extends object ? {
740
+ [K in keyof T]?: DeepPartial<T[K]>;
741
+ } : T;
742
+ /**
743
+ * A per-session override of the flow ({@link CreateSessionInput.overrides}).
744
+ *
745
+ * - `settings`: any subset of {@link FlowOverridableSettings}, at any depth.
746
+ * - `services`: keyed by service (applied to every node of that service): any
747
+ * subset of its {@link FlowServiceSettings}, or `'off'` to remove it from
748
+ * the flow. A service the flow does not use is ignored.
749
+ *
750
+ * Objects merge into the flow; arrays and scalar values replace. Unknown keys
751
+ * and invalid results answer `400 override_invalid`. An override may only
752
+ * make the flow stricter unless the flow allows widening; turning a service
753
+ * `'off'` always widens. A widening change answers `403 override_widens_flow`.
754
+ * The changed paths are reported on {@link Session.overriddenFields}.
755
+ *
756
+ * @example
757
+ * ```ts
758
+ * await sekyro.sessions.create({
759
+ * flow: "foreigners",
760
+ * overrides: {
761
+ * settings: { eligibility: { minAge: 21 } },
762
+ * services: { liveness: { attempts: 2 } },
763
+ * },
764
+ * });
765
+ * ```
766
+ * @public
767
+ */
768
+ interface FlowOverrides {
769
+ settings?: DeepPartial<FlowOverridableSettings>;
770
+ services?: {
771
+ [S in ServiceId]?: DeepPartial<FlowServiceSettings[S]> | "off";
772
+ };
773
+ }
774
+ /**
775
+ * The flow version a session runs: its `flw_` id, its slug and the published
776
+ * version pinned at create.
777
+ * @public
778
+ */
779
+ interface SessionFlowRef {
780
+ id: string;
781
+ slug: string;
782
+ version: number;
783
+ }
784
+ /**
785
+ * One flow of your app, from {@link Sekyro.listFlows}. Published flows only;
786
+ * pass `slug` or `id` as {@link CreateSessionInput.flow}.
787
+ * @public
788
+ */
789
+ interface FlowSummary {
790
+ /** `flw_` id. */
791
+ id: string;
792
+ slug: string;
793
+ name: string;
794
+ /** The published version a new session runs. */
795
+ version: number;
796
+ /** The flow a session runs when you send no `flow`. */
797
+ isDefault: boolean;
798
+ }
799
+ /**
800
+ * Input of {@link SessionsApi.create}. The API key belongs to an app; the
801
+ * app's flow (its default flow, or the one named in `flow`) decides the steps.
802
+ * @public
803
+ */
804
+ interface CreateSessionInput {
805
+ /**
806
+ * The app's flow to run: its slug (e.g. `foreigners`) or `flw_` id, as
807
+ * {@link Sekyro.listFlows} lists them. Absent = the app's default flow.
808
+ * Errors: `404 flow_not_found` (no such flow in the key's app),
809
+ * `409 flow_not_published`, `409 flow_archived`.
810
+ */
811
+ flow?: string;
812
+ /** Pins the hosted-flow language. Omit to let the person's device decide. */
813
+ locale?: Locale;
814
+ /**
815
+ * Pre-choose the identity method when the flow offers a choice of identity
816
+ * method (the hosted choice screen is then skipped). Ignored otherwise.
817
+ */
818
+ identityMethod?: IdentityMethod;
819
+ /**
820
+ * Session lifetime in minutes. Must fall within the flow's link range,
821
+ * otherwise the API answers `400 ttl_out_of_policy`. Omit to use the
822
+ * flow's default.
823
+ */
824
+ ttlMinutes?: number;
825
+ /** Also send the hosted link to the person by SMS or WhatsApp. */
826
+ deliver?: DeliverOptions;
827
+ /**
828
+ * Where the hosted flow returns the person when the session ends
829
+ * ({@link SessionLinkInput}). A URL outside the app's web origins and app
830
+ * scheme answers `400 return_url_not_allowed`.
831
+ */
832
+ link?: SessionLinkInput;
833
+ /**
834
+ * What you already know about the person (preferred over `input` for
835
+ * identity data). A key sent in both `subject` and `input` with different
836
+ * values answers `400 subject_input_conflict`.
837
+ */
838
+ subject?: SessionSubjectInput;
839
+ /**
840
+ * Your own id for the agent filming the person, for flows whose liveness
841
+ * capture is `assisted` (1 to 128 characters). Stored as is and echoed on
842
+ * the session and in webhooks.
843
+ */
844
+ assistedBy?: {
845
+ externalRef: string;
846
+ };
847
+ /**
848
+ * Override the flow for this session only ({@link FlowOverrides}): its
849
+ * general settings and per-service settings, or turn a service `'off'`.
850
+ * `400 override_invalid` for an unknown key or an invalid result;
851
+ * `403 override_widens_flow` for a change that makes the flow less strict
852
+ * when the flow does not allow widening.
853
+ */
854
+ overrides?: FlowOverrides;
855
+ /**
856
+ * Step inputs consumed server-side: an open record of branch facts your flow's
857
+ * conditions read. The person keys below are deprecated: send them in
858
+ * {@link CreateSessionInput.subject} (the response's `warnings` names each one
859
+ * you used). Values are strings (a number is a string, never a JSON number).
860
+ */
861
+ input?: {
862
+ /**
863
+ * @deprecated Use `subject.idNumber: { type: "national_id", issuingCountry: "MR", number }`.
864
+ * A Mauritanian national ID number (10 digits), as a string.
865
+ */
866
+ nni?: string;
867
+ /** @deprecated Use `subject.phone`. E.164 phone number. */
868
+ phone?: string;
869
+ /** @deprecated Use `subject.email`. Email address for the email OTP step. */
870
+ email?: string;
871
+ /** @deprecated Use `subject.fullName`. */
872
+ fullName?: string;
873
+ /** @deprecated Use `subject.birthDate`. ISO 8601 date (`YYYY-MM-DD`). */
874
+ birthDate?: string;
875
+ /**
876
+ * @deprecated Use the reference keys of `subject` (`idNumber`, `names`,
877
+ * `birthDate`, `photo`, `fetchedAt`, ...), for example from
878
+ * {@link subjectFromNationalRegistry}.
879
+ * Partner-supplied identity data (`supplied` mode only).
880
+ */
881
+ suppliedIdentity?: SuppliedIdentityRecord;
882
+ } & Record<string, unknown>;
883
+ }
884
+ /**
885
+ * @deprecated Send the record in `subject` instead (`idNumber`, `names`,
886
+ * `birthDate`, `birthPlace`, `sex`, `nationality`, `photo`, `photoDate`,
887
+ * `fetchedAt`), for example from {@link subjectFromNationalRegistry}.
888
+ *
889
+ * Partner-supplied identity data (`sessions.create` `input.suppliedIdentity`):
890
+ * the person's biographic record and photo, as your organization holds them.
891
+ * Refusals at create: `400 supplied_identity_nni_mismatch`,
892
+ * `422 supplied_identity_stale` (`fetchedAt` older than 24 h),
893
+ * `422 supplied_identity_photo_unusable` (not a JPEG/PNG of at most 1 MB within the
894
+ * size bounds).
895
+ * @public
896
+ */
897
+ interface SuppliedIdentityRecord {
898
+ /** 10-digit national ID number, as a string. */
899
+ nni: string;
900
+ firstNameFr: string;
901
+ lastNameFr: string;
902
+ fatherNameFr?: string;
903
+ firstNameAr: string;
904
+ lastNameAr: string;
905
+ fatherNameAr?: string;
906
+ /** ISO 8601 date (`YYYY-MM-DD`). */
907
+ birthDate: string;
908
+ birthPlaceFr?: string;
909
+ birthPlaceAr?: string;
910
+ sex?: "M" | "F";
911
+ /** Nationality text as your source holds it. */
912
+ nationalities?: string[];
913
+ /** Base64 JPEG or PNG (at most 1 MB decoded). */
914
+ photo: string;
915
+ /** ISO 8601 date (`YYYY-MM-DD`) of the registry photo. */
916
+ photoDate?: string;
917
+ /** ISO 8601 date-time at which your system obtained this record. */
918
+ fetchedAt: string;
919
+ }
920
+ /** Per-request options. @public */
921
+ interface RequestOptions {
922
+ /**
923
+ * Sent as `X-Idempotency-Key`. Replaying the same key within 24 h returns the
924
+ * original response instead of creating a second session.
925
+ */
926
+ idempotencyKey?: string;
927
+ }
928
+ /**
929
+ * Result of {@link SessionsApi.create}. `clientToken` is returned ONCE and never
930
+ * again — hand it to the browser (`@sekyro/web`) and do not persist it.
931
+ * @public
932
+ */
933
+ interface CreatedSession {
934
+ id: string;
935
+ status: SessionStatus;
936
+ /** One-time credential for the client SDK / hosted flow. */
937
+ clientToken: string;
938
+ /** Hosted verification link for this session. */
939
+ hostedUrl: string;
940
+ /** The flow version the session runs (the default flow when you sent no `flow`). */
941
+ flow?: SessionFlowRef;
942
+ /** The checks on the session's path (checks of a lane not taken are omitted). */
943
+ steps: SessionStep[];
944
+ /** ISO 8601 — when the session (and its link) stop accepting input. */
945
+ expiresAt: string;
946
+ /** The levels the flow can reach on its paths; absent from older API versions. */
947
+ levelTarget?: LevelTarget;
948
+ /**
949
+ * How the flow uses the person data you sent: `reference` (believed, your
950
+ * record is the identity reference) or `prefill` (checked against the
951
+ * person's document or registry record). Absent from older API versions.
952
+ */
953
+ subjectUse?: "reference" | "prefill";
954
+ /** One entry per deprecated request key you used, naming its replacement. Absent otherwise. */
955
+ warnings?: CreatedSessionWarning[];
956
+ }
957
+ /**
958
+ * A deprecation warning of {@link CreatedSession.warnings}: `field` is the
959
+ * deprecated key you sent (e.g. `input.nni`), `replacement` the key to send
960
+ * instead (e.g. `subject.idNumber`).
961
+ * @public
962
+ */
963
+ interface CreatedSessionWarning {
964
+ code: "deprecated_field";
965
+ field: string;
966
+ replacement: string;
967
+ }
968
+ /**
969
+ * Input of {@link SubjectsApi.createSession}: a re-check or step-up session
970
+ * for an existing subject in one call.
971
+ * @public
972
+ */
973
+ interface SubjectSessionInput {
974
+ mode: SubjectReuseMode;
975
+ /** The app's flow to run (slug or `flw_` id); absent = the app's default flow. */
976
+ flow?: string;
977
+ link?: SessionLinkInput;
978
+ /** Session lifetime in minutes, within the flow's link range. */
979
+ ttlMinutes?: number;
980
+ locale?: Locale;
981
+ }
982
+ /**
983
+ * Which subject {@link SubjectsApi.createSession} targets: the subject id or
984
+ * your own external reference.
985
+ * @public
986
+ */
987
+ type SubjectSessionTarget = {
988
+ subjectId: string;
989
+ } | {
990
+ externalRef: string;
991
+ };
992
+ /** Result of {@link SessionsApi.resultToken}: a freshly signed result token. @public */
993
+ interface ResultTokenResponse {
994
+ /** ES256 JWT; check it with {@link verifyResultToken}. */
995
+ token: string;
996
+ /** ISO 8601: when the token expires (10 minutes after signing). */
997
+ expiresAt: string;
998
+ }
999
+ /**
1000
+ * The end user's network at the start of the session (IP-derived, approximate).
1001
+ * @public
1002
+ */
1003
+ interface SessionNetworkEvent {
1004
+ /** ISO 8601. */
1005
+ at: string;
1006
+ /** ISO 3166-1 alpha-2. */
1007
+ country?: string;
1008
+ region?: string;
1009
+ city?: string;
1010
+ asn?: number;
1011
+ operator?: string;
1012
+ connectionType: "mobile" | "hosting" | "unknown";
1013
+ anonymizer: {
1014
+ vpn: boolean;
1015
+ tor: boolean;
1016
+ hosting: boolean;
1017
+ };
1018
+ /** IANA time zone reported by the end user's device. */
1019
+ browserTimezone?: string;
1020
+ /** True when the device time zone does not belong to the IP country. */
1021
+ timezoneMismatch?: boolean;
1022
+ }
1023
+ /**
1024
+ * End-user network context; absent when not recorded.
1025
+ * @public
1026
+ */
1027
+ interface SessionNetwork {
1028
+ /** The start event's IP address. Never sent in webhooks. */
1029
+ ip?: string;
1030
+ /** True when a later call came from a different country than the start. */
1031
+ countryChanged: boolean;
1032
+ start: SessionNetworkEvent;
1033
+ }
1034
+ /**
1035
+ * Device signals detected on the end user's device.
1036
+ * @public
1037
+ */
1038
+ type SessionDeviceSignal = "webdriver" | "headless" | "emulator" | "rooted" | "jailbroken" | "debugger" | "hooking" | "virtual_camera";
1039
+ /**
1040
+ * End-user device summary; absent when not recorded.
1041
+ * @public
1042
+ */
1043
+ interface SessionDevice {
1044
+ platform: "web" | "android" | "ios";
1045
+ sdk?: string;
1046
+ os?: string;
1047
+ osVersion?: string;
1048
+ browser?: string;
1049
+ browserVersion?: string;
1050
+ deviceClass: "mobile" | "tablet" | "desktop" | "unknown";
1051
+ model?: string;
1052
+ /** Device ids hashed with a key unique to your organization. */
1053
+ deviceKeys: string[];
1054
+ signals: SessionDeviceSignal[];
1055
+ }
1056
+ /**
1057
+ * The national eID that verified the session's identity (the `eid_auth` check
1058
+ * passed): the provider id (`{country}.{provider}`, e.g. `MR.houwiyeti`), its
1059
+ * ISO 3166-1 alpha-2 country and when. A passed eID ends the session.
1060
+ * @public
1061
+ */
1062
+ interface EidResult {
1063
+ provider: string;
1064
+ country: string;
1065
+ verifiedAt: string;
1066
+ }
1067
+ /**
1068
+ * The full phone number and email address the person verified in a session
1069
+ * (an OTP check that passed) — sent ONLY to you (the session view and your
1070
+ * webhooks), never to the person's browser, and removed when the session's
1071
+ * personal data is purged. You are the controller of these values. A
1072
+ * prefilled value that was not verified is never listed.
1073
+ * @public
1074
+ */
1075
+ interface VerifiedContacts {
1076
+ /** From a passed `phone_otp` check. */
1077
+ phone?: {
1078
+ /** E.164 (`+` and the country code). */
1079
+ number: string;
1080
+ /** The channel the code was delivered on. */
1081
+ channel: "whatsapp" | "sms";
1082
+ /** ISO 8601. */
1083
+ verifiedAt: string;
1084
+ };
1085
+ /** From a passed `email_otp` check. */
1086
+ email?: {
1087
+ /** The verified address (domain lowercased). */
1088
+ address: string;
1089
+ /** ISO 8601. */
1090
+ verifiedAt: string;
1091
+ };
1092
+ }
1093
+ /**
1094
+ * The whitelisted session view returned by {@link SessionsApi.get}. Never
1095
+ * contains the client token.
1096
+ * @public
1097
+ */
1098
+ interface Session {
1099
+ id: string;
1100
+ /** Sekyro flows: the flow version the session runs (absent on sessions created before flows). */
1101
+ flow?: SessionFlowRef;
1102
+ status: SessionStatus;
1103
+ outcome: SessionOutcome | null;
1104
+ /**
1105
+ * What the session proved ({@link VerificationLevel}); `null` while the
1106
+ * session is active, `0` when it was rejected. Absent from older API versions.
1107
+ */
1108
+ level?: VerificationLevel | null;
1109
+ /** How the level was proved; `null` while the session is active. */
1110
+ assurance?: VerificationAssurance | null;
1111
+ /** The billing unit the session consumed; `null` while the session is active. */
1112
+ unit?: VerificationUnit | null;
1113
+ /** The levels the session's flow can reach. */
1114
+ levelTarget?: LevelTarget;
1115
+ /** The checks on the session's path (checks of a lane the person did not take are omitted). */
1116
+ steps: SessionStep[];
1117
+ /** ISO 8601. */
1118
+ expiresAt: string;
1119
+ /** ISO 8601. */
1120
+ createdAt: string;
1121
+ /** ISO 8601: when the session reached a terminal state; `null` while it is active. */
1122
+ completedAt?: string | null;
1123
+ /** End-user network context; absent when not recorded. */
1124
+ network?: SessionNetwork;
1125
+ /** End-user device; absent when not recorded. */
1126
+ device?: SessionDevice;
1127
+ /**
1128
+ * Set when a profile-v2 policy ended the session: a session-level gate
1129
+ * (location, anonymizer) or a failed check's policy reason (eligibility,
1130
+ * `document_nni_mismatch`). Absent otherwise.
1131
+ */
1132
+ failureReason?: PolicyFailureReason;
1133
+ /** With failureReason `camera_unavailable`: why (`denied` or `no_camera`), when the SDK said. Absent otherwise. */
1134
+ failureDetail?: CameraUnavailableCause;
1135
+ /** The subject (person) this session is linked to, once that subject has passed a verification (absent before that). */
1136
+ subjectId?: string;
1137
+ /** Your own id for the person, from `subject.externalRef` at create. */
1138
+ externalRef?: string;
1139
+ /** The agent reference sent as `assistedBy` at create, for assisted capture. */
1140
+ assistedBy?: {
1141
+ externalRef: string;
1142
+ };
1143
+ /**
1144
+ * `true` when an identifier this session read already belongs to a
1145
+ * different subject than `subjectId` — the subjects are never merged.
1146
+ */
1147
+ subjectConflict?: boolean;
1148
+ /**
1149
+ * ISO 8601 — when the end user's device may verify again; set with
1150
+ * `failureReason: 'device_cooldown'`.
1151
+ */
1152
+ retryAfter?: string;
1153
+ /**
1154
+ * Dotted paths this session's {@link CreateSessionInput.overrides} changed
1155
+ * (e.g. `settings.decisions.mode`, `services.liveness`).
1156
+ */
1157
+ overriddenFields?: string[];
1158
+ /**
1159
+ * Risk signals recorded on the session (e.g. `device_velocity`,
1160
+ * `timezone_mismatch`, `icao_non_compliant` when an `alert` ICAO policy flagged
1161
+ * the selfie) — signals only, never a verdict by themselves.
1162
+ */
1163
+ riskSignals?: string[];
1164
+ /**
1165
+ * `true` for a returning-user session (created with
1166
+ * {@link SessionSubjectInput.reuse}): liveness + face match against the
1167
+ * subject's stored reference photo only.
1168
+ */
1169
+ returning?: true;
1170
+ /** On a returning-user session: the subject (person) it re-verifies. */
1171
+ reuseOf?: string;
1172
+ /**
1173
+ * On a session created for an existing subject: `recheck` (the same person
1174
+ * again) or `step_up` (raised to identity level). Absent otherwise.
1175
+ */
1176
+ reuseMode?: SubjectReuseMode;
1177
+ /** The contacts verified in this session (passed OTP checks only); absent when none. */
1178
+ verifiedContacts?: VerifiedContacts;
1179
+ /** The national eID that verified this session (the `eid_auth` check passed); absent otherwise. */
1180
+ eid?: EidResult;
1181
+ /**
1182
+ * When the flow sets a minimum age and the session proved it: the threshold
1183
+ * and how it was proved ({@link AgeResult}). Absent otherwise.
1184
+ */
1185
+ age?: AgeResult;
1186
+ /**
1187
+ * ID mode (`portrait.purpose = id_document`) only: the ICAO portrait can be
1188
+ * fetched with {@link SessionsApi.portrait}.
1189
+ */
1190
+ portraitAvailable?: boolean;
1191
+ /**
1192
+ * Terminal sessions: a failure identification match
1193
+ * ({@link FailureIdentification}), present only for a match and only when the
1194
+ * setting is on. A signal, never a decision.
1195
+ */
1196
+ failureIdentification?: FailureIdentification;
1197
+ }
1198
+ /**
1199
+ * `data` of the terminal / review-pending session lifecycle events
1200
+ * (`session.completed` | `session.failed` | `session.review_pending` |
1201
+ * `session.expired`): ids and enums only, no civil data,
1202
+ * scores or links. `outcome` and `steps` travel on `completed` / `failed`;
1203
+ * `review_pending` carries `steps` without an outcome; `expired` carries the
1204
+ * status and the session's refs (`flow`, subject ids, `overriddenFields`).
1205
+ * @public
1206
+ */
1207
+ interface SessionLifecycleEventData {
1208
+ sessionId: string;
1209
+ status: SessionStatus;
1210
+ outcome?: SessionOutcome | null;
1211
+ /** On `completed` / `failed`: the app the session belongs to. */
1212
+ appId?: string;
1213
+ /** On `completed` / `failed`: what the session proved ({@link VerificationLevel}). */
1214
+ level?: VerificationLevel | null;
1215
+ /** On `completed` / `failed`: how the level was proved. */
1216
+ assurance?: VerificationAssurance | null;
1217
+ /** On `completed` / `failed`: the billing unit the session consumed. */
1218
+ unit?: VerificationUnit | null;
1219
+ /** On `completed` / `failed`: ISO 8601 terminal time. */
1220
+ verifiedAt?: string;
1221
+ /** On `completed` / `failed`: device and network risk facts, when recorded. */
1222
+ risk?: ResultRisk;
1223
+ /** On `completed` / `failed`: other subjects the face matched, when a duplicate search ran. */
1224
+ duplicates?: ResultDuplicate[];
1225
+ /**
1226
+ * On `completed` / `failed`: the signed result token (ES256 JWT, valid
1227
+ * 10 minutes). Check it with {@link verifyResultToken}; absent when
1228
+ * result tokens are not enabled.
1229
+ */
1230
+ resultToken?: string;
1231
+ /**
1232
+ * The checks on the session's path (checks of a lane the person did not take
1233
+ * are omitted), each with its {@link SessionStepDecision} when a person decided it.
1234
+ */
1235
+ steps?: Array<Pick<SessionStep, "checkType" | "state" | "nodeId" | "service" | "decision">>;
1236
+ /** Sekyro flows: the flow version the session runs (absent on sessions created before flows). */
1237
+ flow?: SessionFlowRef;
1238
+ /** Machine-readable reason, when the transition has one. */
1239
+ reason?: string;
1240
+ /** End-user network context (no IP); on `completed` / `failed` when recorded. */
1241
+ network?: Omit<SessionNetwork, "ip">;
1242
+ /** End-user device; on `completed` / `failed` when recorded. */
1243
+ device?: SessionDevice;
1244
+ /**
1245
+ * On `session.failed`: set when a profile-v2 policy ended the session — a
1246
+ * session-level gate (location, anonymizer) or a failed check's policy
1247
+ * reason (eligibility, `document_nni_mismatch`).
1248
+ */
1249
+ failureReason?: PolicyFailureReason;
1250
+ /** On `session.failed` with failureReason `camera_unavailable`: why (`denied` or `no_camera`), when the SDK said. Absent otherwise. */
1251
+ failureDetail?: CameraUnavailableCause;
1252
+ /** The subject (person) the session is linked to, once that subject has passed a verification (absent before that). */
1253
+ subjectId?: string;
1254
+ /** Your own id for the person, from `subject.externalRef` at create. */
1255
+ externalRef?: string;
1256
+ /**
1257
+ * `true` when an identifier this session read already belongs to a
1258
+ * different subject than `subjectId` — the subjects are never merged.
1259
+ */
1260
+ subjectConflict?: boolean;
1261
+ /** `true` on a returning-user session (liveness + face match against the stored photo). */
1262
+ returning?: true;
1263
+ /** On a returning-user session: the subject (person) it re-verifies. */
1264
+ reuseOf?: string;
1265
+ /**
1266
+ * On a session created for an existing subject: `recheck` (the same person
1267
+ * again) or `step_up` (raised to identity level). Absent otherwise.
1268
+ */
1269
+ reuseMode?: SubjectReuseMode;
1270
+ /**
1271
+ * On `completed` / `failed`: the `link.state` the session was created
1272
+ * with, echoed back; absent when the session had none.
1273
+ */
1274
+ link?: {
1275
+ state: string;
1276
+ };
1277
+ /**
1278
+ * On `session.failed` with `failureReason: 'device_cooldown'`: ISO time
1279
+ * from which the device may start a new verification.
1280
+ */
1281
+ retryAfter?: string;
1282
+ /** Dotted paths the session's create-time {@link CreateSessionInput.overrides} changed. */
1283
+ overriddenFields?: string[];
1284
+ /** On `completed` / `failed`: the contacts verified in this session (passed OTP checks only). */
1285
+ verifiedContacts?: VerifiedContacts;
1286
+ /** On `completed` / `failed`: the national eID that verified this session, when one did. */
1287
+ eid?: EidResult;
1288
+ /** On `completed` / `failed`: the minimum age the session proved and how ({@link AgeResult}), when the flow sets one. */
1289
+ age?: AgeResult;
1290
+ /**
1291
+ * ID mode only, on `completed` / `failed`: the ICAO portrait can be fetched
1292
+ * with {@link SessionsApi.portrait} (the event never carries the image).
1293
+ */
1294
+ portraitAvailable?: boolean;
1295
+ /**
1296
+ * On `completed` / `failed`: a failure identification match
1297
+ * ({@link FailureIdentification}), when the setting is on and the search
1298
+ * found one before the event was sent. A signal, never a decision.
1299
+ */
1300
+ failureIdentification?: FailureIdentification;
1301
+ }
1302
+ /**
1303
+ * `data` of `subject.updated` — either a session linked to the subject reached
1304
+ * a terminal state (`sessionId`, session `status`, `outcome`), or the subject
1305
+ * was revoked (`status: 'revoked'`, no session). Ids and enums only.
1306
+ * @public
1307
+ */
1308
+ interface SubjectUpdatedEventData {
1309
+ subjectId: string;
1310
+ /** The session that reached a terminal state; absent on a revocation. */
1311
+ sessionId?: string;
1312
+ status: SessionStatus | "revoked";
1313
+ /** The session outcome; absent on a revocation. */
1314
+ outcome?: SessionOutcome | null;
1315
+ /** The session's level; absent on a revocation. */
1316
+ level?: VerificationLevel | null;
1317
+ /** The session's assurance; absent on a revocation. */
1318
+ assurance?: VerificationAssurance | null;
1319
+ /**
1320
+ * Your own ids for the person (`subject.externalRef` values), so a
1321
+ * revocation can find your user without a lookup. Absent from older API versions.
1322
+ */
1323
+ externalRefs?: string[];
1324
+ }
1325
+ /**
1326
+ * `data` of `subject.enrolled` — the subject's first reference photo was
1327
+ * stored (it can now be used for returning-user sessions). Ids and enums only.
1328
+ * @public
1329
+ */
1330
+ interface SubjectEnrolledEventData {
1331
+ subjectId: string;
1332
+ /** The approved session the reference photo came from. */
1333
+ sessionId: string;
1334
+ assurance: SubjectAssurance;
1335
+ }
1336
+ /**
1337
+ * `data` of `subject.deleted`. A delete through the subjects API carries
1338
+ * `subjectId`; a right-to-erasure request carries the tokenized `subjectRef`
1339
+ * (with `orgId` / `env`) instead — never the national number.
1340
+ * @public
1341
+ */
1342
+ interface SubjectDeletedEventData {
1343
+ subjectId?: string;
1344
+ subjectRef?: string;
1345
+ orgId?: string;
1346
+ env?: SekyroEnvironment;
1347
+ /**
1348
+ * With `subjectId` (a delete through the subjects API): your own ids for
1349
+ * the person, so you can find your user. Never on the erasure variant.
1350
+ */
1351
+ externalRefs?: string[];
1352
+ }
1353
+ /** Subject lifecycle: a revoked subject cannot be reused. @public */
1354
+ type SubjectStatus = "active" | "revoked";
1355
+ /**
1356
+ * How strongly a subject's identity was established: the reference photo
1357
+ * came from the national registry, the document's chip (`chip_biometric`, a
1358
+ * passed chip read plus a face match) or the document, and a face match passed
1359
+ * (`*_biometric`) or the session had no face match (`*_only`). `supplied_*`:
1360
+ * partner-supplied identity data (`input.suppliedIdentity`), with
1361
+ * (`supplied_biometric`) or without (`supplied_only`) a face match against its photo.
1362
+ * @public
1363
+ */
1364
+ type SubjectAssurance = "registry_biometric" | "chip_biometric" | "document_biometric" | "registry_only" | "document_only" | "supplied_biometric" | "supplied_only";
1365
+ /**
1366
+ * Origin of a subject's stored reference photo, best first (`chip`: the document chip's portrait;
1367
+ * `org_supplied`: the photo of your partner-supplied identity data).
1368
+ * @public
1369
+ */
1370
+ type SubjectReferenceSource = "registry" | "doc_registry" | "chip" | "org_supplied" | "document";
1371
+ /** One session linked to a subject. @public */
1372
+ interface SubjectSession {
1373
+ sessionId: string;
1374
+ appId: string | null;
1375
+ /** ISO 8601 — when the session was linked. */
1376
+ at: string;
1377
+ status: SessionStatus;
1378
+ outcome: SessionOutcome | null;
1379
+ /** What the session proved; present only when stored (sessions linked before the field existed have none). */
1380
+ level?: VerificationLevel;
1381
+ /** How the session's level was proved; present only when stored. */
1382
+ assurance?: VerificationAssurance;
1383
+ }
1384
+ /**
1385
+ * A subject (the same person across your apps), as `GET /subjects/:id`
1386
+ * returns it. Never contains photo keys or URLs.
1387
+ * @public
1388
+ */
1389
+ interface Subject {
1390
+ id: string;
1391
+ status: SubjectStatus;
1392
+ /** ISO 8601 — present only when revoked. */
1393
+ revokedAt?: string;
1394
+ sessions: SubjectSession[];
1395
+ externalRefs: string[];
1396
+ /** ISO 8601. */
1397
+ firstSeenAt: string;
1398
+ /** ISO 8601. */
1399
+ lastSeenAt: string;
1400
+ /** ISO 8601, or `null` before the first approved session. */
1401
+ lastPassedAt: string | null;
1402
+ /** ISO 8601 of the last approved full or returning session, or `null`. */
1403
+ lastVerifiedAt: string | null;
1404
+ /** The stored reference photo's origin and date — `null` until one is stored. */
1405
+ reference: {
1406
+ source: SubjectReferenceSource;
1407
+ capturedAt: string;
1408
+ } | null;
1409
+ assurance: SubjectAssurance | null;
1410
+ /**
1411
+ * The highest {@link VerificationLevel} an approved linked session proved;
1412
+ * `0` once the subject is revoked; `null` when no terminal session was
1413
+ * recorded since the field exists. Absent from API versions before the field.
1414
+ */
1415
+ level?: VerificationLevel | null | undefined;
1416
+ /** ISO 8601: when {@link Subject.level} was last proved (the latest approved session at that level or higher); `null` with it. Absent with it. */
1417
+ levelAt?: string | null | undefined;
1418
+ /** The assurance of the session that proved {@link Subject.level}; `null` with it. Absent with it. */
1419
+ levelAssurance?: VerificationAssurance | null | undefined;
1420
+ /**
1421
+ * A returning-user session can be created now: active, a reference photo is
1422
+ * stored, and the last FULL verification (returning-user sessions do not
1423
+ * reset it) is within the returning-user limit of your app's default flow
1424
+ * (`settings.returning`: turned on, and `maxAgeMonths` when set).
1425
+ */
1426
+ returningReady: boolean;
1427
+ /** The verified name / birth date of the latest approved session. */
1428
+ display?: {
1429
+ name?: string;
1430
+ birthDate?: string;
1431
+ };
1432
+ }
1433
+ /**
1434
+ * Filters of {@link SessionsApi.list}: your own user id
1435
+ * (`subject.externalRef` at create) and/or a status.
1436
+ * @public
1437
+ */
1438
+ interface ListSessionsQuery {
1439
+ /** Your own id for the person (1 to 128 characters). */
1440
+ externalRef?: string;
1441
+ status?: SessionStatus;
1442
+ }
1443
+ /** Result of {@link SubjectsApi.delete}. @public */
1444
+ interface DeletedSubject {
1445
+ id: string;
1446
+ deleted: true;
1447
+ }
1448
+ /** Options of {@link SubjectsApi.revoke}. @public */
1449
+ interface RevokeSubjectInput {
1450
+ /** Kept on the audit trail only (≤ 500 characters). Do not put personal data here. */
1451
+ reason?: string;
1452
+ }
1453
+ /**
1454
+ * `data` of `subject.suspicious_activity` — a device already linked to
1455
+ * ANOTHER subject was used for a session of this subject. `count` is the
1456
+ * subject's running total of such events. Ids only.
1457
+ * @public
1458
+ */
1459
+ interface SubjectSuspiciousActivityEventData {
1460
+ subjectId: string;
1461
+ sessionId: string;
1462
+ count: number;
1463
+ }
1464
+ /**
1465
+ * `data` of `session.step.completed` — the check that just passed.
1466
+ * @public
1467
+ */
1468
+ interface SessionStepCompletedEventData {
1469
+ sessionId: string;
1470
+ checkType: CheckType;
1471
+ state: CheckState;
1472
+ /** Sekyro flows: the flow node of the passed check. */
1473
+ nodeId?: string;
1474
+ /** Sekyro flows: the service of that node. */
1475
+ service?: ServiceId;
1476
+ /** Sekyro flows: the flow version the session runs (absent on sessions created before flows). */
1477
+ flow?: SessionFlowRef;
1478
+ /** The subject (person) the session is linked to, once that subject has passed a verification (absent before that). */
1479
+ subjectId?: string;
1480
+ /** Your own id for the person, from `subject.externalRef` at create. */
1481
+ externalRef?: string;
1482
+ /**
1483
+ * `true` when an identifier this session read already belongs to a
1484
+ * different subject than `subjectId` — the subjects are never merged.
1485
+ */
1486
+ subjectConflict?: boolean;
1487
+ /** `true` on a returning-user session (liveness + face match against the stored photo). */
1488
+ returning?: true;
1489
+ /** On a returning-user session: the subject (person) it re-verifies. */
1490
+ reuseOf?: string;
1491
+ /** When the passed check is `phone_otp` / `email_otp`: that one verified contact. */
1492
+ verifiedContacts?: VerifiedContacts;
1493
+ }
1494
+ /**
1495
+ * `data` of `session.review_decided`: a human (or the review deadline) decided
1496
+ * a pending review. `outcome` speaks the REVIEW vocabulary (`pass` | `fail`),
1497
+ * not the session outcome; `reason` is the reviewer's code, `review_timeout`
1498
+ * when the review expired, or `review_split` when two reviewers disagreed and
1499
+ * nobody settled it by the deadline. A reviewer's decision also carries
1500
+ * `reasons`, `decision` and the terminal fields of `session.completed` /
1501
+ * `session.failed`; a deadline carries the ids only.
1502
+ * @public
1503
+ */
1504
+ interface SessionReviewDecidedEventData {
1505
+ sessionId: string;
1506
+ outcome: "pass" | "fail";
1507
+ reason: string;
1508
+ /** A reviewer's decision: what it was about ({@link ReviewReason}). */
1509
+ reasons?: ReviewReason[];
1510
+ /** A reviewer's decision: how it was formed ({@link SessionStepDecision}; counts only). */
1511
+ decision?: SessionStepDecision;
1512
+ /** The app the session belongs to. */
1513
+ appId?: string;
1514
+ /** What the session proved ({@link VerificationLevel}). */
1515
+ level?: VerificationLevel | null;
1516
+ /** How the level was proved. */
1517
+ assurance?: VerificationAssurance | null;
1518
+ /** The billing unit the session consumed. */
1519
+ unit?: VerificationUnit | null;
1520
+ /** ISO 8601 terminal time. */
1521
+ verifiedAt?: string;
1522
+ /** Device and network risk facts, when recorded. */
1523
+ risk?: ResultRisk;
1524
+ /** Other subjects the face matched, when a duplicate search ran. */
1525
+ duplicates?: ResultDuplicate[];
1526
+ /** The duplicate search could not run. */
1527
+ dedupUnavailable?: true;
1528
+ /** The minimum age the session proved and how ({@link AgeResult}), when the flow sets one. */
1529
+ age?: AgeResult;
1530
+ /** A failure identification match ({@link FailureIdentification}), when the setting is on and the search found one. */
1531
+ failureIdentification?: FailureIdentification;
1532
+ /** The `link.state` the session was created with, echoed back; absent when the session had none. */
1533
+ link?: {
1534
+ state: string;
1535
+ };
1536
+ /** The signed result token (ES256 JWT, valid 10 minutes), when result tokens are enabled. */
1537
+ resultToken?: string;
1538
+ /** The agent reference sent as `assistedBy` at create, for assisted capture. */
1539
+ assistedBy?: {
1540
+ externalRef: string;
1541
+ };
1542
+ /** Dotted paths the session's create-time {@link CreateSessionInput.overrides} changed. */
1543
+ overriddenFields?: string[];
1544
+ /**
1545
+ * On a session created for an existing subject: `recheck` (the same person
1546
+ * again) or `step_up` (raised to identity level). Absent otherwise.
1547
+ */
1548
+ reuseMode?: SubjectReuseMode;
1549
+ /** Sekyro flows: the flow version the session runs (absent on sessions created before flows). */
1550
+ flow?: SessionFlowRef;
1551
+ /** The subject (person) the session is linked to, once that subject has passed a verification (absent before that). */
1552
+ subjectId?: string;
1553
+ /** Your own id for the person, from `subject.externalRef` at create. */
1554
+ externalRef?: string;
1555
+ /**
1556
+ * `true` when an identifier this session read already belongs to a
1557
+ * different subject than `subjectId` — the subjects are never merged.
1558
+ */
1559
+ subjectConflict?: boolean;
1560
+ /** `true` on a returning-user session (liveness + face match against the stored photo). */
1561
+ returning?: true;
1562
+ /** On a returning-user session: the subject (person) it re-verifies. */
1563
+ reuseOf?: string;
1564
+ /** ID mode only: the ICAO portrait can be fetched with {@link SessionsApi.portrait}. */
1565
+ portraitAvailable?: boolean;
1566
+ }
1567
+ /**
1568
+ * `data` of `session.superseded`: a session that waited for a review closed
1569
+ * because a newer attempt of the same person took that review over. The
1570
+ * session ends with status `completed` and outcome `superseded`, its review
1571
+ * step failed with `superseded_by_retry`; nothing of it is deleted. Read the
1572
+ * newer session (`supersededBy`) for the verdict.
1573
+ * @public
1574
+ */
1575
+ interface SessionSupersededEventData {
1576
+ sessionId: string;
1577
+ /** The newer session of the same person that took the review over. */
1578
+ supersededBy: string;
1579
+ /** The review case both sessions belong to (an opaque id). */
1580
+ caseId: string;
1581
+ reason: "superseded_by_retry";
1582
+ /** Your own id for the person, from `subject.externalRef` at create. */
1583
+ externalRef?: string;
1584
+ }
1585
+ /**
1586
+ * `usage.threshold_reached`: a usage, credit or spend threshold of the organization's
1587
+ * plan was reached (sent once per threshold and period). `kind` is `tier` for a monthly
1588
+ * tier, or the alert, e.g. `credit_80`, `usage_100_paid`, `spend_cap_reached`.
1589
+ * @public
1590
+ */
1591
+ interface UsageThresholdReachedEventData {
1592
+ kind: string;
1593
+ /** The verification unit, on per-unit alerts. */
1594
+ unit?: "human_verification" | "identity_verification";
1595
+ /** Percent of the limit (80, 100), or `overage` for the first verification beyond a tier. */
1596
+ threshold?: number | "overage";
1597
+ used?: number;
1598
+ limit?: number;
1599
+ /** UTC month, `YYYY-MM`. */
1600
+ period?: string;
1601
+ /** Tier alerts: verifications that reached a result this month. */
1602
+ confirmed?: number;
1603
+ /** Tier alerts: verifications beyond the tier this month. */
1604
+ overage?: number;
1605
+ }
1606
+ /**
1607
+ * Event type → the shape of its `data`. Session events are typed; the
1608
+ * remaining events carry an open record until their payloads are frozen.
1609
+ * @public
1610
+ */
1611
+ interface WebhookEventDataMap {
1612
+ "session.created": Record<string, unknown>;
1613
+ "session.started": Record<string, unknown>;
1614
+ "session.step.completed": SessionStepCompletedEventData;
1615
+ "session.review_pending": SessionLifecycleEventData;
1616
+ "session.review_decided": SessionReviewDecidedEventData;
1617
+ "session.completed": SessionLifecycleEventData;
1618
+ "session.expired": SessionLifecycleEventData;
1619
+ "session.failed": SessionLifecycleEventData;
1620
+ "session.superseded": SessionSupersededEventData;
1621
+ "subject.enrolled": SubjectEnrolledEventData;
1622
+ "subject.updated": SubjectUpdatedEventData;
1623
+ "subject.suspicious_activity": SubjectSuspiciousActivityEventData;
1624
+ "subject.deleted": SubjectDeletedEventData;
1625
+ "aml.match_flagged": Record<string, unknown>;
1626
+ "payment.received": Record<string, unknown>;
1627
+ "invoice.generated": Record<string, unknown>;
1628
+ "invoice.paid": Record<string, unknown>;
1629
+ "invoice.overdue": Record<string, unknown>;
1630
+ "usage.threshold_reached": UsageThresholdReachedEventData;
1631
+ "webhook.test": Record<string, unknown>;
1632
+ }
1633
+ /** Every event a partner endpoint may receive. @public */
1634
+ type WebhookEventType = keyof WebhookEventDataMap;
1635
+ /**
1636
+ * The signed webhook payload for ONE event type. There is no global API
1637
+ * version; each event carries its own per-event `version`. Retried deliveries
1638
+ * keep the same `id` — de-duplicate on it.
1639
+ * @public
1640
+ */
1641
+ interface WebhookEnvelopeOf<E extends WebhookEventType> {
1642
+ /** UUIDv7, stable across delivery retries. */
1643
+ id: string;
1644
+ event: E;
1645
+ /** Per-event payload version. */
1646
+ version: number;
1647
+ /** ISO 8601. */
1648
+ createdAt: string;
1649
+ orgId: string;
1650
+ env: SekyroEnvironment;
1651
+ data: WebhookEventDataMap[E];
1652
+ }
1653
+ /**
1654
+ * The signed webhook payload, discriminated on `event`: narrowing on
1655
+ * `envelope.event` narrows `envelope.data` to that event's shape.
1656
+ *
1657
+ * @example
1658
+ * ```ts
1659
+ * const envelope = verifyWebhook(rawBody, header, secret);
1660
+ * switch (envelope.event) {
1661
+ * case "session.completed":
1662
+ * envelope.data.outcome; // SessionOutcome | null | undefined
1663
+ * break;
1664
+ * case "session.review_decided":
1665
+ * envelope.data.outcome; // "pass" | "fail"
1666
+ * break;
1667
+ * }
1668
+ * ```
1669
+ * @public
1670
+ */
1671
+ type WebhookEnvelope<E extends WebhookEventType = WebhookEventType> = E extends WebhookEventType ? WebhookEnvelopeOf<E> : never;
1672
+ /**
1673
+ * `data` of any `session.*` event.
1674
+ * @deprecated Use {@link SessionLifecycleEventData}, {@link SessionStepCompletedEventData}
1675
+ * or {@link SessionReviewDecidedEventData}, or narrow a {@link WebhookEnvelope} on `event`.
1676
+ * @public
1677
+ */
1678
+ type SessionEventData = SessionLifecycleEventData | SessionStepCompletedEventData | SessionReviewDecidedEventData;
1679
+
1680
+ /** Default partner API origin + version prefix. @public */
1681
+ declare const DEFAULT_BASE_URL = "https://api.sekyro.ai/api/v2";
1682
+ /** Default per-request timeout. @public */
1683
+ declare const DEFAULT_TIMEOUT_MS = 30000;
1684
+ /** `fetch`-compatible function; the global `fetch` by default. @public */
1685
+ type FetchLike = typeof globalThis.fetch;
1686
+ /** Constructor options of {@link Sekyro}. @public */
1687
+ interface SekyroOptions {
1688
+ /** Partner API key (server-side only). Sent as `Authorization: Bearer`. */
1689
+ apiKey: string;
1690
+ /** API base URL incl. the `/api/v2` prefix. Default {@link DEFAULT_BASE_URL}. */
1691
+ baseUrl?: string;
1692
+ /** Per-request timeout in ms. Default {@link DEFAULT_TIMEOUT_MS}. */
1693
+ timeoutMs?: number;
1694
+ /** Custom `fetch` (tests, proxies, custom agents). Default `globalThis.fetch`. */
1695
+ fetch?: FetchLike;
1696
+ /**
1697
+ * The auth-provider connector this client runs in, sent as the
1698
+ * `x-sekyro-connector: <provider>/<version>` header on every call so the
1699
+ * dashboard can show the connector as connected. Ids only. A connector
1700
+ * created with `createConnector` from `@sekyro/node/connect` sets it for you
1701
+ * (unless its `telemetry` option is `false`).
1702
+ */
1703
+ connector?: ConnectorIdentity;
1704
+ }
1705
+ /** A connector's provider id and package version, for {@link SekyroOptions.connector}. @public */
1706
+ interface ConnectorIdentity {
1707
+ /** The provider id, for example `supabase`: lowercase letters, digits and `-`, at most 32 characters. */
1708
+ provider: string;
1709
+ /** The connector package version, for example `0.1.0`: at most 64 characters. */
1710
+ version: string;
1711
+ }
1712
+ /**
1713
+ * `sekyro.sessions` — create and read verification sessions.
1714
+ *
1715
+ * Exported as a TYPE only (`import type { SessionsApi }`): the class value is
1716
+ * not part of the package surface, so it can only be obtained through
1717
+ * {@link Sekyro.sessions} — never constructed by hand with an unchecked
1718
+ * transport.
1719
+ * @public
1720
+ */
1721
+ declare class SessionsApi {
1722
+ private readonly call;
1723
+ /**
1724
+ * Constructed by {@link Sekyro}; the transport is kept out of the public
1725
+ * surface on purpose (only its bound `call` crosses this boundary).
1726
+ * @internal
1727
+ */
1728
+ constructor(call: <T>(method: "GET" | "POST" | "DELETE", path: string, body?: unknown, idempotencyKey?: string) => Promise<T>);
1729
+ /**
1730
+ * `POST /sessions`. Returns the one-time `clientToken` — hand it to the
1731
+ * browser, never persist it. Pass an `idempotencyKey` so a retried call
1732
+ * cannot create a second session.
1733
+ */
1734
+ create(input?: CreateSessionInput, opts?: RequestOptions): Promise<CreatedSession>;
1735
+ /**
1736
+ * `POST /sessions/:id/method` — choose the identity method of an
1737
+ * optional-document session on the person's behalf (the hosted method
1738
+ * screen is then skipped). `409 method_locked` once the choice can no
1739
+ * longer change; `409 session_not_active` on a finished or expired session.
1740
+ * On a flow session: `409 choice_not_found` (the flow has no identity-method
1741
+ * choice), `409 choice_locked`, `409 choice_option_unavailable` (see
1742
+ * {@link isFlowError}).
1743
+ */
1744
+ selectMethod(id: string, method: IdentityMethod): Promise<Session>;
1745
+ /** `GET /sessions/:id` — the whitelisted view (no client token). */
1746
+ get(id: string): Promise<Session>;
1747
+ /**
1748
+ * `GET /sessions?externalRef=&status=`: your newest sessions (at most 100),
1749
+ * optionally filtered by your own user id and/or a status. The filters are
1750
+ * applied again to the answer, so an API that ignores them never returns
1751
+ * another user's sessions.
1752
+ */
1753
+ list(query?: ListSessionsQuery): Promise<Session[]>;
1754
+ /**
1755
+ * `GET /sessions/:id/portrait?format=url` — ID mode: a 5-minute presigned
1756
+ * link to the 480×640 ICAO portrait (JPEG). Needs the `portrait:read` scope
1757
+ * (keys minted from the dashboard carry it). `404 portrait_not_available`
1758
+ * until the session's `portrait_icao` check has passed (`portraitAvailable`).
1759
+ */
1760
+ portrait(id: string): Promise<SessionPortraitLink>;
1761
+ /**
1762
+ * `GET /sessions/:id/result-token`: a freshly signed result token for a
1763
+ * finished session (valid 10 minutes; check it with
1764
+ * {@link verifyResultToken}). `409 session_not_terminal` while the session
1765
+ * is still active. Needs the `sessions:read` scope.
1766
+ */
1767
+ resultToken(id: string): Promise<ResultTokenResponse>;
1768
+ }
1769
+ /**
1770
+ * `sekyro.subjects` — read and manage subjects (the same person across your
1771
+ * apps). Reads need the `subjects:read` scope, `revoke` / `delete` the
1772
+ * `subjects:write` scope (keys minted from the dashboard carry both; an older
1773
+ * key answers `403 insufficient_scope`). A subject is visible once the
1774
+ * person has passed a verification: a subject that never passed, an unknown
1775
+ * id and a subject of another organization or environment all answer the same
1776
+ * `404 subject_not_found` on `get`, `revoke` and `delete`, and `list` leaves
1777
+ * it out.
1778
+ *
1779
+ * Type-only export, like {@link SessionsApi}: obtained through
1780
+ * {@link Sekyro.subjects}.
1781
+ * @public
1782
+ */
1783
+ declare class SubjectsApi {
1784
+ private readonly call;
1785
+ /** @internal */
1786
+ constructor(call: <T>(method: "GET" | "POST" | "DELETE", path: string, body?: unknown, idempotencyKey?: string) => Promise<T>);
1787
+ /** `GET /subjects/:id` — the subject, its sessions and its returning-user readiness. */
1788
+ get(id: string): Promise<Subject>;
1789
+ /**
1790
+ * `GET /subjects?externalRef=…`: the subjects carrying your own id that have
1791
+ * passed a verification (newest first, at most 50). The list can be empty
1792
+ * while sessions with this `externalRef` exist.
1793
+ */
1794
+ list(query: {
1795
+ externalRef: string;
1796
+ }): Promise<Subject[]>;
1797
+ /**
1798
+ * `POST /subjects/:id/revoke` — the subject can no longer be used for
1799
+ * returning-user sessions. Idempotent: revoking again returns the same view.
1800
+ * Emits `subject.updated` with `status: 'revoked'`.
1801
+ */
1802
+ revoke(id: string, input?: RevokeSubjectInput, opts?: RequestOptions): Promise<Subject>;
1803
+ /**
1804
+ * `DELETE /subjects/:id` — deletes the subject's stored photos, face
1805
+ * templates and identifiers, and unlinks its sessions. Emits
1806
+ * `subject.deleted`. Cannot be undone; a second call answers `404`.
1807
+ */
1808
+ delete(id: string): Promise<DeletedSubject>;
1809
+ /**
1810
+ * A re-check or step-up session for an existing subject in one call:
1811
+ * `POST /subjects/:id/sessions` when `target` is a subject id (24
1812
+ * hexadecimal characters) or `{ subjectId }`, otherwise
1813
+ * `POST /subjects/by-external-ref/:externalRef/sessions` (pass
1814
+ * `{ externalRef }` to force it). Same result and errors as
1815
+ * {@link SessionsApi.create}; needs the `sessions:create` and
1816
+ * `subjects:read` scopes.
1817
+ */
1818
+ createSession(target: string | SubjectSessionTarget, input: SubjectSessionInput, opts?: RequestOptions): Promise<CreatedSession>;
1819
+ }
1820
+ /**
1821
+ * Sekyro AI partner API client. Server-side only: it carries your API key.
1822
+ *
1823
+ * Throws {@link SekyroConfigError} synchronously when `apiKey` is missing or
1824
+ * `baseUrl` is not `https:` (plain `http:` is accepted for `localhost`,
1825
+ * `127.0.0.1` and `[::1]` only).
1826
+ *
1827
+ * @example
1828
+ * ```ts
1829
+ * const sekyro = new Sekyro({ apiKey: process.env.SEKYRO_API_KEY! });
1830
+ * const { id, clientToken } = await sekyro.sessions.create({ input: { nni: "1357924632" } });
1831
+ * ```
1832
+ * @public
1833
+ */
1834
+ declare class Sekyro {
1835
+ #private;
1836
+ readonly sessions: SessionsApi;
1837
+ readonly subjects: SubjectsApi;
1838
+ constructor(opts: SekyroOptions);
1839
+ /**
1840
+ * `GET /flows` — the published flows of the API key's app (default flow
1841
+ * first, then by name). Pass a flow's `slug` or `id` as
1842
+ * {@link CreateSessionInput.flow}. Needs the `sessions:create` scope; an
1843
+ * invalid key answers `401 unauthorized`.
1844
+ */
1845
+ listFlows(): Promise<FlowSummary[]>;
1846
+ }
1847
+
1848
+ export { type ReviewOutcomeReason as $, type AgeMethod as A, type FlowOverridableSettings as B, type CreatedSession as C, DEFAULT_BASE_URL as D, type EidResult as E, type FetchLike as F, type FlowOverrides as G, type FlowServiceSettings as H, type FlowSummary as I, type IdNumberReason as J, type IdentityMethod as K, type Locale as L, type LevelTarget as M, type ListSessionsQuery as N, type MatchReason as O, type PolicyFailureReason as P, type PortraitReportEntry as Q, type ReviewReason as R, Sekyro as S, type PriorReviewReason as T, type ProbeBindingReason as U, type VerificationLevel as V, type WebhookEventType as W, type ProbeQuality as X, type ProfileDocumentType as Y, type RequestOptions as Z, type ResultTokenResponse as _, type ServiceId as a, type RevokeSubjectInput as a0, type SekyroOptions as a1, type Session as a2, type SessionDevice as a3, type SessionDeviceSignal as a4, type SessionEventData as a5, type SessionFailureReason as a6, type SessionFlowRef as a7, type SessionLifecycleEventData as a8, type SessionLinkInput as a9, type SuppliedIdentityRecord as aA, type UsageThresholdReachedEventData as aB, type VerifiedContacts as aC, type WebhookEnvelopeOf as aD, type WebhookEventDataMap as aE, type SessionNetwork as aa, type SessionNetworkEvent as ab, type SessionPortraitLink as ac, type SessionReviewDecidedEventData as ad, type SessionStatus as ae, type SessionStep as af, type SessionStepCompletedEventData as ag, type SessionStepDecision as ah, type SessionSupersededEventData as ai, SessionsApi as aj, type Subject as ak, type SubjectAssurance as al, type SubjectDeletedEventData as am, type SubjectEnrolledEventData as an, type SubjectIdNumber as ao, type SubjectName as ap, type SubjectReferenceSource as aq, type SubjectReuseDocument as ar, type SubjectReuseTarget as as, type SubjectSession as at, type SubjectSessionInput as au, type SubjectSessionTarget as av, type SubjectStatus as aw, type SubjectSuspiciousActivityEventData as ax, type SubjectUpdatedEventData as ay, SubjectsApi as az, type SessionSubjectInput as b, type WebhookEnvelope as c, type SekyroEnvironment as d, type VerificationAssurance as e, type SessionOutcome as f, type VerificationUnit as g, type SubjectReuseMode as h, type ResultRisk as i, type ResultCheckProofs as j, type ResultDuplicate as k, type FailureIdentification as l, type AgeResult as m, type CameraUnavailableCause as n, type CheckState as o, type CheckType as p, type ConnectorIdentity as q, type CreateSessionInput as r, type CreatedSessionWarning as s, DEFAULT_TIMEOUT_MS as t, type DecisionReason as u, type DeepPartial as v, type DeletedSubject as w, type DeliverOptions as x, type DocumentSubstitutionSettings as y, type EligibilityReason as z };