@nimbusnexus/webhooks-sdk 0.2.0 → 0.3.0

package/README.md

@@ -44,6 +44,59 @@ try {
 Transient failures (network errors, `429`, `5xx`) are retried with backoff (a `429` honours
 `Retry-After`); other `4xx` throw `WebhookdApiError` carrying the `{error:{code,message}}` envelope.
 
+## Outbox / durable buffering (producers)
+
+`publish()` calls webhookd synchronously — if webhookd is unreachable it rejects and the event is
+lost. The **write-first outbox** decouples the two: `enqueue()` durably persists the event to a
+pluggable `Store` and resolves IMMEDIATELY (no network); `drain()` (or a background drainer) ships the
+buffered events later. Every send carries `Idempotency-Key = record.id`, so a re-drain after a crash
+or a lost response never double-publishes — webhookd dedupes. Delivery is **at-least-once**: nothing
+is lost while webhookd is down.
+
+```ts
+import { WebhookdClient, SqliteStore } from "@nimbusnexus/webhooks-sdk";
+
+// 1. Configure a durable store (survives process restarts; needs Node >= 22.5 for node:sqlite).
+const store = new SqliteStore("outbox.db");
+
+const wh = new WebhookdClient({
+  baseUrl: "https://webhooks.example.com",
+  apiKey: "whsk_…",
+  store,
+});
+
+// 2. enqueue() instead of publish() — writes to the store and resolves at once, NO network call.
+const { id } = await wh.enqueue("order.created", { orderId: "ord_123", total: 4200 });
+
+// 3a. Drain on demand (resolves to { sent, failed, remaining }):
+await wh.drain();
+
+// 3b. …or run a background drainer that calls drain() every 5s until you stop it.
+wh.startDrainer(5);
+// ... your app keeps enqueuing; the drainer ships in the background ...
+wh.stopDrainer();
+```
+
+**Idempotency guarantee.** `id` is the `idempotencyKey` you pass (or a generated UUID v4) and becomes
+the `Idempotency-Key` header on every delivery attempt for that record. If the process crashes after
+a send but before the response is recorded, the next `drain()` re-sends with the *same* key and
+webhookd returns the original event without re-fanning-out. A record that keeps failing is retried
+with capped exponential backoff up to `maxAttempts` (default 10), then parked **dead** (never retried
+again, retrievable via `store.listDead()`) and passed to the optional `onDead` callback.
+
+**Built-in stores** — pass one as `store` in `ClientOptions`:
+
+| Store | Durable? | Extra needed |
+| --- | --- | --- |
+| `MemoryStore` | No (in-process) | — (built-in) |
+| `FileStore(dir)` | Yes (per-record JSON files) | — (built-in) |
+| `SqliteStore(path)` | Yes (transactional) | — (built-in `node:sqlite`, Node ≥ 22.5) |
+| `RedisStore({ url })` | Yes | `npm install redis` |
+| `PostgresStore({ connectionString })` | Yes | `npm install pg` |
+
+The core SDK stays zero-dependency; `redis` / `pg` are `optionalDependencies`, imported lazily only
+when you construct `RedisStore` / `PostgresStore`.
+
 ## Manage endpoints, keys & deliveries (operators)
 
 The same client wraps the control-plane API — register receivers, mint keys, and drain the

package/dist/index.cjs

@@ -1,7 +1,9 @@
 "use strict";
+var __create = Object.create;
 var __defProp = Object.defineProperty;
 var __getOwnPropDesc = Object.getOwnPropertyDescriptor;
 var __getOwnPropNames = Object.getOwnPropertyNames;
+var __getProtoOf = Object.getPrototypeOf;
 var __hasOwnProp = Object.prototype.hasOwnProperty;
 var __export = (target, all) => {
   for (var name in all)
@@ -15,16 +17,31 @@ var __copyProps = (to, from, except, desc) => {
   }
   return to;
 };
+var __toESM = (mod, isNodeMode, target) => (target = mod != null ? __create(__getProtoOf(mod)) : {}, __copyProps(
+  // If the importer is in node compatibility mode or this is not an ESM
+  // file that has been converted to a CommonJS file using a Babel-
+  // compatible transform (i.e. "__esModule" has not been set), then set
+  // "default" to the CommonJS "module.exports" for node compatibility.
+  isNodeMode || !mod || !mod.__esModule ? __defProp(target, "default", { value: mod, enumerable: true }) : target,
+  mod
+));
 var __toCommonJS = (mod) => __copyProps(__defProp({}, "__esModule", { value: true }), mod);
 
 // src/index.ts
 var src_exports = {};
 __export(src_exports, {
+  DEAD_NEXT_ATTEMPT_MS: () => DEAD_NEXT_ATTEMPT_MS,
   DEFAULT_TOLERANCE_SECONDS: () => DEFAULT_TOLERANCE_SECONDS,
+  FileStore: () => FileStore,
+  MemoryStore: () => MemoryStore,
+  PostgresStore: () => PostgresStore,
+  RedisStore: () => RedisStore,
+  SqliteStore: () => SqliteStore,
   VERSION: () => VERSION,
   WebhookdApiError: () => WebhookdApiError,
   WebhookdClient: () => WebhookdClient,
   WebhookdError: () => WebhookdError,
+  isDead: () => isDead,
   sign: () => sign,
   verify: () => verify
 });
@@ -62,6 +79,9 @@ function verify(secret, rawBody, signature, opts = {}) {
   return false;
 }
 
+// src/client.ts
+var import_node_crypto3 = require("crypto");
+
 // src/errors.ts
 var WebhookdError = class extends Error {
   constructor(message) {
@@ -80,6 +100,443 @@ var WebhookdApiError = class extends WebhookdError {
   }
 };
 
+// src/outbox.ts
+var import_node_fs = require("fs");
+var import_node_path = require("path");
+var import_node_crypto2 = require("crypto");
+var import_node_module = require("module");
+
+// src/stores/redis.ts
+function byCreatedAt(a, b) {
+  return a.createdAt - b.createdAt || (a.id < b.id ? -1 : a.id > b.id ? 1 : 0);
+}
+var RedisStore = class {
+  url;
+  keyPrefix;
+  client;
+  connecting;
+  constructor(opts = {}) {
+    this.url = opts.url;
+    this.client = opts.client;
+    this.keyPrefix = opts.keyPrefix ?? "webhookd:outbox";
+  }
+  get zsetKey() {
+    return `${this.keyPrefix}:due`;
+  }
+  get hashKey() {
+    return `${this.keyPrefix}:records`;
+  }
+  /** Lazily import the driver + connect exactly once. */
+  async ensure() {
+    if (this.client && this.client.isOpen) return this.client;
+    if (this.connecting) return this.connecting;
+    this.connecting = (async () => {
+      if (!this.client) {
+        const { createClient: create } = await import("redis");
+        this.client = create({ url: this.url });
+      }
+      if (!this.client.isOpen) await this.client.connect();
+      return this.client;
+    })();
+    try {
+      return await this.connecting;
+    } finally {
+      this.connecting = void 0;
+    }
+  }
+  async save(record) {
+    const client = await this.ensure();
+    await client.hSet(this.hashKey, record.id, JSON.stringify(record));
+    await client.zAdd(this.zsetKey, { score: record.nextAttemptAt, value: record.id });
+  }
+  async listPending(limit) {
+    const client = await this.ensure();
+    const ids = await client.zRangeByScore(this.zsetKey, "-inf", Date.now());
+    return this.loadSorted(client, ids, limit);
+  }
+  async markSent(id) {
+    const client = await this.ensure();
+    await client.hDel(this.hashKey, id);
+    await client.zRem(this.zsetKey, id);
+  }
+  async markFailed(id, error, attempts, nextAttemptAt) {
+    const client = await this.ensure();
+    const raw = await client.hGet(this.hashKey, id);
+    if (raw === void 0 || raw === null) return;
+    const record = JSON.parse(raw);
+    record.attempts = attempts;
+    record.lastError = error;
+    record.nextAttemptAt = nextAttemptAt;
+    await client.hSet(this.hashKey, id, JSON.stringify(record));
+    await client.zAdd(this.zsetKey, { score: nextAttemptAt, value: id });
+  }
+  async size() {
+    const client = await this.ensure();
+    return client.hLen(this.hashKey);
+  }
+  async listDead(limit) {
+    const client = await this.ensure();
+    const ids = await client.zRangeByScore(this.zsetKey, DEAD_NEXT_ATTEMPT_MS, "+inf");
+    const dead = (await this.loadSorted(client, ids, ids.length)).filter(isDead);
+    return limit === void 0 ? dead : dead.slice(0, limit);
+  }
+  async close() {
+    if (this.client && this.client.isOpen) await this.client.close();
+  }
+  /** Load records for `ids` from the hash, drop any missing, sort oldest-first, cap at `limit`. */
+  async loadSorted(client, ids, limit) {
+    const records = [];
+    for (const id of ids) {
+      const raw = await client.hGet(this.hashKey, id);
+      if (raw === void 0 || raw === null) continue;
+      records.push(cloneRecord(JSON.parse(raw)));
+    }
+    return records.sort(byCreatedAt).slice(0, limit);
+  }
+};
+
+// src/stores/postgres.ts
+function rowToRecord(row) {
+  return {
+    id: row.id,
+    eventType: row.event_type,
+    payload: row.payload,
+    environment: row.environment,
+    application: row.application,
+    source: row.source,
+    createdAt: Number(row.created_at),
+    attempts: row.attempts,
+    lastError: row.last_error,
+    nextAttemptAt: Number(row.next_attempt_at)
+  };
+}
+var PostgresStore = class {
+  connectionString;
+  table;
+  pool;
+  ready;
+  constructor(opts = {}) {
+    this.connectionString = opts.connectionString;
+    this.pool = opts.pool;
+    const table = opts.table ?? "webhookd_outbox";
+    if (!/^[A-Za-z_][A-Za-z0-9_]*$/.test(table)) {
+      throw new Error(`invalid table name: ${table}`);
+    }
+    this.table = table;
+  }
+  /** Lazily import the driver, open the pool, and create the table exactly once. */
+  async ensure() {
+    if (this.ready) return this.ready;
+    this.ready = (async () => {
+      if (!this.pool) {
+        const pg = await import("pg");
+        const Pool = pg.Pool ?? pg.default?.Pool;
+        if (!Pool) throw new Error("pg: could not resolve Pool export");
+        this.pool = new Pool({ connectionString: this.connectionString });
+      }
+      await this.pool.query(
+        `CREATE TABLE IF NOT EXISTS ${this.table} (
+          id TEXT PRIMARY KEY,
+          event_type TEXT NOT NULL,
+          payload JSONB NOT NULL,
+          environment TEXT NOT NULL,
+          application TEXT NOT NULL,
+          source TEXT,
+          sent BOOLEAN NOT NULL DEFAULT FALSE,
+          attempts INTEGER NOT NULL,
+          last_error TEXT,
+          next_attempt_at BIGINT NOT NULL,
+          created_at BIGINT NOT NULL
+        )`
+      );
+      return this.pool;
+    })();
+    return this.ready;
+  }
+  async save(record) {
+    const pool = await this.ensure();
+    await pool.query(
+      `INSERT INTO ${this.table}
+        (id, event_type, payload, environment, application, source, sent, attempts, last_error, next_attempt_at, created_at)
+       VALUES ($1, $2, $3, $4, $5, $6, FALSE, $7, $8, $9, $10)
+       ON CONFLICT (id) DO UPDATE SET
+         event_type = EXCLUDED.event_type,
+         payload = EXCLUDED.payload,
+         environment = EXCLUDED.environment,
+         application = EXCLUDED.application,
+         source = EXCLUDED.source,
+         sent = EXCLUDED.sent,
+         attempts = EXCLUDED.attempts,
+         last_error = EXCLUDED.last_error,
+         next_attempt_at = EXCLUDED.next_attempt_at,
+         created_at = EXCLUDED.created_at`,
+      [
+        record.id,
+        record.eventType,
+        JSON.stringify(record.payload),
+        record.environment,
+        record.application,
+        record.source,
+        record.attempts,
+        record.lastError,
+        record.nextAttemptAt,
+        record.createdAt
+      ]
+    );
+  }
+  async listPending(limit) {
+    const pool = await this.ensure();
+    const res = await pool.query(
+      `SELECT * FROM ${this.table}
+       WHERE NOT sent AND next_attempt_at <= $1 AND next_attempt_at < $2
+       ORDER BY created_at ASC, id ASC
+       LIMIT $3`,
+      [Date.now(), DEAD_NEXT_ATTEMPT_MS, limit]
+    );
+    return res.rows.map(rowToRecord);
+  }
+  async markSent(id) {
+    const pool = await this.ensure();
+    await pool.query(`UPDATE ${this.table} SET sent = TRUE WHERE id = $1`, [id]);
+  }
+  async markFailed(id, error, attempts, nextAttemptAt) {
+    const pool = await this.ensure();
+    await pool.query(
+      `UPDATE ${this.table} SET attempts = $2, last_error = $3, next_attempt_at = $4 WHERE id = $1`,
+      [id, attempts, error, nextAttemptAt]
+    );
+  }
+  async size() {
+    const pool = await this.ensure();
+    const res = await pool.query(
+      `SELECT COUNT(*) AS n FROM ${this.table} WHERE NOT sent`
+    );
+    return Number(res.rows[0].n);
+  }
+  async listDead(limit) {
+    const pool = await this.ensure();
+    const res = await pool.query(
+      `SELECT * FROM ${this.table}
+       WHERE NOT sent AND next_attempt_at >= $1
+       ORDER BY created_at ASC, id ASC
+       ${limit === void 0 ? "" : "LIMIT $2"}`,
+      limit === void 0 ? [DEAD_NEXT_ATTEMPT_MS] : [DEAD_NEXT_ATTEMPT_MS, limit]
+    );
+    return res.rows.map(rowToRecord);
+  }
+  async close() {
+    if (this.pool) await this.pool.end();
+  }
+};
+
+// src/outbox.ts
+var import_meta = {};
+var DEAD_NEXT_ATTEMPT_MS = 864e13;
+function isDead(record) {
+  return record.nextAttemptAt >= DEAD_NEXT_ATTEMPT_MS;
+}
+function cloneRecord(record) {
+  return { ...record, payload: structuredClone(record.payload) };
+}
+function byCreatedAt2(a, b) {
+  return a.createdAt - b.createdAt || (a.id < b.id ? -1 : a.id > b.id ? 1 : 0);
+}
+var MemoryStore = class {
+  records = /* @__PURE__ */ new Map();
+  save(record) {
+    this.records.set(record.id, cloneRecord(record));
+  }
+  listPending(limit) {
+    const now = Date.now();
+    return [...this.records.values()].filter((r) => r.nextAttemptAt <= now).sort(byCreatedAt2).slice(0, limit).map(cloneRecord);
+  }
+  markSent(id) {
+    this.records.delete(id);
+  }
+  markFailed(id, error, attempts, nextAttemptAt) {
+    const record = this.records.get(id);
+    if (!record) return;
+    record.attempts = attempts;
+    record.lastError = error;
+    record.nextAttemptAt = nextAttemptAt;
+  }
+  size() {
+    return this.records.size;
+  }
+  listDead(limit) {
+    const dead = [...this.records.values()].filter(isDead).sort(byCreatedAt2).map(cloneRecord);
+    return limit === void 0 ? dead : dead.slice(0, limit);
+  }
+  close() {
+    this.records.clear();
+  }
+};
+var FileStore = class {
+  dir;
+  constructor(dir) {
+    this.dir = dir;
+    (0, import_node_fs.mkdirSync)(dir, { recursive: true });
+  }
+  /** Map an arbitrary id to a safe filename (ids may be caller-supplied idempotency keys). */
+  pathFor(id) {
+    return (0, import_node_path.join)(this.dir, `${encodeURIComponent(id)}.json`);
+  }
+  readAll() {
+    const out = [];
+    for (const name of (0, import_node_fs.readdirSync)(this.dir)) {
+      if (!name.endsWith(".json")) continue;
+      try {
+        out.push(JSON.parse((0, import_node_fs.readFileSync)((0, import_node_path.join)(this.dir, name), "utf8")));
+      } catch {
+      }
+    }
+    return out;
+  }
+  save(record) {
+    const dest = this.pathFor(record.id);
+    const tmp = `${dest}.tmp-${(0, import_node_crypto2.randomBytes)(6).toString("hex")}`;
+    (0, import_node_fs.writeFileSync)(tmp, JSON.stringify(record), "utf8");
+    (0, import_node_fs.renameSync)(tmp, dest);
+  }
+  listPending(limit) {
+    const now = Date.now();
+    return this.readAll().filter((r) => r.nextAttemptAt <= now).sort(byCreatedAt2).slice(0, limit);
+  }
+  markSent(id) {
+    (0, import_node_fs.rmSync)(this.pathFor(id), { force: true });
+  }
+  markFailed(id, error, attempts, nextAttemptAt) {
+    let record;
+    try {
+      record = JSON.parse((0, import_node_fs.readFileSync)(this.pathFor(id), "utf8"));
+    } catch {
+      return;
+    }
+    record.attempts = attempts;
+    record.lastError = error;
+    record.nextAttemptAt = nextAttemptAt;
+    this.save(record);
+  }
+  size() {
+    return (0, import_node_fs.readdirSync)(this.dir).filter((n) => n.endsWith(".json")).length;
+  }
+  listDead(limit) {
+    const dead = this.readAll().filter(isDead).sort(byCreatedAt2);
+    return limit === void 0 ? dead : dead.slice(0, limit);
+  }
+  close() {
+  }
+};
+function rowToRecord2(row) {
+  return {
+    id: row.id,
+    eventType: row.event_type,
+    payload: JSON.parse(row.payload),
+    environment: row.environment,
+    application: row.application,
+    source: row.source,
+    createdAt: row.created_at,
+    attempts: row.attempts,
+    lastError: row.last_error,
+    nextAttemptAt: row.next_attempt_at
+  };
+}
+var SqliteStore = class {
+  db;
+  constructor(path = ":memory:") {
+    let DatabaseSync;
+    try {
+      let load;
+      try {
+        load = (0, import_node_module.createRequire)(import_meta.url);
+      } catch {
+        load = require;
+      }
+      ({ DatabaseSync } = load("node:sqlite"));
+    } catch (err) {
+      throw new Error(
+        `SqliteStore requires the built-in node:sqlite (Node >= 22.5): ${String(err)}`
+      );
+    }
+    this.db = new DatabaseSync(path);
+    this.db.exec(
+      `CREATE TABLE IF NOT EXISTS webhookd_outbox (
+        id TEXT PRIMARY KEY,
+        event_type TEXT NOT NULL,
+        payload TEXT NOT NULL,
+        environment TEXT NOT NULL,
+        application TEXT NOT NULL,
+        source TEXT,
+        created_at INTEGER NOT NULL,
+        attempts INTEGER NOT NULL,
+        last_error TEXT,
+        next_attempt_at INTEGER NOT NULL
+      )`
+    );
+  }
+  save(record) {
+    this.db.prepare(
+      `INSERT INTO webhookd_outbox
+          (id, event_type, payload, environment, application, source, created_at, attempts, last_error, next_attempt_at)
+         VALUES (?, ?, ?, ?, ?, ?, ?, ?, ?, ?)
+         ON CONFLICT(id) DO UPDATE SET
+           event_type = excluded.event_type,
+           payload = excluded.payload,
+           environment = excluded.environment,
+           application = excluded.application,
+           source = excluded.source,
+           created_at = excluded.created_at,
+           attempts = excluded.attempts,
+           last_error = excluded.last_error,
+           next_attempt_at = excluded.next_attempt_at`
+    ).run(
+      record.id,
+      record.eventType,
+      JSON.stringify(record.payload),
+      record.environment,
+      record.application,
+      record.source,
+      record.createdAt,
+      record.attempts,
+      record.lastError,
+      record.nextAttemptAt
+    );
+  }
+  listPending(limit) {
+    const rows = this.db.prepare(
+      `SELECT * FROM webhookd_outbox
+         WHERE next_attempt_at <= ? AND next_attempt_at < ?
+         ORDER BY created_at ASC, id ASC
+         LIMIT ?`
+    ).all(Date.now(), DEAD_NEXT_ATTEMPT_MS, limit);
+    return rows.map(rowToRecord2);
+  }
+  markSent(id) {
+    this.db.prepare(`DELETE FROM webhookd_outbox WHERE id = ?`).run(id);
+  }
+  markFailed(id, error, attempts, nextAttemptAt) {
+    this.db.prepare(
+      `UPDATE webhookd_outbox SET attempts = ?, last_error = ?, next_attempt_at = ? WHERE id = ?`
+    ).run(attempts, error, nextAttemptAt, id);
+  }
+  size() {
+    const row = this.db.prepare(`SELECT COUNT(*) AS n FROM webhookd_outbox`).get();
+    return Number(row.n);
+  }
+  listDead(limit) {
+    const rows = this.db.prepare(
+      `SELECT * FROM webhookd_outbox
+         WHERE next_attempt_at >= ?
+         ORDER BY created_at ASC, id ASC
+         ${limit === void 0 ? "" : "LIMIT ?"}`
+    ).all(...limit === void 0 ? [DEAD_NEXT_ATTEMPT_MS] : [DEAD_NEXT_ATTEMPT_MS, limit]);
+    return rows.map(rowToRecord2);
+  }
+  close() {
+    this.db.close();
+  }
+};
+
 // src/client.ts
 var RETRY_STATUSES = /* @__PURE__ */ new Set([429, 500, 502, 503, 504]);
 var WebhookdClient = class {
@@ -88,12 +545,24 @@ var WebhookdClient = class {
   timeoutMs;
   maxRetries;
   fetchImpl;
+  store;
+  maxAttempts;
+  drainBatchLimit;
+  onDead;
+  onDrainError;
+  drainTimer;
+  draining = false;
   constructor(opts) {
     this.baseUrl = opts.baseUrl.replace(/\/+$/, "");
     this.apiKey = opts.apiKey;
     this.timeoutMs = opts.timeoutMs ?? 1e4;
     this.maxRetries = opts.maxRetries ?? 2;
     this.fetchImpl = opts.fetchImpl ?? fetch;
+    this.store = opts.store;
+    this.maxAttempts = opts.maxAttempts ?? 10;
+    this.drainBatchLimit = opts.drainBatchLimit ?? 100;
+    this.onDead = opts.onDead;
+    this.onDrainError = opts.onDrainError;
   }
   async publish(eventType, payload, opts = {}) {
     const body = {
@@ -117,6 +586,114 @@ var WebhookdClient = class {
       source: data.source ?? null
     };
   }
+  // ── Outbox (write-first, durable) ────────────────────────────────────────────
+  /**
+   * 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.
+   */
+  async enqueue(eventType, payload, opts = {}) {
+    const store = this.requireStore();
+    const now = Date.now();
+    const record = {
+      id: opts.idempotencyKey ?? (0, import_node_crypto3.randomUUID)(),
+      eventType,
+      payload,
+      environment: opts.environment ?? "prod",
+      application: opts.application ?? "default",
+      source: opts.source ?? null,
+      createdAt: now,
+      attempts: 0,
+      lastError: null,
+      nextAttemptAt: now
+    };
+    await store.save(record);
+    return { id: record.id };
+  }
+  /**
+   * 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`.
+   */
+  async drain(opts = {}) {
+    const store = this.requireStore();
+    const batchLimit = opts.batchLimit ?? this.drainBatchLimit;
+    const maxAttempts = opts.maxAttempts ?? this.maxAttempts;
+    const rows = await store.listPending(batchLimit);
+    let sent = 0;
+    let failed = 0;
+    for (const record of rows) {
+      const body = {
+        event_type: record.eventType,
+        payload: record.payload,
+        environment: record.environment,
+        application: record.application
+      };
+      if (record.source !== null) body.source = record.source;
+      try {
+        await this.request("POST", "/v1/events", {
+          body,
+          headers: { "Idempotency-Key": record.id }
+        });
+        await store.markSent(record.id);
+        sent += 1;
+      } catch (err) {
+        const attempts = record.attempts + 1;
+        const message = err instanceof Error ? err.message : String(err);
+        if (attempts >= maxAttempts) {
+          await store.markFailed(record.id, message, attempts, DEAD_NEXT_ATTEMPT_MS);
+          this.onDead?.({
+            ...record,
+            attempts,
+            lastError: message,
+            nextAttemptAt: DEAD_NEXT_ATTEMPT_MS
+          });
+        } else {
+          await store.markFailed(record.id, message, attempts, Date.now() + backoffMs(attempts - 1));
+        }
+        failed += 1;
+      }
+    }
+    return { sent, failed, remaining: await store.size() };
+  }
+  /**
+   * 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) {
+    this.requireStore();
+    if (this.drainTimer) return;
+    const ms = Math.max(1, Math.floor(intervalSeconds * 1e3));
+    this.drainTimer = setInterval(() => void this.drainTick(), ms);
+    this.drainTimer.unref?.();
+  }
+  /** Stop the background drainer started by {@link startDrainer}. Safe to call when not running. */
+  stopDrainer() {
+    if (this.drainTimer) {
+      clearInterval(this.drainTimer);
+      this.drainTimer = void 0;
+    }
+  }
+  async drainTick() {
+    if (this.draining) return;
+    this.draining = true;
+    try {
+      await this.drain();
+    } catch (err) {
+      this.onDrainError?.(err);
+    } finally {
+      this.draining = false;
+    }
+  }
+  requireStore() {
+    if (!this.store) {
+      throw new WebhookdError("no outbox store configured \u2014 pass `store` in ClientOptions");
+    }
+    return this.store;
+  }
   // ── Endpoints ──────────────────────────────────────────────────────────────
   /** Create an endpoint. The response includes the signing `secret` exactly once — persist it. */
   async createEndpoint(url, opts = {}) {
@@ -284,14 +861,21 @@ function sleep(ms) {
 }
 
 // src/index.ts
-var VERSION = "0.2.0";
+var VERSION = "0.3.0";
 // Annotate the CommonJS export names for ESM import in node:
 0 && (module.exports = {
+  DEAD_NEXT_ATTEMPT_MS,
   DEFAULT_TOLERANCE_SECONDS,
+  FileStore,
+  MemoryStore,
+  PostgresStore,
+  RedisStore,
+  SqliteStore,
   VERSION,
   WebhookdApiError,
   WebhookdClient,
   WebhookdError,
+  isDead,
   sign,
   verify
 });