@zhin.js/adapter-telegram 1.0.69 → 1.1.2

package/lib/endpoint.js

@@ -0,0 +1,535 @@
+import { Endpoint, createEndpointLifecycle, } from 'zhin.js/adapter';
+/**
+ * TelegramEndpoint — lifecycle, outbound, admit, Bot API helpers for agent tools.
+ */
+import { readFile } from 'node:fs/promises';
+import { formatCompact, getAdapterLogger } from '@zhin.js/logger';
+import { runTelegramPollLoop } from './polling.js';
+import { normalizeTelegramChatMember } from './platform-permit.js';
+import { botApiUrl, buildWebhookUrl, formatCallbackContent, formatCallbackSegments, formatInboundContent, formatInboundSegments, formatOutboundPlan, resolveTelegramChannelType, senderDisplayName, telegramInboundConversation, } from './protocol.js';
+import { registerTelegramWebhookRoutes } from './webhook.js';
+const CHAT_MEMBER_CACHE_TTL_MS = 60_000;
+const CHAT_MEMBER_CACHE_MAX = 2_000;
+/** Telegram Bot API client carried by message, update and lifecycle events. */
+export class TelegramClient {
+    api;
+    constructor(api) {
+        this.api = api;
+    }
+    callApi = (method, params = {}) => this.api.callApi(method, params);
+    callApiForm = (method, form) => this.api.callApiForm(method, form);
+    pinMessage = (chatId, messageId) => this.api.pinMessage(chatId, messageId);
+    unpinMessage = (chatId, messageId) => this.api.unpinMessage(chatId, messageId);
+    setChatDescription = (chatId, description) => this.api.setChatDescription(chatId, description);
+    setMessageReaction = (chatId, messageId, reaction) => this.api.setMessageReaction(chatId, messageId, reaction);
+    getChatMemberCount = (chatId) => this.api.getChatMemberCount(chatId);
+    getChatAdmins = (chatId) => this.api.getChatAdmins(chatId);
+    sendStickerMessage = (chatId, sticker) => this.api.sendStickerMessage(chatId, sticker);
+    setChatPermissionsAll = (chatId, permissions) => this.api.setChatPermissionsAll(chatId, permissions);
+    createInviteLink = (chatId) => this.api.createInviteLink(chatId);
+    sendPoll = (chatId, question, options, anonymous, multiple) => this.api.sendPoll(chatId, question, options, anonymous, multiple);
+}
+/**
+ * Telegram Bot API 无列表类接口（无 getMyChats/getChatMembers），
+ * 仅 getChat/getChatMember 按已知 id 单查，不构成列表能力；
+ * 因此本 endpoint 不暴露 EndpointManagement（Console 社交面 RPC 对该平台保持未接线）。
+ */
+export class TelegramEndpoint extends Endpoint {
+    client = new TelegramClient({
+        callApi: (method, params) => this.callApi(method, params),
+        callApiForm: (method, form) => this.callApiForm(method, form),
+        pinMessage: (chatId, messageId) => this.pinMessage(chatId, messageId),
+        unpinMessage: (chatId, messageId) => this.unpinMessage(chatId, messageId),
+        setChatDescription: (chatId, description) => this.setChatDescription(chatId, description),
+        setMessageReaction: (chatId, messageId, reaction) => this.setMessageReaction(chatId, messageId, reaction),
+        getChatMemberCount: (chatId) => this.getChatMemberCount(chatId),
+        getChatAdmins: (chatId) => this.getChatAdmins(chatId),
+        sendStickerMessage: (chatId, sticker) => this.sendStickerMessage(chatId, sticker),
+        setChatPermissionsAll: (chatId, permissions) => this.setChatPermissionsAll(chatId, permissions),
+        createInviteLink: (chatId) => this.createInviteLink(chatId),
+        sendPoll: (chatId, question, options, anonymous, multiple) => this.sendPoll(chatId, question, options, anonymous, multiple),
+    });
+    #logger;
+    #options;
+    #fetch;
+    #pollAbort;
+    #pollPromise;
+    #lifecycle;
+    #open = false;
+    #admission;
+    #updateOffset = 0;
+    #botUserId;
+    #botUsername;
+    #chatMemberCache = new Map();
+    control = Object.freeze({
+        recall: (message) => this.recallMessage(message),
+    });
+    content = Object.freeze({
+        resolve: (reference, context) => this.#resolveContent(reference, context.signal),
+    });
+    constructor(options) {
+        super();
+        this.#logger = getAdapterLogger('telegram', options.config.id);
+        this.#lifecycle = createEndpointLifecycle({ name: options.config.id, reconnect: false });
+        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() {
+        await this.#lifecycle.start(async (handle) => {
+            const abort = new AbortController();
+            const routes = [];
+            this.#pollAbort = abort;
+            const cleanup = () => {
+                abort.abort();
+                for (const release of routes.splice(0))
+                    release();
+                if (this.#pollAbort === abort) {
+                    this.#botUserId = undefined;
+                    this.#botUsername = undefined;
+                }
+            };
+            handle.onForceClose(cleanup);
+            try {
+                const me = await this.callApi('getMe', {}, abort.signal);
+                if (abort.signal.aborted)
+                    return;
+                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');
+                    }
+                    routes.push(...registerTelegramWebhookRoutes(this.#options.http, this));
+                    const webhook = this.#options.config.webhook;
+                    if (!webhook.secretToken) {
+                        // 未配 secretToken 时 webhook 无鉴权：任何人知道 path 即可注入假 update。
+                        this.#logger.warn(formatCompact({
+                            op: 'webhook_no_secret',
+                            endpoint: this.#options.config.id,
+                            path: webhook.path,
+                            hint: 'set webhook.secretToken to authenticate Telegram callbacks',
+                        }));
+                    }
+                    const url = buildWebhookUrl(webhook);
+                    await this.callApi('setWebhook', {
+                        url,
+                        allowed_updates: this.#options.config.allowedUpdates,
+                        ...(webhook.secretToken ? { secret_token: webhook.secretToken } : {}),
+                    }, abort.signal);
+                    if (abort.signal.aborted)
+                        return;
+                    this.#logger.info(formatCompact({
+                        op: 'connect',
+                        endpoint: this.#options.config.id,
+                        mode: 'webhook',
+                        path: webhook.path,
+                        username: me.username,
+                    }));
+                    return;
+                }
+                await this.callApi('deleteWebhook', { drop_pending_updates: false }, abort.signal);
+                if (abort.signal.aborted)
+                    return;
+                this.#pollPromise = runTelegramPollLoop(this, abort.signal);
+                this.#logger.info(formatCompact({
+                    op: 'connect',
+                    endpoint: this.#options.config.id,
+                    mode: 'polling',
+                    username: me.username,
+                }));
+            }
+            catch (error) {
+                const cancelled = abort.signal.aborted;
+                cleanup();
+                if (cancelled)
+                    return;
+                this.#logger.error('Failed to connect Telegram bot:', error);
+                throw error;
+            }
+        });
+    }
+    open() {
+        if (this.#open)
+            return;
+        this.#admission = new AbortController();
+        this.#open = true;
+    }
+    close() {
+        this.#open = false;
+        this.#admission?.abort();
+        this.#chatMemberCache.clear();
+    }
+    async stop() {
+        this.close();
+        const polling = this.#pollPromise;
+        this.#pollPromise = undefined;
+        await this.#lifecycle.stop();
+        try {
+            await polling;
+        }
+        catch {
+            /* poll loop exit */
+        }
+        this.#logger.debug(formatCompact({ op: 'disconnect' }));
+    }
+    async send({ conversation, payload }) {
+        const plan = formatOutboundPlan(conversation.id, payload);
+        let lastId = '';
+        for (const action of plan.actions) {
+            const form = await this.#buildUploadForm(action.params, plan.uploads);
+            const result = form
+                ? await this.callApiForm(action.method, form)
+                : await this.callApi(action.method, action.params);
+            if (!result || !Number.isSafeInteger(result.message_id) || result.message_id <= 0) {
+                throw new Error(`Telegram API ${action.method} returned no valid message_id; delivery is unconfirmed`);
+            }
+            lastId = String(result.message_id);
+        }
+        if (!lastId)
+            throw new Error('Telegram message contains no sendable actions');
+        return lastId;
+    }
+    async recallMessage(message) {
+        if (!message.id || message.id.startsWith('telegram-'))
+            return;
+        await this.callApi('deleteMessage', {
+            chat_id: message.conversation.id,
+            message_id: Number(message.id),
+        });
+    }
+    async #resolveContent(reference, signal) {
+        if (reference.kind !== 'media') {
+            return Object.freeze({ status: 'unsupported', code: 'telegram_message_lookup_unavailable' });
+        }
+        if (reference.media.kind !== 'file') {
+            return Object.freeze({ status: 'resolved', reference, value: reference.media });
+        }
+        try {
+            signal.throwIfAborted();
+            const file = await this.callApi('getFile', {
+                file_id: reference.media.value,
+            });
+            if (!file.file_path)
+                return Object.freeze({ status: 'not_found', code: 'telegram_file_not_found' });
+            if ((file.file_size ?? 0) > 26_214_400)
+                return Object.freeze({ status: 'forbidden', code: 'media_size_limit' });
+            const response = await this.#fetch(`${this.#options.config.apiBaseUrl}/file/bot${this.#options.config.token}/${file.file_path}`, { signal });
+            if (!response.ok)
+                return Object.freeze({ status: 'failed', code: 'telegram_file_download_failed' });
+            if (!response.arrayBuffer)
+                return Object.freeze({ status: 'failed', code: 'telegram_binary_transport_unavailable' });
+            const bytes = Buffer.from(await response.arrayBuffer());
+            if (bytes.byteLength > 26_214_400)
+                return Object.freeze({ status: 'forbidden', code: 'media_size_limit' });
+            return Object.freeze({
+                status: 'resolved',
+                reference,
+                value: Object.freeze({
+                    kind: 'base64',
+                    value: bytes.toString('base64'),
+                    ...(response.headers?.get('content-type')?.split(';')[0] || reference.media.mime_type
+                        ? { mime_type: response.headers?.get('content-type')?.split(';')[0] ?? reference.media.mime_type }
+                        : {}),
+                    ...(reference.media.file_name ? { file_name: reference.media.file_name } : {}),
+                    size: bytes.byteLength,
+                }),
+            });
+        }
+        catch (error) {
+            if (signal.aborted)
+                return Object.freeze({ status: 'expired', code: 'turn_aborted' });
+            return Object.freeze({ status: 'failed', code: 'telegram_file_resolution_failed', message: error instanceof Error ? error.message : String(error) });
+        }
+    }
+    /**
+     * 含 `attach://` 占位的媒体参数 → multipart/form-data：
+     * 标量参数原样、对象参数 JSON 序列化、attach 占位替换为文件 part
+     * （base64 直接解码，本地路径读盘）。无上传时返回 undefined（走 JSON 调用）。
+     */
+    async #buildUploadForm(params, uploads) {
+        const values = Object.values(params);
+        if (!values.some((v) => typeof v === 'string' && v.startsWith('attach://')))
+            return undefined;
+        const form = new FormData();
+        for (const [key, value] of Object.entries(params)) {
+            if (value == null)
+                continue;
+            if (typeof value === 'string' && value.startsWith('attach://')) {
+                const upload = uploads.find((item) => `attach://${item.attachName}` === value);
+                if (!upload)
+                    throw new Error(`Telegram upload 未登记: ${value}`);
+                const data = upload.source.kind === 'base64'
+                    ? Buffer.from(upload.source.data, 'base64')
+                    : await readFile(upload.source.path);
+                form.append(key, new Blob([data], upload.mimeType ? { type: upload.mimeType } : undefined), upload.filename);
+                continue;
+            }
+            form.append(key, typeof value === 'object' ? JSON.stringify(value) : String(value));
+        }
+        return form;
+    }
+    /** Test / internal: admit a message when open. */
+    admit(msg) {
+        if (!this.#open || !this.#admission)
+            return;
+        const conversation = telegramInboundConversation(String(this.#options.id), msg.chat);
+        void this.#admitWithSenderRole(msg, conversation, this.#admission.signal).catch((err) => {
+            this.#logger.warn(formatCompact({
+                op: 'telegram_gateway_receive_failed',
+                target: `${conversation.kind}:${conversation.id}`,
+                error: err instanceof Error ? err.message : String(err),
+            }));
+        });
+    }
+    async #admitWithSenderRole(msg, conversation, signal) {
+        const permit = await this.#resolveGroupSenderPermit(msg, signal);
+        if (signal.aborted)
+            return;
+        // 新 Runtime Message.content 为纯文本：@ 本机只能经 metadata 传递
+        const mentioned = this.#isBotMentioned(msg);
+        await this.emit('message.receive', {
+            conversation,
+            message: { conversation, id: String(msg.message_id) },
+            content: formatInboundContent(msg),
+            segments: formatInboundSegments(msg),
+            sender: {
+                id: String(msg.from?.id ?? ''),
+                name: senderDisplayName(msg.from) || undefined,
+                ...(permit?.role ? { roles: [permit.role] } : {}),
+            },
+            endpointId: this.#options.config.id,
+            ...(mentioned ? { mentioned: true } : {}),
+            metadata: Object.freeze({
+                channelType: resolveTelegramChannelType(msg.chat.type),
+                chatType: msg.chat.type,
+                userId: msg.from?.id,
+                date: msg.date,
+                ...(permit?.role ? { senderRole: permit.role } : {}),
+                ...(permit?.permissions.length ? { senderPermissions: [...permit.permissions] } : {}),
+            }),
+        });
+    }
+    /** 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 (entity.type !== 'mention' || !this.#botUsername)
+                continue;
+            const slice = (msg.text ?? '').slice(entity.offset, entity.offset + entity.length);
+            if (slice.toLowerCase() === `@${this.#botUsername.toLowerCase()}`)
+                return true;
+        }
+        return false;
+    }
+    /** 群消息 sender role 解析：getChatMember + 60s 缓存（对齐旧 enrichGroupSender）。 */
+    async #resolveGroupSenderPermit(msg, signal) {
+        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 {
+            const member = await this.callApi('getChatMember', {
+                chat_id: chatId,
+                user_id: userId,
+            }, signal);
+            if (signal.aborted)
+                return undefined;
+            const normalized = normalizeTelegramChatMember(member);
+            const entry = { at: now, ...normalized };
+            this.#chatMemberCache.set(key, entry);
+            return entry;
+        }
+        catch {
+            // 保守拒绝：无角色快照
+            return undefined;
+        }
+    }
+    #sweepChatMemberCache(now) {
+        for (const [key, entry] of this.#chatMemberCache) {
+            if (now - entry.at >= CHAT_MEMBER_CACHE_TTL_MS)
+                this.#chatMemberCache.delete(key);
+        }
+        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++;
+            }
+        }
+    }
+    /** Test / internal: admit a callback query when open. */
+    admitCallback(query) {
+        if (!this.#open)
+            return;
+        const endpointKey = String(this.#options.id);
+        const msg = query.message;
+        // 无挂载消息的 callback（如 inline 模式）退化为 sender 私聊会话
+        const conversation = msg
+            ? telegramInboundConversation(endpointKey, msg.chat)
+            : telegramInboundConversation(endpointKey, { id: query.from.id, type: 'private' });
+        void this.emit('message.receive', {
+            conversation,
+            message: { conversation, id: query.id },
+            content: formatCallbackContent(query),
+            segments: formatCallbackSegments(query),
+            sender: { id: String(query.from?.id ?? ''), name: senderDisplayName(query.from) || undefined },
+            endpointId: this.#options.config.id,
+            metadata: Object.freeze({
+                eventType: 'callback_query',
+                payload: query.data,
+                sourceMessageId: msg ? String(msg.message_id) : undefined,
+            }),
+        }).catch((err) => {
+            this.#logger.warn(formatCompact({
+                op: 'telegram_gateway_receive_failed',
+                target: `${conversation.kind}:${conversation.id}`,
+                error: err instanceof Error ? err.message : String(err),
+            }));
+        });
+    }
+    /** Used by webhook / polling handlers. */
+    handleUpdate(update) {
+        const eventName = update.message
+            ? 'message'
+            : update.callback_query
+                ? 'callback_query'
+                : 'update';
+        void this.emitPlatform(eventName, update).catch((error) => {
+            this.#logger.warn(formatCompact({
+                op: 'telegram_platform_event_failed',
+                event: eventName,
+                error: error instanceof Error ? error.message : String(error),
+            }));
+        });
+        if (update.message) {
+            this.admit(update.message);
+            return;
+        }
+        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.admitCallback(query);
+        }
+    }
+    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,
+        });
+        return this.#parseApiResponse(method, response);
+    }
+    /** multipart/form-data 变体（attach:// 媒体上传；Content-Type 边界由 FormData 自带）。 */
+    async callApiForm(method, form, signal) {
+        const url = botApiUrl(this.#options.config, method);
+        const response = await this.#fetch(url, {
+            method: 'POST',
+            body: form,
+            signal,
+        });
+        return this.#parseApiResponse(method, response);
+    }
+    async #parseApiResponse(method, response) {
+        const text = await response.text();
+        let body;
+        try {
+            body = JSON.parse(text);
+        }
+        catch {
+            throw new Error(`Telegram API ${method} invalid JSON (${response.status}): ${text.slice(0, 200)}`);
+        }
+        if (!body.ok) {
+            throw new Error(`Telegram API ${method} failed (${body.error_code ?? response.status}): ${body.description ?? text}`);
+        }
+        return body.result;
+    }
+    // ── Agent tool surface ──────────────────────────────────────────────
+    async pinMessage(chatId, messageId) {
+        await this.callApi('pinChatMessage', { chat_id: chatId, message_id: messageId });
+        return true;
+    }
+    async unpinMessage(chatId, messageId) {
+        if (messageId != null) {
+            await this.callApi('unpinChatMessage', { chat_id: chatId, message_id: messageId });
+        }
+        else {
+            await this.callApi('unpinAllChatMessages', { chat_id: chatId });
+        }
+        return true;
+    }
+    async setChatDescription(chatId, description) {
+        await this.callApi('setChatDescription', { chat_id: chatId, description });
+        return true;
+    }
+    async setMessageReaction(chatId, messageId, reaction) {
+        await this.callApi('setMessageReaction', {
+            chat_id: chatId,
+            message_id: messageId,
+            reaction: [{ type: 'emoji', emoji: reaction }],
+        });
+        return true;
+    }
+    async getChatMemberCount(chatId) {
+        return this.callApi('getChatMemberCount', { chat_id: chatId });
+    }
+    async getChatAdmins(chatId) {
+        return this.callApi('getChatAdministrators', { chat_id: chatId });
+    }
+    async sendStickerMessage(chatId, sticker) {
+        return this.callApi('sendSticker', { chat_id: chatId, sticker });
+    }
+    async setChatPermissionsAll(chatId, permissions) {
+        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,
+        });
+    }
+}

