@better-webhook/cli 0.2.0 → 0.3.0

package/dist/index.js

@@ -1,15 +1,35 @@
 #!/usr/bin/env node
 
 // src/index.ts
+import { Command as Command4 } from "commander";
+
+// src/commands/webhooks.ts
 import { Command } from "commander";
-import {
-  readdirSync,
-  statSync,
-  mkdirSync,
-  writeFileSync,
-  existsSync
-} from "fs";
-import { join, resolve, basename, extname } from "path";
+import { join as join2, resolve as resolve2, basename } from "path";
+import { statSync as statSync2 } from "fs";
+
+// src/utils/index.ts
+import { readdirSync, statSync } from "fs";
+import { join, resolve, extname } from "path";
+function findWebhooksDir(cwd) {
+  return resolve(cwd, ".webhooks");
+}
+function listWebhookFiles(dir) {
+  return listJsonFiles(dir);
+}
+function findCapturesDir(cwd) {
+  return resolve(cwd, ".webhook-captures");
+}
+function listJsonFiles(dir) {
+  try {
+    const entries = readdirSync(dir);
+    return entries.filter(
+      (e) => statSync(join(dir, e)).isFile() && extname(e) === ".json"
+    );
+  } catch {
+    return [];
+  }
+}
 
 // src/loader.ts
 import { readFileSync } from "fs";
@@ -101,28 +121,85 @@ async function executeWebhook(def) {
   };
 }
 
-// src/index.ts
+// src/commands/webhooks.ts
+import { mkdirSync, writeFileSync, existsSync } from "fs";
 import { request as request2 } from "undici";
-var program = new Command();
-program.name("better-webhook").description("CLI for listing, downloading and executing predefined webhooks").version("0.2.0");
-function findWebhooksDir(cwd) {
-  return resolve(cwd, ".webhooks");
-}
-function listWebhookFiles(dir) {
-  try {
-    const entries = readdirSync(dir);
-    return entries.filter(
-      (e) => statSync(join(dir, e)).isFile() && extname(e) === ".json"
-    );
-  } catch {
-    return [];
-  }
-}
 var TEMPLATE_REPO_BASE = "https://raw.githubusercontent.com/endalk200/better-webhook/main";
 var TEMPLATES = {
   "stripe-invoice.payment_succeeded": "templates/stripe-invoice.payment_succeeded.json"
 };
