calabasas 0.23.0 → 0.23.1

package/dist/index.js

@@ -7992,6 +7992,182 @@ async function webhookRevoke(token, _options) {
   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");
@@ -8032,4 +8208,5 @@ var webhookCmd = program2.command("webhook").description("Manage one-off webhook
 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.23.0",
+  "version": "0.23.1",
   "description": "CLI for Calabasas - Discord Gateway as a Service for Convex",
   "type": "module",
   "bin": {