package/lib/index.d.ts

@@ -1,18 +1,4 @@
-import { TelegramAdapter } from "./adapter.js";
-import { PageManager } from "@zhin.js/console";
-declare module "zhin.js" {
-    namespace Plugin {
-        interface Contexts {
-            web: PageManager;
-        }
-    }
-}
-declare module "zhin.js" {
-    interface Adapters {
-        telegram: TelegramAdapter;
-    }
-}
-export * from "./types.js";
-export { TelegramBot } from "./bot.js";
-export { TelegramAdapter } from "./adapter.js";
-//# sourceMappingURL=index.d.ts.map
+export { TelegramClient, TelegramEndpoint, type TelegramClientApi, type TelegramEndpointOptions, type TelegramFetch, } from './endpoint.js';
+export { botApiUrl, formatCallbackContent, formatInboundContent, formatOutboundActions, formatOutboundPlan, normalizeWebhookPath, resolveTelegramConfig, senderDisplayName, type ResolvedTelegramConfig, type TelegramEndpointConfig, type TelegramCallbackQuery, type TelegramChat, type TelegramChatMember, type TelegramMessage, type TelegramOutboundAction, type TelegramOutboundPlan, type TelegramOutboundUpload, type TelegramUpdate, type TelegramUser, type TelegramWireSegment, } from './protocol.js';
+export { telegramClient, type TelegramClientEventMap } from './client.js';
+export { checkTelegramPlatformPermit, normalizeTelegramChatMember, platformPermit, telegramGroupPermitResolver, } from './platform-permit.js';