@better-webhook/cli 3.9.0 → 3.10.0

package/dist/core/capture-server.js

@@ -0,0 +1,400 @@
+import { createServer, } from "http";
+import { WebSocketServer } from "ws";
+import { writeFileSync, mkdirSync, existsSync, readdirSync, readFileSync, unlinkSync, } from "fs";
+import { join } from "path";
+import { randomUUID } from "crypto";
+import { homedir } from "os";
+export class CaptureServer {
+    server = null;
+    wss = null;
+    capturesDir;
+    clients = new Set();
+    captureCount = 0;
+    enableWebSocket;
+    onCapture;
+    verbose;
+    constructor(options) {
+        const capturesDir = typeof options === "string" ? options : options?.capturesDir;
+        this.capturesDir =
+            capturesDir || join(homedir(), ".better-webhook", "captures");
+        this.enableWebSocket =
+            typeof options === "object" ? options?.enableWebSocket !== false : true;
+        this.onCapture =
+            typeof options === "object" ? options?.onCapture : undefined;
+        this.verbose =
+            typeof options === "object" ? options?.verbose === true : false;
+        if (!existsSync(this.capturesDir)) {
+            mkdirSync(this.capturesDir, { recursive: true });
+        }
+    }
+    getCapturesDir() {
+        return this.capturesDir;
+    }
+    async start(port = 3001, host = "0.0.0.0") {
+        return new Promise((resolve, reject) => {
+            this.server = createServer((req, res) => this.handleRequest(req, res));
+            if (this.enableWebSocket) {
+                this.wss = new WebSocketServer({ server: this.server });
+                this.wss.on("connection", (ws) => {
+                    this.clients.add(ws);
+                    console.log("📡 Dashboard connected via WebSocket");
+                    ws.on("close", () => {
+                        this.clients.delete(ws);
+                        console.log("📡 Dashboard disconnected");
+                    });
+                    ws.on("error", (error) => {
+                        console.error("WebSocket error:", error);
+                        this.clients.delete(ws);
+                    });
+                    this.sendToClient(ws, {
+                        type: "captures_updated",
+                        payload: {
+                            captures: this.listCaptures(),
+                            count: this.captureCount,
+                        },
+                    });
+                });
+            }
+            this.server.on("error", (err) => {
+                if (err.code === "EADDRINUSE") {
+                    reject(new Error(`Port ${port} is already in use`));
+                }
+                else {
+                    reject(err);
+                }
+            });
+            this.server.listen(port, host, () => {
+                const address = this.server?.address();
+                const actualPort = typeof address === "object" ? address?.port || port : port;
+                console.log(`\n🎣 Webhook Capture Server`);
+                console.log(`   Listening on http://${host === "0.0.0.0" ? "localhost" : host}:${actualPort}`);
+                console.log(`   📁 Captures saved to: ${this.capturesDir}`);
+                console.log(`   💡 Send webhooks to any path to capture them`);
+                if (this.enableWebSocket) {
+                    console.log(`   🌐 WebSocket available for real-time updates`);
+                }
+                console.log(`   ⏹️  Press Ctrl+C to stop\n`);
+                resolve(actualPort);
+            });
+        });
+    }
+    async stop() {
+        return new Promise((resolve) => {
+            for (const client of this.clients) {
+                client.close();
+            }
+            this.clients.clear();
+            if (this.wss) {
+                this.wss.close();
+                this.wss = null;
+            }
+            if (this.server) {
+                this.server.close(() => {
+                    console.log("\n🛑 Capture server stopped");
+                    resolve();
+                });
+            }
+            else {
+                resolve();
+            }
+        });
+    }
+    async handleRequest(req, res) {
+        if (req.headers.upgrade?.toLowerCase() === "websocket") {
+            return;
+        }
+        const timestamp = new Date().toISOString();
+        const id = randomUUID();
+        const url = req.url || "/";
+        const hostHeader = req.headers.host;
+        const hostValue = typeof hostHeader === "string" ? hostHeader : "";
+        const isHostSafe = /^[a-z0-9.-]+(:\d+)?$/i.test(hostValue);
+        const baseUrl = isHostSafe ? `http://${hostValue}` : "http://localhost";
+        let urlParts;
+        try {
+            urlParts = new URL(url, baseUrl);
+        }
+        catch {
+            urlParts = new URL(url, "http://localhost");
+        }
+        const query = {};
+        for (const [key, value] of urlParts.searchParams.entries()) {
+            if (query[key]) {
+                if (Array.isArray(query[key])) {
+                    query[key].push(value);
+                }
+                else {
+                    query[key] = [query[key], value];
+                }
+            }
+            else {
+                query[key] = value;
+            }
+        }
+        const chunks = [];
+        for await (const chunk of req) {
+            chunks.push(chunk);
+        }
+        const rawBody = Buffer.concat(chunks).toString("utf8");
+        let body = null;
+        const contentType = req.headers["content-type"] || "";
+        if (rawBody) {
+            if (contentType.includes("application/json")) {
+                try {
+                    body = JSON.parse(rawBody);
+                }
+                catch {
+                    body = rawBody;
+                }
+            }
+            else if (contentType.includes("application/x-www-form-urlencoded")) {
+                body = Object.fromEntries(new URLSearchParams(rawBody));
+            }
+            else {
+                body = rawBody;
+            }
+        }
+        const provider = this.detectProvider(req.headers, body);
+        const captured = {
+            id,
+            timestamp,
+            method: (req.method || "GET"),
+            url,
+            path: urlParts.pathname,
+            headers: req.headers,
+            body,
+            rawBody,
+            query,
+            provider,
+            contentType: contentType || undefined,
+            contentLength: rawBody.length,
+        };
+        const date = new Date(timestamp);
+        const dateStr = date.toISOString().split("T")[0];
+        const timeStr = date
+            .toISOString()
+            .split("T")[1]
+            ?.replace(/[:.]/g, "-")
+            .slice(0, 8);
+        const filename = `${dateStr}_${timeStr}_${id.slice(0, 8)}.json`;
+        const filepath = join(this.capturesDir, filename);
+        try {
+            writeFileSync(filepath, JSON.stringify(captured, null, 2));
+            this.captureCount++;
+            const providerStr = provider ? ` [${provider}]` : "";
+            console.log(`📦 ${req.method} ${urlParts.pathname}${providerStr} -> ${filename}`);
+            if (this.verbose) {
+                const headerEntries = Object.entries(req.headers)
+                    .map(([key, value]) => {
+                    if (Array.isArray(value)) {
+                        return `${key}: ${value.join(", ")}`;
+                    }
+                    if (value === undefined) {
+                        return `${key}:`;
+                    }
+                    return `${key}: ${value}`;
+                })
+                    .join("\n");
+                const method = req.method || "GET";
+                const providerLabel = provider || "unknown";
+                const contentTypeLabel = contentType || "(none)";
+                console.log([
+                    "[debug] request",
+                    `method: ${method}`,
+                    `path: ${urlParts.pathname}`,
+                    `provider: ${providerLabel}`,
+                    `content-type: ${contentTypeLabel}`,
+                    `body-length: ${rawBody.length}`,
+                    "headers:",
+                    headerEntries || "(none)",
+                    "raw-body:",
+                    rawBody,
+                ].join("\n"));
+            }
+            this.onCapture?.({ file: filename, capture: captured });
+            if (this.enableWebSocket) {
+                this.broadcast({
+                    type: "capture",
+                    payload: {
+                        file: filename,
+                        capture: captured,
+                    },
+                });
+            }
+        }
+        catch (error) {
+            console.error(`❌ Failed to save capture:`, error);
+        }
+        res.statusCode = 200;
+        res.setHeader("Content-Type", "application/json");
+        res.setHeader("X-Capture-Id", id);
+        res.end(JSON.stringify({
+            success: true,
+            message: "Webhook captured successfully",
+            id,
+            timestamp,
+            file: filename,
+        }));
+    }
+    detectProvider(headers, body) {
+        if (headers["stripe-signature"]) {
+            return "stripe";
+        }
+        if (headers["x-github-event"] || headers["x-hub-signature-256"]) {
+            return "github";
+        }
+        if (headers["x-signature"]) {
+            if (body &&
+                typeof body === "object" &&
+                "type" in body &&
+                "payload" in body &&
+                "nonce" in body) {
+                return "ragie";
+            }
+        }
+        if (this.hasStandardWebhookHeaders(headers)) {
+            const recallUserAgent = this.headerIncludes(headers["user-agent"], "recall");
+            if (recallUserAgent || this.hasRecallStandardWebhookShape(body)) {
+                return "recall";
+            }
+        }
+        if (headers["x-shopify-hmac-sha256"] || headers["x-shopify-topic"]) {
+            return "shopify";
+        }
+        if (headers["x-twilio-signature"]) {
+            return "twilio";
+        }
+        if (headers["x-twilio-email-event-webhook-signature"]) {
+            return "sendgrid";
+        }
+        if (headers["x-slack-signature"]) {
+            return "slack";
+        }
+        if (headers["x-signature-ed25519"]) {
+            return "discord";
+        }
+        if (headers["linear-signature"]) {
+            return "linear";
+        }
+        if (headers["svix-signature"]) {
+            if (body &&
+                typeof body === "object" &&
+                "event" in body &&
+                typeof body.event === "string" &&
+                body.event.startsWith("bot.")) {
+                return "recall";
+            }
+            return "clerk";
+        }
+        return undefined;
+    }
+    broadcast(message) {
+        const data = JSON.stringify(message);
+        for (const client of this.clients) {
+            if (client.readyState === 1) {
+                client.send(data);
+            }
+        }
+    }
+    hasStandardWebhookHeaders(headers) {
+        return Boolean(headers["webhook-signature"] ||
+            (headers["webhook-id"] && headers["webhook-timestamp"]));
+    }
+    hasRecallStandardWebhookShape(body) {
+        if (!body || typeof body !== "object") {
+            return false;
+        }
+        const payload = body;
+        const event = payload.event;
+        if (typeof event === "string") {
+            const recallEventPrefixes = [
+                "bot.",
+                "transcript.",
+                "participant_events.",
+            ];
+            if (recallEventPrefixes.some((prefix) => event.startsWith(prefix))) {
+                return true;
+            }
+        }
+        if (this.hasRecallResourceKeys(payload)) {
+            return true;
+        }
+        const nestedData = payload.data;
+        if (nestedData && typeof nestedData === "object") {
+            return this.hasRecallResourceKeys(nestedData);
+        }
+        return false;
+    }
+    hasRecallResourceKeys(payload) {
+        return [
+            "bot",
+            "realtime_endpoint",
+            "participant_events",
+            "transcript",
+            "recording",
+        ].some((key) => key in payload);
+    }
+    headerIncludes(headerValue, searchText) {
+        const normalizedSearchText = searchText.toLowerCase();
+        if (typeof headerValue === "string") {
+            return headerValue.toLowerCase().includes(normalizedSearchText);
+        }
+        if (Array.isArray(headerValue)) {
+            return headerValue.some((value) => value.toLowerCase().includes(normalizedSearchText));
+        }
+        return false;
+    }
+    sendToClient(client, message) {
+        if (client.readyState === 1) {
+            client.send(JSON.stringify(message));
+        }
+    }
+    listCaptures(limit = 100) {
+        if (!existsSync(this.capturesDir)) {
+            return [];
+        }
+        const files = readdirSync(this.capturesDir)
+            .filter((f) => f.endsWith(".json"))
+            .sort()
+            .reverse()
+            .slice(0, limit);
+        const captures = [];
+        for (const file of files) {
+            try {
+                const content = readFileSync(join(this.capturesDir, file), "utf-8");
+                const capture = JSON.parse(content);
+                captures.push({ file, capture });
+            }
+            catch {
+            }
+        }
+        return captures;
+    }
+    getCapture(captureId) {
+        const captures = this.listCaptures(1000);
+        return (captures.find((c) => c.capture.id === captureId || c.file.includes(captureId)) || null);
+    }
+    deleteCapture(captureId) {
+        const capture = this.getCapture(captureId);
+        if (!capture) {
+            return false;
+        }
+        try {
+            unlinkSync(join(this.capturesDir, capture.file));
+            return true;
+        }
+        catch {
+            return false;
+        }
+    }
+    getClientCount() {
+        return this.clients.size;
+    }
+}
+let instance = null;
+export function getCaptureServer(capturesDir) {
+    if (!instance) {
+        instance = new CaptureServer(capturesDir);
+    }
+    return instance;
+}

