@stonyx/discord 0.1.1-beta.13 → 0.1.1-beta.131

package/README.md

@@ -68,20 +68,13 @@ export default class MessageCreateHandler extends EventHandler {
 
 ### 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:
-
-```javascript
-import { DiscordBot } from '@stonyx/discord';
-
-const bot = new DiscordBot();
-await bot.init();
-```
+`Discord.init()` (called by the Stonyx module loader) awaits `new DiscordBot().init()`, which discovers commands/events, derives intents, and connects to the gateway. The lazy-init guards still apply: if `DISCORD_TOKEN` is unset or no commands/events exist, the bot skips login.
 
 ## Command Architecture
 
@@ -185,7 +178,16 @@ All methods are on the `DiscordBot` instance (accessible via `this._bot` in comm
 
 ### 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 +250,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 +298,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
 

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 } 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 } 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,29 +16,35 @@ 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 discordConfig = config.discord;
-        const intents = deriveIntents(this.eventHandlers, discordConfig.additionalIntents);
-        const partials = derivePartials(intents, discordConfig.additionalPartials);
+        const intents = deriveIntents(this.eventHandlers, config.discord.additionalIntents);
+        const partials = derivePartials(intents, config.discord.additionalPartials);
         if (Object.keys(this.commands).length > 0) {
             intents.push(GatewayIntentBits.Guilds);
         }
@@ -42,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())
@@ -88,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() {
@@ -103,31 +144,184 @@ 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({
             content: '',
             files: [{
                     attachment: file,
-                    name: file.split('/').pop()
+                    name: file.split('/').pop() ?? file
                 }]
         });
     }
@@ -152,32 +346,52 @@ 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({
             activities: [{ name, type }],
             status: 'online'
         });
     }
     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);
-        const discordConfig = config.discord;
         return await channel.messages.fetch({
-            limit: discordConfig.maxMessagesPerRequest,
+            limit: config.discord.maxMessagesPerRequest,
             ...options
         });
     }
     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) {
-        const discordConfig = config.discord;
-        return await this.client.guilds.fetch(guildId || discordConfig.serverId);
+        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();
@@ -186,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;
@@ -196,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.13",
+  "version": "0.1.1-beta.131",
   "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.27",
     "@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.98",
+    "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'"
   }
 }