@sekyro/node 0.1.0-rc.8 → 0.1.0-rc.9

This diff represents the content of publicly available package versions that have been released to one of the supported registries. The information contained in this diff is provided for informational purposes only and reflects changes between package versions as they appear in their respective public registries.
package/CHANGELOG.md CHANGED
@@ -1,5 +1,15 @@
1
1
  # @sekyro/node
2
2
 
3
+ ## 0.1.0-rc.9
4
+
5
+ ### Minor Changes
6
+
7
+ - ef0b9b2: Person data in one international `subject` (spec 2026-10-31). `SessionSubjectInput` gains `idNumber` (`{ type, issuingCountry, number }`, new `SubjectIdNumber`), `names` (per ISO 15924 script, new `SubjectName`), `email`, `birthPlace`, `sex`, `photo`, `photoDate` and `fetchedAt`; the flow decides whether they are checked or believed. `subject.reuse` takes `{ idNumber }`. `CreatedSession` gains `subjectUse` and `warnings` (one `deprecated_field` entry per deprecated key you sent). `SekyroApiError.retryAfterSeconds` reads the `Retry-After` header (seconds or an HTTP date).
8
+
9
+ Deprecated, still sent as passed: `input.nni`, `input.fullName`, `input.birthDate`, `input.phone`, `input.email`, `input.suppliedIdentity` (`SuppliedIdentityRecord`), `subject.nni`, `subject.documentNumber`, the `nni` and `document` reuse targets, and the flow setting `population_registry.nniSource` (use `idNumberSource`). Reason unions carry each renamed reason under both names (`IdNumberReason`; `PolicyFailureReason` gains `document_id_number_mismatch`).
10
+
11
+ Breaking (pre-1.0): `registryFromAnrpts()` and `RegistryFromAnrptsOptions` are removed. Use `subjectFromNationalRegistry("MR", answer, { fetchedAt })`, which returns the `subject` reference keys (`SubjectRecord`) and throws `SekyroConfigError` `registry_country_unsupported` for a country without a format, and `registry_nationality_unmapped` when the answer states a nationality it cannot map (pass `options.nationality` to map it yourself).
12
+
3
13
  ## 0.1.0-rc.8
4
14
 
5
15
  ### Patch Changes
