@zhin.js/adapter-telegram 1.0.69 → 1.1.2

package/agents/telegram/skills/telegram-chat-admin/tools/unpin_message/index.js

@@ -0,0 +1,19 @@
+// Generated by build-plugin-runtime-entries.mjs. Do not edit.
+import { defineAgentTool } from '@zhin.js/tool';
+import { z } from 'zod';
+import { platformPermission } from '@zhin.js/permission';
+export default defineAgentTool({
+    description: '取消置顶 Telegram 群组消息',
+    inputSchema: z.object({
+        chat_id: z.string().describe('聊天 ID'),
+        message_id: z.string().optional().describe('消息 ID（可选，不提供则取消所有置顶）'),
+    }),
+    adapter: 'telegram',
+    tags: ['telegram'],
+    permissions: [platformPermission('telegram', 'pin_messages')],
+    async execute({ chat_id, message_id }, context) {
+        const endpoint = context.$client;
+        const success = await endpoint.unpinMessage(Number(chat_id), message_id ? Number(message_id) : undefined);
+        return { success, message: success ? '已取消置顶' : '操作失败' };
+    },
+});

package/agents/telegram/skills/telegram-chat-admin/tools/unpin_message/index.ts

@@ -0,0 +1,19 @@
+import { defineAgentTool } from '@zhin.js/tool';
+import { z } from 'zod';
+import { platformPermission } from '@zhin.js/permission';
+
+export default defineAgentTool<{ chat_id: string; message_id?: string }>({
+  description: '取消置顶 Telegram 群组消息',
+  inputSchema: z.object({
+    chat_id: z.string().describe('聊天 ID'),
+    message_id: z.string().optional().describe('消息 ID（可选，不提供则取消所有置顶）'),
+  }),
+  adapter: 'telegram',
+  tags: ['telegram'],
+  permissions: [platformPermission('telegram', 'pin_messages')],
+  async execute({ chat_id, message_id  }: { chat_id: string; message_id?: string }, context) {
+    const endpoint = context.$client;
+    const success = await endpoint.unpinMessage(Number(chat_id), message_id ? Number(message_id) : undefined);
+    return { success, message: success ? '已取消置顶' : '操作失败' };
+  },
+});

package/agents/telegram/skills/telegram-messages/SKILL.md

@@ -0,0 +1,19 @@
+---
+name: telegram-messages
+platforms:
+  - telegram
+description: Telegram 投票、reaction 和贴纸消息能力。
+keywords:
+  - "telegram"
+  - "poll"
+  - "reaction"
+  - "sticker"
+tools:
+  - "send_poll"
+  - "react"
+  - "send_sticker"
+---
+
+# telegram-messages
+
+用于消息互动。确认聊天和目标消息后调用，避免重复发送。

package/agents/telegram/skills/telegram-messages/tools/react/index.js

@@ -0,0 +1,18 @@
+// Generated by build-plugin-runtime-entries.mjs. Do not edit.
+import { defineAgentTool } from '@zhin.js/tool';
+import { z } from 'zod';
+export default defineAgentTool({
+    description: '对 Telegram 消息添加表情反应',
+    inputSchema: z.object({
+        chat_id: z.string().describe('聊天 ID'),
+        message_id: z.string().describe('消息 ID'),
+        reaction: z.string().describe('反应表情（如 👍、❤️、🔥）'),
+    }),
+    adapter: 'telegram',
+    tags: ['telegram'],
+    async execute({ chat_id, message_id, reaction }, context) {
+        const endpoint = context.$client;
+        const success = await endpoint.setMessageReaction(Number(chat_id), Number(message_id), reaction);
+        return { success, message: success ? `已添加反应 ${reaction}` : '操作失败' };
+    },
+});

package/agents/telegram/skills/telegram-messages/tools/react/index.ts

@@ -0,0 +1,18 @@
+import { defineAgentTool } from '@zhin.js/tool';
+import { z } from 'zod';
+
+export default defineAgentTool<{ chat_id: string; message_id: string; reaction: string }>({
+  description: '对 Telegram 消息添加表情反应',
+  inputSchema: z.object({
+    chat_id: z.string().describe('聊天 ID'),
+    message_id: z.string().describe('消息 ID'),
+    reaction: z.string().describe('反应表情（如 👍、❤️、🔥）'),
+  }),
+  adapter: 'telegram',
+  tags: ['telegram'],
+  async execute({ chat_id, message_id, reaction  }: { chat_id: string; message_id: string; reaction: string }, context) {
+    const endpoint = context.$client;
+    const success = await endpoint.setMessageReaction(Number(chat_id), Number(message_id), reaction);
+    return { success, message: success ? `已添加反应 ${reaction}` : '操作失败' };
+  },
+});

