@sekyro/node 0.1.0-rc.2 → 0.1.0-rc.4

package/dist/index.d.ts

@@ -1,5 +1,5 @@
 /**
- * Wire-level enums and shapes of the Sekyro partner API (`/api/v2`). These
+ * Wire-level enums and shapes of the Sekyro AI partner API (`/api/v2`). These
  * mirror the backend's frozen partner contract; they are plain string unions so
  * a newer API value never throws at runtime — it simply widens the type in the
  * next SDK release.
@@ -14,10 +14,81 @@ type SessionStatus = "created" | "in_progress" | "review_pending" | "completed"
  * @public
  */
 type SessionOutcome = "approved" | "review" | "rejected";
+/**
+ * How the person proves their identity on an optional-document app: type the
+ * national number, or photograph the document (`document_chip`: native NFC clients only).
+ * `national_eid`: the country's national eID (e.g. Houwiyeti for Mauritania),
+ * offered when the app's profile turns the national eID on.
+ * @public
+ */
+type IdentityMethod = "national_number" | "document_photo" | "document_chip" | "national_eid";
 /** The verification checks a flow may contain. @public */
-type CheckType = "liveness" | "face_match" | "doc_ocr" | "population_registry" | "phone_otp";
+type CheckType = "liveness" | "face_match" | "doc_ocr" | "population_registry" | "phone_otp" | "nfc_chip" | "email_otp" | "portrait_icao" | "eid_auth";
 /** Per-check execution state within a session. @public */
 type CheckState = "pending" | "input_required" | "processing" | "passed" | "failed" | "review" | "skipped";
+/**
+ * Why a session was stopped by a profile-v2 policy gate rather than by a
+ * failed check:
+ *  - `location_not_allowed` — the end user's IP location is not allowed for the app;
+ *  - `anonymizer_blocked` — an anonymizer (VPN / proxy / Tor) was detected while the app blocks them;
+ *  - `capture_tampered` — the device reported a tampered capture (virtual
+ *    camera, hooking, emulator…) while the app's `device.tamper` is `block`;
+ *  - `device_velocity_exceeded` — the device already verified more different
+ *    people than `device.velocity` allows, with `action: 'block'`;
+ *  - `device_cooldown` — the device had too many rejected sessions
+ *    (`cooldown` tiers); {@link Session.retryAfter} says when it may try again.
+ *    Not billed.
+ * @public
+ */
+type SessionFailureReason = "location_not_allowed" | "anonymizer_blocked" | "capture_tampered" | "device_velocity_exceeded" | "device_cooldown";
+/**
+ * Profile-v2 decision-mode reasons a check's {@link SessionStep.reason} may
+ * carry when the app decides automatically (`decisions.mode: 'automatic'`)
+ * instead of routing to human review. All are retryable within the step's
+ * attempts: `liveness_inconclusive` (liveness middle band),
+ * `match_inconclusive` (face match middle band on every reference),
+ * `document_authenticity` (doc_ocr authenticity warning — retake the original)
+ * and `mobile_required` (liveness captured on a desktop — continue on a phone;
+ * not billed). Every inconclusive attempt is billed.
+ * @public
+ */
+type DecisionReason = "liveness_inconclusive" | "match_inconclusive" | "document_authenticity" | "mobile_required";
+/**
+ * Profile-v2 eligibility reasons a check's {@link SessionStep.reason} may carry:
+ * `document_type_not_accepted` (doc_ocr; the person may pick another
+ * document), `nationality_not_allowed` and `underage` (doc_ocr or
+ * population_registry; terminal), and `age_unverifiable` (the app sets a
+ * minimum age but the birth date could not be read — doc_ocr: retryable with
+ * a clearer photo; population_registry: terminal).
+ * @public
+ */
+type EligibilityReason = "document_type_not_accepted" | "nationality_not_allowed" | "underage" | "age_unverifiable";
+/**
+ * Why a profile-v2 policy ended a session: a session-level
+ * {@link SessionFailureReason} (location / anonymizer gate), or the failed
+ * check's policy reason — an {@link EligibilityReason} or
+ * `document_nni_mismatch` (the document belongs to someone other than the
+ * NNI the session was created for).
+ * @public
+ */
+type PolicyFailureReason = SessionFailureReason | EligibilityReason | "document_nni_mismatch";
+/**
+ * Profile-v2 matching reasons a check's {@link SessionStep.reason} may carry
+ * when the data you sent in {@link CreateSessionInput.subject} differs from the
+ * reference identity: `name_mismatch`, `birth_date_mismatch`,
+ * `nationality_mismatch` (doc_ocr or population_registry) and
+ * `document_number_mismatch` (doc_ocr). All are final.
+ * @public
+ */
+type MatchReason = "name_mismatch" | "birth_date_mismatch" | "nationality_mismatch" | "document_number_mismatch";
+/**
+ * Face-match probe-binding reason a `face_match` {@link SessionStep.reason} may
+ * carry (SDK spec §4.10): `probe_not_from_liveness` — the face image isn't the
+ * person in the liveness clip. Retryable within the step's attempts (the
+ * person re-takes the liveness capture); billed.
+ * @public
+ */
+type ProbeBindingReason = "probe_not_from_liveness";
 /** Hosted-flow languages. @public */
 type Locale = "ar" | "fr" | "en";
 /** The environment a webhook was emitted from. @public */
