@sekyro/node 0.1.0-rc.9 → 1.0.0-rc.16
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 +111 -0
- package/README.md +252 -106
- package/dist/{chunk-TAPXGI3Q.js → chunk-IM3UCVDB.js} +1 -1
- package/dist/chunk-J6U2QY7M.js +1 -0
- package/dist/client-BDULrZqs.d.cts +2444 -0
- package/dist/client-BDULrZqs.d.ts +2444 -0
- package/dist/connect/express/index.cjs +1 -1
- package/dist/connect/express/index.d.cts +2 -2
- package/dist/connect/express/index.d.ts +2 -2
- package/dist/connect/express/index.js +1 -1
- package/dist/connect/index.cjs +1 -1
- package/dist/connect/index.d.cts +2 -2
- package/dist/connect/index.d.ts +2 -2
- package/dist/connect/index.js +1 -1
- package/dist/connect/next/index.cjs +1 -1
- package/dist/connect/next/index.d.cts +2 -2
- package/dist/connect/next/index.d.ts +2 -2
- package/dist/connect/next/index.js +1 -1
- package/dist/{connector-Bo0P3ytq.d.cts → connector-B90Jh4fv.d.cts} +98 -15
- package/dist/{connector-B2vbywn2.d.ts → connector-BXzO5Wgf.d.ts} +98 -15
- package/dist/index.cjs +1 -1
- package/dist/index.d.cts +92 -29
- package/dist/index.d.ts +92 -29
- package/dist/index.js +1 -1
- package/package.json +1 -1
- package/sbom.cdx.json +7 -7
- package/dist/chunk-O5GJ3YJV.js +0 -1
- package/dist/client-BYoo67F-.d.cts +0 -1654
- package/dist/client-BYoo67F-.d.ts +0 -1654
|
@@ -0,0 +1,2444 @@
|
|
|
1
|
+
/**
|
|
2
|
+
* Wire-level enums and shapes of the Sekyro AI 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
|
+
* 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}.
|
|
20
|
+
* @public
|
|
21
|
+
*/
|
|
22
|
+
type SessionOutcome = "approved" | "review" | "rejected" | "superseded";
|
|
23
|
+
/**
|
|
24
|
+
* What a finished session proved: `1` a live, real person (human), `2` that
|
|
25
|
+
* person's identity (document, chip, registry or supplied data bound to the
|
|
26
|
+
* face), `3` an identity corroborated by an independent source. `0` on a
|
|
27
|
+
* rejected session.
|
|
28
|
+
* @public
|
|
29
|
+
*/
|
|
30
|
+
type VerificationLevel = 0 | 1 | 2 | 3;
|
|
31
|
+
/**
|
|
32
|
+
* How a session's {@link VerificationLevel} was proved: `live_only` (liveness
|
|
33
|
+
* only), `live_unique` (liveness plus a duplicate search), and the
|
|
34
|
+
* `*_biometric` values, where a face match bound the person to a document,
|
|
35
|
+
* its chip, the registry record or partner-supplied identity data, and
|
|
36
|
+
* `eid_authenticated`, where the person signed in with a national digital
|
|
37
|
+
* identity (level 3 without a Sekyro selfie).
|
|
38
|
+
* @public
|
|
39
|
+
*/
|
|
40
|
+
type VerificationAssurance = "live_only" | "live_unique" | "document_biometric" | "chip_biometric" | "registry_biometric" | "supplied_biometric" | "eid_authenticated";
|
|
41
|
+
/** The one billing unit a finished session consumed. @public */
|
|
42
|
+
type VerificationUnit = "human_verification" | "identity_verification";
|
|
43
|
+
/** The lowest and highest {@link VerificationLevel} the session's flow can reach. @public */
|
|
44
|
+
interface LevelTarget {
|
|
45
|
+
min: VerificationLevel;
|
|
46
|
+
max: VerificationLevel;
|
|
47
|
+
}
|
|
48
|
+
/**
|
|
49
|
+
* Device and network risk facts of a finished session (booleans and a level
|
|
50
|
+
* word, never scores).
|
|
51
|
+
* @public
|
|
52
|
+
*/
|
|
53
|
+
interface ResultRisk {
|
|
54
|
+
level: "low" | "medium" | "high";
|
|
55
|
+
vpn: boolean;
|
|
56
|
+
ipDocumentMismatch: boolean;
|
|
57
|
+
deviceTampered: boolean;
|
|
58
|
+
}
|
|
59
|
+
/**
|
|
60
|
+
* What the liveness step verified about the capture itself: the device
|
|
61
|
+
* attestation, the capture proof and the injection signals.
|
|
62
|
+
* @public
|
|
63
|
+
*/
|
|
64
|
+
interface ResultCheckProofs {
|
|
65
|
+
attestation: "verified" | "missing" | "failed";
|
|
66
|
+
captureProof: "verified" | "missing";
|
|
67
|
+
injectionSignals: "clear" | "flagged";
|
|
68
|
+
}
|
|
69
|
+
/**
|
|
70
|
+
* How a session proved the person's minimum age: `estimated` (the age check
|
|
71
|
+
* (selfie) step estimated the face over the threshold by a safety margin), or
|
|
72
|
+
* from identity data: `document`, `chip`, `registry` or `eid`.
|
|
73
|
+
* @public
|
|
74
|
+
*/
|
|
75
|
+
type AgeMethod = "estimated" | "document" | "chip" | "registry" | "eid";
|
|
76
|
+
/**
|
|
77
|
+
* The age answer of a session whose flow sets a minimum age. `over` is the
|
|
78
|
+
* flow's minimum age (the threshold), never the person's age. `estimate`
|
|
79
|
+
* (years, one decimal) and `sigma` (its spread in years) are present only on
|
|
80
|
+
* the API session and webhooks, and only when the age check (selfie) step's
|
|
81
|
+
* "Keep and show the estimated age" setting is on; the result token never
|
|
82
|
+
* carries them.
|
|
83
|
+
* @public
|
|
84
|
+
*/
|
|
85
|
+
interface AgeResult {
|
|
86
|
+
over: number;
|
|
87
|
+
method: AgeMethod;
|
|
88
|
+
estimate?: number;
|
|
89
|
+
sigma?: number;
|
|
90
|
+
}
|
|
91
|
+
/** Another person the face already matched (duplicate search). @public */
|
|
92
|
+
interface ResultDuplicate {
|
|
93
|
+
/** That person's id, `per_` prefixed, as on `GET /people` and `Session.personId`. */
|
|
94
|
+
personId: string;
|
|
95
|
+
externalRef?: string;
|
|
96
|
+
}
|
|
97
|
+
/**
|
|
98
|
+
* How a `person.reuse` session runs: `recheck` verifies the same person
|
|
99
|
+
* again (liveness and face match against the stored photo), `step_up` raises
|
|
100
|
+
* the subject to identity level with a flow that proves level 2 on every path.
|
|
101
|
+
* @public
|
|
102
|
+
*/
|
|
103
|
+
type SubjectReuseMode = "recheck" | "step_up";
|
|
104
|
+
/**
|
|
105
|
+
* Where the hosted flow sends the person when the session ends: an `https`
|
|
106
|
+
* URL on one of the app's web origins, or the app's `sekyro-<slug>://` scheme.
|
|
107
|
+
* `state` (up to 256 characters) is echoed back on the redirect.
|
|
108
|
+
* @public
|
|
109
|
+
*/
|
|
110
|
+
interface SessionLinkInput {
|
|
111
|
+
returnUrl?: string;
|
|
112
|
+
state?: string;
|
|
113
|
+
}
|
|
114
|
+
/**
|
|
115
|
+
* How the person proves their identity on an optional-document app: type the
|
|
116
|
+
* national number, or photograph the document (`document_chip`: native NFC clients only).
|
|
117
|
+
* `national_eid`: the country's national eID (e.g. Houwiyeti for Mauritania),
|
|
118
|
+
* offered when the app's profile turns the national eID on.
|
|
119
|
+
* @public
|
|
120
|
+
*/
|
|
121
|
+
type IdentityMethod = "national_number" | "document_photo" | "document_chip" | "national_eid";
|
|
122
|
+
/** The verification checks a flow may contain. @public */
|
|
123
|
+
type CheckType = "liveness" | "face_match" | "doc_ocr" | "population_registry" | "phone_otp" | "nfc_chip" | "email_otp" | "portrait_icao" | "eid_auth" | "aml_screening";
|
|
124
|
+
/** Per-check execution state within a session. @public */
|
|
125
|
+
type CheckState = "pending" | "input_required" | "processing" | "passed" | "failed" | "review" | "skipped";
|
|
126
|
+
/**
|
|
127
|
+
* Why a session was stopped by a profile-v2 policy gate rather than by a
|
|
128
|
+
* failed check:
|
|
129
|
+
* - `location_not_allowed` — the end user's IP location is not allowed for the app;
|
|
130
|
+
* - `anonymizer_blocked` — an anonymizer (VPN / proxy / Tor) was detected while the app blocks them;
|
|
131
|
+
* - `capture_tampered` — the device reported a tampered capture (virtual
|
|
132
|
+
* camera, hooking, emulator…) while the app's `device.tamper` is `block`;
|
|
133
|
+
* - `device_velocity_exceeded` — the device already verified more different
|
|
134
|
+
* people than `device.velocity` allows, with `action: 'block'`;
|
|
135
|
+
* - `device_cooldown` — the device had too many rejected sessions
|
|
136
|
+
* (`cooldown` tiers); {@link Session.retryAfter} says when it may try again.
|
|
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});
|
|
142
|
+
* - `blocked_by_org`: one of your blocks (a device, a person, an account or a
|
|
143
|
+
* contact) stopped the session. Not retryable, not billed.
|
|
144
|
+
* @public
|
|
145
|
+
*/
|
|
146
|
+
type SessionFailureReason = "location_not_allowed" | "anonymizer_blocked" | "capture_tampered" | "device_velocity_exceeded" | "device_cooldown" | "platform_unsupported" | "cancelled_by_organization" | "blocked_by_org";
|
|
147
|
+
/**
|
|
148
|
+
* Profile-v2 decision-mode reasons a check's {@link SessionStep.reason} may
|
|
149
|
+
* carry when the app decides automatically (`decisions.mode: 'automatic'`)
|
|
150
|
+
* instead of routing to human review. All are retryable within the step's
|
|
151
|
+
* attempts: `liveness_inconclusive` (liveness middle band),
|
|
152
|
+
* `match_inconclusive` (face match middle band on every reference),
|
|
153
|
+
* `document_authenticity` (doc_ocr authenticity warning — retake the original)
|
|
154
|
+
* and `mobile_required` (liveness captured on a desktop — continue on a phone;
|
|
155
|
+
* not billed). Every inconclusive attempt is billed.
|
|
156
|
+
* @public
|
|
157
|
+
*/
|
|
158
|
+
type DecisionReason = "liveness_inconclusive" | "match_inconclusive" | "document_authenticity" | "mobile_required";
|
|
159
|
+
/**
|
|
160
|
+
* Profile-v2 eligibility reasons a check's {@link SessionStep.reason} may carry:
|
|
161
|
+
* `document_type_not_accepted` (doc_ocr; the person may pick another
|
|
162
|
+
* document), `nationality_not_allowed` and `underage` (doc_ocr or
|
|
163
|
+
* population_registry; terminal), and `age_unverifiable` (the app sets a
|
|
164
|
+
* minimum age but the birth date could not be read — doc_ocr: retryable with
|
|
165
|
+
* a clearer photo; population_registry: terminal).
|
|
166
|
+
* @public
|
|
167
|
+
*/
|
|
168
|
+
type EligibilityReason = "document_type_not_accepted" | "nationality_not_allowed" | "underage" | "age_unverifiable" | "underage_estimated";
|
|
169
|
+
/**
|
|
170
|
+
* Why a profile-v2 policy ended a session: a session-level
|
|
171
|
+
* {@link SessionFailureReason} (location / anonymizer gate), or the failed
|
|
172
|
+
* check's policy reason — an {@link EligibilityReason} or
|
|
173
|
+
* `document_id_number_mismatch` (the document belongs to someone other than the
|
|
174
|
+
* ID number the session was created for; `document_nni_mismatch` is its former
|
|
175
|
+
* name, still sent until the API switches to the new names), or `camera_unavailable` (spec 2026-10-29 §3.4: the person had no usable camera,
|
|
176
|
+
* so the live step ended without a capture; the session is rejected at level 0 unless your flow has a fallback),
|
|
177
|
+
* `subject_face_mismatch` (a step-up whose face did not match the person it was created for), or a review that
|
|
178
|
+
* ended at its deadline: `review_timeout` (nobody decided it) or `review_split` (two reviewers disagreed and
|
|
179
|
+
* nobody settled it); those two carry `decidedBy: "automatic"`.
|
|
180
|
+
* @public
|
|
181
|
+
*/
|
|
182
|
+
type PolicyFailureReason = SessionFailureReason | EligibilityReason | "document_id_number_mismatch" | "document_nni_mismatch" | "camera_unavailable" | "subject_face_mismatch" | "review_timeout" | "review_split" | "aml_hit";
|
|
183
|
+
/**
|
|
184
|
+
* The ID-number reasons a check's {@link SessionStep.reason} may carry (person data
|
|
185
|
+
* spec Appendix A.2), each under its generic name and its former Mauritanian name:
|
|
186
|
+
* `id_number_invalid` (`nni_invalid`: the number fails its country's rule),
|
|
187
|
+
* `registry_record_not_found` (`nni_not_found`: no registry record for the number),
|
|
188
|
+
* `id_number_recheck` (`nni_recheck`: the number must be checked again) and
|
|
189
|
+
* `document_id_number_mismatch` (`document_nni_mismatch`). The API sends the former
|
|
190
|
+
* names until it switches to the generic ones; handle both.
|
|
191
|
+
* @public
|
|
192
|
+
*/
|
|
193
|
+
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";
|
|
194
|
+
/**
|
|
195
|
+
* Why the person had no camera (spec 2026-10-29 §3.4, 2026-10-30), when the SDK said: `denied` (the
|
|
196
|
+
* person refused camera access) or `no_camera` (no usable camera: none found, an insecure page or a
|
|
197
|
+
* browser that cannot capture). A detail under `failureReason: "camera_unavailable"`, never a reason of its own.
|
|
198
|
+
* @public
|
|
199
|
+
*/
|
|
200
|
+
type CameraUnavailableCause = "denied" | "no_camera";
|
|
201
|
+
/**
|
|
202
|
+
* Profile-v2 matching reasons a check's {@link SessionStep.reason} may carry
|
|
203
|
+
* when the data you sent in {@link CreateSessionInput.person} differs from the
|
|
204
|
+
* reference identity: `name_mismatch`, `birth_date_mismatch`,
|
|
205
|
+
* `nationality_mismatch` (doc_ocr or population_registry) and
|
|
206
|
+
* `document_number_mismatch` (doc_ocr). All are final.
|
|
207
|
+
* @public
|
|
208
|
+
*/
|
|
209
|
+
type MatchReason = "name_mismatch" | "birth_date_mismatch" | "nationality_mismatch" | "document_number_mismatch";
|
|
210
|
+
/**
|
|
211
|
+
* Reasons a `face_match` {@link SessionStep.reason} carries when an earlier
|
|
212
|
+
* human review of the same person, reference photo and face settled the match
|
|
213
|
+
* score instead of a new review: `prior_review_approved` (the step passed;
|
|
214
|
+
* final) and `prior_review_rejected` (the step failed; retryable, a better
|
|
215
|
+
* capture sends the session to a reviewer again). Both are billed like
|
|
216
|
+
* `review_band`. The step's {@link SessionStep.decision} has
|
|
217
|
+
* `source: "prior_review"` and names your earlier session.
|
|
218
|
+
* @public
|
|
219
|
+
*/
|
|
220
|
+
type PriorReviewReason = "prior_review_approved" | "prior_review_rejected";
|
|
221
|
+
/**
|
|
222
|
+
* Review outcome reasons any reviewable step may carry: `superseded_by_retry`
|
|
223
|
+
* (a newer attempt of the same person took the review over; the session ends
|
|
224
|
+
* with `outcome: null` and {@link Session.supersededBy}) and `review_split` (two reviewers disagreed and
|
|
225
|
+
* nobody settled it before the review deadline; the session is rejected).
|
|
226
|
+
* Both are billed and retryable: the person may verify again. Neither counts
|
|
227
|
+
* toward the device cooldown.
|
|
228
|
+
* @public
|
|
229
|
+
*/
|
|
230
|
+
type ReviewOutcomeReason = "superseded_by_retry" | "review_split";
|
|
231
|
+
/**
|
|
232
|
+
* What a review decision is about, on {@link SessionStepDecision.reasons}: the
|
|
233
|
+
* part that failed on a rejection (several may apply), or the check the
|
|
234
|
+
* reviewer overrode on an approval.
|
|
235
|
+
* @public
|
|
236
|
+
*/
|
|
237
|
+
type ReviewReason = "document_authenticity" | "liveness" | "face_match" | "data_mismatch" | "screening" | "org_rule" | "other";
|
|
238
|
+
/**
|
|
239
|
+
* How a person decided a step: a reviewer (`source: "review"`), or an earlier
|
|
240
|
+
* review of the same person, reference photo and face that was reused
|
|
241
|
+
* (`source: "prior_review"`). Counts and enums only: never a reviewer's
|
|
242
|
+
* identity and never an individual vote.
|
|
243
|
+
* @public
|
|
244
|
+
*/
|
|
245
|
+
interface SessionStepDecision {
|
|
246
|
+
source: "review" | "prior_review";
|
|
247
|
+
/** One reviewer (`single`) or two independent reviewers (`dual`). */
|
|
248
|
+
mode: "single" | "dual";
|
|
249
|
+
/** How many reviewer votes formed the decision (a third vote settles a dual split). */
|
|
250
|
+
votes: 1 | 2 | 3;
|
|
251
|
+
/** Dual review only: whether the first two reviewers agreed. */
|
|
252
|
+
agreement?: boolean;
|
|
253
|
+
/** What the decision was about ({@link ReviewReason}). */
|
|
254
|
+
reasons: ReviewReason[];
|
|
255
|
+
/** ISO 8601: when the decision was made. */
|
|
256
|
+
decidedAt: string;
|
|
257
|
+
/** `prior_review` only: your earlier session whose review decided this one. */
|
|
258
|
+
sessionId?: string;
|
|
259
|
+
}
|
|
260
|
+
/**
|
|
261
|
+
* A failure identification match (terminal sessions, when the flow's
|
|
262
|
+
* identify-failures setting is on and the search found one): who the face
|
|
263
|
+
* matches when the face match did not prove the claimed identity against a
|
|
264
|
+
* registry portrait. A signal, never a decision: the session state is
|
|
265
|
+
* unchanged. Ids, enums and numbers only, never a name or an ID number.
|
|
266
|
+
*
|
|
267
|
+
* `kind`: `presenter` (the live person is most likely the matched record),
|
|
268
|
+
* `shown_face` (the photo or screen shown carries the matched record, a
|
|
269
|
+
* possible victim) or `other_identity`. `other_identity` is informational
|
|
270
|
+
* only: the registry also knows this face under another record. The person may
|
|
271
|
+
* legitimately hold more than one identity document, for example a foreign
|
|
272
|
+
* passport, an older document, a second nationality or a residence permit. Do
|
|
273
|
+
* not treat this signal alone as fraud: use it as a lead for your own process.
|
|
274
|
+
* @public
|
|
275
|
+
*/
|
|
276
|
+
interface FailureIdentification {
|
|
277
|
+
kind: "presenter" | "shown_face" | "other_identity";
|
|
278
|
+
/** The search scope: your verified persons (`org`) or the whole registry index (`registry`). */
|
|
279
|
+
scope: "org" | "registry";
|
|
280
|
+
match: {
|
|
281
|
+
/** Your verified person for the match, when you hold one, `per_` prefixed. */
|
|
282
|
+
personId?: string;
|
|
283
|
+
/** An opaque reference of the matched person when you hold no verified subject for it, scoped to your organisation. */
|
|
284
|
+
reference?: string;
|
|
285
|
+
/** The registry photo that matched (an opaque id, scoped to your organisation). */
|
|
286
|
+
photoId?: string;
|
|
287
|
+
/** The grade of that photo: `1` or `2` registry, `3` an older bulk import photo. */
|
|
288
|
+
tier: 1 | 2 | 3;
|
|
289
|
+
/** Calibrated similarity on the face match scale, in [0, 1]. */
|
|
290
|
+
score: number;
|
|
291
|
+
band: "strong" | "moderate";
|
|
292
|
+
};
|
|
293
|
+
/** With `other_identity`: the reference the session passed against. */
|
|
294
|
+
referenceSource?: "registry" | "chip" | "document" | "subject" | "org_supplied";
|
|
295
|
+
}
|
|
296
|
+
/**
|
|
297
|
+
* Face-match probe-binding reason a `face_match` {@link SessionStep.reason} may
|
|
298
|
+
* carry (SDK spec §4.10): `probe_not_from_liveness` — the face image isn't the
|
|
299
|
+
* person in the liveness clip. Retryable within the step's attempts (the
|
|
300
|
+
* person re-takes the liveness capture); billed.
|
|
301
|
+
* @public
|
|
302
|
+
*/
|
|
303
|
+
type ProbeBindingReason = "probe_not_from_liveness";
|
|
304
|
+
/**
|
|
305
|
+
* The languages the person being verified sees (hosted flow and SDK screens; spec 2026-10-29 §9), every screen in
|
|
306
|
+
* each. SMS and email messages stay in `ar`, `fr` or `en` (English for the three others).
|
|
307
|
+
* @public
|
|
308
|
+
*/
|
|
309
|
+
type Locale = "ar" | "fr" | "en" | "es" | "pt" | "de";
|
|
310
|
+
/** The environment a webhook was emitted from. @public */
|
|
311
|
+
type SekyroEnvironment = "sandbox" | "live";
|
|
312
|
+
/**
|
|
313
|
+
* One check of a session, as the partner API projects it: enum/id fields only,
|
|
314
|
+
* never civil data.
|
|
315
|
+
* @public
|
|
316
|
+
*/
|
|
317
|
+
interface SessionStep {
|
|
318
|
+
/** The node of your flow this step belongs to (e.g. `n_live`): the name of the step. Absent on sessions created before flows. */
|
|
319
|
+
id?: string;
|
|
320
|
+
/** What the step runs: the service of its node. Absent on sessions created before flows. */
|
|
321
|
+
service?: ServiceId;
|
|
322
|
+
state: CheckState;
|
|
323
|
+
/** Sekyro flows: the check failed and the flow's fallback took over. */
|
|
324
|
+
handled?: true;
|
|
325
|
+
/** Machine-readable failure/review reason, when the check has one. */
|
|
326
|
+
reason?: string;
|
|
327
|
+
/** With reason `camera_unavailable`: why, when the SDK said (`denied` or `no_camera`). */
|
|
328
|
+
reasonDetail?: CameraUnavailableCause;
|
|
329
|
+
/** Calibrated model score in [0, 1] for scored checks (liveness, face match). */
|
|
330
|
+
calibratedScore?: number;
|
|
331
|
+
/** The check failed after using all of its attempts. */
|
|
332
|
+
attemptsExhausted?: boolean;
|
|
333
|
+
/**
|
|
334
|
+
* `portrait_icao` only (ID mode): the per-criterion ICAO report of the last
|
|
335
|
+
* attempt — numbers and enums only, never the image.
|
|
336
|
+
*/
|
|
337
|
+
report?: PortraitReportEntry[];
|
|
338
|
+
/**
|
|
339
|
+
* `face_match` only: the probe-quality measurement of the selfie that was
|
|
340
|
+
* matched (occlusion, head pose, eye openness, sharpness). Recorded for
|
|
341
|
+
* information only: it never changes the step's state or reason.
|
|
342
|
+
*/
|
|
343
|
+
probeQuality?: ProbeQuality;
|
|
344
|
+
/**
|
|
345
|
+
* How a person decided this step ({@link SessionStepDecision}); absent when
|
|
346
|
+
* no person decided it.
|
|
347
|
+
*/
|
|
348
|
+
decision?: SessionStepDecision;
|
|
349
|
+
/** The step last ran simulated in the Sandbox (no paid or external service). */
|
|
350
|
+
simulated?: true;
|
|
351
|
+
}
|
|
352
|
+
/**
|
|
353
|
+
* The probe-quality measurement on a `face_match` step. Numbers only; `null`
|
|
354
|
+
* means the value could not be measured. Informational: no threshold applies.
|
|
355
|
+
* @public
|
|
356
|
+
*/
|
|
357
|
+
interface ProbeQuality {
|
|
358
|
+
/** Share of the inner face that is covered (a hand, a mask, a phone), in [0, 1]. */
|
|
359
|
+
occlusion: number | null;
|
|
360
|
+
/** Head pose in degrees. */
|
|
361
|
+
pose: {
|
|
362
|
+
yaw: number | null;
|
|
363
|
+
pitch: number | null;
|
|
364
|
+
roll: number | null;
|
|
365
|
+
};
|
|
366
|
+
/** Openness of the less-open eye, in [0, 1]. */
|
|
367
|
+
eyesOpen: number | null;
|
|
368
|
+
/** Sharpness of the face region (higher is sharper; no fixed scale). */
|
|
369
|
+
sharpness: number | null;
|
|
370
|
+
}
|
|
371
|
+
/**
|
|
372
|
+
* One row of the `portrait_icao` report (ID mode): the server's measurement of
|
|
373
|
+
* one ICAO criterion and the threshold that applied.
|
|
374
|
+
* @public
|
|
375
|
+
*/
|
|
376
|
+
interface PortraitReportEntry {
|
|
377
|
+
criterion: "pose" | "eyes" | "mouth" | "occlusion" | "glare" | "lighting" | "background" | "resolution";
|
|
378
|
+
value: number | null;
|
|
379
|
+
threshold: number | string | null;
|
|
380
|
+
pass: boolean;
|
|
381
|
+
}
|
|
382
|
+
/**
|
|
383
|
+
* Out-of-band delivery of the session's hosted link, sent by Sekyro AI after the
|
|
384
|
+
* session is created. Best effort: a failed send never fails the create.
|
|
385
|
+
* @public
|
|
386
|
+
*/
|
|
387
|
+
interface DeliverOptions {
|
|
388
|
+
/** Delivery channel. */
|
|
389
|
+
channel: "sms" | "whatsapp";
|
|
390
|
+
/** E.164 phone number of the recipient (`+` and the country code). */
|
|
391
|
+
to: string;
|
|
392
|
+
}
|
|
393
|
+
/**
|
|
394
|
+
* An ID number of the person (person data spec §4.1): the document type, the
|
|
395
|
+
* issuing country (ISO 3166-1 alpha-2; alpha-3 is accepted and normalized) and
|
|
396
|
+
* the number (1 to 40 characters, then the issuing country's rule, e.g. the
|
|
397
|
+
* check digit of a Mauritanian national ID number).
|
|
398
|
+
* @public
|
|
399
|
+
*/
|
|
400
|
+
interface SubjectIdNumber {
|
|
401
|
+
type: "national_id" | "passport" | "residence_permit";
|
|
402
|
+
issuingCountry: string;
|
|
403
|
+
number: string;
|
|
404
|
+
}
|
|
405
|
+
/**
|
|
406
|
+
* The person's name in one script (ISO 15924 code, e.g. `Latn` or `Arab`).
|
|
407
|
+
* @public
|
|
408
|
+
*/
|
|
409
|
+
interface SubjectName {
|
|
410
|
+
script: string;
|
|
411
|
+
/** 1 to 100 characters. */
|
|
412
|
+
given: string;
|
|
413
|
+
/** 1 to 100 characters. */
|
|
414
|
+
family: string;
|
|
415
|
+
/** Optional, 1 to 100 characters. */
|
|
416
|
+
patronymic?: string;
|
|
417
|
+
}
|
|
418
|
+
/**
|
|
419
|
+
* One birth place entry of {@link SessionPersonInput.birthPlace}: the place in
|
|
420
|
+
* one script (ISO 15924 code, e.g. `Latn` or `Arab`), 1 to 120 characters.
|
|
421
|
+
* @public
|
|
422
|
+
*/
|
|
423
|
+
interface PersonBirthPlaceInput {
|
|
424
|
+
script: string;
|
|
425
|
+
value: string;
|
|
426
|
+
}
|
|
427
|
+
/**
|
|
428
|
+
* The person's identity document ({@link SessionPersonInput.document}): its
|
|
429
|
+
* type, issuing country (ISO 3166-1 alpha-2 or alpha-3) and the number it
|
|
430
|
+
* prints (1 to 40 letters, digits, spaces or hyphens). Compared with what the
|
|
431
|
+
* capture reads; it does not bind the session (`idNumber` does).
|
|
432
|
+
* @public
|
|
433
|
+
*/
|
|
434
|
+
interface PersonDocumentInput {
|
|
435
|
+
type: "national_id" | "passport" | "residence_permit";
|
|
436
|
+
issuingCountry: string;
|
|
437
|
+
number: string;
|
|
438
|
+
}
|
|
439
|
+
/**
|
|
440
|
+
* What you already know about the person (`person` at session create). A
|
|
441
|
+
* closed object: unknown keys are refused (`400`). Every field is optional;
|
|
442
|
+
* `null` or blank counts as absent.
|
|
443
|
+
*
|
|
444
|
+
* The flow decides whether these are checked or believed: in a flow that checks
|
|
445
|
+
* identity from a document or a registry, they are a prefill compared with what
|
|
446
|
+
* the person shows; in a flow that verifies identity from your data (the
|
|
447
|
+
* response's `subjectUse: "reference"`), `idNumber`, `birthDate`, `photo` and
|
|
448
|
+
* `fetchedAt` are required and the record is the reference. `idNumber` binds the
|
|
449
|
+
* session to that identity in both cases: the hosted flow may omit it but cannot
|
|
450
|
+
* substitute another number.
|
|
451
|
+
* @public
|
|
452
|
+
*/
|
|
453
|
+
interface SessionPersonInput {
|
|
454
|
+
/** The person's ID number. Binds the session. */
|
|
455
|
+
idNumber?: SubjectIdNumber;
|
|
456
|
+
/** E.164 phone number (`+` and the country code). */
|
|
457
|
+
phone?: string;
|
|
458
|
+
/** Email address, for the email OTP step. */
|
|
459
|
+
email?: string;
|
|
460
|
+
/** Full name, 1 to 200 characters, any script. */
|
|
461
|
+
fullName?: string;
|
|
462
|
+
/** The name per script, at most 4 entries, one per script. */
|
|
463
|
+
names?: SubjectName[];
|
|
464
|
+
/** ISO 8601 date (`YYYY-MM-DD`). */
|
|
465
|
+
birthDate?: string;
|
|
466
|
+
/**
|
|
467
|
+
* Place of birth (kept only with a reference record): a string of 1 to 120
|
|
468
|
+
* characters in any script, or one entry per script (at most 4).
|
|
469
|
+
*/
|
|
470
|
+
birthPlace?: string | PersonBirthPlaceInput[];
|
|
471
|
+
/** `M`, `F` or `X` (ICAO 9303 values; kept only with a reference record). */
|
|
472
|
+
sex?: "M" | "F" | "X";
|
|
473
|
+
/** ISO 3166-1 alpha-2 codes, 1 to 4. */
|
|
474
|
+
nationalities?: string[];
|
|
475
|
+
/** The person's identity document ({@link PersonDocumentInput}). */
|
|
476
|
+
document?: PersonDocumentInput;
|
|
477
|
+
/**
|
|
478
|
+
* Base64 JPEG or PNG (optional data-URL prefix, at most 1 MB decoded): the
|
|
479
|
+
* face-match reference of a reference record. Refused in a flow that uses the
|
|
480
|
+
* data as a prefill (`422 subject_photo_not_used`).
|
|
481
|
+
*/
|
|
482
|
+
photo?: string;
|
|
483
|
+
/** ISO 8601 date (`YYYY-MM-DD`) of the photo. */
|
|
484
|
+
photoDate?: string;
|
|
485
|
+
/**
|
|
486
|
+
* ISO 8601 date-time: when YOUR system obtained this data. Required with a
|
|
487
|
+
* reference record; at most 24 h old (`422 subject_record_stale`).
|
|
488
|
+
*/
|
|
489
|
+
fetchedAt?: string;
|
|
490
|
+
/**
|
|
491
|
+
* Your own id for this person (1–128 characters). Echoed on the session and
|
|
492
|
+
* its webhooks, and searchable on the people API ({@link PeopleApi.list}).
|
|
493
|
+
*/
|
|
494
|
+
externalRef?: string;
|
|
495
|
+
/**
|
|
496
|
+
* Returning user (profile v2 step 5): verify this already-verified subject
|
|
497
|
+
* again with liveness + face match only, against the reference photo stored
|
|
498
|
+
* on the subject. Name exactly one target. Errors at create:
|
|
499
|
+
* `404 subject_not_found`, `409 subject_revoked`, `409 subject_no_reference`,
|
|
500
|
+
* `409 subject_stale` (older than the flow's `returning.maxAgeMonths`),
|
|
501
|
+
* `409 reuse_disabled` (the flow turns returning-user sessions off) and
|
|
502
|
+
* `400` / `409 reuse_target_ambiguous`.
|
|
503
|
+
*/
|
|
504
|
+
reuse?: SubjectReuseTarget;
|
|
505
|
+
}
|
|
506
|
+
/**
|
|
507
|
+
* Which person a returning-user session re-verifies: exactly ONE of the
|
|
508
|
+
* person id (`personId`, `per_...` or bare), your own `externalRef` (must match a
|
|
509
|
+
* single person) or the `idNumber` the person verified with.
|
|
510
|
+
* @public
|
|
511
|
+
*/
|
|
512
|
+
type SubjectReuseTarget = ({
|
|
513
|
+
personId: string;
|
|
514
|
+
externalRef?: never;
|
|
515
|
+
idNumber?: never;
|
|
516
|
+
} | {
|
|
517
|
+
externalRef: string;
|
|
518
|
+
personId?: never;
|
|
519
|
+
idNumber?: never;
|
|
520
|
+
} | {
|
|
521
|
+
idNumber: SubjectIdNumber;
|
|
522
|
+
personId?: never;
|
|
523
|
+
externalRef?: never;
|
|
524
|
+
}) & {
|
|
525
|
+
/**
|
|
526
|
+
* `recheck` (default) or `step_up` ({@link SubjectReuseMode}). `step_up` on
|
|
527
|
+
* a flow that does not prove level 2 on every path answers
|
|
528
|
+
* `400 step_up_flow_too_weak`.
|
|
529
|
+
*/
|
|
530
|
+
mode?: SubjectReuseMode;
|
|
531
|
+
};
|
|
532
|
+
/** A document type the backend reads (kyc-docs-v2 vocabulary; `carte_identite` = identity card of any issuer). @public */
|
|
533
|
+
type ProfileDocumentType = "carte_identite" | "passport" | "residence_permit";
|
|
534
|
+
/**
|
|
535
|
+
* The services a Sekyro flow is built from. A session's steps
|
|
536
|
+
* ({@link SessionStep.service}) and {@link FlowOverrides.services} use these
|
|
537
|
+
* ids; one service may run several checks (e.g. `liveness` with an ICAO
|
|
538
|
+
* portrait).
|
|
539
|
+
* @public
|
|
540
|
+
*/
|
|
541
|
+
type ServiceId = "device_network" | "phone_otp" | "email_otp" | "national_eid" | "document" | "nfc" | "population_registry" | "supplied_identity" | "summary_confirm" | "liveness" | "portrait" | "face_match" | "aml_screening" | "face_dedup" | "age_estimation";
|
|
542
|
+
/**
|
|
543
|
+
* The general settings of a flow that a session may override (the flow's
|
|
544
|
+
* `link`, `language` and override policy are not overridable). Country codes
|
|
545
|
+
* are ISO 3166-1 alpha-2 (`MR`). Used through {@link FlowOverrides.settings}.
|
|
546
|
+
* @public
|
|
547
|
+
*/
|
|
548
|
+
interface FlowOverridableSettings {
|
|
549
|
+
/** Who may be verified. */
|
|
550
|
+
eligibility: {
|
|
551
|
+
/** Accepted nationalities: `'*'` or a list, optionally per IP location. */
|
|
552
|
+
nationalities: {
|
|
553
|
+
default: "*" | string[];
|
|
554
|
+
byLocation?: Record<string, "*" | string[]>;
|
|
555
|
+
};
|
|
556
|
+
/** Minimum age in years (1–120), or `null` for none. */
|
|
557
|
+
minAge: number | null;
|
|
558
|
+
};
|
|
559
|
+
/** Automatic decisions instead of human review (`retryConfidentRejects` lets confident rejects retry). */
|
|
560
|
+
decisions?: {
|
|
561
|
+
mode: "automatic" | "review";
|
|
562
|
+
retryConfidentRejects: boolean;
|
|
563
|
+
};
|
|
564
|
+
/** Data consistency across sources. */
|
|
565
|
+
fraud: {
|
|
566
|
+
/** Comparison of your `subject` data with the reference identity. */
|
|
567
|
+
nameMatch?: {
|
|
568
|
+
level: "strict" | "standard" | "lenient";
|
|
569
|
+
onMismatch: "fail" | "signal";
|
|
570
|
+
};
|
|
571
|
+
};
|
|
572
|
+
/** Returning-user sessions (`person.reuse`). */
|
|
573
|
+
returning: {
|
|
574
|
+
/** `false`: returning-user sessions are refused (`409 reuse_disabled`). */
|
|
575
|
+
enabled: boolean;
|
|
576
|
+
/** Maximum age in months (1–120) of the subject's last verification; `null` = no limit. */
|
|
577
|
+
maxAgeMonths: number | null;
|
|
578
|
+
};
|
|
579
|
+
/** Identity-document rules. */
|
|
580
|
+
documents: {
|
|
581
|
+
/** Accepted document types: `'*'` (all) or a list, optionally per issuing country. */
|
|
582
|
+
accepted: {
|
|
583
|
+
default: "*" | ProfileDocumentType[];
|
|
584
|
+
byIssuer?: Record<string, ProfileDocumentType[]>;
|
|
585
|
+
};
|
|
586
|
+
/** Expired documents: refused, allowed, or allowed for `graceDays` (1–365) after expiry. */
|
|
587
|
+
expired: "reject" | "allow" | {
|
|
588
|
+
graceDays: number;
|
|
589
|
+
};
|
|
590
|
+
authenticity: "standard" | "off";
|
|
591
|
+
};
|
|
592
|
+
}
|
|
593
|
+
/**
|
|
594
|
+
* Document substitution: the portrait a `document` or `nfc` step produces is
|
|
595
|
+
* compared with the registry portrait (or the chip with the printed photo).
|
|
596
|
+
* `signal` records a risk signal on a clear mismatch, `review` also sends the
|
|
597
|
+
* session to review, `off` compares nothing. `failBelow` is the mismatch bound
|
|
598
|
+
* in (0, 1), absent = the platform bound.
|
|
599
|
+
* @public
|
|
600
|
+
*/
|
|
601
|
+
interface DocumentSubstitutionSettings {
|
|
602
|
+
mode: "off" | "signal" | "review";
|
|
603
|
+
failBelow?: number;
|
|
604
|
+
}
|
|
605
|
+
/**
|
|
606
|
+
* The per-service settings a session may override, by {@link ServiceId}.
|
|
607
|
+
* `attempts` limits are per step (absent = the platform default).
|
|
608
|
+
* @public
|
|
609
|
+
*/
|
|
610
|
+
interface FlowServiceSettings {
|
|
611
|
+
/** Device & Network Intelligence: IP location, anonymizers, cooldown, device and capture postures. */
|
|
612
|
+
device_network: {
|
|
613
|
+
/** Where the end user may be (IP location). */
|
|
614
|
+
locations: {
|
|
615
|
+
mode: "all";
|
|
616
|
+
} | {
|
|
617
|
+
mode: "only" | "all_except";
|
|
618
|
+
countries: string[];
|
|
619
|
+
};
|
|
620
|
+
/** VPN / proxy / Tor. */
|
|
621
|
+
anonymizers: "allow" | "block";
|
|
622
|
+
/** Device cooldown after repeated rejections (at most 5 tiers; `[]` = off). */
|
|
623
|
+
cooldown?: {
|
|
624
|
+
tiers: Array<{
|
|
625
|
+
rejectedSessions: number;
|
|
626
|
+
windowHours: number;
|
|
627
|
+
waitMinutes: number;
|
|
628
|
+
}>;
|
|
629
|
+
};
|
|
630
|
+
/** Device tamper and velocity actions. */
|
|
631
|
+
device?: {
|
|
632
|
+
tamper: "block" | "signal";
|
|
633
|
+
velocity: {
|
|
634
|
+
maxIdentitiesPerDevice: number;
|
|
635
|
+
windowDays: number;
|
|
636
|
+
action: "signal" | "block";
|
|
637
|
+
};
|
|
638
|
+
};
|
|
639
|
+
attestation?: "off" | "signal" | "enforce";
|
|
640
|
+
captureIntegrity?: "off" | "signal" | "enforce";
|
|
641
|
+
};
|
|
642
|
+
phone_otp: {
|
|
643
|
+
/** Where the number comes from: your `person.phone`, the person, or either. */
|
|
644
|
+
numberSource: "prefilled" | "user_entered" | "prefilled_or_entered";
|
|
645
|
+
/** Narrow the channels the person may choose from (absent = every channel the org has on). */
|
|
646
|
+
channels?: Array<"whatsapp" | "sms">;
|
|
647
|
+
/** Which countries codes may be sent to (absent = the flow's allowed `locations`). */
|
|
648
|
+
destinations?: "locations" | "any" | {
|
|
649
|
+
countries: string[];
|
|
650
|
+
};
|
|
651
|
+
attempts?: number;
|
|
652
|
+
};
|
|
653
|
+
email_otp: {
|
|
654
|
+
/** Where the address comes from: your `input.email`, the person, or either. */
|
|
655
|
+
emailSource: "prefilled" | "user_entered" | "prefilled_or_entered";
|
|
656
|
+
/** Disposable (temporary) addresses: allowed, flagged as a risk signal (default), or refused. */
|
|
657
|
+
disposable?: "allow" | "signal" | "block";
|
|
658
|
+
attempts?: number;
|
|
659
|
+
};
|
|
660
|
+
national_eid: {
|
|
661
|
+
/**
|
|
662
|
+
* `'org'` (every national eID the org can use, resolved at session create)
|
|
663
|
+
* or provider ids (`{country}.{provider}`, e.g. `MR.houwiyeti`).
|
|
664
|
+
*/
|
|
665
|
+
providers: "org" | string[];
|
|
666
|
+
/** The eID portrait is the face-match reference. */
|
|
667
|
+
portraitReference: boolean;
|
|
668
|
+
};
|
|
669
|
+
document: {
|
|
670
|
+
attempts?: number;
|
|
671
|
+
/** Compare the document photo with the registry photo (absent = the platform default). */
|
|
672
|
+
documentSubstitution?: DocumentSubstitutionSettings;
|
|
673
|
+
};
|
|
674
|
+
/** The chip read (its MRZ source is derived from the flow and is not overridable). */
|
|
675
|
+
nfc: {
|
|
676
|
+
maxAttempts?: number;
|
|
677
|
+
/** Compare the chip photo with the registry photo (absent = the platform default). */
|
|
678
|
+
documentSubstitution?: DocumentSubstitutionSettings;
|
|
679
|
+
};
|
|
680
|
+
population_registry: {
|
|
681
|
+
/** `'org'` (every registry the org can use, resolved at session create) or registry ids. */
|
|
682
|
+
sources: "org" | Array<"MR.anrpts">;
|
|
683
|
+
/**
|
|
684
|
+
* @deprecated Use `idNumberSource` (same values). Both with different values is
|
|
685
|
+
* `400 override_invalid`.
|
|
686
|
+
*/
|
|
687
|
+
nniSource: "auto" | "typed" | "bound_only";
|
|
688
|
+
/** Where the ID number comes from: `auto`, `typed` (the person types it) or `bound_only` (your `person.idNumber`). */
|
|
689
|
+
idNumberSource: "auto" | "typed" | "bound_only";
|
|
690
|
+
onUncovered: "skip";
|
|
691
|
+
attempts?: number;
|
|
692
|
+
};
|
|
693
|
+
supplied_identity: Record<string, never>;
|
|
694
|
+
summary_confirm: {
|
|
695
|
+
/** Offer « Reprendre » (re-open the identity source). */
|
|
696
|
+
retake: boolean;
|
|
697
|
+
};
|
|
698
|
+
liveness: {
|
|
699
|
+
/** `off`, selfie ICAO `alert` / `reject`, or `id_document` (ID-photo portrait, always rejects). */
|
|
700
|
+
icao: "off" | "alert" | "reject" | "id_document";
|
|
701
|
+
attempts?: number;
|
|
702
|
+
};
|
|
703
|
+
/** The ICAO photo step. */
|
|
704
|
+
portrait: {
|
|
705
|
+
/** Where the photo comes from (absent = `camera`). */
|
|
706
|
+
source?: "camera" | "upload" | "choice";
|
|
707
|
+
/** Who holds the camera (absent = `self`). */
|
|
708
|
+
capture?: "self" | "assisted" | "choice";
|
|
709
|
+
/** An upload on a path with no liveness: `refuse`, or `mark` with the signal `portrait_unbound` (absent = `refuse`). */
|
|
710
|
+
unbound?: "refuse" | "mark";
|
|
711
|
+
/** `reject`: a failing photo asks for another; `alert`: it passes with the signal `icao_non_compliant`. */
|
|
712
|
+
policy: "reject" | "alert";
|
|
713
|
+
/** Crop, scale and straighten (absent = `on`). */
|
|
714
|
+
fixes?: "off" | "on";
|
|
715
|
+
/** Ask the person to confirm a fixed photo (absent = `confirm`). */
|
|
716
|
+
fixReview?: "confirm" | "silent";
|
|
717
|
+
/** The delivered format (absent = `icao_9303`). */
|
|
718
|
+
output?: "icao_9303" | "photo_35x45_300dpi" | "square_600";
|
|
719
|
+
attempts?: number;
|
|
720
|
+
};
|
|
721
|
+
face_match: {
|
|
722
|
+
reference: "auto" | "document" | "registry";
|
|
723
|
+
attempts?: number;
|
|
724
|
+
};
|
|
725
|
+
/**
|
|
726
|
+
* Sanctions and PEP screening of the person the flow verified. `onHit`: `signal`
|
|
727
|
+
* (the session goes on and the match is reported), `review` (a reviewer
|
|
728
|
+
* decides) or `fail` (the session is rejected with `aml_hit`).
|
|
729
|
+
*/
|
|
730
|
+
aml_screening: {
|
|
731
|
+
lists: ScreeningList[];
|
|
732
|
+
onHit: "signal" | "review" | "fail";
|
|
733
|
+
};
|
|
734
|
+
face_dedup: {
|
|
735
|
+
scope: "app" | "org";
|
|
736
|
+
onDuplicate: "review" | "fail";
|
|
737
|
+
};
|
|
738
|
+
/** The age check (selfie); the threshold is the flow's `eligibility.minAge`. */
|
|
739
|
+
age_estimation: {
|
|
740
|
+
/** Keep and show the estimated age ({@link AgeResult.estimate}) on the API session and webhooks. Default `false`. */
|
|
741
|
+
showEstimatedAge?: boolean;
|
|
742
|
+
};
|
|
743
|
+
}
|
|
744
|
+
/**
|
|
745
|
+
* `T` with every property optional, recursively. Arrays are replaced as a
|
|
746
|
+
* whole, never merged element by element.
|
|
747
|
+
* @public
|
|
748
|
+
*/
|
|
749
|
+
type DeepPartial<T> = T extends readonly unknown[] ? T : T extends object ? {
|
|
750
|
+
[K in keyof T]?: DeepPartial<T[K]>;
|
|
751
|
+
} : T;
|
|
752
|
+
/**
|
|
753
|
+
* A per-session override of the flow ({@link CreateSessionInput.overrides}).
|
|
754
|
+
*
|
|
755
|
+
* - `settings`: any subset of {@link FlowOverridableSettings}, at any depth.
|
|
756
|
+
* - `services`: keyed by service (applied to every node of that service): any
|
|
757
|
+
* subset of its {@link FlowServiceSettings}, or `'off'` to remove it from
|
|
758
|
+
* the flow. A service the flow does not use is ignored.
|
|
759
|
+
*
|
|
760
|
+
* Objects merge into the flow; arrays and scalar values replace. Unknown keys
|
|
761
|
+
* and invalid results answer `400 override_invalid`. An override may only
|
|
762
|
+
* make the flow stricter unless the flow allows widening; turning a service
|
|
763
|
+
* `'off'` always widens. A widening change answers `403 override_widens_flow`.
|
|
764
|
+
* The changed paths are reported on {@link Session.overriddenFields}.
|
|
765
|
+
*
|
|
766
|
+
* @example
|
|
767
|
+
* ```ts
|
|
768
|
+
* await sekyro.sessions.create({
|
|
769
|
+
* flow: "foreigners",
|
|
770
|
+
* overrides: {
|
|
771
|
+
* settings: { eligibility: { minAge: 21 } },
|
|
772
|
+
* services: { liveness: { attempts: 2 } },
|
|
773
|
+
* },
|
|
774
|
+
* });
|
|
775
|
+
* ```
|
|
776
|
+
* @public
|
|
777
|
+
*/
|
|
778
|
+
interface FlowOverrides {
|
|
779
|
+
settings?: DeepPartial<FlowOverridableSettings>;
|
|
780
|
+
services?: {
|
|
781
|
+
[S in ServiceId]?: DeepPartial<FlowServiceSettings[S]> | "off";
|
|
782
|
+
};
|
|
783
|
+
}
|
|
784
|
+
/**
|
|
785
|
+
* The flow version a session runs: its `flw_` id, its slug and the published
|
|
786
|
+
* version pinned at create.
|
|
787
|
+
* @public
|
|
788
|
+
*/
|
|
789
|
+
interface SessionFlowRef {
|
|
790
|
+
id: string;
|
|
791
|
+
slug: string;
|
|
792
|
+
version: number;
|
|
793
|
+
}
|
|
794
|
+
/**
|
|
795
|
+
* Input of {@link SessionsApi.simulate}.
|
|
796
|
+
* @public
|
|
797
|
+
*/
|
|
798
|
+
interface SimulateSessionInput {
|
|
799
|
+
/** How the session ends. The flow must be able to reach it, else `422 simulate_outcome_unreachable`. */
|
|
800
|
+
outcome: "approved" | "rejected" | "review";
|
|
801
|
+
/**
|
|
802
|
+
* Only with `rejected`: the reason the failing step reports, e.g.
|
|
803
|
+
* `spoof_detected`. No step on the path can fail with it: `422 simulate_reason_invalid`.
|
|
804
|
+
*/
|
|
805
|
+
reason?: string;
|
|
806
|
+
}
|
|
807
|
+
/**
|
|
808
|
+
* The API key in use, from {@link Sekyro.me}. Never carries the secret.
|
|
809
|
+
* @public
|
|
810
|
+
*/
|
|
811
|
+
interface ApiKeyIdentity {
|
|
812
|
+
/** The environment the key belongs to. */
|
|
813
|
+
env: SekyroEnvironment;
|
|
814
|
+
/** The public start of the key, e.g. `sk_test_ab12`. */
|
|
815
|
+
keyPrefix: string;
|
|
816
|
+
scopes: string[];
|
|
817
|
+
app: {
|
|
818
|
+
id: string;
|
|
819
|
+
slug: string;
|
|
820
|
+
name: string;
|
|
821
|
+
};
|
|
822
|
+
org: {
|
|
823
|
+
name: string;
|
|
824
|
+
};
|
|
825
|
+
}
|
|
826
|
+
/**
|
|
827
|
+
* One flow of your app, from {@link FlowsApi.list}. Published flows only;
|
|
828
|
+
* pass `slug` or `id` as {@link CreateSessionInput.flow}.
|
|
829
|
+
* @public
|
|
830
|
+
*/
|
|
831
|
+
interface FlowSummary {
|
|
832
|
+
/** `flw_` id. */
|
|
833
|
+
id: string;
|
|
834
|
+
slug: string;
|
|
835
|
+
name: string;
|
|
836
|
+
/** The published version a new session runs. */
|
|
837
|
+
version: number;
|
|
838
|
+
/** The flow a session runs when you send no `flow`. */
|
|
839
|
+
isDefault: boolean;
|
|
840
|
+
}
|
|
841
|
+
/**
|
|
842
|
+
* Input of {@link SessionsApi.create}. The API key belongs to an app; the
|
|
843
|
+
* app's flow (its default flow, or the one named in `flow`) decides the steps.
|
|
844
|
+
* @public
|
|
845
|
+
*/
|
|
846
|
+
interface CreateSessionInput {
|
|
847
|
+
/**
|
|
848
|
+
* The app's flow to run: its slug (e.g. `foreigners`) or `flw_` id, as
|
|
849
|
+
* {@link FlowsApi.list} lists them. Absent = the app's default flow.
|
|
850
|
+
* Errors: `404 flow_not_found` (no such flow in the key's app),
|
|
851
|
+
* `409 flow_not_published`, `409 flow_archived`.
|
|
852
|
+
*/
|
|
853
|
+
flow?: string;
|
|
854
|
+
/** Pins the hosted-flow language. Omit to let the person's device decide. */
|
|
855
|
+
locale?: Locale;
|
|
856
|
+
/**
|
|
857
|
+
* Pre-choose the identity method when the flow offers a choice of identity
|
|
858
|
+
* method (the hosted choice screen is then skipped). Ignored otherwise.
|
|
859
|
+
*/
|
|
860
|
+
identityMethod?: IdentityMethod;
|
|
861
|
+
/**
|
|
862
|
+
* Session lifetime in minutes. Must fall within the flow's link range,
|
|
863
|
+
* otherwise the API answers `400 ttl_out_of_policy`. Omit to use the
|
|
864
|
+
* flow's default.
|
|
865
|
+
*/
|
|
866
|
+
ttlMinutes?: number;
|
|
867
|
+
/** Also send the hosted link to the person by SMS or WhatsApp. */
|
|
868
|
+
deliver?: DeliverOptions;
|
|
869
|
+
/**
|
|
870
|
+
* Where the hosted flow returns the person when the session ends
|
|
871
|
+
* ({@link SessionLinkInput}). A URL outside the app's web origins and app
|
|
872
|
+
* scheme answers `400 return_url_not_allowed`.
|
|
873
|
+
*/
|
|
874
|
+
link?: SessionLinkInput;
|
|
875
|
+
/**
|
|
876
|
+
* What you already know about the person (preferred over `input` for
|
|
877
|
+
* identity data).
|
|
878
|
+
*/
|
|
879
|
+
person?: SessionPersonInput;
|
|
880
|
+
/**
|
|
881
|
+
* Your own id for the agent filming the person, for flows whose liveness
|
|
882
|
+
* capture is `assisted` (1 to 128 characters). Stored as is and echoed on
|
|
883
|
+
* the session and in webhooks.
|
|
884
|
+
*/
|
|
885
|
+
assistedBy?: {
|
|
886
|
+
externalRef: string;
|
|
887
|
+
};
|
|
888
|
+
/**
|
|
889
|
+
* Override the flow for this session only ({@link FlowOverrides}): its
|
|
890
|
+
* general settings and per-service settings, or turn a service `'off'`.
|
|
891
|
+
* `400 override_invalid` for an unknown key or an invalid result;
|
|
892
|
+
* `403 override_widens_flow` for a change that makes the flow less strict
|
|
893
|
+
* when the flow does not allow widening.
|
|
894
|
+
*/
|
|
895
|
+
overrides?: FlowOverrides;
|
|
896
|
+
/**
|
|
897
|
+
* An open record of branch facts your flow's `input.<key>` conditions read.
|
|
898
|
+
* Person data goes in {@link CreateSessionInput.person}: `nni`, `phone`,
|
|
899
|
+
* `email`, `fullName`, `birthDate` or `suppliedIdentity` here answers
|
|
900
|
+
* `400 input_field_misplaced`.
|
|
901
|
+
*/
|
|
902
|
+
input?: Record<string, unknown>;
|
|
903
|
+
}
|
|
904
|
+
/** Per-request options. @public */
|
|
905
|
+
interface RequestOptions {
|
|
906
|
+
/**
|
|
907
|
+
* Sent as `X-Idempotency-Key`. Replaying the same key within 24 h returns the
|
|
908
|
+
* original response instead of creating a second session.
|
|
909
|
+
*/
|
|
910
|
+
idempotencyKey?: string;
|
|
911
|
+
}
|
|
912
|
+
/**
|
|
913
|
+
* Result of {@link SessionsApi.create}. `clientToken` is returned ONCE and never
|
|
914
|
+
* again — hand it to the browser (`@sekyro/web`) and do not persist it.
|
|
915
|
+
* @public
|
|
916
|
+
*/
|
|
917
|
+
interface CreatedSession {
|
|
918
|
+
id: string;
|
|
919
|
+
status: SessionStatus;
|
|
920
|
+
/** One-time credential for the client SDK / hosted flow. */
|
|
921
|
+
clientToken: string;
|
|
922
|
+
/** Hosted verification link for this session. */
|
|
923
|
+
hostedUrl: string;
|
|
924
|
+
/** The flow version the session runs (the default flow when you sent no `flow`). */
|
|
925
|
+
flow?: SessionFlowRef;
|
|
926
|
+
/** The checks on the session's path (checks of a lane not taken are omitted). */
|
|
927
|
+
steps: SessionStep[];
|
|
928
|
+
/** ISO 8601 — when the session (and its link) stop accepting input. */
|
|
929
|
+
expiresAt: string;
|
|
930
|
+
/** The levels the flow can reach on its paths; absent from older API versions. */
|
|
931
|
+
levelTarget?: LevelTarget;
|
|
932
|
+
/**
|
|
933
|
+
* How the flow uses the person data you sent: `reference` (believed, your
|
|
934
|
+
* record is the identity reference) or `prefill` (checked against the
|
|
935
|
+
* person's document or registry record). Absent from older API versions.
|
|
936
|
+
*/
|
|
937
|
+
subjectUse?: "reference" | "prefill";
|
|
938
|
+
/**
|
|
939
|
+
* With {@link CreateSessionInput.deliver} only: the send of the hosted link.
|
|
940
|
+
* `failed` never fails the create; `simulated` on a simulated Sandbox session.
|
|
941
|
+
*/
|
|
942
|
+
delivery?: {
|
|
943
|
+
status: "queued" | "failed" | "simulated";
|
|
944
|
+
};
|
|
945
|
+
}
|
|
946
|
+
/**
|
|
947
|
+
* Input of {@link PeopleApi.createSession}: a re-check or step-up session
|
|
948
|
+
* for an existing person in one call.
|
|
949
|
+
* @public
|
|
950
|
+
*/
|
|
951
|
+
interface PersonSessionInput {
|
|
952
|
+
mode: SubjectReuseMode;
|
|
953
|
+
/** The app's flow to run (slug or `flw_` id); absent = the app's default flow. */
|
|
954
|
+
flow?: string;
|
|
955
|
+
link?: SessionLinkInput;
|
|
956
|
+
/** Session lifetime in minutes, within the flow's link range. */
|
|
957
|
+
ttlMinutes?: number;
|
|
958
|
+
locale?: Locale;
|
|
959
|
+
}
|
|
960
|
+
/**
|
|
961
|
+
* Which person {@link PeopleApi.createSession} targets: the person id
|
|
962
|
+
* (`per_...` or the bare 24 hexadecimal characters) or your own external
|
|
963
|
+
* reference.
|
|
964
|
+
* @public
|
|
965
|
+
*/
|
|
966
|
+
type PersonSessionTarget = {
|
|
967
|
+
personId: string;
|
|
968
|
+
} | {
|
|
969
|
+
externalRef: string;
|
|
970
|
+
};
|
|
971
|
+
/** Result of {@link SessionsApi.resultToken}: a freshly signed result token. @public */
|
|
972
|
+
interface ResultTokenResponse {
|
|
973
|
+
/** ES256 JWT; check it with {@link verifyResultToken}. */
|
|
974
|
+
token: string;
|
|
975
|
+
/** ISO 8601: when the token expires (10 minutes after signing). */
|
|
976
|
+
expiresAt: string;
|
|
977
|
+
}
|
|
978
|
+
/**
|
|
979
|
+
* The end user's network at the start of the session (IP-derived, approximate).
|
|
980
|
+
* @public
|
|
981
|
+
*/
|
|
982
|
+
interface SessionNetworkEvent {
|
|
983
|
+
/** ISO 8601. */
|
|
984
|
+
at: string;
|
|
985
|
+
/** ISO 3166-1 alpha-2. */
|
|
986
|
+
country?: string;
|
|
987
|
+
region?: string;
|
|
988
|
+
city?: string;
|
|
989
|
+
asn?: number;
|
|
990
|
+
operator?: string;
|
|
991
|
+
connectionType: "mobile" | "hosting" | "unknown";
|
|
992
|
+
anonymizer: {
|
|
993
|
+
/** A known commercial VPN service exit. */
|
|
994
|
+
vpn: boolean;
|
|
995
|
+
/** A Tor exit. */
|
|
996
|
+
tor: boolean;
|
|
997
|
+
/** A cloud, hosting or data center network. */
|
|
998
|
+
hosting: boolean;
|
|
999
|
+
/** A public open proxy. Present only when true. */
|
|
1000
|
+
proxy?: boolean;
|
|
1001
|
+
/**
|
|
1002
|
+
* Apple iCloud Private Relay. A privacy relay for Apple accounts, not counted
|
|
1003
|
+
* as an anonymizer. Present only when true.
|
|
1004
|
+
*/
|
|
1005
|
+
relay?: boolean;
|
|
1006
|
+
};
|
|
1007
|
+
/** IANA time zone reported by the end user's device. */
|
|
1008
|
+
browserTimezone?: string;
|
|
1009
|
+
/** True when the device time zone does not belong to the IP country. */
|
|
1010
|
+
timezoneMismatch?: boolean;
|
|
1011
|
+
}
|
|
1012
|
+
/**
|
|
1013
|
+
* End-user network context; absent when not recorded.
|
|
1014
|
+
* @public
|
|
1015
|
+
*/
|
|
1016
|
+
interface SessionNetwork {
|
|
1017
|
+
/** The start event's IP address. Never sent in webhooks. */
|
|
1018
|
+
ip?: string;
|
|
1019
|
+
/** True when a later call came from a different country than the start. */
|
|
1020
|
+
countryChanged: boolean;
|
|
1021
|
+
start: SessionNetworkEvent;
|
|
1022
|
+
}
|
|
1023
|
+
/**
|
|
1024
|
+
* Device signals detected on the end user's device.
|
|
1025
|
+
* @public
|
|
1026
|
+
*/
|
|
1027
|
+
type SessionDeviceSignal = "webdriver" | "headless" | "emulator" | "rooted" | "jailbroken" | "debugger" | "hooking" | "virtual_camera";
|
|
1028
|
+
/**
|
|
1029
|
+
* End-user device summary; absent when not recorded.
|
|
1030
|
+
* @public
|
|
1031
|
+
*/
|
|
1032
|
+
interface SessionDevice {
|
|
1033
|
+
platform: "web" | "android" | "ios";
|
|
1034
|
+
sdk?: string;
|
|
1035
|
+
os?: string;
|
|
1036
|
+
osVersion?: string;
|
|
1037
|
+
browser?: string;
|
|
1038
|
+
browserVersion?: string;
|
|
1039
|
+
deviceClass: "mobile" | "tablet" | "desktop" | "unknown";
|
|
1040
|
+
model?: string;
|
|
1041
|
+
/**
|
|
1042
|
+
* Opaque device identity inside your organization and environment, stable across sessions
|
|
1043
|
+
* while the device keeps its install id. May be absent (for example without a device
|
|
1044
|
+
* header).
|
|
1045
|
+
*/
|
|
1046
|
+
deviceId?: string;
|
|
1047
|
+
/** Hashed device keys of this session, per organization. */
|
|
1048
|
+
deviceKeys: string[];
|
|
1049
|
+
signals: SessionDeviceSignal[];
|
|
1050
|
+
}
|
|
1051
|
+
/**
|
|
1052
|
+
* The national eID that verified the session's identity (the `eid_auth` check
|
|
1053
|
+
* passed): the provider id (`{country}.{provider}`, e.g. `MR.houwiyeti`), its
|
|
1054
|
+
* ISO 3166-1 alpha-2 country and when. A passed eID ends the session.
|
|
1055
|
+
* @public
|
|
1056
|
+
*/
|
|
1057
|
+
interface EidResult {
|
|
1058
|
+
provider: string;
|
|
1059
|
+
country: string;
|
|
1060
|
+
verifiedAt: string;
|
|
1061
|
+
}
|
|
1062
|
+
/**
|
|
1063
|
+
* The full phone number and email address the person verified in a session
|
|
1064
|
+
* (an OTP check that passed) — sent ONLY to you (the session view and your
|
|
1065
|
+
* webhooks), never to the person's browser, and removed when the session's
|
|
1066
|
+
* personal data is purged. You are the controller of these values. A
|
|
1067
|
+
* prefilled value that was not verified is never listed.
|
|
1068
|
+
* @public
|
|
1069
|
+
*/
|
|
1070
|
+
interface VerifiedContacts {
|
|
1071
|
+
/** From a passed `phone_otp` check. */
|
|
1072
|
+
phone?: {
|
|
1073
|
+
/** E.164 (`+` and the country code). */
|
|
1074
|
+
number: string;
|
|
1075
|
+
/** The channel the code was delivered on. */
|
|
1076
|
+
channel: "whatsapp" | "sms";
|
|
1077
|
+
/** ISO 8601. */
|
|
1078
|
+
verifiedAt: string;
|
|
1079
|
+
};
|
|
1080
|
+
/** From a passed `email_otp` check. */
|
|
1081
|
+
email?: {
|
|
1082
|
+
/** The verified address (domain lowercased). */
|
|
1083
|
+
address: string;
|
|
1084
|
+
/** ISO 8601. */
|
|
1085
|
+
verifiedAt: string;
|
|
1086
|
+
};
|
|
1087
|
+
}
|
|
1088
|
+
/**
|
|
1089
|
+
* Where a value of {@link Identity} comes from: the `document` (its machine
|
|
1090
|
+
* readable zone or printed text), the passport `chip`, the population
|
|
1091
|
+
* `registry`, a national `eid`, or the record you `supplied` at create.
|
|
1092
|
+
* @public
|
|
1093
|
+
*/
|
|
1094
|
+
type IdentitySource = "document" | "chip" | "registry" | "eid" | "supplied";
|
|
1095
|
+
/**
|
|
1096
|
+
* How a name of {@link Identity.names} was obtained: `mrz` (the ICAO
|
|
1097
|
+
* transliteration of the machine readable zone: upper case, truncated, no
|
|
1098
|
+
* diacritics), `printed` (the visual zone, as written), `chip` (the chip's
|
|
1099
|
+
* data groups), `registry`, `eid` or `supplied`.
|
|
1100
|
+
* @public
|
|
1101
|
+
*/
|
|
1102
|
+
type NameForm = "mrz" | "printed" | "chip" | "registry" | "eid" | "supplied";
|
|
1103
|
+
/**
|
|
1104
|
+
* One name as one source gives it. Names from different sources are never
|
|
1105
|
+
* merged. For an `mrz` entry `family` holds the ICAO primary identifier and
|
|
1106
|
+
* `given` the secondary one, as the document arranges them. To show a name,
|
|
1107
|
+
* pick the first entry whose `form` is not `mrz`.
|
|
1108
|
+
* @public
|
|
1109
|
+
*/
|
|
1110
|
+
interface IdentityName {
|
|
1111
|
+
/** ISO 15924 script, e.g. `Latn` or `Arab`. */
|
|
1112
|
+
script: string;
|
|
1113
|
+
form: NameForm;
|
|
1114
|
+
/** Given names (the secondary identifier). */
|
|
1115
|
+
given?: string;
|
|
1116
|
+
/** Family name (the primary identifier). */
|
|
1117
|
+
family?: string;
|
|
1118
|
+
/** The father's given name, when the source distinguishes it. */
|
|
1119
|
+
patronymic?: string;
|
|
1120
|
+
/** The name as one string, when the source gives one (never built from the parts). */
|
|
1121
|
+
fullName?: string;
|
|
1122
|
+
source: IdentitySource;
|
|
1123
|
+
}
|
|
1124
|
+
/** One birth place as one source wrote it ({@link Identity.birthPlace}). @public */
|
|
1125
|
+
interface IdentityBirthPlace {
|
|
1126
|
+
/** ISO 15924 script. */
|
|
1127
|
+
script: string;
|
|
1128
|
+
value: string;
|
|
1129
|
+
source: IdentitySource;
|
|
1130
|
+
}
|
|
1131
|
+
/** The holder's national number, when a per-country rule recognises it ({@link Identity.idNumber}). @public */
|
|
1132
|
+
interface IdentityIdNumber {
|
|
1133
|
+
type: "national_id" | "passport" | "residence_permit";
|
|
1134
|
+
/** ISO 3166-1 alpha-2. */
|
|
1135
|
+
issuingCountry: string;
|
|
1136
|
+
/** The number, normalised. */
|
|
1137
|
+
number: string;
|
|
1138
|
+
}
|
|
1139
|
+
/** The document or chip that was read ({@link Identity.document}). @public */
|
|
1140
|
+
interface IdentityDocument {
|
|
1141
|
+
type: "national_id" | "passport" | "residence_permit";
|
|
1142
|
+
/** ISO 3166-1 alpha-2, or the ICAO code as read when it has no ISO equivalent. */
|
|
1143
|
+
issuingCountry?: string;
|
|
1144
|
+
/** The document number as read: upper case, no spaces. */
|
|
1145
|
+
number?: string;
|
|
1146
|
+
/** `YYYY-MM-DD`. */
|
|
1147
|
+
expiryDate?: string;
|
|
1148
|
+
/** `YYYY-MM-DD`, from the chip. */
|
|
1149
|
+
issueDate?: string;
|
|
1150
|
+
/** The issuing authority as written, from the chip. */
|
|
1151
|
+
issuingAuthority?: string;
|
|
1152
|
+
/** The keys whose value a check digit protects. Never the names. */
|
|
1153
|
+
mrzVerified?: Array<"number" | "birthDate" | "expiryDate" | "idNumber">;
|
|
1154
|
+
}
|
|
1155
|
+
/**
|
|
1156
|
+
* The scalar keys of {@link Identity} that {@link Identity.sources} reports on.
|
|
1157
|
+
* @public
|
|
1158
|
+
*/
|
|
1159
|
+
type IdentityScalarKey = "idNumber" | "birthDate" | "sex" | "nationalities" | "document.number" | "document.expiryDate";
|
|
1160
|
+
/**
|
|
1161
|
+
* For each scalar key, the sources whose value equals the returned one. A
|
|
1162
|
+
* source that read another value is not listed (its step carries the mismatch
|
|
1163
|
+
* reason).
|
|
1164
|
+
* @public
|
|
1165
|
+
*/
|
|
1166
|
+
type IdentitySources = Partial<Record<IdentityScalarKey, IdentitySource[]>>;
|
|
1167
|
+
/**
|
|
1168
|
+
* The identity data a session read (its document, chip, registry, eID or your
|
|
1169
|
+
* supplied record), present once one identity step settled, whatever the
|
|
1170
|
+
* outcome. On a person ({@link Person.identity}), the identity of the latest
|
|
1171
|
+
* approved session that read one. Every key is optional. Sent to you only (the
|
|
1172
|
+
* session view, the person view and the terminal webhooks).
|
|
1173
|
+
* @public
|
|
1174
|
+
*/
|
|
1175
|
+
interface Identity {
|
|
1176
|
+
idNumber?: IdentityIdNumber;
|
|
1177
|
+
/** One entry per source and script, registry forms first. */
|
|
1178
|
+
names?: IdentityName[];
|
|
1179
|
+
/** ISO 8601 with the precision the source has: `YYYY-MM-DD`, `YYYY-MM` or `YYYY`. */
|
|
1180
|
+
birthDate?: string;
|
|
1181
|
+
birthPlace?: IdentityBirthPlace[];
|
|
1182
|
+
/** `null` when the source read an unspecified value; absent when no source read it. */
|
|
1183
|
+
sex?: "M" | "F" | "X" | null;
|
|
1184
|
+
/** ISO 3166-1 alpha-2 codes, or the ICAO code when it has no ISO equivalent. */
|
|
1185
|
+
nationalities?: string[];
|
|
1186
|
+
/** Set when the nationality code is not a country (e.g. `stateless`). */
|
|
1187
|
+
nationalityKind?: string;
|
|
1188
|
+
document?: IdentityDocument;
|
|
1189
|
+
sources?: IdentitySources;
|
|
1190
|
+
/** The registry a registry step passed against. */
|
|
1191
|
+
registry?: {
|
|
1192
|
+
id: string;
|
|
1193
|
+
fetchedAt?: string;
|
|
1194
|
+
};
|
|
1195
|
+
/** The national eID that verified the identity. */
|
|
1196
|
+
eid?: {
|
|
1197
|
+
provider: string;
|
|
1198
|
+
country: string;
|
|
1199
|
+
verifiedAt?: string;
|
|
1200
|
+
};
|
|
1201
|
+
/** ISO 8601: when the last identity step settled. */
|
|
1202
|
+
verifiedAt?: string;
|
|
1203
|
+
/** @deprecated Read {@link Identity.names}. The first Latin name as one string. */
|
|
1204
|
+
name?: string;
|
|
1205
|
+
}
|
|
1206
|
+
/**
|
|
1207
|
+
* The media kinds of a session, in the order the API lists them.
|
|
1208
|
+
* `reference_portrait` is the photo the face match compared against.
|
|
1209
|
+
* @public
|
|
1210
|
+
*/
|
|
1211
|
+
type MediaKind = "icao_portrait" | "document_front" | "document_back" | "document_portrait" | "chip_portrait" | "reference_portrait" | "supplied_photo" | "selfie" | "liveness_clip";
|
|
1212
|
+
/**
|
|
1213
|
+
* One media object of a session ({@link SessionsApi.media}). `url` is a
|
|
1214
|
+
* download link valid 15 minutes, or the bytes route on this API
|
|
1215
|
+
* (`/api/v2/sessions/{id}/media/{kind}`), which needs your key: read it with
|
|
1216
|
+
* {@link SessionsApi.mediaBytes}. Never store the URL.
|
|
1217
|
+
* @public
|
|
1218
|
+
*/
|
|
1219
|
+
interface MediaItem {
|
|
1220
|
+
kind: MediaKind;
|
|
1221
|
+
/** The check that produced or used it. */
|
|
1222
|
+
check: string;
|
|
1223
|
+
/** The attempt it came from (1, 2, ...); absent when it is not per attempt. */
|
|
1224
|
+
attempt?: number;
|
|
1225
|
+
/** It belongs to the attempt that settled the check. */
|
|
1226
|
+
decisive: boolean;
|
|
1227
|
+
/** The state of that attempt, else of the check. */
|
|
1228
|
+
state?: string;
|
|
1229
|
+
/** The reason of that attempt, when it did not pass. */
|
|
1230
|
+
reason?: string;
|
|
1231
|
+
/** The attempt was set aside (for example a retake) and not counted. */
|
|
1232
|
+
voided?: string;
|
|
1233
|
+
contentType: "image/jpeg" | "image/png" | "video/mp4" | "video/webm";
|
|
1234
|
+
/** `reference_portrait` and `supplied_photo`: where the photo came from (`stored`: kept from an earlier verification). */
|
|
1235
|
+
source?: "registry" | "eid" | "chip" | "document" | "supplied" | "stored";
|
|
1236
|
+
/** `reference_portrait`: the registry photo was fetched again for this match. */
|
|
1237
|
+
refreshed?: true;
|
|
1238
|
+
url: string;
|
|
1239
|
+
/** ISO 8601: when `url` expires. List the media again for fresh links. */
|
|
1240
|
+
expiresAt: string;
|
|
1241
|
+
}
|
|
1242
|
+
/** Result of {@link SessionsApi.media}. @public */
|
|
1243
|
+
interface MediaList {
|
|
1244
|
+
items: MediaItem[];
|
|
1245
|
+
}
|
|
1246
|
+
/** Options of {@link SessionsApi.mediaBytes}. @public */
|
|
1247
|
+
interface MediaBytesOptions {
|
|
1248
|
+
/** The attempt (1, 2, ...) to read; default: the decisive item, else the latest attempt. */
|
|
1249
|
+
attempt?: number;
|
|
1250
|
+
/** `reference_portrait` only: the first reference, when a second one decided the step. */
|
|
1251
|
+
reference?: "first";
|
|
1252
|
+
}
|
|
1253
|
+
/** Result of {@link SessionsApi.mediaBytes}: the bytes and their media type. @public */
|
|
1254
|
+
interface MediaBytes {
|
|
1255
|
+
contentType: string;
|
|
1256
|
+
bytes: Uint8Array;
|
|
1257
|
+
}
|
|
1258
|
+
/**
|
|
1259
|
+
* Who closed a completed or failed session: `review` when a person decided
|
|
1260
|
+
* the verdict (the deciding step carries its {@link SessionStepDecision}),
|
|
1261
|
+
* `automatic` otherwise (a review deadline included).
|
|
1262
|
+
* @public
|
|
1263
|
+
*/
|
|
1264
|
+
type DecidedBy = "automatic" | "review";
|
|
1265
|
+
/**
|
|
1266
|
+
* The whitelisted session view returned by {@link SessionsApi.get}. Never
|
|
1267
|
+
* contains the client token.
|
|
1268
|
+
* @public
|
|
1269
|
+
*/
|
|
1270
|
+
interface Session {
|
|
1271
|
+
id: string;
|
|
1272
|
+
/** Sekyro flows: the flow version the session runs (absent on sessions created before flows). */
|
|
1273
|
+
flow?: SessionFlowRef;
|
|
1274
|
+
status: SessionStatus;
|
|
1275
|
+
outcome: SessionOutcome | null;
|
|
1276
|
+
/** Completed and failed sessions: who decided the verdict ({@link DecidedBy}). */
|
|
1277
|
+
decidedBy?: DecidedBy;
|
|
1278
|
+
/**
|
|
1279
|
+
* A session closed because a newer attempt of the same person took over its
|
|
1280
|
+
* review: that session's id (`outcome` is `null`). Watch it instead.
|
|
1281
|
+
*/
|
|
1282
|
+
supersededBy?: string;
|
|
1283
|
+
/**
|
|
1284
|
+
* What the session proved ({@link VerificationLevel}), on a completed or
|
|
1285
|
+
* failed session: `0` when it was rejected. Absent while the session is
|
|
1286
|
+
* active, and from older API versions.
|
|
1287
|
+
*/
|
|
1288
|
+
level?: VerificationLevel | null;
|
|
1289
|
+
/** How the level was proved; `null` while the session is active. */
|
|
1290
|
+
assurance?: VerificationAssurance | null;
|
|
1291
|
+
/** The billing unit the session consumed; `null` while the session is active. */
|
|
1292
|
+
unit?: VerificationUnit | null;
|
|
1293
|
+
/** The levels the session's flow can reach. */
|
|
1294
|
+
levelTarget?: LevelTarget;
|
|
1295
|
+
/** The checks on the session's path (checks of a lane the person did not take are omitted). */
|
|
1296
|
+
steps: SessionStep[];
|
|
1297
|
+
/** ISO 8601. */
|
|
1298
|
+
expiresAt: string;
|
|
1299
|
+
/** ISO 8601. Absent on a session view that does not carry it. */
|
|
1300
|
+
createdAt?: string;
|
|
1301
|
+
/** ISO 8601: when the session reached a terminal state; `null` while it is active. */
|
|
1302
|
+
completedAt?: string | null;
|
|
1303
|
+
/** End-user network context; absent when not recorded. */
|
|
1304
|
+
network?: SessionNetwork;
|
|
1305
|
+
/** End-user device; absent when not recorded. */
|
|
1306
|
+
device?: SessionDevice;
|
|
1307
|
+
/**
|
|
1308
|
+
* Set when a profile-v2 policy ended the session: a session-level gate
|
|
1309
|
+
* (location, anonymizer) or a failed check's policy reason (eligibility,
|
|
1310
|
+
* `document_nni_mismatch`). Absent otherwise.
|
|
1311
|
+
*/
|
|
1312
|
+
failureReason?: PolicyFailureReason;
|
|
1313
|
+
/** With failureReason `camera_unavailable`: why (`denied` or `no_camera`), when the SDK said. Absent otherwise. */
|
|
1314
|
+
failureDetail?: CameraUnavailableCause;
|
|
1315
|
+
/** The person (`per_...`) this session is linked to, once that person has passed a verification (absent before that). */
|
|
1316
|
+
personId?: string;
|
|
1317
|
+
/** Your own id for the person, from `person.externalRef` at create. */
|
|
1318
|
+
externalRef?: string;
|
|
1319
|
+
/** The agent reference sent as `assistedBy` at create, for assisted capture. */
|
|
1320
|
+
assistedBy?: {
|
|
1321
|
+
externalRef: string;
|
|
1322
|
+
};
|
|
1323
|
+
/**
|
|
1324
|
+
* `true` when an identifier this session read already belongs to a
|
|
1325
|
+
* different person than `personId`: the people are never merged.
|
|
1326
|
+
*/
|
|
1327
|
+
personConflict?: boolean;
|
|
1328
|
+
/**
|
|
1329
|
+
* ISO 8601 — when the end user's device may verify again; set with
|
|
1330
|
+
* `failureReason: 'device_cooldown'`.
|
|
1331
|
+
*/
|
|
1332
|
+
retryAfter?: string;
|
|
1333
|
+
/**
|
|
1334
|
+
* Dotted paths this session's {@link CreateSessionInput.overrides} changed
|
|
1335
|
+
* (e.g. `settings.decisions.mode`, `services.liveness`).
|
|
1336
|
+
*/
|
|
1337
|
+
overriddenFields?: string[];
|
|
1338
|
+
/**
|
|
1339
|
+
* Risk signals recorded on the session (e.g. `device_velocity`,
|
|
1340
|
+
* `timezone_mismatch`, `icao_non_compliant` when an `alert` ICAO policy flagged
|
|
1341
|
+
* the selfie, `document_uploaded` and the `document_upload_*` signals when the
|
|
1342
|
+
* person uploaded a photo of the document) — signals only, never a verdict by themselves.
|
|
1343
|
+
*/
|
|
1344
|
+
riskSignals?: string[];
|
|
1345
|
+
/**
|
|
1346
|
+
* `true` for a returning-user session (created with
|
|
1347
|
+
* {@link SessionPersonInput.reuse}): liveness + face match against the
|
|
1348
|
+
* subject's stored reference photo only.
|
|
1349
|
+
*/
|
|
1350
|
+
returning?: true;
|
|
1351
|
+
/** On a returning-user session: the subject (person) it re-verifies. */
|
|
1352
|
+
reuseOf?: string;
|
|
1353
|
+
/**
|
|
1354
|
+
* On a session created for an existing subject: `recheck` (the same person
|
|
1355
|
+
* again) or `step_up` (raised to identity level). Absent otherwise.
|
|
1356
|
+
*/
|
|
1357
|
+
reuseMode?: SubjectReuseMode;
|
|
1358
|
+
/** The contacts verified in this session (passed OTP checks only); absent when none. */
|
|
1359
|
+
verifiedContacts?: VerifiedContacts;
|
|
1360
|
+
/**
|
|
1361
|
+
* When the flow sets a minimum age and the session proved it: the threshold
|
|
1362
|
+
* and how it was proved ({@link AgeResult}). Absent otherwise.
|
|
1363
|
+
*/
|
|
1364
|
+
age?: AgeResult;
|
|
1365
|
+
/**
|
|
1366
|
+
* The identity data the session read ({@link Identity}), once one identity
|
|
1367
|
+
* step settled. On an approved returning-user session, with a key that also
|
|
1368
|
+
* holds `people:read`, the identity stored on the person.
|
|
1369
|
+
*/
|
|
1370
|
+
identity?: Identity;
|
|
1371
|
+
/** The media kinds this session has, in kind order: fetch them with {@link SessionsApi.media}. */
|
|
1372
|
+
media?: MediaKind[];
|
|
1373
|
+
/**
|
|
1374
|
+
* Terminal sessions, when result tokens are on: a signed result token
|
|
1375
|
+
* (ES256 JWT, valid 10 minutes). Check it with {@link verifyResultToken}.
|
|
1376
|
+
*/
|
|
1377
|
+
resultToken?: string;
|
|
1378
|
+
/** Terminal sessions: other people the face matched in the duplicate search (non-empty only). */
|
|
1379
|
+
duplicates?: ResultDuplicate[];
|
|
1380
|
+
/** Terminal sessions: the duplicate search could not run. */
|
|
1381
|
+
dedupUnavailable?: true;
|
|
1382
|
+
/**
|
|
1383
|
+
* Terminal sessions: a failure identification match
|
|
1384
|
+
* ({@link FailureIdentification}), present only for a match and only when the
|
|
1385
|
+
* setting is on. A signal, never a decision.
|
|
1386
|
+
*/
|
|
1387
|
+
failureIdentification?: FailureIdentification;
|
|
1388
|
+
/**
|
|
1389
|
+
* Terminal sessions whose flow screens the person against sanctions and PEP
|
|
1390
|
+
* lists: the result ({@link SessionScreening}), or why it could not run.
|
|
1391
|
+
*/
|
|
1392
|
+
screening?: SessionScreening;
|
|
1393
|
+
}
|
|
1394
|
+
/**
|
|
1395
|
+
* `data` of the session lifecycle events (`session.started` |
|
|
1396
|
+
* `session.review_pending` | `session.completed` | `session.failed` |
|
|
1397
|
+
* `session.expired`). `outcome`, `decidedBy` and `steps` travel on
|
|
1398
|
+
* `completed` / `failed`, which are the one terminal event of a session: a
|
|
1399
|
+
* reviewer's decision arrives as one of them with `decidedBy: "review"` and
|
|
1400
|
+
* the `decision`. `review_pending` carries `steps` without an outcome;
|
|
1401
|
+
* `expired` carries the status and the session's refs (`flow`, person ids,
|
|
1402
|
+
* `overriddenFields`). `identity` and `media` (kinds only, never links) ride on
|
|
1403
|
+
* `completed` / `failed` when the platform sends them.
|
|
1404
|
+
* @public
|
|
1405
|
+
*/
|
|
1406
|
+
interface SessionLifecycleEventData {
|
|
1407
|
+
/** The session id (`ses_...`). */
|
|
1408
|
+
sessionId: string;
|
|
1409
|
+
status: SessionStatus;
|
|
1410
|
+
outcome?: SessionOutcome | null;
|
|
1411
|
+
/** On `completed` / `failed`: who decided the verdict ({@link DecidedBy}). */
|
|
1412
|
+
decidedBy?: DecidedBy;
|
|
1413
|
+
/** On `completed` / `failed` with `decidedBy: "review"`: how the deciding step was decided. */
|
|
1414
|
+
decision?: SessionStepDecision;
|
|
1415
|
+
/** On `completed` / `failed`: the app the session belongs to. */
|
|
1416
|
+
appId?: string;
|
|
1417
|
+
/** On `completed` / `failed`: what the session proved ({@link VerificationLevel}). */
|
|
1418
|
+
level?: VerificationLevel | null;
|
|
1419
|
+
/** On `completed` / `failed`: how the level was proved. */
|
|
1420
|
+
assurance?: VerificationAssurance | null;
|
|
1421
|
+
/** On `completed` / `failed`: the billing unit the session consumed. */
|
|
1422
|
+
unit?: VerificationUnit | null;
|
|
1423
|
+
/** On `completed` / `failed`: ISO 8601 terminal time. */
|
|
1424
|
+
verifiedAt?: string;
|
|
1425
|
+
/** On `completed` / `failed`: device and network risk facts, when recorded. */
|
|
1426
|
+
risk?: ResultRisk;
|
|
1427
|
+
/** On `completed` / `failed`: other subjects the face matched, when a duplicate search ran. */
|
|
1428
|
+
duplicates?: ResultDuplicate[];
|
|
1429
|
+
/**
|
|
1430
|
+
* On `completed` / `failed`: the signed result token (ES256 JWT, valid
|
|
1431
|
+
* 10 minutes). Check it with {@link verifyResultToken}; absent when
|
|
1432
|
+
* result tokens are not enabled.
|
|
1433
|
+
*/
|
|
1434
|
+
resultToken?: string;
|
|
1435
|
+
/** On `completed` / `failed`: the duplicate search could not run. */
|
|
1436
|
+
dedupUnavailable?: true;
|
|
1437
|
+
/**
|
|
1438
|
+
* The checks on the session's path (checks of a lane the person did not take
|
|
1439
|
+
* are omitted), each with its {@link SessionStepDecision} when a person decided it.
|
|
1440
|
+
*/
|
|
1441
|
+
steps?: Array<Pick<SessionStep, "id" | "service" | "state" | "simulated" | "decision">>;
|
|
1442
|
+
/** Sekyro flows: the flow version the session runs (absent on sessions created before flows). */
|
|
1443
|
+
flow?: SessionFlowRef;
|
|
1444
|
+
/** Machine-readable reason, when the transition has one. */
|
|
1445
|
+
reason?: string;
|
|
1446
|
+
/** End-user network context (no IP); on `completed` / `failed` when recorded. */
|
|
1447
|
+
network?: Omit<SessionNetwork, "ip">;
|
|
1448
|
+
/** End-user device; on `completed` / `failed` when recorded. */
|
|
1449
|
+
device?: SessionDevice;
|
|
1450
|
+
/**
|
|
1451
|
+
* On `session.failed`: set when a profile-v2 policy ended the session — a
|
|
1452
|
+
* session-level gate (location, anonymizer) or a failed check's policy
|
|
1453
|
+
* reason (eligibility, `document_nni_mismatch`).
|
|
1454
|
+
*/
|
|
1455
|
+
failureReason?: PolicyFailureReason;
|
|
1456
|
+
/** On `session.failed` with failureReason `camera_unavailable`: why (`denied` or `no_camera`), when the SDK said. Absent otherwise. */
|
|
1457
|
+
failureDetail?: CameraUnavailableCause;
|
|
1458
|
+
/** The person (`per_...`) the session is linked to, once that person has passed a verification (absent before that). */
|
|
1459
|
+
personId?: string;
|
|
1460
|
+
/** Your own id for the person, from `person.externalRef` at create. */
|
|
1461
|
+
externalRef?: string;
|
|
1462
|
+
/** The agent reference sent as `assistedBy` at create, for assisted capture. */
|
|
1463
|
+
assistedBy?: {
|
|
1464
|
+
externalRef: string;
|
|
1465
|
+
};
|
|
1466
|
+
/**
|
|
1467
|
+
* `true` when an identifier this session read already belongs to a
|
|
1468
|
+
* different person than `personId`: the people are never merged.
|
|
1469
|
+
*/
|
|
1470
|
+
personConflict?: boolean;
|
|
1471
|
+
/** `true` on a returning-user session (liveness + face match against the stored photo). */
|
|
1472
|
+
returning?: true;
|
|
1473
|
+
/** On a returning-user session: the person (`per_...`) it re-verifies. */
|
|
1474
|
+
reuseOf?: string;
|
|
1475
|
+
/**
|
|
1476
|
+
* On a session created for an existing person: `recheck` (the same person
|
|
1477
|
+
* again) or `step_up` (raised to identity level). Absent otherwise.
|
|
1478
|
+
*/
|
|
1479
|
+
reuseMode?: SubjectReuseMode;
|
|
1480
|
+
/**
|
|
1481
|
+
* On `completed` / `failed`: the `link.state` the session was created
|
|
1482
|
+
* with, echoed back; absent when the session had none.
|
|
1483
|
+
*/
|
|
1484
|
+
link?: {
|
|
1485
|
+
state: string;
|
|
1486
|
+
};
|
|
1487
|
+
/**
|
|
1488
|
+
* On `session.failed` with `failureReason: 'device_cooldown'`: ISO time
|
|
1489
|
+
* from which the device may start a new verification.
|
|
1490
|
+
*/
|
|
1491
|
+
retryAfter?: string;
|
|
1492
|
+
/** Dotted paths the session's create-time {@link CreateSessionInput.overrides} changed. */
|
|
1493
|
+
overriddenFields?: string[];
|
|
1494
|
+
/** On `completed` / `failed`: the contacts verified in this session (passed OTP checks only). */
|
|
1495
|
+
verifiedContacts?: VerifiedContacts;
|
|
1496
|
+
/** On `completed` / `failed`: the minimum age the session proved and how ({@link AgeResult}), when the flow sets one. */
|
|
1497
|
+
age?: AgeResult;
|
|
1498
|
+
/** On `completed` / `failed`: the identity data the session read ({@link Identity}), when the platform sends it. */
|
|
1499
|
+
identity?: Identity;
|
|
1500
|
+
/** On `completed` / `failed`: the media kinds of the session (never links), when the platform sends them. */
|
|
1501
|
+
media?: MediaKind[];
|
|
1502
|
+
/**
|
|
1503
|
+
* On `completed` / `failed`: a failure identification match
|
|
1504
|
+
* ({@link FailureIdentification}), when the setting is on and the search
|
|
1505
|
+
* found one before the event was sent. A signal, never a decision.
|
|
1506
|
+
*/
|
|
1507
|
+
failureIdentification?: FailureIdentification;
|
|
1508
|
+
/** On `completed` / `failed`: the AML screening result ({@link SessionScreening}), when the flow screens the person. */
|
|
1509
|
+
screening?: SessionScreening;
|
|
1510
|
+
}
|
|
1511
|
+
/**
|
|
1512
|
+
* `data` of `person.updated`: either a session linked to the person reached
|
|
1513
|
+
* a terminal state (`sessionId`, session `status`, `outcome`), or the person
|
|
1514
|
+
* was revoked (`status: 'revoked'`, no session). Ids and enums only.
|
|
1515
|
+
* @public
|
|
1516
|
+
*/
|
|
1517
|
+
interface PersonUpdatedEventData {
|
|
1518
|
+
/** The person (`per_...`). */
|
|
1519
|
+
personId: string;
|
|
1520
|
+
/** The session that reached a terminal state; absent on a revocation. */
|
|
1521
|
+
sessionId?: string;
|
|
1522
|
+
status: SessionStatus | "revoked";
|
|
1523
|
+
/** The session outcome; absent on a revocation. */
|
|
1524
|
+
outcome?: SessionOutcome | null;
|
|
1525
|
+
/** The session's level; absent on a revocation. */
|
|
1526
|
+
level?: VerificationLevel | null;
|
|
1527
|
+
/** The session's assurance; absent on a revocation. */
|
|
1528
|
+
assurance?: VerificationAssurance | null;
|
|
1529
|
+
/**
|
|
1530
|
+
* Your own ids for the person (`person.externalRef` values), so a
|
|
1531
|
+
* revocation can find your user without a lookup.
|
|
1532
|
+
*/
|
|
1533
|
+
externalRefs?: string[];
|
|
1534
|
+
}
|
|
1535
|
+
/**
|
|
1536
|
+
* `data` of `person.enrolled`: the person's first reference photo was
|
|
1537
|
+
* stored (it can now be used for returning-user sessions). Ids and enums only.
|
|
1538
|
+
* @public
|
|
1539
|
+
*/
|
|
1540
|
+
interface PersonEnrolledEventData {
|
|
1541
|
+
/** The person (`per_...`). */
|
|
1542
|
+
personId: string;
|
|
1543
|
+
/** The approved session the reference photo came from. */
|
|
1544
|
+
sessionId: string;
|
|
1545
|
+
assurance: SubjectAssurance;
|
|
1546
|
+
}
|
|
1547
|
+
/**
|
|
1548
|
+
* `data` of `person.deleted`. A delete through the people API carries
|
|
1549
|
+
* `personId`; a right-to-erasure request carries the tokenized `subjectRef`
|
|
1550
|
+
* (with `orgId` / `env`), and `personId` when it named exactly one person, never
|
|
1551
|
+
* the national number.
|
|
1552
|
+
* @public
|
|
1553
|
+
*/
|
|
1554
|
+
interface PersonDeletedEventData {
|
|
1555
|
+
personId?: string;
|
|
1556
|
+
subjectRef?: string;
|
|
1557
|
+
orgId?: string;
|
|
1558
|
+
env?: SekyroEnvironment;
|
|
1559
|
+
/**
|
|
1560
|
+
* On a delete through the people API: your own ids for the person, so you
|
|
1561
|
+
* can find your user. Never on the erasure variant.
|
|
1562
|
+
*/
|
|
1563
|
+
externalRefs?: string[];
|
|
1564
|
+
}
|
|
1565
|
+
/** Subject lifecycle: a revoked subject cannot be reused. @public */
|
|
1566
|
+
type SubjectStatus = "active" | "revoked";
|
|
1567
|
+
/**
|
|
1568
|
+
* How strongly a subject's identity was established: the reference photo
|
|
1569
|
+
* came from the national registry, the document's chip (`chip_biometric`, a
|
|
1570
|
+
* passed chip read plus a face match) or the document, and a face match passed
|
|
1571
|
+
* (`*_biometric`) or the session had no face match (`*_only`). `supplied_*`:
|
|
1572
|
+
* partner-supplied identity data (`input.suppliedIdentity`), with
|
|
1573
|
+
* (`supplied_biometric`) or without (`supplied_only`) a face match against its photo.
|
|
1574
|
+
* @public
|
|
1575
|
+
*/
|
|
1576
|
+
type SubjectAssurance = "registry_biometric" | "chip_biometric" | "document_biometric" | "registry_only" | "document_only" | "supplied_biometric" | "supplied_only";
|
|
1577
|
+
/**
|
|
1578
|
+
* Origin of a subject's stored reference photo, best first (`chip`: the document chip's portrait;
|
|
1579
|
+
* `org_supplied`: the photo of your partner-supplied identity data).
|
|
1580
|
+
* @public
|
|
1581
|
+
*/
|
|
1582
|
+
type SubjectReferenceSource = "registry" | "doc_registry" | "chip" | "org_supplied" | "document";
|
|
1583
|
+
/** One session linked to a person. @public */
|
|
1584
|
+
interface PersonSession {
|
|
1585
|
+
/** The session id (`ses_...`). */
|
|
1586
|
+
sessionId: string;
|
|
1587
|
+
appId: string | null;
|
|
1588
|
+
/** ISO 8601 — when the session was linked. */
|
|
1589
|
+
at: string;
|
|
1590
|
+
status: SessionStatus;
|
|
1591
|
+
outcome: SessionOutcome | null;
|
|
1592
|
+
/** What the session proved; present only when stored (sessions linked before the field existed have none). */
|
|
1593
|
+
level?: VerificationLevel;
|
|
1594
|
+
/** How the session's level was proved; present only when stored. */
|
|
1595
|
+
assurance?: VerificationAssurance;
|
|
1596
|
+
}
|
|
1597
|
+
/**
|
|
1598
|
+
* A person (the same person across your apps), as `GET /people/:id`
|
|
1599
|
+
* returns it. Never contains photo keys or URLs.
|
|
1600
|
+
* @public
|
|
1601
|
+
*/
|
|
1602
|
+
interface Person {
|
|
1603
|
+
/** The person id (`per_...`). */
|
|
1604
|
+
id: string;
|
|
1605
|
+
/** The same value as `id`. Absent from older API versions. */
|
|
1606
|
+
personId?: string;
|
|
1607
|
+
status: SubjectStatus;
|
|
1608
|
+
/** ISO 8601 — present only when revoked. */
|
|
1609
|
+
revokedAt?: string;
|
|
1610
|
+
sessions: PersonSession[];
|
|
1611
|
+
externalRefs: string[];
|
|
1612
|
+
/** ISO 8601. */
|
|
1613
|
+
firstSeenAt: string;
|
|
1614
|
+
/** ISO 8601. */
|
|
1615
|
+
lastSeenAt: string;
|
|
1616
|
+
/** ISO 8601, or `null` before the first approved session. */
|
|
1617
|
+
lastPassedAt: string | null;
|
|
1618
|
+
/** ISO 8601 of the last approved full or returning session, or `null`. */
|
|
1619
|
+
lastVerifiedAt: string | null;
|
|
1620
|
+
/** The stored reference photo's origin and date — `null` until one is stored. */
|
|
1621
|
+
reference: {
|
|
1622
|
+
source: SubjectReferenceSource;
|
|
1623
|
+
capturedAt: string;
|
|
1624
|
+
} | null;
|
|
1625
|
+
assurance: SubjectAssurance | null;
|
|
1626
|
+
/**
|
|
1627
|
+
* The highest {@link VerificationLevel} an approved linked session proved;
|
|
1628
|
+
* `0` once the subject is revoked; `null` when no terminal session was
|
|
1629
|
+
* recorded since the field exists. Absent from API versions before the field.
|
|
1630
|
+
*/
|
|
1631
|
+
level?: VerificationLevel | null | undefined;
|
|
1632
|
+
/** ISO 8601: when {@link Person.level} was last proved (the latest approved session at that level or higher); `null` with it. Absent with it. */
|
|
1633
|
+
levelAt?: string | null | undefined;
|
|
1634
|
+
/** The assurance of the session that proved {@link Person.level}; `null` with it. Absent with it. */
|
|
1635
|
+
levelAssurance?: VerificationAssurance | null | undefined;
|
|
1636
|
+
/**
|
|
1637
|
+
* A returning-user session can be created now: active, a reference photo is
|
|
1638
|
+
* stored, and the last FULL verification (returning-user sessions do not
|
|
1639
|
+
* reset it) is within the returning-user limit of your app's default flow
|
|
1640
|
+
* (`settings.returning`: turned on, and `maxAgeMonths` when set).
|
|
1641
|
+
*/
|
|
1642
|
+
returningReady: boolean;
|
|
1643
|
+
/** The verified name / birth date of the latest approved session. */
|
|
1644
|
+
display?: {
|
|
1645
|
+
name?: string;
|
|
1646
|
+
birthDate?: string;
|
|
1647
|
+
};
|
|
1648
|
+
/** The identity of the latest approved session that read one ({@link Identity}). */
|
|
1649
|
+
identity?: Identity;
|
|
1650
|
+
}
|
|
1651
|
+
/**
|
|
1652
|
+
* Filters of {@link SessionsApi.list}, {@link SessionsApi.listPage} and
|
|
1653
|
+
* {@link SessionsApi.iterate}, combined with AND. Newest first.
|
|
1654
|
+
* @public
|
|
1655
|
+
*/
|
|
1656
|
+
interface ListSessionsQuery {
|
|
1657
|
+
/** Your own id for the person (1 to 128 characters), exact match. */
|
|
1658
|
+
externalRef?: string;
|
|
1659
|
+
status?: SessionStatus;
|
|
1660
|
+
/** A flow id (`flw_...`) or slug. */
|
|
1661
|
+
flow?: string;
|
|
1662
|
+
/** Sessions created at or after this time (ISO 8601 or a `Date`). */
|
|
1663
|
+
createdAfter?: string | Date;
|
|
1664
|
+
/** Sessions created before this time (ISO 8601 or a `Date`). */
|
|
1665
|
+
createdBefore?: string | Date;
|
|
1666
|
+
/** Only the sessions of this device (`device.deviceId` of a session). */
|
|
1667
|
+
deviceId?: string;
|
|
1668
|
+
/** Page size, 1 to 100 (the API's default is 50). */
|
|
1669
|
+
limit?: number;
|
|
1670
|
+
/** The {@link Page.nextCursor} of the previous page. */
|
|
1671
|
+
cursor?: string;
|
|
1672
|
+
}
|
|
1673
|
+
/**
|
|
1674
|
+
* What a block holds, as {@link BlocksApi.list} shows it. `face` blocks are made in the dashboard.
|
|
1675
|
+
* @public
|
|
1676
|
+
*/
|
|
1677
|
+
type BlockKind = "id_number" | "external_ref" | "phone" | "email" | "device" | "face";
|
|
1678
|
+
/** Why a block exists. `rule`: an automatic rule made it. @public */
|
|
1679
|
+
type BlockReason = "fraud_confirmed" | "chargeback" | "abuse" | "test" | "rule" | "other";
|
|
1680
|
+
/** How long a block lasts; `null` has no end. @public */
|
|
1681
|
+
type BlockDuration = "P1D" | "P7D" | "P30D" | null;
|
|
1682
|
+
/**
|
|
1683
|
+
* A block on one key of this environment. Never a value or a hash.
|
|
1684
|
+
* @public
|
|
1685
|
+
*/
|
|
1686
|
+
interface Block {
|
|
1687
|
+
/** `blk_...` */
|
|
1688
|
+
id: string;
|
|
1689
|
+
kind: BlockKind;
|
|
1690
|
+
/** Four characters derived from the key, to tell blocks apart. */
|
|
1691
|
+
label: string;
|
|
1692
|
+
/** The device, on a device block. */
|
|
1693
|
+
deviceId?: string;
|
|
1694
|
+
effect: "block" | "flag" | "review";
|
|
1695
|
+
reason: BlockReason;
|
|
1696
|
+
/** When it ends; `null` has no end. */
|
|
1697
|
+
expiresAt: string | null;
|
|
1698
|
+
createdAt: string;
|
|
1699
|
+
status: "active" | "lifted" | "expired";
|
|
1700
|
+
/** `rul_...`: the rule that made it, on a block made by a rule. Such a block has no end date. */
|
|
1701
|
+
ruleId?: string;
|
|
1702
|
+
/** The version of that rule when it made the block. */
|
|
1703
|
+
ruleVersion?: number;
|
|
1704
|
+
liftedAt?: string;
|
|
1705
|
+
}
|
|
1706
|
+
/** An ID number as a document shows it. Hashed by the API, never stored. @public */
|
|
1707
|
+
interface BlockIdNumber {
|
|
1708
|
+
number: string;
|
|
1709
|
+
/** ISO 3166-1 alpha-2 or alpha-3 code of the issuer. */
|
|
1710
|
+
issuingCountry: string;
|
|
1711
|
+
type: "national_id" | "passport" | "residence_permit";
|
|
1712
|
+
}
|
|
1713
|
+
/**
|
|
1714
|
+
* What to block, with `sekyro.blocks.create`. `value` carries `external_ref`, `phone` and
|
|
1715
|
+
* `email`; `person` blocks each ID number of the person and answers a list.
|
|
1716
|
+
* @public
|
|
1717
|
+
*/
|
|
1718
|
+
type CreateBlockInput = {
|
|
1719
|
+
expiresIn: BlockDuration;
|
|
1720
|
+
reason?: Exclude<BlockReason, "rule">;
|
|
1721
|
+
/** Your note. It stays on your dashboard. */
|
|
1722
|
+
note?: string;
|
|
1723
|
+
} & ({
|
|
1724
|
+
kind: "external_ref" | "phone" | "email";
|
|
1725
|
+
value: string;
|
|
1726
|
+
} | {
|
|
1727
|
+
kind: "id_number";
|
|
1728
|
+
idNumber: BlockIdNumber;
|
|
1729
|
+
} | {
|
|
1730
|
+
kind: "person";
|
|
1731
|
+
personId: string;
|
|
1732
|
+
} | ({
|
|
1733
|
+
kind: "device";
|
|
1734
|
+
force?: boolean;
|
|
1735
|
+
} & ({
|
|
1736
|
+
deviceId: string;
|
|
1737
|
+
} | {
|
|
1738
|
+
sessionId: string;
|
|
1739
|
+
})));
|
|
1740
|
+
/** What to look up, with {@link BlocksApi.check}. @public */
|
|
1741
|
+
type BlockCheckInput = {
|
|
1742
|
+
kind: "external_ref" | "phone" | "email";
|
|
1743
|
+
value: string;
|
|
1744
|
+
} | {
|
|
1745
|
+
kind: "id_number";
|
|
1746
|
+
idNumber: BlockIdNumber;
|
|
1747
|
+
} | {
|
|
1748
|
+
kind: "person";
|
|
1749
|
+
personId: string;
|
|
1750
|
+
} | {
|
|
1751
|
+
kind: "device";
|
|
1752
|
+
deviceId: string;
|
|
1753
|
+
};
|
|
1754
|
+
/** The answer of {@link BlocksApi.check}. @public */
|
|
1755
|
+
interface BlockCheck {
|
|
1756
|
+
blocked: boolean;
|
|
1757
|
+
/** When the block ends; `null` has no end. Only when blocked. */
|
|
1758
|
+
expiresAt?: string | null;
|
|
1759
|
+
}
|
|
1760
|
+
/** Why a block is lifted, with {@link BlocksApi.lift}. @public */
|
|
1761
|
+
interface LiftBlockInput {
|
|
1762
|
+
/**
|
|
1763
|
+
* `false_positive` also marks the signal behind the block, so no rule fires on it again. On a
|
|
1764
|
+
* block made by a rule it counts against the rule, which pauses after too many reports.
|
|
1765
|
+
*/
|
|
1766
|
+
reason?: "false_positive" | "other";
|
|
1767
|
+
note?: string;
|
|
1768
|
+
}
|
|
1769
|
+
/**
|
|
1770
|
+
* Filters of {@link BlocksApi.list}, {@link BlocksApi.listPage} and {@link BlocksApi.iterate}.
|
|
1771
|
+
* Newest first.
|
|
1772
|
+
* @public
|
|
1773
|
+
*/
|
|
1774
|
+
interface ListBlocksQuery {
|
|
1775
|
+
kind?: BlockKind;
|
|
1776
|
+
status?: Block["status"];
|
|
1777
|
+
/** Page size, 1 to 100 (the API's default is 50). */
|
|
1778
|
+
limit?: number;
|
|
1779
|
+
/** The {@link Page.nextCursor} of the previous page. */
|
|
1780
|
+
cursor?: string;
|
|
1781
|
+
}
|
|
1782
|
+
/**
|
|
1783
|
+
* A device of this environment, counted inside it.
|
|
1784
|
+
* @public
|
|
1785
|
+
*/
|
|
1786
|
+
interface Device {
|
|
1787
|
+
/** `dev_...`, as a session's `device.deviceId`. */
|
|
1788
|
+
deviceId: string;
|
|
1789
|
+
platform: "web" | "android" | "ios";
|
|
1790
|
+
model?: string;
|
|
1791
|
+
firstSeenAt: string;
|
|
1792
|
+
lastSeenAt: string;
|
|
1793
|
+
/** Your sessions on this device. */
|
|
1794
|
+
sessions: number;
|
|
1795
|
+
/** Distinct verified people among them over 90 days. */
|
|
1796
|
+
people: number;
|
|
1797
|
+
/** An agent filmed on it, many verified people passed on it, or you marked it. */
|
|
1798
|
+
shared: boolean;
|
|
1799
|
+
/** Its active block. */
|
|
1800
|
+
block: {
|
|
1801
|
+
id: string;
|
|
1802
|
+
expiresAt: string | null;
|
|
1803
|
+
} | null;
|
|
1804
|
+
}
|
|
1805
|
+
/**
|
|
1806
|
+
* Filters of {@link PeopleApi.list}, {@link PeopleApi.listPage} and
|
|
1807
|
+
* {@link PeopleApi.iterate}. Newest first; only people who passed a verification.
|
|
1808
|
+
* @public
|
|
1809
|
+
*/
|
|
1810
|
+
interface ListPeopleQuery {
|
|
1811
|
+
/** Your own id for the person, exact match. */
|
|
1812
|
+
externalRef?: string;
|
|
1813
|
+
/** Page size, 1 to 100 (the API's default is 50). */
|
|
1814
|
+
limit?: number;
|
|
1815
|
+
/** The {@link Page.nextCursor} of the previous page. */
|
|
1816
|
+
cursor?: string;
|
|
1817
|
+
}
|
|
1818
|
+
/**
|
|
1819
|
+
* One page of a list: the items and, when more exist, the cursor of the next
|
|
1820
|
+
* page (pass it as `cursor`). Opaque; absent on the last page.
|
|
1821
|
+
* @public
|
|
1822
|
+
*/
|
|
1823
|
+
interface Page<T> {
|
|
1824
|
+
data: T[];
|
|
1825
|
+
nextCursor?: string;
|
|
1826
|
+
}
|
|
1827
|
+
/** Result of {@link PeopleApi.delete}. @public */
|
|
1828
|
+
interface DeletedPerson {
|
|
1829
|
+
/** The person id (`per_...`). */
|
|
1830
|
+
id: string;
|
|
1831
|
+
deleted: true;
|
|
1832
|
+
}
|
|
1833
|
+
/** The lists an AML screening can search. @public */
|
|
1834
|
+
type ScreeningList = "sanctions" | "pep" | "adverse_media";
|
|
1835
|
+
/**
|
|
1836
|
+
* Where a screening stands: `clear` (nothing scored above the possible
|
|
1837
|
+
* threshold), `possible` (a possible match), `hit` (a match), `confirmed` or
|
|
1838
|
+
* `dismissed` (a person of your organization decided the hits), `unavailable`
|
|
1839
|
+
* (the lists could not be searched; never billed).
|
|
1840
|
+
* @public
|
|
1841
|
+
*/
|
|
1842
|
+
type ScreeningStatus = "clear" | "possible" | "hit" | "confirmed" | "dismissed" | "unavailable";
|
|
1843
|
+
/** Why the lists could not be searched. @public */
|
|
1844
|
+
type ScreeningUnavailableReason = "screening_unavailable" | "no_identity_data" | "no_list_covered";
|
|
1845
|
+
/** What ran a screening: a session step, a screening run again, or ongoing screening. @public */
|
|
1846
|
+
type ScreeningTrigger = "session" | "rescreen" | "monitor";
|
|
1847
|
+
/** A list entry that matched the person, best first. Public list data. @public */
|
|
1848
|
+
interface ScreeningHitSummary {
|
|
1849
|
+
/** The stable id of the list entry. */
|
|
1850
|
+
entityId: string;
|
|
1851
|
+
/** The name of the entry as the list publishes it. */
|
|
1852
|
+
caption: string;
|
|
1853
|
+
/** How closely the entry matches the person, 0 to 1. */
|
|
1854
|
+
score: number;
|
|
1855
|
+
/** The searched lists the entry is on. */
|
|
1856
|
+
lists: ScreeningList[];
|
|
1857
|
+
}
|
|
1858
|
+
/** A list entry that matched, with its public attributes and sources. @public */
|
|
1859
|
+
interface ScreeningHit extends ScreeningHitSummary {
|
|
1860
|
+
/** The tags of the entry on its lists (`sanction`, `role.pep`, ...). */
|
|
1861
|
+
topics: string[];
|
|
1862
|
+
/** The source datasets of the entry. */
|
|
1863
|
+
datasets: string[];
|
|
1864
|
+
/** Public attributes of the entry, when the list publishes them. */
|
|
1865
|
+
attributes: {
|
|
1866
|
+
birthDates?: string[];
|
|
1867
|
+
nationalities?: string[];
|
|
1868
|
+
positions?: string[];
|
|
1869
|
+
aliases?: string[];
|
|
1870
|
+
gender?: string;
|
|
1871
|
+
};
|
|
1872
|
+
/** Where the list publishes the entry. */
|
|
1873
|
+
sourceUrls: string[];
|
|
1874
|
+
firstSeen?: string;
|
|
1875
|
+
lastSeen?: string;
|
|
1876
|
+
}
|
|
1877
|
+
/**
|
|
1878
|
+
* {@link Session.screening}: the search a session's AML screening step ran, or
|
|
1879
|
+
* `{ unavailable }` alone when it could not run.
|
|
1880
|
+
* @public
|
|
1881
|
+
*/
|
|
1882
|
+
type SessionScreening = {
|
|
1883
|
+
/** The screening id (`scr_...`); see {@link PeopleApi.screenings}. */
|
|
1884
|
+
id: string;
|
|
1885
|
+
status: Exclude<ScreeningStatus, "unavailable">;
|
|
1886
|
+
/** The lists the flow asked for. */
|
|
1887
|
+
lists: ScreeningList[];
|
|
1888
|
+
/** The lists actually searched. */
|
|
1889
|
+
listsCovered: ScreeningList[];
|
|
1890
|
+
/** The list data release the search ran on. */
|
|
1891
|
+
datasetVersion: string;
|
|
1892
|
+
/** The best score, 0 when nothing matched. */
|
|
1893
|
+
topScore: number;
|
|
1894
|
+
hits: ScreeningHitSummary[];
|
|
1895
|
+
} | {
|
|
1896
|
+
unavailable: ScreeningUnavailableReason;
|
|
1897
|
+
};
|
|
1898
|
+
/** One screening of a person ({@link PeopleApi.screen}, {@link PeopleApi.screenings}). @public */
|
|
1899
|
+
interface Screening {
|
|
1900
|
+
/** The screening id (`scr_...`). */
|
|
1901
|
+
id: string;
|
|
1902
|
+
trigger: ScreeningTrigger;
|
|
1903
|
+
status: ScreeningStatus;
|
|
1904
|
+
/** With `status: "unavailable"`: why the lists could not be searched. */
|
|
1905
|
+
unavailable?: ScreeningUnavailableReason;
|
|
1906
|
+
/** The lists asked for. */
|
|
1907
|
+
lists: ScreeningList[];
|
|
1908
|
+
/** The lists actually searched. */
|
|
1909
|
+
listsCovered: ScreeningList[];
|
|
1910
|
+
/** The list data release the search ran on. */
|
|
1911
|
+
datasetVersion: string;
|
|
1912
|
+
/** The best score, 0 when nothing matched. */
|
|
1913
|
+
topScore: number;
|
|
1914
|
+
/** The matching entries, best first. */
|
|
1915
|
+
hits: ScreeningHit[];
|
|
1916
|
+
/** The decision of a person of your organization on the hits, once made. */
|
|
1917
|
+
decision?: {
|
|
1918
|
+
outcome: "confirmed" | "dismissed";
|
|
1919
|
+
at: string;
|
|
1920
|
+
note?: string;
|
|
1921
|
+
};
|
|
1922
|
+
/** ISO 8601. */
|
|
1923
|
+
createdAt: string;
|
|
1924
|
+
}
|
|
1925
|
+
/** Input of {@link PeopleApi.screen}. @public */
|
|
1926
|
+
interface ScreenPersonInput {
|
|
1927
|
+
/** The lists to search, each once. Default `["sanctions", "pep"]`. */
|
|
1928
|
+
lists?: ScreeningList[];
|
|
1929
|
+
}
|
|
1930
|
+
/** Query of {@link PeopleApi.screenings}. @public */
|
|
1931
|
+
interface ListScreeningsQuery {
|
|
1932
|
+
/** Page size, 1 to 50 (the API's default is 25). */
|
|
1933
|
+
limit?: number;
|
|
1934
|
+
/** The {@link Page.nextCursor} of the previous page. */
|
|
1935
|
+
cursor?: string;
|
|
1936
|
+
}
|
|
1937
|
+
/**
|
|
1938
|
+
* `data` of `aml.match_flagged`: a screening settled `hit` or `possible`, from
|
|
1939
|
+
* a session step, a screening run again or ongoing screening. Sent once per
|
|
1940
|
+
* screening (de-duplicate on `screeningId`); a decision sends no event.
|
|
1941
|
+
* @public
|
|
1942
|
+
*/
|
|
1943
|
+
interface AmlMatchFlaggedEventData {
|
|
1944
|
+
screeningId: string;
|
|
1945
|
+
trigger: ScreeningTrigger;
|
|
1946
|
+
/** The session the screening ran in, or the person's latest approved session. */
|
|
1947
|
+
sessionId?: string;
|
|
1948
|
+
/** The person (`per_...`), once known. */
|
|
1949
|
+
personId?: string;
|
|
1950
|
+
status: "hit" | "possible";
|
|
1951
|
+
lists: ScreeningList[];
|
|
1952
|
+
listsCovered: ScreeningList[];
|
|
1953
|
+
datasetVersion: string;
|
|
1954
|
+
topScore: number;
|
|
1955
|
+
hits: ScreeningHitSummary[];
|
|
1956
|
+
}
|
|
1957
|
+
/** Options of {@link PeopleApi.revoke}. @public */
|
|
1958
|
+
interface RevokePersonInput {
|
|
1959
|
+
/** Kept on the audit trail only (≤ 500 characters). Do not put personal data here. */
|
|
1960
|
+
reason?: string;
|
|
1961
|
+
}
|
|
1962
|
+
/**
|
|
1963
|
+
* Input of {@link SessionsApi.extendLink}: the new link lifetime in minutes,
|
|
1964
|
+
* counted from the session creation, or the new expiry. It must be later than
|
|
1965
|
+
* the current expiry and within the flow's maximum link lifetime.
|
|
1966
|
+
* @public
|
|
1967
|
+
*/
|
|
1968
|
+
type ExtendLinkInput = {
|
|
1969
|
+
ttlMinutes: number;
|
|
1970
|
+
} | {
|
|
1971
|
+
expiresAt: string | Date;
|
|
1972
|
+
};
|
|
1973
|
+
/** Result of {@link SessionsApi.resendLink}: the new delivery attempt. @public */
|
|
1974
|
+
interface SessionLinkDelivery {
|
|
1975
|
+
delivery: {
|
|
1976
|
+
channel: "sms" | "whatsapp" | "email";
|
|
1977
|
+
/** `simulated` in the Sandbox: nothing is sent. */
|
|
1978
|
+
status: "queued" | "sent" | "failed" | "simulated";
|
|
1979
|
+
};
|
|
1980
|
+
}
|
|
1981
|
+
/** Result of {@link SessionsApi.extendLink}. @public */
|
|
1982
|
+
interface SessionLinkExpiry {
|
|
1983
|
+
/** ISO 8601: the new expiry of the link and its session. */
|
|
1984
|
+
expiresAt: string;
|
|
1985
|
+
}
|
|
1986
|
+
/**
|
|
1987
|
+
* `data` of `person.suspicious_activity`: a device already linked to ANOTHER
|
|
1988
|
+
* person was used for a session of this person. `count` is the person's running
|
|
1989
|
+
* total of such events. Ids only.
|
|
1990
|
+
* @public
|
|
1991
|
+
*/
|
|
1992
|
+
interface PersonSuspiciousActivityEventData {
|
|
1993
|
+
/** The person (`per_...`). */
|
|
1994
|
+
personId: string;
|
|
1995
|
+
sessionId: string;
|
|
1996
|
+
count: number;
|
|
1997
|
+
}
|
|
1998
|
+
/**
|
|
1999
|
+
* `data` of `session.superseded`: a session that waited for a review closed
|
|
2000
|
+
* because a newer attempt of the same person took that review over. The
|
|
2001
|
+
* session ends with status `completed`, `outcome: null` and `supersededBy`;
|
|
2002
|
+
* its review step failed with `superseded_by_retry`; nothing of it is deleted.
|
|
2003
|
+
* Read the newer session (`supersededBy`) for the verdict. This is the one
|
|
2004
|
+
* terminal event of the superseded session.
|
|
2005
|
+
* @public
|
|
2006
|
+
*/
|
|
2007
|
+
interface SessionSupersededEventData {
|
|
2008
|
+
/** The superseded session (`ses_...`). */
|
|
2009
|
+
sessionId: string;
|
|
2010
|
+
/** The newer session of the same person that took the review over (`ses_...`). */
|
|
2011
|
+
supersededBy: string;
|
|
2012
|
+
reason: "superseded_by_retry";
|
|
2013
|
+
/** Your own id for the person, from `person.externalRef` at create. */
|
|
2014
|
+
externalRef?: string;
|
|
2015
|
+
}
|
|
2016
|
+
/**
|
|
2017
|
+
* `usage.threshold_reached`: a usage, credit or spend threshold of the organization's
|
|
2018
|
+
* plan was reached (sent once per threshold and period). `kind` is `tier` for a monthly
|
|
2019
|
+
* tier, or the alert, e.g. `credit_80`, `usage_100_paid`, `spend_cap_reached`.
|
|
2020
|
+
* @public
|
|
2021
|
+
*/
|
|
2022
|
+
interface UsageThresholdReachedEventData {
|
|
2023
|
+
kind: string;
|
|
2024
|
+
/** The verification unit, on per-unit alerts. */
|
|
2025
|
+
unit?: "human_verification" | "identity_verification";
|
|
2026
|
+
/** Percent of the limit (80, 100), or `overage` for the first verification beyond a tier. */
|
|
2027
|
+
threshold?: number | "overage";
|
|
2028
|
+
used?: number;
|
|
2029
|
+
limit?: number;
|
|
2030
|
+
/** UTC month, `YYYY-MM`. */
|
|
2031
|
+
period?: string;
|
|
2032
|
+
/** Tier alerts: verifications that reached a result this month. */
|
|
2033
|
+
confirmed?: number;
|
|
2034
|
+
/** Tier alerts: verifications beyond the tier this month. */
|
|
2035
|
+
overage?: number;
|
|
2036
|
+
}
|
|
2037
|
+
/**
|
|
2038
|
+
* Event type → the shape of its `data`. Session events are typed; the
|
|
2039
|
+
* remaining events carry an open record until their payloads are frozen.
|
|
2040
|
+
* @public
|
|
2041
|
+
*/
|
|
2042
|
+
interface WebhookEventDataMap {
|
|
2043
|
+
"session.started": Record<string, unknown>;
|
|
2044
|
+
"session.review_pending": SessionLifecycleEventData;
|
|
2045
|
+
"session.completed": SessionLifecycleEventData;
|
|
2046
|
+
"session.expired": SessionLifecycleEventData;
|
|
2047
|
+
"session.failed": SessionLifecycleEventData;
|
|
2048
|
+
"session.superseded": SessionSupersededEventData;
|
|
2049
|
+
"person.enrolled": PersonEnrolledEventData;
|
|
2050
|
+
"person.updated": PersonUpdatedEventData;
|
|
2051
|
+
"person.suspicious_activity": PersonSuspiciousActivityEventData;
|
|
2052
|
+
"person.deleted": PersonDeletedEventData;
|
|
2053
|
+
"aml.match_flagged": AmlMatchFlaggedEventData;
|
|
2054
|
+
"payment.received": Record<string, unknown>;
|
|
2055
|
+
"invoice.generated": Record<string, unknown>;
|
|
2056
|
+
"invoice.paid": Record<string, unknown>;
|
|
2057
|
+
"invoice.overdue": Record<string, unknown>;
|
|
2058
|
+
"usage.threshold_reached": UsageThresholdReachedEventData;
|
|
2059
|
+
"webhook.test": Record<string, unknown>;
|
|
2060
|
+
}
|
|
2061
|
+
/** Every event a partner endpoint may receive. @public */
|
|
2062
|
+
type WebhookEventType = keyof WebhookEventDataMap;
|
|
2063
|
+
/**
|
|
2064
|
+
* The signed webhook payload for ONE event type. There is no global API
|
|
2065
|
+
* version; each event carries its own per-event `version`. Retried deliveries
|
|
2066
|
+
* keep the same `id` — de-duplicate on it.
|
|
2067
|
+
* @public
|
|
2068
|
+
*/
|
|
2069
|
+
interface WebhookEnvelopeOf<E extends WebhookEventType> {
|
|
2070
|
+
/** UUIDv7, stable across delivery retries. */
|
|
2071
|
+
id: string;
|
|
2072
|
+
event: E;
|
|
2073
|
+
/** Per-event payload version. */
|
|
2074
|
+
version: number;
|
|
2075
|
+
/** ISO 8601. */
|
|
2076
|
+
createdAt: string;
|
|
2077
|
+
orgId: string;
|
|
2078
|
+
env: SekyroEnvironment;
|
|
2079
|
+
data: WebhookEventDataMap[E];
|
|
2080
|
+
}
|
|
2081
|
+
/**
|
|
2082
|
+
* The signed webhook payload, discriminated on `event`: narrowing on
|
|
2083
|
+
* `envelope.event` narrows `envelope.data` to that event's shape.
|
|
2084
|
+
*
|
|
2085
|
+
* @example
|
|
2086
|
+
* ```ts
|
|
2087
|
+
* const envelope = verifyWebhook(rawBody, header, secret);
|
|
2088
|
+
* switch (envelope.event) {
|
|
2089
|
+
* case "session.completed":
|
|
2090
|
+
* envelope.data.outcome; // SessionOutcome | null | undefined
|
|
2091
|
+
* break;
|
|
2092
|
+
* case "person.updated":
|
|
2093
|
+
* envelope.data.personId; // "per_..."
|
|
2094
|
+
* break;
|
|
2095
|
+
* }
|
|
2096
|
+
* ```
|
|
2097
|
+
* @public
|
|
2098
|
+
*/
|
|
2099
|
+
type WebhookEnvelope<E extends WebhookEventType = WebhookEventType> = E extends WebhookEventType ? WebhookEnvelopeOf<E> : never;
|
|
2100
|
+
|
|
2101
|
+
/** Default partner API origin + version prefix. @public */
|
|
2102
|
+
declare const DEFAULT_BASE_URL = "https://api.sekyro.ai/api/v2";
|
|
2103
|
+
/** Default per-request timeout. @public */
|
|
2104
|
+
declare const DEFAULT_TIMEOUT_MS = 30000;
|
|
2105
|
+
/** `fetch`-compatible function; the global `fetch` by default. @public */
|
|
2106
|
+
type FetchLike = typeof globalThis.fetch;
|
|
2107
|
+
/** Constructor options of {@link Sekyro}. @public */
|
|
2108
|
+
interface SekyroOptions {
|
|
2109
|
+
/** Partner API key (server-side only). Sent as `Authorization: Bearer`. */
|
|
2110
|
+
apiKey: string;
|
|
2111
|
+
/** API base URL incl. the `/api/v2` prefix. Default {@link DEFAULT_BASE_URL}. */
|
|
2112
|
+
baseUrl?: string;
|
|
2113
|
+
/** Per-request timeout in ms. Default {@link DEFAULT_TIMEOUT_MS}. */
|
|
2114
|
+
timeoutMs?: number;
|
|
2115
|
+
/** Custom `fetch` (tests, proxies, custom agents). Default `globalThis.fetch`. */
|
|
2116
|
+
fetch?: FetchLike;
|
|
2117
|
+
/**
|
|
2118
|
+
* The auth-provider connector this client runs in, sent as the
|
|
2119
|
+
* `x-sekyro-connector: <provider>/<version>` header on every call so the
|
|
2120
|
+
* dashboard can show the connector as connected. Ids only. A connector
|
|
2121
|
+
* created with `createConnector` from `@sekyro/node/connect` sets it for you
|
|
2122
|
+
* (unless its `telemetry` option is `false`).
|
|
2123
|
+
*/
|
|
2124
|
+
connector?: ConnectorIdentity;
|
|
2125
|
+
}
|
|
2126
|
+
/** A connector's provider id and package version, for {@link SekyroOptions.connector}. @public */
|
|
2127
|
+
interface ConnectorIdentity {
|
|
2128
|
+
/** The provider id, for example `supabase`: lowercase letters, digits and `-`, at most 32 characters. */
|
|
2129
|
+
provider: string;
|
|
2130
|
+
/** The connector package version, for example `0.1.0`: at most 64 characters. */
|
|
2131
|
+
version: string;
|
|
2132
|
+
}
|
|
2133
|
+
type HttpMethod = "GET" | "POST" | "PATCH" | "DELETE";
|
|
2134
|
+
/**
|
|
2135
|
+
* `sekyro.sessions` — create and read verification sessions.
|
|
2136
|
+
*
|
|
2137
|
+
* Exported as a TYPE only (`import type { SessionsApi }`): the class value is
|
|
2138
|
+
* not part of the package surface, so it can only be obtained through
|
|
2139
|
+
* {@link Sekyro.sessions} — never constructed by hand with an unchecked
|
|
2140
|
+
* transport.
|
|
2141
|
+
* @public
|
|
2142
|
+
*/
|
|
2143
|
+
declare class SessionsApi {
|
|
2144
|
+
private readonly t;
|
|
2145
|
+
/**
|
|
2146
|
+
* Constructed by {@link Sekyro}; the transport is kept out of the public
|
|
2147
|
+
* surface on purpose (only its bound calls cross this boundary).
|
|
2148
|
+
* @internal
|
|
2149
|
+
*/
|
|
2150
|
+
constructor(t: {
|
|
2151
|
+
call<T>(method: "GET" | "POST" | "DELETE", path: string, body?: unknown, idempotencyKey?: string): Promise<T>;
|
|
2152
|
+
page<T>(path: string): Promise<Page<T>>;
|
|
2153
|
+
bytes(path: string): Promise<MediaBytes>;
|
|
2154
|
+
});
|
|
2155
|
+
/**
|
|
2156
|
+
* `POST /sessions`. Returns the one-time `clientToken` — hand it to the
|
|
2157
|
+
* browser, never persist it. Pass an `idempotencyKey` so a retried call
|
|
2158
|
+
* cannot create a second session.
|
|
2159
|
+
*/
|
|
2160
|
+
create(input?: CreateSessionInput, opts?: RequestOptions): Promise<CreatedSession>;
|
|
2161
|
+
/**
|
|
2162
|
+
* `POST /sessions/:id/method` — choose the identity method of an
|
|
2163
|
+
* optional-document session on the person's behalf (the hosted method
|
|
2164
|
+
* screen is then skipped). `409 method_locked` once the choice can no
|
|
2165
|
+
* longer change; `409 session_not_active` on a finished or expired session.
|
|
2166
|
+
* On a flow session: `409 choice_not_found` (the flow has no identity-method
|
|
2167
|
+
* choice), `409 choice_locked`, `409 choice_option_unavailable` (see
|
|
2168
|
+
* {@link isFlowError}).
|
|
2169
|
+
*/
|
|
2170
|
+
selectMethod(id: string, method: IdentityMethod): Promise<Session>;
|
|
2171
|
+
/** `GET /sessions/:id` — the whitelisted view (no client token). Either id form (`ses_...` or bare) works. */
|
|
2172
|
+
get(id: string): Promise<Session>;
|
|
2173
|
+
/**
|
|
2174
|
+
* `POST /sessions/:id/cancel` — stop a session that has not ended. The
|
|
2175
|
+
* hosted link stops working, and one `session.failed` with
|
|
2176
|
+
* `failureReason: "cancelled_by_organization"` is sent. Returns the
|
|
2177
|
+
* cancelled session. `409 session_not_cancellable` once the session has
|
|
2178
|
+
* ended (a repeated cancel included). Needs the `sessions:create` scope.
|
|
2179
|
+
*/
|
|
2180
|
+
cancel(id: string, opts?: RequestOptions): Promise<Session>;
|
|
2181
|
+
/**
|
|
2182
|
+
* `POST /sessions/:id/link/resend` — send the hosted link again through the
|
|
2183
|
+
* session's own `deliver` channel, to the same destination (neither can be
|
|
2184
|
+
* changed). Only for sessions created with `deliver`:
|
|
2185
|
+
* `409 link_not_deliverable` otherwise, `409 link_not_usable` once the
|
|
2186
|
+
* session ended, `429 resend_rate_limited` past the send limits. Needs the
|
|
2187
|
+
* `sessions:create` scope.
|
|
2188
|
+
*/
|
|
2189
|
+
resendLink(id: string, opts?: RequestOptions): Promise<SessionLinkDelivery>;
|
|
2190
|
+
/**
|
|
2191
|
+
* `POST /sessions/:id/link/extend` — a later expiry for the hosted link
|
|
2192
|
+
* and its session: `{ ttlMinutes }` counted from the session creation, or
|
|
2193
|
+
* `{ expiresAt }`. `400 ttl_out_of_policy` when it is not later than the
|
|
2194
|
+
* current expiry or past the flow's maximum. Only for sessions created with
|
|
2195
|
+
* `deliver`. Needs the `sessions:create` scope.
|
|
2196
|
+
*/
|
|
2197
|
+
extendLink(id: string, input: ExtendLinkInput, opts?: RequestOptions): Promise<SessionLinkExpiry>;
|
|
2198
|
+
/**
|
|
2199
|
+
* The first page of your sessions, newest first (`GET /sessions`; the API
|
|
2200
|
+
* returns 50 by default, at most 100 with `limit`). Read every page with
|
|
2201
|
+
* {@link SessionsApi.iterate}, or one page and its cursor with
|
|
2202
|
+
* {@link SessionsApi.listPage}. The `externalRef` and `status` filters are
|
|
2203
|
+
* applied again to the answer, so an API that ignores them never returns
|
|
2204
|
+
* another user's sessions.
|
|
2205
|
+
*/
|
|
2206
|
+
list(query?: ListSessionsQuery): Promise<Session[]>;
|
|
2207
|
+
/** One page of {@link SessionsApi.list} with its `nextCursor` (absent on the last page). */
|
|
2208
|
+
listPage(query?: ListSessionsQuery): Promise<Page<Session>>;
|
|
2209
|
+
/**
|
|
2210
|
+
* Every session matching `query`, newest first, following `nextCursor` page
|
|
2211
|
+
* after page (`limit` sets the page size).
|
|
2212
|
+
*
|
|
2213
|
+
* @example
|
|
2214
|
+
* ```ts
|
|
2215
|
+
* for await (const s of sekyro.sessions.iterate({ status: "completed" })) {
|
|
2216
|
+
* console.log(s.id);
|
|
2217
|
+
* }
|
|
2218
|
+
* ```
|
|
2219
|
+
*/
|
|
2220
|
+
iterate(query?: ListSessionsQuery): AsyncGenerator<Session, void, undefined>;
|
|
2221
|
+
/**
|
|
2222
|
+
* `GET /sessions/:id/media` — the session's media (documents, portraits,
|
|
2223
|
+
* the selfie, the clips), each with its check, attempt tags and a URL valid
|
|
2224
|
+
* 15 minutes ({@link MediaItem}). Needs the `sessions:read` scope.
|
|
2225
|
+
*/
|
|
2226
|
+
media(id: string): Promise<MediaList>;
|
|
2227
|
+
/**
|
|
2228
|
+
* `GET /sessions/:id/media/:kind` — the bytes of one media item: the
|
|
2229
|
+
* decisive attempt of that kind by default, `attempt` for another one,
|
|
2230
|
+
* `reference: "first"` for the first reference of a `reference_portrait`
|
|
2231
|
+
* a second reference decided. `404 media_not_available` when the kind, the
|
|
2232
|
+
* attempt or the object is not there. Needs the `sessions:read` scope.
|
|
2233
|
+
*/
|
|
2234
|
+
mediaBytes(id: string, kind: MediaKind, opts?: MediaBytesOptions): Promise<MediaBytes>;
|
|
2235
|
+
/**
|
|
2236
|
+
* `GET /sessions/:id/result-token`: a freshly signed result token for a
|
|
2237
|
+
* finished session (valid 10 minutes; check it with
|
|
2238
|
+
* {@link verifyResultToken}). `409 session_not_terminal` while the session
|
|
2239
|
+
* is still active. Needs the `sessions:read` scope.
|
|
2240
|
+
*/
|
|
2241
|
+
resultToken(id: string): Promise<ResultTokenResponse>;
|
|
2242
|
+
/**
|
|
2243
|
+
* `POST /sessions/:id/simulate`: finishes a simulated Sandbox session in one
|
|
2244
|
+
* call, for tests and CI. It runs every step of the flow through the real
|
|
2245
|
+
* engine, so the status, the webhooks, the result token and the dashboard
|
|
2246
|
+
* behave as for a session driven by a person. Never billed. Returns the
|
|
2247
|
+
* finished session; pass an `idempotencyKey` to make a retry safe. Errors:
|
|
2248
|
+
* `400 sandbox_only` (Live key), `409 session_not_simulated` (bound to a
|
|
2249
|
+
* tester), `409 session_already_final`, `422 simulate_outcome_unreachable`
|
|
2250
|
+
* (`details.issues` says why), `422 simulate_reason_invalid`. Needs the
|
|
2251
|
+
* `sessions:create` scope.
|
|
2252
|
+
*/
|
|
2253
|
+
simulate(id: string, input: SimulateSessionInput, opts?: RequestOptions): Promise<Session>;
|
|
2254
|
+
}
|
|
2255
|
+
/**
|
|
2256
|
+
* `sekyro.flows`: the flows of the API key's app.
|
|
2257
|
+
*
|
|
2258
|
+
* Exported as a TYPE only, like {@link SessionsApi}: obtained through
|
|
2259
|
+
* {@link Sekyro.flows}.
|
|
2260
|
+
* @public
|
|
2261
|
+
*/
|
|
2262
|
+
declare class FlowsApi {
|
|
2263
|
+
private readonly t;
|
|
2264
|
+
/** @internal */
|
|
2265
|
+
constructor(t: {
|
|
2266
|
+
call<T>(method: HttpMethod, path: string, body?: unknown, idempotencyKey?: string): Promise<T>;
|
|
2267
|
+
});
|
|
2268
|
+
/**
|
|
2269
|
+
* `GET /flows`: the published flows of the API key's app (default flow
|
|
2270
|
+
* first, then by name). Pass a flow's `slug` or `id` as
|
|
2271
|
+
* {@link CreateSessionInput.flow}. Needs the `sessions:create` scope; an
|
|
2272
|
+
* invalid key answers `401 unauthorized`.
|
|
2273
|
+
*/
|
|
2274
|
+
list(): Promise<FlowSummary[]>;
|
|
2275
|
+
}
|
|
2276
|
+
/**
|
|
2277
|
+
* `sekyro.people` — read and manage people (the same person across your
|
|
2278
|
+
* apps). Reads need the `people:read` scope, `revoke` / `delete` the
|
|
2279
|
+
* `people:write` scope. A person is
|
|
2280
|
+
* visible once they have passed a verification: a person who never passed,
|
|
2281
|
+
* an unknown id and a person of another organization or environment all
|
|
2282
|
+
* answer the same `404 subject_not_found` on `get`, `revoke` and `delete`,
|
|
2283
|
+
* and `list` leaves them out. Ids are `per_...`; the bare 24 hexadecimal
|
|
2284
|
+
* characters name the same person.
|
|
2285
|
+
*
|
|
2286
|
+
* Type-only export, like {@link SessionsApi}: obtained through
|
|
2287
|
+
* {@link Sekyro.people}.
|
|
2288
|
+
* @public
|
|
2289
|
+
*/
|
|
2290
|
+
declare class PeopleApi {
|
|
2291
|
+
private readonly t;
|
|
2292
|
+
/** @internal */
|
|
2293
|
+
constructor(t: {
|
|
2294
|
+
call<T>(method: "GET" | "POST" | "DELETE", path: string, body?: unknown, idempotencyKey?: string): Promise<T>;
|
|
2295
|
+
page<T>(path: string): Promise<Page<T>>;
|
|
2296
|
+
});
|
|
2297
|
+
/** `GET /people/:id` — the person, their sessions and their returning-user readiness. */
|
|
2298
|
+
get(id: string): Promise<Person>;
|
|
2299
|
+
/**
|
|
2300
|
+
* The first page of the people who have passed a verification, newest
|
|
2301
|
+
* first (`GET /people`; 50 by default, at most 100 with `limit`),
|
|
2302
|
+
* optionally only those carrying your own id (`externalRef`). The list can
|
|
2303
|
+
* be empty while sessions with this `externalRef` exist. Every page:
|
|
2304
|
+
* {@link PeopleApi.iterate}.
|
|
2305
|
+
*/
|
|
2306
|
+
list(query?: ListPeopleQuery): Promise<Person[]>;
|
|
2307
|
+
/** One page of {@link PeopleApi.list} with its `nextCursor` (absent on the last page). */
|
|
2308
|
+
listPage(query?: ListPeopleQuery): Promise<Page<Person>>;
|
|
2309
|
+
/** Every person matching `query`, newest first, following `nextCursor` page after page. */
|
|
2310
|
+
iterate(query?: ListPeopleQuery): AsyncGenerator<Person, void, undefined>;
|
|
2311
|
+
/**
|
|
2312
|
+
* `POST /people/:id/revoke` — the person can no longer be used for
|
|
2313
|
+
* returning-user sessions. Idempotent: revoking again returns the same view.
|
|
2314
|
+
* Emits `person.updated` with `status: 'revoked'`.
|
|
2315
|
+
*/
|
|
2316
|
+
revoke(id: string, input?: RevokePersonInput, opts?: RequestOptions): Promise<Person>;
|
|
2317
|
+
/**
|
|
2318
|
+
* `POST /people/:id/screen` — screens a verified person again against
|
|
2319
|
+
* sanctions and PEP lists (`lists`, default sanctions and PEP), from the
|
|
2320
|
+
* person's stored name, birth date and the issuing countries of their identity
|
|
2321
|
+
* numbers. Billed as one AML screening; a refusal is not billed
|
|
2322
|
+
* (`400 screening_list_not_covered`, `403 service_not_in_plan`,
|
|
2323
|
+
* `503 screening_unavailable`). A hit or a possible match also sends
|
|
2324
|
+
* `aml.match_flagged`. Pass an `idempotencyKey` so a retried call is not
|
|
2325
|
+
* billed twice.
|
|
2326
|
+
*/
|
|
2327
|
+
screen(id: string, input?: ScreenPersonInput, opts?: RequestOptions): Promise<Screening>;
|
|
2328
|
+
/**
|
|
2329
|
+
* The first page of a person's screenings, newest first
|
|
2330
|
+
* (`GET /people/:id/screenings`; 25 by default, at most 50 with `limit`).
|
|
2331
|
+
* Every page: {@link PeopleApi.iterateScreenings}.
|
|
2332
|
+
*/
|
|
2333
|
+
screenings(id: string, query?: ListScreeningsQuery): Promise<Screening[]>;
|
|
2334
|
+
/** One page of {@link PeopleApi.screenings} with its `nextCursor` (absent on the last page). */
|
|
2335
|
+
screeningsPage(id: string, query?: ListScreeningsQuery): Promise<Page<Screening>>;
|
|
2336
|
+
/** Every screening of a person, newest first, following `nextCursor` page after page. */
|
|
2337
|
+
iterateScreenings(id: string, query?: ListScreeningsQuery): AsyncGenerator<Screening, void, undefined>;
|
|
2338
|
+
/**
|
|
2339
|
+
* `DELETE /people/:id` — deletes the person's stored photos, face
|
|
2340
|
+
* templates and identifiers, and the personal data and media of their
|
|
2341
|
+
* sessions, which it unlinks (they keep their outcome and steps). Emits
|
|
2342
|
+
* `person.deleted`. Cannot be undone; a second call answers `404`.
|
|
2343
|
+
*/
|
|
2344
|
+
delete(id: string): Promise<DeletedPerson>;
|
|
2345
|
+
/**
|
|
2346
|
+
* A re-check or step-up session for an existing person in one call:
|
|
2347
|
+
* `POST /people/:id/sessions` when `target` is a person id (`per_...` or 24
|
|
2348
|
+
* hexadecimal characters) or `{ personId }`, otherwise
|
|
2349
|
+
* `POST /people/by-external-ref/:externalRef/sessions` (pass
|
|
2350
|
+
* `{ externalRef }` to force it). Same result and errors as
|
|
2351
|
+
* {@link SessionsApi.create}; needs the `sessions:create` and
|
|
2352
|
+
* `people:read` scopes.
|
|
2353
|
+
*/
|
|
2354
|
+
createSession(target: string | PersonSessionTarget, input: PersonSessionInput, opts?: RequestOptions): Promise<CreatedSession>;
|
|
2355
|
+
}
|
|
2356
|
+
/**
|
|
2357
|
+
* Stops the next sessions of a device, a person, an account or a contact. Exposed as
|
|
2358
|
+
* {@link Sekyro.blocks}. Needs the `blocks:read` or `blocks:write` scope.
|
|
2359
|
+
* Exported as a TYPE only.
|
|
2360
|
+
* @public
|
|
2361
|
+
*/
|
|
2362
|
+
declare class BlocksApi {
|
|
2363
|
+
private readonly t;
|
|
2364
|
+
/** @internal */
|
|
2365
|
+
constructor(t: {
|
|
2366
|
+
call<T>(method: HttpMethod, path: string, body?: unknown, idempotencyKey?: string): Promise<T>;
|
|
2367
|
+
page<T>(path: string): Promise<Page<T>>;
|
|
2368
|
+
});
|
|
2369
|
+
/**
|
|
2370
|
+
* `POST /blocks`: blocks the key, or answers the active block already on it. `kind: "person"`
|
|
2371
|
+
* blocks each ID number of the person and answers a list. A shared device answers
|
|
2372
|
+
* `409 device_shared` with `details.people` unless `force: true`. `403 blocks_disabled` while blocks
|
|
2373
|
+
* are turned off. The API requires an idempotency key: one is generated when you pass none, so
|
|
2374
|
+
* pass your own to make a retry of the same call safe.
|
|
2375
|
+
*/
|
|
2376
|
+
create(input: CreateBlockInput & {
|
|
2377
|
+
kind: "person";
|
|
2378
|
+
}, opts?: RequestOptions): Promise<Block[]>;
|
|
2379
|
+
create(input: CreateBlockInput, opts?: RequestOptions): Promise<Block>;
|
|
2380
|
+
/** The first page of the blocks of this environment, newest first. Every page: {@link BlocksApi.iterate}. */
|
|
2381
|
+
list(query?: ListBlocksQuery): Promise<Block[]>;
|
|
2382
|
+
/** One page of {@link BlocksApi.list} with its `nextCursor` (absent on the last page). */
|
|
2383
|
+
listPage(query?: ListBlocksQuery): Promise<Page<Block>>;
|
|
2384
|
+
/** Every block matching `query`, newest first, following `nextCursor` page after page. */
|
|
2385
|
+
iterate(query?: ListBlocksQuery): AsyncGenerator<Block, void, undefined>;
|
|
2386
|
+
/** `GET /blocks/:id`. */
|
|
2387
|
+
get(id: string): Promise<Block>;
|
|
2388
|
+
/** `DELETE /blocks/:id`: the next sessions on its key go through. Lifting again is a no-op. */
|
|
2389
|
+
lift(id: string, input?: LiftBlockInput, opts?: RequestOptions): Promise<Block>;
|
|
2390
|
+
/** `POST /blocks/check`: whether a value is blocked. A POST, so it never sits in a URL or a log. */
|
|
2391
|
+
check(input: BlockCheckInput): Promise<BlockCheck>;
|
|
2392
|
+
}
|
|
2393
|
+
/**
|
|
2394
|
+
* What you know about a device before you block it. Exposed as {@link Sekyro.devices}. Needs the
|
|
2395
|
+
* `blocks:read` or `blocks:write` scope. Exported as a TYPE only.
|
|
2396
|
+
* @public
|
|
2397
|
+
*/
|
|
2398
|
+
declare class DevicesApi {
|
|
2399
|
+
private readonly t;
|
|
2400
|
+
/** @internal */
|
|
2401
|
+
constructor(t: {
|
|
2402
|
+
call<T>(method: HttpMethod, path: string, body?: unknown, idempotencyKey?: string): Promise<T>;
|
|
2403
|
+
});
|
|
2404
|
+
/** `GET /devices/:deviceId`: `404 device_not_found` for a device of another environment. */
|
|
2405
|
+
get(deviceId: string): Promise<Device>;
|
|
2406
|
+
/**
|
|
2407
|
+
* `PATCH /devices/:deviceId`: marks or unmarks the device as shared. Unmarking only clears your
|
|
2408
|
+
* own mark: a device recognised as shared from its sessions stays shared.
|
|
2409
|
+
*/
|
|
2410
|
+
update(deviceId: string, input: {
|
|
2411
|
+
shared: boolean;
|
|
2412
|
+
}, opts?: RequestOptions): Promise<Device>;
|
|
2413
|
+
}
|
|
2414
|
+
/**
|
|
2415
|
+
* Sekyro AI partner API client. Server-side only: it carries your API key.
|
|
2416
|
+
*
|
|
2417
|
+
* Throws {@link SekyroConfigError} synchronously when `apiKey` is missing or
|
|
2418
|
+
* `baseUrl` is not `https:` (plain `http:` is accepted for `localhost`,
|
|
2419
|
+
* `127.0.0.1` and `[::1]` only).
|
|
2420
|
+
*
|
|
2421
|
+
* @example
|
|
2422
|
+
* ```ts
|
|
2423
|
+
* const sekyro = new Sekyro({ apiKey: process.env.SEKYRO_API_KEY! });
|
|
2424
|
+
* const { id, hostedUrl } = await sekyro.sessions.create({ person: { externalRef: "<your user id>" } });
|
|
2425
|
+
* ```
|
|
2426
|
+
* @public
|
|
2427
|
+
*/
|
|
2428
|
+
declare class Sekyro {
|
|
2429
|
+
#private;
|
|
2430
|
+
readonly sessions: SessionsApi;
|
|
2431
|
+
readonly people: PeopleApi;
|
|
2432
|
+
readonly blocks: BlocksApi;
|
|
2433
|
+
readonly devices: DevicesApi;
|
|
2434
|
+
readonly flows: FlowsApi;
|
|
2435
|
+
constructor(opts: SekyroOptions);
|
|
2436
|
+
/**
|
|
2437
|
+
* `GET /me`: which key this is. Tells a Sandbox key from a Live one, and
|
|
2438
|
+
* names its app, organization and scopes. Works with any valid secret key;
|
|
2439
|
+
* never returns the secret. An invalid key answers `401 unauthorized`.
|
|
2440
|
+
*/
|
|
2441
|
+
me(): Promise<ApiKeyIdentity>;
|
|
2442
|
+
}
|
|
2443
|
+
|
|
2444
|
+
export { type FlowSummary as $, type AgeMethod as A, type Block as B, type CreatedSession as C, type CreateBlockInput as D, type CreateSessionInput as E, type FetchLike as F, DEFAULT_BASE_URL as G, DEFAULT_TIMEOUT_MS as H, type DecidedBy as I, type DecisionReason as J, type DeepPartial as K, type Locale as L, type DeletedPerson as M, type DeliverOptions as N, type Device as O, DevicesApi as P, type DocumentSubstitutionSettings as Q, type ReviewReason as R, Sekyro as S, type EidResult as T, type EligibilityReason as U, type VerificationLevel as V, type WebhookEventType as W, type ExtendLinkInput as X, type FlowOverridableSettings as Y, type FlowOverrides as Z, type FlowServiceSettings as _, type ServiceId as a, type SessionLinkInput as a$, FlowsApi as a0, type IdNumberReason as a1, type Identity as a2, type IdentityBirthPlace as a3, type IdentityDocument as a4, type IdentityIdNumber as a5, type IdentityMethod as a6, type IdentityName as a7, type IdentityScalarKey as a8, type IdentitySource as a9, type PolicyFailureReason as aA, type PortraitReportEntry as aB, type PriorReviewReason as aC, type ProbeBindingReason as aD, type ProbeQuality as aE, type ProfileDocumentType as aF, type RequestOptions as aG, type ResultTokenResponse as aH, type ReviewOutcomeReason as aI, type RevokePersonInput as aJ, type ScreenPersonInput as aK, type Screening as aL, type ScreeningHit as aM, type ScreeningHitSummary as aN, type ScreeningList as aO, type ScreeningStatus as aP, type ScreeningTrigger as aQ, type ScreeningUnavailableReason as aR, type SekyroOptions as aS, type Session as aT, type SessionDevice as aU, type SessionDeviceSignal as aV, type SessionFailureReason as aW, type SessionFlowRef as aX, type SessionLifecycleEventData as aY, type SessionLinkDelivery as aZ, type SessionLinkExpiry as a_, type IdentitySources as aa, type LevelTarget as ab, type LiftBlockInput as ac, type ListBlocksQuery as ad, type ListPeopleQuery as ae, type ListScreeningsQuery as af, type ListSessionsQuery as ag, type MatchReason as ah, type MediaBytes as ai, type MediaBytesOptions as aj, type MediaItem as ak, type MediaKind as al, type MediaList as am, type NameForm as an, type Page as ao, PeopleApi as ap, type Person as aq, type PersonBirthPlaceInput as ar, type PersonDeletedEventData as as, type PersonDocumentInput as at, type PersonEnrolledEventData as au, type PersonSession as av, type PersonSessionInput as aw, type PersonSessionTarget as ax, type PersonSuspiciousActivityEventData as ay, type PersonUpdatedEventData as az, type SessionPersonInput as b, type SessionNetwork as b0, type SessionNetworkEvent as b1, type SessionScreening as b2, type SessionStatus as b3, type SessionStep as b4, type SessionStepDecision as b5, type SessionSupersededEventData as b6, SessionsApi as b7, type SimulateSessionInput as b8, type SubjectAssurance as b9, type SubjectIdNumber as ba, type SubjectName as bb, type SubjectReferenceSource as bc, type SubjectReuseTarget as bd, type SubjectStatus as be, type UsageThresholdReachedEventData as bf, type VerifiedContacts as bg, type WebhookEnvelopeOf as bh, type WebhookEventDataMap as bi, type WebhookEnvelope as c, type SekyroEnvironment as d, type VerificationAssurance as e, type SessionOutcome as f, type VerificationUnit as g, type SubjectReuseMode as h, type ResultRisk as i, type ResultCheckProofs as j, type ResultDuplicate as k, type FailureIdentification as l, type AgeResult as m, type AmlMatchFlaggedEventData as n, type ApiKeyIdentity as o, type BlockCheck as p, type BlockCheckInput as q, type BlockDuration as r, type BlockIdNumber as s, type BlockKind as t, type BlockReason as u, BlocksApi as v, type CameraUnavailableCause as w, type CheckState as x, type CheckType as y, type ConnectorIdentity as z };
|