package/agents/telegram/skills/telegram-messages/tools/send_poll/index.js

@@ -0,0 +1,30 @@
+// Generated by build-plugin-runtime-entries.mjs. Do not edit.
+import { defineAgentTool } from '@zhin.js/tool';
+import { z } from 'zod';
+export default defineAgentTool({
+    description: '在 Telegram 群组中发起投票',
+    inputSchema: z.object({
+        chat_id: z.string().describe('聊天 ID'),
+        question: z.string().describe('投票问题'),
+        options: z.string().describe('选项 JSON 数组，如 ["A","B","C"]'),
+        is_anonymous: z.boolean().optional().describe('是否匿名投票，默认 true'),
+        allows_multiple: z.boolean().optional().describe('是否允许多选，默认 false'),
+    }),
+    adapter: 'telegram',
+    tags: ['telegram'],
+    async execute({ chat_id, question, options, is_anonymous, allows_multiple }, context) {
+        const endpoint = context.$client;
+        let optList;
+        try {
+            optList = JSON.parse(options);
+        }
+        catch {
+            return { success: false, message: 'options 格式错误，应为 JSON 数组' };
+        }
+        if (!Array.isArray(optList) || optList.length < 2) {
+            return { success: false, message: '至少需要 2 个选项' };
+        }
+        const result = await endpoint.sendPoll(Number(chat_id), question, optList, is_anonymous ?? true, allows_multiple ?? false);
+        return { success: true, message_id: result.message_id, message: '投票已发送' };
+    },
+});

package/agents/telegram/skills/telegram-messages/tools/send_poll/index.ts

@@ -0,0 +1,32 @@
+import { defineAgentTool } from '@zhin.js/tool';
+import { z } from 'zod';
+
+export default defineAgentTool<{ chat_id: string; question: string; options: string; is_anonymous?: boolean; allows_multiple?: boolean }>({
+  description: '在 Telegram 群组中发起投票',
+  inputSchema: z.object({
+    chat_id: z.string().describe('聊天 ID'),
+    question: z.string().describe('投票问题'),
+    options: z.string().describe('选项 JSON 数组，如 ["A","B","C"]'),
+    is_anonymous: z.boolean().optional().describe('是否匿名投票，默认 true'),
+    allows_multiple: z.boolean().optional().describe('是否允许多选，默认 false'),
+  }),
+  adapter: 'telegram',
+  tags: ['telegram'],
+  async execute({ chat_id, question, options, is_anonymous, allows_multiple  }: { chat_id: string; question: string; options: string; is_anonymous?: boolean; allows_multiple?: boolean }, context) {
+    const endpoint = context.$client;
+    let optList: string[];
+    try {
+      optList = JSON.parse(options);
+    } catch {
+      return { success: false, message: 'options 格式错误，应为 JSON 数组' };
+    }
+    if (!Array.isArray(optList) || optList.length < 2) {
+      return { success: false, message: '至少需要 2 个选项' };
+    }
+    const result = await endpoint.sendPoll(
+      Number(chat_id), question, optList,
+      is_anonymous ?? true, allows_multiple ?? false,
+    );
+    return { success: true, message_id: result.message_id, message: '投票已发送' };
+  },
+});

package/agents/telegram/skills/telegram-messages/tools/send_sticker/index.js

@@ -0,0 +1,17 @@
+// Generated by build-plugin-runtime-entries.mjs. Do not edit.
+import { defineAgentTool } from '@zhin.js/tool';
+import { z } from 'zod';
+export default defineAgentTool({
+    description: '发送 Telegram 贴纸',
+    inputSchema: z.object({
+        chat_id: z.string().describe('聊天 ID'),
+        sticker: z.string().describe('贴纸 file_id 或 URL'),
+    }),
+    adapter: 'telegram',
+    tags: ['telegram'],
+    async execute({ chat_id, sticker }, context) {
+        const endpoint = context.$client;
+        const result = await endpoint.sendStickerMessage(Number(chat_id), sticker);
+        return { success: true, message_id: result.message_id, message: '贴纸已发送' };
+    },
+});

package/agents/telegram/skills/telegram-messages/tools/send_sticker/index.ts

