@zhin.js/adapter-telegram 1.1.26 → 1.1.27

package/lib/platform-permit.d.ts

@@ -1,20 +1,20 @@
 /**
- * Telegram platform permit — ChatMember 状态 + 细粒度权限
+ * Telegram platform standing — ChatMember 状态 + 管理员权限（ADR 0056 §1）
  *
- * `role` 使用跨平台规范名 owner / admin（原生 creator / administrator 仅作兼容输入）；
- * 细粒度能力放在 `permissions`。
+ * `standing` 使用跨平台规范名 owner / admin / member / guest；细粒度管理员权限放在 `permissions`。
  */
-import type { PermissionSubject } from '@zhin.js/permission';
+import type { PlatformStanding } from '@zhin.js/im-contract';
 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, subject: PermissionSubject): boolean;
+/**
+ * ADR 0056 §1：`getChatMember` 结果 → `sender.platform`。
+ * creator → `owner`（拥有全部管理员权限）；administrator → `admin`，其 `can_*` 权限去掉前缀进
+ * `permissions`（如 `restrict_members`、`pin_messages`）；member / 仍在群内的 restricted → `member`；
+ * left / kicked → `guest`。Telegram 没有身份组，`roles` 不上报。
+ *
+ * 只有管理员权限作为平台权限上报：restricted 成员的 `can_*`（如 `can_pin_messages`）是对其个人的
+ * 发言许可，普通成员同样可能按群默认权限拥有，两者都不上报，`platform-permission:*` 只由管理员满足。
+ */
+export declare function telegramChatMemberStanding(member: {
+    readonly status?: string;
+    readonly is_member?: boolean;
+}): PlatformStanding;

package/lib/platform-permit.js

@@ -1,51 +1,32 @@
-const ADAPTER = 'telegram';
 export function platformPermit(perm) {
-    return `platform(${ADAPTER},${perm})`;
+    return `platform-permission:${perm}`;
 }
