@tusile/bot 0.2.1 → 0.5.0

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';
+}

package/src/errors.js

@@ -1,61 +1,61 @@
-/** What a refusal from Tusile looks like by the time a bot author sees it. */
-export class ApiError extends Error {
-  constructor({ method, path, status, body, retryAfterMs = null }) {
-    const code = codeIn(body);
-    // Everything needed to work out what happened, in the one line that reaches a log:
-    // which call, what the server said, and the server's own word for why.
-    super(`${method} ${path} failed: ${status}${code ? ` ${code}` : ''}${detail(body, code)}`);
-    this.name = 'TusileApiError';
-    this.method = method;
-    this.path = path;
-    this.status = status;
-    this.code = code;
-    this.body = body;
-    this.retryAfterMs = retryAfterMs;
-  }
-
-  /**
-   * The community removed this bot.
-   *
-   * Worth its own question, because it is the one failure that will never come right: a
-   * bot that keeps reconnecting to a community that dropped it is doing nothing but
-   * making noise in two sets of logs.
-   */
-  get isUninstalled() {
-    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;
-  }
-
-  /** Permission, usually. Nothing to retry, something to fix in the bot's roles. */
-  get isForbidden() {
-    return this.status === 403;
-  }
-}
-
-function codeIn(body) {
-  if (!body || typeof body !== 'object') return '';
-  return String(body.error || body.code || '');
-}
-
-function detail(body, code) {
-  if (typeof body === 'string' && body.trim() && body.length < 200) return `: ${body.trim()}`;
-  if (body && typeof body === 'object' && body.message && body.message !== code) {
-    return `: ${body.message}`;
-  }
-  return '';
-}
+/** What a refusal from Tusile looks like by the time a bot author sees it. */
+export class ApiError extends Error {
+  constructor({ method, path, status, body, retryAfterMs = null }) {
+    const code = codeIn(body);
+    // Everything needed to work out what happened, in the one line that reaches a log:
+    // which call, what the server said, and the server's own word for why.
+    super(`${method} ${path} failed: ${status}${code ? ` ${code}` : ''}${detail(body, code)}`);
+    this.name = 'TusileApiError';
+    this.method = method;
+    this.path = path;
+    this.status = status;
+    this.code = code;
+    this.body = body;
+    this.retryAfterMs = retryAfterMs;
+  }
+
+  /**
+   * The community removed this bot.
+   *
+   * Worth its own question, because it is the one failure that will never come right: a
+   * bot that keeps reconnecting to a community that dropped it is doing nothing but
+   * making noise in two sets of logs.
+   */
+  get isUninstalled() {
+    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;
+  }
+
+  /** Permission, usually. Nothing to retry, something to fix in the bot's roles. */
+  get isForbidden() {
+    return this.status === 403;
+  }
+}
+
+function codeIn(body) {
+  if (!body || typeof body !== 'object') return '';
+  return String(body.error || body.code || '');
+}
+
+function detail(body, code) {
+  if (typeof body === 'string' && body.trim() && body.length < 200) return `: ${body.trim()}`;
+  if (body && typeof body === 'object' && body.message && body.message !== code) {
+    return `: ${body.message}`;
+  }
+  return '';
+}