@fonderie/webhooks 1.0.0

package/dist/index.d.cts

@@ -0,0 +1,68 @@
+import { IFonderieModule, IFonderieApp } from '@fonderie/core';
+import { IStoreAdapter } from '@fonderie/store';
+import { EventBus } from '@fonderie/events';
+
+interface IWebhooksConfig {
+    maxAttempts?: number;
+    retryDelays?: number[];
+    retryInterval?: number;
+}
+
+declare class WebhooksModule implements IFonderieModule {
+    private readonly store;
+    private readonly config;
+    private readonly bus?;
+    readonly name = "@fonderie/webhooks";
+    readonly deps: string[];
+    private retryTimer?;
+    constructor(store: IStoreAdapter, config?: IWebhooksConfig, bus?: EventBus | undefined);
+    install(app: IFonderieApp): void;
+}
+
+type DeliveryStatus = 'pending' | 'delivered' | 'failed';
+interface IWebhookEndpoint {
+    id: string;
+    workspaceId: string;
+    url: string;
+    secret: string;
+    events: string[];
+    enabled: boolean;
+    createdAt: Date;
+}
+interface IWebhookDelivery {
+    id: string;
+    endpointId: string;
+    eventId: string;
+    eventType: string;
+    payload: Record<string, unknown>;
+    status: DeliveryStatus;
+    attempts: number;
+    responseStatus: number | null;
+    responseBody: string | null;
+    nextAttemptAt: Date | null;
+    deliveredAt: Date | null;
+    createdAt: Date;
+}
+
+interface IWebhookEndpointDTO {
+    id: string;
+    url: string;
+    events: string[];
+    enabled: boolean;
+    createdAt: string;
+}
+interface IWebhookEndpointCreatedDTO extends IWebhookEndpointDTO {
+    secret: string;
+}
+interface IWebhookDeliveryDTO {
+    id: string;
+    eventId: string;
+    eventType: string;
+    status: string;
+    attempts: number;
+    responseStatus: number | null;
+    deliveredAt: string | null;
+    createdAt: string;
+}
+
+export { type DeliveryStatus, type IWebhookDelivery, type IWebhookDeliveryDTO, type IWebhookEndpoint, type IWebhookEndpointCreatedDTO, type IWebhookEndpointDTO, type IWebhooksConfig, WebhooksModule };

package/dist/index.d.ts

@@ -0,0 +1,68 @@
+import { IFonderieModule, IFonderieApp } from '@fonderie/core';
+import { IStoreAdapter } from '@fonderie/store';
+import { EventBus } from '@fonderie/events';
+
+interface IWebhooksConfig {
+    maxAttempts?: number;
+    retryDelays?: number[];
+    retryInterval?: number;
+}
+
+declare class WebhooksModule implements IFonderieModule {
+    private readonly store;
+    private readonly config;
+    private readonly bus?;
+    readonly name = "@fonderie/webhooks";
+    readonly deps: string[];
+    private retryTimer?;
+    constructor(store: IStoreAdapter, config?: IWebhooksConfig, bus?: EventBus | undefined);
+    install(app: IFonderieApp): void;
+}
+
+type DeliveryStatus = 'pending' | 'delivered' | 'failed';
+interface IWebhookEndpoint {
+    id: string;
+    workspaceId: string;
+    url: string;
+    secret: string;
+    events: string[];
+    enabled: boolean;
+    createdAt: Date;
+}
+interface IWebhookDelivery {
+    id: string;
+    endpointId: string;
+    eventId: string;
+    eventType: string;
+    payload: Record<string, unknown>;
+    status: DeliveryStatus;
+    attempts: number;
+    responseStatus: number | null;
+    responseBody: string | null;
+    nextAttemptAt: Date | null;
+    deliveredAt: Date | null;
+    createdAt: Date;
+}
+
+interface IWebhookEndpointDTO {
+    id: string;
+    url: string;
+    events: string[];
+    enabled: boolean;
+    createdAt: string;
+}
+interface IWebhookEndpointCreatedDTO extends IWebhookEndpointDTO {
+    secret: string;
+}
+interface IWebhookDeliveryDTO {
+    id: string;
+    eventId: string;
+    eventType: string;
+    status: string;
+    attempts: number;
+    responseStatus: number | null;
+    deliveredAt: string | null;
+    createdAt: string;
+}
+
+export { type DeliveryStatus, type IWebhookDelivery, type IWebhookDeliveryDTO, type IWebhookEndpoint, type IWebhookEndpointCreatedDTO, type IWebhookEndpointDTO, type IWebhooksConfig, WebhooksModule };

