diff --git a/Phase-4.md b/Phase-4.md new file mode 100644 index 0000000..28e111a --- /dev/null +++ b/Phase-4.md @@ -0,0 +1,126 @@ +# Phase 4: Bots & Extensibility + +Phase 4 brings the bot framework, slash commands, and incoming webhooks to Dumpster. + +## Features Implemented + +### Bot Framework + +| Feature | Status | Description | +|---------|--------|-------------| +| Bot CRUD | ✅ | Create, list, get, update, delete bots | +| Bot tokens | ✅ | 64-char hex tokens, shown once on create/regenerate | +| Bot server management | ✅ | Add/remove bots from servers | +| Bot WebSocket | ✅ | `/ws/bot` endpoint for real-time events | +| Bot message sending | ✅ | Bots send messages via API with bot auth | + +### Slash Commands + +| Feature | Status | Description | +|---------|--------|-------------| +| Command registration | ✅ | Register commands per bot per server | +| Command management | ✅ | CRUD for slash commands | +| Command autocomplete | ✅ | `/` triggers popup with registered commands | +| Server commands API | ✅ | List all commands for a server | + +### Incoming Webhooks + +| Feature | Status | Description | +|---------|--------|-------------| +| Webhook creation | ✅ | Create webhooks per channel | +| Webhook execution | ✅ | Public endpoint (no auth) to send messages | +| Username/avatar override | ✅ | Webhook messages can override bot name/avatar | +| Webhook management | ✅ | CRUD for webhooks | + +### Example Bots + +| Bot | Description | +|-----|-------------| +| **Modbot** | Auto-delete messages with banned words, `/kick`, `/ban`, `/purge` commands | +| **Welcome bot** | Send welcome message when member joins server | + +## API Reference + +### Bot Management + +```bash +# Create a bot +POST /api/v1/bots +{ "name": "Modbot", "description": "Moderation bot" } +→ { "id": "...", "token": "abc123...", "name": "Modbot" } + +# List my bots +GET /api/v1/bots +→ [{ "id": "...", "name": "Modbot", ... }] + +# Add bot to server +POST /api/v1/bots/{id}/servers +{ "server_id": "..." } +→ { "ok": true } + +# Regenerate token +POST /api/v1/bots/{id}/regenerate-token +→ { "token": "new_token..." } +``` + +### Bot WebSocket + +```bash +# Connect as bot +ws://host/ws/bot?token=abc123... + +# Receive events +{ "type": "MESSAGE_CREATE", "payload": { ... } } +{ "type": "SERVER_MEMBER_ADD", "payload": { ... } } + +# Send message +{ "type": "SEND_MESSAGE", "payload": { "channel_id": "...", "content": "Hello!" } } +``` + +### Slash Commands + +```bash +# Register command +POST /api/v1/bots/{id}/commands +{ "server_id": "...", "name": "kick", "description": "Kick a user" } + +# List server commands (for autocomplete) +GET /api/v1/servers/{id}/commands +→ [{ "name": "kick", "description": "Kick a user", "bot_name": "Modbot" }] +``` + +### Webhooks + +```bash +# Create webhook +POST /api/v1/channels/{id}/webhooks +{ "name": "GitHub" } +→ { "id": "...", "token": "...", "url": "https://host/webhooks/{id}/{token}" } + +# Execute webhook (public, no auth) +POST /webhooks/{id}/{token} +{ "content": "New commit pushed", "username": "GitHub", "avatar_url": "..." } +``` + +## Running Example Bots + +### Modbot + +```bash +cd examples/modbot +BOT_TOKEN=your_bot_token go run main.go +``` + +### Welcome Bot + +```bash +cd examples/welcome +BOT_TOKEN=your_bot_token go run main.go +``` + +## What's Next + +Phase 5: TUI Client +- Terminal-based chat + voice client +- Vim-style keybindings +- LiveKit audio integration diff --git a/_Sidebar.md b/_Sidebar.md index 0b86923..b2a648f 100644 --- a/_Sidebar.md +++ b/_Sidebar.md @@ -7,6 +7,7 @@ - [Profiles](Profiles) - [Voice & Video](Voice-and-Video) - [Phase 3: Polish & PWA](Phase-3) +- [Phase 4: Bots & Extensibility](Phase-4) - [Frontend Design](Frontend-Design) - [Self-Hosting](Self-Hosting) - [Roadmap](Roadmap)