@zhin.js/adapter-telegram 1.0.69 → 1.1.2

package/lib/index.js

@@ -1,455 +1,4 @@
-/**
- * Telegram 适配器入口：类型扩展、导出、注册
- */
-import path from "node:path";
-import { usePlugin, createGroupManagementTools } from "zhin.js";
-import { TelegramAdapter } from "./adapter.js";
-export * from "./types.js";
-export { TelegramBot } from "./bot.js";
-export { TelegramAdapter } from "./adapter.js";
-const plugin = usePlugin();
-const { provide, useContext } = plugin;
-provide({
-    name: "telegram",
-    description: "Telegram Bot Adapter",
-    mounted: async (p) => {
-        const adapter = new TelegramAdapter(p);
-        await adapter.start();
-        return adapter;
-    },
-    dispose: async (adapter) => {
-        await adapter.stop();
-    },
-});
-useContext('tool', 'telegram', (toolService, telegram) => {
-    const groupTools = createGroupManagementTools(telegram, 'telegram');
-    const disposers = groupTools.map(t => toolService.addTool(t, plugin.name));
-    disposers.push(toolService.addTool({
-        name: 'telegram_pin_message',
-        description: '置顶 Telegram 群组消息',
-        parameters: {
-            type: 'object',
-            properties: {
-                bot: { type: 'string', description: 'Bot 名称' },
-                chat_id: { type: 'string', description: '聊天 ID' },
-                message_id: { type: 'string', description: '消息 ID' },
-            },
-            required: ['bot', 'chat_id', 'message_id'],
-        },
-        platforms: ['telegram'],
-        tags: ['telegram'],
-        execute: async (args) => {
-            const bot = telegram.bots.get(args.bot);
-            if (!bot)
-                throw new Error(`Bot ${args.bot} 不存在`);
-            const success = await bot.pinMessage(Number(args.chat_id), Number(args.message_id));
-            return { success, message: success ? '消息已置顶' : '操作失败' };
-        },
-    }, plugin.name));
-    disposers.push(toolService.addTool({
-        name: 'telegram_unpin_message',
-        description: '取消置顶 Telegram 群组消息',
-        parameters: {
-            type: 'object',
-            properties: {
-                bot: { type: 'string', description: 'Bot 名称' },
-                chat_id: { type: 'string', description: '聊天 ID' },
-                message_id: { type: 'string', description: '消息 ID（可选，不提供则取消所有置顶）' },
-            },
-            required: ['bot', 'chat_id'],
-        },
-        platforms: ['telegram'],
-        tags: ['telegram'],
-        execute: async (args) => {
-            const bot = telegram.bots.get(args.bot);
-            if (!bot)
-                throw new Error(`Bot ${args.bot} 不存在`);
-            const success = await bot.unpinMessage(Number(args.chat_id), args.message_id ? Number(args.message_id) : undefined);
-            return { success, message: success ? '已取消置顶' : '操作失败' };
-        },
-    }, plugin.name));
-    disposers.push(toolService.addTool({
-        name: 'telegram_list_admins',
-        description: '获取 Telegram 群组管理员列表',
-        parameters: {
-            type: 'object',
-            properties: {
-                bot: { type: 'string', description: 'Bot 名称' },
-                chat_id: { type: 'string', description: '聊天 ID' },
-            },
-            required: ['bot', 'chat_id'],
-        },
-        platforms: ['telegram'],
-        tags: ['telegram'],
-        execute: async (args) => {
-            const bot = telegram.bots.get(args.bot);
-            if (!bot)
-                throw new Error(`Bot ${args.bot} 不存在`);
-            const admins = await bot.getChatAdmins(Number(args.chat_id));
-            return {
-                admins: admins.map((a) => ({
-                    user_id: a.user.id,
-                    username: a.user.username,
-                    first_name: a.user.first_name,
-                    status: a.status,
-                })),
-                count: admins.length,
-            };
-        },
-    }, plugin.name));
-    disposers.push(toolService.addTool({
-        name: 'telegram_member_count',
-        description: '获取 Telegram 群组成员数量',
-        parameters: {
-            type: 'object',
-            properties: {
-                bot: { type: 'string', description: 'Bot 名称' },
-                chat_id: { type: 'string', description: '聊天 ID' },
-            },
-            required: ['bot', 'chat_id'],
-        },
-        platforms: ['telegram'],
-        tags: ['telegram'],
-        execute: async (args) => {
-            const bot = telegram.bots.get(args.bot);
-            if (!bot)
-                throw new Error(`Bot ${args.bot} 不存在`);
-            const count = await bot.getChatMemberCount(Number(args.chat_id));
-            return { count, message: `群组共有 ${count} 名成员` };
-        },
-    }, plugin.name));
-    disposers.push(toolService.addTool({
-        name: 'telegram_create_invite',
-        description: '创建 Telegram 群组邀请链接',
-        parameters: {
-            type: 'object',
-            properties: {
-                bot: { type: 'string', description: 'Bot 名称' },
-                chat_id: { type: 'string', description: '聊天 ID' },
-            },
-            required: ['bot', 'chat_id'],
-        },
-        platforms: ['telegram'],
-        tags: ['telegram'],
-        execute: async (args) => {
-            const bot = telegram.bots.get(args.bot);
-            if (!bot)
-                throw new Error(`Bot ${args.bot} 不存在`);
-            const link = await bot.createInviteLink(Number(args.chat_id));
-            return { invite_link: link, message: `邀请链接: ${link}` };
-        },
-    }, plugin.name));
-    disposers.push(toolService.addTool({
-        name: 'telegram_send_poll',
-        description: '在 Telegram 群组中发起投票',
-        parameters: {
-            type: 'object',
-            properties: {
-                bot: { type: 'string', description: 'Bot 名称' },
-                chat_id: { type: 'string', description: '聊天 ID' },
-                question: { type: 'string', description: '投票问题' },
-                options: { type: 'string', description: '选项 JSON 数组，如 ["A","B","C"]' },
-                is_anonymous: { type: 'boolean', description: '是否匿名投票，默认 true' },
-                allows_multiple: { type: 'boolean', description: '是否允许多选，默认 false' },
-            },
-            required: ['bot', 'chat_id', 'question', 'options'],
-        },
-        platforms: ['telegram'],
-        tags: ['telegram'],
-        execute: async (args) => {
-            const bot = telegram.bots.get(args.bot);
-            if (!bot)
-                throw new Error(`Bot ${args.bot} 不存在`);
-            let optList;
-            try {
-                optList = JSON.parse(args.options);
-            }
-            catch {
-                return { success: false, message: 'options 格式错误，应为 JSON 数组' };
-            }
-            if (!Array.isArray(optList) || optList.length < 2) {
-                return { success: false, message: '至少需要 2 个选项' };
-            }
-            const result = await bot.sendPoll(Number(args.chat_id), args.question, optList, args.is_anonymous ?? true, args.allows_multiple ?? false);
-            return { success: true, message_id: result.message_id, message: '投票已发送' };
-        },
-    }, plugin.name));
-    disposers.push(toolService.addTool({
-        name: 'telegram_react',
-        description: '对 Telegram 消息添加表情反应',
-        parameters: {
-            type: 'object',
-            properties: {
-                bot: { type: 'string', description: 'Bot 名称' },
-                chat_id: { type: 'string', description: '聊天 ID' },
-                message_id: { type: 'string', description: '消息 ID' },
-                reaction: { type: 'string', description: '反应表情（如 👍、❤️、🔥）' },
-            },
-            required: ['bot', 'chat_id', 'message_id', 'reaction'],
-        },
-        platforms: ['telegram'],
-        tags: ['telegram'],
-        execute: async (args) => {
-            const bot = telegram.bots.get(args.bot);
-            if (!bot)
-                throw new Error(`Bot ${args.bot} 不存在`);
-            const success = await bot.setMessageReaction(Number(args.chat_id), Number(args.message_id), args.reaction);
-            return { success, message: success ? `已添加反应 ${args.reaction}` : '操作失败' };
-        },
-    }, plugin.name));
-    disposers.push(toolService.addTool({
-        name: 'telegram_send_sticker',
-        description: '发送 Telegram 贴纸',
-        parameters: {
-            type: 'object',
-            properties: {
-                bot: { type: 'string', description: 'Bot 名称' },
-                chat_id: { type: 'string', description: '聊天 ID' },
-                sticker: { type: 'string', description: '贴纸 file_id 或 URL' },
-            },
-            required: ['bot', 'chat_id', 'sticker'],
-        },
-        platforms: ['telegram'],
-        tags: ['telegram'],
-        execute: async (args) => {
-            const bot = telegram.bots.get(args.bot);
-            if (!bot)
-                throw new Error(`Bot ${args.bot} 不存在`);
-            const result = await bot.sendStickerMessage(Number(args.chat_id), args.sticker);
-            return { success: true, message_id: result.message_id, message: '贴纸已发送' };
-        },
-    }, plugin.name));
-    disposers.push(toolService.addTool({
-        name: 'telegram_set_permissions',
-        description: '设置 Telegram 群组的默认成员权限',
-        parameters: {
-            type: 'object',
-            properties: {
-                bot: { type: 'string', description: 'Bot 名称' },
-                chat_id: { type: 'string', description: '聊天 ID' },
-                can_send_messages: { type: 'boolean', description: '是否可以发消息' },
-                can_send_photos: { type: 'boolean', description: '是否可以发图片' },
-                can_send_videos: { type: 'boolean', description: '是否可以发视频' },
-                can_send_polls: { type: 'boolean', description: '是否可以发投票' },
-                can_send_other_messages: { type: 'boolean', description: '是否可以发贴纸/GIF等' },
-                can_add_web_page_previews: { type: 'boolean', description: '是否可以添加网页预览' },
-                can_change_info: { type: 'boolean', description: '是否可以改群信息' },
-                can_invite_users: { type: 'boolean', description: '是否可以邀请用户' },
-                can_pin_messages: { type: 'boolean', description: '是否可以置顶消息' },
-            },
-            required: ['bot', 'chat_id'],
-        },
-        platforms: ['telegram'],
-        tags: ['telegram'],
-        execute: async (args) => {
-            const { bot: botId, chat_id, ...perms } = args;
-            const bot = telegram.bots.get(botId);
-            if (!bot)
-                throw new Error(`Bot ${botId} 不存在`);
-            const permissions = {};
-            for (const [k, v] of Object.entries(perms)) {
-                if (typeof v === 'boolean')
-                    permissions[k] = v;
-            }
-            const success = await bot.setChatPermissionsAll(Number(chat_id), permissions);
-            return { success, message: success ? '群权限已更新' : '操作失败' };
-        },
-    }, plugin.name));
-    disposers.push(toolService.addTool({
-        name: 'telegram_set_description',
-        description: '设置 Telegram 群组描述',
-        parameters: {
-            type: 'object',
-            properties: {
-                bot: { type: 'string', description: 'Bot 名称' },
-                chat_id: { type: 'string', description: '聊天 ID' },
-                description: { type: 'string', description: '群描述文字' },
-            },
-            required: ['bot', 'chat_id', 'description'],
-        },
-        platforms: ['telegram'],
-        tags: ['telegram'],
-        execute: async (args) => {
-            const bot = telegram.bots.get(args.bot);
-            if (!bot)
-                throw new Error(`Bot ${args.bot} 不存在`);
-            const success = await bot.setChatDescription(Number(args.chat_id), args.description);
-            return { success, message: success ? '群描述已更新' : '操作失败' };
-        },
-    }, plugin.name));
-    return () => disposers.forEach(d => d());
-});
-// ── Web 控制台 ─────────────────────────────────────────────────────────
-useContext("web", (pageManager) => {
-    pageManager.addEntry({
-        id: "telegram",
-        development: path.resolve(import.meta.dirname, "../client/index.tsx"),
-        production: path.resolve(import.meta.dirname, "../dist/index.js"),
-        meta: { name: "Telegram" },
-    });
-});
-useContext("router", "telegram", (router, telegram) => {
-    router.get("/api/telegram/bots", async (ctx) => {
-        try {
-            const bots = Array.from(telegram.bots.values());
-            const result = bots.map((bot) => {
-                try {
-                    return {
-                        name: bot.$config.name,
-                        connected: bot.$connected || false,
-                        mode: bot.$config.polling !== false ? "polling" : "webhook",
-                        status: bot.$connected ? "online" : "offline",
-                        botInfo: bot.botInfo ? { username: bot.botInfo.username, firstName: bot.botInfo.first_name } : null,
-                    };
-                }
-                catch {
-                    return { name: bot.$config.name, connected: false, mode: "unknown", status: "error", botInfo: null };
-                }
-            });
-            ctx.body = { success: true, data: result };
-        }
-        catch {
-            ctx.status = 500;
-            ctx.body = { success: false, error: "获取机器人数据失败" };
-        }
-    });
-    // Bot 连接/断开
-    router.post("/api/telegram/bots/:name/connect", async (ctx) => {
-        try {
-            const bot = telegram.bots.get(ctx.params.name);
-            if (!bot) {
-                ctx.status = 404;
-                ctx.body = { success: false, error: "Bot 不存在" };
-                return;
-            }
-            if (bot.$connected) {
-                ctx.body = { success: true, message: "已经在线" };
-                return;
-            }
-            await bot.$connect();
-            ctx.body = { success: true, message: "连接成功" };
-        }
-        catch (e) {
-            ctx.status = 500;
-            ctx.body = { success: false, error: e?.message || "连接失败" };
-        }
-    });
-    router.post("/api/telegram/bots/:name/disconnect", async (ctx) => {
-        try {
-            const bot = telegram.bots.get(ctx.params.name);
-            if (!bot) {
-                ctx.status = 404;
-                ctx.body = { success: false, error: "Bot 不存在" };
-                return;
-            }
-            if (!bot.$connected) {
-                ctx.body = { success: true, message: "已经离线" };
-                return;
-            }
-            await bot.$disconnect();
-            ctx.body = { success: true, message: "已断开" };
-        }
-        catch (e) {
-            ctx.status = 500;
-            ctx.body = { success: false, error: e?.message || "断开失败" };
-        }
-    });
-    // 快捷操作：创建邀请链接
-    router.post("/api/telegram/bots/:name/invite", async (ctx) => {
-        try {
-            const bot = telegram.bots.get(ctx.params.name);
-            if (!bot) {
-                ctx.status = 404;
-                ctx.body = { success: false, error: "Bot 不存在" };
-                return;
-            }
-            if (!bot.$connected) {
-                ctx.status = 400;
-                ctx.body = { success: false, error: "Bot 未连接" };
-                return;
-            }
-            const { chat_id } = ctx.request.body || {};
-            if (!chat_id) {
-                ctx.status = 400;
-                ctx.body = { success: false, error: "缺少 chat_id" };
-                return;
-            }
-            const link = await bot.createInviteLink(Number(chat_id));
-            ctx.body = { success: true, data: { invite_link: link } };
-        }
-        catch (e) {
-            ctx.status = 500;
-            ctx.body = { success: false, error: e?.message || "创建邀请链接失败" };
-        }
-    });
-    // 快捷操作：发起投票
-    router.post("/api/telegram/bots/:name/poll", async (ctx) => {
-        try {
-            const bot = telegram.bots.get(ctx.params.name);
-            if (!bot) {
-                ctx.status = 404;
-                ctx.body = { success: false, error: "Bot 不存在" };
-                return;
-            }
-            if (!bot.$connected) {
-                ctx.status = 400;
-                ctx.body = { success: false, error: "Bot 未连接" };
-                return;
-            }
-            const { chat_id, question, options, is_anonymous, allows_multiple } = ctx.request.body || {};
-            if (!chat_id || !question || !options?.length) {
-                ctx.status = 400;
-                ctx.body = { success: false, error: "缺少 chat_id, question 或 options" };
-                return;
-            }
-            if (options.length < 2) {
-                ctx.status = 400;
-                ctx.body = { success: false, error: "至少需要 2 个选项" };
-                return;
-            }
-            const result = await bot.sendPoll(Number(chat_id), question, options, is_anonymous ?? true, allows_multiple ?? false);
-            ctx.body = { success: true, data: { message_id: result.message_id } };
-        }
-        catch (e) {
-            ctx.status = 500;
-            ctx.body = { success: false, error: e?.message || "发起投票失败" };
-        }
-    });
-    // 快捷操作：获取群管理员
-    router.get("/api/telegram/bots/:name/admins", async (ctx) => {
-        try {
-            const bot = telegram.bots.get(ctx.params.name);
-            if (!bot) {
-                ctx.status = 404;
-                ctx.body = { success: false, error: "Bot 不存在" };
-                return;
-            }
-            if (!bot.$connected) {
-                ctx.status = 400;
-                ctx.body = { success: false, error: "Bot 未连接" };
-                return;
-            }
-            const chat_id = ctx.query.chat_id;
-            if (!chat_id) {
-                ctx.status = 400;
-                ctx.body = { success: false, error: "缺少 chat_id" };
-                return;
-            }
-            const admins = await bot.getChatAdmins(Number(chat_id));
-            ctx.body = {
-                success: true,
-                data: admins.map((a) => ({
-                    user_id: a.user.id,
-                    username: a.user.username,
-                    first_name: a.user.first_name,
-                    status: a.status,
-                })),
-            };
-        }
-        catch (e) {
-            ctx.status = 500;
-            ctx.body = { success: false, error: e?.message || "获取管理员失败" };
-        }
-    });
-});
-//# sourceMappingURL=index.js.map
+export { TelegramClient, TelegramEndpoint, } from './endpoint.js';
+export { botApiUrl, formatCallbackContent, formatInboundContent, formatOutboundActions, formatOutboundPlan, normalizeWebhookPath, resolveTelegramConfig, senderDisplayName, } from './protocol.js';
+export { telegramClient } from './client.js';
+export { checkTelegramPlatformPermit, normalizeTelegramChatMember, platformPermit, telegramGroupPermitResolver, } from './platform-permit.js';

