@tusile/bot 0.1.1 → 0.2.1

package/README.md

@@ -119,7 +119,7 @@ await i.reply({
     components: [
       { type: 'button', style: 'primary', label: 'Press me', custom_id: 'vote:yes' },
       { type: 'button', style: 'danger', label: 'No', custom_id: 'vote:no' },
-      { type: 'button', style: 'link', label: 'Docs', url: 'https://tusile.com/bots.html' },
+      { type: 'button', style: 'link', label: 'Docs', url: 'https://tusile.com/bots' },
     ],
   }],
 });
@@ -133,8 +133,9 @@ whatever state you need in it: `page:3`, `vote:close:99`. An exactly registered
 a prefix, and the longest matching prefix wins, so a general handler cannot swallow presses
 meant for a specific one.
 
-Button styles are `primary`, `secondary`, `success`, `danger` and `link` (which takes a
-`url` instead of a `custom_id`). A row can hold five buttons, or one select.
+Button styles are `primary`, `secondary`, `danger` and `link` (which takes a `url` instead
+of a `custom_id`). Anything else draws as a plain button rather than not at all. A row can
+hold five buttons, or one select.
 
 ## Forms
 
@@ -173,6 +174,9 @@ bot.command({ name: 'recap', description: 'What was said here' }, async (i) => {
 | `react(id, emoji)`, `unreact(id, emoji)` | reactions |
 | `pin(id)`, `unpin(id)`, `typing(channelId)` | |
 | `channels()`, `createChannel(c)`, `updateChannel(id, c)`, `deleteChannel(id)` | |
+| `categories()`, `createCategory(c)`, `updateCategory(id, c)`, `deleteCategory(id)` | |
+| `channelPermissions(channelId)` | who can do what in one channel |
+| `setChannelPermission(channelId, rule)`, `removeChannelPermission(channelId, id)` | |
 | `roles()`, `createRole(r)`, `updateRole(id, r)`, `deleteRole(id)` | |
 | `members()`, `addRole(userId, roleId)`, `removeRole(userId, roleId)` | |
 | `setNickname(userId, name)` | `'@me'` renames the bot itself |
@@ -188,6 +192,46 @@ endpoint newer than your copy of this package is one line away.
 A call the bot lacks permission for comes back as a `TusileApiError` with `status: 403` and
 a reason, never as silence.
 
+## A bot that sets a server up
+
+Everything a server is made of is reachable, so the first bot most people want to write is
+the one that builds the whole thing from a template:
+
+```js
+import { Bot, Permissions } from '@tusile/bot';
+
+bot.command({ name: 'setup', description: 'Build the standard channels' }, async (i) => {
+  await i.defer();
+  const s = i.server;
+
+  const staff = await s.createRole({ name: 'Staff', permissions: Permissions.view_channel });
+  const team = await s.createCategory({ name: 'Team' });
+
+  const general = await s.createChannel({ name: 'general', type: 'text', category_id: team.id });
+  const private_ = await s.createChannel({ name: 'staff-only', type: 'text', category_id: team.id });
+
+  // The part that makes it a server rather than a pile of channels.
+  const [everyone] = (await s.roles()).filter((r) => r.is_default);
+  await s.setChannelPermission(private_.id, { role: everyone.id, deny: 'view_channel' });
+  await s.setChannelPermission(private_.id, { role: staff.id, allow: 'view_channel' });
+
+  await s.addRole(i.userId, staff.id);
+  await s.send(general.id, 'Set up. #staff-only is for the Staff role.');
+  await i.editReply('Done.');
+});
+```
+
+`allow` and `deny` take a permission name, a list of names, or a number:
+`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
+than quietly denying nothing.
+
+Two rules the server keeps, whatever the bot asks for: it cannot create a role above its
+own, and it cannot allow, in a channel, a permission it does not hold itself. Denying is
+not capped, so a bot locking a channel down does not need every permission it switches off.
+
 ## Events
 
 ```js
@@ -209,6 +253,9 @@ unreachable, so a redeploy does not read as a lost message. A bad request is not
 `server.rateLimit` says what was left on the last call.
 
 A bot removed from a community stops reconnecting to it and keeps every other connection.
+Credentials Core refuses stop it entirely, rather than being retried: a deleted bot or a
+rotated secret will not come right on its own, and a bot asking every thirty seconds until
+somebody notices fills a log and spends rate limit the working bots need.
 
 ## Running it without the Bot class
 
@@ -233,6 +280,6 @@ commands, a custom status line, gateway resume after a drop (it reconnects and r
 instead), and outbound webhooks.
 
 Full reference, including every field of an embed, a component and a command option:
-**https://tusile.com/bots.html**
+**https://tusile.com/bots**
 
 MIT licensed.

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@tusile/bot",
-  "version": "0.1.1",
+  "version": "0.2.1",
   "description": "Write a Tusile bot: slash commands, buttons, forms and voice, over an outbound WebSocket.",
   "type": "module",
   "main": "src/index.js",
@@ -27,7 +27,7 @@
     "chat",
     "slash-commands"
   ],
-  "homepage": "https://tusile.com/bots.html",
+  "homepage": "https://tusile.com/bots",
   "license": "MIT",
   "author": "Tusile"
 }

