@zhin.js/adapter-telegram 1.1.17 → 1.1.19

package/lib/endpoint.js

@@ -1,4 +1,5 @@
-import { Endpoint, createEndpointLifecycle, } from 'zhin.js/adapter';
+import { TelegramClient } from './telegram-client.js';
+import { createEndpointSpecification, endpointSpec, createEndpointLifecycle, } from 'zhin.js/adapter';
 /**
  * TelegramEndpoint — lifecycle, outbound, admit, Bot API helpers for agent tools.
  */
@@ -6,64 +7,30 @@ import { readFile } from 'node:fs/promises';
 import { EndpointDeliveryError, } from '@zhin.js/im-contract';
 import { formatCompact, getAdapterLogger } from '@zhin.js/logger';
 import { runTelegramPollLoop } from './polling.js';
-import { TelegramApiError } from './api-error.js';
 export { TelegramApiError } from './api-error.js';
 import { normalizeTelegramChatMember } from './platform-permit.js';
-import { botApiUrl, buildWebhookUrl, formatCallbackContent, formatCallbackSegments, formatInboundContent, formatInboundSegments, formatOutboundPlan, resolveTelegramChannelType, senderDisplayName, telegramInboundConversation, } from './protocol.js';
+import { 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;
 const ADMITTED_UPDATE_LIMIT = 2_048;
 const INFLIGHT_UPDATE_LIMIT = 256;
-const DEFAULT_API_TIMEOUT_MS = 30_000;
-/** Telegram Bot API client carried by message, update and lifecycle events. */
-export class TelegramClient {
-    api;
-    constructor(api) {
-        this.api = api;
-    }
-    callApi = (method, params = {}, signal) => this.api.callApi(method, params, signal);
-    callApiForm = (method, form, signal) => this.api.callApiForm(method, form, signal);
-    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);
-}
+export { TelegramClient } from './telegram-client.js';
 /**
  * Telegram Bot API 无列表类接口（无 getMyChats/getChatMembers），
  * 仅 getChat/getChatMember 按已知 id 单查，不构成列表能力；
  * 因此本 endpoint 不暴露 EndpointManagement（Console 社交面 RPC 对该平台保持未接线）。
  */
