@zhin.js/adapter-telegram 1.1.17 → 1.1.19

package/lib/telegram-client.d.ts

@@ -0,0 +1,79 @@
+import { type ResolvedTelegramConfig, type TelegramChatMember } 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 TelegramClientApi {
+    callApi<T = unknown>(method: string, params?: Record<string, unknown>, signal?: AbortSignal): Promise<T>;
+    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(request: TelegramPollRequest): Promise<{
+        message_id: number;
+    }>;
+}
+export interface TelegramPollRequest {
+    readonly chatId: number;
+    readonly question: string;
+    readonly options: string[];
+    readonly isAnonymous?: boolean;
+    readonly allowsMultipleAnswers?: boolean;
+}
+interface TelegramDeadlineOperation<T> {
+    readonly method: string;
+    readonly run: (signal: AbortSignal) => Promise<T>;
+    readonly signal?: AbortSignal;
+    readonly timeoutMs?: number;
+}
+/** Owns Telegram Bot API transport, cancellation, deadlines and native API operations. */
+export declare class TelegramClient implements TelegramClientApi {
+    #private;
+    protected readonly fetchTransport: TelegramFetch;
+    protected requestSignal?: AbortSignal;
+    constructor(options: Readonly<{
+        config: ResolvedTelegramConfig;
+        fetch?: TelegramFetch;
+        requestTimeoutMs?: number;
+    }>);
+    protected restartRequests(): void;
+    protected cancelRequests(): 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>;
+    protected withRequestDeadline<T>({ method, run, signal, timeoutMs, }: TelegramDeadlineOperation<T>): 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, question, options, isAnonymous, allowsMultipleAnswers }: TelegramPollRequest): Promise<{
+        message_id: number;
+    }>;
+}
+export {};

package/lib/telegram-client.js

