@better-webhook/cli 3.3.0 → 3.4.0

package/README.md

@@ -18,6 +18,10 @@ A modern CLI tool for webhook development, testing, and debugging. Capture incom
 
 ## Supported Providers
 
+### Signature Generation Support
+
+The CLI can automatically generate signatures for the following providers when you provide a `--secret`:
+
 | Provider     | Signature Algorithm             | Auto-Detection |
 | ------------ | ------------------------------- | -------------- |
 | Stripe       | HMAC-SHA256 (`t={ts},v1={sig}`) | ✅             |
@@ -28,8 +32,16 @@ A modern CLI tool for webhook development, testing, and debugging. Capture incom
 | SendGrid     | HMAC-SHA256 (Base64)            | ✅             |
 | Linear       | HMAC-SHA256 (Hex)               | ✅             |
 | Clerk (Svix) | HMAC-SHA256 (`v1,{sig}`)        | ✅             |
-| Discord      | Ed25519                         | ✅             |
-| Custom       | —                               | —              |
+| Ragie        | HMAC-SHA256 (Hex)               | ✅             |
+
+### Detection Only (No Signature Generation)
+
+These providers are auto-detected from headers but signature generation is not yet implemented:
+
+| Provider | Notes                                                 |
+| -------- | ----------------------------------------------------- |
+| Discord  | Detected from headers; uses Ed25519 (not implemented) |
+| Custom   | Generic detection; no signature generation            |
 
 ## Installation
 
@@ -51,7 +63,6 @@ npx @better-webhook/cli --help
 
 ```bash
 better-webhook --version
-# 2.0.0
 ```
 
 ## Quick Start