-const FACTORY_PERM_MAP = {
-    scene_admin: 'chat_administrator',
-    scene_owner: 'chat_creator',
-};
-export function telegramGroupPermitResolver(logicalPerm) {
-    return platformPermit(FACTORY_PERM_MAP[logicalPerm] ?? logicalPerm);
-}
-export function normalizeTelegramChatMember(member) {
-    const permissions = [];
+/** Administrator rights a chat creator implicitly holds (Bot API `ChatAdministratorRights`). */
+const TELEGRAM_ADMIN_RIGHTS = [
+    'manage_chat', 'delete_messages', 'manage_video_chats', 'restrict_members', 'promote_members', 'change_info',
+    'invite_users', 'post_stories', 'edit_stories', 'delete_stories', 'post_messages', 'edit_messages', 'pin_messages',
+    'manage_topics',
+];
+/**
+ * ADR 0056 §1：`getChatMember` 结果 → `sender.platform`。
+ * creator → `owner`（拥有全部管理员权限）；administrator → `admin`，其 `can_*` 权限去掉前缀进
+ * `permissions`（如 `restrict_members`、`pin_messages`）；member / 仍在群内的 restricted → `member`；
+ * left / kicked → `guest`。Telegram 没有身份组，`roles` 不上报。
+ *
+ * 只有管理员权限作为平台权限上报：restricted 成员的 `can_*`（如 `can_pin_messages`）是对其个人的
+ * 发言许可，普通成员同样可能按群默认权限拥有，两者都不上报，`platform-permission:*` 只由管理员满足。
+ */
+export function telegramChatMemberStanding(member) {
     const status = member.status;
-    if (status === 'creator') {
-        permissions.push('chat_creator', 'chat_administrator', 'restrict_members', 'pin_messages');
-        return { role: 'owner', permissions };
-    }
+    if (status === 'creator')
+        return { standing: 'owner', permissions: [...TELEGRAM_ADMIN_RIGHTS] };
     if (status === 'administrator') {
-        permissions.push('chat_administrator');
-        if (member.can_restrict_members)
-            permissions.push('restrict_members');
-        if (member.can_pin_messages)
-            permissions.push('pin_messages');
-        if (member.can_delete_messages)
-            permissions.push('delete_messages');
-        if (member.can_manage_chat)
-            permissions.push('manage_chat');
-        return { role: 'admin', permissions };
-    }
-    return { role: 'member', permissions };
-}
-export function checkTelegramPlatformPermit(perm, subject) {
-    const role = subject.sender?.role?.[0];
-    const permissions = subject.sender?.permissions ?? [];
-    const has = (t) => permissions.includes(t);
-    switch (perm) {
-        case 'chat_creator':
-            return role === 'owner' || role === 'creator' || has('chat_creator');
-        case 'chat_administrator':
-            return role === 'owner' || role === 'admin' || role === 'creator' || role === 'administrator' || has('chat_administrator');
-        case 'restrict_members':
-            return has('restrict_members') || role === 'owner' || role === 'creator';
-        case 'pin_messages':
-            return has('pin_messages') || role === 'owner' || role === 'creator';
-        case 'manage_chat':
-            return has('manage_chat') || role === 'owner' || role === 'creator';
-        default:
-            return false;
+        const granted = Object.entries(member)
+            .filter(([key, value]) => key.startsWith('can_') && value === true)
+            .map(([key]) => key.slice(4));
+        return { standing: 'admin', ...(granted.length ? { permissions: granted } : {}) };
     }
+    if (status === 'left' || status === 'kicked' || (status === 'restricted' && member.is_member === false))
+        return { standing: 'guest' };
+    return { standing: 'member' };
 }

package/lib/protocol.d.ts

@@ -3,7 +3,6 @@ import type { EndpointProfileConfiguration } from 'zhin.js/adapter';
  * 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';
 import { type ConversationKind, type ConversationRef } from '@zhin.js/im-contract';
 import type { Segment } from '@zhin.js/core/runtime';
 /** One endpoint config after AdapterIndex expands `plugins.<instanceKey>.endpoints`. */
@@ -130,6 +129,17 @@ export interface TelegramUpdate {
     readonly message?: TelegramMessage;
     readonly edited_message?: TelegramMessage;
     readonly callback_query?: TelegramCallbackQuery;
+    /** A member's status changed (only delivered when `allowed_updates` lists it and the Bot is an admin). */
+    readonly chat_member?: TelegramChatMemberUpdated;
+    /** The Bot's own member status changed. */
+    readonly my_chat_member?: TelegramChatMemberUpdated;
+}
+export interface TelegramChatMemberUpdated {
+    readonly chat: TelegramChat;
+    readonly from?: TelegramUser;
+    readonly date?: number;
+    readonly old_chat_member?: TelegramChatMember;
+    readonly new_chat_member: TelegramChatMember;
 }
 export interface TelegramChatMember {
     readonly status: string;
@@ -138,6 +148,8 @@ export interface TelegramChatMember {
     readonly can_pin_messages?: boolean;
     readonly can_delete_messages?: boolean;
     readonly can_manage_chat?: boolean;
+    /** `restricted` only: whether the user is still a member of the chat. */
+    readonly is_member?: boolean;
 }
 export interface TelegramWireSegment {
     readonly type: string;
@@ -237,13 +249,22 @@ export type TelegramOutboundAction = {
             readonly message_id: number;
         };
     };
+} | {
+    readonly method: 'sendPoll';
+    readonly params: {
+        readonly chat_id: number | string;
+        readonly question: string;
+        readonly options: readonly string[];
+        readonly is_anonymous: boolean;
+        readonly allows_multiple_answers: boolean;
+        readonly reply_parameters?: {
+            readonly message_id: number;
+        };
+    };
 };
 export declare function resolveTelegramConfig(config: TelegramEndpointConfig): 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;
 /** Telegram chat.type → canonical 会话 kind（supergroup 即 group，无容器层级故无 parent）。 */
 export declare function resolveTelegramChannelType(chatType: TelegramChat['type']): ConversationKind;

package/lib/protocol.js

@@ -1,3 +1,7 @@
+/**
+ * Telegram Bot API protocol helpers — no legacy Adapter/Endpoint / segment-mapper.
+ * Canonicalization is owned by gateway/core before endpoint.send.
+ */
 import { EndpointDeliveryError, isMediaRef } from '@zhin.js/im-contract';
 import { formatCompact, getLogger } from '@zhin.js/logger';
 import { escapeTelegramHtml, markdownToTelegramHtml } from './markdown-to-html.js';
@@ -12,7 +16,8 @@ export function resolveTelegramConfig(config) {
     const webhookSource = config.webhook;
     const mode = polling === false ? 'webhook' : 'polling';
     const apiBaseUrl = (config.apiBaseUrl ?? 'https://api.telegram.org').replace(/\/$/, '');
-    const allowedUpdates = config.allowedUpdates ?? ['message', 'callback_query'];
+    // chat_member / my_chat_member keep the cached sender standing fresh (ADR 0056 §1).
+    const allowedUpdates = config.allowedUpdates ?? ['message', 'callback_query', 'chat_member', 'my_chat_member'];
     const webhook = mode === 'webhook'
         ? {
             domain: webhookSource?.domain ?? '',
@@ -49,21 +54,6 @@ export function buildWebhookUrl(webhook) {
     }
     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}`;
 }
@@ -474,6 +464,31 @@ function buildOutboundActions(target, payload, uploads) {
                 }
                 break;
             }
+            case 'telegram:sticker': {
+                // Agent-authored sticker: an existing Telegram file_id or an http(s) URL only, never a host path.
+                const sticker = typeof data.sticker === 'string' ? data.sticker.trim() : '';
+                if (!sticker || /^(?:file:|base64:|attach:)/i.test(sticker) || (/[\\/]/.test(sticker) && !/^https?:\/\//i.test(sticker))) {
+                    throw new EndpointDeliveryError('invalid_payload', 'telegram:sticker requires a Telegram file_id or an http(s) URL', 'not_sent');
+                }
+                flushText();
+                actions.push({ method: 'sendSticker', params: { chat_id: chatId, sticker, ...replyParams() } });
+                break;
+            }
+            case 'telegram:poll': {
+                const question = typeof data.question === 'string' ? data.question.trim() : '';
+                const options = Array.isArray(data.options) ? data.options.map(String).filter(Boolean) : [];
+                if (!question || options.length < 2) {
+                    throw new EndpointDeliveryError('invalid_payload', 'telegram:poll requires a question and at least two options', 'not_sent');
+                }
+                flushText();
+                actions.push({ method: 'sendPoll', params: {
+                        chat_id: chatId, question, options,
+                        is_anonymous: data.is_anonymous !== false,
+                        allows_multiple_answers: data.allows_multiple_answers === true,
+                        ...replyParams(),
+                    } });
+                break;
+            }
             case 'location': {
                 flushText();
                 actions.push({

package/lib/webhook.d.ts

@@ -1,4 +1,3 @@
-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，避免长度差异直接抛异常。 */
@@ -9,4 +8,4 @@ export interface TelegramWebhookHandler {
     handleUpdate(update: TelegramUpdate): void | Promise<void>;
 }
 export declare function registerTelegramWebhookRoutes(http: HttpHost, handler: TelegramWebhookHandler): HttpRouteRegistration[];
-export declare function handleTelegramWebhookRequest(request: IncomingMessage, response: ServerResponse, handler: TelegramWebhookHandler): Promise<void>;
+export declare function handleTelegramWebhookRequest(request: Request, handler: TelegramWebhookHandler): Promise<Response>;

package/lib/webhook.js

@@ -2,8 +2,8 @@
  * Telegram webhook HTTP: secret token → parse → handle update.
  */
 import { timingSafeEqual } from 'node:crypto';
+import { readTextBody } from '@zhin.js/host-http-contract';
 import { getLogger } from '@zhin.js/logger';
-import { readTextBody } from './protocol.js';
 const logger = getLogger('telegram');
 /** 等长时才 timingSafeEqual，避免长度差异直接抛异常。 */
 export function safeTokenEqual(a, b) {
@@ -14,21 +14,16 @@ export function safeTokenEqual(a, b) {
 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'] }),
+        http.route('POST', path, (request) => handleTelegramWebhookRequest(request, handler), { summary: 'Telegram Bot API webhook', tags: ['telegram'] }),
     ];
 }
-export async function handleTelegramWebhookRequest(request, response, handler) {
+export async function handleTelegramWebhookRequest(request, 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;
+            const token = request.headers.get('x-telegram-bot-api-secret-token');
             if (!token || !safeTokenEqual(token, secret)) {
-                response.writeHead(403, { 'Content-Type': 'application/json' });
-                response.end(JSON.stringify({ ok: false, description: 'Invalid secret token' }));
-                return;
+                return new Response(JSON.stringify({ ok: false, description: 'Invalid secret token' }), { status: 403, headers: { 'Content-Type': 'application/json' } });
             }
         }
         const rawBody = await readTextBody(request);
@@ -37,24 +32,18 @@ export async function handleTelegramWebhookRequest(request, response, handler) {
             update = JSON.parse(rawBody);
         }
         catch {
-            response.writeHead(400, { 'Content-Type': 'application/json' });
-            response.end(JSON.stringify({ ok: false, description: 'Invalid JSON' }));
-            return;
+            return new Response(JSON.stringify({ ok: false, description: 'Invalid JSON' }), { status: 400, headers: { 'Content-Type': 'application/json' } });
         }
         if (!update || !Number.isSafeInteger(update.update_id) || update.update_id < 0) {
-            response.writeHead(400, { 'Content-Type': 'application/json' });
-            response.end(JSON.stringify({ ok: false, description: 'Invalid update_id' }));
-            return;
+            return new Response(JSON.stringify({ ok: false, description: 'Invalid update_id' }), { status: 400, headers: { 'Content-Type': 'application/json' } });
         }
         if (!handler.isOpen)
             throw new Error('Telegram endpoint is not accepting updates');
         await handler.handleUpdate(update);
-        response.writeHead(200, { 'Content-Type': 'application/json' });
-        response.end(JSON.stringify({ ok: true }));
+        return new Response(JSON.stringify({ ok: true }), { status: 200, headers: { 'Content-Type': 'application/json' } });
     }
     catch (error) {
         logger.error('Telegram webhook error:', error);
-        response.writeHead(503, { 'Content-Type': 'application/json' });
-        response.end(JSON.stringify({ ok: false, description: 'Update was not admitted' }));
+        return new Response(JSON.stringify({ ok: false, description: 'Update was not admitted' }), { status: 503, headers: { 'Content-Type': 'application/json' } });
     }
 }

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@zhin.js/adapter-telegram",
-  "version": "1.1.26",
+  "version": "1.1.27",
   "description": "Zhin.js Telegram Bot API adapter for Plugin Runtime (long-poll getUpdates)",
   "type": "module",
   "main": "./lib/index.js",
@@ -31,25 +31,26 @@
     "directory": "plugins/adapters/telegram"
   },
   "dependencies": {
-    "@zhin.js/adapter": "1.1.32",
-    "@zhin.js/agent-feature": "1.1.16",
-    "@zhin.js/console-contract": "1.1.5",
-    "@zhin.js/core": "1.1.60",
-    "@zhin.js/feature-kit": "1.1.15",
-    "@zhin.js/host-http": "1.1.17",
-    "@zhin.js/im-contract": "1.1.13",
-    "@zhin.js/logger": "1.1.2",
-    "@zhin.js/page": "1.1.17",
-    "@zhin.js/skill": "1.1.16",
-    "@zhin.js/tool": "1.1.18"
+    "zod": "^4.6.7",
+    "@zhin.js/adapter": "1.1.33",
+    "@zhin.js/agent-feature": "1.1.17",
+    "@zhin.js/console-contract": "1.1.6",
+    "@zhin.js/core": "1.2.0",
+    "@zhin.js/feature-kit": "1.1.16",
+    "@zhin.js/host-http": "1.2.0",
+    "@zhin.js/host-http-contract": "1.2.0",
+    "@zhin.js/im-contract": "1.1.14",
+    "@zhin.js/logger": "1.1.3",
+    "@zhin.js/page": "1.1.18",
+    "@zhin.js/skill": "1.1.17",
+    "@zhin.js/tool": "1.1.19"
   },
   "peerDependencies": {
-    "zod": "^4.0.0",
-    "@zhin.js/adapter": "^1.1.32",
-    "@zhin.js/command": "^1.1.17",
-    "@zhin.js/core": "^1.1.60",
-    "@zhin.js/permission": "^1.1.15",
-    "zhin.js": "^1.1.25"
+    "@zhin.js/adapter": "^1.1.33",
+    "@zhin.js/command": "^1.2.0",
+    "@zhin.js/core": "^1.2.0",
+    "@zhin.js/permission": "^1.2.0",
+    "zhin.js": "^1.1.26"
   },
   "peerDependenciesMeta": {
     "@zhin.js/command": {
@@ -57,9 +58,6 @@
     },
     "zhin.js": {
       "optional": true
-    },
-    "zod": {
-      "optional": true
     }
   },
   "devDependencies": {
@@ -67,10 +65,9 @@
     "htmlparser2": "12.0.0",
     "typescript": "^6.0.3",
     "vitest": "^4.1.10",
-    "zod": "^4.4.3",
-    "@zhin.js/host-http": "1.1.17",
-    "@zhin.js/pagemanager": "1.1.24",
-    "zhin.js": "1.1.25"
+    "@zhin.js/host-http": "1.2.0",
+    "@zhin.js/pagemanager": "1.1.25",
+    "zhin.js": "1.1.26"
   },
   "files": [
     "adapters",
@@ -80,7 +77,6 @@
     "schema.json",
     "src",
     "lib",
-    "tools",
     "agents",
     "README.md",
     "CHANGELOG.md",
@@ -130,6 +126,6 @@
   "scripts": {
     "build": "tsc",
     "clean": "rimraf lib",
-    "test": "NODE_OPTIONS=--experimental-strip-types vitest run --root ../../.. plugins/adapters/telegram/tests"
+    "test": "vitest run --root ../../.. plugins/adapters/telegram/tests"
   }
 }

package/plugin.js

@@ -1,7 +1,5 @@
 // Generated by build-plugin-runtime-entries.mjs. Do not edit.
 import { definePlugin } from 'zhin.js';
-import { permissionHostToken } from '@zhin.js/permission';
-import { checkTelegramPlatformPermit } from "./lib/platform-permit.js";
 import { createTelegramConsoleRpc } from "./lib/console.js";
 export default definePlugin({
     name: 'telegram',
@@ -10,12 +8,8 @@ export default definePlugin({
         displayName: 'Telegram Bot API Adapter',
     },
     setup(context) {
-        const dispose = context.resources.has(permissionHostToken)
-            ? context.resources.use(permissionHostToken).registerPlatform('telegram', checkTelegramPlatformPermit)
-            : undefined;
         return {
             consoleRpc: createTelegramConsoleRpc(() => context.config.get()),
-            ...(dispose ? { dispose } : {}),
         };
     },
 });

package/schema.json

@@ -40,34 +40,6 @@
       "type": "string",
       "default": "https://api.telegram.org"
     },
-    "master": {
-      "type": [
-        "string",
-        "number"
-      ],
-      "description": "框架 master（Telegram user id；AI/工具权限、endpoint 管理）。endpoints[i].master 可逐项覆盖",
-      "x-i18n": {
-        "en": {
-          "description": "Framework masters (Telegram user id; AI/tool permissions and endpoint management). endpoints[i].master can override this value."
-        }
-      }
-    },
-    "trusted": {
-      "type": "array",
-      "items": {
-        "type": [
-          "string",
-          "number"
-        ],
-        "description": "Trusted Telegram user id"
-      },
-      "description": "框架 trusted 用户列表（弱于 master）。endpoints[i].trusted 可逐项追加",
-      "x-i18n": {
-        "en": {
-          "description": "Framework trusted users, below master authority. endpoints[i].trusted can add users."
-        }
-      }
-    },
     "endpoints": {
       "type": "array",
       "minItems": 1,
@@ -76,34 +48,6 @@
         "type": "object",
         "additionalProperties": false,
         "properties": {
-          "master": {
-            "type": [
-              "string",
-              "number"
-            ],
-            "description": "本 endpoint 的框架 master（Telegram user id）；覆盖顶层 master",
-            "x-i18n": {
-              "en": {
-                "description": "Framework masters for this endpoint (Telegram user id), overriding the top-level master list."
-              }
-            }
-          },
-          "trusted": {
-            "type": "array",
-            "items": {
-              "type": [
-                "string",
-                "number"
-              ],
-              "description": "Trusted Telegram user id"
-            },
-            "description": "本 endpoint 的 trusted 列表",
-            "x-i18n": {
-              "en": {
-                "description": "Trusted users for this endpoint."
-              }
-            }
-          },
           "token": {
             "type": "string",
             "description": "Telegram bot token"