@stonyx/discord 0.1.1-beta.15 → 0.1.1-beta.151

package/README.md

@@ -11,7 +11,7 @@ Discord bot module for the [Stonyx framework](https://github.com/abofs/stonyx),
 * **Command auto-discovery:** Drop command files into a directory and the framework registers them automatically.
 * **Event handler auto-discovery:** Same pattern for Discord gateway events.
 * **Intent auto-derivation:** Required intents computed from discovered event handlers.
-* **Lazy initialization:** Bot only starts if a token is configured and commands/events exist.
+* **Token-gated start:** The bot logs in only when a token is configured. With a token and no commands or events, it still logs in, so a send-only bot works.
 * **Singleton pattern:** Matches conventions of `@stonyx/sockets` and `@stonyx/events`.
 * **Utility methods:** sendMessage, reply with auto-chunking, role management, and more.
 
@@ -23,6 +23,8 @@ pnpm install @stonyx/discord
 
 ## Quick Start
 
+The examples below are complete files: each one imports only from `@stonyx/discord` subpaths, so it runs in an app that depends on nothing but `@stonyx/discord`. The repo's `test/sample/` directory holds samples written the same way ([source](https://github.com/abofs/stonyx-discord/tree/dev/test/sample)), and the test suite loads and exercises them on every run. See [Samples](#samples) for the list.
+
 ### 1. Create handler directories
 
 ```
@@ -36,8 +38,8 @@ discord-events/         # default directory (configurable)
 
 ```javascript
 // discord-commands/ping.js
-import { SlashCommandBuilder } from 'discord.js';
-import { Command } from '@stonyx/discord';
+import { SlashCommandBuilder } from '@stonyx/discord/base';
+import Command from '@stonyx/discord/command';
 
 export default class PingCommand extends Command {
   data = new SlashCommandBuilder()
@@ -54,34 +56,38 @@ export default class PingCommand extends Command {
 
 ```javascript
 // discord-events/message-create.js
-import { EventHandler } from '@stonyx/discord';
+import EventHandler from '@stonyx/discord/event-handler';
 
 export default class MessageCreateHandler extends EventHandler {
   static event = 'messageCreate';
 
-  handle(message) {
+  async handle(message) {
     if (message.author.bot) return;
-    console.log(`${message.author.username}: ${message.content}`);
+    if (message.content === '!ping') await message.reply('pong');
   }
 }
 ```
 
 ### 4. Start the bot
 
-With Stonyx auto-initialization (recommended):
+Stonyx auto-initializes the bot when your app boots — no manual wiring needed:
 
 ```bash
 stonyx serve
 ```
 
-Or manually:
+`Discord.init()` (called by the Stonyx module loader) awaits `new DiscordBot().init()`, which discovers commands/events, derives intents, and connects to the gateway. If `DISCORD_TOKEN` is unset, the bot skips login. With a token it always logs in, even when no commands or events exist.
 
-```javascript
-import { DiscordBot } from '@stonyx/discord';
+## Exports
 
-const bot = new DiscordBot();
-await bot.init();
-```
+| Import | Provides |
+|--------|----------|
+| `@stonyx/discord` | `Discord` (default) — the Stonyx module entry point; no named exports |
+| `@stonyx/discord/bot` | `DiscordBot` (default) — the bot singleton and its utility methods |
+| `@stonyx/discord/command` | `Command` (default) — base class for slash commands |
+| `@stonyx/discord/event-handler` | `EventHandler` (default) — base class for gateway event handlers |
+| `@stonyx/discord/message` | `chunkMessage` — message chunking helper |
+| `@stonyx/discord/base` | Re-exports of discord.js: `SlashCommandBuilder`, `EmbedBuilder`, `ActionRowBuilder`, `ButtonBuilder`, `ButtonStyle`, `MessageFlags`, `PermissionFlagsBits`, `AttachmentBuilder`, `REST`, `Routes`, `Client`, `GatewayIntentBits`, `Partials` |
 
 ## Command Architecture
 
@@ -114,6 +120,22 @@ The framework wraps `execute()` in a try/catch. On error:
 2. Sends an ephemeral "There was an error executing this command!" reply
 3. Uses `followUp` if the interaction was already replied to or deferred
 
+### Registering commands with Discord
+
+The bot loads your command classes at boot, but it never registers them with Discord. Registration is a separate script you run whenever a command's `data` changes. [`test/sample/scripts/deploy-commands.js`](https://github.com/abofs/stonyx-discord/blob/dev/test/sample/scripts/deploy-commands.js) is a complete one. It loads the command directory and PUTs each command's `data.toJSON()` to `Routes.applicationGuildCommands(applicationId, guildId)` using `REST` from `@stonyx/discord/base`. Guild-scoped commands update immediately, which is what you want in development.
+
+```bash
+DISCORD_TOKEN=... DISCORD_BOT_USER_ID=... DISCORD_SERVER_ID=... node scripts/deploy-commands.js ./discord-commands
+```
+
+### Buttons, autocomplete and other interactions
+
+The bot's own `interactionCreate` listener dispatches only chat-input (slash) commands. Buttons, autocomplete, select menus and modals belong to your app: write an event handler with `static event = 'interactionCreate'`. [`test/sample/discord-events/interaction-create.js`](https://github.com/abofs/stonyx-discord/blob/dev/test/sample/discord-events/interaction-create.js) routes autocomplete to the command's `autocomplete(interaction)` and buttons, by `customId`, to the command's `button(interaction, action, argument)`. It leaves chat-input interactions alone so commands do not run twice.
+
+### Embeds
+
+Build embeds and button rows with `EmbedBuilder`, `ActionRowBuilder`, `ButtonBuilder` and `ButtonStyle` from `@stonyx/discord/base`. [`test/sample/discord-commands/color.js`](https://github.com/abofs/stonyx-discord/blob/dev/test/sample/discord-commands/color.js) replies with an embed and a button, and implements the `autocomplete()` and `button()` methods the router above calls.
+
 ## Event Handler Architecture
 
 ### How handlers are discovered
@@ -155,7 +177,7 @@ The framework automatically computes the required intents from your registered e
 | `voiceStateUpdate` | `GuildVoiceStates` |
 | `interactionCreate` | *(none — handled by default)* |
 
-**`Guilds` is always included** when commands are registered.
+**`Guilds` is always included**, whether or not any commands or events are registered.
 
 ### Intent-to-Partial Mapping
 
@@ -181,11 +203,20 @@ Values are resolved against `GatewayIntentBits` and `Partials` enums from discor
 
 ## Utility Methods
 
-All methods are on the `DiscordBot` instance (accessible via `this._bot` in commands/handlers or `new DiscordBot()`).
+All methods are on the `DiscordBot` instance (accessible via `this._bot` in commands/handlers, or `new DiscordBot()` after `import DiscordBot from '@stonyx/discord/bot'`).
 
 ### sendMessage(content, channelId, imagePath?)
 
-Send a text message to a channel. Optionally attach an image file.
+Send a text message to a channel with auto-chunking. Messages over 2000 characters are split at newline/space boundaries and sent sequentially. Optionally attach an image file (attached to the first chunk only).
+
+Messages are delivered reliably across connection state transitions:
+- If the bot is **ready**, the message is sent immediately.
+- If the bot is **connecting or disconnected**, the message is queued and auto-delivered when the connection resumes.
+- **Transient failures** (5xx, network errors) are retried up to 3 times with exponential backoff.
+- Queued messages expire after **5 minutes** (TTL) — stale messages are rejected rather than sent late.
+- The queue holds up to **1000** messages; excess messages are rejected with a "queue full" error.
+
+The returned promise resolves when the message is actually delivered or rejects on permanent failure.
 
 ```javascript
 await bot.sendMessage('Hello world', '123456789');
@@ -248,10 +279,10 @@ const guild = await bot.getGuild();
 
 ### clearChannelMessages(channelId)
 
-Delete all fetched messages in a channel (up to `maxMessagesPerRequest`).
+Delete all fetched messages in a channel (up to `maxMessagesPerRequest`). Awaits every delete via `Promise.allSettled` and resolves with a structured `{ deleted, failed, errors }` so callers can act on partial failure. Never throws on individual delete failures; emits a single `log.warn` summary when any deletes fail.
 
 ```javascript
-await bot.clearChannelMessages('123456789');
+const { deleted, failed, errors } = await bot.clearChannelMessages('123456789');
 ```
 
 ### giveRole(memberId, roleId)
@@ -296,18 +327,18 @@ Configuration is read from `stonyx/config` under `discord`:
 | `commands` | `Object` — registered command instances keyed by name |
 | `eventHandlers` | `Array` — registered event handler instances |
 | `client` | Discord.js `Client` instance (after init) |
-| `ready` | `Promise` — resolves when the bot is connected and ready |
-| `sendMessage(content, channelId, imagePath?)` | Send a message to a channel |
+| `ready` | `Promise` — resolves when the bot is connected and ready; re-pends on gateway disconnects |
+| `sendMessage(content, channelId, imagePath?)` | Send a message to a channel with auto-chunking (queues during disconnections, retries transient failures) |
 | `sendFile(file, messageObject)` | Replace a message with a file attachment |
 | `reply(interaction, content)` | Reply with auto-chunking |
 | `updateStatus(name, type?)` | Set bot presence |
 | `getChannelMessages(channelId, options?)` | Fetch channel messages |
 | `getChannelMessage(channelId, messageId)` | Fetch a single message |
 | `getGuild(guildId?)` | Fetch a guild |
-| `clearChannelMessages(channelId)` | Delete messages in a channel |
+| `clearChannelMessages(channelId)` | Delete messages in a channel; returns `{ deleted, failed, errors }` and never throws on partial failure |
 | `giveRole(memberId, roleId)` | Add a role to a member |
-| `close()` | Destroy the Discord client and clear singleton |
-| `reset()` | Close + clear all commands and handlers |
+| `close()` | Destroy the Discord client, reject pending queue, clear singleton |
+| `reset()` | Close + clear all commands, handlers, and connection state |
 
 ### Command
 
@@ -326,6 +357,18 @@ Configuration is read from `stonyx/config` under `discord`:
 | `handle(...args)` | Handle the event — define in subclass |
 | `this._bot` | Reference to `DiscordBot` (set during discovery) |
 
+## Samples
+
+Each sample imports only from `@stonyx/discord` subpaths and `node:` builtins, so it can be copied into an app as is. [`test/unit/sample-patterns-test.ts`](https://github.com/abofs/stonyx-discord/blob/dev/test/unit/sample-patterns-test.ts) exercises them with a fake REST client and fake interactions.
+
+| Sample | Shows |
+|--------|-------|
+| [`discord-commands/ping.js`](https://github.com/abofs/stonyx-discord/blob/dev/test/sample/discord-commands/ping.js) | A minimal slash command |
+| [`discord-commands/color.js`](https://github.com/abofs/stonyx-discord/blob/dev/test/sample/discord-commands/color.js) | A command with an embed, a button row, `autocomplete()` and `button()` |
+| [`discord-events/log-message.js`](https://github.com/abofs/stonyx-discord/blob/dev/test/sample/discord-events/log-message.js) | A `messageCreate` handler |
+| [`discord-events/interaction-create.js`](https://github.com/abofs/stonyx-discord/blob/dev/test/sample/discord-events/interaction-create.js) | Routing buttons and autocomplete from `interactionCreate` |
+| [`scripts/deploy-commands.js`](https://github.com/abofs/stonyx-discord/blob/dev/test/sample/scripts/deploy-commands.js) | Registering slash commands, guild-scoped, with `REST` and `Routes` |
+
 ## Example Project Structure
 
 ```
@@ -338,6 +381,8 @@ my-app/
 ├── discord-events/
 │   ├── message-create.js
 │   └── guild-member-add.js
+├── scripts/
+│   └── deploy-commands.js
 ├── package.json
 └── app.js
 ```

package/dist/base.d.ts

@@ -1 +1 @@
-export { SlashCommandBuilder, MessageFlags, PermissionFlagsBits, GatewayIntentBits, AttachmentBuilder, Client, Partials } from 'discord.js';
+export { SlashCommandBuilder, MessageFlags, PermissionFlagsBits, GatewayIntentBits, AttachmentBuilder, Client, Partials, REST, Routes, EmbedBuilder, ActionRowBuilder, ButtonBuilder, ButtonStyle, } from 'discord.js';

package/dist/base.js

@@ -1 +1 @@
-export { SlashCommandBuilder, MessageFlags, PermissionFlagsBits, GatewayIntentBits, AttachmentBuilder, Client, Partials } from 'discord.js';
+export { SlashCommandBuilder, MessageFlags, PermissionFlagsBits, GatewayIntentBits, AttachmentBuilder, Client, Partials, REST, Routes, EmbedBuilder, ActionRowBuilder, ButtonBuilder, ButtonStyle, } from 'discord.js';

package/dist/bot.d.ts

@@ -1,5 +1,10 @@
 import { Client } from 'discord.js';
 import type { ChatInputCommandInteraction, Message } from 'discord.js';
+export interface ClearChannelMessagesResult {
+    deleted: number;
+    failed: number;
+    errors: Error[];
+}
 interface CommandInstance {
     data?: {
         name: string;
@@ -24,19 +29,30 @@ export default class DiscordBot {
     resolveReady: () => void;
     ready: Promise<void>;
     client: Client | null;
+    private _connectionState;
+    private _queue;
     constructor();
     init(): Promise<void>;
+    private _resetReady;
     registerClientEvents(): void;
     discoverCommands(): Promise<void>;
     discoverEvents(): Promise<void>;
+    private _doSend;
     sendMessage(content: string, channelId: string, imagePath?: string | null): Promise<Message>;
+    private _enqueue;
+    private _enqueueForRetry;
+    private _scheduleRetry;
+    private _processEntry;
+    private _flushQueue;
+    private _isRetryable;
+    private _ensureReady;
     sendFile(file: string, messageObject: Message): Promise<Message>;
     reply(interaction: ChatInputCommandInteraction, content: string): Promise<void>;
     updateStatus(name: string, type?: number): Promise<void>;
     getChannelMessages(channelId: string, options?: Record<string, unknown>): Promise<unknown>;
     getChannelMessage(channelId: string, messageId: string): Promise<unknown>;
     getGuild(guildId?: string): Promise<unknown>;
-    clearChannelMessages(channelId: string): Promise<unknown[]>;
+    clearChannelMessages(channelId: string): Promise<ClearChannelMessagesResult>;
     giveRole(memberId: string, roleId: string): Promise<void>;
     close(): void;
     reset(): void;

package/dist/bot.js

@@ -4,6 +4,11 @@ import { Client, GatewayIntentBits, AttachmentBuilder, MessageFlags } from 'disc
 import { forEachFileImport } from '@stonyx/utils/file';
 import { deriveIntents, derivePartials } from './intents.js';
 import { chunkMessage } from './message.js';
+const MAX_RETRIES = 3;
+const MAX_QUEUE_SIZE = 1000;
+const QUEUE_TTL = 300_000; // 5 minutes
+const READY_TIMEOUT = 30_000; // 30 seconds
+const RETRYABLE_NETWORK_CODES = new Set(['ECONNRESET', 'ETIMEDOUT', 'ECONNREFUSED']);
 export default class DiscordBot {
     static instance;
     commands = {};
@@ -11,26 +16,33 @@ export default class DiscordBot {
     resolveReady;
     ready = new Promise(resolve => { this.resolveReady = resolve; });
     client = null;
+    _connectionState = 'connecting';
+    _queue = [];
     constructor() {
         if (DiscordBot.instance)
             return DiscordBot.instance;
         DiscordBot.instance = this;
     }
     async init() {
+        // Self-register so log.discord works even when @stonyx/discord is in the
+        // consumer's `dependencies` (stonyx loader only merges devDependencies).
+        const { logColor = '#7289da', logMethod = 'discord' } = config.discord;
+        log.defineType(logMethod, logColor);
+        if (this.client) {
+            // Already initialized — singleton reuse via Discord.init() or a direct
+            // new DiscordBot().init() call. Wait for the existing ready promise
+            // rather than re-running discovery + login.
+            await this.ready;
+            return;
+        }
         const { token } = config.discord;
         if (!token) {
-            log.discord('No DISCORD_TOKEN configured — bot will not start');
+            log.discord?.('No DISCORD_TOKEN configured — bot will not start');
             this.resolveReady();
             return;
         }
         await this.discoverCommands();
         await this.discoverEvents();
-        const hasWork = Object.keys(this.commands).length > 0 || this.eventHandlers.length > 0;
-        if (!hasWork) {
-            log.discord('No discord commands or event handlers found — skipping bot initialization');
-            this.resolveReady();
-            return;
-        }
         const intents = deriveIntents(this.eventHandlers, config.discord.additionalIntents);
         const partials = derivePartials(intents, config.discord.additionalPartials);
         if (Object.keys(this.commands).length > 0) {
@@ -41,13 +53,43 @@ export default class DiscordBot {
         this.client.login(token);
         await this.ready;
     }
+    _resetReady() {
+        this.ready = new Promise(resolve => { this.resolveReady = resolve; });
+    }
     registerClientEvents() {
         const { client } = this;
         if (!client)
             return;
         client.on('ready', () => {
+            this._connectionState = 'ready';
             this.resolveReady();
-            log.discord('Discord Bot is Ready!');
+            this._flushQueue();
+            log.discord?.('Discord Bot is Ready!');
+        });
+        client.on('shardDisconnect', () => {
+            this._resetReady();
+            this._connectionState = 'disconnected';
+            log.discord?.('Shard disconnected');
+        });
+        client.on('shardReconnecting', () => {
+            this._resetReady();
+            this._connectionState = 'connecting';
+            log.discord?.('Shard reconnecting');
+        });
+        client.on('shardResume', () => {
+            this._connectionState = 'ready';
+            this.resolveReady();
+            this._flushQueue();
+            log.discord?.('Shard resumed');
+        });
+        client.on('invalidated', () => {
+            log.error('Discord session invalidated — rejecting all queued messages');
+            const entries = this._queue.splice(0);
+            for (const entry of entries) {
+                if (entry.timerId !== null)
+                    clearTimeout(entry.timerId);
+                entry.reject(new Error('Discord session invalidated'));
+            }
         });
         client.on('interactionCreate', async (interaction) => {
             if (!interaction.isChatInputCommand())
@@ -87,12 +129,12 @@ export default class DiscordBot {
             const CommandClass = CommandClassUntyped;
             const instance = new CommandClass();
             if (!instance.data || typeof instance.execute !== 'function') {
-                log.discord(`Command "${name}" is missing data or execute — skipping`);
+                log.discord?.(`Command "${name}" is missing data or execute — skipping`);
                 return;
             }
             instance._bot = this;
             this.commands[instance.data.name] = instance;
-            log.discord(`Loaded command: /${instance.data.name}`);
+            log.discord?.(`Loaded command: /${instance.data.name}`);
         }, { ignoreAccessFailure: true });
     }
     async discoverEvents() {
@@ -102,26 +144,177 @@ export default class DiscordBot {
         await forEachFileImport(eventDir, (EventHandlerClassUntyped, { name }) => {
             const EventHandlerClass = EventHandlerClassUntyped;
             if (!EventHandlerClass.event) {
-                log.discord(`Event handler "${name}" is missing static event property — skipping`);
+                log.discord?.(`Event handler "${name}" is missing static event property — skipping`);
                 return;
             }
             const instance = new EventHandlerClass();
             instance._bot = this;
             this.eventHandlers.push(instance);
-            log.discord(`Loaded event handler: ${EventHandlerClass.event} (${name})`);
+            log.discord?.(`Loaded event handler: ${EventHandlerClass.event} (${name})`);
         }, { ignoreAccessFailure: true });
     }
-    async sendMessage(content, channelId, imagePath = null) {
+    async _doSend(content, channelId, imagePath) {
         if (!this.client)
             throw new Error('Discord bot is not initialized');
         const channel = await this.client.channels.fetch(channelId);
         if (!channel)
             throw new Error('Invalid Channel ID');
+        const sendable = channel;
+        if (content.length > 2000) {
+            const chunks = chunkMessage('', content);
+            let firstMessage;
+            for (let i = 0; i < chunks.length; i++) {
+                const options = { content: chunks[i] };
+                if (i === 0 && imagePath) {
+                    options.files = [new AttachmentBuilder(imagePath)];
+                }
+                const msg = await sendable.send(options);
+                if (i === 0)
+                    firstMessage = msg;
+            }
+            return firstMessage;
+        }
         const options = { content };
         if (imagePath) {
             options.files = [new AttachmentBuilder(imagePath)];
         }
-        return await channel.send(options);
+        return await sendable.send(options);
+    }
+    async sendMessage(content, channelId, imagePath = null) {
+        if (this._connectionState === 'ready') {
+            try {
+                return await this._doSend(content, channelId, imagePath);
+            }
+            catch (error) {
+                if (this._isRetryable(error)) {
+                    return this._enqueueForRetry(content, channelId, imagePath, 1);
+                }
+                throw error;
+            }
+        }
+        return this._enqueue(content, channelId, imagePath);
+    }
+    _enqueue(content, channelId, imagePath) {
+        if (this._queue.length >= MAX_QUEUE_SIZE) {
+            return Promise.reject(new Error('Message queue full'));
+        }
+        return new Promise((resolve, reject) => {
+            this._queue.push({
+                content,
+                channelId,
+                imagePath,
+                resolve,
+                reject,
+                retries: 0,
+                enqueuedAt: Date.now(),
+                timerId: null,
+            });
+        });
+    }
+    _enqueueForRetry(content, channelId, imagePath, retries) {
+        if (this._queue.length >= MAX_QUEUE_SIZE) {
+            return Promise.reject(new Error('Message queue full'));
+        }
+        return new Promise((resolve, reject) => {
+            const entry = {
+                content,
+                channelId,
+                imagePath,
+                resolve,
+                reject,
+                retries,
+                enqueuedAt: Date.now(),
+                timerId: null,
+            };
+            this._queue.push(entry);
+            this._scheduleRetry(entry);
+        });
+    }
+    _scheduleRetry(entry) {
+        const backoff = Math.min(1000 * Math.pow(2, entry.retries) + Math.floor(Math.random() * 500), 30000);
+        entry.timerId = setTimeout(() => {
+            entry.timerId = null;
+            // Only process if the entry is still in the queue (wasn't rejected by close/invalidated)
+            const idx = this._queue.indexOf(entry);
+            if (idx === -1)
+                return;
+            if (this._connectionState === 'ready') {
+                this._processEntry(entry, idx);
+            }
+            // If not ready, entry stays in queue for _flushQueue on reconnect
+        }, backoff);
+    }
+    async _processEntry(entry, idx) {
+        // Remove from queue before attempting
+        const currentIdx = this._queue.indexOf(entry);
+        if (currentIdx === -1)
+            return;
+        this._queue.splice(currentIdx, 1);
+        // TTL check
+        if (Date.now() - entry.enqueuedAt > QUEUE_TTL) {
+            entry.reject(new Error('Message expired: stale TTL exceeded'));
+            return;
+        }
+        try {
+            const msg = await this._doSend(entry.content, entry.channelId, entry.imagePath);
+            entry.resolve(msg);
+        }
+        catch (error) {
+            if (this._isRetryable(error) && entry.retries < MAX_RETRIES) {
+                entry.retries++;
+                this._queue.push(entry);
+                this._scheduleRetry(entry);
+            }
+            else {
+                const message = entry.retries >= MAX_RETRIES
+                    ? `Message send failed: retries exhausted (${entry.retries}/${MAX_RETRIES})`
+                    : (error instanceof Error ? error.message : String(error));
+                entry.reject(new Error(message));
+            }
+        }
+    }
+    async _flushQueue() {
+        // Take a snapshot of entries to process
+        const entries = this._queue.splice(0);
+        for (const entry of entries) {
+            // TTL check
+            if (Date.now() - entry.enqueuedAt > QUEUE_TTL) {
+                entry.reject(new Error('Message expired: stale TTL exceeded'));
+                continue;
+            }
+            try {
+                const msg = await this._doSend(entry.content, entry.channelId, entry.imagePath);
+                entry.resolve(msg);
+            }
+            catch (error) {
+                if (this._isRetryable(error) && entry.retries < MAX_RETRIES) {
+                    entry.retries++;
+                    this._queue.push(entry);
+                    this._scheduleRetry(entry);
+                }
+                else {
+                    entry.reject(error instanceof Error ? error : new Error(String(error)));
+                }
+            }
+        }
+    }
+    _isRetryable(error) {
+        if (error == null || typeof error !== 'object')
+            return false;
+        const err = error;
+        // HTTP 5xx errors
+        if (typeof err.status === 'number' && err.status >= 500 && err.status <= 599) {
+            return true;
+        }
+        // Network error codes
+        if (typeof err.code === 'string' && RETRYABLE_NETWORK_CODES.has(err.code)) {
+            return true;
+        }
+        return false;
+    }
+    async _ensureReady() {
+        const timeout = new Promise((_, reject) => setTimeout(() => reject(new Error('Timed out waiting for Discord bot to be ready')), READY_TIMEOUT));
+        await Promise.race([this.ready, timeout]);
     }
     async sendFile(file, messageObject) {
         return await messageObject.edit({
@@ -153,6 +346,7 @@ export default class DiscordBot {
         }
     }
     async updateStatus(name, type = 0) {
+        await this._ensureReady();
         if (!this.client?.user)
             throw new Error('Discord bot is not initialized');
         await this.client.user.setPresence({
@@ -161,6 +355,7 @@ export default class DiscordBot {
         });
     }
     async getChannelMessages(channelId, options = {}) {
+        await this._ensureReady();
         if (!this.client)
             throw new Error('Discord bot is not initialized');
         const channel = await this.client.channels.fetch(channelId);
@@ -170,21 +365,33 @@ export default class DiscordBot {
         });
     }
     async getChannelMessage(channelId, messageId) {
+        await this._ensureReady();
         if (!this.client)
             throw new Error('Discord bot is not initialized');
         const channel = await this.client.channels.fetch(channelId);
         return await channel.messages.fetch(messageId);
     }
     async getGuild(guildId) {
+        await this._ensureReady();
         if (!this.client)
             throw new Error('Discord bot is not initialized');
         return await this.client.guilds.fetch(guildId || config.discord.serverId || '');
     }
     async clearChannelMessages(channelId) {
-        const promises = [];
         const messages = await this.getChannelMessages(channelId);
-        messages.forEach(message => promises.push(message.delete()));
-        return Promise.all(promises);
+        const settled = await Promise.allSettled([...messages.values()].map(m => m.delete()));
+        const errors = settled
+            .filter((s) => s.status === 'rejected')
+            .map(s => s.reason instanceof Error ? s.reason : new Error(String(s.reason)));
+        const result = {
+            deleted: settled.length - errors.length,
+            failed: errors.length,
+            errors,
+        };
+        if (result.failed > 0) {
+            log.warn(`clearChannelMessages partial failure on channel ${channelId}: deleted=${result.deleted} failed=${result.failed} errors=${errors.map(String).join('; ')}`);
+        }
+        return result;
     }
     async giveRole(memberId, roleId) {
         const guild = await this.getGuild();
@@ -193,6 +400,13 @@ export default class DiscordBot {
         await member.roles.add(role);
     }
     close() {
+        // Cancel all pending retry timers and reject all queue entries
+        const entries = this._queue.splice(0);
+        for (const entry of entries) {
+            if (entry.timerId !== null)
+                clearTimeout(entry.timerId);
+            entry.reject(new Error('Discord bot closed'));
+        }
         if (this.client) {
             this.client.destroy();
             this.client = null;
@@ -203,5 +417,7 @@ export default class DiscordBot {
         this.close();
         this.commands = {};
         this.eventHandlers = [];
+        this._connectionState = 'connecting';
+        this._resetReady();
     }
 }

package/dist/main.js

@@ -1,3 +1,4 @@
+import DiscordBot from './bot.js';
 export default class Discord {
     static instance;
     constructor() {
@@ -6,8 +7,7 @@ export default class Discord {
         Discord.instance = this;
     }
     async init() {
-        // Bot initialization is deferred to DiscordBot.init()
-        // This entry point satisfies Stonyx module auto-initialization
+        await new DiscordBot().init();
     }
     reset() {
         Discord.instance = null;

package/package.json

@@ -4,7 +4,7 @@
     "stonyx-async",
     "stonyx-module"
   ],
-  "version": "0.1.1-beta.15",
+  "version": "0.1.1-beta.151",
   "description": "Discord bot module for the Stonyx framework",
   "main": "dist/main.js",
   "types": "dist/main.d.ts",
@@ -64,16 +64,19 @@
     "stonyx": ">=0.2.3-beta.4"
   },
   "devDependencies": {
-    "@stonyx/utils": "0.2.3-beta.7",
+    "@stonyx/utils": "0.2.3-beta.29",
     "@types/node": "^25.5.2",
+    "@types/qunit": "^2.19.13",
+    "@types/sinon": "^21.0.1",
     "qunit": "^2.24.1",
     "sinon": "^21.0.0",
-    "stonyx": "0.2.3-beta.12",
+    "stonyx": "0.2.3-beta.105",
+    "tsx": "^4.21.0",
     "typescript": "^5.8.3"
   },
   "scripts": {
     "build": "tsc",
-    "build:test": "tsc -p tsconfig.test.json",
-    "test": "pnpm build && pnpm build:test && stonyx test 'dist-test/test/**/*-test.js'"
+    "typecheck": "tsc --noEmit && tsc --noEmit -p tsconfig.test.json",
+    "test": "pnpm build && NODE_ENV=test node --import tsx/esm --import ./test/setup.ts node_modules/qunit/bin/qunit.js 'test/**/*-test.ts'"
   }
 }