grammy-message-queue 0.1.0

package/README.md

@@ -0,0 +1,115 @@
+# grammy-message-queue
+
+[![npm version](https://img.shields.io/npm/v/grammy-message-queue?style=flat-square)](https://www.npmjs.com/package/grammy-message-queue)
+[![npm downloads](https://img.shields.io/npm/dm/grammy-message-queue?style=flat-square)](https://www.npmjs.com/package/grammy-message-queue)
+[![GitHub](https://img.shields.io/badge/GitHub-Repository-black?style=flat-square&logo=github)](https://github.com/snipe-dev/grammy-message-queue)
+
+Reliable sequential message delivery queue for Telegram bots built with
+**grammy**.
+
+-   Preserves message order
+-   Automatic Telegram 429 rate limit handling
+-   Supports `retry_after`
+-   Separate send & edit queues
+-   ESM + CommonJS compatible
+-   Node.js \>= 16
+
+------------------------------------------------------------------------
+
+## Installation
+
+``` bash
+npm install grammy-message-queue
+npm install grammy
+```
+
+------------------------------------------------------------------------
+
+## Usage (ESM)
+
+``` ts
+import { Bot } from "grammy";
+import { TelegramQueue } from "grammy-message-queue";
+
+const bot = new Bot(process.env.BOT_TOKEN!);
+const queue = new TelegramQueue(bot.api);
+
+await queue.sendMessage(123456789, "<b>Hello from queue</b>");
+```
+
+------------------------------------------------------------------------
+
+## Usage (CommonJS)
+
+``` js
+const { Bot } = require("grammy");
+const { TelegramQueue } = require("grammy-message-queue");
+
+const bot = new Bot(process.env.BOT_TOKEN);
+const queue = new TelegramQueue(bot.api);
+
+queue.sendMessage(123456789, "<b>Hello from queue</b>");
+```
+
+------------------------------------------------------------------------
+
+## API
+
+### new TelegramQueue(api: Api)
+
+Creates a new transport-safe queue instance.
+
+### sendMessage(chatId, text, buttons?)
+
+Sequential queued send.
+
+Returns:
+
+``` ts
+Promise<number>
+```
+
+### editMessage(chatId, msgId, text, buttons?)
+
+Queued edit.
+
+Returns:
+
+``` ts
+Promise<boolean>
+```
+
+### sendSingleMessage(...)
+
+Immediate send without queue.
+
+### sendSinglePhoto(...)
+
+Immediate photo send.
+
+### editSingleMessage(...)
+
+Immediate edit.
+
+------------------------------------------------------------------------
+
+## Build
+
+``` bash
+npm run build
+```
+
+------------------------------------------------------------------------
+
+## Publish
+
+``` bash
+npm pack
+npm publish --access public
+```
+
+------------------------------------------------------------------------
+
+## Repository
+
+https://github.com/snipe-dev/grammy-message-queue

package/dist/cjs/index.js

@@ -0,0 +1,262 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.TelegramQueue = exports.sleep = void 0;
+exports.applyDefaults = applyDefaults;
+const grammy_1 = require("grammy");
+/**
+ * Utility function to delay execution.
+ */
+const sleep = (ms) => new Promise((resolve) => setTimeout(resolve, ms));
+exports.sleep = sleep;
+/**
+ * Applies default Telegram API options.
+ */
+function applyDefaults(method, payload) {
+    if (!payload || typeof payload !== "object") {
+        return;
+    }
+    if (!payload.parse_mode) {
+        payload.parse_mode = "HTML";
+    }
+    if ((method === "sendMessage" || method === "editMessageText") &&
+        !payload.link_preview_options) {
+        payload.link_preview_options = { is_disabled: true };
+    }
+}
+/**
+ * TelegramQueue
+ *
+ * Sequential and rate-limit-safe outgoing message queue
+ * for Telegram bots built with grammy.
+ */
+class TelegramQueue {
+    constructor(api) {
+        this.botId = "unnamedbot";
+        this.sendQueue = [];
+        this.isProcessingSendQueue = false;
+        this.pendingSendMessages = new Map();
+        this.editQueue = [];
+        this.isProcessingEditQueue = false;
+        this.pendingEditMessages = new Map();
+        this.api = api;
+        this.setupApiMiddleware();
+        this.api
+            .getMe()
+            .then((me) => {
+            this.botId = me.username?.toLowerCase() || "unnamedbot";
+        })
+            .catch(() => {
+            // Silent failure
+        });
+    }
+    setupApiMiddleware() {
+        this.api.config.use((prev, method, payload) => {
+            applyDefaults(method, payload);
+            return prev(method, payload);
+        });
+    }
+    async sendMessage(chatId, text, buttons) {
+        return this.enqueueSendMessage(chatId, text, buttons);
+    }
+    async enqueueSendMessage(chatId, text, buttons) {
+        if (text.length > 4096) {
+            throw new Error("Message too long");
+        }
+        const messageId = `${chatId}_${Date.now()}_${Math.random()}`;
+        let resolve;
+        let reject;
+        const promise = new Promise((res, rej) => {
+            resolve = res;
+            reject = rej;
+        });
+        this.sendQueue.push({
+            chatId,
+            text,
+            buttons,
+            messageId,
+            resolve,
+            reject,
+        });
+        this.pendingSendMessages.set(messageId, promise);
+        if (!this.isProcessingSendQueue) {
+            this.processSendQueue().catch(() => {
+                // Critical failure in queue processor
+                console.error("TelegramQueue send processor crashed");
+            });
+        }
+        return promise;
+    }
+    async processSendQueue() {
+        if (this.isProcessingSendQueue)
+            return;
+        this.isProcessingSendQueue = true;
+        while (this.sendQueue.length > 0) {
+            const item = this.sendQueue[0];
+            try {
+                const msg = await this.api.sendMessage(item.chatId, item.text, item.buttons ? { reply_markup: item.buttons } : {});
+                this.sendQueue.shift();
+                this.pendingSendMessages.delete(item.messageId);
+                item.resolve(msg.message_id);
+                await (0, exports.sleep)(200);
+            }
+            catch (err) {
+                const action = this.handleError(err, item.chatId);
+                if (action.retrySending) {
+                    await (0, exports.sleep)(action.retryAfter * 1000);
+                    continue;
+                }
+                if (action.removeMessage) {
+                    this.sendQueue.shift();
+                    this.pendingSendMessages.delete(item.messageId);
+                    item.reject(err);
+                }
+            }
+        }
+        this.isProcessingSendQueue = false;
+    }
+    async editMessage(chatId, msgId, text, buttons) {
+        return this.enqueueEditMessage(chatId, msgId, text, buttons);
+    }
+    async enqueueEditMessage(chatId, msgId, text, buttons) {
+        if (text.length > 4096) {
+            throw new Error("Message too long");
+        }
+        const editId = `${chatId}_${msgId}_${Date.now()}`;
+        let resolve;
+        let reject;
+        const promise = new Promise((res, rej) => {
+            resolve = res;
+            reject = rej;
+        });
+        this.editQueue.push({
+            chatId,
+            msgId,
+            text,
+            buttons,
+            editId,
+            resolve,
+            reject,
+        });
+        this.pendingEditMessages.set(editId, promise);
+        if (!this.isProcessingEditQueue) {
+            this.processEditQueue().catch(() => {
+                console.error("TelegramQueue edit processor crashed");
+            });
+        }
+        return promise;
+    }
+    async processEditQueue() {
+        if (this.isProcessingEditQueue)
+            return;
+        this.isProcessingEditQueue = true;
+        while (this.editQueue.length > 0) {
+            const item = this.editQueue[0];
+            try {
+                await this.api.editMessageText(item.chatId, item.msgId, item.text, item.buttons ? { reply_markup: item.buttons } : {});
+                this.editQueue.shift();
+                this.pendingEditMessages.delete(item.editId);
+                item.resolve(true);
+                await (0, exports.sleep)(200);
+            }
+            catch (err) {
+                const action = this.handleError(err, item.chatId);
+                if (action.retrySending) {
+                    await (0, exports.sleep)(action.retryAfter * 1000);
+                    continue;
+                }
+                if (action.removeMessage) {
+                    this.editQueue.shift();
+                    this.pendingEditMessages.delete(item.editId);
+                    item.reject(err);
+                }
+            }
+        }
+        this.isProcessingEditQueue = false;
+    }
+    async sendSingleMessage(chatId, text, buttons) {
+        if (text.length > 4096)
+            return null;
+        try {
+            const msg = await this.api.sendMessage(chatId, text, buttons ? { reply_markup: buttons } : {});
+            return msg.message_id;
+        }
+        catch (err) {
+            this.handleError(err, chatId);
+            return null;
+        }
+    }
+    async sendSinglePhoto(chatId, text, photo, buttons) {
+        if (text.length > 2048)
+            return null;
+        try {
+            const file = new grammy_1.InputFile(photo, "photo.png");
+            const msg = await this.api.sendPhoto(chatId, file, {
+                caption: text,
+                ...(buttons ? { reply_markup: buttons } : {}),
+            });
+            return msg.message_id;
+        }
+        catch (err) {
+            this.handleError(err, chatId);
+            return null;
+        }
+    }
+    async editSingleMessage(chatId, msgId, text, buttons) {
+        if (text.length > 4096)
+            return null;
+        try {
+            await this.api.editMessageText(chatId, msgId, text, buttons ? { reply_markup: buttons } : {});
+            return msgId;
+        }
+        catch (err) {
+            this.handleError(err, chatId);
+            return null;
+        }
+    }
+    handleError(error, chatId) {
+        const result = {
+            removeMessage: true,
+            removeUser: false,
+            retrySending: false,
+            retryAfter: 1,
+        };
+        if (!(error instanceof grammy_1.GrammyError)) {
+            console.error(`TelegramQueue unknown error for chat ${chatId}:`, error?.message || error);
+            return result;
+        }
+        const errorCode = error.error_code;
+        const description = error.description || "";
+        if (errorCode === 429) {
+            result.retryAfter = error.parameters?.retry_after || 1;
+            result.removeMessage = false;
+            result.retrySending = true;
+            return result;
+        }
+        if (description.includes("bot was blocked by the user") ||
+            description.includes("chat not found") ||
+            description.includes("bot was kicked") ||
+            description.includes("user is deactivated")) {
+            result.removeUser = true;
+            return result;
+        }
+        if (description.includes("message text is invalid") ||
+            description.includes("message to edit not found")) {
+            return result;
+        }
+        console.error(`TelegramQueue unhandled error for chat ${chatId}: ${errorCode} - ${description}`);
+        return result;
+    }
+    parseReceiver(msg) {
+        const chat = msg.chat;
+        const name = chat.username
+            ? "@" + chat.username
+            : chat.title || `Chat${chat.id}`;
+        return {
+            chatId: chat.id,
+            botId: this.botId,
+            type: chat.type,
+            fullname: `${this.botId}|${name}`,
+        };
+    }
+}
+exports.TelegramQueue = TelegramQueue;

package/dist/esm/index.js

@@ -0,0 +1,256 @@
+import { GrammyError, InputFile } from "grammy";
+/**
+ * Utility function to delay execution.
+ */
+export const sleep = (ms) => new Promise((resolve) => setTimeout(resolve, ms));
+/**
+ * Applies default Telegram API options.
+ */
+export function applyDefaults(method, payload) {
+    if (!payload || typeof payload !== "object") {
+        return;
+    }
+    if (!payload.parse_mode) {
+        payload.parse_mode = "HTML";
+    }
+    if ((method === "sendMessage" || method === "editMessageText") &&
+        !payload.link_preview_options) {
+        payload.link_preview_options = { is_disabled: true };
+    }
+}
+/**
+ * TelegramQueue
+ *
+ * Sequential and rate-limit-safe outgoing message queue
+ * for Telegram bots built with grammy.
+ */
+export class TelegramQueue {
+    constructor(api) {
+        this.botId = "unnamedbot";
+        this.sendQueue = [];
+        this.isProcessingSendQueue = false;
+        this.pendingSendMessages = new Map();
+        this.editQueue = [];
+        this.isProcessingEditQueue = false;
+        this.pendingEditMessages = new Map();
+        this.api = api;
+        this.setupApiMiddleware();
+        this.api
+            .getMe()
+            .then((me) => {
+            this.botId = me.username?.toLowerCase() || "unnamedbot";
+        })
+            .catch(() => {
+            // Silent failure
+        });
+    }
+    setupApiMiddleware() {
+        this.api.config.use((prev, method, payload) => {
+            applyDefaults(method, payload);
+            return prev(method, payload);
+        });
+    }
+    async sendMessage(chatId, text, buttons) {
+        return this.enqueueSendMessage(chatId, text, buttons);
+    }
+    async enqueueSendMessage(chatId, text, buttons) {
+        if (text.length > 4096) {
+            throw new Error("Message too long");
+        }
+        const messageId = `${chatId}_${Date.now()}_${Math.random()}`;
+        let resolve;
+        let reject;
+        const promise = new Promise((res, rej) => {
+            resolve = res;
+            reject = rej;
+        });
+        this.sendQueue.push({
+            chatId,
+            text,
+            buttons,
+            messageId,
+            resolve,
+            reject,
+        });
+        this.pendingSendMessages.set(messageId, promise);
+        if (!this.isProcessingSendQueue) {
+            this.processSendQueue().catch(() => {
+                // Critical failure in queue processor
+                console.error("TelegramQueue send processor crashed");
+            });
+        }
+        return promise;
+    }
+    async processSendQueue() {
+        if (this.isProcessingSendQueue)
+            return;
+        this.isProcessingSendQueue = true;
+        while (this.sendQueue.length > 0) {
+            const item = this.sendQueue[0];
+            try {
+                const msg = await this.api.sendMessage(item.chatId, item.text, item.buttons ? { reply_markup: item.buttons } : {});
+                this.sendQueue.shift();
+                this.pendingSendMessages.delete(item.messageId);
+                item.resolve(msg.message_id);
+                await sleep(200);
+            }
+            catch (err) {
+                const action = this.handleError(err, item.chatId);
+                if (action.retrySending) {
+                    await sleep(action.retryAfter * 1000);
+                    continue;
+                }
+                if (action.removeMessage) {
+                    this.sendQueue.shift();
+                    this.pendingSendMessages.delete(item.messageId);
+                    item.reject(err);
+                }
+            }
+        }
+        this.isProcessingSendQueue = false;
+    }
+    async editMessage(chatId, msgId, text, buttons) {
+        return this.enqueueEditMessage(chatId, msgId, text, buttons);
+    }
+    async enqueueEditMessage(chatId, msgId, text, buttons) {
+        if (text.length > 4096) {
+            throw new Error("Message too long");
+        }
+        const editId = `${chatId}_${msgId}_${Date.now()}`;
+        let resolve;
+        let reject;
+        const promise = new Promise((res, rej) => {
+            resolve = res;
+            reject = rej;
+        });
+        this.editQueue.push({
+            chatId,
+            msgId,
+            text,
+            buttons,
+            editId,
+            resolve,
+            reject,
+        });
+        this.pendingEditMessages.set(editId, promise);
+        if (!this.isProcessingEditQueue) {
+            this.processEditQueue().catch(() => {
+                console.error("TelegramQueue edit processor crashed");
+            });
+        }
+        return promise;
+    }
+    async processEditQueue() {
+        if (this.isProcessingEditQueue)
+            return;
+        this.isProcessingEditQueue = true;
+        while (this.editQueue.length > 0) {
+            const item = this.editQueue[0];
+            try {
+                await this.api.editMessageText(item.chatId, item.msgId, item.text, item.buttons ? { reply_markup: item.buttons } : {});
+                this.editQueue.shift();
+                this.pendingEditMessages.delete(item.editId);
+                item.resolve(true);
+                await sleep(200);
+            }
+            catch (err) {
+                const action = this.handleError(err, item.chatId);
+                if (action.retrySending) {
+                    await sleep(action.retryAfter * 1000);
+                    continue;
+                }
+                if (action.removeMessage) {
+                    this.editQueue.shift();
+                    this.pendingEditMessages.delete(item.editId);
+                    item.reject(err);
+                }
+            }
+        }
+        this.isProcessingEditQueue = false;
+    }
+    async sendSingleMessage(chatId, text, buttons) {
+        if (text.length > 4096)
+            return null;
+        try {
+            const msg = await this.api.sendMessage(chatId, text, buttons ? { reply_markup: buttons } : {});
+            return msg.message_id;
+        }
+        catch (err) {
+            this.handleError(err, chatId);
+            return null;
+        }
+    }
+    async sendSinglePhoto(chatId, text, photo, buttons) {
+        if (text.length > 2048)
+            return null;
+        try {
+            const file = new InputFile(photo, "photo.png");
+            const msg = await this.api.sendPhoto(chatId, file, {
+                caption: text,
+                ...(buttons ? { reply_markup: buttons } : {}),
+            });
+            return msg.message_id;
+        }
+        catch (err) {
+            this.handleError(err, chatId);
+            return null;
+        }
+    }
+    async editSingleMessage(chatId, msgId, text, buttons) {
+        if (text.length > 4096)
+            return null;
+        try {
+            await this.api.editMessageText(chatId, msgId, text, buttons ? { reply_markup: buttons } : {});
+            return msgId;
+        }
+        catch (err) {
+            this.handleError(err, chatId);
+            return null;
+        }
+    }
+    handleError(error, chatId) {
+        const result = {
+            removeMessage: true,
+            removeUser: false,
+            retrySending: false,
+            retryAfter: 1,
+        };
+        if (!(error instanceof GrammyError)) {
+            console.error(`TelegramQueue unknown error for chat ${chatId}:`, error?.message || error);
+            return result;
+        }
+        const errorCode = error.error_code;
+        const description = error.description || "";
+        if (errorCode === 429) {
+            result.retryAfter = error.parameters?.retry_after || 1;
+            result.removeMessage = false;
+            result.retrySending = true;
+            return result;
+        }
+        if (description.includes("bot was blocked by the user") ||
+            description.includes("chat not found") ||
+            description.includes("bot was kicked") ||
+            description.includes("user is deactivated")) {
+            result.removeUser = true;
+            return result;
+        }
+        if (description.includes("message text is invalid") ||
+            description.includes("message to edit not found")) {
+            return result;
+        }
+        console.error(`TelegramQueue unhandled error for chat ${chatId}: ${errorCode} - ${description}`);
+        return result;
+    }
+    parseReceiver(msg) {
+        const chat = msg.chat;
+        const name = chat.username
+            ? "@" + chat.username
+            : chat.title || `Chat${chat.id}`;
+        return {
+            chatId: chat.id,
+            botId: this.botId,
+            type: chat.type,
+            fullname: `${this.botId}|${name}`,
+        };
+    }
+}

package/dist/types/index.d.ts

@@ -0,0 +1,68 @@
+import { Api } from "grammy";
+import type { InlineKeyboard } from "grammy";
+import type { Message } from "grammy/types";
+/**
+ * Internal queue item representing a pending send operation.
+ */
+export type SendQueueItem = {
+    chatId: number | string;
+    text: string;
+    buttons: InlineKeyboard | undefined;
+    messageId: string;
+    resolve: (value: number) => void;
+    reject: (reason?: any) => void;
+};
+/**
+ * Internal queue item representing a pending edit operation.
+ */
+export type EditQueueItem = {
+    chatId: number | string;
+    msgId: number;
+    text: string;
+    buttons: InlineKeyboard | undefined;
+    editId: string;
+    resolve: (value: boolean) => void;
+    reject: (reason?: any) => void;
+};
+/**
+ * Utility function to delay execution.
+ */
+export declare const sleep: (ms: number) => Promise<void>;
+/**
+ * Applies default Telegram API options.
+ */
+export declare function applyDefaults(method: string, payload: any): void;
+/**
+ * TelegramQueue
+ *
+ * Sequential and rate-limit-safe outgoing message queue
+ * for Telegram bots built with grammy.
+ */
+export declare class TelegramQueue {
+    private api;
+    private botId;
+    private sendQueue;
+    private isProcessingSendQueue;
+    private pendingSendMessages;
+    private editQueue;
+    private isProcessingEditQueue;
+    private pendingEditMessages;
+    constructor(api: Api);
+    private setupApiMiddleware;
+    sendMessage(chatId: number | string, text: string, buttons?: InlineKeyboard): Promise<number>;
+    private enqueueSendMessage;
+    private processSendQueue;
+    editMessage(chatId: number | string, msgId: number, text: string, buttons?: InlineKeyboard): Promise<boolean>;
+    private enqueueEditMessage;
+    private processEditQueue;
+    sendSingleMessage(chatId: number | string, text: string, buttons?: InlineKeyboard): Promise<number | null>;
+    sendSinglePhoto(chatId: number | string, text: string, photo: Buffer, buttons?: InlineKeyboard): Promise<number | null>;
+    editSingleMessage(chatId: number | string, msgId: number, text: string, buttons?: InlineKeyboard): Promise<number | null>;
+    private handleError;
+    parseReceiver(msg: Message): {
+        chatId: number;
+        botId: string;
+        type: "private" | "group" | "supergroup" | "channel";
+        fullname: string;
+    };
+}

package/package.json

@@ -0,0 +1,54 @@
+{
+  "name": "grammy-message-queue",
+  "version": "0.1.0",
+  "description": "Reliable sequential message queue for Telegram bots built with grammy. Handles rate limits (429), retry_after and preserves message order.",
+  "keywords": [
+    "telegram",
+    "telegram-bot",
+    "grammy",
+    "message-queue",
+    "rate-limit",
+    "bot",
+    "queue"
+  ],
+  "author": "snipe-dev",
+  "license": "MIT",
+  "repository": {
+    "type": "git",
+    "url": "https://github.com/snipe-dev/grammy-message-queue.git"
+  },
+  "homepage": "https://github.com/snipe-dev/grammy-message-queue#readme",
+  "bugs": {
+    "url": "https://github.com/snipe-dev/grammy-message-queue/issues"
+  },
+  "type": "module",
+  "main": "./dist/cjs/index.js",
+  "module": "./dist/esm/index.js",
+  "types": "./dist/types/index.d.ts",
+  "exports": {
+    ".": {
+      "types": "./dist/types/index.d.ts",
+      "require": "./dist/cjs/index.js",
+      "import": "./dist/esm/index.js"
+    }
+  },
+  "files": [
+    "dist"
+  ],
+  "scripts": {
+    "build:esm": "tsc -p tsconfig.esm.json",
+    "build:cjs": "tsc -p tsconfig.cjs.json",
+    "build": "npm run build:esm && npm run build:cjs",
+    "prepublishOnly": "npm run build"
+  },
+  "engines": {
+    "node": ">=16"
+  },
+  "peerDependencies": {
+    "grammy": "^1.39.0"
+  },
+  "devDependencies": {
+    "@types/node": "^25.1.0",
+    "typescript": "^5.4.0"
+  }
+}