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

This diff represents the content of publicly available package versions that have been released to one of the supported registries. The information contained in this diff is provided for informational purposes only and reflects changes between package versions as they appear in their respective public registries.
package/CHANGELOG.md CHANGED
@@ -1,5 +1,14 @@
1
1
  # @sekyro/node
2
2
 
3
+ ## 0.1.0-rc.13
4
+
5
+ ### Minor Changes
6
+
7
+ - a43e198: The connector claim carries the proven minimum age. `SekyroClaim` gains `age_over` (the minimum age of the flow that proved it, never the person's age) and `age_method` (`estimated`, `document`, `chip`, `registry` or `eid`), written from the result token's `sekyro.age` (or from the webhook's `age` when a session has no token), never the estimate or a birth date. The claim keeps the stronger proof of the same person: a birth date from identity data beats an estimate, then the higher minimum age wins; a session below the stored level that proved a stronger age writes the age alone (new merge rule `age_proved`), and a revocation or deletion clears it. Gates take `minAge` and `ageMethods`, and fail with `age_not_proven` (action `verify`) or `age_method_not_allowed` (action `step_up`). `AgeMethod` is exported from `@sekyro/node/connect`. Claims without the fields still parse and pass gates without `minAge`.
8
+
9
+ `@sekyro/connect-clerk` sends `age_over` and `age_method` as `null` when absent, so Clerk's deep merge never keeps a cleared age. Its peer range now requires `@sekyro/node` 0.1.0-rc.13 or later, the release that writes the age, so an older adapter cannot run next to a core that writes an age it would never clear.
10
+ - fcba7e9: AML screening. Sessions on a flow with an AML screening step return `screening` (`SessionScreening`: the lists searched, the dataset version, the best score and the matching list entries, or `{ unavailable }` when the lists could not be searched), on `sessions.get()` and in the `session.completed` and `session.failed` data. `people.screen(id, { lists })` screens a person again (billed as one AML screening; pass an `idempotencyKey`), and `people.screenings(id)`, `people.screeningsPage()` and `people.iterateScreenings()` list their history. `aml.match_flagged` is sent again, with a typed payload (`AmlMatchFlaggedEventData`). `CheckType` gains `aml_screening`, the `aml_screening` flow settings take `onHit: "signal"`, `PolicyFailureReason` gains `aml_hit` and `ReviewReason` gains `screening`.
11
+
3
12
  ## 0.1.0-rc.12
4
13
 
5
14
  ### Minor Changes
package/README.md CHANGED
@@ -118,8 +118,7 @@ changes a service's settings, keyed by service id (`liveness`, `phone_otp`,
118
118
  the flow stricter unless the flow allows widening; turning a service `'off'`
119
119
  always widens. The changed paths come back on `session.overriddenFields`.
120
120
 
121
- > **Sekyro flows breaking change.** The `profile` override is gone: use
122
- > `overrides`. `flow` is accepted again, now as the app's flow slug or id.
121
+ `flow` takes the app's flow slug or id.
123
122
 
124
123
  The session view also carries `failureReason` (a policy stop such as
125
124
  `location_not_allowed` or `underage`), `failureDetail` (why, when that reason
@@ -185,8 +184,8 @@ patronymic per ISO 15924 script), `birthDate`, `birthPlace` (a string or
185
184
  (`{ type, issuingCountry, number }`), `phone`, `email`, and for a flow that
186
185
  verifies identity from your data, `photo` and `fetchedAt`.
187
186
  The session's flow decides how Sekyro AI uses it, never the request: when a step
188
- reads partner-supplied data (an environment Sekyro AI set to the `supplied`
189
- mode), the record is the **reference** to believe; otherwise it is a
187
+ reads partner-supplied data (a Partner-supplied identity step on the session's
188
+ path, available in every environment), the record is the **reference** to believe; otherwise it is a
190
189
  **prefill** checked against what the person shows. `created.subjectUse` says
191
190
  which (`"reference"` or `"prefill"`). The rules, the trust table and every
192
191
  error are on the [Person data](https://docs.sekyro.ai/en/guides/person-data)
@@ -206,8 +205,7 @@ await sekyro.sessions.create({
206
205
  If your data comes from your own call to a national registry,
207
206
  `personFromNationalRegistry()` converts that answer locally into the
208
207
  reference keys. Sekyro AI treats the result as identity data supplied by your
209
- organization: it makes no registry call, and it never receives or stores any
210
- registry key.
208
+ organization: it makes no registry call and needs no registry key.
211
209
 
212
210
  ```ts
213
211
  import { personFromNationalRegistry } from "@sekyro/node";
@@ -221,7 +219,7 @@ const created = await sekyro.sessions.create({
221
219
  ...personFromNationalRegistry("MR", answer, { fetchedAt: receivedAt }),
222
220
  },
223
221
  });
224
- created.subjectUse; // "reference" in a supplied-mode environment whose flow reads it
222
+ created.subjectUse; // "reference" when the flow has a Partner-supplied identity step
225
223
  ```
226
224
 
227
225
  The first argument is the registry's country (ISO alpha-2) and types the
@@ -237,8 +235,7 @@ An answer that states a nationality none of whose values the SDK can map throws
237
235
  yourself and pass `options.nationality` (ISO alpha-2), so the stated nationality
238
236
  is never dropped.
239
237
 
240
- Refusals of a reference, in this order: `403 supplied_identity_not_entitled`
241
- (the environment is not in `supplied` mode), `422 subject_record_incomplete`
238
+ Refusals of a reference, in this order: `422 subject_record_incomplete`
242
239
  (`error.details.fields` names the missing keys), `422 subject_record_stale`
243
240
  (obtained more than 24 h ago, or more than 5 min ahead) and
244
241
  `422 subject_photo_unusable` (not a JPEG or PNG of at most 1 MB within the size
@@ -250,15 +247,13 @@ the person consents, at the face match: a photo without one usable face fails th
250
247
  step with `no_face_reference` (or `low_quality_reference`). That step runs after liveness, so check
251
248
  that the photo shows exactly one clear face before you send it.
252
249
 
253
- Partner-supplied identity data is not billed: the identity step in `supplied` mode
250
+ Partner-supplied identity data is not billed: the Partner-supplied identity step
254
251
  records no usage event (other steps, such as the face match, bill as usual).
255
252
 
256
- The step reasons and codes about the number have generic names
257
- (`registry_record_not_found`, `id_number_locked`, `document_id_number_mismatch`, ...)
258
- and the API sends them as `nni_not_found`, `nni_locked`, `document_nni_mismatch`
259
- today, so accept both. The table is on the
260
- [Person data](https://docs.sekyro.ai/en/guides/person-data#renamed-reasons-and-codes)
261
- page.
253
+ The step reasons and codes about the number are `registry_record_not_found`,
254
+ `id_number_invalid`, `id_number_locked`, `document_id_number_mismatch` and
255
+ `sandbox_id_number_not_seeded`. See
256
+ [Person data](https://docs.sekyro.ai/en/guides/person-data).
262
257
 
263
258
  ### Errors
264
259
 
@@ -449,7 +444,7 @@ const result = await verifyResultToken(token, { appId: process.env.SEKYRO_APP_ID
449
444
  result.level; // 0 | 1 | 2 | 3 | null (1 human, 2 identity, 3 corroborated)
450
445
  result.assurance; // 'live_only' | 'document_biometric' | 'registry_biometric' | ...
451
446
  result.outcome; // 'approved' | 'rejected' | ...
452
- result.subjectId; // the person, when known
447
+ result.subjectId; // the person id without its per_ prefix, when known
453
448
  ```
454
449
 
455
450
  - Keys come from `https://api.sekyro.ai/.well-known/sekyro/jwks.json` and are
@@ -468,9 +463,9 @@ and `method` says how it was proved (`estimated` by the age check (selfie)
468
463
  step, or `document`, `chip`, `registry`, `eid`). The token never carries the
469
464
  estimated age; with the step's "Keep and show the estimated age" setting on,
470
465
  `estimate` and `sigma` arrive on the session (`sekyro.sessions.get`) and the
471
- `session.completed` / `session.failed` webhooks only. To carry the answer into
472
- an identity provider, map it to the claims `sekyro_age_over` (`result.age.over`)
473
- and `sekyro_age_method` (`result.age.method`).
466
+ `session.completed` / `session.failed` webhooks only. The connectors
467
+ (`@sekyro/node/connect`, see [Connect](#connect)) carry the answer into your
468
+ auth provider as `age_over` and `age_method` in the `sekyro` claim.
474
469
 
475
470
  `result.decision` is the `sekyro.decision` claim (`ResultDecision`, the same
476
471
  fields as a step's `decision`), when a person decided a step of the session.
@@ -555,13 +550,23 @@ app.get(
555
550
  // Next.js: sekyroGate() and gateRoute() from "@sekyro/node/connect/next".
556
551
  ```
557
552
 
558
- The claim (unix seconds; never a name, a document number, a photo or a score):
553
+ The claim (unix seconds; never a name, a document number, a photo, a score, a birth date or an estimated age):
559
554
 
560
555
  ```json
561
556
  { "v": 1, "level": 2, "assurance": "document_biometric", "verified_at": 1790000000, "rechecked_at": 1790003600,
562
- "session_id": "<session id>", "subject_id": "<subject id>", "env": "live", "flags": ["face_mismatch"] }
557
+ "session_id": "<session id>", "subject_id": "<subject id>", "env": "live", "flags": ["face_mismatch"],
558
+ "age_over": 18, "age_method": "document" }
563
559
  ```
564
560
 
561
+ `age_over` and `age_method` appear once a session of a flow with a minimum age
562
+ proved it: the flow's minimum age and how (`estimated`, or `document`, `chip`,
563
+ `registry`, `eid`). The claim keeps the stronger proof of the same person (a
564
+ birth date from identity data beats an estimate, then the higher minimum age).
565
+ Gate on it with `minAge`, and `ageMethods` when the route needs a proven birth
566
+ date: `{ level: 1, minAge: 18, ageMethods: ["document", "chip", "registry", "eid"] }`
567
+ fails with `age_not_proven` (action `verify`) or `age_method_not_allowed`
568
+ (action `step_up`).
569
+
565
570
  Trust rules:
566
571
 
567
572
  - A webhook writes only after its HMAC signature verified; retries are de-duplicated on the envelope id, which is never left recorded for a delivery whose handling failed (see the `store` contract in the guide).
@@ -1 +1 @@
1
- import{evaluateGate}from"./chunk-D53NUEJ6.js";function sekyroGate(source,tokenClaims,policy){let claims=tokenClaims??{};if("gate"in source)return source.gate(claims,policy);let effective=source.env!==void 0&&policy.env===void 0?{...policy,env:source.env}:policy;return evaluateGate(source.provider.readClaimFromToken(claims),effective)}function gateRoute(result,routes){if(result.ok)return null;switch(result.action){case"verify":return routes.verify;case"step_up":return routes.stepUp;case"recheck":return routes.recheck;case"block":return routes.block}}export{sekyroGate,gateRoute};
1
+ import{evaluateGate}from"./chunk-J6U2QY7M.js";function sekyroGate(source,tokenClaims,policy){let claims=tokenClaims??{};if("gate"in source)return source.gate(claims,policy);let effective=source.env!==void 0&&policy.env===void 0?{...policy,env:source.env}:policy;return evaluateGate(source.provider.readClaimFromToken(claims),effective)}function gateRoute(result,routes){if(result.ok)return null;switch(result.action){case"verify":return routes.verify;case"step_up":return routes.stepUp;case"recheck":return routes.recheck;case"block":return routes.block}}export{sekyroGate,gateRoute};
@@ -0,0 +1 @@
1
+ var CLAIM_VERSION=1,KNOWN_FLAGS=["face_mismatch","duplicate","revoked"],AGE_METHODS=["estimated","document","chip","registry","eid"];function ageProofOf(over,method){if(!(typeof over!="number"||!Number.isInteger(over)||over<=0)&&!(typeof method!="string"||!AGE_METHODS.includes(method)))return{over,method}}var ageRank=a=>a.method==="estimated"?0:1;function strongerAge(stored,next){if(!stored)return next;if(!next)return stored;let r=ageRank(next)-ageRank(stored);return r!==0?r>0?next:stored:next.over>stored.over?next:stored}var sameAge=(a,b)=>a?.over===b?.over&&a?.method===b?.method;function canonicalId(id){return id.replace(/^(ses|per)_/,"")}function isRecord(v){return typeof v=="object"&&v!==null&&!Array.isArray(v)}function isFiniteNumber(v){return typeof v=="number"&&Number.isFinite(v)}function build(c){let out={v:1,level:c.level,assurance:c.assurance,verified_at:c.verified_at};c.rechecked_at!==void 0&&(out.rechecked_at=c.rechecked_at),out.session_id=c.session_id,c.subject_id!==void 0&&(out.subject_id=canonicalId(c.subject_id)),out.env=c.env;let flags=new Set;for(let f of c.flags??[])KNOWN_FLAGS.includes(f)&&flags.add(f);flags.size>0&&(out.flags=[...flags].sort());let age=ageProofOf(c.age_over,c.age_method);return age&&(out.age_over=age.over,out.age_method=age.method),out}function ageFields(age){return{age_over:age?.over,age_method:age?.method}}function parseClaim(value){let v=value;if(typeof v=="string")try{v=JSON.parse(v)}catch{return null}if(!isRecord(v)||!isFiniteNumber(v.v))return null;if(v.v>1)return v;if(v.v!==1)return null;let level=v.level;return level!==0&&level!==1&&level!==2&&level!==3||typeof v.assurance!="string"||!isFiniteNumber(v.verified_at)||typeof v.session_id!="string"||v.env!=="live"&&v.env!=="sandbox"?null:build({level,assurance:v.assurance,verified_at:v.verified_at,rechecked_at:isFiniteNumber(v.rechecked_at)?v.rechecked_at:void 0,session_id:v.session_id,subject_id:typeof v.subject_id=="string"?v.subject_id:void 0,env:v.env,flags:Array.isArray(v.flags)?v.flags:void 0,age_over:v.age_over,age_method:v.age_method})}function toUnix(isoTime,now){let ms=Date.parse(isoTime);return Math.floor((Number.isFinite(ms)?ms:now())/1e3)}var same=(claim,rule)=>({claim,changed:!1,rule}),wrote=(claim,rule)=>({claim,changed:!0,rule});function mergeClaim(previous,event,opts){let now=opts.now??Date.now,prev=parseClaim(previous);if(prev&&prev.v>1)return same(prev,"unsupported_version");if(event.kind==="revoked"||event.kind==="deleted"){if(!prev)return same(null,"no_change");if(!(prev.subject_id===void 0?event.userInExternalRefs===!0:prev.subject_id===canonicalId(event.subjectId)))return same(prev,"subject_mismatch");if(prev.level===0&&prev.flags?.includes("revoked"))return same(prev,"no_change");let{rechecked_at:_cleared,age_over:_over,age_method:_method,...kept}=prev;return wrote(build({...kept,level:0,subject_id:event.subjectId,flags:["revoked"]}),"revoked")}let r=event.result;if(r.env!==opts.env)return same(prev,"env_mismatch");let t=toUnix(r.verifiedAt,now);if(prev&&t<prev.verified_at)return same(prev,"stale_ignored");let revokedPrev=prev?.flags?.includes("revoked")===!0;if(prev&&revokedPrev&&(r.subjectId===void 0||canonicalId(r.subjectId)===prev.subject_id))return same(prev,"revoked_ignored");if(r.outcome==="rejected"&&r.subjectConflict===!0)return!prev||prev.flags?.includes("face_mismatch")?same(prev,"no_change"):wrote(build({...prev,flags:[...prev.flags??[],"face_mismatch"]}),"face_mismatch");if(r.outcome!=="approved"||r.level===null||r.level===0)return same(prev,"not_approved");let level=r.level,assurance=r.assurance??"none",duplicate=r.duplicates===!0?["duplicate"]:[],nextAge=r.age?ageProofOf(r.age.over,r.age.method):void 0;if(!prev)return wrote(build({level,assurance,verified_at:t,session_id:r.sessionId,subject_id:r.subjectId,env:r.env,flags:duplicate,...ageFields(nextAge)}),"created");let prevAge=ageProofOf(prev.age_over,prev.age_method),otherPerson=prev.subject_id!==void 0&&r.subjectId!==void 0&&canonicalId(r.subjectId)!==prev.subject_id,mergedAge=otherPerson?prevAge:strongerAge(prevAge,nextAge);if(!revokedPrev&&(r.reuseMode==="recheck"||r.returning===!0&&level<=prev.level))return prev.rechecked_at!==void 0&&t<=prev.rechecked_at?same(prev,t<prev.rechecked_at?"stale_ignored":"no_change"):wrote(build({...prev,rechecked_at:t,subject_id:prev.subject_id??r.subjectId,...ageFields(mergedAge)}),"rechecked");if(level>prev.level){let kept=(prev.flags??[]).filter(f=>f!=="face_mismatch"&&f!=="revoked");return wrote(build({...prev,level,assurance,verified_at:t,session_id:r.sessionId,subject_id:r.subjectId??prev.subject_id,flags:[...kept,...duplicate],...ageFields(otherPerson?nextAge:mergedAge)}),"raised")}return level===prev.level&&t>prev.verified_at?wrote(build({...prev,assurance,verified_at:t,session_id:r.sessionId,subject_id:prev.subject_id??r.subjectId,flags:[...prev.flags??[],...duplicate],...ageFields(mergedAge)}),"renewed"):sameAge(mergedAge,prevAge)?same(prev,"no_change"):wrote(build({...prev,subject_id:prev.subject_id??r.subjectId,...ageFields(mergedAge)}),"age_proved")}var DEFAULT_DENY_FLAGS=["revoked","face_mismatch"],fail=(reason,action,claim)=>({ok:!1,reason,action,claim});function evaluateGate(claim,policy,nowSec=Math.floor(Date.now()/1e3)){let parsed=parseClaim(claim);if(!parsed)return fail("no_claim","verify",null);if(parsed.v>1)return fail("unsupported_version","verify",parsed);if(policy.env!==void 0&&parsed.env!==policy.env)return fail("wrong_env","verify",parsed);let deny=policy.denyFlags??DEFAULT_DENY_FLAGS;if(parsed.flags?.some(f=>deny.includes(f)))return fail("flagged","block",parsed);if(parsed.level<policy.level)return fail("level_too_low",parsed.level>=1?"step_up":"verify",parsed);if(policy.maxAgeDays!==void 0&&nowSec-parsed.verified_at>policy.maxAgeDays*86400)return fail("stale","recheck",parsed);if(policy.maxRecheckAgeMinutes!==void 0&&nowSec-(parsed.rechecked_at??parsed.verified_at)>policy.maxRecheckAgeMinutes*60)return fail("recheck_stale","recheck",parsed);if(policy.assurance&&!policy.assurance.includes(parsed.assurance))return fail("assurance_not_allowed","step_up",parsed);if(policy.minAge!==void 0){if(parsed.age_over===void 0||parsed.age_over<policy.minAge)return fail("age_not_proven","verify",parsed);if(policy.ageMethods&&(parsed.age_method===void 0||!policy.ageMethods.includes(parsed.age_method)))return fail("age_method_not_allowed","step_up",parsed)}return{ok:!0,claim:parsed}}export{CLAIM_VERSION,canonicalId,parseClaim,mergeClaim,evaluateGate};
@@ -120,7 +120,7 @@ interface SessionLinkInput {
120
120
  */
121
121
  type IdentityMethod = "national_number" | "document_photo" | "document_chip" | "national_eid";
122
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";
123
+ type CheckType = "liveness" | "face_match" | "doc_ocr" | "population_registry" | "phone_otp" | "nfc_chip" | "email_otp" | "portrait_icao" | "eid_auth" | "aml_screening";
124
124
  /** Per-check execution state within a session. @public */
125
125
  type CheckState = "pending" | "input_required" | "processing" | "passed" | "failed" | "review" | "skipped";
126
126
  /**
@@ -177,7 +177,7 @@ type EligibilityReason = "document_type_not_accepted" | "nationality_not_allowed
177
177
  * nobody settled it); those two carry `decidedBy: "automatic"`.
178
178
  * @public
179
179
  */
180
- type PolicyFailureReason = SessionFailureReason | EligibilityReason | "document_id_number_mismatch" | "document_nni_mismatch" | "camera_unavailable" | "subject_face_mismatch" | "review_timeout" | "review_split";
180
+ type PolicyFailureReason = SessionFailureReason | EligibilityReason | "document_id_number_mismatch" | "document_nni_mismatch" | "camera_unavailable" | "subject_face_mismatch" | "review_timeout" | "review_split" | "aml_hit";
181
181
  /**
182
182
  * The ID-number reasons a check's {@link SessionStep.reason} may carry (person data
183
183
  * spec Appendix A.2), each under its generic name and its former Mauritanian name:
@@ -232,7 +232,7 @@ type ReviewOutcomeReason = "superseded_by_retry" | "review_split";
232
232
  * reviewer overrode on an approval.
233
233
  * @public
234
234
  */
235
- type ReviewReason = "document_authenticity" | "liveness" | "face_match" | "data_mismatch" | "other";
235
+ type ReviewReason = "document_authenticity" | "liveness" | "face_match" | "data_mismatch" | "screening" | "other";
236
236
  /**
237
237
  * How a person decided a step: a reviewer (`source: "review"`), or an earlier
238
238
  * review of the same person, reference photo and face that was reused
@@ -300,9 +300,8 @@ interface FailureIdentification {
300
300
  */
301
301
  type ProbeBindingReason = "probe_not_from_liveness";
302
302
  /**
303
- * The languages the person being verified sees (hosted flow and SDK screens; spec 2026-10-29 §9). `ar`, `fr` and `en`
304
- * carry every screen; `es`, `pt` and `de` carry the Human verification screens and show English elsewhere. SMS and
305
- * email messages stay in `ar`, `fr` or `en` (English for the three others).
303
+ * The languages the person being verified sees (hosted flow and SDK screens; spec 2026-10-29 §9), every screen in
304
+ * each. SMS and email messages stay in `ar`, `fr` or `en` (English for the three others).
306
305
  * @public
307
306
  */
308
307
  type Locale = "ar" | "fr" | "en" | "es" | "pt" | "de";
@@ -773,9 +772,14 @@ interface FlowServiceSettings {
773
772
  reference: "auto" | "document" | "registry";
774
773
  attempts?: number;
775
774
  };
775
+ /**
776
+ * Sanctions and PEP screening of the person the flow verified. `onHit`: `signal`
777
+ * (the session goes on and the match is reported), `review` (a reviewer
778
+ * decides) or `fail` (the session is rejected with `aml_hit`).
779
+ */
776
780
  aml_screening: {
777
- lists: Array<"sanctions" | "pep" | "adverse_media">;
778
- onHit: "review" | "fail";
781
+ lists: ScreeningList[];
782
+ onHit: "signal" | "review" | "fail";
779
783
  };
780
784
  face_dedup: {
781
785
  scope: "app" | "org";
@@ -1491,6 +1495,11 @@ interface Session {
1491
1495
  * setting is on. A signal, never a decision.
1492
1496
  */
1493
1497
  failureIdentification?: FailureIdentification;
1498
+ /**
1499
+ * Terminal sessions whose flow screens the person against sanctions and PEP
1500
+ * lists: the result ({@link SessionScreening}), or why it could not run.
1501
+ */
1502
+ screening?: SessionScreening;
1494
1503
  }
1495
1504
  /**
1496
1505
  * `data` of the session lifecycle events (`session.started` |
@@ -1618,6 +1627,8 @@ interface SessionLifecycleEventData {
1618
1627
  * found one before the event was sent. A signal, never a decision.
1619
1628
  */
1620
1629
  failureIdentification?: FailureIdentification;
1630
+ /** On `completed` / `failed`: the AML screening result ({@link SessionScreening}), when the flow screens the person. */
1631
+ screening?: SessionScreening;
1621
1632
  }
1622
1633
  /**
1623
1634
  * `data` of `subject.updated` — either a session linked to the subject reached
@@ -1810,6 +1821,130 @@ interface DeletedPerson {
1810
1821
  }
1811
1822
  /** @deprecated Use {@link DeletedPerson}. @public */
1812
1823
  type DeletedSubject = DeletedPerson;
1824
+ /** The lists an AML screening can search. @public */
1825
+ type ScreeningList = "sanctions" | "pep" | "adverse_media";
1826
+ /**
1827
+ * Where a screening stands: `clear` (nothing scored above the possible
1828
+ * threshold), `possible` (a possible match), `hit` (a match), `confirmed` or
1829
+ * `dismissed` (a person of your organization decided the hits), `unavailable`
1830
+ * (the lists could not be searched; never billed).
1831
+ * @public
1832
+ */
1833
+ type ScreeningStatus = "clear" | "possible" | "hit" | "confirmed" | "dismissed" | "unavailable";
1834
+ /** Why the lists could not be searched. @public */
1835
+ type ScreeningUnavailableReason = "screening_unavailable" | "no_identity_data" | "no_list_covered";
1836
+ /** What ran a screening: a session step, a screening run again, or ongoing screening. @public */
1837
+ type ScreeningTrigger = "session" | "rescreen" | "monitor";
1838
+ /** A list entry that matched the person, best first. Public list data. @public */
1839
+ interface ScreeningHitSummary {
1840
+ /** The stable id of the list entry. */
1841
+ entityId: string;
1842
+ /** The name of the entry as the list publishes it. */
1843
+ caption: string;
1844
+ /** How closely the entry matches the person, 0 to 1. */
1845
+ score: number;
1846
+ /** The searched lists the entry is on. */
1847
+ lists: ScreeningList[];
1848
+ }
1849
+ /** A list entry that matched, with its public attributes and sources. @public */
1850
+ interface ScreeningHit extends ScreeningHitSummary {
1851
+ /** The tags of the entry on its lists (`sanction`, `role.pep`, ...). */
1852
+ topics: string[];
1853
+ /** The source datasets of the entry. */
1854
+ datasets: string[];
1855
+ /** Public attributes of the entry, when the list publishes them. */
1856
+ attributes: {
1857
+ birthDates?: string[];
1858
+ nationalities?: string[];
1859
+ positions?: string[];
1860
+ aliases?: string[];
1861
+ gender?: string;
1862
+ };
1863
+ /** Where the list publishes the entry. */
1864
+ sourceUrls: string[];
1865
+ firstSeen?: string;
1866
+ lastSeen?: string;
1867
+ }
1868
+ /**
1869
+ * {@link Session.screening}: the search a session's AML screening step ran, or
1870
+ * `{ unavailable }` alone when it could not run.
1871
+ * @public
1872
+ */
1873
+ type SessionScreening = {
1874
+ /** The screening id (`scr_...`); see {@link PeopleApi.screenings}. */
1875
+ id: string;
1876
+ status: Exclude<ScreeningStatus, "unavailable">;
1877
+ /** The lists the flow asked for. */
1878
+ lists: ScreeningList[];
1879
+ /** The lists actually searched. */
1880
+ listsCovered: ScreeningList[];
1881
+ /** The list data release the search ran on. */
1882
+ datasetVersion: string;
1883
+ /** The best score, 0 when nothing matched. */
1884
+ topScore: number;
1885
+ hits: ScreeningHitSummary[];
1886
+ } | {
1887
+ unavailable: ScreeningUnavailableReason;
1888
+ };
1889
+ /** One screening of a person ({@link PeopleApi.screen}, {@link PeopleApi.screenings}). @public */
1890
+ interface Screening {
1891
+ /** The screening id (`scr_...`). */
1892
+ id: string;
1893
+ trigger: ScreeningTrigger;
1894
+ status: ScreeningStatus;
1895
+ /** With `status: "unavailable"`: why the lists could not be searched. */
1896
+ unavailable?: ScreeningUnavailableReason;
1897
+ /** The lists asked for. */
1898
+ lists: ScreeningList[];
1899
+ /** The lists actually searched. */
1900
+ listsCovered: ScreeningList[];
1901
+ /** The list data release the search ran on. */
1902
+ datasetVersion: string;
1903
+ /** The best score, 0 when nothing matched. */
1904
+ topScore: number;
1905
+ /** The matching entries, best first. */
1906
+ hits: ScreeningHit[];
1907
+ /** The decision of a person of your organization on the hits, once made. */
1908
+ decision?: {
1909
+ outcome: "confirmed" | "dismissed";
1910
+ at: string;
1911
+ note?: string;
1912
+ };
1913
+ /** ISO 8601. */
1914
+ createdAt: string;
1915
+ }
1916
+ /** Input of {@link PeopleApi.screen}. @public */
1917
+ interface ScreenPersonInput {
1918
+ /** The lists to search, each once. Default `["sanctions", "pep"]`. */
1919
+ lists?: ScreeningList[];
1920
+ }
1921
+ /** Query of {@link PeopleApi.screenings}. @public */
1922
+ interface ListScreeningsQuery {
1923
+ /** Page size, 1 to 50 (the API's default is 25). */
1924
+ limit?: number;
1925
+ /** The {@link Page.nextCursor} of the previous page. */
1926
+ cursor?: string;
1927
+ }
1928
+ /**
1929
+ * `data` of `aml.match_flagged`: a screening settled `hit` or `possible`, from
1930
+ * a session step, a screening run again or ongoing screening. Sent once per
1931
+ * screening (de-duplicate on `screeningId`); a decision sends no event.
1932
+ * @public
1933
+ */
1934
+ interface AmlMatchFlaggedEventData {
1935
+ screeningId: string;
1936
+ trigger: ScreeningTrigger;
1937
+ /** The session the screening ran in, or the person's latest approved session. */
1938
+ sessionId?: string;
1939
+ /** The person (`per_...`), once known. */
1940
+ personId?: string;
1941
+ status: "hit" | "possible";
1942
+ lists: ScreeningList[];
1943
+ listsCovered: ScreeningList[];
1944
+ datasetVersion: string;
1945
+ topScore: number;
1946
+ hits: ScreeningHitSummary[];
1947
+ }
1813
1948
  /** Options of {@link PeopleApi.revoke}. @public */
1814
1949
  interface RevokePersonInput {
1815
1950
  /** Kept on the audit trail only (≤ 500 characters). Do not put personal data here. */
@@ -2057,8 +2192,7 @@ interface WebhookEventDataMap {
2057
2192
  "subject.suspicious_activity": SubjectSuspiciousActivityEventData;
2058
2193
  /** @deprecated Subscribe to `person.deleted`, sent next to it with `personId`. */
2059
2194
  "subject.deleted": SubjectDeletedEventData;
2060
- /** @deprecated Leaves the catalog after this release (no AML feature behind it). */
2061
- "aml.match_flagged": Record<string, unknown>;
2195
+ "aml.match_flagged": AmlMatchFlaggedEventData;
2062
2196
  "payment.received": Record<string, unknown>;
2063
2197
  "invoice.generated": Record<string, unknown>;
2064
2198
  "invoice.paid": Record<string, unknown>;
@@ -2307,6 +2441,27 @@ declare class PeopleApi {
2307
2441
  * Emits `person.updated` (and `subject.updated`) with `status: 'revoked'`.
2308
2442
  */
2309
2443
  revoke(id: string, input?: RevokePersonInput, opts?: RequestOptions): Promise<Person>;
2444
+ /**
2445
+ * `POST /people/:id/screen` — screens a verified person again against
2446
+ * sanctions and PEP lists (`lists`, default sanctions and PEP), from the
2447
+ * person's stored name, birth date and the issuing countries of their identity
2448
+ * numbers. Billed as one AML screening; a refusal is not billed
2449
+ * (`400 screening_list_not_covered`, `403 service_not_in_plan`,
2450
+ * `503 screening_unavailable`). A hit or a possible match also sends
2451
+ * `aml.match_flagged`. Pass an `idempotencyKey` so a retried call is not
2452
+ * billed twice.
2453
+ */
2454
+ screen(id: string, input?: ScreenPersonInput, opts?: RequestOptions): Promise<Screening>;
2455
+ /**
2456
+ * The first page of a person's screenings, newest first
2457
+ * (`GET /people/:id/screenings`; 25 by default, at most 50 with `limit`).
2458
+ * Every page: {@link PeopleApi.iterateScreenings}.
2459
+ */
2460
+ screenings(id: string, query?: ListScreeningsQuery): Promise<Screening[]>;
2461
+ /** One page of {@link PeopleApi.screenings} with its `nextCursor` (absent on the last page). */
2462
+ screeningsPage(id: string, query?: ListScreeningsQuery): Promise<Page<Screening>>;
2463
+ /** Every screening of a person, newest first, following `nextCursor` page after page. */
2464
+ iterateScreenings(id: string, query?: ListScreeningsQuery): AsyncGenerator<Screening, void, undefined>;
2310
2465
  /**
2311
2466
  * `DELETE /people/:id` — deletes the person's stored photos, face
2312
2467
  * templates and identifiers, and the personal data and media of their
@@ -2361,4 +2516,4 @@ declare class Sekyro {
2361
2516
  listFlows(): Promise<FlowSummary[]>;
2362
2517
  }
2363
2518
 
2364
- export { type LevelTarget as $, type AgeMethod as A, type DocumentSubstitutionSettings as B, type CreatedSession as C, DEFAULT_BASE_URL as D, type EidResult as E, type FetchLike as F, type EligibilityReason as G, type ExtendLinkInput as H, type FlowOverridableSettings as I, type FlowOverrides as J, type FlowServiceSettings as K, type Locale as L, type FlowSummary as M, type IdNumberReason as N, type Identity as O, type IdentityBirthPlace as P, type IdentityDocument as Q, type ReviewReason as R, Sekyro as S, type IdentityIdNumber as T, type IdentityMethod as U, type VerificationLevel as V, type WebhookEventType as W, type IdentityName as X, type IdentityScalarKey as Y, type IdentitySource as Z, type IdentitySources as _, type ServiceId as a, type SubjectSession as a$, type ListPeopleQuery as a0, type ListSessionsQuery as a1, type MatchReason as a2, type MediaBytes as a3, type MediaBytesOptions as a4, type MediaItem as a5, type MediaKind as a6, type MediaList as a7, type NameForm as a8, type Page as a9, type SessionEventData as aA, type SessionFailureReason as aB, type SessionFlowRef as aC, type SessionLifecycleEventData as aD, type SessionLinkDelivery as aE, type SessionLinkExpiry as aF, type SessionLinkInput as aG, type SessionNetwork as aH, type SessionNetworkEvent as aI, type SessionPortraitLink as aJ, type SessionReviewDecidedEventData as aK, type SessionStatus as aL, type SessionStep as aM, type SessionStepCompletedEventData as aN, type SessionStepDecision as aO, type SessionSubjectInput as aP, type SessionSupersededEventData as aQ, SessionsApi as aR, type Subject as aS, type SubjectAssurance as aT, type SubjectDeletedEventData as aU, type SubjectEnrolledEventData as aV, type SubjectIdNumber as aW, type SubjectName as aX, type SubjectReferenceSource as aY, type SubjectReuseDocument as aZ, type SubjectReuseTarget as a_, PeopleApi as aa, type Person as ab, type PersonBirthPlaceInput as ac, type PersonDeletedEventData as ad, type PersonDocumentInput as ae, type PersonEnrolledEventData as af, type PersonSession as ag, type PersonSessionInput as ah, type PersonSessionTarget as ai, type PersonSuspiciousActivityEventData as aj, type PersonUpdatedEventData as ak, type PolicyFailureReason as al, type PortraitReportEntry as am, type PriorReviewReason as an, type ProbeBindingReason as ao, type ProbeQuality as ap, type ProfileDocumentType as aq, type RequestOptions as ar, type ResultTokenResponse as as, type ReviewOutcomeReason as at, type RevokePersonInput as au, type RevokeSubjectInput as av, type SekyroOptions as aw, type Session as ax, type SessionDevice as ay, type SessionDeviceSignal as az, type SessionPersonInput as b, type SubjectSessionInput as b0, type SubjectSessionTarget as b1, type SubjectStatus as b2, type SubjectSuspiciousActivityEventData as b3, type SubjectUpdatedEventData as b4, type SubjectsApi as b5, type SuppliedIdentityRecord as b6, type UsageThresholdReachedEventData as b7, type VerifiedContacts as b8, type WebhookEnvelopeOf as b9, type WebhookEventDataMap as ba, type WebhookEnvelope as c, type SekyroEnvironment as d, type VerificationAssurance as e, type SessionOutcome as f, type VerificationUnit as g, type SubjectReuseMode as h, type ResultRisk as i, type ResultCheckProofs as j, type ResultDuplicate as k, type FailureIdentification as l, type AgeResult as m, type CameraUnavailableCause as n, type CheckState as o, type CheckType as p, type ConnectorIdentity as q, type CreateSessionInput as r, type CreatedSessionWarning as s, DEFAULT_TIMEOUT_MS as t, type DecidedBy as u, type DecisionReason as v, type DeepPartial as w, type DeletedPerson as x, type DeletedSubject as y, type DeliverOptions as z };
2519
+ export { type IdentitySources as $, type AgeMethod as A, type DeliverOptions as B, type CreatedSession as C, DEFAULT_BASE_URL as D, type DocumentSubstitutionSettings as E, type FetchLike as F, type EidResult as G, type EligibilityReason as H, type ExtendLinkInput as I, type FlowOverridableSettings as J, type FlowOverrides as K, type Locale as L, type FlowServiceSettings as M, type FlowSummary as N, type IdNumberReason as O, type Identity as P, type IdentityBirthPlace as Q, type ReviewReason as R, Sekyro as S, type IdentityDocument as T, type IdentityIdNumber as U, type VerificationLevel as V, type WebhookEventType as W, type IdentityMethod as X, type IdentityName as Y, type IdentityScalarKey as Z, type IdentitySource as _, type ServiceId as a, type SessionSupersededEventData as a$, type LevelTarget as a0, type ListPeopleQuery as a1, type ListScreeningsQuery as a2, type ListSessionsQuery as a3, type MatchReason as a4, type MediaBytes as a5, type MediaBytesOptions as a6, type MediaItem as a7, type MediaKind as a8, type MediaList as a9, type ScreeningHit as aA, type ScreeningHitSummary as aB, type ScreeningList as aC, type ScreeningStatus as aD, type ScreeningTrigger as aE, type ScreeningUnavailableReason as aF, type SekyroOptions as aG, type Session as aH, type SessionDevice as aI, type SessionDeviceSignal as aJ, type SessionEventData as aK, type SessionFailureReason as aL, type SessionFlowRef as aM, type SessionLifecycleEventData as aN, type SessionLinkDelivery as aO, type SessionLinkExpiry as aP, type SessionLinkInput as aQ, type SessionNetwork as aR, type SessionNetworkEvent as aS, type SessionPortraitLink as aT, type SessionReviewDecidedEventData as aU, type SessionScreening as aV, type SessionStatus as aW, type SessionStep as aX, type SessionStepCompletedEventData as aY, type SessionStepDecision as aZ, type SessionSubjectInput as a_, type NameForm as aa, type Page as ab, PeopleApi as ac, type Person as ad, type PersonBirthPlaceInput as ae, type PersonDeletedEventData as af, type PersonDocumentInput as ag, type PersonEnrolledEventData as ah, type PersonSession as ai, type PersonSessionInput as aj, type PersonSessionTarget as ak, type PersonSuspiciousActivityEventData as al, type PersonUpdatedEventData as am, type PolicyFailureReason as an, type PortraitReportEntry as ao, type PriorReviewReason as ap, type ProbeBindingReason as aq, type ProbeQuality as ar, type ProfileDocumentType as as, type RequestOptions as at, type ResultTokenResponse as au, type ReviewOutcomeReason as av, type RevokePersonInput as aw, type RevokeSubjectInput as ax, type ScreenPersonInput as ay, type Screening as az, type SessionPersonInput as b, SessionsApi as b0, type Subject as b1, type SubjectAssurance as b2, type SubjectDeletedEventData as b3, type SubjectEnrolledEventData as b4, type SubjectIdNumber as b5, type SubjectName as b6, type SubjectReferenceSource as b7, type SubjectReuseDocument as b8, type SubjectReuseTarget as b9, type SubjectSession as ba, type SubjectSessionInput as bb, type SubjectSessionTarget as bc, type SubjectStatus as bd, type SubjectSuspiciousActivityEventData as be, type SubjectUpdatedEventData as bf, type SubjectsApi as bg, type SuppliedIdentityRecord as bh, type UsageThresholdReachedEventData as bi, type VerifiedContacts as bj, type WebhookEnvelopeOf as bk, type WebhookEventDataMap as bl, 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 CameraUnavailableCause as o, type CheckState as p, type CheckType as q, type ConnectorIdentity as r, type CreateSessionInput as s, type CreatedSessionWarning as t, DEFAULT_TIMEOUT_MS as u, type DecidedBy as v, type DecisionReason as w, type DeepPartial as x, type DeletedPerson as y, type DeletedSubject as z };