@scotthamilton77/discord-bot-lib 0.1.2 → 1.0.0

package/README.md

@@ -10,8 +10,8 @@ TypeScript library for managing Discord bot identities, messaging, and multi-bot
 ## Features
 
 - **Factory construction** -- `Bot.fromConfig()` connects, verifies guilds, and returns a ready bot in one call
-- **Dual receive API** -- event-driven callbacks (`onMention`, `onReply`, `onMessage`) and async iterables (`mentions()`, `replies()`, `messages()`)
-- **Multi-bot management** -- `ConnectorManager` aggregates mentions across bots with lifecycle events
+- **Unified receive API** -- event-driven callback (`onMessage`) and async iterable (`messages()`) with full routing metadata (`isDM`, `isMention`, `isReply`, `replyTo`)
+- **Multi-bot management** -- `ConnectorManager` aggregates messages across bots with lifecycle events
 - **Guided onboarding** -- `BotOnboarding` walks through token validation, server invitation, and permission verification
 - **Message chunking** -- automatically splits messages at paragraph/line/word boundaries to stay within Discord's 2000-char limit
 - **File attachments** -- send files from Buffer or file path, with size validation and filename sanitization
@@ -37,19 +37,14 @@ const bot = await Bot.fromConfig({
   token: process.env.DISCORD_TOKEN!,
 });
 
