@zhin.js/adapter-telegram 5.0.2 → 5.0.3

package/lib/protocol.js

@@ -0,0 +1,324 @@
+/**
+ * Telegram Bot API protocol helpers — no legacy Adapter/Endpoint / segment-mapper.
+ * Canonicalization is owned by gateway/core before endpoint.send.
+ */
+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 name = (typeof config.name === 'string' && config.name)
+        || (typeof entry?.name === 'string' && entry.name)
+        || 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',
+        name,
+        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}`;
+}
+export function resolveChannel(msg) {
+    return {
+        channelType: msg.chat.type === 'private' ? 'private' : 'group',
+        channelId: String(msg.chat.id),
+    };
+}
+export function senderDisplayName(user) {
+    if (!user)
+        return 'Unknown';
+    return user.username || user.first_name || String(user.id);
+}
+/** Build inbound text for MessageGateway.receive. */
+export function formatInboundContent(msg) {
+    if (msg.text)
+        return msg.text;
+    if (msg.caption)
+        return msg.caption;
+    if (msg.photo?.length)
+        return '[image]';
+    if (msg.video)
+        return '[video]';
+    if (msg.audio)
+        return '[audio]';
+    if (msg.voice)
+        return '[voice]';
+    if (msg.document) {
+        return msg.document.file_name ? `[file: ${msg.document.file_name}]` : '[file]';
+    }
+    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]';
+}
+/**
+ * Wire-encode an already-rendered outbound payload into Telegram Bot API actions.
+ * Segment canonicalization is intentionally not done here.
+ */
+export function formatOutboundActions(target, payload) {
+    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]
+            : [];
+    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 } } : {});
+    const mediaSource = (data) => {
+        if (typeof data.file_id === 'string' && data.file_id)
+            return data.file_id;
+        if (typeof data.url === 'string' && data.url)
+            return data.url;
+        if (typeof data.file === 'string' && data.file)
+            return data.file;
+        return undefined;
+    };
+    for (const item of items) {
+        if (typeof item === 'string') {
+            textContent += item;
+            continue;
+        }
+        const data = item.data ?? {};
+        switch (item.type) {
+            case 'text':
+                textContent += String(data.text ?? data.content ?? '');
+                break;
+            case 'at':
+                if (data.id)
+                    textContent += `@${String(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(data);
+                if (photo) {
+                    actions.push({
+                        method: 'sendPhoto',
+                        params: {
+                            chat_id: chatId,
+                            photo,
+                            caption: textContent.trim() || undefined,
+                            ...replyParams(),
+                        },
+                    });
+                    textContent = '';
+                }
+                break;
+            }
+            case 'video': {
+                const video = mediaSource(data);
+                if (video) {
+                    actions.push({
+                        method: 'sendVideo',
+                        params: {
+                            chat_id: chatId,
+                            video,
+                            caption: textContent.trim() || undefined,
+                            ...replyParams(),
+                        },
+                    });
+                    textContent = '';
+                }
+                break;
+            }
+            case 'audio': {
+                const audio = mediaSource(data);
+                if (audio) {
+                    actions.push({
+                        method: 'sendAudio',
+                        params: {
+                            chat_id: chatId,
+                            audio,
+                            caption: textContent.trim() || undefined,
+                            ...replyParams(),
+                        },
+                    });
+                    textContent = '';
+                }
+                break;
+            }
+            case 'voice': {
+                const voice = mediaSource(data);
+                if (voice) {
+                    actions.push({
+                        method: 'sendVoice',
+                        params: {
+                            chat_id: chatId,
+                            voice,
+                            caption: textContent.trim() || undefined,
+                            ...replyParams(),
+                        },
+                    });
+                    textContent = '';
+                }
+                break;
+            }
+            case 'file': {
+                const document = mediaSource(data);
+                if (document) {
+                    actions.push({
+                        method: 'sendDocument',
+                        params: {
+                            chat_id: chatId,
+                            document,
+                            caption: textContent.trim() || undefined,
+                            ...replyParams(),
+                        },
+                    });
+                    textContent = '';
+                }
+                break;
+            }
+            case 'sticker': {
+                const sticker = typeof data.file_id === 'string' ? data.file_id : mediaSource(data);
+                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 += String(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 || ' ',
+                    ...replyParams(),
+                    ...(keyboard ? { reply_markup: { inline_keyboard: keyboard } } : {}),
+                },
+            }];
+    }
+    if (textContent.trim() || keyboard) {
+        actions.unshift({
+            method: 'sendMessage',
+            params: {
+                chat_id: chatId,
+                text: textContent.trim() || ' ',
+                ...replyParams(),
+                ...(keyboard ? { reply_markup: { inline_keyboard: keyboard } } : {}),
+            },
+        });
+    }
+    return actions;
+}

