@better-webhook/cli 0.2.0

package/LICENSE

@@ -0,0 +1,22 @@
+MIT License
+
+Copyright (c) 2025 Endalkachew Biruk
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.
+

package/README.md

@@ -0,0 +1,156 @@
+# Better Webhook CLI
+
+Simple CLI for listing, downloading, and executing predefined webhook JSON payloads stored in a local `.webhooks` directory.
+
+## Install (workspace)
+
+From repo root after cloning:
+
+```bash
+pnpm install
+pnpm --filter @better-webhook/cli build
+```
+
+Run via pnpm:
+
+```bash
+pnpm --filter @better-webhook/cli exec better-webhook list
+```
+
+Or in dev (watch) mode:
+
+```bash
+pnpm --filter @better-webhook/cli dev run sample
+```
+
+## Install (published)
+
+After publishing to npm you can use:
+
+```bash
+npx @better-webhook/cli list
+# or (after global install)
+pnpm add -g @better-webhook/cli
+better-webhook list
+```
+
+The binary name is `better-webhook`.
+
+## Publishing (maintainers)
+
+1. Update version (pnpm):
+   ```bash
+   pnpm --filter @better-webhook/cli version patch   # or minor / major
+   ```
+2. Build & publish (ensure you are logged in with `npm whoami`):
+   ```bash
+   pnpm --filter @better-webhook/cli run build
+   cd apps/webhook-cli
+   npm publish --access public
+   ```
+   (The `prepublishOnly` script also builds/validates automatically.)
+3. Test install:
+   ```bash
+   pnpm dlx @better-webhook/cli@latest --help
+   ```
+
+## Webhook File Schema
+
+Every webhook JSON file MUST conform to this schema (validated with `zod`):
+
+```jsonc
+{
+  "url": "https://example.com/endpoint", // required, valid URL
+  "method": "POST", // optional, defaults to POST (GET, POST, PUT, PATCH, DELETE, HEAD, OPTIONS)
+  "headers": [
+    // optional, defaults to []
+    { "key": "X-Custom", "value": "abc" },
+  ],
+  "body": {
+    // optional (omit for methods w/out body)
+    "event": "user.created",
+    "data": { "id": "123" },
+  },
+}
+```
+
+Validation errors list all failing fields with context.
+
+## Directory Structure
+
+```
+./.webhooks/
+  user_created.json
+  order_paid.json
+```
+
+## Commands
+
+### List
+
+```
+better-webhook list
+```
+
+Lists all JSON filenames (without extension) in `.webhooks`.
+
+### Download Templates
+
+```
+better-webhook download                # lists available templates
+better-webhook download stripe-invoice.payment_succeeded
+better-webhook download --all
+```
+
+### Run
+
+```
+better-webhook run user_created
+better-webhook run path/to/file.json
+```
+
+Overrides:
+
+```
+--url https://override.test/hook
+--method PUT
+```
+
+### Examples
+
+Minimal:
+
+```json
+{ "url": "https://example.com/hook" }
+```
+
+With headers + body:
+
+```json
+{
+  "url": "https://example.com/hook",
+  "method": "POST",
+  "headers": [
+    { "key": "X-Env", "value": "staging" },
+    { "key": "Authorization", "value": "Bearer TOKEN" }
+  ],
+  "body": { "event": "deploy", "status": "ok" }
+}
+```
+
+## Output
+
+- Prints status code
+- Prints response headers
+- Pretty-prints JSON response or raw body
+
+## Error Handling
+
+- Invalid JSON -> fails with parse message
+- Schema violations -> detailed list of issues
+- Network errors -> reported with non-zero exit code
+
+## Notes
+
+- Content-Type automatically set to `application/json` if body present and not already specified.
+- Headers defined later override earlier duplicates.

package/dist/index.cjs