@@ -34,9 +105,62 @@ interface SessionStep {
     reason?: string;
     /** Calibrated model score in [0, 1] for scored checks (liveness, face match). */
     calibratedScore?: number;
+    /** The check failed after using all of its attempts. */
+    attemptsExhausted?: boolean;
+    /**
+     * `portrait_icao` only (ID mode): the per-criterion ICAO report of the last
+     * attempt — numbers and enums only, never the image.
+     */
+    report?: PortraitReportEntry[];
+    /**
+     * `face_match` only: the probe-quality measurement of the selfie that was
+     * matched (occlusion, head pose, eye openness, sharpness). Recorded for
+     * information only: it never changes the step's state or reason.
+     */
+    probeQuality?: ProbeQuality;
 }
 /**
- * Out-of-band delivery of the session's hosted link, sent by Sekyro after the
+ * The probe-quality measurement on a `face_match` step. Numbers only; `null`
+ * means the value could not be measured. Informational: no threshold applies.
+ * @public
+ */
+interface ProbeQuality {
+    /** Share of the inner face that is covered (a hand, a mask, a phone), in [0, 1]. */
+    occlusion: number | null;
+    /** Head pose in degrees. */
+    pose: {
+        yaw: number | null;
+        pitch: number | null;
+        roll: number | null;
+    };
+    /** Openness of the less-open eye, in [0, 1]. */
+    eyesOpen: number | null;
+    /** Sharpness of the face region (higher is sharper; no fixed scale). */
+    sharpness: number | null;
+}
+/**
+ * One row of the `portrait_icao` report (ID mode): the server's measurement of
+ * one ICAO criterion and the threshold that applied.
+ * @public
+ */
+interface PortraitReportEntry {
+    criterion: "pose" | "eyes" | "mouth" | "occlusion" | "glare" | "lighting" | "background" | "resolution";
+    value: number | null;
+    threshold: number | string | null;
+    pass: boolean;
+}
+/**
+ * A short-lived link to a session's ICAO portrait (480×640 JPEG), from
+ * {@link SessionsApi.portrait}. Download it before `expiresAt`; never store the URL.
+ * @public
+ */
+interface SessionPortraitLink {
+    url: string;
+    /** ISO 8601 (about 5 minutes after the call). */
+    expiresAt: string;
+}
+/**
+ * Out-of-band delivery of the session's hosted link, sent by Sekyro AI after the
  * session is created. Best effort: a failed send never fails the create.
  * @public
  */
@@ -46,6 +170,225 @@ interface DeliverOptions {
     /** E.164 phone number of the recipient, e.g. `+22236123456`. */
     to: string;
 }