-// Respond to @mentions
-bot.onMention(async (event) => {
-  await bot.send(event.channelId, `Hello, ${event.author.username}!`);
-});
-
-// Respond to replies to messages this bot sent
-bot.onReply(async (event, original) => {
-  await bot.send(event.channelId, `You replied to my message ${original.messageId}`);
-});
-
-// Listen to all messages in a specific channel
-bot.onMessage("123456789012345678", (event) => {
-  console.log(`${event.author.username}: ${event.content}`);
+// Every incoming message — route by metadata
+bot.onMessage(async (event) => {
+  if (event.isMention) {
+    await bot.send(event.channelId, `Hello, ${event.author.username}!`);
+  }
+  if (event.isReply) {
+    await bot.send(event.channelId, `You replied to my message ${event.replyTo!.messageId}`);
+  }
 });
 
 // Error handling
@@ -58,7 +53,7 @@ bot.on("error", (err) => console.error("Bot error:", err.message));
 
 ## Async Iterables
 
-Every event type is also available as an `AsyncIterable`, useful for sequential processing with `for await`:
+All messages are also available as an `AsyncIterable`, useful for sequential processing with `for await`:
 
 ```typescript
 import { Bot } from "@scotthamilton77/discord-bot-lib";
@@ -70,16 +65,14 @@ const bot = await Bot.fromConfig({
 });
 
 // Process mentions one at a time
-for await (const event of bot.mentions()) {
+for await (const event of bot.messages({ filter: (e) => e.isMention })) {
   await bot.reply(event.channelId, event.messageId, "Got it!");
 }
 ```
 
 ```typescript
-// Filter channel messages with a predicate
-for await (const event of bot.messages("123456789012345678", {
-  filter: (msg) => msg.content.startsWith("!cmd"),
-})) {
+// Filter messages with a predicate
+for await (const event of bot.messages({ filter: (msg) => msg.content.startsWith("!cmd") })) {
   await bot.send(event.channelId, `Command received: ${event.content}`);
 }
 ```
@@ -99,9 +92,11 @@ const botB = await Bot.fromConfig({ id: "b", name: "Bravo", token: TOKEN_B });
 manager.addBot(botA);
 manager.addBot(botB);
 
-// Single handler receives mentions from all bots
-manager.onMention((event, bot) => {
-  console.log(`${bot.name} was mentioned by ${event.author.username}`);
+// Single handler receives all messages from all bots
+manager.onMessage((event, bot) => {
+  if (event.isMention) {
+    console.log(`${bot.name} was mentioned by ${event.author.username}`);
+  }
 });
 
 // Lifecycle events
@@ -266,12 +261,12 @@ const { buffer, filename, contentType } = await downloadAttachment(attachment);
 |---|---|
 | `BotConfig` | Configuration for `Bot.fromConfig()` -- id, name, token, optional intents/channels/cacheSize. |
 | `BotStatus` | `"unregistered" \| "configuring" \| "connecting" \| "verifying" \| "ready" \| "disconnected" \| "failed"` |
-| `MessageEvent` | Incoming message with author, content, channelId, mentions, and `raw` discord.js Message. |
+| `MessageEvent` | Incoming message with routing metadata (`isDM`, `isMention`, `isReply`, `replyTo`), author, content, channelId, mentions, and `raw` discord.js Message. |
 | `SentMessage` | Tracked outgoing message with messageId, channelId, timestamp, and `raw` escape hatch. |
 | `MessageContent` | `string \| { content?: string; embeds?: unknown[]; files?: FileAttachment[] }` |
 | `FetchedMessage` | Lightweight message from `fetchMessages()` / `fetchHistory()`. |
 | `FetchHistoryOptions` | Discriminated union: `{ after: string } \| { before: string }` with optional `limit`. |
-| `MessageFilter` | `(message: MessageEvent) => boolean` predicate for `onMessage()` / `messages()`. |
+| `MessageFilter` | `(message: MessageEvent) => boolean` predicate for `messages({ filter })`. |
 | `FileAttachment` | `{ data: Buffer \| string; name: string }` for sending files. |
 | `OnboardingStep` | Step in the onboarding flow with id, label, instructions, status, and `complete()`. |
 | `AttachmentLike` | Minimal shape for attachment validation utilities. |

package/dist/index.cjs

@@ -43,6 +43,10 @@ var EventBuffer = class {
   buffer = [];
   resolve = null;
   closed = false;
+  onClose;
+  constructor(options) {
+    this.onClose = options?.onClose;
+  }
   push(value) {
     if (this.closed) return;
     if (this.resolve) {
@@ -54,7 +58,9 @@ var EventBuffer = class {
     }
   }
   close() {
+    if (this.closed) return;
     this.closed = true;
+    this.onClose?.();
     if (this.resolve) {
       const r = this.resolve;
       this.resolve = null;
@@ -77,6 +83,10 @@ var EventBuffer = class {
         return new Promise((resolve) => {
           this.resolve = resolve;
         });
+      },
+      return: () => {
+        this.close();
+        return Promise.resolve({ value: void 0, done: true });
       }
     };
   }
@@ -153,9 +163,7 @@ var Bot = class _Bot {
   client;
   sentMessages;
   _connectedAt = null;
-  mentionHandlers = [];
-  replyHandlers = [];
-  channelSubscriptions = /* @__PURE__ */ new Map();
+  messageHandlers = [];
   errorHandlers = [];
   _includeBotMessages;
   constructor(id, name, client, sentMessageCacheSize, includeBotMessages) {
@@ -221,18 +229,10 @@ var Bot = class _Bot {
     );
   }
   async reply(channelId, messageId, content) {
-    const channel = await this.fetchTextChannel(channelId);
+    const { channel, message } = await this.fetchMessage(channelId, messageId, "reply to");
     if (!("send" in channel)) {
       throw new Error(`Channel ${channelId} is not a sendable channel`);
     }
-    let message;
-    try {
-      message = await channel.messages.fetch(messageId);
-    } catch (error) {
-      throw new Error(
-        `Cannot reply to message ${messageId}: ${error instanceof Error ? error.message : String(error)}`
-      );
-    }
     return this.sendPayloads(content, (payload, i) => {
       if (i === 0) {
         return message.reply(payload);
@@ -242,9 +242,8 @@ var Bot = class _Bot {
   }
   // --- Channel operations ---
   async react(channelId, messageId, emoji) {
-    const channel = await this.fetchTextChannel(channelId);
+    const { message } = await this.fetchMessage(channelId, messageId, "react to");
     try {
-      const message = await channel.messages.fetch(messageId);
       await message.react(emoji);
     } catch (error) {
       throw new Error(
@@ -253,9 +252,8 @@ var Bot = class _Bot {
     }
   }
   async editMessage(channelId, messageId, content) {
-    const channel = await this.fetchTextChannel(channelId);
+    const { message } = await this.fetchMessage(channelId, messageId, "edit");
     try {
-      const message = await channel.messages.fetch(messageId);
       await message.edit(content);
     } catch (error) {
       throw new Error(
@@ -306,76 +304,48 @@ var Bot = class _Bot {
     }
   }
   async getMessageAttachments(channelId, messageId) {
-    const channel = await this.fetchTextChannel(channelId);
-    try {
-      const message = await channel.messages.fetch(messageId);
-      return [...message.attachments.values()].map((att) => ({
-        id: att.id,
-        size: att.size,
-        name: att.name,
-        url: att.url,
-        contentType: att.contentType
-      }));
-    } catch (error) {
-      throw new Error(
-        `Cannot fetch attachments for message ${messageId}: ${error instanceof Error ? error.message : String(error)}`
-      );
-    }
+    const { message } = await this.fetchMessage(channelId, messageId, "fetch attachments for");
+    return [...message.attachments.values()].map((att) => ({
+      id: att.id,
+      size: att.size,
+      name: att.name,
+      url: att.url,
+      contentType: att.contentType
+    }));
   }
   // --- Receiving (event-driven) ---
-  onMention(handler) {
-    this.mentionHandlers.push(handler);
-  }
-  onReply(handler) {
-    this.replyHandlers.push(handler);
-  }
-  onMessage(channelId, handlerOrOpts, maybeHandler) {
-    let filter;
-    let handler;
-    if (typeof handlerOrOpts === "function") {
-      handler = handlerOrOpts;
-    } else {
-      filter = handlerOrOpts.filter;
-      if (!maybeHandler) {
-        throw new Error("Handler is required when providing filter options");
-      }
-      handler = maybeHandler;
-    }
-    const subs = this.channelSubscriptions.get(channelId) ?? [];
-    subs.push({ filter, handler });
-    this.channelSubscriptions.set(channelId, subs);
+  onMessage(handler) {
+    this.messageHandlers.push(handler);
+    let removed = false;
+    return () => {
+      if (removed) return;
+      removed = true;
+      const index = this.messageHandlers.indexOf(handler);
+      if (index !== -1) this.messageHandlers.splice(index, 1);
+    };
   }
   // --- Receiving (async iterable) ---
-  mentions() {
-    const buffer = new EventBuffer();
-    this.onMention((event) => {
-      buffer.push(event);
+  messages(options) {
+    let unsubscribe;
+    const buffer = new EventBuffer({
+      onClose: () => unsubscribe?.()
     });
-    return buffer;
-  }
-  replies() {
-    const buffer = new EventBuffer();
-    this.onReply((event, original) => {
-      buffer.push([event, original]);
+    unsubscribe = this.onMessage((event) => {
+      if (options?.filter && !options.filter(event)) return;
+      buffer.push(event);
     });
     return buffer;
   }
-  messages(channelId, options) {
-    const buffer = new EventBuffer();
-    if (options?.filter) {
-      this.onMessage(channelId, { filter: options.filter }, (event) => {
-        buffer.push(event);
-      });
-    } else {
-      this.onMessage(channelId, (event) => {
-        buffer.push(event);
-      });
-    }
-    return buffer;
-  }
   // --- Error handling ---
   on(_event, handler) {
     this.errorHandlers.push(handler);
+    let removed = false;
+    return () => {
+      if (removed) return;
+      removed = true;
+      const index = this.errorHandlers.indexOf(handler);
+      if (index !== -1) this.errorHandlers.splice(index, 1);
+    };
   }
   emitError(error) {
     const err = error instanceof Error ? error : new Error(String(error));
@@ -387,6 +357,8 @@ var Bot = class _Bot {
   async disconnect() {
     this.client.removeAllListeners();
     await this.client.destroy();
+    this.messageHandlers.length = 0;
+    this.errorHandlers.length = 0;
     this._status = "disconnected";
     this._connectedAt = null;
   }
@@ -400,6 +372,17 @@ var Bot = class _Bot {
     }
     return channel;
   }
+  async fetchMessage(channelId, messageId, verb) {
+    const channel = await this.fetchTextChannel(channelId);
+    try {
+      const message = await channel.messages.fetch(messageId);
+      return { channel, message };
+    } catch (error) {
+      throw new Error(
+        `Cannot ${verb} message ${messageId}: ${error instanceof Error ? error.message : String(error)}`
+      );
+    }
+  }
   toFetchedMessage(msg) {
     return {
       messageId: msg.id,
@@ -447,27 +430,8 @@ var Bot = class _Bot {
         if (message.author.id === this.client.user?.id) return;
         if (message.author.bot && !this._includeBotMessages) return;
         const event = this.toMessageEvent(message);
-        const botUser = this.client.user;
-        const isDM = message.channel.type === import_discord.ChannelType.DM;
-        if (botUser && (message.mentions.has(botUser.id) || isDM)) {
-          for (const handler of this.mentionHandlers) {
-            handler(event);
-          }
-        }
-        if (message.reference?.messageId) {
-          const original = this.sentMessages.get(message.reference.messageId);
-          if (original) {
-            for (const handler of this.replyHandlers) {
-              handler(event, original);
-            }
-          }
-        }
-        const subs = this.channelSubscriptions.get(message.channelId);
-        if (subs) {
-          for (const sub of subs) {
-            if (sub.filter && !sub.filter(event)) continue;
-            sub.handler(event);
-          }
+        for (const handler of this.messageHandlers) {
+          handler(event);
         }
       } catch (error) {
         this.emitError(error);
@@ -475,6 +439,18 @@ var Bot = class _Bot {
     });
   }
   toMessageEvent(message) {
+    const isDM = message.channel.type === import_discord.ChannelType.DM;
+    const botUser = this.client.user;
+    const isMention = isDM || (botUser ? message.mentions.has(botUser.id) : false);
+    let isReply = false;
+    let replyTo = null;
+    if (message.reference?.messageId) {
+      const original = this.sentMessages.get(message.reference.messageId);
+      if (original) {
+        isReply = true;
+        replyTo = original;
+      }
+    }
     return {
       messageId: message.id,
       author: {
@@ -487,7 +463,11 @@ var Bot = class _Bot {
       guildId: message.guildId ?? null,
       timestamp: message.createdAt,
       mentions: [...message.mentions.users.keys()],
-      raw: message
+      raw: message,
+      isDM,
+      isMention,
+      isReply,
+      replyTo
     };
   }
   async sendPayloads(content, dispatcher) {
@@ -694,21 +674,28 @@ var BotOnboarding = class {
 // src/connector-manager.ts
 var ConnectorManager = class {
   botMap = /* @__PURE__ */ new Map();
-  mentionHandlers = [];
+  botUnsubscribers = /* @__PURE__ */ new Map();
+  messageHandlers = [];
   lifecycleHandlers = /* @__PURE__ */ new Map();
   addBot(bot) {
     if (this.botMap.has(bot.id)) {
       throw new Error(`Bot with id "${bot.id}" already exists in this manager.`);
     }
     this.botMap.set(bot.id, bot);
-    bot.onMention((event) => {
-      for (const handler of this.mentionHandlers) {
-        handler(event, bot);
-      }
-    });
-    bot.on("error", (error) => {
-      this.emitLifecycle("botError", bot, error);
-    });
+    const unsubs = [];
+    unsubs.push(
+      bot.onMessage((event) => {
+        for (const handler of this.messageHandlers) {
+          handler(event, bot);
+        }
+      })
+    );
+    unsubs.push(
+      bot.on("error", (error) => {
+        this.emitLifecycle("botError", bot, error);
+      })
+    );
+    this.botUnsubscribers.set(bot.id, unsubs);
   }
   getBot(id) {
     return this.botMap.get(id);
@@ -717,6 +704,11 @@ var ConnectorManager = class {
     return this.botMap.values();
   }
   removeBot(id) {
+    const unsubs = this.botUnsubscribers.get(id);
+    if (unsubs) {
+      for (const unsub of unsubs) unsub();
+      this.botUnsubscribers.delete(id);
+    }
     this.botMap.delete(id);
   }
   status() {
@@ -726,8 +718,8 @@ var ConnectorManager = class {
       status: bot.status
     }));
   }
-  onMention(callback) {
-    this.mentionHandlers.push(callback);
+  onMessage(handler) {
+    this.messageHandlers.push(handler);
   }
   on(event, callback) {
     const handlers = this.lifecycleHandlers.get(event) ?? [];