package/lib/telegram-agent-deps.d.ts

@@ -0,0 +1,28 @@
+/**
+ * Agent tool deps for telegram.
+ * Endpoints register themselves on start; tools look up by config name / endpoint id.
+ */
+import type { TelegramChatMember } from './protocol.js';
+export interface TelegramAgentEndpoint {
+    pinMessage(chatId: number, messageId: number): Promise<boolean>;
+    unpinMessage(chatId: number, messageId?: number): Promise<boolean>;
+    setChatDescription(chatId: number, description: string): Promise<boolean>;
+    setMessageReaction(chatId: number, messageId: number, reaction: string): Promise<boolean>;
+    getChatMemberCount(chatId: number): Promise<number>;
+    getChatAdmins(chatId: number): Promise<TelegramChatMember[]>;
+    sendStickerMessage(chatId: number, sticker: string): Promise<{
+        message_id: number;
+    }>;
+    setChatPermissionsAll(chatId: number, permissions: Record<string, boolean | undefined>): Promise<boolean>;
+    createInviteLink(chatId: number): Promise<string>;
+    sendPoll(chatId: number, question: string, options: string[], isAnonymous?: boolean, allowsMultipleAnswers?: boolean): Promise<{
+        message_id: number;
+    }>;
+}
+export interface TelegramAgentDeps {
+    getEndpoint: (endpointId: string) => TelegramAgentEndpoint;
+}
+export declare function registerTelegramAgentEndpoint(endpointId: string, endpoint: TelegramAgentEndpoint): () => void;
+/** Optional override used by tests / transitional callers. Pass `null` to clear. */
+export declare function setTelegramAgentDeps(deps: TelegramAgentDeps | null): void;
+export declare function getTelegramAgentDeps(): TelegramAgentDeps;

package/lib/telegram-agent-deps.js

@@ -0,0 +1,30 @@
+/**
+ * Agent tool deps for telegram.
+ * Endpoints register themselves on start; tools look up by config name / endpoint id.
+ */
+const endpoints = new Map();
+let override = null;
+export function registerTelegramAgentEndpoint(endpointId, endpoint) {
+    endpoints.set(endpointId, endpoint);
+    return () => {
+        if (endpoints.get(endpointId) === endpoint) {
+            endpoints.delete(endpointId);
+        }
+    };
+}
+/** Optional override used by tests / transitional callers. Pass `null` to clear. */
+export function setTelegramAgentDeps(deps) {
+    override = deps;
+}
+export function getTelegramAgentDeps() {
+    if (override)
+        return override;
+    return {
+        getEndpoint(endpointId) {
+            const registered = endpoints.get(endpointId);
+            if (!registered)
+                throw new Error(`Endpoint ${endpointId} 不存在`);
+            return registered;
+        },
+    };
+}

package/lib/webhook.d.ts

@@ -0,0 +1,13 @@
+/**
+ * Telegram webhook HTTP: secret token → parse → handle update.
+ */
+import type { IncomingMessage, ServerResponse } from 'node:http';
+import type { HttpHost, HttpRouteRegistration } from '@zhin.js/host-http';
+import { type ResolvedTelegramConfig, type TelegramUpdate } from './protocol.js';
+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,45 @@
+import { getLogger } from '@zhin.js/logger';
+import { readTextBody } from './protocol.js';
+const logger = getLogger('telegram');
+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 !== 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 }));
+    }
+}

package/package.json

