@zhin.js/adapter-telegram 5.0.2 → 5.0.3

package/lib/endpoint.js

@@ -0,0 +1,332 @@
+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 {
+            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');
+                }
+                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;
+            }
+            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) {
+            await this.stop();
+            logger.error('Failed to connect Telegram bot:', error);
+            throw error;
+        }
+    }
+    open() {
+        this.#open = true;
+    }
+    close() {
+        this.#open = false;
+    }
+    async stop() {
+        this.#open = false;
+        this.#pollAbort?.abort();
+        try {
+            await this.#pollPromise;
+        }
+        catch {
+            /* 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 { 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),
+            }));
+        });
+    }
+    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 } : {}),
+            }),
+        });
+    }
+    /** 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) {
+        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,
+            });
+            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 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),
+            }));
+        });
+    }
+    /** Used by webhook / polling handlers. */
+    handleUpdate(update) {
+        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,
+        });
+        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

@@ -0,0 +1,4 @@
+export { TelegramEndpoint, type TelegramEndpointOptions, type TelegramFetch, } from './endpoint.js';
+export { botApiUrl, formatCallbackContent, formatInboundContent, formatOutboundActions, normalizeWebhookPath, resolveChannel, resolveTelegramConfig, senderDisplayName, type ResolvedTelegramConfig, type TelegramAdapterConfig, type TelegramCallbackQuery, type TelegramChat, type TelegramChatMember, type TelegramMessage, type TelegramOutboundAction, type TelegramUpdate, type TelegramUser, type TelegramWireSegment, } from './protocol.js';
+export { getTelegramAgentDeps, registerTelegramAgentEndpoint, setTelegramAgentDeps, type TelegramAgentDeps, type TelegramAgentEndpoint, } from './telegram-agent-deps.js';
+export { checkTelegramPlatformPermit, normalizeTelegramChatMember, platformPermit, registerTelegramPlatformPermitChecker, telegramGroupPermitResolver, } from './platform-permit.js';

package/lib/index.js

@@ -0,0 +1,4 @@
+export { TelegramEndpoint, } from './endpoint.js';
+export { botApiUrl, formatCallbackContent, formatInboundContent, formatOutboundActions, normalizeWebhookPath, resolveChannel, resolveTelegramConfig, senderDisplayName, } from './protocol.js';
+export { getTelegramAgentDeps, registerTelegramAgentEndpoint, setTelegramAgentDeps, } from './telegram-agent-deps.js';
+export { checkTelegramPlatformPermit, normalizeTelegramChatMember, platformPermit, registerTelegramPlatformPermitChecker, telegramGroupPermitResolver, } from './platform-permit.js';

package/lib/platform-permit.d.ts

@@ -0,0 +1,18 @@
+/**
+ * Telegram platform permit — ChatMember 状态 + 细粒度权限
+ */
+import { type Message } from '@zhin.js/core';
+export declare function platformPermit(perm: string): string;
+export declare function telegramGroupPermitResolver(logicalPerm: string): string;
+export declare function normalizeTelegramChatMember(member: {
+    status?: string;
+    can_restrict_members?: boolean;
+    can_pin_messages?: boolean;
+    can_delete_messages?: boolean;
+    can_manage_chat?: boolean;
+}): {
+    role?: string;
+    permissions: string[];
+};
+export declare function checkTelegramPlatformPermit(perm: string, message: Message<any>): boolean;
+export declare function registerTelegramPlatformPermitChecker(): () => void;

package/lib/{src/platform-permit.js → platform-permit.js}

@@ -1,7 +1,7 @@
 /**
  * Telegram platform permit — ChatMember 状态 + 细粒度权限
  */
-import { registerPlatformPermitChecker } from 'zhin.js';
+import { registerPlatformPermitChecker } from '@zhin.js/core';
 const ADAPTER = 'telegram';
 export function platformPermit(perm) {
     return `platform(${ADAPTER},${perm})`;
@@ -59,4 +59,3 @@ export function checkTelegramPlatformPermit(perm, message) {
 export function registerTelegramPlatformPermitChecker() {
     return registerPlatformPermitChecker(ADAPTER, checkTelegramPlatformPermit);
 }
-//# sourceMappingURL=platform-permit.js.map

package/lib/polling.d.ts

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

package/lib/polling.js

@@ -0,0 +1,52 @@
+/**
+ * Telegram long-polling loop for getUpdates.
+ */
+import { formatCompact, getLogger } from '@zhin.js/logger';
+const logger = getLogger('telegram');
+const RETRY_DELAY_MS = 2_000;
+const BACKOFF_DELAY_MS = 10_000;
+const MAX_CONSECUTIVE_FAILURES = 5;
+const DEFAULT_POLL_TIMEOUT_SEC = 30;
+export async function runTelegramPollLoop(host, abortSignal) {
+    let consecutiveFailures = 0;
+    while (!abortSignal.aborted) {
+        try {
+            const updates = await host.callApi('getUpdates', {
+                offset: host.getUpdateOffset() || undefined,
+                timeout: DEFAULT_POLL_TIMEOUT_SEC,
+                allowed_updates: host.allowedUpdates,
+            }, abortSignal);
+            consecutiveFailures = 0;
+            for (const update of updates) {
+                host.setUpdateOffset(update.update_id + 1);
+                host.handleUpdate(update);
+            }
+        }
+        catch (err) {
+            if (abortSignal.aborted)
+                return;
+            consecutiveFailures += 1;
+            logger.error(formatCompact({
+                op: 'poll',
+                ok: false,
+                error: err instanceof Error ? err.message : String(err),
+            }));
+            await sleep(consecutiveFailures >= MAX_CONSECUTIVE_FAILURES ? BACKOFF_DELAY_MS : RETRY_DELAY_MS, abortSignal);
+            if (consecutiveFailures >= MAX_CONSECUTIVE_FAILURES)
+                consecutiveFailures = 0;
+        }
+    }
+}
+function sleep(ms, signal) {
+    return new Promise((resolve) => {
+        if (signal?.aborted) {
+            resolve();
+            return;
+        }
+        const timer = setTimeout(resolve, ms);
+        signal?.addEventListener('abort', () => {
+            clearTimeout(timer);
+            resolve();
+        }, { once: true });
+    });
+}

package/lib/protocol.d.ts

@@ -0,0 +1,250 @@
+/**
+ * Telegram Bot API protocol helpers — no legacy Adapter/Endpoint / segment-mapper.
+ * Canonicalization is owned by gateway/core before endpoint.send.
+ */
+import type { IncomingMessage } from 'node:http';
+/** Plugin Runtime owner config (`plugins.<instanceKey>` / schema.json). */
+export interface TelegramAdapterConfig {
+    readonly name?: string;
+    readonly token?: string;
+    /** Default true. `false` selects webhook mode (requires httpHostToken). */
+    readonly polling?: boolean;
+    readonly webhook?: {
+        readonly domain?: string;
+        readonly path?: string;
+        readonly secretToken?: string;
+    };
+    readonly allowedUpdates?: readonly string[];
+    readonly apiBaseUrl?: string;
+    /** Transitional: legacy root `endpoints[]` with `context: telegram`. */
+    readonly endpoints?: ReadonlyArray<Partial<ResolvedTelegramConfig> & {
+        readonly context?: string;
+        readonly polling?: boolean;
+        readonly webhook?: TelegramAdapterConfig['webhook'];
+        readonly allowedUpdates?: readonly string[];
+        readonly apiBaseUrl?: string;
+    }>;
+}
+export interface ResolvedTelegramConfig {
+    readonly context: 'telegram';
+    readonly name: string;
+    readonly token: string;
+    readonly mode: 'polling' | 'webhook';
+    readonly allowedUpdates: readonly string[];
+    readonly apiBaseUrl: string;
+    readonly webhook?: {
+        readonly domain: string;
+        readonly path: string;
+        readonly secretToken?: string;
+    };
+}
+export interface TelegramUser {
+    readonly id: number;
+    readonly is_bot?: boolean;
+    readonly first_name?: string;
+    readonly last_name?: string;
+    readonly username?: string;
+}
+export interface TelegramChat {
+    readonly id: number;
+    readonly type: 'private' | 'group' | 'supergroup' | 'channel';
+    readonly title?: string;
+    readonly username?: string;
+}
+export interface TelegramMessageEntity {
+    readonly type: string;
+    readonly offset: number;
+    readonly length: number;
+    readonly url?: string;
+    readonly user?: TelegramUser;
+}
+export interface TelegramPhotoSize {
+    readonly file_id: string;
+    readonly file_unique_id?: string;
+    readonly width?: number;
+    readonly height?: number;
+    readonly file_size?: number;
+}
+export interface TelegramMessage {
+    readonly message_id: number;
+    readonly date: number;
+    readonly chat: TelegramChat;
+    readonly from?: TelegramUser;
+    readonly text?: string;
+    readonly caption?: string;
+    readonly entities?: readonly TelegramMessageEntity[];
+    readonly reply_to_message?: TelegramMessage;
+    readonly photo?: readonly TelegramPhotoSize[];
+    readonly video?: {
+        readonly file_id: string;
+        readonly file_unique_id?: string;
+        readonly width?: number;
+        readonly height?: number;
+        readonly duration?: number;
+        readonly file_size?: number;
+    };
+    readonly audio?: {
+        readonly file_id: string;
+        readonly file_unique_id?: string;
+        readonly duration?: number;
+        readonly performer?: string;
+        readonly title?: string;
+        readonly file_size?: number;
+    };
+    readonly voice?: {
+        readonly file_id: string;
+        readonly file_unique_id?: string;
+        readonly duration?: number;
+        readonly file_size?: number;
+    };
+    readonly document?: {
+        readonly file_id: string;
+        readonly file_unique_id?: string;
+        readonly file_name?: string;
+        readonly mime_type?: string;
+        readonly file_size?: number;
+    };
+    readonly sticker?: {
+        readonly file_id: string;
+        readonly file_unique_id?: string;
+        readonly width?: number;
+        readonly height?: number;
+        readonly is_animated?: boolean;
+        readonly is_video?: boolean;
+        readonly emoji?: string;
+    };
+    readonly location?: {
+        readonly longitude: number;
+        readonly latitude: number;
+    };
+}
+export interface TelegramCallbackQuery {
+    readonly id: string;
+    readonly from: TelegramUser;
+    readonly data?: string;
+    readonly message?: TelegramMessage;
+}
+export interface TelegramUpdate {
+    readonly update_id: number;
+    readonly message?: TelegramMessage;
+    readonly edited_message?: TelegramMessage;
+    readonly callback_query?: TelegramCallbackQuery;
+}
+export interface TelegramChatMember {
+    readonly status: string;
+    readonly user: TelegramUser;
+    readonly can_restrict_members?: boolean;
+    readonly can_pin_messages?: boolean;
+    readonly can_delete_messages?: boolean;
+    readonly can_manage_chat?: boolean;
+}
+export interface TelegramWireSegment {
+    readonly type: string;
+    readonly data?: Record<string, unknown>;
+}
+export interface TelegramInlineButton {
+    readonly text: string;
+    readonly callback_data: string;
+}
+export type TelegramOutboundAction = {
+    readonly method: 'sendMessage';
+    readonly params: {
+        readonly chat_id: number | string;
+        readonly text: string;
+        readonly reply_parameters?: {
+            readonly message_id: number;
+        };
+        readonly reply_markup?: {
+            readonly inline_keyboard: TelegramInlineButton[][];
+        };
+    };
+} | {
+    readonly method: 'sendPhoto';
+    readonly params: {
+        readonly chat_id: number | string;
+        readonly photo: string;
+        readonly caption?: string;
+        readonly reply_parameters?: {
+            readonly message_id: number;
+        };
+    };
+} | {
+    readonly method: 'sendVideo';
+    readonly params: {
+        readonly chat_id: number | string;
+        readonly video: string;
+        readonly caption?: string;
+        readonly reply_parameters?: {
+            readonly message_id: number;
+        };
+    };
+} | {
+    readonly method: 'sendAudio';
+    readonly params: {
+        readonly chat_id: number | string;
+        readonly audio: string;
+        readonly caption?: string;
+        readonly reply_parameters?: {
+            readonly message_id: number;
+        };
+    };
+} | {
+    readonly method: 'sendVoice';
+    readonly params: {
+        readonly chat_id: number | string;
+        readonly voice: string;
+        readonly caption?: string;
+        readonly reply_parameters?: {
+            readonly message_id: number;
+        };
+    };
+} | {
+    readonly method: 'sendDocument';
+    readonly params: {
+        readonly chat_id: number | string;
+        readonly document: string;
+        readonly caption?: string;
+        readonly reply_parameters?: {
+            readonly message_id: number;
+        };
+    };
+} | {
+    readonly method: 'sendSticker';
+    readonly params: {
+        readonly chat_id: number | string;
+        readonly sticker: string;
+        readonly reply_parameters?: {
+            readonly message_id: number;
+        };
+    };
+} | {
+    readonly method: 'sendLocation';
+    readonly params: {
+        readonly chat_id: number | string;
+        readonly latitude: number;
+        readonly longitude: number;
+        readonly reply_parameters?: {
+            readonly message_id: number;
+        };
+    };
+};
+export declare function resolveTelegramConfig(config?: TelegramAdapterConfig): ResolvedTelegramConfig;
+export declare function normalizeWebhookPath(path: string): string;
+export declare function buildWebhookUrl(webhook: NonNullable<ResolvedTelegramConfig['webhook']>): string;
+export declare function readTextBody(request: IncomingMessage, options?: {
+    readonly limit?: number;
+}): Promise<string>;
+export declare function botApiUrl(config: Pick<ResolvedTelegramConfig, 'apiBaseUrl' | 'token'>, method: string): string;
+export declare function resolveChannel(msg: Pick<TelegramMessage, 'chat'>): {
+    readonly channelType: 'private' | 'group';
+    readonly channelId: string;
+};
+export declare function senderDisplayName(user?: TelegramUser): string;
+/** Build inbound text for MessageGateway.receive. */
+export declare function formatInboundContent(msg: TelegramMessage): string;
+export declare function formatCallbackContent(query: TelegramCallbackQuery): string;
+/**
+ * Wire-encode an already-rendered outbound payload into Telegram Bot API actions.
+ * Segment canonicalization is intentionally not done here.
+ */
+export declare function formatOutboundActions(target: string | number, payload: unknown): TelegramOutboundAction[];