@@ -0,0 +1,259 @@
+#!/usr/bin/env node
+"use strict";
+
+// src/index.ts
+var import_commander = require("commander");
+var import_fs2 = require("fs");
+var import_path = require("path");
+
+// src/loader.ts
+var import_fs = require("fs");
+
+// src/schema.ts
+var import_zod = require("zod");
+var httpMethodSchema = import_zod.z.enum([
+  "GET",
+  "POST",
+  "PUT",
+  "PATCH",
+  "DELETE",
+  "HEAD",
+  "OPTIONS"
+]);
+var headerEntrySchema = import_zod.z.object({
+  key: import_zod.z.string().min(1, "Header key cannot be empty").regex(/^[A-Za-z0-9-]+$/, {
+    message: "Header key must contain only alphanumerics and -"
+  }),
+  value: import_zod.z.string().min(1, "Header value cannot be empty")
+});
+var webhookSchema = import_zod.z.object({
+  url: import_zod.z.string().url("Invalid URL"),
+  method: httpMethodSchema.default("POST"),
+  headers: import_zod.z.array(headerEntrySchema).default([]),
+  body: import_zod.z.any().optional()
+  // could be anything JSON-serializable
+}).strict();
+function validateWebhookJSON(raw, source) {
+  const parsed = webhookSchema.safeParse(raw);
+  if (!parsed.success) {
+    const issues = parsed.error.issues.map((i) => `- ${i.path.join(".") || "(root)"}: ${i.message}`).join("\n");
+    throw new Error(`Invalid webhook definition in ${source}:
+${issues}`);
+  }
+  return parsed.data;
+}
+
+// src/loader.ts
+function loadWebhookFile(path) {
+  let rawContent;
+  try {
+    rawContent = (0, import_fs.readFileSync)(path, "utf8");
+  } catch (e) {
+    throw new Error(`Failed to read file ${path}: ${e.message}`);
+  }
+  let json;
+  try {
+    json = JSON.parse(rawContent);
+  } catch (e) {
+    throw new Error(`Invalid JSON in file ${path}: ${e.message}`);
+  }
+  return validateWebhookJSON(json, path);
+}
+
+// src/http.ts
+var import_undici = require("undici");
+async function executeWebhook(def) {
+  const headerMap = {};
+  for (const h of def.headers) {
+    headerMap[h.key] = h.value;
+  }
+  if (!headerMap["content-type"] && def.body !== void 0) {
+    headerMap["content-type"] = "application/json";
+  }
+  const bodyPayload = def.body !== void 0 ? JSON.stringify(def.body) : void 0;
+  const { statusCode, headers, body } = await (0, import_undici.request)(def.url, {
+    method: def.method,
+    headers: headerMap,
+    body: bodyPayload
+  });
+  const text = await body.text();
+  let parsed;
+  if (text) {
+    try {
+      parsed = JSON.parse(text);
+    } catch {
+    }
+  }
+  const resultHeaders = {};
+  for (const [k, v] of Object.entries(headers)) {
+    resultHeaders[k] = v;
+  }
+  return {
+    status: statusCode,
+    headers: resultHeaders,
+    bodyText: text,
+    json: parsed
+  };
+}
+
+// src/index.ts
+var import_undici2 = require("undici");
+var program = new import_commander.Command();
+program.name("better-webhook").description("CLI for listing, downloading and executing predefined webhooks").version("0.2.0");
+function findWebhooksDir(cwd) {
+  return (0, import_path.resolve)(cwd, ".webhooks");
+}
+function listWebhookFiles(dir) {
+  try {
+    const entries = (0, import_fs2.readdirSync)(dir);
+    return entries.filter(
+      (e) => (0, import_fs2.statSync)((0, import_path.join)(dir, e)).isFile() && (0, import_path.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(
+  "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) => {
+    if (name && opts.all) {
+      console.error("Specify either a template name or --all, not both.");
+      process.exitCode = 1;
+      return;
+    }
+    const cwd = process.cwd();
+    const dir = findWebhooksDir(cwd);
+    (0, import_fs2.mkdirSync)(dir, { recursive: true });
+    const toDownload = opts.all ? Object.keys(TEMPLATES) : name ? [name] : [];
+    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");
+      return;
+    }
+    for (const templateName of toDownload) {
+      const rel = TEMPLATES[templateName];
+      if (!rel) {
+        console.error(
+          `Unknown template '${templateName}'. Run without arguments to list available templates.`
+        );
+        continue;
+      }
+      const rawUrl = `${TEMPLATE_REPO_BASE}/${rel}`;
+      try {
+        const { statusCode, body } = await (0, import_undici2.request)(rawUrl);
+        if (statusCode !== 200) {
+          console.error(
+            `Failed to fetch ${templateName} (HTTP ${statusCode}) from ${rawUrl}`
+          );
+          continue;
+        }
+        const text = await body.text();
+        let json;
+        try {
+          json = JSON.parse(text);
+        } catch (e) {
+          console.error(
+            `Invalid JSON in remote template ${templateName}: ${e.message}`
+          );
+          continue;
+        }
+        try {
+          validateWebhookJSON(json, rawUrl);
+        } catch (e) {
+          console.error(`Template failed schema validation: ${e.message}`);
+          continue;
+        }
+        const fileName = (0, import_path.basename)(rel);
+        const destPath = (0, import_path.join)(dir, fileName);
+        if ((0, import_fs2.existsSync)(destPath) && !opts.force) {
+          console.log(
+            `Skipping existing file ${fileName} (use --force to overwrite)`
+          );
+          continue;
+        }
+        (0, import_fs2.writeFileSync)(destPath, JSON.stringify(json, null, 2));
+        console.log(`Downloaded ${templateName} -> .webhooks/${fileName}`);
+      } catch (e) {
+        console.error(`Error downloading ${templateName}: ${e.message}`);
+      }
+    }
+  }
+);
+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;
+  }
+  files.forEach((f) => console.log((0, import_path.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 = (0, import_path.join)(findWebhooksDir(cwd), nameOrPath);
+  } else {
+    const candidate = (0, import_path.join)(
+      findWebhooksDir(cwd),
+      nameOrPath + (nameOrPath.endsWith(".json") ? "" : ".json")
+    );
+    if (statExists(candidate)) {
+      filePath = candidate;
+    } else {
+      filePath = (0, import_path.resolve)(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;
+  }
+});
+function statExists(p) {
+  try {
+    (0, import_fs2.statSync)(p);
+    return true;
+  } catch {
+    return false;
+  }
+}
+program.parseAsync(process.argv);

package/dist/index.d.cts

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

package/dist/index.d.ts

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

package/dist/index.js

@@ -0,0 +1,264 @@
+#!/usr/bin/env node
+
+// src/index.ts
+import { Command } from "commander";
+import {
+  readdirSync,
+  statSync,
+  mkdirSync,
+  writeFileSync,
+  existsSync
+} from "fs";
+import { join, resolve, basename, extname } from "path";
+
+// src/loader.ts
+import { readFileSync } from "fs";
+
+// src/schema.ts
+import { z } from "zod";
+var httpMethodSchema = z.enum([
+  "GET",
+  "POST",
+  "PUT",
+  "PATCH",
+  "DELETE",
+  "HEAD",
+  "OPTIONS"
+]);
+var headerEntrySchema = z.object({
+  key: z.string().min(1, "Header key cannot be empty").regex(/^[A-Za-z0-9-]+$/, {
+    message: "Header key must contain only alphanumerics and -"
+  }),
+  value: z.string().min(1, "Header value cannot be empty")
+});
+var webhookSchema = z.object({
+  url: z.string().url("Invalid URL"),
+  method: httpMethodSchema.default("POST"),
+  headers: z.array(headerEntrySchema).default([]),
+  body: z.any().optional()
+  // could be anything JSON-serializable
+}).strict();
+function validateWebhookJSON(raw, source) {
+  const parsed = webhookSchema.safeParse(raw);
+  if (!parsed.success) {
+    const issues = parsed.error.issues.map((i) => `- ${i.path.join(".") || "(root)"}: ${i.message}`).join("\n");
+    throw new Error(`Invalid webhook definition in ${source}:
+${issues}`);
+  }
+  return parsed.data;
+}
+
+// src/loader.ts
+function loadWebhookFile(path) {
+  let rawContent;
+  try {
+    rawContent = readFileSync(path, "utf8");
+  } catch (e) {
+    throw new Error(`Failed to read file ${path}: ${e.message}`);
+  }
+  let json;
+  try {
+    json = JSON.parse(rawContent);
+  } catch (e) {
+    throw new Error(`Invalid JSON in file ${path}: ${e.message}`);
+  }
+  return validateWebhookJSON(json, path);
+}
+
+// src/http.ts
+import { request } from "undici";
+async function executeWebhook(def) {
+  const headerMap = {};
+  for (const h of def.headers) {
+    headerMap[h.key] = h.value;
+  }
+  if (!headerMap["content-type"] && def.body !== void 0) {
+    headerMap["content-type"] = "application/json";
+  }
+  const bodyPayload = def.body !== void 0 ? JSON.stringify(def.body) : void 0;
+  const { statusCode, headers, body } = await request(def.url, {
+    method: def.method,
+    headers: headerMap,
+    body: bodyPayload
+  });
+  const text = await body.text();
+  let parsed;
+  if (text) {
+    try {
+      parsed = JSON.parse(text);
+    } catch {
+    }
+  }
+  const resultHeaders = {};
+  for (const [k, v] of Object.entries(headers)) {
+    resultHeaders[k] = v;
+  }
+  return {
+    status: statusCode,
+    headers: resultHeaders,
+    bodyText: text,
+    json: parsed
+  };
+}
+
+// src/index.ts
+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(
+  "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) => {
+    if (name && opts.all) {
+      console.error("Specify either a template name or --all, not both.");
+      process.exitCode = 1;
+      return;
+    }
+    const cwd = process.cwd();
+    const dir = findWebhooksDir(cwd);
+    mkdirSync(dir, { recursive: true });
+    const toDownload = opts.all ? Object.keys(TEMPLATES) : name ? [name] : [];
+    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");
+      return;
+    }
+    for (const templateName of toDownload) {
+      const rel = TEMPLATES[templateName];
+      if (!rel) {
+        console.error(
+          `Unknown template '${templateName}'. Run without arguments to list available templates.`
+        );
+        continue;
+      }
+      const rawUrl = `${TEMPLATE_REPO_BASE}/${rel}`;
+      try {
+        const { statusCode, body } = await request2(rawUrl);
+        if (statusCode !== 200) {
+          console.error(
+            `Failed to fetch ${templateName} (HTTP ${statusCode}) from ${rawUrl}`
+          );
+          continue;
+        }
+        const text = await body.text();
+        let json;
+        try {
+          json = JSON.parse(text);
+        } catch (e) {
+          console.error(
+            `Invalid JSON in remote template ${templateName}: ${e.message}`
+          );
+          continue;
+        }
+        try {
+          validateWebhookJSON(json, rawUrl);
+        } catch (e) {
+          console.error(`Template failed schema validation: ${e.message}`);
+          continue;
+        }
+        const fileName = basename(rel);
+        const destPath = join(dir, fileName);
+        if (existsSync(destPath) && !opts.force) {
+          console.log(
+            `Skipping existing file ${fileName} (use --force to overwrite)`
+          );
+          continue;
+        }
+        writeFileSync(destPath, JSON.stringify(json, null, 2));
+        console.log(`Downloaded ${templateName} -> .webhooks/${fileName}`);
+      } catch (e) {
+        console.error(`Error downloading ${templateName}: ${e.message}`);
+      }
+    }
+  }
+);
+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;
+  }
+  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")
+    );
+    if (statExists(candidate)) {
+      filePath = candidate;
+    } else {
+      filePath = resolve(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;
+  }
+});
+function statExists(p) {
+  try {
+    statSync(p);
+    return true;
+  } catch {
+    return false;
+  }
+}
+program.parseAsync(process.argv);

