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

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.
@@ -11,9 +11,12 @@ type SessionStatus = "created" | "in_progress" | "review_pending" | "completed"
11
11
  /**
12
12
  * Terminal verdict, orthogonal to {@link SessionStatus}. `null` until the session
13
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.
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}.
17
20
  * @public
18
21
  */
19
22
  type SessionOutcome = "approved" | "review" | "rejected" | "superseded";
@@ -85,8 +88,9 @@ interface AgeResult {
85
88
  estimate?: number;
86
89
  sigma?: number;
87
90
  }
88
- /** Another subject the person's face already matched (duplicate search). @public */
91
+ /** Another person the face already matched (duplicate search). @public */
89
92
  interface ResultDuplicate {
93
+ /** That person's id, bare (24 hexadecimal characters). */
90
94
  subjectId: string;
91
95
  externalRef?: string;
92
96
  }
@@ -130,10 +134,14 @@ type CheckState = "pending" | "input_required" | "processing" | "passed" | "fail
130
134
  * people than `device.velocity` allows, with `action: 'block'`;
131
135
  * - `device_cooldown` — the device had too many rejected sessions
132
136
  * (`cooldown` tiers); {@link Session.retryAfter} says when it may try again.
133
- * Not billed.
137
+ * Not billed;
138
+ * - `platform_unsupported` — the flow requires a chip read and the person
139
+ * opened the link on the web (the link stays usable in a native app);
140
+ * - `cancelled_by_organization` — you cancelled the session
141
+ * ({@link SessionsApi.cancel}).
134
142
  * @public
135
143
  */
136
- type SessionFailureReason = "location_not_allowed" | "anonymizer_blocked" | "capture_tampered" | "device_velocity_exceeded" | "device_cooldown";
144
+ type SessionFailureReason = "location_not_allowed" | "anonymizer_blocked" | "capture_tampered" | "device_velocity_exceeded" | "device_cooldown" | "platform_unsupported" | "cancelled_by_organization";
137
145
  /**
138
146
  * Profile-v2 decision-mode reasons a check's {@link SessionStep.reason} may
139
147
  * carry when the app decides automatically (`decisions.mode: 'automatic'`)
@@ -163,10 +171,13 @@ type EligibilityReason = "document_type_not_accepted" | "nationality_not_allowed
163
171
  * `document_id_number_mismatch` (the document belongs to someone other than the
164
172
  * ID number the session was created for; `document_nni_mismatch` is its former
165
173
  * 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).
174
+ * so the live step ended without a capture; the session is rejected at level 0 unless your flow has a fallback),
175
+ * `subject_face_mismatch` (a step-up whose face did not match the person it was created for), or a review that
176
+ * ended at its deadline: `review_timeout` (nobody decided it) or `review_split` (two reviewers disagreed and
177
+ * nobody settled it); those two carry `decidedBy: "automatic"`.
167
178
  * @public
168
179
  */
169
- type PolicyFailureReason = SessionFailureReason | EligibilityReason | "document_id_number_mismatch" | "document_nni_mismatch" | "camera_unavailable";
180
+ type PolicyFailureReason = SessionFailureReason | EligibilityReason | "document_id_number_mismatch" | "document_nni_mismatch" | "camera_unavailable" | "subject_face_mismatch" | "review_timeout" | "review_split";
170
181
  /**
171
182
  * The ID-number reasons a check's {@link SessionStep.reason} may carry (person data
172
183
  * spec Appendix A.2), each under its generic name and its former Mauritanian name:
@@ -208,7 +219,7 @@ type PriorReviewReason = "prior_review_approved" | "prior_review_rejected";
208
219
  /**
209
220
  * Review outcome reasons any reviewable step may carry: `superseded_by_retry`
210
221
  * (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
222
+ * with `outcome: null` and {@link Session.supersededBy}) and `review_split` (two reviewers disagreed and
212
223
  * nobody settled it before the review deadline; the session is rejected).
213
224
  * Both are billed and retryable: the person may verify again. Neither counts
214
225
  * toward the device cooldown.
@@ -303,12 +314,18 @@ type SekyroEnvironment = "sandbox" | "live";
303
314
  * @public
304
315
  */