+/**
+ * What you already know about the person (`subject` at session create). A
+ * closed object: unknown keys are refused (`400`). Every field is optional;
+ * `null` or blank counts as absent. Identity fields are compared with the
+ * person's document or registry record when the app's profile turns name
+ * matching on; `nni` binds the session to that identity.
+ * @public
+ */
+interface SessionSubjectInput {
+    /** 10-digit Mauritanian NNI, as a string. */
+    nni?: string;
+    /** E.164 phone number, e.g. `+22236123456`. */
+    phone?: string;
+    fullName?: string;
+    /** ISO 8601 date (`YYYY-MM-DD`). */
+    birthDate?: string;
+    /** ISO 3166-1 alpha-2, e.g. `MR`. */
+    nationality?: string;
+    /** Identity-document number (1–40 characters). */
+    documentNumber?: string;
+    /**
+     * Your own id for this person (1–128 characters). Echoed on the session and
+     * its webhooks, and searchable on the subjects API.
+     */
+    externalRef?: string;
+    /**
+     * Returning user (profile v2 step 5): verify this already-verified subject
+     * again with liveness + face match only, against the reference photo stored
+     * on the subject. Name exactly one target. Errors at create:
+     * `404 subject_not_found`, `409 subject_revoked`, `409 subject_no_reference`,
+     * `409 subject_stale` (older than the app's `reuse.maxAgeMonths`) and
+     * `400` / `409 reuse_target_ambiguous`.
+     */
+    reuse?: SubjectReuseTarget;
+}
+/**
+ * Which subject a returning-user session re-verifies — exactly ONE of the
+ * subject id, your own `externalRef` (must match a single subject) or the NNI.
+ * @public
+ */
+type SubjectReuseTarget = {
+    subjectId: string;
+    externalRef?: never;
+    nni?: never;
+} | {
+    externalRef: string;
+    subjectId?: never;
+    nni?: never;
+} | {
+    nni: string;
+    subjectId?: never;
+    externalRef?: never;
+};
+/** A document type the backend reads (kyc-docs-v2 vocabulary; `carte_identite` = identity card of any issuer). @public */
+type ProfileDocumentType = "carte_identite" | "passport" | "residence_permit";
+/**
+ * The settings of an app's eKYC profile that a session may override — a
+ * mirror of the backend profile (schema version 2) without `schemaVersion`,
+ * `link` (use {@link CreateSessionInput.ttlMinutes}) and `overrides` (the
+ * app's own permission). Country codes are ISO 3166-1 alpha-2 (`MR`).
+ * Used through {@link EkycProfileOverride}.
+ * @public
+ */
+interface EkycProfileSettings {
+    /**
+     * Phone OTP step: off, or on with where the number comes from. The person
+     * chooses WhatsApp or SMS from the channels left after the org's settings
+     * and `channels`.
+     */
+    phone: "off" | {
+        /** Where the number comes from: your `subject.phone` / `input.phone`, the person, or either. */
+        numberSource: "prefilled" | "user_entered" | "prefilled_or_entered";
+        /**
+         * Narrow the channels the person may choose from (absent = every
+         * channel the org has on). A channel the org turned off answers
+         * `400 phone_channels_disabled_for_org`; an empty or duplicated list
+         * `400 phone_channels_invalid`.
+         */
+        channels?: Array<"whatsapp" | "sms">;
+        /**
+         * Which countries codes may be sent to: the profile's allowed
+         * `locations` (default), `any`, or a list of ISO 3166-1 alpha-2 codes.
+         * Invalid values answer `400 phone_destinations_invalid`.
+         */
+        destinations?: "locations" | "any" | {
+            countries: string[];
+        };
+    };
+    /** Email OTP step (absent = off): a one-time code sent to the person's email address. */
+    email?: "off" | ProfileEmail;
+    document: {
+        mode: "off" | "optional" | "mandatory";
+        /** Accepted document types: `'*'` (all) or a list, optionally per issuing country. */
+        accepted: {
+            default: "*" | ProfileDocumentType[];
+            byIssuer?: Record<string, ProfileDocumentType[]>;
+        };
+        /** Expired documents: refused, allowed, or allowed for `graceDays` (1–365) after expiry. */
+        expired: "reject" | "allow" | {
+            graceDays: number;
+        };
+        authenticity: "standard" | "off";
+    };
+    registry: {
+        enabled: boolean;
+        sources: Array<"MR.anrpts">;
+        /** Which identity is the reference for face match and your data. */
+        reference?: "document" | "registry";
+        /** What happens when the registry has no record for the NNI. */
+        onNoRecord?: "fail" | "use_document";
+    };
+    liveness: {
+        enabled: boolean;
+    };
+    faceMatch: {
+        enabled: boolean;
+    };
+    /** Comparison of your `subject` data with the reference identity. */
+    nameMatch?: {
+        level: "strict" | "standard" | "lenient";
+        onMismatch: "fail" | "signal";
+    };
+    /** Per-step attempt limits. */
+    attempts?: {
+        phone: number;
+        /** Email OTP attempts (1–5); absent = the platform default. */
+        email?: number;
+        document: number;
+        registry: number;
+        liveness: number;
+        faceMatch: number;
+    };
+    /** Where the end user may be (IP location). */
+    locations: {
+        mode: "all";
+    } | {
+        mode: "only" | "all_except";
+        countries: string[];
+    };
+    anonymizers: "allow" | "block";
+    /** Accepted nationalities: `'*'` or a list, optionally per IP location. */
+    nationalities: {
+        default: "*" | string[];
+        byLocation?: Record<string, "*" | string[]>;
+    };
+    /** Minimum age in years (1–120), or `null` for none. */
+    minAge: number | null;
+    /** Automatic decisions instead of human review (`retryConfidentRejects` lets confident rejects retry). */
+    decisions?: {
+        mode: "automatic" | "review";
+        retryConfidentRejects: boolean;
+    };
+    /** Device cooldown after repeated rejections (at most 5 tiers; `[]` = off). */
+    cooldown?: {
+        tiers: Array<{
+            rejectedSessions: number;
+            windowHours: number;
+            waitMinutes: number;
+        }>;
+    };
+    /** Device tamper and velocity actions. */
+    device?: {
+        tamper: "block" | "signal";
+        velocity: {
+            maxIdentitiesPerDevice: number;
+            windowDays: number;
+            action: "signal" | "block";
+        };
+    };
+    /**
+     * The live photo. `purpose: "id_document"` also takes an ICAO 480×640 portrait you
+     * download for printing on an ID document. `icao` makes a verification selfie meet
+     * the ICAO photo rules: `"reject"` asks the person to retake a non-compliant photo
+     * (after the last attempt the session fails, or goes to review in review mode);
+     * `"alert"` lets the person continue and adds the risk signal `icao_non_compliant`.
+     * Both need liveness on; `"alert"` with `"id_document"` answers
+     * `400 portrait_icao_policy_id_document`. Absent = a verification selfie, no ICAO check.
+     */
+    portrait?: {
+        purpose?: "verification" | "id_document";
+        icao?: {
+            policy: "alert" | "reject";
+        };
+    };
+}
+/**
+ * The email OTP step of a profile. When the email check is not available on
+ * the platform yet, saving it answers `400 email_otp_not_available`.
+ * @public
+ */
+interface ProfileEmail {
+    /** Where the address comes from: your `input.email`, the person, or either. */
+    emailSource: "prefilled" | "user_entered" | "prefilled_or_entered";
+    /** Disposable (temporary) addresses: allowed, flagged as a risk signal (default), or refused. */
+    disposable?: "allow" | "signal" | "block";
+}
+/**
+ * `T` with every property optional, recursively. Arrays are replaced as a
+ * whole, never merged element by element.
+ * @public
+ */
+type DeepPartial<T> = T extends readonly unknown[] ? T : T extends object ? {
+    [K in keyof T]?: DeepPartial<T[K]>;
+} : T;
+/**
+ * A per-session override of the app's eKYC profile
+ * ({@link CreateSessionInput.profile}): any subset of
+ * {@link EkycProfileSettings}, at any depth (every field optional). Objects
+ * are merged into the app's profile; arrays and scalar values replace it.
+ *
+ * The API validates the merged result like a profile save. Unknown keys are
+ * rejected server-side (`400`, also for keys this SDK version does not type).
+ * An override may only make the profile stricter unless the app allows
+ * widening (`overrides.allowWidening`); otherwise a widening change answers
+ * `403 override_widens_profile`. The changed paths are reported on
+ * {@link Session.overriddenFields}.
+ * @public
+ */
+type EkycProfileOverride = DeepPartial<EkycProfileSettings>;
 /**
  * Input of {@link SessionsApi.create}. There is no recipe field: the API key
  * belongs to an app, and that app's eKYC profile decides the steps.
@@ -54,6 +397,11 @@ interface DeliverOptions {
 interface CreateSessionInput {
     /** Pins the hosted-flow language. Omit to let the person's device decide. */
     locale?: Locale;
+    /**
+     * Pre-choose the identity method when the app's document step is optional
+     * (the hosted method screen is then skipped). Ignored for other apps.
+     */
+    identityMethod?: IdentityMethod;
     /**
      * Session lifetime in minutes. Must fall within the app profile's link
      * range, otherwise the API answers `400 ttl_out_of_policy`. Omit to use the
@@ -62,6 +410,19 @@ interface CreateSessionInput {
     ttlMinutes?: number;
     /** Also send the hosted link to the person by SMS or WhatsApp. */
     deliver?: DeliverOptions;
+    /**
+     * What you already know about the person (preferred over `input` for
+     * identity data). A key sent in both `subject` and `input` with different
+     * values answers `400 subject_input_conflict`.
+     */
+    subject?: SessionSubjectInput;
+    /**
+     * Override the app's eKYC profile for this session only (profile v2): a
+     * deep-partial {@link EkycProfileOverride}. Unknown keys are rejected
+     * server-side; a change that makes the profile less strict answers
+     * `403 override_widens_profile` unless the app allows widening.
+     */
+    profile?: EkycProfileOverride;
     /**
      * Step inputs consumed server-side. The known anchors are typed (all
      * strings — an `nni` is a 10-digit string, never a number); further keys
@@ -73,11 +434,59 @@ interface CreateSessionInput {
         nni?: string;
         /** E.164 phone number, e.g. `+22236123456`. */
         phone?: string;
