@objectstack/plugin-webhooks 4.0.1

package/dist/index.js

@@ -0,0 +1,253 @@
+"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);
+
+// src/index.ts
+var index_exports = {};
+__export(index_exports, {
+  WebhooksPlugin: () => WebhooksPlugin
+});
+module.exports = __toCommonJS(index_exports);
+
+// 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;
+  }
+  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"
+      );
+      return;
+    }
+    ctx.logger.info(`WebhooksPlugin: ${this.sinks.length} sink(s) configured`);
+  }
+  async start(ctx) {
+    if (this.sinks.length === 0) return;
+    ctx.hook("kernel:ready", async () => {
+      try {
+        this.realtime = ctx.getService("realtime");
+      } catch {
+        ctx.logger.warn("WebhooksPlugin: realtime service unavailable \u2014 events will not be forwarded");
+        return;
+      }
+      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)`);
+    });
+  }
+  async stop(ctx) {
+    if (!this.realtime) return;
+    for (const id of this.subscriptionIds) {
+      try {
+        await this.realtime.unsubscribe(id);
+      } catch (err) {
+        ctx.logger.debug("WebhooksPlugin: unsubscribe failed", { id, err });
+      }
+    }
+    this.subscriptionIds = [];
+  }
+  /**
+   * Resolve sinks from constructor options, falling back to env vars when
+   * none provided. Exposed for testing.
+   */
+  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 } : {}
+    }));
+  }
+  /**
+   * 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;
+    }
+    if (sink.eventTypes && sink.eventTypes.length > 0 && !sink.eventTypes.includes(event.type)) {
+      return;
+    }
+    const fetchImpl = this.options.fetchImpl ?? globalThis.fetch;
+    if (!fetchImpl) {
+      this.logger?.warn("WebhooksPlugin: no fetch implementation available \u2014 dropping event", { sinkId: sink.id });
+      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 ?? {}
+    };
+    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);
+      try {
+        const res = await fetchImpl(sink.url, {
+          method: "POST",
+          headers,
+          body,
+          signal: controller.signal
+        });
+        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
+            });
+          }
+          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
+        });
+      } 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
+        });
+      }
+      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));
+    }
+  }
+};
+// Annotate the CommonJS export names for ESM import in node:
+0 && (module.exports = {
+  WebhooksPlugin
+});
+//# sourceMappingURL=index.js.map

package/dist/index.js.map

@@ -0,0 +1 @@
+{"version":3,"sources":["../src/index.ts","../src/webhooks-plugin.ts"],"sourcesContent":["// Copyright (c) 2025 ObjectStack. Licensed under the Apache-2.0 license.\n\n/**\n * @objectstack/plugin-webhooks\n *\n * Outbound webhook delivery for `data.record.created`,\n * `data.record.updated`, and `data.record.deleted` events. Subscribes to\n * the realtime service, fans events out to one or more configured HTTP\n * sinks, signs each request with HMAC-SHA256, and retries transient\n * failures with exponential backoff.\n */\n\nexport { WebhooksPlugin } from './webhooks-plugin.js';\nexport type {\n  WebhooksPluginOptions,\n  WebhookSink,\n  WebhookDeliveryRecord,\n  WebhookDeliveryStatus,\n} from './webhooks-plugin.js';\n","// Copyright (c) 2025 ObjectStack. Licensed under the Apache-2.0 license.\n\nimport crypto from 'node:crypto';\nimport type { Plugin, PluginContext } from '@objectstack/core';\nimport type {\n  IRealtimeService,\n  RealtimeEventPayload,\n  RealtimeSubscriptionOptions,\n} from '@objectstack/spec/contracts';\n\n/**\n * A single webhook delivery target.\n */\nexport interface WebhookSink {\n  /** Unique sink id used for log correlation. */\n  id: string;\n  /** Target HTTPS URL. */\n  url: string;\n  /** Optional HMAC-SHA256 secret. When set, `X-Objectstack-Signature: sha256=…` is added. */\n  secret?: string;\n  /**\n   * Restrict to specific object names (logical names, e.g. `lead`, `account`).\n   * Omit / empty → all objects.\n   */\n  objects?: string[];\n  /**\n   * Restrict to specific event types. Omit / empty → all `data.record.*` events.\n   */\n  eventTypes?: string[];\n  /** Extra headers to send (Authorization, Tenant, etc.). */\n  headers?: Record<string, string>;\n  /** Per-request timeout in milliseconds. Default 5000. */\n  timeoutMs?: number;\n  /** Retry attempts on transient failure. Default 3. Set 0 to disable retries. */\n  retries?: number;\n}\n\n/**\n * Delivery attempt outcome surfaced to in-process listeners / tests.\n */\nexport type WebhookDeliveryStatus = 'ok' | 'retrying' | 'failed';\n\nexport interface WebhookDeliveryRecord {\n  sinkId: string;\n  url: string;\n  eventType: string;\n  object?: string;\n  status: WebhookDeliveryStatus;\n  httpStatus?: number;\n  attempt: number;\n  error?: string;\n}\n\n/**\n * Plugin configuration.\n *\n * Sinks may be supplied programmatically OR via env vars when none are\n * passed (suitable for 12-factor / Docker deployments):\n *\n *   OBJECTSTACK_WEBHOOK_URL       — single URL, or comma-separated URLs.\n *   OBJECTSTACK_WEBHOOK_SECRET    — HMAC secret applied to all env-sourced URLs.\n *   OBJECTSTACK_WEBHOOK_OBJECTS   — comma-separated object whitelist.\n *   OBJECTSTACK_WEBHOOK_EVENTS    — comma-separated event-type whitelist\n *                                   (e.g. `data.record.created`).\n */\nexport interface WebhooksPluginOptions {\n  /** Explicit sink list (takes precedence over env vars). */\n  sinks?: WebhookSink[];\n  /** Override fetch (mainly for tests). Defaults to globalThis.fetch. */\n  fetchImpl?: typeof fetch;\n  /** Hook invoked with each delivery outcome (mainly for tests / metrics). */\n  onDelivery?: (record: WebhookDeliveryRecord) => void;\n}\n\nconst DEFAULT_TIMEOUT_MS = 5_000;\nconst DEFAULT_RETRIES = 3;\nconst BACKOFF_BASE_MS = 250;\nconst BACKOFF_MAX_MS = 5_000;\n\n/**\n * WebhooksPlugin — fan out data.record.* events to external HTTP endpoints.\n *\n * @example\n * ```ts\n * kernel.use(new WebhooksPlugin({\n *   sinks: [\n *     { id: 'crm-sync', url: 'https://hooks.example.com/in',\n *       secret: process.env.HOOK_SECRET, objects: ['lead', 'account'] },\n *   ],\n * }));\n * ```\n */\nexport class WebhooksPlugin implements Plugin {\n  name = 'com.objectstack.webhooks';\n  version = '1.0.0';\n  type = 'standard';\n  dependencies = ['com.objectstack.service.realtime'];\n\n  private readonly options: WebhooksPluginOptions;\n  private subscriptionIds: string[] = [];\n  private realtime?: IRealtimeService;\n  private sinks: WebhookSink[] = [];\n  private logger?: PluginContext['logger'];\n\n  constructor(options: WebhooksPluginOptions = {}) {\n    this.options = options;\n  }\n\n  async init(ctx: PluginContext): Promise<void> {\n    this.logger = ctx.logger;\n    this.sinks = this.resolveSinks();\n    if (this.sinks.length === 0) {\n      ctx.logger.info(\n        'WebhooksPlugin: no sinks configured (options.sinks empty and OBJECTSTACK_WEBHOOK_URL unset) — plugin is dormant',\n      );\n      return;\n    }\n    ctx.logger.info(`WebhooksPlugin: ${this.sinks.length} sink(s) configured`);\n  }\n\n  async start(ctx: PluginContext): Promise<void> {\n    if (this.sinks.length === 0) return;\n    ctx.hook('kernel:ready', async () => {\n      try {\n        this.realtime = ctx.getService<IRealtimeService>('realtime');\n      } catch {\n        ctx.logger.warn('WebhooksPlugin: realtime service unavailable — events will not be forwarded');\n        return;\n      }\n\n      // We subscribe once per sink so the realtime service can apply each\n      // sink's object / eventTypes filter at the channel layer where\n      // possible. This also lets us cleanly unsubscribe on stop().\n      for (const sink of this.sinks) {\n        const opts: RealtimeSubscriptionOptions | undefined =\n          (sink.objects && sink.objects.length === 1) ||\n          (sink.eventTypes && sink.eventTypes.length > 0)\n            ? {\n                ...(sink.objects && sink.objects.length === 1 ? { object: sink.objects[0] } : {}),\n                ...(sink.eventTypes && sink.eventTypes.length > 0 ? { eventTypes: sink.eventTypes } : {}),\n              }\n            : undefined;\n        const id = await this.realtime.subscribe(\n          'data.record',\n          async (event) => { await this.dispatch(sink, event); },\n          opts,\n        );\n        this.subscriptionIds.push(id);\n      }\n      ctx.logger.info(`WebhooksPlugin: subscribed ${this.subscriptionIds.length} realtime listener(s)`);\n    });\n  }\n\n  async stop(ctx: PluginContext): Promise<void> {\n    if (!this.realtime) return;\n    for (const id of this.subscriptionIds) {\n      try { await this.realtime.unsubscribe(id); }\n      catch (err) { ctx.logger.debug('WebhooksPlugin: unsubscribe failed', { id, err }); }\n    }\n    this.subscriptionIds = [];\n  }\n\n  /**\n   * Resolve sinks from constructor options, falling back to env vars when\n   * none provided. Exposed for testing.\n   */\n  private resolveSinks(): WebhookSink[] {\n    if (this.options.sinks && this.options.sinks.length > 0) return this.options.sinks;\n\n    const urlEnv = process.env.OBJECTSTACK_WEBHOOK_URL;\n    if (!urlEnv) return [];\n\n    const urls = urlEnv.split(',').map(s => s.trim()).filter(Boolean);\n    const secret = process.env.OBJECTSTACK_WEBHOOK_SECRET;\n    const objectsEnv = process.env.OBJECTSTACK_WEBHOOK_OBJECTS;\n    const eventsEnv = process.env.OBJECTSTACK_WEBHOOK_EVENTS;\n    const objects = objectsEnv ? objectsEnv.split(',').map(s => s.trim()).filter(Boolean) : undefined;\n    const eventTypes = eventsEnv ? eventsEnv.split(',').map(s => s.trim()).filter(Boolean) : undefined;\n\n    return urls.map((url, idx) => ({\n      id: `env-${idx + 1}`,\n      url,\n      ...(secret ? { secret } : {}),\n      ...(objects ? { objects } : {}),\n      ...(eventTypes ? { eventTypes } : {}),\n    }));\n  }\n\n  /**\n   * Dispatch a single event to a sink, with HMAC signing, timeout, and\n   * exponential-backoff retry. Failures past the retry budget are logged\n   * but never thrown — webhook delivery must never break the originating\n   * mutation.\n   */\n  private async dispatch(sink: WebhookSink, event: RealtimeEventPayload): Promise<void> {\n    // Defence in depth: the realtime layer already filters by single-object\n    // subscriptions, but multi-object whitelists are applied here.\n    if (sink.objects && sink.objects.length > 0 && event.object && !sink.objects.includes(event.object)) {\n      return;\n    }\n    if (sink.eventTypes && sink.eventTypes.length > 0 && !sink.eventTypes.includes(event.type)) {\n      return;\n    }\n\n    const fetchImpl = this.options.fetchImpl ?? globalThis.fetch;\n    if (!fetchImpl) {\n      this.logger?.warn('WebhooksPlugin: no fetch implementation available — dropping event', { sinkId: sink.id });\n      return;\n    }\n\n    const body = JSON.stringify(event);\n    const headers: Record<string, string> = {\n      'Content-Type': 'application/json',\n      'User-Agent': 'ObjectStack-Webhooks/1.0',\n      'X-Objectstack-Event': event.type,\n      ...(event.object ? { 'X-Objectstack-Object': event.object } : {}),\n      'X-Objectstack-Delivery': crypto.randomUUID(),\n      ...(sink.headers ?? {}),\n    };\n    if (sink.secret) {\n      const sig = crypto.createHmac('sha256', sink.secret).update(body).digest('hex');\n      headers['X-Objectstack-Signature'] = `sha256=${sig}`;\n    }\n\n    const timeoutMs = sink.timeoutMs ?? DEFAULT_TIMEOUT_MS;\n    const maxAttempts = (sink.retries ?? DEFAULT_RETRIES) + 1;\n\n    for (let attempt = 1; attempt <= maxAttempts; attempt++) {\n      const controller = new AbortController();\n      const timer = setTimeout(() => controller.abort(), timeoutMs);\n      try {\n        const res = await fetchImpl(sink.url, {\n          method: 'POST',\n          headers,\n          body,\n          signal: controller.signal,\n        });\n        clearTimeout(timer);\n        if (res.ok || (res.status >= 400 && res.status < 500)) {\n          // 4xx is \"permanent\" — don't retry; only 2xx counts as success.\n          const status: WebhookDeliveryStatus = res.ok ? 'ok' : 'failed';\n          this.options.onDelivery?.({\n            sinkId: sink.id, url: sink.url, eventType: event.type,\n            object: event.object, status, httpStatus: res.status, attempt,\n          });\n          if (status === 'failed') {\n            this.logger?.warn('WebhooksPlugin: sink rejected event', {\n              sinkId: sink.id, status: res.status, eventType: event.type,\n            });\n          }\n          return;\n        }\n        // 5xx → fall through to retry.\n        if (attempt === maxAttempts) {\n          this.options.onDelivery?.({\n            sinkId: sink.id, url: sink.url, eventType: event.type, object: event.object,\n            status: 'failed', httpStatus: res.status, attempt,\n          });\n          this.logger?.warn('WebhooksPlugin: max retries exhausted', {\n            sinkId: sink.id, status: res.status, eventType: event.type,\n          });\n          return;\n        }\n        this.options.onDelivery?.({\n          sinkId: sink.id, url: sink.url, eventType: event.type, object: event.object,\n          status: 'retrying', httpStatus: res.status, attempt,\n        });\n      } catch (err: any) {\n        clearTimeout(timer);\n        const errMessage = err?.name === 'AbortError'\n          ? `timeout after ${timeoutMs}ms`\n          : (err?.message ?? String(err));\n        if (attempt === maxAttempts) {\n          this.options.onDelivery?.({\n            sinkId: sink.id, url: sink.url, eventType: event.type, object: event.object,\n            status: 'failed', attempt, error: errMessage,\n          });\n          this.logger?.warn('WebhooksPlugin: delivery failed', {\n            sinkId: sink.id, eventType: event.type, error: errMessage,\n          });\n          return;\n        }\n        this.options.onDelivery?.({\n          sinkId: sink.id, url: sink.url, eventType: event.type, object: event.object,\n          status: 'retrying', attempt, error: errMessage,\n        });\n      }\n      // Exponential backoff with full jitter.\n      const delay = Math.min(BACKOFF_MAX_MS, BACKOFF_BASE_MS * 2 ** (attempt - 1));\n      const jittered = Math.floor(Math.random() * delay);\n      await new Promise(r => setTimeout(r, jittered));\n    }\n  }\n}\n"],"mappings":"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","names":["crypto"]}

package/dist/index.mjs

@@ -0,0 +1,216 @@
+// src/webhooks-plugin.ts
+import crypto from "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;
+  }
+  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"
+      );
+      return;
+    }
+    ctx.logger.info(`WebhooksPlugin: ${this.sinks.length} sink(s) configured`);
+  }
+  async start(ctx) {
+    if (this.sinks.length === 0) return;
+    ctx.hook("kernel:ready", async () => {
+      try {
+        this.realtime = ctx.getService("realtime");
+      } catch {
+        ctx.logger.warn("WebhooksPlugin: realtime service unavailable \u2014 events will not be forwarded");
+        return;
+      }
+      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)`);
+    });
+  }
+  async stop(ctx) {
+    if (!this.realtime) return;
+    for (const id of this.subscriptionIds) {
+      try {
+        await this.realtime.unsubscribe(id);
+      } catch (err) {
+        ctx.logger.debug("WebhooksPlugin: unsubscribe failed", { id, err });
+      }
+    }
+    this.subscriptionIds = [];
+  }
+  /**
+   * Resolve sinks from constructor options, falling back to env vars when
+   * none provided. Exposed for testing.
+   */
+  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 } : {}
+    }));
+  }
+  /**
+   * 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;
+    }
+    if (sink.eventTypes && sink.eventTypes.length > 0 && !sink.eventTypes.includes(event.type)) {
+      return;
+    }
+    const fetchImpl = this.options.fetchImpl ?? globalThis.fetch;
+    if (!fetchImpl) {
+      this.logger?.warn("WebhooksPlugin: no fetch implementation available \u2014 dropping event", { sinkId: sink.id });
+      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": crypto.randomUUID(),
+      ...sink.headers ?? {}
+    };
+    if (sink.secret) {
+      const sig = crypto.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);
+      try {
+        const res = await fetchImpl(sink.url, {
+          method: "POST",
+          headers,
+          body,
+          signal: controller.signal
+        });
+        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
+            });
+          }
+          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
+        });
+      } 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
+        });
+      }
+      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));
+    }
+  }
+};
+export {
+  WebhooksPlugin
+};
+//# sourceMappingURL=index.mjs.map

package/dist/index.mjs.map

@@ -0,0 +1 @@
+{"version":3,"sources":["../src/webhooks-plugin.ts"],"sourcesContent":["// Copyright (c) 2025 ObjectStack. Licensed under the Apache-2.0 license.\n\nimport crypto from 'node:crypto';\nimport type { Plugin, PluginContext } from '@objectstack/core';\nimport type {\n  IRealtimeService,\n  RealtimeEventPayload,\n  RealtimeSubscriptionOptions,\n} from '@objectstack/spec/contracts';\n\n/**\n * A single webhook delivery target.\n */\nexport interface WebhookSink {\n  /** Unique sink id used for log correlation. */\n  id: string;\n  /** Target HTTPS URL. */\n  url: string;\n  /** Optional HMAC-SHA256 secret. When set, `X-Objectstack-Signature: sha256=…` is added. */\n  secret?: string;\n  /**\n   * Restrict to specific object names (logical names, e.g. `lead`, `account`).\n   * Omit / empty → all objects.\n   */\n  objects?: string[];\n  /**\n   * Restrict to specific event types. Omit / empty → all `data.record.*` events.\n   */\n  eventTypes?: string[];\n  /** Extra headers to send (Authorization, Tenant, etc.). */\n  headers?: Record<string, string>;\n  /** Per-request timeout in milliseconds. Default 5000. */\n  timeoutMs?: number;\n  /** Retry attempts on transient failure. Default 3. Set 0 to disable retries. */\n  retries?: number;\n}\n\n/**\n * Delivery attempt outcome surfaced to in-process listeners / tests.\n */\nexport type WebhookDeliveryStatus = 'ok' | 'retrying' | 'failed';\n\nexport interface WebhookDeliveryRecord {\n  sinkId: string;\n  url: string;\n  eventType: string;\n  object?: string;\n  status: WebhookDeliveryStatus;\n  httpStatus?: number;\n  attempt: number;\n  error?: string;\n}\n\n/**\n * Plugin configuration.\n *\n * Sinks may be supplied programmatically OR via env vars when none are\n * passed (suitable for 12-factor / Docker deployments):\n *\n *   OBJECTSTACK_WEBHOOK_URL       — single URL, or comma-separated URLs.\n *   OBJECTSTACK_WEBHOOK_SECRET    — HMAC secret applied to all env-sourced URLs.\n *   OBJECTSTACK_WEBHOOK_OBJECTS   — comma-separated object whitelist.\n *   OBJECTSTACK_WEBHOOK_EVENTS    — comma-separated event-type whitelist\n *                                   (e.g. `data.record.created`).\n */\nexport interface WebhooksPluginOptions {\n  /** Explicit sink list (takes precedence over env vars). */\n  sinks?: WebhookSink[];\n  /** Override fetch (mainly for tests). Defaults to globalThis.fetch. */\n  fetchImpl?: typeof fetch;\n  /** Hook invoked with each delivery outcome (mainly for tests / metrics). */\n  onDelivery?: (record: WebhookDeliveryRecord) => void;\n}\n\nconst DEFAULT_TIMEOUT_MS = 5_000;\nconst DEFAULT_RETRIES = 3;\nconst BACKOFF_BASE_MS = 250;\nconst BACKOFF_MAX_MS = 5_000;\n\n/**\n * WebhooksPlugin — fan out data.record.* events to external HTTP endpoints.\n *\n * @example\n * ```ts\n * kernel.use(new WebhooksPlugin({\n *   sinks: [\n *     { id: 'crm-sync', url: 'https://hooks.example.com/in',\n *       secret: process.env.HOOK_SECRET, objects: ['lead', 'account'] },\n *   ],\n * }));\n * ```\n */\nexport class WebhooksPlugin implements Plugin {\n  name = 'com.objectstack.webhooks';\n  version = '1.0.0';\n  type = 'standard';\n  dependencies = ['com.objectstack.service.realtime'];\n\n  private readonly options: WebhooksPluginOptions;\n  private subscriptionIds: string[] = [];\n  private realtime?: IRealtimeService;\n  private sinks: WebhookSink[] = [];\n  private logger?: PluginContext['logger'];\n\n  constructor(options: WebhooksPluginOptions = {}) {\n    this.options = options;\n  }\n\n  async init(ctx: PluginContext): Promise<void> {\n    this.logger = ctx.logger;\n    this.sinks = this.resolveSinks();\n    if (this.sinks.length === 0) {\n      ctx.logger.info(\n        'WebhooksPlugin: no sinks configured (options.sinks empty and OBJECTSTACK_WEBHOOK_URL unset) — plugin is dormant',\n      );\n      return;\n    }\n    ctx.logger.info(`WebhooksPlugin: ${this.sinks.length} sink(s) configured`);\n  }\n\n  async start(ctx: PluginContext): Promise<void> {\n    if (this.sinks.length === 0) return;\n    ctx.hook('kernel:ready', async () => {\n      try {\n        this.realtime = ctx.getService<IRealtimeService>('realtime');\n      } catch {\n        ctx.logger.warn('WebhooksPlugin: realtime service unavailable — events will not be forwarded');\n        return;\n      }\n\n      // We subscribe once per sink so the realtime service can apply each\n      // sink's object / eventTypes filter at the channel layer where\n      // possible. This also lets us cleanly unsubscribe on stop().\n      for (const sink of this.sinks) {\n        const opts: RealtimeSubscriptionOptions | undefined =\n          (sink.objects && sink.objects.length === 1) ||\n          (sink.eventTypes && sink.eventTypes.length > 0)\n            ? {\n                ...(sink.objects && sink.objects.length === 1 ? { object: sink.objects[0] } : {}),\n                ...(sink.eventTypes && sink.eventTypes.length > 0 ? { eventTypes: sink.eventTypes } : {}),\n              }\n            : undefined;\n        const id = await this.realtime.subscribe(\n          'data.record',\n          async (event) => { await this.dispatch(sink, event); },\n          opts,\n        );\n        this.subscriptionIds.push(id);\n      }\n      ctx.logger.info(`WebhooksPlugin: subscribed ${this.subscriptionIds.length} realtime listener(s)`);\n    });\n  }\n\n  async stop(ctx: PluginContext): Promise<void> {\n    if (!this.realtime) return;\n    for (const id of this.subscriptionIds) {\n      try { await this.realtime.unsubscribe(id); }\n      catch (err) { ctx.logger.debug('WebhooksPlugin: unsubscribe failed', { id, err }); }\n    }\n    this.subscriptionIds = [];\n  }\n\n  /**\n   * Resolve sinks from constructor options, falling back to env vars when\n   * none provided. Exposed for testing.\n   */\n  private resolveSinks(): WebhookSink[] {\n    if (this.options.sinks && this.options.sinks.length > 0) return this.options.sinks;\n\n    const urlEnv = process.env.OBJECTSTACK_WEBHOOK_URL;\n    if (!urlEnv) return [];\n\n    const urls = urlEnv.split(',').map(s => s.trim()).filter(Boolean);\n    const secret = process.env.OBJECTSTACK_WEBHOOK_SECRET;\n    const objectsEnv = process.env.OBJECTSTACK_WEBHOOK_OBJECTS;\n    const eventsEnv = process.env.OBJECTSTACK_WEBHOOK_EVENTS;\n    const objects = objectsEnv ? objectsEnv.split(',').map(s => s.trim()).filter(Boolean) : undefined;\n    const eventTypes = eventsEnv ? eventsEnv.split(',').map(s => s.trim()).filter(Boolean) : undefined;\n\n    return urls.map((url, idx) => ({\n      id: `env-${idx + 1}`,\n      url,\n      ...(secret ? { secret } : {}),\n      ...(objects ? { objects } : {}),\n      ...(eventTypes ? { eventTypes } : {}),\n    }));\n  }\n\n  /**\n   * Dispatch a single event to a sink, with HMAC signing, timeout, and\n   * exponential-backoff retry. Failures past the retry budget are logged\n   * but never thrown — webhook delivery must never break the originating\n   * mutation.\n   */\n  private async dispatch(sink: WebhookSink, event: RealtimeEventPayload): Promise<void> {\n    // Defence in depth: the realtime layer already filters by single-object\n    // subscriptions, but multi-object whitelists are applied here.\n    if (sink.objects && sink.objects.length > 0 && event.object && !sink.objects.includes(event.object)) {\n      return;\n    }\n    if (sink.eventTypes && sink.eventTypes.length > 0 && !sink.eventTypes.includes(event.type)) {\n      return;\n    }\n\n    const fetchImpl = this.options.fetchImpl ?? globalThis.fetch;\n    if (!fetchImpl) {\n      this.logger?.warn('WebhooksPlugin: no fetch implementation available — dropping event', { sinkId: sink.id });\n      return;\n    }\n\n    const body = JSON.stringify(event);\n    const headers: Record<string, string> = {\n      'Content-Type': 'application/json',\n      'User-Agent': 'ObjectStack-Webhooks/1.0',\n      'X-Objectstack-Event': event.type,\n      ...(event.object ? { 'X-Objectstack-Object': event.object } : {}),\n      'X-Objectstack-Delivery': crypto.randomUUID(),\n      ...(sink.headers ?? {}),\n    };\n    if (sink.secret) {\n      const sig = crypto.createHmac('sha256', sink.secret).update(body).digest('hex');\n      headers['X-Objectstack-Signature'] = `sha256=${sig}`;\n    }\n\n    const timeoutMs = sink.timeoutMs ?? DEFAULT_TIMEOUT_MS;\n    const maxAttempts = (sink.retries ?? DEFAULT_RETRIES) + 1;\n\n    for (let attempt = 1; attempt <= maxAttempts; attempt++) {\n      const controller = new AbortController();\n      const timer = setTimeout(() => controller.abort(), timeoutMs);\n      try {\n        const res = await fetchImpl(sink.url, {\n          method: 'POST',\n          headers,\n          body,\n          signal: controller.signal,\n        });\n        clearTimeout(timer);\n        if (res.ok || (res.status >= 400 && res.status < 500)) {\n          // 4xx is \"permanent\" — don't retry; only 2xx counts as success.\n          const status: WebhookDeliveryStatus = res.ok ? 'ok' : 'failed';\n          this.options.onDelivery?.({\n            sinkId: sink.id, url: sink.url, eventType: event.type,\n            object: event.object, status, httpStatus: res.status, attempt,\n          });\n          if (status === 'failed') {\n            this.logger?.warn('WebhooksPlugin: sink rejected event', {\n              sinkId: sink.id, status: res.status, eventType: event.type,\n            });\n          }\n          return;\n        }\n        // 5xx → fall through to retry.\n        if (attempt === maxAttempts) {\n          this.options.onDelivery?.({\n            sinkId: sink.id, url: sink.url, eventType: event.type, object: event.object,\n            status: 'failed', httpStatus: res.status, attempt,\n          });\n          this.logger?.warn('WebhooksPlugin: max retries exhausted', {\n            sinkId: sink.id, status: res.status, eventType: event.type,\n          });\n          return;\n        }\n        this.options.onDelivery?.({\n          sinkId: sink.id, url: sink.url, eventType: event.type, object: event.object,\n          status: 'retrying', httpStatus: res.status, attempt,\n        });\n      } catch (err: any) {\n        clearTimeout(timer);\n        const errMessage = err?.name === 'AbortError'\n          ? `timeout after ${timeoutMs}ms`\n          : (err?.message ?? String(err));\n        if (attempt === maxAttempts) {\n          this.options.onDelivery?.({\n            sinkId: sink.id, url: sink.url, eventType: event.type, object: event.object,\n            status: 'failed', attempt, error: errMessage,\n          });\n          this.logger?.warn('WebhooksPlugin: delivery failed', {\n            sinkId: sink.id, eventType: event.type, error: errMessage,\n          });\n          return;\n        }\n        this.options.onDelivery?.({\n          sinkId: sink.id, url: sink.url, eventType: event.type, object: event.object,\n          status: 'retrying', attempt, error: errMessage,\n        });\n      }\n      // Exponential backoff with full jitter.\n      const delay = Math.min(BACKOFF_MAX_MS, BACKOFF_BASE_MS * 2 ** (attempt - 1));\n      const jittered = Math.floor(Math.random() * delay);\n      await new Promise(r => setTimeout(r, jittered));\n    }\n  }\n}\n"],"mappings":"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","names":[]}

package/package.json

@@ -0,0 +1,34 @@
+{
+  "name": "@objectstack/plugin-webhooks",
+  "version": "4.0.1",
+  "license": "Apache-2.0",
+  "description": "Outbound webhook delivery plugin for ObjectStack — fan-out data.record.* events to external HTTP(S) sinks with HMAC signing and retry.",
+  "main": "dist/index.js",
+  "types": "dist/index.d.ts",
+  "exports": {
+    ".": {
+      "types": "./dist/index.d.ts",
+      "import": "./dist/index.mjs",
+      "require": "./dist/index.js"
+    }
+  },
+  "dependencies": {
+    "@objectstack/core": "4.1.0",
+    "@objectstack/spec": "4.1.0"
+  },
+  "devDependencies": {
+    "@types/node": "^25.9.1",
+    "typescript": "^6.0.3",
+    "vitest": "^4.1.7"
+  },
+  "keywords": [
+    "objectstack",
+    "plugin",
+    "webhooks",
+    "events"
+  ],
+  "scripts": {
+    "build": "tsup --config ../../../tsup.config.ts",
+    "test": "vitest run --passWithNoTests"
+  }
+}

package/src/index.ts

@@ -0,0 +1,19 @@
+// Copyright (c) 2025 ObjectStack. Licensed under the Apache-2.0 license.
+
+/**
+ * @objectstack/plugin-webhooks
+ *
+ * Outbound webhook delivery for `data.record.created`,
+ * `data.record.updated`, and `data.record.deleted` events. Subscribes to
+ * the realtime service, fans events out to one or more configured HTTP
+ * sinks, signs each request with HMAC-SHA256, and retries transient
+ * failures with exponential backoff.
+ */
+
+export { WebhooksPlugin } from './webhooks-plugin.js';
+export type {
+  WebhooksPluginOptions,
+  WebhookSink,
+  WebhookDeliveryRecord,
+  WebhookDeliveryStatus,
+} from './webhooks-plugin.js';