cord-bot 1.0.2 → 1.0.5

package/skills/cord/HTTP-API.md

@@ -0,0 +1,273 @@
+# HTTP API Reference
+
+Low-level HTTP API for interacting with Discord. For Claude Code, use the CLI commands in [SKILL.md](./SKILL.md) instead.
+
+**Port:** `2643` (configurable via `API_PORT` env var)
+
+## Health Check
+
+```bash
+curl http://localhost:2643/health
+# {"status":"ok","connected":true,"user":"MyBot#1234"}
+```
+
+## send-message
+
+Send a text message to a channel or thread.
+
+```bash
+curl -X POST http://localhost:2643/command \
+  -H 'Content-Type: application/json' \
+  -d '{
+    "command": "send-to-thread",
+    "args": {
+      "thread": "CHANNEL_OR_THREAD_ID",
+      "message": "Hello from Cord!"
+    }
+  }'
+```
+
+## send-embed
+
+Send a formatted embed card with optional fields.
+
+```bash
+curl -X POST http://localhost:2643/command \
+  -H 'Content-Type: application/json' \
+  -d '{
+    "command": "send-to-thread",
+    "args": {
+      "thread": "CHANNEL_OR_THREAD_ID",
+      "embeds": [{
+        "title": "Status Report",
+        "description": "Daily summary",
+        "color": 3447003,
+        "fields": [
+          {"name": "Tasks", "value": "5 completed", "inline": true},
+          {"name": "Emails", "value": "12 processed", "inline": true}
+        ],
+        "footer": {"text": "Generated by Cord"}
+      }]
+    }
+  }'
+```
+
+**Color reference:**
+- Success/Green: `3066993` (0x2ECC71)
+- Info/Blue: `3447003` (0x3498DB)
+- Warning/Yellow: `16776960` (0xFFFF00)
+- Error/Red: `15158332` (0xE74C3C)
+- Purple: `10181046` (0x9B59B6)
+
+## send-file
+
+Attach content as a file (good for long reports).
+
+```bash
+curl -X POST http://localhost:2643/send-with-file \
+  -H 'Content-Type: application/json' \
+  -d '{
+    "channelId": "CHANNEL_OR_THREAD_ID",
+    "fileName": "report.md",
+    "fileContent": "# Report\n\nContent here...",
+    "content": "Here is the detailed report"
+  }'
+```
+
+## send-buttons
+
+Send a message with interactive button choices.
+
+```bash
+curl -X POST http://localhost:2643/send-with-buttons \
+  -H 'Content-Type: application/json' \
+  -d '{
+    "channelId": "CHANNEL_OR_THREAD_ID",
+    "content": "Choose an option:",
+    "buttons": [
+      {"label": "Approve", "customId": "approve-123", "style": "success"},
+      {"label": "Reject", "customId": "reject-123", "style": "danger"}
+    ]
+  }'
+```
+
+**Button styles:** `primary`, `secondary`, `success`, `danger`
+
+### Buttons with inline handler
+
+Register a handler that fires when the button is clicked.
+
+```bash
+curl -X POST http://localhost:2643/send-with-buttons \
+  -H 'Content-Type: application/json' \
+  -d '{
+    "channelId": "CHANNEL_OR_THREAD_ID",
+    "content": "Click for details",
+    "buttons": [{
+      "label": "Show Details",
+      "customId": "details-123",
+      "style": "secondary",
+      "handler": {
+        "type": "inline",
+        "content": "Here are the details...",
+        "ephemeral": true
+      }
+    }]
+  }'
+```
+
+### Buttons with webhook handler
+
+Call an external URL when clicked.
+
+```bash
+curl -X POST http://localhost:2643/send-with-buttons \
+  -H 'Content-Type: application/json' \
+  -d '{
+    "channelId": "CHANNEL_OR_THREAD_ID",
+    "content": "Approve deployment?",
+    "buttons": [{
+      "label": "Deploy",
+      "customId": "deploy-prod",
+      "style": "success",
+      "handler": {
+        "type": "webhook",
+        "url": "http://localhost:8080/deploy",
+        "data": {"env": "production"}
+      }
+    }]
+  }'
+```
+
+## typing
+
+Show typing indicator (useful before slow operations).
+
+```bash
+curl -X POST http://localhost:2643/command \
+  -H 'Content-Type: application/json' \
+  -d '{
+    "command": "start-typing",
+    "args": {"channel": "CHANNEL_OR_THREAD_ID"}
+  }'
+```
+
+## edit-message
+
+Edit an existing message.
+
+```bash
+curl -X POST http://localhost:2643/command \
+  -H 'Content-Type: application/json' \
+  -d '{
+    "command": "edit-message",
+    "args": {
+      "channel": "CHANNEL_ID",
+      "message": "MESSAGE_ID",
+      "content": "Updated content"
+    }
+  }'
+```
+
+## delete-message
+
+Delete a message.
+
+```bash
+curl -X POST http://localhost:2643/command \
+  -H 'Content-Type: application/json' \
+  -d '{
+    "command": "delete-message",
+    "args": {
+      "channel": "CHANNEL_ID",
+      "message": "MESSAGE_ID"
+    }
+  }'
+```
+
+## rename-thread
+
+Rename a thread.
+
+```bash
+curl -X POST http://localhost:2643/command \
+  -H 'Content-Type: application/json' \
+  -d '{
+    "command": "rename-thread",
+    "args": {
+      "thread": "THREAD_ID",
+      "name": "New Thread Name"
+    }
+  }'
+```
+
+## reply-to-message
+
+Reply to a specific message (shows reply preview).
+
+```bash
+curl -X POST http://localhost:2643/command \
+  -H 'Content-Type: application/json' \
+  -d '{
+    "command": "reply-to-message",
+    "args": {
+      "channel": "CHANNEL_ID",
+      "message": "MESSAGE_ID",
+      "content": "This is a reply"
+    }
+  }'
+```
+
+## create-thread
+
+Create a thread from a message.
+
+```bash
+curl -X POST http://localhost:2643/command \
+  -H 'Content-Type: application/json' \
+  -d '{
+    "command": "create-thread",
+    "args": {
+      "channel": "CHANNEL_ID",
+      "message": "MESSAGE_ID",
+      "name": "Thread Name"
+    }
+  }'
+```
+
+## add-reaction
+
+Add a reaction to a message.
+
+```bash
+curl -X POST http://localhost:2643/command \
+  -H 'Content-Type: application/json' \
+  -d '{
+    "command": "add-reaction",
+    "args": {
+      "channel": "CHANNEL_ID",
+      "message": "MESSAGE_ID",
+      "emoji": "👍"
+    }
+  }'
+```
+
+## Response Format
+
+All endpoints return JSON:
+
+```json
+{"success": true, "messageId": "1234567890"}
+```
+
+On error:
+
+```json
+{"error": "Description of what went wrong"}
+```
+
+## Environment Variables
+
+| Variable | Default | Description |
+|----------|---------|-------------|
+| `API_PORT` | `2643` | HTTP API server port |

