@zhin.js/adapter-telegram 5.0.1 → 5.0.3

package/lib/endpoint.js

@@ -1,1046 +1,332 @@
-/**
- * Telegram Endpoint 实现
- */
-import { Telegraf } from "telegraf";
-import { Message, segment, expandInteractiveSegmentsInContent, } from 'zhin.js';
-import { normalizeTelegramChatMember } from "./platform-permit.js";
-import { fromCanonicalSegments, toCanonicalSegments } from './segment-mapper.js';
-export class TelegramEndpoint extends Telegraf {
-    adapter;
-    $config;
-    $connected = false;
-    /** message_id -> chat_id，用于在仅有 message_id 的场景执行 reaction 操作 */
-    messageChatMap = new Map();
-    /** reply_to_message 解析结果缓存，供 $getMsg 使用 */
-    quotedPayloadCache = new Map();
-    get pluginLogger() {
-        return this.adapter.plugin.logger;
-    }
-    get $id() {
-        return this.$config.name;
-    }
-    constructor(adapter, $config) {
-        super($config.token);
-        this.adapter = adapter;
-        this.$config = $config;
-    }
-    async $connect() {
+import { formatCompact, getLogger } from '@zhin.js/logger';
+import { runTelegramPollLoop } from './polling.js';
+import { normalizeTelegramChatMember } from './platform-permit.js';
+import { botApiUrl, buildWebhookUrl, formatCallbackContent, formatInboundContent, formatOutboundActions, resolveChannel, senderDisplayName, } from './protocol.js';
+import { registerTelegramAgentEndpoint } from './telegram-agent-deps.js';
+import { registerTelegramWebhookRoutes } from './webhook.js';
+const logger = getLogger('telegram');
+const CHAT_MEMBER_CACHE_TTL_MS = 60_000;
+const CHAT_MEMBER_CACHE_MAX = 2_000;
+export class TelegramEndpoint {
+    #options;
+    #fetch;
+    #pollAbort;
+    #pollPromise;
+    #routeReleases = [];
+    #open = false;
+    #started = false;
+    #unregisterAgent;
+    #updateOffset = 0;
+    #botUserId;
+    #botUsername;
+    #chatMemberCache = new Map();
+    constructor(options) {
+        this.#options = options;
+        this.#fetch = options.fetch ?? globalThis.fetch;
+    }
+    /** Used by webhook handler. */
+    get isOpen() {
+        return this.#open;
+    }
+    get config() {
+        return this.#options.config;
+    }
+    get allowedUpdates() {
+        return this.#options.config.allowedUpdates;
+    }
+    getUpdateOffset() {
+        return this.#updateOffset;
+    }
+    setUpdateOffset(offset) {
+        this.#updateOffset = offset;
+    }
+    async start() {
+        if (this.#started)
+            return;
+        this.#started = true;
         try {
-            // Set up message handler
-            this.on("message", async (ctx) => {
-                await this.handleTelegramMessage(ctx);
-            });
-            // Set up callback query handler (for inline buttons)
-            this.on("callback_query", async (ctx) => {
-                if (ctx.callbackQuery && "data" in ctx.callbackQuery) {
-                    try {
-                        await ctx.answerCbQuery();
-                    }
-                    catch {
-                        // already answered
-                    }
-                    const message = this.$formatCallbackQuery(ctx);
-                    this.adapter.emit("message.receive", message);
-                    this.pluginLogger.debug(`${this.$config.name} recv callback ${message.$channel.type}(${message.$channel.id}): ${segment.raw(message.$content)}`);
+            this.#unregisterAgent = registerTelegramAgentEndpoint(this.#options.config.name, this);
+            const me = await this.callApi('getMe');
+            this.#botUserId = me.id;
+            this.#botUsername = me.username;
+            if (this.#options.config.mode === 'webhook') {
+                if (!this.#options.http) {
+                    throw new TypeError('Telegram webhook mode requires httpHostToken');
                 }
-            });
-            // Start bot with polling or webhook
-            if (this.$config.polling !== false) {
-                // Use polling by default
-                await this.launch({
-                    allowedUpdates: this.$config.allowedUpdates,
-                });
-            }
-            else if (this.$config.webhook) {
-                // Use webhook
-                const { domain, path = "/telegram-webhook", port } = this.$config.webhook;
-                await this.launch({
-                    webhook: {
-                        domain,
-                        port,
-                        hookPath: path,
-                    },
-                    allowedUpdates: this.$config.allowedUpdates,
+                this.#routeReleases.push(...registerTelegramWebhookRoutes(this.#options.http, this));
+                const webhook = this.#options.config.webhook;
+                const url = buildWebhookUrl(webhook);
+                await this.callApi('setWebhook', {
+                    url,
+                    allowed_updates: this.#options.config.allowedUpdates,
+                    ...(webhook.secretToken ? { secret_token: webhook.secretToken } : {}),
                 });
+                logger.info(formatCompact({
+                    op: 'connect',
+                    endpoint: this.#options.config.name,
+                    mode: 'webhook',
+                    path: webhook.path,
+                    username: me.username,
+                }));
+                return;
             }
-            else {
-                throw new Error("Either polling must be enabled or webhook configuration must be provided");
-            }
-            this.$connected = true;
-            const me = await this.telegram.getMe();
-            this.pluginLogger.info(`Telegram endpoint ${this.$config.name} connected successfully as @${me.username}`);
+            await this.callApi('deleteWebhook', { drop_pending_updates: false });
+            this.#pollAbort = new AbortController();
+            this.#pollPromise = runTelegramPollLoop(this, this.#pollAbort.signal);
+            logger.info(formatCompact({
+                op: 'connect',
+                endpoint: this.#options.config.name,
+                mode: 'polling',
+                username: me.username,
+            }));
         }
         catch (error) {
-            this.pluginLogger.error("Failed to connect Telegram bot:", error);
-            this.$connected = false;
-            throw error;
-        }
-    }
-    async $disconnect() {
-        try {
-            this.removeAllListeners();
-            this.chatMemberCache.clear();
             await this.stop();
-            this.$connected = false;
-            this.pluginLogger.info(`Telegram endpoint ${this.$config.name} disconnected`);
-        }
-        catch (error) {
-            this.pluginLogger.error("Error disconnecting Telegram bot:", error);
+            logger.error('Failed to connect Telegram bot:', error);
             throw error;
         }
     }
-    static CHAT_MEMBER_CACHE_TTL_MS = 60_000;
-    static CHAT_MEMBER_CACHE_MAX = 2_000;
-    chatMemberCache = new Map();
-    sweepChatMemberCache(now) {
-        const ttl = TelegramEndpoint.CHAT_MEMBER_CACHE_TTL_MS;
-        for (const [key, entry] of this.chatMemberCache) {
-            if (now - entry.at >= ttl)
-                this.chatMemberCache.delete(key);
-        }
-        if (this.chatMemberCache.size > TelegramEndpoint.CHAT_MEMBER_CACHE_MAX) {
-            const excess = this.chatMemberCache.size - TelegramEndpoint.CHAT_MEMBER_CACHE_MAX;
-            let removed = 0;
-            for (const [key] of this.chatMemberCache) {
-                if (removed >= excess)
-                    break;
-                this.chatMemberCache.delete(key);
-                removed++;
-            }
-        }
+    open() {
+        this.#open = true;
     }
-    async enrichGroupSender(message, msg) {
-        if (message.$channel.type !== "group" || !msg.from?.id)
-            return;
-        const chatId = Number(msg.chat.id);
-        const userId = msg.from.id;
-        const key = `${chatId}:${userId}`;
-        const now = Date.now();
-        this.sweepChatMemberCache(now);
-        const cached = this.chatMemberCache.get(key);
-        if (cached && now - cached.at < TelegramEndpoint.CHAT_MEMBER_CACHE_TTL_MS) {
-            message.$sender.role = cached.role;
-            message.$sender.permissions = cached.permissions;
-            return;
-        }
+    close() {
+        this.#open = false;
+    }
+    async stop() {
+        this.#open = false;
+        this.#pollAbort?.abort();
         try {
-            const member = await this.getChatMember(chatId, userId);
-            const normalized = normalizeTelegramChatMember(member);
-            this.chatMemberCache.set(key, { at: now, ...normalized });
-            message.$sender.role = normalized.role;
-            message.$sender.permissions = normalized.permissions;
+            await this.#pollPromise;
         }
         catch {
-            // 保守拒绝：无角色快照
-        }
-    }
-    async handleTelegramMessage(ctx) {
-        if (!ctx.message)
+            /* poll loop exit */
+        }
+        for (const release of this.#routeReleases.splice(0))
+            release();
+        this.#unregisterAgent?.();
+        this.#unregisterAgent = undefined;
+        this.#chatMemberCache.clear();
+        this.#started = false;
+        logger.debug(formatCompact({ op: 'disconnect', endpoint: this.#options.config.name }));
+    }
+    async send({ target, payload }) {
+        const actions = formatOutboundActions(target, payload);
+        let lastId = '';
+        for (const action of actions) {
+            const result = await this.callApi(action.method, action.params);
+            if (result.message_id != null)
+                lastId = String(result.message_id);
+        }
+        return lastId || `telegram-${Date.now()}`;
+    }
+    /** Test / internal: admit a message when open. */
+    admit(msg) {
+        if (!this.#open)
             return;
-        const message = this.$formatMessage(ctx.message);
-        await this.enrichGroupSender(message, ctx.message);
-        this.adapter.emit("message.receive", message);
-        this.pluginLogger.debug(`${this.$config.name} recv  ${message.$channel.type}(${message.$channel.id}): ${segment.raw(message.$content)}`);
-    }
-    $formatMessage(msg) {
-        // Determine channel type
-        const channelType = msg.chat.type === "private" ? "private" : "group";
-        const channelId = msg.chat.id.toString();
-        // Parse message content
-        const wire = this.parseMessageContent(msg);
-        const quoteId = Message.quoteIdFromContent(wire);
-        Message.alignReplySegments(wire, quoteId);
-        const content = toCanonicalSegments(wire);
-        const result = Message.from(msg, {
-            $id: msg.message_id.toString(),
-            $adapter: "telegram",
-            $endpoint: this.$config.name,
-            $sender: {
-                id: msg.from?.id.toString() || "",
-                name: msg.from?.username || msg.from?.first_name || "Unknown",
-            },
-            $channel: {
-                id: channelId,
-                type: channelType,
-            },
-            $content: content,
-            $quote_id: quoteId,
-            $raw: "text" in msg ? msg.text || "" : "",
-            $timestamp: msg.date * 1000,
-            $recall: async () => {
-                try {
-                    await this.telegram.deleteMessage(parseInt(channelId), parseInt(result.$id));
-                }
-                catch (error) {
-                    this.pluginLogger.error("Error recalling Telegram message:", error);
-                    throw error;
-                }
-            },
-            $reply: async (content, quote) => {
-                if (!Array.isArray(content))
-                    content = [content];
-                // Handle reply
-                if (quote) {
-                    const replyToMessageId = typeof quote === "boolean" ? result.$id : quote;
-                    content.unshift({ type: "reply", data: { id: replyToMessageId } });
-                }
-                return await this.adapter.sendMessage({
-                    context: "telegram",
-                    endpoint: this.$config.name,
-                    id: channelId,
-                    type: channelType,
-                    content: content,
-                });
-            },
+        const { channelId } = resolveChannel(msg);
+        void this.#admitWithSenderRole(msg, channelId).catch((err) => {
+            logger.warn(formatCompact({
+                op: 'telegram_gateway_receive_failed',
+                target: channelId,
+                error: err instanceof Error ? err.message : String(err),
+            }));
         });
-        this.messageChatMap.set(result.$id, channelId);
-        return result;
     }
-    async $getMsg(messageId) {
-        const hit = this.quotedPayloadCache.get(messageId);
-        if (!hit) {
-            throw new Error(`Telegram quoted message ${messageId} is not cached`);
-        }
-        return hit;
-    }
-    cacheQuotedTelegramMessage(msg) {
-        const segments = this.parseMessageContent(msg);
-        const payload = {
-            messageId: msg.message_id.toString(),
-            sender: msg.from
-                ? {
-                    id: msg.from.id.toString(),
-                    name: msg.from.username || msg.from.first_name,
-                }
-                : undefined,
-            content: segments,
-            raw: "text" in msg ? msg.text : undefined,
-            time: msg.date,
-        };
-        this.quotedPayloadCache.set(payload.messageId, payload);
-    }
-    $formatCallbackQuery(ctx) {
-        if (!ctx.callbackQuery || !("data" in ctx.callbackQuery)) {
-            throw new Error("Invalid callback query");
-        }
-        const query = ctx.callbackQuery;
-        const msg = query.message;
-        const channelType = msg && "chat" in msg && msg.chat.type === "private" ? "private" : "group";
-        const channelId = msg && "chat" in msg ? msg.chat.id.toString() : query.from.id.toString();
-        const result = Message.from(query, {
-            $id: query.id,
-            $adapter: "telegram",
-            $endpoint: this.$config.name,
-            $sender: {
-                id: query.from.id.toString(),
-                name: query.from.username || query.from.first_name,
-            },
-            $channel: {
-                id: channelId,
-                type: channelType,
-            },
-            $content: [{
-                    type: "action",
-                    data: {
-                        id: query.id,
-                        payload: query.data,
-                        sourceMessageId: msg && "message_id" in msg ? String(msg.message_id) : undefined,
-                    },
-                }],
-            $raw: query.data,
-            $timestamp: Date.now(),
-            $recall: async () => {
-                // Callback queries cannot be recalled
-            },
-            $reply: async (content) => {
-                if (!Array.isArray(content))
-                    content = [content];
-                const sentMsg = await this.sendContentToChat(parseInt(channelId), content);
-                return sentMsg.message_id.toString();
-            },
+    async #admitWithSenderRole(msg, channelId) {
+        const permit = await this.#resolveGroupSenderPermit(msg);
+        // 新 Runtime Message.content 为纯文本：@ 本机只能经 metadata 传递
+        const mentioned = this.#isBotMentioned(msg);
+        await this.#options.gateway.receive({
+            adapter: this.#options.id,
+            target: channelId,
+            content: formatInboundContent(msg),
+            sender: senderDisplayName(msg.from),
+            id: String(msg.message_id),
+            metadata: Object.freeze({
+                endpoint: this.#options.config.name,
+                chatType: msg.chat.type,
+                userId: msg.from?.id,
+                date: msg.date,
+                ...(permit?.role ? { senderRole: permit.role } : {}),
+                ...(permit?.permissions.length ? { senderPermissions: [...permit.permissions] } : {}),
+                ...(mentioned ? { mentioned: true } : {}),
+            }),
         });
-        return result;
-    }
-    parseMessageContent(msg) {
-        const segments = [];
-        // Handle text messages
-        if ("text" in msg && msg.text) {
-            // Check for reply
-            if (msg.reply_to_message) {
-                this.cacheQuotedTelegramMessage(msg.reply_to_message);
-                const replyId = msg.reply_to_message.message_id.toString();
-                segments.push({
-                    type: "reply",
-                    data: { id: replyId, message_id: replyId },
-                });
-            }
-            // Parse text with entities
-            if (msg.entities && msg.entities.length > 0) {
-                segments.push(...this.parseTextWithEntities(msg.text, msg.entities));
-            }
-            else {
-                segments.push({ type: "text", data: { text: msg.text } });
-            }
-        }
-        // Handle photo
-        if ("photo" in msg && msg.photo) {
-            const largestPhoto = msg.photo[msg.photo.length - 1];
-            segments.push({
-                type: "image",
-                data: {
-                    file_id: largestPhoto.file_id,
-                    file_unique_id: largestPhoto.file_unique_id,
-                    width: largestPhoto.width,
-                    height: largestPhoto.height,
-                    file_size: largestPhoto.file_size,
-                },
-            });
-            if (msg.caption) {
-                segments.push({ type: "text", data: { text: msg.caption } });
-            }
-        }
-        // Handle video
-        if ("video" in msg && msg.video) {
-            segments.push({
-                type: "video",
-                data: {
-                    file_id: msg.video.file_id,
-                    file_unique_id: msg.video.file_unique_id,
-                    width: msg.video.width,
-                    height: msg.video.height,
-                    duration: msg.video.duration,
-                    file_size: msg.video.file_size,
-                },
-            });
-            if (msg.caption) {
-                segments.push({ type: "text", data: { text: msg.caption } });
-            }
-        }
-        // Handle audio
-        if ("audio" in msg && msg.audio) {
-            segments.push({
-                type: "audio",
-                data: {
-                    file_id: msg.audio.file_id,
-                    file_unique_id: msg.audio.file_unique_id,
-                    duration: msg.audio.duration,
-                    performer: msg.audio.performer,
-                    title: msg.audio.title,
-                    file_size: msg.audio.file_size,
-                },
-            });
-        }
-        // Handle voice
-        if ("voice" in msg && msg.voice) {
-            segments.push({
-                type: "voice",
-                data: {
-                    file_id: msg.voice.file_id,
-                    file_unique_id: msg.voice.file_unique_id,
-                    duration: msg.voice.duration,
-                    file_size: msg.voice.file_size,
-                },
-            });
-        }
-        // Handle document
-        if ("document" in msg && msg.document) {
-            segments.push({
-                type: "file",
-                data: {
-                    file_id: msg.document.file_id,
-                    file_unique_id: msg.document.file_unique_id,
-                    file_name: msg.document.file_name,
-                    mime_type: msg.document.mime_type,
-                    file_size: msg.document.file_size,
-                },
-            });
-        }
-        // Handle sticker
-        if ("sticker" in msg && msg.sticker) {
-            segments.push({
-                type: "sticker",
-                data: {
-                    file_id: msg.sticker.file_id,
-                    file_unique_id: msg.sticker.file_unique_id,
-                    width: msg.sticker.width,
-                    height: msg.sticker.height,
-                    is_animated: msg.sticker.is_animated,
-                    is_video: msg.sticker.is_video,
-                    emoji: msg.sticker.emoji,
-                },
-            });
-        }
-        // Handle location
-        if ("location" in msg && msg.location) {
-            segments.push({
-                type: "location",
-                data: {
-                    longitude: msg.location.longitude,
-                    latitude: msg.location.latitude,
-                },
-            });
-        }
-        return segments.length > 0
-            ? segments
-            : [{ type: "text", data: { text: "" } }];
     }
-    parseTextWithEntities(text, entities) {
-        const segments = [];
-        let lastOffset = 0;
-        for (const entity of entities) {
-            // Add text before entity
-            if (entity.offset > lastOffset) {
-                const beforeText = text.slice(lastOffset, entity.offset);
-                if (beforeText) {
-                    segments.push({ type: "text", data: { text: beforeText } });
-                }
-            }
-            const entityText = text.slice(entity.offset, entity.offset + entity.length);
-            switch (entity.type) {
-                case "mention":
-                case "text_mention":
-                    segments.push({
-                        type: "at",
-                        data: {
-                            id: ("user" in entity && entity.user?.id.toString()) || entityText.slice(1),
-                            name: ("user" in entity && entity.user?.username) || entityText,
-                            text: entityText,
-                        },
-                    });
-                    break;
-                case "url":
-                case "text_link":
-                    segments.push({
-                        type: "link",
-                        data: {
-                            url: ("url" in entity && entity.url) || entityText,
-                            text: entityText,
-                        },
-                    });
-                    break;
-                case "hashtag":
-                    segments.push({
-                        type: "text",
-                        data: { text: entityText },
-                    });
-                    break;
-                case "bold":
-                case "italic":
-                case "code":
-                case "pre":
-                case "underline":
-                case "strikethrough":
-                    segments.push({
-                        type: "text",
-                        data: { text: entityText, format: entity.type },
-                    });
-                    break;
-                default:
-                    segments.push({ type: "text", data: { text: entityText } });
-            }
-            lastOffset = entity.offset + entity.length;
-        }
-        // Add remaining text
-        if (lastOffset < text.length) {
-            const remainingText = text.slice(lastOffset);
-            if (remainingText) {
-                segments.push({ type: "text", data: { text: remainingText } });
-            }
-        }
-        return segments;
-    }
-    async $sendMessage(options) {
-        try {
-            const chatId = parseInt(options.id);
-            const canonical = expandInteractiveSegmentsInContent(options.content);
-            const wire = fromCanonicalSegments(canonical);
-            const result = await this.sendContentToChat(chatId, wire);
-            this.messageChatMap.set(result.message_id.toString(), options.id);
-            this.pluginLogger.debug(`${this.$config.name} send ${options.type}(${options.id}): ${segment.raw(options.content)}`);
-            return result.message_id.toString();
-        }
-        catch (error) {
-            this.pluginLogger.error("Failed to send Telegram message:", error);
-            throw error;
-        }
-    }
-    async $editMessage(options) {
-        const chatId = parseInt(options.id);
-        const messageId = parseInt(options.messageId);
-        const content = Array.isArray(options.content) ? options.content : [options.content];
-        let textContent = "";
-        let keyboard;
-        for (const seg of content) {
-            if (typeof seg === "string") {
-                textContent += seg;
+    /** entities 里 mention 文本命中 bot username（getMe 缓存），或 text_mention 指向 bot 用户。 */
+    #isBotMentioned(msg) {
+        if (!msg.entities?.length)
+            return false;
+        for (const entity of msg.entities) {
+            if (entity.type === 'text_mention') {
+                if (this.#botUserId != null && entity.user?.id === this.#botUserId)
+                    return true;
                 continue;
             }
-            if (seg.type === "text")
-                textContent += seg.data.text || "";
-            if (seg.type === "keyboard") {
-                keyboard = {
-                    inline_keyboard: (seg.data.rows ?? []).map((row) => row.map((btn) => ({
-                        text: btn.label,
-                        callback_data: String(btn.payload).slice(0, 64),
-                    }))),
-                };
-            }
-        }
-        await this.telegram.editMessageText(chatId, messageId, undefined, textContent.trim() || " ", keyboard ? { reply_markup: keyboard } : {});
-    }
-    async sendContentToChat(chatId, content, extraOptions = {}) {
-        if (!Array.isArray(content))
-            content = [content];
-        let textContent = "";
-        let hasMedia = false;
-        for (const segment of content) {
-            if (typeof segment === "string") {
-                textContent += segment;
+            if (entity.type !== 'mention' || !this.#botUsername)
                 continue;
-            }
-            const { type, data } = segment;
-            switch (type) {
-                case "text":
-                    textContent += data.text || "";
-                    break;
-                case "at":
-                    if (data.id) {
-                        textContent += `@${data.name || data.id}`;
-                    }
-                    break;
-                case "image":
-                    hasMedia = true;
-                    if (data.file_id) {
-                        // Send by file_id
-                        return await this.telegram.sendPhoto(chatId, data.file_id, {
-                            caption: textContent || undefined,
-                            ...extraOptions,
-                        });
-                    }
-                    else if (data.url) {
-                        // Send by URL
-                        return await this.telegram.sendPhoto(chatId, data.url, {
-                            caption: textContent || undefined,
-                            ...extraOptions,
-                        });
-                    }
-                    else if (data.file) {
-                        // Send by file path
-                        return await this.telegram.sendPhoto(chatId, { source: data.file }, {
-                            caption: textContent || undefined,
-                            ...extraOptions,
-                        });
-                    }
-                    break;
-                case "video":
-                    hasMedia = true;
-                    if (data.file_id) {
-                        return await this.telegram.sendVideo(chatId, data.file_id, {
-                            caption: textContent || undefined,
-                            ...extraOptions,
-                        });
-                    }
-                    else if (data.url) {
-                        return await this.telegram.sendVideo(chatId, data.url, {
-                            caption: textContent || undefined,
-                            ...extraOptions,
-                        });
-                    }
-                    else if (data.file) {
-                        return await this.telegram.sendVideo(chatId, { source: data.file }, {
-                            caption: textContent || undefined,
-                            ...extraOptions,
-                        });
-                    }
-                    break;
-                case "audio":
-                    hasMedia = true;
-                    if (data.file_id) {
-                        return await this.telegram.sendAudio(chatId, data.file_id, {
-                            caption: textContent || undefined,
-                            ...extraOptions,
-                        });
-                    }
-                    else if (data.url) {
-                        return await this.telegram.sendAudio(chatId, data.url, {
-                            caption: textContent || undefined,
-                            ...extraOptions,
-                        });
-                    }
-                    else if (data.file) {
-                        return await this.telegram.sendAudio(chatId, { source: data.file }, {
-                            caption: textContent || undefined,
-                            ...extraOptions,
-                        });
-                    }
-                    break;
-                case "voice":
-                    hasMedia = true;
-                    if (data.file_id) {
-                        return await this.telegram.sendVoice(chatId, data.file_id, {
-                            caption: textContent || undefined,
-                            ...extraOptions,
-                        });
-                    }
-                    else if (data.url) {
-                        return await this.telegram.sendVoice(chatId, data.url, {
-                            caption: textContent || undefined,
-                            ...extraOptions,
-                        });
-                    }
-                    else if (data.file) {
-                        return await this.telegram.sendVoice(chatId, { source: data.file }, {
-                            caption: textContent || undefined,
-                            ...extraOptions,
-                        });
-                    }
-                    break;
-                case "file":
-                    hasMedia = true;
-                    if (data.file_id) {
-                        return await this.telegram.sendDocument(chatId, data.file_id, {
-                            caption: textContent || undefined,
-                            ...extraOptions,
-                        });
-                    }
-                    else if (data.url) {
-                        return await this.telegram.sendDocument(chatId, data.url, {
-                            caption: textContent || undefined,
-                            ...extraOptions,
-                        });
-                    }
-                    else if (data.file) {
-                        return await this.telegram.sendDocument(chatId, { source: data.file }, {
-                            caption: textContent || undefined,
-                            ...extraOptions,
-                        });
-                    }
-                    break;
-                case "sticker":
-                    if (data.file_id) {
-                        hasMedia = true;
-                        return await this.telegram.sendSticker(chatId, data.file_id, extraOptions);
-                    }
-                    break;
-                case "location":
-                    return await this.telegram.sendLocation(chatId, data.latitude, data.longitude, extraOptions);
-                case "reply":
-                    return await this.telegram.sendMessage(chatId, data.id, {
-                        reply_parameters: { message_id: parseInt(data.id) },
-                        ...extraOptions,
-                    });
-                case "keyboard": {
-                    const rows = (data.rows ?? []).map((row) => row.map((btn) => ({
-                        text: btn.label,
-                        callback_data: String(btn.payload).slice(0, 64),
-                    })));
-                    return await this.telegram.sendMessage(chatId, textContent.trim() || " ", {
-                        reply_markup: { inline_keyboard: rows },
-                        ...extraOptions,
-                    });
-                }
-                default:
-                    // Unknown segment type, add as text
-                    textContent += data.text || `[${type}]`;
-            }
-        }
-        // If no media was sent, send as text message
-        if (!hasMedia && textContent.trim()) {
-            return await this.telegram.sendMessage(chatId, textContent.trim(), extraOptions);
-        }
-        // If neither media nor text was sent, this is an error
-        throw new Error("TelegramEndpoint.$sendMessage: No media or text content to send.");
-    }
-    async $recallMessage(id) {
-        // The Endpoint interface only provides message_id, making recall impossible
-        // Users should use message.$recall() instead, which has the full context
-        throw new Error("TelegramEndpoint.$recallMessage: Message recall not supported without chat_id. " +
-            "Use message.$recall() method instead, which contains the required context.");
-    }
-    resolveTelegramMessageRef(messageId) {
-        if (messageId.includes(':')) {
-            const [chatIdRaw, msgIdRaw] = messageId.split(':');
-            const chatId = Number(chatIdRaw);
-            const msgId = Number(msgIdRaw);
-            if (Number.isFinite(chatId) && Number.isFinite(msgId)) {
-                this.messageChatMap.set(String(msgId), String(chatId));
-                return { chatId, msgId };
-            }
-        }
-        const mappedChatId = this.messageChatMap.get(messageId);
-        if (!mappedChatId)
-            return null;
-        const chatId = Number(mappedChatId);
-        const msgId = Number(messageId);
-        if (!Number.isFinite(chatId) || !Number.isFinite(msgId))
-            return null;
-        return { chatId, msgId };
-    }
-    async $addReaction(messageId, emoji) {
-        const ref = this.resolveTelegramMessageRef(messageId);
-        if (!ref) {
-            this.pluginLogger.warn(`Telegram Endpoint ${this.$id} 无法根据 message_id=${messageId} 定位 chat_id，跳过 addReaction`);
-            return null;
-        }
-        try {
-            await this.setMessageReaction(ref.chatId, ref.msgId, emoji);
-            return emoji;
-        }
-        catch (error) {
-            this.pluginLogger.error(`Telegram Endpoint ${this.$id} 添加 reaction 失败:`, error);
-            return null;
+            const slice = (msg.text ?? '').slice(entity.offset, entity.offset + entity.length);
+            if (slice.toLowerCase() === `@${this.#botUsername.toLowerCase()}`)
+                return true;
         }
+        return false;
     }
-    async $removeReaction(messageId, _reactionId) {
-        const ref = this.resolveTelegramMessageRef(messageId);
-        if (!ref) {
-            this.pluginLogger.warn(`Telegram Endpoint ${this.$id} 无法根据 message_id=${messageId} 定位 chat_id，跳过 removeReaction`);
-            return;
-        }
+    /** 群消息 sender role 解析：getChatMember + 60s 缓存（对齐旧 enrichGroupSender）。 */
+    async #resolveGroupSenderPermit(msg) {
+        if (msg.chat.type === 'private' || !msg.from?.id)
+            return undefined;
+        const chatId = Number(msg.chat.id);
+        const userId = msg.from.id;
+        const key = `${chatId}:${userId}`;
+        const now = Date.now();
+        this.#sweepChatMemberCache(now);
+        const cached = this.#chatMemberCache.get(key);
+        if (cached && now - cached.at < CHAT_MEMBER_CACHE_TTL_MS)
+            return cached;
         try {
-            await this.telegram.callApi('setMessageReaction', {
-                chat_id: ref.chatId,
-                message_id: ref.msgId,
-                reaction: [],
+            const member = await this.callApi('getChatMember', {
+                chat_id: chatId,
+                user_id: userId,
             });
+            const normalized = normalizeTelegramChatMember(member);
+            const entry = { at: now, ...normalized };
+            this.#chatMemberCache.set(key, entry);
+            return entry;
         }
-        catch (error) {
-            this.pluginLogger.error(`Telegram Endpoint ${this.$id} 移除 reaction 失败:`, error);
-        }
-    }
-    // ==================== 群组管理 API ====================
-    /**
-     * 踢出用户
-     * @param chatId 聊天 ID
-     * @param userId 用户 ID
-     * @param untilDate 封禁截止时间（Unix 时间戳），0 表示永久
-     */
-    async kickMember(chatId, userId, untilDate) {
-        try {
-            await this.telegram.banChatMember(chatId, userId, untilDate);
-            this.pluginLogger.info(`Telegram Endpoint ${this.$id} 踢出用户 ${userId} 从聊天 ${chatId}`);
-            return true;
-        }
-        catch (error) {
-            this.pluginLogger.error(`Telegram Endpoint ${this.$id} 踢出用户失败:`, error);
-            throw error;
+        catch {
+            // 保守拒绝：无角色快照
+            return undefined;
         }
     }
-    /**
-     * 解除封禁
-     * @param chatId 聊天 ID
-     * @param userId 用户 ID
-     */
-    async unbanMember(chatId, userId) {
-        try {
-            await this.telegram.unbanChatMember(chatId, userId, { only_if_banned: true });
-            this.pluginLogger.info(`Telegram Endpoint ${this.$id} 解除用户 ${userId} 的封禁（聊天 ${chatId}）`);
-            return true;
+    #sweepChatMemberCache(now) {
+        for (const [key, entry] of this.#chatMemberCache) {
+            if (now - entry.at >= CHAT_MEMBER_CACHE_TTL_MS)
+                this.#chatMemberCache.delete(key);
         }
-        catch (error) {
-            this.pluginLogger.error(`Telegram Endpoint ${this.$id} 解除封禁失败:`, error);
-            throw error;
+        if (this.#chatMemberCache.size > CHAT_MEMBER_CACHE_MAX) {
+            const excess = this.#chatMemberCache.size - CHAT_MEMBER_CACHE_MAX;
+            let removed = 0;
+            for (const [key] of this.#chatMemberCache) {
+                if (removed >= excess)
+                    break;
+                this.#chatMemberCache.delete(key);
+                removed++;
+            }
         }
     }
-    /**
-     * 限制用户权限（禁言等）
-     * @param chatId 聊天 ID
-     * @param userId 用户 ID
-     * @param permissions 权限设置
-     * @param untilDate 限制截止时间
-     */
-    async restrictMember(chatId, userId, permissions, untilDate) {
-        try {
-            await this.telegram.restrictChatMember(chatId, userId, {
-                permissions,
-                until_date: untilDate,
-            });
-            this.pluginLogger.info(`Telegram Endpoint ${this.$id} 限制用户 ${userId} 权限（聊天 ${chatId}）`);
-            return true;
-        }
-        catch (error) {
-            this.pluginLogger.error(`Telegram Endpoint ${this.$id} 限制权限失败:`, error);
-            throw error;
-        }
+    /** Test / internal: admit a callback query when open. */
+    admitCallback(query) {
+        if (!this.#open)
+            return;
+        const msg = query.message;
+        const channelId = msg ? resolveChannel(msg).channelId : String(query.from.id);
+        void this.#options.gateway.receive({
+            adapter: this.#options.id,
+            target: channelId,
+            content: formatCallbackContent(query),
+            sender: senderDisplayName(query.from),
+            id: query.id,
+            metadata: Object.freeze({
+                endpoint: this.#options.config.name,
+                eventType: 'callback_query',
+                payload: query.data,
+                sourceMessageId: msg ? String(msg.message_id) : undefined,
+            }),
+        }).catch((err) => {
+            logger.warn(formatCompact({
+                op: 'telegram_gateway_receive_failed',
+                target: channelId,
+                error: err instanceof Error ? err.message : String(err),
+            }));
+        });
     }
-    /**
-     * 禁言用户
-     * @param chatId 聊天 ID
-     * @param userId 用户 ID
-     * @param duration 禁言时长（秒），0 表示解除禁言
-     */
-    async muteMember(chatId, userId, duration = 600) {
-        try {
-            if (duration === 0) {
-                // 解除禁言 - 恢复发送消息权限
-                await this.telegram.restrictChatMember(chatId, userId, {
-                    permissions: {
-                        can_send_messages: true,
-                        can_send_audios: true,
-                        can_send_documents: true,
-                        can_send_photos: true,
-                        can_send_videos: true,
-                        can_send_video_notes: true,
-                        can_send_voice_notes: true,
-                        can_send_polls: true,
-                        can_send_other_messages: true,
-                        can_add_web_page_previews: true,
-                    },
-                });
-                this.pluginLogger.info(`Telegram Endpoint ${this.$id} 解除用户 ${userId} 禁言（聊天 ${chatId}）`);
-            }
-            else {
-                const untilDate = Math.floor(Date.now() / 1000) + duration;
-                await this.telegram.restrictChatMember(chatId, userId, {
-                    permissions: {
-                        can_send_messages: false,
-                        can_send_audios: false,
-                        can_send_documents: false,
-                        can_send_photos: false,
-                        can_send_videos: false,
-                        can_send_video_notes: false,
-                        can_send_voice_notes: false,
-                        can_send_polls: false,
-                        can_send_other_messages: false,
-                        can_add_web_page_previews: false,
-                    },
-                    until_date: untilDate,
-                });
-                this.pluginLogger.info(`Telegram Endpoint ${this.$id} 禁言用户 ${userId} ${duration}秒（聊天 ${chatId}）`);
-            }
-            return true;
-        }
-        catch (error) {
-            this.pluginLogger.error(`Telegram Endpoint ${this.$id} 禁言操作失败:`, error);
-            throw error;
+    /** Used by webhook / polling handlers. */
+    handleUpdate(update) {
+        if (update.message) {
+            this.admit(update.message);
+            return;
         }
-    }
-    /**
-     * 提升/降级管理员
-     * @param chatId 聊天 ID
-     * @param userId 用户 ID
-     * @param promote 是否提升为管理员
-     */
-    async setAdmin(chatId, userId, promote = true) {
-        try {
-            if (promote) {
-                await this.telegram.promoteChatMember(chatId, userId, {
-                    can_manage_chat: true,
-                    can_delete_messages: true,
-                    can_manage_video_chats: true,
-                    can_restrict_members: true,
-                    can_promote_members: false,
-                    can_change_info: true,
-                    can_invite_users: true,
-                    can_pin_messages: true,
-                });
-            }
-            else {
-                await this.telegram.promoteChatMember(chatId, userId, {
-                    can_manage_chat: false,
-                    can_delete_messages: false,
-                    can_manage_video_chats: false,
-                    can_restrict_members: false,
-                    can_promote_members: false,
-                    can_change_info: false,
-                    can_invite_users: false,
-                    can_pin_messages: false,
+        if (update.callback_query) {
+            const query = update.callback_query;
+            if (query.data) {
+                void this.callApi('answerCallbackQuery', { callback_query_id: query.id }).catch(() => {
+                    /* already answered */
                 });
             }
-            this.pluginLogger.info(`Telegram Endpoint ${this.$id} ${promote ? '提升' : '降级'}用户 ${userId} 为管理员（聊天 ${chatId}）`);
-            return true;
-        }
-        catch (error) {
-            this.pluginLogger.error(`Telegram Endpoint ${this.$id} 设置管理员失败:`, error);
-            throw error;
+            this.admitCallback(query);
         }
     }
-    /**
-     * 设置聊天标题
-     * @param chatId 聊天 ID
-     * @param title 新标题
-     */
-    async setChatTitle(chatId, title) {
+    async callApi(method, params = {}, signal) {
+        const url = botApiUrl(this.#options.config, method);
+        const response = await this.#fetch(url, {
+            method: 'POST',
+            headers: { 'Content-Type': 'application/json' },
+            body: JSON.stringify(params),
+            signal,
+        });
+        const text = await response.text();
+        let body;
         try {
-            await this.telegram.setChatTitle(chatId, title);
-            this.pluginLogger.info(`Telegram Endpoint ${this.$id} 设置聊天 ${chatId} 标题为 "${title}"`);
-            return true;
+            body = JSON.parse(text);
         }
-        catch (error) {
-            this.pluginLogger.error(`Telegram Endpoint ${this.$id} 设置标题失败:`, error);
-            throw error;
-        }
-    }
-    /**
-     * 设置聊天描述
-     * @param chatId 聊天 ID
-     * @param description 新描述
-     */
-    async setChatDescription(chatId, description) {
-        try {
-            await this.telegram.setChatDescription(chatId, description);
-            this.pluginLogger.info(`Telegram Endpoint ${this.$id} 设置聊天 ${chatId} 描述`);
-            return true;
+        catch {
+            throw new Error(`Telegram API ${method} invalid JSON (${response.status}): ${text.slice(0, 200)}`);
         }
-        catch (error) {
-            this.pluginLogger.error(`Telegram Endpoint ${this.$id} 设置描述失败:`, error);
-            throw error;
+        if (!body.ok) {
+            throw new Error(`Telegram API ${method} failed (${body.error_code ?? response.status}): ${body.description ?? text}`);
         }
+        return body.result;
     }
-    /**
-     * 置顶消息
-     * @param chatId 聊天 ID
-     * @param messageId 消息 ID
-     */
+    // ── Agent tool surface ──────────────────────────────────────────────
     async pinMessage(chatId, messageId) {
-        try {
-            await this.telegram.pinChatMessage(chatId, messageId);
-            this.pluginLogger.info(`Telegram Endpoint ${this.$id} 置顶消息 ${messageId}（聊天 ${chatId}）`);
-            return true;
-        }
-        catch (error) {
-            this.pluginLogger.error(`Telegram Endpoint ${this.$id} 置顶消息失败:`, error);
-            throw error;
-        }
+        await this.callApi('pinChatMessage', { chat_id: chatId, message_id: messageId });
+        return true;
     }
-    /**
-     * 取消置顶消息
-     * @param chatId 聊天 ID
-     * @param messageId 消息 ID（可选，不提供则取消所有置顶）
-     */
     async unpinMessage(chatId, messageId) {
-        try {
-            if (messageId) {
-                await this.telegram.unpinChatMessage(chatId, messageId);
-            }
-            else {
-                await this.telegram.unpinAllChatMessages(chatId);
-            }
-            this.pluginLogger.info(`Telegram Endpoint ${this.$id} 取消置顶消息（聊天 ${chatId}）`);
-            return true;
+        if (messageId != null) {
+            await this.callApi('unpinChatMessage', { chat_id: chatId, message_id: messageId });
         }
-        catch (error) {
-            this.pluginLogger.error(`Telegram Endpoint ${this.$id} 取消置顶失败:`, error);
-            throw error;
+        else {
+            await this.callApi('unpinAllChatMessages', { chat_id: chatId });
         }
+        return true;
     }
-    /**
-     * 获取聊天信息
-     * @param chatId 聊天 ID
-     */
-    async getChatInfo(chatId) {
-        try {
-            return await this.telegram.getChat(chatId);
-        }
-        catch (error) {
-            this.pluginLogger.error(`Telegram Endpoint ${this.$id} 获取聊天信息失败:`, error);
-            throw error;
-        }
-    }
-    /**
-     * 获取聊天成员
-     * @param chatId 聊天 ID
-     * @param userId 用户 ID
-     */
-    async getChatMember(chatId, userId) {
-        try {
-            return await this.telegram.getChatMember(chatId, userId);
-        }
-        catch (error) {
-            this.pluginLogger.error(`Telegram Endpoint ${this.$id} 获取成员信息失败:`, error);
-            throw error;
-        }
+    async setChatDescription(chatId, description) {
+        await this.callApi('setChatDescription', { chat_id: chatId, description });
+        return true;
     }
-    /**
-     * 获取管理员列表
-     * @param chatId 聊天 ID
-     */
-    async getChatAdmins(chatId) {
-        try {
-            return await this.telegram.getChatAdministrators(chatId);
-        }
-        catch (error) {
-            this.pluginLogger.error(`Telegram Endpoint ${this.$id} 获取管理员列表失败:`, error);
-            throw error;
-        }
+    async setMessageReaction(chatId, messageId, reaction) {
+        await this.callApi('setMessageReaction', {
+            chat_id: chatId,
+            message_id: messageId,
+            reaction: [{ type: 'emoji', emoji: reaction }],
+        });
+        return true;
     }
-    /**
-     * 获取聊天成员数量
-     * @param chatId 聊天 ID
-     */
     async getChatMemberCount(chatId) {
-        try {
-            return await this.telegram.getChatMembersCount(chatId);
-        }
-        catch (error) {
-            this.pluginLogger.error(`Telegram Endpoint ${this.$id} 获取成员数量失败:`, error);
-            throw error;
-        }
-    }
-    /**
-     * 创建邀请链接
-     * @param chatId 聊天 ID
-     */
-    async createInviteLink(chatId) {
-        try {
-            const link = await this.telegram.createChatInviteLink(chatId, {});
-            this.pluginLogger.info(`Telegram Endpoint ${this.$id} 创建邀请链接（聊天 ${chatId}）`);
-            return link.invite_link;
-        }
-        catch (error) {
-            this.pluginLogger.error(`Telegram Endpoint ${this.$id} 创建邀请链接失败:`, error);
-            throw error;
-        }
-    }
-    async sendPoll(chatId, question, options, isAnonymous = true, allowsMultipleAnswers = false) {
-        try {
-            const result = await this.telegram.sendPoll(chatId, question, options, {
-                is_anonymous: isAnonymous,
-                allows_multiple_answers: allowsMultipleAnswers,
-            });
-            this.pluginLogger.info(`Telegram Endpoint ${this.$id} 发送投票到 ${chatId}`);
-            return result;
-        }
-        catch (error) {
-            this.pluginLogger.error(`Telegram Endpoint ${this.$id} 发送投票失败:`, error);
-            throw error;
-        }
+        return this.callApi('getChatMemberCount', { chat_id: chatId });
     }
-    async setMessageReaction(chatId, messageId, reaction) {
-        try {
-            await this.telegram.callApi('setMessageReaction', {
-                chat_id: chatId,
-                message_id: messageId,
-                reaction: [{ type: 'emoji', emoji: reaction }],
-            });
-            return true;
-        }
-        catch (error) {
-            this.pluginLogger.error(`Telegram Endpoint ${this.$id} 设置反应失败:`, error);
-            throw error;
-        }
+    async getChatAdmins(chatId) {
+        return this.callApi('getChatAdministrators', { chat_id: chatId });
     }
     async sendStickerMessage(chatId, sticker) {
-        try {
-            const result = await this.telegram.sendSticker(chatId, sticker);
-            this.pluginLogger.info(`Telegram Endpoint ${this.$id} 发送贴纸到 ${chatId}`);
-            return result;
-        }
-        catch (error) {
-            this.pluginLogger.error(`Telegram Endpoint ${this.$id} 发送贴纸失败:`, error);
-            throw error;
-        }
+        return this.callApi('sendSticker', { chat_id: chatId, sticker });
     }
     async setChatPermissionsAll(chatId, permissions) {
-        try {
-            await this.telegram.setChatPermissions(chatId, permissions);
-            this.pluginLogger.info(`Telegram Endpoint ${this.$id} 设置聊天 ${chatId} 权限`);
-            return true;
-        }
-        catch (error) {
-            this.pluginLogger.error(`Telegram Endpoint ${this.$id} 设置聊天权限失败:`, error);
-            throw error;
-        }
+        await this.callApi('setChatPermissions', { chat_id: chatId, permissions });
+        return true;
+    }
+    async createInviteLink(chatId) {
+        const link = await this.callApi('createChatInviteLink', { chat_id: chatId });
+        return link.invite_link;
+    }
+    async sendPoll(chatId, question, options, isAnonymous = true, allowsMultipleAnswers = false) {
+        return this.callApi('sendPoll', {
+            chat_id: chatId,
+            question,
+            options,
+            is_anonymous: isAnonymous,
+            allows_multiple_answers: allowsMultipleAnswers,
+        });
     }
 }
-//# sourceMappingURL=endpoint.js.map