@zhin.js/adapter-telegram 1.0.69 → 1.1.0

package/lib/protocol.js

@@ -0,0 +1,474 @@
+/**
+ * Telegram Bot API protocol helpers — no legacy Adapter/Endpoint / segment-mapper.
+ * Canonicalization is owned by gateway/core before endpoint.send.
+ */
+import { isMediaRef } from '@zhin.js/core';
+import { formatCompact, getLogger } from '@zhin.js/logger';
+import { escapeTelegramHtml, markdownToTelegramHtml } from './markdown-to-html.js';
+const logger = getLogger('telegram');
+export function resolveTelegramConfig(config = {}) {
+    const entry = config.endpoints?.find((item) => item.context === 'telegram');
+    const token = config.token
+        ?? entry?.token
+        ?? process.env.TELEGRAM_TOKEN
+        ?? process.env.TELEGRAM_BOT_TOKEN;
+    if (!token) {
+        throw new TypeError('Telegram adapter requires token (plugins.<key>.token or endpoints with context: telegram)');
+    }
+    const id = (typeof config.id === 'string' && config.id)
+        || (typeof entry?.id === 'string' && entry.id)
+        || process.env.TELEGRAM_BOT_NAME
+        || 'telegram-bot';
+    const polling = config.polling ?? entry?.polling;
+    const webhookSource = config.webhook ?? entry?.webhook;
+    // Match legacy: polling defaults true; webhook only when polling === false.
+    const mode = polling === false ? 'webhook' : 'polling';
+    const apiBaseUrl = (config.apiBaseUrl
+        ?? entry?.apiBaseUrl
+        ?? 'https://api.telegram.org').replace(/\/$/, '');
+    const allowedUpdates = config.allowedUpdates
+        ?? entry?.allowedUpdates
+        ?? ['message', 'callback_query'];
+    const webhook = mode === 'webhook'
+        ? {
+            domain: webhookSource?.domain ?? '',
+            path: normalizeWebhookPath(webhookSource?.path ?? '/telegram/webhook'),
+            secretToken: webhookSource?.secretToken
+                ?? process.env.TELEGRAM_WEBHOOK_SECRET
+                ?? undefined,
+        }
+        : undefined;
+    return {
+        context: 'telegram',
+        id,
+        token,
+        mode,
+        allowedUpdates: [...allowedUpdates],
+        apiBaseUrl,
+        webhook,
+    };
+}
+export function normalizeWebhookPath(path) {
+    const trimmed = path.trim() || '/telegram/webhook';
+    return trimmed.startsWith('/') ? trimmed : `/${trimmed}`;
+}
+export function buildWebhookUrl(webhook) {
+    const domain = webhook.domain.replace(/\/$/, '');
+    if (!domain) {
+        throw new TypeError('Telegram webhook mode requires webhook.domain');
+    }
+    return `${domain}${webhook.path}`;
+}
+export async function readTextBody(request, options = {}) {
+    const limit = options.limit ?? 1_048_576;
+    const chunks = [];
+    let size = 0;
+    for await (const chunk of request) {
+        const buffer = Buffer.isBuffer(chunk) ? chunk : Buffer.from(chunk);
+        size += buffer.length;
+        if (size > limit) {
+            request.destroy();
+            throw new Error(`Request body exceeds ${limit} bytes`);
+        }
+        chunks.push(buffer);
+    }
+    return Buffer.concat(chunks).toString('utf8');
+}
+export function botApiUrl(config, method) {
+    return `${config.apiBaseUrl}/bot${config.token}/${method}`;
+}
+/** Telegram chat.type → canonical 会话 kind（supergroup 即 group，无容器层级故无 parent）。 */
+export function resolveTelegramChannelType(chatType) {
+    if (chatType === 'private')
+        return 'private';
+    if (chatType === 'channel')
+        return 'channel';
+    return 'group';
+}
+/**
+ * 入站归一化 → ConversationRef：Telegram 无 guild/群组容器层级，
+ * kind 直取 chat.type（private/group/supergroup/channel），无 parent。
+ */
+export function telegramInboundConversation(endpointKey, chat) {
+    return {
+        endpoint: { id: endpointKey, adapter: endpointKey.split('\0')[0] ?? endpointKey },
+        kind: resolveTelegramChannelType(chat.type),
+        id: String(chat.id),
+    };
+}
+export function senderDisplayName(user) {
+    if (!user)
+        return 'Unknown';
+    return user.username || user.first_name || String(user.id);
+}
+/** Build inbound text for OutboundMessageService.receive. */
+export function formatInboundContent(msg) {
+    if (msg.text)
+        return msg.text;
+    if (msg.caption)
+        return msg.caption;
+    if (msg.sticker) {
+        return msg.sticker.emoji ? `[sticker: ${msg.sticker.emoji}]` : '[sticker]';
+    }
+    if (msg.location) {
+        return `[location: ${msg.location.latitude},${msg.location.longitude}]`;
+    }
+    return '';
+}
+export function formatCallbackContent(query) {
+    return query.data ? `[action: ${query.data}]` : '[action]';
+}
+/**
+ * 入站消息 → canonical Segment[]；媒体只存在于 canonical 段，不重复写入文本。
+ * Telegram 附件只有不透明 file_id（需 getFile 二次解析，非 URL），
+ * 统一进 MediaRef kind=file；photo 取数组末尾（最大尺寸）。
+ */
+export function formatInboundSegments(msg) {
+    const out = [];
+    if (msg.reply_to_message) {
+        out.push({
+            type: 'reply',
+            data: { message_id: String(msg.reply_to_message.message_id) },
+        });
+    }
+    const text = msg.text ?? msg.caption;
+    if (text)
+        out.push({ type: 'text', data: { text } });
+    if (msg.photo?.length) {
+        const largest = msg.photo[msg.photo.length - 1];
+        out.push({
+            type: 'image',
+            data: { media: { kind: 'file', value: largest.file_id } },
+        });
+    }
+    if (msg.video) {
+        out.push({
+            type: 'video',
+            data: { media: { kind: 'file', value: msg.video.file_id } },
+        });
+    }
+    if (msg.audio) {
+        out.push({
+            type: 'audio',
+            data: {
+                media: { kind: 'file', value: msg.audio.file_id },
+                ...(msg.audio.title ? { name: msg.audio.title } : {}),
+            },
+        });
+    }
+    if (msg.voice) {
+        out.push({
+            type: 'voice',
+            data: { media: { kind: 'file', value: msg.voice.file_id } },
+        });
+    }
+    if (msg.document) {
+        out.push({
+            type: 'file',
+            data: {
+                media: {
+                    kind: 'file',
+                    value: msg.document.file_id,
+                    ...(msg.document.mime_type ? { mime_type: msg.document.mime_type } : {}),
+                },
+                ...(msg.document.file_name ? { name: msg.document.file_name } : {}),
+            },
+        });
+    }
+    if (msg.sticker) {
+        out.push({
+            type: 'image',
+            data: {
+                media: { kind: 'file', value: msg.sticker.file_id },
+                ...(msg.sticker.emoji ? { alt: msg.sticker.emoji } : {}),
+            },
+        });
+    }
+    return out;
+}
+/**
+ * callback_query → action 段（Wave 1 C interactive 约定：
+ * {type:'action', data:{id, payload, sourceMessageId?}}），
+ * 与 formatCallbackContent / metadata.payload 同源。
+ */
+export function formatCallbackSegments(query) {
+    return [{
+            type: 'action',
+            data: {
+                id: query.id,
+                payload: query.data ?? '',
+                ...(query.message ? { sourceMessageId: String(query.message.message_id) } : {}),
+            },
+        }];
+}
+/**
+ * Wire-encode an already-rendered outbound payload into Telegram Bot API actions.
+ * Segment canonicalization is intentionally not done here.
+ */
+export function formatOutboundActions(target, payload) {
+    return formatOutboundPlan(target, payload).actions;
+}
+/**
+ * formatOutboundActions 的上传感知变体：canonical MediaRef kind=base64/path
+ * 的媒体段产出 `attach://` 占位 + uploads 清单（endpoint 走 multipart 表单上传）；
+ * kind=url/file 保持字符串直发（file 即 Telegram file_id 不透明引用）。
+ */
+export function formatOutboundPlan(target, payload) {
+    const uploads = [];
+    return { actions: buildOutboundActions(target, payload, uploads), uploads };
+}
+function buildOutboundActions(target, payload, uploads) {
+    const chatId = typeof target === 'number' ? target : (/^-?\d+$/.test(target) ? Number(target) : target);
+    if (typeof payload === 'string') {
+        const text = payload.trim();
+        if (!text)
+            throw new Error('No Telegram content to send');
+        return [{ method: 'sendMessage', params: { chat_id: chatId, text } }];
+    }
+    const items = Array.isArray(payload)
+        ? payload
+        : payload && typeof payload === 'object' && 'type' in payload
+            ? [payload]
+            : [];
+    const hasMarkdown = items.some((item) => typeof item !== 'string' && item.type === 'markdown');
+    const appendPlain = (value) => hasMarkdown
+        ? escapeTelegramHtml(String(value ?? ''))
+        : String(value ?? '');
+    const htmlMode = hasMarkdown ? { parse_mode: 'HTML' } : {};
+    if (items.length === 0) {
+        const text = payload == null
+            ? ''
+            : typeof payload === 'object'
+                ? JSON.stringify(payload)
+                : String(payload);
+        if (!text.trim())
+            throw new Error('No Telegram content to send');
+        return [{ method: 'sendMessage', params: { chat_id: chatId, text: text.trim() } }];
+    }
+    let textContent = '';
+    let replyTo;
+    let keyboard;
+    const actions = [];
+    const replyParams = () => (replyTo != null ? { reply_parameters: { message_id: replyTo } } : {});
+    /**
+     * 媒体来源归一：唯一来源是 canonical `data.media` MediaRef。
+     * kind=url/file → 字符串直发（file 即 Telegram file_id 不透明引用）；
+     * kind=base64/path → attach:// 占位并登记上传。
+     * 无 MediaRef 时 warn + 丢弃（返回 undefined）。
+     */
+    const mediaSource = (segType, data, defaultName) => {
+        const media = isMediaRef(data.media) ? data.media : undefined;
+        if (!media) {
+            logger.warn(formatCompact({
+                op: 'telegram_outbound_media_dropped',
+                type: segType,
+                reason: 'missing_media_ref',
+            }));
+            return undefined;
+        }
+        if (media.kind === 'file' || media.kind === 'url')
+            return media.value;
+        const named = data.name ?? data.filename;
+        let filename = typeof named === 'string' && named ? named : undefined;
+        if (!filename && media.kind === 'path') {
+            const raw = media.value.startsWith('file://') ? media.value.slice('file://'.length) : media.value;
+            filename = raw.split(/[\\/]/).filter(Boolean).pop();
+        }
+        const attachName = `attach${uploads.length}`;
+        uploads.push({
+            attachName,
+            filename: filename ?? defaultName,
+            source: media.kind === 'base64'
+                ? {
+                    kind: 'base64',
+                    data: media.value.startsWith('base64://')
+                        ? media.value.slice('base64://'.length)
+                        : media.value,
+                }
+                : {
+                    kind: 'path',
+                    path: media.value.startsWith('file://') ? media.value.slice('file://'.length) : media.value,
+                },
+            ...(media.mime_type ? { mimeType: media.mime_type } : {}),
+        });
+        return `attach://${attachName}`;
+    };
+    for (const item of items) {
+        if (typeof item === 'string') {
+            textContent += appendPlain(item);
+            continue;
+        }
+        const data = item.data ?? {};
+        switch (item.type) {
+            case 'text':
+                textContent += appendPlain(data.text ?? data.content ?? '');
+                break;
+            case 'markdown':
+                textContent += markdownToTelegramHtml(String(data.content ?? data.text ?? ''));
+                break;
+            case 'at':
+                if (data.id)
+                    textContent += `@${appendPlain(data.name || data.id)}`;
+                break;
+            case 'reply': {
+                const id = Number(data.id ?? data.message_id);
+                if (Number.isFinite(id))
+                    replyTo = id;
+                break;
+            }
+            case 'keyboard': {
+                const rows = Array.isArray(data.rows) ? data.rows : [];
+                keyboard = rows.map((row) => {
+                    const buttons = Array.isArray(row) ? row : [];
+                    return buttons.map((btn) => {
+                        const record = btn && typeof btn === 'object'
+                            ? btn
+                            : {};
+                        return {
+                            text: String(record.label ?? record.text ?? ''),
+                            callback_data: String(record.payload ?? record.callback_data ?? '').slice(0, 64),
+                        };
+                    });
+                });
+                break;
+            }
+            case 'image': {
+                const photo = mediaSource('image', data, 'image.png');
+                if (photo) {
+                    actions.push({
+                        method: 'sendPhoto',
+                        params: {
+                            chat_id: chatId,
+                            photo,
+                            caption: textContent.trim() || undefined,
+                            ...(textContent.trim() ? htmlMode : {}),
+                            ...replyParams(),
+                        },
+                    });
+                    textContent = '';
+                }
+                break;
+            }
+            case 'video': {
+                const video = mediaSource('video', data, 'video.mp4');
+                if (video) {
+                    actions.push({
+                        method: 'sendVideo',
+                        params: {
+                            chat_id: chatId,
+                            video,
+                            caption: textContent.trim() || undefined,
+                            ...(textContent.trim() ? htmlMode : {}),
+                            ...replyParams(),
+                        },
+                    });
+                    textContent = '';
+                }
+                break;
+            }
+            case 'audio': {
+                const audio = mediaSource('audio', data, 'audio.mp3');
+                if (audio) {
+                    actions.push({
+                        method: 'sendAudio',
+                        params: {
+                            chat_id: chatId,
+                            audio,
+                            caption: textContent.trim() || undefined,
+                            ...(textContent.trim() ? htmlMode : {}),
+                            ...replyParams(),
+                        },
+                    });
+                    textContent = '';
+                }
+                break;
+            }
+            case 'voice': {
+                const voice = mediaSource('voice', data, 'voice.ogg');
+                if (voice) {
+                    actions.push({
+                        method: 'sendVoice',
+                        params: {
+                            chat_id: chatId,
+                            voice,
+                            caption: textContent.trim() || undefined,
+                            ...(textContent.trim() ? htmlMode : {}),
+                            ...replyParams(),
+                        },
+                    });
+                    textContent = '';
+                }
+                break;
+            }
+            case 'file': {
+                const document = mediaSource('file', data, 'file');
+                if (document) {
+                    actions.push({
+                        method: 'sendDocument',
+                        params: {
+                            chat_id: chatId,
+                            document,
+                            caption: textContent.trim() || undefined,
+                            ...(textContent.trim() ? htmlMode : {}),
+                            ...replyParams(),
+                        },
+                    });
+                    textContent = '';
+                }
+                break;
+            }
+            case 'sticker': {
+                const sticker = mediaSource('sticker', data, 'sticker.webp');
+                if (sticker) {
+                    actions.push({
+                        method: 'sendSticker',
+                        params: { chat_id: chatId, sticker, ...replyParams() },
+                    });
+                }
+                break;
+            }
+            case 'location': {
+                actions.push({
+                    method: 'sendLocation',
+                    params: {
+                        chat_id: chatId,
+                        latitude: Number(data.latitude ?? 0),
+                        longitude: Number(data.longitude ?? 0),
+                        ...replyParams(),
+                    },
+                });
+                break;
+            }
+            default:
+                textContent += appendPlain(data.text ?? `[${item.type}]`);
+        }
+    }
+    if (actions.length === 0) {
+        const text = textContent.trim() || (keyboard ? ' ' : '');
+        if (!text && !keyboard)
+            throw new Error('No Telegram content to send');
+        return [{
+                method: 'sendMessage',
+                params: {
+                    chat_id: chatId,
+                    text: text || ' ',
+                    ...htmlMode,
+                    ...replyParams(),
+                    ...(keyboard ? { reply_markup: { inline_keyboard: keyboard } } : {}),
+                },
+            }];
+    }
+    if (textContent.trim() || keyboard) {
+        actions.unshift({
+            method: 'sendMessage',
+            params: {
+                chat_id: chatId,
+                text: textContent.trim() || ' ',
+                ...htmlMode,
+                ...replyParams(),
+                ...(keyboard ? { reply_markup: { inline_keyboard: keyboard } } : {}),
+            },
+        });
+    }
+    return actions;
+}