+        /** Email address for the email OTP step (`emailSource` `prefilled` / `prefilled_or_entered`). */
+        email?: string;
         fullName?: string;
         /** ISO 8601 date (`YYYY-MM-DD`). */
         birthDate?: string;
+        /**
+         * Partner-supplied identity data (`supplied` mode only): the person's
+         * biographic record and photo as YOUR system holds them — for example
+         * from your own ANRPTS answer, converted with {@link registryFromAnrpts}.
+         * Sekyro AI stores it as data you vouch for, makes no registry call, and
+         * never receives or stores any registry key. `nni` must be set too and
+         * equal `suppliedIdentity.nni`. Refused unless Sekyro AI enabled the mode
+         * for the environment (`403 supplied_identity_not_entitled`); required in
+         * that mode when the app verifies identity (`422 supplied_identity_required`).
+         */
+        suppliedIdentity?: SuppliedIdentityRecord;
     } & Record<string, unknown>;
 }
+/**
+ * Partner-supplied identity data (`sessions.create` `input.suppliedIdentity`):
+ * the person's biographic record and photo, as your organization holds them.
+ * Sekyro AI treats it as identity data supplied by your organization, not as
+ * a registry lookup. Refusals at create: `400 supplied_identity_nni_mismatch`,
+ * `422 supplied_identity_stale` (`fetchedAt` older than 24 h),
+ * `422 supplied_identity_photo_unusable` (not a JPEG/PNG of at most 1 MB within the
+ * size bounds). In a `supplied` environment whose app verifies identity, a create
+ * without `input.suppliedIdentity` is `422 supplied_identity_required`. The face on
+ * the photo is checked after consent, at the face match (`no_face_reference`).
+ * @public
+ */
+interface SuppliedIdentityRecord {
+    /** 10-digit NNI, as a string. */
+    nni: string;
+    firstNameFr: string;
+    lastNameFr: string;
+    fatherNameFr?: string;
+    firstNameAr: string;
+    lastNameAr: string;
+    fatherNameAr?: string;
+    /** ISO 8601 date (`YYYY-MM-DD`). */
+    birthDate: string;
+    birthPlaceFr?: string;
+    birthPlaceAr?: string;
+    sex?: "M" | "F";
+    /** Nationality text as your source holds it (e.g. `Mauritanienne`). */
+    nationalities?: string[];
+    /** Base64 JPEG or PNG (at most 1 MB decoded). */
+    photo: string;
+    /** ISO 8601 date (`YYYY-MM-DD`) of the registry photo. */
+    photoDate?: string;
+    /** ISO 8601 date-time at which your system obtained this record. */
+    fetchedAt: string;
+}
 /** Per-request options. @public */
 interface RequestOptions {
     /**
@@ -102,6 +511,100 @@ interface CreatedSession {
     /** ISO 8601 — when the session (and its link) stop accepting input. */
     expiresAt: string;
 }
+/**
+ * The end user's network at the start of the session (IP-derived, approximate).
+ * @public
+ */
+interface SessionNetworkEvent {
+    /** ISO 8601. */
+    at: string;
+    /** ISO 3166-1 alpha-2. */
+    country?: string;
+    region?: string;
+    city?: string;
+    asn?: number;
+    operator?: string;
+    connectionType: "mobile" | "hosting" | "unknown";
+    anonymizer: {
+        vpn: boolean;
+        tor: boolean;
+        hosting: boolean;
+    };
+    /** IANA time zone reported by the end user's device. */
+    browserTimezone?: string;
+    /** True when the device time zone does not belong to the IP country. */
+    timezoneMismatch?: boolean;
+}
+/**
+ * End-user network context; absent when not recorded.
+ * @public
+ */
+interface SessionNetwork {
+    /** The start event's IP address. Never sent in webhooks. */
+    ip?: string;
+    /** True when a later call came from a different country than the start. */
+    countryChanged: boolean;
+    start: SessionNetworkEvent;
+}
+/**
+ * Device signals detected on the end user's device.
+ * @public
+ */
+type SessionDeviceSignal = "webdriver" | "headless" | "emulator" | "rooted" | "jailbroken" | "debugger" | "hooking" | "virtual_camera";
+/**
+ * End-user device summary; absent when not recorded.
+ * @public
+ */
+interface SessionDevice {
+    platform: "web" | "android" | "ios";
+    sdk?: string;
+    os?: string;
+    osVersion?: string;
+    browser?: string;
+    browserVersion?: string;
+    deviceClass: "mobile" | "tablet" | "desktop" | "unknown";
+    model?: string;
+    /** Device ids hashed with a key unique to your organization. */
+    deviceKeys: string[];
+    signals: SessionDeviceSignal[];
+}
+/**
+ * The national eID that verified the session's identity (the `eid_auth` check
+ * passed): the provider id (`{country}.{provider}`, e.g. `MR.houwiyeti`), its
+ * ISO 3166-1 alpha-2 country and when. A passed eID ends the session.
+ * @public
+ */
+interface EidResult {
+    provider: string;
+    country: string;
+    verifiedAt: string;
+}
+/**
+ * The full phone number and email address the person verified in a session
+ * (an OTP check that passed) — sent ONLY to you (the session view and your
+ * webhooks), never to the person's browser, and removed when the session's
+ * personal data is purged. You are the controller of these values. A
+ * prefilled value that was not verified is never listed.
+ * @public
+ */
+interface VerifiedContacts {
+    /** From a passed `phone_otp` check. */
+    phone?: {
+        /** E.164, e.g. `+22236123456`. */
+        number: string;
+        /** The channel the code was delivered on. */
+        channel: "whatsapp" | "sms";
+        /** ISO 8601. */
+        verifiedAt: string;
+    };
+    /** From a passed `email_otp` check. */
+    email?: {
+        /** The verified address (domain lowercased). */
+        address: string;
+        /** ISO 8601. */
+        verifiedAt: string;
+    };
+}
 /**
  * The whitelisted session view returned by {@link SessionsApi.get}. Never
  * contains the client token.
@@ -116,6 +619,55 @@ interface Session {
     expiresAt: string;
     /** ISO 8601. */
     createdAt: string;