package/dist/core/capture-server.test.d.ts

@@ -0,0 +1 @@
+export {};

package/dist/core/capture-server.test.js

@@ -0,0 +1,86 @@
+import { afterEach, beforeEach, describe, expect, it } from "vitest";
+import { mkdirSync, rmSync } from "node:fs";
+import { join } from "node:path";
+import { tmpdir } from "node:os";
+import { request } from "undici";
+import { CaptureServer } from "./capture-server.js";
+const sleep = (ms) => new Promise((resolve) => {
+    setTimeout(resolve, ms);
+});
+describe("CaptureServer provider detection", () => {
+    let capturesDir;
+    let server;
+    let port;
+    beforeEach(async () => {
+        capturesDir = join(tmpdir(), `better-webhook-capture-test-${Date.now()}`);
+        mkdirSync(capturesDir, { recursive: true });
+        server = new CaptureServer({ capturesDir, enableWebSocket: false });
+        port = await server.start(0, "127.0.0.1");
+    });
+    afterEach(async () => {
+        await server.stop();
+        rmSync(capturesDir, { recursive: true, force: true });
+    });
+    async function waitForCapturedProvider() {
+        for (let attempt = 0; attempt < 10; attempt++) {
+            const captures = server.listCaptures(1);
+            const provider = captures[0]?.capture.provider;
+            if (provider) {
+                return provider;
+            }
+            await sleep(25);
+        }
+        return undefined;
+    }
+    it("detects Recall from webhook verification headers", async () => {
+        const response = await request(`http://127.0.0.1:${port}/webhooks/recall`, {
+            method: "POST",
+            headers: {
+                "content-type": "application/json",
+                "webhook-id": "msg_test_123",
+                "webhook-timestamp": "1731705121",
+                "webhook-signature": "v1,abc123",
+            },
+            body: JSON.stringify({
+                event: "transcript.data",
+                data: { data: { words: [] } },
+            }),
+        });
+        expect(response.statusCode).toBe(200);
+        expect(await waitForCapturedProvider()).toBe("recall");
+    });
+    it("does not misclassify generic Standard Webhooks payloads as Recall", async () => {
+        const response = await request(`http://127.0.0.1:${port}/webhooks/generic`, {
+            method: "POST",
+            headers: {
+                "content-type": "application/json",
+                "webhook-id": "msg_test_generic_123",
+                "webhook-timestamp": "1731705121",
+                "webhook-signature": "v1,abc123",
+            },
+            body: JSON.stringify({
+                event: "user.created",
+                data: { id: "usr_123" },
+            }),
+        });
+        expect(response.statusCode).toBe(200);
+        expect(await waitForCapturedProvider()).toBeUndefined();
+    });
+    it("detects Recall from svix headers when event starts with bot.", async () => {
+        const response = await request(`http://127.0.0.1:${port}/webhooks/recall`, {
+            method: "POST",
+            headers: {
+                "content-type": "application/json",
+                "svix-id": "msg_test_234",
+                "svix-timestamp": "1731705121",
+                "svix-signature": "v1,abc123",
+            },
+            body: JSON.stringify({
+                event: "bot.done",
+                data: { data: { code: "done", sub_code: null, updated_at: "now" } },
+            }),
+        });
+        expect(response.statusCode).toBe(200);
+        expect(await waitForCapturedProvider()).toBe("recall");
+    });
+});