package/src/bot.js

@@ -137,7 +137,19 @@ export class Bot {
   async sync() {
     if (this.#stopped) return;
     const waitSeconds = this.servers.size === 0 ? JOIN_WAIT_SECONDS : undefined;
-    const servers = await this.#core.servers({ waitSeconds });
+    let servers;
+    try {
+      servers = await this.#core.servers({ waitSeconds });
+    } catch (err) {
+      // Credentials Core refuses will be refused next minute too. Stopping is the honest
+      // answer: a bot that cannot authenticate is not running, and saying so once beats
+      // a 401 a minute for as long as nobody notices.
+      if (err?.isAuthFailure) {
+        this.#report(err);
+        await this.stop();
+      }
+      throw err;
+    }
     if (this.#stopped) return;
 
     const seen = new Set();
@@ -181,6 +193,14 @@ export class Bot {
       },
       onFrame: (frame, client) => this.#onFrame(frame, client),
       onError: (err) => this.#report(err, { serverId }),
+      // A connection that has ended for good stops being this bot's connection to that
+      // community. Leaving it in place would make a community that removed the bot and
+      // added it again unreachable until the process was restarted: the next sync would
+      // see a link already there and skip it, and the bot would sit offline with nothing
+      // in any log to say why.
+      onFinished: () => {
+        if (this.#links.get(serverId) === link) this.#leave(serverId);
+      },
     });
 
     this.#links.set(serverId, link);
@@ -243,11 +263,13 @@ class Link {
   #onError;
   #onReady;
   #onFrame;
+  #onFinished;
   #token = '';
   #backoff = 0;
   #stopped = false;
 
-  constructor({ serverId, apiUrl, raw, core, fetch, sleep, connect, timers, onReady, onFrame, onError }) {
+  constructor({ serverId, apiUrl, raw, core, fetch, sleep, connect, timers, onReady, onFrame,
+    onError, onFinished }) {
     this.serverId = serverId;
     this.apiUrl = apiUrl;
     this.raw = raw;
@@ -256,6 +278,7 @@ class Link {
     this.#onError = onError;
     this.#onReady = onReady;
     this.#onFrame = onFrame;
+    this.#onFinished = onFinished || (() => {});
 
     this.client = new ServerClient({
       apiUrl,
@@ -305,15 +328,23 @@ class Link {
     while (!this.#stopped) {
       const { fatal, reason, wasLive } = await this.#gateway.closed();
       if (reason) this.#onError(new Error(`[${this.serverId}] ${reason}`));
-      if (fatal || this.#stopped) return;
+      if (fatal || this.#stopped) return this.#finish();
       // A connection that was up and then dropped is worth picking straight back up.
       // Carrying the backoff over would leave a bot that reconnects cleanly once an hour
       // eventually waiting half a minute every time, for nothing.
       if (wasLive) this.#backoff = 0;
       this.#backoff = nextBackoff(this.#backoff, RECONNECT_MIN_MS, RECONNECT_MAX_MS);
       await this.#sleep(this.#backoff);
-      if (this.#stopped) return;
+      if (this.#stopped) return this.#finish();
       await this.#open();
     }
+    this.#finish();
+  }
+
+  /** Say, once, that this connection is over and will not come back by itself. */
+  #finish() {
+    const done = this.#onFinished;
+    this.#onFinished = () => {};
+    done();
   }
 }

package/src/errors.js

@@ -25,6 +25,18 @@ export class ApiError extends Error {
     return this.code === 'bot_uninstalled';
   }
 
+  /**
+   * The credentials are wrong, or gone.
+   *
+   * Not something that comes right on its own: a bot deleted while it was running, or a
+   * secret somebody rotated, answers this to every request for the rest of the process's
+   * life. Retrying it on a timer is how one dead bot fills a log and then trips the rate
+   * limiter for the live ones.
+   */
+  get isAuthFailure() {
+    return this.status === 401 || this.status === 403;
+  }
+
   get isRateLimited() {
     return this.status === 429;
   }

package/src/gateway.js

@@ -99,7 +99,14 @@ export class Gateway {
     } catch (err) {
       // Core refusing a token, or a socket that would not even be constructed. Settled as
       // well as thrown: a caller waiting on `closed` would otherwise wait for good.
-      this.#settle({ fatal: err?.isUninstalled === true, reason: String(err?.message || err) });
+      //
+      // Credentials Core refuses are final. The bot was deleted, or its secret was
+      // rotated, and every retry from here is a 401 in somebody's log until the process
+      // is stopped, plus a share of the rate limit the working bots need.
+      this.#settle({
+        fatal: err?.isUninstalled === true || err?.isAuthFailure === true,
+        reason: String(err?.message || err),
+      });
       throw err;
     }
   }
@@ -117,7 +124,11 @@ export class Gateway {
       await this.open();
     } catch (err) {
       // Core refusing to mint a token, usually. Not a reason to give up on the community.
-      return { fatal: err?.isUninstalled === true, reason: String(err?.message || err), wasLive: false };
+      return {
+        fatal: err?.isUninstalled === true || err?.isAuthFailure === true,
+        reason: String(err?.message || err),
+        wasLive: false,
+      };
     }
     return this.closed();
   }

package/src/index.js

@@ -1,26 +1,27 @@
-/**
- * @tusile/bot
- *
- * Everything a Tusile bot needs, in one place. The short version:
- *
- *   import { Bot } from '@tusile/bot';
- *
- *   const bot = new Bot();                       // reads CORE_SERVER_URL, BOT_KEY, BOT_SECRET
- *   bot.command({ name: 'ping', description: 'Check the bot is awake' },
- *               (i) => i.reply('pong'));
- *   await bot.start();
- *
- * That is a working bot on every community that has added it. No inbound port, no public
- * url, no webhook to register: it dials out.
- *
- * The pieces are exported as well, for a bot that wants one without the rest: a script
- * that only posts a message needs a CoreClient and a ServerClient and no gateway at all.
- */
-
-export { Bot } from './bot.js';
-export { CoreClient } from './core.js';
-export { ServerClient } from './rest.js';
-export { Gateway, gatewayUrl, nextBackoff } from './gateway.js';
-export { Dispatcher } from './dispatch.js';
-export { Interaction, ANSWER_WINDOW_MS } from './interaction.js';
-export { ApiError } from './errors.js';
+/**
+ * @tusile/bot
+ *
+ * Everything a Tusile bot needs, in one place. The short version:
+ *
+ *   import { Bot } from '@tusile/bot';
+ *
+ *   const bot = new Bot();                       // reads CORE_SERVER_URL, BOT_KEY, BOT_SECRET
+ *   bot.command({ name: 'ping', description: 'Check the bot is awake' },
+ *               (i) => i.reply('pong'));
+ *   await bot.start();
+ *
+ * That is a working bot on every community that has added it. No inbound port, no public
+ * url, no webhook to register: it dials out.
+ *
+ * The pieces are exported as well, for a bot that wants one without the rest: a script
+ * that only posts a message needs a CoreClient and a ServerClient and no gateway at all.
+ */
+
+export { Bot } from './bot.js';
+export { CoreClient } from './core.js';
+export { ServerClient } from './rest.js';
+export { Gateway, gatewayUrl, nextBackoff } from './gateway.js';
+export { Dispatcher } from './dispatch.js';
+export { Interaction, ANSWER_WINDOW_MS } from './interaction.js';
+export { ApiError } from './errors.js';
+export { Permissions, toMask } from './permissions.js';

package/src/permissions.js

@@ -0,0 +1,55 @@
+/**
+ * The permission bits, by the names the app uses for them.
+ *
+ * A bot deciding who can see a channel otherwise writes `1024` and hopes. These are the
+ * same bits the server checks, so a rule written here is the rule a person would set by
+ * hand in the channel's permissions screen.
+ */
+export const Permissions = {
+  view_channel: 1 << 0,
+  send_messages: 1 << 1,
+  manage_messages: 1 << 2,
+  manage_channels: 1 << 3,
+  manage_roles: 1 << 4,
+  manage_members: 1 << 5,
+  administrator: 1 << 6,
+  connect: 1 << 7,
+  speak: 1 << 8,
+  mute_members: 1 << 9,
+  deafen_members: 1 << 10,
+  manage_server: 1 << 11,
+  create_invite: 1 << 12,
+  attach_files: 1 << 13,
+  stream: 1 << 14,
+  use_camera: 1 << 15,
+  manage_emojis: 1 << 16,
+  manage_emoji_policy: 1 << 17,
+  timeout_members: 1 << 18,
+};
+
+/**
+ * A number, a name, or a list of names, as one mask.
+ *
+ * A name this package has never heard of throws rather than contributing nothing: a
+ * typo in a deny list would otherwise leave a channel open and say nothing about it.
+ */
+export function toMask(value) {
+  if (value === undefined || value === null) return 0;
+  if (typeof value === 'number') return value;
+  const names = Array.isArray(value) ? value : [value];
+  let mask = 0;
+  for (const name of names) {
+    if (typeof name === 'number') {
+      mask |= name;
+      continue;
+    }
+    const bit = Permissions[String(name).toLowerCase()];
+    if (bit === undefined) {
+      throw new Error(
+        `unknown permission "${name}". Known: ${Object.keys(Permissions).join(', ')}`,
+      );
+    }
+    mask |= bit;
+  }
+  return mask;
+}

package/src/rest.js

@@ -1,234 +1,288 @@
-import { Transport, query } from './http.js';
-
-/**
- * One community, and everything a bot can do in it.
- *
- * Every method here is a line and a half over `request`, which is deliberate: the wrapper
- * exists so that a bot author does not have to know that history comes back wrapped in an
- * envelope or that a reaction has to be url-encoded, and `request` stays public so that an
- * endpoint added next month needs no new release of this package.
- *
- * What a bot may actually do is decided by its roles in the community, not here. A call
- * the bot lacks permission for comes back as a 403 with a reason, not as silence.
- */
-export class ServerClient {
-  #transport;
-
-  constructor({ apiUrl, token, serverId = '', fetch, sleep, maxRetries }) {
-    this.serverId = serverId;
-    this.apiUrl = String(apiUrl || '').replace(/\/+$/, '');
-    this.#transport = new Transport({
-      baseUrl: this.apiUrl,
-      authorization: () => `Bearer ${token()}`,
-      fetch,
-      sleep,
-      maxRetries,
-    });
-  }
-
-  /**
-   * Anything at all, with this community's token.
-   *
-   * The escape hatch, and not a second-class one: everything below is written in terms of
-   * it, so a bot reaching an endpoint this package has never heard of is in exactly the
-   * same position as one calling a named method.
-   */
-  request(method, path, body) {
-    return this.#transport.request(method, path, body);
-  }
-
-  /** What the budget looked like a moment ago, for a bot that would rather not find out. */
-  get rateLimit() {
-    return this.#transport.rateLimit;
-  }
-
-  // The community itself.
-
-  serverInfo() {
-    return this.request('GET', '/bot/server');
-  }
-
-  // Messages.
-
-  /** Say something. A string is the common case; an object carries embeds and controls. */
-  send(channelId, message) {
-    return this.request('POST', `/bot/channels/${enc(channelId)}/messages`, contentOf(message));
-  }
-
-  /** Recent messages, newest first. `before` is a message id, for walking backwards. */
-  async history(channelId, { limit, before } = {}) {
-    const page = await this.request(
-      'GET',
-      `/bot/channels/${enc(channelId)}/messages${query({ limit, before })}`,
-    );
-    return page?.messages ?? [];
-  }
-
-  message(messageId) {
-    return this.request('GET', `/bot/messages/${enc(messageId)}`);
-  }
-
-  editMessage(messageId, message) {
-    return this.request('PATCH', `/bot/messages/${enc(messageId)}`, contentOf(message));
-  }
-
-  deleteMessage(messageId) {
-    return this.request('DELETE', `/bot/messages/${enc(messageId)}`);
-  }
-
-  /** Clear several at once, which the server does as one act rather than a flood. */
-  deleteMessages(channelId, messageIds) {
-    return this.request('POST', `/bot/channels/${enc(channelId)}/messages/bulk-delete`, {
-      message_ids: messageIds,
-    });
-  }
-
-  /** The typing dots, for a bot about to take a second or two over a plain message. */
-  typing(channelId) {
-    return this.request('POST', `/bot/channels/${enc(channelId)}/typing`, {});
-  }
-
-  pin(messageId) {
-    return this.request('PUT', `/bot/messages/${enc(messageId)}/pin`);
-  }
-
-  unpin(messageId) {
-    return this.request('DELETE', `/bot/messages/${enc(messageId)}/pin`);
-  }
-
-  react(messageId, emoji) {
-    return this.request('PUT', `/bot/messages/${enc(messageId)}/reactions/${enc(emoji)}`);
-  }
-
-  unreact(messageId, emoji) {
-    return this.request('DELETE', `/bot/messages/${enc(messageId)}/reactions/${enc(emoji)}`);
-  }
-
-  // Channels.
-
-  async channels() {
-    const out = await this.request('GET', '/bot/channels');
-    return out?.channels ?? [];
-  }
-
-  createChannel(channel) {
-    return this.request('POST', '/bot/channels', channel);
-  }
-
-  updateChannel(channelId, changes) {
-    return this.request('PATCH', `/bot/channels/${enc(channelId)}`, changes);
-  }
-
-  deleteChannel(channelId) {
-    return this.request('DELETE', `/bot/channels/${enc(channelId)}`);
-  }
-
-  // Roles.
-
-  async roles() {
-    const out = await this.request('GET', '/bot/roles');
-    return out?.roles ?? [];
-  }
-
-  createRole(role) {
-    return this.request('POST', '/bot/roles', role);
-  }
-
-  updateRole(roleId, changes) {
-    return this.request('PATCH', `/bot/roles/${enc(roleId)}`, changes);
-  }
-
-  deleteRole(roleId) {
-    return this.request('DELETE', `/bot/roles/${enc(roleId)}`);
-  }
-
-  // Members.
-
-  async members() {
-    const out = await this.request('GET', '/bot/members');
-    return out?.members ?? [];
-  }
-
-  addRole(userId, roleId) {
-    return this.request('PUT', `/bot/members/${enc(userId)}/roles/${enc(roleId)}`);
-  }
-
-  removeRole(userId, roleId) {
-    return this.request('DELETE', `/bot/members/${enc(userId)}/roles/${enc(roleId)}`);
-  }
-
-  /** A nickname, or null to put somebody back to their own name. `@me` renames the bot. */
-  setNickname(userId, nickname) {
-    return this.request('PATCH', `/bot/members/${enc(userId)}`, { nickname });
-  }
-
-  // Moderation.
-
-  kick(userId) {
-    return this.request('DELETE', `/bot/members/${enc(userId)}`);
-  }
-
-  /** Silence somebody for a while. Seconds, because "until" invites timezone bugs. */
-  timeout(userId, seconds, reason = '') {
-    return this.request('POST', `/bot/members/${enc(userId)}/timeout`, { seconds, reason });
-  }
-
-  clearTimeout(userId) {
-    return this.request('DELETE', `/bot/members/${enc(userId)}/timeout`);
-  }
-
-  ban(userId, reason = '') {
-    return this.request('POST', '/bot/bans', { user_id: userId, reason });
-  }
-
-  unban(userId) {
-    return this.request('DELETE', `/bot/bans/${enc(userId)}`);
-  }
-
-  async bans() {
-    const out = await this.request('GET', '/bot/bans');
-    return out?.bans ?? [];
-  }
-
-  // Commands.
-
-  async commands() {
-    const out = await this.request('GET', '/bot/commands');
-    return out?.commands ?? [];
-  }
-
-  /** Replace the command list. Whatever is not in it stops being offered. */
-  setCommands(commands) {
-    return this.request('PUT', '/bot/commands', { commands });
-  }
-
-  // Voice.
-
-  /**
-   * Appear in a voice channel.
-   *
-   * This is the presence half, which is what most bots want. Carrying audio needs a
-   * LiveKit client as well (`@livekit/rtc-node`, joining room `channel_<id>` with the
-   * token from `voiceToken`).
-   */
-  joinVoice(channelId) {
-    return this.request('POST', '/bot/voice/join', { channel_id: channelId });
-  }
-
-  leaveVoice(channelId) {
-    return this.request('POST', '/bot/voice/leave', { channel_id: channelId });
-  }
-
-  voiceToken(channelId) {
-    return this.request('POST', '/bot/livekit/token', { room: `channel_${channelId}` });
-  }
-}
-
-/** A string is content; anything else is already a body. */
-function contentOf(message) {
-  return typeof message === 'string' ? { content: message } : message;
-}
-
-function enc(value) {
-  return encodeURIComponent(String(value ?? ''));
-}
+import { Transport, query } from './http.js';
+import { toMask } from './permissions.js';
+
+/**
+ * One community, and everything a bot can do in it.
+ *
+ * Every method here is a line and a half over `request`, which is deliberate: the wrapper
+ * exists so that a bot author does not have to know that history comes back wrapped in an
+ * envelope or that a reaction has to be url-encoded, and `request` stays public so that an
+ * endpoint added next month needs no new release of this package.
+ *
+ * What a bot may actually do is decided by its roles in the community, not here. A call
+ * the bot lacks permission for comes back as a 403 with a reason, not as silence.
+ */
+export class ServerClient {
+  #transport;
+
+  constructor({ apiUrl, token, serverId = '', fetch, sleep, maxRetries }) {
+    this.serverId = serverId;
+    this.apiUrl = String(apiUrl || '').replace(/\/+$/, '');
+    this.#transport = new Transport({
+      baseUrl: this.apiUrl,
+      authorization: () => `Bearer ${token()}`,
+      fetch,
+      sleep,
+      maxRetries,
+    });
+  }
+
+  /**
+   * Anything at all, with this community's token.
+   *
+   * The escape hatch, and not a second-class one: everything below is written in terms of
+   * it, so a bot reaching an endpoint this package has never heard of is in exactly the
+   * same position as one calling a named method.
+   */
+  request(method, path, body) {
+    return this.#transport.request(method, path, body);
+  }
+
+  /** What the budget looked like a moment ago, for a bot that would rather not find out. */
+  get rateLimit() {
+    return this.#transport.rateLimit;
+  }
+
+  // The community itself.
+
+  serverInfo() {
+    return this.request('GET', '/bot/server');
+  }
+
+  // Messages.
+
+  /** Say something. A string is the common case; an object carries embeds and controls. */
+  send(channelId, message) {
+    return this.request('POST', `/bot/channels/${enc(channelId)}/messages`, contentOf(message));
+  }
+
+  /** Recent messages, newest first. `before` is a message id, for walking backwards. */
+  async history(channelId, { limit, before } = {}) {
+    const page = await this.request(
+      'GET',
+      `/bot/channels/${enc(channelId)}/messages${query({ limit, before })}`,
+    );
+    return page?.messages ?? [];
+  }
+
+  message(messageId) {
+    return this.request('GET', `/bot/messages/${enc(messageId)}`);
+  }
+
+  editMessage(messageId, message) {
+    return this.request('PATCH', `/bot/messages/${enc(messageId)}`, contentOf(message));
+  }
+
+  deleteMessage(messageId) {
+    return this.request('DELETE', `/bot/messages/${enc(messageId)}`);
+  }
+
+  /** Clear several at once, which the server does as one act rather than a flood. */
+  deleteMessages(channelId, messageIds) {
+    return this.request('POST', `/bot/channels/${enc(channelId)}/messages/bulk-delete`, {
+      message_ids: messageIds,
+    });
+  }
+
+  /** The typing dots, for a bot about to take a second or two over a plain message. */
+  typing(channelId) {
+    return this.request('POST', `/bot/channels/${enc(channelId)}/typing`, {});
+  }
+
+  pin(messageId) {
+    return this.request('PUT', `/bot/messages/${enc(messageId)}/pin`);
+  }
+
+  unpin(messageId) {
+    return this.request('DELETE', `/bot/messages/${enc(messageId)}/pin`);
+  }
+
+  react(messageId, emoji) {
+    return this.request('PUT', `/bot/messages/${enc(messageId)}/reactions/${enc(emoji)}`);
+  }
+
+  unreact(messageId, emoji) {
+    return this.request('DELETE', `/bot/messages/${enc(messageId)}/reactions/${enc(emoji)}`);
+  }
+
+  // Channels.
+
+  async channels() {
+    const out = await this.request('GET', '/bot/channels');
+    return out?.channels ?? [];
+  }
+
+  createChannel(channel) {
+    return this.request('POST', '/bot/channels', channel);
+  }
+
+  updateChannel(channelId, changes) {
+    return this.request('PATCH', `/bot/channels/${enc(channelId)}`, changes);
+  }
+
+  deleteChannel(channelId) {
+    return this.request('DELETE', `/bot/channels/${enc(channelId)}`);
+  }
+
+  // Categories, which are what turns a pile of channels into a server.
+
+  async categories() {
+    const out = await this.request('GET', '/bot/categories');
+    return out?.categories ?? [];
+  }
+
+  createCategory(category) {
+    return this.request('POST', '/bot/categories', category);
+  }
+
+  updateCategory(categoryId, changes) {
+    return this.request('PATCH', `/bot/categories/${enc(categoryId)}`, changes);
+  }
+
+  /** Removing a category leaves its channels; they come back to the top level. */
+  deleteCategory(categoryId) {
+    return this.request('DELETE', `/bot/categories/${enc(categoryId)}`);
+  }
+
+  // Who can do what in one channel.
+
+  async channelPermissions(channelId) {
+    const out = await this.request('GET', `/bot/channels/${enc(channelId)}/overrides`);
+    return out?.overrides ?? [];
+  }
+
+  /**
+   * Allow or deny permissions in one channel, for a role or one person.
+   *
+   * The call a setup bot is mostly made of: deny `view_channel` to `@everyone` and allow
+   * it to one role, and the channel is that team's. `allow` and `deny` take permission
+   * names as well as numbers.
+   */
+  setChannelPermission(channelId, { role, member, allow, deny } = {}) {
+    if (!role && !member) {
+      return Promise.reject(new Error('a channel permission needs a role or a member to be about'));
+    }
+    return this.request('PUT', `/bot/channels/${enc(channelId)}/overrides`, {
+      target_type: role ? 'role' : 'member',
+      target_id: role || member,
+      allow: toMask(allow),
+      deny: toMask(deny),
+    });
+  }
+
+  removeChannelPermission(channelId, overrideId) {
+    return this.request(
+      'DELETE',
+      `/bot/channels/${enc(channelId)}/overrides/${enc(overrideId)}`,
+    );
+  }
+
+  // Roles.
+
+  async roles() {
+    const out = await this.request('GET', '/bot/roles');
+    return out?.roles ?? [];
+  }
+
+  createRole(role) {
+    return this.request('POST', '/bot/roles', role);
+  }
+
+  updateRole(roleId, changes) {
+    return this.request('PATCH', `/bot/roles/${enc(roleId)}`, changes);
+  }
+
+  deleteRole(roleId) {
+    return this.request('DELETE', `/bot/roles/${enc(roleId)}`);
+  }
+
+  // Members.
+
+  async members() {
+    const out = await this.request('GET', '/bot/members');
+    return out?.members ?? [];
+  }
+
+  addRole(userId, roleId) {
+    return this.request('PUT', `/bot/members/${enc(userId)}/roles/${enc(roleId)}`);
+  }
+
+  removeRole(userId, roleId) {
+    return this.request('DELETE', `/bot/members/${enc(userId)}/roles/${enc(roleId)}`);
+  }
+
+  /** A nickname, or null to put somebody back to their own name. `@me` renames the bot. */
+  setNickname(userId, nickname) {
+    return this.request('PATCH', `/bot/members/${enc(userId)}`, { nickname });
+  }
+
+  // Moderation.
+
+  kick(userId) {
+    return this.request('DELETE', `/bot/members/${enc(userId)}`);
+  }
+
+  /** Silence somebody for a while. Seconds, because "until" invites timezone bugs. */
+  timeout(userId, seconds, reason = '') {
+    return this.request('POST', `/bot/members/${enc(userId)}/timeout`, { seconds, reason });
+  }
+
+  clearTimeout(userId) {
+    return this.request('DELETE', `/bot/members/${enc(userId)}/timeout`);
+  }
+
+  ban(userId, reason = '') {
+    return this.request('POST', '/bot/bans', { user_id: userId, reason });
+  }
+
+  unban(userId) {
+    return this.request('DELETE', `/bot/bans/${enc(userId)}`);
+  }
+
+  async bans() {
+    const out = await this.request('GET', '/bot/bans');
+    return out?.bans ?? [];
+  }
+
+  // Commands.
+
+  async commands() {
+    const out = await this.request('GET', '/bot/commands');
+    return out?.commands ?? [];
+  }
+
+  /** Replace the command list. Whatever is not in it stops being offered. */
+  setCommands(commands) {
+    return this.request('PUT', '/bot/commands', { commands });
+  }
+
+  // Voice.
+
+  /**
+   * Appear in a voice channel.
+   *
+   * This is the presence half, which is what most bots want. Carrying audio needs a
+   * LiveKit client as well (`@livekit/rtc-node`, joining room `channel_<id>` with the
+   * token from `voiceToken`).
+   */
+  joinVoice(channelId) {
+    return this.request('POST', '/bot/voice/join', { channel_id: channelId });
+  }
+
+  leaveVoice(channelId) {
+    return this.request('POST', '/bot/voice/leave', { channel_id: channelId });
+  }
+
+  voiceToken(channelId) {
+    return this.request('POST', '/bot/livekit/token', { room: `channel_${channelId}` });
+  }
+}
+
+/** A string is content; anything else is already a body. */
+function contentOf(message) {
+  return typeof message === 'string' ? { content: message } : message;
+}
+
+function enc(value) {
+  return encodeURIComponent(String(value ?? ''));
+}