@stonyx/discord 0.1.1-beta.62 → 0.1.1-beta.63

package/README.md

@@ -180,6 +180,15 @@ All methods are on the `DiscordBot` instance (accessible via `this._bot` in comm
 
 Send a text message to a channel. Optionally attach an image file.
 
+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');
 await bot.sendMessage('Check this out', '123456789', './screenshot.png');
@@ -289,8 +298,8 @@ 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 (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 |
@@ -299,8 +308,8 @@ Configuration is read from `stonyx/config` under `discord`:
 | `getGuild(guildId?)` | Fetch a guild |
 | `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/bot.d.ts

@@ -29,12 +29,23 @@ 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>;

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,6 +16,8 @@ export default class DiscordBot {
     resolveReady;
     ready = new Promise(resolve => { this.resolveReady = resolve; });
     client = null;
+    _connectionState = 'connecting';
+    _queue = [];
     constructor() {
         if (DiscordBot.instance)
             return DiscordBot.instance;
@@ -46,14 +53,44 @@ 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();
+            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())
                 return;
@@ -116,7 +153,7 @@ export default class DiscordBot {
             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);
@@ -128,6 +165,142 @@ export default class DiscordBot {
         }
         return await channel.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: '',
@@ -158,6 +331,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({
@@ -166,6 +340,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);
@@ -175,12 +350,14 @@ 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 || '');
@@ -208,6 +385,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;
@@ -218,5 +402,7 @@ export default class DiscordBot {
         this.close();
         this.commands = {};
         this.eventHandlers = [];
+        this._connectionState = 'connecting';
+        this._resetReady();
     }
 }

package/package.json

@@ -4,7 +4,7 @@
     "stonyx-async",
     "stonyx-module"
   ],
-  "version": "0.1.1-beta.62",
+  "version": "0.1.1-beta.63",
   "description": "Discord bot module for the Stonyx framework",
   "main": "dist/main.js",
   "types": "dist/main.d.ts",