@@ -0,0 +1,17 @@
+import { defineAgentTool } from '@zhin.js/tool';
+import { z } from 'zod';
+
+export default defineAgentTool<{ chat_id: string; sticker: string }>({
+  description: '发送 Telegram 贴纸',
+  inputSchema: z.object({
+    chat_id: z.string().describe('聊天 ID'),
+    sticker: z.string().describe('贴纸 file_id 或 URL'),
+  }),
+  adapter: 'telegram',
+  tags: ['telegram'],
+  async execute({ chat_id, sticker  }: { chat_id: string; sticker: string }, context) {
+    const endpoint = context.$client;
+    const result = await endpoint.sendStickerMessage(Number(chat_id), sticker);
+    return { success: true, message_id: result.message_id, message: '贴纸已发送' };
+  },
+});

package/agents/telegram/system.md

@@ -0,0 +1,3 @@
+# TELEGRAM Platform Agent
+
+You are the telegram platform specialist. Interpret requests in the current telegram conversation and load only the narrowest private Skill needed for the task.

package/commands/telegram/endpoint/add/[id]/index.js

@@ -0,0 +1,3 @@
+// Generated by build-plugin-runtime-entries.mjs. Do not edit.
+import { telegramEndpointCommands } from '../../definition.js';
+export default telegramEndpointCommands.add;

package/commands/telegram/endpoint/add/[id]/index.ts

@@ -0,0 +1,3 @@
+import { telegramEndpointCommands } from '../../definition.js';
+
+export default telegramEndpointCommands.add;

package/commands/telegram/endpoint/definition.js

@@ -0,0 +1,17 @@
+// Generated by build-plugin-runtime-entries.mjs. Do not edit.
+/**
+ * `telegram endpoint` 命令族：由 @zhin.js/adapter 的 createEndpointCommands 套件生成。
+ * commands/telegram/endpoint/ 下的 list / add / remove 直接默认导出这三项。
+ */
+import { createEndpointCommands } from 'zhin.js/adapter';
+import { defineCommand } from 'zhin.js/command';
+import { telegramRuntimeStateToken } from "../../../lib/telegram-runtime-state.js";
+export const telegramEndpointCommands = createEndpointCommands({
+    adapterKey: 'telegram',
+    adapterDisplayName: 'Telegram',
+    fields: [
+        { key: 'token', required: true, env: true, description: 'Telegram bot token' },
+    ],
+    running: (use) => use(telegramRuntimeStateToken).endpoints.values(),
+    describeEntry: (entry) => `token: ${String(entry.token)}`,
+}, defineCommand);

package/commands/telegram/endpoint/definition.ts

@@ -0,0 +1,17 @@
+/**
+ * `telegram endpoint` 命令族：由 @zhin.js/adapter 的 createEndpointCommands 套件生成。
+ * commands/telegram/endpoint/ 下的 list / add / remove 直接默认导出这三项。
+ */
+import { createEndpointCommands } from 'zhin.js/adapter';
+import { defineCommand } from 'zhin.js/command';
+import { telegramRuntimeStateToken } from '../../../src/telegram-runtime-state.js';
+
+export const telegramEndpointCommands = createEndpointCommands({
+  adapterKey: 'telegram',
+  adapterDisplayName: 'Telegram',
+  fields: [
+    { key: 'token', required: true, env: true, description: 'Telegram bot token' },
+  ],
+  running: (use) => use(telegramRuntimeStateToken).endpoints.values(),
+  describeEntry: (entry) => `token: ${String(entry.token)}`,
+}, defineCommand);

package/commands/telegram/endpoint/list/index.js

@@ -0,0 +1,3 @@
+// Generated by build-plugin-runtime-entries.mjs. Do not edit.
+import { telegramEndpointCommands } from '../definition.js';
+export default telegramEndpointCommands.list;

package/commands/telegram/endpoint/list/index.ts

@@ -0,0 +1,3 @@
+import { telegramEndpointCommands } from '../definition.js';
+
+export default telegramEndpointCommands.list;

package/commands/telegram/endpoint/remove/[id]/index.js

@@ -0,0 +1,3 @@
+// Generated by build-plugin-runtime-entries.mjs. Do not edit.
+import { telegramEndpointCommands } from '../../definition.js';
+export default telegramEndpointCommands.remove;

package/commands/telegram/endpoint/remove/[id]/index.ts

@@ -0,0 +1,3 @@
+import { telegramEndpointCommands } from '../../definition.js';
+
+export default telegramEndpointCommands.remove;

package/lib/client.d.ts

