@sekyro/node 1.0.0-rc.16 → 1.0.0-rc.17

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.
@@ -6,20 +6,54 @@
6
6
  *
7
7
  * @packageDocumentation
8
8
  */
9
- /** Session lifecycle status. @public */
10
- type SessionStatus = "created" | "in_progress" | "review_pending" | "completed" | "expired" | "failed";
11
9
  /**
12
- * Terminal verdict, orthogonal to {@link SessionStatus}. `null` until the session
13
- * reaches a terminal status; `review` when a human reviewer must adjudicate.
14
- * A session that waited for a review and was taken over by a newer attempt of
15
- * the same person (`session.superseded`) has `outcome: null` and names that
16
- * attempt in {@link Session.supersededBy}: read the newer session for the
17
- * verdict. `superseded` is no longer sent on the session view, its webhooks or
18
- * the result token; it stays in this union for one release and may still
19
- * appear on {@link PersonSession.outcome}.
10
+ * Session lifecycle status: `created` (nobody opened it yet), `in_progress`, `review_pending`
11
+ * (a step waits for a person's review), then one of the two finished statuses, `verified` or
12
+ * `not_verified`. A `not_verified` session says why in {@link Session.reason}; every finished
13
+ * session says who or what closed it in {@link Session.closedBy}.
20
14
  * @public
21
15
  */
22
- type SessionOutcome = "approved" | "review" | "rejected" | "superseded";
16
+ type SessionStatus = "created" | "in_progress" | "review_pending" | "verified" | "not_verified";
17
+ /**
18
+ * Why a `not_verified` session was not verified: `rejected` (a check decided against the
19
+ * person, or a reviewer did), `inconclusive` (no verdict could be reached: the model was
20
+ * unsure, the captures stayed unreadable, or a review was not decided by its deadline),
21
+ * `unavailable` (the check could not run), `abandoned` (the person left before a result),
22
+ * `not_opened` (nobody opened the link), `policy` (a flow rule stopped it), `cancelled` (you
23
+ * cancelled it) or `superseded` (a newer session of the same person took its review over).
24
+ * @public
25
+ */
26
+ type SessionReason = "rejected" | "inconclusive" | "unavailable" | "abandoned" | "not_opened" | "policy" | "cancelled" | "superseded";
27
+ /**
28
+ * Who or what closed a finished session: `automatic` (the checks), `reviewer` (a person's
29
+ * review), `deadline` (the review deadline passed), `expiry` (the link expired) or
30
+ * `organization` (you cancelled it).
31
+ * @public
32
+ */
33
+ type ClosedBy = "automatic" | "reviewer" | "deadline" | "expiry" | "organization";
34
+ /**
35
+ * What a step's last counted attempt said: `passed`, `rejected`, `inconclusive`, `unreadable`
36
+ * (the capture could not be used), `unavailable` (the check could not run) or `review`.
37
+ * Absent before the first counted attempt.
38
+ * @public
39
+ */
40
+ type StepResult = "passed" | "rejected" | "inconclusive" | "unreadable" | "unavailable" | "review";
41
+ /**
42
+ * A step's counted attempts and its cap: `used >= max` means no attempt is left.
43
+ * @public
44
+ */
45
+ interface SessionStepAttempts {
46
+ used: number;
47
+ max: number;
48
+ }
49
+ /**
50
+ * The step that decided a `not_verified` session: its node id in your flow and its service.
51
+ * @public
52
+ */
53
+ interface SessionDecidingStep {
54
+ id: string;
55
+ service: string;
56
+ }
23
57
  /**
24
58
  * What a finished session proved: `1` a live, real person (human), `2` that
25
59
  * person's identity (document, chip, registry or supplied data bound to the
@@ -45,17 +79,6 @@ interface LevelTarget {
45
79
  min: VerificationLevel;
46
80
  max: VerificationLevel;
47
81
  }
48
- /**
49
- * Device and network risk facts of a finished session (booleans and a level
50
- * word, never scores).
51
- * @public
52
- */
53
- interface ResultRisk {
54
- level: "low" | "medium" | "high";
55
- vpn: boolean;
56
- ipDocumentMismatch: boolean;
57
- deviceTampered: boolean;
58
- }
59
82
  /**
60
83
  * What the liveness step verified about the capture itself: the device
61
84
  * attestation, the capture proof and the injection signals.
@@ -89,11 +112,175 @@ interface AgeResult {
89
112
  sigma?: number;
90
113
  }
91
114
  /** Another person the face already matched (duplicate search). @public */