package/lib/telegram-endpoint-commands.d.ts

@@ -0,0 +1 @@
+export declare const telegramEndpointCommands: import("@zhin.js/adapter").EndpointCommands<Readonly<import("@zhin.js/command").CommandDefinition<unknown, unknown, import("@zhin.js/command").CommandMessage, string | undefined>>>;

package/lib/telegram-endpoint-commands.js

@@ -0,0 +1,16 @@
+/**
+ * `telegram.endpoint` 命令族：由 @zhin.js/adapter 的 createEndpointCommands 套件生成。
+ * commands/endpoint/ 下的 list / add / remove 直接默认导出这三项。
+ */
+import { createEndpointCommands } from 'zhin.js/adapter';
+import { defineCommand } from 'zhin.js/command';
+import { telegramRuntimeStateToken } from './telegram-runtime-state.js';
+export const telegramEndpointCommands = createEndpointCommands({
+    adapterKey: 'telegram',
+    adapterDisplayName: 'Telegram',
+    fields: [
+        { key: 'token', required: true, env: true, description: 'Telegram bot token' },
+    ],
+    running: (use) => use(telegramRuntimeStateToken).endpoints.values(),
+    describeEntry: (entry) => `token: ${String(entry.token)}`,
+}, defineCommand);

package/lib/telegram-runtime-state.d.ts