package/skills/cord/SKILL.md

@@ -0,0 +1,304 @@
+---
+name: cord
+description: Send messages, embeds, files, and interactive buttons to Discord via the Cord CLI. Use for notifications, reports, interactive choices, and dynamic Discord interactions.
+triggers:
+  - "send to discord"
+  - "post to discord"
+  - "discord message"
+  - "notify discord"
+---
+
+# Cord - Discord Bridge Skill
+
+Interact with Discord through Cord's CLI commands. This skill teaches Claude Code how to send messages, embeds, files, and interactive buttons.
+
+**GitHub:** https://github.com/alexknowshtml/cord
+
+## Setup
+
+Ensure Cord is running:
+```bash
+cord start
+```
+
+Verify it's connected:
+```bash
+curl -s http://localhost:2643/health
+# {"status":"ok","connected":true,"user":"MyBot#1234"}
+```
+
+---
+
+## CLI Commands
+
+### send
+
+Send a text message to a channel or thread.
+
+```bash
+cord send <channel> "message"
+```
+
+**Example:**
+```bash
+cord send 123456789 "Hello world!"
+```
+
+---
+
+### embed
+
+Send a formatted embed card with optional styling.
+
+```bash
+cord embed <channel> "description" [options]
+```
+
+**Options:**
+| Flag | Description |
+|------|-------------|
+| `--title "..."` | Embed title |
+| `--url "..."` | Title link URL |
+| `--color <name\|hex>` | red, green, blue, yellow, purple, orange, or 0xHEX |
+| `--author "..."` | Author name |
+| `--author-url "..."` | Author link |
+| `--author-icon "..."` | Author icon URL |
+| `--thumbnail "..."` | Small image (top right) |
+| `--image "..."` | Large image (bottom) |
+| `--footer "..."` | Footer text |
+| `--footer-icon "..."` | Footer icon URL |
+| `--timestamp` | Add current timestamp |
+| `--field "Name:Value"` | Add field (append `:inline` for inline) |
+
+**Examples:**
+
+Simple embed:
+```bash
+cord embed 123456789 "Daily status update" --title "Status Report" --color green
+```
+
+Embed with fields:
+```bash
+cord embed 123456789 "Build completed successfully" \
+  --title "CI/CD Pipeline" \
+  --color green \
+  --field "Branch:main:inline" \
+  --field "Duration:2m 34s:inline" \
+  --field "Tests:142 passed" \
+  --footer "Deployed by Cord" \
+  --timestamp
+```
+
+---
+
+### file
+
+Send a file attachment.
+
+```bash
+cord file <channel> <filepath> ["message"]
+```
+
+**Examples:**
+```bash
+cord file 123456789 ./report.md "Here's the weekly report"
+cord file 123456789 ./logs.txt
+```
+
+---
+
+### buttons
+
+Send interactive buttons with optional handlers.
+
+```bash
+cord buttons <channel> "prompt" --button label="..." id="..." [options]
+```
+
+**Button options:**
+| Option | Description |
+|--------|-------------|
+| `label="..."` | Button text (required) |
+| `id="..."` | Custom ID for tracking (required) |
+| `style="..."` | primary, secondary, success, danger |
+| `reply="..."` | Ephemeral reply when clicked |
+| `webhook="..."` | URL to POST click data to |
+
+**Examples:**
+
+Simple confirmation:
+```bash
+cord buttons 123456789 "Deploy to production?" \
+  --button label="Deploy" id="deploy-prod" style="success" \
+  --button label="Cancel" id="cancel-deploy" style="secondary"
+```
+
+With inline responses:
+```bash
+cord buttons 123456789 "Approve this PR?" \
+  --button label="Approve" id="approve" style="success" reply="Approved! Merging now." \
+  --button label="Reject" id="reject" style="danger" reply="Rejected. Please revise."
+```
+
+With webhook callback:
+```bash
+cord buttons 123456789 "Start backup?" \
+  --button label="Start Backup" id="backup-start" style="primary" webhook="http://localhost:8080/backup"
+```
+
+---
+
+### typing
+
+Show typing indicator (useful before slow operations).
+
+```bash
+cord typing <channel>
+```
+
+---
+
+### edit
+
+Edit an existing message.
+
+```bash
+cord edit <channel> <messageId> "new content"
+```
+
+---
+
+### delete
+
+Delete a message.
+
+```bash
+cord delete <channel> <messageId>
+```
+
+---
+
+### rename
+
+Rename a thread.
+
+```bash
+cord rename <threadId> "new name"
+```
+
+---
+
+### reply
+
+Reply to a specific message (shows reply preview).
+
+```bash
+cord reply <channel> <messageId> "message"
+```
+
+---
+
+### thread
+
+Create a thread from a message.
+
+```bash
+cord thread <channel> <messageId> "thread name"
+```
+
+---
+
+### react
+
+Add a reaction to a message.
+
+```bash
+cord react <channel> <messageId> "emoji"
+```
+
+**Example:**
+```bash
+cord react 123456789 987654321 "👍"
+```
+
+---
+
+## Choosing the Right Command
+
+| Use Case | Command |
+|----------|---------|
+| Simple notification | `cord send` |
+| Formatted status update | `cord embed` |
+| Long content (logs, reports) | `cord file` |
+| User needs to make a choice | `cord buttons` |
+| Indicate processing | `cord typing` |
+| Update previous message | `cord edit` |
+| Start a focused discussion | `cord thread` |
+| Quick acknowledgment | `cord react` |
+
+---
+
+## Assembly Patterns
+
+### Notification with follow-up options
+
+```bash
+# Send the notification
+cord embed 123456789 "Build failed on main branch" \
+  --title "CI Alert" \
+  --color red \
+  --field "Error:Test suite timeout" \
+  --field "Commit:abc1234:inline"
+
+# Offer actions
+cord buttons 123456789 "What would you like to do?" \
+  --button label="View Logs" id="view-logs" style="primary" reply="Fetching logs..." \
+  --button label="Retry Build" id="retry" style="success" webhook="http://ci/retry" \
+  --button label="Ignore" id="ignore" style="secondary" reply="Acknowledged"
+```
+
+### Progress updates
+
+```bash
+# Start with typing indicator
+cord typing 123456789
+
+# Send initial status
+MSGID=$(cord send 123456789 "Processing... 0%" | grep -o '[0-9]*$')
+
+# Update as progress continues
+cord edit 123456789 $MSGID "Processing... 50%"
+cord edit 123456789 $MSGID "Processing... 100% Complete!"
+
+# Add completion reaction
+cord react 123456789 $MSGID "✅"
+```
+
+### Report delivery
+
+```bash
+# Send summary embed
+cord embed 123456789 "Weekly metrics compiled" \
+  --title "Weekly Report Ready" \
+  --color blue \
+  --field "Period:Jan 15-21:inline" \
+  --field "Pages:12:inline"
+
+# Attach the full report
+cord file 123456789 ./weekly-report.pdf "Full report attached"
+```
+
+### Confirmation flow
+
+```bash
+# Ask for confirmation
+cord buttons 123456789 "Delete all archived items older than 30 days?" \
+  --button label="Yes, Delete" id="confirm-delete" style="danger" reply="Deleting..." \
+  --button label="Cancel" id="cancel-delete" style="secondary" reply="Cancelled"
+```
+
+---
+
+## HTTP API
+
+For advanced use cases (webhooks, external scripts), see [HTTP-API.md](./HTTP-API.md).