@tusile/bot 0.1.0

package/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 Tusile
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

package/README.md

@@ -0,0 +1,234 @@
+# @tusile/bot
+
+Write a [Tusile](https://tusile.com) bot: slash commands, buttons, forms, embeds and voice.
+
+There is no inbound port and no public URL. The bot dials out, one WebSocket per community
+it has been added to, so it runs anywhere that can make an outgoing connection: a laptop, a
+Raspberry Pi, a free dyno.
+
+```bash
+npm install @tusile/bot
+```
+
+## A whole bot
+
+```js
+import { Bot } from '@tusile/bot';
+
+const bot = new Bot(); // reads CORE_SERVER_URL, BOT_KEY, BOT_SECRET
+
+bot.command({ name: 'ping', description: 'Check the bot is awake' }, (i) => i.reply('pong'));
+
+await bot.start();
+```
+
+```bash
+CORE_SERVER_URL=https://api.tusile.com BOT_KEY=... BOT_SECRET=... node bot.js
+```
+
+That bot is live on every community that has added it, and joins new ones by itself.
+
+## Getting a key and a secret
+
+1. In the Tusile app: **Settings → Bots → Create bot**. Give it a name and a picture.
+2. Copy the key and the secret. **The secret is shown once**; a lost one is rotated, not
+   recovered.
+3. Add the bot to a community: **Community settings → Bots**, or tick "List in bot
+   discovery" when you create it and let people add it themselves.
+
+A bot is an ordinary member of the community. It has roles, its permissions are checked the
+same way yours are, and it cannot see a channel it has not been given access to. Giving a
+bot a role is how you decide what it may do.
+
+## Commands
+
+```js
+bot.command(
+  {
+    name: 'roll',
+    description: 'Roll a die',
+    options: [
+      { name: 'sides', type: 'integer', description: 'How many sides', min: 2, max: 100 },
+      { name: 'secret', type: 'boolean', description: 'Only you see the result' },
+    ],
+  },
+  async (i) => {
+    const sides = i.options.sides || 6;
+    await i.reply(`d${sides} → ${1 + Math.floor(Math.random() * sides)}`, {
+      ephemeral: Boolean(i.options.secret),
+    });
+  },
+);
+```
+
+Option types are `string`, `integer`, `boolean`, `user`, `channel` and `role`. A `user`,
+`channel` or `role` option is a picker in the app and arrives as an id. `choices` turns any
+option into a picker, so nobody can send a value the bot will refuse. `min` and `max` apply
+to integers, `required: true` makes an option compulsory, and all of it is checked in the
+app before the bot is ever asked anything.
+
+The command list is registered on every connect, so a redeploy with a changed set takes
+effect immediately and a bot added to a community while it was down still registers.
+
+## Answering
+
+A bot has **ten seconds** to say something, or the person who ran the command is shown "the
+bot did not respond".
+
+```js
+await i.reply('everyone in the channel sees this');
+await i.replyPrivately('only the person who asked sees this');
+await i.defer();                    // buys fifteen minutes
+await i.followUp('still working');  // another message after the first
+await i.editReply('done');          // rewrite what it already said
+await i.deleteReply();
+await i.showModal({ ... });         // ask them to fill something in
+await i.update({ content: 'x', components: [] }); // rewrite the message a button is on
+await i.acknowledge();              // a press that needs no visible change
+```
+
+A private answer is not channel history: nobody else ever sees it, it is not searchable or
+exportable, and it is gone within a day.
+
+If a handler takes longer than eight seconds, the SDK defers on its behalf rather than let
+the window run out. If a handler throws, or returns without answering, the person is told
+something went wrong instead of being left watching a spinner, and the error reaches
+`bot.on('error')`.
+
+## Embeds and controls
+
+```js
+await i.reply({
+  content: '',
+  embeds: [{
+    title: 'A card',
+    description: 'Embeds carry structure that plain text cannot.',
+    color: 0x5865f2,
+    fields: [
+      { name: 'Inline', value: 'shares a line', inline: true },
+      { name: 'Stacked', value: 'takes its own line' },
+    ],
+    footer: { text: 'sent by a bot' },
+  }],
+  components: [{
+    type: 'row',
+    components: [
+      { type: 'button', style: 'primary', label: 'Press me', custom_id: 'vote:yes' },
+      { type: 'button', style: 'danger', label: 'No', custom_id: 'vote:no' },
+      { type: 'button', style: 'link', label: 'Docs', url: 'https://tusile.com/bots.html' },
+    ],
+  }],
+});
+
+// Matched on the prefix, so both buttons land here and the id carries the choice.
+bot.component('vote', (i) => i.update({ content: `You said ${i.customId}`, components: [] }));
+```
+
+A `custom_id` is yours. The server echoes it back verbatim and never parses it, so encode
+whatever state you need in it: `page:3`, `vote:close:99`. An exactly registered id wins over
+a prefix, and the longest matching prefix wins, so a general handler cannot swallow presses
+meant for a specific one.
+
+Button styles are `primary`, `secondary`, `success`, `danger` and `link` (which takes a
+`url` instead of a `custom_id`). A row can hold five buttons, or one select.
+
+## Forms
+
+```js
+bot.command({ name: 'feedback', description: 'Send a note' }, (i) =>
+  i.showModal({
+    custom_id: 'feedback',
+    title: 'Tell us something',
+    fields: [
+      { custom_id: 'subject', label: 'Subject', required: true },
+      { custom_id: 'body', label: 'Anything else', style: 'paragraph' },
+    ],
+  }),
+);
+
+bot.modal('feedback', (i) => i.replyPrivately(`Noted: ${i.fields.subject}`));
+```
+
+## Everything else
+
+Each handler is given `i.server`, the community the interaction came from:
+
+```js
+bot.command({ name: 'recap', description: 'What was said here' }, async (i) => {
+  const messages = await i.server.history(i.channelId, { limit: 10 });
+  await i.replyPrivately(messages.map((m) => `- ${m.content}`).join('\n'));
+});
+```
+
+| | |
+|---|---|
+| `send(channelId, message)` | say something, with embeds and components |
+| `history(channelId, { limit, before })` | read a channel |
+| `message(id)`, `editMessage(id, m)`, `deleteMessage(id)` | one message |
+| `deleteMessages(channelId, ids)` | clear several at once |
+| `react(id, emoji)`, `unreact(id, emoji)` | reactions |
+| `pin(id)`, `unpin(id)`, `typing(channelId)` | |
+| `channels()`, `createChannel(c)`, `updateChannel(id, c)`, `deleteChannel(id)` | |
+| `roles()`, `createRole(r)`, `updateRole(id, r)`, `deleteRole(id)` | |
+| `members()`, `addRole(userId, roleId)`, `removeRole(userId, roleId)` | |
+| `setNickname(userId, name)` | `'@me'` renames the bot itself |
+| `kick(userId)`, `ban(userId, reason)`, `unban(userId)`, `bans()` | |
+| `timeout(userId, seconds, reason)`, `clearTimeout(userId)` | |
+| `joinVoice(channelId)`, `leaveVoice(channelId)`, `voiceToken(channelId)` | |
+| `serverInfo()`, `commands()`, `setCommands(list)` | |
+| `request(method, path, body)` | anything not on this list |
+
+`request` is not a second-class citizen: everything above is written in terms of it, so an
+endpoint newer than your copy of this package is one line away.
+
+A call the bot lacks permission for comes back as a `TusileApiError` with `status: 403` and
+a reason, never as silence.
+
+## Events
+
+```js
+bot.on('ready',   (me, server) => {});     // connected to a community
+bot.on('message', (message, server) => {}); // said in a channel the bot can see
+bot.on('joined',  (server) => {});          // added to a community
+bot.on('left',    (serverId) => {});        // removed from one
+bot.on('error',   (err, context) => {});    // anything that went wrong
+```
+
+A bot that answers plain messages should check `message.author_id !== bot.me.id` first, or
+it will answer itself.
+
+## Rate limits and failures
+
+Writes are about 60 a minute per community with a burst of 20; reads 300 with a burst of 60.
+The SDK waits out a rate limit and retries, and retries a community that is briefly
+unreachable, so a redeploy does not read as a lost message. A bad request is not retried.
+`server.rateLimit` says what was left on the last call.
+
+A bot removed from a community stops reconnecting to it and keeps every other connection.
+
+## Running it without the Bot class
+
+The pieces are exported on their own, for a script that only wants to post a message:
+
+```js
+import { CoreClient, ServerClient } from '@tusile/bot';
+
+const core = new CoreClient({ url: process.env.CORE_SERVER_URL, key, secret });
+const [server] = await core.servers();
+const client = new ServerClient({
+  apiUrl: server.apiUrl,
+  token: () => token,
+  serverId: server.serverId,
+});
+```
+
+## What this does not have
+
+Deliberately, for now: direct messages to a bot, autocomplete on options, context-menu
+commands, a custom status line, gateway resume after a drop (it reconnects and re-registers
+instead), and outbound webhooks.
+
+Full reference, including every field of an embed, a component and a command option:
+**https://tusile.com/bots.html**
+
+MIT licensed.

package/package.json

@@ -0,0 +1,33 @@
+{
+  "name": "@tusile/bot",
+  "version": "0.1.0",
+  "description": "Write a Tusile bot: slash commands, buttons, forms and voice, over an outbound WebSocket.",
+  "type": "module",
+  "main": "src/index.js",
+  "exports": {
+    ".": "./src/index.js"
+  },
+  "files": [
+    "src",
+    "README.md",
+    "LICENSE"
+  ],
+  "engines": {
+    "node": ">=20"
+  },
+  "scripts": {
+    "test": "node --test"
+  },
+  "dependencies": {
+    "ws": "^8.18.0"
+  },
+  "keywords": [
+    "tusile",
+    "bot",
+    "chat",
+    "slash-commands"
+  ],
+  "homepage": "https://tusile.com/bots.html",
+  "license": "MIT",
+  "author": "Tusile"
+}

package/src/bot.js

@@ -0,0 +1,319 @@
+import { CoreClient } from './core.js';
+import { Dispatcher } from './dispatch.js';
+import { Gateway, nextBackoff } from './gateway.js';
+import { Interaction } from './interaction.js';
+import { ServerClient } from './rest.js';
+
+/**
+ * A bot, on every community that has added it.
+ *
+ * The shape of the problem: one identity held by Core, one short-lived token per
+ * community, one socket per community, and a list of communities that changes while the
+ * bot runs. None of that is a bot author's business, and all of it used to be. What is
+ * left is `command`, `component`, `modal`, and `start`.
+ */
+
+const DEFAULT_POLL_MS = 60 * 1000;
+
+/** How long to let Core hold a request open while the bot is on no communities at all. */
+const JOIN_WAIT_SECONDS = 25;
+
+const RECONNECT_MIN_MS = 1000;
+const RECONNECT_MAX_MS = 30 * 1000;
+
+export class Bot {
+  #core;
+  #dispatcher;
+  #links = new Map();
+  #listeners = new Map();
+  #connect;
+  #timers;
+  #sleep;
+  #fetch;
+  #pollMs;
+  #poll = null;
+  #stopped = false;
+
+  constructor({
+    coreUrl = process.env?.CORE_SERVER_URL,
+    key = process.env?.BOT_KEY,
+    secret = process.env?.BOT_SECRET,
+    fetch,
+    sleep,
+    connect,
+    timers = globalThis,
+    onError,
+    autoDeferMs,
+    pollMs = DEFAULT_POLL_MS,
+  } = {}) {
+    if (!coreUrl) throw new Error('no coreUrl: set CORE_SERVER_URL to the Tusile core server');
+    if (!key || !secret) {
+      // Said here rather than at the first request, because the first request happens
+      // inside a deploy where nobody is watching, and this happens at startup.
+      throw new Error(
+        'no bot credentials: set BOT_KEY and BOT_SECRET. Create a bot in the Tusile app, ' +
+          'under Settings, Bots, and copy them there.',
+      );
+    }
+
+    this.#core = new CoreClient({ url: coreUrl, key, secret, fetch, sleep });
+    this.#fetch = fetch;
+    this.#sleep = sleep || ((ms) => new Promise((r) => setTimeout(r, ms)));
+    this.#connect = connect || null;
+    this.#timers = timers;
+    this.#pollMs = pollMs;
+    this.#dispatcher = new Dispatcher({
+      autoDeferMs,
+      onError: (err, interaction) => this.#report(err, interaction),
+    });
+    if (onError) this.on('error', onError);
+
+    /** This bot's own account, once it has asked. Its id is how it recognises itself. */
+    this.me = null;
+    /** Every community it is connected to, by id. */
+    this.servers = new Map();
+  }
+
+  // What the bot does.
+
+  command(definition, handler) {
+    this.#dispatcher.command(definition, handler);
+    return this;
+  }
+
+  component(customId, handler) {
+    this.#dispatcher.component(customId, handler);
+    return this;
+  }
+
+  modal(customId, handler) {
+    this.#dispatcher.modal(customId, handler);
+    return this;
+  }
+
+  /**
+   * ready    (bot, server)     connected to a community and registered there
+   * message  (message, server) something said in a channel the bot can see
+   * joined   (server)          added to a community
+   * left     (serverId)        removed from one
+   * error    (error, context)  anything that went wrong, including in a handler
+   */
+  on(event, listener) {
+    if (!this.#listeners.has(event)) this.#listeners.set(event, []);
+    this.#listeners.get(event).push(listener);
+    return this;
+  }
+
+  /**
+   * Connect, and stay connected.
+   *
+   * Resolves once every community known right now has a socket, so that a caller can
+   * reasonably look at `servers` afterwards. Keeps running until `stop`.
+   */
+  async start() {
+    // `ws` is loaded only if nobody supplied a socket, so a runtime with its own
+    // WebSocket, or a test, never pays for it.
+    if (!this.#connect) {
+      const { default: WebSocket } = await import('ws');
+      this.#connect = (url) => new WebSocket(url);
+    }
+    this.me = await this.#core.me();
+    await this.sync();
+    // Being added to a community is a change Core cannot push to a bot, so this is a
+    // poll. It is a slow one, because the empty case, which is the one somebody is
+    // watching, is handled by asking Core to hold the request open instead.
+    this.#poll = this.#timers.setInterval(() => {
+      this.sync().catch((err) => this.#report(err));
+    }, this.#pollMs);
+    return this;
+  }
+
+  /**
+   * Bring the set of connections in line with the set of communities.
+   *
+   * Called on a timer, and worth calling by hand after installing the bot somewhere if a
+   * caller happens to know that has just happened.
+   */
+  async sync() {
+    if (this.#stopped) return;
+    const waitSeconds = this.servers.size === 0 ? JOIN_WAIT_SECONDS : undefined;
+    const servers = await this.#core.servers({ waitSeconds });
+    if (this.#stopped) return;
+
+    const seen = new Set();
+    for (const server of servers) {
+      seen.add(server.serverId);
+      if (this.#links.has(server.serverId)) continue;
+      await this.#join(server);
+    }
+    // A community that removed the bot stops being listed, so its socket goes with it.
+    for (const serverId of [...this.#links.keys()]) {
+      if (!seen.has(serverId)) this.#leave(serverId);
+    }
+  }
+
+  /** Close every socket and stop looking for new communities. */
+  async stop() {
+    this.#stopped = true;
+    if (this.#poll) this.#timers.clearInterval(this.#poll);
+    this.#poll = null;
+    for (const serverId of [...this.#links.keys()]) this.#leave(serverId);
+  }
+
+  async #join({ serverId, apiUrl, raw }) {
+    const link = new Link({
+      serverId,
+      apiUrl,
+      raw,
+      core: this.#core,
+      fetch: this.#fetch,
+      sleep: this.#sleep,
+      connect: this.#connect,
+      timers: this.#timers,
+      onReady: (bot, client) => {
+        // Registered on every connect rather than once at startup: a bot redeployed with
+        // a changed command set, or added to a community while it was down, would
+        // otherwise go on offering whatever it registered last time.
+        client
+          .setCommands(this.#dispatcher.definitions())
+          .catch((err) => this.#report(err, { serverId }));
+        this.#emit('ready', bot, client);
+      },
+      onFrame: (frame, client) => this.#onFrame(frame, client),
+      onError: (err) => this.#report(err, { serverId }),
+    });
+
+    this.#links.set(serverId, link);
+    this.servers.set(serverId, link.client);
+    await link.start();
+    this.#emit('joined', link.client);
+  }
+
+  #leave(serverId) {
+    this.#links.get(serverId)?.stop();
+    this.#links.delete(serverId);
+    this.servers.delete(serverId);
+    this.#emit('left', serverId);
+  }
+
+  #onFrame(frame, client) {
+    if (frame?.type === 'interaction_create') {
+      const interaction = new Interaction(frame.data || {}, client);
+      this.#dispatcher.handle(interaction).catch((err) => this.#report(err, interaction));
+      return;
+    }
+    if (frame?.type === 'message_create') {
+      this.#emit('message', frame.data || {}, client);
+    }
+  }
+
+  #emit(event, ...args) {
+    for (const listener of this.#listeners.get(event) ?? []) {
+      try {
+        listener(...args);
+      } catch (err) {
+        // A throwing listener must not take down the socket that fed it.
+        if (event !== 'error') this.#report(err);
+      }
+    }
+  }
+
+  #report(err, context) {
+    const listeners = this.#listeners.get('error') ?? [];
+    if (!listeners.length) {
+      // Better a line on stderr than a bot that fails in total silence because nobody
+      // wired up an error handler.
+      console.error('[tusile-bot]', err);
+      return;
+    }
+    this.#emit('error', err, context);
+  }
+}
+
+/**
+ * One community: its socket, its token, and its reconnects.
+ *
+ * Kept separate from the bot because everything here is per community. One community being
+ * down, or having removed the bot, must leave every other connection alone.
+ */
+class Link {
+  #gateway;
+  #core;
+  #sleep;
+  #onError;
+  #onReady;
+  #onFrame;
+  #token = '';
+  #backoff = 0;
+  #stopped = false;
+
+  constructor({ serverId, apiUrl, raw, core, fetch, sleep, connect, timers, onReady, onFrame, onError }) {
+    this.serverId = serverId;
+    this.apiUrl = apiUrl;
+    this.raw = raw;
+    this.#core = core;
+    this.#sleep = sleep;
+    this.#onError = onError;
+    this.#onReady = onReady;
+    this.#onFrame = onFrame;
+
+    this.client = new ServerClient({
+      apiUrl,
+      serverId,
+      // Read per request, so a reconnect that mints a new token does not leave the rest
+      // client holding an expired one.
+      token: () => this.#token,
+      fetch,
+      sleep,
+    });
+
+    this.#gateway = new Gateway({
+      url: apiUrl,
+      token: async () => {
+        this.#token = await this.#core.token(serverId);
+        return this.#token;
+      },
+      connect,
+      timers,
+      onReady: (bot) => this.#onReady(bot, this.client),
+      onFrame: (frame) => this.#onFrame(frame, this.client),
+    });
+  }
+
+  /** Open the socket, then keep it open in the background. */
+  async start() {
+    await this.#open();
+    this.#keepAlive().catch((err) => this.#onError(err));
+  }
+
+  stop() {
+    this.#stopped = true;
+    this.#gateway.stop();
+  }
+
+  async #open() {
+    try {
+      await this.#gateway.open();
+    } catch (err) {
+      // Core refusing a token, most likely. Swallowed here because the failure is also
+      // settled on the connection, and the loop below reports it from there: what
+      // matters is that it does not take the bot's other communities with it.
+    }
+  }
+
+  async #keepAlive() {
+    while (!this.#stopped) {
+      const { fatal, reason, wasLive } = await this.#gateway.closed();
+      if (reason) this.#onError(new Error(`[${this.serverId}] ${reason}`));
+      if (fatal || this.#stopped) return;
+      // A connection that was up and then dropped is worth picking straight back up.
+      // Carrying the backoff over would leave a bot that reconnects cleanly once an hour
+      // eventually waiting half a minute every time, for nothing.
+      if (wasLive) this.#backoff = 0;
+      this.#backoff = nextBackoff(this.#backoff, RECONNECT_MIN_MS, RECONNECT_MAX_MS);
+      await this.#sleep(this.#backoff);
+      if (this.#stopped) return;
+      await this.#open();
+    }
+  }
+}

package/src/core.js

@@ -0,0 +1,68 @@
+import { Transport, query } from './http.js';
+
+/**
+ * Tusile Core: who this bot is, and which communities have added it.
+ *
+ * A bot has one identity across the whole network and a separate short-lived token for
+ * each community it is in. Core is where both come from. The key and secret only ever go
+ * here; a community never sees them.
+ */
+export class CoreClient {
+  #transport;
+
+  constructor({ url, key, secret, fetch, sleep, maxRetries }) {
+    this.url = String(url || '').replace(/\/+$/, '');
+    this.#transport = new Transport({
+      baseUrl: this.url,
+      authorization: () => 'Bot ' + base64(`${key}:${secret}`),
+      fetch,
+      sleep,
+      maxRetries,
+    });
+  }
+
+  /** The bot's own account: id, name, picture. */
+  me() {
+    return this.#transport.request('GET', '/bots/me');
+  }
+
+  /**
+   * 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.
+   */
+  async servers({ waitSeconds } = {}) {
+    const out = await this.#transport.request(
+      'GET',
+      `/bots/me/servers${query({ wait: waitSeconds })}`,
+    );
+    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,
+    }));
+  }
+
+  /**
+   * A token for one community.
+   *
+   * Good for an hour and for that community only, so every connect mints a new one rather
+   * than trying to work out whether the last one is still alive.
+   */
+  async token(serverId) {
+    const out = await this.#transport.request('POST', '/bots/token', { server_id: serverId });
+    if (!out?.token) throw new Error(`Core issued no token for ${serverId}`);
+    return out.token;
+  }
+}
+
+function base64(text) {
+  if (typeof Buffer !== 'undefined') return Buffer.from(text, 'utf8').toString('base64');
+  // Not Node. Nothing in this package needs it, but failing here would be a strange way
+  // to find that out.
+  return btoa(text);
+}