@hogsend/cli 0.7.0 → 0.9.0

package/dist/bin.js

@@ -85,6 +85,10 @@ function createAdminClient(cfg) {
     post: (path, body) => request(cfg.baseUrl, cfg.adminKey, missing, "POST", path, {
       body,
       auth: true
+    }),
+    del: (path, body) => request(cfg.baseUrl, cfg.adminKey, missing, "DELETE", path, {
+      body,
+      auth: true
     })
   };
 }
@@ -1057,8 +1061,8 @@ async function run3(ctx) {
     if (!ok) process.exit(1);
     return;
   }
-  const badge5 = `${color.bgMagenta(color.black(" hogsend "))} doctor`;
-  ctx.out.intro(badge5);
+  const badge6 = `${color.bgMagenta(color.black(" hogsend "))} doctor`;
+  ctx.out.intro(badge6);
   const verdictColor = verdict === "ok" ? color.green : verdict === "degraded" ? color.red : color.yellow;
   const lines = [
     `${verdictColor("\u25CF")} ${color.bold(verdict)}`,
@@ -2944,6 +2948,438 @@ var upgradeCommand = {
   run: run13
 };
 
+// src/commands/webhooks.ts
+import { parseArgs as parseArgs14 } from "util";
+var WEBHOOK_EVENT_TYPES = [
+  "contact.created",
+  "contact.updated",
+  "contact.deleted",
+  "contact.unsubscribed",
+  "email.sent",
+  "email.delivered",
+  "email.opened",
+  "email.clicked",
+  "email.bounced",
+  "email.complained",
+  "journey.completed",
+  "bucket.entered",
+  "bucket.left"
+];
+var usage14 = `hogsend webhooks <subcommand> [options]
+
+Manage outbound webhook endpoints \u2014 the Svix-style signed event stream Hogsend
+emits to your URLs. Wraps the admin routes (/v1/admin/webhooks), so this command
+REQUIRES an admin key (--admin-key / HOGSEND_ADMIN_KEY), not the data key.
+
+Subcommands:
+  list                       List endpoints.
+  get <id>                   Show one endpoint.
+  create                     Register an endpoint (prints the secret ONCE).
+  update <id>                Patch an endpoint.
+  delete <id>                Hard-delete an endpoint (drops its deliveries).
+  rotate-secret <id>         Issue a new signing secret (prints it ONCE).
+  test <id>                  Enqueue an out-of-band webhook.test delivery.
+
+list options:
+  --include-disabled         Include disabled endpoints.
+  --limit <n>                Page size.
+  --offset <n>               Page offset.
+
+create options (--url required, plus at least one event):
+  --url <url>                Destination URL (required).
+  --event <type>             Subscribe to an event; repeatable.
+  --all-events               Subscribe to all 13 event types.
+  --description <text>       Human label.
+  --disabled                 Create the endpoint disabled.
+
+update options (only the provided fields change):
+  --url <url>                New destination URL.
+  --event <type>             Replace the subscribed events (repeatable).
+  --all-events               Subscribe to all 13 event types.
+  --description <text>       New description.
+  --disabled / --enabled     Disable or enable the endpoint.
+
+Event types:
+  ${WEBHOOK_EVENT_TYPES.join(", ")}
+
+Global options (handled by the router): --url, --admin-key, --data-key, --json,
+-h/--help.
+
+Examples:
+  hogsend webhooks create --url https://x.com/hook --event contact.created --event email.sent
+  hogsend webhooks create --url https://x.com/hook --all-events --json
+  hogsend webhooks list --include-disabled
+  hogsend webhooks rotate-secret we_123
+  hogsend webhooks test we_123`;
+var badge5 = `${color.bgMagenta(color.black(" hogsend "))} webhooks`;
+async function fetchOrFail2(ctx, label, fn) {
+  try {
+    return await ctx.out.step(label, fn);
+  } catch (err) {
+    if (isHttpError(err)) {
+      if (err.status === 404) {
+        ctx.out.fail(err.message || "webhook endpoint not found");
+      }
+      ctx.out.fail(err.message);
+    }
+    throw err;
+  }
+}
+function resolveEvents(ctx, allEvents, events) {
+  if (allEvents) {
+    return [...WEBHOOK_EVENT_TYPES];
+  }
+  if (!events || events.length === 0) {
+    return void 0;
+  }
+  const valid = new Set(WEBHOOK_EVENT_TYPES);
+  const out = [];
+  for (const ev of events) {
+    if (!valid.has(ev)) {
+      ctx.out.fail(
+        `unknown event type "${ev}" \u2014 expected one of: ${WEBHOOK_EVENT_TYPES.join(", ")}`
+      );
+    }
+    if (!out.includes(ev)) {
+      out.push(ev);
+    }
+  }
+  return out;
+}
+function printSecretOnce(ctx, secret) {
+  ctx.out.note(
+    `${color.yellow("Store this signing secret now \u2014 it is shown only once and cannot be recovered.")}
+
+${color.bold(secret)}`,
+    color.yellow("Signing secret")
+  );
+}
+async function runList4(ctx, argv) {
+  const { values } = parseArgs14({
+    args: argv,
+    allowPositionals: true,
+    options: {
+      "include-disabled": { type: "boolean", default: false },
+      limit: { type: "string" },
+      offset: { type: "string" },
+      help: { type: "boolean", short: "h", default: false }
+    }
+  });
+  if (values.help) {
+    ctx.out.log(usage14);
+    return;
+  }
+  const query = {
+    includeDisabled: values["include-disabled"] ? "true" : void 0,
+    limit: values.limit,
+    offset: values.offset
+  };
+  if (!ctx.json) ctx.out.intro(`${badge5} list`);
+  const res = await fetchOrFail2(
+    ctx,
+    "Fetching webhooks",
+    () => ctx.http.get("/v1/admin/webhooks", query)
+  );
+  if (ctx.json) {
+    ctx.out.json(res);
+    return;
+  }
+  ctx.out.table(
+    res.endpoints.map((ep) => ({
+      id: ep.id,
+      url: ep.url,
+      status: ep.status === "enabled" ? color.green(ep.status) : color.yellow(ep.status),
+      events: ep.eventTypes.length,
+      lastDeliveryAt: ep.lastDeliveryAt ?? color.dim("(never)")
+    })),
+    ["id", "url", "status", "events", "lastDeliveryAt"]
+  );
+  ctx.out.outro(
+    `${res.endpoints.length} of ${res.total} endpoint(s) \u2014 offset ${res.offset}, limit ${res.limit}`
+  );
+}
+function renderEndpoint(ctx, ep, title) {
+  ctx.out.kv(
+    {
+      id: ep.id,
+      url: ep.url,
+      description: ep.description ?? color.dim("(none)"),
+      status: ep.status === "enabled" ? color.green(ep.status) : color.yellow(ep.status),
+      eventTypes: ep.eventTypes,
+      secretPrefix: ep.secretPrefix ?? color.dim("(none \u2014 keyed destination)"),
+      lastDeliveryAt: ep.lastDeliveryAt ?? color.dim("(never)"),
+      createdAt: ep.createdAt,
+      updatedAt: ep.updatedAt
+    },
+    title
+  );
+}
+async function runGet3(ctx, argv) {
+  const { values, positionals } = parseArgs14({
+    args: argv,
+    allowPositionals: true,
+    options: { help: { type: "boolean", short: "h", default: false } }
+  });
+  if (values.help) {
+    ctx.out.log(usage14);
+    return;
+  }
+  const id = positionals[0];
+  if (!id) {
+    ctx.out.fail(
+      "webhooks get requires an endpoint id, e.g. hogsend webhooks get we_123"
+    );
+  }
+  if (!ctx.json) ctx.out.intro(`${badge5} get`);
+  const res = await fetchOrFail2(
+    ctx,
+    "Fetching webhook",
+    () => ctx.http.get(
+      `/v1/admin/webhooks/${encodeURIComponent(id)}`
+    )
+  );
+  if (ctx.json) {
+    ctx.out.json(res);
+    return;
+  }
+  renderEndpoint(ctx, res, "Endpoint");
+  ctx.out.outro(`${res.url} \u2192 ${res.status}`);
+}
+async function runCreate(ctx, argv) {
+  const { values } = parseArgs14({
+    args: argv,
+    allowPositionals: true,
+    options: {
+      url: { type: "string" },
+      event: { type: "string", multiple: true },
+      "all-events": { type: "boolean", default: false },
+      description: { type: "string" },
+      disabled: { type: "boolean", default: false },
+      help: { type: "boolean", short: "h", default: false }
+    }
+  });
+  if (values.help) {
+    ctx.out.log(usage14);
+    return;
+  }
+  const url = values.url;
+  if (!url) {
+    ctx.out.fail(
+      "webhooks create requires --url, e.g. hogsend webhooks create --url https://x.com/hook --all-events"
+    );
+  }
+  const eventTypes = resolveEvents(ctx, values["all-events"], values.event);
+  if (!eventTypes || eventTypes.length === 0) {
+    ctx.out.fail(
+      "webhooks create requires at least one --event <type> (or --all-events)"
+    );
+  }
+  const body = { url, eventTypes };
+  if (values.description !== void 0) body.description = values.description;
+  if (values.disabled) body.disabled = true;
+  if (!ctx.json) ctx.out.intro(`${badge5} create`);
+  const res = await fetchOrFail2(
+    ctx,
+    "Creating webhook",
+    () => ctx.http.post("/v1/admin/webhooks", body)
+  );
+  if (ctx.json) {
+    ctx.out.json(res);
+    return;
+  }
+  const { secret, ...endpoint } = res;
+  renderEndpoint(ctx, endpoint, "Endpoint created");
+  printSecretOnce(ctx, secret);
+  ctx.out.outro(`${color.green("Created")} ${res.id} \u2192 ${res.url}`);
+}
+async function runUpdate(ctx, argv) {
+  const { values, positionals } = parseArgs14({
+    args: argv,
+    allowPositionals: true,
+    options: {
+      url: { type: "string" },
+      event: { type: "string", multiple: true },
+      "all-events": { type: "boolean", default: false },
+      description: { type: "string" },
+      disabled: { type: "boolean", default: false },
+      enabled: { type: "boolean", default: false },
+      help: { type: "boolean", short: "h", default: false }
+    }
+  });
+  if (values.help) {
+    ctx.out.log(usage14);
+    return;
+  }
+  const id = positionals[0];
+  if (!id) {
+    ctx.out.fail(
+      "webhooks update requires an endpoint id, e.g. hogsend webhooks update we_123 --enabled"
+    );
+  }
+  if (values.disabled && values.enabled) {
+    ctx.out.fail("webhooks update: pass at most one of --disabled / --enabled");
+  }
+  const eventTypes = resolveEvents(ctx, values["all-events"], values.event);
+  const body = {};
+  if (values.url !== void 0) body.url = values.url;
+  if (eventTypes !== void 0) body.eventTypes = eventTypes;
+  if (values.description !== void 0) body.description = values.description;
+  if (values.disabled) body.disabled = true;
+  if (values.enabled) body.disabled = false;
+  if (Object.keys(body).length === 0) {
+    ctx.out.fail(
+      "webhooks update: nothing to change \u2014 pass --url / --event / --description / --disabled / --enabled"
+    );
+  }
+  if (!ctx.json) ctx.out.intro(`${badge5} update`);
+  const res = await fetchOrFail2(
+    ctx,
+    "Updating webhook",
+    () => ctx.http.patch(
+      `/v1/admin/webhooks/${encodeURIComponent(id)}`,
+      body
+    )
+  );
+  if (ctx.json) {
+    ctx.out.json(res);
+    return;
+  }
+  renderEndpoint(ctx, res, "Endpoint updated");
+  ctx.out.outro(`${color.green("Updated")} ${res.id} \u2192 ${res.status}`);
+}
+async function runDelete(ctx, argv) {
+  const { values, positionals } = parseArgs14({
+    args: argv,
+    allowPositionals: true,
+    options: { help: { type: "boolean", short: "h", default: false } }
+  });
+  if (values.help) {
+    ctx.out.log(usage14);
+    return;
+  }
+  const id = positionals[0];
+  if (!id) {
+    ctx.out.fail(
+      "webhooks delete requires an endpoint id, e.g. hogsend webhooks delete we_123"
+    );
+  }
+  if (!ctx.json) ctx.out.intro(`${badge5} delete`);
+  const res = await fetchOrFail2(
+    ctx,
+    "Deleting webhook",
+    () => ctx.http.del(
+      `/v1/admin/webhooks/${encodeURIComponent(id)}`
+    )
+  );
+  if (ctx.json) {
+    ctx.out.json(res);
+    return;
+  }
+  ctx.out.outro(`${color.green("Deleted")} ${id}`);
+}
+async function runRotate(ctx, argv) {
+  const { values, positionals } = parseArgs14({
+    args: argv,
+    allowPositionals: true,
+    options: { help: { type: "boolean", short: "h", default: false } }
+  });
+  if (values.help) {
+    ctx.out.log(usage14);
+    return;
+  }
+  const id = positionals[0];
+  if (!id) {
+    ctx.out.fail(
+      "webhooks rotate-secret requires an endpoint id, e.g. hogsend webhooks rotate-secret we_123"
+    );
+  }
+  if (!ctx.json) ctx.out.intro(`${badge5} rotate-secret`);
+  const res = await fetchOrFail2(
+    ctx,
+    "Rotating signing secret",
+    () => ctx.http.post(
+      `/v1/admin/webhooks/${encodeURIComponent(id)}/rotate-secret`,
+      {}
+    )
+  );
+  if (ctx.json) {
+    ctx.out.json(res);
+    return;
+  }
+  ctx.out.kv({ id: res.id, secretPrefix: res.secretPrefix }, "Secret rotated");
+  printSecretOnce(ctx, res.secret);
+  ctx.out.outro(
+    `${color.green("Rotated")} \u2014 the old secret is now invalid. Update every subscriber.`
+  );
+}
+async function runTest(ctx, argv) {
+  const { values, positionals } = parseArgs14({
+    args: argv,
+    allowPositionals: true,
+    options: { help: { type: "boolean", short: "h", default: false } }
+  });
+  if (values.help) {
+    ctx.out.log(usage14);
+    return;
+  }
+  const id = positionals[0];
+  if (!id) {
+    ctx.out.fail(
+      "webhooks test requires an endpoint id, e.g. hogsend webhooks test we_123"
+    );
+  }
+  if (!ctx.json) ctx.out.intro(`${badge5} test`);
+  const res = await fetchOrFail2(
+    ctx,
+    "Enqueuing test delivery",
+    () => ctx.http.post(
+      `/v1/admin/webhooks/${encodeURIComponent(id)}/test`,
+      {}
+    )
+  );
+  if (ctx.json) {
+    ctx.out.json(res);
+    return;
+  }
+  ctx.out.outro(
+    `${color.green("Enqueued")} a ${color.cyan(res.eventType)} delivery to ${id}.`
+  );
+}
+async function run14(ctx) {
+  const sub = ctx.argv[0];
+  switch (sub) {
+    case "list":
+      return runList4(ctx, ctx.argv.slice(1));
+    case "get":
+      return runGet3(ctx, ctx.argv.slice(1));
+    case "create":
+      return runCreate(ctx, ctx.argv.slice(1));
+    case "update":
+      return runUpdate(ctx, ctx.argv.slice(1));
+    case "delete":
+      return runDelete(ctx, ctx.argv.slice(1));
+    case "rotate-secret":
+      return runRotate(ctx, ctx.argv.slice(1));
+    case "test":
+      return runTest(ctx, ctx.argv.slice(1));
+    case void 0:
+      ctx.out.fail(
+        "webhooks requires a subcommand: list | get | create | update | delete | rotate-secret | test (see hogsend webhooks --help)"
+      );
+      break;
+    default:
+      ctx.out.fail(
+        `unknown webhooks subcommand "${sub}" \u2014 expected one of list | get | create | update | delete | rotate-secret | test`
+      );
+  }
+}
+var webhooksCommand = {
+  name: "webhooks",
+  summary: "Manage outbound webhook endpoints (create, rotate, test)",
+  usage: usage14,
+  run: run14
+};
+
 // src/commands/index.ts
 var commands = [
   doctorCommand,
@@ -2953,6 +3389,7 @@ var commands = [
   eventsCommand,
   emailsCommand,
   campaignsCommand,
+  webhooksCommand,
   studioCommand,
   setupCommand,
   skillsCommand,
@@ -2964,10 +3401,10 @@ var commands = [
 // src/lib/config.ts
 import { existsSync as existsSync8, readFileSync as readFileSync5 } from "fs";
 import { join as join8 } from "path";
-import { parseArgs as parseArgs14 } from "util";
+import { parseArgs as parseArgs15 } from "util";
 var DEFAULT_BASE_URL = "http://localhost:3002";
 function parseGlobalFlags(argv) {
-  const { values, tokens } = parseArgs14({
+  const { values, tokens } = parseArgs15({
     args: argv,
     allowPositionals: true,
     strict: false,