@emdash-cms/plugin-webhook-notifier 0.0.3 → 0.1.1

package/LICENSE

@@ -0,0 +1,9 @@
+The MIT License
+
+Copyright 2026 Cloudflare Inc.
+
+Permission is hereby granted, free of charge, to any person obtaining a copy of this software and associated documentation files (the “Software”), to deal in the Software without restriction, including without limitation the rights to use, copy, modify, merge, publish, distribute, sublicense, and/or sell copies of the Software, and to permit persons to whom the Software is furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED “AS IS”, WITHOUT WARRANTY OF ANY KIND, EXPRESS OR IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY, FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM, OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE SOFTWARE.

package/dist/index.d.mts

@@ -0,0 +1,19 @@
+import { PluginDescriptor } from "emdash";
+
+//#region src/index.d.ts
+interface WebhookPayload {
+  event: "content:create" | "content:update" | "content:delete" | "media:upload";
+  timestamp: string;
+  collection?: string;
+  resourceId: string;
+  resourceType: "content" | "media";
+  data?: Record<string, unknown>;
+  metadata?: Record<string, unknown>;
+}
+/**
+ * Create the webhook notifier plugin descriptor
+ */
+declare function webhookNotifierPlugin(): PluginDescriptor;
+//#endregion
+export { WebhookPayload, webhookNotifierPlugin };
+//# sourceMappingURL=index.d.mts.map

package/dist/index.d.mts.map

@@ -0,0 +1 @@
+{"version":3,"file":"index.d.mts","names":[],"sources":["../src/index.ts"],"mappings":";;;UAuBiB,cAAA;EAChB,KAAA;EACA,SAAA;EACA,UAAA;EACA,UAAA;EACA,YAAA;EACA,IAAA,GAAO,MAAA;EACP,QAAA,GAAW,MAAA;AAAA;;;;iBAMI,qBAAA,CAAA,GAAyB,gBAAA"}

package/dist/index.mjs

@@ -0,0 +1,32 @@
+//#region src/index.ts
+/**
+* Create the webhook notifier plugin descriptor
+*/
+function webhookNotifierPlugin() {
+	return {
+		id: "webhook-notifier",
+		version: "0.1.0",
+		format: "standard",
+		entrypoint: "@emdash-cms/plugin-webhook-notifier/sandbox",
+		capabilities: ["network:fetch:any"],
+		storage: { deliveries: { indexes: [
+			"timestamp",
+			"webhookUrl",
+			"status"
+		] } },
+		adminPages: [{
+			path: "/settings",
+			label: "Webhook Settings",
+			icon: "send"
+		}],
+		adminWidgets: [{
+			id: "status",
+			title: "Webhooks",
+			size: "third"
+		}]
+	};
+}
+
+//#endregion
+export { webhookNotifierPlugin };
+//# sourceMappingURL=index.mjs.map

package/dist/index.mjs.map

