@nimbusnexus/webhooks-sdk 0.1.1 → 0.3.0

package/dist/index.d.ts

@@ -1,3 +1,6 @@
+import { Pool } from 'pg';
+import { createClient } from 'redis';
+
 declare const DEFAULT_TOLERANCE_SECONDS = 300;
 /** The `sha256=<hex>` signature webhookd would send for `rawBody` (+ optional timestamp). */
 declare function sign(secret: string | Buffer, rawBody: string | Buffer, timestamp?: number | null): string;
@@ -17,6 +20,171 @@ interface VerifyOptions {
  */
 declare function verify(secret: string | Buffer, rawBody: string | Buffer, signature: string, opts?: VerifyOptions): boolean;
 
+/**
+ * Redis-backed {@link Store}. Durable ordering via a sorted set scored on `nextAttemptAt` (for due
+ * filtering) plus a hash of record bodies keyed by id. The `redis` driver is an OPTIONAL dependency,
+ * imported lazily inside {@link RedisStore.ensure} — the SDK core stays zero-runtime-dependency and
+ * importing this module never pulls in `redis` unless you actually construct the store.
+ */
+
+type RedisClient = ReturnType<typeof createClient>;
+interface RedisStoreOptions {
+    /** Redis connection URL, e.g. `redis://localhost:6379`. Ignored if `client` is supplied. */
+    url?: string;
+    /** Reuse an already-created (not necessarily connected) `redis` client instead of `url`. */
+    client?: RedisClient;
+    /** Namespace for the two keys this store uses. Default `webhookd:outbox`. */
+    keyPrefix?: string;
+}
+declare class RedisStore implements Store {
+    private readonly url?;
+    private readonly keyPrefix;
+    private client;
+    private connecting;
+    constructor(opts?: RedisStoreOptions);
+    private get zsetKey();
+    private get hashKey();
+    /** Lazily import the driver + connect exactly once. */
+    private ensure;
+    save(record: OutboxRecord): Promise<void>;
+    listPending(limit: number): Promise<OutboxRecord[]>;
+    markSent(id: string): Promise<void>;
+    markFailed(id: string, error: string, attempts: number, nextAttemptAt: number): Promise<void>;
+    size(): Promise<number>;
+    listDead(limit?: number): Promise<OutboxRecord[]>;
+    close(): Promise<void>;
+    /** Load records for `ids` from the hash, drop any missing, sort oldest-first, cap at `limit`. */
+    private loadSorted;
+}
+
+/**
+ * Postgres-backed {@link Store}. A single `webhookd_outbox` table with a `sent` flag; upsert on `id`;
+ * pending = `WHERE NOT sent AND next_attempt_at <= now`. The `pg` driver is an OPTIONAL dependency,
+ * imported lazily inside {@link PostgresStore.ensure} — importing this module never pulls in `pg`
+ * unless you actually construct the store.
+ */
+
+interface PostgresStoreOptions {
+    /** Postgres connection string, e.g. `postgres://user:pass@host:5432/db`. Ignored if `pool` is given. */
+    connectionString?: string;
+    /** Reuse an existing `pg` Pool instead of `connectionString`. */
+    pool?: Pool;
+    /** Table name (must be a plain identifier). Default `webhookd_outbox`. */
+    table?: string;
+}
+declare class PostgresStore implements Store {
+    private readonly connectionString?;
+    private readonly table;
+    private pool;
+    private ready;
+    constructor(opts?: PostgresStoreOptions);
+    /** Lazily import the driver, open the pool, and create the table exactly once. */
+    private ensure;
+    save(record: OutboxRecord): Promise<void>;
+    listPending(limit: number): Promise<OutboxRecord[]>;
+    markSent(id: string): Promise<void>;
+    markFailed(id: string, error: string, attempts: number, nextAttemptAt: number): Promise<void>;
+    size(): Promise<number>;
+    listDead(limit?: number): Promise<OutboxRecord[]>;
+    close(): Promise<void>;
+}
+
+/**
+ * A sentinel `nextAttemptAt` (JS max timestamp) used to park a record that has exhausted its retry
+ * budget. It is never `<= now`, so {@link Store.listPending} never returns it again — the record
+ * stays durably in the store, flagged dead, retrievable via {@link Store.listDead}.
+ */
+declare const DEAD_NEXT_ATTEMPT_MS = 8640000000000000;
+/**
+ * A single buffered event. `id` doubles as the webhookd `Idempotency-Key`, so re-saving the same
+ * `id` (an idempotent enqueue) simply overwrites, and re-draining after a crash never double-sends.
+ * Timestamps are epoch milliseconds.
+ */
+interface OutboxRecord {
+    /** The Idempotency-Key — caller-supplied or a generated UUID v4. */
+    id: string;
+    eventType: string;
+    payload: Record<string, unknown>;
+    environment: string;
+    application: string;
+    source: string | null;
+    /** Epoch ms the record was first enqueued; `listPending` orders by this, oldest first. */
+    createdAt: number;
+    /** Delivery attempts made so far; starts at 0. */
+    attempts: number;
+    lastError: string | null;
+    /** Epoch ms the record next becomes due; initially `now`. `DEAD_NEXT_ATTEMPT_MS` when dead. */
+    nextAttemptAt: number;
+}
+/** Whether a record has been parked as dead (retry budget exhausted). */
+declare function isDead(record: OutboxRecord): boolean;
+/**
+ * A durable buffer of pending events. Implementations may be sync or async; every method returns a
+ * value or a promise, and callers always `await`. Built-ins: {@link MemoryStore}, {@link FileStore},
+ * {@link SqliteStore}, and (optional-dep) `RedisStore` / `PostgresStore`.
+ */
+interface Store {
+    /** Insert-or-update by `record.id`. Idempotent: the same id overwrites, so enqueue is safe to repeat. */
+    save(record: OutboxRecord): void | Promise<void>;
+    /** Records not yet sent whose `nextAttemptAt <= now`, oldest first (by `createdAt`), capped at `limit`. */
+    listPending(limit: number): OutboxRecord[] | Promise<OutboxRecord[]>;
+    /** Remove (or flag sent) a record after a 2xx. */
+    markSent(id: string): void | Promise<void>;
+    /** Persist a failure + schedule the next retry (or park it dead via `DEAD_NEXT_ATTEMPT_MS`). */
+    markFailed(id: string, error: string, attempts: number, nextAttemptAt: number): void | Promise<void>;
+    /** Count of records still in the store (i.e. not yet sent), dead ones included. */
+    size(): number | Promise<number>;
+    /** Records parked dead, oldest first. */
+    listDead(limit?: number): OutboxRecord[] | Promise<OutboxRecord[]>;
+    /** Release any resources (file handles, DB connections, timers). */
+    close(): void | Promise<void>;
+}
+/** In-process, non-durable store. The default for tests and single-process best-effort buffering. */
+declare class MemoryStore implements Store {
+    private readonly records;
+    save(record: OutboxRecord): void;
+    listPending(limit: number): OutboxRecord[];
+    markSent(id: string): void;
+    markFailed(id: string, error: string, attempts: number, nextAttemptAt: number): void;
+    size(): number;
+    listDead(limit?: number): OutboxRecord[];
+    close(): void;
+}
+/**
+ * Durable store backed by a directory of per-record JSON files with atomic writes (write-tmp +
+ * rename). Survives process restarts. `markSent` unlinks the file. Suitable for a single process; it
+ * does not coordinate concurrent drainers across processes.
+ */
+declare class FileStore implements Store {
+    private readonly dir;
+    constructor(dir: string);
+    /** Map an arbitrary id to a safe filename (ids may be caller-supplied idempotency keys). */
+    private pathFor;
+    private readAll;
+    save(record: OutboxRecord): void;
+    listPending(limit: number): OutboxRecord[];
+    markSent(id: string): void;
+    markFailed(id: string, error: string, attempts: number, nextAttemptAt: number): void;
+    size(): number;
+    listDead(limit?: number): OutboxRecord[];
+    close(): void;
+}
+/**
+ * Durable, transactional store on the built-in `node:sqlite` (Node >= 22.5 — no native dependency).
+ * `markSent` deletes the row. Pass a file path to persist across restarts, or `":memory:"` for tests.
+ */
+declare class SqliteStore implements Store {
+    private readonly db;
+    constructor(path?: string);
+    save(record: OutboxRecord): void;
+    listPending(limit: number): OutboxRecord[];
+    markSent(id: string): void;
+    markFailed(id: string, error: string, attempts: number, nextAttemptAt: number): void;
+    size(): number;
+    listDead(limit?: number): OutboxRecord[];
+    close(): void;
+}
+
 /** The published event, as returned by `POST /v1/events` (webhookd's `EventOut`). */
 interface WebhookdEvent {
     id: string;
@@ -27,6 +195,62 @@ interface WebhookdEvent {
     deliveriesCreated: number;
     source: string | null;
 }
+/** A subscription filter attached to an endpoint. */
+interface Subscription {
+    match_kind: "exact" | "prefix" | "suffix" | "all";
+    pattern: string;
+}
+/**
+ * An endpoint, as returned by the management endpoints (webhookd's `EndpointOut`).
+ * Fields mirror the server's snake_case wire shape verbatim. `secret` is present ONLY on the
+ * create + rotate-secret responses (returned exactly once).
+ */
+interface Endpoint {
+    id: string;
+    url: string;
+    environment: string;
+    application: string;
+    status: string;
+    subscriptions: Subscription[];
+    /** The signing secret — returned ONCE, on create + rotate-secret only. */
+    secret?: string;
+    max_attempts?: number;
+    retry_schedule?: number[];
+    description?: string | null;
+    custom_headers?: Record<string, string> | null;
+    delivery_timeout_ms?: number | null;
+    created_at?: string;
+    updated_at?: string;
+}
+/**
+ * An API key, as returned by `POST /v1/api-keys` (webhookd's `ApiKeyOut`). `key` is present ONLY on
+ * the create response (returned exactly once).
+ */
+interface ApiKey {
+    id: string;
+    name: string;
+    scope: string;
+    /** The raw key — returned ONCE, on create only. */
+    key?: string;
+    created_at?: string;
+    expires_at?: string | null;
+}
+/** A delivery attempt record, as returned by the deliveries endpoints (webhookd's `DeliveryOut`). */
+interface Delivery {
+    id: string;
+    endpoint_id: string;
+    event_id?: string;
+    event_type?: string;
+    status: string;
+    attempts?: number;
+    created_at?: string;
+    updated_at?: string;
+}
+/** A single page of a list endpoint — items plus the cursor for the next page (`null` at the end). */
+interface Page<T> {
+    items: T[];
+    next_offset: number | null;
+}
 interface ClientOptions {
     baseUrl: string;
     /** A per-tenant API key (`whsk_…`) or a service token. */
@@ -35,6 +259,40 @@ interface ClientOptions {
     maxRetries?: number;
     /** Inject a `fetch` implementation (defaults to the global `fetch`); used for tests. */
     fetchImpl?: typeof fetch;
+    /**
+     * Durable outbox store. When set, {@link WebhookdClient.enqueue} / {@link WebhookdClient.drain}
+     * (and the background drainer) become available. Omit to use only the live {@link WebhookdClient.publish}.
+     */
+    store?: Store;
+    /** Max delivery attempts before a record is parked dead (default 10). */
+    maxAttempts?: number;
+    /** How many records a single {@link WebhookdClient.drain} pulls from the store (default 100). */
+    drainBatchLimit?: number;
+    /** Invoked once when `drain` parks a record dead (retry budget exhausted). */
+    onDead?: (record: OutboxRecord) => void;
+    /** Invoked when a background-drainer tick throws (a foreground `drain` still rejects normally). */
+    onDrainError?: (error: unknown) => void;
+}
+interface EnqueueOptions {
+    environment?: string;
+    application?: string;
+    source?: string;
+    /** The Idempotency-Key / record id. Defaults to a generated UUID v4. Re-enqueuing the same key is a no-op overwrite. */
+    idempotencyKey?: string;
+}
+interface DrainOptions {
+    /** Override the client's `drainBatchLimit` for this call. */
+    batchLimit?: number;
+    /** Override the client's `maxAttempts` for this call. */
+    maxAttempts?: number;
+}
+interface DrainResult {
+    /** Records delivered (2xx) and marked sent this drain. */
+    sent: number;
+    /** Records that failed this drain (rescheduled or newly parked dead). */
+    failed: number;
+    /** Records still buffered in the store afterwards (`store.size()`). */
+    remaining: number;
 }
 interface PublishOptions {
     environment?: string;
@@ -43,15 +301,124 @@ interface PublishOptions {
     /** Makes the publish safe to retry — a replay returns the original event without re-fanning-out. */
     idempotencyKey?: string;
 }
+interface CreateEndpointOptions {
+    environment?: string;
+    subscriptions?: Subscription[];
+    application?: string;
+    secret?: string;
+    maxAttempts?: number;
+    retrySchedule?: number[];
+    description?: string;
+    customHeaders?: Record<string, string>;
+    deliveryTimeoutMs?: number;
+}
+interface ListEndpointsOptions {
+    environment?: string;
+    offset?: number;
+    limit?: number;
+}
+/**
+ * A raw PATCH mapping for `updateEndpoint`, keyed with the server's snake_case names. PATCH semantics:
+ * an OMITTED key is left unchanged; an explicit `null` CLEARS the field. The object is sent verbatim.
+ */
+interface EndpointPatch {
+    url?: string;
+    max_attempts?: number | null;
+    retry_schedule?: number[] | null;
+    status?: "enabled" | "disabled";
+    description?: string | null;
+    custom_headers?: Record<string, string> | null;
+    delivery_timeout_ms?: number | null;
+}
+interface CreateApiKeyOptions {
+    name?: string;
+    scope?: "admin" | "publish";
+    expiresInDays?: number;
+}
+interface ListDeliveriesOptions {
+    status?: "queued" | "sending" | "sent" | "failed" | "dead";
+    endpointId?: string;
+    eventType?: string;
+    since?: string | number;
+    until?: string | number;
+    q?: string;
+    offset?: number;
+    limit?: number;
+}
 declare class WebhookdClient {
     private readonly baseUrl;
     private readonly apiKey;
     private readonly timeoutMs;
     private readonly maxRetries;
     private readonly fetchImpl;
+    private readonly store?;
+    private readonly maxAttempts;
+    private readonly drainBatchLimit;
+    private readonly onDead?;
+    private readonly onDrainError?;
+    private drainTimer?;
+    private draining;
     constructor(opts: ClientOptions);
     publish(eventType: string, payload: Record<string, unknown>, opts?: PublishOptions): Promise<WebhookdEvent>;
-    private post;
+    /**
+     * Durably buffer an event and return IMMEDIATELY — NO network call. Builds an {@link OutboxRecord}
+     * (id = `opts.idempotencyKey` or a fresh UUID v4), saves it to the configured store, and returns the
+     * id. Ship it later with {@link drain} (or the background drainer). Requires a `store` in options.
+     */
+    enqueue(eventType: string, payload: Record<string, unknown>, opts?: EnqueueOptions): Promise<{
+        id: string;
+    }>;
+    /**
+     * Send buffered records to webhookd. Pulls a due batch (oldest first), POSTs each to `/v1/events`
+     * with header `Idempotency-Key = record.id` (so a re-drain after a crash never double-publishes —
+     * webhookd dedupes). On 2xx the record is marked sent; on error `attempts` is bumped and the record
+     * is rescheduled with capped exponential backoff, or parked dead once it hits `maxAttempts` (the
+     * `onDead` hook fires, and it is retrievable via `store.listDead()`). Requires a `store`.
+     */
+    drain(opts?: DrainOptions): Promise<DrainResult>;
+    /**
+     * Start a background loop calling {@link drain} every `intervalSeconds`. Overlapping ticks are
+     * skipped while a drain is in flight, and a tick that throws is swallowed (routed to `onDrainError`)
+     * so the loop keeps running. The timer is `unref`'d so it never blocks process exit. Idempotent.
+     */
+    startDrainer(intervalSeconds: number): void;
+    /** Stop the background drainer started by {@link startDrainer}. Safe to call when not running. */
+    stopDrainer(): void;
+    private drainTick;
+    private requireStore;
+    /** Create an endpoint. The response includes the signing `secret` exactly once — persist it. */
+    createEndpoint(url: string, opts?: CreateEndpointOptions): Promise<Endpoint>;
+    /** List endpoints for an environment (defaults to `prod`). */
+    listEndpoints(opts?: ListEndpointsOptions): Promise<Page<Endpoint>>;
+    /** Fetch a single endpoint by id. */
+    getEndpoint(id: string): Promise<Endpoint>;
+    /**
+     * Partially update an endpoint. `patch` is sent verbatim (snake_case keys): an omitted key is left
+     * unchanged, an explicit `null` clears the field. No defaults are injected.
+     */
+    updateEndpoint(id: string, patch: EndpointPatch): Promise<Endpoint>;
+    /** Delete an endpoint. Returns nothing (the server replies `204 No Content`). */
+    deleteEndpoint(id: string): Promise<void>;
+    /** Rotate an endpoint's signing secret. The response includes the new `secret` exactly once. */
+    rotateEndpointSecret(id: string): Promise<Endpoint>;
+    /** Re-enable an endpoint that webhookd auto-disabled after repeated delivery failures. */
+    enableEndpoint(id: string): Promise<Endpoint>;
+    /** Create an API key. The response includes the raw `key` exactly once — persist it. */
+    createApiKey(opts?: CreateApiKeyOptions): Promise<ApiKey>;
+    /** Revoke an API key. Returns nothing (the server replies `204 No Content`). */
+    revokeApiKey(id: string): Promise<void>;
+    /** List deliveries. Only the filters you provide are sent as query params. */
+    listDeliveries(opts?: ListDeliveriesOptions): Promise<Page<Delivery>>;
+    /** Re-queue a delivery for another attempt. */
+    redeliver(deliveryId: string): Promise<Delivery>;
+    /** Issue a request and parse the JSON response as `T`. Never use for 204s (there's no body). */
+    private requestJson;
+    /**
+     * The single request path used by every method: builds the URL (+ query), attaches auth, and runs
+     * the shared retry loop (connection errors + 429 honoring Retry-After + 5xx, capped exponential
+     * backoff), raising a typed {@link WebhookdApiError} on other 4xx/5xx. The caller reads the body.
+     */
+    private request;
 }
 
 /** Base class for all webhookd SDK errors (network failures, etc.). */
@@ -76,6 +443,6 @@ declare class WebhookdApiError extends WebhookdError {
  * - `WebhookdClient` — publish events to webhookd (for producers).
  */
 
-declare const VERSION = "0.1.0";
+declare const VERSION = "0.3.0";
 
-export { type ClientOptions, DEFAULT_TOLERANCE_SECONDS, type PublishOptions, VERSION, type VerifyOptions, WebhookdApiError, WebhookdClient, WebhookdError, type WebhookdEvent, sign, verify };
+export { type ApiKey, type ClientOptions, type CreateApiKeyOptions, type CreateEndpointOptions, DEAD_NEXT_ATTEMPT_MS, DEFAULT_TOLERANCE_SECONDS, type Delivery, type DrainOptions, type DrainResult, type Endpoint, type EndpointPatch, type EnqueueOptions, FileStore, type ListDeliveriesOptions, type ListEndpointsOptions, MemoryStore, type OutboxRecord, type Page, PostgresStore, type PostgresStoreOptions, type PublishOptions, RedisStore, type RedisStoreOptions, SqliteStore, type Store, type Subscription, VERSION, type VerifyOptions, WebhookdApiError, WebhookdClient, WebhookdError, type WebhookdEvent, isDead, sign, verify };