@zhin.js/adapter-telegram 1.0.68 → 1.1.0

package/lib/protocol.d.ts

@@ -0,0 +1,299 @@
+/**
+ * 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 { 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 id?: string;
+    readonly token?: string;
+    /** Default true. `false` selects webhook mode (requires httpHostToken). */
+    readonly polling?: boolean;
+    readonly webhook?: {
+        readonly domain?: string;
+        readonly path?: string;
+        readonly secretToken?: string;
+    };
+    readonly allowedUpdates?: readonly string[];
+    readonly apiBaseUrl?: string;
+    /** Transitional: legacy root `endpoints[]` with `context: telegram`. */
+    readonly endpoints?: ReadonlyArray<Partial<ResolvedTelegramConfig> & {
+        readonly context?: string;
+        readonly polling?: boolean;
+        readonly webhook?: TelegramAdapterConfig['webhook'];
+        readonly allowedUpdates?: readonly string[];
+        readonly apiBaseUrl?: string;
+    }>;
+}
+export interface ResolvedTelegramConfig {
+    readonly context: 'telegram';
+    readonly id: string;
+    readonly token: string;
+    readonly mode: 'polling' | 'webhook';
+    readonly allowedUpdates: readonly string[];
+    readonly apiBaseUrl: string;
+    readonly webhook?: {
+        readonly domain: string;
+        readonly path: string;
+        readonly secretToken?: string;
+    };
+}
+export interface TelegramUser {
+    readonly id: number;
+    readonly is_bot?: boolean;
+    readonly first_name?: string;
+    readonly last_name?: string;
+    readonly username?: string;
+}
+export interface TelegramChat {
+    readonly id: number;
+    readonly type: 'private' | 'group' | 'supergroup' | 'channel';
+    readonly title?: string;
+    readonly username?: string;
+}
+export interface TelegramMessageEntity {
+    readonly type: string;
+    readonly offset: number;
+    readonly length: number;
+    readonly url?: string;
+    readonly user?: TelegramUser;
+}
+export interface TelegramPhotoSize {
+    readonly file_id: string;
+    readonly file_unique_id?: string;
+    readonly width?: number;
+    readonly height?: number;
+    readonly file_size?: number;
+}
+export interface TelegramMessage {
+    readonly message_id: number;
+    readonly date: number;
+    readonly chat: TelegramChat;
+    readonly from?: TelegramUser;
+    readonly text?: string;
+    readonly caption?: string;
+    readonly entities?: readonly TelegramMessageEntity[];
+    readonly reply_to_message?: TelegramMessage;
+    readonly photo?: readonly TelegramPhotoSize[];
+    readonly video?: {
+        readonly file_id: string;
+        readonly file_unique_id?: string;
+        readonly width?: number;
+        readonly height?: number;
+        readonly duration?: number;
+        readonly file_size?: number;
+    };
+    readonly audio?: {
+        readonly file_id: string;
+        readonly file_unique_id?: string;
+        readonly duration?: number;
+        readonly performer?: string;
+        readonly title?: string;
+        readonly file_size?: number;
+    };
+    readonly voice?: {
+        readonly file_id: string;
+        readonly file_unique_id?: string;
+        readonly duration?: number;
+        readonly file_size?: number;
+    };
+    readonly document?: {
+        readonly file_id: string;
+        readonly file_unique_id?: string;
+        readonly file_name?: string;
+        readonly mime_type?: string;
+        readonly file_size?: number;
+    };
+    readonly sticker?: {
+        readonly file_id: string;
+        readonly file_unique_id?: string;
+        readonly width?: number;
+        readonly height?: number;
+        readonly is_animated?: boolean;
+        readonly is_video?: boolean;
+        readonly emoji?: string;
+    };
+    readonly location?: {
+        readonly longitude: number;
+        readonly latitude: number;
+    };
+}
+export interface TelegramCallbackQuery {
+    readonly id: string;
+    readonly from: TelegramUser;
+    readonly data?: string;
+    readonly message?: TelegramMessage;
+}
+export interface TelegramUpdate {
+    readonly update_id: number;
+    readonly message?: TelegramMessage;
+    readonly edited_message?: TelegramMessage;
+    readonly callback_query?: TelegramCallbackQuery;
+}
+export interface TelegramChatMember {
+    readonly status: string;
+    readonly user: TelegramUser;
+    readonly can_restrict_members?: boolean;
+    readonly can_pin_messages?: boolean;
+    readonly can_delete_messages?: boolean;
+    readonly can_manage_chat?: boolean;
+}
+export interface TelegramWireSegment {
+    readonly type: string;
+    readonly data?: Record<string, unknown>;
+}
+export interface TelegramInlineButton {
+    readonly text: string;
+    readonly callback_data: string;
+}
+export type TelegramOutboundAction = {
+    readonly method: 'sendMessage';
+    readonly params: {
+        readonly chat_id: number | string;
+        readonly text: string;
+        readonly parse_mode?: 'HTML';
+        readonly reply_parameters?: {
+            readonly message_id: number;
+        };
+        readonly reply_markup?: {
+            readonly inline_keyboard: TelegramInlineButton[][];
+        };
+    };
+} | {
+    readonly method: 'sendPhoto';
+    readonly params: {
+        readonly chat_id: number | string;
+        readonly photo: string;
+        readonly caption?: string;
+        readonly parse_mode?: 'HTML';
+        readonly reply_parameters?: {
+            readonly message_id: number;
+        };
+    };
+} | {
+    readonly method: 'sendVideo';
+    readonly params: {
+        readonly chat_id: number | string;
+        readonly video: string;
+        readonly caption?: string;
+        readonly parse_mode?: 'HTML';
+        readonly reply_parameters?: {
+            readonly message_id: number;
+        };
+    };
+} | {
+    readonly method: 'sendAudio';
+    readonly params: {
+        readonly chat_id: number | string;
+        readonly audio: string;
+        readonly caption?: string;
+        readonly parse_mode?: 'HTML';
+        readonly reply_parameters?: {
+            readonly message_id: number;
+        };
+    };
+} | {
+    readonly method: 'sendVoice';
+    readonly params: {
+        readonly chat_id: number | string;
+        readonly voice: string;
+        readonly caption?: string;
+        readonly parse_mode?: 'HTML';
+        readonly reply_parameters?: {
+            readonly message_id: number;
+        };
+    };
+} | {
+    readonly method: 'sendDocument';
+    readonly params: {
+        readonly chat_id: number | string;
+        readonly document: string;
+        readonly caption?: string;
+        readonly parse_mode?: 'HTML';
+        readonly reply_parameters?: {
+            readonly message_id: number;
+        };
+    };
+} | {
+    readonly method: 'sendSticker';
+    readonly params: {
+        readonly chat_id: number | string;
+        readonly sticker: string;
+        readonly reply_parameters?: {
+            readonly message_id: number;
+        };
+    };
+} | {
+    readonly method: 'sendLocation';
+    readonly params: {
+        readonly chat_id: number | string;
+        readonly latitude: number;
+        readonly longitude: number;
+        readonly reply_parameters?: {
+            readonly message_id: number;
+        };
+    };
+};
+export declare function resolveTelegramConfig(config?: TelegramAdapterConfig): 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;
+/**
+ * 入站归一化 → ConversationRef：Telegram 无 guild/群组容器层级，
+ * kind 直取 chat.type（private/group/supergroup/channel），无 parent。
+ */
+export declare function telegramInboundConversation(endpointKey: string, chat: Pick<TelegramChat, 'id' | 'type'>): ConversationRef;
+export declare function senderDisplayName(user?: TelegramUser): string;
+/** Build inbound text for OutboundMessageService.receive. */
+export declare function formatInboundContent(msg: TelegramMessage): string;
+export declare function formatCallbackContent(query: TelegramCallbackQuery): string;
+/**
+ * 入站消息 → canonical Segment[]；媒体只存在于 canonical 段，不重复写入文本。
+ * Telegram 附件只有不透明 file_id（需 getFile 二次解析，非 URL），
+ * 统一进 MediaRef kind=file；photo 取数组末尾（最大尺寸）。
+ */
+export declare function formatInboundSegments(msg: TelegramMessage): Segment[];
+/**
+ * callback_query → action 段（Wave 1 C interactive 约定：
+ * {type:'action', data:{id, payload, sourceMessageId?}}），
+ * 与 formatCallbackContent / metadata.payload 同源。
+ */
+export declare function formatCallbackSegments(query: TelegramCallbackQuery): Segment[];
+/**
+ * 出站待上传媒体（base64 / 本地路径 MediaRef 物化为 multipart 附件）。
+ * params 里以 `attach://<attachName>` 占位，endpoint 发送时替换为文件 part。
+ */
+export interface TelegramOutboundUpload {
+    readonly attachName: string;
+    readonly filename: string;
+    readonly source: {
+        readonly kind: 'base64';
+        readonly data: string;
+    } | {
+        readonly kind: 'path';
+        readonly path: string;
+    };
+    readonly mimeType?: string;
+}
+export interface TelegramOutboundPlan {
+    readonly actions: TelegramOutboundAction[];
+    readonly uploads: readonly TelegramOutboundUpload[];
+}
+/**
+ * Wire-encode an already-rendered outbound payload into Telegram Bot API actions.
+ * Segment canonicalization is intentionally not done here.
+ */
+export declare function formatOutboundActions(target: string | number, payload: unknown): TelegramOutboundAction[];
+/**
+ * formatOutboundActions 的上传感知变体：canonical MediaRef kind=base64/path
+ * 的媒体段产出 `attach://` 占位 + uploads 清单（endpoint 走 multipart 表单上传）；
+ * kind=url/file 保持字符串直发（file 即 Telegram file_id 不透明引用）。
+ */
+export declare function formatOutboundPlan(target: string | number, payload: unknown): TelegramOutboundPlan;