@objectstack/plugin-webhooks 5.1.0 → 6.0.0

package/dist/index.js

@@ -1,253 +1,908 @@
-"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)
-    __defProp(target, name, { get: all[name], enumerable: true });
-};
-var __copyProps = (to, from, except, desc) => {
-  if (from && typeof from === "object" || typeof from === "function") {
-    for (let key of __getOwnPropNames(from))
-      if (!__hasOwnProp.call(to, key) && key !== except)
-        __defProp(to, key, { get: () => from[key], enumerable: !(desc = __getOwnPropDesc(from, key)) || desc.enumerable });
-  }
-  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);
+import {
+  RedeliverError,
+  SqlWebhookOutbox,
+  hashPartition
+} from "./chunk-BS2QTZH3.js";
+import {
+  SYS_WEBHOOK_DELIVERY,
+  SysWebhookDelivery
+} from "./chunk-33LYZT7O.js";
 
-// src/index.ts
-var index_exports = {};
-__export(index_exports, {
-  WebhooksPlugin: () => WebhooksPlugin
-});
-module.exports = __toCommonJS(index_exports);
+// src/webhook-outbox-plugin.ts
+import { SysWebhook } from "@objectstack/platform-objects/integration";
 
-// src/webhooks-plugin.ts
-var import_node_crypto = __toESM(require("crypto"));
-var DEFAULT_TIMEOUT_MS = 5e3;
-var DEFAULT_RETRIES = 3;
-var BACKOFF_BASE_MS = 250;
-var BACKOFF_MAX_MS = 5e3;
-var WebhooksPlugin = class {
-  constructor(options = {}) {
-    this.name = "com.objectstack.webhooks";
-    this.version = "1.0.0";
-    this.type = "standard";
-    this.dependencies = ["com.objectstack.service.realtime"];
-    this.subscriptionIds = [];
-    this.sinks = [];
-    this.options = options;
+// src/auto-enqueuer.ts
+var AutoEnqueuer = class {
+  constructor(engine, realtime, outbox, opts = {}) {
+    this.engine = engine;
+    this.realtime = realtime;
+    this.outbox = outbox;
+    this.subscriptions = /* @__PURE__ */ new Map();
+    this.running = false;
+    this.subscriptionsObject = opts.subscriptionsObject ?? "sys_webhook";
+    this.refreshIntervalMs = opts.refreshIntervalMs ?? 6e4;
+    this.logger = opts.logger ?? {};
   }
-  async init(ctx) {
-    this.logger = ctx.logger;
-    this.sinks = this.resolveSinks();
-    if (this.sinks.length === 0) {
-      ctx.logger.info(
-        "WebhooksPlugin: no sinks configured (options.sinks empty and OBJECTSTACK_WEBHOOK_URL unset) \u2014 plugin is dormant"
+  /**
+   * Load the subscription cache and start listening for events.
+   */
+  async start() {
+    if (this.running) return;
+    this.running = true;
+    await this.refresh();
+    this.subId = await this.realtime.subscribe(
+      "webhook-auto-enqueuer",
+      (event) => this.handleEvent(event)
+    );
+    this.subIdSelfHeal = await this.realtime.subscribe(
+      "webhook-auto-enqueuer-self-heal",
+      (event) => this.handleSelfHealEvent(event),
+      { object: this.subscriptionsObject }
+    );
+    if (this.refreshIntervalMs > 0) {
+      this.refreshTimer = setInterval(() => {
+        this.refresh().catch(
+          (err) => this.logger.warn?.("[webhook-auto-enqueuer] periodic refresh failed", err)
+        );
+      }, this.refreshIntervalMs);
+      this.refreshTimer.unref?.();
+    }
+  }
+  async stop() {
+    if (!this.running) return;
+    this.running = false;
+    if (this.subId) await this.realtime.unsubscribe(this.subId);
+    if (this.subIdSelfHeal) await this.realtime.unsubscribe(this.subIdSelfHeal);
+    if (this.refreshTimer) clearInterval(this.refreshTimer);
+    this.subId = void 0;
+    this.subIdSelfHeal = void 0;
+    this.refreshTimer = void 0;
+  }
+  /**
+   * Force-refresh the subscription cache from storage. Concurrent
+   * callers share a single in-flight refresh.
+   */
+  async refresh() {
+    if (this.refreshing) return this.refreshing;
+    this.refreshing = this.doRefresh().finally(() => {
+      this.refreshing = void 0;
+    });
+    return this.refreshing;
+  }
+  async doRefresh() {
+    let rows;
+    try {
+      rows = await this.engine.find(this.subscriptionsObject, {
+        where: { active: true }
+      });
+    } catch (err) {
+      this.logger.warn?.(
+        `[webhook-auto-enqueuer] failed to load ${this.subscriptionsObject}`,
+        err
       );
       return;
     }
-    ctx.logger.info(`WebhooksPlugin: ${this.sinks.length} sink(s) configured`);
+    const next = /* @__PURE__ */ new Map();
+    for (const row of rows) {
+      const sub = this.parseRow(row);
+      if (!sub) continue;
+      const key = sub.objectName ?? "*";
+      const arr = next.get(key) ?? [];
+      arr.push(sub);
+      next.set(key, arr);
+    }
+    this.subscriptions.clear();
+    for (const [k, v] of next) this.subscriptions.set(k, v);
+    this.logger.debug?.("[webhook-auto-enqueuer] cache refreshed", {
+      objects: this.subscriptions.size,
+      rows: rows.length
+    });
   }
-  async start(ctx) {
-    if (this.sinks.length === 0) return;
-    ctx.hook("kernel:ready", async () => {
+  parseRow(row) {
+    if (!row?.id || !row?.url) return null;
+    const triggersField = row.triggers ?? "";
+    const triggers = new Set(
+      triggersField.split(",").map((s) => s.trim().toLowerCase()).filter(Boolean)
+    );
+    if (triggers.size === 0) {
+      return null;
+    }
+    let defn = {};
+    if (typeof row.definition_json === "string" && row.definition_json.length > 0) {
       try {
-        this.realtime = ctx.getService("realtime");
+        defn = JSON.parse(row.definition_json) ?? {};
       } catch {
-        ctx.logger.warn("WebhooksPlugin: realtime service unavailable \u2014 events will not be forwarded");
-        return;
+        defn = {};
       }
-      for (const sink of this.sinks) {
-        const opts = sink.objects && sink.objects.length === 1 || sink.eventTypes && sink.eventTypes.length > 0 ? {
-          ...sink.objects && sink.objects.length === 1 ? { object: sink.objects[0] } : {},
-          ...sink.eventTypes && sink.eventTypes.length > 0 ? { eventTypes: sink.eventTypes } : {}
-        } : void 0;
-        const id = await this.realtime.subscribe(
-          "data.record",
-          async (event) => {
-            await this.dispatch(sink, event);
-          },
-          opts
-        );
-        this.subscriptionIds.push(id);
-      }
-      ctx.logger.info(`WebhooksPlugin: subscribed ${this.subscriptionIds.length} realtime listener(s)`);
+    }
+    return {
+      id: row.id,
+      name: row.name ?? row.id,
+      objectName: row.object_name ? String(row.object_name) : void 0,
+      triggers,
+      url: String(row.url),
+      method: row.method ?? defn.method ?? "POST",
+      headers: defn.headers,
+      secret: defn.secret,
+      timeoutMs: defn.timeoutMs
+    };
+  }
+  /**
+   * Handler for the firehose subscription.
+   *
+   * NOTE: we intentionally `void` the inner enqueue() so the realtime
+   * publisher (and therefore the user's request) is never blocked on
+   * webhook persistence.
+   */
+  handleEvent(event) {
+    if (!event.type?.startsWith("data.record.")) return;
+    if (!event.object) return;
+    if (event.object === this.subscriptionsObject) return;
+    const action = event.type.slice("data.record.".length);
+    const trigger = mapActionToTrigger(action);
+    if (!trigger) return;
+    const subs = [
+      ...this.subscriptions.get(event.object) ?? [],
+      ...this.subscriptions.get("*") ?? []
+    ];
+    if (subs.length === 0) return;
+    const payload = event.payload ?? {};
+    const recordId = payload.recordId ?? payload.id ?? payload.after?.id ?? payload.before?.id ?? "unknown";
+    const eventId = `${event.object}:${recordId}:${action}:${event.timestamp}`;
+    for (const sub of subs) {
+      if (!sub.triggers.has(trigger)) continue;
+      void this.outbox.enqueue({
+        webhookId: sub.id,
+        eventId,
+        eventType: event.type,
+        url: sub.url,
+        method: sub.method,
+        headers: sub.headers,
+        secret: sub.secret,
+        timeoutMs: sub.timeoutMs,
+        payload: {
+          object: event.object,
+          recordId,
+          action,
+          timestamp: event.timestamp,
+          ...payload
+        }
+      }).catch(
+        (err) => this.logger.warn?.("[webhook-auto-enqueuer] enqueue failed", {
+          webhook: sub.name,
+          eventId,
+          err: err?.message ?? err
+        })
+      );
+    }
+  }
+  handleSelfHealEvent(event) {
+    if (event.object !== this.subscriptionsObject) return;
+    if (!event.type?.startsWith("data.record.")) return;
+    this.refresh().catch(
+      (err) => this.logger.warn?.("[webhook-auto-enqueuer] self-heal refresh failed", err)
+    );
+  }
+  /** Test / admin accessor. */
+  snapshot() {
+    return this.subscriptions;
+  }
+};
+function mapActionToTrigger(action) {
+  switch (action) {
+    case "created":
+      return "create";
+    case "updated":
+      return "update";
+    case "deleted":
+      return "delete";
+    case "undeleted":
+      return "undelete";
+    default:
+      return null;
+  }
+}
+
+// src/http-sender.ts
+import { createHmac, randomUUID } from "crypto";
+var DEFAULT_TIMEOUT_MS = 15e3;
+var RESPONSE_BODY_CAP = 16 * 1024;
+async function sendOnce(delivery, fetchImpl) {
+  const body = typeof delivery.payload === "string" ? delivery.payload : JSON.stringify(delivery.payload);
+  const headers = {
+    "Content-Type": "application/json",
+    "User-Agent": "ObjectStack-Webhooks/1.0",
+    "X-Objectstack-Event": delivery.eventType,
+    "X-Objectstack-Delivery": delivery.id,
+    "X-Objectstack-Attempt": String(delivery.attempts + 1),
+    ...delivery.headers ?? {}
+  };
+  if (delivery.secret) {
+    const sig = createHmac("sha256", delivery.secret).update(body).digest("hex");
+    headers["X-Objectstack-Signature"] = `sha256=${sig}`;
+  }
+  const timeoutMs = delivery.timeoutMs ?? DEFAULT_TIMEOUT_MS;
+  const controller = new AbortController();
+  const timer = setTimeout(() => controller.abort(), timeoutMs);
+  const start = Date.now();
+  try {
+    const res = await fetchImpl(delivery.url, {
+      method: delivery.method ?? "POST",
+      headers,
+      body,
+      signal: controller.signal
     });
+    clearTimeout(timer);
+    const responseText = await safeReadBody(res);
+    const durationMs = Date.now() - start;
+    if (res.ok) {
+      return { success: true, httpStatus: res.status, responseBody: responseText, durationMs };
+    }
+    const retriable = res.status === 408 || res.status === 429 || res.status >= 500;
+    return {
+      success: false,
+      retriable,
+      httpStatus: res.status,
+      responseBody: responseText,
+      error: `HTTP ${res.status}`,
+      durationMs
+    };
+  } catch (err) {
+    clearTimeout(timer);
+    const durationMs = Date.now() - start;
+    const e = err;
+    const error = e?.name === "AbortError" ? `timeout after ${timeoutMs}ms` : e?.message ?? String(err);
+    return { success: false, retriable: true, error, durationMs };
   }
-  async stop(ctx) {
-    if (!this.realtime) return;
-    for (const id of this.subscriptionIds) {
+}
+async function safeReadBody(res) {
+  try {
+    const text = await res.text();
+    return text.length > RESPONSE_BODY_CAP ? text.slice(0, RESPONSE_BODY_CAP) : text;
+  } catch {
+    return void 0;
+  }
+}
+function nextRetryDelayMs(attemptsSoFar, rng = Math.random) {
+  const SCHEDULE = [1e3, 1e4, 6e4, 6e5, 36e5, 216e5, 864e5];
+  if (attemptsSoFar < 1 || attemptsSoFar > SCHEDULE.length) return null;
+  const base = SCHEDULE[attemptsSoFar - 1];
+  const jitter = 0.8 + rng() * 0.4;
+  return Math.floor(base * jitter);
+}
+function classifyAttempt(outcome, attemptsSoFar, now = Date.now(), rng) {
+  if (outcome.success) return outcome;
+  if (!outcome.retriable) {
+    return {
+      success: false,
+      httpStatus: outcome.httpStatus,
+      responseBody: outcome.responseBody,
+      error: outcome.error,
+      durationMs: outcome.durationMs,
+      dead: true
+    };
+  }
+  const delay = nextRetryDelayMs(attemptsSoFar + 1, rng);
+  if (delay === null) {
+    return {
+      success: false,
+      httpStatus: outcome.httpStatus,
+      responseBody: outcome.responseBody,
+      error: outcome.error,
+      durationMs: outcome.durationMs,
+      dead: true
+    };
+  }
+  return {
+    success: false,
+    httpStatus: outcome.httpStatus,
+    responseBody: outcome.responseBody,
+    error: outcome.error,
+    durationMs: outcome.durationMs,
+    nextRetryAt: now + delay
+  };
+}
+
+// src/dispatcher.ts
+var WebhookDispatcher = class {
+  constructor(options) {
+    this.running = false;
+    const intervalMs = options.intervalMs ?? 250;
+    const lockTtlMs = options.lockTtlMs ?? intervalMs * 5;
+    this.opts = {
+      nodeId: options.nodeId,
+      cluster: options.cluster,
+      outbox: options.outbox,
+      partitionCount: options.partitionCount ?? 8,
+      batchSize: options.batchSize ?? 32,
+      intervalMs,
+      lockTtlMs,
+      claimTtlMs: options.claimTtlMs ?? lockTtlMs * 2,
+      onAttempt: options.onAttempt,
+      fetchImpl: options.fetchImpl,
+      rng: options.rng,
+      logger: options.logger
+    };
+  }
+  /** Begin the periodic loop. Safe to call once; subsequent calls are no-ops. */
+  start() {
+    if (this.running) return;
+    this.running = true;
+    this.scheduleTick();
+    this.timer = setInterval(() => this.scheduleTick(), this.opts.intervalMs);
+  }
+  /** Stop the loop and wait for the in-flight tick to drain. */
+  async stop() {
+    if (!this.running) return;
+    this.running = false;
+    if (this.timer) {
+      clearInterval(this.timer);
+      this.timer = void 0;
+    }
+    if (this.inflightTick) {
       try {
-        await this.realtime.unsubscribe(id);
-      } catch (err) {
-        ctx.logger.debug("WebhooksPlugin: unsubscribe failed", { id, err });
+        await this.inflightTick;
+      } catch {
       }
     }
-    this.subscriptionIds = [];
   }
   /**
-   * Resolve sinks from constructor options, falling back to env vars when
-   * none provided. Exposed for testing.
+   * Run one full tick (all partitions, single attempt each). Exposed for
+   * deterministic tests that want to step the dispatcher manually.
    */
-  resolveSinks() {
-    if (this.options.sinks && this.options.sinks.length > 0) return this.options.sinks;
-    const urlEnv = process.env.OBJECTSTACK_WEBHOOK_URL;
-    if (!urlEnv) return [];
-    const urls = urlEnv.split(",").map((s) => s.trim()).filter(Boolean);
-    const secret = process.env.OBJECTSTACK_WEBHOOK_SECRET;
-    const objectsEnv = process.env.OBJECTSTACK_WEBHOOK_OBJECTS;
-    const eventsEnv = process.env.OBJECTSTACK_WEBHOOK_EVENTS;
-    const objects = objectsEnv ? objectsEnv.split(",").map((s) => s.trim()).filter(Boolean) : void 0;
-    const eventTypes = eventsEnv ? eventsEnv.split(",").map((s) => s.trim()).filter(Boolean) : void 0;
-    return urls.map((url, idx) => ({
-      id: `env-${idx + 1}`,
-      url,
-      ...secret ? { secret } : {},
-      ...objects ? { objects } : {},
-      ...eventTypes ? { eventTypes } : {}
-    }));
+  async tick() {
+    await this.runTick();
   }
-  /**
-   * Dispatch a single event to a sink, with HMAC signing, timeout, and
-   * exponential-backoff retry. Failures past the retry budget are logged
-   * but never thrown — webhook delivery must never break the originating
-   * mutation.
-   */
-  async dispatch(sink, event) {
-    if (sink.objects && sink.objects.length > 0 && event.object && !sink.objects.includes(event.object)) {
-      return;
+  scheduleTick() {
+    if (this.inflightTick) return;
+    this.inflightTick = this.runTick().catch((err) => {
+      this.opts.logger?.warn?.("webhook-dispatcher: tick failed", {
+        nodeId: this.opts.nodeId,
+        error: err?.message ?? String(err)
+      });
+    }).finally(() => {
+      this.inflightTick = void 0;
+    });
+  }
+  async runTick() {
+    const partitionCount = this.opts.partitionCount;
+    const offset = stableNodeOffset(this.opts.nodeId, partitionCount);
+    for (let step = 0; step < partitionCount; step++) {
+      const i = (offset + step) % partitionCount;
+      await this.runPartition(i);
     }
-    if (sink.eventTypes && sink.eventTypes.length > 0 && !sink.eventTypes.includes(event.type)) {
-      return;
+  }
+  async runPartition(index) {
+    const key = `webhook.dispatcher.partition.${index}`;
+    const handle = await this.opts.cluster.lock.acquire(key, {
+      ttlMs: this.opts.lockTtlMs,
+      // waitMs=0 → fail-fast; we'll try this partition again next tick.
+      waitMs: 0
+    });
+    if (!handle) return;
+    try {
+      const claimed = await this.opts.outbox.claim({
+        nodeId: this.opts.nodeId,
+        limit: this.opts.batchSize,
+        partition: { index, count: this.opts.partitionCount },
+        claimTtlMs: this.opts.claimTtlMs
+      });
+      if (claimed.length === 0) return;
+      await handle.renew(this.opts.lockTtlMs);
+      for (const row of claimed) {
+        if (!handle.isHeld()) break;
+        await this.processRow(row);
+      }
+    } finally {
+      await handle.release();
     }
-    const fetchImpl = this.options.fetchImpl ?? globalThis.fetch;
+  }
+  async processRow(row) {
+    const fetchImpl = this.opts.fetchImpl ?? globalThis.fetch;
     if (!fetchImpl) {
-      this.logger?.warn("WebhooksPlugin: no fetch implementation available \u2014 dropping event", { sinkId: sink.id });
+      this.opts.logger?.warn?.("webhook-dispatcher: no fetch impl available", {
+        rowId: row.id
+      });
+      await this.opts.outbox.ack(row.id, {
+        success: false,
+        error: "no fetch implementation",
+        durationMs: 0,
+        dead: true
+      });
       return;
     }
-    const body = JSON.stringify(event);
-    const headers = {
-      "Content-Type": "application/json",
-      "User-Agent": "ObjectStack-Webhooks/1.0",
-      "X-Objectstack-Event": event.type,
-      ...event.object ? { "X-Objectstack-Object": event.object } : {},
-      "X-Objectstack-Delivery": import_node_crypto.default.randomUUID(),
-      ...sink.headers ?? {}
+    const outcome = await sendOnce(row, fetchImpl);
+    const result = classifyAttempt(outcome, row.attempts, Date.now(), this.opts.rng);
+    await this.opts.outbox.ack(row.id, result);
+    this.opts.onAttempt?.(row, result.success);
+  }
+};
+function stableNodeOffset(nodeId, partitionCount) {
+  let h = 0;
+  for (let i = 0; i < nodeId.length; i++) {
+    h = h * 31 + nodeId.charCodeAt(i) | 0;
+  }
+  return Math.abs(h) % partitionCount;
+}
+
+// src/memory-outbox.ts
+import { randomUUID as randomUUID2 } from "crypto";
+var MemoryWebhookOutbox = class {
+  constructor() {
+    this.rows = /* @__PURE__ */ new Map();
+    /** Dedup index keyed by `${eventId}::${webhookId}` -> row id. */
+    this.dedup = /* @__PURE__ */ new Map();
+  }
+  async enqueue(input) {
+    const dedupKey = `${input.eventId}::${input.webhookId}`;
+    const existing = this.dedup.get(dedupKey);
+    if (existing) return existing;
+    const id = randomUUID2();
+    const now = Date.now();
+    const row = {
+      id,
+      webhookId: input.webhookId,
+      eventId: input.eventId,
+      eventType: input.eventType,
+      url: input.url,
+      method: input.method ?? "POST",
+      headers: input.headers,
+      secret: input.secret,
+      timeoutMs: input.timeoutMs,
+      payload: input.payload,
+      status: "pending",
+      attempts: 0,
+      createdAt: now,
+      updatedAt: now
     };
-    if (sink.secret) {
-      const sig = import_node_crypto.default.createHmac("sha256", sink.secret).update(body).digest("hex");
-      headers["X-Objectstack-Signature"] = `sha256=${sig}`;
-    }
-    const timeoutMs = sink.timeoutMs ?? DEFAULT_TIMEOUT_MS;
-    const maxAttempts = (sink.retries ?? DEFAULT_RETRIES) + 1;
-    for (let attempt = 1; attempt <= maxAttempts; attempt++) {
-      const controller = new AbortController();
-      const timer = setTimeout(() => controller.abort(), timeoutMs);
+    this.rows.set(id, row);
+    this.dedup.set(dedupKey, id);
+    return id;
+  }
+  async claim(opts) {
+    const now = opts.now ?? Date.now();
+    const claimed = [];
+    for (const row of this.rows.values()) {
+      if (row.status === "in_flight" && row.claimedAt !== void 0 && now - row.claimedAt > opts.claimTtlMs) {
+        row.status = "pending";
+        row.claimedBy = void 0;
+        row.claimedAt = void 0;
+        row.updatedAt = now;
+      }
+    }
+    for (const row of this.rows.values()) {
+      if (claimed.length >= opts.limit) break;
+      if (row.status !== "pending") continue;
+      if (row.nextRetryAt !== void 0 && row.nextRetryAt > now) continue;
+      if (opts.partition) {
+        const p = hashPartition(row.webhookId, opts.partition.count);
+        if (p !== opts.partition.index) continue;
+      }
+      row.status = "in_flight";
+      row.claimedBy = opts.nodeId;
+      row.claimedAt = now;
+      row.updatedAt = now;
+      claimed.push({ ...row });
+    }
+    return claimed;
+  }
+  async ack(id, result) {
+    const row = this.rows.get(id);
+    if (!row) return;
+    const now = Date.now();
+    row.attempts += 1;
+    row.lastAttemptedAt = now;
+    row.updatedAt = now;
+    row.claimedBy = void 0;
+    row.claimedAt = void 0;
+    row.responseCode = result.httpStatus;
+    row.responseBody = result.responseBody;
+    let status;
+    if (result.success) {
+      status = "success";
+      row.nextRetryAt = void 0;
+      row.error = void 0;
+    } else if (result.dead) {
+      status = "dead";
+      row.error = result.error;
+      row.nextRetryAt = void 0;
+    } else {
+      status = "pending";
+      row.error = result.error;
+      row.nextRetryAt = result.nextRetryAt;
+    }
+    row.status = status;
+  }
+  async list(filter) {
+    const all = Array.from(this.rows.values()).map((r) => ({ ...r }));
+    return filter?.status ? all.filter((r) => r.status === filter.status) : all;
+  }
+  async redeliver(id) {
+    const row = this.rows.get(id);
+    if (!row) {
+      throw new RedeliverError(
+        `Delivery row '${id}' not found`,
+        "not_found"
+      );
+    }
+    if (row.status !== "success" && row.status !== "failed" && row.status !== "dead") {
+      throw new RedeliverError(
+        `Delivery row '${id}' is '${row.status}', expected one of: success, failed, dead`,
+        "not_eligible"
+      );
+    }
+    const now = Date.now();
+    row.status = "pending";
+    row.attempts = 0;
+    row.claimedBy = void 0;
+    row.claimedAt = void 0;
+    row.nextRetryAt = void 0;
+    row.error = void 0;
+    row.responseCode = void 0;
+    row.responseBody = void 0;
+    row.updatedAt = now;
+    return { ...row };
+  }
+};
+
+// src/retention.ts
+var DEFAULTS = {
+  successTtlMs: 7 * 24 * 60 * 60 * 1e3,
+  deadTtlMs: 30 * 24 * 60 * 60 * 1e3,
+  sweepIntervalMs: 60 * 60 * 1e3
+};
+var DeliveryRetentionSweeper = class {
+  constructor(engine, opts = {}) {
+    this.engine = engine;
+    this.running = false;
+    this.objectName = opts.objectName ?? SYS_WEBHOOK_DELIVERY;
+    this.successTtlMs = opts.successTtlMs ?? DEFAULTS.successTtlMs;
+    this.deadTtlMs = opts.deadTtlMs ?? DEFAULTS.deadTtlMs;
+    this.sweepIntervalMs = opts.sweepIntervalMs ?? DEFAULTS.sweepIntervalMs;
+    this.logger = opts.logger ?? {};
+  }
+  start() {
+    if (this.running) return;
+    this.running = true;
+    this.timer = setInterval(() => {
+      this.sweep().catch(
+        (err) => this.logger.warn?.("[webhook-retention] sweep failed", err)
+      );
+    }, this.sweepIntervalMs);
+    this.timer.unref?.();
+  }
+  stop() {
+    if (!this.running) return;
+    this.running = false;
+    if (this.timer) clearInterval(this.timer);
+    this.timer = void 0;
+  }
+  /** Run one sweep immediately. Returns the number of rows deleted. */
+  async sweep(now = Date.now()) {
+    let successDeleted = 0;
+    let deadDeleted = 0;
+    if (this.successTtlMs > 0) {
       try {
-        const res = await fetchImpl(sink.url, {
-          method: "POST",
-          headers,
-          body,
-          signal: controller.signal
+        const res = await this.engine.delete(this.objectName, {
+          where: {
+            status: "success",
+            updated_at: { $lt: now - this.successTtlMs }
+          }
         });
-        clearTimeout(timer);
-        if (res.ok || res.status >= 400 && res.status < 500) {
-          const status = res.ok ? "ok" : "failed";
-          this.options.onDelivery?.({
-            sinkId: sink.id,
-            url: sink.url,
-            eventType: event.type,
-            object: event.object,
-            status,
-            httpStatus: res.status,
-            attempt
-          });
-          if (status === "failed") {
-            this.logger?.warn("WebhooksPlugin: sink rejected event", {
-              sinkId: sink.id,
-              status: res.status,
-              eventType: event.type
-            });
+        successDeleted = res?.affected ?? 0;
+      } catch (err) {
+        this.logger.warn?.("[webhook-retention] success sweep failed", err);
+      }
+    }
+    if (this.deadTtlMs > 0) {
+      try {
+        const res = await this.engine.delete(this.objectName, {
+          where: {
+            status: "dead",
+            updated_at: { $lt: now - this.deadTtlMs }
           }
-          return;
-        }
-        if (attempt === maxAttempts) {
-          this.options.onDelivery?.({
-            sinkId: sink.id,
-            url: sink.url,
-            eventType: event.type,
-            object: event.object,
-            status: "failed",
-            httpStatus: res.status,
-            attempt
-          });
-          this.logger?.warn("WebhooksPlugin: max retries exhausted", {
-            sinkId: sink.id,
-            status: res.status,
-            eventType: event.type
-          });
-          return;
-        }
-        this.options.onDelivery?.({
-          sinkId: sink.id,
-          url: sink.url,
-          eventType: event.type,
-          object: event.object,
-          status: "retrying",
-          httpStatus: res.status,
-          attempt
         });
+        deadDeleted = res?.affected ?? 0;
       } catch (err) {
-        clearTimeout(timer);
-        const errMessage = err?.name === "AbortError" ? `timeout after ${timeoutMs}ms` : err?.message ?? String(err);
-        if (attempt === maxAttempts) {
-          this.options.onDelivery?.({
-            sinkId: sink.id,
-            url: sink.url,
-            eventType: event.type,
-            object: event.object,
-            status: "failed",
-            attempt,
-            error: errMessage
-          });
-          this.logger?.warn("WebhooksPlugin: delivery failed", {
-            sinkId: sink.id,
-            eventType: event.type,
-            error: errMessage
-          });
-          return;
-        }
-        this.options.onDelivery?.({
-          sinkId: sink.id,
-          url: sink.url,
-          eventType: event.type,
-          object: event.object,
-          status: "retrying",
-          attempt,
-          error: errMessage
+        this.logger.warn?.("[webhook-retention] dead sweep failed", err);
+      }
+    }
+    if (successDeleted + deadDeleted > 0) {
+      this.logger.info?.("[webhook-retention] sweep complete", {
+        success: successDeleted,
+        dead: deadDeleted
+      });
+    }
+    return { success: successDeleted, dead: deadDeleted };
+  }
+};
+
+// src/webhook-outbox-plugin.ts
+var WebhookOutboxPlugin = class {
+  constructor(options = {}) {
+    this.options = options;
+    this.name = "com.objectstack.plugin-webhook-outbox";
+    this.version = "1.1.0";
+    this.type = "standard";
+    this.dependencies = ["com.objectstack.service.cluster"];
+  }
+  async init(ctx) {
+    const cluster = ctx.getService("cluster");
+    if (!cluster) {
+      throw new Error(
+        'WebhookOutboxPlugin: required service "cluster" not found \u2014 register ClusterServicePlugin first'
+      );
+    }
+    const manifest = ctx.getService("manifest");
+    if (manifest && typeof manifest.register === "function") {
+      manifest.register({
+        id: "com.objectstack.plugin-webhook-outbox.schema",
+        namespace: "sys",
+        version: this.version,
+        type: "plugin",
+        scope: "system",
+        name: "Webhook Outbox Schemas",
+        description: "Registers sys_webhook (configuration) and sys_webhook_delivery (durable outbox telemetry).",
+        objects: [SysWebhook, SysWebhookDelivery]
+      });
+    } else {
+      ctx.logger.warn?.(
+        "[webhook-outbox] manifest service unavailable \u2014 sys_webhook / sys_webhook_delivery will NOT appear in REST or Studio nav. Register MetadataService before WebhookOutboxPlugin."
+      );
+    }
+    const outbox = this.resolveOutbox(ctx);
+    this.outboxInstance = outbox;
+    const nodeId = this.options.nodeId ?? process.env.OBJECTSTACK_NODE_ID ?? `node-${Math.random().toString(36).slice(2, 10)}`;
+    const dispatcher = new WebhookDispatcher({
+      nodeId,
+      cluster,
+      outbox,
+      partitionCount: this.options.partitionCount,
+      batchSize: this.options.batchSize,
+      intervalMs: this.options.intervalMs,
+      lockTtlMs: this.options.lockTtlMs,
+      claimTtlMs: this.options.claimTtlMs,
+      fetchImpl: this.options.fetchImpl,
+      onAttempt: this.options.onAttempt,
+      rng: this.options.rng,
+      logger: ctx.logger
+    });
+    this.dispatcher = dispatcher;
+    ctx.registerService("webhook.outbox", outbox);
+    ctx.registerService("webhook.dispatcher", dispatcher);
+    if (this.options.autoStart !== false) {
+      dispatcher.start();
+    }
+    const usingMemoryOutbox = outbox instanceof MemoryWebhookOutbox;
+    if (usingMemoryOutbox && process.env.NODE_ENV === "production") {
+      ctx.logger.warn?.(
+        "[webhook-outbox] MemoryWebhookOutbox in production \u2014 webhook deliveries WILL be lost on process exit. Ensure ObjectQL is registered before WebhookOutboxPlugin so the SQL outbox can auto-select."
+      );
+    }
+    const autoEnqueueOpt = this.options.autoEnqueue ?? true;
+    const retentionOpt = this.options.retention ?? true;
+    const needsReadyHook = autoEnqueueOpt !== false || retentionOpt !== false;
+    if (needsReadyHook && typeof ctx.hook === "function") {
+      ctx.hook("kernel:ready", async () => {
+        await this.bootAutoEnqueue(ctx, autoEnqueueOpt);
+        this.bootRetention(ctx, retentionOpt);
+      });
+    }
+    if (typeof ctx.hook === "function") {
+      ctx.hook("kernel:ready", () => {
+        this.registerAdminRoutes(ctx);
+      });
+    }
+    ctx.logger.info?.("[webhook-outbox] initialised", {
+      nodeId,
+      partitions: this.options.partitionCount ?? 8,
+      interval: this.options.intervalMs ?? 250,
+      autoEnqueue: autoEnqueueOpt !== false,
+      retention: retentionOpt !== false
+    });
+  }
+  async dispose() {
+    await this.autoEnqueuer?.stop();
+    this.retention?.stop();
+    await this.dispatcher?.stop();
+  }
+  resolveOutbox(ctx) {
+    const opt = this.options.outbox;
+    if (opt) {
+      return typeof opt === "function" ? opt(ctx) : opt;
+    }
+    const engine = this.tryGetService(ctx, ["objectql", "data"]);
+    if (engine) {
+      const partitionCount = this.options.partitionCount ?? 8;
+      const sql = new SqlWebhookOutbox(engine, { partitionCount });
+      ctx.logger.info?.(
+        "[webhook-outbox] auto-selected SqlWebhookOutbox (objectql engine detected)",
+        { partitionCount }
+      );
+      return sql;
+    }
+    ctx.logger.warn?.(
+      "[webhook-outbox] no IDataEngine available \u2014 falling back to MemoryWebhookOutbox. Deliveries will NOT survive process restart and the redeliver REST endpoint will not see rows written through ObjectQL."
+    );
+    return new MemoryWebhookOutbox();
+  }
+  async bootAutoEnqueue(ctx, opt) {
+    if (opt === false) return;
+    const engine = this.tryGetService(ctx, ["objectql", "data"]);
+    const realtime = this.tryGetService(ctx, ["realtime"]);
+    if (!engine || !realtime) {
+      ctx.logger.warn?.(
+        "[webhook-auto-enqueuer] disabled \u2014 ObjectQL or Realtime service not available",
+        { hasEngine: !!engine, hasRealtime: !!realtime }
+      );
+      return;
+    }
+    if (!this.outboxInstance) return;
+    const enqOpts = typeof opt === "object" ? opt : {};
+    this.autoEnqueuer = new AutoEnqueuer(
+      engine,
+      realtime,
+      this.outboxInstance,
+      { ...enqOpts, logger: ctx.logger }
+    );
+    await this.autoEnqueuer.start();
+    ctx.registerService("webhook.autoEnqueuer", this.autoEnqueuer);
+    ctx.logger.info?.("[webhook-auto-enqueuer] started");
+  }
+  bootRetention(ctx, opt) {
+    if (opt === false) return;
+    if (this.outboxInstance instanceof MemoryWebhookOutbox) return;
+    const engine = this.tryGetService(ctx, ["objectql", "data"]);
+    if (!engine) {
+      ctx.logger.warn?.(
+        "[webhook-retention] disabled \u2014 ObjectQL service not available"
+      );
+      return;
+    }
+    const retOpts = typeof opt === "object" ? opt : {};
+    this.retention = new DeliveryRetentionSweeper(engine, {
+      ...retOpts,
+      logger: ctx.logger
+    });
+    this.retention.start();
+    ctx.registerService("webhook.retention", this.retention);
+    ctx.logger.info?.("[webhook-retention] sweeper started");
+  }
+  tryGetService(ctx, names) {
+    for (const n of names) {
+      try {
+        const svc = ctx.getService(n);
+        if (svc) return svc;
+      } catch {
+      }
+    }
+    return void 0;
+  }
+  /**
+   * Mount POST /api/v1/webhooks/redeliver on the host Hono app, if one
+   * is available. Silently no-ops in environments without an HTTP
+   * server (MSW, edge tests, pure library use). Auth is delegated to
+   * the better-auth session cookie — every authenticated user counts.
+   */
+  registerAdminRoutes(ctx) {
+    const http = this.tryGetService(ctx, ["http-server"]);
+    if (!http || typeof http.getRawApp !== "function") {
+      ctx.logger.debug?.(
+        "[webhook-outbox] HTTP server not available; redeliver REST endpoint not mounted"
+      );
+      return;
+    }
+    const rawApp = http.getRawApp();
+    const outbox = this.outboxInstance;
+    if (!rawApp || !outbox) return;
+    rawApp.post("/api/v1/webhooks/redeliver", async (c) => {
+      const userId = await this.resolveSessionUserId(ctx, c);
+      if (!userId) {
+        return c.json(
+          {
+            success: false,
+            error: "unauthenticated",
+            message: "Sign in to redeliver webhook deliveries."
+          },
+          401
+        );
+      }
+      let body;
+      try {
+        body = await c.req.json();
+      } catch {
+        return c.json(
+          {
+            success: false,
+            error: "invalid_body",
+            message: "Request body must be JSON."
+          },
+          400
+        );
+      }
+      const deliveryId = typeof body?.deliveryId === "string" ? body.deliveryId.trim() : "";
+      if (!deliveryId) {
+        return c.json(
+          {
+            success: false,
+            error: "missing_delivery_id",
+            message: "Body must include `deliveryId: string`."
+          },
+          400
+        );
+      }
+      try {
+        const row = await outbox.redeliver(deliveryId);
+        ctx.logger.info?.("[webhook-outbox] redelivered", {
+          deliveryId,
+          requestedBy: userId
         });
+        return c.json({ success: true, data: { id: row.id, status: row.status } });
+      } catch (err) {
+        const code = err?.code;
+        if (code === "not_found") {
+          return c.json(
+            { success: false, error: "not_found", message: err.message },
+            404
+          );
+        }
+        if (code === "not_eligible") {
+          return c.json(
+            { success: false, error: "not_eligible", message: err.message },
+            409
+          );
+        }
+        ctx.logger.error?.(
+          "[webhook-outbox] redeliver failed",
+          err
+        );
+        return c.json(
+          {
+            success: false,
+            error: "internal_error",
+            message: err?.message ?? String(err)
+          },
+          500
+        );
+      }
+    });
+    ctx.logger.info?.(
+      "[webhook-outbox] redeliver endpoint mounted at POST /api/v1/webhooks/redeliver"
+    );
+  }
+  /**
+   * Resolve the requesting user's id from a better-auth session cookie.
+   * Returns `undefined` for anonymous callers — the caller decides
+   * whether that's a 401.
+   */
+  async resolveSessionUserId(ctx, c) {
+    try {
+      const authService = this.tryGetService(ctx, ["auth"]);
+      if (!authService) return void 0;
+      let api = authService.api;
+      if (!api && typeof authService.getApi === "function") {
+        api = await authService.getApi();
       }
-      const delay = Math.min(BACKOFF_MAX_MS, BACKOFF_BASE_MS * 2 ** (attempt - 1));
-      const jittered = Math.floor(Math.random() * delay);
-      await new Promise((r) => setTimeout(r, jittered));
+      if (!api?.getSession) return void 0;
+      const session = await api.getSession({ headers: c.req.raw.headers });
+      const uid = session?.user?.id;
+      return typeof uid === "string" && uid.length > 0 ? uid : void 0;
+    } catch {
+      return void 0;
     }
   }
 };
-// Annotate the CommonJS export names for ESM import in node:
-0 && (module.exports = {
-  WebhooksPlugin
-});
+export {
+  AutoEnqueuer,
+  DEFAULT_TIMEOUT_MS,
+  DeliveryRetentionSweeper,
+  MemoryWebhookOutbox,
+  RedeliverError,
+  WebhookDispatcher,
+  WebhookOutboxPlugin,
+  classifyAttempt,
+  hashPartition,
+  nextRetryDelayMs,
+  sendOnce
+};
 //# sourceMappingURL=index.js.map