package/dist/core/cli-version.d.ts

@@ -0,0 +1 @@
+export declare function resolveRuntimePackageVersion(runtimeDir: string): string | undefined;

package/dist/core/cli-version.js

@@ -0,0 +1,30 @@
+import { readFileSync } from "node:fs";
+import path from "node:path";
+import { findCliPackageRoot } from "./runtime-paths.js";
+function readPackageVersion(packageJsonPath) {
+    try {
+        const packageJson = JSON.parse(readFileSync(packageJsonPath, { encoding: "utf8" }));
+        return typeof packageJson.version === "string" && packageJson.version
+            ? packageJson.version
+            : undefined;
+    }
+    catch {
+        return undefined;
+    }
+}
+export function resolveRuntimePackageVersion(runtimeDir) {
+    const searchDirs = [runtimeDir, path.resolve(runtimeDir, "..")];
+    const visitedRoots = new Set();
+    for (const searchDir of searchDirs) {
+        const cliPackageRoot = findCliPackageRoot(searchDir);
+        if (!cliPackageRoot || visitedRoots.has(cliPackageRoot)) {
+            continue;
+        }
+        visitedRoots.add(cliPackageRoot);
+        const version = readPackageVersion(path.join(cliPackageRoot, "package.json"));
+        if (version) {
+            return version;
+        }
+    }
+    return undefined;
+}