package/dist/index.js

@@ -0,0 +1,492 @@
+// src/models/endpoint.model.ts
+var COLS = `id, workspace_id as "workspaceId", url, secret, events,
+              enabled, created_at as "createdAt"`;
+var EndpointModel = class {
+  constructor(store) {
+    this.store = store;
+  }
+  store;
+  async create(data) {
+    const [row] = await this.store.query(
+      `INSERT INTO fonderie_webhook_endpoints (workspace_id, url, secret, events)
+			 VALUES ($1, $2, $3, $4)
+			 RETURNING ${COLS}`,
+      [data.workspaceId, data.url, data.secret, data.events]
+    );
+    return row;
+  }
+  list(workspaceId) {
+    return this.store.query(
+      `SELECT ${COLS} FROM fonderie_webhook_endpoints
+			 WHERE workspace_id = $1
+			 ORDER BY created_at DESC`,
+      [workspaceId]
+    );
+  }
+  async findById(id, workspaceId) {
+    const [row] = await this.store.query(
+      `SELECT ${COLS} FROM fonderie_webhook_endpoints
+			 WHERE id = $1 AND workspace_id = $2`,
+      [id, workspaceId]
+    );
+    return row ?? null;
+  }
+  async update(id, workspaceId, data) {
+    const sets = [];
+    const params = [id, workspaceId];
+    if (data.url !== void 0) {
+      params.push(data.url);
+      sets.push(`url = $${params.length}`);
+    }
+    if (data.events !== void 0) {
+      params.push(data.events);
+      sets.push(`events = $${params.length}`);
+    }
+    if (data.enabled !== void 0) {
+      params.push(data.enabled);
+      sets.push(`enabled = $${params.length}`);
+    }
+    if (sets.length === 0) return this.findById(id, workspaceId);
+    const [row] = await this.store.query(
+      `UPDATE fonderie_webhook_endpoints SET ${sets.join(", ")}
+			 WHERE id = $1 AND workspace_id = $2
+			 RETURNING ${COLS}`,
+      params
+    );
+    return row ?? null;
+  }
+  async delete(id, workspaceId) {
+    const rows = await this.store.query(
+      `DELETE FROM fonderie_webhook_endpoints WHERE id = $1 AND workspace_id = $2 RETURNING id`,
+      [id, workspaceId]
+    );
+    return rows.length > 0;
+  }
+  findForEvent(workspaceId, eventType) {
+    return this.store.query(
+      `SELECT ${COLS} FROM fonderie_webhook_endpoints
+			 WHERE workspace_id = $1
+			   AND enabled = true
+			   AND (events = '{}' OR $2 = ANY(events))`,
+      [workspaceId, eventType]
+    );
+  }
+};
+
+// src/models/delivery.model.ts
+var COLS2 = `id, endpoint_id as "endpointId", event_id as "eventId",
+              event_type as "eventType", payload, status, attempts,
+              response_status as "responseStatus", response_body as "responseBody",
+              next_attempt_at as "nextAttemptAt", delivered_at as "deliveredAt",
+              created_at as "createdAt"`;
+var D_COLS = `d.id, d.endpoint_id as "endpointId", d.event_id as "eventId",
+                d.event_type as "eventType", d.payload, d.status, d.attempts,
+                d.response_status as "responseStatus", d.response_body as "responseBody",
+                d.next_attempt_at as "nextAttemptAt", d.delivered_at as "deliveredAt",
+                d.created_at as "createdAt"`;
+var DeliveryModel = class {
+  constructor(store) {
+    this.store = store;
+  }
+  store;
+  async create(data) {
+    const [row] = await this.store.query(
+      `INSERT INTO fonderie_webhook_deliveries (endpoint_id, event_id, event_type, payload)
+			 VALUES ($1, $2, $3, $4)
+			 RETURNING ${COLS2}`,
+      [data.endpointId, data.eventId, data.eventType, JSON.stringify(data.payload)]
+    );
+    return row;
+  }
+  async markResult(id, result) {
+    await this.store.query(
+      `UPDATE fonderie_webhook_deliveries
+			 SET status          = $2,
+			     attempts        = attempts + 1,
+			     response_status = $3,
+			     response_body   = $4,
+			     next_attempt_at = $5,
+			     delivered_at    = $6
+			 WHERE id = $1`,
+      [
+        id,
+        result.ok ? "delivered" : "failed",
+        result.responseStatus,
+        result.responseBody,
+        result.nextAttemptAt,
+        result.ok ? /* @__PURE__ */ new Date() : null
+      ]
+    );
+  }
+  listByEndpoint(endpointId, limit = 50) {
+    return this.store.query(
+      `SELECT ${COLS2} FROM fonderie_webhook_deliveries
+			 WHERE endpoint_id = $1
+			 ORDER BY created_at DESC
+			 LIMIT $2`,
+      [endpointId, limit]
+    );
+  }
+  claimForRetry(limit = 10) {
+    return this.store.query(
+      `SELECT ${D_COLS},
+			        e.url, e.secret
+			 FROM   fonderie_webhook_deliveries d
+			 JOIN   fonderie_webhook_endpoints  e ON e.id = d.endpoint_id
+			 WHERE  d.status = 'failed'
+			   AND  d.next_attempt_at IS NOT NULL
+			   AND  d.next_attempt_at <= now()
+			   AND  e.enabled = true
+			 ORDER  BY d.next_attempt_at
+			 LIMIT  $1`,
+      [limit]
+    );
+  }
+};
+
+// src/signing.ts
+import { createHmac, randomBytes } from "crypto";
+function generateSecret() {
+  return randomBytes(32).toString("hex");
+}
+function signPayload(secret, body) {
+  return `sha256=${createHmac("sha256", secret).update(body).digest("hex")}`;
+}
+
+// src/dispatcher.ts
+var WebhookDispatcher = class {
+  constructor(store, config = {}) {
+    this.store = store;
+    this.config = config;
+    this.maxAttempts = config.maxAttempts ?? 3;
+    this.retryDelays = config.retryDelays ?? [6e4, 3e5, 18e5];
+  }
+  store;
+  config;
+  maxAttempts;
+  retryDelays;
+  // Called by the bus consumer for every event.
+  // Skips events that don't carry a workspaceId — not workspace-scoped.
+  async dispatch(payload, meta) {
+    const workspaceId = payload["workspaceId"];
+    if (typeof workspaceId !== "string") return;
+    const endpoints = await new EndpointModel(this.store).findForEvent(workspaceId, meta.type);
+    if (endpoints.length === 0) return;
+    const deliveries = new DeliveryModel(this.store);
+    await Promise.allSettled(endpoints.map((ep) => this.deliver(ep, payload, meta, deliveries)));
+  }
+  // Retries failed deliveries whose next_attempt_at has passed.
+  async retry() {
+    const deliveries = new DeliveryModel(this.store);
+    const pending = await deliveries.claimForRetry();
+    await Promise.allSettled(
+      pending.map(
+        ({ delivery, url, secret }) => this.attemptDelivery(url, secret, delivery, deliveries)
+      )
+    );
+  }
+  async deliver(endpoint, payload, meta, deliveries) {
+    const delivery = await deliveries.create({
+      endpointId: endpoint.id,
+      eventId: meta.id,
+      eventType: meta.type,
+      payload
+    });
+    await this.attemptDelivery(endpoint.url, endpoint.secret, delivery, deliveries);
+  }
+  async attemptDelivery(url, secret, delivery, deliveries) {
+    const body = JSON.stringify({
+      id: delivery.eventId,
+      type: delivery.eventType,
+      data: delivery.payload
+    });
+    const signature = signPayload(secret, body);
+    try {
+      const res = await fetch(url, {
+        method: "POST",
+        headers: {
+          "Content-Type": "application/json",
+          "X-Webhook-Signature": signature,
+          "X-Webhook-Event": delivery.eventType,
+          "X-Webhook-ID": delivery.id
+        },
+        body,
+        signal: AbortSignal.timeout(1e4)
+      });
+      const responseBody = await res.text().catch(() => "");
+      await deliveries.markResult(delivery.id, {
+        ok: res.ok,
+        responseStatus: res.status,
+        responseBody,
+        nextAttemptAt: res.ok ? null : this.nextRetryAt(delivery.attempts)
+      });
+    } catch (err) {
+      await deliveries.markResult(delivery.id, {
+        ok: false,
+        responseStatus: null,
+        responseBody: err instanceof Error ? err.message : String(err),
+        nextAttemptAt: this.nextRetryAt(delivery.attempts)
+      });
+    }
+  }
+  nextRetryAt(currentAttempts) {
+    if (currentAttempts + 1 >= this.maxAttempts) return null;
+    const delay = this.retryDelays[currentAttempts] ?? this.retryDelays[this.retryDelays.length - 1];
+    return new Date(Date.now() + delay);
+  }
+};
+
+// src/routes.ts
+import { setApiResponse, HTTP } from "@fonderie/core";
+import { requireAuth } from "@fonderie/core/middlewares";
+import { withBody } from "@fonderie/core/middlewares";
+
+// src/dtos/webhook.ts
+function toEndpointDTO(e) {
+  return {
+    id: e.id,
+    url: e.url,
+    events: e.events,
+    enabled: e.enabled,
+    createdAt: e.createdAt.toISOString()
+  };
+}
+function toEndpointCreatedDTO(e) {
+  return { ...toEndpointDTO(e), secret: e.secret };
+}
+function toDeliveryDTO(d) {
+  return {
+    id: d.id,
+    eventId: d.eventId,
+    eventType: d.eventType,
+    status: d.status,
+    attempts: d.attempts,
+    responseStatus: d.responseStatus,
+    deliveredAt: d.deliveredAt?.toISOString() ?? null,
+    createdAt: d.createdAt.toISOString()
+  };
+}
+
+// src/routes.ts
+function buildWebhookRoutes(store, config = {}) {
+  return [
+    [
+      "POST",
+      "/webhooks",
+      requireAuth,
+      withBody,
+      async (ctx) => {
+        if (!ctx.workspace)
+          return setApiResponse(
+            HTTP.UNPROCESSABLE,
+            "MISSING_WORKSPACE",
+            "Workspace context required"
+          );
+        const body = ctx.meta["body"];
+        if (!body?.url)
+          return setApiResponse(HTTP.UNPROCESSABLE, "MISSING_FIELD", "url is required");
+        const endpoint = await new EndpointModel(store).create({
+          workspaceId: ctx.workspace.id,
+          url: body.url,
+          secret: generateSecret(),
+          events: body.events ?? []
+        });
+        return setApiResponse(
+          HTTP.CREATED,
+          "WEBHOOK_CREATED",
+          "Webhook endpoint registered.",
+          toEndpointCreatedDTO(endpoint)
+        );
+      }
+    ],
+    [
+      "GET",
+      "/webhooks",
+      requireAuth,
+      async (ctx) => {
+        if (!ctx.workspace)
+          return setApiResponse(
+            HTTP.UNPROCESSABLE,
+            "MISSING_WORKSPACE",
+            "Workspace context required"
+          );
+        const list = await new EndpointModel(store).list(ctx.workspace.id);
+        return setApiResponse(HTTP.OK, "WEBHOOKS_FETCHED", "Webhook endpoints retrieved.", {
+          endpoints: list.map(toEndpointDTO)
+        });
+      }
+    ],
+    [
+      "GET",
+      "/webhooks/:endpointId",
+      requireAuth,
+      async (ctx) => {
+        if (!ctx.workspace)
+          return setApiResponse(
+            HTTP.UNPROCESSABLE,
+            "MISSING_WORKSPACE",
+            "Workspace context required"
+          );
+        const { endpointId } = ctx.meta["params"];
+        const endpoint = await new EndpointModel(store).findById(endpointId, ctx.workspace.id);
+        if (!endpoint)
+          return setApiResponse(HTTP.NOT_FOUND, "NOT_FOUND", "Webhook endpoint not found");
+        return setApiResponse(
+          HTTP.OK,
+          "WEBHOOK_FETCHED",
+          "Webhook endpoint retrieved.",
+          toEndpointDTO(endpoint)
+        );
+      }
+    ],
+    [
+      "PATCH",
+      "/webhooks/:endpointId",
+      requireAuth,
+      withBody,
+      async (ctx) => {
+        if (!ctx.workspace)
+          return setApiResponse(
+            HTTP.UNPROCESSABLE,
+            "MISSING_WORKSPACE",
+            "Workspace context required"
+          );
+        const { endpointId } = ctx.meta["params"];
+        const body = ctx.meta["body"];
+        const patch = {};
+        if (body?.url !== void 0) patch.url = body.url;
+        if (body?.events !== void 0) patch.events = body.events;
+        if (body?.enabled !== void 0) patch.enabled = body.enabled;
+        const updated = await new EndpointModel(store).update(endpointId, ctx.workspace.id, patch);
+        if (!updated)
+          return setApiResponse(HTTP.NOT_FOUND, "NOT_FOUND", "Webhook endpoint not found");
+        return setApiResponse(
+          HTTP.OK,
+          "WEBHOOK_UPDATED",
+          "Webhook endpoint updated.",
+          toEndpointDTO(updated)
+        );
+      }
+    ],
+    [
+      "DELETE",
+      "/webhooks/:endpointId",
+      requireAuth,
+      async (ctx) => {
+        if (!ctx.workspace)
+          return setApiResponse(
+            HTTP.UNPROCESSABLE,
+            "MISSING_WORKSPACE",
+            "Workspace context required"
+          );
+        const { endpointId } = ctx.meta["params"];
+        const deleted = await new EndpointModel(store).delete(endpointId, ctx.workspace.id);
+        if (!deleted)
+          return setApiResponse(HTTP.NOT_FOUND, "NOT_FOUND", "Webhook endpoint not found");
+        return new Response(null, { status: HTTP.NO_CONTENT });
+      }
+    ],
+    [
+      "GET",
+      "/webhooks/:endpointId/deliveries",
+      requireAuth,
+      async (ctx) => {
+        if (!ctx.workspace)
+          return setApiResponse(
+            HTTP.UNPROCESSABLE,
+            "MISSING_WORKSPACE",
+            "Workspace context required"
+          );
+        const { endpointId } = ctx.meta["params"];
+        const endpoint = await new EndpointModel(store).findById(endpointId, ctx.workspace.id);
+        if (!endpoint)
+          return setApiResponse(HTTP.NOT_FOUND, "NOT_FOUND", "Webhook endpoint not found");
+        const list = await new DeliveryModel(store).listByEndpoint(endpointId);
+        return setApiResponse(HTTP.OK, "DELIVERIES_FETCHED", "Deliveries retrieved.", {
+          deliveries: list.map(toDeliveryDTO)
+        });
+      }
+    ],
+    [
+      "POST",
+      "/webhooks/:endpointId/test",
+      requireAuth,
+      async (ctx) => {
+        if (!ctx.workspace)
+          return setApiResponse(
+            HTTP.UNPROCESSABLE,
+            "MISSING_WORKSPACE",
+            "Workspace context required"
+          );
+        const { endpointId } = ctx.meta["params"];
+        const endpoint = await new EndpointModel(store).findById(endpointId, ctx.workspace.id);
+        if (!endpoint)
+          return setApiResponse(HTTP.NOT_FOUND, "NOT_FOUND", "Webhook endpoint not found");
+        const body = JSON.stringify({
+          id: `test-${Date.now()}`,
+          type: "webhook.test",
+          data: { workspaceId: ctx.workspace.id, message: "Test webhook delivery." }
+        });
+        try {
+          const res = await fetch(endpoint.url, {
+            method: "POST",
+            headers: {
+              "Content-Type": "application/json",
+              "X-Webhook-Signature": signPayload(endpoint.secret, body),
+              "X-Webhook-Event": "webhook.test"
+            },
+            body,
+            signal: AbortSignal.timeout(1e4)
+          });
+          return setApiResponse(HTTP.OK, "TEST_SENT", "Test delivery attempted.", {
+            status: res.status,
+            ok: res.ok
+          });
+        } catch (err) {
+          return setApiResponse(HTTP.OK, "TEST_SENT", "Test delivery attempted.", {
+            status: null,
+            ok: false,
+            error: err instanceof Error ? err.message : String(err)
+          });
+        }
+      }
+    ]
+  ];
+}
+
+// src/module.ts
+var WebhooksModule = class {
+  constructor(store, config = {}, bus) {
+    this.store = store;
+    this.config = config;
+    this.bus = bus;
+  }
+  store;
+  config;
+  bus;
+  name = "@fonderie/webhooks";
+  deps = ["@fonderie/auth", "@fonderie/workspaces"];
+  retryTimer;
+  install(app) {
+    const dispatcher = new WebhookDispatcher(this.store, this.config);
+    this.bus?.on(
+      "*",
+      async (payload, meta) => {
+        await dispatcher.dispatch(payload, meta);
+      },
+      "webhooks"
+    );
+    const interval = this.config.retryInterval ?? 6e4;
+    this.retryTimer = setInterval(() => {
+      dispatcher.retry().catch((err) => console.error("[webhooks] retry error:", err));
+    }, interval);
+    const routes = buildWebhookRoutes(this.store, this.config);
+    for (const [method, path, ...handlers] of routes) {
+      app.addRoute(method, path, ...handlers);
+    }
+  }
+};
+export {
+  WebhooksModule
+};
+//# sourceMappingURL=index.js.map