92
- interface ResultDuplicate {
115
+ interface PersonRef {
93
116
  /** That person's id, `per_` prefixed, as on `GET /people` and `Session.personId`. */
94
117
  personId: string;
118
+ /** That person's latest reference of yours, when it has one. */
95
119
  externalRef?: string;
96
120
  }
121
+ /**
122
+ * What a signal is about: one kind of the catalog, the same on a session's
123
+ * {@link SessionSignal} and on a finding ({@link Signal}).
124
+ * @public
125
+ */
126
+ type SignalKind = "account_targeted" | "id_many_faces" | "duplicate_identity" | "device_farm" | "document_reuse" | "presentation_attack" | "probing" | "velocity" | "network" | "contact_reuse" | "age_probing" | "known_person_new_device" | "registry_burst" | "link_sharing" | "device_integrity" | "too_fast" | "account_volume" | "document_conflict";
127
+ /** How strong a signal is. @public */
128
+ type SignalSeverity = "low" | "medium" | "high";
129
+ /** The strength of the evidence that set a finding's severity. @public */
130
+ type SignalGrade = "strong" | "medium" | "weak";
131
+ /**
132
+ * One evidence code of the catalog: a fact behind a signal. Codes only, never
133
+ * a value.
134
+ * @public
135
+ */
136
+ type SignalEvidence = "injection_suspected" | "capture_tampered" | "capture_provenance_invalid" | "virtual_camera" | "repeated_spoof" | "identity_stop" | "identity_switch" | "registry_burst" | "many_faces" | "face_many_ids" | "dedup_match" | "digest_conflict" | "documents_only" | "subject_conflict" | "session_velocity" | "many_people" | "device_velocity_exceeded" | "counted_rejections" | "shared_device" | "print_only" | "location_mismatch" | "anonymizer_asn" | "vpn" | "tor" | "proxy" | "hosting" | "attestation_failed" | "emulator" | "hooking" | "debugger" | "webdriver" | "headless" | "rooted_device" | "no_device_id" | "too_fast" | "account_volume" | "identities_vary" | "contact_reuse" | "disposable_email" | "role_email" | "age_probing" | "image_reuse" | "document_altered" | "document_substitution" | "mrz_visual_mismatch" | "many_devices" | "new_device";
137
+ /**
138
+ * One signal on a session: a kind, a severity and the evidence behind it.
139
+ * Facts only, never a verdict. On {@link Session.signals}, the terminal
140
+ * `session.*` webhooks and {@link VerifiedResult.signals}.
141
+ * @public
142
+ */
143
+ interface SessionSignal {
144
+ kind: SignalKind;
145
+ /** The strongest grade of its evidence. */
146
+ severity: SignalSeverity;
147
+ /** The facts behind the signal, sorted (at most 16). */
148
+ evidence: SignalEvidence[];
149
+ /** `duplicate_identity` only: the other people the duplicate search matched (at most 10). */
150
+ details?: {
151
+ people: PersonRef[];
152
+ };
153
+ /** The finding (`sig_...`) that holds this session, once it is linked: read it with {@link SignalsApi.get}. */
154
+ signalId?: string;
155
+ }
156
+ /**
157
+ * One of your blocks or rules that flagged the session (`flag`) or held it
158
+ * for review (`review`). A `block` effect stops the session instead
159
+ * (`status: "not_verified"`, `reason: "policy"`, `reasonCode: "blocked_by_org"`).
160
+ * @public
161
+ */
162
+ interface BlockMatch {
163
+ /** The block (`blk_...`). */
164
+ blockId: string;
165
+ effect: "flag" | "review";
166
+ /** The rule (`rul_...`) that made the block, on a block made by a rule. */
167
+ ruleId?: string;
168
+ }
169
+ /**
170
+ * A finding's status: `open`, `reviewed` or `false_positive` (your mark), or
171
+ * `closed` (it went quiet or no longer holds).
172
+ * @public
173
+ */
174
+ type SignalStatus = "open" | "reviewed" | "false_positive" | "closed";
175
+ /** What the sessions of a finding share. @public */
176
+ type SignalKeyKind = "external_ref" | "id_number" | "face_cluster" | "device" | "doc_image" | "contact_phone" | "contact_email" | "person" | "spike" | "asn" | "link";
177
+ /**
178
+ * A finding: sessions of this environment that share a key (a device, an ID
179
+ * number, an account, a contact, a network) and met a pattern. Never a value
180
+ * or a hash: `label` is four characters derived from the key. Read with
181
+ * {@link SignalsApi}.
182
+ * @public
183
+ */
184
+ interface Signal {
185
+ /** `sig_...` */
186
+ id: string;
187
+ kind: SignalKind;
188
+ severity: SignalSeverity;
189
+ grade: SignalGrade;
190
+ status: SignalStatus;
191
+ keyKind: SignalKeyKind;
192
+ /** Four characters derived from the key. */
193
+ label: string;
194
+ /** Why it has this severity. */
195
+ evidence: SignalEvidence[];
196
+ /** The sessions of the finding, by step result. */
197
+ counts: {
198
+ sessions: number;
199
+ failed: number;
200
+ passed: number;
201
+ review: number;
202
+ };
203
+ /** Distinct people among the sessions. */
204
+ people: number;
205
+ /** Distinct devices among the sessions. */
206
+ devices: number;
207
+ /** The sessions (`ses_...`), newest first (at most 200). */
208
+ sessionIds: string[];
209
+ /** The people (`per_...`) among the sessions (at most 50). */
210
+ personIds: string[];
211
+ /** ISO 8601: oldest session. */
212
+ firstAt: string;
213
+ /** ISO 8601: newest session. */
214
+ lastAt: string;
215
+ /** ISO 8601: when you last set the status. */
216
+ reviewedAt?: string;
217
+ /** Your note. */
218
+ note?: string;
219
+ /** Why it closed, on a closed finding. */
220
+ closedReason?: "rules_changed" | "disabled" | "quiet" | "under_threshold";
221
+ /** ISO 8601: when it closed, on a closed finding. */
222
+ closedAt?: string;
223
+ /** ISO 8601: when it was first raised. */
224
+ createdAt: string;
225
+ /** ISO 8601: when it last changed. */
226
+ updatedAt: string;
227
+ }
228
+ /**
229
+ * Filters of {@link SignalsApi.list}, {@link SignalsApi.listPage} and
230
+ * {@link SignalsApi.iterate}, combined with AND. Newest activity first.
231
+ * @public
232
+ */
233
+ interface ListSignalsQuery {
234
+ kind?: SignalKind;
235
+ severity?: SignalSeverity;
236
+ /** Default `open`; `any` lists every status (closed findings for 30 days). */
237
+ status?: SignalStatus | "any";
238
+ /** Findings whose newest session is at or after this time (ISO 8601 or a `Date`). */
239
+ since?: string | Date;
240
+ /** Findings whose newest session is at or before this time (ISO 8601 or a `Date`). */
241
+ until?: string | Date;
242
+ /** Page size, 1 to 100 (the API's default is 50). */
243
+ limit?: number;
244
+ /** The {@link Page.nextCursor} of the previous page. */
245
+ cursor?: string;
246
+ }
247
+ /**
248
+ * Your mark on a finding, with {@link SignalsApi.update}. `open` opens a
249
+ * reviewed, false positive or closed finding again; `closed` is never set by
250
+ * a caller.
251
+ * @public
252
+ */
253
+ interface UpdateSignalInput {
254
+ status: "reviewed" | "false_positive" | "open";
255
+ /** Your note, at most 500 characters. It shows in your dashboard. */
256
+ note?: string;
257
+ }
258
+ /**
259
+ * `data` of `signal.raised` (a finding opened, or opened again) and
260
+ * `signal.escalated` (its severity rose). Never the sessions or the people:
261
+ * read the finding with {@link SignalsApi.get}.
262
+ * @public
263
+ */
264
+ interface SignalEventData {
265
+ /** The finding (`sig_...`). */
266
+ signalId: string;
267
+ kind: SignalKind;
268
+ /** Its severity now. */
269
+ severity: SignalSeverity;
270
+ grade: SignalGrade;
271
+ /** `signal.raised` only: always `open`. */
272
+ status?: "open";
273
+ /** `signal.escalated` only: the severity before. */
274
+ previousSeverity?: SignalSeverity;
275
+ /** ISO 8601: oldest session. */
276
+ firstAt: string;
277
+ /** ISO 8601: newest session. */
278
+ lastAt: string;
279
+ /** `signal.raised` only, ISO 8601: when it opened. */
280
+ raisedAt?: string;
281
+ /** `signal.escalated` only, ISO 8601: when the severity rose. */
282
+ escalatedAt?: string;
283
+ }
97
284
  /**
98
285
  * How a `person.reuse` session runs: `recheck` verifies the same person
99
286
  * again (liveness and face match against the stored photo), `step_up` raises
@@ -166,20 +353,6 @@ type DecisionReason = "liveness_inconclusive" | "match_inconclusive" | "document
166
353
  * @public
167
354
  */
168
355
  type EligibilityReason = "document_type_not_accepted" | "nationality_not_allowed" | "underage" | "age_unverifiable" | "underage_estimated";
169
- /**
170
- * Why a profile-v2 policy ended a session: a session-level
171
- * {@link SessionFailureReason} (location / anonymizer gate), or the failed
172
- * check's policy reason — an {@link EligibilityReason} or
173
- * `document_id_number_mismatch` (the document belongs to someone other than the
174
- * ID number the session was created for; `document_nni_mismatch` is its former
175
- * 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,
176
- * so the live step ended without a capture; the session is rejected at level 0 unless your flow has a fallback),
177
- * `subject_face_mismatch` (a step-up whose face did not match the person it was created for), or a review that
178
- * ended at its deadline: `review_timeout` (nobody decided it) or `review_split` (two reviewers disagreed and
179
- * nobody settled it); those two carry `decidedBy: "automatic"`.
180
- * @public
181
- */
182
- type PolicyFailureReason = SessionFailureReason | EligibilityReason | "document_id_number_mismatch" | "document_nni_mismatch" | "camera_unavailable" | "subject_face_mismatch" | "review_timeout" | "review_split" | "aml_hit";
183
356
  /**
184
357
  * The ID-number reasons a check's {@link SessionStep.reason} may carry (person data
185
358
  * spec Appendix A.2), each under its generic name and its former Mauritanian name:
@@ -194,7 +367,8 @@ type IdNumberReason = "id_number_invalid" | "nni_invalid" | "registry_record_not
194
367
  /**
195
368
  * Why the person had no camera (spec 2026-10-29 §3.4, 2026-10-30), when the SDK said: `denied` (the
196
369
  * person refused camera access) or `no_camera` (no usable camera: none found, an insecure page or a
197
- * browser that cannot capture). A detail under `failureReason: "camera_unavailable"`, never a reason of its own.
370
+ * browser that cannot capture). On the step's {@link SessionStep.reasonDetail} when its reason is
371
+ * `camera_unavailable` (the session's `reasonCode` is then `camera_unavailable`), never a reason of its own.
198
372
  * @public
199
373
  */
200
374
  type CameraUnavailableCause = "denied" | "no_camera";
@@ -208,21 +382,21 @@ type CameraUnavailableCause = "denied" | "no_camera";
208
382
  */
209
383
  type MatchReason = "name_mismatch" | "birth_date_mismatch" | "nationality_mismatch" | "document_number_mismatch";
210
384
  /**
211
- * Reasons a `face_match` {@link SessionStep.reason} carries when an earlier
212
- * human review of the same person, reference photo and face settled the match
213
- * score instead of a new review: `prior_review_approved` (the step passed;
214
- * final) and `prior_review_rejected` (the step failed; retryable, a better
215
- * capture sends the session to a reviewer again). Both are billed like
216
- * `review_band`. The step's {@link SessionStep.decision} has
217
- * `source: "prior_review"` and names your earlier session.
385
+ * Reason a `face_match` {@link SessionStep.reason} carries when an earlier
386
+ * human review of the same person, reference photo and face approved the
387
+ * match score instead of a new review: `prior_review_approved` (the step
388
+ * passed; final). It is billed like `review_band`. The step's
389
+ * {@link SessionStep.decision} has `source: "prior_review"` and names your
390
+ * earlier session.
218
391
  * @public
219
392
  */
220
- type PriorReviewReason = "prior_review_approved" | "prior_review_rejected";
393
+ type PriorReviewReason = "prior_review_approved";
221
394
  /**
222
- * Review outcome reasons any reviewable step may carry: `superseded_by_retry`
395
+ * Reasons any reviewable step may carry when its review ends without a verdict: `superseded_by_retry`
223
396
  * (a newer attempt of the same person took the review over; the session ends
224
- * with `outcome: null` and {@link Session.supersededBy}) and `review_split` (two reviewers disagreed and
225
- * nobody settled it before the review deadline; the session is rejected).
397
+ * `not_verified` with `reason: superseded` and {@link Session.supersededBy}) and `review_split` (two
398
+ * reviewers disagreed and nobody settled it before the review deadline; the session ends `not_verified`
399
+ * with `reason: inconclusive` and `closedBy: deadline`).
226
400
  * Both are billed and retryable: the person may verify again. Neither counts
227
401
  * toward the device cooldown.
228
402
  * @public
@@ -309,6 +483,16 @@ type ProbeBindingReason = "probe_not_from_liveness";
309
483
  type Locale = "ar" | "fr" | "en" | "es" | "pt" | "de";
310
484
  /** The environment a webhook was emitted from. @public */
311
485
  type SekyroEnvironment = "sandbox" | "live";
486
+ /**
487
+ * The shown band a scored step decided on ({@link SessionStep.band}), 0 to 1.
488
+ * @public
489
+ */
490
+ interface SessionStepBand {
491
+ /** Below this score the step fails. */
492
+ failBelow: number;
493
+ /** At or above this score the step passes. */
494
+ passAtOrAbove: number;
495
+ }
312
496
  /**
313
497
  * One check of a session, as the partner API projects it: enum/id fields only,
314
498
  * never civil data.
@@ -328,8 +512,16 @@ interface SessionStep {
328
512
  reasonDetail?: CameraUnavailableCause;
329
513
  /** Calibrated model score in [0, 1] for scored checks (liveness, face match). */
330
514
  calibratedScore?: number;
331
- /** The check failed after using all of its attempts. */
332
- attemptsExhausted?: boolean;
515
+ /**
516
+ * The lines the step decided on, on the same 0 to 1 scale as `calibratedScore`: below
517
+ * `failBelow` the step fails, at or above `passAtOrAbove` it passes, between them it is
518
+ * reviewed or retried. Liveness and face match steps only.
519
+ */
520
+ band?: SessionStepBand;
521
+ /** What the last counted attempt said ({@link StepResult}); absent before the first one. */
522
+ result?: StepResult;
523
+ /** Counted attempts and the cap ({@link SessionStepAttempts}): `used >= max` means none is left. */
524
+ attempts: SessionStepAttempts;
333
525
  /**
334
526
  * `portrait_icao` only (ID mode): the per-criterion ICAO report of the last
335
527
  * attempt — numbers and enums only, never the image.
@@ -348,6 +540,52 @@ interface SessionStep {
348
540
  decision?: SessionStepDecision;
349
541
  /** The step last ran simulated in the Sandbox (no paid or external service). */
350
542
  simulated?: true;
543
+ /** `doc_ocr` only: how the document was captured, and what an upload showed. */
544
+ document?: SessionStepDocument;
545
+ /** `portrait_icao` only (the ID photo step): how the delivered photo was produced. */
546
+ portrait?: SessionStepPortrait;
547
+ /**
548
+ * `face_match` only: what the live face was compared with: a registry photo,
549
+ * the document chip's photo, the printed document photo, or a photo of the
550
+ * person (a returning person or the photo you supplied).
551
+ */
552
+ referenceSource?: "registry" | "chip" | "document" | "person";
553
+ }
554
+ /**
555
+ * {@link SessionStep.document}: filmed with the camera, or a file the person
556
+ * uploaded, and what the upload showed.
557
+ * @public
558
+ */
559
+ interface SessionStepDocument {
560
+ source: "camera" | "upload";
561
+ /**
562
+ * Upload only (non-empty only): `edited` (an editing tool or a screenshot),
563
+ * `recaptured` (a photo of a screen or a print), `compressed` (heavily compressed).
564
+ */
565
+ findings?: Array<"edited" | "recaptured" | "compressed">;
566
+ }
567
+ /**
568
+ * {@link SessionStep.portrait}: how the delivered ID photo was produced. Codes
569
+ * and numbers only: fetch the photos as the `icao_portrait` media.
570
+ * @public
571
+ */
572
+ interface SessionStepPortrait {
573
+ /** Where the photo came from. */
574
+ source?: "camera" | "upload";
575
+ /** The delivered format. */
576
+ output?: "icao_9303" | "photo_35x45_300dpi" | "square_600";
577
+ /** What was corrected on the delivered photo, never the face. */
578
+ fixes: Array<"crop" | "scale" | "straighten" | "background" | "exposure" | "white_balance">;
579
+ /** When the flow has a face match: the delivered photo compared with its reference photo. */
580
+ referenceMatch?: {
581
+ status: "scored" | "no_reference";
582
+ score?: number;
583
+ passed?: boolean;
584
+ };
585
+ /** Present and `false` only: no liveness capture to compare the photo with. */
586
+ bound?: false;
587
+ /** Present and `false` only: the photo passed with an alert, it does not meet the ICAO rules. */
588
+ compliant?: false;
351
589
  }