package/dist/core/cli-version.test.d.ts

@@ -0,0 +1 @@
+export {};

package/dist/core/cli-version.test.js

@@ -0,0 +1,42 @@
+import { afterEach, describe, expect, it } from "vitest";
+import { mkdirSync, mkdtempSync, rmSync, writeFileSync } from "node:fs";
+import { tmpdir } from "node:os";
+import path from "node:path";
+import { resolveRuntimePackageVersion } from "./cli-version.js";
+const tempDirs = [];
+function createTempDir(prefix) {
+    const tempDir = mkdtempSync(path.join(tmpdir(), prefix));
+    tempDirs.push(tempDir);
+    return tempDir;
+}
+function writePackageJson(dirPath, metadata) {
+    mkdirSync(dirPath, { recursive: true });
+    writeFileSync(path.join(dirPath, "package.json"), JSON.stringify(metadata));
+}
+afterEach(() => {
+    for (const tempDir of tempDirs) {
+        rmSync(tempDir, { recursive: true, force: true });
+    }
+    tempDirs.length = 0;
+});
+describe("resolveRuntimePackageVersion", () => {
+    it("returns CLI version from the resolved package root", () => {
+        const tempDir = createTempDir("better-webhook-cli-version-");
+        const cliRoot = path.join(tempDir, "node_modules", "@better-webhook", "cli");
+        const runtimeDir = path.join(cliRoot, "dist", "core");
+        writePackageJson(cliRoot, {
+            name: "@better-webhook/cli",
+            version: "3.8.0",
+        });
+        mkdirSync(runtimeDir, { recursive: true });
+        expect(resolveRuntimePackageVersion(runtimeDir)).toBe("3.8.0");
+    });
+    it("returns undefined when package roots do not match CLI names", () => {
+        const tempDir = createTempDir("better-webhook-cli-version-");
+        const runtimeRoot = path.join(tempDir, "runtime");
+        const runtimeDir = path.join(runtimeRoot, "dist", "core");
+        writePackageJson(runtimeRoot, { name: "consumer-app", version: "1.0.0" });
+        mkdirSync(runtimeDir, { recursive: true });
+        expect(resolveRuntimePackageVersion(runtimeDir)).toBeUndefined();
+    });
+});

package/dist/core/dashboard-api.d.ts

@@ -0,0 +1,8 @@
+import express from "express";
+import { type WebSocketMessage } from "../types/index.js";
+export interface DashboardApiOptions {
+    capturesDir?: string;
+    templatesBaseDir?: string;
+    broadcast?: (message: WebSocketMessage) => void;
+}
+export declare function createDashboardApiRouter(options?: DashboardApiOptions): express.Router;