@tusile/bot 0.4.0 → 0.5.0

package/README.md

@@ -1,439 +1,439 @@
-# @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. Its permissions are checked the same way yours
-are, and it cannot see a channel it has not been given access to.
-
-## Saying what your bot needs
-
-Whoever adds your bot is shown the permissions it asks for, and ticks what they are willing
-to allow. It gets exactly that, so asking for less is a bot more people will add.
-
-```js
-const bot = new Bot({
-  permissions: ['view_channel', 'send_messages', 'manage_channels', 'connect', 'speak'],
-});
-```
-
-Declaring it here rather than in a form means the list lives next to the commands that need
-it, and a command that grows a new requirement says so in the same commit. The names are the
-ones in `Permissions`; an unknown name throws at startup rather than quietly dropping out of
-the list somebody is shown. Your bot's owner can tick the same list in **Settings → Bots**,
-and a declaration in code wins when the bot starts.
-
-A declaration grants nothing by itself. A bot that asks for nothing gets whatever everybody
-on that community can do, which is where bots started out before any of this existed. To
-give a bot more than it asked for, give it a role, the way you would anybody else.
-
-Ask for `view_channel` if your bot does anything at all in a channel. It is the floor: a bot
-that cannot see a channel is not handed the interactions that happen there, so a bot that
-asks only for `send_messages` will be added, will look installed, and will answer nothing.
-
-## 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.
-
-**Who may run it.** A command that acts on the server rather than answering a question can
-say what the person running it must hold:
-
-```js
-bot.command(
-  { name: 'setup', description: 'Build a server',
-    requiredPermissions: ['manage_channels', 'manage_roles'] },
-  async (i) => { /* ... */ },
-);
-```
-
-All of them are required, not any of them; an administrator bypasses the check. Somebody
-without them is refused, and the command is not offered to them in the app at all. This is
-separate from the bot own permissions, which decide what the bot may do once asked and say
-nothing about who may ask: a /setup that rebuilds a server is open to every member who can
-talk in a channel until it says otherwise here.
-
-## 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.defer({ ephemeral: true }); // ...and the answer will be private
-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 command or form handler takes longer than eight seconds, the SDK defers on its behalf
-rather than let the window run out. A button handler is left alone: a press is answered by
-rewriting the message it sits on, and that is only available before the interaction has
-been answered at all, so deferring for you would trade a late answer for one that cannot be
-given. A slow press should defer and `followUp`.
-
-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' },
-    ],
-  }],
-});
-
-// 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`, `danger` and `link` (which takes a `url` instead
-of a `custom_id`). Anything else draws as a plain button rather than not at all. 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)` | |
-| `thinking(channelId)` | Says "working on it" until you call the function it returns. The client shows a bot as **thinking**, not typing, and drops it three seconds after the last one, so this repeats for you. Nothing it does can fail an answer. |
-| `channels()`, `createChannel(c)`, `updateChannel(id, c)`, `deleteChannel(id)` | |
-| `categories()`, `createCategory(c)`, `updateCategory(id, c)`, `deleteCategory(id)` | |
-| `channelPermissions(channelId)` | who can do what in one channel |
-| `setChannelPermission(channelId, rule)`, `removeChannelPermission(channelId, id)` | |
-| `roles()`, `createRole(r)`, `updateRole(id, r)`, `deleteRole(id)` | |
-| `members()`, `addRole(userId, roleId)`, `removeRole(userId, roleId)` | |
-| `member(userId)` | one member with their roles, held for a minute. There is no route for one member, so the alternative is re-reading the whole community before every permission check. `member(id, { fresh: true })` skips the held copy, `forgetMembers()` drops it. |
-| `setNickname(userId, name)` | `'@me'` renames the bot itself |
-| `kick(userId)`, `ban(userId, reason)`, `unban(userId)`, `bans()` | |
-| `timeout(userId, seconds, reason)`, `clearTimeout(userId)` | |
-| `joinVoice(channelId, { speaking })`, `setVoiceState(...)`, `leaveVoice(channelId)` | |
-| `voiceToken(channelId)` | a media token, for publishing audio |
-| `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.
-
-## Who somebody is
-
-Two facts a community does not hold. Its members table knows when somebody joined and
-nothing else, so a bot that decides anything about a person asks Core.
-
-```js
-const profile = await bot.core.profile(userId);   // last_seen, is_guest, username, ...
-const name = await bot.core.displayName(userId);  // what to call them, remembered
-const owner = (await bot.core.community(serverId))?.owner_id;
-```
-
-| | |
-|---|---|
-| `profile(userId)` | the public profile, or `null` |
-| `displayName(userId)` | their name, cached for ten minutes, or `null` |
-| `community(serverId)` | a community's public row, which is where its owner is named, or `null` |
-| `request(method, path, body)` | anything else on Core, with the bot's own credentials |
-
-All three answer `null` rather than throwing, which is the opposite of everything else here
-and is the point: a bot sweeping two hundred members must not lose the pass to one lookup,
-and somebody it knows nothing about is somebody to leave alone. `displayName` returns `null`
-rather than a word like "someone", because the word belongs to your bot, in its own language.
-
-**`member()` is a saving, not a source of truth about what somebody may do.** The held copy
-carries roles, so a role taken away a minute ago is still in it. It cannot grant anybody
-anything, because the community server checks every action against the real roles and
-refuses it regardless. What it can do is let your bot offer somebody a thing the server
-will then refuse, or act on its own judgement where your 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.
-
-Knowing the owner matters more than it looks. 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.
-
-## A bot that sets a server up
-
-Everything a server is made of is reachable, so the first bot most people want to write is
-the one that builds the whole thing from a template:
-
-```js
-import { Bot, Permissions } from '@tusile/bot';
-
-bot.command({ name: 'setup', description: 'Build the standard channels' }, async (i) => {
-  await i.defer();
-  const s = i.server;
-
-  const staff = await s.createRole({ name: 'Staff', permissions: Permissions.view_channel });
-  const team = await s.createCategory({ name: 'Team' });
-
-  const general = await s.createChannel({ name: 'general', type: 'text', category_id: team.id });
-  const private_ = await s.createChannel({ name: 'staff-only', type: 'text', category_id: team.id });
-
-  // The part that makes it a server rather than a pile of channels.
-  const [everyone] = (await s.roles()).filter((r) => r.is_default);
-  await s.setChannelPermission(private_.id, { role: everyone.id, deny: 'view_channel' });
-  await s.setChannelPermission(private_.id, { role: staff.id, allow: 'view_channel' });
-
-  await s.addRole(i.userId, staff.id);
-  await s.send(general.id, 'Set up. #staff-only is for the Staff role.');
-  await i.editReply('Done.');
-});
-```
-
-`allow` and `deny` take a permission name, a list of names, or a number:
-`view_channel`, `send_messages`, `manage_messages`, `manage_channels`, `manage_roles`,
-`manage_members`, `administrator`, `connect`, `speak`, `mute_members`, `deafen_members`,
-`manage_server`, `create_invite`, `attach_files`, `stream`, `use_camera`, `manage_emojis`,
-`manage_emoji_policy`, `timeout_members`. A name this package does not know throws, rather
-than quietly denying nothing.
-
-Two rules the server keeps, whatever the bot asks for: it cannot create a role above its
-own, and it cannot allow, in a channel, a permission it does not hold itself. Denying is
-not capped, so a bot locking a channel down does not need every permission it switches off.
-
-## Playing audio
-
-A bot can be heard, not just seen. `joinVoice` puts it in the channel; the audio itself
-goes through LiveKit, the same path the app uses:
-
-```bash
-npm install @livekit/rtc-node
-```
-
-```js
-import { Room, AudioSource, LocalAudioTrack, TrackPublishOptions, TrackSource, AudioFrame }
-  from '@livekit/rtc-node';
-
-bot.command({ name: 'play', description: 'Play a tone' }, async (i) => {
-  const channelId = i.options.channel;
-  await i.server.joinVoice(channelId, { speaking: true });
-  const { token, url } = await i.server.voiceToken(channelId);
-
-  const room = new Room();
-  await room.connect(url, token, { autoSubscribe: false });
-
-  const source = new AudioSource(48000, 1);
-  const options = new TrackPublishOptions();
-  options.source = TrackSource.SOURCE_MICROPHONE;
-  await room.localParticipant.publishTrack(
-    LocalAudioTrack.createAudioTrack('tone', source), options);
-
-  // 10 ms frames of signed 16-bit samples at 48 kHz, which is what a decoder hands you.
-  let phase = 0;
-  for (let n = 0; n < 300; n++) {
-    const samples = new Int16Array(480);
-    for (let s = 0; s < 480; s++) {
-      samples[s] = Math.round(Math.sin(phase) * 12000);
-      phase += (2 * Math.PI * 440) / 48000;
-    }
-    await source.captureFrame(new AudioFrame(samples, 48000, 1, 480));
-  }
-
-  await room.disconnect();
-  await i.server.setVoiceState(channelId, { speaking: false });
-  await i.reply('Done.');
-});
-```
-
-`speaking: true` is what the channel shows. Without it the bot is drawn with the
-crossed-out microphone while it plays, which is right for a bot that only listens and
-wrong for one that is making a sound. It needs **Connect** to be in the channel and
-**Speak** to claim a live microphone; the server refuses the claim without it, because
-presence is a promise to the room that it can be heard.
-
-A bot that plays a file decodes it to the same frames: 48 kHz, signed 16-bit, mono or
-stereo. Nothing in Tusile transcodes for you.
-
-## 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.
-
-## Tokens
-
-A community issues a token good for an hour, and the socket it was minted for stays up for
-days. The SDK mints another the moment a community refuses one, so a bot that has been
-running since yesterday keeps working; there is nothing to do about this in bot code.
-
-## 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.
-Credentials Core refuses stop it entirely, rather than being retried: a deleted bot or a
-rotated secret will not come right on its own, and a bot asking every thirty seconds until
-somebody notices fills a log and spends rate limit the working bots need.
-
-## 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,
-});
-```
-
-## If you write your own loop
-
-Two things the `Bot` class handles that are easy to get wrong, and both were found in
-production rather than reasoned about.
-
-**A community keeps its id when it moves and only its `api_url` changes.** Reconcile your
-connections on the address as well as the id. A loop that keys on `server_id` alone holds a
-socket to the host the community has left, which usually goes on answering, so nothing
-errors and nothing reconnects. The bot reads as offline in that community until it is
-restarted.
-
-**A close is not always a failure.** `bot_uninstalled` means stop; `server_retired` means
-the community has left that box, so ask Core for the list again before reconnecting rather
-than redialling the address you hold. Everything else is worth a backoff.
-
-## 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**
-
-MIT licensed.
+# @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. Its permissions are checked the same way yours
+are, and it cannot see a channel it has not been given access to.
+
+## Saying what your bot needs
+
+Whoever adds your bot is shown the permissions it asks for, and ticks what they are willing
+to allow. It gets exactly that, so asking for less is a bot more people will add.
+
+```js
+const bot = new Bot({
+  permissions: ['view_channel', 'send_messages', 'manage_channels', 'connect', 'speak'],
+});
+```
+
+Declaring it here rather than in a form means the list lives next to the commands that need
+it, and a command that grows a new requirement says so in the same commit. The names are the
+ones in `Permissions`; an unknown name throws at startup rather than quietly dropping out of
+the list somebody is shown. Your bot's owner can tick the same list in **Settings → Bots**,
+and a declaration in code wins when the bot starts.
+
+A declaration grants nothing by itself. A bot that asks for nothing gets whatever everybody
+on that community can do, which is where bots started out before any of this existed. To
+give a bot more than it asked for, give it a role, the way you would anybody else.
+
+Ask for `view_channel` if your bot does anything at all in a channel. It is the floor: a bot
+that cannot see a channel is not handed the interactions that happen there, so a bot that
+asks only for `send_messages` will be added, will look installed, and will answer nothing.
+
+## 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.
+
+**Who may run it.** A command that acts on the server rather than answering a question can
+say what the person running it must hold:
+
+```js
+bot.command(
+  { name: 'setup', description: 'Build a server',
+    requiredPermissions: ['manage_channels', 'manage_roles'] },
+  async (i) => { /* ... */ },
+);
+```
+
+All of them are required, not any of them; an administrator bypasses the check. Somebody
+without them is refused, and the command is not offered to them in the app at all. This is
+separate from the bot own permissions, which decide what the bot may do once asked and say
+nothing about who may ask: a /setup that rebuilds a server is open to every member who can
+talk in a channel until it says otherwise here.
+
+## 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.defer({ ephemeral: true }); // ...and the answer will be private
+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 command or form handler takes longer than eight seconds, the SDK defers on its behalf
+rather than let the window run out. A button handler is left alone: a press is answered by
+rewriting the message it sits on, and that is only available before the interaction has
+been answered at all, so deferring for you would trade a late answer for one that cannot be
+given. A slow press should defer and `followUp`.
+
+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' },
+    ],
+  }],
+});
+
+// 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`, `danger` and `link` (which takes a `url` instead
+of a `custom_id`). Anything else draws as a plain button rather than not at all. 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)` | |
+| `thinking(channelId)` | Says "working on it" until you call the function it returns. The client shows a bot as **thinking**, not typing, and drops it three seconds after the last one, so this repeats for you. Nothing it does can fail an answer. |
+| `channels()`, `createChannel(c)`, `updateChannel(id, c)`, `deleteChannel(id)` | |
+| `categories()`, `createCategory(c)`, `updateCategory(id, c)`, `deleteCategory(id)` | |
+| `channelPermissions(channelId)` | who can do what in one channel |
+| `setChannelPermission(channelId, rule)`, `removeChannelPermission(channelId, id)` | |
+| `roles()`, `createRole(r)`, `updateRole(id, r)`, `deleteRole(id)` | |
+| `members()`, `addRole(userId, roleId)`, `removeRole(userId, roleId)` | |
+| `member(userId)` | one member with their roles, held for a minute. There is no route for one member, so the alternative is re-reading the whole community before every permission check. `member(id, { fresh: true })` skips the held copy, `forgetMembers()` drops it. |
+| `setNickname(userId, name)` | `'@me'` renames the bot itself |
+| `kick(userId)`, `ban(userId, reason)`, `unban(userId)`, `bans()` | |
+| `timeout(userId, seconds, reason)`, `clearTimeout(userId)` | |
+| `joinVoice(channelId, { speaking })`, `setVoiceState(...)`, `leaveVoice(channelId)` | |
+| `voiceToken(channelId)` | a media token, for publishing audio |
+| `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.
+
+## Who somebody is
+
+Two facts a community does not hold. Its members table knows when somebody joined and
+nothing else, so a bot that decides anything about a person asks Core.
+
+```js
+const profile = await bot.core.profile(userId);   // last_seen, is_guest, username, ...
+const name = await bot.core.displayName(userId);  // what to call them, remembered
+const owner = (await bot.core.community(serverId))?.owner_id;
+```
+
+| | |
+|---|---|
+| `profile(userId)` | the public profile, or `null` |
+| `displayName(userId)` | their name, cached for ten minutes, or `null` |
+| `community(serverId)` | a community's public row, which is where its owner is named, or `null` |
+| `request(method, path, body)` | anything else on Core, with the bot's own credentials |
+
+All three answer `null` rather than throwing, which is the opposite of everything else here
+and is the point: a bot sweeping two hundred members must not lose the pass to one lookup,
+and somebody it knows nothing about is somebody to leave alone. `displayName` returns `null`
+rather than a word like "someone", because the word belongs to your bot, in its own language.
+
+**`member()` is a saving, not a source of truth about what somebody may do.** The held copy
+carries roles, so a role taken away a minute ago is still in it. It cannot grant anybody
+anything, because the community server checks every action against the real roles and
+refuses it regardless. What it can do is let your bot offer somebody a thing the server
+will then refuse, or act on its own judgement where your 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.
+
+Knowing the owner matters more than it looks. 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.
+
+## A bot that sets a server up
+
+Everything a server is made of is reachable, so the first bot most people want to write is
+the one that builds the whole thing from a template:
+
+```js
+import { Bot, Permissions } from '@tusile/bot';
+
+bot.command({ name: 'setup', description: 'Build the standard channels' }, async (i) => {
+  await i.defer();
+  const s = i.server;
+
+  const staff = await s.createRole({ name: 'Staff', permissions: Permissions.view_channel });
+  const team = await s.createCategory({ name: 'Team' });
+
+  const general = await s.createChannel({ name: 'general', type: 'text', category_id: team.id });
+  const private_ = await s.createChannel({ name: 'staff-only', type: 'text', category_id: team.id });
+
+  // The part that makes it a server rather than a pile of channels.
+  const [everyone] = (await s.roles()).filter((r) => r.is_default);
+  await s.setChannelPermission(private_.id, { role: everyone.id, deny: 'view_channel' });
+  await s.setChannelPermission(private_.id, { role: staff.id, allow: 'view_channel' });
+
+  await s.addRole(i.userId, staff.id);
+  await s.send(general.id, 'Set up. #staff-only is for the Staff role.');
+  await i.editReply('Done.');
+});
+```
+
+`allow` and `deny` take a permission name, a list of names, or a number:
+`view_channel`, `send_messages`, `manage_messages`, `manage_channels`, `manage_roles`,
+`manage_members`, `administrator`, `connect`, `speak`, `mute_members`, `deafen_members`,
+`manage_server`, `create_invite`, `attach_files`, `stream`, `use_camera`, `manage_emojis`,
+`manage_emoji_policy`, `timeout_members`. A name this package does not know throws, rather
+than quietly denying nothing.
+
+Two rules the server keeps, whatever the bot asks for: it cannot create a role above its
+own, and it cannot allow, in a channel, a permission it does not hold itself. Denying is
+not capped, so a bot locking a channel down does not need every permission it switches off.
+
+## Playing audio
+
+A bot can be heard, not just seen. `joinVoice` puts it in the channel; the audio itself
+goes through LiveKit, the same path the app uses:
+
+```bash
+npm install @livekit/rtc-node
+```
+
+```js
+import { Room, AudioSource, LocalAudioTrack, TrackPublishOptions, TrackSource, AudioFrame }
+  from '@livekit/rtc-node';
+
+bot.command({ name: 'play', description: 'Play a tone' }, async (i) => {
+  const channelId = i.options.channel;
+  await i.server.joinVoice(channelId, { speaking: true });
+  const { token, url } = await i.server.voiceToken(channelId);
+
+  const room = new Room();
+  await room.connect(url, token, { autoSubscribe: false });
+
+  const source = new AudioSource(48000, 1);
+  const options = new TrackPublishOptions();
+  options.source = TrackSource.SOURCE_MICROPHONE;
+  await room.localParticipant.publishTrack(
+    LocalAudioTrack.createAudioTrack('tone', source), options);
+
+  // 10 ms frames of signed 16-bit samples at 48 kHz, which is what a decoder hands you.
+  let phase = 0;
+  for (let n = 0; n < 300; n++) {
+    const samples = new Int16Array(480);
+    for (let s = 0; s < 480; s++) {
+      samples[s] = Math.round(Math.sin(phase) * 12000);
+      phase += (2 * Math.PI * 440) / 48000;
+    }
+    await source.captureFrame(new AudioFrame(samples, 48000, 1, 480));
+  }
+
+  await room.disconnect();
+  await i.server.setVoiceState(channelId, { speaking: false });
+  await i.reply('Done.');
+});
+```
+
+`speaking: true` is what the channel shows. Without it the bot is drawn with the
+crossed-out microphone while it plays, which is right for a bot that only listens and
+wrong for one that is making a sound. It needs **Connect** to be in the channel and
+**Speak** to claim a live microphone; the server refuses the claim without it, because
+presence is a promise to the room that it can be heard.
+
+A bot that plays a file decodes it to the same frames: 48 kHz, signed 16-bit, mono or
+stereo. Nothing in Tusile transcodes for you.
+
+## 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.
+
+## Tokens
+
+A community issues a token good for an hour, and the socket it was minted for stays up for
+days. The SDK mints another the moment a community refuses one, so a bot that has been
+running since yesterday keeps working; there is nothing to do about this in bot code.
+
+## 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.
+Credentials Core refuses stop it entirely, rather than being retried: a deleted bot or a
+rotated secret will not come right on its own, and a bot asking every thirty seconds until
+somebody notices fills a log and spends rate limit the working bots need.
+
+## 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,
+});
+```
+
+## If you write your own loop
+
+Two things the `Bot` class handles that are easy to get wrong, and both were found in
+production rather than reasoned about.
+
+**A community keeps its id when it moves and only its `api_url` changes.** Reconcile your
+connections on the address as well as the id. A loop that keys on `server_id` alone holds a
+socket to the host the community has left, which usually goes on answering, so nothing
+errors and nothing reconnects. The bot reads as offline in that community until it is
+restarted.
+
+**A close is not always a failure.** `bot_uninstalled` means stop; `server_retired` means
+the community has left that box, so ask Core for the list again before reconnecting rather
+than redialling the address you hold. Everything else is worth a backoff.
+
+## 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**
+
+MIT licensed.