From 0f99e7914b928c3a6f8940b1381ca4f33f063f8c Mon Sep 17 00:00:00 2001 From: cottongin Date: Thu, 12 Mar 2026 08:26:16 -0400 Subject: [PATCH] docs: add IRC commands/plugin setup to README, update WebSocket docs MIME-Version: 1.0 Content-Type: text/plain; charset=UTF-8 Content-Transfer-Encoding: 8bit README was missing IRC command reference, plugin installation/config guidance, and referenced nonexistent plugin READMEs. The WebSocket docs in api.md were stale — subscribe message now documents role and client_id fields, status message now includes the clients array. Made-with: Cursor --- README.md | 53 +++++++++++++++++++++++++++++++++++++++++++++++++++-- docs/api.md | 33 +++++++++++++++++++++++++++++++-- 2 files changed, 82 insertions(+), 4 deletions(-) diff --git a/README.md b/README.md index 75a8636..1e8304e 100644 --- a/README.md +++ b/README.md @@ -78,8 +78,57 @@ Enable by setting these environment variables: | `NTR_WEB_PASSWORD` | *(required)* | Dashboard login password | | `NTR_SECRET_KEY` | *(required)* | Secret key for cookie signing | -Bot plugins (Sopel and Limnoria) connect to the API's WebSocket endpoint -to receive announcements. See plugin READMEs for configuration. +## IRC Commands + +Both Sopel and Limnoria plugins expose the same commands: + +| Command | Description | +|---------|-------------| +| `!1`, `!2`, ... `!N` | Track by position in the current week's playlist | +| `!song ` | Track from a specific episode's playlist | +| `!playlist [episode]` | Current week's playlist, or a specific episode | +| `!lastshow ` | Track from the previous week's show | +| `!status` | API health, poller status, and track count | +| `!refresh` | Trigger a manual SoundCloud fetch (admin only) | + +## IRC Plugin Setup + +Both plugins require the `websocket-client` package for live announcements: + +```bash +pip install websocket-client +``` + +### Sopel + +Copy `plugins/sopel/ntr_playlist.py` into your Sopel plugins directory +(typically `~/.sopel/plugins/`). Add a `[ntr_playlist]` section to your +Sopel config: + +| Setting | Default | Description | +|---------|---------|-------------| +| `api_base_url` | `http://127.0.0.1:8000` | NtR API base URL | +| `admin_token` | *(empty)* | Bearer token for admin commands | +| `admin_nicks` | *(empty)* | Comma-separated list of admin nicknames | +| `display_timezone` | `America/New_York` | Timezone for displayed timestamps | +| `ws_url` | `ws://127.0.0.1:8000/ws/announce` | WebSocket endpoint for announcements | +| `announce_channel` | `#sewerchat` | Channel to send announcements to | +| `client_id` | `sopel` | Identifier for this bot in status messages | + +### Limnoria + +Copy the `plugins/limnoria/NtrPlaylist/` directory into your Limnoria bot's +plugins folder. Configure via the Limnoria registry: + +| Registry Value | Default | Description | +|----------------|---------|-------------| +| `apiBaseUrl` | `http://127.0.0.1:8000` | NtR API base URL | +| `adminToken` | *(empty)* | Bearer token for admin commands | +| `adminNicks` | *(empty)* | Space-separated list of admin nicknames | +| `displayTimezone` | `America/New_York` | Timezone for displayed timestamps | +| `wsUrl` | `ws://127.0.0.1:8000/ws/announce` | WebSocket endpoint for announcements | +| `announceChannel` | `#sewerchat` | Channel to send announcements to | +| `clientId` | `limnoria` | Identifier for this bot in status messages | ## Development diff --git a/docs/api.md b/docs/api.md index c0c8bfb..6f69cb9 100644 --- a/docs/api.md +++ b/docs/api.md @@ -412,23 +412,52 @@ WebSocket endpoint for receiving announce broadcasts. Used by IRC bot plugins. After connecting, send a subscribe message: ```json -{"type": "subscribe", "token": ""} +{ + "type": "subscribe", + "token": "", + "role": "bot", + "client_id": "limnoria" +} ``` +| Field | Type | Required | Description | +|-------|------|----------|-------------| +| `type` | string | yes | Must be `"subscribe"` | +| `token` | string | yes | `NTR_ADMIN_TOKEN` value | +| `role` | string | no | Client role, defaults to `"bot"` | +| `client_id` | string | no | Identifier for this client (e.g. `"sopel"`, `"limnoria"`) | + Invalid token closes the connection with code `4001`. **Messages from server** Announce broadcast: + ```json {"type": "announce", "message": "Now Playing: Song #1: Title by Artist - URL"} ``` Status update (sent on subscriber connect/disconnect): + ```json -{"type": "status", "subscribers": 2} +{ + "type": "status", + "subscribers": 2, + "clients": [ + { + "client_id": "limnoria", + "remote_addr": "1.2.3.4", + "connected_at": "2026-03-12T02:00:00+00:00" + } + ] +} ``` +| Field | Type | Description | +|-------|------|-------------| +| `subscribers` | integer | Number of connected bot clients | +| `clients` | array | List of connected bot clients with their `client_id`, `remote_addr`, and `connected_at` timestamp | + --- ## Dashboard Configuration