+    /** End-user network context; absent when not recorded. */
+    network?: SessionNetwork;
+    /** End-user device; absent when not recorded. */
+    device?: SessionDevice;
+    /**
+     * Set when a profile-v2 policy ended the session: a session-level gate
+     * (location, anonymizer) or a failed check's policy reason (eligibility,
+     * `document_nni_mismatch`). Absent otherwise.
+     */
+    failureReason?: PolicyFailureReason;
+    /** The subject (person) this session is linked to, once an identifier is known. */
+    subjectId?: string;
+    /** Your own id for the person, from `subject.externalRef` at create. */
+    externalRef?: string;
+    /**
+     * `true` when an identifier this session read already belongs to a
+     * different subject than `subjectId` — the subjects are never merged.
+     */
+    subjectConflict?: boolean;
+    /**
+     * ISO 8601 — when the end user's device may verify again; set with
+     * `failureReason: 'device_cooldown'`.
+     */
+    retryAfter?: string;
+    /** Dotted profile paths this session's {@link CreateSessionInput.profile} changed (e.g. `decisions.mode`). */
+    overriddenFields?: string[];
+    /**
+     * Risk signals recorded on the session (e.g. `device_velocity`,
+     * `timezone_mismatch`, `icao_non_compliant` when an `alert` ICAO policy flagged
+     * the selfie) — signals only, never a verdict by themselves.
+     */
+    riskSignals?: string[];
+    /**
+     * `true` for a returning-user session (created with
+     * {@link SessionSubjectInput.reuse}): liveness + face match against the
+     * subject's stored reference photo only.
+     */
+    returning?: true;
+    /** On a returning-user session: the subject (person) it re-verifies. */
+    reuseOf?: string;
+    /** The contacts verified in this session (passed OTP checks only); absent when none. */
+    verifiedContacts?: VerifiedContacts;
+    /** The national eID that verified this session (the `eid_auth` check passed); absent otherwise. */
+    eid?: EidResult;
+    /**
+     * ID mode (`portrait.purpose = id_document`) only: the ICAO portrait can be
+     * fetched with {@link SessionsApi.portrait}.
+     */
+    portraitAvailable?: boolean;
 }
 /**
  * `data` of the terminal / review-pending session lifecycle events
@@ -133,6 +685,169 @@ interface SessionLifecycleEventData {
     steps?: Array<Pick<SessionStep, "checkType" | "state">>;
     /** Machine-readable reason, when the transition has one. */
     reason?: string;
