@tusile/bot 0.1.2 → 0.4.0

package/src/core.js

@@ -7,10 +7,15 @@ import { Transport, query } from './http.js';
  * each community it is in. Core is where both come from. The key and secret only ever go
  * here; a community never sees them.
  */
+/** How long a display name is good for. Names change rarely; a stale one costs nothing. */
+const NAME_TTL_MS = 10 * 60 * 1000;
+
 export class CoreClient {
   #transport;
+  #names = new Map();
+  #nameTtlMs;
 
-  constructor({ url, key, secret, fetch, sleep, maxRetries }) {
+  constructor({ url, key, secret, fetch, sleep, maxRetries, nameTtlMs = NAME_TTL_MS }) {
     this.url = String(url || '').replace(/\/+$/, '');
     this.#transport = new Transport({
       baseUrl: this.url,
@@ -19,6 +24,20 @@ export class CoreClient {
       sleep,
       maxRetries,
     });
+    this.#nameTtlMs = nameTtlMs;
+  }
+
+  /**
+   * Anything at all, with this bot's own credentials.
+   *
+   * The escape hatch, and not a second-class one: everything below is written in terms of
+   * it, so a bot reaching a Core endpoint this package has never heard of is in exactly the
+   * same position as one calling a named method. ServerClient has had this since it was
+   * written; without it here, a bot filing a support ticket built its own authenticated
+   * fetch and owned the base url, the timeout and the retry policy twice.
+   */
+  request(method, path, body) {
+    return this.#transport.request(method, path, body);
   }
 
   /** The bot's own account: id, name, picture. */
@@ -29,22 +48,64 @@ export class CoreClient {
   /**
    * Every community this bot is in.
    *
-   * `waitSeconds` asks Core to hold the request open until something changes, which is for
-   * the case that matters: a bot running on no servers at all. Polling that once a minute
-   * means somebody adds the bot, watches nothing happen, and concludes it is broken.
+   * Answers at once. Returns a plain array, which is what it has always returned: this is
+   * public API, and a bot author calling it wants the list rather than a wrapper.
    */
   async servers({ waitSeconds } = {}) {
+    const { servers } = await this.watchServers({ waitSeconds });
+    return servers;
+  }
+
+  /**
+   * The same list, with the request held open until it would be different.
+   *
+   * `waitSeconds` is how long Core may hold it. `known` is a digest of what the bot already
+   * serves (see known.js): Core compares, and holds only while the two agree. Without it
+   * Core falls back to its older rule and holds only for a bot on no communities at all,
+   * which left every bot already serving one to hear about the next on its own timer.
+   *
+   * `watch` in the answer is Core saying it understood the token and will hold the next
+   * request. It matters because the body alone cannot distinguish a Core that held this
+   * request for twenty-five seconds and found nothing new from an older Core that ignored
+   * the parameter and answered instantly: a bot that guesses wrong either polls the old one
+   * in a tight loop or throws away the feature against the new one. Timing does not settle
+   * it either, because a duplicate install wakes every waiter while changing nothing.
+   *
+   * `signal` gives up on a hold that is never answered. Mandatory for the loop that drives
+   * this: without it one blackholed request silences the bot until it is restarted.
+   */
+  async watchServers({ waitSeconds, known, signal } = {}) {
     const out = await this.#transport.request(
       'GET',
-      `/bots/me/servers${query({ wait: waitSeconds })}`,
+      `/bots/me/servers${query({ wait: waitSeconds, known })}`,
+      undefined,
+      { signal },
     );
-    return (out?.servers ?? []).map((row) => ({
-      serverId: row.server_id,
-      apiUrl: row.api_url,
-      // Whatever else Core said about it, kept as it came, so a field added later is
-      // already available without a release of this package.
-      raw: row,
-    }));
+    return {
+      watch: out?.watch === true,
+      servers: (out?.servers ?? []).map((row) => ({
+        serverId: row.server_id,
+        apiUrl: row.api_url,
+        // Whatever else Core said about it, kept as it came, so a field added later is
+        // already available without a release of this package.
+        raw: row,
+      })),
+    };
+  }
+
+  /**
+   * Say what this bot needs to do its job.
+   *
+   * A declaration, not a grant. It is the list shown to whoever adds the bot to a community,
+   * and they decide what of it to allow; the bot ends up with what they ticked and nothing
+   * more. Declaring it here rather than in a form somewhere means it lives next to the
+   * commands that need it, and a bot that grows a command that needs Manage Channels says so
+   * in the same commit.
+   */
+  declarePermissions(mask) {
+    return this.#transport.request('PUT', '/bots/me/permissions', {
+      requested_permissions: mask,
+    });
   }
 
   /**
@@ -58,6 +119,84 @@ export class CoreClient {
     if (!out?.token) throw new Error(`Core issued no token for ${serverId}`);
     return out.token;
   }
+
+  /**
+   * Somebody's public profile: when they were last here, and whether they are a guest.
+   *
+   * Neither fact is on a community's /bot routes. A community's members table knows when
+   * somebody joined and nothing else, so a bot that decides anything about a person, who to
+   * warn, who to retire, who to leave alone, has to ask Core, once per person.
+   *
+   * Null for a profile that is not there or cannot be read, rather than a throw. That is the
+   * difference between this and everything else on this client, and it is deliberate: a bot
+   * sweeping a community of two hundred must not lose the whole pass to one lookup, and
+   * somebody it knows nothing about is somebody to leave alone. A caller that treats null as
+   * "no information" gets the safe behaviour for free.
+   */
+  profile(userId) {
+    return this.#publicRead(`/profiles/${encodeURIComponent(String(userId ?? ''))}`);
+  }
+
+  /**
+   * A community's public row, which is where its owner is named.
+   *
+   * A bot holding Manage Members can remove the owner of the community that installed it:
+   * the bot kick route checks the permission bit and whether the target is a bot, and
+   * nothing else. Knowing who the owner is, is how a bot refuses to.
+   *
+   * Null on anything that is not an answer, for the same reason as [profile]: not knowing
+   * who the owner is must read as "do not touch anybody", not as a crash.
+   */
+  community(serverId) {
+    return this.#publicRead(`/servers/${encodeURIComponent(String(serverId ?? ''))}`);
+  }
+
+  /**
+   * What to call somebody, from their id, remembered.
+   *
+   * A message frame carries who wrote it and not what they are called. A transcript where
+   * everybody is "someone" is worse than no names at all: "she said it is broken" then has
+   * nobody to attach to. Without a cache this is a call per message.
+   *
+   * Null when Core cannot name them, rather than a word of its own: "someone", "unknown",
+   * "a member" are all decisions about tone and language, and this package ships no copy.
+   * A failure is not remembered, so somebody unnameable during a deploy is named afterwards.
+   */
+  async displayName(userId) {
+    const key = String(userId ?? '');
+    if (!key) return null;
+    const held = this.#names.get(key);
+    if (held && held.at > Date.now() - this.#nameTtlMs) return held.name;
+    const profile = await this.profile(key);
+    const name = profile?.display_name || profile?.username || null;
+    if (name === null) return null;
+    // A community is a few hundred people, and only the ones who have spoken land here.
+    // Cleared rather than evicted one by one: the next few messages pay a call each, which
+    // is cheaper than carrying a policy nobody will ever tune.
+    if (this.#names.size > 500) this.#names.clear();
+    this.#names.set(key, { name, at: Date.now() });
+    return name;
+  }
+
+  /** Forget every remembered name, for a bot that has reason to think one changed. */
+  forgetNames() {
+    this.#names.clear();
+  }
+
+  /**
+   * A public Core route, where absent and unreachable are the same answer: null.
+   *
+   * It goes through the same transport as everything else, so it carries the bot's own
+   * credentials. Core ignores them on these routes, and sending them keeps one place that
+   * knows the base url, the timeout and the retry policy.
+   */
+  async #publicRead(path) {
+    try {
+      return (await this.#transport.request('GET', path)) ?? null;
+    } catch {
+      return null;
+    }
+  }
 }
 
 function base64(text) {

package/src/dispatch.js

@@ -1,178 +1,195 @@
-/**
- * Which handler wants this interaction, and what to do when none of them does.
- *
- * The routing is the easy half. The half worth writing carefully is the part that runs
- * when a handler throws, forgets to answer, or takes longer than the server's ten second
- * window: the person who ran the command is sitting in front of a spinner, and every one
- * of those cases ends with them being told "the bot did not respond", which reads as a
- * dead bot rather than a bug in one command. So every path through here answers.
- */
-
-/**
- * When to defer on the handler's behalf.
- *
- * The server's window is ten seconds. Two seconds of margin covers the round trip from
- * wherever the bot is running, and a bot author who never thinks about any of this gets
- * the same behaviour as one who deferred by hand.
- */
-const DEFAULT_AUTO_DEFER_MS = 8000;
-
-export class Dispatcher {
-  #commands = new Map();
-  #components = [];
-  #modals = [];
-  #onError;
-  #autoDeferMs;
-
-  constructor({ onError = () => {}, autoDeferMs = DEFAULT_AUTO_DEFER_MS } = {}) {
-    this.#onError = onError;
-    this.#autoDeferMs = autoDeferMs;
-  }
-
-  /**
-   * A slash command and what runs it.
-   *
-   * The definition is what people see in the app: name, description, and options that are
-   * checked and turned into pickers before the bot is ever asked anything.
-   */
-  command(definition, handler) {
-    const name = definition?.name;
-    if (!name) throw new Error('a command needs a name');
-    if (typeof handler !== 'function') throw new Error(`/${name} needs a handler`);
-    if (this.#commands.has(name)) throw new Error(`/${name} is already registered`);
-    this.#commands.set(name, { definition: { ...definition }, handler });
-    return this;
-  }
-
-  /**
-   * A button or select, matched on its custom id exactly or by prefix.
-   *
-   * A custom id is the bot's own: the server echoes it back without ever parsing it, so
-   * `vote:close:99` is how a control carries its state. Prefix matching is what makes
-   * that usable, and an exact registration still wins over a prefix that would match it.
-   */
-  component(customId, handler) {
-    if (!customId) throw new Error('a component handler needs a custom id');
-    if (typeof handler !== 'function') throw new Error(`the ${customId} handler is not a function`);
-    this.#components.push({ customId, handler });
-    return this;
-  }
-
-  /** A form submission, matched the same way. */
-  modal(customId, handler) {
-    if (!customId) throw new Error('a modal handler needs a custom id');
-    if (typeof handler !== 'function') throw new Error(`the ${customId} handler is not a function`);
-    this.#modals.push({ customId, handler });
-    return this;
-  }
-
-  /** What to send the server as this bot's command list. */
-  definitions() {
-    return [...this.#commands.values()].map((c) => c.definition);
-  }
-
-  async handle(interaction) {
-    const found = this.#route(interaction);
-    if (!found) return;
-    if (!found.handler) {
-      // Something is offered that this bot no longer implements: a command list left over
-      // from an older deploy, or a button on a message from one. Say so quietly rather
-      // than leave somebody watching a spinner run out.
-      await this.#sayQuietly(interaction, found.missing);
-      return;
-    }
-
-    const deferring = this.#deferAfterAWhile(interaction);
-    try {
-      await found.handler(interaction);
-      if (!interaction.answered) {
-        // The commonest bot bug there is, and from the outside identical to a crash.
-        throw new Error(`${describe(interaction)} was handled without an answer`);
-      }
-    } catch (err) {
-      this.#onError(err, interaction);
-      await this.#apologise(interaction);
-    } finally {
-      deferring.cancel();
-    }
-  }
-
-  #route(interaction) {
-    if (interaction.isCommand) {
-      const found = this.#commands.get(interaction.command);
-      return found || { missing: `I do not know /${interaction.command} any more.` };
-    }
-    if (interaction.isComponent) {
-      const found = longestMatch(this.#components, interaction.customId);
-      return found || { missing: 'That control belongs to an older version of this bot.' };
-    }
-    if (interaction.isModalSubmit) {
-      const found = longestMatch(this.#modals, interaction.customId);
-      return found || { missing: 'That form belongs to an older version of this bot.' };
-    }
-    // A kind of interaction newer than this package. Answering it could say the wrong
-    // thing, and it is not a bug in the bot, so it goes no further.
-    return null;
-  }
-
-  /**
-   * Defer if the handler is still working when the window is nearly up.
-   *
-   * Cancelled the moment the handler returns, and it checks again before sending: an
-   * unasked-for defer arriving after a normal answer would be refused every time.
-   *
-   * Not for a press. A press is answered by rewriting the message it sits on, and that is
-   * only available before the interaction has been answered at all; after a bare defer the
-   * server has no message to edit and refuses. Deferring on the handler's behalf would
-   * trade a late answer for one that cannot be given, and leave the buttons live.
-   */
-  #deferAfterAWhile(interaction) {
-    if (!(this.#autoDeferMs > 0) || interaction.isComponent) return { cancel() {} };
-    const timer = setTimeout(() => {
-      if (interaction.answered) return;
-      interaction.defer().catch((err) => this.#onError(err, interaction));
-    }, this.#autoDeferMs);
-    return { cancel: () => clearTimeout(timer) };
-  }
-
-  async #apologise(interaction) {
-    if (interaction.answered) return;
-    try {
-      await interaction.replyPrivately('Something went wrong. The bot author has been told.');
-    } catch (err) {
-      // Nothing left to try. The person will see the server's own timeout notice, which
-      // at least is true.
-      this.#onError(err, interaction);
-    }
-  }
-
-  async #sayQuietly(interaction, text) {
-    try {
-      await interaction.replyPrivately(text);
-    } catch (err) {
-      this.#onError(err, interaction);
-    }
-  }
-}
-
-/**
- * The most specific registration that matches.
- *
- * An exact id is the longest possible match, so this is one rule rather than two: a
- * general `vote` handler cannot swallow presses meant for `vote:close`.
- */
-function longestMatch(entries, customId) {
-  const id = customId || '';
-  let best = null;
-  for (const entry of entries) {
-    if (id !== entry.customId && !id.startsWith(entry.customId)) continue;
-    if (!best || entry.customId.length > best.customId.length) best = entry;
-  }
-  return best;
-}
-
-function describe(interaction) {
-  if (interaction.isCommand) return `/${interaction.command}`;
-  if (interaction.customId) return `\`${interaction.customId}\``;
-  return interaction.type || 'an interaction';
-}
+/**
+ * Which handler wants this interaction, and what to do when none of them does.
+ *
+ * The routing is the easy half. The half worth writing carefully is the part that runs
+ * when a handler throws, forgets to answer, or takes longer than the server's ten second
+ * window: the person who ran the command is sitting in front of a spinner, and every one
+ * of those cases ends with them being told "the bot did not respond", which reads as a
+ * dead bot rather than a bug in one command. So every path through here answers.
+ */
+
+/**
+ * When to defer on the handler's behalf.
+ *
+ * The server's window is ten seconds. Two seconds of margin covers the round trip from
+ * wherever the bot is running, and a bot author who never thinks about any of this gets
+ * the same behaviour as one who deferred by hand.
+ */
+import { toMask } from './permissions.js';
+
+const DEFAULT_AUTO_DEFER_MS = 8000;
+
+export class Dispatcher {
+  #commands = new Map();
+  #components = [];
+  #modals = [];
+  #onError;
+  #autoDeferMs;
+
+  constructor({ onError = () => {}, autoDeferMs = DEFAULT_AUTO_DEFER_MS } = {}) {
+    this.#onError = onError;
+    this.#autoDeferMs = autoDeferMs;
+  }
+
+  /**
+   * A slash command and what runs it.
+   *
+   * The definition is what people see in the app: name, description, and options that are
+   * checked and turned into pickers before the bot is ever asked anything.
+   *
+   * `requiredPermissions` is what the PERSON running it must hold, by the names in
+   * `Permissions` or as a mask: `requiredPermissions: ['manage_channels', 'manage_roles']`.
+   * The community refuses the invocation without them and leaves the command out of the
+   * picker for anybody who cannot run it. It is not the bot own permissions, which say what
+   * the bot may do and nothing about who may ask: a /setup that rebuilds a server is open to
+   * every member who can talk, unless it says otherwise here.
+   */
+  command(definition, handler) {
+    const name = definition?.name;
+    if (!name) throw new Error('a command needs a name');
+    if (typeof handler !== 'function') throw new Error(`/${name} needs a handler`);
+    if (this.#commands.has(name)) throw new Error(`/${name} is already registered`);
+    const { requiredPermissions, ...rest } = definition;
+    const wire = { ...rest };
+    if (requiredPermissions !== undefined && requiredPermissions !== null) {
+      // toMask throws on a name it does not know, at registration rather than at the
+      // moment somebody runs the command: a typo here is a command anybody can run on a
+      // bot whose author believed they had locked it.
+      wire.required_permissions = toMask(requiredPermissions);
+    }
+    this.#commands.set(name, { definition: wire, handler });
+    return this;
+  }
+
+  /**
+   * A button or select, matched on its custom id exactly or by prefix.
+   *
+   * A custom id is the bot's own: the server echoes it back without ever parsing it, so
+   * `vote:close:99` is how a control carries its state. Prefix matching is what makes
+   * that usable, and an exact registration still wins over a prefix that would match it.
+   */
+  component(customId, handler) {
+    if (!customId) throw new Error('a component handler needs a custom id');
+    if (typeof handler !== 'function') throw new Error(`the ${customId} handler is not a function`);
+    this.#components.push({ customId, handler });
+    return this;
+  }
+
+  /** A form submission, matched the same way. */
+  modal(customId, handler) {
+    if (!customId) throw new Error('a modal handler needs a custom id');
+    if (typeof handler !== 'function') throw new Error(`the ${customId} handler is not a function`);
+    this.#modals.push({ customId, handler });
+    return this;
+  }
+
+  /** What to send the server as this bot's command list. */
+  definitions() {
+    return [...this.#commands.values()].map((c) => c.definition);
+  }
+
+  async handle(interaction) {
+    const found = this.#route(interaction);
+    if (!found) return;
+    if (!found.handler) {
+      // Something is offered that this bot no longer implements: a command list left over
+      // from an older deploy, or a button on a message from one. Say so quietly rather
+      // than leave somebody watching a spinner run out.
+      await this.#sayQuietly(interaction, found.missing);
+      return;
+    }
+
+    const deferring = this.#deferAfterAWhile(interaction);
+    try {
+      await found.handler(interaction);
+      if (!interaction.answered) {
+        // The commonest bot bug there is, and from the outside identical to a crash.
+        throw new Error(`${describe(interaction)} was handled without an answer`);
+      }
+    } catch (err) {
+      this.#onError(err, interaction);
+      await this.#apologise(interaction);
+    } finally {
+      deferring.cancel();
+    }
+  }
+
+  #route(interaction) {
+    if (interaction.isCommand) {
+      const found = this.#commands.get(interaction.command);
+      return found || { missing: `I do not know /${interaction.command} any more.` };
+    }
+    if (interaction.isComponent) {
+      const found = longestMatch(this.#components, interaction.customId);
+      return found || { missing: 'That control belongs to an older version of this bot.' };
+    }
+    if (interaction.isModalSubmit) {
+      const found = longestMatch(this.#modals, interaction.customId);
+      return found || { missing: 'That form belongs to an older version of this bot.' };
+    }
+    // A kind of interaction newer than this package. Answering it could say the wrong
+    // thing, and it is not a bug in the bot, so it goes no further.
+    return null;
+  }
+
+  /**
+   * Defer if the handler is still working when the window is nearly up.
+   *
+   * Cancelled the moment the handler returns, and it checks again before sending: an
+   * unasked-for defer arriving after a normal answer would be refused every time.
+   *
+   * Not for a press. A press is answered by rewriting the message it sits on, and that is
+   * only available before the interaction has been answered at all; after a bare defer the
+   * server has no message to edit and refuses. Deferring on the handler's behalf would
+   * trade a late answer for one that cannot be given, and leave the buttons live.
+   */
+  #deferAfterAWhile(interaction) {
+    if (!(this.#autoDeferMs > 0) || interaction.isComponent) return { cancel() {} };
+    const timer = setTimeout(() => {
+      if (interaction.answered) return;
+      interaction.defer().catch((err) => this.#onError(err, interaction));
+    }, this.#autoDeferMs);
+    return { cancel: () => clearTimeout(timer) };
+  }
+
+  async #apologise(interaction) {
+    if (interaction.answered) return;
+    try {
+      await interaction.replyPrivately('Something went wrong. The bot author has been told.');
+    } catch (err) {
+      // Nothing left to try. The person will see the server's own timeout notice, which
+      // at least is true.
+      this.#onError(err, interaction);
+    }
+  }
+
+  async #sayQuietly(interaction, text) {
+    try {
+      await interaction.replyPrivately(text);
+    } catch (err) {
+      this.#onError(err, interaction);
+    }
+  }
+}
+
+/**
+ * The most specific registration that matches.
+ *
+ * An exact id is the longest possible match, so this is one rule rather than two: a
+ * general `vote` handler cannot swallow presses meant for `vote:close`.
+ */
+function longestMatch(entries, customId) {
+  const id = customId || '';
+  let best = null;
+  for (const entry of entries) {
+    if (id !== entry.customId && !id.startsWith(entry.customId)) continue;
+    if (!best || entry.customId.length > best.customId.length) best = entry;
+  }
+  return best;
+}
+
+function describe(interaction) {
+  if (interaction.isCommand) return `/${interaction.command}`;
+  if (interaction.customId) return `\`${interaction.customId}\``;
+  return interaction.type || 'an interaction';
+}