package/README.md CHANGED
@@ -46,10 +46,14 @@ const sekyro = new Sekyro({
46
46
 
47
47
  // Create: returns the one-time client token your front end hands to @sekyro/web.
48
48
  // `flow` picks one of the app's flows (omit it for the default flow).
49
- // `input.nni` BINDS the session to that identity: the browser never sends the
50
- // NNI (a different one is refused with 409 nni_locked).
49
+ // `subject.idNumber` BINDS the session to that identity: the browser never sends
50
+ // the number (a different one is refused with 409 id_number_locked, formerly nni_locked).
51
51
  const created = await sekyro.sessions.create(
52
- { flow: "default", locale: "ar", input: { nni: "0000000098" } },
52
+ {
53
+ flow: "default",
54
+ locale: "ar",
55
+ subject: { idNumber: { type: "national_id", issuingCountry: "<ISO alpha-2>", number: "<id number>" } },
56
+ },
53
57
  { idempotencyKey: `signup:${userId}` },
54
58
  );
55
59
  created.id; // persist against your user before returning to the page
@@ -57,6 +61,8 @@ created.clientToken; // give this to the browser; it is returned ONCE
57
61
  created.hostedUrl; // the hosted-flow link, if you use that path instead
58
62
  created.expiresAt; // ISO 8601
59
63
  created.flow; // { id, slug, version }: the flow version the session runs
64
+ created.subjectUse; // 'reference' | 'prefill': whether the flow believes or checks your subject data
65
+ created.warnings; // one { code: 'deprecated_field', field, replacement } per deprecated key you sent
60
66
 
61
67
  // Read: the whitelisted session view (never contains the client token).
62
68
  const session = await sekyro.sessions.get(created.id);
@@ -81,8 +87,8 @@ Every field is optional:
81
87
  | `overrides` | `{ settings?, services? }`: changes the flow for this session only (see below; `403 override_widens_flow` for a looser change unless the flow allows it, `400 override_invalid` for an invalid one) |
82
88
  | `locale` | `ar`, `fr` or `en`: pins the hosted-flow language |
83
89
  | `ttlMinutes` | session lifetime, within the flow's link range (`400 ttl_out_of_policy` otherwise); omit for the flow default |
84
- | `input` | the step anchors: `nni`, `phone`, `email`, `fullName`, `birthDate`, all **strings** (an NNI is a 10-digit string, never a number), plus any further keys (flow branches can read them); `input.nni` binds the session to that identity |
85
- | `subject` | what you know about the person (`nni`, `phone`, `fullName`, `birthDate`, `nationality`, `documentNumber`), your own id for them (`externalRef`), or `reuse` for a [returning user](#subjects) |
90
+ | `subject` | what you know about the person: `idNumber` (`{ type, issuingCountry, number }`, binds the session), `fullName`, `names` (per script), `birthDate`, `birthPlace`, `sex`, `nationality`, `phone`, `email`, and for a reference record `photo`, `photoDate`, `fetchedAt`; your own id for them (`externalRef`), or `reuse` for a [returning user](#subjects). The flow decides whether the data is checked or believed (`created.subjectUse`) |
91
+ | `input` | an open record of branch facts your flow's conditions read. Its person keys (`nni`, `phone`, `email`, `fullName`, `birthDate`, `suppliedIdentity`) are deprecated: send them in `subject` (`subject.nni` and `subject.documentNumber` are deprecated too, for `subject.idNumber`) |
86
92
  | `identityMethod` | `national_number`, `document_photo`, `document_chip` or `national_eid`: pre-chooses the option of the flow's identity choice |
87
93
  | `deliver` | `{ channel: "sms" \| "whatsapp", to: "+1555…" }`: also send the hosted link to the person |
88
94
 
@@ -130,34 +136,73 @@ Two more session calls:
130
136
  `sekyro.sessions` is a `SessionsApi`, exported as a type only: you get the
131
137
  instance from the client, never by constructing one.
132
138
 
133
- ### Partner-supplied identity data (`supplied` mode)
139
+ ### Person data
134
140
 
135
- If Sekyro AI set your environment to the `supplied` mode, you send the
136
- person's identity data (biographic record and photo) with the session in
137
- `input.suppliedIdentity`. Sekyro AI treats it as identity data supplied by
138
- your organization: it makes no registry call, and it never receives or stores
139
- any registry key. If your data comes from your own call to the national
140
- population registry, `registryFromAnrpts()` converts that answer locally into
141
- the record shape:
141
+ Send what you know about the person in `subject`: `idNumber`
142
+ (`{ type, issuingCountry, number }`), `fullName` or `names` (given, family and
143
+ patronymic per ISO 15924 script), `birthDate`, `nationality`, `phone`, `email`,
144
+ and for a flow that verifies identity from your data, `photo` and `fetchedAt`.
145
+ The session's flow decides how Sekyro AI uses it, never the request: when a step
146
+ reads partner-supplied data (an environment Sekyro AI set to the `supplied`
147
+ mode), the record is the **reference** to believe; otherwise it is a
148
+ **prefill** checked against what the person shows. `created.subjectUse` says
149
+ which (`"reference"` or `"prefill"`). The rules, the trust table and every
150
+ error are on the [Person data](https://docs.sekyro.ai/en/guides/person-data)
151
+ page.
142
152
 
143
153
  ```ts
144
- import { registryFromAnrpts } from "@sekyro/node";
154
+ // A prefill: the flow checks it against the registry or the document.
155
+ await sekyro.sessions.create({
156
+ subject: {
157
+ externalRef: userId,
158
+ idNumber: { type: "passport", issuingCountry: "<ISO alpha-2>", number: "<id number>" },
159
+ birthDate: "<YYYY-MM-DD>",
160
+ },
161
+ });
162
+ ```
163
+
164
+ If your data comes from your own call to a national registry,
165
+ `subjectFromNationalRegistry()` converts that answer locally into the
166
+ reference keys. Sekyro AI treats the result as identity data supplied by your
167
+ organization: it makes no registry call, and it never receives or stores any
168
+ registry key.
145
169
 
146
- const answer = await myRegistryClient.lookup(nni); // your call, your key
170
+ ```ts
171
+ import { subjectFromNationalRegistry } from "@sekyro/node";
172
+
173
+ const answer = await myRegistryClient.lookup(idNumber); // your call, your key
147
174
  const receivedAt = new Date();
148
- await sekyro.sessions.create({
149
- // fetchedAt: when YOUR system received this answer (required; > 24 h old is refused)
150
- input: { nni, suppliedIdentity: registryFromAnrpts(answer, { fetchedAt: receivedAt }) },
175
+ const created = await sekyro.sessions.create({
176
+ subject: {
177
+ externalRef: userId,
178
+ // fetchedAt: when YOUR system received this answer (required; > 24 h old is refused)
179
+ ...subjectFromNationalRegistry("MR", answer, { fetchedAt: receivedAt }),
180
+ },
151
181
  });
182
+ created.subjectUse; // "reference" in a supplied-mode environment whose flow reads it
152
183
  ```
153
184
 
154
- `suppliedIdentity.nni` must equal `input.nni`. Refusals:
155
- `403 supplied_identity_not_entitled` (the environment is not in `supplied` mode),
156
- `422 supplied_identity_required` (the environment is in `supplied` mode and the app
157
- verifies identity, but `input.suppliedIdentity` was not sent),
158
- `400 supplied_identity_nni_mismatch`, `422 supplied_identity_stale` (obtained more
159
- than 24 h ago) and `422 supplied_identity_photo_unusable` (not a JPEG or PNG of at
160
- most 1 MB within the size bounds).
185
+ The first argument is the registry's country (ISO alpha-2) and types the
186
+ answer: `"MR"` takes the ANRPTS `getPersonne` answer
187
+ (`AnrptsPersonneResponse`). The result is a `SubjectRecord`: `idNumber`,
188
+ `names` (one entry per script found), `birthDate`, `birthPlace`, `sex`,
189
+ `nationality` (alpha-2), `photo`, `photoDate` and `fetchedAt`. A record without
190
+ a number, a birth date, a photo or any name, or with an invalid `fetchedAt`,
191
+ throws `SekyroConfigError` `invalid_registry_record` naming the field (never
192
+ its value); a country without an adapter throws `registry_country_unsupported`.
193
+ An answer that states a nationality none of whose values the SDK can map throws
194
+ `registry_nationality_unmapped` (the message never carries the value): map it
195
+ yourself and pass `options.nationality` (ISO alpha-2), so the stated nationality
196
+ is never dropped.
197
+ `subjectFromNationalRegistry()` replaces `registryFromAnrpts()`.
198
+
199
+ Refusals of a reference, in this order: `403 supplied_identity_not_entitled`
200
+ (the environment is not in `supplied` mode), `422 subject_record_incomplete`
201
+ (`error.details.fields` names the missing keys), `422 subject_record_stale`
202
+ (obtained more than 24 h ago, or more than 5 min ahead) and
203
+ `422 subject_photo_unusable` (not a JPEG or PNG of at most 1 MB within the size
204
+ bounds). A `photo` on a session that cannot use it (a prefill, a returning
205
+ user) answers `422 subject_photo_not_used`.
161
206
 
162
207
  No face processing runs at create. The face on the supplied photo is checked after
163
208
  the person consents, at the face match: a photo without one usable face fails that
@@ -167,6 +212,18 @@ that the photo shows exactly one clear face before you send it.
167
212
  Partner-supplied identity data is not billed: the identity step in `supplied` mode
168
213
  records no usage event (other steps, such as the face match, bill as usual).
169
214
 
215
+ **Deprecated keys.** `input.nni`, `input.fullName`, `input.birthDate`,
216
+ `input.phone`, `input.email`, `input.suppliedIdentity`, `subject.nni`,
217
+ `subject.documentNumber`, `subject.reuse.nni` and `subject.reuse.document`
218
+ still work. A create that uses one gets a `Deprecation` header and one
219
+ `created.warnings` entry per key (`{ code: "deprecated_field", field,
220
+ replacement }`). The step reasons and codes about the number get generic names
221
+ (`registry_record_not_found` for `nni_not_found`, `id_number_locked` for
222
+ `nni_locked`, `document_id_number_mismatch` for `document_nni_mismatch`, ...):
223
+ the API still sends the previous names, so accept both. The full migration
224
+ table is on the [Person data](https://docs.sekyro.ai/en/guides/person-data#deprecated-keys)
225
+ page.
226
+
170
227
  ### Errors
171
228
 
172
229
  Every non-2xx response, network failure and timeout throws `SekyroApiError`:
@@ -179,15 +236,16 @@ Every non-2xx response, network failure and timeout throws `SekyroApiError`:
179
236
  | `requestId` | the API's `request_id`, quote it to support |
180
237
  | `details` | the API's `error.details` when sent, else `undefined`; typed for the flow codes through `isFlowError()` |
181
238
  | `retryable` | `true` for `network`, `timeout`, `429`, `5xx` and `idempotency_in_progress` |
239
+ | `retryAfterSeconds` | seconds to wait from the response's `Retry-After` header (seconds or an HTTP date), else `undefined` |
182
240
 
183
241
  ```ts
184
242
  import { SekyroApiError } from "@sekyro/node";
185
243
 
186
244
  try {
187
- await sekyro.sessions.create({ input: { nni } });
245
+ await sekyro.sessions.create({ subject: { idNumber } });
188
246
  } catch (err) {
189
247
  if (err instanceof SekyroApiError && err.retryable) {
190
- // back off and retry with the SAME idempotencyKey
248
+ // wait err.retryAfterSeconds when set, else back off; retry with the SAME idempotencyKey
191
249
  }
192
250
  }
193
251
  ```
@@ -243,7 +301,7 @@ const recent = await sekyro.sessions.list({ externalRef: userId, status: "comple
243
301
  const [byRef] = await sekyro.subjects.list({ externalRef: userId });
244
302
 
245
303
  // Returning user: liveness + face match against the stored reference photo.
246
- // Name exactly one of subjectId, externalRef or nni.
304
+ // Name exactly one of subjectId, externalRef or idNumber (nni and document are deprecated).
247
305
  await sekyro.sessions.create({ subject: { reuse: { subjectId } } });
248
306
 
249
307
  // The same in one call, with a mode: `recheck` (verify the same person again)
@@ -157,12 +157,24 @@ type EligibilityReason = "document_type_not_accepted" | "nationality_not_allowed
157
157
  * Why a profile-v2 policy ended a session: a session-level
158
158
  * {@link SessionFailureReason} (location / anonymizer gate), or the failed
159
159
  * check's policy reason — an {@link EligibilityReason} or
160
- * `document_nni_mismatch` (the document belongs to someone other than the
161
- * NNI the session was created for), or `camera_unavailable` (spec 2026-10-29 §3.4: the person had no usable camera,
160
+ * `document_id_number_mismatch` (the document belongs to someone other than the
161
+ * ID number the session was created for; `document_nni_mismatch` is its former
162
+ * 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,
162
163
  * so the live step ended without a capture; the session is rejected at level 0 unless your flow has a fallback).
163
164
  * @public
164
165
  */
165
- type PolicyFailureReason = SessionFailureReason | EligibilityReason | "document_nni_mismatch" | "camera_unavailable";
166
+ type PolicyFailureReason = SessionFailureReason | EligibilityReason | "document_id_number_mismatch" | "document_nni_mismatch" | "camera_unavailable";
167
+ /**
168
+ * The ID-number reasons a check's {@link SessionStep.reason} may carry (person data
169
+ * spec Appendix A.2), each under its generic name and its former Mauritanian name:
170
+ * `id_number_invalid` (`nni_invalid`: the number fails its country's rule),
171
+ * `registry_record_not_found` (`nni_not_found`: no registry record for the number),
172
+ * `id_number_recheck` (`nni_recheck`: the number must be checked again) and
173
+ * `document_id_number_mismatch` (`document_nni_mismatch`). The API sends the former
174
+ * names until it switches to the generic ones; handle both.
175
+ * @public
176
+ */
177
+ type IdNumberReason = "id_number_invalid" | "nni_invalid" | "registry_record_not_found" | "nni_not_found" | "id_number_recheck" | "nni_recheck" | "document_id_number_mismatch" | "document_nni_mismatch";
166
178
  /**
167
179
  * Why the person had no camera (spec 2026-10-29 §3.4, 2026-10-30), when the SDK said: `denied` (the
168
180
  * person refused camera access) or `no_camera` (no usable camera: none found, an insecure page or a
@@ -278,29 +290,90 @@ interface SessionPortraitLink {
278
290
  interface DeliverOptions {
279
291
  /** Delivery channel. */
280
292
  channel: "sms" | "whatsapp";
281
- /** E.164 phone number of the recipient, e.g. `+22236123456`. */
293
+ /** E.164 phone number of the recipient (`+` and the country code). */
282
294
  to: string;
283
295
  }
296
+ /**
297
+ * An ID number of the person (person data spec §4.1): the document type, the
298
+ * issuing country (ISO 3166-1 alpha-2; alpha-3 is accepted and normalized) and
299
+ * the number (1 to 40 characters, then the issuing country's rule, e.g. the
300
+ * check digit of a Mauritanian national ID number).
301
+ * @public
302
+ */
303
+ interface SubjectIdNumber {
304
+ type: "national_id" | "passport" | "residence_permit";
305
+ issuingCountry: string;
306
+ number: string;
307
+ }
308
+ /**
309
+ * The person's name in one script (ISO 15924 code, e.g. `Latn` or `Arab`).
310
+ * @public
311
+ */
312
+ interface SubjectName {
313
+ script: string;
314
+ /** 1 to 100 characters. */
315
+ given: string;
316
+ /** 1 to 100 characters. */
317
+ family: string;
318
+ /** Optional, 1 to 100 characters. */
319
+ patronymic?: string;
320
+ }
284
321
  /**
285
322
  * What you already know about the person (`subject` at session create). A
286
323
  * closed object: unknown keys are refused (`400`). Every field is optional;
287
- * `null` or blank counts as absent. Identity fields are compared with the
288
- * person's document or registry record when the app's profile turns name
289
- * matching on; `nni` binds the session to that identity.
324
+ * `null` or blank counts as absent.
325
+ *
326
+ * The flow decides whether these are checked or believed: in a flow that checks
327
+ * identity from a document or a registry, they are a prefill compared with what
328
+ * the person shows; in a flow that verifies identity from your data (the
329
+ * response's `subjectUse: "reference"`), `idNumber`, `birthDate`, `photo` and
330
+ * `fetchedAt` are required and the record is the reference. `idNumber` binds the
331
+ * session to that identity in both cases: the hosted flow may omit it but cannot
332
+ * substitute another number.
290
333
  * @public
291
334
  */
292
335
  interface SessionSubjectInput {
293
- /** 10-digit Mauritanian NNI, as a string. */
336
+ /** The person's ID number. Binds the session. */
337
+ idNumber?: SubjectIdNumber;
338
+ /**
339
+ * @deprecated Use `idNumber: { type: "national_id", issuingCountry: "MR", number }`.
340
+ * A Mauritanian national ID number (10 digits), as a string.
341
+ */
294
342
  nni?: string;
295
- /** E.164 phone number, e.g. `+22236123456`. */
343
+ /** E.164 phone number (`+` and the country code). */
296
344
  phone?: string;
345
+ /** Email address, for the email OTP step. */
346
+ email?: string;
347
+ /** Full name, 1 to 200 characters, any script. */
297
348
  fullName?: string;
349
+ /** The name per script, at most 4 entries, one per script. */
350
+ names?: SubjectName[];
298
351
  /** ISO 8601 date (`YYYY-MM-DD`). */
299
352
  birthDate?: string;
300
- /** ISO 3166-1 alpha-2, e.g. `MR`. */
353
+ /** Place of birth, 1 to 120 characters, any script (kept only with a reference record). */
354
+ birthPlace?: string;
355
+ /** `M`, `F` or `X` (ICAO 9303 values; kept only with a reference record). */
356
+ sex?: "M" | "F" | "X";
357
+ /** ISO 3166-1 alpha-2. */
301
358
  nationality?: string;
302
- /** Identity-document number (1–40 characters). */
359
+ /**
360
+ * @deprecated Use `idNumber` with the document's `type` and `issuingCountry`.
361
+ * Identity-document number (1 to 40 characters).
362
+ */
303
363
  documentNumber?: string;
364
+ /**
365
+ * Base64 JPEG or PNG (optional data-URL prefix, at most 1 MB decoded): the
366
+ * face-match reference of a reference record. Refused in a flow that uses the
367
+ * data as a prefill (`422 subject_photo_not_used`).
368
+ */
369
+ photo?: string;
370
+ /** ISO 8601 date (`YYYY-MM-DD`) of the photo. */
371
+ photoDate?: string;
372
+ /**
373
+ * ISO 8601 date-time: when YOUR system obtained this data. Required with a
374
+ * reference record; at most 24 h old (`422 subject_record_stale`).
375
+ */
376
+ fetchedAt?: string;
304
377
  /**
305
378
  * Your own id for this person (1–128 characters). Echoed on the session and
306
379
  * its webhooks, and searchable on the subjects API.
@@ -328,9 +401,11 @@ interface SubjectReuseDocument {
328
401
  number: string;
329
402
  }
330
403
  /**
331
- * Which subject a returning-user session re-verifies — exactly ONE of the
332
- * subject id, your own `externalRef` (must match a single subject), the NNI
333
- * or an identity document the person verified with.
404
+ * Which subject a returning-user session re-verifies: exactly ONE of the
405
+ * subject id, your own `externalRef` (must match a single subject) or the
406
+ * `idNumber` the person verified with. `nni` and `document` are the deprecated
407
+ * names of the `idNumber` target: an `nni` is an `idNumber` of type
408
+ * `national_id` issued by `MR`; a `document` has the same three parts.
334
409
  * @public
335
410
  */
336
411
  type SubjectReuseTarget = ({
@@ -338,21 +413,33 @@ type SubjectReuseTarget = ({
338
413
  externalRef?: never;
339
414
  nni?: never;
340
415
  document?: never;
416
+ idNumber?: never;
341
417
  } | {
342
418
  externalRef: string;
343
419
  subjectId?: never;
344
420
  nni?: never;
345
421
  document?: never;
422
+ idNumber?: never;
346
423
  } | {
424
+ /** @deprecated Use `idNumber` with type `national_id` and issuing country `MR`. */
347
425
  nni: string;
348
426
  subjectId?: never;
349
427
  externalRef?: never;
350
428
  document?: never;
429
+ idNumber?: never;
351
430
  } | {
431
+ /** @deprecated Use `idNumber` (the same three parts). */
352
432
  document: SubjectReuseDocument;
353
433
  subjectId?: never;
354
434
  externalRef?: never;
355
435
  nni?: never;
436
+ idNumber?: never;
437
+ } | {
438
+ idNumber: SubjectIdNumber;
439
+ subjectId?: never;
440
+ externalRef?: never;
441
+ nni?: never;
442
+ document?: never;
356
443
  }) & {
357
444
  /**
358
445
  * `recheck` (default) or `step_up` ({@link SubjectReuseMode}). `step_up` on
@@ -512,7 +599,13 @@ interface FlowServiceSettings {
512
599
  population_registry: {
513
600
  /** `'org'` (every registry the org can use, resolved at session create) or registry ids. */
514
601
  sources: "org" | Array<"MR.anrpts">;
602
+ /**
603
+ * @deprecated Use `idNumberSource` (same values). Both with different values is
604
+ * `400 override_invalid`.
605
+ */
515
606
  nniSource: "auto" | "typed" | "bound_only";
607
+ /** Where the ID number comes from: `auto`, `typed` (the person types it) or `bound_only` (your `subject.idNumber`). */
608
+ idNumberSource: "auto" | "typed" | "bound_only";
516
609
  onUncovered: "skip";
517
610
  attempts?: number;
518
611
  };
@@ -666,48 +759,49 @@ interface CreateSessionInput {
666
759
  */
667
760
  overrides?: FlowOverrides;
668
761
  /**
669
- * Step inputs consumed server-side. The known anchors are typed (all
670
- * strings — an `nni` is a 10-digit string, never a number); further keys
671
- * pass through to the API as-is. `nni` binds the session to that identity:
672
- * the hosted flow may omit it but cannot substitute another.
762
+ * Step inputs consumed server-side: an open record of branch facts your flow's
763
+ * conditions read. The person keys below are deprecated: send them in
764
+ * {@link CreateSessionInput.subject} (the response's `warnings` names each one
765
+ * you used). Values are strings (a number is a string, never a JSON number).
673
766
  */
674
767
  input?: {
675
- /** 10-digit Mauritanian NNI, as a string. */
768
+ /**
769
+ * @deprecated Use `subject.idNumber: { type: "national_id", issuingCountry: "MR", number }`.
770
+ * A Mauritanian national ID number (10 digits), as a string.
771
+ */
676
772
  nni?: string;
677
- /** E.164 phone number, e.g. `+22236123456`. */
773
+ /** @deprecated Use `subject.phone`. E.164 phone number. */
678
774
  phone?: string;
679
- /** Email address for the email OTP step (`emailSource` `prefilled` / `prefilled_or_entered`). */
775
+ /** @deprecated Use `subject.email`. Email address for the email OTP step. */
680
776
  email?: string;
777
+ /** @deprecated Use `subject.fullName`. */
681
778
  fullName?: string;
682
- /** ISO 8601 date (`YYYY-MM-DD`). */
779
+ /** @deprecated Use `subject.birthDate`. ISO 8601 date (`YYYY-MM-DD`). */
683
780
  birthDate?: string;
684
781
  /**
685
- * Partner-supplied identity data (`supplied` mode only): the person's
686
- * biographic record and photo as YOUR system holds them — for example
687
- * from your own ANRPTS answer, converted with {@link registryFromAnrpts}.
688
- * Sekyro AI stores it as data you vouch for, makes no registry call, and
689
- * never receives or stores any registry key. `nni` must be set too and
690
- * equal `suppliedIdentity.nni`. Refused unless Sekyro AI enabled the mode
691
- * for the environment (`403 supplied_identity_not_entitled`); required in
692
- * that mode when the app verifies identity (`422 supplied_identity_required`).
782
+ * @deprecated Use the reference keys of `subject` (`idNumber`, `names`,
783
+ * `birthDate`, `photo`, `fetchedAt`, ...), for example from
784
+ * {@link subjectFromNationalRegistry}.
785
+ * Partner-supplied identity data (`supplied` mode only).
693
786
  */
694
787
  suppliedIdentity?: SuppliedIdentityRecord;
695
788
  } & Record<string, unknown>;
696
789
  }
697
790
  /**
791
+ * @deprecated Send the record in `subject` instead (`idNumber`, `names`,
792
+ * `birthDate`, `birthPlace`, `sex`, `nationality`, `photo`, `photoDate`,
793
+ * `fetchedAt`), for example from {@link subjectFromNationalRegistry}.
794
+ *
698
795
  * Partner-supplied identity data (`sessions.create` `input.suppliedIdentity`):
699
796
  * the person's biographic record and photo, as your organization holds them.
700
- * Sekyro AI treats it as identity data supplied by your organization, not as
701
- * a registry lookup. Refusals at create: `400 supplied_identity_nni_mismatch`,
797
+ * Refusals at create: `400 supplied_identity_nni_mismatch`,
702
798
  * `422 supplied_identity_stale` (`fetchedAt` older than 24 h),
703
799
  * `422 supplied_identity_photo_unusable` (not a JPEG/PNG of at most 1 MB within the
704
- * size bounds). In a `supplied` environment whose app verifies identity, a create
705
- * without `input.suppliedIdentity` is `422 supplied_identity_required`. The face on
706
- * the photo is checked after consent, at the face match (`no_face_reference`).
800
+ * size bounds).
707
801
  * @public
708
802
  */
709
803
  interface SuppliedIdentityRecord {
710
- /** 10-digit NNI, as a string. */
804
+ /** 10-digit national ID number, as a string. */
711
805
  nni: string;
712
806
  firstNameFr: string;
713
807
  lastNameFr: string;
@@ -720,7 +814,7 @@ interface SuppliedIdentityRecord {
720
814
  birthPlaceFr?: string;
721
815
  birthPlaceAr?: string;
722
816
  sex?: "M" | "F";
723
- /** Nationality text as your source holds it (e.g. `Mauritanienne`). */
817
+ /** Nationality text as your source holds it. */
724
818
  nationalities?: string[];
725
819
  /** Base64 JPEG or PNG (at most 1 MB decoded). */
726
820
  photo: string;
@@ -757,6 +851,25 @@ interface CreatedSession {
757
851
  expiresAt: string;
758
852
  /** The levels the flow can reach on its paths; absent from older API versions. */
759
853
  levelTarget?: LevelTarget;
854
+ /**
855
+ * How the flow uses the person data you sent: `reference` (believed, your
856
+ * record is the identity reference) or `prefill` (checked against the
857
+ * person's document or registry record). Absent from older API versions.
858
+ */
859
+ subjectUse?: "reference" | "prefill";
860
+ /** One entry per deprecated request key you used, naming its replacement. Absent otherwise. */
861
+ warnings?: CreatedSessionWarning[];
862
+ }
863
+ /**
864
+ * A deprecation warning of {@link CreatedSession.warnings}: `field` is the
865
+ * deprecated key you sent (e.g. `input.nni`), `replacement` the key to send
866
+ * instead (e.g. `subject.idNumber`).
867
+ * @public
868
+ */
869
+ interface CreatedSessionWarning {
870
+ code: "deprecated_field";
871
+ field: string;
872
+ replacement: string;
760
873
  }
761
874
  /**
762
875
  * Input of {@link SubjectsApi.createSession}: a re-check or step-up session
@@ -868,7 +981,7 @@ interface EidResult {
868
981
  interface VerifiedContacts {
869
982
  /** From a passed `phone_otp` check. */
870
983
  phone?: {
871
- /** E.164, e.g. `+22236123456`. */
984
+ /** E.164 (`+` and the country code). */
872
985
  number: string;
873
986
  /** The channel the code was delivered on. */
874
987
  channel: "whatsapp" | "sms";
@@ -1538,4 +1651,4 @@ declare class Sekyro {
1538
1651
  listFlows(): Promise<FlowSummary[]>;
1539
1652
  }
1540
1653
 
1541
- export { type SessionFailureReason as $, type AgeMethod as A, type LevelTarget as B, type CreatedSession as C, DEFAULT_BASE_URL as D, type EidResult as E, type FetchLike as F, type ListSessionsQuery as G, type PortraitReportEntry as H, type IdentityMethod as I, type ProbeBindingReason as J, type ProbeQuality as K, type Locale as L, type MatchReason as M, type ProfileDocumentType as N, type RequestOptions as O, type PolicyFailureReason as P, type ResultTokenResponse as Q, type ResultRisk as R, Sekyro as S, type RevokeSubjectInput as T, type SekyroOptions as U, type VerificationLevel as V, type WebhookEventType as W, type Session as X, type SessionDevice as Y, type SessionDeviceSignal as Z, type SessionEventData as _, type ServiceId as a, type SessionFlowRef as a0, type SessionLifecycleEventData as a1, type SessionLinkInput as a2, type SessionNetwork as a3, type SessionNetworkEvent as a4, type SessionPortraitLink as a5, type SessionReviewDecidedEventData as a6, type SessionStatus as a7, type SessionStep as a8, type SessionStepCompletedEventData as a9, type SessionSubjectInput as aa, SessionsApi as ab, type Subject as ac, type SubjectAssurance as ad, type SubjectDeletedEventData as ae, type SubjectEnrolledEventData as af, type SubjectReferenceSource as ag, type SubjectReuseDocument as ah, type SubjectReuseTarget as ai, type SubjectSession as aj, type SubjectSessionInput as ak, type SubjectSessionTarget as al, type SubjectStatus as am, type SubjectSuspiciousActivityEventData as an, type SubjectUpdatedEventData as ao, SubjectsApi as ap, type UsageThresholdReachedEventData as aq, type VerifiedContacts as ar, type WebhookEnvelopeOf as as, type WebhookEventDataMap as at, type SuppliedIdentityRecord 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 ResultCheckProofs as i, type ResultDuplicate as j, type AgeResult as k, type CameraUnavailableCause as l, type CheckState as m, type CheckType as n, type CreateSessionInput as o, DEFAULT_TIMEOUT_MS as p, type DecisionReason as q, type DeepPartial as r, type DeletedSubject as s, type DeliverOptions as t, type DocumentSubstitutionSettings as u, type EligibilityReason as v, type FlowOverridableSettings as w, type FlowOverrides as x, type FlowServiceSettings as y, type FlowSummary as z };
1654
+ export { type SessionDeviceSignal as $, type AgeMethod as A, type FlowSummary as B, type CreatedSession as C, DEFAULT_BASE_URL as D, type EidResult as E, type FetchLike as F, type IdentityMethod as G, type LevelTarget as H, type IdNumberReason as I, type ListSessionsQuery as J, type PortraitReportEntry as K, type Locale as L, type MatchReason as M, type ProbeBindingReason as N, type ProbeQuality as O, type PolicyFailureReason as P, type ProfileDocumentType as Q, type ResultRisk as R, Sekyro as S, type RequestOptions as T, type ResultTokenResponse as U, type VerificationLevel as V, type WebhookEventType as W, type RevokeSubjectInput as X, type SekyroOptions as Y, type Session as Z, type SessionDevice as _, type ServiceId as a, type SessionEventData as a0, type SessionFailureReason as a1, type SessionFlowRef as a2, type SessionLifecycleEventData as a3, type SessionLinkInput as a4, type SessionNetwork as a5, type SessionNetworkEvent as a6, type SessionPortraitLink as a7, type SessionReviewDecidedEventData as a8, type SessionStatus as a9, type SessionStep as aa, type SessionStepCompletedEventData as ab, SessionsApi as ac, type Subject as ad, type SubjectAssurance as ae, type SubjectDeletedEventData as af, type SubjectEnrolledEventData as ag, type SubjectIdNumber as ah, type SubjectName as ai, type SubjectReferenceSource as aj, type SubjectReuseDocument as ak, type SubjectReuseTarget as al, type SubjectSession as am, type SubjectSessionInput as an, type SubjectSessionTarget as ao, type SubjectStatus as ap, type SubjectSuspiciousActivityEventData as aq, type SubjectUpdatedEventData as ar, SubjectsApi as as, type SuppliedIdentityRecord as at, type UsageThresholdReachedEventData as au, type VerifiedContacts as av, type WebhookEnvelopeOf as aw, type WebhookEventDataMap as ax, 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 ResultCheckProofs as i, type ResultDuplicate as j, type AgeResult as k, type CameraUnavailableCause as l, type CheckState as m, type CheckType as n, type CreateSessionInput as o, type CreatedSessionWarning as p, DEFAULT_TIMEOUT_MS as q, type DecisionReason as r, type DeepPartial as s, type DeletedSubject as t, type DeliverOptions as u, type DocumentSubstitutionSettings as v, type EligibilityReason as w, type FlowOverridableSettings as x, type FlowOverrides as y, type FlowServiceSettings as z };