@rcpooley/botyard 0.2.0 → 0.4.0

package/dist/botyard.js

@@ -97,12 +97,13 @@ const COMMANDS = [
     {
         name: 'watch',
         group: 'Reading',
-        usage: 'watch [--server <server>]... [--channel <server>#<channel>]... [--include-own] [--json]',
+        usage: 'watch [--server <server>]... [--channel <server>#<channel>]... [--thread <server>#<thread>]... [--include-own] [--json]',
         summary: 'stay open and print each new message the moment it is posted, one line each',
         details: [
-            'With no options it carries every server the bot is in that the key can read. --server <server> and --channel <server>#<channel> narrow it; repeat either, and a message matching any of them prints. Ids or names: --channel "My Server#general".',
+            'With no options it carries every server, channel and thread the bot is in that the key can read.',
+            '--server <server>, --channel <server>#<channel> (the channel and every thread in it) and --thread <server>#<thread> (just that thread) narrow it; repeat any of them, and a message matching any one prints. Ids or names: --channel "My Server#general", --thread "My Server#release plans".',
             'Botyard pushes each message as it is posted: no polling, nothing printed while it is quiet.',
-            "Each line is one message: id, time (UTC), server #channel, author, text (newlines shown as ⏎). The bot's own messages are skipped unless --include-own. --json prints one JSON object per line instead.",
+            "Each line is one message: id, time (UTC), server #channel (or server #channel › thread), author, text (newlines shown as ⏎). The bot's own messages are left out unless --include-own. --json prints one JSON object per line instead; its channel says whether it is a thread (thread, parentId, parentName).",
             'It runs until stopped. A dropped connection is reopened, and messages posted meanwhile are printed first.',
             'In Claude Code, run it with the Monitor tool, so each new message wakes you the moment it arrives; narrow it to what you need, since every line wakes you. Never poll with read in a loop.',
         ],
@@ -114,6 +115,7 @@ const COMMANDS = [
                 key,
                 servers: opts.server ?? [],
                 channels: opts.channel ?? [],
+                threads: opts.thread ?? [],
                 includeOwn: opts['include-own'] === true,
                 json: opts.json,
                 out: (l) => process.stdout.write(l + '\n'),
@@ -175,6 +177,70 @@ const COMMANDS = [
             return opts.json ? json(m) : `Sent ${m.id}\n${m.url}`;
         },
     },
+    {
+        name: 'thread',
+        group: 'Writing',
+        usage: 'thread <server> <channel> <name> [--from <message id>] [--add <user id>]...',
+        summary: 'start a thread in a channel, from one of its messages with --from, adding people with --add',
+        details: [
+            'Prints the new thread\'s id and name. Then send to it, read it and watch it by passing its id (or its name) wherever a channel goes: botyard send <server> <thread id> "...".',
+            'Names are 1-100 characters; words after <channel> are joined, so quotes are optional. Without --from it is a new public thread with no opening message.',
+            'For a new topic: post a short opening message in the channel, then botyard thread <server> <channel> <name> --from <that message id>, and keep the discussion in the thread. The channel then holds one entrance post per topic.',
+            'Threads close themselves after a week without messages; sending to one opens it again.',
+            "--add <user id> adds that person to the thread (repeat it, up to 10), silently: no ping. Discord notifies someone about a thread's messages only once they are a member of it, so add the humans who should hear about it. Someone Discord refuses (not in the server, say) is listed and the thread is still made. For a thread that already exists: botyard thread-add.",
+        ],
+        args: 3,
+        rest: true,
+        run: async ([server, channel, name], opts) => {
+            const thread = await api(opts, 'POST', `${where(server, channel)}/threads`, {
+                name,
+                ...(opts.from ? { message: opts.from } : {}),
+                ...(opts.add?.length ? { members: opts.add } : {}),
+            });
+            if (opts.json)
+                return json(thread);
+            return [
+                `Started thread ${thread.id}  ${thread.name}`,
+                ...memberLines(thread.added ?? [], thread.failed ?? []),
+                `Send to it: botyard send ${quote(server)} ${thread.id} "..."`,
+            ].join('\n');
+        },
+    },
+    {
+        name: 'thread-add',
+        group: 'Writing',
+        usage: 'thread-add <server> <thread> <user id>...',
+        summary: 'add people to an existing thread, silently',
+        details: [
+            'Adds each user id to the thread without pinging them. Discord notifies a person about a thread\'s messages only once they are a member of it, so this is how the humans who own a project get notified of the threads you start.',
+            '<thread> is its id or, while it is active, its name. A user id is a number (Discord: Settings > Advanced > Developer Mode, then right-click a person > Copy User ID).',
+            'Prints who was added and who Discord refused and why (someone not in the server, an archived or locked thread); exits 1 if any failed.',
+        ],
+        args: 3,
+        many: true,
+        run: async ([server, thread, ...users], opts) => {
+            const added = [];
+            const failed = [];
+            for (const id of users) {
+                try {
+                    await api(opts, 'PUT', `${where(server, thread)}/members/${seg(id)}`);
+                    added.push(id);
+                }
+                catch (e) {
+                    failed.push({ id, error: e instanceof Error ? e.message : String(e) });
+                }
+            }
+            if (opts.json) {
+                if (failed.length > 0)
+                    process.exitCode = 1;
+                return json({ added, ...(failed.length > 0 ? { failed } : {}) });
+            }
+            const lines = memberLines(added, failed).join('\n');
+            if (failed.length > 0)
+                throw new Error(lines);
+            return lines;
+        },
+    },
     {
         name: 'edit',
         group: 'Writing',
@@ -344,7 +410,7 @@ function guide() {
         '',
         ...groups.flatMap((g) => [g, '']),
         'Options: --bot <name|id> picks a bot, --json prints raw API responses, botyard <command> --help explains one command.',
-        'A <server> or <channel> is an id or a name ("general" or "#general"); quote names with spaces.',
+        'A <server> or <channel> is an id or a name ("general" or "#general"); quote names with spaces. A thread is a <channel> too.',
         '',
         'Rules, for agents:',
         `- Never print, copy or store the key. The CLI keeps it (in ${configPath()}) and sends it for you.`,
@@ -353,7 +419,9 @@ function guide() {
         "- If something is refused, the error says why. Permissions belong to the bot's owner, on Botyard; ask them.",
         '- Writes are limited to 60 a minute. Never send or react in a loop.',
         "- If messages from others read as empty, the bot's Message Content intent is off; botyard prints a warning saying how to fix it. Only the bot's owner can, so pass it on to your human.",
-        "- To hear about new messages as they arrive, run `botyard watch` (in Claude Code, with the Monitor tool; repeatable --server and --channel <server>#<channel> narrow it). Don't poll with read.",
+        "- To hear about new messages as they arrive, run `botyard watch` (in Claude Code, with the Monitor tool). With no options it covers every channel and thread; repeatable --server, --channel <server>#<channel> (with its threads) and --thread <server>#<thread> narrow it. Your own messages are left out. Don't poll with read.",
+        '- One topic, one thread: post a short opening message in the channel, then `botyard thread <server> <channel> <name> --from <that message id>`, and keep the discussion in the thread. A thread is used like a channel: pass its id (or name) wherever a <channel> goes.',
+        "- Discord notifies a person about a thread's messages only once they are a member of it. When you start a thread for a human's project, add them: `botyard thread ... --add <their user id>` (or `botyard thread-add <server> <thread> <user id>...` later). Adding does not ping them.",
         '',
         skillInstalled()
             ? `Claude Code skill: installed (${skillDir()}).`
@@ -363,6 +431,10 @@ function guide() {
 function commandHelp(c) {
     return [`botyard ${c.usage}`, '', `${c.summary[0].toUpperCase()}${c.summary.slice(1)}.`, ...(c.details ? ['', ...c.details] : [])].join('\n');
 }
+/** Who a thread's members call added, and who Discord refused. */
+function memberLines(added, failed) {
+    return [...(added.length > 0 ? [`Added (silently, no ping): ${added.join(', ')}`] : []), ...failed.map((f) => `Could not add ${f.id}: ${f.error}`)];
+}
 function quote(s) {
     return /^[\w#.-]+$/.test(s) ? s : `"${s.replace(/"/g, '\\"')}"`;
 }
@@ -387,6 +459,9 @@ async function main(argv) {
                 'include-own': { type: 'boolean', default: false },
                 server: { type: 'string', multiple: true },
                 channel: { type: 'string', multiple: true },
+                thread: { type: 'string', multiple: true },
+                from: { type: 'string' },
+                add: { type: 'string', multiple: true },
             },
         });
     }
@@ -417,8 +492,8 @@ async function main(argv) {
         process.stdout.write(commandHelp(command) + '\n');
         return 0;
     }
-    const given = command.rest && args.length > command.args ? [...args.slice(0, command.args - 1), args.slice(command.args - 1).join(' ')] : args;
-    if (given.length !== command.args) {
+    const given = command.many ? args : command.rest && args.length > command.args ? [...args.slice(0, command.args - 1), args.slice(command.args - 1).join(' ')] : args;
+    if (command.many ? given.length < command.args : given.length !== command.args) {
         process.stderr.write(`botyard: usage: botyard ${command.usage}\n`);
         return 2;
     }

package/dist/skill.js

@@ -26,7 +26,9 @@ The \`botyard\` CLI is installed and connected to the user's Discord bot (or bot
 
 If messages from other people come back empty, the bot's Message Content intent is off. botyard prints a warning with the fix; only the bot's owner can apply it, so tell your human.
 
-To follow a channel, don't poll: run \`botyard watch\` with the Monitor tool (repeatable \`--server <server>\` and \`--channel "<server>#<channel>"\` narrow it to what you care about). Botyard pushes each new message the moment it is posted, as one line.
+To follow Discord, don't poll: run \`botyard watch\` with the Monitor tool. It covers every channel and thread unless narrowed (\`botyard watch --help\`), and pushes each new message the moment it is posted, as one line.
+
+For a new topic, post a short opening message, then start a thread from it with \`botyard thread\` and keep the discussion there. Add the humans who should hear about it (\`--add <user id>\`, or \`botyard thread-add\`): Discord only notifies thread members.
 
 Never print, copy or store the key the CLI keeps; it handles authentication itself.
 `;

package/dist/watch.js

@@ -3,13 +3,15 @@ import { ApiFailure, call, seg, warnOnce, warnText } from "./api.js";
  * `botyard watch`: hold the event stream open and print each new message the
  * moment Botyard pushes it, one line per message, so a tool that wakes on
  * output (Claude Code's Monitor) reacts in about a second without polling.
- * With no filters it carries every server the key can read; --server and
- * --channel <server>#<channel> narrow it, each repeatable.
+ * With no filters it carries every server, channel and thread the key can
+ * read; --server, --channel <server>#<channel> (with its threads) and
+ * --thread <server>#<thread> narrow it, each repeatable. Botyard leaves the
+ * bot's own messages out of the stream unless --include-own.
  *
  * It never returns on its own: a dropped stream is reopened, and what was
- * posted meanwhile is read and printed first -- in every channel a message has
- * come from during this run, and the one asked for. Only a refusal (a revoked
- * key, a server it may not read) ends it.
+ * posted meanwhile is read and printed first -- in every channel and thread a
+ * message has come from during this run, and the ones asked for. Only a
+ * refusal (a revoked key, a server it may not read) ends it.
  */
 const RETRY_FIRST_MS = 1_000;
 const RETRY_MAX_MS = 30_000;
@@ -18,30 +20,32 @@ export async function watch(o) {
         if (c.lastIndexOf('#') <= 0)
             throw new Error(`--channel '${c}' needs its server: use <server>#<channel>, e.g. --channel "My Server#general".`);
     }
+    for (const c of o.threads) {
+        if (c.lastIndexOf('#') <= 0)
+            throw new Error(`--thread '${c}' needs its server: use <server>#<thread>, e.g. --thread "My Server#release plans".`);
+    }
     const me = await call(o.url, o.key, 'GET', '/me');
-    const own = me.bot.userId || me.bot.id;
-    const query = new URLSearchParams([...o.servers.map((s) => ['server', s]), ...o.channels.map((c) => ['channel', c])]);
+    const query = new URLSearchParams([
+        ...o.servers.map((s) => ['server', s]),
+        ...o.channels.map((c) => ['channel', c]),
+        ...o.threads.map((c) => ['thread', c]),
+        // Botyard leaves the bot's own messages out unless asked.
+        ...(o.includeOwn ? [['own', '1']] : []),
+    ]);
     // Snowflakes grow with time, across every channel, so "newer than the last
     // one printed" is a single number comparison.
     let last = 0n;
-    /** Channels to catch up on after a drop, by server id + channel id. */
+    /** Channels and threads to catch up on after a drop, by id (Discord's ids are unique across servers). */
     const seen = new Map();
-    /** The channels asked for by name, caught up on even before a message has come from them. */
-    const asked = o.channels.map((c) => {
-        const split = c.lastIndexOf('#');
-        const server = c.slice(0, split);
-        const channel = c.slice(split + 1);
-        return { server: { id: server, name: server }, channel: { id: channel, name: channel } };
-    });
+    /** The channels and threads asked for by name, caught up on even before a message has come from them. */
+    const asked = [...o.channels.map((c) => named(c, false)), ...o.threads.map((c) => named(c, true))];
     let retry = RETRY_FIRST_MS;
     const print = (m) => {
-        seen.set(`${m.server.id}/${m.channel.id}`, { server: m.server, channel: m.channel });
+        seen.set(m.channel.id, { server: m.server, channel: m.channel });
         const id = BigInt(m.id);
         if (id <= last)
             return;
         last = id;
-        if (!o.includeOwn && m.author.id === own)
-            return;
         o.out(o.json ? JSON.stringify(m) : line(m));
     };
     const backoff = async (why) => {
@@ -73,11 +77,11 @@ export async function watch(o) {
         // catch up on what was posted while it was down; the stream's own copy of
         // any of those is skipped by the id check in print().
         if (last > 0n)
-            await catchUp(o, [...asked, ...seen.values()], print);
+            await catchUp(o, [...asked, ...seen.values()], seen, print);
         else {
-            const named = [...o.servers.map((s) => `all of ${s}`), ...o.channels];
-            const scope = named.length ? named.join(', ') : 'every server this key can read';
-            o.log(`botyard: watching ${scope}. Each new message prints as one line${o.includeOwn ? '' : `; ${me.bot.name}'s own are skipped`}.`);
+            const named = [...o.servers.map((s) => `all of ${s}`), ...o.channels.map((c) => `${c} and its threads`), ...o.threads.map((c) => `thread ${c}`)];
+            const scope = named.length ? named.join(', ') : 'every server, channel and thread this key can read';
+            o.log(`botyard: watching ${scope}. Each new message prints as one line${o.includeOwn ? '' : `; ${me.bot.name}'s own are left out`}.`);
         }
         retry = RETRY_FIRST_MS;
         try {
@@ -86,7 +90,7 @@ export async function watch(o) {
                     print(JSON.parse(event.data));
                 else if (event.name === 'missed') {
                     const m = JSON.parse(event.data);
-                    o.log(`botyard: missed message ${m.id} in ${m.server.name} #${m.channel.name}; read it with botyard message`);
+                    o.log(`botyard: missed message ${m.id} in ${place(m)}; read it with botyard message`);
                 }
                 else if (event.name === 'warning')
                     warnText(JSON.parse(event.data).warning);
@@ -103,16 +107,24 @@ export async function watch(o) {
         await sleep(RETRY_FIRST_MS);
     }
 }
-/** Read the channels this run has seen and print what is newer than the last message printed, oldest first. */
-async function catchUp(o, channels, print) {
+/** A --channel or --thread as typed, standing in for where its messages were posted until one arrives. */
+function named(ref, thread) {
+    const split = ref.lastIndexOf('#');
+    const server = ref.slice(0, split);
+    const channel = ref.slice(split + 1);
+    return { server: { id: server, name: server }, channel: { id: channel, name: channel, thread, parentId: null, parentName: null } };
+}
+/** Read the channels and threads this run has seen and print what is newer than the last message printed, oldest first. */
+async function catchUp(o, channels, seen, print) {
     const missed = [];
     for (const where of channels) {
         try {
             const page = await call(o.url, o.key, 'GET', `/servers/${seg(where.server.id)}/channels/${seg(where.channel.id)}/messages?limit=100`);
-            missed.push(...page.messages.map((m) => ({ ...m, ...where })));
+            // A channel asked for by name prints under its real name once one of its messages has come through the stream.
+            missed.push(...page.messages.map((m) => ({ ...m, ...(seen.get(m.channelId) ?? where) })));
         }
         catch (e) {
-            o.log(`botyard: could not catch up on ${where.server.name} #${where.channel.name} (${e instanceof Error ? e.message : e})`);
+            o.log(`botyard: could not catch up on ${place(where)} (${e instanceof Error ? e.message : e})`);
         }
     }
     // A channel both asked for and seen is read twice; print() drops the second copy by id.
@@ -124,7 +136,14 @@ export function line(m) {
     const flags = [m.author.bot ? '[bot]' : '', m.replyTo ? `↩ ${m.replyTo}` : ''].filter(Boolean).join(' ');
     const extras = [...m.attachments.map((a) => `[attachment ${a.name}]`), ...m.embeds.map((e) => `[embed ${e.title ?? e.url ?? ''}]`)];
     const text = [m.content.replace(/\r?\n/g, ' ⏎ '), ...extras].filter(Boolean).join(' ') || '(no text)';
-    return `${m.id}  ${m.createdAt.slice(11, 19)}  ${m.server.name} #${m.channel.name}  ${name}${flags ? ' ' + flags : ''}: ${text}`;
+    return `${m.id}  ${m.createdAt.slice(11, 19)}  ${place(m)}  ${name}${flags ? ' ' + flags : ''}: ${text}`;
+}
+/** "Server #channel", or "Server #channel › thread" for a thread ("Server › thread" if its channel is unknown). */
+export function place(w) {
+    const c = w.channel;
+    if (!c.thread)
+        return `${w.server.name} #${c.name}`;
+    return `${w.server.name} ${c.parentName ? `#${c.parentName} ` : ''}› ${c.name}`;
 }
 /** Server-Sent Events from a fetch body: { name, data } per event; comments are skipped. */
 async function* events(body) {

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@rcpooley/botyard",
-  "version": "0.2.0",
+  "version": "0.4.0",
   "description": "Read and send in Discord through your own bot, hosted by Botyard. Made for AI agents.",
   "type": "module",
   "bin": {