+    /** End-user network context (no IP); on `completed` / `failed` when recorded. */
+    network?: Omit<SessionNetwork, "ip">;
+    /** End-user device; on `completed` / `failed` when recorded. */
+    device?: SessionDevice;
+    /**
+     * On `session.failed`: set when a profile-v2 policy ended the session — a
+     * session-level gate (location, anonymizer) or a failed check's policy
+     * reason (eligibility, `document_nni_mismatch`).
+     */
+    failureReason?: PolicyFailureReason;
+    /** The subject (person) the session is linked to, when known. */
+    subjectId?: string;
+    /** Your own id for the person, from `subject.externalRef` at create. */
+    externalRef?: string;
+    /**
+     * `true` when an identifier this session read already belongs to a
+     * different subject than `subjectId` — the subjects are never merged.
+     */
+    subjectConflict?: boolean;
+    /** `true` on a returning-user session (liveness + face match against the stored photo). */
+    returning?: true;
+    /** On a returning-user session: the subject (person) it re-verifies. */
+    reuseOf?: string;
+    /**
+     * On `session.failed` with `failureReason: 'device_cooldown'`: ISO time
+     * from which the device may start a new verification.
+     */
+    retryAfter?: string;
+    /** Dotted profile paths the session's create-time override changed. */
+    overriddenFields?: string[];
+    /** On `completed` / `failed`: the contacts verified in this session (passed OTP checks only). */
+    verifiedContacts?: VerifiedContacts;
+    /** On `completed` / `failed`: the national eID that verified this session, when one did. */
+    eid?: EidResult;
+    /**
+     * ID mode only, on `completed` / `failed`: the ICAO portrait can be fetched
+     * with {@link SessionsApi.portrait} (the event never carries the image).
+     */
+    portraitAvailable?: boolean;
+}
+/**
+ * `data` of `subject.updated` — either a session linked to the subject reached
+ * a terminal state (`sessionId`, session `status`, `outcome`), or the subject
+ * was revoked (`status: 'revoked'`, no session). Ids and enums only.
+ * @public
+ */
+interface SubjectUpdatedEventData {
+    subjectId: string;
+    /** The session that reached a terminal state; absent on a revocation. */
+    sessionId?: string;
+    status: SessionStatus | "revoked";
+    /** The session outcome; absent on a revocation. */
+    outcome?: SessionOutcome | null;
+}
+/**
+ * `data` of `subject.enrolled` — the subject's first reference photo was
+ * stored (it can now be used for returning-user sessions). Ids and enums only.
+ * @public
+ */
+interface SubjectEnrolledEventData {
+    subjectId: string;
+    /** The approved session the reference photo came from. */
+    sessionId: string;
+    assurance: SubjectAssurance;
+}
+/**
+ * `data` of `subject.deleted`. A delete through the subjects API carries
+ * `subjectId`; a right-to-erasure request carries the tokenized `subjectRef`
+ * (with `orgId` / `env`) instead — never the national number.
+ * @public
+ */
+interface SubjectDeletedEventData {
+    subjectId?: string;
+    subjectRef?: string;
+    orgId?: string;
+    env?: SekyroEnvironment;
+}
+/** Subject lifecycle: a revoked subject cannot be reused. @public */
+type SubjectStatus = "active" | "revoked";
+/**
+ * How strongly a subject's identity was established: the reference photo
+ * came from the national registry, the document's chip (`chip_biometric`, a
+ * passed chip read plus a face match) or the document, and a face match passed
+ * (`*_biometric`) or the session had no face match (`*_only`). `supplied_*`:
+ * partner-supplied identity data (`input.suppliedIdentity`), with
+ * (`supplied_biometric`) or without (`supplied_only`) a face match against its photo.
+ * @public
+ */
+type SubjectAssurance = "registry_biometric" | "chip_biometric" | "document_biometric" | "registry_only" | "document_only" | "supplied_biometric" | "supplied_only";
+/**
+ * Origin of a subject's stored reference photo, best first (`chip`: the document chip's portrait;
+ * `org_supplied`: the photo of your partner-supplied identity data).
+ * @public
+ */
+type SubjectReferenceSource = "registry" | "doc_registry" | "chip" | "org_supplied" | "document";
+/** One session linked to a subject. @public */
+interface SubjectSession {
+    sessionId: string;
+    appId: string | null;
+    /** ISO 8601 — when the session was linked. */
+    at: string;
+    status: SessionStatus;
+    outcome: SessionOutcome | null;
+}
+/**
+ * A subject (the same person across your apps), as `GET /subjects/:id`
+ * returns it. Never contains photo keys or URLs.
+ * @public
+ */
+interface Subject {
+    id: string;
+    status: SubjectStatus;
+    /** ISO 8601 — present only when revoked. */
+    revokedAt?: string;
+    sessions: SubjectSession[];
+    externalRefs: string[];
+    /** ISO 8601. */
+    firstSeenAt: string;
+    /** ISO 8601. */
+    lastSeenAt: string;
+    /** ISO 8601, or `null` before the first approved session. */
+    lastPassedAt: string | null;
+    /** ISO 8601 of the last approved full or returning session, or `null`. */
+    lastVerifiedAt: string | null;
+    /** The stored reference photo's origin and date — `null` until one is stored. */
+    reference: {
+        source: SubjectReferenceSource;
+        capturedAt: string;
+    } | null;
+    assurance: SubjectAssurance | null;
+    /**
+     * A returning-user session can be created now: active, a reference photo is
+     * stored, and the last FULL verification (returning-user sessions do not
+     * reset it) is within your app's
+     * `reuse.maxAgeMonths` (when set).
+     */
+    returningReady: boolean;
+    /** The verified name / birth date of the latest approved session. */
+    display?: {
+        name?: string;
+        birthDate?: string;
+    };
+}
+/** Result of {@link SubjectsApi.delete}. @public */
+interface DeletedSubject {
+    id: string;
+    deleted: true;
+}
+/** Options of {@link SubjectsApi.revoke}. @public */
+interface RevokeSubjectInput {
+    /** Kept on the audit trail only (≤ 500 characters). Do not put personal data here. */
+    reason?: string;
+}
+/**
+ * `data` of `subject.suspicious_activity` — a device already linked to
+ * ANOTHER subject was used for a session of this subject. `count` is the
+ * subject's running total of such events. Ids only.
+ * @public
+ */
+interface SubjectSuspiciousActivityEventData {
+    subjectId: string;
+    sessionId: string;
+    count: number;
 }
 /**
  * `data` of `session.step.completed` — the check that just passed.
@@ -142,6 +857,21 @@ interface SessionStepCompletedEventData {
     sessionId: string;
     checkType: CheckType;
     state: CheckState;
+    /** The subject (person) the session is linked to, when known. */
+    subjectId?: string;
+    /** Your own id for the person, from `subject.externalRef` at create. */
+    externalRef?: string;
+    /**
+     * `true` when an identifier this session read already belongs to a
+     * different subject than `subjectId` — the subjects are never merged.
+     */
+    subjectConflict?: boolean;
+    /** `true` on a returning-user session (liveness + face match against the stored photo). */
+    returning?: true;
+    /** On a returning-user session: the subject (person) it re-verifies. */
+    reuseOf?: string;
+    /** When the passed check is `phone_otp` / `email_otp`: that one verified contact. */
+    verifiedContacts?: VerifiedContacts;
 }
 /**
  * `data` of `session.review_decided` — a human (or the review-timeout sweep)
@@ -154,6 +884,21 @@ interface SessionReviewDecidedEventData {
     sessionId: string;
     outcome: "pass" | "fail";
     reason: string;
+    /** The subject (person) the session is linked to, when known. */
+    subjectId?: string;
+    /** Your own id for the person, from `subject.externalRef` at create. */
+    externalRef?: string;
+    /**
+     * `true` when an identifier this session read already belongs to a
+     * different subject than `subjectId` — the subjects are never merged.
+     */
+    subjectConflict?: boolean;
+    /** `true` on a returning-user session (liveness + face match against the stored photo). */
+    returning?: true;
+    /** On a returning-user session: the subject (person) it re-verifies. */
+    reuseOf?: string;
+    /** ID mode only: the ICAO portrait can be fetched with {@link SessionsApi.portrait}. */
+    portraitAvailable?: boolean;
 }
 /**
  * Event type → the shape of its `data`. Session events are typed; the
@@ -170,8 +915,10 @@ interface WebhookEventDataMap {
     "session.rejected": SessionLifecycleEventData;
     "session.expired": SessionLifecycleEventData;
     "session.failed": SessionLifecycleEventData;
-    "subject.enrolled": Record<string, unknown>;
-    "subject.deleted": Record<string, unknown>;
+    "subject.enrolled": SubjectEnrolledEventData;
+    "subject.updated": SubjectUpdatedEventData;
+    "subject.suspicious_activity": SubjectSuspiciousActivityEventData;
+    "subject.deleted": SubjectDeletedEventData;
     "aml.match_flagged": Record<string, unknown>;
     "payment.received": Record<string, unknown>;
     "invoice.generated": Record<string, unknown>;
@@ -259,18 +1006,66 @@ declare class SessionsApi {
      * surface on purpose (only its bound `call` crosses this boundary).
      * @internal
      */
