@better-webhook/cli 3.3.0 → 3.4.1

package/dist/core/dashboard-server.js

@@ -0,0 +1,124 @@
+import express from "express";
+import { createServer } from "http";
+import { WebSocketServer } from "ws";
+import path from "path";
+import { existsSync } from "fs";
+import { fileURLToPath } from "url";
+import { createDashboardApiRouter, } from "./dashboard-api.js";
+import { CaptureServer } from "./capture-server.js";
+import { ReplayEngine } from "./replay-engine.js";
+import { TemplateManager } from "./template-manager.js";
+function resolveDashboardDistDir(runtimeDir) {
+    const candidates = [
+        path.resolve(runtimeDir, "dashboard"),
+        path.resolve(runtimeDir, "..", "dashboard"),
+        path.resolve(runtimeDir, "..", "..", "dist", "dashboard"),
+        path.resolve(runtimeDir, "..", "..", "..", "dashboard", "dist"),
+    ];
+    for (const distDir of candidates) {
+        const indexHtml = path.join(distDir, "index.html");
+        if (existsSync(indexHtml)) {
+            return { distDir, indexHtml };
+        }
+    }
+    const details = candidates.map((p) => `- ${p}`).join("\n");
+    throw new Error(`Dashboard UI build output not found.\n` +
+        `Looked in:\n${details}\n\n` +
+        `Build it with:\n` +
+        `- pnpm --filter @better-webhook/dashboard build\n` +
+        `- pnpm --filter @better-webhook/cli build\n`);
+}
+export async function startDashboardServer(options = {}) {
+    const app = express();
+    app.get("/health", (_req, res) => {
+        res.json({ ok: true });
+    });
+    const clients = new Set();
+    const broadcast = (message) => {
+        const data = JSON.stringify(message);
+        for (const client of clients) {
+            if (client.readyState === 1) {
+                client.send(data);
+            }
+        }
+    };
+    app.use("/api", createDashboardApiRouter({
+        capturesDir: options.capturesDir,
+        templatesBaseDir: options.templatesBaseDir,
+        broadcast,
+    }));
+    const host = options.host || "localhost";
+    const port = options.port ?? 4000;
+    const runtimeDir = typeof __dirname !== "undefined"
+        ?
+            __dirname
+        : path.dirname(fileURLToPath(import.meta.url));
+    const { distDir: dashboardDistDir, indexHtml: dashboardIndexHtml } = resolveDashboardDistDir(runtimeDir);
+    app.use(express.static(dashboardDistDir));
+    app.get("*", (req, res, next) => {
+        if (req.path.startsWith("/api") || req.path === "/health")
+            return next();
+        res.sendFile(dashboardIndexHtml, (err) => {
+            if (err)
+                next();
+        });
+    });
+    const server = createServer(app);
+    const wss = new WebSocketServer({ server, path: "/ws" });
+    wss.on("connection", async (ws) => {
+        clients.add(ws);
+        ws.on("close", () => clients.delete(ws));
+        ws.on("error", () => clients.delete(ws));
+        const replayEngine = new ReplayEngine(options.capturesDir);
+        const templateManager = new TemplateManager(options.templatesBaseDir);
+        const captures = replayEngine.listCaptures(200);
+        ws.send(JSON.stringify({
+            type: "captures_updated",
+            payload: { captures, count: captures.length },
+        }));
+        const local = templateManager.listLocalTemplates();
+        let remote = [];
+        try {
+            const index = await templateManager.fetchRemoteIndex(true);
+            const localIds = new Set(local.map((t) => t.id));
+            remote = index.templates.map((metadata) => ({
+                metadata,
+                isDownloaded: localIds.has(metadata.id),
+            }));
+        }
+        catch {
+            remote = [];
+        }
+        ws.send(JSON.stringify({
+            type: "templates_updated",
+            payload: { local, remote },
+        }));
+    });
+    await new Promise((resolve, reject) => {
+        server.listen(port, host, () => resolve());
+        server.on("error", reject);
+    });
+    const url = `http://${host}:${port}`;
+    let capture;
+    const shouldStartCapture = options.startCapture !== false;
+    if (shouldStartCapture) {
+        const captureHost = options.captureHost || "0.0.0.0";
+        const capturePort = options.capturePort ?? 3001;
+        const captureServer = new CaptureServer({
+            capturesDir: options.capturesDir,
+            enableWebSocket: false,
+            onCapture: ({ file, capture }) => {
+                broadcast({
+                    type: "capture",
+                    payload: { file, capture },
+                });
+            },
+        });
+        const actualPort = await captureServer.start(capturePort, captureHost);
+        capture = {
+            server: captureServer,
+            url: `http://${captureHost === "0.0.0.0" ? "localhost" : captureHost}:${actualPort}`,
+        };
+    }
+    return { app, server, url, capture };
+}