@@ -379,15 +390,15 @@ By default, this command starts:
 better-webhook dashboard [options]
 ```
 
-| Option                    | Description                     | Default     |
-| ------------------------- | ------------------------------- | ----------- |
-| `-p, --port <port>`       | Dashboard server port           | `4000`      |
-| `-h, --host <host>`       | Dashboard server host           | `localhost` |
-| `--capture-port <port>`   | Capture server port             | `3001`      |
-| `--capture-host <host>`   | Capture server host             | `0.0.0.0`   |
-| `--no-capture`            | Do not start capture server     | —           |
-| `--captures-dir <dir>`    | Override captures directory     | —           |
-| `--templates-dir <dir>`   | Override templates base dir     | —           |
+| Option                  | Description                 | Default     |
+| ----------------------- | --------------------------- | ----------- |
+| `-p, --port <port>`     | Dashboard server port       | `4000`      |
+| `-h, --host <host>`     | Dashboard server host       | `localhost` |
+| `--capture-port <port>` | Capture server port         | `3001`      |
+| `--capture-host <host>` | Capture server host         | `0.0.0.0`   |
+| `--no-capture`          | Do not start capture server | —           |
+| `--captures-dir <dir>`  | Override captures directory | —           |
+| `--templates-dir <dir>` | Override templates base dir | —           |
 
 **Security note:**
 Keep the dashboard bound to `localhost` unless you trust your network. The API includes endpoints that can send HTTP requests to arbitrary URLs (run/replay).
@@ -408,6 +419,7 @@ The CLI automatically reads webhook secrets from environment variables based on
 | Linear   | `LINEAR_WEBHOOK_SECRET`   |
 | Clerk    | `CLERK_WEBHOOK_SECRET`    |
 | SendGrid | `SENDGRID_WEBHOOK_SECRET` |
+| Ragie    | `RAGIE_WEBHOOK_SECRET`    |
 | Discord  | `DISCORD_WEBHOOK_SECRET`  |
 | Custom   | `WEBHOOK_SECRET`          |
 

package/dist/commands/capture.d.ts

@@ -0,0 +1,2 @@
+import { Command } from "commander";
+export declare const capture: Command;

package/dist/commands/capture.js

@@ -0,0 +1,30 @@
+import { Command } from "commander";
+import chalk from "chalk";
+import { CaptureServer } from "../core/capture-server.js";
+export const capture = new Command()
+    .name("capture")
+    .description("Start a server to capture incoming webhooks")
+    .option("-p, --port <port>", "Port to listen on", "3001")
+    .option("-h, --host <host>", "Host to bind to", "0.0.0.0")
+    .action(async (options) => {
+    const port = parseInt(options.port, 10);
+    if (isNaN(port) || port < 0 || port > 65535) {
+        console.error(chalk.red("Invalid port number"));
+        process.exitCode = 1;
+        return;
+    }
+    const server = new CaptureServer();
+    try {
+        await server.start(port, options.host);
+        const shutdown = async () => {
+            await server.stop();
+            process.exit(0);
+        };
+        process.on("SIGINT", shutdown);
+        process.on("SIGTERM", shutdown);
+    }
+    catch (error) {
+        console.error(chalk.red(`Failed to start server: ${error.message}`));
+        process.exitCode = 1;
+    }
+});

package/dist/commands/captures.d.ts

@@ -0,0 +1,2 @@
+import { Command } from "commander";
+export declare const captures: Command;

package/dist/commands/captures.js

@@ -0,0 +1,217 @@
+import { Command } from "commander";
+import chalk from "chalk";
+import prompts from "prompts";
+import { getReplayEngine } from "../core/replay-engine.js";
+const listCommand = new Command()
+    .name("list")
+    .alias("ls")
+    .description("List captured webhooks")
+    .option("-l, --limit <limit>", "Maximum number of captures to show", "20")
+    .option("-p, --provider <provider>", "Filter by provider")
+    .action((options) => {
+    const limit = parseInt(options.limit, 10);
+    if (isNaN(limit) || limit <= 0) {
+        console.error(chalk.red("Invalid limit value"));
+        process.exitCode = 1;
+        return;
+    }
+    const engine = getReplayEngine();
+    let captures = engine.listCaptures(limit);
+    if (options.provider) {
+        captures = captures.filter((c) => c.capture.provider?.toLowerCase() === options.provider?.toLowerCase());
+    }
+    if (captures.length === 0) {
+        console.log(chalk.yellow("\n📭 No captured webhooks found."));
+        console.log(chalk.gray("   Start capturing with: better-webhook capture\n"));
+        return;
+    }
+    console.log(chalk.bold("\n📦 Captured Webhooks\n"));
+    for (const { file, capture } of captures) {
+        const date = new Date(capture.timestamp).toLocaleString();
+        const provider = capture.provider
+            ? chalk.cyan(`[${capture.provider}]`)
+            : chalk.gray("[unknown]");
+        const size = capture.contentLength || capture.rawBody?.length || 0;
+        console.log(`  ${chalk.white(capture.id.slice(0, 8))} ${provider}`);
+        console.log(chalk.gray(`    ${capture.method} ${capture.path}`));
+        console.log(chalk.gray(`    ${date} | ${size} bytes`));
+        console.log(chalk.gray(`    File: ${file}`));
+        console.log();
+    }
+    console.log(chalk.gray(`  Showing ${captures.length} captures`));
+    console.log(chalk.gray(`  Storage: ${engine.getCapturesDir()}\n`));
+});
+const showCommand = new Command()
+    .name("show")
+    .argument("<captureId>", "Capture ID or partial ID")
+    .description("Show detailed information about a capture")
+    .option("-b, --body", "Show full body content")
+    .action((captureId, options) => {
+    const engine = getReplayEngine();
+    const captureFile = engine.getCapture(captureId);
+    if (!captureFile) {
+        console.log(chalk.red(`\n❌ Capture not found: ${captureId}\n`));
+        process.exitCode = 1;
+        return;
+    }
+    const { capture } = captureFile;
+    console.log(chalk.bold("\n📋 Capture Details\n"));
+    console.log(`  ${chalk.gray("ID:")} ${capture.id}`);
+    console.log(`  ${chalk.gray("File:")} ${captureFile.file}`);
+    console.log(`  ${chalk.gray("Timestamp:")} ${new Date(capture.timestamp).toLocaleString()}`);
+    console.log(`  ${chalk.gray("Method:")} ${capture.method}`);
+    console.log(`  ${chalk.gray("Path:")} ${capture.path}`);
+    console.log(`  ${chalk.gray("URL:")} ${capture.url}`);
+    if (capture.provider) {
+        console.log(`  ${chalk.gray("Provider:")} ${chalk.cyan(capture.provider)}`);
+    }
+    console.log(`  ${chalk.gray("Content-Type:")} ${capture.contentType || "unknown"}`);
+    console.log(`  ${chalk.gray("Content-Length:")} ${capture.contentLength || 0} bytes`);
+    const queryKeys = Object.keys(capture.query);
+    if (queryKeys.length > 0) {
+        console.log(chalk.bold("\n  Query Parameters:"));
+        for (const [key, value] of Object.entries(capture.query)) {
+            const queryValue = Array.isArray(value) ? value.join(", ") : value;
+            console.log(chalk.gray(`    ${key}: ${queryValue}`));
+        }
+    }
+    console.log(chalk.bold("\n  Headers:"));
+    for (const [key, value] of Object.entries(capture.headers)) {
+        const headerValue = Array.isArray(value) ? value.join(", ") : value;
+        const display = headerValue.length > 80
+            ? headerValue.slice(0, 80) + "..."
+            : headerValue;
+        console.log(chalk.gray(`    ${key}: ${display}`));
+    }
+    if (options.body && capture.body) {
+        console.log(chalk.bold("\n  Body:"));
+        if (typeof capture.body === "object") {
+            console.log(chalk.gray(JSON.stringify(capture.body, null, 2)
+                .split("\n")
+                .map((l) => `    ${l}`)
+                .join("\n")));
+        }
+        else {
+            console.log(chalk.gray(`    ${capture.body}`));
+        }
+    }
+    else if (capture.body) {
+        console.log(chalk.bold("\n  Body:"));
+        const preview = JSON.stringify(capture.body).slice(0, 200);
+        console.log(chalk.gray(`    ${preview}${preview.length >= 200 ? "..." : ""}`));
+        console.log(chalk.gray("    Use --body to see full content"));
+    }
+    console.log();
+});
+const searchCommand = new Command()
+    .name("search")
+    .argument("<query>", "Search query")
+    .description("Search captures by path, method, or provider")
+    .action((query) => {
+    const engine = getReplayEngine();
+    const results = engine.searchCaptures(query);
+    if (results.length === 0) {
+        console.log(chalk.yellow(`\n📭 No captures found for: "${query}"\n`));
+        return;
+    }
+    console.log(chalk.bold(`\n🔍 Search Results for "${query}"\n`));
+    for (const { file, capture } of results) {
+        const date = new Date(capture.timestamp).toLocaleString();
+        const provider = capture.provider
+            ? chalk.cyan(`[${capture.provider}]`)
+            : "";
+        console.log(`  ${chalk.white(capture.id.slice(0, 8))} ${provider}`);
+        console.log(chalk.gray(`    ${capture.method} ${capture.path}`));
+        console.log(chalk.gray(`    ${date}`));
+        console.log();
+    }
+    console.log(chalk.gray(`  Found: ${results.length} captures\n`));
+});
+const deleteCommand = new Command()
+    .name("delete")
+    .alias("rm")
+    .argument("<captureId>", "Capture ID or partial ID to delete")
+    .description("Delete a specific captured webhook")
+    .option("-f, --force", "Skip confirmation prompt")
+    .action(async (captureId, options) => {
+    const engine = getReplayEngine();
+    const captureFile = engine.getCapture(captureId);
+    if (!captureFile) {
+        console.log(chalk.red(`\n❌ Capture not found: ${captureId}\n`));
+        process.exitCode = 1;
+        return;
+    }
+    const { capture } = captureFile;
+    if (!options.force) {
+        console.log(chalk.bold("\n🗑️  Capture to delete:\n"));
+        console.log(`    ${chalk.white(capture.id.slice(0, 8))}`);
+        console.log(chalk.gray(`    ${capture.method} ${capture.path}`));
+        console.log(chalk.gray(`    ${new Date(capture.timestamp).toLocaleString()}`));
+        console.log();
+        const response = await prompts({
+            type: "confirm",
+            name: "confirm",
+            message: "Delete this capture?",
+            initial: false,
+        });
+        if (!response.confirm) {
+            console.log(chalk.yellow("Cancelled"));
+            return;
+        }
+    }
+    const deleted = engine.deleteCapture(captureId);
+    if (deleted) {
+        console.log(chalk.green(`\n✓ Deleted capture: ${capture.id.slice(0, 8)}\n`));
+    }
+    else {
+        console.log(chalk.red(`\n❌ Failed to delete capture\n`));
+        process.exitCode = 1;
+    }
+});
+const cleanCommand = new Command()
+    .name("clean")
+    .alias("remove-all")
+    .description("Remove all captured webhooks")
+    .option("-f, --force", "Skip confirmation prompt")
+    .action(async (options) => {
+    const engine = getReplayEngine();
+    const captures = engine.listCaptures(10000);
+    if (captures.length === 0) {
+        console.log(chalk.yellow("\n📭 No captures to remove.\n"));
+        return;
+    }
+    console.log(chalk.bold(`\n🗑️  Found ${captures.length} captured webhook(s)\n`));
+    const byProvider = new Map();
+    for (const c of captures) {
+        const provider = c.capture.provider || "unknown";
+        byProvider.set(provider, (byProvider.get(provider) || 0) + 1);
+    }
+    for (const [provider, count] of byProvider) {
+        console.log(chalk.gray(`    ${provider}: ${count}`));
+    }
+    console.log();
+    if (!options.force) {
+        const response = await prompts({
+            type: "confirm",
+            name: "confirm",
+            message: `Delete all ${captures.length} capture(s)?`,
+            initial: false,
+        });
+        if (!response.confirm) {
+            console.log(chalk.yellow("Cancelled"));
+            return;
+        }
+    }
+    const deleted = engine.deleteAllCaptures();
+    console.log(chalk.green(`\n✓ Removed ${deleted} capture(s)`));
+    console.log(chalk.gray(`  Storage: ${engine.getCapturesDir()}\n`));
+});
+export const captures = new Command()
+    .name("captures")
+    .alias("c")
+    .description("Manage captured webhooks")
+    .addCommand(listCommand)
+    .addCommand(showCommand)
+    .addCommand(searchCommand)
+    .addCommand(deleteCommand)
+    .addCommand(cleanCommand);

package/dist/commands/dashboard.d.ts

@@ -0,0 +1,2 @@
+import { Command } from "commander";
+export declare const dashboard: Command;

package/dist/commands/dashboard.js

@@ -0,0 +1,63 @@
+import { Command } from "commander";
+import chalk from "chalk";
+import { startDashboardServer } from "../core/dashboard-server.js";
+export const dashboard = new Command()
+    .name("dashboard")
+    .description("Start the local dashboard (UI + API + WebSocket) server")
+    .option("-p, --port <port>", "Port to listen on", "4000")
+    .option("-h, --host <host>", "Host to bind to", "localhost")
+    .option("--capture-port <port>", "Capture server port", "3001")
+    .option("--capture-host <host>", "Capture server host", "0.0.0.0")
+    .option("--no-capture", "Do not start the capture server")
+    .option("--captures-dir <dir>", "Override captures directory")
+    .option("--templates-dir <dir>", "Override templates base directory")
+    .action(async (options) => {
+    const port = Number.parseInt(String(options.port), 10);
+    if (!Number.isFinite(port) || port < 0 || port > 65535) {
+        console.error(chalk.red("Invalid port number"));
+        process.exitCode = 1;
+        return;
+    }
+    try {
+        const capturePort = Number.parseInt(String(options.capturePort), 10);
+        if (!Number.isFinite(capturePort) || capturePort < 0 || capturePort > 65535) {
+            console.error(chalk.red("Invalid capture port number"));
+            process.exitCode = 1;
+            return;
+        }
+        const { url, server, capture } = await startDashboardServer({
+            host: options.host,
+            port,
+            captureHost: options.captureHost,
+            capturePort,
+            startCapture: options.capture !== false,
+            capturesDir: options.capturesDir,
+            templatesBaseDir: options.templatesDir,
+        });
+        console.log(chalk.bold("\n🧭 Dashboard Server\n"));
+        console.log(chalk.gray(`   Dashboard: ${url}/`));
+        console.log(chalk.gray(`   Health: ${url}/health`));
+        console.log(chalk.gray(`   API Base: ${url}/api`));
+        console.log(chalk.gray(`   WebSocket: ${url.replace("http://", "ws://")}/ws`));
+        if (capture) {
+            console.log();
+            console.log(chalk.bold("🎣 Capture Server"));
+            console.log(chalk.gray(`   Capture: ${capture.url}`));
+            console.log(chalk.gray(`   Tip: Send webhooks to any path, e.g. ${capture.url}/webhooks/github`));
+        }
+        console.log();
+        const shutdown = async () => {
+            if (capture) {
+                await capture.server.stop();
+            }
+            await new Promise((resolve) => server.close(() => resolve()));
+            process.exit(0);
+        };
+        process.on("SIGINT", shutdown);
+        process.on("SIGTERM", shutdown);
+    }
+    catch (error) {
+        console.error(chalk.red(`Failed to start dashboard server: ${error?.message || error}`));
+        process.exitCode = 1;
+    }
+});

package/dist/commands/index.d.ts

@@ -0,0 +1,6 @@
+export { templates } from "./templates.js";
+export { run } from "./run.js";
+export { capture } from "./capture.js";
+export { captures } from "./captures.js";
+export { replay } from "./replay.js";
+export { dashboard } from "./dashboard.js";

package/dist/commands/index.js

@@ -0,0 +1,6 @@
+export { templates } from "./templates.js";
+export { run } from "./run.js";
+export { capture } from "./capture.js";
+export { captures } from "./captures.js";
+export { replay } from "./replay.js";
+export { dashboard } from "./dashboard.js";

package/dist/commands/replay.d.ts

@@ -0,0 +1,2 @@
+import { Command } from "commander";
+export declare const replay: Command;

package/dist/commands/replay.js

@@ -0,0 +1,140 @@
+import { Command } from "commander";
+import ora from "ora";
+import prompts from "prompts";
+import chalk from "chalk";
+import { getReplayEngine } from "../core/replay-engine.js";
+export const replay = new Command()
+    .name("replay")
+    .argument("[captureId]", "Capture ID to replay")
+    .argument("[targetUrl]", "Target URL to replay to")
+    .description("Replay a captured webhook to a target URL")
+    .option("-m, --method <method>", "Override HTTP method")
+    .option("-H, --header <header>", "Add or override header (format: key:value)", (value, previous) => {
+    const [key, ...valueParts] = value.split(":");
+    const headerValue = valueParts.join(":");
+    if (!key || !headerValue) {
+        throw new Error("Header format should be key:value");
+    }
+    return (previous || []).concat([
+        { key: key.trim(), value: headerValue.trim() },
+    ]);
+}, [])
+    .option("-v, --verbose", "Show detailed request/response information")
+    .action(async (captureId, targetUrl, options) => {
+    const engine = getReplayEngine();
+    if (!captureId) {
+        const captures = engine.listCaptures(50);
+        if (captures.length === 0) {
+            console.log(chalk.yellow("\n📭 No captured webhooks found."));
+            console.log(chalk.gray("   Start capturing with: better-webhook capture\n"));
+            return;
+        }
+        const choices = captures.map((c) => {
+            const date = new Date(c.capture.timestamp).toLocaleString();
+            const provider = c.capture.provider ? `[${c.capture.provider}]` : "";
+            return {
+                title: `${c.capture.id.slice(0, 8)} ${provider} ${c.capture.method} ${c.capture.path}`,
+                description: date,
+                value: c.capture.id,
+            };
+        });
+        const response = await prompts({
+            type: "select",
+            name: "captureId",
+            message: "Select a capture to replay:",
+            choices,
+        });
+        if (!response.captureId) {
+            console.log(chalk.yellow("Cancelled"));
+            return;
+        }
+        captureId = response.captureId;
+    }
+    const captureFile = engine.getCapture(captureId);
+    if (!captureFile) {
+        console.log(chalk.red(`\n❌ Capture not found: ${captureId}\n`));
+        process.exitCode = 1;
+        return;
+    }
+    if (!targetUrl) {
+        const response = await prompts({
+            type: "text",
+            name: "url",
+            message: "Enter target URL:",
+            initial: `http://localhost:3000${captureFile.capture.path}`,
+            validate: (value) => {
+                try {
+                    new URL(value);
+                    return true;
+                }
+                catch {
+                    return "Please enter a valid URL";
+                }
+            },
+        });
+        if (!response.url) {
+            console.log(chalk.yellow("Cancelled"));
+            return;
+        }
+        targetUrl = response.url;
+    }
+    const { capture } = captureFile;
+    console.log(chalk.bold("\n🔄 Replaying Webhook\n"));
+    console.log(chalk.gray(`   Capture ID: ${capture.id.slice(0, 8)}`));
+    console.log(chalk.gray(`   Original: ${capture.method} ${capture.path}`));
+    if (capture.provider) {
+        console.log(chalk.gray(`   Provider: ${capture.provider}`));
+    }
+    console.log(chalk.gray(`   Target: ${targetUrl}`));
+    console.log();
+    const spinner = ora("Replaying webhook...").start();
+    try {
+        const result = await engine.replay(captureId, {
+            targetUrl: targetUrl,
+            method: options?.method,
+            headers: options?.header,
+        });
+        spinner.stop();
+        const statusColor = result.status >= 200 && result.status < 300
+            ? chalk.green
+            : result.status >= 400
+                ? chalk.red
+                : chalk.yellow;
+        console.log(chalk.bold("📥 Response\n"));
+        console.log(`   Status: ${statusColor(`${result.status} ${result.statusText}`)}`);
+        console.log(`   Duration: ${chalk.cyan(`${result.duration}ms`)}`);
+        if (options?.verbose) {
+            console.log(chalk.bold("\n   Headers:"));
+            for (const [key, value] of Object.entries(result.headers)) {
+                const headerValue = Array.isArray(value) ? value.join(", ") : value;
+                console.log(chalk.gray(`     ${key}: ${headerValue}`));
+            }
+        }
+        if (result.json !== undefined) {
+            console.log(chalk.bold("\n   Body:"));
+            console.log(chalk.gray(JSON.stringify(result.json, null, 2)
+                .split("\n")
+                .map((l) => `     ${l}`)
+                .join("\n")));
+        }
+        else if (result.bodyText) {
+            console.log(chalk.bold("\n   Body:"));
+            const preview = result.bodyText.length > 500
+                ? result.bodyText.slice(0, 500) + "..."
+                : result.bodyText;
+            console.log(chalk.gray(`     ${preview}`));
+        }
+        console.log();
+        if (result.status >= 200 && result.status < 300) {
+            console.log(chalk.green("✓ Replay completed successfully\n"));
+        }
+        else {
+            console.log(chalk.yellow(`⚠ Replay completed with status ${result.status}\n`));
+        }
+    }
+    catch (error) {
+        spinner.fail("Replay failed");
+        console.error(chalk.red(`\n❌ ${error.message}\n`));
+        process.exitCode = 1;
+    }
+});

package/dist/commands/run.d.ts

@@ -0,0 +1,2 @@
+import { Command } from "commander";
+export declare const run: Command;