-    constructor(call: <T>(method: "GET" | "POST", path: string, body?: unknown, idempotencyKey?: string) => Promise<T>);
+    constructor(call: <T>(method: "GET" | "POST" | "DELETE", path: string, body?: unknown, idempotencyKey?: string) => Promise<T>);
     /**
      * `POST /sessions`. Returns the one-time `clientToken` — hand it to the
      * browser, never persist it. Pass an `idempotencyKey` so a retried call
      * cannot create a second session.
      */
     create(input?: CreateSessionInput, opts?: RequestOptions): Promise<CreatedSession>;
+    /**
+     * `POST /sessions/:id/method` — choose the identity method of an
+     * optional-document session on the person's behalf (the hosted method
+     * screen is then skipped). `409 method_locked` once the choice can no
+     * longer change; `409 session_not_active` on a finished or expired session.
+     */
+    selectMethod(id: string, method: IdentityMethod): Promise<Session>;
     /** `GET /sessions/:id` — the whitelisted view (no client token). */
     get(id: string): Promise<Session>;
+    /**
+     * `GET /sessions/:id/portrait?format=url` — ID mode: a 5-minute presigned
+     * link to the 480×640 ICAO portrait (JPEG). Needs the `portrait:read` scope
+     * (keys minted from the dashboard carry it). `404 portrait_not_available`
+     * until the session's `portrait_icao` check has passed (`portraitAvailable`).
+     */
+    portrait(id: string): Promise<SessionPortraitLink>;
 }
 /**
- * Sekyro partner API client. Server-side only: it carries your API key.
+ * `sekyro.subjects` — read and manage subjects (the same person across your
+ * apps). Reads need the `subjects:read` scope, `revoke` / `delete` the
+ * `subjects:write` scope (keys minted from the dashboard carry both; an older
+ * key answers `403 insufficient_scope`). A foreign or unknown id answers
+ * `404 subject_not_found`.
+ *
+ * Type-only export, like {@link SessionsApi}: obtained through
+ * {@link Sekyro.subjects}.
+ * @public
+ */
+declare class SubjectsApi {
+    private readonly call;
+    /** @internal */
+    constructor(call: <T>(method: "GET" | "POST" | "DELETE", path: string, body?: unknown, idempotencyKey?: string) => Promise<T>);
+    /** `GET /subjects/:id` — the subject, its sessions and its returning-user readiness. */
+    get(id: string): Promise<Subject>;
+    /** `GET /subjects?externalRef=…` — the subjects carrying your own id (newest first, at most 50). */
+    list(query: {
+        externalRef: string;
+    }): Promise<Subject[]>;
+    /**
+     * `POST /subjects/:id/revoke` — the subject can no longer be used for
+     * returning-user sessions. Idempotent: revoking again returns the same view.
+     * Emits `subject.updated` with `status: 'revoked'`.
+     */
+    revoke(id: string, input?: RevokeSubjectInput, opts?: RequestOptions): Promise<Subject>;
+    /**
+     * `DELETE /subjects/:id` — deletes the subject's stored photos, face
+     * templates and identifiers, and unlinks its sessions. Emits
+     * `subject.deleted`. Cannot be undone; a second call answers `404`.
+     */
+    delete(id: string): Promise<DeletedSubject>;
+}
+/**
+ * Sekyro AI partner API client. Server-side only: it carries your API key.
  *
  * Throws {@link SekyroConfigError} synchronously when `apiKey` is missing or
  * `baseUrl` is not `https:` (plain `http:` is accepted for `localhost`,
@@ -285,6 +1080,7 @@ declare class SessionsApi {
  */
 declare class Sekyro {
     readonly sessions: SessionsApi;
+    readonly subjects: SubjectsApi;
     constructor(opts: SekyroOptions);
 }
 
