npm - @tusile/bot - Versions diffs - 0.4.0 → 0.6.0 - Mend

@tusile/bot 0.4.0 → 0.6.0

This diff represents the content of publicly available package versions that have been released to one of the supported registries. The information contained in this diff is provided for informational purposes only and reflects changes between package versions as they appear in their respective public registries.

Files changed (6) hide show

package/README.md CHANGED Viewed

@@ -1,439 +1,441 @@
-# @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.
+Since 0.6.0 the same list is also sent to Core, so the bot directory shows your commands to
+somebody deciding whether to add the bot.
+**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.