-export class TelegramEndpoint extends Endpoint {
-    client = new TelegramClient({
-        callApi: (method, params, signal) => this.callApi(method, params, signal),
-        callApiForm: (method, form, signal) => this.callApiForm(method, form, signal),
-        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),
-    });
+export class TelegramEndpoint extends TelegramClient {
+    [endpointSpec];
     #logger;
     #options;
-    #fetch;
-    #apiAbort = new AbortController();
     #pollAbort;
     #pollPromise;
     #lifecycle;
     #open = false;
     #admission;
+    #executionSignal;
     #updateOffset = 0;
     #pollingHealthy = true;
     #admittedUpdates = new Set();
@@ -71,27 +38,30 @@ export class TelegramEndpoint extends Endpoint {
     #botUserId;
     #botUsername;
     #chatMemberCache = new Map();
-    control = Object.freeze({
-        recall: (message) => this.recallMessage(message),
+    #control = Object.freeze({
+        recall: ({ message, signal }) => this.recallMessage(message, signal),
     });
-    content = Object.freeze({
+    #content = Object.freeze({
         resolve: (reference, context) => this.#resolveContent(reference, context.signal),
     });
     constructor(options) {
-        super();
-        if (options.requestTimeoutMs !== undefined && (!Number.isFinite(options.requestTimeoutMs) || options.requestTimeoutMs <= 0)) {
-            throw new TypeError('Telegram requestTimeoutMs must be a positive finite number');
-        }
+        super(options);
         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;
+        const endpoint = this;
+        this[endpointSpec] = createEndpointSpecification(this, {
+            start: signal => this.#startFramework(signal), open: () => this.#openFramework(), close: () => this.#closeFramework(),
+            stop: () => this.#stopFramework(), send: request => this.#sendFramework(request),
+            get name() { return options.config.id; }, get transportState() { return endpoint.#transportState; },
+            control: this.#control, content: this.#content,
+        });
     }
     /** Used by webhook handler. */
     get isOpen() {
         return this.#open;
     }
-    get transportState() {
+    get #transportState() {
         const state = this.#lifecycle.state;
         return state === 'open' && this.#options.config.mode === 'polling' && !this.#pollingHealthy
             ? 'reconnecting' : state;
@@ -111,13 +81,14 @@ export class TelegramEndpoint extends Endpoint {
     setUpdateOffset(offset) {
         this.#updateOffset = offset;
     }
-    async start() {
-        if (this.#apiAbort.signal.aborted)
-            this.#apiAbort = new AbortController();
+    async #startFramework(signal) {
+        this.#executionSignal = signal;
+        this.restartRequests();
         await this.#lifecycle.start(async (handle) => {
             const abort = new AbortController();
             const routes = [];
             this.#pollAbort = abort;
+            this.requestSignal = AbortSignal.any([abort.signal, signal]);
             const cleanup = () => {
                 abort.abort();
                 for (const release of routes.splice(0))
@@ -187,20 +158,21 @@ export class TelegramEndpoint extends Endpoint {
             }
         });
     }
-    open() {
+    #openFramework() {
         if (this.#open)
             return;
         this.#admission = new AbortController();
+        this.#chatMemberCache.clear();
         this.#open = true;
     }
-    close() {
+    #closeFramework() {
         this.#open = false;
-        this.#admission?.abort();
         this.#chatMemberCache.clear();
     }
-    async stop() {
-        this.close();
-        this.#apiAbort.abort();
+    async #stopFramework() {
+        this.#admission?.abort();
+        this.#closeFramework();
+        this.cancelRequests();
         const polling = this.#pollPromise;
         this.#pollPromise = undefined;
         await this.#lifecycle.stop();
@@ -212,16 +184,18 @@ export class TelegramEndpoint extends Endpoint {
         }
         this.#logger.debug(formatCompact({ op: 'disconnect' }));
     }
-    async send({ conversation, payload }) {
+    async #sendFramework({ conversation, payload, signal }) {
         let lastId = '';
         let completedActions = 0;
         try {
             const plan = formatOutboundPlan(conversation.id, payload);
             for (const action of plan.actions) {
-                const form = await this.#buildUploadForm(action.params, plan.uploads);
+                signal?.throwIfAborted();
+                const form = await this.#buildUploadForm(action.params, plan.uploads, signal);
+                signal?.throwIfAborted();
                 const result = form
-                    ? await this.callApiForm(action.method, form)
-                    : await this.callApi(action.method, action.params);
+                    ? await this.callApiForm(action.method, form, signal)
+                    : await this.callApi(action.method, action.params, signal);
                 if (!result || !Number.isSafeInteger(result.message_id) || result.message_id <= 0) {
                     throw new EndpointDeliveryError('delivery_unconfirmed', `Telegram API ${action.method} returned no valid message_id; delivery is unconfirmed`, 'unknown');
                 }
@@ -241,13 +215,13 @@ export class TelegramEndpoint extends Endpoint {
             throw new EndpointDeliveryError('invalid_payload', 'Telegram message could not be prepared', 'not_sent', { cause: error });
         }
     }
-    async recallMessage(message) {
+    async recallMessage(message, signal) {
         if (!message.id || message.id.startsWith('telegram-'))
             return;
         await this.callApi('deleteMessage', {
             chat_id: message.conversation.id,
             message_id: Number(message.id),
-        });
+        }, signal);
     }
     async #resolveContent(reference, signal) {
         if (reference.kind !== 'media') {
@@ -265,29 +239,29 @@ export class TelegramEndpoint extends Endpoint {
                 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' });
-            return await this.#withRequestDeadline('downloadFile', async (downloadSignal) => {
-                const response = await this.#fetch(`${this.#options.config.apiBaseUrl}/file/bot${this.#options.config.token}/${file.file_path}`, { signal: downloadSignal });
-                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,
-                    }),
-                });
-            }, signal);
+            return await this.withRequestDeadline({ method: 'downloadFile', run: async (downloadSignal) => {
+                    const response = await this.fetchTransport(`${this.#options.config.apiBaseUrl}/file/bot${this.#options.config.token}/${file.file_path}`, { signal: downloadSignal });
+                    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,
+                        }),
+                    });
+                }, signal });
         }
         catch {
             if (signal.aborted)
@@ -300,7 +274,7 @@ export class TelegramEndpoint extends Endpoint {
      * 标量参数原样、对象参数 JSON 序列化、attach 占位替换为文件 part
      * （base64 直接解码，本地路径读盘）。无上传时返回 undefined（走 JSON 调用）。
      */
-    async #buildUploadForm(params, uploads) {
+    async #buildUploadForm(params, uploads, signal) {
         const values = Object.values(params);
         if (!values.some((v) => typeof v === 'string' && v.startsWith('attach://')))
             return undefined;
@@ -314,7 +288,7 @@ export class TelegramEndpoint extends Endpoint {
                     throw new Error(`Telegram upload 未登记: ${value}`);
                 const data = upload.source.kind === 'base64'
                     ? Buffer.from(upload.source.data, 'base64')
-                    : await readFile(upload.source.path);
+                    : await readFile(upload.source.path, { signal });
                 form.append(key, new Blob([data], upload.mimeType ? { type: upload.mimeType } : undefined), upload.filename);
                 continue;
             }
@@ -324,23 +298,27 @@ export class TelegramEndpoint extends Endpoint {
     }
     /** 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),
-            }));
-        });
+        void this[endpointSpec].events.run(() => {
+            if (!this.#admission)
+                return;
+            const conversation = telegramInboundConversation(String(this.#options.id), msg.chat);
+            return this.#admitWithSenderRole({ message: msg, conversation, signal: AbortSignal.any([this.#admission.signal, this.#executionSignal]) }).catch((err) => {
+                this.#logger.warn(formatCompact({
+                    op: 'telegram_gateway_receive_failed',
+                    target: `${conversation.kind}:${conversation.id}`,
+                    error: err instanceof Error ? err.message : String(err),
+                }));
+            });
+        }).catch(() => this.#logger.debug('Inbound callback was not admitted'));
     }
-    async #admitWithSenderRole(msg, conversation, signal) {
+    async #admitWithSenderRole({ message: msg, conversation, signal, event = msg }) {
         const permit = await this.#resolveGroupSenderPermit(msg, signal);
         signal.throwIfAborted();
         // 新 Runtime Message.content 为纯文本：@ 本机只能经 metadata 传递
         const mentioned = this.#isBotMentioned(msg);
-        await this.emitAccepted('message.receive', {
+        await this[endpointSpec].events.emitAccepted('message.receive', {
+            event,
+            ...(typeof msg.date === 'number' ? { platformSentAt: msg.date * 1_000 } : {}),
             conversation,
             message: { conversation, id: String(msg.message_id) },
             content: formatInboundContent(msg),
@@ -427,23 +405,24 @@ export class TelegramEndpoint extends Endpoint {
     }
     /** Test / internal: admit a callback query when open. */
     admitCallback(query) {
-        if (!this.#open)
-            return;
-        void this.#admitCallback(query).catch((err) => {
-            this.#logger.warn(formatCompact({
-                op: 'telegram_gateway_receive_failed',
-                error: err instanceof Error ? err.message : String(err),
-            }));
-        });
+        void this[endpointSpec].events.run(() => {
+            return this.#admitCallback(query).catch((err) => {
+                this.#logger.warn(formatCompact({
+                    op: 'telegram_gateway_receive_failed',
+                    error: err instanceof Error ? err.message : String(err),
+                }));
+            });
+        }).catch(() => this.#logger.debug('Inbound callback was not admitted'));
     }
