@nimbusnexus/webhooks-sdk 0.2.0 → 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;
@@ -91,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;
@@ -149,8 +351,41 @@ declare class WebhookdClient {
     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>;
+    /**
+     * 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`). */
@@ -208,6 +443,6 @@ declare class WebhookdApiError extends WebhookdError {
  * - `WebhookdClient` — publish events to webhookd (for producers).
  */
 
-declare const VERSION = "0.2.0";
+declare const VERSION = "0.3.0";
 
-export { type ApiKey, type ClientOptions, type CreateApiKeyOptions, type CreateEndpointOptions, DEFAULT_TOLERANCE_SECONDS, type Delivery, type Endpoint, type EndpointPatch, type ListDeliveriesOptions, type ListEndpointsOptions, type Page, type PublishOptions, type Subscription, 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 };