@@ -0,0 +1,159 @@
+import { botApiUrl } from './protocol.js';
+import { TelegramApiError } from './api-error.js';
+const DEFAULT_API_TIMEOUT_MS = 30_000;
+/** Owns Telegram Bot API transport, cancellation, deadlines and native API operations. */
+export class TelegramClient {
+    #options;
+    fetchTransport;
+    requestSignal;
+    #apiAbort = new AbortController();
+    constructor(options) {
+        if (options.requestTimeoutMs !== undefined && (!Number.isFinite(options.requestTimeoutMs) || options.requestTimeoutMs <= 0)) {
+            throw new TypeError('Telegram requestTimeoutMs must be a positive finite number');
+        }
+        this.#options = options;
+        this.fetchTransport = options.fetch ?? globalThis.fetch;
+    }
+    restartRequests() { if (this.#apiAbort.signal.aborted)
+        this.#apiAbort = new AbortController(); }
+    cancelRequests() { this.#apiAbort.abort(); }
+    async callApi(method, params = {}, signal) {
+        return this.#requestApi({ method, init: {
+                method: 'POST', headers: { 'Content-Type': 'application/json' }, body: JSON.stringify(params),
+            }, signal, timeoutMs: method === 'getUpdates'
+                ? Math.max(this.#options.requestTimeoutMs ?? DEFAULT_API_TIMEOUT_MS, (Number(params.timeout) || 0) * 1_000 + 15_000)
+                : undefined });
+    }
+    /** multipart/form-data 变体（attach:// 媒体上传；Content-Type 边界由 FormData 自带）。 */
+    async callApiForm(method, form, signal) {
+        return this.#requestApi({ method, init: { method: 'POST', body: form }, signal });
+    }
+    async #requestApi({ method, init, signal, timeoutMs }) {
+        return this.withRequestDeadline({ method, run: async (requestSignal) => {
+                const response = await this.fetchTransport(botApiUrl(this.#options.config, method), { ...init, signal: requestSignal });
+                return this.#parseApiResponse(method, response);
+            }, signal, timeoutMs });
+    }
+    async withRequestDeadline({ method, run, signal, timeoutMs = this.#options.requestTimeoutMs ?? DEFAULT_API_TIMEOUT_MS, }) {
+        const abort = new AbortController();
+        let issued = false;
+        const sources = [...new Set([signal, this.requestSignal, this.#apiAbort.signal].filter((item) => !!item))];
+        let rejectAbort;
+        const cancelled = new Promise((_resolve, reject) => { rejectAbort = reject; });
+        const onCancel = () => {
+            const error = new TelegramApiError('cancelled', `Telegram API ${method} cancelled`, {
+                disposition: issued ? 'unknown' : 'not_sent',
+            });
+            abort.abort(error);
+            rejectAbort(error);
+        };
+        const timer = setTimeout(() => {
+            const error = new TelegramApiError('timeout', `Telegram API ${method} timed out`);
+            abort.abort(error);
+            rejectAbort(error);
+        }, timeoutMs);
+        for (const source of sources)
+            source.addEventListener('abort', onCancel, { once: true });
+        try {
+            if (sources.some((source) => source.aborted))
+                onCancel();
+            const request = Promise.resolve().then(async () => {
+                abort.signal.throwIfAborted();
+                issued = true;
+                return run(abort.signal);
+            });
+            return await Promise.race([request, cancelled]);
+        }
+        catch (error) {
+            if (abort.signal.aborted)
+                throw abort.signal.reason;
+            if (error instanceof TelegramApiError)
+                throw error;
+            // Network exceptions can contain credential-bearing URLs. Keep those out of errors/logs.
+            const detail = error instanceof Error
+                ? error.message.replaceAll(this.#options.config.token, '[redacted]') : 'transport failure';
+            throw new TelegramApiError('network', `Telegram API ${method} network request failed: ${detail}`);
+        }
+        finally {
+            clearTimeout(timer);
+            for (const source of sources)
+                source.removeEventListener('abort', onCancel);
+        }
+    }
+    async #parseApiResponse(method, response) {
+        const text = await response.text();
+        let body;
+        try {
+            body = JSON.parse(text);
+        }
+        catch {
+            throw new TelegramApiError('invalid_response', `Telegram API ${method} invalid JSON (${response.status})`, { status: response.status });
+        }
+        if (!body || typeof body !== 'object' || typeof body.ok !== 'boolean') {
+            throw new TelegramApiError('invalid_response', `Telegram API ${method} invalid response envelope`, { status: response.status });
+        }
+        if (!body.ok || response.status < 200 || response.status >= 300) {
+            const status = !body.ok ? body.error_code ?? response.status : response.status;
+            const kind = status === 401 || status === 403 ? 'authentication'
+                : status === 429 ? 'rate_limit' : response.status >= 400 ? 'http' : 'api';
+            const description = !body.ok ? body.description?.replaceAll(this.#options.config.token, '[redacted]') : undefined;
+            throw new TelegramApiError(kind, `Telegram API ${method} failed (${status}): ${description ?? 'request rejected'}`, { status, disposition: !body.ok ? 'rejected' : 'unknown', ...(!body.ok && body.parameters?.retry_after != null
+                    ? { retryAfterSeconds: body.parameters.retry_after } : {}) });
+        }
+        if (!('result' in body))
+            throw new TelegramApiError('invalid_response', `Telegram API ${method} missing result`);
+        return body.result;
+    }
+    // ── Agent tool surface ──────────────────────────────────────────────
+    async pinMessage(chatId, messageId) {
+        await this.callApi('pinChatMessage', { chat_id: chatId, message_id: messageId });
+        return true;
+    }
+    async unpinMessage(chatId, messageId) {
+        if (messageId != null) {
+            await this.callApi('unpinChatMessage', { chat_id: chatId, message_id: messageId });
+        }
+        else {
+            await this.callApi('unpinAllChatMessages', { chat_id: chatId });
+        }
+        return true;
+    }
+    async setChatDescription(chatId, description) {
+        await this.callApi('setChatDescription', { chat_id: chatId, description });
+        return true;
+    }
+    async setMessageReaction(chatId, messageId, reaction) {
+        await this.callApi('setMessageReaction', {
+            chat_id: chatId,
+            message_id: messageId,
+            reaction: [{ type: 'emoji', emoji: reaction }],
+        });
+        return true;
+    }
+    async getChatMemberCount(chatId) {
+        return this.callApi('getChatMemberCount', { chat_id: chatId });
+    }
+    async getChatAdmins(chatId) {
+        return this.callApi('getChatAdministrators', { chat_id: chatId });
+    }
+    async sendStickerMessage(chatId, sticker) {
+        return this.callApi('sendSticker', { chat_id: chatId, sticker });
+    }
+    async setChatPermissionsAll(chatId, permissions) {
+        await this.callApi('setChatPermissions', { chat_id: chatId, permissions });
+        return true;
+    }
+    async createInviteLink(chatId) {
+        const link = await this.callApi('createChatInviteLink', { chat_id: chatId });
+        return link.invite_link;
+    }
+    async sendPoll({ chatId, question, options, isAnonymous = true, allowsMultipleAnswers = false }) {
+        return this.callApi('sendPoll', {
+            chat_id: chatId,
+            question,
+            options,
+            is_anonymous: isAnonymous,
+            allows_multiple_answers: allowsMultipleAnswers,
+        });
+    }
+}

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@zhin.js/adapter-telegram",
-  "version": "1.1.17",
+  "version": "1.1.19",
   "description": "Zhin.js Telegram Bot API adapter for Plugin Runtime (long-poll getUpdates)",
   "type": "module",
   "main": "./lib/index.js",
@@ -31,23 +31,26 @@
     "directory": "plugins/adapters/telegram"
   },
   "dependencies": {
-    "@zhin.js/adapter": "1.1.24",
-    "@zhin.js/agent-feature": "1.1.10",
-    "@zhin.js/core": "1.1.52",
-    "@zhin.js/feature-kit": "1.1.9",
-    "@zhin.js/host-http": "1.1.11",
-    "@zhin.js/im-contract": "1.1.8",
+    "@zhin.js/adapter": "1.1.26",
+    "@zhin.js/agent-feature": "1.1.11",
+    "@zhin.js/client": "1.1.22",
+    "@zhin.js/console-contract": "1.1.3",
+    "@zhin.js/core": "1.1.54",
+    "@zhin.js/feature-kit": "1.1.10",
+    "@zhin.js/host-http": "1.1.12",
+    "@zhin.js/im-contract": "1.1.9",
     "@zhin.js/logger": "1.1.2",
-    "@zhin.js/skill": "1.1.10",
-    "@zhin.js/tool": "1.1.11"
+    "@zhin.js/page": "1.1.11",
+    "@zhin.js/skill": "1.1.11",
+    "@zhin.js/tool": "1.1.13"
   },
   "peerDependencies": {
     "zod": "^4.0.0",
-    "@zhin.js/adapter": "^1.1.24",
-    "@zhin.js/command": "^1.1.11",
-    "@zhin.js/core": "^1.1.52",
-    "@zhin.js/permission": "^1.1.9",
-    "zhin.js": "^1.1.17"
+    "@zhin.js/adapter": "^1.1.26",
+    "@zhin.js/command": "^1.1.12",
+    "@zhin.js/core": "^1.1.54",
+    "@zhin.js/permission": "^1.1.10",
+    "zhin.js": "^1.1.19"
   },
   "peerDependenciesMeta": {
     "@zhin.js/command": {
@@ -65,12 +68,14 @@
     "typescript": "^6.0.3",
     "vitest": "^4.1.10",
     "zod": "^4.4.3",
-    "@zhin.js/host-http": "1.1.11",
-    "zhin.js": "1.1.17"
+    "@zhin.js/host-http": "1.1.12",
+    "@zhin.js/pagemanager": "1.1.18",
+    "zhin.js": "1.1.19"
   },
   "files": [
     "adapters",
     "commands",
+    "pages",
     "plugin.js",
     "schema.json",
     "src",
@@ -97,7 +102,7 @@
     "features": [
       {
         "package": "@zhin.js/adapter",
-        "api": "^1.0.0"
+        "api": "^2.0.0"
       },
       {
         "package": "@zhin.js/command",
@@ -114,6 +119,10 @@
       {
         "package": "@zhin.js/agent-feature",
         "api": "^1.0.0"
+      },
+      {
+        "package": "@zhin.js/page",
+        "api": "^1.0.0"
       }
     ],
     "plugins": []

package/pages/index/index.js

@@ -0,0 +1,15 @@
+// Generated by build-plugin-runtime-entries.mjs. Do not edit.
+import { definePage } from '@zhin.js/console-contract';
+import { createAdapterConsolePage } from '@zhin.js/client';
+export const meta = definePage({
+    title: 'Telegram',
+    titleI18n: { en: 'Telegram' },
+    icon: 'Send',
+    order: 74,
+    requiredPermissions: ['telegram:read'],
+});
+/**
+ * Convention page: `pages/index/index.ts` → `/telegram`（插件路径）。
+ * 连接状态、连接测试、endpoint 增删；登录待办来自 LoginAssist（ICQQ 等）。
+ */
+export default createAdapterConsolePage('telegram');

package/pages/index/index.ts

@@ -0,0 +1,16 @@
+import { definePage } from '@zhin.js/console-contract';
+import { createAdapterConsolePage } from '@zhin.js/client';
+
+export const meta = definePage({
+  title: 'Telegram',
+  titleI18n: { en: 'Telegram' },
+  icon: 'Send',
+  order: 74,
+  requiredPermissions: ['telegram:read'],
+});
+
+/**
+ * Convention page: `pages/index/index.ts` → `/telegram`（插件路径）。
+ * 连接状态、连接测试、endpoint 增删；登录待办来自 LoginAssist（ICQQ 等）。
+ */
+export default createAdapterConsolePage('telegram');

package/plugin.js

@@ -1,16 +1,15 @@
 // Generated by build-plugin-runtime-entries.mjs. Do not edit.
-import { createEndpointRuntimeState } from 'zhin.js/adapter';
-import { definePlugin } from 'zhin.js';
+import { definePlugin, pluginConsoleRpcToken } from 'zhin.js';
 import { permissionHostToken } from '@zhin.js/permission';
 import { checkTelegramPlatformPermit } from "./lib/platform-permit.js";
-import { telegramRuntimeStateToken } from "./lib/telegram-runtime-state.js";
+import { createTelegramConsoleRpc } from "./lib/console.js";
 export default definePlugin({
     name: 'telegram',
     metadata: {
         displayName: 'Telegram Bot API Adapter',
     },
     setup(context) {
-        context.resources.provide(telegramRuntimeStateToken, createEndpointRuntimeState());
+        context.resources.provide(pluginConsoleRpcToken, createTelegramConsoleRpc(() => context.config.get()));
         if (context.resources.has(permissionHostToken)) {
             const host = context.resources.use(permissionHostToken);
             return host.registerPlatform('telegram', checkTelegramPlatformPermit);

package/src/adapter.ts

@@ -0,0 +1,27 @@
+import { Adapter, type AdapterContext, type EndpointCreationContext } from 'zhin.js/adapter';
+import { httpHostToken } from '@zhin.js/host-http';
+import { TelegramEndpoint, type TelegramEndpointOptions } from './endpoint.js';
+import { TelegramClient } from './telegram-client.js';
+import { resolveTelegramConfig, type TelegramEndpointConfig } from './protocol.js';
+import type { TelegramClientEventMap } from './client.js';
+
+export class TelegramAdapter extends Adapter<TelegramEndpoint, TelegramEndpointConfig, TelegramClientEventMap> {
+  constructor(private readonly context: AdapterContext<TelegramEndpointConfig>,
+    private readonly transport: Pick<TelegramEndpointOptions, 'fetch' | 'requestTimeoutMs'> = {}) { super(); }
+  override get configurationIdentityFields(): readonly string[] { return ['id']; }
+  override get configurationIdentityProbeFields(): readonly string[] { return ['token', 'apiBaseUrl']; }
+  override get configurationUpdateFields(): readonly string[] { return ['token', 'polling', 'webhook',
+    'webhook.domain', 'webhook.path', 'webhook.secretToken', 'allowedUpdates', 'apiBaseUrl']; }
+  protected override validateConfiguration(config: TelegramEndpointConfig): void { resolveTelegramConfig(config); }
+  protected override async identifyConfiguration(input: TelegramEndpointConfig, signal: AbortSignal): Promise<string> {
+    const client = new TelegramClient({ config: resolveTelegramConfig(input), ...this.transport });
+    const me = await client.callApi<{ id?: number }>('getMe', {}, signal);
+    if (typeof me?.id !== 'number' || !Number.isFinite(me.id)) throw new Error('Telegram identity response is incomplete');
+    return JSON.stringify(['telegram', String(me.id)]);
+  }
+  protected createEndpoint(input: TelegramEndpointConfig, execution: EndpointCreationContext): TelegramEndpoint {
+    const config = resolveTelegramConfig(input);
+    return new TelegramEndpoint({ id: execution.canonicalId, config, ...this.transport,
+      ...(config.mode === 'webhook' ? { http: this.context.use(httpHostToken) } : {}) });
+  }
+}

package/src/client.ts

@@ -1,16 +1,8 @@
-import { defineEndpointClient } from 'zhin.js/adapter';
-import type { TelegramClient } from './endpoint.js';
+import type { TelegramAdapter } from './adapter.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;
-    };
-  }
+  interface AdapterRegistry { readonly telegram: TelegramAdapter; }
 }
-
-export const telegramClient = defineEndpointClient<TelegramClient, TelegramClientEventMap>('telegram');

package/src/console-spec.ts

@@ -0,0 +1,20 @@
+/**
+ * Telegram Console 页面元数据（浏览器与服务端共享；不要在这里 import 服务端代码）。
+ */
+import type { AdapterConsoleField } from 'zhin.js/adapter';
+
+export const telegramConsoleSpec = {
+  adapterKey: 'telegram',
+  adapterDisplayName: 'Telegram',
+  fields: [
+    { key: 'token', required: true, env: true, description: 'Telegram bot token' },
+    { key: 'apiBaseUrl', description: 'Telegram Bot API URL' },
+    { key: 'polling', type: 'boolean', description: 'Use long polling; false selects webhook mode' },
+    { key: 'webhook.domain', description: 'Public webhook origin' },
+    { key: 'webhook.path', description: 'Local webhook route' },
+    { key: 'webhook.secretToken', env: true, description: 'Webhook secret token' },
+  ] as readonly AdapterConsoleField[],
+  docsUrl: 'https://zhin.js.org/adapters/telegram',
+  readPermission: 'telegram:read',
+  writePermission: 'telegram:write',
+} as const;

package/src/console.ts

@@ -0,0 +1,17 @@
+/**
+ * Telegram Console RPC：运行状态 + endpoint 增删（原 `telegram endpoint` 聊天命令）。
+ *
+ * 页面绑定 `pages/index`，读取 / 写入分别要求 `<adapter>:read` / `<adapter>:write`。
+ */
+import { createAdapterConsoleRpc } from 'zhin.js/adapter';
+import type { PluginConsoleRpc } from 'zhin.js';
+import { telegramConsoleSpec } from './console-spec.js';
+
+export function createTelegramConsoleRpc(
+  getConfig: () => unknown,
+): PluginConsoleRpc {
+  return createAdapterConsoleRpc({
+    ...telegramConsoleSpec,
+    getConfig,
+  });
+}