@zhin.js/adapter-telegram 1.1.26 → 1.1.27

package/src/endpoint.ts

@@ -3,7 +3,7 @@ import { createTelegramStreaming } from './streaming.js';
 import {
   createEndpointSpecification, endpointSpec, type Endpoint, type EndpointSpecification, createEndpointLifecycle,
   type EndpointLifecycle, type EndpointContentPort, type EndpointContentResolveContext,
-  type EndpointControl, type EndpointSendRequest, type EndpointTransportState,
+  type EndpointControl, type EndpointManagement, type EndpointSendRequest, type EndpointTransportState,
   InboundDeduper, TtlLookupCache,
 } from 'zhin.js/adapter';
 /**
@@ -17,13 +17,14 @@ import {
   type ConversationReference,
   type ConversationResolution,
   type MessageRef,
+  type PlatformStanding,
 } from '@zhin.js/im-contract';
 import { formatCompact, getAdapterLogger } from '@zhin.js/logger';
 import type { CapabilityId } from 'zhin.js';
 import { runTelegramPollLoop } from './polling.js';
 import { TelegramApiError } from './api-error.js';
 export { TelegramApiError } from './api-error.js';
-import { normalizeTelegramChatMember } from './platform-permit.js';
+import { telegramChatMemberStanding } from './platform-permit.js';
 import {
   buildWebhookUrl,
   formatCallbackContent,
@@ -37,6 +38,7 @@ import {
   type ResolvedTelegramConfig,
   type TelegramCallbackQuery,
   type TelegramChatMember,
+  type TelegramChatMemberUpdated,
   type TelegramMessage,
   type TelegramOutboundUpload,
   type TelegramUpdate,
@@ -46,13 +48,13 @@ import { createTelegramSelfProfile } from './self-profile.js';
 
 const CHAT_MEMBER_CACHE_TTL_MS = 60_000;
 const CHAT_MEMBER_CACHE_MAX = 2_000;
+/** A failed `getChatMember` is not retried for every message of a busy chat (unknown standing meanwhile). */
+const CHAT_MEMBER_FAILURE_TTL_MS = 10_000;
 const ADMITTED_UPDATE_LIMIT = 2_048;
 const INFLIGHT_UPDATE_LIMIT = 256;
 
-interface ChatMemberPermit {
-  readonly role?: string;
-  readonly permissions: string[];
-}
+/** ADR 0056 §1 normalized standing of one chat member (cached per chat + user). */
+type ChatMemberPermit = PlatformStanding;
 
 /** One admitted platform message and its original framework lifetime. */
 interface TelegramMessageAdmission {
@@ -76,7 +78,8 @@ export { TelegramClient, type TelegramClientApi, type TelegramFetch } from './te
 /**
  * Telegram Bot API 无列表类接口（无 getMyChats/getChatMembers），
  * 仅 getChat/getChatMember 按已知 id 单查，不构成列表能力；
- * 因此本 endpoint 不暴露 EndpointManagement（Console 社交面 RPC 对该平台保持未接线）。
+ * 因此本 endpoint 的 EndpointManagement 只有 `inspectSelfStanding`（ADR 0056 §1：getChatMember bot），
+ * Console 社交面 RPC 对该平台保持未接线。
  */
 export class TelegramEndpoint extends TelegramClient implements Endpoint {
   readonly [endpointSpec]: EndpointSpecification;
@@ -100,6 +103,23 @@ export class TelegramEndpoint extends TelegramClient implements Endpoint {
     ttlMs: CHAT_MEMBER_CACHE_TTL_MS,
     maxEntries: CHAT_MEMBER_CACHE_MAX,
   });
+  /** Recently failed lookups (negative cache): the standing stays unknown until it expires. */
+  readonly #chatMemberFailures = new TtlLookupCache<string, true>({
+    ttlMs: CHAT_MEMBER_FAILURE_TTL_MS,
+    maxEntries: CHAT_MEMBER_CACHE_MAX,
+  });
+  /** Concurrent messages from one sender share one `getChatMember` call. */
+  readonly #chatMemberInflight = new Map<string, { promise?: Promise<ChatMemberPermit | undefined> }>();
+  readonly #management: EndpointManagement = Object.freeze<EndpointManagement>({
+    // ADR 0056 §1: the Bot's own standing (`bot:*` permits); the framework caches per conversation.
+    inspectSelfStanding: async ({ conversation, signal }) => {
+      if (conversation.kind === 'private' || !this.#botUserId) return undefined;
+      const member = await this.callApi<TelegramChatMember>('getChatMember', {
+        chat_id: Number(conversation.id), user_id: this.#botUserId,
+      }, signal);
+      return telegramChatMemberStanding(member);
+    },
+  });
   readonly #control: EndpointControl = Object.freeze<EndpointControl>({
     recall: ({ message, signal }) => this.recallMessage(message, signal),
   });
