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

package/dist/index.d.ts

@@ -1,5 +1,5 @@
 /**
- * Wire-level enums and shapes of the Sekyro partner API (`/api/v2`). These
+ * Wire-level enums and shapes of the Sekyro AI partner API (`/api/v2`). These
  * mirror the backend's frozen partner contract; they are plain string unions so
  * a newer API value never throws at runtime — it simply widens the type in the
  * next SDK release.
@@ -14,10 +14,71 @@ type SessionStatus = "created" | "in_progress" | "review_pending" | "completed"
  * @public
  */
 type SessionOutcome = "approved" | "review" | "rejected";
+/**
+ * How the person proves their identity on an optional-document app: type the
+ * national number, or photograph the document.
+ * @public
+ */
+type IdentityMethod = "national_number" | "document_photo";
 /** The verification checks a flow may contain. @public */
 type CheckType = "liveness" | "face_match" | "doc_ocr" | "population_registry" | "phone_otp";
 /** Per-check execution state within a session. @public */
 type CheckState = "pending" | "input_required" | "processing" | "passed" | "failed" | "review" | "skipped";
+/**
+ * Why a session was stopped by a profile-v2 policy gate rather than by a
+ * failed check:
+ *  - `location_not_allowed` — the end user's IP location is not allowed for the app;
+ *  - `anonymizer_blocked` — an anonymizer (VPN / proxy / Tor) was detected while the app blocks them;
+ *  - `capture_tampered` — the device reported a tampered capture (virtual
+ *    camera, hooking, emulator…) while the app's `device.tamper` is `block`;
+ *  - `device_velocity_exceeded` — the device already verified more different
+ *    people than `device.velocity` allows, with `action: 'block'`;
+ *  - `device_cooldown` — the device had too many rejected sessions
+ *    (`cooldown` tiers); {@link Session.retryAfter} says when it may try again.
+ *    Not billed.
+ * @public
+ */
+type SessionFailureReason = "location_not_allowed" | "anonymizer_blocked" | "capture_tampered" | "device_velocity_exceeded" | "device_cooldown";
+/**
+ * Profile-v2 decision-mode reasons a check's {@link SessionStep.reason} may
+ * carry when the app decides automatically (`decisions.mode: 'automatic'`)
+ * instead of routing to human review. All are retryable within the step's
+ * attempts: `liveness_inconclusive` (liveness middle band),
+ * `match_inconclusive` (face match middle band on every reference),
+ * `document_authenticity` (doc_ocr authenticity warning — retake the original)
+ * and `mobile_required` (liveness captured on a desktop — continue on a phone;
+ * not billed). Every inconclusive attempt is billed.
+ * @public
+ */
+type DecisionReason = "liveness_inconclusive" | "match_inconclusive" | "document_authenticity" | "mobile_required";
+/**
+ * Profile-v2 eligibility reasons a check's {@link SessionStep.reason} may carry:
+ * `document_type_not_accepted` (doc_ocr; the person may pick another
+ * document), `nationality_not_allowed` and `underage` (doc_ocr or
+ * population_registry; terminal), and `age_unverifiable` (the app sets a
+ * minimum age but the birth date could not be read — doc_ocr: retryable with
+ * a clearer photo; population_registry: terminal).
+ * @public
+ */
+type EligibilityReason = "document_type_not_accepted" | "nationality_not_allowed" | "underage" | "age_unverifiable";
+/**
+ * Why a profile-v2 policy ended a session: a session-level
+ * {@link SessionFailureReason} (location / anonymizer gate), or the failed
+ * check's policy reason — an {@link EligibilityReason} or
+ * `document_nni_mismatch` (the document belongs to someone other than the
+ * NNI the session was created for).
+ * @public
+ */
+type PolicyFailureReason = SessionFailureReason | EligibilityReason | "document_nni_mismatch";
+/**
+ * Profile-v2 matching reasons a check's {@link SessionStep.reason} may carry
+ * when the data you sent in {@link CreateSessionInput.subject} differs from the
+ * reference identity: `name_mismatch`, `birth_date_mismatch`,
+ * `nationality_mismatch` (doc_ocr or population_registry) and
+ * `document_number_mismatch` (doc_ocr). All are final.
+ * @public
+ */
+type MatchReason = "name_mismatch" | "birth_date_mismatch" | "nationality_mismatch" | "document_number_mismatch";
 /** Hosted-flow languages. @public */
 type Locale = "ar" | "fr" | "en";
 /** The environment a webhook was emitted from. @public */
