@tusile/bot 0.5.0 → 0.7.0

package/README.md

@@ -93,6 +93,8 @@ app before the bot is ever asked anything.
 
 The command list is registered on every connect, so a redeploy with a changed set takes
 effect immediately and a bot added to a community while it was down still registers.
+Since 0.6.0 the same list is also sent to Core, so the bot directory shows your commands to
+somebody deciding whether to add the bot.
 
 **Who may run it.** A command that acts on the server rather than answering a question can
 say what the person running it must hold:
@@ -305,7 +307,7 @@ bot.command({ name: 'setup', description: 'Build the standard channels' }, async
 `view_channel`, `send_messages`, `manage_messages`, `manage_channels`, `manage_roles`,
 `manage_members`, `administrator`, `connect`, `speak`, `mute_members`, `deafen_members`,
 `manage_server`, `create_invite`, `attach_files`, `stream`, `use_camera`, `manage_emojis`,
-`manage_emoji_policy`, `timeout_members`. A name this package does not know throws, rather
+`manage_emoji_policy`, `timeout_members`, `use_soundboard`, `manage_soundboard`. A name this package does not know throws, rather
 than quietly denying nothing.
 
 Two rules the server keeps, whatever the bot asks for: it cannot create a role above its

package/package.json

@@ -1,33 +1,33 @@
-{
-  "name": "@tusile/bot",
-  "version": "0.5.0",
-  "description": "Write a Tusile bot: slash commands, buttons, forms and voice, over an outbound WebSocket.",
-  "type": "module",
-  "main": "src/index.js",
-  "exports": {
-    ".": "./src/index.js"
-  },
-  "files": [
-    "src",
-    "README.md",
-    "LICENSE"
-  ],
-  "engines": {
-    "node": ">=20"
-  },
-  "scripts": {
-    "test": "node --test"
-  },
-  "dependencies": {
-    "ws": "^8.18.0"
-  },
-  "keywords": [
-    "tusile",
-    "bot",
-    "chat",
-    "slash-commands"
-  ],
-  "homepage": "https://tusile.com/bots",
-  "license": "MIT",
-  "author": "Tusile"
-}
+{
+  "name": "@tusile/bot",
+  "version": "0.7.0",
+  "description": "Write a Tusile bot: slash commands, buttons, forms and voice, over an outbound WebSocket.",
+  "type": "module",
+  "main": "src/index.js",
+  "exports": {
+    ".": "./src/index.js"
+  },
+  "files": [
+    "src",
+    "README.md",
+    "LICENSE"
+  ],
+  "engines": {
+    "node": ">=20"
+  },
+  "scripts": {
+    "test": "node --test"
+  },
+  "dependencies": {
+    "ws": "^8.18.0"
+  },
+  "keywords": [
+    "tusile",
+    "bot",
+    "chat",
+    "slash-commands"
+  ],
+  "homepage": "https://tusile.com/bots",
+  "license": "MIT",
+  "author": "Tusile"
+}

package/src/bot.js

@@ -98,6 +98,10 @@ export class Bot {
   #stopped = false;
   #declared;
   #declaredOk = false;
+  // The command list Core last accepted for the directory, as JSON, so it is sent again only
+  // when it changes. Its own tries, so a Core without the route cannot use up the permissions'.
+  #publishedCommands = null;
+  #publishTries = 0;
   #declareTries = 0;
   #watching = null;
   #pollBackoff = 0;
@@ -235,6 +239,43 @@ export class Bot {
    * of, and refusing to run without it would be worse than running without it.
    */
   async #declare() {
+    // Each step is awaited only when it has something to send, so a pass with nothing to say
+    // costs the loop no extra turns before its next request.
+    if (this.#commandsToPublish() !== null) await this.#publishCommands();
+    if (this.#declared !== null && !this.#declaredOk && this.#declareTries < DECLARE_TRIES) {
+      await this.#declarePermissions();
+    }
+  }
+
+  /** The command list as JSON when Core has not yet taken it, else null. */
+  #commandsToPublish() {
+    if (this.#publishTries >= DECLARE_TRIES) return null;
+    const json = JSON.stringify(this.#dispatcher.definitions());
+    return json === this.#publishedCommands ? null : json;
+  }
+
+  /**
+   * Tell Core what commands this bot offers, for the bot directory.
+   *
+   * Without it the directory could show a name and a line and nothing else, and the only way
+   * to find out what a bot does was to add it somewhere. Sent again whenever the list differs
+   * from the one Core last took, and retried like the declaration below. Never fatal: a Core
+   * that predates the route answers 404, and the bot runs the same either way.
+   */
+  async #publishCommands() {
+    const json = this.#commandsToPublish();
+    if (json === null) return;
+    this.#publishTries += 1;
+    try {
+      await this.#core.publishCommands(JSON.parse(json));
+      this.#publishedCommands = json;
+      this.#publishTries = 0;
+    } catch (err) {
+      if (this.#publishTries >= DECLARE_TRIES) this.#report(err);
+    }
+  }
+
+  async #declarePermissions() {
     // Nothing to say, or already said. A bot that declares nothing must not overwrite what its
     // author ticked in the app with an empty list.
     if (this.#declared === null || this.#declaredOk) return;

package/src/core.js

@@ -108,6 +108,19 @@ export class CoreClient {
     });
   }
 
+  /**
+   * Tell Core what commands this bot offers, so the bot directory can show them to somebody
+   * deciding whether to add it.
+   *
+   * The same definitions every community gets. Core keeps only names, descriptions and option
+   * schemas for display; the copy each community holds is still the one that is run.
+   */
+  publishCommands(definitions) {
+    return this.#transport.request('PUT', '/bots/me/commands', {
+      commands: definitions,
+    });
+  }
+
   /**
    * A token for one community.
    *

package/src/permissions.js

@@ -25,6 +25,8 @@ export const Permissions = {
   manage_emojis: 1 << 16,
   manage_emoji_policy: 1 << 17,
   timeout_members: 1 << 18,
+  use_soundboard: 1 << 19,
+  manage_soundboard: 1 << 20,
 };
 
 /**