@nexpress/plugin-webhook-relay 0.2.0

package/dist/index.d.ts

@@ -0,0 +1,31 @@
+import * as _nexpress_plugin_sdk from '@nexpress/plugin-sdk';
+import { z } from 'zod';
+
+declare const configSchema: z.ZodObject<{
+    endpointUrl: z.ZodOptional<z.ZodString>;
+    signingSecret: z.ZodOptional<z.ZodString>;
+    includeDrafts: z.ZodDefault<z.ZodBoolean>;
+    timeoutMs: z.ZodDefault<z.ZodNumber>;
+}, z.core.$strip>;
+type WebhookRelayConfig = z.infer<typeof configSchema>;
+interface WebhookRelayPayload {
+    event: string;
+    collection: string;
+    documentId: string | null;
+    status: string | null;
+    at: string;
+}
+type HookData = Record<string, unknown> & {
+    collection?: string;
+    doc?: Record<string, unknown>;
+};
+declare function buildPayload(event: string, data: HookData): WebhookRelayPayload;
+declare function signPayload(payload: WebhookRelayPayload, secret: string): string;
+declare const webhookRelayPlugin: _nexpress_plugin_sdk.NpResolvedPlugin<{
+    includeDrafts: boolean;
+    timeoutMs: number;
+    endpointUrl?: string | undefined;
+    signingSecret?: string | undefined;
+}>;
+
+export { type WebhookRelayConfig, type WebhookRelayPayload, buildPayload, webhookRelayPlugin as default, signPayload, webhookRelayPlugin };

package/dist/index.js

@@ -0,0 +1,129 @@
+// src/index.ts
+import { createHmac } from "crypto";
+import {
+  definePlugin,
+  npAdminActionError,
+  npAdminStatus
+} from "@nexpress/plugin-sdk";
+import { z } from "zod";
+var configSchema = z.object({
+  endpointUrl: z.string().url().optional().describe("Webhook endpoint URL"),
+  signingSecret: z.string().optional().describe("Optional HMAC signing secret").meta({ sensitive: true }),
+  includeDrafts: z.boolean().default(false).describe("Send draft document events"),
+  timeoutMs: z.number().int().min(500).max(3e4).default(5e3).describe("Request timeout")
+});
+function pickDoc(data) {
+  return data.doc && typeof data.doc === "object" ? data.doc : data;
+}
+function buildPayload(event, data) {
+  const doc = pickDoc(data);
+  const id = typeof doc.id === "string" ? doc.id : null;
+  const status = typeof doc.status === "string" ? doc.status : null;
+  const collection = typeof data.collection === "string" ? data.collection : "unknown";
+  return {
+    event,
+    collection,
+    documentId: id,
+    status,
+    at: (/* @__PURE__ */ new Date()).toISOString()
+  };
+}
+function signPayload(payload, secret) {
+  return createHmac("sha256", secret).update(JSON.stringify(payload)).digest("hex");
+}
+var webhookRelayPlugin = definePlugin({
+  manifest: {
+    id: "webhook-relay",
+    version: "0.1.0",
+    name: "Webhook Relay",
+    description: "Relays content lifecycle events to a configured webhook endpoint and exposes admin delivery diagnostics.",
+    author: { name: "NexPress" },
+    license: "MIT",
+    nexpress: { minVersion: "0.1.0" },
+    allowedHosts: ["*"],
+    capabilities: ["network:fetch", "storage:kv"],
+    agent: {
+      description: "Integration plugin example that combines content hooks, outbound fetch, plugin storage, and declarative admin widgets.",
+      category: "integration",
+      tags: ["webhook", "integration", "content-hooks", "admin"]
+    }
+  },
+  configSchema,
+  hooks: {
+    "content:afterCreate": ({ data, ctx }) => deliver("content:afterCreate", data, ctx),
+    "content:afterUpdate": ({ data, ctx }) => deliver("content:afterUpdate", data, ctx),
+    "content:afterDelete": ({ data, ctx }) => deliver("content:afterDelete", data, ctx)
+  },
+  admin: {
+    widgets: [
+      {
+        id: "last-delivery",
+        label: "Last delivery",
+        kind: "status",
+        actionId: "lastDelivery"
+      }
+    ],
+    actions: [
+      {
+        id: "test-delivery",
+        label: "Send test delivery",
+        actionId: "sendTest",
+        confirm: "Send a test webhook delivery now?"
+      }
+    ]
+  },
+  setup: (ctx) => {
+    ctx.actions.registerStatus("lastDelivery", async () => {
+      const last = await ctx.storage.get("last-delivery");
+      return last ? npAdminStatus(last.ok ? "ok" : "warn", last.message) : npAdminStatus("warn", "No deliveries recorded yet.");
+    });
+    ctx.actions.register("sendTest", async () => {
+      const result = await deliver(
+        "webhook:test",
+        { collection: "test", doc: { id: "test", status: "published" } },
+        ctx
+      );
+      return result.ok ? { ok: true, data: result.message } : npAdminActionError(result.message);
+    });
+  }
+});
+async function deliver(event, data, ctx) {
+  const payload = buildPayload(event, data);
+  if (!ctx.config.includeDrafts && payload.status === "draft") {
+    return { ok: true, message: "Skipped draft document." };
+  }
+  if (!ctx.config.endpointUrl) {
+    const message2 = "Webhook endpoint is not configured.";
+    await ctx.storage.set("last-delivery", { ok: false, message: message2 }, { ttl: 30 * 24 * 60 * 60 });
+    return { ok: false, message: message2 };
+  }
+  const headers = { "content-type": "application/json" };
+  if (ctx.config.signingSecret) {
+    headers["x-np-signature"] = signPayload(payload, ctx.config.signingSecret);
+  }
+  const res = await ctx.http.fetch(ctx.config.endpointUrl, {
+    method: "POST",
+    headers,
+    body: { ...payload },
+    timeoutMs: ctx.config.timeoutMs
+  });
+  const ok = res.ok;
+  const message = ok ? `Delivered ${payload.event}` : `Endpoint returned HTTP ${res.status}`;
+  await ctx.storage.set(
+    "last-delivery",
+    { ok, message, at: payload.at },
+    { ttl: 30 * 24 * 60 * 60 }
+  );
+  if (!ok) {
+    ctx.log.warn("Webhook delivery failed", { status: String(res.status), event: payload.event });
+  }
+  return { ok, message };
+}
+var index_default = webhookRelayPlugin;
+export {
+  buildPayload,
+  index_default as default,
+  signPayload,
+  webhookRelayPlugin
+};
+//# sourceMappingURL=index.js.map

