@blokjs/trigger-webhook 0.2.0

package/dist/index.js

@@ -0,0 +1,76 @@
+"use strict";
+/**
+ * @blok/trigger-webhook
+ *
+ * Webhook trigger for Blok workflows.
+ * Handle webhook events from external services.
+ *
+ * Supported Services:
+ * - GitHub (push, pull_request, issues, releases, etc.)
+ * - Stripe (payment_intent, checkout.session, customer, etc.)
+ * - Shopify (orders, products, customers, etc.)
+ * - Custom webhooks (any service with signature verification)
+ *
+ * Features:
+ * - Signature verification (HMAC-SHA256)
+ * - Event type filtering
+ * - Source-specific handlers
+ * - Custom source registration
+ *
+ * @example
+ * ```typescript
+ * import { WebhookTrigger } from "@blok/trigger-webhook";
+ *
+ * class MyWebhookTrigger extends WebhookTrigger {
+ *   protected nodes = myNodes;
+ *   protected workflows = myWorkflows;
+ * }
+ *
+ * const trigger = new MyWebhookTrigger();
+ * await trigger.listen();
+ *
+ * // In your HTTP endpoint handler:
+ * app.post("/webhooks/:source", async (req, res) => {
+ *   const rawBody = JSON.stringify(req.body);
+ *   const result = await trigger.handleWebhook(
+ *     req.params.source,
+ *     rawBody,
+ *     req.headers as Record<string, string>
+ *   );
+ *   res.status(200).json({ received: true });
+ * });
+ * ```
+ *
+ * Workflow Definition:
+ * ```typescript
+ * Workflow({ name: "github-push", version: "1.0.0" })
+ *   .addTrigger("webhook", {
+ *     source: "github",
+ *     events: ["push", "pull_request.*"],
+ *     secret: process.env.GITHUB_WEBHOOK_SECRET,
+ *   })
+ *   .addStep({ ... });
+ * ```
+ *
+ * Custom Source Handler:
+ * ```typescript
+ * import { WebhookTrigger } from "@blok/trigger-webhook";
+ *
+ * WebhookTrigger.registerSourceHandler("my-service", {
+ *   getEventType: (headers, body) => body.event_type,
+ *   getSignature: (headers) => headers["x-my-signature"],
+ *   verifySignature: (rawBody, signature, secret) => {
+ *     // Your verification logic
+ *     return { valid: true };
+ *   },
+ *   getEventId: (headers, body) => body.id,
+ * });
+ * ```
+ */
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.sourceHandlers = exports.WebhookTrigger = void 0;
+// Core exports
+var WebhookTrigger_1 = require("./WebhookTrigger");
+Object.defineProperty(exports, "WebhookTrigger", { enumerable: true, get: function () { return WebhookTrigger_1.WebhookTrigger; } });
+Object.defineProperty(exports, "sourceHandlers", { enumerable: true, get: function () { return WebhookTrigger_1.sourceHandlers; } });
+//# sourceMappingURL=data:application/json;base64,eyJ2ZXJzaW9uIjozLCJmaWxlIjoiaW5kZXguanMiLCJzb3VyY2VSb290IjoiIiwic291cmNlcyI6WyIuLi9zcmMvaW5kZXgudHMiXSwibmFtZXMiOltdLCJtYXBwaW5ncyI6IjtBQUFBOzs7Ozs7Ozs7Ozs7Ozs7Ozs7Ozs7Ozs7Ozs7Ozs7Ozs7Ozs7Ozs7Ozs7Ozs7Ozs7Ozs7Ozs7Ozs7Ozs7Ozs7Ozs7O0dBbUVHOzs7QUFFSCxlQUFlO0FBQ2YsbURBTTBCO0FBTHpCLGdIQUFBLGNBQWMsT0FBQTtBQUNkLGdIQUFBLGNBQWMsT0FBQSIsInNvdXJjZXNDb250ZW50IjpbIi8qKlxuICogQGJsb2svdHJpZ2dlci13ZWJob29rXG4gKlxuICogV2ViaG9vayB0cmlnZ2VyIGZvciBCbG9rIHdvcmtmbG93cy5cbiAqIEhhbmRsZSB3ZWJob29rIGV2ZW50cyBmcm9tIGV4dGVybmFsIHNlcnZpY2VzLlxuICpcbiAqIFN1cHBvcnRlZCBTZXJ2aWNlczpcbiAqIC0gR2l0SHViIChwdXNoLCBwdWxsX3JlcXVlc3QsIGlzc3VlcywgcmVsZWFzZXMsIGV0Yy4pXG4gKiAtIFN0cmlwZSAocGF5bWVudF9pbnRlbnQsIGNoZWNrb3V0LnNlc3Npb24sIGN1c3RvbWVyLCBldGMuKVxuICogLSBTaG9waWZ5IChvcmRlcnMsIHByb2R1Y3RzLCBjdXN0b21lcnMsIGV0Yy4pXG4gKiAtIEN1c3RvbSB3ZWJob29rcyAoYW55IHNlcnZpY2Ugd2l0aCBzaWduYXR1cmUgdmVyaWZpY2F0aW9uKVxuICpcbiAqIEZlYXR1cmVzOlxuICogLSBTaWduYXR1cmUgdmVyaWZpY2F0aW9uIChITUFDLVNIQTI1NilcbiAqIC0gRXZlbnQgdHlwZSBmaWx0ZXJpbmdcbiAqIC0gU291cmNlLXNwZWNpZmljIGhhbmRsZXJzXG4gKiAtIEN1c3RvbSBzb3VyY2UgcmVnaXN0cmF0aW9uXG4gKlxuICogQGV4YW1wbGVcbiAqIGBgYHR5cGVzY3JpcHRcbiAqIGltcG9ydCB7IFdlYmhvb2tUcmlnZ2VyIH0gZnJvbSBcIkBibG9rL3RyaWdnZXItd2ViaG9va1wiO1xuICpcbiAqIGNsYXNzIE15V2ViaG9va1RyaWdnZXIgZXh0ZW5kcyBXZWJob29rVHJpZ2dlciB7XG4gKiAgIHByb3RlY3RlZCBub2RlcyA9IG15Tm9kZXM7XG4gKiAgIHByb3RlY3RlZCB3b3JrZmxvd3MgPSBteVdvcmtmbG93cztcbiAqIH1cbiAqXG4gKiBjb25zdCB0cmlnZ2VyID0gbmV3IE15V2ViaG9va1RyaWdnZXIoKTtcbiAqIGF3YWl0IHRyaWdnZXIubGlzdGVuKCk7XG4gKlxuICogLy8gSW4geW91ciBIVFRQIGVuZHBvaW50IGhhbmRsZXI6XG4gKiBhcHAucG9zdChcIi93ZWJob29rcy86c291cmNlXCIsIGFzeW5jIChyZXEsIHJlcykgPT4ge1xuICogICBjb25zdCByYXdCb2R5ID0gSlNPTi5zdHJpbmdpZnkocmVxLmJvZHkpO1xuICogICBjb25zdCByZXN1bHQgPSBhd2FpdCB0cmlnZ2VyLmhhbmRsZVdlYmhvb2soXG4gKiAgICAgcmVxLnBhcmFtcy5zb3VyY2UsXG4gKiAgICAgcmF3Qm9keSxcbiAqICAgICByZXEuaGVhZGVycyBhcyBSZWNvcmQ8c3RyaW5nLCBzdHJpbmc+XG4gKiAgICk7XG4gKiAgIHJlcy5zdGF0dXMoMjAwKS5qc29uKHsgcmVjZWl2ZWQ6IHRydWUgfSk7XG4gKiB9KTtcbiAqIGBgYFxuICpcbiAqIFdvcmtmbG93IERlZmluaXRpb246XG4gKiBgYGB0eXBlc2NyaXB0XG4gKiBXb3JrZmxvdyh7IG5hbWU6IFwiZ2l0aHViLXB1c2hcIiwgdmVyc2lvbjogXCIxLjAuMFwiIH0pXG4gKiAgIC5hZGRUcmlnZ2VyKFwid2ViaG9va1wiLCB7XG4gKiAgICAgc291cmNlOiBcImdpdGh1YlwiLFxuICogICAgIGV2ZW50czogW1wicHVzaFwiLCBcInB1bGxfcmVxdWVzdC4qXCJdLFxuICogICAgIHNlY3JldDogcHJvY2Vzcy5lbnYuR0lUSFVCX1dFQkhPT0tfU0VDUkVULFxuICogICB9KVxuICogICAuYWRkU3RlcCh7IC4uLiB9KTtcbiAqIGBgYFxuICpcbiAqIEN1c3RvbSBTb3VyY2UgSGFuZGxlcjpcbiAqIGBgYHR5cGVzY3JpcHRcbiAqIGltcG9ydCB7IFdlYmhvb2tUcmlnZ2VyIH0gZnJvbSBcIkBibG9rL3RyaWdnZXItd2ViaG9va1wiO1xuICpcbiAqIFdlYmhvb2tUcmlnZ2VyLnJlZ2lzdGVyU291cmNlSGFuZGxlcihcIm15LXNlcnZpY2VcIiwge1xuICogICBnZXRFdmVudFR5cGU6IChoZWFkZXJzLCBib2R5KSA9PiBib2R5LmV2ZW50X3R5cGUsXG4gKiAgIGdldFNpZ25hdHVyZTogKGhlYWRlcnMpID0+IGhlYWRlcnNbXCJ4LW15LXNpZ25hdHVyZVwiXSxcbiAqICAgdmVyaWZ5U2lnbmF0dXJlOiAocmF3Qm9keSwgc2lnbmF0dXJlLCBzZWNyZXQpID0+IHtcbiAqICAgICAvLyBZb3VyIHZlcmlmaWNhdGlvbiBsb2dpY1xuICogICAgIHJldHVybiB7IHZhbGlkOiB0cnVlIH07XG4gKiAgIH0sXG4gKiAgIGdldEV2ZW50SWQ6IChoZWFkZXJzLCBib2R5KSA9PiBib2R5LmlkLFxuICogfSk7XG4gKiBgYGBcbiAqL1xuXG4vLyBDb3JlIGV4cG9ydHNcbmV4cG9ydCB7XG5cdFdlYmhvb2tUcmlnZ2VyLFxuXHRzb3VyY2VIYW5kbGVycyxcblx0dHlwZSBXZWJob29rRXZlbnQsXG5cdHR5cGUgVmVyaWZpY2F0aW9uUmVzdWx0LFxuXHR0eXBlIFdlYmhvb2tTb3VyY2VIYW5kbGVyLFxufSBmcm9tIFwiLi9XZWJob29rVHJpZ2dlclwiO1xuXG4vLyBSZS1leHBvcnQgdHlwZXMgZnJvbSBoZWxwZXIgZm9yIGNvbnZlbmllbmNlXG5leHBvcnQgdHlwZSB7IFdlYmhvb2tUcmlnZ2VyT3B0cyB9IGZyb20gXCJAYmxvay9oZWxwZXJcIjtcbiJdfQ==