@@ -1,7 +1,7 @@
 {
   "name": "@zhin.js/adapter-telegram",
-  "version": "5.0.2",
-  "description": "Zhin.js adapter for Telegram",
+  "version": "5.0.3",
+  "description": "Zhin.js Telegram Bot API adapter for Plugin Runtime (long-poll getUpdates)",
   "type": "module",
   "main": "./lib/index.js",
   "types": "./lib/index.d.ts",
@@ -32,58 +32,47 @@
     "directory": "plugins/adapters/telegram"
   },
   "dependencies": {
-    "telegraf": "^4.16.3"
-  },
-  "devDependencies": {
-    "@types/node": "^26.1.0",
-    "@types/react": "^19.2.17",
-    "@types/react-dom": "^19.2.3",
-    "lucide-react": "^1.22.0",
-    "typescript": "^6.0.3",
-    "zod": "^4.4.3",
-    "@zhin.js/contract": "1.0.3",
-    "@zhin.js/host-router": "2.0.3",
-    "@zhin.js/client": "2.0.5",
-    "@zhin.js/host-api": "2.0.5",
-    "@zhin.js/cli": "1.0.93",
-    "@zhin.js/logger": "1.0.74",
-    "zhin.js": "4.1.2",
-    "@zhin.js/agent": "1.0.3"
+    "@zhin.js/adapter": "1.0.1",
+    "@zhin.js/core": "1.3.5",
+    "@zhin.js/host-http": "1.0.1",
+    "@zhin.js/logger": "1.0.75",
+    "@zhin.js/plugin-runtime": "1.0.1"
   },
   "peerDependencies": {
     "zod": "^4.0.0",
-    "@zhin.js/host-api": "2.0.5",
-    "@zhin.js/contract": "1.0.3",
-    "@zhin.js/client": "2.0.5",
-    "@zhin.js/host-router": "2.0.3",
-    "@zhin.js/agent": "1.0.3",
-    "@zhin.js/logger": "1.0.74",
-    "zhin.js": "4.1.2"
+    "@zhin.js/adapter": "1.0.1",
+    "@zhin.js/agent": "1.0.4",
+    "@zhin.js/core": "1.3.5",
+    "@zhin.js/plugin-runtime": "1.0.1",
+    "zhin.js": "4.1.3"
   },
   "peerDependenciesMeta": {
-    "@zhin.js/agent": {
-      "optional": true
-    },
-    "@zhin.js/client": {
+    "zhin.js": {
       "optional": true
     },
-    "@zhin.js/host-router": {
-      "optional": true
-    },
-    "@zhin.js/host-api": {
+    "@zhin.js/agent": {
       "optional": true
     },
     "zod": {
       "optional": true
     }
   },
+  "devDependencies": {
+    "@types/node": "^26.1.0",
+    "typescript": "^6.0.3",
+    "vitest": "^4.1.10",
+    "zod": "^4.4.3",
+    "@zhin.js/agent": "1.0.4",
+    "@zhin.js/host-http": "1.0.1",
+    "zhin.js": "4.1.3"
+  },
   "files": [
+    "adapters",
+    "plugin.ts",
+    "schema.json",
     "src",
     "lib",
-    "client",
-    "dist",
     "agent",
-    "plugin.yml",
     "README.md",
     "CHANGELOG.md"
   ],
@@ -94,9 +83,23 @@
   "engines": {
     "node": "^20.19.0 || >=22.12.0"
   },
+  "zhin": {
+    "protocol": 1,
+    "type": "plugin",
+    "entry": "./plugin.ts",
+    "engine": "^1.0.0",
+    "runtime": "trusted",
+    "features": [
+      {
+        "package": "@zhin.js/adapter",
+        "api": "^1.0.0"
+      }
+    ],
+    "plugins": []
+  },
   "scripts": {
-    "build": "zhin build",
-    "clean": "rimraf lib dist",
-    "build:node": "tsc"
+    "build": "tsc",
+    "clean": "rimraf lib",
+    "test": "NODE_OPTIONS=--experimental-strip-types vitest run --root ../../.. plugins/adapters/telegram/tests"
   }
 }

package/plugin.ts

@@ -0,0 +1,13 @@
+import { definePlugin } from '@zhin.js/plugin-runtime';
+import { registerTelegramPlatformPermitChecker } from './src/platform-permit.js';
+
+export default definePlugin({
+  name: 'telegram',
+  metadata: {
+    displayName: 'Telegram Bot API Adapter',
+  },
+  setup() {
+    // 平台权限门禁：chat_creator / chat_administrator / pin_messages 等（agent 工具 platformPermit）
+    return registerTelegramPlatformPermitChecker();
+  },
+});

package/schema.json

@@ -0,0 +1,39 @@
+{
+  "$schema": "https://json-schema.org/draft/2020-12/schema",
+  "type": "object",
+  "additionalProperties": false,
+  "properties": {
+    "name": {
+      "type": "string",
+      "default": "telegram-bot"
+    },
+    "token": {
+      "type": "string"
+    },
+    "polling": {
+      "type": "boolean",
+      "default": true,
+      "description": "Long-poll getUpdates (default). Set false for webhook via httpHostToken."
+    },
+    "webhook": {
+      "type": "object",
+      "additionalProperties": false,
+      "description": "Webhook settings when polling is false.",
+      "properties": {
+        "domain": { "type": "string" },
+        "path": { "type": "string", "default": "/telegram/webhook" },
+        "secretToken": { "type": "string", "description": "Verified via X-Telegram-Bot-Api-Secret-Token." }
+      }
+    },
+    "allowedUpdates": {
+      "type": "array",
+      "items": { "type": "string" },
+      "default": ["message", "callback_query"]
+    },
+    "apiBaseUrl": {
+      "type": "string",
+      "default": "https://api.telegram.org"
+    }
+  },
+  "required": ["token"]
+}