package/dist/index.js.map

@@ -0,0 +1 @@
+{"version":3,"sources":["../src/index.ts"],"sourcesContent":["import { createHmac } from \"node:crypto\";\n\nimport {\n  definePlugin,\n  npAdminActionError,\n  npAdminStatus,\n  type NpPluginContext,\n} from \"@nexpress/plugin-sdk\";\nimport { z } from \"zod\";\n\nconst configSchema = z.object({\n  endpointUrl: z.string().url().optional().describe(\"Webhook endpoint URL\"),\n  signingSecret: z\n    .string()\n    .optional()\n    .describe(\"Optional HMAC signing secret\")\n    .meta({ sensitive: true }),\n  includeDrafts: z.boolean().default(false).describe(\"Send draft document events\"),\n  timeoutMs: z.number().int().min(500).max(30000).default(5000).describe(\"Request timeout\"),\n});\n\nexport type WebhookRelayConfig = z.infer<typeof configSchema>;\n\nexport interface WebhookRelayPayload {\n  event: string;\n  collection: string;\n  documentId: string | null;\n  status: string | null;\n  at: string;\n}\n\ntype HookData = Record<string, unknown> & {\n  collection?: string;\n  doc?: Record<string, unknown>;\n};\n\nfunction pickDoc(data: HookData): Record<string, unknown> {\n  return data.doc && typeof data.doc === \"object\" ? data.doc : data;\n}\n\nexport function buildPayload(event: string, data: HookData): WebhookRelayPayload {\n  const doc = pickDoc(data);\n  const id = typeof doc.id === \"string\" ? doc.id : null;\n  const status = typeof doc.status === \"string\" ? doc.status : null;\n  const collection = typeof data.collection === \"string\" ? data.collection : \"unknown\";\n\n  return {\n    event,\n    collection,\n    documentId: id,\n    status,\n    at: new Date().toISOString(),\n  };\n}\n\nexport function signPayload(payload: WebhookRelayPayload, secret: string): string {\n  return createHmac(\"sha256\", secret).update(JSON.stringify(payload)).digest(\"hex\");\n}\n\nexport const webhookRelayPlugin = definePlugin<WebhookRelayConfig>({\n  manifest: {\n    id: \"webhook-relay\",\n    version: \"0.1.0\",\n    name: \"Webhook Relay\",\n    description:\n      \"Relays content lifecycle events to a configured webhook endpoint and exposes admin delivery diagnostics.\",\n    author: { name: \"NexPress\" },\n    license: \"MIT\",\n    nexpress: { minVersion: \"0.1.0\" },\n    allowedHosts: [\"*\"],\n    capabilities: [\"network:fetch\", \"storage:kv\"],\n    agent: {\n      description:\n        \"Integration plugin example that combines content hooks, outbound fetch, plugin storage, and declarative admin widgets.\",\n      category: \"integration\",\n      tags: [\"webhook\", \"integration\", \"content-hooks\", \"admin\"],\n    },\n  },\n  configSchema,\n  hooks: {\n    \"content:afterCreate\": ({ data, ctx }) => deliver(\"content:afterCreate\", data, ctx),\n    \"content:afterUpdate\": ({ data, ctx }) => deliver(\"content:afterUpdate\", data, ctx),\n    \"content:afterDelete\": ({ data, ctx }) => deliver(\"content:afterDelete\", data, ctx),\n  },\n  admin: {\n    widgets: [\n      {\n        id: \"last-delivery\",\n        label: \"Last delivery\",\n        kind: \"status\",\n        actionId: \"lastDelivery\",\n      },\n    ],\n    actions: [\n      {\n        id: \"test-delivery\",\n        label: \"Send test delivery\",\n        actionId: \"sendTest\",\n        confirm: \"Send a test webhook delivery now?\",\n      },\n    ],\n  },\n  setup: (ctx) => {\n    ctx.actions.registerStatus(\"lastDelivery\", async () => {\n      const last = await ctx.storage.get<{ ok: boolean; message: string }>(\"last-delivery\");\n      return last\n        ? npAdminStatus(last.ok ? \"ok\" : \"warn\", last.message)\n        : npAdminStatus(\"warn\", \"No deliveries recorded yet.\");\n    });\n\n    ctx.actions.register(\"sendTest\", async () => {\n      const result = await deliver(\n        \"webhook:test\",\n        { collection: \"test\", doc: { id: \"test\", status: \"published\" } },\n        ctx,\n      );\n      return result.ok ? { ok: true, data: result.message } : npAdminActionError(result.message);\n    });\n  },\n});\n\nasync function deliver(\n  event: string,\n  data: Record<string, unknown>,\n  ctx: Pick<NpPluginContext<WebhookRelayConfig>, \"config\" | \"http\" | \"storage\" | \"log\">,\n): Promise<{ ok: boolean; message: string }> {\n  const payload = buildPayload(event, data);\n\n  if (!ctx.config.includeDrafts && payload.status === \"draft\") {\n    return { ok: true, message: \"Skipped draft document.\" };\n  }\n\n  if (!ctx.config.endpointUrl) {\n    const message = \"Webhook endpoint is not configured.\";\n    await ctx.storage.set(\"last-delivery\", { ok: false, message }, { ttl: 30 * 24 * 60 * 60 });\n    return { ok: false, message };\n  }\n\n  const headers: Record<string, string> = { \"content-type\": \"application/json\" };\n  if (ctx.config.signingSecret) {\n    headers[\"x-np-signature\"] = signPayload(payload, ctx.config.signingSecret);\n  }\n\n  const res = await ctx.http.fetch(ctx.config.endpointUrl, {\n    method: \"POST\",\n    headers,\n    body: { ...payload },\n    timeoutMs: ctx.config.timeoutMs,\n  });\n  const ok = res.ok;\n  const message = ok ? `Delivered ${payload.event}` : `Endpoint returned HTTP ${res.status}`;\n  await ctx.storage.set(\n    \"last-delivery\",\n    { ok, message, at: payload.at },\n    { ttl: 30 * 24 * 60 * 60 },\n  );\n\n  if (!ok) {\n    ctx.log.warn(\"Webhook delivery failed\", { status: String(res.status), event: payload.event });\n  }\n\n  return { ok, message };\n}\n\nexport default webhookRelayPlugin;\n"],"mappings":"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","names":["message"]}