@@ -292,7 +1088,7 @@ declare class Sekyro {
 type SekyroWebhookErrorCode = "invalid_signature" | "stale" | "malformed";
 /**
  * Thrown by {@link verifyWebhook}. Respond with a 4xx and do not process the
- * body; Sekyro retries deliveries that do not receive a 2xx.
+ * body; Sekyro AI retries deliveries that do not receive a 2xx.
  * @public
  */
 declare class SekyroWebhookError extends Error {
@@ -301,7 +1097,7 @@ declare class SekyroWebhookError extends Error {
     constructor(code: SekyroWebhookErrorCode, message?: string);
 }
 /** Why the {@link Sekyro} constructor rejected its options. @public */
-type SekyroConfigErrorCode = "missing_api_key" | "invalid_base_url";
+type SekyroConfigErrorCode = "missing_api_key" | "invalid_base_url" | "invalid_registry_record";
 /**
  * Thrown synchronously by `new Sekyro(...)` for an unusable configuration —
  * before any request is made. Extends `TypeError` so existing
@@ -345,6 +1141,61 @@ declare class SekyroApiError extends Error {
     constructor(init: SekyroApiErrorInit);
 }
 
+/**
+ * The raw ANRPTS `getPersonne` answer your server received with your own
+ * access: `{ personne, photo }`, where `photo` is a base64 JPEG (optionally
+ * data-URL prefixed). Only the fields the mapping reads are typed.
+ * @public
+ */
+interface AnrptsPersonneResponse {
+    personne?: {
+        nni?: string | undefined;
+        prenomFr?: string | undefined;
+        patronymeFr?: string | undefined;
+        perePrenomFr?: string | undefined;
+        prenomAr?: string | undefined;
+        patronymeAr?: string | undefined;
+        perePrenomAr?: string | undefined;
+        /** ISO date or date-time (`1990-01-01T00:00:00.000Z`), or `DD/MM/YYYY`. */
+        dateNaissance?: string | undefined;
+        lieuNaissanceFr?: string | undefined;
+        lieuNaissanceAr?: string | undefined;
+        sexeCode?: string | undefined;
+        nationalities?: string[] | undefined;
+        [key: string]: unknown;
+    };
+    photo?: string | undefined;
+    datePhoto?: string | undefined;
+    [key: string]: unknown;
+}
+/** Options of {@link registryFromAnrpts}. @public */
+interface RegistryFromAnrptsOptions {
+    /**
+     * When YOUR system received this ANRPTS answer (not "now" when you map a cached
+     * answer). Required: records older than 24 h are refused at session create.
+     */
+    fetchedAt: Date | string;
+}
+/**
+ * Convert an ANRPTS `getPersonne` answer that YOUR server already received,
+ * with your own access, into the `input.suppliedIdentity` record of
+ * `sessions.create` (partner-supplied identity data). A pure, local mapping:
+ * it makes no network call, and Sekyro AI never sees, receives or stores any
+ * ANRPTS key — only the record and photo you pass.
+ *
+ * ```ts
+ * const anrpts = await myAnrptsClient.getPersonne(nni); // your call, your key
+ * const suppliedIdentity = registryFromAnrpts(anrpts, { fetchedAt: receivedAt });
+ * await sekyro.sessions.create({ input: { nni, suppliedIdentity } });
+ * ```
+ *
+ * Throws {@link SekyroConfigError} (`invalid_registry_record`) when a required
+ * field (NNI, French and Arabic first and last names, birth date, photo) is
+ * missing. The message names the field, never its value.
+ * @public
+ */
+declare function registryFromAnrpts(response: AnrptsPersonneResponse, options: RegistryFromAnrptsOptions): SuppliedIdentityRecord;
+
 /**
  * The HTTP header carrying the webhook signature:
  * `t=<unix seconds>,v1=<hex>[,v1=<hex>]`.
@@ -352,7 +1203,7 @@ declare class SekyroApiError extends Error {
  */
 declare const SEKYRO_SIGNATURE_HEADER = "x-sekyro-signature";
 /**
- * The pre-rebrand name of the signature header. Sekyro sends BOTH headers with
+ * The pre-rebrand name of the signature header. Sekyro AI sends BOTH headers with
  * the same value during the transition; prefer {@link SEKYRO_SIGNATURE_HEADER}
  * and use {@link signatureFromHeaders} to accept either.
  * @public
@@ -380,13 +1231,13 @@ interface VerifyWebhookOptions {
     now?: () => number;
 }
 /**
- * Verify a Sekyro webhook delivery and return its parsed envelope, discriminated
+ * Verify a Sekyro AI webhook delivery and return its parsed envelope, discriminated
  * on `event` (narrow with a `switch` to type `data`).
  *
  * - `rawBody` MUST be the request body exactly as received (before any JSON
  *   parsing / re-serialisation); the signature covers those bytes.
  * - Accepts the delivery when ANY `v1` in the header matches, which is what
- *   makes secret rotation seamless (Sekyro signs with current + previous).
+ *   makes secret rotation seamless (Sekyro AI signs with current + previous).
  * - Uses `node:crypto` only; the digest compare is constant-time.
  *
  * Checks run in this order: header/secret present → header well-formed →
@@ -401,4 +1252,4 @@ interface VerifyWebhookOptions {
  */
 declare function verifyWebhook(rawBody: string, header: string | null | undefined, secret: string, opts?: VerifyWebhookOptions): WebhookEnvelope;
 
-export { type CheckState, type CheckType, type CreateSessionInput, type CreatedSession, DEFAULT_BASE_URL, DEFAULT_TIMEOUT_MS, type DeliverOptions, type FetchLike, LEGACY_SIGNATURE_HEADER, type Locale, type RequestOptions, SEKYRO_SIGNATURE_HEADER, Sekyro, SekyroApiError, type SekyroApiErrorInit, type SekyroClientErrorCode, SekyroConfigError, type SekyroConfigErrorCode, type SekyroEnvironment, type SekyroOptions, SekyroWebhookError, type SekyroWebhookErrorCode, type Session, type SessionEventData, type SessionLifecycleEventData, type SessionOutcome, type SessionReviewDecidedEventData, type SessionStatus, type SessionStep, type SessionStepCompletedEventData, SessionsApi, type VerifyWebhookOptions, type WebhookEnvelope, type WebhookEnvelopeOf, type WebhookEventDataMap, type WebhookEventType, signatureFromHeaders, verifyWebhook };
+export { type AnrptsPersonneResponse, type CheckState, type CheckType, type CreateSessionInput, type CreatedSession, DEFAULT_BASE_URL, DEFAULT_TIMEOUT_MS, type DecisionReason, type DeepPartial, type DeletedSubject, type DeliverOptions, type EidResult, type EkycProfileOverride, type EkycProfileSettings, type EligibilityReason, type FetchLike, type IdentityMethod, LEGACY_SIGNATURE_HEADER, type Locale, type MatchReason, type PolicyFailureReason, type PortraitReportEntry, type ProbeBindingReason, type ProbeQuality, type ProfileDocumentType, type ProfileEmail, type RegistryFromAnrptsOptions, type RequestOptions, type RevokeSubjectInput, SEKYRO_SIGNATURE_HEADER, Sekyro, SekyroApiError, type SekyroApiErrorInit, type SekyroClientErrorCode, SekyroConfigError, type SekyroConfigErrorCode, type SekyroEnvironment, type SekyroOptions, SekyroWebhookError, type SekyroWebhookErrorCode, type Session, type SessionDevice, type SessionDeviceSignal, type SessionEventData, type SessionFailureReason, type SessionLifecycleEventData, type SessionNetwork, type SessionNetworkEvent, type SessionOutcome, type SessionPortraitLink, type SessionReviewDecidedEventData, type SessionStatus, type SessionStep, type SessionStepCompletedEventData, type SessionSubjectInput, SessionsApi, type Subject, type SubjectAssurance, type SubjectDeletedEventData, type SubjectEnrolledEventData, type SubjectReferenceSource, type SubjectReuseTarget, type SubjectSession, type SubjectStatus, type SubjectSuspiciousActivityEventData, type SubjectUpdatedEventData, SubjectsApi, type SuppliedIdentityRecord, type VerifiedContacts, type VerifyWebhookOptions, type WebhookEnvelope, type WebhookEnvelopeOf, type WebhookEventDataMap, type WebhookEventType, registryFromAnrpts, signatureFromHeaders, verifyWebhook };