@sekyro/node 0.1.0-rc.7 → 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 +17 -0
- package/README.md +97 -29
- package/dist/{client-DUMp_I-1.d.cts → client-BYoo67F-.d.cts} +210 -41
- package/dist/{client-DUMp_I-1.d.ts → client-BYoo67F-.d.ts} +210 -41
- package/dist/connect/express/index.d.cts +2 -2
- package/dist/connect/express/index.d.ts +2 -2
- package/dist/connect/index.d.cts +2 -2
- package/dist/connect/index.d.ts +2 -2
- package/dist/connect/next/index.d.cts +2 -2
- package/dist/connect/next/index.d.ts +2 -2
- package/dist/{connector-CMHuC-CU.d.ts → connector-B2vbywn2.d.ts} +1 -1
- package/dist/{connector-D1bhSLBl.d.cts → connector-Bo0P3ytq.d.cts} +1 -1
- package/dist/index.cjs +1 -1
- package/dist/index.d.cts +64 -20
- package/dist/index.d.ts +64 -20
- package/dist/index.js +1 -1
- package/package.json +1 -1
- package/sbom.cdx.json +7 -7
package/CHANGELOG.md
CHANGED
|
@@ -1,5 +1,22 @@
|
|
|
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
|
+
|
|
13
|
+
## 0.1.0-rc.8
|
|
14
|
+
|
|
15
|
+
### Patch Changes
|
|
16
|
+
|
|
17
|
+
- 22acfcf: Adds the Age check (selfie) types: `AgeMethod` and `AgeResult`, `age` on sessions and on the `session.completed` and `session.failed` webhooks (with `estimate` and `sigma` only when the step's "Keep and show the estimated age" setting is on), `age` on `verifyResultToken` results from the `sekyro.age` claim (the threshold and the method, never the estimate), the `age_estimation` service and its `showEstimatedAge` setting, and the `underage_estimated` reason. Deploy this version before turning on the age check for your organization.
|
|
18
|
+
- 24a22a4: Adds the `usage.threshold_reached` webhook payload type, `UsageThresholdReachedEventData`: sent once when a usage, credit or spend threshold of your plan is reached (`kind`, and when they apply `unit`, `threshold`, `used`, `limit` and `period`).
|
|
19
|
+
|
|
3
20
|
## 0.1.0-rc.7
|
|
4
21
|
|
|
5
22
|
### Minor 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
|
-
// `
|
|
50
|
-
//
|
|
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
|
-
{
|
|
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
|
-
| `
|
|
85
|
-
| `
|
|
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
|
-
###
|
|
139
|
+
### Person data
|
|
140
|
+
|
|
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.
|
|
152
|
+
|
|
153
|
+
```ts
|
|
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
|
+
```
|
|
134
163
|
|
|
135
|
-
If
|
|
136
|
-
|
|
137
|
-
|
|
138
|
-
|
|
139
|
-
|
|
140
|
-
population registry, `registryFromAnrpts()` converts that answer locally into
|
|
141
|
-
the record shape:
|
|
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.
|
|
142
169
|
|
|
143
170
|
```ts
|
|
144
|
-
import {
|
|
171
|
+
import { subjectFromNationalRegistry } from "@sekyro/node";
|
|
145
172
|
|
|
146
|
-
const answer = await myRegistryClient.lookup(
|
|
173
|
+
const answer = await myRegistryClient.lookup(idNumber); // your call, your key
|
|
147
174
|
const receivedAt = new Date();
|
|
148
|
-
await sekyro.sessions.create({
|
|
149
|
-
|
|
150
|
-
|
|
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
|
-
|
|
155
|
-
|
|
156
|
-
`
|
|
157
|
-
|
|
158
|
-
`
|
|
159
|
-
|
|
160
|
-
|
|
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({
|
|
245
|
+
await sekyro.sessions.create({ subject: { idNumber } });
|
|
188
246
|
} catch (err) {
|
|
189
247
|
if (err instanceof SekyroApiError && err.retryable) {
|
|
190
|
-
// back off
|
|
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)
|
|
@@ -339,13 +397,23 @@ result.subjectId; // the person, when known
|
|
|
339
397
|
`expired`, `wrong_audience`, `wrong_issuer`, `wrong_env`,
|
|
340
398
|
`key_env_mismatch`, `jwks_unavailable` or `invalid_options`.
|
|
341
399
|
|
|
400
|
+
When the flow sets a minimum age, `result.age` is `{ over, method }` from the
|
|
401
|
+
`sekyro.age` claim: `over` is the flow's minimum age (never the person's age)
|
|
402
|
+
and `method` says how it was proved (`estimated` by the age check (selfie)
|
|
403
|
+
step, or `document`, `chip`, `registry`, `eid`). The token never carries the
|
|
404
|
+
estimated age; with the step's "Keep and show the estimated age" setting on,
|
|
405
|
+
`estimate` and `sigma` arrive on the session (`sekyro.sessions.get`) and the
|
|
406
|
+
`session.completed` / `session.failed` webhooks only. To carry the answer into
|
|
407
|
+
an identity provider, map it to the claims `sekyro_age_over` (`result.age.over`)
|
|
408
|
+
and `sekyro_age_method` (`result.age.method`).
|
|
409
|
+
|
|
342
410
|
## Connect
|
|
343
411
|
|
|
344
412
|
`@sekyro/node/connect` carries the Sekyro proof into your auth provider as one
|
|
345
413
|
small claim, `sekyro`, on the provider's user, and gates routes on it. A
|
|
346
414
|
provider package supplies the adapter that reads and writes the claim
|
|
347
415
|
(`@sekyro/connect-zitadel`, `@sekyro/connect-supabase`, `@sekyro/connect-clerk`,
|
|
348
|
-
`@sekyro/connect-auth0`, `@sekyro/connect-firebase`); any object with the
|
|
416
|
+
`@sekyro/connect-auth0`, `@sekyro/connect-firebase`, `@sekyro/connect-keycloak`); any object with the
|
|
349
417
|
`ProviderAdapter` shape works too. Nothing else to install: the subpaths ship
|
|
350
418
|
inside `@sekyro/node`.
|
|
351
419
|
|