diff --git a/Home.md b/Home.md index 3f980a9..1e43c47 100644 --- a/Home.md +++ b/Home.md @@ -11,3 +11,4 @@ Welcome to the Dumpster wiki. This is the living documentation for the self-host - [Self-Hosting](Self-Hosting) - [Development Roadmap](Roadmap) - [Troubleshooting](Troubleshooting) +- [Bots & Extensibility](Phase-4) diff --git a/Phase-4.md b/Phase-4.md index 28e111a..0fdf9b5 100644 --- a/Phase-4.md +++ b/Phase-4.md @@ -1,6 +1,6 @@ # Phase 4: Bots & Extensibility -Phase 4 brings the bot framework, slash commands, and incoming webhooks to Dumpster. +Phase 4 brings the bot framework, slash commands, incoming webhooks, and built-in bots to Dumpster. ## Features Implemented @@ -12,7 +12,11 @@ Phase 4 brings the bot framework, slash commands, and incoming webhooks to Dumps | 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 | +| Bot message sending | ✅ | Bots send messages via WS with bot auth | +| Bot store | ✅ | Public listing at `/bots` with server counts | +| Bot message badges | ✅ | Green name + BOT tag on bot messages in chat | +| Built-in bot runner | ✅ | Server-manages bots, no SSH required | +| Built-in bot: steamfree | ✅ | Polls Steam API for free games, auto-posts | ### Slash Commands @@ -38,29 +42,81 @@ Phase 4 brings the bot framework, slash commands, and incoming webhooks to Dumps |-----|-------------| | **Modbot** | Auto-delete messages with banned words, `/kick`, `/ban`, `/purge` commands | | **Welcome bot** | Send welcome message when member joins server | +| **Steam Free Games** | Polls Steam's featured categories for 100%-off games (built-in) | + +## Using Built-in Bots + +Built-in bots run inside the dumpsterChat server. No SSH, no separate process. + +1. Go to **/bots/manage** in the web UI +2. Click **[CREATE BOT]** +3. Name it, pick a type from the dropdown (e.g. "Steam Free Games") +4. Select the server and channel to post to +5. Click **[SAVE]** + +The bot starts immediately. It restarts automatically when the server restarts. + +### Adding New Built-in Bot Types + +Three touch points: + +1. **`internal/bot/yourbot.go`** — write a `BotFunc` that takes `(ctx, config, send)` +2. **`cmd/server/main.go`** — register it: `botRunner.Register("yourbot", bot.YourBot)` +3. **`web/src/components/BotManager.tsx`** — add config fields to `BOT_TYPE_CONFIGS` + +## Running External Example Bots + +External bots connect via WebSocket and run as separate processes. + +### 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 DUMPSTER_HOST=dumpster.dustin.coffee go run main.go +``` + +### Steam Free Games (standalone) + +```bash +cd examples/steamfree +BOT_TOKEN=your_bot_token CHANNEL_ID=channel-uuid DUMPSTER_HOST=dumpster.dustin.coffee go run main.go +``` ## API Reference ### Bot Management ```bash -# Create a bot +# Create a bot (external) POST /api/v1/bots { "name": "Modbot", "description": "Moderation bot" } -→ { "id": "...", "token": "abc123...", "name": "Modbot" } + +# Create a built-in bot +POST /api/v1/bots +{ "name": "Free Games", "description": "Posts free Steam games", "bot_type": "steamfree", "config": { "channel_id": "...", "poll_minutes": 30 } } # List my bots GET /api/v1/bots -→ [{ "id": "...", "name": "Modbot", ... }] + +# Bot store (all bots, public) +GET /api/v1/bots/store + +# Available bot types +GET /api/v1/bots/types # 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 @@ -75,6 +131,9 @@ ws://host/ws/bot?token=abc123... # Send message { "type": "SEND_MESSAGE", "payload": { "channel_id": "...", "content": "Hello!" } } + +# Delete message +{ "type": "DELETE_MESSAGE", "payload": { "channel_id": "...", "message_id": "..." } } ``` ### Slash Commands @@ -85,7 +144,7 @@ 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 +GET /api/v1/bots/servers/{id}/commands → [{ "name": "kick", "description": "Kick a user", "bot_name": "Modbot" }] ``` @@ -101,26 +160,3 @@ POST /api/v1/channels/{id}/webhooks 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 3f459f1..054a419 100644 --- a/_Sidebar.md +++ b/_Sidebar.md @@ -7,7 +7,7 @@ - [Profiles](Profiles) - [Voice & Video](Voice-and-Video) - [Phase 3: Polish & PWA](Phase-3) -- [Phase 4: Bots & Extensibility](Phase-4) +- [Bots & Extensibility](Phase-4) - [Phase 5: TUI Client](Phase-5) - [Phase 6: Security & Permissions](Phase-6) - [Frontend Design](Frontend-Design)