package/package.json

@@ -0,0 +1,56 @@
+{
+  "name": "@nexpress/plugin-webhook-relay",
+  "version": "0.2.0",
+  "description": "Webhook relay plugin for NexPress content lifecycle events.",
+  "license": "MIT",
+  "author": "Nexpress",
+  "homepage": "https://github.com/nexpress-cms/nexpress#readme",
+  "repository": {
+    "type": "git",
+    "url": "https://github.com/nexpress-cms/nexpress.git",
+    "directory": "packages/plugins/webhook-relay"
+  },
+  "bugs": {
+    "url": "https://github.com/nexpress-cms/nexpress/issues"
+  },
+  "keywords": [
+    "nexpress",
+    "plugin",
+    "webhook",
+    "integration"
+  ],
+  "type": "module",
+  "main": "./dist/index.js",
+  "types": "./dist/index.d.ts",
+  "exports": {
+    ".": {
+      "types": "./dist/index.d.ts",
+      "import": "./dist/index.js",
+      "default": "./dist/index.js"
+    }
+  },
+  "files": [
+    "dist"
+  ],
+  "engines": {
+    "node": ">=20"
+  },
+  "dependencies": {
+    "@nexpress/plugin-sdk": "workspace:*",
+    "zod": "^4.4.3"
+  },
+  "devDependencies": {
+    "@types/node": "^22.0.0",
+    "tsup": "^8.5.0",
+    "typescript": "^5.8.0",
+    "vitest": "^4.1.6"
+  },
+  "scripts": {
+    "build": "tsup",
+    "dev": "tsup --watch --no-clean",
+    "clean": "rm -rf dist",
+    "typecheck": "tsc --noEmit",
+    "test": "vitest run",
+    "lint": "eslint . --cache --cache-location node_modules/.cache/eslint"
+  }
+}