@tusile/bot 0.2.1 → 0.5.0

package/src/rest.js

@@ -12,19 +12,43 @@ import { toMask } from './permissions.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;
   }
 
   /**
@@ -89,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`);
   }
@@ -203,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)}`);
   }
@@ -252,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.
@@ -261,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) {