@@ -0,0 +1 @@
+export declare const telegramRuntimeStateToken: import("zhin.js").Token<import("@zhin.js/adapter").EndpointRuntimeState>;

package/lib/telegram-runtime-state.js

@@ -0,0 +1,6 @@
+/**
+ * Telegram 插件实例的运行时状态：adapter create() 注册的 endpoint 列表。
+ * 由 plugin.ts setup() provide，adapter create 与 `telegram.endpoint` 命令共享（同一 owner generation）。
+ */
+import { defineEndpointRuntimeStateToken } from 'zhin.js/adapter';
+export const telegramRuntimeStateToken = defineEndpointRuntimeStateToken('telegram');

package/lib/webhook.d.ts

@@ -0,0 +1,12 @@
+import type { IncomingMessage, ServerResponse } from 'node:http';
+import type { HttpHost, HttpRouteRegistration } from '@zhin.js/host-http';
+import { type ResolvedTelegramConfig, type TelegramUpdate } from './protocol.js';
+/** 等长时才 timingSafeEqual，避免长度差异直接抛异常。 */
+export declare function safeTokenEqual(a: string, b: string): boolean;
+export interface TelegramWebhookHandler {
+    readonly config: ResolvedTelegramConfig;
+    readonly isOpen: boolean;
+    handleUpdate(update: TelegramUpdate): void;
+}
+export declare function registerTelegramWebhookRoutes(http: HttpHost, handler: TelegramWebhookHandler): HttpRouteRegistration[];
+export declare function handleTelegramWebhookRequest(request: IncomingMessage, response: ServerResponse, handler: TelegramWebhookHandler): Promise<void>;

