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

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/dist/index.d.cts CHANGED
@@ -1,334 +1,288 @@
1
+ import { a as ServiceId, b as SessionSubjectInput, c as WebhookEnvelope, d as SekyroEnvironment, V as VerificationLevel, e as VerificationAssurance, f as SessionOutcome, g as VerificationUnit, h as SubjectReuseMode, R as ResultRisk, i as ResultCheckProofs, j as ResultDuplicate, A as AgeMethod, F as FetchLike } from './client-Hkxwn6ZA.cjs';
2
+ export { k as AgeResult, l as CameraUnavailableCause, m as CheckState, n as CheckType, o as ConnectorIdentity, p as CreateSessionInput, C as CreatedSession, q as CreatedSessionWarning, D as DEFAULT_BASE_URL, r as DEFAULT_TIMEOUT_MS, s as DecisionReason, t as DeepPartial, u as DeletedSubject, v as DeliverOptions, w as DocumentSubstitutionSettings, E as EidResult, x as EligibilityReason, y as FlowOverridableSettings, z as FlowOverrides, B as FlowServiceSettings, G as FlowSummary, I as IdNumberReason, H as IdentityMethod, J as LevelTarget, K as ListSessionsQuery, L as Locale, M as MatchReason, P as PolicyFailureReason, N as PortraitReportEntry, O as ProbeBindingReason, Q as ProbeQuality, T as ProfileDocumentType, U as RequestOptions, X as ResultTokenResponse, Y as RevokeSubjectInput, S as Sekyro, Z as SekyroOptions, _ as Session, $ as SessionDevice, a0 as SessionDeviceSignal, a1 as SessionEventData, a2 as SessionFailureReason, a3 as SessionFlowRef, a4 as SessionLifecycleEventData, a5 as SessionLinkInput, a6 as SessionNetwork, a7 as SessionNetworkEvent, a8 as SessionPortraitLink, a9 as SessionReviewDecidedEventData, aa as SessionStatus, ab as SessionStep, ac as SessionStepCompletedEventData, ad as SessionsApi, ae as Subject, af as SubjectAssurance, ag as SubjectDeletedEventData, ah as SubjectEnrolledEventData, ai as SubjectIdNumber, aj as SubjectName, ak as SubjectReferenceSource, al as SubjectReuseDocument, am as SubjectReuseTarget, an as SubjectSession, ao as SubjectSessionInput, ap as SubjectSessionTarget, aq as SubjectStatus, ar as SubjectSuspiciousActivityEventData, as as SubjectUpdatedEventData, at as SubjectsApi, au as SuppliedIdentityRecord, av as UsageThresholdReachedEventData, aw as VerifiedContacts, ax as WebhookEnvelopeOf, ay as WebhookEventDataMap, W as WebhookEventType } from './client-Hkxwn6ZA.cjs';
3
+
4
+ /** Why {@link verifyWebhook} rejected a delivery. @public */
5
+ type SekyroWebhookErrorCode = "invalid_signature" | "stale" | "malformed";
1
6
  /**
2
- * Wire-level enums and shapes of the Sekyro partner API (`/api/v2`). These
3
- * mirror the backend's frozen partner contract; they are plain string unions so
4
- * a newer API value never throws at runtime — it simply widens the type in the
5
- * next SDK release.
6
- *
7
- * @packageDocumentation
8
- */
9
- /** Session lifecycle status. @public */
10
- type SessionStatus = "created" | "in_progress" | "review_pending" | "completed" | "expired" | "failed";
11
- /**
12
- * Terminal verdict, orthogonal to {@link SessionStatus}. `null` until the session
13
- * reaches a terminal status; `review` when a human reviewer must adjudicate.
14
- * @public
15
- */
16
- type SessionOutcome = "approved" | "review" | "rejected";
17
- /** The verification checks a flow may contain. @public */
18
- type CheckType = "liveness" | "face_match" | "doc_ocr" | "population_registry" | "phone_otp";
19
- /** Per-check execution state within a session. @public */
20
- type CheckState = "pending" | "input_required" | "processing" | "passed" | "failed" | "review" | "skipped";
21
- /** Hosted-flow languages. @public */
22
- type Locale = "ar" | "fr" | "en";
23
- /** The environment a webhook was emitted from. @public */
24
- type SekyroEnvironment = "sandbox" | "live";
25
- /**
26
- * One check of a session, as the partner API projects it: enum/id fields only,
27
- * never civil data.
7
+ * Thrown by {@link verifyWebhook}. Respond with a 4xx and do not process the
8
+ * body; Sekyro AI retries deliveries that do not receive a 2xx.
28
9
  * @public
29
10
  */