305
316
  interface SessionStep {
317
+ /** The node of your flow this step belongs to (e.g. `n_live`): the name of the step. Absent on sessions created before flows. */
318
+ id?: string;
319
+ /** What the step runs: the service of its node. Absent on sessions created before flows. */
320
+ service?: ServiceId;
321
+ /**
322
+ * @deprecated Read {@link SessionStep.service}. The internal check this step
323
+ * runs; removed from the API after this release.
324
+ */
306
325
  checkType: CheckType;
307
326
  state: CheckState;
308
- /** Sekyro flows: the flow node this check belongs to (e.g. `n_live`). */
327
+ /** @deprecated Read {@link SessionStep.id}, which holds the same node id. */
309
328
  nodeId?: string;
310
- /** Sekyro flows: the service of that node. */
311
- service?: ServiceId;
312
329
  /** Sekyro flows: the check failed and the flow's fallback took over. */
313
330
  handled?: true;
314
331
  /** Machine-readable failure/review reason, when the check has one. */
@@ -335,6 +352,8 @@ interface SessionStep {
335
352
  * no person decided it.
336
353
  */
337
354
  decision?: SessionStepDecision;
355
+ /** The step last ran simulated in the Sandbox (no paid or external service). */
356
+ simulated?: true;
338
357
  }
339
358
  /**
340
359
  * The probe-quality measurement on a `face_match` step. Numbers only; `null`
@@ -369,6 +388,7 @@ interface PortraitReportEntry {
369
388
  /**
370
389
  * A short-lived link to a session's ICAO portrait (480×640 JPEG), from
371
390
  * {@link SessionsApi.portrait}. Download it before `expiresAt`; never store the URL.
391
+ * @deprecated Use {@link SessionsApi.media} and its `icao_portrait` item ({@link MediaItem}).
372
392
  * @public
373
393
  */
374
394
  interface SessionPortraitLink {
@@ -413,7 +433,28 @@ interface SubjectName {
413
433
  patronymic?: string;
414
434
  }
415
435
  /**
416
- * What you already know about the person (`subject` at session create). A
436
+ * One birth place entry of {@link SessionPersonInput.birthPlace}: the place in
437
+ * one script (ISO 15924 code, e.g. `Latn` or `Arab`), 1 to 120 characters.
438
+ * @public
439
+ */
440
+ interface PersonBirthPlaceInput {
441
+ script: string;
442
+ value: string;
443
+ }
444
+ /**
445
+ * The person's identity document ({@link SessionPersonInput.document}): its
446
+ * type, issuing country (ISO 3166-1 alpha-2 or alpha-3) and the number it
447
+ * prints (1 to 40 letters, digits, spaces or hyphens). Compared with what the
448
+ * capture reads; it does not bind the session (`idNumber` does).
449
+ * @public
450
+ */
451
+ interface PersonDocumentInput {
452
+ type: "national_id" | "passport" | "residence_permit";
453
+ issuingCountry: string;
454
+ number: string;
455
+ }
456
+ /**
457
+ * What you already know about the person (`person` at session create). A
417
458
  * closed object: unknown keys are refused (`400`). Every field is optional;
418
459
  * `null` or blank counts as absent.
419
460
  *
@@ -426,7 +467,7 @@ interface SubjectName {
426
467
  * substitute another number.
427
468
  * @public
428
469
  */
429
- interface SessionSubjectInput {
470
+ interface SessionPersonInput {
430
471
  /** The person's ID number. Binds the session. */
431
472
  idNumber?: SubjectIdNumber;
432
473
  /**
@@ -444,14 +485,24 @@ interface SessionSubjectInput {
444
485
  names?: SubjectName[];
445
486
  /** ISO 8601 date (`YYYY-MM-DD`). */
446
487
  birthDate?: string;
447
- /** Place of birth, 1 to 120 characters, any script (kept only with a reference record). */
448
- birthPlace?: string;
488
+ /**
489
+ * Place of birth (kept only with a reference record): a string of 1 to 120
490
+ * characters in any script, or one entry per script (at most 4).
491
+ */
492
+ birthPlace?: string | PersonBirthPlaceInput[];
449
493
  /** `M`, `F` or `X` (ICAO 9303 values; kept only with a reference record). */
450
494
  sex?: "M" | "F" | "X";
451
- /** ISO 3166-1 alpha-2. */
495
+ /** ISO 3166-1 alpha-2 codes, 1 to 4. */
496
+ nationalities?: string[];
497
+ /**
498
+ * @deprecated Send `nationalities: [code]`. ISO 3166-1 alpha-2. Both keys
499
+ * with different values answer `400 subject_input_conflict`.
500
+ */
452
501
  nationality?: string;
502
+ /** The person's identity document ({@link PersonDocumentInput}). */
503
+ document?: PersonDocumentInput;
453
504
  /**
454
- * @deprecated Use `idNumber` with the document's `type` and `issuingCountry`.
505
+ * @deprecated Send `document` (`type`, `issuingCountry`, `number`).
455
506
  * Identity-document number (1 to 40 characters).
456
507
  */
457
508
  documentNumber?: string;
@@ -470,7 +521,7 @@ interface SessionSubjectInput {
470
521
  fetchedAt?: string;
471
522
  /**
472
523
  * Your own id for this person (1–128 characters). Echoed on the session and
473
- * its webhooks, and searchable on the subjects API.
524
+ * its webhooks, and searchable on the people API ({@link PeopleApi.list}).
474
525
  */
475
526
  externalRef?: string;
476
527
  /**
@@ -484,6 +535,11 @@ interface SessionSubjectInput {
484
535
  */
485
536
  reuse?: SubjectReuseTarget;
486
537
  }
538
+ /**
539
+ * @deprecated Use {@link SessionPersonInput} (the `person` create key).
540
+ * @public
541
+ */
542
+ type SessionSubjectInput = SessionPersonInput;
487
543
  /**
488
544
  * An identity document for {@link SubjectReuseTarget}: the document type, the
489
545
  * issuing country (ISO 3166-1 alpha-2 or alpha-3) and its number.
@@ -832,10 +888,16 @@ interface CreateSessionInput {
832
888
  link?: SessionLinkInput;
833
889
  /**
834
890
  * What you already know about the person (preferred over `input` for
835
- * identity data). A key sent in both `subject` and `input` with different
891
+ * identity data). A key sent in both `person` and `input` with different
836
892
  * values answers `400 subject_input_conflict`.
837
893
  */
838
- subject?: SessionSubjectInput;
894
+ person?: SessionPersonInput;
895
+ /**
896
+ * @deprecated Send {@link CreateSessionInput.person}, the same object. The
897
+ * same value under both keys is accepted; different values answer
898
+ * `400 subject_input_conflict`.
899
+ */
900
+ subject?: SessionPersonInput;
839
901
  /**
840
902
  * Your own id for the agent filming the person, for flows whose liveness
841
903
  * capture is `assisted` (1 to 128 characters). Stored as is and echoed on
@@ -953,6 +1015,13 @@ interface CreatedSession {
953
1015
  subjectUse?: "reference" | "prefill";
954
1016
  /** One entry per deprecated request key you used, naming its replacement. Absent otherwise. */
955
1017
  warnings?: CreatedSessionWarning[];
1018
+ /**
1019
+ * With {@link CreateSessionInput.deliver} only: the send of the hosted link.
1020
+ * `failed` never fails the create; `simulated` on a simulated Sandbox session.
1021
+ */
1022
+ delivery?: {
1023
+ status: "queued" | "failed" | "simulated";
1024
+ };
956
1025
  }
957
1026
  /**
958
1027
  * A deprecation warning of {@link CreatedSession.warnings}: `field` is the
@@ -966,11 +1035,11 @@ interface CreatedSessionWarning {
966
1035
  replacement: string;
967
1036
  }
968
1037
  /**
969
- * Input of {@link SubjectsApi.createSession}: a re-check or step-up session
970
- * for an existing subject in one call.
1038
+ * Input of {@link PeopleApi.createSession}: a re-check or step-up session
1039
+ * for an existing person in one call.
971
1040
  * @public
972
1041
  */
973
- interface SubjectSessionInput {
1042
+ interface PersonSessionInput {
974
1043
  mode: SubjectReuseMode;
975
1044
  /** The app's flow to run (slug or `flw_` id); absent = the app's default flow. */
976
1045
  flow?: string;
@@ -979,16 +1048,24 @@ interface SubjectSessionInput {
979
1048
  ttlMinutes?: number;
980
1049
  locale?: Locale;
981
1050
  }
1051
+ /** @deprecated Use {@link PersonSessionInput}. @public */
1052
+ type SubjectSessionInput = PersonSessionInput;
982
1053
  /**
983
- * Which subject {@link SubjectsApi.createSession} targets: the subject id or
984
- * your own external reference.
1054
+ * Which person {@link PeopleApi.createSession} targets: the person id
1055
+ * (`per_...` or the bare 24 hexadecimal characters) or your own external
1056
+ * reference. `{ subjectId }` is the deprecated name of `{ personId }`.
985
1057
  * @public
986
1058
  */
987
- type SubjectSessionTarget = {
1059
+ type PersonSessionTarget = {
1060
+ personId: string;
1061
+ } | {
1062
+ /** @deprecated Use `personId`. */
988
1063
  subjectId: string;
989
1064
  } | {
990
1065
  externalRef: string;
991
1066
  };
1067
+ /** @deprecated Use {@link PersonSessionTarget}. @public */
1068
+ type SubjectSessionTarget = PersonSessionTarget;
992
1069
  /** Result of {@link SessionsApi.resultToken}: a freshly signed result token. @public */
993
1070
  interface ResultTokenResponse {
994
1071
  /** ES256 JWT; check it with {@link verifyResultToken}. */
@@ -1011,9 +1088,19 @@ interface SessionNetworkEvent {
1011
1088
  operator?: string;
1012
1089
  connectionType: "mobile" | "hosting" | "unknown";
1013
1090
  anonymizer: {
1091
+ /** A known commercial VPN service exit. */
1014
1092
  vpn: boolean;
1093
+ /** A Tor exit. */
1015
1094
  tor: boolean;
1095
+ /** A cloud, hosting or data center network. */
1016
1096
  hosting: boolean;
1097
+ /** A public open proxy. Present only when true. */
1098
+ proxy?: boolean;
1099
+ /**
1100
+ * Apple iCloud Private Relay. A privacy relay for Apple accounts, not counted
1101
+ * as an anonymizer. Present only when true.
1102
+ */
1103
+ relay?: boolean;
1017
1104
  };
1018
1105
  /** IANA time zone reported by the end user's device. */
1019
1106
  browserTimezone?: string;
@@ -1090,6 +1177,183 @@ interface VerifiedContacts {
1090
1177
  verifiedAt: string;
1091
1178
  };
1092
1179
  }
1180
+ /**
1181
+ * Where a value of {@link Identity} comes from: the `document` (its machine
1182
+ * readable zone or printed text), the passport `chip`, the population
1183
+ * `registry`, a national `eid`, or the record you `supplied` at create.
1184
+ * @public
1185
+ */
1186
+ type IdentitySource = "document" | "chip" | "registry" | "eid" | "supplied";
1187
+ /**
1188
+ * How a name of {@link Identity.names} was obtained: `mrz` (the ICAO
1189
+ * transliteration of the machine readable zone: upper case, truncated, no
1190
+ * diacritics), `printed` (the visual zone, as written), `chip` (the chip's
1191
+ * data groups), `registry`, `eid` or `supplied`.
1192
+ * @public
1193
+ */
1194
+ type NameForm = "mrz" | "printed" | "chip" | "registry" | "eid" | "supplied";
1195
+ /**
1196
+ * One name as one source gives it. Names from different sources are never
1197
+ * merged. For an `mrz` entry `family` holds the ICAO primary identifier and
1198
+ * `given` the secondary one, as the document arranges them. To show a name,
1199
+ * pick the first entry whose `form` is not `mrz`.
1200
+ * @public
1201
+ */
1202
+ interface IdentityName {
1203
+ /** ISO 15924 script, e.g. `Latn` or `Arab`. */
1204
+ script: string;
1205
+ form: NameForm;
1206
+ /** Given names (the secondary identifier). */
1207
+ given?: string;
1208
+ /** Family name (the primary identifier). */
1209
+ family?: string;
1210
+ /** The father's given name, when the source distinguishes it. */
1211
+ patronymic?: string;
1212
+ /** The name as one string, when the source gives one (never built from the parts). */
1213
+ fullName?: string;
1214
+ source: IdentitySource;
1215
+ }
1216
+ /** One birth place as one source wrote it ({@link Identity.birthPlace}). @public */
1217
+ interface IdentityBirthPlace {
1218
+ /** ISO 15924 script. */
1219
+ script: string;
1220
+ value: string;
1221
+ source: IdentitySource;
1222
+ }
1223
+ /** The holder's national number, when a per-country rule recognises it ({@link Identity.idNumber}). @public */
1224
+ interface IdentityIdNumber {
1225
+ type: "national_id" | "passport" | "residence_permit";
1226
+ /** ISO 3166-1 alpha-2. */
1227
+ issuingCountry: string;
1228
+ /** The number, normalised. */
1229
+ number: string;
1230
+ }
1231
+ /** The document or chip that was read ({@link Identity.document}). @public */
1232
+ interface IdentityDocument {
1233
+ type: "national_id" | "passport" | "residence_permit";
1234
+ /** ISO 3166-1 alpha-2, or the ICAO code as read when it has no ISO equivalent. */
1235
+ issuingCountry?: string;
1236
+ /** The document number as read: upper case, no spaces. */
1237
+ number?: string;
1238
+ /** `YYYY-MM-DD`. */
1239
+ expiryDate?: string;
1240
+ /** `YYYY-MM-DD`, from the chip. */
1241
+ issueDate?: string;
1242
+ /** The issuing authority as written, from the chip. */
1243
+ issuingAuthority?: string;
1244
+ /** The keys whose value a check digit protects. Never the names. */
1245
+ mrzVerified?: Array<"number" | "birthDate" | "expiryDate" | "idNumber">;
1246
+ }
1247
+ /**
1248
+ * The scalar keys of {@link Identity} that {@link Identity.sources} reports on.
1249
+ * @public
1250
+ */
1251
+ type IdentityScalarKey = "idNumber" | "birthDate" | "sex" | "nationalities" | "document.number" | "document.expiryDate";
1252
+ /**
1253
+ * For each scalar key, the sources whose value equals the returned one. A
1254
+ * source that read another value is not listed (its step carries the mismatch
1255
+ * reason).
1256
+ * @public
1257
+ */
1258
+ type IdentitySources = Partial<Record<IdentityScalarKey, IdentitySource[]>>;
1259
+ /**
1260
+ * The identity data a session read (its document, chip, registry, eID or your
1261
+ * supplied record), present once one identity step settled, whatever the
1262
+ * outcome. On a person ({@link Person.identity}), the identity of the latest
1263
+ * approved session that read one. Every key is optional. Sent to you only (the
1264
+ * session view, the person view and the terminal webhooks).
1265
+ * @public
1266
+ */
1267
+ interface Identity {
1268
+ idNumber?: IdentityIdNumber;
1269
+ /** One entry per source and script, registry forms first. */
1270
+ names?: IdentityName[];
1271
+ /** ISO 8601 with the precision the source has: `YYYY-MM-DD`, `YYYY-MM` or `YYYY`. */
1272
+ birthDate?: string;
1273
+ birthPlace?: IdentityBirthPlace[];
1274
+ /** `null` when the source read an unspecified value; absent when no source read it. */
1275
+ sex?: "M" | "F" | "X" | null;
1276
+ /** ISO 3166-1 alpha-2 codes, or the ICAO code when it has no ISO equivalent. */
1277
+ nationalities?: string[];
1278
+ /** Set when the nationality code is not a country (e.g. `stateless`). */
1279
+ nationalityKind?: string;
1280
+ document?: IdentityDocument;
1281
+ sources?: IdentitySources;
1282
+ /** The registry a registry step passed against. */
1283
+ registry?: {
1284
+ id: string;
1285
+ fetchedAt?: string;
1286
+ };
1287
+ /** The national eID that verified the identity. */
1288
+ eid?: {
1289
+ provider: string;
1290
+ country: string;
1291
+ verifiedAt?: string;
1292
+ };
1293
+ /** ISO 8601: when the last identity step settled. */
1294
+ verifiedAt?: string;
1295
+ /** @deprecated Read {@link Identity.names}. The first Latin name as one string. */
1296
+ name?: string;
1297
+ }
1298
+ /**
1299
+ * The media kinds of a session, in the order the API lists them.
1300
+ * `reference_portrait` is the photo the face match compared against.
1301
+ * @public
1302
+ */
1303
+ type MediaKind = "icao_portrait" | "document_front" | "document_back" | "document_portrait" | "chip_portrait" | "reference_portrait" | "supplied_photo" | "selfie" | "liveness_clip";
1304
+ /**
1305
+ * One media object of a session ({@link SessionsApi.media}). `url` is a
1306
+ * download link valid 15 minutes, or the bytes route on this API
1307
+ * (`/api/v2/sessions/{id}/media/{kind}`), which needs your key: read it with
1308
+ * {@link SessionsApi.mediaBytes}. Never store the URL.
1309
+ * @public
1310
+ */
1311
+ interface MediaItem {
1312
+ kind: MediaKind;
1313
+ /** The check that produced or used it. */
1314
+ check: string;
1315
+ /** The attempt it came from (1, 2, ...); absent when it is not per attempt. */
1316
+ attempt?: number;
1317
+ /** It belongs to the attempt that settled the check. */
1318
+ decisive: boolean;
1319
+ /** The state of that attempt, else of the check. */
1320
+ state?: string;
1321
+ /** The reason of that attempt, when it did not pass. */
1322
+ reason?: string;
1323
+ /** The attempt was set aside (for example a retake) and not counted. */
1324
+ voided?: string;
1325
+ contentType: "image/jpeg" | "image/png" | "video/mp4" | "video/webm";
1326
+ /** `reference_portrait` and `supplied_photo`: where the photo came from (`stored`: kept from an earlier verification). */
1327
+ source?: "registry" | "eid" | "chip" | "document" | "supplied" | "stored";
1328
+ /** `reference_portrait`: the registry photo was fetched again for this match. */
1329
+ refreshed?: true;
1330
+ url: string;
1331
+ /** ISO 8601: when `url` expires. List the media again for fresh links. */
1332
+ expiresAt: string;
1333
+ }
1334
+ /** Result of {@link SessionsApi.media}. @public */
1335
+ interface MediaList {
1336
+ items: MediaItem[];
1337
+ }
1338
+ /** Options of {@link SessionsApi.mediaBytes}. @public */
1339
+ interface MediaBytesOptions {
1340
+ /** The attempt (1, 2, ...) to read; default: the decisive item, else the latest attempt. */
1341
+ attempt?: number;
1342
+ /** `reference_portrait` only: the first reference, when a second one decided the step. */
1343
+ reference?: "first";
1344
+ }
1345
+ /** Result of {@link SessionsApi.mediaBytes}: the bytes and their media type. @public */
1346
+ interface MediaBytes {
1347
+ contentType: string;
1348
+ bytes: Uint8Array;
1349
+ }
1350
+ /**
1351
+ * Who closed a completed or failed session: `review` when a person decided
1352
+ * the verdict (the deciding step carries its {@link SessionStepDecision}),
1353
+ * `automatic` otherwise (a review deadline included).
1354
+ * @public
1355
+ */
1356
+ type DecidedBy = "automatic" | "review";
1093
1357
  /**
1094
1358
  * The whitelisted session view returned by {@link SessionsApi.get}. Never
1095
1359
  * contains the client token.
@@ -1101,9 +1365,17 @@ interface Session {
1101
1365
  flow?: SessionFlowRef;
1102
1366
  status: SessionStatus;
1103
1367
  outcome: SessionOutcome | null;
1368
+ /** Completed and failed sessions: who decided the verdict ({@link DecidedBy}). */
1369
+ decidedBy?: DecidedBy;
1104
1370
  /**
1105
- * What the session proved ({@link VerificationLevel}); `null` while the
1106
- * session is active, `0` when it was rejected. Absent from older API versions.
1371
+ * A session closed because a newer attempt of the same person took over its
1372
+ * review: that session's id (`outcome` is `null`). Watch it instead.
1373
+ */
1374
+ supersededBy?: string;
1375
+ /**
1376
+ * What the session proved ({@link VerificationLevel}), on a completed or
1377
+ * failed session: `0` when it was rejected. Absent while the session is
1378
+ * active, and from older API versions.
1107
1379
  */
1108
1380
  level?: VerificationLevel | null;
1109
1381
  /** How the level was proved; `null` while the session is active. */
@@ -1116,8 +1388,8 @@ interface Session {
1116
1388
  steps: SessionStep[];
1117
1389
  /** ISO 8601. */
1118
1390
  expiresAt: string;
1119
- /** ISO 8601. */
1120
- createdAt: string;
1391
+ /** ISO 8601. Absent on a session view that does not carry it. */
1392
+ createdAt?: string;
1121
1393
  /** ISO 8601: when the session reached a terminal state; `null` while it is active. */
1122
1394
  completedAt?: string | null;
1123
1395
  /** End-user network context; absent when not recorded. */
@@ -1132,9 +1404,14 @@ interface Session {
1132
1404
  failureReason?: PolicyFailureReason;
1133
1405
  /** With failureReason `camera_unavailable`: why (`denied` or `no_camera`), when the SDK said. Absent otherwise. */
1134
1406
  failureDetail?: CameraUnavailableCause;
1135
- /** The subject (person) this session is linked to, once that subject has passed a verification (absent before that). */
1407
+ /** The person (`per_...`) this session is linked to, once that person has passed a verification (absent before that). */
1408
+ personId?: string;
1409
+ /**
1410
+ * @deprecated Read {@link Session.personId}. The same person with the id
1411
+ * bare (no `per_` prefix), as the result token's `sub` names it.
1412
+ */
1136
1413
  subjectId?: string;
1137
- /** Your own id for the person, from `subject.externalRef` at create. */
1414
+ /** Your own id for the person, from `person.externalRef` at create. */
1138
1415
  externalRef?: string;
1139
1416
  /** The agent reference sent as `assistedBy` at create, for assisted capture. */
1140
1417
  assistedBy?: {
@@ -1163,7 +1440,7 @@ interface Session {
1163
1440
  riskSignals?: string[];
1164
1441
  /**
1165
1442
  * `true` for a returning-user session (created with
1166
- * {@link SessionSubjectInput.reuse}): liveness + face match against the
1443
+ * {@link SessionPersonInput.reuse}): liveness + face match against the
1167
1444
  * subject's stored reference photo only.
1168
1445
  */
1169
1446
  returning?: true;
@@ -1176,7 +1453,10 @@ interface Session {
1176
1453
  reuseMode?: SubjectReuseMode;
1177
1454
  /** The contacts verified in this session (passed OTP checks only); absent when none. */
1178
1455
  verifiedContacts?: VerifiedContacts;
1179
- /** The national eID that verified this session (the `eid_auth` check passed); absent otherwise. */
1456
+ /**
1457
+ * The national eID that verified this session (the `eid_auth` check passed); absent otherwise.
1458
+ * @deprecated Read `identity.eid` ({@link Identity}) instead.
1459
+ */
1180
1460
  eid?: EidResult;
1181
1461
  /**
1182
1462
  * When the flow sets a minimum age and the session proved it: the threshold
@@ -1184,10 +1464,27 @@ interface Session {
1184
1464
  */
1185
1465
  age?: AgeResult;
1186
1466
  /**
1187
- * ID mode (`portrait.purpose = id_document`) only: the ICAO portrait can be
1188
- * fetched with {@link SessionsApi.portrait}.
1467
+ * @deprecated Read {@link Session.media}: `true` when it includes
1468
+ * `icao_portrait`. ID mode only: the ICAO portrait can be fetched.
1189
1469
  */
1190
1470
  portraitAvailable?: boolean;
1471
+ /**
1472
+ * The identity data the session read ({@link Identity}), once one identity
1473
+ * step settled. On an approved returning-user session, with a key that also
1474
+ * holds `people:read`, the identity stored on the person.
1475
+ */
1476
+ identity?: Identity;
1477
+ /** The media kinds this session has, in kind order: fetch them with {@link SessionsApi.media}. */
1478
+ media?: MediaKind[];
1479
+ /**
1480
+ * Terminal sessions, when result tokens are on: a signed result token
1481
+ * (ES256 JWT, valid 10 minutes). Check it with {@link verifyResultToken}.
1482
+ */
1483
+ resultToken?: string;
1484
+ /** Terminal sessions: other people the face matched in the duplicate search (non-empty only). */
1485
+ duplicates?: ResultDuplicate[];
1486
+ /** Terminal sessions: the duplicate search could not run. */
1487
+ dedupUnavailable?: true;
1191
1488
  /**
1192
1489
  * Terminal sessions: a failure identification match
1193
1490
  * ({@link FailureIdentification}), present only for a match and only when the
@@ -1196,18 +1493,26 @@ interface Session {
1196
1493
  failureIdentification?: FailureIdentification;
1197
1494
  }
1198
1495
  /**
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`).
1496
+ * `data` of the session lifecycle events (`session.started` |
1497
+ * `session.review_pending` | `session.completed` | `session.failed` |
1498
+ * `session.expired`). `outcome`, `decidedBy` and `steps` travel on
1499
+ * `completed` / `failed`, which are the one terminal event of a session: a
1500
+ * reviewer's decision arrives as one of them with `decidedBy: "review"` and
1501
+ * the `decision`. `review_pending` carries `steps` without an outcome;
1502
+ * `expired` carries the status and the session's refs (`flow`, person ids,
1503
+ * `overriddenFields`). `identity` and `media` (kinds only, never links) ride on
1504
+ * `completed` / `failed` when the platform sends them.
1205
1505
  * @public
1206
1506
  */
1207
1507
  interface SessionLifecycleEventData {
1508
+ /** The session id (`ses_...`). */
1208
1509
  sessionId: string;
1209
1510
  status: SessionStatus;
1210
1511
  outcome?: SessionOutcome | null;
1512
+ /** On `completed` / `failed`: who decided the verdict ({@link DecidedBy}). */
1513
+ decidedBy?: DecidedBy;
1514
+ /** On `completed` / `failed` with `decidedBy: "review"`: how the deciding step was decided. */
1515
+ decision?: SessionStepDecision;
1211
1516
  /** On `completed` / `failed`: the app the session belongs to. */
1212
1517
  appId?: string;
1213
1518
  /** On `completed` / `failed`: what the session proved ({@link VerificationLevel}). */
@@ -1228,11 +1533,13 @@ interface SessionLifecycleEventData {
1228
1533
  * result tokens are not enabled.
1229
1534
  */
1230
1535
  resultToken?: string;
1536
+ /** On `completed` / `failed`: the duplicate search could not run. */
1537
+ dedupUnavailable?: true;
1231
1538
  /**
1232
1539
  * The checks on the session's path (checks of a lane the person did not take
1233
1540
  * are omitted), each with its {@link SessionStepDecision} when a person decided it.
1234
1541
  */
1235
- steps?: Array<Pick<SessionStep, "checkType" | "state" | "nodeId" | "service" | "decision">>;
1542
+ steps?: Array<Pick<SessionStep, "id" | "service" | "checkType" | "state" | "nodeId" | "simulated" | "decision">>;
1236
1543
  /** Sekyro flows: the flow version the session runs (absent on sessions created before flows). */
1237
1544
  flow?: SessionFlowRef;
1238
1545
  /** Machine-readable reason, when the transition has one. */
@@ -1249,21 +1556,30 @@ interface SessionLifecycleEventData {
1249
1556
  failureReason?: PolicyFailureReason;
1250
1557
  /** On `session.failed` with failureReason `camera_unavailable`: why (`denied` or `no_camera`), when the SDK said. Absent otherwise. */
1251
1558
  failureDetail?: CameraUnavailableCause;
1252
- /** The subject (person) the session is linked to, once that subject has passed a verification (absent before that). */
1559
+ /** The person (`per_...`) the session is linked to, once that person has passed a verification (absent before that). */
1560
+ personId?: string;
1561
+ /**
1562
+ * @deprecated Read {@link SessionLifecycleEventData.personId}. The same
1563
+ * person with the id bare (no `per_` prefix).
1564
+ */
1253
1565
  subjectId?: string;
1254
- /** Your own id for the person, from `subject.externalRef` at create. */
1566
+ /** Your own id for the person, from `person.externalRef` at create. */
1255
1567
  externalRef?: string;
1568
+ /** The agent reference sent as `assistedBy` at create, for assisted capture. */
1569
+ assistedBy?: {
1570
+ externalRef: string;
1571
+ };
1256
1572
  /**
1257
1573
  * `true` when an identifier this session read already belongs to a
1258
- * different subject than `subjectId` — the subjects are never merged.
1574
+ * different person than `personId`: the people are never merged.
1259
1575
  */
1260
1576
  subjectConflict?: boolean;
1261
1577
  /** `true` on a returning-user session (liveness + face match against the stored photo). */
1262
1578
  returning?: true;
1263
- /** On a returning-user session: the subject (person) it re-verifies. */
1579
+ /** On a returning-user session: the person (`per_...`) it re-verifies. */
1264
1580
  reuseOf?: string;
1265
1581
  /**
1266
- * On a session created for an existing subject: `recheck` (the same person
1582
+ * On a session created for an existing person: `recheck` (the same person
1267
1583
  * again) or `step_up` (raised to identity level). Absent otherwise.
1268
1584
  */
1269
1585
  reuseMode?: SubjectReuseMode;
@@ -1288,10 +1604,14 @@ interface SessionLifecycleEventData {
1288
1604
  /** On `completed` / `failed`: the minimum age the session proved and how ({@link AgeResult}), when the flow sets one. */
1289
1605
  age?: AgeResult;
1290
1606
  /**
1291
- * ID mode only, on `completed` / `failed`: the ICAO portrait can be fetched
1292
- * with {@link SessionsApi.portrait} (the event never carries the image).
1607
+ * @deprecated Read {@link SessionLifecycleEventData.media}. ID mode only, on
1608
+ * `completed` / `failed`: the ICAO portrait can be fetched.
1293
1609
  */
1294
1610
  portraitAvailable?: boolean;
1611
+ /** On `completed` / `failed`: the identity data the session read ({@link Identity}), when the platform sends it. */
1612
+ identity?: Identity;
1613
+ /** On `completed` / `failed`: the media kinds of the session (never links), when the platform sends them. */
1614
+ media?: MediaKind[];
1295
1615
  /**
1296
1616
  * On `completed` / `failed`: a failure identification match
1297
1617
  * ({@link FailureIdentification}), when the setting is on and the search
@@ -1368,8 +1688,9 @@ type SubjectAssurance = "registry_biometric" | "chip_biometric" | "document_biom
1368
1688
  * @public
1369
1689
  */
1370
1690
  type SubjectReferenceSource = "registry" | "doc_registry" | "chip" | "org_supplied" | "document";
1371
- /** One session linked to a subject. @public */
1372
- interface SubjectSession {
1691
+ /** One session linked to a person. @public */
1692
+ interface PersonSession {
1693
+ /** The session id (`ses_...`). */
1373
1694
  sessionId: string;
1374
1695
  appId: string | null;
1375
1696
  /** ISO 8601 — when the session was linked. */
@@ -1381,17 +1702,22 @@ interface SubjectSession {
1381
1702
  /** How the session's level was proved; present only when stored. */
1382
1703
  assurance?: VerificationAssurance;
1383
1704
  }
1705
+ /** @deprecated Use {@link PersonSession}. @public */
1706
+ type SubjectSession = PersonSession;
1384
1707
  /**
1385
- * A subject (the same person across your apps), as `GET /subjects/:id`
1708
+ * A person (the same person across your apps), as `GET /people/:id`
1386
1709
  * returns it. Never contains photo keys or URLs.
1387
1710
  * @public
1388
1711
  */
1389
- interface Subject {
1712
+ interface Person {
1713
+ /** The person id (`per_...`). */
1390
1714
  id: string;
1715
+ /** The same value as `id`. Absent from older API versions. */
1716
+ personId?: string;
1391
1717
  status: SubjectStatus;
1392
1718
  /** ISO 8601 — present only when revoked. */
1393
1719
  revokedAt?: string;
1394
- sessions: SubjectSession[];
1720
+ sessions: PersonSession[];
1395
1721
  externalRefs: string[];
1396
1722
  /** ISO 8601. */
1397
1723
  firstSeenAt: string;
@@ -1413,9 +1739,9 @@ interface Subject {
1413
1739
  * recorded since the field exists. Absent from API versions before the field.
1414
1740
  */
1415
1741
  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. */
1742
+ /** ISO 8601: when {@link Person.level} was last proved (the latest approved session at that level or higher); `null` with it. Absent with it. */
1417
1743
  levelAt?: string | null | undefined;
1418
- /** The assurance of the session that proved {@link Subject.level}; `null` with it. Absent with it. */
1744
+ /** The assurance of the session that proved {@link Person.level}; `null` with it. Absent with it. */
1419
1745
  levelAssurance?: VerificationAssurance | null | undefined;
1420
1746
  /**
1421
1747
  * A returning-user session can be created now: active, a reference photo is
@@ -1429,27 +1755,92 @@ interface Subject {
1429
1755
  name?: string;
1430
1756
  birthDate?: string;
1431
1757
  };
1758
+ /** The identity of the latest approved session that read one ({@link Identity}). */
1759
+ identity?: Identity;
1432
1760
  }
1761
+ /** @deprecated Use {@link Person}. @public */
1762
+ type Subject = Person;
1433
1763
  /**
1434
- * Filters of {@link SessionsApi.list}: your own user id
1435
- * (`subject.externalRef` at create) and/or a status.
1764
+ * Filters of {@link SessionsApi.list}, {@link SessionsApi.listPage} and
1765
+ * {@link SessionsApi.iterate}, combined with AND. Newest first.
1436
1766
  * @public
1437
1767
  */
1438
1768
  interface ListSessionsQuery {
1439
- /** Your own id for the person (1 to 128 characters). */
1769
+ /** Your own id for the person (1 to 128 characters), exact match. */
1440
1770
  externalRef?: string;
1441
1771
  status?: SessionStatus;
1772
+ /** A flow id (`flw_...`) or slug. */
1773
+ flow?: string;
1774
+ /** Sessions created at or after this time (ISO 8601 or a `Date`). */
1775
+ createdAfter?: string | Date;
1776
+ /** Sessions created before this time (ISO 8601 or a `Date`). */
1777
+ createdBefore?: string | Date;
1778
+ /** Page size, 1 to 100 (the API's default is 50). */
1779
+ limit?: number;
1780
+ /** The {@link Page.nextCursor} of the previous page. */
1781
+ cursor?: string;
1782
+ }
1783
+ /**
1784
+ * Filters of {@link PeopleApi.list}, {@link PeopleApi.listPage} and
1785
+ * {@link PeopleApi.iterate}. Newest first; only people who passed a verification.
1786
+ * @public
1787
+ */
1788
+ interface ListPeopleQuery {
1789
+ /** Your own id for the person, exact match. */
1790
+ externalRef?: string;
1791
+ /** Page size, 1 to 100 (the API's default is 50). */
1792
+ limit?: number;
1793
+ /** The {@link Page.nextCursor} of the previous page. */
1794
+ cursor?: string;
1795
+ }
1796
+ /**
1797
+ * One page of a list: the items and, when more exist, the cursor of the next
1798
+ * page (pass it as `cursor`). Opaque; absent on the last page.
1799
+ * @public
1800
+ */
1801
+ interface Page<T> {
1802
+ data: T[];
1803
+ nextCursor?: string;
1442
1804
  }
1443
- /** Result of {@link SubjectsApi.delete}. @public */
1444
- interface DeletedSubject {
1805
+ /** Result of {@link PeopleApi.delete}. @public */
1806
+ interface DeletedPerson {
1807
+ /** The person id (`per_...`). */
1445
1808
  id: string;
1446
1809
  deleted: true;
1447
1810
  }
1448
- /** Options of {@link SubjectsApi.revoke}. @public */
1449
- interface RevokeSubjectInput {
1811
+ /** @deprecated Use {@link DeletedPerson}. @public */
1812
+ type DeletedSubject = DeletedPerson;
1813
+ /** Options of {@link PeopleApi.revoke}. @public */
1814
+ interface RevokePersonInput {
1450
1815
  /** Kept on the audit trail only (≤ 500 characters). Do not put personal data here. */
1451
1816
  reason?: string;
1452
1817
  }
1818
+ /** @deprecated Use {@link RevokePersonInput}. @public */
1819
+ type RevokeSubjectInput = RevokePersonInput;
1820
+ /**
1821
+ * Input of {@link SessionsApi.extendLink}: the new link lifetime in minutes,
1822
+ * counted from the session creation, or the new expiry. It must be later than
1823
+ * the current expiry and within the flow's maximum link lifetime.
1824
+ * @public
1825
+ */
1826
+ type ExtendLinkInput = {
1827
+ ttlMinutes: number;
1828
+ } | {
1829
+ expiresAt: string | Date;
1830
+ };
1831
+ /** Result of {@link SessionsApi.resendLink}: the new delivery attempt. @public */
1832
+ interface SessionLinkDelivery {
1833
+ delivery: {
1834
+ channel: "sms" | "whatsapp" | "email";
1835
+ /** `simulated` in the Sandbox: nothing is sent. */
1836
+ status: "queued" | "sent" | "failed" | "simulated";
1837
+ };
1838
+ }
1839
+ /** Result of {@link SessionsApi.extendLink}. @public */
1840
+ interface SessionLinkExpiry {
1841
+ /** ISO 8601: the new expiry of the link and its session. */
1842
+ expiresAt: string;
1843
+ }
1453
1844
  /**
1454
1845
  * `data` of `subject.suspicious_activity` — a device already linked to
1455
1846
  * ANOTHER subject was used for a session of this subject. `count` is the
@@ -1461,8 +1852,35 @@ interface SubjectSuspiciousActivityEventData {
1461
1852
  sessionId: string;
1462
1853
  count: number;
1463
1854
  }
1855
+ /**
1856
+ * `data` of `person.updated`: the `subject.updated` data plus `personId`
1857
+ * (`per_...`). `subjectId` names the same person bare during this release.
1858
+ * @public
1859
+ */
1860
+ interface PersonUpdatedEventData extends SubjectUpdatedEventData {
1861
+ personId: string;
1862
+ }
1863
+ /** `data` of `person.enrolled`: the `subject.enrolled` data plus `personId` (`per_...`). @public */
1864
+ interface PersonEnrolledEventData extends SubjectEnrolledEventData {
1865
+ personId: string;
1866
+ }
1867
+ /**
1868
+ * `data` of `person.deleted`: the `subject.deleted` data plus `personId`
1869
+ * (`per_...`) when the delete names the person (a delete through the people
1870
+ * API); the erasure variant carries `subjectRef` instead.
1871
+ * @public
1872
+ */
1873
+ interface PersonDeletedEventData extends SubjectDeletedEventData {
1874
+ personId?: string;
1875
+ }
1876
+ /** `data` of `person.suspicious_activity`: the `subject.suspicious_activity` data plus `personId` (`per_...`). @public */
1877
+ interface PersonSuspiciousActivityEventData extends SubjectSuspiciousActivityEventData {
1878
+ personId: string;
1879
+ }
1464
1880
  /**
1465
1881
  * `data` of `session.step.completed` — the check that just passed.
1882
+ * @deprecated The event leaves the catalog after this release: read the steps
1883
+ * of the terminal event (`session.completed` / `session.failed`).
1466
1884
  * @public
1467
1885
  */
1468
1886
  interface SessionStepCompletedEventData {
@@ -1499,6 +1917,10 @@ interface SessionStepCompletedEventData {
1499
1917
  * nobody settled it by the deadline. A reviewer's decision also carries
1500
1918
  * `reasons`, `decision` and the terminal fields of `session.completed` /
1501
1919
  * `session.failed`; a deadline carries the ids only.
1920
+ * @deprecated The event leaves the catalog after this release: a reviewer's
1921
+ * decision arrives as `session.completed` or `session.failed` with
1922
+ * `decidedBy: "review"` and the `decision`; a review deadline as
1923
+ * `session.failed` with `failureReason: "review_timeout" | "review_split"`.
1502
1924
  * @public
1503
1925
  */
1504
1926
  interface SessionReviewDecidedEventData {
@@ -1567,17 +1989,19 @@ interface SessionReviewDecidedEventData {
1567
1989
  /**
1568
1990
  * `data` of `session.superseded`: a session that waited for a review closed
1569
1991
  * 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.
1992
+ * session ends with status `completed`, `outcome: null` and `supersededBy`;
1993
+ * its review step failed with `superseded_by_retry`; nothing of it is deleted.
1994
+ * Read the newer session (`supersededBy`) for the verdict. This is the one
1995
+ * terminal event of the superseded session.
1573
1996
  * @public
1574
1997
  */
1575
1998
  interface SessionSupersededEventData {
1999
+ /** The superseded session (`ses_...`). */
1576
2000
  sessionId: string;
1577
- /** The newer session of the same person that took the review over. */
2001
+ /** The newer session of the same person that took the review over (`ses_...`). */
1578
2002
  supersededBy: string;
1579
- /** The review case both sessions belong to (an opaque id). */
1580
- caseId: string;
2003
+ /** @deprecated No longer sent: the review case is internal. */
2004
+ caseId?: string;
1581
2005
  reason: "superseded_by_retry";
1582
2006
  /** Your own id for the person, from `subject.externalRef` at create. */
1583
2007
  externalRef?: string;
@@ -1609,19 +2033,31 @@ interface UsageThresholdReachedEventData {
1609
2033
  * @public
1610
2034
  */
1611
2035
  interface WebhookEventDataMap {
2036
+ /** @deprecated Leaves the catalog after this release (you created the session). */
1612
2037
  "session.created": Record<string, unknown>;
1613
2038
  "session.started": Record<string, unknown>;
2039
+ /** @deprecated Leaves the catalog after this release: read the steps of the terminal event. */
1614
2040
  "session.step.completed": SessionStepCompletedEventData;
1615
2041
  "session.review_pending": SessionLifecycleEventData;
2042
+ /** @deprecated Leaves the catalog after this release: see {@link SessionReviewDecidedEventData}. */
1616
2043
  "session.review_decided": SessionReviewDecidedEventData;
1617
2044
  "session.completed": SessionLifecycleEventData;
1618
2045
  "session.expired": SessionLifecycleEventData;
1619
2046
  "session.failed": SessionLifecycleEventData;
1620
2047
  "session.superseded": SessionSupersededEventData;
2048
+ "person.enrolled": PersonEnrolledEventData;
2049
+ "person.updated": PersonUpdatedEventData;
2050
+ "person.suspicious_activity": PersonSuspiciousActivityEventData;
2051
+ "person.deleted": PersonDeletedEventData;
2052
+ /** @deprecated Subscribe to `person.enrolled`, sent next to it with `personId`. */
1621
2053
  "subject.enrolled": SubjectEnrolledEventData;
2054
+ /** @deprecated Subscribe to `person.updated`, sent next to it with `personId`. */
1622
2055
  "subject.updated": SubjectUpdatedEventData;
2056
+ /** @deprecated Subscribe to `person.suspicious_activity`, sent next to it with `personId`. */
1623
2057
  "subject.suspicious_activity": SubjectSuspiciousActivityEventData;
2058
+ /** @deprecated Subscribe to `person.deleted`, sent next to it with `personId`. */
1624
2059
  "subject.deleted": SubjectDeletedEventData;
2060
+ /** @deprecated Leaves the catalog after this release (no AML feature behind it). */
1625
2061
  "aml.match_flagged": Record<string, unknown>;
1626
2062
  "payment.received": Record<string, unknown>;
1627
2063
  "invoice.generated": Record<string, unknown>;
@@ -1661,8 +2097,8 @@ interface WebhookEnvelopeOf<E extends WebhookEventType> {
1661
2097
  * case "session.completed":
1662
2098
  * envelope.data.outcome; // SessionOutcome | null | undefined
1663
2099
  * break;
1664
- * case "session.review_decided":
1665
- * envelope.data.outcome; // "pass" | "fail"
2100
+ * case "person.updated":
2101
+ * envelope.data.personId; // "per_..."
1666
2102
  * break;
1667
2103
  * }
1668
2104
  * ```
@@ -1719,13 +2155,17 @@ interface ConnectorIdentity {
1719
2155
  * @public
1720
2156
  */
1721
2157
  declare class SessionsApi {
1722
- private readonly call;
2158
+ private readonly t;
1723
2159
  /**
1724
2160
  * Constructed by {@link Sekyro}; the transport is kept out of the public
1725
- * surface on purpose (only its bound `call` crosses this boundary).
2161
+ * surface on purpose (only its bound calls cross this boundary).
1726
2162
  * @internal
1727
2163
  */
1728
- constructor(call: <T>(method: "GET" | "POST" | "DELETE", path: string, body?: unknown, idempotencyKey?: string) => Promise<T>);
2164
+ constructor(t: {
2165
+ call<T>(method: "GET" | "POST" | "DELETE", path: string, body?: unknown, idempotencyKey?: string): Promise<T>;
2166
+ page<T>(path: string): Promise<Page<T>>;
2167
+ bytes(path: string): Promise<MediaBytes>;
2168
+ });
1729
2169
  /**
1730
2170
  * `POST /sessions`. Returns the one-time `clientToken` — hand it to the
1731
2171
  * browser, never persist it. Pass an `idempotencyKey` so a retried call
@@ -1742,20 +2182,79 @@ declare class SessionsApi {
1742
2182
  * {@link isFlowError}).
1743
2183
  */
1744
2184
  selectMethod(id: string, method: IdentityMethod): Promise<Session>;
1745
- /** `GET /sessions/:id` — the whitelisted view (no client token). */
2185
+ /** `GET /sessions/:id` — the whitelisted view (no client token). Either id form (`ses_...` or bare) works. */
1746
2186
  get(id: string): Promise<Session>;
1747
2187
  /**
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
2188
+ * `POST /sessions/:id/cancel` — stop a session that has not ended. The
2189
+ * hosted link stops working, and one `session.failed` with
2190
+ * `failureReason: "cancelled_by_organization"` is sent. Returns the
2191
+ * cancelled session. `409 session_not_cancellable` once the session has
2192
+ * ended (a repeated cancel included). Needs the `sessions:create` scope.
2193
+ */
2194
+ cancel(id: string, opts?: RequestOptions): Promise<Session>;
2195
+ /**
2196
+ * `POST /sessions/:id/link/resend` — send the hosted link again through the
2197
+ * session's own `deliver` channel, to the same destination (neither can be
2198
+ * changed). Only for sessions created with `deliver`:
2199
+ * `409 link_not_deliverable` otherwise, `409 link_not_usable` once the
2200
+ * session ended, `429 resend_rate_limited` past the send limits. Needs the
2201
+ * `sessions:create` scope.
2202
+ */
2203
+ resendLink(id: string, opts?: RequestOptions): Promise<SessionLinkDelivery>;
2204
+ /**
2205
+ * `POST /sessions/:id/link/extend` — a later expiry for the hosted link
2206
+ * and its session: `{ ttlMinutes }` counted from the session creation, or
2207
+ * `{ expiresAt }`. `400 ttl_out_of_policy` when it is not later than the
2208
+ * current expiry or past the flow's maximum. Only for sessions created with
2209
+ * `deliver`. Needs the `sessions:create` scope.
2210
+ */
2211
+ extendLink(id: string, input: ExtendLinkInput, opts?: RequestOptions): Promise<SessionLinkExpiry>;
2212
+ /**
2213
+ * The first page of your sessions, newest first (`GET /sessions`; the API
2214
+ * returns 50 by default, at most 100 with `limit`). Read every page with
2215
+ * {@link SessionsApi.iterate}, or one page and its cursor with
2216
+ * {@link SessionsApi.listPage}. The `externalRef` and `status` filters are
1750
2217
  * applied again to the answer, so an API that ignores them never returns
1751
2218
  * another user's sessions.
1752
2219
  */
1753
2220
  list(query?: ListSessionsQuery): Promise<Session[]>;
2221
+ /** One page of {@link SessionsApi.list} with its `nextCursor` (absent on the last page). */
2222
+ listPage(query?: ListSessionsQuery): Promise<Page<Session>>;
1754
2223
  /**
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`).
2224
+ * Every session matching `query`, newest first, following `nextCursor` page
2225
+ * after page (`limit` sets the page size).
2226
+ *
2227
+ * @example
2228
+ * ```ts
2229
+ * for await (const s of sekyro.sessions.iterate({ status: "completed" })) {
2230
+ * console.log(s.id);
2231
+ * }
2232
+ * ```
2233
+ */
2234
+ iterate(query?: ListSessionsQuery): AsyncGenerator<Session, void, undefined>;
2235
+ /**
2236
+ * `GET /sessions/:id/media` — the session's media (documents, portraits,
2237
+ * the selfie, the clips), each with its check, attempt tags and a URL valid
2238
+ * 15 minutes ({@link MediaItem}). Needs the `sessions:read` scope.
2239
+ */
2240
+ media(id: string): Promise<MediaList>;
2241
+ /**
2242
+ * `GET /sessions/:id/media/:kind` — the bytes of one media item: the
2243
+ * decisive attempt of that kind by default, `attempt` for another one,
2244
+ * `reference: "first"` for the first reference of a `reference_portrait`
2245
+ * a second reference decided. `404 media_not_available` when the kind, the
2246
+ * attempt or the object is not there. Needs the `sessions:read` scope.
2247
+ */
2248
+ mediaBytes(id: string, kind: MediaKind, opts?: MediaBytesOptions): Promise<MediaBytes>;
2249
+ /**
2250
+ * `GET /sessions/:id/portrait?format=url` — ID mode: a short-lived
2251
+ * presigned link to the 480×640 ICAO portrait (JPEG). Needs the
2252
+ * `sessions:read` scope (the older `portrait:read` still works).
2253
+ * `404 portrait_not_available` until the session's `portrait_icao` check
2254
+ * has passed (`portraitAvailable`).
2255
+ * @deprecated Use {@link SessionsApi.media} (the `icao_portrait` item) or
2256
+ * {@link SessionsApi.mediaBytes} with `icao_portrait`. This method stays on
2257
+ * the portrait route for its last release.
1759
2258
  */
1760
2259
  portrait(id: string): Promise<SessionPortraitLink>;
1761
2260
  /**
@@ -1767,56 +2266,71 @@ declare class SessionsApi {
1767
2266
  resultToken(id: string): Promise<ResultTokenResponse>;
1768
2267
  }
1769
2268
  /**
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.
2269
+ * `sekyro.people` — read and manage people (the same person across your
2270
+ * apps). Reads need the `people:read` scope, `revoke` / `delete` the
2271
+ * `people:write` scope (`subjects:read` and `subjects:write`, the older
2272
+ * names, still work; keys minted from the dashboard carry both). A person is
2273
+ * visible once they have passed a verification: a person who never passed,
2274
+ * an unknown id and a person of another organization or environment all
2275
+ * answer the same `404 subject_not_found` on `get`, `revoke` and `delete`,
2276
+ * and `list` leaves them out. Ids are `per_...`; the bare 24 hexadecimal
2277
+ * characters name the same person.
1778
2278
  *
1779
2279
  * Type-only export, like {@link SessionsApi}: obtained through
1780
- * {@link Sekyro.subjects}.
2280
+ * {@link Sekyro.people}.
1781
2281
  * @public
1782
2282
  */
1783
- declare class SubjectsApi {
1784
- private readonly call;
2283
+ declare class PeopleApi {
2284
+ private readonly t;
1785
2285
  /** @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>;
2286
+ constructor(t: {
2287
+ call<T>(method: "GET" | "POST" | "DELETE", path: string, body?: unknown, idempotencyKey?: string): Promise<T>;
2288
+ page<T>(path: string): Promise<Page<T>>;
2289
+ });
2290
+ /** `GET /people/:id` — the person, their sessions and their returning-user readiness. */
2291
+ get(id: string): Promise<Person>;
1789
2292
  /**
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.
2293
+ * The first page of the people who have passed a verification, newest
2294
+ * first (`GET /people`; 50 by default, at most 100 with `limit`),
2295
+ * optionally only those carrying your own id (`externalRef`). The list can
2296
+ * be empty while sessions with this `externalRef` exist. Every page:
2297
+ * {@link PeopleApi.iterate}.
1793
2298
  */
1794
- list(query: {
1795
- externalRef: string;
1796
- }): Promise<Subject[]>;
2299
+ list(query?: ListPeopleQuery): Promise<Person[]>;
2300
+ /** One page of {@link PeopleApi.list} with its `nextCursor` (absent on the last page). */
2301
+ listPage(query?: ListPeopleQuery): Promise<Page<Person>>;
2302
+ /** Every person matching `query`, newest first, following `nextCursor` page after page. */
2303
+ iterate(query?: ListPeopleQuery): AsyncGenerator<Person, void, undefined>;
1797
2304
  /**
1798
- * `POST /subjects/:id/revoke` — the subject can no longer be used for
2305
+ * `POST /people/:id/revoke` — the person can no longer be used for
1799
2306
  * returning-user sessions. Idempotent: revoking again returns the same view.
1800
- * Emits `subject.updated` with `status: 'revoked'`.
2307
+ * Emits `person.updated` (and `subject.updated`) with `status: 'revoked'`.
1801
2308
  */
1802
- revoke(id: string, input?: RevokeSubjectInput, opts?: RequestOptions): Promise<Subject>;
2309
+ revoke(id: string, input?: RevokePersonInput, opts?: RequestOptions): Promise<Person>;
1803
2310
  /**
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`.
2311
+ * `DELETE /people/:id` — deletes the person's stored photos, face
2312
+ * templates and identifiers, and the personal data and media of their
2313
+ * sessions, which it unlinks (they keep their outcome and steps). Emits
2314
+ * `person.deleted` (and `subject.deleted`). Cannot be undone; a second call answers `404`.
1807
2315
  */
1808
- delete(id: string): Promise<DeletedSubject>;
2316
+ delete(id: string): Promise<DeletedPerson>;
1809
2317
  /**
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
2318
+ * A re-check or step-up session for an existing person in one call:
2319
+ * `POST /people/:id/sessions` when `target` is a person id (`per_...` or 24
2320
+ * hexadecimal characters) or `{ personId }`, otherwise
2321
+ * `POST /people/by-external-ref/:externalRef/sessions` (pass
1814
2322
  * `{ externalRef }` to force it). Same result and errors as
1815
2323
  * {@link SessionsApi.create}; needs the `sessions:create` and
1816
- * `subjects:read` scopes.
2324
+ * `people:read` scopes.
1817
2325
  */
1818
- createSession(target: string | SubjectSessionTarget, input: SubjectSessionInput, opts?: RequestOptions): Promise<CreatedSession>;
2326
+ createSession(target: string | PersonSessionTarget, input: PersonSessionInput, opts?: RequestOptions): Promise<CreatedSession>;
1819
2327
  }
2328
+ /**
2329
+ * @deprecated Use {@link PeopleApi} ({@link Sekyro.people}); `sekyro.subjects`
2330
+ * is the same object.
2331
+ * @public
2332
+ */
2333
+ type SubjectsApi = PeopleApi;
1820
2334
  /**
1821
2335
  * Sekyro AI partner API client. Server-side only: it carries your API key.
1822
2336
  *
@@ -1827,14 +2341,16 @@ declare class SubjectsApi {
1827
2341
  * @example
1828
2342
  * ```ts
1829
2343
  * const sekyro = new Sekyro({ apiKey: process.env.SEKYRO_API_KEY! });
1830
- * const { id, clientToken } = await sekyro.sessions.create({ input: { nni: "1357924632" } });
2344
+ * const { id, hostedUrl } = await sekyro.sessions.create({ person: { externalRef: "<your user id>" } });
1831
2345
  * ```
1832
2346
  * @public
1833
2347
  */
1834
2348
  declare class Sekyro {
1835
2349
  #private;
1836
2350
  readonly sessions: SessionsApi;
1837
- readonly subjects: SubjectsApi;
2351
+ readonly people: PeopleApi;
2352
+ /** @deprecated Use {@link Sekyro.people}: the same object. */
2353
+ readonly subjects: PeopleApi;
1838
2354
  constructor(opts: SekyroOptions);
1839
2355
  /**
1840
2356
  * `GET /flows` — the published flows of the API key's app (default flow
@@ -1845,4 +2361,4 @@ declare class Sekyro {
1845
2361
  listFlows(): Promise<FlowSummary[]>;
1846
2362
  }
1847
2363
 
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 };
2364
+ export { type LevelTarget as $, type AgeMethod as A, type DocumentSubstitutionSettings as B, type CreatedSession as C, DEFAULT_BASE_URL as D, type EidResult as E, type FetchLike as F, type EligibilityReason as G, type ExtendLinkInput as H, type FlowOverridableSettings as I, type FlowOverrides as J, type FlowServiceSettings as K, type Locale as L, type FlowSummary as M, type IdNumberReason as N, type Identity as O, type IdentityBirthPlace as P, type IdentityDocument as Q, type ReviewReason as R, Sekyro as S, type IdentityIdNumber as T, type IdentityMethod as U, type VerificationLevel as V, type WebhookEventType as W, type IdentityName as X, type IdentityScalarKey as Y, type IdentitySource as Z, type IdentitySources as _, type ServiceId as a, type SubjectSession as a$, type ListPeopleQuery as a0, type ListSessionsQuery as a1, type MatchReason as a2, type MediaBytes as a3, type MediaBytesOptions as a4, type MediaItem as a5, type MediaKind as a6, type MediaList as a7, type NameForm as a8, type Page as a9, type SessionEventData as aA, type SessionFailureReason as aB, type SessionFlowRef as aC, type SessionLifecycleEventData as aD, type SessionLinkDelivery as aE, type SessionLinkExpiry as aF, type SessionLinkInput as aG, type SessionNetwork as aH, type SessionNetworkEvent as aI, type SessionPortraitLink as aJ, type SessionReviewDecidedEventData as aK, type SessionStatus as aL, type SessionStep as aM, type SessionStepCompletedEventData as aN, type SessionStepDecision as aO, type SessionSubjectInput as aP, type SessionSupersededEventData as aQ, SessionsApi as aR, type Subject as aS, type SubjectAssurance as aT, type SubjectDeletedEventData as aU, type SubjectEnrolledEventData as aV, type SubjectIdNumber as aW, type SubjectName as aX, type SubjectReferenceSource as aY, type SubjectReuseDocument as aZ, type SubjectReuseTarget as a_, PeopleApi as aa, type Person as ab, type PersonBirthPlaceInput as ac, type PersonDeletedEventData as ad, type PersonDocumentInput as ae, type PersonEnrolledEventData as af, type PersonSession as ag, type PersonSessionInput as ah, type PersonSessionTarget as ai, type PersonSuspiciousActivityEventData as aj, type PersonUpdatedEventData as ak, type PolicyFailureReason as al, type PortraitReportEntry as am, type PriorReviewReason as an, type ProbeBindingReason as ao, type ProbeQuality as ap, type ProfileDocumentType as aq, type RequestOptions as ar, type ResultTokenResponse as as, type ReviewOutcomeReason as at, type RevokePersonInput as au, type RevokeSubjectInput as av, type SekyroOptions as aw, type Session as ax, type SessionDevice as ay, type SessionDeviceSignal as az, type SessionPersonInput as b, type SubjectSessionInput as b0, type SubjectSessionTarget as b1, type SubjectStatus as b2, type SubjectSuspiciousActivityEventData as b3, type SubjectUpdatedEventData as b4, type SubjectsApi as b5, type SuppliedIdentityRecord as b6, type UsageThresholdReachedEventData as b7, type VerifiedContacts as b8, type WebhookEnvelopeOf as b9, type WebhookEventDataMap as ba, 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 DecidedBy as u, type DecisionReason as v, type DeepPartial as w, type DeletedPerson as x, type DeletedSubject as y, type DeliverOptions as z };