@tusile/bot 0.4.0 → 0.5.0

package/src/rest.js

@@ -1,414 +1,414 @@
-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.
- */
-/** How long a member list is good for. Roles do not change between two commands in a breath. */
-const MEMBER_TTL_MS = 60 * 1000;
-
-export class ServerClient {
-  #transport;
-  #members = null;
-  #membersAt = 0;
-  #memberTtlMs;
-
-  constructor({
-    apiUrl,
-    token,
-    refreshToken,
-    serverId = '',
-    fetch,
-    sleep,
-    maxRetries,
-    memberTtlMs = MEMBER_TTL_MS,
-  }) {
-    this.serverId = serverId;
-    this.apiUrl = String(apiUrl || '').replace(/\/+$/, '');
-    this.#transport = new Transport({
-      baseUrl: this.apiUrl,
-      authorization: () => `Bearer ${token()}`,
-      // Nothing about a token says when it stops working, and asking Core for a fresh one on a
-      // timer means guessing at a clock somebody else owns. The refusal is the signal.
-      onRefused: refreshToken
-        ? async () => {
-            await refreshToken();
-            return true;
-          }
-        : undefined,
-      fetch,
-      sleep,
-      maxRetries,
-    });
-    this.#memberTtlMs = memberTtlMs;
-  }
-
-  /**
-   * 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`, {});
-  }
-
-  /**
-   * Say "working on it" until the answer is ready. Returns the function that stops it.
-   *
-   * One POST is not enough. The client drops somebody from the line three seconds after
-   * their last one, and a model call runs longer than that, so a bot that posted once
-   * showed the dots, lost them, and then answered into a channel that had gone quiet.
-   *
-   * Nothing here can stop an answer. A community that refuses the indicator, or a request
-   * that times out, is swallowed: saying you are working is worth nothing next to the
-   * sentence itself, and the caller is in the middle of producing it.
-   *
-   *     const done = bot.rest(serverId).thinking(channelId);
-   *     try { await say(await model(question)); } finally { done(); }
-   */
-  thinking(channelId, { everyMs = 2000, setTimer = setTimeout, clearTimer = clearTimeout } = {}) {
-    let stopped = false;
-    let timer = null;
-    const beat = () => {
-      if (stopped) return;
-      Promise.resolve(this.typing(channelId)).catch(() => {});
-      timer = setTimer(beat, everyMs);
-    };
-    beat();
-    // Idempotent, because the caller stops it from a finally block and an error path will
-    // reach that twice often enough.
-    return () => {
-      if (stopped) return;
-      stopped = true;
-      if (timer !== null) clearTimer(timer);
-    };
-  }
-
-  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 ?? [];
-  }
-
-  /**
-   * One member, with the roles that say what they may do.
-   *
-   * There is no route for one member: GET /bot/members is the whole community, and it is
-   * rate limited on a box shared by hundreds of them. A bot that checks a permission before
-   * every command would otherwise re-read every member each time. So the list is held for a
-   * minute, which is shorter than anybody's patience and longer than a burst of commands.
-   *
-   * **The held copy carries roles, so it carries permissions, and a role taken away a minute
-   * ago is still in it.** That cannot grant anybody anything: the community server checks
-   * every action against the real roles and refuses it regardless. What it can do is let a
-   * bot offer somebody a thing the server will then refuse, or act on its own judgement
-   * where the bot is the only judge, which is most of what a moderation bot does. Pass
-   * `{ fresh: true }` when the answer is a decision rather than a label, and take the extra
-   * call: a fresh read also replaces the held copy, so the next caller is not handed the
-   * stale one back.
-   *
-   * Null for somebody who is not here. A failed read is not held, so a community that could
-   * not be read during a deploy is not remembered as empty.
-   */
-  async member(userId, { fresh = false } = {}) {
-    if (fresh || !this.#members || this.#membersAt <= Date.now() - this.#memberTtlMs) {
-      const list = await this.members();
-      this.#members = list;
-      this.#membersAt = Date.now();
-    }
-    const id = String(userId ?? '');
-    return this.#members.find((m) => m.user_id === id) ?? null;
-  }
-
-  /**
-   * Forget the held member list.
-   *
-   * For the one case where a minute of staleness is a bug rather than a saving: a bot that
-   * has just granted a role and wants to read the member back.
-   */
-  forgetMembers() {
-    this.#members = null;
-    this.#membersAt = 0;
-  }
-
-  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. */
-  /**
-   * Register this bot's commands with one community, and say what it needs while it is here.
-   *
-   * `requestedPermissions` is the bot's own declaration, sent again on every connect because
-   * this is the one message a bot sends every community every time. A community copies the
-   * declaration from Core when somebody adds the bot and never again, so without this a bot
-   * that had declared nothing at that moment offered nothing to tick for the life of that
-   * install. It changes nothing about what the bot holds: asking is not having.
-   */
-  setCommands(commands, { requestedPermissions } = {}) {
-    return this.request('PUT', '/bot/commands', {
-      commands,
-      ...(requestedPermissions === undefined || requestedPermissions === null
-        ? {}
-        : { requested_permissions: requestedPermissions }),
-    });
-  }
-
-  // Voice.
-
-  /**
-   * Appear in a voice channel.
-   *
-   * `speaking` is what everybody else is shown. Mic state reaches the server over a
-   * person's websocket and a bot has none, so a bot that does not say this is drawn with
-   * the crossed-out microphone: right for a bot that only listens, wrong and confusing
-   * for one that is about to play something.
-   *
-   * Presence is this one call. Carrying audio needs a media client as well
-   * (`@livekit/rtc-node`, connecting to `voiceToken(channelId)` and publishing a track).
-   */
-  joinVoice(channelId, { speaking = false } = {}) {
-    return this.request('POST', '/bot/voice/join', {
-      channel_id: channelId,
-      mic_enabled: speaking,
-    });
-  }
-
-  /** Change what the channel shows: done playing, or about to start. */
-  setVoiceState(channelId, { speaking = false } = {}) {
-    return this.request('POST', '/bot/voice/state', {
-      channel_id: channelId,
-      mic_enabled: speaking,
-    });
-  }
-
-  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.
+ */
+/** How long a member list is good for. Roles do not change between two commands in a breath. */
+const MEMBER_TTL_MS = 60 * 1000;
+
+export class ServerClient {
+  #transport;
+  #members = null;
+  #membersAt = 0;
+  #memberTtlMs;
+
+  constructor({
+    apiUrl,
+    token,
+    refreshToken,
+    serverId = '',
+    fetch,
+    sleep,
+    maxRetries,
+    memberTtlMs = MEMBER_TTL_MS,
+  }) {
+    this.serverId = serverId;
+    this.apiUrl = String(apiUrl || '').replace(/\/+$/, '');
+    this.#transport = new Transport({
+      baseUrl: this.apiUrl,
+      authorization: () => `Bearer ${token()}`,
+      // Nothing about a token says when it stops working, and asking Core for a fresh one on a
+      // timer means guessing at a clock somebody else owns. The refusal is the signal.
+      onRefused: refreshToken
+        ? async () => {
+            await refreshToken();
+            return true;
+          }
+        : undefined,
+      fetch,
+      sleep,
+      maxRetries,
+    });
+    this.#memberTtlMs = memberTtlMs;
+  }
+
+  /**
+   * 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`, {});
+  }
+
+  /**
+   * Say "working on it" until the answer is ready. Returns the function that stops it.
+   *
+   * One POST is not enough. The client drops somebody from the line three seconds after
+   * their last one, and a model call runs longer than that, so a bot that posted once
+   * showed the dots, lost them, and then answered into a channel that had gone quiet.
+   *
+   * Nothing here can stop an answer. A community that refuses the indicator, or a request
+   * that times out, is swallowed: saying you are working is worth nothing next to the
+   * sentence itself, and the caller is in the middle of producing it.
+   *
+   *     const done = bot.rest(serverId).thinking(channelId);
+   *     try { await say(await model(question)); } finally { done(); }
+   */
+  thinking(channelId, { everyMs = 2000, setTimer = setTimeout, clearTimer = clearTimeout } = {}) {
+    let stopped = false;
+    let timer = null;
+    const beat = () => {
+      if (stopped) return;
+      Promise.resolve(this.typing(channelId)).catch(() => {});
+      timer = setTimer(beat, everyMs);
+    };
+    beat();
+    // Idempotent, because the caller stops it from a finally block and an error path will
+    // reach that twice often enough.
+    return () => {
+      if (stopped) return;
+      stopped = true;
+      if (timer !== null) clearTimer(timer);
+    };
+  }
+
+  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 ?? [];
+  }
+
+  /**
+   * One member, with the roles that say what they may do.
+   *
+   * There is no route for one member: GET /bot/members is the whole community, and it is
+   * rate limited on a box shared by hundreds of them. A bot that checks a permission before
+   * every command would otherwise re-read every member each time. So the list is held for a
+   * minute, which is shorter than anybody's patience and longer than a burst of commands.
+   *
+   * **The held copy carries roles, so it carries permissions, and a role taken away a minute
+   * ago is still in it.** That cannot grant anybody anything: the community server checks
+   * every action against the real roles and refuses it regardless. What it can do is let a
+   * bot offer somebody a thing the server will then refuse, or act on its own judgement
+   * where the bot is the only judge, which is most of what a moderation bot does. Pass
+   * `{ fresh: true }` when the answer is a decision rather than a label, and take the extra
+   * call: a fresh read also replaces the held copy, so the next caller is not handed the
+   * stale one back.
+   *
+   * Null for somebody who is not here. A failed read is not held, so a community that could
+   * not be read during a deploy is not remembered as empty.
+   */
+  async member(userId, { fresh = false } = {}) {
+    if (fresh || !this.#members || this.#membersAt <= Date.now() - this.#memberTtlMs) {
+      const list = await this.members();
+      this.#members = list;
+      this.#membersAt = Date.now();
+    }
+    const id = String(userId ?? '');
+    return this.#members.find((m) => m.user_id === id) ?? null;
+  }
+
+  /**
+   * Forget the held member list.
+   *
+   * For the one case where a minute of staleness is a bug rather than a saving: a bot that
+   * has just granted a role and wants to read the member back.
+   */
+  forgetMembers() {
+    this.#members = null;
+    this.#membersAt = 0;
+  }
+
+  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. */
+  /**
+   * Register this bot's commands with one community, and say what it needs while it is here.
+   *
+   * `requestedPermissions` is the bot's own declaration, sent again on every connect because
+   * this is the one message a bot sends every community every time. A community copies the
+   * declaration from Core when somebody adds the bot and never again, so without this a bot
+   * that had declared nothing at that moment offered nothing to tick for the life of that
+   * install. It changes nothing about what the bot holds: asking is not having.
+   */
+  setCommands(commands, { requestedPermissions } = {}) {
+    return this.request('PUT', '/bot/commands', {
+      commands,
+      ...(requestedPermissions === undefined || requestedPermissions === null
+        ? {}
+        : { requested_permissions: requestedPermissions }),
+    });
+  }
+
+  // Voice.
+
+  /**
+   * Appear in a voice channel.
+   *
+   * `speaking` is what everybody else is shown. Mic state reaches the server over a
+   * person's websocket and a bot has none, so a bot that does not say this is drawn with
+   * the crossed-out microphone: right for a bot that only listens, wrong and confusing
+   * for one that is about to play something.
+   *
+   * Presence is this one call. Carrying audio needs a media client as well
+   * (`@livekit/rtc-node`, connecting to `voiceToken(channelId)` and publishing a track).
+   */
+  joinVoice(channelId, { speaking = false } = {}) {
+    return this.request('POST', '/bot/voice/join', {
+      channel_id: channelId,
+      mic_enabled: speaking,
+    });
+  }
+
+  /** Change what the channel shows: done playing, or about to start. */
+  setVoiceState(channelId, { speaking = false } = {}) {
+    return this.request('POST', '/bot/voice/state', {
+      channel_id: channelId,
+      mic_enabled: speaking,
+    });
+  }
+
+  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 ?? ''));
+}