@@ -34,9 +95,11 @@ interface SessionStep {
     reason?: string;
     /** Calibrated model score in [0, 1] for scored checks (liveness, face match). */
     calibratedScore?: number;
+    /** The check failed after using all of its attempts. */
+    attemptsExhausted?: boolean;
 }
 /**
- * Out-of-band delivery of the session's hosted link, sent by Sekyro after the
+ * Out-of-band delivery of the session's hosted link, sent by Sekyro AI after the
  * session is created. Best effort: a failed send never fails the create.
  * @public
  */
@@ -46,6 +109,148 @@ interface DeliverOptions {
     /** E.164 phone number of the recipient, e.g. `+22236123456`. */
     to: string;
 }
+/**
+ * What you already know about the person (`subject` at session create). A
+ * closed object: unknown keys are refused (`400`). Every field is optional;
+ * `null` or blank counts as absent. Identity fields are compared with the
+ * person's document or registry record when the app's profile turns name
+ * matching on; `nni` binds the session to that identity.
+ * @public
+ */
+interface SessionSubjectInput {
+    /** 10-digit Mauritanian NNI, as a string. */
+    nni?: string;
+    /** E.164 phone number, e.g. `+22236123456`. */
+    phone?: string;
+    fullName?: string;
+    /** ISO 8601 date (`YYYY-MM-DD`). */
+    birthDate?: string;
+    /** ISO 3166-1 alpha-2, e.g. `MR`. */
+    nationality?: string;
+    /** Identity-document number (1–40 characters). */
+    documentNumber?: string;
+    /**
+     * Your own id for this person (1–128 characters). Echoed on the session and
+     * its webhooks, and searchable on the subjects API.
+     */
+    externalRef?: string;
+}
+/** A document type the backend reads (kyc-docs-v2 vocabulary). @public */
+type ProfileDocumentType = "carte_identite" | "passport";
+/**
+ * The settings of an app's eKYC profile that a session may override — a
+ * mirror of the backend profile (schema version 2) without `schemaVersion`,
+ * `link` (use {@link CreateSessionInput.ttlMinutes}) and `overrides` (the
+ * app's own permission). Country codes are ISO 3166-1 alpha-2 (`MR`).
+ * Used through {@link EkycProfileOverride}.
+ * @public
+ */
+interface EkycProfileSettings {
+    /** Phone OTP step: off, or on with where the number comes from. */
+    phone: "off" | {
+        numberSource: "prefilled" | "user_entered" | "prefilled_or_entered";
+    };
+    document: {
+        mode: "off" | "optional" | "mandatory";
+        /** Accepted document types: `'*'` (all) or a list, optionally per issuing country. */
+        accepted: {
+            default: "*" | ProfileDocumentType[];
+            byIssuer?: Record<string, ProfileDocumentType[]>;
+        };
+        /** Expired documents: refused, allowed, or allowed for `graceDays` (1–365) after expiry. */
+        expired: "reject" | "allow" | {
+            graceDays: number;
+        };
+        authenticity: "standard" | "off";
+    };
+    registry: {
+        enabled: boolean;
+        sources: Array<"MR.anrpts">;
+        /** Which identity is the reference for face match and your data. */
+        reference?: "document" | "registry";
+        /** What happens when the registry has no record for the NNI. */
+        onNoRecord?: "fail" | "use_document";
+    };
+    liveness: {
+        enabled: boolean;
+    };
+    faceMatch: {
+        enabled: boolean;
+    };
+    /** Comparison of your `subject` data with the reference identity. */
+    nameMatch?: {
+        level: "strict" | "standard" | "lenient";
+        onMismatch: "fail" | "signal";
+    };
+    /** Per-step attempt limits. */
+    attempts?: {
+        phone: number;
+        document: number;
+        registry: number;
+        liveness: number;
+        faceMatch: number;
+    };
+    /** Where the end user may be (IP location). */
+    locations: {
+        mode: "all";
+    } | {
+        mode: "only" | "all_except";
+        countries: string[];
+    };
+    anonymizers: "allow" | "block";
+    /** Accepted nationalities: `'*'` or a list, optionally per IP location. */
+    nationalities: {
+        default: "*" | string[];
+        byLocation?: Record<string, "*" | string[]>;
+    };
+    /** Minimum age in years (1–120), or `null` for none. */
+    minAge: number | null;
+    /** Automatic decisions instead of human review (`retryConfidentRejects` lets confident rejects retry). */
+    decisions?: {
+        mode: "automatic" | "review";
+        retryConfidentRejects: boolean;
+    };
+    /** Device cooldown after repeated rejections (at most 5 tiers; `[]` = off). */
+    cooldown?: {
+        tiers: Array<{
+            rejectedSessions: number;
+            windowHours: number;
+            waitMinutes: number;
+        }>;
+    };
+    /** Device tamper and velocity actions. */
+    device?: {
+        tamper: "block" | "signal";
+        velocity: {
+            maxIdentitiesPerDevice: number;
+            windowDays: number;
+            action: "signal" | "block";
+        };
+    };
+}
+/**
+ * `T` with every property optional, recursively. Arrays are replaced as a
+ * whole, never merged element by element.
+ * @public
+ */
+type DeepPartial<T> = T extends readonly unknown[] ? T : T extends object ? {
+    [K in keyof T]?: DeepPartial<T[K]>;
+} : T;
+/**
+ * A per-session override of the app's eKYC profile
+ * ({@link CreateSessionInput.profile}): any subset of
+ * {@link EkycProfileSettings}, at any depth (every field optional). Objects
+ * are merged into the app's profile; arrays and scalar values replace it.
+ *
+ * The API validates the merged result like a profile save. Unknown keys are
+ * rejected server-side (`400`, also for keys this SDK version does not type).
+ * An override may only make the profile stricter unless the app allows
+ * widening (`overrides.allowWidening`); otherwise a widening change answers
+ * `403 override_widens_profile`. The changed paths are reported on
+ * {@link Session.overriddenFields}.
+ * @public
+ */
+type EkycProfileOverride = DeepPartial<EkycProfileSettings>;
 /**
  * Input of {@link SessionsApi.create}. There is no recipe field: the API key
  * belongs to an app, and that app's eKYC profile decides the steps.
@@ -54,6 +259,11 @@ interface DeliverOptions {
 interface CreateSessionInput {
     /** Pins the hosted-flow language. Omit to let the person's device decide. */
     locale?: Locale;
