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

package/dist/index.d.ts

@@ -101,6 +101,12 @@ type SekyroEnvironment = "sandbox" | "live";
 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;
     /** Calibrated model score in [0, 1] for scored checks (liveness, face match). */
@@ -200,7 +206,8 @@ interface SessionSubjectInput {
      * 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
+     * `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;
@@ -226,42 +233,52 @@ type SubjectReuseTarget = {
 /** 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}.
+ * 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
  */
-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[];
+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;
     };
-    /** Email OTP step (absent = off): a one-time code sent to the person's email address. */
-    email?: "off" | ProfileEmail;
-    document: {
-        mode: "off" | "optional" | "mandatory";
+    /** 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[];
@@ -273,98 +290,123 @@ interface EkycProfileSettings {
         };
         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";
+}
+/**
+ * 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";
     };
-    liveness: {
-        enabled: boolean;
+    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;
     };
-    faceMatch: {
-        enabled: boolean;
+    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;
     };
-    /** Comparison of your `subject` data with the reference identity. */
-    nameMatch?: {
-        level: "strict" | "standard" | "lenient";
-        onMismatch: "fail" | "signal";
+    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;
     };
-    /** 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;
+    document: {
+        attempts?: number;
+        /** Compare the document photo with the registry photo (absent = the platform default). */
+        documentSubstitution?: DocumentSubstitutionSettings;
     };
-    /** Where the end user may be (IP location). */
-    locations: {
-        mode: "all";
-    } | {
-        mode: "only" | "all_except";
-        countries: string[];
+    /** 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;
     };
-    anonymizers: "allow" | "block";
-    /** Accepted nationalities: `'*'` or a list, optionally per IP location. */
-    nationalities: {
-        default: "*" | string[];
-        byLocation?: Record<string, "*" | string[]>;
+    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;
     };
-    /** 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;
+    supplied_identity: Record<string, never>;
+    summary_confirm: {
+        /** Offer « Reprendre » (re-open the identity source). */
+        retake: boolean;
     };
-    /** Device cooldown after repeated rejections (at most 5 tiers; `[]` = off). */
-    cooldown?: {
-        tiers: Array<{
-            rejectedSessions: number;
-            windowHours: number;
-            waitMinutes: number;
-        }>;
+    liveness: {
+        /** `off`, selfie ICAO `alert` / `reject`, or `id_document` (ID-photo portrait, always rejects). */
+        icao: "off" | "alert" | "reject" | "id_document";
+        attempts?: number;
     };
-    /** Device tamper and velocity actions. */
-    device?: {
-        tamper: "block" | "signal";
-        velocity: {
-            maxIdentitiesPerDevice: number;
-            windowDays: number;
-            action: "signal" | "block";
-        };
+    face_match: {
+        reference: "auto" | "document" | "registry";
+        attempts?: number;
     };
-    /**
-     * 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";
-        };
+    aml_screening: {
+        lists: Array<"sanctions" | "pep" | "adverse_media">;
+        onHit: "review" | "fail";
+    };
+    face_dedup: {
+        scope: "app" | "org";
+        onDuplicate: "review" | "fail";
     };
-}
-/**
- * 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
@@ -375,37 +417,86 @@ 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.
+ * A per-session override of the flow ({@link CreateSessionInput.overrides}).
  *
- * 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}.
+ * - `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
  */
-type EkycProfileOverride = DeepPartial<EkycProfileSettings>;
+interface SessionFlowRef {
+    id: string;
+    slug: string;
+    version: number;
+}
 /**
- * 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.
+ * 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 app's document step is optional
-     * (the hosted method screen is then skipped). Ignored for other apps.
+     * 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 app profile's link
-     * range, otherwise the API answers `400 ttl_out_of_policy`. Omit to use the
-     * profile's default.
+     * 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. */
@@ -417,12 +508,13 @@ interface CreateSessionInput {
      */
     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.
+     * 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.
      */
-    profile?: EkycProfileOverride;
+    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
@@ -507,6 +599,9 @@ interface CreatedSession {
     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;
@@ -612,8 +707,11 @@ interface VerifiedContacts {
  */
 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;
+    /** The checks on the session's path (checks of a lane the person did not take are omitted). */
     steps: SessionStep[];
     /** ISO 8601. */
     expiresAt: string;
@@ -643,7 +741,10 @@ interface Session {
      * `failureReason: 'device_cooldown'`.
      */
     retryAfter?: string;
-    /** Dotted profile paths this session's {@link CreateSessionInput.profile} changed (e.g. `decisions.mode`). */
+    /**
+     * 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`,
@@ -675,14 +776,17 @@ interface Session {
  * `session.expired` | `session.rejected`) — 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 alone.
+ * status and the session's refs (`flow`, subject ids, `overriddenFields`).
  * @public
  */
 interface SessionLifecycleEventData {
     sessionId: string;
     status: SessionStatus;
     outcome?: SessionOutcome | null;
-    steps?: Array<Pick<SessionStep, "checkType" | "state">>;
+    /** 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. */
@@ -713,7 +817,7 @@ interface SessionLifecycleEventData {
      * from which the device may start a new verification.
      */
     retryAfter?: string;
-    /** Dotted profile paths the session's create-time override changed. */
+    /** 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;
@@ -818,8 +922,8 @@ interface Subject {
     /**
      * 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).
+     * 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. */
@@ -857,6 +961,12 @@ 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. */
@@ -884,6 +994,8 @@ 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. */
@@ -1018,6 +1130,9 @@ declare class SessionsApi {
      * 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). */
@@ -1079,9 +1194,17 @@ declare class SubjectsApi {
  * @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; a key
+     * not bound to an app answers `401 key_not_bound`.
+     */
+    listFlows(): Promise<FlowSummary[]>;
 }
 
 /** Why {@link verifyWebhook} rejected a delivery. @public */
@@ -1109,15 +1232,104 @@ declare class SekyroConfigError extends TypeError {
     readonly code: SekyroConfigErrorCode;
     constructor(code: SekyroConfigErrorCode, message?: string);
 }
+/**
+ * The flow codes of the partner API (Sekyro flows). Each carries
+ * {@link SekyroApiError.details} (see {@link SekyroFlowErrorDetailsMap} and
+ * {@link isFlowError}). On `sessions.create`:
+ *  - `flow_not_found` (404): no flow with this slug or `flw_` id in the key's app;
+ *  - `flow_not_published` (409): the flow has no published version yet;
+ *  - `flow_archived` (409): the flow is archived;
+ *  - `override_invalid` (400): an unknown key or value in `overrides`, or a
+ *    result that is not a valid flow;
+ *  - `override_widens_flow` (403): the override makes the flow less strict
+ *    (e.g. a service turned `'off'`) and the flow does not allow widening;
+ *  - `reuse_disabled` (409): `subject.reuse` on a flow whose returning-user
+ *    sessions are turned off.
+ *
+ * On `sessions.selectMethod` (a flow session's identity-method choice):
+ * `choice_not_found` (409: the session's flow has no identity-method choice),
+ * `choice_locked` (409: it can no longer change) and
+ * `choice_option_unavailable` (409: that method is not offered).
+ * @public
+ */
+type SekyroFlowErrorCode = "flow_not_found" | "flow_not_published" | "flow_archived" | "override_invalid" | "override_widens_flow" | "reuse_disabled" | "choice_not_found" | "choice_locked" | "choice_option_unavailable";
+/**
+ * One machine-readable issue of a flow error. Never carries a value you sent.
+ * @public
+ */
+interface FlowErrorIssue {
+    /**
+     * A flow validation code (e.g. `face_match_needs_liveness`), `schema_invalid`,
+     * `schema_unknown_field`, `field_widens_flow`, or the error's own code.
+     */
+    code: string;
+    /** A short plain English sentence. */
+    message: string;
+    /** The field of your request body, e.g. `overrides.services.liveness.attempts`, `flow`, `subject.reuse`. */
+    path?: string;
+    /** A node of your app's flow. */
+    nodeId?: string;
+    /** The service of that node (or of the `overrides.services` key). */
+    service?: ServiceId;
+    /** `override_widens_flow`: the widened field, e.g. `settings.eligibility.minAge`, `services.nfc`. */
+    field?: string;
+}
+/** `details` common to every flow error: at least one issue. @public */
+interface FlowErrorDetails {
+    issues: FlowErrorIssue[];
+}
+/** `details` of `override_widens_flow`: the widened fields, plus one `field_widens_flow` issue each. @public */
+interface FlowWidensErrorDetails extends FlowErrorDetails {
+    fields: string[];
+}
+/** `details` of `flow_not_published`, `flow_archived` and `reuse_disabled`: the flow concerned. @public */
+interface FlowRefErrorDetails extends FlowErrorDetails {
+    flow: {
+        id: string;
+        slug: string;
+    };
+}
+/**
+ * {@link SekyroFlowErrorCode} → the shape of its {@link SekyroApiError.details}.
+ * @public
+ */
+interface SekyroFlowErrorDetailsMap {
+    flow_not_found: FlowErrorDetails;
+    flow_not_published: FlowRefErrorDetails;
+    flow_archived: FlowRefErrorDetails;
+    override_invalid: FlowErrorDetails;
+    override_widens_flow: FlowWidensErrorDetails;
+    reuse_disabled: FlowRefErrorDetails;
+    choice_not_found: FlowErrorDetails;
+    choice_locked: FlowErrorDetails;
+    choice_option_unavailable: FlowErrorDetails;
+}
+/**
+ * A {@link SekyroApiError} narrowed by {@link isFlowError}: `code` is a flow
+ * code and `details` has that code's shape.
+ * @public
+ */
+type SekyroFlowError<C extends SekyroFlowErrorCode = SekyroFlowErrorCode> = C extends SekyroFlowErrorCode ? SekyroApiError & {
+    readonly code: C;
+    readonly details: SekyroFlowErrorDetailsMap[C];
+} : never;
+/**
+ * {@link SekyroApiError.code}: an SDK code, a documented flow code, or any
+ * other API code (the union stays open so a new API code never breaks a build).
+ * @public
+ */
+type SekyroApiErrorCode = SekyroClientErrorCode | SekyroFlowErrorCode | (string & {});
 /** Constructor input of {@link SekyroApiError}. @public */
 interface SekyroApiErrorInit {
     /** HTTP status; `0` when no response was received (network / timeout). */
     status: number;
     /** API error code, or `network` | `timeout` | `http_error` | `malformed_response`. */
-    code: string;
+    code: SekyroApiErrorCode;
     message: string;
     /** The API's `request_id`, when the response carried one. */
     requestId?: string;
+    /** The API's `error.details`, when the response carried them (the flow codes: {@link SekyroFlowErrorDetailsMap}). */
+    details?: unknown;
     /** Underlying error (network failures, abort reasons, JSON parse errors). */
     cause?: unknown;
 }
@@ -1135,11 +1347,35 @@ type SekyroClientErrorCode = "network" | "timeout" | "http_error" | "malformed_r
 declare class SekyroApiError extends Error {
     readonly name = "SekyroApiError";
     readonly status: number;
-    readonly code: string;
+    readonly code: SekyroApiErrorCode;
     readonly requestId: string | undefined;
+    /**
+     * The API's `error.details`, when the response carried them; `undefined`
+     * otherwise. Untyped here: narrow with {@link isFlowError} to read a flow
+     * code's documented shape ({@link SekyroFlowErrorDetailsMap}).
+     */
+    readonly details: unknown;
     readonly retryable: boolean;
     constructor(init: SekyroApiErrorInit);
 }
+/**
+ * Narrow an error to a flow error, optionally to given codes: `true` only for
+ * a {@link SekyroApiError} with a flow code whose `details` have that code's
+ * documented shape, so `err.details` is typed after the check. An error whose
+ * `details` are missing or unexpected is not narrowed (read `err.code`).
+ *
+ * @example
+ * ```ts
+ * try {
+ *   await sekyro.sessions.create({ flow, overrides });
+ * } catch (err) {
+ *   if (isFlowError(err, "override_widens_flow")) err.details.fields; // string[]
+ *   else if (isFlowError(err)) err.details.issues.map((i) => i.path);
+ * }
+ * ```
+ * @public
+ */
+declare function isFlowError<C extends SekyroFlowErrorCode = SekyroFlowErrorCode>(err: unknown, ...codes: C[]): err is SekyroFlowError<C>;
 
 /**
  * The raw ANRPTS `getPersonne` answer your server received with your own
@@ -1252,4 +1488,4 @@ interface VerifyWebhookOptions {
  */
 declare function verifyWebhook(rawBody: string, header: string | null | undefined, secret: string, opts?: VerifyWebhookOptions): WebhookEnvelope;
 
-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 };
+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 DocumentSubstitutionSettings, type EidResult, type EligibilityReason, type FetchLike, type FlowErrorDetails, type FlowErrorIssue, type FlowOverridableSettings, type FlowOverrides, type FlowRefErrorDetails, type FlowServiceSettings, type FlowSummary, type FlowWidensErrorDetails, type IdentityMethod, LEGACY_SIGNATURE_HEADER, type Locale, type MatchReason, type PolicyFailureReason, type PortraitReportEntry, type ProbeBindingReason, type ProbeQuality, type ProfileDocumentType, type RegistryFromAnrptsOptions, type RequestOptions, type RevokeSubjectInput, SEKYRO_SIGNATURE_HEADER, Sekyro, SekyroApiError, type SekyroApiErrorCode, type SekyroApiErrorInit, type SekyroClientErrorCode, SekyroConfigError, type SekyroConfigErrorCode, type SekyroEnvironment, type SekyroFlowError, type SekyroFlowErrorCode, type SekyroFlowErrorDetailsMap, type SekyroOptions, SekyroWebhookError, type SekyroWebhookErrorCode, type ServiceId, type Session, type SessionDevice, type SessionDeviceSignal, type SessionEventData, type SessionFailureReason, type SessionFlowRef, 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, isFlowError, registryFromAnrpts, signatureFromHeaders, verifyWebhook };