package/package.json

@@ -0,0 +1,33 @@
+{
+	"name": "@blokjs/trigger-webhook",
+	"version": "0.2.0",
+	"description": "Webhook trigger for Blok workflows - supports GitHub, Stripe, Shopify, and custom webhooks",
+	"type": "module",
+	"main": "dist/index.js",
+	"types": "dist/index.d.ts",
+	"scripts": {
+		"build": "rm -rf dist && bun run tsc",
+		"build:dev": "tsc --watch",
+		"test": "vitest run",
+		"test:dev": "vitest"
+	},
+	"author": "Deskree Technologies Inc.",
+	"license": "Apache-2.0",
+	"dependencies": {
+		"@blokjs/helper": "workspace:*",
+		"@blokjs/runner": "workspace:*",
+		"@blokjs/shared": "workspace:*",
+		"@opentelemetry/api": "^1.9.0",
+		"uuid": "^11.1.0"
+	},
+	"devDependencies": {
+		"@types/node": "^22.15.21",
+		"@types/uuid": "^11.0.0",
+		"typescript": "^5.8.3",
+		"vitest": "^4.0.18"
+	},
+	"private": false,
+	"publishConfig": {
+		"access": "public"
+	}
+}

package/src/WebhookTrigger.test.ts

@@ -0,0 +1,163 @@
+/**
+ * WebhookTrigger Tests
+ */
+
+import crypto from "crypto";
+import { describe, expect, it } from "vitest";
+import { sourceHandlers } from "./WebhookTrigger";
+
+describe("WebhookTrigger", () => {
+	describe("WebhookEvent Interface", () => {
+		it("should accept valid webhook event structure", () => {
+			const event = {
+				id: "event-123",
+				source: "github",
+				eventType: "push",
+				payload: { ref: "refs/heads/main" },
+				headers: { "x-github-event": "push" },
+				signature: "sha256=abc123",
+				timestamp: new Date(),
+				rawBody: '{"ref":"refs/heads/main"}',
+			};
+
+			expect(event.id).toBe("event-123");
+			expect(event.source).toBe("github");
+			expect(event.eventType).toBe("push");
+		});
+	});
+});
+
+describe("Source Handlers", () => {
+	describe("GitHub Handler", () => {
+		const handler = sourceHandlers.github;
+
+		it("should extract event type from headers", () => {
+			const headers = { "x-github-event": "push" };
+			expect(handler.getEventType(headers, {})).toBe("push");
+		});
+
+		it("should extract signature from headers", () => {
+			const headers = { "x-hub-signature-256": "sha256=abc123" };
+			expect(handler.getSignature(headers)).toBe("sha256=abc123");
+		});
+
+		it("should verify valid signature", () => {
+			const secret = "my-secret";
+			const rawBody = '{"action":"created"}';
+			const hmac = crypto.createHmac("sha256", secret);
+			const signature = "sha256=" + hmac.update(rawBody).digest("hex");
+
+			const result = handler.verifySignature(rawBody, signature, secret);
+			expect(result.valid).toBe(true);
+		});
+
+		it("should reject invalid signature", () => {
+			const result = handler.verifySignature('{"action":"created"}', "sha256=invalid", "my-secret");
+			expect(result.valid).toBe(false);
+		});
+
+		it("should extract event ID from headers", () => {
+			const headers = { "x-github-delivery": "delivery-123" };
+			expect(handler.getEventId(headers, {})).toBe("delivery-123");
+		});
+	});
+
+	describe("Stripe Handler", () => {
+		const handler = sourceHandlers.stripe;
+
+		it("should extract event type from body", () => {
+			const body = { type: "payment_intent.succeeded" };
+			expect(handler.getEventType({}, body)).toBe("payment_intent.succeeded");
+		});
+
+		it("should extract signature from headers", () => {
+			const headers = { "stripe-signature": "t=123,v1=abc" };
+			expect(handler.getSignature(headers)).toBe("t=123,v1=abc");
+		});
+
+		it("should verify valid Stripe signature", () => {
+			const secret = "whsec_test";
+			const rawBody = '{"type":"test"}';
+			const timestamp = Math.floor(Date.now() / 1000);
+			const payload = `${timestamp}.${rawBody}`;
+			const hmac = crypto.createHmac("sha256", secret);
+			const sig = hmac.update(payload).digest("hex");
+			const signature = `t=${timestamp},v1=${sig}`;
+
+			const result = handler.verifySignature(rawBody, signature, secret);
+			expect(result.valid).toBe(true);
+		});
+
+		it("should extract event ID from body", () => {
+			const body = { id: "evt_123" };
+			expect(handler.getEventId({}, body)).toBe("evt_123");
+		});
+	});
+
+	describe("Shopify Handler", () => {
+		const handler = sourceHandlers.shopify;
+
+		it("should extract event type from headers", () => {
+			const headers = { "x-shopify-topic": "orders/create" };
+			expect(handler.getEventType(headers, {})).toBe("orders/create");
+		});
+
+		it("should extract signature from headers", () => {
+			const headers = { "x-shopify-hmac-sha256": "abc123base64==" };
+			expect(handler.getSignature(headers)).toBe("abc123base64==");
+		});
+
+		it("should extract event ID from headers", () => {
+			const headers = { "x-shopify-webhook-id": "webhook-123" };
+			expect(handler.getEventId(headers, {})).toBe("webhook-123");
+		});
+	});
+
+	describe("Custom Handler", () => {
+		const handler = sourceHandlers.custom;
+
+		it("should extract event type from headers or body", () => {
+			expect(handler.getEventType({ "x-event-type": "custom.event" }, {})).toBe("custom.event");
+			expect(handler.getEventType({}, { event: "body.event" })).toBe("body.event");
+		});
+
+		it("should extract signature from headers", () => {
+			const headers = { "x-signature": "sig123" };
+			expect(handler.getSignature(headers)).toBe("sig123");
+		});
+
+		it("should verify valid custom signature", () => {
+			const secret = "custom-secret";
+			const rawBody = '{"data":"test"}';
+			const hmac = crypto.createHmac("sha256", secret);
+			const signature = hmac.update(rawBody).digest("hex");
+
+			const result = handler.verifySignature(rawBody, signature, secret);
+			expect(result.valid).toBe(true);
+		});
+	});
+});
+
+describe("WebhookTriggerOpts Schema", () => {
+	it("should validate webhook trigger configuration", () => {
+		const validConfig = {
+			source: "github",
+			events: ["push", "pull_request.*"],
+			secret: "my-webhook-secret",
+			path: "/webhooks/github",
+		};
+
+		expect(validConfig.source).toBe("github");
+		expect(validConfig.events).toContain("push");
+		expect(validConfig.secret).toBeDefined();
+	});
+
+	it("should support wildcard events", () => {
+		const config = {
+			source: "stripe",
+			events: ["payment_intent.*", "checkout.session.*"],
+		};
+
+		expect(config.events).toContain("payment_intent.*");
+	});
+});