@@ -0,0 +1 @@
+{"version":3,"file":"index.mjs","names":[],"sources":["../src/index.ts"],"sourcesContent":["/**\n * Webhook Notifier Plugin for EmDash CMS\n *\n * Posts to external URLs when content changes occur.\n *\n * Features:\n * - Configurable webhook URLs (admin settings)\n * - Secret token for authentication (encrypted)\n * - Retry logic with exponential backoff\n * - Event filtering by collection and action\n * - Manual trigger via API route\n *\n * Demonstrates:\n * - network:fetch:any capability (unrestricted outbound for user-configured URLs)\n * - settings.secret() for encrypted tokens\n * - apiRoutes for custom endpoints\n * - content:afterDelete hook\n * - Hook dependencies (runs after audit-log)\n * - errorPolicy: \"continue\" (don't block save on webhook failure)\n */\n\nimport type { PluginDescriptor } from \"emdash\";\n\nexport interface WebhookPayload {\n\tevent: \"content:create\" | \"content:update\" | \"content:delete\" | \"media:upload\";\n\ttimestamp: string;\n\tcollection?: string;\n\tresourceId: string;\n\tresourceType: \"content\" | \"media\";\n\tdata?: Record<string, unknown>;\n\tmetadata?: Record<string, unknown>;\n}\n\n/**\n * Create the webhook notifier plugin descriptor\n */\nexport function webhookNotifierPlugin(): PluginDescriptor {\n\treturn {\n\t\tid: \"webhook-notifier\",\n\t\tversion: \"0.1.0\",\n\t\tformat: \"standard\",\n\t\tentrypoint: \"@emdash-cms/plugin-webhook-notifier/sandbox\",\n\t\tcapabilities: [\"network:fetch:any\"],\n\t\tstorage: {\n\t\t\tdeliveries: { indexes: [\"timestamp\", \"webhookUrl\", \"status\"] },\n\t\t},\n\t\tadminPages: [{ path: \"/settings\", label: \"Webhook Settings\", icon: \"send\" }],\n\t\tadminWidgets: [{ id: \"status\", title: \"Webhooks\", size: \"third\" }],\n\t};\n}\n"],"mappings":";;;;AAoCA,SAAgB,wBAA0C;AACzD,QAAO;EACN,IAAI;EACJ,SAAS;EACT,QAAQ;EACR,YAAY;EACZ,cAAc,CAAC,oBAAoB;EACnC,SAAS,EACR,YAAY,EAAE,SAAS;GAAC;GAAa;GAAc;GAAS,EAAE,EAC9D;EACD,YAAY,CAAC;GAAE,MAAM;GAAa,OAAO;GAAoB,MAAM;GAAQ,CAAC;EAC5E,cAAc,CAAC;GAAE,IAAI;GAAU,OAAO;GAAY,MAAM;GAAS,CAAC;EAClE"}

package/dist/sandbox-entry.d.mts

@@ -0,0 +1,13 @@
+import * as emdash from "emdash";
+
+//#region src/sandbox-entry.d.ts
+/**
+ * Sandbox Entry Point -- Webhook Notifier
+ *
+ * Canonical plugin implementation using the standard format.
+ * Runs in both trusted (in-process) and sandboxed (isolate) modes.
+ */
+declare const _default: emdash.StandardPluginDefinition;
+//#endregion
+export { _default as default };
+//# sourceMappingURL=sandbox-entry.d.mts.map

package/dist/sandbox-entry.d.mts.map

@@ -0,0 +1 @@
+{"version":3,"file":"sandbox-entry.d.mts","names":[],"sources":["../src/sandbox-entry.ts"],"mappings":""}

package/dist/sandbox-entry.mjs