352
590
  /**
353
591
  * The probe-quality measurement on a `face_match` step. Numbers only; `null`
@@ -796,13 +1034,17 @@ interface SessionFlowRef {
796
1034
  * @public
797
1035
  */
798
1036
  interface SimulateSessionInput {
799
- /** How the session ends. The flow must be able to reach it, else `422 simulate_outcome_unreachable`. */
800
- outcome: "approved" | "rejected" | "review";
801
1037
  /**
802
- * Only with `rejected`: the reason the failing step reports, e.g.
803
- * `spoof_detected`. No step on the path can fail with it: `422 simulate_reason_invalid`.
1038
+ * Where the session ends: `verified`, `not_verified` or `review_pending`. The flow must be able
1039
+ * to reach it, else `422 simulate_status_unreachable`.
804
1040
  */
805
- reason?: string;
1041
+ status: "verified" | "not_verified" | "review_pending";
1042
+ /**
1043
+ * Only with `not_verified`: the code a step on the path fails with, e.g. `spoof_detected`
1044
+ * (the session's {@link Session.reasonCode}). No step on the path can fail with it:
1045
+ * `422 simulate_reason_invalid`.
1046
+ */
1047
+ reasonCode?: string;
806
1048
  }
807
1049
  /**
808
1050
  * The API key in use, from {@link Sekyro.me}. Never carries the secret.
@@ -1020,11 +1262,6 @@ interface SessionNetwork {
1020
1262
  countryChanged: boolean;
1021
1263
  start: SessionNetworkEvent;
1022
1264
  }
1023
- /**
1024
- * Device signals detected on the end user's device.
1025
- * @public
1026
- */
1027
- type SessionDeviceSignal = "webdriver" | "headless" | "emulator" | "rooted" | "jailbroken" | "debugger" | "hooking" | "virtual_camera";
1028
1265
  /**
1029
1266
  * End-user device summary; absent when not recorded.
1030
1267
  * @public
@@ -1040,13 +1277,42 @@ interface SessionDevice {
1040
1277
  model?: string;
1041
1278
  /**
1042
1279
  * Opaque device identity inside your organization and environment, stable across sessions
1043
- * while the device keeps its install id. May be absent (for example without a device
1044
- * header).
1280
+ * while the device keeps its install id. After a handoff, the identity of the mobile device
1281
+ * that continued. May be absent (for example without a device header).
1045
1282
  */
1046
1283
  deviceId?: string;
1047
1284
  /** Hashed device keys of this session, per organization. */
1048
1285
  deviceKeys: string[];
1049
- signals: SessionDeviceSignal[];
1286
+ }
1287
+ /**
1288
+ * The computer a session started on before a handoff ({@link SessionHandoff.fromDevice}): its
1289
+ * summary only, no device id, keys or signals.
1290
+ * @public
1291
+ */
1292
+ type SessionHandoffDevice = Pick<SessionDevice, "platform" | "sdk" | "os" | "osVersion" | "browser" | "browserVersion" | "deviceClass" | "model">;
1293
+ /**
1294
+ * The session started on a computer that was shown the QR code at a camera step, and (once a
1295
+ * mobile device sent the first camera capture) continued on a phone or tablet. From then on
1296
+ * {@link Session.device}, its `deviceId` included, describes that mobile device and
1297
+ * `fromDevice` the computer.
1298
+ * @public
1299
+ */
1300
+ interface SessionHandoff {
1301
+ from: "desktop";
1302
+ /** What identified the computer: the request headers, or the Sekyro web SDK when they cannot tell. */
1303
+ fromSource: "headers" | "client";
1304
+ /** ISO 8601: when the computer was shown the handoff. */
1305
+ startedAt: string;
1306
+ /** Present once a mobile device sent the first camera capture. */
1307
+ to?: "mobile";
1308
+ /** What identified the mobile device: the request headers, the Sekyro web SDK, the Sekyro native SDK, or a passed device attestation. */
1309
+ toSource?: "headers" | "client" | "app" | "attestation";
1310
+ /** How the mobile device continued: an app whose device attestation passed, an app, or a browser. */
1311
+ continuedVia?: "attested_app" | "app" | "browser";
1312
+ /** ISO 8601: when the mobile device sent the first camera capture; absent while it has not. */
1313
+ continuedAt?: string;
1314
+ /** The computer the session started on, once its device was recorded. */
1315
+ fromDevice?: SessionHandoffDevice;
1050
1316
  }