-program.command("download [name]").description(
+function statExists(p) {
+  try {
+    statSync2(p);
+    return true;
+  } catch {
+    return false;
+  }
+}
+var listCommand = new Command().name("list").description("List available webhook JSON definitions in .webhooks directory").action(() => {
+  const cwd = process.cwd();
+  const dir = findWebhooksDir(cwd);
+  const files = listWebhookFiles(dir);
+  if (!files.length) {
+    console.log("No webhook definitions found in .webhooks");
+    return;
+  }
+  files.forEach((f) => console.log(basename(f, ".json")));
+});
+var runCommand = new Command().name("run").argument("<nameOrPath>", "Webhook name (in .webhooks) or path to JSON file").description(
+  "Run a webhook by name (in .webhooks) or by providing a path to a JSON file"
+).option("-u, --url <url>", "Override destination URL").option("-m, --method <method>", "Override HTTP method").action(async (nameOrPath, options) => {
+  const cwd = process.cwd();
+  let filePath;
+  if (nameOrPath.endsWith(".json") && !nameOrPath.includes("/") && !nameOrPath.startsWith(".")) {
+    filePath = join2(findWebhooksDir(cwd), nameOrPath);
+  } else {
+    const candidate = join2(
+      findWebhooksDir(cwd),
+      nameOrPath + (nameOrPath.endsWith(".json") ? "" : ".json")
+    );
+    if (statExists(candidate)) {
+      filePath = candidate;
+    } else {
+      filePath = resolve2(cwd, nameOrPath);
+    }
+  }
+  if (!statExists(filePath)) {
+    console.error(`Webhook file not found: ${filePath}`);
+    process.exitCode = 1;
+    return;
+  }
+  let def;
+  try {
+    def = loadWebhookFile(filePath);
+  } catch (err) {
+    console.error(err.message);
+    process.exitCode = 1;
+    return;
+  }
+  if (options.url) def = { ...def, url: options.url };
+  if (options.method)
+    def = { ...def, method: options.method.toUpperCase() };
+  try {
+    const result = await executeWebhook(def);
+    console.log("Status:", result.status);
+    console.log("Headers:");
+    for (const [k, v] of Object.entries(result.headers)) {
+      console.log(`  ${k}: ${Array.isArray(v) ? v.join(", ") : v}`);
+    }
+    if (result.json !== void 0) {
+      console.log("Response JSON:");
+      console.log(JSON.stringify(result.json, null, 2));
+    } else {
+      console.log("Response Body:");
+      console.log(result.bodyText);
+    }
+  } catch (err) {
+    console.error("Request failed:", err.message);
+    process.exitCode = 1;
+  }
+});
+var downloadCommand = new Command().name("download").argument("[name]", "Template name to download").description(
   "Download official webhook template(s) into the .webhooks directory. If no name is provided, prints available templates."
 ).option("-a, --all", "Download all available templates").option("-f, --force", "Overwrite existing files if they exist").action(
   async (name, opts) => {
@@ -138,7 +215,7 @@ program.command("download [name]").description(
     if (!toDownload.length) {
       console.log("Available templates:");
       for (const key of Object.keys(TEMPLATES)) console.log(` - ${key}`);
-      console.log("Use: better-webhook download <name> OR --all");
+      console.log("Use: better-webhook webhooks download <name> OR --all");
       return;
     }
     for (const templateName of toDownload) {
@@ -175,7 +252,7 @@ program.command("download [name]").description(
           continue;
         }
         const fileName = basename(rel);
-        const destPath = join(dir, fileName);
+        const destPath = join2(dir, fileName);
         if (existsSync(destPath) && !opts.force) {
           console.log(
             `Skipping existing file ${fileName} (use --force to overwrite)`
@@ -190,75 +267,449 @@ program.command("download [name]").description(
     }
   }
 );
-program.command("list").description("List available webhook JSON definitions in .webhooks directory").action(() => {
-  const cwd = process.cwd();
-  const dir = findWebhooksDir(cwd);
-  const files = listWebhookFiles(dir);
-  if (!files.length) {
-    console.log("No webhook definitions found in .webhooks");
-    return;
+var webhooks = new Command().name("webhooks").description("Manage and execute webhook definitions").addCommand(listCommand).addCommand(runCommand).addCommand(downloadCommand);
+
+// src/commands/capture.ts
+import { Command as Command2 } from "commander";
+import { mkdirSync as mkdirSync3, writeFileSync as writeFileSync3 } from "fs";
+import { join as join5, resolve as resolve3 } from "path";
+
+// src/capture.ts
+import { createServer } from "http";
+import { writeFileSync as writeFileSync2, mkdirSync as mkdirSync2, existsSync as existsSync2 } from "fs";
+import { join as join3 } from "path";
+import { randomUUID } from "crypto";
+var WebhookCaptureServer = class {
+  server = null;
+  capturesDir;
+  constructor(capturesDir) {
+    this.capturesDir = capturesDir;
+    if (!existsSync2(capturesDir)) {
+      mkdirSync2(capturesDir, { recursive: true });
+    }
   }
-  files.forEach((f) => console.log(basename(f, ".json")));
-});
-program.command("run <nameOrPath>").description(
-  "Run a webhook by name (in .webhooks) or by providing a path to a JSON file"
-).option("-u, --url <url>", "Override destination URL").option("-m, --method <method>", "Override HTTP method").action(async (nameOrPath, options) => {
-  const cwd = process.cwd();
-  let filePath;
-  if (nameOrPath.endsWith(".json") && !nameOrPath.includes("/") && !nameOrPath.startsWith(".")) {
-    filePath = join(findWebhooksDir(cwd), nameOrPath);
-  } else {
-    const candidate = join(
-      findWebhooksDir(cwd),
-      nameOrPath + (nameOrPath.endsWith(".json") ? "" : ".json")
+  start(startPort = 3001, maxAttempts = 20) {
+    return new Promise((resolve4, reject) => {
+      if (!Number.isInteger(startPort) || startPort < 0 || startPort > 65535) {
+        startPort = 3001;
+      }
+      let attempt = 0;
+      const tryListen = (portToTry) => {
+        this.server = createServer(
+          async (req, res) => {
+            try {
+              await this.handleRequest(req, res);
+            } catch (error) {
+              console.error("Error handling request:", error);
+              res.statusCode = 500;
+              res.end("Internal Server Error");
+            }
+          }
+        );
+        const onError = (err) => {
+          this.server?.off("error", onError);
+          this.server?.off("listening", onListening);
+          if (err && err.code === "EADDRINUSE") {
+            attempt += 1;
+            if (startPort === 0) {
+              reject(new Error("Failed to bind to an ephemeral port."));
+              return;
+            }
+            if (attempt >= maxAttempts) {
+              reject(
+                new Error(
+                  `All ${maxAttempts} port attempts starting at ${startPort} are in use.`
+                )
+              );
+              return;
+            }
+            const nextPort = startPort + attempt;
+            tryListen(nextPort);
+          } else {
+            reject(err);
+          }
+        };
+        const onListening = () => {
+          this.server?.off("error", onError);
+          this.server?.off("listening", onListening);
+          const address = this.server?.address();
+          const actualPort = address?.port ?? portToTry;
+          console.log(
+            `\u{1F3A3} Webhook capture server running on http://localhost:${actualPort}`
+          );
+          console.log(
+            `\u{1F4C1} Captured webhooks will be saved to: ${this.capturesDir}`
+          );
+          console.log(
+            "\u{1F4A1} Send webhooks to any path on this server to capture them"
+          );
+          console.log("\u23F9\uFE0F  Press Ctrl+C to stop the server");
+          resolve4(actualPort);
+        };
+        this.server.on("error", onError);
+        this.server.on("listening", onListening);
+        this.server.listen(portToTry);
+      };
+      tryListen(startPort === 0 ? 0 : startPort);
+    });
+  }
+  stop() {
+    return new Promise((resolve4) => {
+      if (this.server) {
+        this.server.close(() => {
+          console.log("\u{1F4F4} Webhook capture server stopped");
+          resolve4();
+        });
+      } else {
+        resolve4();
+      }
+    });
+  }
+  async handleRequest(req, res) {
+    const timestamp = (/* @__PURE__ */ new Date()).toISOString();
+    const id = this.generateId();
+    const url = req.url || "/";
+    const urlParts = new URL(url, `http://${req.headers.host || "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 = [];
+    req.on("data", (chunk) => chunks.push(chunk));
+    await new Promise((resolve4) => {
+      req.on("end", () => resolve4());
+    });
+    const rawBody = Buffer.concat(chunks).toString("utf8");
+    let parsedBody;
+    try {
+      parsedBody = rawBody ? JSON.parse(rawBody) : null;
+    } catch {
+      parsedBody = rawBody || null;
+    }
+    const captured = {
+      id,
+      timestamp,
+      method: req.method || "GET",
+      url: urlParts.pathname,
+      headers: req.headers,
+      body: parsedBody,
+      rawBody,
+      query
+    };
+    const filename = `${timestamp.replace(/[:.]/g, "-")}_${id}.json`;
+    const filepath = join3(this.capturesDir, filename);
+    try {
+      writeFileSync2(filepath, JSON.stringify(captured, null, 2));
+      console.log(
+        `\u{1F4E6} Captured ${req.method} ${urlParts.pathname} -> ${filename}`
+      );
+    } catch (error) {
+      console.error(`\u274C Failed to save capture: ${error}`);
+    }
+    res.statusCode = 200;
+    res.setHeader("Content-Type", "application/json");
+    res.end(
+      JSON.stringify(
+        {
+          message: "Webhook captured successfully",
+          id,
+          timestamp,
+          file: filename
+        },
+        null,
+        2
+      )
     );
-    if (statExists(candidate)) {
-      filePath = candidate;
+  }
+  generateId() {
+    try {
+      return randomUUID();
+    } catch {
+      return `${Date.now().toString(36)}-${Math.random().toString(36).slice(2, 10)}`;
+    }
+  }
+};
+
+// src/replay.ts
+import { readFileSync as readFileSync2 } from "fs";
+import { join as join4 } from "path";
+var WebhookReplayer = class {
+  constructor(capturesDir) {
+    this.capturesDir = capturesDir;
+  }
+  /**
+   * List all captured webhooks
+   */
+  listCaptured() {
+    try {
+      const files = listJsonFiles(this.capturesDir).sort().reverse();
+      return files.map((file) => ({
+        file,
+        capture: this.loadCapture(join4(this.capturesDir, file))
+      }));
+    } catch {
+      return [];
+    }
+  }
+  /**
+   * Load a specific captured webhook by filename or ID
+   */
+  loadCapture(filePathOrId) {
+    let filepath;
+    if (filePathOrId.includes("/") || filePathOrId.endsWith(".json")) {
+      filepath = filePathOrId;
     } else {
-      filePath = resolve(cwd, nameOrPath);
+      const files = listJsonFiles(this.capturesDir).filter(
+        (f) => f.includes(filePathOrId)
+      );
+      if (files.length === 0) {
+        throw new Error(`No capture found with ID: ${filePathOrId}`);
+      }
+      if (files.length > 1) {
+        throw new Error(
+          `Multiple captures found with ID ${filePathOrId}: ${files.join(", ")}`
+        );
+      }
+      filepath = join4(this.capturesDir, files[0] ?? "");
+    }
+    try {
+      const content = readFileSync2(filepath, "utf8");
+      return JSON.parse(content);
+    } catch (error) {
+      throw new Error(
+        `Failed to load capture from ${filepath}: ${error.message}`
+      );
     }
   }
-  if (!statExists(filePath)) {
-    console.error(`Webhook file not found: ${filePath}`);
+  /**
+   * Replay a captured webhook to a target URL
+   */
+  async replay(captureId, targetUrl, options = {}) {
+    const capture2 = this.loadCapture(captureId);
+    const webhookDef = {
+      url: options.url || targetUrl,
+      method: options.method || capture2.method,
+      headers: options.headers || this.convertHeaders(capture2.headers),
+      body: capture2.body
+    };
+    console.log(`\u{1F504} Replaying webhook ${capture2.id} (${capture2.timestamp})`);
+    console.log(`   Method: ${webhookDef.method}`);
+    console.log(`   URL: ${webhookDef.url}`);
+    console.log(`   Original: ${capture2.method} ${capture2.url}`);
+    try {
+      const result = await executeWebhook(webhookDef);
+      return result;
+    } catch (error) {
+      throw new Error(`Replay failed: ${error.message}`);
+    }
+  }
+  /**
+   * Convert captured webhook to template format
+   */
+  captureToTemplate(captureId, templateUrl) {
+    const capture2 = this.loadCapture(captureId);
+    return {
+      url: templateUrl || "http://localhost:3000/webhook",
+      method: capture2.method,
+      headers: this.convertHeaders(capture2.headers),
+      body: capture2.body
+    };
+  }
+  /**
+   * Convert captured headers to template format
+   */
+  convertHeaders(headers) {
+    const result = [];
+    for (const [key, value] of Object.entries(headers)) {
+      const skipHeaders = [
+        "host",
+        "content-length",
+        "connection",
+        "accept-encoding",
+        "user-agent",
+        "x-forwarded-for",
+        "x-forwarded-proto"
+      ];
+      if (skipHeaders.includes(key.toLowerCase())) {
+        continue;
+      }
+      if (Array.isArray(value)) {
+        if (value.length === 1) {
+          result.push({ key, value: value[0] ?? "" });
+        } else {
+          result.push({ key, value: value.join(", ") });
+        }
+      } else {
+        result.push({ key, value });
+      }
+    }
+    return result;
+  }
+  /**
+   * Get summary information about a capture
+   */
+  getCaptureSummary(captureId) {
+    const capture2 = this.loadCapture(captureId);
+    const date = new Date(capture2.timestamp);
+    const bodySize = capture2.rawBody ? capture2.rawBody.length : 0;
+    const headerCount = Object.keys(capture2.headers).length;
+    return [
+      `ID: ${capture2.id}`,
+      `Date: ${date.toLocaleString()}`,
+      `Method: ${capture2.method}`,
+      `Path: ${capture2.url}`,
+      `Headers: ${headerCount}`,
+      `Body Size: ${bodySize} bytes`,
+      `Query Params: ${Object.keys(capture2.query).length}`
+    ].join("\n");
+  }
+};
+
+// src/commands/capture.ts
+var listCommand2 = new Command2().name("list").description("List captured webhook requests").option("-l, --limit <limit>", "Maximum number of captures to show", "10").action((options) => {
+  const cwd = process.cwd();
+  const capturesDir = findCapturesDir(cwd);
+  const replayer = new WebhookReplayer(capturesDir);
+  const captures = replayer.listCaptured();
+  const limit = parseInt(options.limit, 10);
+  if (Number.isNaN(limit) || limit <= 0) {
+    console.error("Invalid --limit: must be a positive integer.");
     process.exitCode = 1;
     return;
   }
-  let def;
+  if (captures.length === 0) {
+    console.log("No webhook captures found.");
+    console.log(`Run 'better-webhook capture' to start capturing webhooks.`);
+    return;
+  }
+  console.log(
+    `\u{1F4CB} Found ${captures.length} captured webhooks (showing ${Math.min(limit, captures.length)}):
+`
+  );
+  captures.slice(0, limit).forEach(({ file, capture: capture2 }) => {
+    const date = new Date(capture2.timestamp).toLocaleString();
+    const bodySize = capture2.rawBody ? capture2.rawBody.length : 0;
+    console.log(`\u{1F194} ${capture2.id} | \u{1F4C5} ${date}`);
+    console.log(`   ${capture2.method} ${capture2.url} | ${bodySize} bytes`);
+    console.log(`   \u{1F4C4} ${file}
+`);
+  });
+  if (captures.length > limit) {
+    console.log(
+      `... and ${captures.length - limit} more. Use --limit to show more.`
+    );
+  }
+});
+var templateCommand = new Command2().name("template").argument("<captureId>", "ID of the captured webhook to create template from").argument("[templateName]", "Name for the generated template").description("Generate a webhook template from a captured request").option(
+  "-u, --url <url>",
+  "Template URL (default: http://localhost:3000/webhook)"
+).option("-o, --output-dir <dir>", "Output directory (default: .webhooks)").action(
+  async (captureId, templateName, options) => {
+    const cwd = process.cwd();
+    const capturesDir = findCapturesDir(cwd);
+    const replayer = new WebhookReplayer(capturesDir);
+    try {
+      const template = replayer.captureToTemplate(captureId, options?.url);
+      if (!templateName) {
+        const capture2 = replayer.loadCapture(captureId);
+        const date = new Date(capture2.timestamp).toISOString().split("T")[0];
+        const pathPart = capture2.url.replace(/[^a-zA-Z0-9]/g, "_").substring(1) || "webhook";
+        templateName = `captured_${date}_${pathPart}_${capture2.id}`;
+      }
+      const outputDir = options?.outputDir ? resolve3(cwd, options.outputDir) : findWebhooksDir(cwd);
+      mkdirSync3(outputDir, { recursive: true });
+      const templatePath = join5(outputDir, `${templateName}.json`);
+      writeFileSync3(templatePath, JSON.stringify(template, null, 2));
+      console.log(`\u2705 Template created: ${templatePath}`);
+      console.log(
+        `\u{1F504} Run it with: better-webhook webhooks run ${templateName}`
+      );
+      console.log("\n\u{1F4CA} Template Summary:");
+      console.log(replayer.getCaptureSummary(captureId));
+    } catch (error) {
+      console.error("\u274C Template generation failed:", error.message);
+      process.exitCode = 1;
+    }
+  }
+);
+var capture = new Command2().name("capture").description(
+  "Start a server to capture incoming webhook requests, or list captured webhooks"
+).option("-p, --port <port>", "Port to listen on", "3001").action(async (options) => {
+  const cwd = process.cwd();
+  const capturesDir = findCapturesDir(cwd);
+  const server = new WebhookCaptureServer(capturesDir);
+  let actualPort;
   try {
-    def = loadWebhookFile(filePath);
-  } catch (err) {
-    console.error(err.message);
+    actualPort = await server.start(parseInt(options.port));
+  } catch (error) {
+    console.error("Failed to start capture server:", error.message);
     process.exitCode = 1;
     return;
   }
-  if (options.url) def = { ...def, url: options.url };
-  if (options.method)
-    def = { ...def, method: options.method.toUpperCase() };
-  try {
-    const result = await executeWebhook(def);
-    console.log("Status:", result.status);
-    console.log("Headers:");
-    for (const [k, v] of Object.entries(result.headers)) {
-      console.log(`  ${k}: ${Array.isArray(v) ? v.join(", ") : v}`);
+  const shutdown = async () => {
+    console.log("\n\u{1F6D1} Shutting down server...");
+    await server.stop();
+    process.exit(0);
+  };
+  process.on("SIGINT", shutdown);
+  process.on("SIGTERM", shutdown);
+}).addCommand(listCommand2).addCommand(templateCommand);
+
+// src/commands/replay.ts
+import { Command as Command3 } from "commander";
+var replay = new Command3().name("replay").argument("<captureId>", "ID of the captured webhook to replay").argument("<targetUrl>", "Target URL to replay the webhook to").description("Replay a captured webhook to a target URL").option("-m, --method <method>", "Override HTTP method").option(
+  "-H, --header <header>",
+  "Add custom 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");
     }
-    if (result.json !== void 0) {
-      console.log("Response JSON:");
-      console.log(JSON.stringify(result.json, null, 2));
-    } else {
-      console.log("Response Body:");
-      console.log(result.bodyText);
+    return (previous || []).concat([
+      { key: key.trim(), value: headerValue.trim() }
+    ]);
+  },
+  []
+).action(
+  async (captureId, targetUrl, options) => {
+    const cwd = process.cwd();
+    const capturesDir = findCapturesDir(cwd);
+    const replayer = new WebhookReplayer(capturesDir);
+    try {
+      const result = await replayer.replay(captureId, targetUrl, {
+        method: options.method,
+        headers: options.header
+      });
+      console.log("\u2705 Replay completed successfully!");
+      console.log("Status:", result.status);
+      console.log("Headers:");
+      for (const [k, v] of Object.entries(result.headers)) {
+        console.log(`  ${k}: ${Array.isArray(v) ? v.join(", ") : v}`);
+      }
+      if (result.json !== void 0) {
+        console.log("Response JSON:");
+        console.log(JSON.stringify(result.json, null, 2));
+      } else {
+        console.log("Response Body:");
+        console.log(result.bodyText);
+      }
+    } catch (error) {
+      console.error("\u274C Replay failed:", error.message);
+      process.exitCode = 1;
     }
-  } catch (err) {
-    console.error("Request failed:", err.message);
-    process.exitCode = 1;
   }
-});
-function statExists(p) {
-  try {
-    statSync(p);
-    return true;
-  } catch {
-    return false;
-  }
-}
+);
+
+// src/index.ts
+var program = new Command4().name("better-webhook").description("CLI for listing, downloading and executing predefined webhooks").version("0.2.0");
+program.addCommand(webhooks).addCommand(capture).addCommand(replay);
 program.parseAsync(process.argv);

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@better-webhook/cli",
-  "version": "0.2.0",
+  "version": "0.3.0",
   "description": "CLI for developing and replaying webhook payloads locally.",
   "type": "module",
   "bin": {