package/dist/core/executor.d.ts

@@ -0,0 +1,11 @@
+import type { WebhookExecutionOptions, WebhookExecutionResult, HeaderEntry, WebhookTemplate } from "../types/index.js";
+export declare function executeWebhook(options: WebhookExecutionOptions): Promise<WebhookExecutionResult>;
+export declare function executeTemplate(template: WebhookTemplate, options?: {
+    url?: string;
+    secret?: string;
+    headers?: HeaderEntry[];
+}): Promise<WebhookExecutionResult>;
+export declare class ExecutionError extends Error {
+    duration: number;
+    constructor(message: string, duration: number);
+}

package/dist/core/executor.js

@@ -0,0 +1,130 @@
+import { request } from "undici";
+import { generateSignature, getProviderHeaders } from "./signature.js";
+export async function executeWebhook(options) {
+    const startTime = Date.now();
+    let bodyStr;
+    if (options.body !== undefined) {
+        bodyStr =
+            typeof options.body === "string"
+                ? options.body
+                : JSON.stringify(options.body);
+    }
+    const headers = {};
+    if (options.provider) {
+        const providerHeaders = getProviderHeaders(options.provider);
+        for (const h of providerHeaders) {
+            headers[h.key] = h.value;
+        }
+    }
+    if (options.headers) {
+        for (const h of options.headers) {
+            headers[h.key] = h.value;
+        }
+    }
+    if (options.secret && options.provider && bodyStr) {
+        const sig = generateSignature(options.provider, bodyStr, options.secret, {
+            url: options.url,
+        });
+        if (sig) {
+            headers[sig.header] = sig.value;
+        }
+    }
+    if (!headers["Content-Type"] && !headers["content-type"]) {
+        headers["Content-Type"] = "application/json";
+    }
+    try {
+        const response = await request(options.url, {
+            method: options.method || "POST",
+            headers,
+            body: bodyStr,
+            headersTimeout: options.timeout || 30000,
+            bodyTimeout: options.timeout || 30000,
+        });
+        const bodyText = await response.body.text();
+        const duration = Date.now() - startTime;
+        const responseHeaders = {};
+        for (const [key, value] of Object.entries(response.headers)) {
+            if (value !== undefined) {
+                responseHeaders[key] = value;
+            }
+        }
+        let json;
+        try {
+            json = JSON.parse(bodyText);
+        }
+        catch {
+        }
+        return {
+            status: response.statusCode,
+            statusText: getStatusText(response.statusCode),
+            headers: responseHeaders,
+            body: json ?? bodyText,
+            bodyText,
+            json,
+            duration,
+        };
+    }
+    catch (error) {
+        const duration = Date.now() - startTime;
+        throw new ExecutionError(error.message, duration);
+    }
+}
+export async function executeTemplate(template, options = {}) {
+    const targetUrl = options.url || template.url;
+    if (!targetUrl) {
+        throw new Error("No target URL specified. Use --url or set url in template.");
+    }
+    const mergedHeaders = [...(template.headers || [])];
+    if (options.headers) {
+        for (const h of options.headers) {
+            const existingIdx = mergedHeaders.findIndex((mh) => mh.key.toLowerCase() === h.key.toLowerCase());
+            if (existingIdx >= 0) {
+                mergedHeaders[existingIdx] = h;
+            }
+            else {
+                mergedHeaders.push(h);
+            }
+        }
+    }
+    return executeWebhook({
+        url: targetUrl,
+        method: template.method,
+        headers: mergedHeaders,
+        body: template.body,
+        secret: options.secret,
+        provider: template.provider,
+    });
+}
+export class ExecutionError extends Error {
+    duration;
+    constructor(message, duration) {
+        super(message);
+        this.name = "ExecutionError";
+        this.duration = duration;
+    }
+}
+function getStatusText(code) {
+    const statusTexts = {
+        200: "OK",
+        201: "Created",
+        202: "Accepted",
+        204: "No Content",
+        301: "Moved Permanently",
+        302: "Found",
+        304: "Not Modified",
+        400: "Bad Request",
+        401: "Unauthorized",
+        403: "Forbidden",
+        404: "Not Found",
+        405: "Method Not Allowed",
+        408: "Request Timeout",
+        409: "Conflict",
+        422: "Unprocessable Entity",
+        429: "Too Many Requests",
+        500: "Internal Server Error",
+        502: "Bad Gateway",
+        503: "Service Unavailable",
+        504: "Gateway Timeout",
+    };
+    return statusTexts[code] || "Unknown";
+}

