@zhin.js/adapter-telegram 7.0.2 → 7.0.3

package/CHANGELOG.md

@@ -1,5 +1,21 @@
 # Changelog
 
+## 7.0.3
+
+### Patch Changes
+
+- Updated dependencies [afc0e66]
+- Updated dependencies [2e41ad5]
+- Updated dependencies [9f57124]
+  - @zhin.js/core@1.5.2
+  - @zhin.js/adapter@1.1.5
+  - @zhin.js/im-contract@1.0.1
+  - @zhin.js/plugin-runtime@1.1.3
+  - @zhin.js/command@1.0.7
+  - @zhin.js/host-http@1.0.6
+  - @zhin.js/agent@1.1.3
+  - zhin.js@6.0.2
+
 ## 7.0.2
 
 ### Patch Changes

package/README.md

@@ -7,7 +7,7 @@ Zhin.js Telegram Bot API 适配器（Plugin Runtime），默认通过 **长轮
 - 长轮询 `getUpdates` 入站（默认；无需公网 IP / host-http）
 - 解析 text / image / video / audio / voice / document / sticker / location / callback_query
 - 支持私聊与群组
-- 出站 `send({ target, payload })` → Bot API（text / media / keyboard）
+- 出站 `send({ conversation, payload })` → Bot API（text / media / keyboard）
 - 约定式 `defineAdapter` / `definePlugin`（无需 `usePlugin`）
 - Webhook 模式延期（需 `httpHostToken`）；配置 `polling: false` 会明确报错
 
@@ -25,8 +25,8 @@ pnpm add @zhin.js/adapter-telegram
 - 配置经插件 `schema.json` 落到 `plugins.<instanceKey>`
 - **无需** `@zhin.js/host-http`（polling 路径）
 
-入站：`gateway.receive({ adapter, target: chatId, content: text, sender, metadata })`  
-出站：`send({ target, payload })` → Telegram Bot API
+入站：`gateway.receive({ conversation, message, content, sender, metadata })`（`conversation` 为 ConversationRef，由 `telegramInboundConversation` 归一化）  
+出站：`send({ conversation, payload })` → Telegram Bot API
 
 ### 平台权限（platform permit）
 

package/lib/endpoint.d.ts

