calabasas 0.22.0 → 0.23.1

package/dist/index.js

@@ -7834,6 +7834,340 @@ Run ${pc3.cyan("`calabasas init`")} first.`);
   await interactiveConfig(currentConfig, configPath);
 }
 
+// src/commands/webhook.ts
+import pc4 from "picocolors";
+function resolveAuthOrExit() {
+  const resolved = resolvePlatformApiKey({});
+  if (!resolved) {
+    console.error(pc4.red("Error:") + ` no Calabasas credentials found.
+` + "  Run `calabasas login` (user key) or set CALABASAS_PLATFORM_API_KEY in .env.local.");
+    process.exit(1);
+  }
+  return resolved.key;
+}
+function parseDuration(input) {
+  const match = /^(\d+)(s|m|h|d)$/.exec(input.trim());
+  if (!match)
+    return null;
+  const value = Number(match[1]);
+  const unit = match[2];
+  const multipliers = {
+    s: 1000,
+    m: 60000,
+    h: 3600000,
+    d: 86400000
+  };
+  return value * multipliers[unit];
+}
+function normalizeCreateInput(options, now = Date.now()) {
+  if (!options.bot) {
+    return { ok: false, error: "--bot <botId> is required" };
+  }
+  if (options.action !== "sendDM" && options.action !== "sendChannelMessage") {
+    return {
+      ok: false,
+      error: `invalid --action: ${options.action ?? "(missing)"}. Must be one of: sendDM, sendChannelMessage`
+    };
+  }
+  let params;
+  if (options.action === "sendDM") {
+    if (!options.userId) {
+      return { ok: false, error: "--user-id <discordUserId> is required for sendDM" };
+    }
+    params = { userId: options.userId };
+  } else {
+    if (!options.channelId) {
+      return {
+        ok: false,
+        error: "--channel-id <discordChannelId> is required for sendChannelMessage"
+      };
+    }
+    params = { channelId: options.channelId };
+  }
+  let maxUses;
+  if (options.maxUses !== undefined) {
+    const parsed = Number(options.maxUses);
+    if (!Number.isFinite(parsed) || parsed <= 0 || !Number.isInteger(parsed)) {
+      return {
+        ok: false,
+        error: `invalid --max-uses: ${options.maxUses}. Must be a positive integer.`
+      };
+    }
+    maxUses = parsed;
+  }
+  let expiresAt;
+  if (options.expires !== undefined) {
+    const ms = parseDuration(options.expires);
+    if (ms === null) {
+      return {
+        ok: false,
+        error: `invalid --expires: ${options.expires}. Format: <number><unit> where unit is s|m|h|d (e.g. 30m, 24h, 7d).`
+      };
+    }
+    expiresAt = now + ms;
+  }
+  return {
+    ok: true,
+    payload: {
+      botId: options.bot,
+      action: options.action,
+      params,
+      label: options.label,
+      maxUses,
+      expiresAt,
+      platformId: options.platformId
+    }
+  };
+}
+async function webhookCreate(options) {
+  const apiKey = resolveAuthOrExit();
+  const result = normalizeCreateInput(options);
+  if (!result.ok) {
+    console.error(pc4.red("Error:") + " " + result.error);
+    process.exit(1);
+  }
+  const { payload } = result;
+  const { ok, data, status } = await platformApiRequest("POST", "/api/cli/webhooks", apiKey, payload);
+  if (!ok) {
+    const errMsg = data?.error ?? `HTTP ${status}`;
+    console.error(pc4.red("Error:") + " " + errMsg);
+    process.exit(1);
+  }
+  const created = data;
+  console.log(pc4.green("Webhook created."));
+  console.log("");
+  console.log(`URL: ${pc4.cyan(created.url)}`);
+  console.log(`token: ${created.token}`);
+  console.log(`webhookId: ${created.webhookId}`);
+  console.log(`action: ${created.action}`);
+  console.log(`params: ${JSON.stringify(created.params)}`);
+  if (payload.label)
+    console.log(`label: ${payload.label}`);
+  if (payload.maxUses !== undefined)
+    console.log(`maxUses: ${payload.maxUses}`);
+  if (payload.expiresAt !== undefined) {
+    console.log(`expiresAt: ${new Date(payload.expiresAt).toISOString()}`);
+  }
+  console.log("");
+  console.log(pc4.dim(`Fire it with: curl -X POST -H 'Content-Type: application/json' -d '{"content":"hi"}' ` + created.url));
+}
+async function webhookList(options) {
+  const apiKey = resolveAuthOrExit();
+  const { ok, data, status } = await platformApiRequest("GET", "/api/cli/webhooks", apiKey);
+  if (!ok) {
+    const errMsg = data?.error ?? `HTTP ${status}`;
+    console.error(pc4.red("Error:") + " " + errMsg);
+    process.exit(1);
+  }
+  const webhooks = data.webhooks;
+  if (options.json) {
+    console.log(JSON.stringify(webhooks, null, 2));
+    return;
+  }
+  if (webhooks.length === 0) {
+    console.log("No webhooks found.");
+    console.log(pc4.dim("Create one with: calabasas webhook create --bot <id> --action sendDM --user-id <id>"));
+    return;
+  }
+  for (const w of webhooks) {
+    const target = w.params.userId ? `user ${w.params.userId}` : `channel ${w.params.channelId}`;
+    const uses = w.maxUses !== undefined ? `${w.usageCount}/${w.maxUses}` : `${w.usageCount}/—`;
+    const statusColor = w.status === "active" ? pc4.green : w.status === "expired" ? pc4.yellow : pc4.red;
+    console.log(`${pc4.cyan(w.token)}  ${w.action}  ${target}  uses=${uses}  ${statusColor(w.status)}` + (w.label ? `  label=${w.label}` : ""));
+    console.log(`  ${pc4.dim(w.url)}`);
+  }
+}
+async function webhookRevoke(token, _options) {
+  if (!token) {
+    console.error(pc4.red("Error:") + " token argument is required.");
+    process.exit(1);
+  }
+  const apiKey = resolveAuthOrExit();
+  const { ok, data, status } = await platformApiRequest("DELETE", `/api/cli/webhooks?token=${encodeURIComponent(token)}`, apiKey);
+  if (!ok) {
+    const errMsg = data?.error ?? `HTTP ${status}`;
+    console.error(pc4.red("Error:") + " " + errMsg);
+    process.exit(1);
+  }
+  console.log(pc4.green("Webhook revoked."));
+}
+
+// src/commands/webhook-skill.ts
+import * as fs9 from "fs";
+import * as path9 from "path";
+import pc5 from "picocolors";
+var DEFAULT_SKILL_PATH = ".claude/skills/calabasas-webhook/SKILL.md";
+var SKILL_CONTENT = `---
+name: calabasas-webhook
+description: Use when the user wants to fire a single Discord action (DM a user, post to a channel) from a non-Discord-aware system — Zapier, n8n, cron jobs, GitHub Actions, an LLM tool, a no-code form, a webhook from another SaaS. The Calabasas one-off webhook turns a pre-bound action into a plain POST URL with no Discord SDK or auth on the caller side. Trigger when the user says things like "send a DM from a cron", "fire a Discord message from Zapier", "give me a URL that DMs user X", "I need a webhook to post in #channel", or asks how to bridge an external tool to Discord without writing a bot integration.
+---
+
+# Calabasas one-off webhooks
+
+A Calabasas webhook is a URL that fires **one** pre-bound Discord action when POSTed to. The action, the bot, and the target (user or channel) are all baked into the URL at create time. The body only carries the message payload (\`content\` / \`embeds\`).
+
+This is the right tool when:
+- A non-Discord system needs to send a Discord message (Zapier, n8n, cron, external SaaS webhooks, GitHub Actions, monitoring alerts).
+- The caller cannot or should not hold a bot token.
+- The action is narrow and known up front — "DM this exact user", "post to this exact channel".
+
+**Not** the right tool when:
+- The caller needs to choose the target at fire time (use the Calabasas SDK or generated Discord actions instead).
+- The action is more complex than \`sendDM\` / \`sendChannelMessage\` (kick, ban, role assignment — use the SDK).
+- The caller is the user's own Convex backend (use generated Discord actions; no HTTP roundtrip needed).
+
+## Supported actions (v1)
+
+| Action | Bound param | Body fields |
+|--------|-------------|-------------|
+| \`sendDM\` | \`--user-id <discordUserId>\` | \`content\` and/or \`embeds\` |
+| \`sendChannelMessage\` | \`--channel-id <discordChannelId>\` | \`content\` and/or \`embeds\` |
+
+## CLI commands (non-interactive, scriptable)
+
+All flags are required-or-fail; no prompts. Safe to drive from an LLM or shell script.
+
+### Create
+
+\`\`\`bash
+calabasas webhook create \\
+  --bot <botId> \\
+  --action <sendDM|sendChannelMessage> \\
+  [--user-id <discordUserId> | --channel-id <discordChannelId>] \\
+  [--label <label>] \\
+  [--max-uses <number>] \\
+  [--expires <duration>]
+\`\`\`
+
+| Flag | Notes |
+|------|-------|
+| \`--bot\` | Calabasas bot ID. Use \`calabasas bot list --once\` to find one. |
+| \`--action\` | \`sendDM\` or \`sendChannelMessage\`. |
+| \`--user-id\` | Required for \`sendDM\`. Discord user snowflake. |
+| \`--channel-id\` | Required for \`sendChannelMessage\`. Discord channel snowflake. |
+| \`--label\` | Free-form label shown in \`webhook list\`. |
+| \`--max-uses\` | Hard cap. Both successful and failed fires count toward the cap. |
+| \`--expires\` | Auto-expire after duration: \`30m\`, \`24h\`, \`7d\`, etc. (\`s\\|m\\|h\\|d\`). |
+
+Output (key=value lines, easy to grep):
+
+\`\`\`
+Webhook created.
+
+URL: https://calabasas-production.up.railway.app/api/hooks/whk_xxxxx
+token: whk_xxxxx
+webhookId: <id>
+action: sendDM
+params: {"userId":"123456789012345678"}
+\`\`\`
+
+### Fire
+
+\`\`\`bash
+curl -X POST \\
+  -H 'Content-Type: application/json' \\
+  -d '{"content":"Hello!"}' \\
+  https://calabasas-production.up.railway.app/api/hooks/whk_xxxxx
+\`\`\`
+
+Body fields:
+
+| Field | Type | Notes |
+|-------|------|-------|
+| \`content\` | string | Message text. At least one of \`content\` or \`embeds\` is required. |
+| \`embeds\` | array | Discord embed objects. |
+| \`tts\` | boolean | Text-to-speech. |
+| \`allowedMentions\` | object | Discord allowed-mentions object (camelCase). |
+
+Response shape (always JSON):
+
+- Success → \`{ "ok": true, "messageId": "..." }\` (HTTP 200)
+- Failure → \`{ "ok": false, "error": "..." }\` (HTTP 4xx/5xx)
+
+Status codes:
+
+| Code | Meaning |
+|------|---------|
+| 200 | Action fired |
+| 400 | Invalid body (missing \`content\`/\`embeds\`, malformed JSON) |
+| 404 | Token not found or revoked |
+| 410 | Token expired or \`maxUses\` reached |
+| 502 | Discord rejected the request |
+| 503 | Bot is currently offline — retry shortly |
+
+### List
+
+\`\`\`bash
+calabasas webhook list           # human-friendly table
+calabasas webhook list --json    # raw JSON for tooling/LLM use
+\`\`\`
+
+Status column shows \`active\`, \`expired\`, or \`exhausted\`. Revoked rows are filtered out.
+
+### Revoke
+
+\`\`\`bash
+calabasas webhook revoke <token>
+\`\`\`
+
+Soft delete — URL stops working immediately, row stays for audit. To rotate a leaked token, revoke and create a fresh one (the URL changes; consumers must update).
+
+## Choosing limits
+
+Webhooks are public — anyone with the URL can fire. Treat the URL like a one-shot capability token. Defaults to keep things safe:
+
+- **Set \`--max-uses\`** unless the integration genuinely needs unlimited fires. Even \`--max-uses 1000\` is far better than uncapped.
+- **Set \`--expires\`** for any webhook tied to a campaign / deploy / time-bound flow.
+- **Use \`--label\`** so you can identify it in \`webhook list\` later.
+
+## Common patterns
+
+**Cron alert to a channel:**
+\`\`\`bash
+calabasas webhook create --bot <id> --action sendChannelMessage \\
+  --channel-id 123 --label "nightly-report" --max-uses 365 --expires 365d
+# Then in your cron: curl -X POST -d '{"content":"Nightly report ready"}' <url>
+\`\`\`
+
+**One-shot welcome DM from a sign-up form:**
+\`\`\`bash
+calabasas webhook create --bot <id> --action sendDM \\
+  --user-id <id> --max-uses 1 --expires 1h
+\`\`\`
+
+**Zapier "post to Discord" step:** create a \`sendChannelMessage\` webhook, paste URL into Zapier's webhooks-by-Zapier action with body \`{"content": "{{trigger field}}"}\`.
+
+## Authentication
+
+CLI commands resolve credentials in this order:
+1. \`CALABASAS_PLATFORM_API_KEY\` in \`.env.local\` (preferred — \`cpk_\` prefix).
+2. User API key from \`~/.calabasas/config.json\` (fallback — \`clb_\` prefix).
+
+Run \`calabasas login\` (user key) or \`calabasas platform create\` / \`calabasas platform connect\` (platform key) if neither is set.
+
+## Anti-patterns
+
+- **Don't bake secrets into the URL beyond the token** — the token *is* the credential.
+- **Don't share one webhook across many services** — one URL per integration so revoke kills exactly one consumer.
+- **Don't substitute webhooks for the SDK** when the caller is your own Convex backend; the generated \`discord.actions.ts\` is faster and richer.
+`;
+async function webhookSkill(options) {
+  const target = options.output ?? DEFAULT_SKILL_PATH;
+  const fullPath = path9.resolve(process.cwd(), target);
+  const dir = path9.dirname(fullPath);
+  if (fs9.existsSync(fullPath) && !options.force) {
+    console.error(pc5.red("Error:") + ` ${target} already exists.
+` + "  Re-run with --force to overwrite, or pass --output <path> to write elsewhere.");
+    process.exit(1);
+  }
+  if (!fs9.existsSync(dir)) {
+    fs9.mkdirSync(dir, { recursive: true });
+  }
+  fs9.writeFileSync(fullPath, SKILL_CONTENT);
+  console.log(pc5.green("Installed calabasas-webhook skill at ") + pc5.cyan(target));
+  console.log(pc5.dim("Claude Code will pick it up on next start. The skill triggers when the user wants to fire a single Discord action from an external service."));
+}
+
 // src/index.ts
 var dashboard = async () => {
   const mod = await import("./dashboard-a862sabz.js");
@@ -7870,4 +8204,9 @@ platformCmd.command("info").description("Show platform info (secret, URL, API ke
 platformCmd.command("set-url").description("Set Convex URL for your platform").action(platformSetUrl);
 platformCmd.command("rotate-key").description("Rotate your platform API key (for SDK access)").action(platformRotateKey);
 platformCmd.command("rotate-secret").description("Rotate the platform secret (invalidates CALABASAS_SECRET)").action(platformRotateSecret);
+var webhookCmd = program2.command("webhook").description("Manage one-off webhook URLs that fire pre-bound Discord actions");
+webhookCmd.command("create").description("Create a webhook URL bound to a single bot, action, and target").requiredOption("-b, --bot <botId>", "Bot ID that will perform the action").requiredOption("-a, --action <action>", "Action to fire: sendDM | sendChannelMessage").option("--user-id <discordUserId>", "Target user ID (required for sendDM)").option("--channel-id <discordChannelId>", "Target channel ID (required for sendChannelMessage)").option("--label <label>", "Human-readable label for listing").option("--max-uses <number>", "Max times this URL can be fired before it stops working").option("--expires <duration>", "Auto-expire after duration: e.g. 30m, 24h, 7d").option("--platform-id <id>", "Platform ID (only needed with user key + multiple platforms)").action(webhookCreate);
+webhookCmd.command("list").alias("ls").description("List all non-revoked webhooks for the current platform").option("--json", "Output raw JSON instead of a table").action(webhookList);
+webhookCmd.command("revoke <token>").description("Revoke a webhook by token (soft delete)").option("-y, --yes", "Skip confirmation prompt (currently a no-op)").action(webhookRevoke);
+webhookCmd.command("skill").description("Install the calabasas-webhook Claude Code skill in this project").option("-o, --output <path>", "Output path", ".claude/skills/calabasas-webhook/SKILL.md").option("-f, --force", "Overwrite if the file already exists").action(webhookSkill);
 program2.parse();

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "calabasas",
-  "version": "0.22.0",
+  "version": "0.23.1",
   "description": "CLI for Calabasas - Discord Gateway as a Service for Convex",
   "type": "module",
   "bin": {