+    /**
+     * Pre-choose the identity method when the app's document step is optional
+     * (the hosted method screen is then skipped). Ignored for other apps.
+     */
+    identityMethod?: IdentityMethod;
     /**
      * Session lifetime in minutes. Must fall within the app profile's link
      * range, otherwise the API answers `400 ttl_out_of_policy`. Omit to use the
@@ -62,6 +272,19 @@ interface CreateSessionInput {
     ttlMinutes?: number;
     /** Also send the hosted link to the person by SMS or WhatsApp. */
     deliver?: DeliverOptions;
+    /**
+     * What you already know about the person (preferred over `input` for
+     * identity data). A key sent in both `subject` and `input` with different
+     * values answers `400 subject_input_conflict`.
+     */
+    subject?: SessionSubjectInput;
+    /**
+     * Override the app's eKYC profile for this session only (profile v2): a
+     * deep-partial {@link EkycProfileOverride}. Unknown keys are rejected
+     * server-side; a change that makes the profile less strict answers
+     * `403 override_widens_profile` unless the app allows widening.
+     */
+    profile?: EkycProfileOverride;
     /**
      * Step inputs consumed server-side. The known anchors are typed (all
      * strings — an `nni` is a 10-digit string, never a number); further keys
@@ -102,6 +325,63 @@ interface CreatedSession {
     /** ISO 8601 — when the session (and its link) stop accepting input. */
     expiresAt: string;
 }