package/lib/markdown-to-html.d.ts

@@ -0,0 +1,9 @@
+/**
+ * Canonical Markdown → Telegram Bot API HTML.
+ *
+ * Telegram's MarkdownV2 is not CommonMark-compatible and rejects unescaped
+ * punctuation. HTML gives the adapter a safer dialect seam: user text is
+ * escaped first and only the subset supported by Bot API is emitted as tags.
+ */
+export declare function markdownToTelegramHtml(markdown: string): string;
+export declare function escapeTelegramHtml(value: string): string;

package/lib/markdown-to-html.js

@@ -0,0 +1,75 @@
+/**
+ * Canonical Markdown → Telegram Bot API HTML.
+ *
+ * Telegram's MarkdownV2 is not CommonMark-compatible and rejects unescaped
+ * punctuation. HTML gives the adapter a safer dialect seam: user text is
+ * escaped first and only the subset supported by Bot API is emitted as tags.
+ */
+export function markdownToTelegramHtml(markdown) {
+    const protectedFragments = [];
+    const protect = (html) => {
+        const token = `\uE000${protectedFragments.length}\uE001`;
+        protectedFragments.push(html);
+        return token;
+    };
+    let value = protectTelegramFencedCode(markdown, protect);
+    value = value.replace(/`([^`\n]+)`/g, (_match, code) => (protect(`<code>${escapeTelegramHtml(String(code))}</code>`)));
+    value = escapeTelegramHtml(value);
+    value = value
+        .replace(/!\[([^\[\]]*)\]\(([^()\s]+)(?:\s+&quot;[^&]*&quot;)?\)/g, '$1')
+        .replace(/\[([^\[\]]+)\]\(([^()\s]+)(?:\s+&quot;[^&]*&quot;)?\)/g, (_match, label, href) => isSafeTelegramHref(href)
+        ? `<a href="${href}">${label}</a>`
+        : label)
+        .replace(/^#{1,6}\s+(.+)$/gm, '<b>$1</b>')
+        .replace(/^&gt;\s?(.*)$/gm, '<blockquote>$1</blockquote>')
+        .replace(/^\s*[-+*]\s+(.+)$/gm, '• $1')
+        .replace(/\*\*([^*\n]+)\*\*/g, '<b>$1</b>')
+        .replace(/__([^_\n]+)__/g, '<b>$1</b>')
+        .replace(/~~([^~\n]+)~~/g, '<s>$1</s>')
+        .replace(/(^|[^*])\*([^*\n]+)\*/g, '$1<i>$2</i>')
+        .replace(/(^|[^_])_([^_\n]+)_/g, '$1<i>$2</i>');
+    for (let index = 0; index < protectedFragments.length; index += 1) {
+        value = value.replace(`\uE000${index}\uE001`, protectedFragments[index]);
+    }
+    return value;
+}
+function protectTelegramFencedCode(markdown, protect) {
+    const chunks = [];
+    let cursor = 0;
+    while (cursor < markdown.length) {
+        const opening = markdown.indexOf('```', cursor);
+        if (opening < 0) {
+            chunks.push(markdown.slice(cursor));
+            break;
+        }
+        chunks.push(markdown.slice(cursor, opening));
+        const contentStart = opening + 3;
+        const closing = markdown.indexOf('```', contentStart);
+        if (closing < 0) {
+            chunks.push(markdown.slice(opening));
+            break;
+        }
+        const newline = markdown.indexOf('\n', contentStart);
+        const hasHeader = newline >= 0 && newline < closing;
+        const language = markdown.slice(contentStart, hasHeader ? newline : closing).trim();
+        let code = hasHeader ? markdown.slice(newline + 1, closing) : '';
+        if (code.endsWith('\n'))
+            code = code.slice(0, -1);
+        const escapedCode = escapeTelegramHtml(code);
+        chunks.push(/^[A-Za-z0-9_+-]+$/.test(language)
+            ? protect(`<pre><code class="language-${language}">${escapedCode}</code></pre>`)
+            : protect(`<pre>${escapedCode}</pre>`));
+        cursor = closing + 3;
+    }
+    return chunks.join('');
+}
+function isSafeTelegramHref(value) {
+    return /^(?:https?:\/\/|tg:\/\/|mailto:)[^\s<>]+$/iu.test(value);
+}
+export function escapeTelegramHtml(value) {
+    return value
+        .replace(/&/g, '&amp;')
+        .replace(/</g, '&lt;')
+        .replace(/>/g, '&gt;')
+        .replace(/"/g, '&quot;');
+}

package/lib/platform-permit.d.ts

@@ -0,0 +1,17 @@
+/**
+ * Telegram platform permit — ChatMember 状态 + 细粒度权限
+ */
+import type { PermissionSubject } from '@zhin.js/permission';
+export declare function platformPermit(perm: string): string;
+export declare function telegramGroupPermitResolver(logicalPerm: string): string;
+export declare function normalizeTelegramChatMember(member: {
+    status?: string;
+    can_restrict_members?: boolean;
+    can_pin_messages?: boolean;
+    can_delete_messages?: boolean;
+    can_manage_chat?: boolean;
+}): {
+    role?: string;
+    permissions: string[];
+};
+export declare function checkTelegramPlatformPermit(perm: string, subject: PermissionSubject): boolean;

package/lib/platform-permit.js

@@ -0,0 +1,51 @@
+const ADAPTER = 'telegram';
+export function platformPermit(perm) {
+    return `platform(${ADAPTER},${perm})`;
+}
+const FACTORY_PERM_MAP = {
+    scene_admin: 'chat_administrator',
+    scene_owner: 'chat_creator',
+};
+export function telegramGroupPermitResolver(logicalPerm) {
+    return platformPermit(FACTORY_PERM_MAP[logicalPerm] ?? logicalPerm);
+}
+export function normalizeTelegramChatMember(member) {
+    const permissions = [];
+    const status = member.status;
+    if (status === 'creator') {
+        permissions.push('chat_creator', 'chat_administrator', 'restrict_members', 'pin_messages');
+        return { role: 'creator', permissions };
+    }
+    if (status === 'administrator') {
+        permissions.push('chat_administrator');
+        if (member.can_restrict_members)
+            permissions.push('restrict_members');
+        if (member.can_pin_messages)
+            permissions.push('pin_messages');
+        if (member.can_delete_messages)
+            permissions.push('delete_messages');
+        if (member.can_manage_chat)
+            permissions.push('manage_chat');
+        return { role: 'administrator', permissions };
+    }
+    return { role: 'member', permissions };
+}
+export function checkTelegramPlatformPermit(perm, subject) {
+    const role = subject.sender?.role?.[0];
+    const permissions = subject.sender?.permissions ?? [];
+    const has = (t) => permissions.includes(t);
+    switch (perm) {
+        case 'chat_creator':
+            return role === 'creator' || has('chat_creator');
+        case 'chat_administrator':
+            return role === 'creator' || role === 'administrator' || has('chat_administrator');
+        case 'restrict_members':
+            return has('restrict_members') || role === 'creator';
+        case 'pin_messages':
+            return has('pin_messages') || role === 'creator';
+        case 'manage_chat':
+            return has('manage_chat') || role === 'creator';
+        default:
+            return false;
+    }
+}

package/lib/polling.d.ts

@@ -0,0 +1,9 @@
+import type { TelegramUpdate } from './protocol.js';
+export interface TelegramPollingHost {
+    readonly allowedUpdates: readonly string[];
+    callApi<T>(method: string, params?: Record<string, unknown>, signal?: AbortSignal): Promise<T>;
+    getUpdateOffset(): number;
+    setUpdateOffset(offset: number): void;
+    handleUpdate(update: TelegramUpdate): void;
+}
+export declare function runTelegramPollLoop(host: TelegramPollingHost, abortSignal: AbortSignal): Promise<void>;

package/lib/polling.js

@@ -0,0 +1,57 @@
+/**
+ * Telegram long-polling loop for getUpdates.
+ */
+import { formatCompact, getLogger } from '@zhin.js/logger';
+const logger = getLogger('telegram');
+const RETRY_DELAY_MS = 2_000;
+const BACKOFF_DELAY_MS = 10_000;
+const MAX_CONSECUTIVE_FAILURES = 5;
+const DEFAULT_POLL_TIMEOUT_SEC = 30;
+export async function runTelegramPollLoop(host, abortSignal) {
+    let consecutiveFailures = 0;
+    while (!abortSignal.aborted) {
+        try {
+            const updates = await host.callApi('getUpdates', {
+                offset: host.getUpdateOffset() || undefined,
+                timeout: DEFAULT_POLL_TIMEOUT_SEC,
+                allowed_updates: host.allowedUpdates,
+            }, abortSignal);
+            consecutiveFailures = 0;
+            for (const update of updates) {
+                // A transport may resolve after cancellation; never admit that late batch.
+                if (abortSignal.aborted)
+                    return;
+                host.setUpdateOffset(update.update_id + 1);
+                host.handleUpdate(update);
+            }
+        }
+        catch (err) {
+            if (abortSignal.aborted)
+                return;
+            consecutiveFailures += 1;
+            logger.error(formatCompact({
+                op: 'poll',
+                ok: false,
+                error: err instanceof Error ? err.message : String(err),
+            }));
+            // 不在退避后清零：对端持续挂时清零会让重试固定打满 RETRY_DELAY_MS，
+            // 保持计数才能让 BACKOFF_DELAY_MS 持续生效（成功时上面才清零）。
+            await sleep(consecutiveFailures >= MAX_CONSECUTIVE_FAILURES ? BACKOFF_DELAY_MS : RETRY_DELAY_MS, abortSignal);
+        }
+    }
+}
+function sleep(ms, signal) {
+    return new Promise((resolve) => {
+        if (signal?.aborted) {
+            resolve();
+            return;
+        }
+        const finish = () => {
+            clearTimeout(timer);
+            signal?.removeEventListener('abort', finish);
+            resolve();
+        };
+        const timer = setTimeout(finish, ms);
+        signal?.addEventListener('abort', finish, { once: true });
+    });
+}