1051
1317
  /**
1052
1318
  * The national eID that verified the session's identity (the `eid_auth` check
@@ -1167,8 +1433,8 @@ type IdentitySources = Partial<Record<IdentityScalarKey, IdentitySource[]>>;
1167
1433
  /**
1168
1434
  * The identity data a session read (its document, chip, registry, eID or your
1169
1435
  * supplied record), present once one identity step settled, whatever the
1170
- * outcome. On a person ({@link Person.identity}), the identity of the latest
1171
- * approved session that read one. Every key is optional. Sent to you only (the
1436
+ * status. On a person ({@link Person.identity}), the identity of the latest
1437
+ * verified session that read one. Every key is optional. Sent to you only (the
1172
1438
  * session view, the person view and the terminal webhooks).
1173
1439
  * @public
1174
1440
  */
@@ -1255,13 +1521,6 @@ interface MediaBytes {
1255
1521
  contentType: string;
1256
1522
  bytes: Uint8Array;
1257
1523
  }
1258
- /**
1259
- * Who closed a completed or failed session: `review` when a person decided
1260
- * the verdict (the deciding step carries its {@link SessionStepDecision}),
1261
- * `automatic` otherwise (a review deadline included).
1262
- * @public
1263
- */
1264
- type DecidedBy = "automatic" | "review";
1265
1524
  /**
1266
1525
  * The whitelisted session view returned by {@link SessionsApi.get}. Never
1267
1526
  * contains the client token.
@@ -1272,18 +1531,28 @@ interface Session {
1272
1531
  /** Sekyro flows: the flow version the session runs (absent on sessions created before flows). */
1273
1532
  flow?: SessionFlowRef;
1274
1533
  status: SessionStatus;
1275
- outcome: SessionOutcome | null;
1276
- /** Completed and failed sessions: who decided the verdict ({@link DecidedBy}). */
1277
- decidedBy?: DecidedBy;
1534
+ /** `not_verified` only: why ({@link SessionReason}). */
1535
+ reason?: SessionReason;
1536
+ /**
1537
+ * `not_verified` only: the detailed code behind `reason`, when one exists: the deciding step's
1538
+ * reason (e.g. `spoof_detected`, `camera_unavailable`) or a session stop code
1539
+ * ({@link SessionFailureReason}, e.g. `device_cooldown`).
1540
+ */
1541
+ reasonCode?: string;
1542
+ /** Finished sessions: who or what closed it ({@link ClosedBy}). */
1543
+ closedBy?: ClosedBy;
1544
+ /** `not_verified` only: the step that decided it, when one did. */
1545
+ step?: SessionDecidingStep;
1546
+ /** `closedBy: reviewer`: how the deciding step was decided. */
1547
+ decision?: SessionStepDecision;
1278
1548
  /**
1279
- * A session closed because a newer attempt of the same person took over its
1280
- * review: that session's id (`outcome` is `null`). Watch it instead.
1549
+ * `reason: superseded`: the newer session of the same person that took over
1550
+ * its review. Watch it instead.
1281
1551
  */
1282
1552
  supersededBy?: string;
1283
1553
  /**
1284
- * What the session proved ({@link VerificationLevel}), on a completed or
1285
- * failed session: `0` when it was rejected. Absent while the session is
1286
- * active, and from older API versions.
1554
+ * What the session proved ({@link VerificationLevel}), on a finished
1555
+ * session: `0` when it is `not_verified`. Absent while the session is open.
1287
1556
  */
1288
1557
  level?: VerificationLevel | null;
1289
1558
  /** How the level was proved; `null` while the session is active. */