-    async #admitCallback(query) {
+    async #admitCallback(query, event = query) {
         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' });
-        await this.emitAccepted('message.receive', {
+        await this[endpointSpec].events.emitAccepted('message.receive', {
+            event,
             conversation,
             message: { conversation, id: query.id },
             content: formatCallbackContent(query),
@@ -459,36 +438,38 @@ export class TelegramEndpoint extends Endpoint {
     }
     /** Used by webhook / polling handlers. */
     async handleUpdate(update) {
-        if (!this.#open || !this.#admission)
-            throw new Error('Telegram endpoint is not accepting updates');
-        if (!Number.isSafeInteger(update.update_id) || update.update_id < 0) {
-            throw new TypeError('Telegram update_id must be a non-negative safe integer');
-        }
-        if (this.#admittedUpdates.has(update.update_id))
-            return;
-        const pending = this.#inflightUpdates.get(update.update_id);
-        if (pending)
-            return pending;
-        if (this.#inflightUpdates.size >= INFLIGHT_UPDATE_LIMIT) {
-            throw new Error('Telegram update admission capacity exhausted');
-        }
-        const admission = this.#admission;
-        const receiving = (async () => {
-            // Once canonical dispatch enters Core, its generation lease drains the work.
-            // Closing the transport cannot turn successful business processing into a retry.
-            await this.#receiveUpdate(update, admission.signal);
-            this.#admittedUpdates.add(update.update_id);
-            if (this.#admittedUpdates.size > ADMITTED_UPDATE_LIMIT) {
-                this.#admittedUpdates.delete(this.#admittedUpdates.values().next().value);
+        return this[endpointSpec].events.run(async () => {
+            if (!this.#admission)
+                throw new Error('Telegram endpoint is not accepting updates');
+            if (!Number.isSafeInteger(update.update_id) || update.update_id < 0) {
+                throw new TypeError('Telegram update_id must be a non-negative safe integer');
             }
-        })();
-        this.#inflightUpdates.set(update.update_id, receiving);
-        try {
-            await receiving;
-        }
-        finally {
-            this.#inflightUpdates.delete(update.update_id);
-        }
+            if (this.#admittedUpdates.has(update.update_id))
+                return;
+            const pending = this.#inflightUpdates.get(update.update_id);
+            if (pending)
+                return pending;
+            if (this.#inflightUpdates.size >= INFLIGHT_UPDATE_LIMIT) {
+                throw new Error('Telegram update admission capacity exhausted');
+            }
+            const admission = this.#admission;
+            const receiving = (async () => {
+                // Once canonical dispatch enters Core, its generation lease drains the work.
+                // Closing the transport cannot turn successful business processing into a retry.
+                await this.#receiveUpdate(update, AbortSignal.any([admission.signal, this.#executionSignal]));
+                this.#admittedUpdates.add(update.update_id);
+                if (this.#admittedUpdates.size > ADMITTED_UPDATE_LIMIT) {
+                    this.#admittedUpdates.delete(this.#admittedUpdates.values().next().value);
+                }
+            })();
+            this.#inflightUpdates.set(update.update_id, receiving);
+            try {
+                await receiving;
+            }
+            finally {
+                this.#inflightUpdates.delete(update.update_id);
+            }
+        });
     }
     async #receiveUpdate(update, signal) {
         const eventName = update.message
@@ -497,170 +478,26 @@ export class TelegramEndpoint extends Endpoint {
                 ? 'callback_query'
                 : 'update';
         if (update.message || update.callback_query) {
-            await this.emitPlatform(eventName, update);
+            await this[endpointSpec].events.platform(eventName, update);
         }
         else {
-            await this.emitAccepted('platform.receive', Object.freeze({ name: eventName, event: update }));
+            await this[endpointSpec].events.emitAccepted('platform.receive', Object.freeze({ name: eventName, event: update }));
             return;
         }
         signal.throwIfAborted();
         if (update.message) {
             const conversation = telegramInboundConversation(String(this.#options.id), update.message.chat);
-            await this.#admitWithSenderRole(update.message, conversation, signal);
+            await this.#admitWithSenderRole({ message: update.message, conversation, signal, event: update });
             return;
         }
         if (update.callback_query) {
             const query = update.callback_query;
             if (query.data) {
-                void this.callApi('answerCallbackQuery', { callback_query_id: query.id }).catch(() => {
+                void this.callApi('answerCallbackQuery', { callback_query_id: query.id }, signal).catch(() => {
                     /* already answered */
                 });
             }
-            await this.#admitCallback(query);
+            await this.#admitCallback(query, update);
         }
     }
-    async callApi(method, params = {}, signal) {
-        return this.#requestApi(method, {
-            method: 'POST',
-            headers: { 'Content-Type': 'application/json' },
-            body: JSON.stringify(params),
-        }, signal, method === 'getUpdates'
-            ? Math.max(this.#options.requestTimeoutMs ?? DEFAULT_API_TIMEOUT_MS, (Number(params.timeout) || 0) * 1_000 + 15_000)
-            : undefined);
-    }
-    /** multipart/form-data 变体（attach:// 媒体上传；Content-Type 边界由 FormData 自带）。 */
-    async callApiForm(method, form, signal) {
-        return this.#requestApi(method, {
-            method: 'POST',
-            body: form,
-        }, signal);
-    }
-    async #requestApi(method, init, signal, timeoutMs = this.#options.requestTimeoutMs ?? DEFAULT_API_TIMEOUT_MS) {
-        return this.#withRequestDeadline(method, async (requestSignal) => {
-            const response = await this.#fetch(botApiUrl(this.#options.config, method), { ...init, signal: requestSignal });
-            return this.#parseApiResponse(method, response);
-        }, signal, timeoutMs);
-    }
-    async #withRequestDeadline(method, requestOperation, signal, timeoutMs = this.#options.requestTimeoutMs ?? DEFAULT_API_TIMEOUT_MS) {
-        const abort = new AbortController();
-        let issued = false;
-        const sources = [...new Set([signal, this.#pollAbort?.signal, this.#apiAbort.signal].filter((item) => !!item))];
-        let rejectAbort;
-        const cancelled = new Promise((_resolve, reject) => { rejectAbort = reject; });
-        const onCancel = () => {
-            const error = new TelegramApiError('cancelled', `Telegram API ${method} cancelled`, {
-                disposition: issued ? 'unknown' : 'not_sent',
-            });
-            abort.abort(error);
-            rejectAbort(error);
-        };
-        const timer = setTimeout(() => {
-            const error = new TelegramApiError('timeout', `Telegram API ${method} timed out`);
-            abort.abort(error);
-            rejectAbort(error);
-        }, timeoutMs);
-        for (const source of sources)
-            source.addEventListener('abort', onCancel, { once: true });
-        try {
-            if (sources.some((source) => source.aborted))
-                onCancel();
-            const request = Promise.resolve().then(async () => {
-                abort.signal.throwIfAborted();
-                issued = true;
-                return requestOperation(abort.signal);
-            });
-            return await Promise.race([request, cancelled]);
-        }
-        catch (error) {
-            if (abort.signal.aborted)
-                throw abort.signal.reason;
-            if (error instanceof TelegramApiError)
-                throw error;
-            // Network exceptions can contain credential-bearing URLs. Keep those out of errors/logs.
-            const detail = error instanceof Error
-                ? error.message.replaceAll(this.#options.config.token, '[redacted]') : 'transport failure';
-            throw new TelegramApiError('network', `Telegram API ${method} network request failed: ${detail}`);
-        }
-        finally {
-            clearTimeout(timer);
-            for (const source of sources)
-                source.removeEventListener('abort', onCancel);
-        }
-    }
-    async #parseApiResponse(method, response) {
-        const text = await response.text();
-        let body;
-        try {
-            body = JSON.parse(text);
-        }
-        catch {
-            throw new TelegramApiError('invalid_response', `Telegram API ${method} invalid JSON (${response.status})`, { status: response.status });
-        }
-        if (!body || typeof body !== 'object' || typeof body.ok !== 'boolean') {
-            throw new TelegramApiError('invalid_response', `Telegram API ${method} invalid response envelope`, { status: response.status });
-        }
-        if (!body.ok || response.status < 200 || response.status >= 300) {
-            const status = !body.ok ? body.error_code ?? response.status : response.status;
-            const kind = status === 401 || status === 403 ? 'authentication'
-                : status === 429 ? 'rate_limit' : response.status >= 400 ? 'http' : 'api';
-            const description = !body.ok ? body.description?.replaceAll(this.#options.config.token, '[redacted]') : undefined;
-            throw new TelegramApiError(kind, `Telegram API ${method} failed (${status}): ${description ?? 'request rejected'}`, { status, disposition: !body.ok ? 'rejected' : 'unknown', ...(!body.ok && body.parameters?.retry_after != null
-                    ? { retryAfterSeconds: body.parameters.retry_after } : {}) });
-        }
-        if (!('result' in body))
-            throw new TelegramApiError('invalid_response', `Telegram API ${method} missing result`);
-        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,4 +1,6 @@
 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 { type TelegramClientEventMap } from './client.js';
+export { TelegramAdapter } from './adapter.js';
 export { checkTelegramPlatformPermit, normalizeTelegramChatMember, platformPermit, telegramGroupPermitResolver, } from './platform-permit.js';
+export type { TelegramPollRequest } from './telegram-client.js';

package/lib/index.js

@@ -1,4 +1,4 @@
 export { TelegramClient, TelegramEndpoint, } from './endpoint.js';
 export { botApiUrl, formatCallbackContent, formatInboundContent, formatOutboundActions, formatOutboundPlan, normalizeWebhookPath, resolveTelegramConfig, senderDisplayName, } from './protocol.js';
-export { telegramClient } from './client.js';
+export { TelegramAdapter } from './adapter.js';
 export { checkTelegramPlatformPermit, normalizeTelegramChatMember, platformPermit, telegramGroupPermitResolver, } from './platform-permit.js';