package/dist/core/index.d.ts

@@ -0,0 +1,5 @@
+export * from "./template-manager.js";
+export * from "./signature.js";
+export * from "./capture-server.js";
+export * from "./replay-engine.js";
+export * from "./executor.js";

package/dist/core/index.js

@@ -0,0 +1,5 @@
+export * from "./template-manager.js";
+export * from "./signature.js";
+export * from "./capture-server.js";
+export * from "./replay-engine.js";
+export * from "./executor.js";

package/dist/core/replay-engine.d.ts

@@ -0,0 +1,18 @@
+import type { CaptureFile, ReplayOptions, WebhookExecutionResult, WebhookTemplate } from "../types/index.js";
+export declare class ReplayEngine {
+    private capturesDir;
+    constructor(capturesDir?: string);
+    getCapturesDir(): string;
+    listCaptures(limit?: number): CaptureFile[];
+    getCapture(captureId: string): CaptureFile | null;
+    replay(captureId: string, options: ReplayOptions): Promise<WebhookExecutionResult>;
+    captureToTemplate(captureId: string, options?: {
+        url?: string;
+    }): WebhookTemplate;
+    getCaptureSummary(captureId: string): string;
+    searchCaptures(query: string): CaptureFile[];
+    getCapturesByProvider(provider: string): CaptureFile[];
+    deleteCapture(captureId: string): boolean;
+    deleteAllCaptures(): number;
+}
+export declare function getReplayEngine(capturesDir?: string): ReplayEngine;

package/dist/core/replay-engine.js

