@sekyro/node 0.1.0-rc.6 → 0.1.0-rc.7

package/dist/client-DUMp_I-1.d.ts

@@ -0,0 +1,1485 @@
+/**
+ * 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.
+ *
+ * @packageDocumentation
+ */
+/** Session lifecycle status. @public */
+type SessionStatus = "created" | "in_progress" | "review_pending" | "completed" | "expired" | "failed";
+/**
+ * Terminal verdict, orthogonal to {@link SessionStatus}. `null` until the session
+ * reaches a terminal status; `review` when a human reviewer must adjudicate.
+ * @public
+ */
+type SessionOutcome = "approved" | "review" | "rejected";
+/**
+ * What a finished session proved: `1` a live, real person (human), `2` that
+ * person's identity (document, chip, registry or supplied data bound to the
+ * face), `3` an identity corroborated by an independent source. `0` on a
+ * rejected session.
+ * @public
+ */
+type VerificationLevel = 0 | 1 | 2 | 3;
+/**
+ * How a session's {@link VerificationLevel} was proved: `live_only` (liveness
+ * only), `live_unique` (liveness plus a duplicate search), and the
+ * `*_biometric` values, where a face match bound the person to a document,
+ * its chip, the registry record or partner-supplied identity data, and
+ * `eid_authenticated`, where the person signed in with a national digital
+ * identity (level 3 without a Sekyro selfie).
+ * @public
+ */
+type VerificationAssurance = "live_only" | "live_unique" | "document_biometric" | "chip_biometric" | "registry_biometric" | "supplied_biometric" | "eid_authenticated";
+/** The one billing unit a finished session consumed. @public */
+type VerificationUnit = "human_verification" | "identity_verification";
+/** The lowest and highest {@link VerificationLevel} the session's flow can reach. @public */
+interface LevelTarget {
+    min: VerificationLevel;
+    max: VerificationLevel;
+}
+/**
+ * Device and network risk facts of a finished session (booleans and a level
+ * word, never scores).
+ * @public
+ */
+interface ResultRisk {
+    level: "low" | "medium" | "high";
+    vpn: boolean;
+    ipDocumentMismatch: boolean;
+    deviceTampered: boolean;
+}
+/**
+ * What the liveness step verified about the capture itself: the device
+ * attestation, the capture proof and the injection signals.
+ * @public
+ */
+interface ResultCheckProofs {
+    attestation: "verified" | "missing" | "failed";
+    captureProof: "verified" | "missing";
+    injectionSignals: "clear" | "flagged";
+}
+/** Another subject the person's face already matched (duplicate search). @public */
+interface ResultDuplicate {
+    subjectId: string;
+    externalRef?: string;
+}
+/**
+ * How a `subject.reuse` session runs: `recheck` verifies the same person
+ * again (liveness and face match against the stored photo), `step_up` raises
+ * the subject to identity level with a flow that proves level 2 on every path.
+ * @public
+ */
+type SubjectReuseMode = "recheck" | "step_up";
+/**
+ * Where the hosted flow sends the person when the session ends: an `https`
+ * URL on one of the app's web origins, or the app's `sekyro-<slug>://` scheme.
+ * `state` (up to 256 characters) is echoed back on the redirect.
+ * @public
+ */
+interface SessionLinkInput {
+    returnUrl?: string;
+    state?: string;
+}
+/**
+ * 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" | "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), or `camera_unavailable` (spec 2026-10-29 §3.4: the person had no usable camera,
+ * so the live step ended without a capture; the session is rejected at level 0 unless your flow has a fallback).
+ * @public
+ */
+type PolicyFailureReason = SessionFailureReason | EligibilityReason | "document_nni_mismatch" | "camera_unavailable";
+/**
+ * Why the person had no camera (spec 2026-10-29 §3.4, 2026-10-30), when the SDK said: `denied` (the
+ * person refused camera access) or `no_camera` (no usable camera: none found, an insecure page or a
+ * browser that cannot capture). A detail under `failureReason: "camera_unavailable"`, never a reason of its own.
+ * @public
+ */
+type CameraUnavailableCause = "denied" | "no_camera";
+/**
+ * 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";
+/**
+ * The languages the person being verified sees (hosted flow and SDK screens; spec 2026-10-29 §9). `ar`, `fr` and `en`
+ * carry every screen; `es`, `pt` and `de` carry the Human verification screens and show English elsewhere. SMS and
+ * email messages stay in `ar`, `fr` or `en` (English for the three others).
+ * @public
+ */
+type Locale = "ar" | "fr" | "en" | "es" | "pt" | "de";
+/** The environment a webhook was emitted from. @public */
+type SekyroEnvironment = "sandbox" | "live";
+/**
+ * One check of a session, as the partner API projects it: enum/id fields only,
+ * never civil data.
+ * @public
+ */
+interface SessionStep {
+    checkType: CheckType;
+    state: CheckState;
+    /** Sekyro flows: the flow node this check belongs to (e.g. `n_live`). */
+    nodeId?: string;
+    /** Sekyro flows: the service of that node. */
+    service?: ServiceId;
+    /** Sekyro flows: the check failed and the flow's fallback took over. */
+    handled?: true;
+    /** Machine-readable failure/review reason, when the check has one. */
+    reason?: string;
+    /** With reason `camera_unavailable`: why, when the SDK said (`denied` or `no_camera`). */
+    reasonDetail?: CameraUnavailableCause;
+    /** 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;
+}
+/**
+ * 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
+ */
+interface DeliverOptions {
+    /** Delivery channel. */
+    channel: "sms" | "whatsapp";
+    /** 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 flow's `returning.maxAgeMonths`),
+     * `409 reuse_disabled` (the flow turns returning-user sessions off) and
+     * `400` / `409 reuse_target_ambiguous`.
+     */
+    reuse?: SubjectReuseTarget;
+}
+/**
+ * An identity document for {@link SubjectReuseTarget}: the document type, the
+ * issuing country (ISO 3166-1 alpha-2 or alpha-3) and its number.
+ * @public
+ */
+interface SubjectReuseDocument {
+    type: "national_id" | "passport" | "residence_permit";
+    issuingCountry: string;
+    number: string;
+}
+/**
+ * Which subject a returning-user session re-verifies — exactly ONE of the
+ * subject id, your own `externalRef` (must match a single subject), the NNI
+ * or an identity document the person verified with.
+ * @public
+ */
+type SubjectReuseTarget = ({
+    subjectId: string;
+    externalRef?: never;
+    nni?: never;
+    document?: never;
+} | {
+    externalRef: string;
+    subjectId?: never;
+    nni?: never;
+    document?: never;
+} | {
+    nni: string;
+    subjectId?: never;
+    externalRef?: never;
+    document?: never;
+} | {
+    document: SubjectReuseDocument;
+    subjectId?: never;
+    externalRef?: never;
+    nni?: never;
+}) & {
+    /**
+     * `recheck` (default) or `step_up` ({@link SubjectReuseMode}). `step_up` on
+     * a flow that does not prove level 2 on every path answers
+     * `400 step_up_flow_too_weak`.
+     */
+    mode?: SubjectReuseMode;
+};
+/** 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 services a Sekyro flow is built from. A session's steps
+ * ({@link SessionStep.service}) and {@link FlowOverrides.services} use these
+ * ids; one service may run several checks (e.g. `liveness` with an ICAO
+ * portrait).
+ * @public
+ */
+type ServiceId = "device_network" | "phone_otp" | "email_otp" | "national_eid" | "document" | "nfc" | "population_registry" | "supplied_identity" | "summary_confirm" | "liveness" | "face_match" | "aml_screening" | "face_dedup";
+/**
+ * The general settings of a flow that a session may override (the flow's
+ * `link`, `language` and override policy are not overridable). Country codes
+ * are ISO 3166-1 alpha-2 (`MR`). Used through {@link FlowOverrides.settings}.
+ * @public
+ */
+interface FlowOverridableSettings {
+    /** Who may be verified. */
+    eligibility: {
+        /** 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;
+    };
+    /** Data consistency across sources. */
+    fraud: {
+        /** Comparison of your `subject` data with the reference identity. */
+        nameMatch?: {
+            level: "strict" | "standard" | "lenient";
+            onMismatch: "fail" | "signal";
+        };
+    };
+    /** Returning-user sessions (`subject.reuse`). */
+    returning: {
+        /** `false`: returning-user sessions are refused (`409 reuse_disabled`). */
+        enabled: boolean;
+        /** Maximum age in months (1–120) of the subject's last verification; `null` = no limit. */
+        maxAgeMonths: number | null;
+    };
+    /** Identity-document rules. */
+    documents: {
+        /** 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";
+    };
+}
+/**
+ * Document substitution: the portrait a `document` or `nfc` step produces is
+ * compared with the registry portrait (or the chip with the printed photo).
+ * `signal` records a risk signal on a clear mismatch, `review` also sends the
+ * session to review, `off` compares nothing. `failBelow` is the mismatch bound
+ * in (0, 1), absent = the platform bound.
+ * @public
+ */
+interface DocumentSubstitutionSettings {
+    mode: "off" | "signal" | "review";
+    failBelow?: number;
+}
+/**
+ * The per-service settings a session may override, by {@link ServiceId}.
+ * `attempts` limits are per step (absent = the platform default).
+ * @public
+ */
+interface FlowServiceSettings {
+    /** Device & Network Intelligence: IP location, anonymizers, cooldown, device and capture postures. */
+    device_network: {
+        /** Where the end user may be (IP location). */
+        locations: {
+            mode: "all";
+        } | {
+            mode: "only" | "all_except";
+            countries: string[];
+        };
+        /** VPN / proxy / Tor. */
+        anonymizers: "allow" | "block";
+        /** 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";
+            };
+        };
+        attestation?: "off" | "signal" | "enforce";
+        captureIntegrity?: "off" | "signal" | "enforce";
+    };
+    phone_otp: {
+        /** 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). */
+        channels?: Array<"whatsapp" | "sms">;
+        /** Which countries codes may be sent to (absent = the flow's allowed `locations`). */
+        destinations?: "locations" | "any" | {
+            countries: string[];
+        };
+        attempts?: number;
+    };
+    email_otp: {
+        /** 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";
+        attempts?: number;
+    };
+    national_eid: {
+        /**
+         * `'org'` (every national eID the org can use, resolved at session create)
+         * or provider ids (`{country}.{provider}`, e.g. `MR.houwiyeti`).
+         */
+        providers: "org" | string[];
+        /** The eID portrait is the face-match reference. */
+        portraitReference: boolean;
+    };
+    document: {
+        attempts?: number;
+        /** Compare the document photo with the registry photo (absent = the platform default). */
+        documentSubstitution?: DocumentSubstitutionSettings;
+    };
+    /** The chip read (its MRZ source is derived from the flow and is not overridable). */
+    nfc: {
+        maxAttempts?: number;
+        /** Compare the chip photo with the registry photo (absent = the platform default). */
+        documentSubstitution?: DocumentSubstitutionSettings;
+    };
+    population_registry: {
+        /** `'org'` (every registry the org can use, resolved at session create) or registry ids. */
+        sources: "org" | Array<"MR.anrpts">;
+        nniSource: "auto" | "typed" | "bound_only";
+        onUncovered: "skip";
+        attempts?: number;
+    };
+    supplied_identity: Record<string, never>;
+    summary_confirm: {
+        /** Offer « Reprendre » (re-open the identity source). */
+        retake: boolean;
+    };
+    liveness: {
+        /** `off`, selfie ICAO `alert` / `reject`, or `id_document` (ID-photo portrait, always rejects). */
+        icao: "off" | "alert" | "reject" | "id_document";
+        attempts?: number;
+    };
+    face_match: {
+        reference: "auto" | "document" | "registry";
+        attempts?: number;
+    };
+    aml_screening: {
+        lists: Array<"sanctions" | "pep" | "adverse_media">;
+        onHit: "review" | "fail";
+    };
+    face_dedup: {
+        scope: "app" | "org";
+        onDuplicate: "review" | "fail";
+    };
+}
+/**
+ * `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 flow ({@link CreateSessionInput.overrides}).
+ *
+ * - `settings`: any subset of {@link FlowOverridableSettings}, at any depth.
+ * - `services`: keyed by service (applied to every node of that service): any
+ *   subset of its {@link FlowServiceSettings}, or `'off'` to remove it from
+ *   the flow. A service the flow does not use is ignored.
+ *
+ * Objects merge into the flow; arrays and scalar values replace. Unknown keys
+ * and invalid results answer `400 override_invalid`. An override may only
+ * make the flow stricter unless the flow allows widening; turning a service
+ * `'off'` always widens. A widening change answers `403 override_widens_flow`.
+ * The changed paths are reported on {@link Session.overriddenFields}.
+ *
+ * @example
+ * ```ts
+ * await sekyro.sessions.create({
+ *   flow: "foreigners",
+ *   overrides: {
+ *     settings: { eligibility: { minAge: 21 } },
+ *     services: { liveness: { attempts: 2 } },
+ *   },
+ * });
+ * ```
+ * @public
+ */
+interface FlowOverrides {
+    settings?: DeepPartial<FlowOverridableSettings>;
+    services?: {
+        [S in ServiceId]?: DeepPartial<FlowServiceSettings[S]> | "off";
+    };
+}
+/**
+ * The flow version a session runs: its `flw_` id, its slug and the published
+ * version pinned at create.
+ * @public
+ */
+interface SessionFlowRef {
+    id: string;
+    slug: string;
+    version: number;
+}
+/**
+ * One flow of your app, from {@link Sekyro.listFlows}. Published flows only;
+ * pass `slug` or `id` as {@link CreateSessionInput.flow}.
+ * @public
+ */
+interface FlowSummary {
+    /** `flw_` id. */
+    id: string;
+    slug: string;
+    name: string;
+    /** The published version a new session runs. */
+    version: number;
+    /** The flow a session runs when you send no `flow`. */
+    isDefault: boolean;
+}
+/**
+ * Input of {@link SessionsApi.create}. The API key belongs to an app; the
+ * app's flow (its default flow, or the one named in `flow`) decides the steps.
+ * @public
+ */
+interface CreateSessionInput {
+    /**
+     * The app's flow to run: its slug (e.g. `foreigners`) or `flw_` id, as
+     * {@link Sekyro.listFlows} lists them. Absent = the app's default flow.
+     * Errors: `404 flow_not_found` (no such flow in the key's app),
+     * `409 flow_not_published`, `409 flow_archived`.
+     */
+    flow?: string;
+    /** Pins the hosted-flow language. Omit to let the person's device decide. */
+    locale?: Locale;
+    /**
+     * Pre-choose the identity method when the flow offers a choice of identity
+     * method (the hosted choice screen is then skipped). Ignored otherwise.
+     */
+    identityMethod?: IdentityMethod;
+    /**
+     * Session lifetime in minutes. Must fall within the flow's link range,
+     * otherwise the API answers `400 ttl_out_of_policy`. Omit to use the
+     * flow's default.
+     */
+    ttlMinutes?: number;
+    /** Also send the hosted link to the person by SMS or WhatsApp. */
+    deliver?: DeliverOptions;
+    /**
+     * Where the hosted flow returns the person when the session ends
+     * ({@link SessionLinkInput}). A URL outside the app's web origins and app
+     * scheme answers `400 return_url_not_allowed`.
+     */
+    link?: SessionLinkInput;
+    /**
+     * 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;
+    /**
+     * Your own id for the agent filming the person, for flows whose liveness
+     * capture is `assisted` (1 to 128 characters). Stored as is and echoed on
+     * the session and in webhooks.
+     */
+    assistedBy?: {
+        externalRef: string;
+    };
+    /**
+     * Override the flow for this session only ({@link FlowOverrides}): its
+     * general settings and per-service settings, or turn a service `'off'`.
+     * `400 override_invalid` for an unknown key or an invalid result;
+     * `403 override_widens_flow` for a change that makes the flow less strict
+     * when the flow does not allow widening.
+     */
+    overrides?: FlowOverrides;
+    /**
+     * Step inputs consumed server-side. The known anchors are typed (all
+     * strings — an `nni` is a 10-digit string, never a number); further keys
+     * pass through to the API as-is. `nni` binds the session to that identity:
+     * the hosted flow may omit it but cannot substitute another.
+     */
+    input?: {
+        /** 10-digit Mauritanian NNI, as a string. */
+        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 {
+    /**
+     * Sent as `X-Idempotency-Key`. Replaying the same key within 24 h returns the
+     * original response instead of creating a second session.
+     */
+    idempotencyKey?: string;
+}
+/**
+ * Result of {@link SessionsApi.create}. `clientToken` is returned ONCE and never
+ * again — hand it to the browser (`@sekyro/web`) and do not persist it.
+ * @public
+ */
+interface CreatedSession {
+    id: string;
+    status: SessionStatus;
+    /** One-time credential for the client SDK / hosted flow. */
+    clientToken: string;
+    /** Hosted verification link for this session. */
+    hostedUrl: string;
+    /** The flow version the session runs (the default flow when you sent no `flow`). */
+    flow?: SessionFlowRef;
+    /** The checks on the session's path (checks of a lane not taken are omitted). */
+    steps: SessionStep[];
+    /** ISO 8601 — when the session (and its link) stop accepting input. */
+    expiresAt: string;
+    /** The levels the flow can reach on its paths; absent from older API versions. */
+    levelTarget?: LevelTarget;
+}
+/**
+ * Input of {@link SubjectsApi.createSession}: a re-check or step-up session
+ * for an existing subject in one call.
+ * @public
+ */
+interface SubjectSessionInput {
+    mode: SubjectReuseMode;
+    /** The app's flow to run (slug or `flw_` id); absent = the app's default flow. */
+    flow?: string;
+    link?: SessionLinkInput;
+    /** Session lifetime in minutes, within the flow's link range. */
+    ttlMinutes?: number;
+    locale?: Locale;
+}
+/**
+ * Which subject {@link SubjectsApi.createSession} targets: the subject id or
+ * your own external reference.
+ * @public
+ */
+type SubjectSessionTarget = {
+    subjectId: string;
+} | {
+    externalRef: string;
+};
+/** Result of {@link SessionsApi.resultToken}: a freshly signed result token. @public */
+interface ResultTokenResponse {
+    /** ES256 JWT; check it with {@link verifyResultToken}. */
+    token: string;
+    /** ISO 8601: when the token expires (10 minutes after signing). */
+    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.
+ * @public
+ */
+interface Session {
+    id: string;
+    /** Sekyro flows: the flow version the session runs (absent on sessions created before flows). */
+    flow?: SessionFlowRef;
+    status: SessionStatus;
+    outcome: SessionOutcome | null;
+    /**
+     * What the session proved ({@link VerificationLevel}); `null` while the
+     * session is active, `0` when it was rejected. Absent from older API versions.
+     */
+    level?: VerificationLevel | null;
+    /** How the level was proved; `null` while the session is active. */
+    assurance?: VerificationAssurance | null;
+    /** The billing unit the session consumed; `null` while the session is active. */
+    unit?: VerificationUnit | null;
+    /** The levels the session's flow can reach. */
+    levelTarget?: LevelTarget;
+    /** The checks on the session's path (checks of a lane the person did not take are omitted). */
+    steps: SessionStep[];
+    /** ISO 8601. */
+    expiresAt: string;
+    /** ISO 8601. */
+    createdAt: string;
+    /** ISO 8601: when the session reached a terminal state; `null` while it is active. */
+    completedAt?: string | null;
+    /** 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;
+    /** With failureReason `camera_unavailable`: why (`denied` or `no_camera`), when the SDK said. Absent otherwise. */
+    failureDetail?: CameraUnavailableCause;
+    /** 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;
+    /** The agent reference sent as `assistedBy` at create, for assisted capture. */
+    assistedBy?: {
+        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 paths this session's {@link CreateSessionInput.overrides} changed
+     * (e.g. `settings.decisions.mode`, `services.liveness`).
+     */
+    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;
+    /**
+     * On a session created for an existing subject: `recheck` (the same person
+     * again) or `step_up` (raised to identity level). Absent otherwise.
+     */
+    reuseMode?: SubjectReuseMode;
+    /** 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
+ * (`session.completed` | `session.failed` | `session.review_pending` |
+ * `session.expired`): ids and enums only, no civil data,
+ * scores or links. `outcome` and `steps` travel on `completed` / `failed`;
+ * `review_pending` carries `steps` without an outcome; `expired` carries the
+ * status and the session's refs (`flow`, subject ids, `overriddenFields`).
+ * @public
+ */
+interface SessionLifecycleEventData {
+    sessionId: string;
+    status: SessionStatus;
+    outcome?: SessionOutcome | null;
+    /** On `completed` / `failed`: the app the session belongs to. */
+    appId?: string;
+    /** On `completed` / `failed`: what the session proved ({@link VerificationLevel}). */
+    level?: VerificationLevel | null;
+    /** On `completed` / `failed`: how the level was proved. */
+    assurance?: VerificationAssurance | null;
+    /** On `completed` / `failed`: the billing unit the session consumed. */
+    unit?: VerificationUnit | null;
+    /** On `completed` / `failed`: ISO 8601 terminal time. */
+    verifiedAt?: string;
+    /** On `completed` / `failed`: device and network risk facts, when recorded. */
+    risk?: ResultRisk;
+    /** On `completed` / `failed`: other subjects the face matched, when a duplicate search ran. */
+    duplicates?: ResultDuplicate[];
+    /**
+     * On `completed` / `failed`: the signed result token (ES256 JWT, valid
+     * 10 minutes). Check it with {@link verifyResultToken}; absent when
+     * result tokens are not enabled.
+     */
+    resultToken?: string;
+    /** The checks on the session's path (checks of a lane the person did not take are omitted). */
+    steps?: Array<Pick<SessionStep, "checkType" | "state" | "nodeId" | "service">>;
+    /** Sekyro flows: the flow version the session runs (absent on sessions created before flows). */
+    flow?: SessionFlowRef;
+    /** 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;
+    /** On `session.failed` with failureReason `camera_unavailable`: why (`denied` or `no_camera`), when the SDK said. Absent otherwise. */
+    failureDetail?: CameraUnavailableCause;
+    /** 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 a session created for an existing subject: `recheck` (the same person
+     * again) or `step_up` (raised to identity level). Absent otherwise.
+     */
+    reuseMode?: SubjectReuseMode;
+    /**
+     * On `completed` / `failed`: the `link.state` the session was created
+     * with, echoed back; absent when the session had none.
+     */
+    link?: {
+        state: string;
+    };
+    /**
+     * On `session.failed` with `failureReason: 'device_cooldown'`: ISO time
+     * from which the device may start a new verification.
+     */
+    retryAfter?: string;
+    /** Dotted paths the session's create-time {@link CreateSessionInput.overrides} 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;
+    /** The session's level; absent on a revocation. */
+    level?: VerificationLevel | null;
+    /** The session's assurance; absent on a revocation. */
+    assurance?: VerificationAssurance | null;
+    /**
+     * Your own ids for the person (`subject.externalRef` values), so a
+     * revocation can find your user without a lookup. Absent from older API versions.
+     */
+    externalRefs?: string[];
+}
+/**
+ * `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;
+    /**
+     * With `subjectId` (a delete through the subjects API): your own ids for
+     * the person, so you can find your user. Never on the erasure variant.
+     */
+    externalRefs?: string[];
+}
+/** 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;
+    /** What the session proved; present only when stored (sessions linked before the field existed have none). */
+    level?: VerificationLevel;
+    /** How the session's level was proved; present only when stored. */
+    assurance?: VerificationAssurance;
+}
+/**
+ * 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;
+    /**
+     * The highest {@link VerificationLevel} an approved linked session proved;
+     * `0` once the subject is revoked; `null` when no terminal session was
+     * recorded since the field exists. Absent from API versions before the field.
+     */
+    level?: VerificationLevel | null | undefined;
+    /** ISO 8601: when {@link Subject.level} was last proved (the latest approved session at that level or higher); `null` with it. Absent with it. */
+    levelAt?: string | null | undefined;
+    /** The assurance of the session that proved {@link Subject.level}; `null` with it. Absent with it. */
+    levelAssurance?: VerificationAssurance | null | undefined;
+    /**
+     * 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 the returning-user limit of your app's default flow
+     * (`settings.returning`: turned on, and `maxAgeMonths` when set).
+     */
+    returningReady: boolean;
+    /** The verified name / birth date of the latest approved session. */
+    display?: {
+        name?: string;
+        birthDate?: string;
+    };
+}
+/**
+ * Filters of {@link SessionsApi.list}: your own user id
+ * (`subject.externalRef` at create) and/or a status.
+ * @public
+ */
+interface ListSessionsQuery {
+    /** Your own id for the person (1 to 128 characters). */
+    externalRef?: string;
+    status?: SessionStatus;
+}
+/** 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.
+ * @public
+ */
+interface SessionStepCompletedEventData {
+    sessionId: string;
+    checkType: CheckType;
+    state: CheckState;
+    /** Sekyro flows: the flow node of the passed check. */
+    nodeId?: string;
+    /** Sekyro flows: the service of that node. */
+    service?: ServiceId;
+    /** Sekyro flows: the flow version the session runs (absent on sessions created before flows). */
+    flow?: SessionFlowRef;
+    /** 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)
+ * decided a pending review. `outcome` speaks the REVIEW vocabulary
+ * (`pass` | `fail`), not the session outcome; `reason` is the reviewer's code
+ * (e.g. `review_timeout` for an expired review).
+ * @public
+ */
+interface SessionReviewDecidedEventData {
+    sessionId: string;
+    outcome: "pass" | "fail";
+    reason: string;
+    /** Sekyro flows: the flow version the session runs (absent on sessions created before flows). */
+    flow?: SessionFlowRef;
+    /** 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
+ * remaining events carry an open record until their payloads are frozen.
+ * @public
+ */
+interface WebhookEventDataMap {
+    "session.created": Record<string, unknown>;
+    "session.started": Record<string, unknown>;
+    "session.step.completed": SessionStepCompletedEventData;
+    "session.review_pending": SessionLifecycleEventData;
+    "session.review_decided": SessionReviewDecidedEventData;
+    "session.completed": SessionLifecycleEventData;
+    "session.expired": SessionLifecycleEventData;
+    "session.failed": SessionLifecycleEventData;
+    "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>;
+    "invoice.paid": Record<string, unknown>;
+    "invoice.overdue": Record<string, unknown>;
+    "webhook.test": Record<string, unknown>;
+}
+/** Every event a partner endpoint may receive. @public */
+type WebhookEventType = keyof WebhookEventDataMap;
+/**
+ * The signed webhook payload for ONE event type. There is no global API
+ * version; each event carries its own per-event `version`. Retried deliveries
+ * keep the same `id` — de-duplicate on it.
+ * @public
+ */
+interface WebhookEnvelopeOf<E extends WebhookEventType> {
+    /** UUIDv7, stable across delivery retries. */
+    id: string;
+    event: E;
+    /** Per-event payload version. */
+    version: number;
+    /** ISO 8601. */
+    createdAt: string;
+    orgId: string;
+    env: SekyroEnvironment;
+    data: WebhookEventDataMap[E];
+}
+/**
+ * The signed webhook payload, discriminated on `event`: narrowing on
+ * `envelope.event` narrows `envelope.data` to that event's shape.
+ *
+ * @example
+ * ```ts
+ * const envelope = verifyWebhook(rawBody, header, secret);
+ * switch (envelope.event) {
+ *   case "session.completed":
+ *     envelope.data.outcome; // SessionOutcome | null | undefined
+ *     break;
+ *   case "session.review_decided":
+ *     envelope.data.outcome; // "pass" | "fail"
+ *     break;
+ * }
+ * ```
+ * @public
+ */
+type WebhookEnvelope<E extends WebhookEventType = WebhookEventType> = E extends WebhookEventType ? WebhookEnvelopeOf<E> : never;
+/**
+ * `data` of any `session.*` event.
+ * @deprecated Use {@link SessionLifecycleEventData}, {@link SessionStepCompletedEventData}
+ * or {@link SessionReviewDecidedEventData}, or narrow a {@link WebhookEnvelope} on `event`.
+ * @public
+ */
+type SessionEventData = SessionLifecycleEventData | SessionStepCompletedEventData | SessionReviewDecidedEventData;
+
+/** Default partner API origin + version prefix. @public */
+declare const DEFAULT_BASE_URL = "https://api.sekyro.ai/api/v2";
+/** Default per-request timeout. @public */
+declare const DEFAULT_TIMEOUT_MS = 30000;
+/** `fetch`-compatible function; the global `fetch` by default. @public */
+type FetchLike = typeof globalThis.fetch;
+/** Constructor options of {@link Sekyro}. @public */
+interface SekyroOptions {
+    /** Partner API key (server-side only). Sent as `Authorization: Bearer`. */
+    apiKey: string;
+    /** API base URL incl. the `/api/v2` prefix. Default {@link DEFAULT_BASE_URL}. */
+    baseUrl?: string;
+    /** Per-request timeout in ms. Default {@link DEFAULT_TIMEOUT_MS}. */
+    timeoutMs?: number;
+    /** Custom `fetch` (tests, proxies, custom agents). Default `globalThis.fetch`. */
+    fetch?: FetchLike;
+}
+/**
+ * `sekyro.sessions` — create and read verification sessions.
+ *
+ * Exported as a TYPE only (`import type { SessionsApi }`): the class value is
+ * not part of the package surface, so it can only be obtained through
+ * {@link Sekyro.sessions} — never constructed by hand with an unchecked
+ * transport.
+ * @public
+ */
+declare class SessionsApi {
+    private readonly call;
+    /**
+     * Constructed by {@link Sekyro}; the transport is kept out of the public
+     * surface on purpose (only its bound `call` crosses this boundary).
+     * @internal
+     */
+    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.
+     * On a flow session: `409 choice_not_found` (the flow has no identity-method
+     * choice), `409 choice_locked`, `409 choice_option_unavailable` (see
+     * {@link isFlowError}).
+     */
+    selectMethod(id: string, method: IdentityMethod): Promise<Session>;
+    /** `GET /sessions/:id` — the whitelisted view (no client token). */
+    get(id: string): Promise<Session>;
+    /**
+     * `GET /sessions?externalRef=&status=`: your newest sessions (at most 100),
+     * optionally filtered by your own user id and/or a status. The filters are
+     * applied again to the answer, so an API that ignores them never returns
+     * another user's sessions.
+     */
+    list(query?: ListSessionsQuery): 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>;
+    /**
+     * `GET /sessions/:id/result-token`: a freshly signed result token for a
+     * finished session (valid 10 minutes; check it with
+     * {@link verifyResultToken}). `409 session_not_terminal` while the session
+     * is still active. Needs the `sessions:read` scope.
+     */
+    resultToken(id: string): Promise<ResultTokenResponse>;
+}
+/**
+ * `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>;
+    /**
+     * A re-check or step-up session for an existing subject in one call:
+     * `POST /subjects/:id/sessions` when `target` is a subject id (24
+     * hexadecimal characters) or `{ subjectId }`, otherwise
+     * `POST /subjects/by-external-ref/:externalRef/sessions` (pass
+     * `{ externalRef }` to force it). Same result and errors as
+     * {@link SessionsApi.create}; needs the `sessions:create` and
+     * `subjects:read` scopes.
+     */
+    createSession(target: string | SubjectSessionTarget, input: SubjectSessionInput, opts?: RequestOptions): Promise<CreatedSession>;
+}
+/**
+ * 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`,
+ * `127.0.0.1` and `[::1]` only).
+ *
+ * @example
+ * ```ts
+ * const sekyro = new Sekyro({ apiKey: process.env.SEKYRO_API_KEY! });
+ * const { id, clientToken } = await sekyro.sessions.create({ input: { nni: "1357924632" } });
+ * ```
+ * @public
+ */
+declare class Sekyro {
+    #private;
+    readonly sessions: SessionsApi;
+    readonly subjects: SubjectsApi;
+    constructor(opts: SekyroOptions);
+    /**
+     * `GET /flows` — the published flows of the API key's app (default flow
+     * first, then by name). Pass a flow's `slug` or `id` as
+     * {@link CreateSessionInput.flow}. Needs the `sessions:create` scope; an
+     * invalid key answers `401 unauthorized`.
+     */
+    listFlows(): Promise<FlowSummary[]>;
+}
+
+export { type SessionLifecycleEventData as $, type ListSessionsQuery as A, type PortraitReportEntry as B, type CreatedSession as C, DEFAULT_BASE_URL as D, type EidResult as E, type FetchLike as F, type ProbeBindingReason as G, type ProbeQuality as H, type IdentityMethod as I, type ProfileDocumentType as J, type RequestOptions as K, type Locale as L, type MatchReason as M, type ResultTokenResponse as N, type RevokeSubjectInput as O, type PolicyFailureReason as P, type SekyroOptions as Q, type ResultRisk as R, Sekyro as S, type Session as T, type SessionDevice as U, type VerificationLevel as V, type WebhookEventType as W, type SessionDeviceSignal as X, type SessionEventData as Y, type SessionFailureReason as Z, type SessionFlowRef as _, type ServiceId as a, type SessionLinkInput as a0, type SessionNetwork as a1, type SessionNetworkEvent as a2, type SessionPortraitLink as a3, type SessionReviewDecidedEventData as a4, type SessionStatus as a5, type SessionStep as a6, type SessionStepCompletedEventData as a7, type SessionSubjectInput as a8, SessionsApi as a9, type Subject as aa, type SubjectAssurance as ab, type SubjectDeletedEventData as ac, type SubjectEnrolledEventData as ad, type SubjectReferenceSource as ae, type SubjectReuseDocument as af, type SubjectReuseTarget as ag, type SubjectSession as ah, type SubjectSessionInput as ai, type SubjectSessionTarget as aj, type SubjectStatus as ak, type SubjectSuspiciousActivityEventData as al, type SubjectUpdatedEventData as am, SubjectsApi as an, type VerifiedContacts as ao, type WebhookEnvelopeOf as ap, type WebhookEventDataMap as aq, type SuppliedIdentityRecord as b, 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 ResultCheckProofs as i, type ResultDuplicate as j, type CameraUnavailableCause as k, type CheckState as l, type CheckType as m, type CreateSessionInput as n, DEFAULT_TIMEOUT_MS as o, type DecisionReason as p, type DeepPartial as q, type DeletedSubject as r, type DeliverOptions as s, type DocumentSubstitutionSettings as t, type EligibilityReason as u, type FlowOverridableSettings as v, type FlowOverrides as w, type FlowServiceSettings as x, type FlowSummary as y, type LevelTarget as z };