package/package.json

@@ -0,0 +1,62 @@
+{
+  "name": "@better-webhook/cli",
+  "version": "0.2.0",
+  "description": "CLI for developing and replaying webhook payloads locally.",
+  "type": "module",
+  "bin": {
+    "better-webhook": "dist/index.js"
+  },
+  "main": "dist/index.cjs",
+  "module": "dist/index.js",
+  "types": "dist/index.d.ts",
+  "exports": {
+    ".": {
+      "import": "./dist/index.js",
+      "require": "./dist/index.cjs"
+    }
+  },
+  "files": [
+    "dist",
+    "README.md",
+    "LICENSE"
+  ],
+  "keywords": [
+    "webhook",
+    "cli",
+    "developer-tools",
+    "testing",
+    "http"
+  ],
+  "license": "MIT",
+  "author": "Endalk <endalk200>",
+  "repository": {
+    "type": "git",
+    "url": "git+https://github.com/endalk200/better-webhook.git"
+  },
+  "bugs": {
+    "url": "https://github.com/endalk200/better-webhook/issues"
+  },
+  "homepage": "https://github.com/endalk200/better-webhook#readme",
+  "publishConfig": {
+    "access": "public"
+  },
+  "engines": {
+    "node": ">=18"
+  },
+  "dependencies": {
+    "commander": "^14.0.1",
+    "undici": "^7.16.0",
+    "zod": "^4.1.8"
+  },
+  "devDependencies": {
+    "@types/node": "^24.3.1",
+    "tsup": "^8.5.0",
+    "tsx": "^4.19.2",
+    "typescript": "^5.6.3",
+    "@better-webhook/typescript-config": "0.0.0"
+  },
+  "scripts": {
+    "build": "tsup",
+    "dev": "tsup --watch"
+  }
+}