@tusile/bot 0.1.2 → 0.4.0

package/LICENSE

@@ -1,21 +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.
+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

@@ -36,9 +36,33 @@ That bot is live on every community that has added it, and joins new ones by its
 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.
+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
 
@@ -70,6 +94,23 @@ 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
@@ -79,6 +120,7 @@ bot did not respond".
 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();
@@ -173,13 +215,19 @@ bot.command({ name: 'recap', description: 'What was said here' }, async (i) => {
 | `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)`, `leaveVoice(channelId)`, `voiceToken(channelId)` | |
+| `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 |
 
@@ -189,6 +237,134 @@ 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
@@ -202,6 +378,12 @@ 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.
@@ -210,6 +392,9 @@ unreachable, so a redeploy does not read as a lost message. A bad request is not
 `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
 
@@ -227,6 +412,21 @@ const client = new ServerClient({
 });
 ```
 
+## 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

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@tusile/bot",
-  "version": "0.1.2",
+  "version": "0.4.0",
   "description": "Write a Tusile bot: slash commands, buttons, forms and voice, over an outbound WebSocket.",
   "type": "module",
   "main": "src/index.js",