+/**
+ * The end user's network at the start of the session (IP-derived, approximate).
+ * @public
+ */
+interface SessionNetworkEvent {
+    /** ISO 8601. */
+    at: string;
+    /** ISO 3166-1 alpha-2. */
+    country?: string;
+    region?: string;
+    city?: string;
+    asn?: number;
+    operator?: string;
+    connectionType: "mobile" | "hosting" | "unknown";
+    anonymizer: {
+        vpn: boolean;
+        tor: boolean;
+        hosting: boolean;
+    };
+    /** IANA time zone reported by the end user's device. */
+    browserTimezone?: string;
+    /** True when the device time zone does not belong to the IP country. */
+    timezoneMismatch?: boolean;
+}
+/**
+ * End-user network context; absent when not recorded.
+ * @public
+ */
+interface SessionNetwork {
+    /** The start event's IP address. Never sent in webhooks. */
+    ip?: string;
+    /** True when a later call came from a different country than the start. */
+    countryChanged: boolean;
+    start: SessionNetworkEvent;
+}
+/**
+ * Device signals detected on the end user's device.
+ * @public
+ */
+type SessionDeviceSignal = "webdriver" | "headless" | "emulator" | "rooted" | "jailbroken" | "debugger" | "hooking" | "virtual_camera";
+/**
+ * End-user device summary; absent when not recorded.
+ * @public
+ */
+interface SessionDevice {
+    platform: "web" | "android" | "ios";
+    sdk?: string;
+    os?: string;
+    osVersion?: string;
+    browser?: string;
+    browserVersion?: string;
+    deviceClass: "mobile" | "tablet" | "desktop" | "unknown";
+    model?: string;
+    /** Device ids hashed with a key unique to your organization. */
+    deviceKeys: string[];
+    signals: SessionDeviceSignal[];
+}
 /**
  * The whitelisted session view returned by {@link SessionsApi.get}. Never
  * contains the client token.
@@ -116,6 +396,37 @@ interface Session {
     expiresAt: string;
     /** ISO 8601. */
     createdAt: string;
+    /** End-user network context; absent when not recorded. */
+    network?: SessionNetwork;
+    /** End-user device; absent when not recorded. */
+    device?: SessionDevice;
+    /**
+     * Set when a profile-v2 policy ended the session: a session-level gate
+     * (location, anonymizer) or a failed check's policy reason (eligibility,
+     * `document_nni_mismatch`). Absent otherwise.
+     */
+    failureReason?: PolicyFailureReason;
+    /** The subject (person) this session is linked to, once an identifier is known. */
+    subjectId?: string;
+    /** Your own id for the person, from `subject.externalRef` at create. */
+    externalRef?: string;
+    /**
+     * `true` when an identifier this session read already belongs to a
+     * different subject than `subjectId` — the subjects are never merged.
+     */
+    subjectConflict?: boolean;
+    /**
+     * ISO 8601 — when the end user's device may verify again; set with
+     * `failureReason: 'device_cooldown'`.
+     */
+    retryAfter?: string;
+    /** Dotted profile paths this session's {@link CreateSessionInput.profile} changed (e.g. `decisions.mode`). */
+    overriddenFields?: string[];
+    /**
+     * Risk signals recorded on the session (e.g. `device_velocity`,
+     * `timezone_mismatch`) — signals only, never a verdict by themselves.
+     */
+    riskSignals?: string[];
 }
 /**
  * `data` of the terminal / review-pending session lifecycle events
@@ -133,6 +444,54 @@ interface SessionLifecycleEventData {
     steps?: Array<Pick<SessionStep, "checkType" | "state">>;
     /** Machine-readable reason, when the transition has one. */
     reason?: string;
