@tusile/bot 0.1.2 → 0.4.0

package/src/known.js

@@ -0,0 +1,23 @@
+import { createHash } from 'node:crypto';
+
+/**
+ * What this bot already knows, as one short string.
+ *
+ * Sent to Core as ?known= alongside ?wait=, so Core can hold the request open until the
+ * answer would actually be different. Before this, Core would only hold a request for a bot
+ * that was on no communities at all, which meant every bot already serving one heard about
+ * the next one on its own sixty-second timer: half a minute of nothing, on average, after
+ * somebody pressed Add.
+ *
+ * Mirrors core-server/internal/bots/known.go exactly, and the same three vectors are pinned
+ * in both test suites. A count would have been easier and wrong: removed from one community
+ * and added to another between two polls is the same count, so Core would hold the request
+ * while the bot served the wrong place.
+ */
+const VERSION = 'v1';
+
+export function serversToken(serverIds) {
+  const unique = [...new Set(serverIds ?? [])].map(String).sort();
+  const digest = createHash('sha256').update(unique.join('\n')).digest('hex');
+  return `${VERSION}:${digest.slice(0, 16)}`;
+}

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,4 +1,5 @@
 import { Transport, query } from './http.js';
+import { toMask } from './permissions.js';
 
 /**
  * One community, and everything a bot can do in it.
@@ -11,19 +12,43 @@ import { Transport, query } from './http.js';
  * 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;
-
-  constructor({ apiUrl, token, serverId = '', fetch, sleep, maxRetries }) {
+  #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;
   }
 
   /**
@@ -88,6 +113,38 @@ export class ServerClient {
     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`);
   }
@@ -123,6 +180,59 @@ export class ServerClient {
     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() {
@@ -149,6 +259,47 @@ export class ServerClient {
     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)}`);
   }
@@ -198,8 +349,22 @@ export class ServerClient {
   }
 
   /** Replace the command list. Whatever is not in it stops being offered. */
-  setCommands(commands) {
-    return this.request('PUT', '/bot/commands', { commands });
+  /**
+   * 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.
@@ -207,12 +372,27 @@ export class ServerClient {
   /**
    * 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`).
+   * `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) {
-    return this.request('POST', '/bot/voice/join', { channel_id: channelId });
+  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) {