@@ -0,0 +1,208 @@
+import { existsSync, readFileSync, readdirSync, unlinkSync } from "fs";
+import { join } from "path";
+import { homedir } from "os";
+import { executeWebhook } from "./executor.js";
+export class ReplayEngine {
+    capturesDir;
+    constructor(capturesDir) {
+        this.capturesDir =
+            capturesDir || join(homedir(), ".better-webhook", "captures");
+    }
+    getCapturesDir() {
+        return this.capturesDir;
+    }
+    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);
+        let found = captures.find((c) => c.capture.id === captureId);
+        if (found)
+            return found;
+        found = captures.find((c) => c.file.includes(captureId));
+        if (found)
+            return found;
+        found = captures.find((c) => c.capture.id.startsWith(captureId));
+        return found || null;
+    }
+    async replay(captureId, options) {
+        const captureFile = this.getCapture(captureId);
+        if (!captureFile) {
+            throw new Error(`Capture not found: ${captureId}`);
+        }
+        const { capture } = captureFile;
+        const headers = [];
+        const skipHeaders = [
+            "host",
+            "content-length",
+            "connection",
+            "accept-encoding",
+        ];
+        for (const [key, value] of Object.entries(capture.headers)) {
+            if (!skipHeaders.includes(key.toLowerCase())) {
+                const headerValue = Array.isArray(value) ? value.join(", ") : value;
+                if (headerValue) {
+                    headers.push({ key, value: headerValue });
+                }
+            }
+        }
+        if (options.headers) {
+            for (const h of options.headers) {
+                const existingIdx = headers.findIndex((eh) => eh.key.toLowerCase() === h.key.toLowerCase());
+                if (existingIdx >= 0) {
+                    headers[existingIdx] = h;
+                }
+                else {
+                    headers.push(h);
+                }
+            }
+        }
+        const body = capture.rawBody || capture.body;
+        return executeWebhook({
+            url: options.targetUrl,
+            method: options.method || capture.method,
+            headers,
+            body,
+        });
+    }
+    captureToTemplate(captureId, options) {
+        const captureFile = this.getCapture(captureId);
+        if (!captureFile) {
+            throw new Error(`Capture not found: ${captureId}`);
+        }
+        const { capture } = captureFile;
+        const skipHeaders = [
+            "host",
+            "content-length",
+            "connection",
+            "accept-encoding",
+            "stripe-signature",
+            "x-hub-signature-256",
+            "x-hub-signature",
+            "x-shopify-hmac-sha256",
+            "x-twilio-signature",
+            "x-slack-signature",
+            "svix-signature",
+            "linear-signature",
+        ];
+        const headers = [];
+        for (const [key, value] of Object.entries(capture.headers)) {
+            if (!skipHeaders.includes(key.toLowerCase())) {
+                const headerValue = Array.isArray(value) ? value.join(", ") : value;
+                if (headerValue) {
+                    headers.push({ key, value: headerValue });
+                }
+            }
+        }
+        let body;
+        if (capture.body) {
+            body = capture.body;
+        }
+        else if (capture.rawBody) {
+            try {
+                body = JSON.parse(capture.rawBody);
+            }
+            catch {
+                body = capture.rawBody;
+            }
+        }
+        return {
+            url: options?.url || `http://localhost:3000${capture.path}`,
+            method: capture.method,
+            headers,
+            body,
+            provider: capture.provider,
+            description: `Captured ${capture.provider || "webhook"} at ${capture.timestamp}`,
+        };
+    }
+    getCaptureSummary(captureId) {
+        const captureFile = this.getCapture(captureId);
+        if (!captureFile) {
+            return "Capture not found";
+        }
+        const { capture } = captureFile;
+        const lines = [];
+        lines.push(`ID: ${capture.id}`);
+        lines.push(`Timestamp: ${new Date(capture.timestamp).toLocaleString()}`);
+        lines.push(`Method: ${capture.method}`);
+        lines.push(`Path: ${capture.path}`);
+        if (capture.provider) {
+            lines.push(`Provider: ${capture.provider}`);
+        }
+        lines.push(`Content-Type: ${capture.contentType || "unknown"}`);
+        lines.push(`Body Size: ${capture.contentLength || 0} bytes`);
+        const headerCount = Object.keys(capture.headers).length;
+        lines.push(`Headers: ${headerCount}`);
+        return lines.join("\n");
+    }
+    searchCaptures(query) {
+        const queryLower = query.toLowerCase();
+        const captures = this.listCaptures(1000);
+        return captures.filter((c) => {
+            const { capture } = c;
+            return (capture.id.toLowerCase().includes(queryLower) ||
+                capture.path.toLowerCase().includes(queryLower) ||
+                capture.method.toLowerCase().includes(queryLower) ||
+                capture.provider?.toLowerCase().includes(queryLower) ||
+                c.file.toLowerCase().includes(queryLower));
+        });
+    }
+    getCapturesByProvider(provider) {
+        const captures = this.listCaptures(1000);
+        return captures.filter((c) => c.capture.provider === provider);
+    }
+    deleteCapture(captureId) {
+        const captureFile = this.getCapture(captureId);
+        if (!captureFile) {
+            return false;
+        }
+        try {
+            unlinkSync(join(this.capturesDir, captureFile.file));
+            return true;
+        }
+        catch {
+            return false;
+        }
+    }
+    deleteAllCaptures() {
+        if (!existsSync(this.capturesDir)) {
+            return 0;
+        }
+        const files = readdirSync(this.capturesDir).filter((f) => f.endsWith(".json"));
+        let deleted = 0;
+        for (const file of files) {
+            try {
+                unlinkSync(join(this.capturesDir, file));
+                deleted++;
+            }
+            catch {
+            }
+        }
+        return deleted;
+    }
+}
+let instance = null;
+export function getReplayEngine(capturesDir) {
+    if (!instance) {
+        instance = new ReplayEngine(capturesDir);
+    }
+    return instance;
+}

package/dist/core/signature.d.ts

@@ -0,0 +1,24 @@
+import type { WebhookProvider, GeneratedSignature, HeaderEntry } from "../types/index.js";
+export declare function generateStripeSignature(payload: string, secret: string, timestamp?: number): GeneratedSignature;
+export declare function generateGitHubSignature(payload: string, secret: string): GeneratedSignature;
+export declare function generateShopifySignature(payload: string, secret: string): GeneratedSignature;
+export declare function generateTwilioSignature(payload: string, secret: string, url: string): GeneratedSignature;
+export declare function generateSlackSignature(payload: string, secret: string, timestamp?: number): GeneratedSignature;
+export declare function generateLinearSignature(payload: string, secret: string): GeneratedSignature;
+export declare function generateClerkSignature(payload: string, secret: string, timestamp?: number, webhookId?: string): GeneratedSignature;
+export declare function generateSendGridSignature(payload: string, secret: string, timestamp?: number): GeneratedSignature;
+export declare function generateRagieSignature(payload: string, secret: string): GeneratedSignature;
+export declare function generateSignature(provider: WebhookProvider, payload: string, secret: string, options?: {
+    timestamp?: number;
+    url?: string;
+    webhookId?: string;
+}): GeneratedSignature | null;
+export declare function getProviderHeaders(provider: WebhookProvider, options?: {
+    timestamp?: number;
+    webhookId?: string;
+    event?: string;
+}): HeaderEntry[];
+export declare function verifySignature(provider: WebhookProvider, payload: string, signature: string, secret: string, options?: {
+    timestamp?: number;
+    url?: string;
+}): boolean;