+    /** End-user network context (no IP); on `completed` / `failed` when recorded. */
+    network?: Omit<SessionNetwork, "ip">;
+    /** End-user device; on `completed` / `failed` when recorded. */
+    device?: SessionDevice;
+    /**
+     * On `session.failed`: set when a profile-v2 policy ended the session — a
+     * session-level gate (location, anonymizer) or a failed check's policy
+     * reason (eligibility, `document_nni_mismatch`).
+     */
+    failureReason?: PolicyFailureReason;
+    /** The subject (person) the session is linked to, when known. */
+    subjectId?: string;
+    /** Your own id for the person, from `subject.externalRef` at create. */
+    externalRef?: string;
+    /**
+     * `true` when an identifier this session read already belongs to a
+     * different subject than `subjectId` — the subjects are never merged.
+     */
+    subjectConflict?: boolean;
+    /**
+     * On `session.failed` with `failureReason: 'device_cooldown'`: ISO time
+     * from which the device may start a new verification.
+     */
+    retryAfter?: string;
+    /** Dotted profile paths the session's create-time override changed. */
+    overriddenFields?: string[];
+}
+/**
+ * `data` of `subject.updated` — a session linked to the subject reached a
+ * terminal state. Ids and enums only.
+ * @public
+ */
+interface SubjectUpdatedEventData {
+    subjectId: string;
+    sessionId: string;
+    status: SessionStatus;
+    outcome: SessionOutcome | null;
+}
+/**
+ * `data` of `subject.suspicious_activity` — a device already linked to
+ * ANOTHER subject was used for a session of this subject. `count` is the
+ * subject's running total of such events. Ids only.
+ * @public
+ */
+interface SubjectSuspiciousActivityEventData {
+    subjectId: string;
+    sessionId: string;
+    count: number;
 }
 /**
  * `data` of `session.step.completed` — the check that just passed.
@@ -142,6 +501,15 @@ interface SessionStepCompletedEventData {
     sessionId: string;
     checkType: CheckType;
     state: CheckState;
+    /** The subject (person) the session is linked to, when known. */
+    subjectId?: string;
+    /** Your own id for the person, from `subject.externalRef` at create. */
+    externalRef?: string;
+    /**
+     * `true` when an identifier this session read already belongs to a
+     * different subject than `subjectId` — the subjects are never merged.
+     */
+    subjectConflict?: boolean;
 }
 /**
  * `data` of `session.review_decided` — a human (or the review-timeout sweep)
@@ -154,6 +522,15 @@ interface SessionReviewDecidedEventData {
     sessionId: string;
     outcome: "pass" | "fail";
     reason: string;
+    /** The subject (person) the session is linked to, when known. */
+    subjectId?: string;
+    /** Your own id for the person, from `subject.externalRef` at create. */
+    externalRef?: string;
+    /**
+     * `true` when an identifier this session read already belongs to a
+     * different subject than `subjectId` — the subjects are never merged.
+     */
+    subjectConflict?: boolean;
 }
 /**
  * Event type → the shape of its `data`. Session events are typed; the
@@ -171,6 +548,8 @@ interface WebhookEventDataMap {
     "session.expired": SessionLifecycleEventData;
     "session.failed": SessionLifecycleEventData;
     "subject.enrolled": Record<string, unknown>;
+    "subject.updated": SubjectUpdatedEventData;
+    "subject.suspicious_activity": SubjectSuspiciousActivityEventData;
     "subject.deleted": Record<string, unknown>;
     "aml.match_flagged": Record<string, unknown>;
     "payment.received": Record<string, unknown>;
@@ -266,11 +645,18 @@ declare class SessionsApi {
      * cannot create a second session.
      */
     create(input?: CreateSessionInput, opts?: RequestOptions): Promise<CreatedSession>;
