Add slash command subcommand support in API and picker (#5403)

Author: ancsemi

CHANGELOG.md

@@ -34,6 +34,7 @@ Format follows [Keep a Changelog](https://keepachangelog.com/). Haven uses [Sema
 
 ### Fixed
 - **Blank login page / blank app shell after updating directly from v3.18.0 (#5399).** Two SyntaxErrors had been quietly sitting in `main` since the v3.19.0 Guest mode merge (`b6b95bd`): a duplicate `const loginForm` redeclaration in `auth.js`, and an orphan `_setupServerBar() {` opener with no body in `app-ui.js` (a half-merged method definition that was never closed). Anyone already running v3.19.x kept working because their cached/loaded modules survived the crash on initial parse, but users updating directly from v3.18.0 — the prior version many self-hosters were sitting on — hit both errors on first load and got a blank login page followed by a blank app. Mistakenly attributed to the v3.20.1 STUN refresh at first; that work is unaffected.
+- **Bot slash command registration now supports discoverable subcommands in autocomplete (#5403).** `POST /api/webhooks/:token/commands` accepts an optional `subcommands` array (`{ name, description }`), persists it per command, and `/api/bot-commands` now flattens those into picker entries like `/rss add` with per-subcommand descriptions. Callback payload format remains unchanged (`command` is base command, `args` carries the subcommand text and arguments).
 - **`/api/ice-servers` was still returning dead STUN URLs (#5399 followup).** The server-side default in `/api/ice-servers` was still handing out `stun.stunprotocol.org` + `stun.nextcloud.com` — the same pair the v3.20.1 client fix had to route around. Any Haven server using the server-side STUN defaults was giving its clients dead endpoints and only working at all because `voice.js` had been updated to ignore them. Mirrored the same Cloudflare/Metered/Twilio/Google fallback list on the server so the two sides stay in sync.
 - **Right-click → Copy image silently failed for almost everyone, on both static images and GIFs.** Two compounding causes: the previous implementation awaited an `Image()` load + `canvas.toBlob` before calling `navigator.clipboard.write`, by which point the user-gesture token had been dropped and Chromium silently rejected the write with `NotAllowedError`; on top of that, Electron's renderer added enough latency around fetch+decode that even a corrected promise-based path was unreliable. Rewrote with three strategies tried in order: under Haven Desktop, hand the PNG bytes to the main process via a new `clipboard:write-image` IPC (Electron's `clipboard.writeImage` has no gesture restrictions); otherwise call `navigator.clipboard.write` with a promise-based `ClipboardItem` so the gesture token is preserved; last-ditch, copy the image URL as text so the user has something to paste. Failure toasts now include the underlying error message so diagnosing future regressions doesn't require devtools.
 - **Image and member context menus appeared offscreen on top of the image lightbox or PiP DM.** Both `.image-context-menu` and `.user-context-menu` sat at `z-index: 10001`, which left them buried under the image lightbox (`100010`) and the PiP DM panel (`99999`). Right-clicking an enlarged image or a member while a PiP DM was open made the menu look like it vanished. Bumped both to `100020`.

GUIDE.md

@@ -809,6 +809,27 @@ Content-Type: application/json
 }
 ```
 
+Optional subcommands can be included to improve autocomplete discoverability:
+
+```
+POST https://your-server.com/api/webhooks/<token>/commands
+Content-Type: application/json
+
+{
+  "command": "rss",
+  "description": "Manage RSS feeds",
+  "subcommands": [
+    { "name": "add", "description": "Add an RSS feed" },
+    { "name": "remove", "description": "Remove an RSS feed" },
+    { "name": "list", "description": "List active feeds" }
+  ]
+}
+```
+
+The callback payload format is unchanged. Haven still sends `command` as the
+base command (`rss`) and the full remaining text in `args` (for example
+`"add https://example.com/feed.xml"`).
+
 **List:**
 ```
 GET https://your-server.com/api/webhooks/<token>/commands

public/js/modules/app-admin.js

@@ -1991,9 +1991,25 @@ _checkSlashTrigger(inputEl) {
   this._slashInput = input;
   const text = input.value;
 
-  // Only activate if text starts with / and cursor is in the first word
-  if (text.startsWith('/') && !text.includes(' ') && text.length < 25) {
-    const query = text.substring(1).toLowerCase();
+  // Show slash suggestions while typing the command token, or a single
+  // subcommand token (e.g. "/rss ad"). Hide once argument typing starts.
+  if (text.startsWith('/') && text.length < 80) {
+    const raw = text.substring(1);
+    const trimmed = raw.trim();
+    let query = '';
+    if (!trimmed) {
+      query = '';
+    } else {
+      const parts = trimmed.split(/\s+/);
+      if (parts.length === 1) {
+        query = parts[0].toLowerCase();
+      } else if (parts.length === 2 && !raw.endsWith(' ')) {
+        query = `${parts[0].toLowerCase()} ${parts[1].toLowerCase()}`;
+      } else {
+        this._hideSlashDropdown();
+        return;
+      }
+    }
     this._showSlashDropdown(query);
   } else {
     this._hideSlashDropdown();

server.js

@@ -3007,7 +3007,22 @@ app.get('/api/webhooks/:token/commands', webhookLimiter, (req, res) => {
   if (!webhook) return res.status(404).json({ error: 'Webhook not found or inactive' });
 
   const { getDb } = require('./src/database');
-  const commands = getDb().prepare('SELECT id, command, description FROM bot_commands WHERE webhook_id = ?').all(webhook.id);
+  const rows = getDb().prepare('SELECT id, command, description, subcommands_json FROM bot_commands WHERE webhook_id = ?').all(webhook.id);
+  const commands = rows.map(r => {
+    let subcommands = [];
+    if (r.subcommands_json) {
+      try {
+        const parsed = JSON.parse(r.subcommands_json);
+        if (Array.isArray(parsed)) subcommands = parsed;
+      } catch { /* ignore malformed historic values */ }
+    }
+    return {
+      id: r.id,
+      command: r.command,
+      description: r.description,
+      subcommands
+    };
+  });
   res.json({ commands });
 });
 
@@ -3017,7 +3032,7 @@ app.post('/api/webhooks/:token/commands', webhookLimiter, express.json({ limit:
   if (!webhook) return res.status(404).json({ error: 'Webhook not found or inactive' });
   if (!webhook.callback_url) return res.status(400).json({ error: 'Webhook must have a callback_url to register commands' });
 
-  const { command, description } = req.body;
+  const { command, description, subcommands } = req.body;
   if (!command || typeof command !== 'string') return res.status(400).json({ error: 'command required (string)' });
 
   const cmd = command.toLowerCase().replace(/[^a-z0-9]/g, '').slice(0, 32);
@@ -3028,11 +3043,33 @@ app.post('/api/webhooks/:token/commands', webhookLimiter, express.json({ limit:
   if (builtIn.includes(cmd)) return res.status(409).json({ error: `/${cmd} is a built-in command` });
 
   const desc = typeof description === 'string' ? description.trim().slice(0, 100) : '';
+  let cleanSubs = [];
+  if (Array.isArray(subcommands)) {
+    if (subcommands.length > 25) {
+      return res.status(400).json({ error: 'subcommands can contain at most 25 items' });
+    }
+    cleanSubs = subcommands
+      .map(sc => {
+        if (!sc || typeof sc !== 'object') return null;
+        const name = String(sc.name || '').toLowerCase().replace(/[^a-z0-9]/g, '').slice(0, 32);
+        if (!name) return null;
+        const description = typeof sc.description === 'string' ? sc.description.trim().slice(0, 100) : '';
+        return { name, description };
+      })
+      .filter(Boolean);
+    const seen = new Set();
+    cleanSubs = cleanSubs.filter(sc => {
+      if (seen.has(sc.name)) return false;
+      seen.add(sc.name);
+      return true;
+    });
+  }
+  const subcommandsJson = cleanSubs.length ? JSON.stringify(cleanSubs) : null;
 
   const { getDb } = require('./src/database');
   try {
-    getDb().prepare('INSERT OR REPLACE INTO bot_commands (webhook_id, command, description) VALUES (?, ?, ?)').run(webhook.id, cmd, desc);
-    res.json({ success: true, command: cmd, description: desc });
+    getDb().prepare('INSERT OR REPLACE INTO bot_commands (webhook_id, command, description, subcommands_json) VALUES (?, ?, ?, ?)').run(webhook.id, cmd, desc, subcommandsJson);
+    res.json({ success: true, command: cmd, description: desc, subcommands: cleanSubs });
   } catch (err) {
     res.status(500).json({ error: 'Failed to register command' });
   }
@@ -3055,12 +3092,41 @@ app.delete('/api/webhooks/:token/commands/:command', webhookLimiter, (req, res)
 // GET /api/bot-commands — list all registered bot commands (for client autocomplete)
 app.get('/api/bot-commands', (req, res) => {
   const { getDb } = require('./src/database');
-  const commands = getDb().prepare(`
-    SELECT bc.command, bc.description, w.name as bot_name
+  const rows = getDb().prepare(`
+    SELECT bc.command, bc.description, bc.subcommands_json, w.name as bot_name
     FROM bot_commands bc
     JOIN webhooks w ON bc.webhook_id = w.id
     WHERE w.is_active = 1
   `).all();
+  const commands = [];
+  for (const row of rows) {
+    let subcommands = [];
+    if (row.subcommands_json) {
+      try {
+        const parsed = JSON.parse(row.subcommands_json);
+        if (Array.isArray(parsed)) subcommands = parsed;
+      } catch { /* ignore malformed historic values */ }
+    }
+    if (subcommands.length) {
+      for (const sc of subcommands) {
+        const subName = String(sc?.name || '').toLowerCase().replace(/[^a-z0-9]/g, '').slice(0, 32);
+        if (!subName) continue;
+        commands.push({
+          command: `${row.command} ${subName}`,
+          description: typeof sc.description === 'string' && sc.description.trim()
+            ? sc.description.trim()
+            : (row.description || 'Bot command'),
+          bot_name: row.bot_name || 'Bot'
+        });
+      }
+      continue;
+    }
+    commands.push({
+      command: row.command,
+      description: row.description || '',
+      bot_name: row.bot_name || 'Bot'
+    });
+  }
   res.json({ commands });
 });
 

src/database.js

@@ -1019,13 +1019,20 @@ function initDatabase() {
       webhook_id INTEGER NOT NULL REFERENCES webhooks(id) ON DELETE CASCADE,
       command TEXT NOT NULL,
       description TEXT DEFAULT '',
+      subcommands_json TEXT DEFAULT NULL,
       created_at DATETIME DEFAULT CURRENT_TIMESTAMP,
       UNIQUE(webhook_id, command)
     );
     CREATE INDEX IF NOT EXISTS idx_bot_commands_command ON bot_commands(command);
     CREATE INDEX IF NOT EXISTS idx_bot_commands_webhook ON bot_commands(webhook_id);
   `);
 
+  try {
+    db.prepare('SELECT subcommands_json FROM bot_commands LIMIT 0').get();
+  } catch {
+    db.exec('ALTER TABLE bot_commands ADD COLUMN subcommands_json TEXT DEFAULT NULL');
+  }
+
   // ── Migration: chat threads (thread_id on messages) ─────
   try {
     db.prepare("SELECT thread_id FROM messages LIMIT 0").get();