@@ -0,0 +1,533 @@
+import { definePlugin } from "emdash";
+
+//#region src/sandbox-entry.ts
+/**
+* Sandbox Entry Point -- Webhook Notifier
+*
+* Canonical plugin implementation using the standard format.
+* Runs in both trusted (in-process) and sandboxed (isolate) modes.
+*/
+const IPV6_BRACKET_PATTERN = /^\[|\]$/g;
+const BLOCKED_HOSTNAMES = new Set([
+	"localhost",
+	"metadata.google.internal",
+	"[::1]"
+]);
+const PRIVATE_RANGES = [
+	{
+		start: 127 << 24 >>> 0,
+		end: 2147483647
+	},
+	{
+		start: 10 << 24 >>> 0,
+		end: 184549375
+	},
+	{
+		start: 2886729728,
+		end: 2887778303
+	},
+	{
+		start: 3232235520,
+		end: 3232301055
+	},
+	{
+		start: 2851995648,
+		end: 2852061183
+	},
+	{
+		start: 0,
+		end: 16777215
+	}
+];
+function validateWebhookUrl(url) {
+	let parsed;
+	try {
+		parsed = new URL(url);
+	} catch {
+		throw new Error("Invalid webhook URL");
+	}
+	if (parsed.protocol !== "http:" && parsed.protocol !== "https:") throw new Error(`Webhook URL scheme '${parsed.protocol}' is not allowed`);
+	const hostname = parsed.hostname.replace(IPV6_BRACKET_PATTERN, "");
+	if (BLOCKED_HOSTNAMES.has(hostname.toLowerCase())) throw new Error("Webhook URLs targeting internal hosts are not allowed");
+	const parts = hostname.split(".");
+	if (parts.length === 4) {
+		const nums = parts.map(Number);
+		if (nums.every((n) => !isNaN(n) && n >= 0 && n <= 255)) {
+			const ip = (nums[0] << 24 | nums[1] << 16 | nums[2] << 8 | nums[3]) >>> 0;
+			if (PRIVATE_RANGES.some((r) => ip >= r.start && ip <= r.end)) throw new Error("Webhook URLs targeting private IP addresses are not allowed");
+		}
+	}
+	if (hostname === "::1" || hostname.startsWith("fe80:") || hostname.startsWith("fc") || hostname.startsWith("fd")) throw new Error("Webhook URLs targeting internal addresses are not allowed");
+}
+async function sendWebhook(fetchFn, log, url, payload, token, maxRetries) {
+	validateWebhookUrl(url);
+	let lastError;
+	let lastStatus;
+	for (let attempt = 1; attempt <= maxRetries; attempt++) {
+		try {
+			const headers = {
+				"Content-Type": "application/json",
+				"X-EmDash-Event": payload.event
+			};
+			if (token) headers["Authorization"] = `Bearer ${token}`;
+			const response = await fetchFn(url, {
+				method: "POST",
+				headers,
+				body: JSON.stringify(payload)
+			});
+			lastStatus = response.status;
+			if (response.ok) {
+				log.info(`Delivered ${payload.event} to ${url} (${response.status})`);
+				return {
+					success: true,
+					status: response.status
+				};
+			}
+			lastError = `HTTP ${response.status}: ${response.statusText}`;
+			log.warn(`Attempt ${attempt}/${maxRetries} failed: ${lastError}`);
+		} catch (error) {
+			lastError = error instanceof Error ? error.message : "Unknown error";
+			log.warn(`Attempt ${attempt}/${maxRetries} failed: ${lastError}`);
+		}
+		if (attempt < maxRetries) await new Promise((resolve) => setTimeout(resolve, 100 * Math.pow(2, attempt - 1)));
+	}
+	log.error(`Failed to deliver ${payload.event} after ${maxRetries} attempts`);
+	return {
+		success: false,
+		status: lastStatus,
+		error: lastError
+	};
+}
+function isRecord(value) {
+	return typeof value === "object" && value !== null && !Array.isArray(value);
+}
+function getString(value, key) {
+	if (!isRecord(value)) return void 0;
+	const v = value[key];
+	return typeof v === "string" ? v : void 0;
+}
+const MAX_RETRIES = 3;
+async function getConfig(ctx) {
+	return {
+		url: await ctx.kv.get("settings:webhookUrl"),
+		token: await ctx.kv.get("settings:secretToken"),
+		enabled: await ctx.kv.get("settings:enabled")
+	};
+}
+function getFetchFn(ctx) {
+	if (!ctx.http) throw new Error("Webhook notifier requires network:fetch capability");
+	return ctx.http.fetch;
+}
+var sandbox_entry_default = definePlugin({
+	hooks: {
+		"content:afterSave": {
+			priority: 210,
+			timeout: 1e4,
+			dependencies: ["audit-log"],
+			errorPolicy: "continue",
+			handler: async (event, ctx) => {
+				const { url, token, enabled } = await getConfig(ctx);
+				if (enabled === false || !url) return;
+				const contentId = typeof event.content.id === "string" ? event.content.id : String(event.content.id);
+				const payload = {
+					event: event.isNew ? "content:create" : "content:update",
+					timestamp: (/* @__PURE__ */ new Date()).toISOString(),
+					collection: event.collection,
+					resourceId: contentId,
+					resourceType: "content",
+					metadata: {
+						slug: event.content.slug,
+						status: event.content.status
+					}
+				};
+				await sendWebhook(getFetchFn(ctx), ctx.log, url, payload, token ?? void 0, MAX_RETRIES);
+			}
+		},
+		"content:afterDelete": {
+			priority: 210,
+			timeout: 1e4,
+			dependencies: ["audit-log"],
+			errorPolicy: "continue",
+			handler: async (event, ctx) => {
+				const { url, token, enabled } = await getConfig(ctx);
+				if (enabled === false || !url) return;
+				const payload = {
+					event: "content:delete",
+					timestamp: (/* @__PURE__ */ new Date()).toISOString(),
+					collection: event.collection,
+					resourceId: event.id,
+					resourceType: "content"
+				};
+				await sendWebhook(getFetchFn(ctx), ctx.log, url, payload, token ?? void 0, MAX_RETRIES);
+			}
+		},
+		"media:afterUpload": {
+			priority: 210,
+			timeout: 1e4,
+			errorPolicy: "continue",
+			handler: async (event, ctx) => {
+				const { url, token, enabled } = await getConfig(ctx);
+				if (enabled === false || !url) return;
+				const payload = {
+					event: "media:upload",
+					timestamp: (/* @__PURE__ */ new Date()).toISOString(),
+					resourceId: event.media.id,
+					resourceType: "media"
+				};
+				await sendWebhook(getFetchFn(ctx), ctx.log, url, payload, token ?? void 0, MAX_RETRIES);
+			}
+		}
+	},
+	routes: {
+		admin: { handler: async (routeCtx, ctx) => {
+			const interaction = routeCtx.input;
+			if (interaction.type === "page_load" && interaction.page === "widget:webhook-status") return buildStatusWidget(ctx);
+			if (interaction.type === "page_load" && interaction.page === "/settings") return buildSettingsPage(ctx);
+			if (interaction.type === "form_submit" && interaction.action_id === "save_settings") return saveSettings(ctx, interaction.values ?? {});
+			if (interaction.type === "block_action" && interaction.action_id === "test_webhook") return testWebhook(ctx);
+			return { blocks: [] };
+		} },
+		status: { handler: async (_routeCtx, ctx) => {
+			try {
+				const url = await ctx.kv.get("settings:webhookUrl");
+				const enabled = await ctx.kv.get("settings:enabled");
+				const deliveries = ctx.storage.deliveries;
+				const successful = await deliveries.count({ status: "success" });
+				const failed = await deliveries.count({ status: "failed" });
+				const pending = await deliveries.count({ status: "pending" });
+				return {
+					configured: !!url,
+					enabled: enabled ?? true,
+					stats: {
+						successful,
+						failed,
+						pending
+					}
+				};
+			} catch (error) {
+				ctx.log.error("Failed to get status", error);
+				return {
+					configured: false,
+					enabled: true,
+					stats: {
+						successful: 0,
+						failed: 0,
+						pending: 0
+					}
+				};
+			}
+		} },
+		settings: { handler: async (_routeCtx, ctx) => {
+			try {
+				const settings = await ctx.kv.list("settings:");
+				const map = {};
+				for (const entry of settings) map[entry.key.replace("settings:", "")] = entry.value;
+				return {
+					webhookUrl: typeof map.webhookUrl === "string" ? map.webhookUrl : "",
+					enabled: typeof map.enabled === "boolean" ? map.enabled : true,
+					includeData: typeof map.includeData === "boolean" ? map.includeData : false,
+					events: typeof map.events === "string" ? map.events : "all"
+				};
+			} catch (error) {
+				ctx.log.error("Failed to get settings", error);
+				return {
+					webhookUrl: "",
+					enabled: true,
+					includeData: false,
+					events: "all"
+				};
+			}
+		} },
+		"settings/save": { handler: async (routeCtx, ctx) => {
+			try {
+				const input = isRecord(routeCtx.input) ? routeCtx.input : {};
+				if (typeof input.webhookUrl === "string") await ctx.kv.set("settings:webhookUrl", input.webhookUrl);
+				if (typeof input.enabled === "boolean") await ctx.kv.set("settings:enabled", input.enabled);
+				if (typeof input.includeData === "boolean") await ctx.kv.set("settings:includeData", input.includeData);
+				if (typeof input.events === "string") await ctx.kv.set("settings:events", input.events);
+				return { success: true };
+			} catch (error) {
+				ctx.log.error("Failed to save settings", error);
+				return {
+					success: false,
+					error: String(error)
+				};
+			}
+		} },
+		test: { handler: async (routeCtx, ctx) => {
+			const testUrl = getString(routeCtx.input, "url");
+			if (!testUrl) return {
+				success: false,
+				error: "No webhook URL provided"
+			};
+			const token = await ctx.kv.get("settings:secretToken");
+			const testPayload = {
+				event: "content:create",
+				timestamp: (/* @__PURE__ */ new Date()).toISOString(),
+				resourceId: "test-" + Date.now(),
+				resourceType: "content",
+				metadata: {
+					test: true,
+					message: "Webhook test from EmDash CMS"
+				}
+			};
+			const result = await sendWebhook(getFetchFn(ctx), ctx.log, testUrl, testPayload, token ?? void 0, 1);
+			return {
+				success: result.success,
+				status: result.status,
+				error: result.error,
+				payload: testPayload
+			};
+		} }
+	}
+});
+async function buildStatusWidget(ctx) {
+	try {
+		const url = await ctx.kv.get("settings:webhookUrl");
+		const enabled = await ctx.kv.get("settings:enabled");
+		const isConfigured = !!url && enabled !== false;
+		let successful = 0;
+		let failed = 0;
+		let pending = 0;
+		try {
+			const deliveries = ctx.storage.deliveries;
+			successful = await deliveries.count({ status: "success" });
+			failed = await deliveries.count({ status: "failed" });
+			pending = await deliveries.count({ status: "pending" });
+		} catch {}
+		const blocks = [{
+			type: "fields",
+			fields: [{
+				label: "Status",
+				value: isConfigured ? "Active" : "Not Configured"
+			}, {
+				label: "Endpoint",
+				value: url ? url : "None"
+			}]
+		}];
+		if (isConfigured) blocks.push({
+			type: "stats",
+			stats: [
+				{
+					label: "Delivered",
+					value: String(successful)
+				},
+				{
+					label: "Failed",
+					value: String(failed)
+				},
+				{
+					label: "Pending",
+					value: String(pending)
+				}
+			]
+		});
+		else blocks.push({
+			type: "context",
+			text: "Configure a webhook URL in settings to start sending events."
+		});
+		return { blocks };
+	} catch (error) {
+		ctx.log.error("Failed to build status widget", error);
+		return { blocks: [{
+			type: "context",
+			text: "Failed to load webhook status"
+		}] };
+	}
+}
+async function buildSettingsPage(ctx) {
+	try {
+		const webhookUrl = await ctx.kv.get("settings:webhookUrl") ?? "";
+		const enabled = await ctx.kv.get("settings:enabled") ?? true;
+		const includeData = await ctx.kv.get("settings:includeData") ?? false;
+		const events = await ctx.kv.get("settings:events") ?? "all";
+		const payloadPreview = JSON.stringify({
+			event: "content:create",
+			timestamp: (/* @__PURE__ */ new Date()).toISOString(),
+			collection: "posts",
+			resourceId: "abc123",
+			resourceType: "content",
+			...includeData && { data: {
+				title: "Example Post",
+				slug: "example-post"
+			} },
+			metadata: {
+				slug: "example-post",
+				status: "published"
+			}
+		}, null, 2);
+		return { blocks: [
+			{
+				type: "header",
+				text: "Webhook Settings"
+			},
+			{
+				type: "context",
+				text: "Send notifications to external services when content changes."
+			},
+			{ type: "divider" },
+			{
+				type: "form",
+				block_id: "webhook-settings",
+				fields: [
+					{
+						type: "text_input",
+						action_id: "webhookUrl",
+						label: "Webhook URL",
+						initial_value: webhookUrl
+					},
+					{
+						type: "secret_input",
+						action_id: "secretToken",
+						label: "Secret Token"
+					},
+					{
+						type: "toggle",
+						action_id: "enabled",
+						label: "Enable Webhooks",
+						initial_value: enabled
+					},
+					{
+						type: "select",
+						action_id: "events",
+						label: "Events to Send",
+						options: [
+							{
+								label: "All events",
+								value: "all"
+							},
+							{
+								label: "Content changes only",
+								value: "content"
+							},
+							{
+								label: "Media uploads only",
+								value: "media"
+							}
+						],
+						initial_value: events
+					},
+					{
+						type: "toggle",
+						action_id: "includeData",
+						label: "Include Content Data",
+						initial_value: includeData
+					}
+				],
+				submit: {
+					label: "Save Settings",
+					action_id: "save_settings"
+				}
+			},
+			{ type: "divider" },
+			{
+				type: "section",
+				text: "**Payload Preview**"
+			},
+			{
+				type: "code",
+				code: payloadPreview,
+				language: "json"
+			},
+			{
+				type: "actions",
+				elements: [{
+					type: "button",
+					text: "Test Webhook",
+					action_id: "test_webhook",
+					style: "primary"
+				}]
+			}
+		] };
+	} catch (error) {
+		ctx.log.error("Failed to build settings page", error);
+		return { blocks: [{
+			type: "context",
+			text: "Failed to load settings"
+		}] };
+	}
+}
+async function saveSettings(ctx, values) {
+	try {
+		if (typeof values.webhookUrl === "string") await ctx.kv.set("settings:webhookUrl", values.webhookUrl);
+		if (typeof values.secretToken === "string" && values.secretToken !== "") await ctx.kv.set("settings:secretToken", values.secretToken);
+		if (typeof values.enabled === "boolean") await ctx.kv.set("settings:enabled", values.enabled);
+		if (typeof values.events === "string") await ctx.kv.set("settings:events", values.events);
+		if (typeof values.includeData === "boolean") await ctx.kv.set("settings:includeData", values.includeData);
+		return {
+			...await buildSettingsPage(ctx),
+			toast: {
+				message: "Settings saved",
+				type: "success"
+			}
+		};
+	} catch (error) {
+		ctx.log.error("Failed to save settings", error);
+		return {
+			blocks: [{
+				type: "banner",
+				style: "error",
+				text: "Failed to save settings"
+			}],
+			toast: {
+				message: "Failed to save settings",
+				type: "error"
+			}
+		};
+	}
+}
+async function testWebhook(ctx) {
+	const url = await ctx.kv.get("settings:webhookUrl");
+	if (!url) return {
+		blocks: [{
+			type: "banner",
+			style: "warning",
+			text: "Enter a webhook URL first."
+		}],
+		toast: {
+			message: "No webhook URL configured",
+			type: "error"
+		}
+	};
+	const token = await ctx.kv.get("settings:secretToken");
+	const testPayload = {
+		event: "content:create",
+		timestamp: (/* @__PURE__ */ new Date()).toISOString(),
+		resourceId: "test-" + Date.now(),
+		resourceType: "content",
+		metadata: {
+			test: true,
+			message: "Webhook test from EmDash CMS"
+		}
+	};
+	try {
+		const result = await sendWebhook(getFetchFn(ctx), ctx.log, url, testPayload, token ?? void 0, 1);
+		if (result.success) return {
+			...await buildSettingsPage(ctx),
+			toast: {
+				message: `Test sent -- HTTP ${result.status}`,
+				type: "success"
+			}
+		};
+		return {
+			...await buildSettingsPage(ctx),
+			toast: {
+				message: `Test failed: ${result.error ?? "Unknown error"}`,
+				type: "error"
+			}
+		};
+	} catch (error) {
+		const msg = error instanceof Error ? error.message : String(error);
+		return {
+			...await buildSettingsPage(ctx),
+			toast: {
+				message: `Test failed: ${msg}`,
+				type: "error"
+			}
+		};
+	}
+}
+
+//#endregion
+export { sandbox_entry_default as default };
+//# sourceMappingURL=sandbox-entry.mjs.map