+    /**
+     * `POST /sessions/:id/method` — choose the identity method of an
+     * optional-document session on the person's behalf (the hosted method
+     * screen is then skipped). `409 method_locked` once the choice can no
+     * longer change; `409 session_not_active` on a finished or expired session.
+     */
+    selectMethod(id: string, method: IdentityMethod): Promise<Session>;
     /** `GET /sessions/:id` — the whitelisted view (no client token). */
     get(id: string): Promise<Session>;
 }
 /**
- * Sekyro partner API client. Server-side only: it carries your API key.
+ * 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`,
@@ -292,7 +678,7 @@ declare class Sekyro {
 type SekyroWebhookErrorCode = "invalid_signature" | "stale" | "malformed";
 /**
  * Thrown by {@link verifyWebhook}. Respond with a 4xx and do not process the
- * body; Sekyro retries deliveries that do not receive a 2xx.
+ * body; Sekyro AI retries deliveries that do not receive a 2xx.
  * @public
  */
 declare class SekyroWebhookError extends Error {
@@ -352,7 +738,7 @@ declare class SekyroApiError extends Error {
  */
 declare const SEKYRO_SIGNATURE_HEADER = "x-sekyro-signature";
 /**
- * The pre-rebrand name of the signature header. Sekyro sends BOTH headers with
+ * The pre-rebrand name of the signature header. Sekyro AI sends BOTH headers with
  * the same value during the transition; prefer {@link SEKYRO_SIGNATURE_HEADER}
  * and use {@link signatureFromHeaders} to accept either.
  * @public
@@ -380,13 +766,13 @@ interface VerifyWebhookOptions {
     now?: () => number;
 }
 /**
- * Verify a Sekyro webhook delivery and return its parsed envelope, discriminated
+ * Verify a Sekyro AI webhook delivery and return its parsed envelope, discriminated
  * on `event` (narrow with a `switch` to type `data`).
  *
  * - `rawBody` MUST be the request body exactly as received (before any JSON
  *   parsing / re-serialisation); the signature covers those bytes.
  * - Accepts the delivery when ANY `v1` in the header matches, which is what
- *   makes secret rotation seamless (Sekyro signs with current + previous).
+ *   makes secret rotation seamless (Sekyro AI signs with current + previous).
  * - Uses `node:crypto` only; the digest compare is constant-time.
  *
  * Checks run in this order: header/secret present → header well-formed →
@@ -401,4 +787,4 @@ interface VerifyWebhookOptions {
  */
 declare function verifyWebhook(rawBody: string, header: string | null | undefined, secret: string, opts?: VerifyWebhookOptions): WebhookEnvelope;
 
-export { type CheckState, type CheckType, type CreateSessionInput, type CreatedSession, DEFAULT_BASE_URL, DEFAULT_TIMEOUT_MS, type DeliverOptions, type FetchLike, LEGACY_SIGNATURE_HEADER, type Locale, type RequestOptions, SEKYRO_SIGNATURE_HEADER, Sekyro, SekyroApiError, type SekyroApiErrorInit, type SekyroClientErrorCode, SekyroConfigError, type SekyroConfigErrorCode, type SekyroEnvironment, type SekyroOptions, SekyroWebhookError, type SekyroWebhookErrorCode, type Session, type SessionEventData, type SessionLifecycleEventData, type SessionOutcome, type SessionReviewDecidedEventData, type SessionStatus, type SessionStep, type SessionStepCompletedEventData, SessionsApi, type VerifyWebhookOptions, type WebhookEnvelope, type WebhookEnvelopeOf, type WebhookEventDataMap, type WebhookEventType, signatureFromHeaders, verifyWebhook };
+export { type CheckState, type CheckType, type CreateSessionInput, type CreatedSession, DEFAULT_BASE_URL, DEFAULT_TIMEOUT_MS, type DecisionReason, type DeepPartial, type DeliverOptions, type EkycProfileOverride, type EkycProfileSettings, type EligibilityReason, type FetchLike, type IdentityMethod, LEGACY_SIGNATURE_HEADER, type Locale, type MatchReason, type PolicyFailureReason, type ProfileDocumentType, type RequestOptions, 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 SessionReviewDecidedEventData, type SessionStatus, type SessionStep, type SessionStepCompletedEventData, type SessionSubjectInput, SessionsApi, type SubjectSuspiciousActivityEventData, type SubjectUpdatedEventData, type VerifyWebhookOptions, type WebhookEnvelope, type WebhookEnvelopeOf, type WebhookEventDataMap, type WebhookEventType, signatureFromHeaders, verifyWebhook };