@@ -1302,16 +1571,10 @@ interface Session {
1302
1571
  completedAt?: string | null;
1303
1572
  /** End-user network context; absent when not recorded. */
1304
1573
  network?: SessionNetwork;
1305
- /** End-user device; absent when not recorded. */
1574
+ /** End-user device; absent when not recorded. After a handoff, the mobile device that continued. */
1306
1575
  device?: SessionDevice;
1307
- /**
1308
- * Set when a profile-v2 policy ended the session: a session-level gate
1309
- * (location, anonymizer) or a failed check's policy reason (eligibility,
1310
- * `document_nni_mismatch`). Absent otherwise.
1311
- */
1312
- failureReason?: PolicyFailureReason;
1313
- /** With failureReason `camera_unavailable`: why (`denied` or `no_camera`), when the SDK said. Absent otherwise. */
1314
- failureDetail?: CameraUnavailableCause;
1576
+ /** Started on a computer, continued on a phone or tablet; absent when no handoff happened. */
1577
+ handoff?: SessionHandoff;
1315
1578
  /** The person (`per_...`) this session is linked to, once that person has passed a verification (absent before that). */
1316
1579
  personId?: string;
1317
1580
  /** Your own id for the person, from `person.externalRef` at create. */
@@ -1327,7 +1590,7 @@ interface Session {
1327
1590
  personConflict?: boolean;
1328
1591
  /**
1329
1592
  * ISO 8601 — when the end user's device may verify again; set with
1330
- * `failureReason: 'device_cooldown'`.
1593
+ * `reasonCode: 'device_cooldown'`.
1331
1594
  */
1332
1595
  retryAfter?: string;
1333
1596
  /**
@@ -1336,12 +1599,13 @@ interface Session {
1336
1599
  */
1337
1600
  overriddenFields?: string[];
1338
1601
  /**
1339
- * Risk signals recorded on the session (e.g. `device_velocity`,
1340
- * `timezone_mismatch`, `icao_non_compliant` when an `alert` ICAO policy flagged
1341
- * the selfie, `document_uploaded` and the `document_upload_*` signals when the
1342
- * person uploaded a photo of the document) — signals only, never a verdict by themselves.
1602
+ * The signals of the session ({@link SessionSignal}), at any status, from
1603
+ * the facts known so far (non-empty only): high severity first, then by
1604
+ * kind. Facts only, never a verdict by themselves.
1343
1605
  */
1344
- riskSignals?: string[];
1606
+ signals?: SessionSignal[];
1607
+ /** Your blocks and rules that flagged the session or held it for review (non-empty only). */
1608
+ blockMatches?: BlockMatch[];
1345
1609
  /**
1346
1610
  * `true` for a returning-user session (created with
1347
1611
  * {@link SessionPersonInput.reuse}): liveness + face match against the
@@ -1364,7 +1628,7 @@ interface Session {
1364
1628
  age?: AgeResult;
1365
1629
  /**
1366
1630
  * The identity data the session read ({@link Identity}), once one identity
1367
- * step settled. On an approved returning-user session, with a key that also
1631
+ * step settled. On a verified returning-user session, with a key that also
1368
1632
  * holds `people:read`, the identity stored on the person.
1369
1633
  */
1370
1634
  identity?: Identity;
@@ -1375,10 +1639,6 @@ interface Session {
1375
1639
  * (ES256 JWT, valid 10 minutes). Check it with {@link verifyResultToken}.
1376
1640
  */
1377
1641
  resultToken?: string;
1378
- /** Terminal sessions: other people the face matched in the duplicate search (non-empty only). */
1379
- duplicates?: ResultDuplicate[];
1380
- /** Terminal sessions: the duplicate search could not run. */
1381
- dedupUnavailable?: true;
1382
1642
  /**
1383
1643
  * Terminal sessions: a failure identification match
1384
1644
  * ({@link FailureIdentification}), present only for a match and only when the
@@ -1392,69 +1652,45 @@ interface Session {
1392
1652
  screening?: SessionScreening;
1393
1653
  }
1394
1654
  /**
1395
- * `data` of the session lifecycle events (`session.started` |
1396
- * `session.review_pending` | `session.completed` | `session.failed` |
1397
- * `session.expired`). `outcome`, `decidedBy` and `steps` travel on
1398
- * `completed` / `failed`, which are the one terminal event of a session: a
1399
- * reviewer's decision arrives as one of them with `decidedBy: "review"` and
1400
- * the `decision`. `review_pending` carries `steps` without an outcome;
1401
- * `expired` carries the status and the session's refs (`flow`, person ids,
1402
- * `overriddenFields`). `identity` and `media` (kinds only, never links) ride on
1403
- * `completed` / `failed` when the platform sends them.
1655
+ * One step on a session webhook: ids and enums only, never outputs.
1656
+ * @public
1657
+ */
1658
+ interface SessionEventStep {
1659
+ /** The node of your flow this step belongs to (e.g. `n_live`). Absent on sessions created before flows. */
1660
+ id?: string;
1661
+ /** What the step runs: the service of its node. */
1662
+ service?: ServiceId;
1663
+ state: CheckState;
1664
+ /** What the last counted attempt said ({@link StepResult}); absent before the first one. */
1665
+ result?: StepResult;
1666
+ /** Machine-readable reason of the last counted attempt, when it has one. */
1667
+ reason?: string;
1668
+ /** Counted attempts and the cap ({@link SessionStepAttempts}). */
1669
+ attempts: SessionStepAttempts;
1670
+ /** The step last ran simulated in the Sandbox. */
1671
+ simulated?: true;
1672
+ /** How a person decided this step ({@link SessionStepDecision}); absent when no person decided it. */
1673
+ decision?: SessionStepDecision;
1674
+ }
1675
+ /**
1676
+ * The fields every session webhook with a `steps[]` list carries
1677
+ * (`session.review_pending`, `session.verified`, `session.not_verified`).
1404
1678
  * @public
1405
1679
  */
1406
- interface SessionLifecycleEventData {
1680
+ interface SessionEventDataBase {
1407
1681
  /** The session id (`ses_...`). */
1408
1682
  sessionId: string;
1409
1683
  status: SessionStatus;
1410
- outcome?: SessionOutcome | null;
1411
- /** On `completed` / `failed`: who decided the verdict ({@link DecidedBy}). */
1412
- decidedBy?: DecidedBy;
1413
- /** On `completed` / `failed` with `decidedBy: "review"`: how the deciding step was decided. */
1414
- decision?: SessionStepDecision;
1415
- /** On `completed` / `failed`: the app the session belongs to. */
1684
+ /** The app the session belongs to. */
1416
1685
  appId?: string;
1417
- /** On `completed` / `failed`: what the session proved ({@link VerificationLevel}). */
1418
- level?: VerificationLevel | null;
1419
- /** On `completed` / `failed`: how the level was proved. */
1420
- assurance?: VerificationAssurance | null;
1421
- /** On `completed` / `failed`: the billing unit the session consumed. */
1422
- unit?: VerificationUnit | null;
1423
- /** On `completed` / `failed`: ISO 8601 terminal time. */
1424
- verifiedAt?: string;
1425
- /** On `completed` / `failed`: device and network risk facts, when recorded. */
1426
- risk?: ResultRisk;
1427
- /** On `completed` / `failed`: other subjects the face matched, when a duplicate search ran. */
1428
- duplicates?: ResultDuplicate[];
1429
- /**
1430
- * On `completed` / `failed`: the signed result token (ES256 JWT, valid
1431
- * 10 minutes). Check it with {@link verifyResultToken}; absent when
1432
- * result tokens are not enabled.
1433
- */
1434
- resultToken?: string;
1435
- /** On `completed` / `failed`: the duplicate search could not run. */
1436
- dedupUnavailable?: true;
1437
- /**
1438
- * The checks on the session's path (checks of a lane the person did not take
1439
- * are omitted), each with its {@link SessionStepDecision} when a person decided it.
1440
- */
1441
- steps?: Array<Pick<SessionStep, "id" | "service" | "state" | "simulated" | "decision">>;
1442
1686
  /** Sekyro flows: the flow version the session runs (absent on sessions created before flows). */
1443
1687
  flow?: SessionFlowRef;
1444
- /** Machine-readable reason, when the transition has one. */
1445
- reason?: string;
1446
- /** End-user network context (no IP); on `completed` / `failed` when recorded. */
1447
- network?: Omit<SessionNetwork, "ip">;
1448
- /** End-user device; on `completed` / `failed` when recorded. */
1449
- device?: SessionDevice;
1450
1688
  /**
1451
- * On `session.failed`: set when a profile-v2 policy ended the session — a
1452
- * session-level gate (location, anonymizer) or a failed check's policy
1453
- * reason (eligibility, `document_nni_mismatch`).
1689
+ * The checks on the session's path (checks of a lane the person did not take
1690
+ * are omitted), each with its result, reason and attempts, and its
1691
+ * {@link SessionStepDecision} when a person decided it.
1454
1692
  */
1455
- failureReason?: PolicyFailureReason;
1456
- /** On `session.failed` with failureReason `camera_unavailable`: why (`denied` or `no_camera`), when the SDK said. Absent otherwise. */
1457
- failureDetail?: CameraUnavailableCause;
1693
+ steps?: SessionEventStep[];
1458
1694
  /** The person (`per_...`) the session is linked to, once that person has passed a verification (absent before that). */
1459
1695
  personId?: string;
1460
1696
  /** Your own id for the person, from `person.externalRef` at create. */
@@ -1477,40 +1713,109 @@ interface SessionLifecycleEventData {
1477
1713
  * again) or `step_up` (raised to identity level). Absent otherwise.
1478
1714
  */
1479
1715
  reuseMode?: SubjectReuseMode;
1480
- /**
1481
- * On `completed` / `failed`: the `link.state` the session was created
1482
- * with, echoed back; absent when the session had none.
1483
- */
1716
+ /** Dotted paths the session's create-time {@link CreateSessionInput.overrides} changed. */
1717
+ overriddenFields?: string[];
1718
+ }
1719
+ /**
1720
+ * The fields of the two terminal events, `session.verified` and
1721
+ * `session.not_verified`. Each session sends exactly one of them.
1722
+ * @public
1723
+ */
1724
+ interface SessionClosedEventDataBase extends SessionEventDataBase {
1725
+ /** Who or what closed the session ({@link ClosedBy}). */
1726
+ closedBy: ClosedBy;
1727
+ /** `closedBy: reviewer`: how the deciding step was decided. */
1728
+ decision?: SessionStepDecision;
1729
+ /** What the session proved ({@link VerificationLevel}); `0` on `session.not_verified`. */
1730
+ level?: VerificationLevel | null;
1731
+ /** How the level was proved. */
1732
+ assurance?: VerificationAssurance | null;
1733
+ /** The billing unit the session consumed. */
1734
+ unit?: VerificationUnit | null;
1735
+ /** ISO 8601: when the session closed. */
1736
+ verifiedAt?: string;
1737
+ /** The session's signals ({@link SessionSignal}, non-empty only). */
1738
+ signals?: SessionSignal[];
1739
+ /** Your blocks and rules that flagged the session or held it for review (non-empty only). */
1740
+ blockMatches?: BlockMatch[];
1741
+ /** End-user network context (no IP), when recorded. */
1742
+ network?: Omit<SessionNetwork, "ip">;
1743
+ /** End-user device, when recorded. */
1744
+ device?: SessionDevice;
1745
+ /** The `link.state` the session was created with, echoed back; absent when the session had none. */
1484
1746
  link?: {
1485
1747
  state: string;
1486
1748
  };
1487
- /**
1488
- * On `session.failed` with `failureReason: 'device_cooldown'`: ISO time
1489
- * from which the device may start a new verification.
1490
- */
1491
- retryAfter?: string;
1492
- /** Dotted paths the session's create-time {@link CreateSessionInput.overrides} changed. */
1493
- overriddenFields?: string[];
1494
- /** On `completed` / `failed`: the contacts verified in this session (passed OTP checks only). */
1749
+ /** The contacts verified in this session (passed OTP checks only). */
1495
1750
  verifiedContacts?: VerifiedContacts;
1496
- /** On `completed` / `failed`: the minimum age the session proved and how ({@link AgeResult}), when the flow sets one. */
1497
- age?: AgeResult;
1498
- /** On `completed` / `failed`: the identity data the session read ({@link Identity}), when the platform sends it. */
1751
+ /** The identity data the session read ({@link Identity}), when the platform sends it. */
1499
1752
  identity?: Identity;
1500
- /** On `completed` / `failed`: the media kinds of the session (never links), when the platform sends them. */
1753
+ /** The media kinds of the session (never links), when the platform sends them. */
1501
1754
  media?: MediaKind[];
1502
1755
  /**
1503
- * On `completed` / `failed`: a failure identification match
1504
- * ({@link FailureIdentification}), when the setting is on and the search
1505
- * found one before the event was sent. A signal, never a decision.
1756
+ * A failure identification match ({@link FailureIdentification}), when the
1757
+ * setting is on and the search found one before the event was sent. A
1758
+ * signal, never a decision.
1506
1759
  */
1507
1760
  failureIdentification?: FailureIdentification;
1508
- /** On `completed` / `failed`: the AML screening result ({@link SessionScreening}), when the flow screens the person. */
1761
+ /** The AML screening result ({@link SessionScreening}), when the flow screens the person. */
1509
1762
  screening?: SessionScreening;
1510
1763
  }
1764
+ /**
1765
+ * `data` of `session.review_pending`: a step waits for a person's review. The
1766
+ * session stays open; its terminal event follows.
1767
+ * @public
1768
+ */
1769
+ interface SessionReviewPendingEventData extends SessionEventDataBase {
1770
+ status: "review_pending";
1771
+ }
1772
+ /**
1773
+ * `data` of `session.verified`: the session is verified. The signed result
1774
+ * token rides on it when result tokens are on.
1775
+ * @public
1776
+ */
1777
+ interface SessionVerifiedEventData extends SessionClosedEventDataBase {
1778
+ status: "verified";
1779
+ /** The minimum age the session proved and how ({@link AgeResult}), when the flow sets one. */
1780
+ age?: AgeResult;
1781
+ /**
1782
+ * The signed result token (ES256 JWT, valid 10 minutes). Check it with
1783
+ * {@link verifyResultToken}; absent when result tokens are not enabled.
1784
+ */
1785
+ resultToken?: string;
1786
+ }
1787
+ /**
1788
+ * `data` of `session.not_verified`: the session closed without a
1789
+ * verification, for the {@link SessionReason} in `reason`. Expiry,
1790
+ * cancellation and supersession end this way too.
1791
+ * @public
1792
+ */
1793
+ interface SessionNotVerifiedEventData extends SessionClosedEventDataBase {
1794
+ status: "not_verified";
1795
+ /** Why the session was not verified ({@link SessionReason}). */
1796
+ reason: SessionReason;
1797
+ /**
1798
+ * The detailed code behind `reason`, when one exists: the deciding step's
1799
+ * reason (e.g. `spoof_detected`) or a session stop code
1800
+ * ({@link SessionFailureReason}, e.g. `device_cooldown`).
1801
+ */
1802
+ reasonCode?: string;
1803
+ /** The step that decided it, when one did. */
1804
+ step?: SessionDecidingStep;
1805
+ /** `reason: superseded`: the newer session of the same person (`ses_...`). */
1806
+ supersededBy?: string;
1807
+ /** `reasonCode: device_cooldown`: ISO time from which the device may start a new verification. */
1808
+ retryAfter?: string;
1809
+ }
1810
+ /**
1811
+ * `data` of the session events that carry `steps[]`: narrow on `status`
1812
+ * (`review_pending`, `verified` or `not_verified`).
1813
+ * @public
1814
+ */
1815
+ type SessionLifecycleEventData = SessionReviewPendingEventData | SessionVerifiedEventData | SessionNotVerifiedEventData;
1511
1816
  /**
1512
1817
  * `data` of `person.updated`: either a session linked to the person reached
1513
- * a terminal state (`sessionId`, session `status`, `outcome`), or the person
1818
+ * a terminal state (`sessionId`, session `status`, `reason`), or the person
1514
1819
  * was revoked (`status: 'revoked'`, no session). Ids and enums only.
1515
1820
  * @public
1516
1821
  */
@@ -1520,8 +1825,8 @@ interface PersonUpdatedEventData {
1520
1825
  /** The session that reached a terminal state; absent on a revocation. */
1521
1826
  sessionId?: string;
1522
1827
  status: SessionStatus | "revoked";
1523
- /** The session outcome; absent on a revocation. */
1524
- outcome?: SessionOutcome | null;
1828
+ /** `not_verified` sessions: why ({@link SessionReason}); absent on a revocation. */
1829
+ reason?: SessionReason;
1525
1830
  /** The session's level; absent on a revocation. */
1526
1831
  level?: VerificationLevel | null;
1527
1832
  /** The session's assurance; absent on a revocation. */
@@ -1540,7 +1845,7 @@ interface PersonUpdatedEventData {
1540
1845
  interface PersonEnrolledEventData {
1541
1846
  /** The person (`per_...`). */
1542
1847
  personId: string;
1543
- /** The approved session the reference photo came from. */
1848
+ /** The verified session the reference photo came from. */
1544
1849
  sessionId: string;
1545
1850
  assurance: SubjectAssurance;
1546
1851
  }
@@ -1588,7 +1893,8 @@ interface PersonSession {
1588
1893
  /** ISO 8601 — when the session was linked. */
1589
1894
  at: string;
1590
1895
  status: SessionStatus;
1591
- outcome: SessionOutcome | null;
1896
+ /** `not_verified` sessions: why ({@link SessionReason}). */
1897
+ reason?: SessionReason;
1592
1898
  /** What the session proved; present only when stored (sessions linked before the field existed have none). */
1593
1899
  level?: VerificationLevel;
1594
1900
  /** How the session's level was proved; present only when stored. */
@@ -1613,9 +1919,9 @@ interface Person {
1613
1919
  firstSeenAt: string;
1614
1920
  /** ISO 8601. */
1615
1921
  lastSeenAt: string;
1616
- /** ISO 8601, or `null` before the first approved session. */
1922
+ /** ISO 8601, or `null` before the first verified session. */
1617
1923
  lastPassedAt: string | null;
1618
- /** ISO 8601 of the last approved full or returning session, or `null`. */
1924
+ /** ISO 8601 of the last verified full or returning session, or `null`. */
1619
1925
  lastVerifiedAt: string | null;
1620
1926
  /** The stored reference photo's origin and date — `null` until one is stored. */
1621
1927
  reference: {
@@ -1624,12 +1930,12 @@ interface Person {
1624
1930
  } | null;
1625
1931
  assurance: SubjectAssurance | null;
1626
1932
  /**
1627
- * The highest {@link VerificationLevel} an approved linked session proved;
1933
+ * The highest {@link VerificationLevel} a verified linked session proved;
1628
1934
  * `0` once the subject is revoked; `null` when no terminal session was
1629
1935
  * recorded since the field exists. Absent from API versions before the field.
1630
1936
  */
1631
1937
  level?: VerificationLevel | null | undefined;
1632
- /** ISO 8601: when {@link Person.level} was last proved (the latest approved session at that level or higher); `null` with it. Absent with it. */
1938
+ /** ISO 8601: when {@link Person.level} was last proved (the latest verified session at that level or higher); `null` with it. Absent with it. */
1633
1939
  levelAt?: string | null | undefined;
1634
1940
  /** The assurance of the session that proved {@link Person.level}; `null` with it. Absent with it. */
1635
1941
  levelAssurance?: VerificationAssurance | null | undefined;
@@ -1640,12 +1946,12 @@ interface Person {
1640
1946
  * (`settings.returning`: turned on, and `maxAgeMonths` when set).
1641
1947
  */
1642
1948
  returningReady: boolean;
1643
- /** The verified name / birth date of the latest approved session. */
1949
+ /** The verified name / birth date of the latest verified session. */
1644
1950
  display?: {
1645
1951
  name?: string;
1646
1952
  birthDate?: string;
1647
1953
  };
1648
- /** The identity of the latest approved session that read one ({@link Identity}). */
1954
+ /** The identity of the latest verified session that read one ({@link Identity}). */
1649
1955
  identity?: Identity;
1650
1956
  }
1651
1957
  /**
@@ -1657,6 +1963,10 @@ interface ListSessionsQuery {
1657
1963
  /** Your own id for the person (1 to 128 characters), exact match. */
1658
1964
  externalRef?: string;
1659
1965
  status?: SessionStatus;
1966
+ /** Only `not_verified` sessions closed for this reason. */
1967
+ reason?: SessionReason;
1968
+ /** Only ended sessions closed this way. */
1969
+ closedBy?: ClosedBy;
1660
1970
  /** A flow id (`flw_...`) or slug. */
1661
1971
  flow?: string;
1662
1972
  /** Sessions created at or after this time (ISO 8601 or a `Date`). */
@@ -1665,6 +1975,13 @@ interface ListSessionsQuery {
1665
1975
  createdBefore?: string | Date;
1666
1976
  /** Only the sessions of this device (`device.deviceId` of a session). */
1667
1977
  deviceId?: string;
1978
+ /**
1979
+ * Only the sessions whose signals held this kind, or one of these kinds
1980
+ * (sent as a comma list), including findings since closed.
1981
+ */
1982
+ signalKind?: SignalKind | SignalKind[];
1983
+ /** Only the sessions whose strongest signal reached at least this severity. */
1984
+ signalSeverity?: SignalSeverity;
1668
1985
  /** Page size, 1 to 100 (the API's default is 50). */
1669
1986
  limit?: number;
1670
1987
  /** The {@link Page.nextCursor} of the previous page. */
@@ -1943,7 +2260,7 @@ interface ListScreeningsQuery {
1943
2260
  interface AmlMatchFlaggedEventData {
1944
2261
  screeningId: string;
1945
2262
  trigger: ScreeningTrigger;
1946
- /** The session the screening ran in, or the person's latest approved session. */
2263
+ /** The session the screening ran in, or the person's latest verified session. */
1947
2264
  sessionId?: string;
1948
2265
  /** The person (`per_...`), once known. */
1949
2266
  personId?: string;
@@ -1995,24 +2312,6 @@ interface PersonSuspiciousActivityEventData {
1995
2312
  sessionId: string;
1996
2313
  count: number;
1997
2314
  }
1998
- /**
1999
- * `data` of `session.superseded`: a session that waited for a review closed
2000
- * because a newer attempt of the same person took that review over. The
2001
- * session ends with status `completed`, `outcome: null` and `supersededBy`;
2002
- * its review step failed with `superseded_by_retry`; nothing of it is deleted.
2003
- * Read the newer session (`supersededBy`) for the verdict. This is the one
2004
- * terminal event of the superseded session.
2005
- * @public
2006
- */
2007
- interface SessionSupersededEventData {
2008
- /** The superseded session (`ses_...`). */
2009
- sessionId: string;
2010
- /** The newer session of the same person that took the review over (`ses_...`). */
2011
- supersededBy: string;
2012
- reason: "superseded_by_retry";
2013
- /** Your own id for the person, from `person.externalRef` at create. */
2014
- externalRef?: string;
2015
- }
2016
2315
  /**
2017
2316
  * `usage.threshold_reached`: a usage, credit or spend threshold of the organization's
2018
2317
  * plan was reached (sent once per threshold and period). `kind` is `tier` for a monthly
@@ -2034,6 +2333,22 @@ interface UsageThresholdReachedEventData {
2034
2333
  /** Tier alerts: verifications beyond the tier this month. */
2035
2334
  overage?: number;
2036
2335
  }
2336
+ /**
2337
+ * `data` of `session.retake_requested`: a reviewer sent the session back for a new capture of
2338
+ * one step. The session is open again until `expiresAt`.
2339
+ * @public
2340
+ */
2341
+ interface SessionRetakeRequestedEventData {
2342
+ /** The session (`ses_...`). */
2343
+ sessionId: string;
2344
+ status: "in_progress";
2345
+ /** The step to capture again. */
2346
+ step: SessionDecidingStep;
2347
+ /** ISO 8601: the new link expiry. */
2348
+ expiresAt: string;
2349
+ /** Your own id for the person, from `person.externalRef` at create. */
2350
+ externalRef?: string;
2351
+ }
2037
2352
  /**
2038
2353
  * Event type → the shape of its `data`. Session events are typed; the
2039
2354
  * remaining events carry an open record until their payloads are frozen.
@@ -2041,11 +2356,12 @@ interface UsageThresholdReachedEventData {
2041
2356
  */
2042
2357
  interface WebhookEventDataMap {
2043
2358
  "session.started": Record<string, unknown>;
2044
- "session.review_pending": SessionLifecycleEventData;
2045
- "session.completed": SessionLifecycleEventData;
2046
- "session.expired": SessionLifecycleEventData;
2047
- "session.failed": SessionLifecycleEventData;
2048
- "session.superseded": SessionSupersededEventData;
2359
+ "session.review_pending": SessionReviewPendingEventData;
2360
+ "session.verified": SessionVerifiedEventData;
2361
+ "session.not_verified": SessionNotVerifiedEventData;
2362
+ "session.retake_requested": SessionRetakeRequestedEventData;
2363
+ "signal.raised": SignalEventData;
2364
+ "signal.escalated": SignalEventData;
2049
2365
  "person.enrolled": PersonEnrolledEventData;
2050
2366
  "person.updated": PersonUpdatedEventData;
2051
2367
  "person.suspicious_activity": PersonSuspiciousActivityEventData;
@@ -2086,8 +2402,9 @@ interface WebhookEnvelopeOf<E extends WebhookEventType> {
2086
2402
  * ```ts
2087
2403
  * const envelope = verifyWebhook(rawBody, header, secret);
2088
2404
  * switch (envelope.event) {
2089
- * case "session.completed":
2090
- * envelope.data.outcome; // SessionOutcome | null | undefined
2405
+ * case "session.not_verified":
2406
+ * envelope.data.reason; // SessionReason
2407
+ * envelope.data.closedBy; // ClosedBy
2091
2408
  * break;
2092
2409
  * case "person.updated":
2093
2410
  * envelope.data.personId; // "per_..."
@@ -2172,8 +2489,8 @@ declare class SessionsApi {
2172
2489
  get(id: string): Promise<Session>;
2173
2490
  /**
2174
2491
  * `POST /sessions/:id/cancel` — stop a session that has not ended. The
2175
- * hosted link stops working, and one `session.failed` with
2176
- * `failureReason: "cancelled_by_organization"` is sent. Returns the
2492
+ * hosted link stops working, and one `session.not_verified` with
2493
+ * `reason: "cancelled"` and `closedBy: "organization"` is sent. Returns the
2177
2494
  * cancelled session. `409 session_not_cancellable` once the session has
2178
2495
  * ended (a repeated cancel included). Needs the `sessions:create` scope.
2179
2496
  */
@@ -2212,7 +2529,7 @@ declare class SessionsApi {
2212
2529
  *
2213
2530
  * @example
2214
2531
  * ```ts
2215
- * for await (const s of sekyro.sessions.iterate({ status: "completed" })) {
2532
+ * for await (const s of sekyro.sessions.iterate({ status: "verified" })) {
2216
2533
  * console.log(s.id);
2217
2534
  * }
2218
2535
  * ```
@@ -2234,9 +2551,10 @@ declare class SessionsApi {
2234
2551
  mediaBytes(id: string, kind: MediaKind, opts?: MediaBytesOptions): Promise<MediaBytes>;
2235
2552
  /**
2236
2553
  * `GET /sessions/:id/result-token`: a freshly signed result token for a
2237
- * finished session (valid 10 minutes; check it with
2554
+ * verified session (valid 10 minutes; check it with
2238
2555
  * {@link verifyResultToken}). `409 session_not_terminal` while the session
2239
- * is still active. Needs the `sessions:read` scope.
2556
+ * is still open, `409 session_not_verified` for a `not_verified` session
2557
+ * (it has no token). Needs the `sessions:read` scope.
2240
2558
  */
2241
2559
  resultToken(id: string): Promise<ResultTokenResponse>;
2242
2560
  /**
@@ -2246,7 +2564,7 @@ declare class SessionsApi {
2246
2564
  * behave as for a session driven by a person. Never billed. Returns the
2247
2565
  * finished session; pass an `idempotencyKey` to make a retry safe. Errors:
2248
2566
  * `400 sandbox_only` (Live key), `409 session_not_simulated` (bound to a
2249
- * tester), `409 session_already_final`, `422 simulate_outcome_unreachable`
2567
+ * tester), `409 session_already_final`, `422 simulate_status_unreachable`
2250
2568
  * (`details.issues` says why), `422 simulate_reason_invalid`. Needs the
2251
2569
  * `sessions:create` scope.
2252
2570
  */
@@ -2338,7 +2656,7 @@ declare class PeopleApi {
2338
2656
  /**
2339
2657
  * `DELETE /people/:id` — deletes the person's stored photos, face
2340
2658
  * templates and identifiers, and the personal data and media of their
2341
- * sessions, which it unlinks (they keep their outcome and steps). Emits
2659
+ * sessions, which it unlinks (they keep their status and steps). Emits
2342
2660
  * `person.deleted`. Cannot be undone; a second call answers `404`.
2343
2661
  */
2344
2662
  delete(id: string): Promise<DeletedPerson>;
@@ -2390,6 +2708,38 @@ declare class BlocksApi {
2390
2708
  /** `POST /blocks/check`: whether a value is blocked. A POST, so it never sits in a URL or a log. */
2391
2709
  check(input: BlockCheckInput): Promise<BlockCheck>;
2392
2710
  }
2711
+ /**
2712
+ * Findings: sessions of this environment that share a key and met a pattern
2713
+ * ({@link Signal}). Exposed as {@link Sekyro.signals}. Reading needs the
2714
+ * `signals:read` scope, {@link SignalsApi.update} `signals:write`. Every call
2715
+ * answers `403 signals_unavailable` while Signals are not available in the
2716
+ * environment. Exported as a TYPE only.
2717
+ * @public
2718
+ */
2719
+ declare class SignalsApi {
2720
+ private readonly t;
2721
+ /** @internal */
2722
+ constructor(t: {
2723
+ call<T>(method: HttpMethod, path: string, body?: unknown, idempotencyKey?: string): Promise<T>;
2724
+ page<T>(path: string): Promise<Page<T>>;
2725
+ });
2726
+ /**
2727
+ * The first page of the findings (`GET /signals`), newest activity first;
2728
+ * `open` ones unless `status` says otherwise. Every page: {@link SignalsApi.iterate}.
2729
+ */
2730
+ list(query?: ListSignalsQuery): Promise<Signal[]>;
2731
+ /** One page of {@link SignalsApi.list} with its `nextCursor` (absent on the last page). */
2732
+ listPage(query?: ListSignalsQuery): Promise<Page<Signal>>;
2733
+ /** Every finding matching `query`, following `nextCursor` page after page. */
2734
+ iterate(query?: ListSignalsQuery): AsyncGenerator<Signal, void, undefined>;
2735
+ /** `GET /signals/:id`: `404 signal_not_found` for an id of another environment. */
2736
+ get(id: string): Promise<Signal>;
2737
+ /**
2738
+ * `PATCH /signals/:id`: mark a finding `reviewed` or `false_positive`, or
2739
+ * open it again (`open`), with an optional note. Answers the finding.
2740
+ */
2741
+ update(id: string, input: UpdateSignalInput, opts?: RequestOptions): Promise<Signal>;
2742
+ }
2393
2743
  /**
2394
2744
  * What you know about a device before you block it. Exposed as {@link Sekyro.devices}. Needs the
2395
2745
  * `blocks:read` or `blocks:write` scope. Exported as a TYPE only.
@@ -2430,6 +2780,7 @@ declare class Sekyro {
2430
2780
  readonly sessions: SessionsApi;
2431
2781
  readonly people: PeopleApi;
2432
2782
  readonly blocks: BlocksApi;
2783
+ readonly signals: SignalsApi;
2433
2784
  readonly devices: DevicesApi;
2434
2785
  readonly flows: FlowsApi;
2435
2786
  constructor(opts: SekyroOptions);
@@ -2441,4 +2792,4 @@ declare class Sekyro {
2441
2792
  me(): Promise<ApiKeyIdentity>;
2442
2793
  }
2443
2794
 
2444
- export { type FlowSummary as $, type AgeMethod as A, type Block as B, type CreatedSession as C, type CreateBlockInput as D, type CreateSessionInput as E, type FetchLike as F, DEFAULT_BASE_URL as G, DEFAULT_TIMEOUT_MS as H, type DecidedBy as I, type DecisionReason as J, type DeepPartial as K, type Locale as L, type DeletedPerson as M, type DeliverOptions as N, type Device as O, DevicesApi as P, type DocumentSubstitutionSettings as Q, type ReviewReason as R, Sekyro as S, type EidResult as T, type EligibilityReason as U, type VerificationLevel as V, type WebhookEventType as W, type ExtendLinkInput as X, type FlowOverridableSettings as Y, type FlowOverrides as Z, type FlowServiceSettings as _, type ServiceId as a, type SessionLinkInput as a$, FlowsApi as a0, type IdNumberReason as a1, type Identity as a2, type IdentityBirthPlace as a3, type IdentityDocument as a4, type IdentityIdNumber as a5, type IdentityMethod as a6, type IdentityName as a7, type IdentityScalarKey as a8, type IdentitySource as a9, type PolicyFailureReason as aA, type PortraitReportEntry as aB, type PriorReviewReason as aC, type ProbeBindingReason as aD, type ProbeQuality as aE, type ProfileDocumentType as aF, type RequestOptions as aG, type ResultTokenResponse as aH, type ReviewOutcomeReason as aI, type RevokePersonInput as aJ, type ScreenPersonInput as aK, type Screening as aL, type ScreeningHit as aM, type ScreeningHitSummary as aN, type ScreeningList as aO, type ScreeningStatus as aP, type ScreeningTrigger as aQ, type ScreeningUnavailableReason as aR, type SekyroOptions as aS, type Session as aT, type SessionDevice as aU, type SessionDeviceSignal as aV, type SessionFailureReason as aW, type SessionFlowRef as aX, type SessionLifecycleEventData as aY, type SessionLinkDelivery as aZ, type SessionLinkExpiry as a_, type IdentitySources as aa, type LevelTarget as ab, type LiftBlockInput as ac, type ListBlocksQuery as ad, type ListPeopleQuery as ae, type ListScreeningsQuery as af, type ListSessionsQuery as ag, type MatchReason as ah, type MediaBytes as ai, type MediaBytesOptions as aj, type MediaItem as ak, type MediaKind as al, type MediaList as am, type NameForm as an, type Page as ao, PeopleApi as ap, type Person as aq, type PersonBirthPlaceInput as ar, type PersonDeletedEventData as as, type PersonDocumentInput as at, type PersonEnrolledEventData as au, type PersonSession as av, type PersonSessionInput as aw, type PersonSessionTarget as ax, type PersonSuspiciousActivityEventData as ay, type PersonUpdatedEventData as az, type SessionPersonInput as b, type SessionNetwork as b0, type SessionNetworkEvent as b1, type SessionScreening as b2, type SessionStatus as b3, type SessionStep as b4, type SessionStepDecision as b5, type SessionSupersededEventData as b6, SessionsApi as b7, type SimulateSessionInput as b8, type SubjectAssurance as b9, type SubjectIdNumber as ba, type SubjectName as bb, type SubjectReferenceSource as bc, type SubjectReuseTarget as bd, type SubjectStatus as be, type UsageThresholdReachedEventData as bf, type VerifiedContacts as bg, type WebhookEnvelopeOf as bh, type WebhookEventDataMap as bi, 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 AmlMatchFlaggedEventData as n, type ApiKeyIdentity as o, type BlockCheck as p, type BlockCheckInput as q, type BlockDuration as r, type BlockIdNumber as s, type BlockKind as t, type BlockReason as u, BlocksApi as v, type CameraUnavailableCause as w, type CheckState as x, type CheckType as y, type ConnectorIdentity as z };
2795
+ export { type FlowSummary as $, type AgeMethod as A, type Block as B, type CreatedSession as C, type ConnectorIdentity as D, type CreateBlockInput as E, type FetchLike as F, type CreateSessionInput as G, DEFAULT_BASE_URL as H, DEFAULT_TIMEOUT_MS as I, type DecisionReason as J, type DeepPartial as K, type Locale as L, type DeletedPerson as M, type DeliverOptions as N, type Device as O, DevicesApi as P, type DocumentSubstitutionSettings as Q, type ReviewReason as R, type SessionReason as S, type EidResult as T, type EligibilityReason as U, type VerificationLevel as V, type WebhookEventType as W, type ExtendLinkInput as X, type FlowOverridableSettings as Y, type FlowOverrides as Z, type FlowServiceSettings as _, Sekyro as a, type SessionFlowRef as a$, FlowsApi as a0, type IdNumberReason as a1, type Identity as a2, type IdentityBirthPlace as a3, type IdentityDocument as a4, type IdentityIdNumber as a5, type IdentityMethod as a6, type IdentityName as a7, type IdentityScalarKey as a8, type IdentitySource as a9, type PersonSuspiciousActivityEventData as aA, type PersonUpdatedEventData as aB, type PortraitReportEntry as aC, type PriorReviewReason as aD, type ProbeBindingReason as aE, type ProbeQuality as aF, type ProfileDocumentType as aG, type RequestOptions as aH, type ResultTokenResponse as aI, type ReviewOutcomeReason as aJ, type RevokePersonInput as aK, type ScreenPersonInput as aL, type Screening as aM, type ScreeningHit as aN, type ScreeningHitSummary as aO, type ScreeningList as aP, type ScreeningStatus as aQ, type ScreeningTrigger as aR, type ScreeningUnavailableReason as aS, type SekyroOptions as aT, type Session as aU, type SessionClosedEventDataBase as aV, type SessionDecidingStep as aW, type SessionDevice as aX, type SessionEventDataBase as aY, type SessionEventStep as aZ, type SessionFailureReason as a_, type IdentitySources as aa, type LevelTarget as ab, type LiftBlockInput as ac, type ListBlocksQuery as ad, type ListPeopleQuery as ae, type ListScreeningsQuery as af, type ListSessionsQuery as ag, type ListSignalsQuery as ah, type MatchReason as ai, type MediaBytes as aj, type MediaBytesOptions as ak, type MediaItem as al, type MediaKind as am, type MediaList as an, type NameForm as ao, type Page as ap, PeopleApi as aq, type Person as ar, type PersonBirthPlaceInput as as, type PersonDeletedEventData as at, type PersonDocumentInput as au, type PersonEnrolledEventData as av, type PersonRef as aw, type PersonSession as ax, type PersonSessionInput as ay, type PersonSessionTarget as az, type ServiceId as b, type SessionHandoff as b0, type SessionHandoffDevice as b1, type SessionLifecycleEventData as b2, type SessionLinkDelivery as b3, type SessionLinkExpiry as b4, type SessionLinkInput as b5, type SessionNetwork as b6, type SessionNetworkEvent as b7, type SessionNotVerifiedEventData as b8, type SessionRetakeRequestedEventData as b9, type SubjectReuseTarget as bA, type SubjectStatus as bB, type UpdateSignalInput as bC, type UsageThresholdReachedEventData as bD, type VerifiedContacts as bE, type WebhookEnvelopeOf as bF, type WebhookEventDataMap as bG, type SessionReviewPendingEventData as ba, type SessionScreening as bb, type SessionStatus as bc, type SessionStep as bd, type SessionStepAttempts as be, type SessionStepBand as bf, type SessionStepDecision as bg, type SessionStepDocument as bh, type SessionStepPortrait as bi, type SessionVerifiedEventData as bj, SessionsApi as bk, type Signal as bl, type SignalEventData as bm, type SignalEvidence as bn, type SignalGrade as bo, type SignalKeyKind as bp, type SignalKind as bq, type SignalSeverity as br, type SignalStatus as bs, SignalsApi as bt, type SimulateSessionInput as bu, type StepResult as bv, type SubjectAssurance as bw, type SubjectIdNumber as bx, type SubjectName as by, type SubjectReferenceSource as bz, type SessionPersonInput as c, type WebhookEnvelope as d, type SekyroEnvironment as e, type VerificationAssurance as f, type VerificationUnit as g, type SubjectReuseMode as h, type ResultCheckProofs as i, type SessionSignal as j, type FailureIdentification as k, type AgeResult as l, type AmlMatchFlaggedEventData as m, type ApiKeyIdentity as n, type BlockCheck as o, type BlockCheckInput as p, type BlockDuration as q, type BlockIdNumber as r, type BlockKind as s, type BlockMatch as t, type BlockReason as u, BlocksApi as v, type CameraUnavailableCause as w, type CheckState as x, type CheckType as y, type ClosedBy as z };