@tusile/bot 0.1.0

package/src/interaction.js

@@ -0,0 +1,140 @@
+/**
+ * One thing somebody asked a bot to do, and the ways of answering it.
+ *
+ * The protocol underneath is a response type and a JSON body. Written out by hand that is
+ * four lines of ceremony around every answer, repeated at every branch of a switch, which
+ * is how a bot ends up with a `defer` it forgot to follow up and an `ephemeral` it meant
+ * to be public. These are the same four lines, named after what they do.
+ */
+
+/** How long the server gives a bot to say something before the person is told it did not. */
+export const ANSWER_WINDOW_MS = 10_000;
+
+export class Interaction {
+  constructor(data, server) {
+    this.raw = data;
+    this.server = server;
+
+    this.id = data.id;
+    this.type = data.type;
+    this.command = data.command || '';
+    this.options = data.options || {};
+    this.customId = data.custom_id || '';
+    this.values = data.values || [];
+    this.fields = data.fields || {};
+    this.channelId = data.channel_id;
+    this.userId = data.user_id;
+    /** The message a control came from, when there is one. */
+    this.messageId = data.message_id || '';
+    /** The earlier answer a control came from, for a control on a private answer. */
+    this.sourceInteractionId = data.source_interaction_id || '';
+
+    this.answered = false;
+  }
+
+  get isCommand() {
+    return this.type === 'command';
+  }
+
+  get isComponent() {
+    return this.type === 'component';
+  }
+
+  get isModalSubmit() {
+    return this.type === 'modal_submit';
+  }
+
+  /**
+   * Answer it.
+   *
+   * A string is the common case and means a public message. An object is passed through,
+   * so anything the API accepts is still reachable.
+   */
+  reply(response, { ephemeral = false } = {}) {
+    const body =
+      typeof response === 'string'
+        ? { type: ephemeral ? 'ephemeral' : 'message', content: response }
+        : { type: ephemeral ? 'ephemeral' : 'message', ...response };
+    return this.#answer(body);
+  }
+
+  /** Answer only the person who asked. Not channel history, and gone within a day. */
+  replyPrivately(response) {
+    return this.reply(response, { ephemeral: true });
+  }
+
+  /**
+   * Say "give me a moment".
+   *
+   * Buys fifteen minutes. Without it a bot that takes longer than ten seconds is reported
+   * to the person as not having responded, which is a lie about a bot that is working.
+   */
+  defer() {
+    return this.#answer({ type: 'defer' });
+  }
+
+  /**
+   * Rewrite the message the control is on.
+   *
+   * The usual answer to a press: a confirm that removes its own buttons, a page that
+   * turns, a toggle that redraws. `components: []` is how the buttons come off.
+   */
+  update(response) {
+    const body = typeof response === 'string' ? { content: response } : response;
+    return this.#answer({ type: 'update_message', ...body });
+  }
+
+  /** Acknowledge a press that needs no visible change, because it did its work elsewhere. */
+  acknowledge() {
+    return this.#answer({ type: 'defer_update' });
+  }
+
+  /** Ask the person to fill something in. The submission arrives as a modal_submit. */
+  showModal(modal) {
+    return this.#answer({ type: 'modal', modal });
+  }
+
+  /** Another message after the first. Only after defer or a first answer. */
+  followUp(response, { ephemeral = false } = {}) {
+    const body =
+      typeof response === 'string'
+        ? { type: ephemeral ? 'ephemeral' : 'message', content: response }
+        : { type: ephemeral ? 'ephemeral' : 'message', ...response };
+    return this.server.request('POST', `/bot/interactions/${this.id}/followup`, body);
+  }
+
+  /**
+   * Change the answer already given.
+   *
+   * What a slow bot wants: defer, say "working on it", then say what happened, in the
+   * same message rather than a second one underneath the first.
+   */
+  editReply(response) {
+    const body = typeof response === 'string' ? { content: response } : response;
+    return this.server.request('PATCH', `/bot/interactions/${this.id}/response`, body);
+  }
+
+  /** Take the answer back. */
+  deleteReply() {
+    return this.server.request('DELETE', `/bot/interactions/${this.id}/response`);
+  }
+
+  async #answer(body) {
+    // Guarded here as well as on the server, because the server's refusal arrives as a
+    // 409 in a log somewhere and this arrives in the bot author's own stack trace.
+    if (this.answered) {
+      throw new Error(
+        `interaction ${this.id} has already been answered; use followUp or editReply`,
+      );
+    }
+    this.answered = true;
+    try {
+      return await this.server.request('POST', `/bot/interactions/${this.id}/callback`, body);
+    } catch (err) {
+      // Not answered after all, so a retry is allowed. Otherwise one dropped connection
+      // makes the interaction unanswerable for the rest of its life.
+      this.answered = false;
+      throw err;
+    }
+  }
+}

package/src/rest.js

@@ -0,0 +1,234 @@
+import { Transport, query } from './http.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.
+ */
+export class ServerClient {
+  #transport;
+
+  constructor({ apiUrl, token, serverId = '', fetch, sleep, maxRetries }) {
+    this.serverId = serverId;
+    this.apiUrl = String(apiUrl || '').replace(/\/+$/, '');
+    this.#transport = new Transport({
+      baseUrl: this.apiUrl,
+      authorization: () => `Bearer ${token()}`,
+      fetch,
+      sleep,
+      maxRetries,
+    });
+  }
+
+  /**
+   * 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`, {});
+  }
+
+  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)}`);
+  }
+
+  // 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 ?? [];
+  }
+
+  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. */
+  setCommands(commands) {
+    return this.request('PUT', '/bot/commands', { commands });
+  }
+
+  // Voice.
+
+  /**
+   * 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`).
+   */
+  joinVoice(channelId) {
+    return this.request('POST', '/bot/voice/join', { channel_id: channelId });
+  }
+
+  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 ?? ''));
+}