@nimbusnexus/webhooks-sdk 0.2.0 → 0.3.0

package/dist/index.js

@@ -1,3 +1,10 @@
+var __require = /* @__PURE__ */ ((x) => typeof require !== "undefined" ? require : typeof Proxy !== "undefined" ? new Proxy(x, {
+  get: (a, b) => (typeof require !== "undefined" ? require : a)[b]
+}) : x)(function(x) {
+  if (typeof require !== "undefined") return require.apply(this, arguments);
+  throw Error('Dynamic require of "' + x + '" is not supported');
+});
+
 // src/signature.ts
 import { createHmac, timingSafeEqual } from "crypto";
 var PREFIX = "sha256=";
@@ -30,6 +37,9 @@ function verify(secret, rawBody, signature, opts = {}) {
   return false;
 }
 
+// src/client.ts
+import { randomUUID } from "crypto";
+
 // src/errors.ts
 var WebhookdError = class extends Error {
   constructor(message) {
@@ -48,6 +58,442 @@ var WebhookdApiError = class extends WebhookdError {
   }
 };
 
+// src/outbox.ts
+import { mkdirSync, readdirSync, readFileSync, renameSync, rmSync, writeFileSync } from "fs";
+import { join } from "path";
+import { randomBytes } from "crypto";
+import { createRequire } from "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 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;
+    mkdirSync(dir, { recursive: true });
+  }
+  /** Map an arbitrary id to a safe filename (ids may be caller-supplied idempotency keys). */
+  pathFor(id) {
+    return join(this.dir, `${encodeURIComponent(id)}.json`);
+  }
+  readAll() {
+    const out = [];
+    for (const name of readdirSync(this.dir)) {
+      if (!name.endsWith(".json")) continue;
+      try {
+        out.push(JSON.parse(readFileSync(join(this.dir, name), "utf8")));
+      } catch {
+      }
+    }
+    return out;
+  }
+  save(record) {
+    const dest = this.pathFor(record.id);
+    const tmp = `${dest}.tmp-${randomBytes(6).toString("hex")}`;
+    writeFileSync(tmp, JSON.stringify(record), "utf8");
+    renameSync(tmp, dest);
+  }
+  listPending(limit) {
+    const now = Date.now();
+    return this.readAll().filter((r) => r.nextAttemptAt <= now).sort(byCreatedAt2).slice(0, limit);
+  }
+  markSent(id) {
+    rmSync(this.pathFor(id), { force: true });
+  }
+  markFailed(id, error, attempts, nextAttemptAt) {
+    let record;
+    try {
+      record = JSON.parse(readFileSync(this.pathFor(id), "utf8"));
+    } catch {
+      return;
+    }
+    record.attempts = attempts;
+    record.lastError = error;
+    record.nextAttemptAt = nextAttemptAt;
+    this.save(record);
+  }
+  size() {
+    return 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 = 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 {
@@ -56,12 +502,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 = {
@@ -85,6 +543,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 ?? 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 = {}) {
@@ -252,13 +818,20 @@ function sleep(ms) {
 }
 
 // src/index.ts
-var VERSION = "0.2.0";
+var VERSION = "0.3.0";
 export {
+  DEAD_NEXT_ATTEMPT_MS,
   DEFAULT_TOLERANCE_SECONDS,
+  FileStore,
+  MemoryStore,
+  PostgresStore,
+  RedisStore,
+  SqliteStore,
   VERSION,
   WebhookdApiError,
   WebhookdClient,
   WebhookdError,
+  isDead,
   sign,
   verify
 };