@@ -40,7 +40,7 @@ export declare class TelegramEndpoint implements EndpointInstance {
     open(): void;
     close(): void;
     stop(): Promise<void>;
-    send({ target, conversation, payload }: EndpointSendRequest): Promise<string>;
+    send({ conversation, payload }: EndpointSendRequest): Promise<string>;
     recallMessage(messageId: string): Promise<void>;
     /** Test / internal: admit a message when open. */
     admit(msg: TelegramMessage): void;

package/lib/endpoint.js

@@ -2,11 +2,11 @@
  * TelegramEndpoint — lifecycle, outbound, admit, Bot API helpers for agent tools.
  */
 import { readFile } from 'node:fs/promises';
-import { formatLegacyMessageReference, nativeConversationId, parseLegacyMessageReference, } from '@zhin.js/im-contract';
+import { formatLegacyMessageRef, nativeConversationId, parseLegacyMessageReference, } from '@zhin.js/im-contract';
 import { formatCompact, getLogger } from '@zhin.js/logger';
 import { runTelegramPollLoop } from './polling.js';
 import { normalizeTelegramChatMember } from './platform-permit.js';
-import { botApiUrl, buildWebhookUrl, formatCallbackContent, formatCallbackSegments, formatInboundContent, formatInboundSegments, formatOutboundPlan, resolveChannel, senderDisplayName, } from './protocol.js';
+import { botApiUrl, buildWebhookUrl, formatCallbackContent, formatCallbackSegments, formatInboundContent, formatInboundSegments, formatOutboundPlan, resolveTelegramChannelType, senderDisplayName, telegramInboundConversation, } from './protocol.js';
 import { registerTelegramAgentEndpoint } from './telegram-agent-deps.js';
 import { registerTelegramWebhookRoutes } from './webhook.js';
 const logger = getLogger('telegram');
@@ -131,9 +131,8 @@ export class TelegramEndpoint {
         this.#started = false;
         logger.debug(formatCompact({ op: 'disconnect', endpoint: this.#options.config.name }));
     }
-    async send({ target, conversation, payload }) {
-        const chatId = nativeConversationId(target, conversation);
-        const plan = formatOutboundPlan(chatId, payload);
+    async send({ conversation, payload }) {
+        const plan = formatOutboundPlan(conversation.id, payload);
         let lastId = '';
         for (const action of plan.actions) {
             const form = await this.#buildUploadForm(action.params, plan.uploads);
@@ -145,7 +144,7 @@ export class TelegramEndpoint {
         }
         if (!lastId)
             return `telegram-${Date.now()}`;
-        return formatLegacyMessageReference({ target, messageId: lastId });
+        return formatLegacyMessageRef({ conversation, id: lastId });
     }
     async recallMessage(messageId) {
         if (!messageId || messageId.startsWith('telegram-'))
@@ -188,26 +187,25 @@ export class TelegramEndpoint {
     admit(msg) {
         if (!this.#open)
             return;
-        const { channelId } = resolveChannel(msg);
-        void this.#admitWithSenderRole(msg, channelId).catch((err) => {
+        const conversation = telegramInboundConversation(String(this.#options.id), msg.chat);
+        void this.#admitWithSenderRole(msg, conversation).catch((err) => {
             logger.warn(formatCompact({
                 op: 'telegram_gateway_receive_failed',
-                target: channelId,
+                target: `${conversation.kind}:${conversation.id}`,
                 error: err instanceof Error ? err.message : String(err),
             }));
         });
     }
-    async #admitWithSenderRole(msg, channelId) {
+    async #admitWithSenderRole(msg, conversation) {
         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,
+            conversation,
+            message: { conversation, id: String(msg.message_id) },
             content: formatInboundContent(msg),
             segments: formatInboundSegments(msg),
             sender: senderDisplayName(msg.from),
-            id: String(msg.message_id),
             metadata: Object.freeze({
                 endpoint: this.#options.config.name,
                 // Preserve Telegram's native value below, but publish the canonical
@@ -287,15 +285,18 @@ export class TelegramEndpoint {
     admitCallback(query) {
         if (!this.#open)
             return;
+        const endpointId = String(this.#options.id);
         const msg = query.message;
-        const channelId = msg ? resolveChannel(msg).channelId : String(query.from.id);
+        // 无挂载消息的 callback（如 inline 模式）退化为 sender 私聊会话
+        const conversation = msg
+            ? telegramInboundConversation(endpointId, msg.chat)
+            : telegramInboundConversation(endpointId, { id: query.from.id, type: 'private' });
         void this.#options.gateway.receive({
-            adapter: this.#options.id,
-            target: channelId,
+            conversation,
+            message: { conversation, id: query.id },
             content: formatCallbackContent(query),
             segments: formatCallbackSegments(query),
             sender: senderDisplayName(query.from),
-            id: query.id,
             metadata: Object.freeze({
                 endpoint: this.#options.config.name,
                 eventType: 'callback_query',
@@ -305,7 +306,7 @@ export class TelegramEndpoint {
         }).catch((err) => {
             logger.warn(formatCompact({
                 op: 'telegram_gateway_receive_failed',
-                target: channelId,
+                target: `${conversation.kind}:${conversation.id}`,
                 error: err instanceof Error ? err.message : String(err),
             }));
         });
@@ -413,10 +414,3 @@ export class TelegramEndpoint {
         });
     }
 }
-function resolveTelegramChannelType(chatType) {
-    if (chatType === 'private')
-        return 'private';
-    if (chatType === 'channel')
-        return 'channel';
-    return 'group';
-}

package/lib/index.d.ts

@@ -1,4 +1,4 @@
 export { TelegramEndpoint, type TelegramEndpointOptions, type TelegramFetch, } from './endpoint.js';
-export { botApiUrl, formatCallbackContent, formatInboundContent, formatOutboundActions, formatOutboundPlan, normalizeWebhookPath, resolveChannel, resolveTelegramConfig, senderDisplayName, type ResolvedTelegramConfig, type TelegramAdapterConfig, type TelegramCallbackQuery, type TelegramChat, type TelegramChatMember, type TelegramMessage, type TelegramOutboundAction, type TelegramOutboundPlan, type TelegramOutboundUpload, type TelegramUpdate, type TelegramUser, type TelegramWireSegment, } from './protocol.js';
+export { botApiUrl, formatCallbackContent, formatInboundContent, formatOutboundActions, formatOutboundPlan, normalizeWebhookPath, resolveTelegramConfig, senderDisplayName, type ResolvedTelegramConfig, type TelegramAdapterConfig, type TelegramCallbackQuery, type TelegramChat, type TelegramChatMember, type TelegramMessage, type TelegramOutboundAction, type TelegramOutboundPlan, type TelegramOutboundUpload, 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

@@ -1,4 +1,4 @@
 export { TelegramEndpoint, } from './endpoint.js';
-export { botApiUrl, formatCallbackContent, formatInboundContent, formatOutboundActions, formatOutboundPlan, normalizeWebhookPath, resolveChannel, resolveTelegramConfig, senderDisplayName, } from './protocol.js';
+export { botApiUrl, formatCallbackContent, formatInboundContent, formatOutboundActions, formatOutboundPlan, normalizeWebhookPath, 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/protocol.d.ts

@@ -4,6 +4,7 @@
  */
 import type { IncomingMessage } from 'node:http';
 import type { Segment } from '@zhin.js/core/runtime';
+import type { ConversationKind, ConversationRef } from '@zhin.js/im-contract';
 /** Plugin Runtime owner config (`plugins.<instanceKey>` / schema.json). */
 export interface TelegramAdapterConfig {
     readonly name?: string;
@@ -236,10 +237,13 @@ 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;
-};
+/** Telegram chat.type → canonical 会话 kind（supergroup 即 group，无容器层级故无 parent）。 */
+export declare function resolveTelegramChannelType(chatType: TelegramChat['type']): ConversationKind;
+/**
+ * 入站归一化 → ConversationRef：Telegram 无 guild/群组容器层级，
+ * kind 直取 chat.type（private/group/supergroup/channel），无 parent。
+ */
+export declare function telegramInboundConversation(endpointId: string, chat: Pick<TelegramChat, 'id' | 'type'>): ConversationRef;
 export declare function senderDisplayName(user?: TelegramUser): string;
 /** Build inbound text for MessageGateway.receive. */
 export declare function formatInboundContent(msg: TelegramMessage): string;

package/lib/protocol.js

@@ -76,10 +76,23 @@ export async function readTextBody(request, options = {}) {
 export function botApiUrl(config, method) {
     return `${config.apiBaseUrl}/bot${config.token}/${method}`;
 }
-export function resolveChannel(msg) {
+/** 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(endpointId, chat) {
     return {
-        channelType: msg.chat.type === 'private' ? 'private' : 'group',
-        channelId: String(msg.chat.id),
+        endpoint: { id: endpointId, adapter: endpointId.split('\0')[0] ?? endpointId },
+        kind: resolveTelegramChannelType(chat.type),
+        id: String(chat.id),
     };
 }
 export function senderDisplayName(user) {

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@zhin.js/adapter-telegram",
-  "version": "7.0.2",
+  "version": "7.0.3",
   "description": "Zhin.js Telegram Bot API adapter for Plugin Runtime (long-poll getUpdates)",
   "type": "module",
   "main": "./lib/index.js",
@@ -32,21 +32,21 @@
     "directory": "plugins/adapters/telegram"
   },
   "dependencies": {
-    "@zhin.js/adapter": "1.1.4",
-    "@zhin.js/command": "1.0.6",
-    "@zhin.js/core": "1.5.1",
-    "@zhin.js/host-http": "1.0.5",
-    "@zhin.js/im-contract": "1.0.0",
+    "@zhin.js/adapter": "1.1.5",
+    "@zhin.js/command": "1.0.7",
+    "@zhin.js/core": "1.5.2",
+    "@zhin.js/host-http": "1.0.6",
+    "@zhin.js/im-contract": "1.0.1",
     "@zhin.js/logger": "1.0.75",
-    "@zhin.js/plugin-runtime": "1.1.2"
+    "@zhin.js/plugin-runtime": "1.1.3"
   },
   "peerDependencies": {
     "zod": "^4.0.0",
-    "@zhin.js/adapter": "1.1.4",
-    "@zhin.js/agent": "1.1.2",
-    "@zhin.js/core": "1.5.1",
-    "@zhin.js/plugin-runtime": "1.1.2",
-    "zhin.js": "6.0.1"
+    "@zhin.js/adapter": "1.1.5",
+    "@zhin.js/agent": "1.1.3",
+    "@zhin.js/core": "1.5.2",
+    "@zhin.js/plugin-runtime": "1.1.3",
+    "zhin.js": "6.0.2"
   },
   "peerDependenciesMeta": {
     "zhin.js": {
@@ -64,9 +64,9 @@
     "typescript": "^6.0.3",
     "vitest": "^4.1.10",
     "zod": "^4.4.3",
-    "@zhin.js/agent": "1.1.2",
-    "@zhin.js/host-http": "1.0.5",
-    "zhin.js": "6.0.1"
+    "@zhin.js/agent": "1.1.3",
+    "@zhin.js/host-http": "1.0.6",
+    "zhin.js": "6.0.2"
   },
   "files": [
     "adapters",

package/src/endpoint.ts

@@ -6,9 +6,10 @@ import type { EndpointControl, EndpointInstance, EndpointSendRequest } from '@zh
 import type { MessageGateway } from '@zhin.js/core/runtime';
 import type { HttpHost, HttpRouteRegistration } from '@zhin.js/host-http';
 import {
-  formatLegacyMessageReference,
+  formatLegacyMessageRef,
   nativeConversationId,
   parseLegacyMessageReference,
+  type ConversationRef,
 } from '@zhin.js/im-contract';
 import { formatCompact, getLogger } from '@zhin.js/logger';
 import type { CapabilityId } from '@zhin.js/plugin-runtime';
@@ -22,8 +23,9 @@ import {
   formatInboundContent,
   formatInboundSegments,
   formatOutboundPlan,
-  resolveChannel,
+  resolveTelegramChannelType,
   senderDisplayName,
+  telegramInboundConversation,
   type ResolvedTelegramConfig,
   type TelegramCallbackQuery,
   type TelegramChatMember,
@@ -207,9 +209,8 @@ export class TelegramEndpoint implements EndpointInstance {
     logger.debug(formatCompact({ op: 'disconnect', endpoint: this.#options.config.name }));
   }
 
-  async send({ target, conversation, payload }: EndpointSendRequest): Promise<string> {
-    const chatId = nativeConversationId(target, conversation);
-    const plan = formatOutboundPlan(chatId, payload);
+  async send({ conversation, payload }: EndpointSendRequest): Promise<string> {
+    const plan = formatOutboundPlan(conversation.id, payload);
     let lastId = '';
     for (const action of plan.actions) {
       const form = await this.#buildUploadForm(action.params, plan.uploads);
@@ -219,7 +220,7 @@ export class TelegramEndpoint implements EndpointInstance {
       if (result.message_id != null) lastId = String(result.message_id);
     }
     if (!lastId) return `telegram-${Date.now()}`;
-    return formatLegacyMessageReference({ target, messageId: lastId });
+    return formatLegacyMessageRef({ conversation, id: lastId });
   }
 
   async recallMessage(messageId: string): Promise<void> {
@@ -266,27 +267,26 @@ export class TelegramEndpoint implements EndpointInstance {
   /** Test / internal: admit a message when open. */
   admit(msg: TelegramMessage): void {
     if (!this.#open) return;
-    const { channelId } = resolveChannel(msg);
-    void this.#admitWithSenderRole(msg, channelId).catch((err) => {
+    const conversation = telegramInboundConversation(String(this.#options.id), msg.chat);
+    void this.#admitWithSenderRole(msg, conversation).catch((err) => {
       logger.warn(formatCompact({
         op: 'telegram_gateway_receive_failed',
-        target: channelId,
+        target: `${conversation.kind}:${conversation.id}`,
         error: err instanceof Error ? err.message : String(err),
       }));
     });
   }
 
-  async #admitWithSenderRole(msg: TelegramMessage, channelId: string): Promise<void> {
+  async #admitWithSenderRole(msg: TelegramMessage, conversation: ConversationRef): Promise<void> {
     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,
+      conversation,
+      message: { conversation, id: String(msg.message_id) },
       content: formatInboundContent(msg),
       segments: formatInboundSegments(msg),
       sender: senderDisplayName(msg.from),
-      id: String(msg.message_id),
       metadata: Object.freeze({
         endpoint: this.#options.config.name,
         // Preserve Telegram's native value below, but publish the canonical
@@ -360,15 +360,18 @@ export class TelegramEndpoint implements EndpointInstance {
   /** Test / internal: admit a callback query when open. */
   admitCallback(query: TelegramCallbackQuery): void {
     if (!this.#open) return;
+    const endpointId = String(this.#options.id);
     const msg = query.message;
-    const channelId = msg ? resolveChannel(msg).channelId : String(query.from.id);
+    // 无挂载消息的 callback（如 inline 模式）退化为 sender 私聊会话
+    const conversation = msg
+      ? telegramInboundConversation(endpointId, msg.chat)
+      : telegramInboundConversation(endpointId, { id: query.from.id, type: 'private' });
     void this.#options.gateway.receive({
-      adapter: this.#options.id,
-      target: channelId,
+      conversation,
+      message: { conversation, id: query.id },
       content: formatCallbackContent(query),
       segments: formatCallbackSegments(query),
       sender: senderDisplayName(query.from),
-      id: query.id,
       metadata: Object.freeze({
         endpoint: this.#options.config.name,
         eventType: 'callback_query',
@@ -378,7 +381,7 @@ export class TelegramEndpoint implements EndpointInstance {
     }).catch((err) => {
       logger.warn(formatCompact({
         op: 'telegram_gateway_receive_failed',
-        target: channelId,
+        target: `${conversation.kind}:${conversation.id}`,
         error: err instanceof Error ? err.message : String(err),
       }));
     });
@@ -521,11 +524,3 @@ export class TelegramEndpoint implements EndpointInstance {
     });
   }
 }
-
-function resolveTelegramChannelType(
-  chatType: TelegramMessage['chat']['type'],
-): 'private' | 'group' | 'channel' {
-  if (chatType === 'private') return 'private';
-  if (chatType === 'channel') return 'channel';
-  return 'group';
-}

package/src/index.ts

@@ -11,7 +11,6 @@ export {
   formatOutboundActions,
   formatOutboundPlan,
   normalizeWebhookPath,
-  resolveChannel,
   resolveTelegramConfig,
   senderDisplayName,
   type ResolvedTelegramConfig,

package/src/protocol.ts

@@ -6,6 +6,7 @@
 import type { IncomingMessage } from 'node:http';
 import { isMediaRef } from '@zhin.js/core';
 import type { Segment } from '@zhin.js/core/runtime';
+import type { ConversationKind, ConversationRef } from '@zhin.js/im-contract';
 import { formatCompact, getLogger } from '@zhin.js/logger';
 
 const logger = getLogger('telegram');
@@ -321,13 +322,27 @@ export function botApiUrl(config: Pick<ResolvedTelegramConfig, 'apiBaseUrl' | 't
   return `${config.apiBaseUrl}/bot${config.token}/${method}`;
 }
 
-export function resolveChannel(msg: Pick<TelegramMessage, 'chat'>): {
-  readonly channelType: 'private' | 'group';
-  readonly channelId: string;
-} {
+/** Telegram chat.type → canonical 会话 kind（supergroup 即 group，无容器层级故无 parent）。 */
+export function resolveTelegramChannelType(
+  chatType: TelegramChat['type'],
+): ConversationKind {
+  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(
+  endpointId: string,
+  chat: Pick<TelegramChat, 'id' | 'type'>,
+): ConversationRef {
   return {
-    channelType: msg.chat.type === 'private' ? 'private' : 'group',
-    channelId: String(msg.chat.id),
+    endpoint: { id: endpointId, adapter: endpointId.split('\0')[0] ?? endpointId },
+    kind: resolveTelegramChannelType(chat.type),
+    id: String(chat.id),
   };
 }