@@ -0,0 +1,12 @@
+import type { TelegramClient } from './endpoint.js';
+import type { TelegramUpdate } from './protocol.js';
+export type TelegramClientEventMap = Record<string, TelegramUpdate>;
+declare module '@zhin.js/feature-kit' {
+    interface AdapterClientRegistry {
+        readonly telegram: {
+            readonly client: TelegramClient;
+            readonly events: TelegramClientEventMap;
+        };
+    }
+}
+export declare const telegramClient: import("@zhin.js/adapter").EndpointClientToken<TelegramClient, TelegramClientEventMap>;

package/lib/client.js

@@ -0,0 +1,2 @@
+import { defineEndpointClient } from 'zhin.js/adapter';
+export const telegramClient = defineEndpointClient('telegram');

package/lib/endpoint.d.ts

@@ -0,0 +1,112 @@
+import { Endpoint, type EndpointContentPort, type EndpointControl, type EndpointSendRequest } from 'zhin.js/adapter';
+import type { HttpHost } from '@zhin.js/host-http';
+import { type MessageRef } from '@zhin.js/im-contract';
+import type { CapabilityId } from 'zhin.js';
+import { type ResolvedTelegramConfig, type TelegramCallbackQuery, type TelegramChatMember, type TelegramMessage, type TelegramUpdate } from './protocol.js';
+export type TelegramFetch = (url: string, init?: {
+    readonly method?: string;
+    readonly headers?: Record<string, string>;
+    readonly body?: string | FormData;
+    readonly signal?: AbortSignal;
+}) => Promise<{
+    readonly ok: boolean;
+    readonly status: number;
+    text(): Promise<string>;
+    json(): Promise<unknown>;
+    arrayBuffer?(): Promise<ArrayBuffer>;
+    readonly headers?: {
+        get(name: string): string | null;
+    };
+}>;
+export interface TelegramEndpointOptions {
+    readonly id: CapabilityId;
+    readonly config: ResolvedTelegramConfig;
+    readonly http?: HttpHost;
+    readonly fetch?: TelegramFetch;
+}
+export interface TelegramClientApi {
+    callApi<T = unknown>(method: string, params?: Record<string, unknown>): Promise<T>;
+    callApiForm<T = unknown>(method: string, form: FormData): Promise<T>;
+    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;
+    }>;
+}
+/** Telegram Bot API client carried by message, update and lifecycle events. */
+export declare class TelegramClient implements TelegramClientApi {
+    readonly api: TelegramClientApi;
+    constructor(api: TelegramClientApi);
+    callApi: <T = unknown>(method: string, params?: Record<string, unknown>) => Promise<T>;
+    callApiForm: <T = unknown>(method: string, form: FormData) => Promise<T>;
+    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[], anonymous?: boolean, multiple?: boolean) => Promise<{
+        message_id: number;
+    }>;
+}
+/**
+ * Telegram Bot API 无列表类接口（无 getMyChats/getChatMembers），
+ * 仅 getChat/getChatMember 按已知 id 单查，不构成列表能力；
+ * 因此本 endpoint 不暴露 EndpointManagement（Console 社交面 RPC 对该平台保持未接线）。
+ */
+export declare class TelegramEndpoint extends Endpoint<TelegramClient> {
+    #private;
+    readonly client: TelegramClient;
+    readonly control: EndpointControl;
+    readonly content: EndpointContentPort;
+    constructor(options: TelegramEndpointOptions);
+    /** Used by webhook handler. */
+    get isOpen(): boolean;
+    get config(): ResolvedTelegramConfig;
+    get allowedUpdates(): readonly string[];
+    getUpdateOffset(): number;
+    setUpdateOffset(offset: number): void;
+    start(): Promise<void>;
+    open(): void;
+    close(): void;
+    stop(): Promise<void>;
+    send({ conversation, payload }: EndpointSendRequest): Promise<string>;
+    recallMessage(message: MessageRef): Promise<void>;
+    /** Test / internal: admit a message when open. */
+    admit(msg: TelegramMessage): void;
+    /** Test / internal: admit a callback query when open. */
+    admitCallback(query: TelegramCallbackQuery): void;
+    /** Used by webhook / polling handlers. */
+    handleUpdate(update: TelegramUpdate): void;
+    callApi<T = unknown>(method: string, params?: Record<string, unknown>, signal?: AbortSignal): Promise<T>;
+    /** multipart/form-data 变体（attach:// 媒体上传；Content-Type 边界由 FormData 自带）。 */
+    callApiForm<T = unknown>(method: string, form: FormData, signal?: AbortSignal): Promise<T>;
+    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;
+    }>;
+}