package/lib/webhook.js

@@ -0,0 +1,55 @@
+/**
+ * Telegram webhook HTTP: secret token → parse → handle update.
+ */
+import { timingSafeEqual } from 'node:crypto';
+import { getLogger } from '@zhin.js/logger';
+import { readTextBody } from './protocol.js';
+const logger = getLogger('telegram');
+/** 等长时才 timingSafeEqual，避免长度差异直接抛异常。 */
+export function safeTokenEqual(a, b) {
+    const bufA = Buffer.from(a, 'utf8');
+    const bufB = Buffer.from(b, 'utf8');
+    return bufA.length === bufB.length && timingSafeEqual(bufA, bufB);
+}
+export function registerTelegramWebhookRoutes(http, handler) {
+    const path = handler.config.webhook.path;
+    return [
+        http.route('POST', path, async (request, response) => {
+            await handleTelegramWebhookRequest(request, response, handler);
+        }, { summary: 'Telegram Bot API webhook', tags: ['telegram'] }),
+    ];
+}
+export async function handleTelegramWebhookRequest(request, response, handler) {
+    try {
+        const secret = handler.config.webhook?.secretToken;
+        if (secret) {
+            const header = request.headers['x-telegram-bot-api-secret-token'];
+            const token = Array.isArray(header) ? header[0] : header;
+            if (!token || !safeTokenEqual(token, secret)) {
+                response.writeHead(403, { 'Content-Type': 'application/json' });
+                response.end(JSON.stringify({ ok: false, description: 'Invalid secret token' }));
+                return;
+            }
+        }
+        const rawBody = await readTextBody(request);
+        let update;
+        try {
+            update = JSON.parse(rawBody);
+        }
+        catch {
+            response.writeHead(200, { 'Content-Type': 'application/json' });
+            response.end(JSON.stringify({ ok: true }));
+            return;
+        }
+        if (handler.isOpen) {
+            handler.handleUpdate(update);
+        }
+        response.writeHead(200, { 'Content-Type': 'application/json' });
+        response.end(JSON.stringify({ ok: true }));
+    }
+    catch (error) {
+        logger.error('Telegram webhook error:', error);
+        response.writeHead(200, { 'Content-Type': 'application/json' });
+        response.end(JSON.stringify({ ok: true }));
+    }
+}