@@ -117,7 +137,7 @@ export class TelegramEndpoint extends TelegramClient implements Endpoint {
       start: signal => this.#startFramework(signal), open: () => this.#openFramework(), close: () => this.#closeFramework(),
       stop: () => this.#stopFramework(), send: request => this.#sendFramework(request),
       get name() { return options.config.id; }, get transportState() { return endpoint.#transportState; },
-      control: this.#control, content: this.#content,
+      control: this.#control, content: this.#content, management: this.#management,
       streaming: options.config.streaming !== false ? createTelegramStreaming(() => this, options.config.streamingIntervalMs) : undefined,
       profile: createTelegramSelfProfile({ client: this,
         current: () => this.#botName === undefined ? {} : { nickname: this.#botName },
@@ -409,7 +429,7 @@ export class TelegramEndpoint extends TelegramClient implements Endpoint {
       sender: {
         id: String(msg.from?.id ?? ''),
         name: senderDisplayName(msg.from) || undefined,
-        ...(permit?.role ? { roles: [permit.role] } : {}),
+        ...(permit ? { platform: permit } : {}),
       },
       endpointId: this.#options.config.id,
       ...(mentioned ? { mentioned: true } : {}),
@@ -419,8 +439,6 @@ export class TelegramEndpoint extends TelegramClient implements Endpoint {
         chatType: msg.chat.type,
         userId: msg.from?.id,
         date: msg.date,
-        ...(permit?.role ? { senderRole: permit.role } : {}),
-        ...(permit?.permissions.length ? { senderPermissions: [...permit.permissions] } : {}),
       }),
     });
   }
@@ -446,7 +464,10 @@ export class TelegramEndpoint extends TelegramClient implements Endpoint {
     return false;
   }
 
-  /** 群消息 sender role 解析：getChatMember + 60s 缓存（对齐旧 enrichGroupSender）。 */
+  /**
+   * 群消息 sender role 解析：getChatMember + 60s 缓存；并发查询合并为一次调用，失败负缓存 10s，
+   * `chat_member` / `my_chat_member` 更新时以新状态覆盖缓存。
+   */
   async #resolveGroupSenderPermit(msg: TelegramMessage, signal: AbortSignal): Promise<ChatMemberPermit | undefined> {
     if (msg.chat.type === 'private' || !msg.from?.id) return undefined;
     const chatId = Number(msg.chat.id);
@@ -454,20 +475,45 @@ export class TelegramEndpoint extends TelegramClient implements Endpoint {
     const key = `${chatId}:${userId}`;
     const cached = this.#chatMemberCache.get(key);
     if (cached) return cached;
-    try {
-      const member = await this.callApi<TelegramChatMember>('getChatMember', {
-        chat_id: chatId,
-        user_id: userId,
-      }, signal);
-      if (signal.aborted) return undefined;
-      const normalized = normalizeTelegramChatMember(member);
-      const entry: ChatMemberPermit = { ...normalized };
-      this.#chatMemberCache.set(key, entry);
-      return entry;
-    } catch {
-      // 保守拒绝：无角色快照
-      return undefined;
+    if (this.#chatMemberFailures.get(key)) return undefined;
+    let task = this.#chatMemberInflight.get(key)?.promise;
+    if (!task) {
+      const lookup: { promise?: Promise<ChatMemberPermit | undefined> } = {};
+      task = (async () => {
+        await undefined; // registered in #chatMemberInflight before the body runs
+        try {
+          const member = await this.callApi<TelegramChatMember>('getChatMember', {
+            chat_id: chatId,
+            user_id: userId,
+          }, signal);
+          if (signal.aborted) return undefined;
+          const entry: ChatMemberPermit = telegramChatMemberStanding(member);
+          // Invalidated (chat_member update) while in flight: do not store the older answer.
+          if (this.#chatMemberInflight.get(key) === lookup) this.#chatMemberCache.set(key, entry);
+          return entry;
+        } catch {
+          // 保守拒绝：无角色快照；取消不算失败
+          if (!signal.aborted && this.#chatMemberInflight.get(key) === lookup) this.#chatMemberFailures.set(key, true);
+          return undefined;
+        } finally {
+          if (this.#chatMemberInflight.get(key) === lookup) this.#chatMemberInflight.delete(key);
+        }
+      })();
+      lookup.promise = task;
+      this.#chatMemberInflight.set(key, lookup);
     }
+    const entry = await task;
+    return signal.aborted ? undefined : entry;
+  }
+
+  /** `chat_member` / `my_chat_member`: the update carries the new status, so it replaces the cached one. */
+  #applyChatMemberUpdate(update: TelegramChatMemberUpdated | undefined): void {
+    const userId = update?.new_chat_member?.user?.id;
+    if (!update?.chat || userId == null) return;
+    const key = `${Number(update.chat.id)}:${userId}`;
+    this.#chatMemberInflight.delete(key);
+    this.#chatMemberFailures.delete(key);
+    this.#chatMemberCache.set(key, telegramChatMemberStanding(update.new_chat_member));
   }
 
   /** Test / internal: admit a callback query when open. */
@@ -544,6 +590,8 @@ export class TelegramEndpoint extends TelegramClient implements Endpoint {
     if (update.message || update.callback_query) {
       await this[endpointSpec].events.platform(eventName, update);
     } else {
+      this.#applyChatMemberUpdate(update.chat_member);
+      this.#applyChatMemberUpdate(update.my_chat_member);
       await this[endpointSpec].events.emitAccepted('platform.receive', Object.freeze({ name: eventName, event: update }));
       return;
     }

package/src/index.ts

@@ -33,10 +33,8 @@ export { type TelegramClientEventMap } from './client.js';
 export { TelegramAdapter } from './adapter.js';
 
 export {
-  checkTelegramPlatformPermit,
-  normalizeTelegramChatMember,
+  telegramChatMemberStanding,
   platformPermit,
-  telegramGroupPermitResolver,
 } from './platform-permit.js';
 
 export type { TelegramPollRequest } from './telegram-client.js';

package/src/platform-permit.ts

@@ -1,68 +1,39 @@
 /**
- * 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';
-
-const ADAPTER = 'telegram';
+import type { PlatformStanding } from '@zhin.js/im-contract';
 
 export function platformPermit(perm: string): string {
-  return `platform(${ADAPTER},${perm})`;
+  return `platform-permission:${perm}`;
 }
 
-const FACTORY_PERM_MAP: Record<string, string> = {
-  scene_admin: 'chat_administrator',
-  scene_owner: 'chat_creator',
-};
-
-export function telegramGroupPermitResolver(logicalPerm: string): string {
-  return platformPermit(FACTORY_PERM_MAP[logicalPerm] ?? logicalPerm);
-}
+/** 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',
+] as const;
 
-export 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[] } {
-  const permissions: string[] = [];
+/**
+ * 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: { readonly status?: string; readonly is_member?: boolean }): PlatformStanding {
   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: string, subject: PermissionSubject): boolean {
-  const role = subject.sender?.role?.[0];
-  const permissions = subject.sender?.permissions ?? [];
-  const has = (t: string) => 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 as Readonly<Record<string, unknown>>)
+      .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/src/protocol.ts

@@ -4,7 +4,6 @@ import type { EndpointProfileConfiguration } from 'zhin.js/adapter';
  * Canonicalization is owned by gateway/core before endpoint.send.
  */
 
-import type { IncomingMessage } from 'node:http';
 import { EndpointDeliveryError, isMediaRef, type ConversationKind, type ConversationRef } from '@zhin.js/im-contract';
 import type { Segment } from '@zhin.js/core/runtime';
 import { formatCompact, getLogger } from '@zhin.js/logger';
@@ -144,6 +143,18 @@ 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 {
@@ -153,6 +164,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 {
@@ -245,6 +258,17 @@ export type TelegramOutboundAction =
       readonly longitude: number;
       readonly reply_parameters?: { 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 function resolveTelegramConfig(config: TelegramEndpointConfig): ResolvedTelegramConfig {
@@ -256,7 +280,8 @@ export function resolveTelegramConfig(config: TelegramEndpointConfig): ResolvedT
   const webhookSource = config.webhook;
   const mode: 'polling' | 'webhook' = 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 ?? '',
@@ -297,24 +322,6 @@ export function buildWebhookUrl(webhook: NonNullable<ResolvedTelegramConfig['web
   return `${domain}${webhook.path}`;
 }
 
-export async function readTextBody(
-  request: IncomingMessage,
-  options: { readonly limit?: number } = {},
-): Promise<string> {
-  const limit = options.limit ?? 1_048_576;
-  const chunks: Buffer[] = [];
-  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: Pick<ResolvedTelegramConfig, 'apiBaseUrl' | 'token'>, method: string): string {
   return `${config.apiBaseUrl}/bot${config.token}/${method}`;
@@ -746,6 +753,31 @@ function buildOutboundActions(
         }
         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/src/webhook.ts

@@ -2,10 +2,10 @@
  * Telegram webhook HTTP: secret token → parse → handle update.
  */
 import { timingSafeEqual } from 'node:crypto';
-import type { IncomingMessage, ServerResponse } from 'node:http';
 import type { HttpHost, HttpRouteRegistration } from '@zhin.js/host-http';
+import { readTextBody } from '@zhin.js/host-http-contract';
 import { getLogger } from '@zhin.js/logger';
-import { readTextBody, type ResolvedTelegramConfig, type TelegramUpdate } from './protocol.js';
+import { type ResolvedTelegramConfig, type TelegramUpdate } from './protocol.js';
 
 const logger = getLogger('telegram');
 
@@ -28,26 +28,20 @@ export function registerTelegramWebhookRoutes(
 ): HttpRouteRegistration[] {
   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: IncomingMessage,
-  response: ServerResponse,
+  request: Request,
   handler: TelegramWebhookHandler,
-): Promise<void> {
+): Promise<Response> {
   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' } });
       }
     }
 
@@ -56,23 +50,17 @@ export async function handleTelegramWebhookRequest(
     try {
       update = JSON.parse(rawBody) as TelegramUpdate;
     } 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' } });
   }
 }