@sekyro/node 0.0.0-stage → 0.1.0-rc.1

package/dist/index.d.cts

@@ -0,0 +1,389 @@
+/**
+ * Wire-level enums and shapes of the Sekyro 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";
+/** 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";
+/** Hosted-flow languages. @public */
+type Locale = "ar" | "fr" | "en";
+/** 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;
+    /** Machine-readable failure/review reason, when the check has one. */
+    reason?: string;
+    /** Calibrated model score in [0, 1] for scored checks (liveness, face match). */
+    calibratedScore?: number;
+}
+/**
+ * Input of {@link SessionsApi.create}. Name the recipe by EITHER `flow` (the
+ * flow slug) OR `templateId` — exactly one; the API rejects both or neither.
+ * @public
+ */
+interface CreateSessionInput {
+    /** Flow slug configured for your organisation. */
+    flow?: string;
+    /** Legacy template id (pre-flows path). Prefer `flow`. */
+    templateId?: string;
+    /** Pins the hosted-flow language. Omit to let the person's device decide. */
+    locale?: Locale;
+    /**
+     * 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;
+        fullName?: string;
+        /** ISO 8601 date (`YYYY-MM-DD`). */
+        birthDate?: string;
+    } & Record<string, unknown>;
+}
+/** 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;
+    steps: SessionStep[];
+    /** ISO 8601 — when the session (and its link) stop accepting input. */
+    expiresAt: string;
+}
+/**
+ * The whitelisted session view returned by {@link SessionsApi.get}. Never
+ * contains the client token.
+ * @public
+ */
+interface Session {
+    id: string;
+    status: SessionStatus;
+    outcome: SessionOutcome | null;
+    steps: SessionStep[];
+    /** ISO 8601. */
+    expiresAt: string;
+    /** ISO 8601. */
+    createdAt: string;
+}
+/**
+ * `data` of the terminal / review-pending session lifecycle events
+ * (`session.completed` | `session.failed` | `session.review_pending` |
+ * `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.
+ * @public
+ */
+interface SessionLifecycleEventData {
+    sessionId: string;
+    status: SessionStatus;
+    outcome?: SessionOutcome | null;
+    steps?: Array<Pick<SessionStep, "checkType" | "state">>;
+    /** Machine-readable reason, when the transition has one. */
+    reason?: string;
+}
+/**
+ * `data` of `session.step.completed` — the check that just passed.
+ * @public
+ */
+interface SessionStepCompletedEventData {
+    sessionId: string;
+    checkType: CheckType;
+    state: CheckState;
+}
+/**
+ * `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;
+}
+/**
+ * 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.rejected": SessionLifecycleEventData;
+    "session.expired": SessionLifecycleEventData;
+    "session.failed": SessionLifecycleEventData;
+    "subject.enrolled": Record<string, unknown>;
+    "subject.deleted": Record<string, unknown>;
+    "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", 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>;
+    /** `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.
+ *
+ * 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({ flow: "onboarding" });
+ * ```
+ * @public
+ */
+declare class Sekyro {
+    readonly sessions: SessionsApi;
+    constructor(opts: SekyroOptions);
+}
+
+/** Why {@link verifyWebhook} rejected a delivery. @public */
+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.
+ * @public
+ */
+declare class SekyroWebhookError extends Error {
+    readonly name = "SekyroWebhookError";
+    readonly code: SekyroWebhookErrorCode;
+    constructor(code: SekyroWebhookErrorCode, message?: string);
+}
+/** Why the {@link Sekyro} constructor rejected its options. @public */
+type SekyroConfigErrorCode = "missing_api_key" | "invalid_base_url";
+/**
+ * Thrown synchronously by `new Sekyro(...)` for an unusable configuration —
+ * before any request is made. Extends `TypeError` so existing
+ * `instanceof TypeError` guards keep working.
+ * @public
+ */
+declare class SekyroConfigError extends TypeError {
+    readonly name = "SekyroConfigError";
+    readonly code: SekyroConfigErrorCode;
+    constructor(code: SekyroConfigErrorCode, message?: 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;
+    message: string;
+    /** The API's `request_id`, when the response carried one. */
+    requestId?: string;
+    /** Underlying error (network failures, abort reasons, JSON parse errors). */
+    cause?: unknown;
+}
+/** Error codes the SDK itself produces (as opposed to codes from the API). @public */
+type SekyroClientErrorCode = "network" | "timeout" | "http_error" | "malformed_response";
+/**
+ * Any failed call through {@link Sekyro}: a non-2xx partner envelope
+ * `{ status: 'error', error: { code, message, request_id } }`, a non-JSON
+ * response, a network failure or a timeout.
+ *
+ * `retryable` is `true` for `network`, `timeout`, HTTP 429, HTTP 5xx and the
+ * `idempotency_in_progress` code — retry with the SAME idempotency key.
+ * @public
+ */
+declare class SekyroApiError extends Error {
+    readonly name = "SekyroApiError";
+    readonly status: number;
+    readonly code: string;
+    readonly requestId: string | undefined;
+    readonly retryable: boolean;
+    constructor(init: SekyroApiErrorInit);
+}
+
+/**
+ * The HTTP header carrying the webhook signature:
+ * `t=<unix seconds>,v1=<hex>[,v1=<hex>]`.
+ * @public
+ */
+declare const SEKYRO_SIGNATURE_HEADER = "x-sekyro-signature";
+/**
+ * The pre-rebrand name of the signature header. Sekyro sends BOTH headers with
+ * the same value during the transition; prefer {@link SEKYRO_SIGNATURE_HEADER}
+ * and use {@link signatureFromHeaders} to accept either.
+ * @public
+ */
+declare const LEGACY_SIGNATURE_HEADER = "x-ibtikar-signature";
+/**
+ * Pick the signature header out of an incoming request's headers: the
+ * `x-sekyro-signature` value when present, else the legacy
+ * `x-ibtikar-signature`, else `undefined`. Accepts a Fetch `Headers` object or
+ * a Node-style plain record (lower- or mixed-case keys; a multi-valued header
+ * yields its first value).
+ *
+ * @example
+ * ```ts
+ * verifyWebhook(rawBody, signatureFromHeaders(req.headers), secret);
+ * ```
+ * @public
+ */
+declare function signatureFromHeaders(headers: Headers | Record<string, string | string[] | undefined>): string | undefined;
+/** Options of {@link verifyWebhook}. @public */
+interface VerifyWebhookOptions {
+    /** Max |now − t| in seconds before a delivery is rejected as `stale`. Default 300. */
+    toleranceSec?: number;
+    /** Clock returning epoch milliseconds. Default `Date.now`. */
+    now?: () => number;
+}
+/**
+ * Verify a Sekyro 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).
+ * - Uses `node:crypto` only; the digest compare is constant-time.
+ *
+ * Checks run in this order: header/secret present → header well-formed →
+ * timestamp within tolerance → signature → body is a JSON object.
+ *
+ * @param rawBody - The raw UTF-8 request body.
+ * @param header - The `x-sekyro-signature` header value (or the legacy
+ *   `x-ibtikar-signature` — same format; see {@link signatureFromHeaders}).
+ * @param secret - The endpoint secret you hold (current or previous).
+ * @throws {@link SekyroWebhookError} with `code` `invalid_signature` | `stale` | `malformed`.
+ * @public
+ */
+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 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 };