30
- interface SessionStep {
31
- checkType: CheckType;
32
- state: CheckState;
33
- /** Machine-readable failure/review reason, when the check has one. */
34
- reason?: string;
35
- /** Calibrated model score in [0, 1] for scored checks (liveness, face match). */
36
- calibratedScore?: number;
11
+ declare class SekyroWebhookError extends Error {
12
+ readonly name = "SekyroWebhookError";
13
+ readonly code: SekyroWebhookErrorCode;
14
+ constructor(code: SekyroWebhookErrorCode, message?: string);
37
15
  }
38
16
  /**
39
- * Input of {@link SessionsApi.create}. Name the recipe by EITHER `flow` (the
40
- * flow slug) OR `templateId` — exactly one; the API rejects both or neither.
17
+ * Why {@link verifyResultToken} rejected a result token:
18
+ * - `invalid_token`: not a JWT, a bad signature, an unknown key, or no `sekyro` claim;
19
+ * - `expired`: past its `exp` (tokens live 10 minutes; fetch a fresh one with
20
+ * {@link SessionsApi.resultToken});
21
+ * - `wrong_audience`: issued for another app;
22
+ * - `wrong_issuer`: not issued by the expected issuer;
23
+ * - `wrong_env`: a sandbox token when you asked for live, or the reverse;
24
+ * - `key_env_mismatch`: the environment claim does not match the key that signed it;
25
+ * - `jwks_unavailable`: the public key set could not be fetched;
26
+ * - `invalid_options`: a missing `appId` or an unsafe `jwksUrl`.
41
27
  * @public
42
28
  */
43
- interface CreateSessionInput {
44
- /** Flow slug configured for your organisation. */
45
- flow?: string;
46
- /** Legacy template id (pre-flows path). Prefer `flow`. */
47
- templateId?: string;
48
- /** Pins the hosted-flow language. Omit to let the person's device decide. */
49
- locale?: Locale;
50
- /**
51
- * Step inputs consumed server-side. The known anchors are typed (all
52
- * strings — an `nni` is a 10-digit string, never a number); further keys
53
- * pass through to the API as-is. `nni` binds the session to that identity:
54
- * the hosted flow may omit it but cannot substitute another.
55
- */
56
- input?: {
57
- /** 10-digit Mauritanian NNI, as a string. */
58
- nni?: string;
59
- /** E.164 phone number, e.g. `+22236123456`. */
60
- phone?: string;
61
- fullName?: string;
62
- /** ISO 8601 date (`YYYY-MM-DD`). */
63
- birthDate?: string;
64
- } & Record<string, unknown>;
65
- }
66
- /** Per-request options. @public */
67
- interface RequestOptions {
68
- /**
69
- * Sent as `X-Idempotency-Key`. Replaying the same key within 24 h returns the
70
- * original response instead of creating a second session.
71
- */
72
- idempotencyKey?: string;
73
- }
29
+ type SekyroResultTokenErrorCode = "invalid_token" | "expired" | "wrong_audience" | "wrong_issuer" | "wrong_env" | "key_env_mismatch" | "jwks_unavailable" | "invalid_options";
74
30
  /**
75
- * Result of {@link SessionsApi.create}. `clientToken` is returned ONCE and never
76
- * again — hand it to the browser (`@sekyro/web`) and do not persist it.
31
+ * Thrown by {@link verifyResultToken}. Do not use the token's content.
77
32
  * @public
78
33
  */
79
- interface CreatedSession {
80
- id: string;
81
- status: SessionStatus;
82
- /** One-time credential for the client SDK / hosted flow. */
83
- clientToken: string;
84
- /** Hosted verification link for this session. */
85
- hostedUrl: string;
86
- steps: SessionStep[];
87
- /** ISO 8601 — when the session (and its link) stop accepting input. */
88
- expiresAt: string;
34
+ declare class SekyroResultTokenError extends Error {
35
+ readonly name = "SekyroResultTokenError";
36
+ readonly code: SekyroResultTokenErrorCode;
37
+ constructor(code: SekyroResultTokenErrorCode, message?: string, cause?: unknown);
89
38
  }
39
+ /** Why the {@link Sekyro} constructor rejected its options. @public */
40
+ type SekyroConfigErrorCode = "missing_api_key" | "invalid_base_url" | "invalid_registry_record" | "registry_country_unsupported" | "registry_nationality_unmapped";
90
41
  /**
91
- * The whitelisted session view returned by {@link SessionsApi.get}. Never
92
- * contains the client token.
42
+ * Thrown synchronously by `new Sekyro(...)` for an unusable configuration, and by
43
+ * {@link subjectFromNationalRegistry} for an unusable registry answer:
44
+ * before any request is made. Extends `TypeError` so existing
45
+ * `instanceof TypeError` guards keep working.
93
46
  * @public
94
47
  */
95
- interface Session {
96
- id: string;
97
- status: SessionStatus;
98
- outcome: SessionOutcome | null;
99
- steps: SessionStep[];
100
- /** ISO 8601. */
101
- expiresAt: string;
102
- /** ISO 8601. */
103
- createdAt: string;
48
+ declare class SekyroConfigError extends TypeError {
49
+ readonly name = "SekyroConfigError";
50
+ readonly code: SekyroConfigErrorCode;
51
+ constructor(code: SekyroConfigErrorCode, message?: string);
104
52
  }
105
53
  /**
106
- * `data` of the terminal / review-pending session lifecycle events
107
- * (`session.completed` | `session.failed` | `session.review_pending` |
108
- * `session.expired` | `session.rejected`) — ids and enums only, no civil data,
109
- * scores or links. `outcome` and `steps` travel on `completed` / `failed`;
110
- * `review_pending` carries `steps` without an outcome; `expired` carries the
111
- * status alone.
54
+ * The flow codes of the partner API (Sekyro flows). Each carries
55
+ * {@link SekyroApiError.details} (see {@link SekyroFlowErrorDetailsMap} and
56
+ * {@link isFlowError}). On `sessions.create`:
57
+ * - `flow_not_found` (404): no flow with this slug or `flw_` id in the key's app;
58
+ * - `flow_not_published` (409): the flow has no published version yet;
59
+ * - `flow_archived` (409): the flow is archived;
60
+ * - `override_invalid` (400): an unknown key or value in `overrides`, or a
61
+ * result that is not a valid flow;
62
+ * - `override_widens_flow` (403): the override makes the flow less strict
63
+ * (e.g. a service turned `'off'`) and the flow does not allow widening;
64
+ * - `reuse_disabled` (409): `subject.reuse` on a flow whose returning-user
65
+ * sessions are turned off.
66
+ *
67
+ * On `sessions.selectMethod` (a flow session's identity-method choice):
68
+ * `choice_not_found` (409: the session's flow has no identity-method choice),
69
+ * `choice_locked` (409: it can no longer change) and
70
+ * `choice_option_unavailable` (409: that method is not offered).
112
71
  * @public
113
72
  */
114
- interface SessionLifecycleEventData {
115
- sessionId: string;
116
- status: SessionStatus;
117
- outcome?: SessionOutcome | null;
118
- steps?: Array<Pick<SessionStep, "checkType" | "state">>;
119
- /** Machine-readable reason, when the transition has one. */
120
- reason?: string;
121
- }
73
+ type SekyroFlowErrorCode = "flow_not_found" | "flow_not_published" | "flow_archived" | "override_invalid" | "override_widens_flow" | "reuse_disabled" | "choice_not_found" | "choice_locked" | "choice_option_unavailable";
122
74
  /**
123
- * `data` of `session.step.completed` — the check that just passed.
75
+ * One machine-readable issue of a flow error. Never carries a value you sent.
124
76
  * @public
125
77
  */
126
- interface SessionStepCompletedEventData {
127
- sessionId: string;
128
- checkType: CheckType;
129
- state: CheckState;
78
+ interface FlowErrorIssue {
79
+ /**
80
+ * A flow validation code (e.g. `face_match_needs_liveness`), `schema_invalid`,
81
+ * `schema_unknown_field`, `field_widens_flow`, or the error's own code.
82
+ */
83
+ code: string;
84
+ /** A short plain English sentence. */
85
+ message: string;
86
+ /** The field of your request body, e.g. `overrides.services.liveness.attempts`, `flow`, `subject.reuse`. */
87
+ path?: string;
88
+ /** A node of your app's flow. */
89
+ nodeId?: string;
90
+ /** The service of that node (or of the `overrides.services` key). */
91
+ service?: ServiceId;
92
+ /** `override_widens_flow`: the widened field, e.g. `settings.eligibility.minAge`, `services.nfc`. */
93
+ field?: string;
130
94
  }
131
- /**
132
- * `data` of `session.review_decided` — a human (or the review-timeout sweep)
133
- * decided a pending review. `outcome` speaks the REVIEW vocabulary
134
- * (`pass` | `fail`), not the session outcome; `reason` is the reviewer's code
135
- * (e.g. `review_timeout` for an expired review).
136
- * @public
137
- */
138
- interface SessionReviewDecidedEventData {
139
- sessionId: string;
140
- outcome: "pass" | "fail";
141
- reason: string;
95
+ /** `details` common to every flow error: at least one issue. @public */
96
+ interface FlowErrorDetails {
97
+ issues: FlowErrorIssue[];
142
98
  }
143
- /**
144
- * Event type → the shape of its `data`. Session events are typed; the
145
- * remaining events carry an open record until their payloads are frozen.
146
- * @public
147
- */
148
- interface WebhookEventDataMap {
149
- "session.created": Record<string, unknown>;
150
- "session.started": Record<string, unknown>;
151
- "session.step.completed": SessionStepCompletedEventData;
152
- "session.review_pending": SessionLifecycleEventData;
153
- "session.review_decided": SessionReviewDecidedEventData;
154
- "session.completed": SessionLifecycleEventData;
155
- "session.rejected": SessionLifecycleEventData;
156
- "session.expired": SessionLifecycleEventData;
157
- "session.failed": SessionLifecycleEventData;
158
- "subject.enrolled": Record<string, unknown>;
159
- "subject.deleted": Record<string, unknown>;
160
- "aml.match_flagged": Record<string, unknown>;
161
- "payment.received": Record<string, unknown>;
162
- "invoice.generated": Record<string, unknown>;
163
- "invoice.paid": Record<string, unknown>;
164
- "invoice.overdue": Record<string, unknown>;
165
- "webhook.test": Record<string, unknown>;
99
+ /** `details` of `override_widens_flow`: the widened fields, plus one `field_widens_flow` issue each. @public */
100
+ interface FlowWidensErrorDetails extends FlowErrorDetails {
101
+ fields: string[];
102
+ }
103
+ /** `details` of `flow_not_published`, `flow_archived` and `reuse_disabled`: the flow concerned. @public */
104
+ interface FlowRefErrorDetails extends FlowErrorDetails {
105
+ flow: {
106
+ id: string;
107
+ slug: string;
108
+ };
166
109
  }
167
- /** Every event a partner endpoint may receive. @public */
168
- type WebhookEventType = keyof WebhookEventDataMap;
169
110
  /**
170
- * The signed webhook payload for ONE event type. There is no global API
171
- * version; each event carries its own per-event `version`. Retried deliveries
172
- * keep the same `id` — de-duplicate on it.
111
+ * {@link SekyroFlowErrorCode} → the shape of its {@link SekyroApiError.details}.
173
112
  * @public
174
113
  */
175
- interface WebhookEnvelopeOf<E extends WebhookEventType> {
176
- /** UUIDv7, stable across delivery retries. */
177
- id: string;
178
- event: E;
179
- /** Per-event payload version. */
180
- version: number;
181
- /** ISO 8601. */
182
- createdAt: string;
183
- orgId: string;
184
- env: SekyroEnvironment;
185
- data: WebhookEventDataMap[E];
114
+ interface SekyroFlowErrorDetailsMap {
115
+ flow_not_found: FlowErrorDetails;
116
+ flow_not_published: FlowRefErrorDetails;
117
+ flow_archived: FlowRefErrorDetails;
118
+ override_invalid: FlowErrorDetails;
119
+ override_widens_flow: FlowWidensErrorDetails;
120
+ reuse_disabled: FlowRefErrorDetails;
121
+ choice_not_found: FlowErrorDetails;
122
+ choice_locked: FlowErrorDetails;
123
+ choice_option_unavailable: FlowErrorDetails;
186
124
  }
187
125
  /**
188
- * The signed webhook payload, discriminated on `event`: narrowing on
189
- * `envelope.event` narrows `envelope.data` to that event's shape.
190
- *
191
- * @example
192
- * ```ts
193
- * const envelope = verifyWebhook(rawBody, header, secret);
194
- * switch (envelope.event) {
195
- * case "session.completed":
196
- * envelope.data.outcome; // SessionOutcome | null | undefined
197
- * break;
198
- * case "session.review_decided":
199
- * envelope.data.outcome; // "pass" | "fail"
200
- * break;
201
- * }
202
- * ```
126
+ * A {@link SekyroApiError} narrowed by {@link isFlowError}: `code` is a flow
127
+ * code and `details` has that code's shape.
203
128
  * @public
204
129
  */
205
- type WebhookEnvelope<E extends WebhookEventType = WebhookEventType> = E extends WebhookEventType ? WebhookEnvelopeOf<E> : never;
130
+ type SekyroFlowError<C extends SekyroFlowErrorCode = SekyroFlowErrorCode> = C extends SekyroFlowErrorCode ? SekyroApiError & {
131
+ readonly code: C;
132
+ readonly details: SekyroFlowErrorDetailsMap[C];
133
+ } : never;
206
134
  /**
207
- * `data` of any `session.*` event.
208
- * @deprecated Use {@link SessionLifecycleEventData}, {@link SessionStepCompletedEventData}
209
- * or {@link SessionReviewDecidedEventData}, or narrow a {@link WebhookEnvelope} on `event`.
135
+ * {@link SekyroApiError.code}: an SDK code, a documented flow code, or any
136
+ * other API code (the union stays open so a new API code never breaks a build).
210
137
  * @public
211
138
  */
212
- type SessionEventData = SessionLifecycleEventData | SessionStepCompletedEventData | SessionReviewDecidedEventData;
213
-
214
- /** Default partner API origin + version prefix. @public */
215
- declare const DEFAULT_BASE_URL = "https://api.sekyro.ai/api/v2";
216
- /** Default per-request timeout. @public */
217
- declare const DEFAULT_TIMEOUT_MS = 30000;
218
- /** `fetch`-compatible function; the global `fetch` by default. @public */
219
- type FetchLike = typeof globalThis.fetch;
220
- /** Constructor options of {@link Sekyro}. @public */
221
- interface SekyroOptions {
222
- /** Partner API key (server-side only). Sent as `Authorization: Bearer`. */
223
- apiKey: string;
224
- /** API base URL incl. the `/api/v2` prefix. Default {@link DEFAULT_BASE_URL}. */
225
- baseUrl?: string;
226
- /** Per-request timeout in ms. Default {@link DEFAULT_TIMEOUT_MS}. */
227
- timeoutMs?: number;
228
- /** Custom `fetch` (tests, proxies, custom agents). Default `globalThis.fetch`. */
229
- fetch?: FetchLike;
139
+ type SekyroApiErrorCode = SekyroClientErrorCode | SekyroFlowErrorCode | (string & {});
140
+ /** Constructor input of {@link SekyroApiError}. @public */
141
+ interface SekyroApiErrorInit {
142
+ /** HTTP status; `0` when no response was received (network / timeout). */
143
+ status: number;
144
+ /** API error code, or `network` | `timeout` | `http_error` | `malformed_response`. */
145
+ code: SekyroApiErrorCode;
146
+ message: string;
147
+ /** The API's `request_id`, when the response carried one. */
148
+ requestId?: string;
149
+ /** The API's `error.details`, when the response carried them (the flow codes: {@link SekyroFlowErrorDetailsMap}). */
150
+ details?: unknown;
151
+ /** Underlying error (network failures, abort reasons, JSON parse errors). */
152
+ cause?: unknown;
153
+ /** Seconds to wait before retrying, from the response's `Retry-After` header. */
154
+ retryAfterSeconds?: number;
230
155
  }
156
+ /** Error codes the SDK itself produces (as opposed to codes from the API). @public */
157
+ type SekyroClientErrorCode = "network" | "timeout" | "http_error" | "malformed_response";
231
158
  /**
232
- * `sekyro.sessions` — create and read verification sessions.
159
+ * Any failed call through {@link Sekyro}: a non-2xx partner envelope
160
+ * `{ status: 'error', error: { code, message, request_id } }`, a non-JSON
161
+ * response, a network failure or a timeout.
233
162
  *
234
- * Exported as a TYPE only (`import type { SessionsApi }`): the class value is
235
- * not part of the package surface, so it can only be obtained through
236
- * {@link Sekyro.sessions} — never constructed by hand with an unchecked
237
- * transport.
163
+ * `retryable` is `true` for `network`, `timeout`, HTTP 429, HTTP 5xx and the
164
+ * `idempotency_in_progress` code — retry with the SAME idempotency key.
238
165
  * @public
239
166
  */
240
- declare class SessionsApi {
241
- private readonly call;
167
+ declare class SekyroApiError extends Error {
168
+ readonly name = "SekyroApiError";
169
+ readonly status: number;
170
+ readonly code: SekyroApiErrorCode;
171
+ readonly requestId: string | undefined;
242
172
  /**
243
- * Constructed by {@link Sekyro}; the transport is kept out of the public
244
- * surface on purpose (only its bound `call` crosses this boundary).
245
- * @internal
173
+ * The API's `error.details`, when the response carried them; `undefined`
174
+ * otherwise. Untyped here: narrow with {@link isFlowError} to read a flow
175
+ * code's documented shape ({@link SekyroFlowErrorDetailsMap}).
246
176
  */
247
- constructor(call: <T>(method: "GET" | "POST", path: string, body?: unknown, idempotencyKey?: string) => Promise<T>);
177
+ readonly details: unknown;
178
+ readonly retryable: boolean;
248
179
  /**
249
- * `POST /sessions`. Returns the one-time `clientToken` — hand it to the
250
- * browser, never persist it. Pass an `idempotencyKey` so a retried call
251
- * cannot create a second session.
180
+ * Seconds to wait before retrying, from the response's `Retry-After` header
181
+ * (a number of seconds, or an HTTP date rounded up to whole seconds from now).
182
+ * `undefined` when the response had no usable header.
252
183
  */
253
- create(input: CreateSessionInput, opts?: RequestOptions): Promise<CreatedSession>;
254
- /** `GET /sessions/:id` — the whitelisted view (no client token). */
255
- get(id: string): Promise<Session>;
184
+ readonly retryAfterSeconds: number | undefined;
185
+ constructor(init: SekyroApiErrorInit);
256
186
  }
257
187
  /**
258
- * Sekyro partner API client. Server-side only: it carries your API key.
259
- *
260
- * Throws {@link SekyroConfigError} synchronously when `apiKey` is missing or
261
- * `baseUrl` is not `https:` (plain `http:` is accepted for `localhost`,
262
- * `127.0.0.1` and `[::1]` only).
188
+ * Narrow an error to a flow error, optionally to given codes: `true` only for
189
+ * a {@link SekyroApiError} with a flow code whose `details` have that code's
190
+ * documented shape, so `err.details` is typed after the check. An error whose
191
+ * `details` are missing or unexpected is not narrowed (read `err.code`).
263
192
  *
264
193
  * @example
265
194
  * ```ts
266
- * const sekyro = new Sekyro({ apiKey: process.env.SEKYRO_API_KEY! });
267
- * const { id, clientToken } = await sekyro.sessions.create({ flow: "onboarding" });
195
+ * try {
196
+ * await sekyro.sessions.create({ flow, overrides });
197
+ * } catch (err) {
198
+ * if (isFlowError(err, "override_widens_flow")) err.details.fields; // string[]
199
+ * else if (isFlowError(err)) err.details.issues.map((i) => i.path);
200
+ * }
268
201
  * ```
269
202
  * @public
270
203
  */
271
- declare class Sekyro {
272
- readonly sessions: SessionsApi;
273
- constructor(opts: SekyroOptions);
274
- }
204
+ declare function isFlowError<C extends SekyroFlowErrorCode = SekyroFlowErrorCode>(err: unknown, ...codes: C[]): err is SekyroFlowError<C>;
275
205
 
276
- /** Why {@link verifyWebhook} rejected a delivery. @public */
277
- type SekyroWebhookErrorCode = "invalid_signature" | "stale" | "malformed";
278
206
  /**
279
- * Thrown by {@link verifyWebhook}. Respond with a 4xx and do not process the
280
- * body; Sekyro retries deliveries that do not receive a 2xx.
207
+ * The raw ANRPTS `getPersonne` answer your server received with your own
208
+ * access: `{ personne, photo }`, where `photo` is a base64 JPEG (optionally
209
+ * data-URL prefixed). Only the fields the mapping reads are typed.
281
210
  * @public
282
211
  */
283
- declare class SekyroWebhookError extends Error {
284
- readonly name = "SekyroWebhookError";
285
- readonly code: SekyroWebhookErrorCode;
286
- constructor(code: SekyroWebhookErrorCode, message?: string);
212
+ interface AnrptsPersonneResponse {
213
+ personne?: {
214
+ nni?: string | undefined;
215
+ prenomFr?: string | undefined;
216
+ patronymeFr?: string | undefined;
217
+ perePrenomFr?: string | undefined;
218
+ prenomAr?: string | undefined;
219
+ patronymeAr?: string | undefined;
220
+ perePrenomAr?: string | undefined;
221
+ /** ISO date or date-time (`1990-01-01T00:00:00.000Z`), or `DD/MM/YYYY`. */
222
+ dateNaissance?: string | undefined;
223
+ lieuNaissanceFr?: string | undefined;
224
+ lieuNaissanceAr?: string | undefined;
225
+ sexeCode?: string | undefined;
226
+ nationalities?: string[] | undefined;
227
+ [key: string]: unknown;
228
+ };
229
+ photo?: string | undefined;
230
+ datePhoto?: string | undefined;
231
+ [key: string]: unknown;
287
232
  }
288
- /** Why the {@link Sekyro} constructor rejected its options. @public */
289
- type SekyroConfigErrorCode = "missing_api_key" | "invalid_base_url";
290
233
  /**
291
- * Thrown synchronously by `new Sekyro(...)` for an unusable configuration —
292
- * before any request is made. Extends `TypeError` so existing
293
- * `instanceof TypeError` guards keep working.
234
+ * Registry answer formats Sekyro AI can map, by ISO 3166-1 alpha-2 country.
294
235
  * @public
295
236
  */
296
- declare class SekyroConfigError extends TypeError {
297
- readonly name = "SekyroConfigError";
298
- readonly code: SekyroConfigErrorCode;
299
- constructor(code: SekyroConfigErrorCode, message?: string);
237
+ interface NationalRegistryResponses {
238
+ /** Mauritania: the ANRPTS `getPersonne` answer `{ personne, photo, datePhoto? }`. */
239
+ MR: AnrptsPersonneResponse;
300
240
  }
301
- /** Constructor input of {@link SekyroApiError}. @public */
302
- interface SekyroApiErrorInit {
303
- /** HTTP status; `0` when no response was received (network / timeout). */
304
- status: number;
305
- /** API error code, or `network` | `timeout` | `http_error` | `malformed_response`. */
306
- code: string;
307
- message: string;
308
- /** The API's `request_id`, when the response carried one. */
309
- requestId?: string;
310
- /** Underlying error (network failures, abort reasons, JSON parse errors). */
311
- cause?: unknown;
241
+ /** A country {@link subjectFromNationalRegistry} can map. @public */
242
+ type NationalRegistryCountry = keyof NationalRegistryResponses;
243
+ /** Options of {@link subjectFromNationalRegistry}. @public */
244
+ interface SubjectFromRegistryOptions {
245
+ /**
246
+ * When YOUR system received this answer (not "now" when you map a cached
247
+ * answer). Required: records older than 24 h are refused at session create.
248
+ */
249
+ fetchedAt: Date | string;
250
+ /**
251
+ * The person's nationality (ISO 3166-1 alpha-2) when you map the registry's
252
+ * nationality text yourself; it replaces the SDK's mapping. Needed when the answer
253
+ * states a nationality the SDK cannot map (`registry_nationality_unmapped`).
254
+ */
255
+ nationality?: string;
312
256
  }
313
- /** Error codes the SDK itself produces (as opposed to codes from the API). @public */
314
- type SekyroClientErrorCode = "network" | "timeout" | "http_error" | "malformed_response";
315
257
  /**
316
- * Any failed call through {@link Sekyro}: a non-2xx partner envelope
317
- * `{ status: 'error', error: { code, message, request_id } }`, a non-JSON
318
- * response, a network failure or a timeout.
258
+ * The `subject` keys of a reference record, ready to spread into
259
+ * `sessions.create({ subject })`.
260
+ * @public
261
+ */
262
+ type SubjectRecord = Required<Pick<SessionSubjectInput, "idNumber" | "birthDate" | "photo" | "fetchedAt">> & Pick<SessionSubjectInput, "fullName" | "names" | "birthPlace" | "sex" | "nationality" | "photoDate">;
263
+ /**
264
+ * Convert a national registry answer that YOUR server already received, with
265
+ * your own access, into the `subject` reference keys of `sessions.create`. A
266
+ * pure, local mapping: it makes no network call, and Sekyro AI never sees,
267
+ * receives or stores any registry key, only the record and photo you pass.
319
268
  *
320
- * `retryable` is `true` for `network`, `timeout`, HTTP 429, HTTP 5xx and the
321
- * `idempotency_in_progress` code — retry with the SAME idempotency key.
269
+ * ```ts
270
+ * const answer = await myRegistryClient.lookup(number); // your call, your key
271
+ * await sekyro.sessions.create({
272
+ * subject: { externalRef, ...subjectFromNationalRegistry("MR", answer, { fetchedAt: receivedAt }) },
273
+ * });
274
+ * ```
275
+ *
276
+ * Throws {@link SekyroConfigError}: `invalid_registry_record` when a required
277
+ * field (the number, a given and family name in at least one script, the birth
278
+ * date, the photo) is missing or `fetchedAt` is not a date (the message names
279
+ * the field, never its value); `registry_country_unsupported` for a country
280
+ * without an adapter; `registry_nationality_unmapped` when the answer states a
281
+ * nationality and none of its values maps to an ISO code (map it yourself and pass
282
+ * `options.nationality`; the message never carries the value).
322
283
  * @public
323
284
  */
324
- declare class SekyroApiError extends Error {
325
- readonly name = "SekyroApiError";
326
- readonly status: number;
327
- readonly code: string;
328
- readonly requestId: string | undefined;
329
- readonly retryable: boolean;
330
- constructor(init: SekyroApiErrorInit);
331
- }
285
+ declare function subjectFromNationalRegistry<C extends NationalRegistryCountry>(country: C, response: NationalRegistryResponses[C], options: SubjectFromRegistryOptions): SubjectRecord;
332
286
 
333
287
  /**
334
288
  * The HTTP header carrying the webhook signature:
@@ -337,7 +291,7 @@ declare class SekyroApiError extends Error {
337
291
  */
338
292
  declare const SEKYRO_SIGNATURE_HEADER = "x-sekyro-signature";
339
293
  /**
340
- * The pre-rebrand name of the signature header. Sekyro sends BOTH headers with
294
+ * The pre-rebrand name of the signature header. Sekyro AI sends BOTH headers with
341
295
  * the same value during the transition; prefer {@link SEKYRO_SIGNATURE_HEADER}
342
296
  * and use {@link signatureFromHeaders} to accept either.
343
297
  * @public
@@ -365,13 +319,13 @@ interface VerifyWebhookOptions {
365
319
  now?: () => number;
366
320
  }
367
321
  /**
368
- * Verify a Sekyro webhook delivery and return its parsed envelope, discriminated
322
+ * Verify a Sekyro AI webhook delivery and return its parsed envelope, discriminated
369
323
  * on `event` (narrow with a `switch` to type `data`).
370
324
  *
371
325
  * - `rawBody` MUST be the request body exactly as received (before any JSON
372
326
  * parsing / re-serialisation); the signature covers those bytes.
373
327
  * - Accepts the delivery when ANY `v1` in the header matches, which is what
374
- * makes secret rotation seamless (Sekyro signs with current + previous).
328
+ * makes secret rotation seamless (Sekyro AI signs with current + previous).
375
329
  * - Uses `node:crypto` only; the digest compare is constant-time.
376
330
  *
377
331
  * Checks run in this order: header/secret present → header well-formed →
@@ -386,4 +340,94 @@ interface VerifyWebhookOptions {
386
340
  */
387
341
  declare function verifyWebhook(rawBody: string, header: string | null | undefined, secret: string, opts?: VerifyWebhookOptions): WebhookEnvelope;
388
342
 
389
- export { type CheckState, type CheckType, type CreateSessionInput, type CreatedSession, DEFAULT_BASE_URL, DEFAULT_TIMEOUT_MS, type FetchLike, LEGACY_SIGNATURE_HEADER, type Locale, type RequestOptions, SEKYRO_SIGNATURE_HEADER, Sekyro, SekyroApiError, type SekyroApiErrorInit, type SekyroClientErrorCode, SekyroConfigError, type SekyroConfigErrorCode, type SekyroEnvironment, type SekyroOptions, SekyroWebhookError, type SekyroWebhookErrorCode, type Session, type SessionEventData, type SessionLifecycleEventData, type SessionOutcome, type SessionReviewDecidedEventData, type SessionStatus, type SessionStep, type SessionStepCompletedEventData, SessionsApi, type VerifyWebhookOptions, type WebhookEnvelope, type WebhookEnvelopeOf, type WebhookEventDataMap, type WebhookEventType, signatureFromHeaders, verifyWebhook };
343
+ /** Issuer of production result tokens. @public */
344
+ declare const DEFAULT_RESULT_TOKEN_ISSUER = "https://api.sekyro.ai";
345
+ /** Path of the public key set under the issuer origin. @public */
346
+ declare const RESULT_TOKEN_JWKS_PATH = "/.well-known/sekyro/jwks.json";
347
+ /** Options of {@link verifyResultToken}. @public */
348
+ interface VerifyResultTokenOptions {
349
+ /**
350
+ * Your app id, or every app id this server accepts. The token's `aud` must
351
+ * be one of them; {@link VerifiedResult.appId} says which.
352
+ */
353
+ appId: string | string[];
354
+ /** Expected `iss`. Default {@link DEFAULT_RESULT_TOKEN_ISSUER}. */
355
+ issuer?: string;
356
+ /** Key set URL. Default `${issuer}/.well-known/sekyro/jwks.json`. Must be `https:` (plain `http:` only on a loopback host). */
357
+ jwksUrl?: string;
358
+ /**
359
+ * The environment you accept. A sandbox token is refused when you ask for
360
+ * `live`, and the reverse. Omit to accept both and read {@link VerifiedResult.env}.
361
+ */
362
+ env?: SekyroEnvironment;
363
+ /** Custom `fetch` for the key set (tests, proxies). Default `globalThis.fetch`. */
364
+ fetch?: FetchLike;
365
+ /** Clock returning epoch milliseconds. Default `Date.now`. */
366
+ now?: () => number;
367
+ /** Allowed clock skew in seconds for `exp` / `iat`. Default 30. */
368
+ clockToleranceSec?: number;
369
+ }
370
+ /**
371
+ * The verified content of a result token, in camelCase.
372
+ * @public
373
+ */
374
+ interface VerifiedResult {
375
+ sessionId: string;
376
+ orgId: string;
377
+ /** The app id the token was issued for (its `aud`), one of {@link VerifyResultTokenOptions.appId}. */
378
+ appId: string;
379
+ /** The subject (person) the session is linked to (`sub`), once that subject has passed a verification (absent before that). */
380
+ subjectId?: string;
381
+ /** Your own id for the person, from `subject.externalRef` at create. */
382
+ externalRef?: string;
383
+ env: SekyroEnvironment;
384
+ level: VerificationLevel | null;
385
+ assurance: VerificationAssurance | null;
386
+ outcome: SessionOutcome | null;
387
+ unit: VerificationUnit | null;
388
+ /** ISO 8601: when the session reached its terminal state. */
389
+ verifiedAt: string;
390
+ /** The flow version the session ran. */
391
+ flow?: {
392
+ slug: string;
393
+ version: number;
394
+ };
395
+ /** `recheck` or `step_up` on a session created for an existing subject; absent otherwise. */
396
+ reuseMode?: SubjectReuseMode;
397
+ risk?: ResultRisk;
398
+ checks?: ResultCheckProofs;
399
+ duplicates?: ResultDuplicate[];
400
+ /**
401
+ * The `sekyro.age` claim, when the flow sets a minimum age and the session
402
+ * proved it: `over` is the flow's minimum age, `method` how it was proved.
403
+ * The token never carries the estimated age.
404
+ */
405
+ age?: {
406
+ over: number;
407
+ method: AgeMethod;
408
+ };
409
+ }
410
+ /**
411
+ * Verify a Sekyro AI result token (the `resultToken` of a terminal webhook,
412
+ * or {@link SessionsApi.resultToken}) and return its content.
413
+ *
414
+ * Checks the ES256 signature against the public key set (fetched from
415
+ * `${issuer}/.well-known/sekyro/jwks.json` and cached for 10 minutes; an
416
+ * unknown key id fetches it again), the issuer, the audience (your app id),
417
+ * the expiry, and that the environment claim matches the key that signed it
418
+ * (sandbox keys have ids starting `sbx-`). Throws
419
+ * {@link SekyroResultTokenError} otherwise; never trust the token's content
420
+ * before this resolves.
421
+ *
422
+ * @example
423
+ * ```ts
424
+ * const result = await verifyResultToken(token, { appId: process.env.SEKYRO_APP_ID!, env: "live" });
425
+ * if (result.outcome === "approved" && (result.level ?? 0) >= 1) {
426
+ * // a verified real person
427
+ * }
428
+ * ```
429
+ * @public
430
+ */
431
+ declare function verifyResultToken(token: string, opts: VerifyResultTokenOptions): Promise<VerifiedResult>;
432
+
433
+ export { AgeMethod, type AnrptsPersonneResponse, DEFAULT_RESULT_TOKEN_ISSUER, FetchLike, type FlowErrorDetails, type FlowErrorIssue, type FlowRefErrorDetails, type FlowWidensErrorDetails, LEGACY_SIGNATURE_HEADER, type NationalRegistryCountry, type NationalRegistryResponses, RESULT_TOKEN_JWKS_PATH, ResultCheckProofs, ResultDuplicate, ResultRisk, SEKYRO_SIGNATURE_HEADER, SekyroApiError, type SekyroApiErrorCode, type SekyroApiErrorInit, type SekyroClientErrorCode, SekyroConfigError, type SekyroConfigErrorCode, SekyroEnvironment, type SekyroFlowError, type SekyroFlowErrorCode, type SekyroFlowErrorDetailsMap, SekyroResultTokenError, type SekyroResultTokenErrorCode, SekyroWebhookError, type SekyroWebhookErrorCode, ServiceId, SessionOutcome, SessionSubjectInput, type SubjectFromRegistryOptions, type SubjectRecord, SubjectReuseMode, VerificationAssurance, VerificationLevel, VerificationUnit, type VerifiedResult, type VerifyResultTokenOptions, type VerifyWebhookOptions, WebhookEnvelope, isFlowError, signatureFromHeaders, subjectFromNationalRegistry, verifyResultToken, verifyWebhook };