@zhin.js/adapter-telegram 1.1.20 → 1.1.22

package/lib/self-profile.js

@@ -0,0 +1,61 @@
+import { TelegramApiError } from './api-error.js';
+/** Bot API names/descriptions are account fields, not the title/description of a chat. */
+export function createTelegramSelfProfile({ client, current, nicknameChanged }) {
+    return Object.freeze({
+        writableFields: Object.freeze(['nickname', 'signature', 'bio', 'avatar']),
+        get current() { return current(); },
+        async read({ signal }) {
+            const [name, description, shortDescription] = await Promise.all([
+                client.callApi('getMyName', {}, signal),
+                client.callApi('getMyDescription', {}, signal),
+                client.callApi('getMyShortDescription', {}, signal),
+            ]);
+            if (typeof name.name !== 'string' || typeof description.description !== 'string' || typeof shortDescription.short_description !== 'string') {
+                throw new Error('Telegram returned an incomplete bot profile');
+            }
+            return { nickname: name.name, signature: shortDescription.short_description, bio: description.description };
+        },
+        async write({ change, signal }) {
+            try {
+                if (change.field === 'avatar') {
+                    if (change.value.kind !== 'base64' || change.value.mime_type !== 'image/jpeg') {
+                        return { status: 'rejected', message: 'Telegram profile photos require resolved JPEG image bytes' };
+                    }
+                    const form = new FormData();
+                    form.set('photo', JSON.stringify({ type: 'static', photo: 'attach://avatar' }));
+                    form.set('avatar', new Blob([Uint8Array.from(Buffer.from(change.value.value, 'base64'))], { type: 'image/jpeg' }), 'avatar.jpg');
+                    const accepted = await client.callApiForm('setMyProfilePhoto', form, signal);
+                    return accepted === true ? { status: 'updated' } : { status: 'rejected', message: 'Telegram rejected the avatar change' };
+                }
+                let method;
+                let params;
+                switch (change.field) {
+                    case 'nickname':
+                        method = 'setMyName';
+                        params = { name: change.value };
+                        break;
+                    case 'signature':
+                        method = 'setMyShortDescription';
+                        params = { short_description: change.value };
+                        break;
+                    case 'bio':
+                        method = 'setMyDescription';
+                        params = { description: change.value };
+                        break;
+                    default: return { status: 'rejected', message: `Telegram bot profile does not expose ${change.field} through this port` };
+                }
+                const accepted = await client.callApi(method, params, signal);
+                if (accepted !== true)
+                    return { status: 'rejected', message: `Telegram rejected the ${change.field} change` };
+                if (change.field === 'nickname')
+                    nicknameChanged(change.value);
+                return { status: 'updated', profile: { [change.field]: change.value } };
+            }
+            catch (error) {
+                if (!(error instanceof TelegramApiError) || error.disposition === 'not_sent')
+                    throw error;
+                return { status: error.disposition === 'rejected' ? 'rejected' : 'unknown', message: error.message };
+            }
+        },
+    });
+}

package/lib/stream-markdown.d.ts

@@ -0,0 +1,6 @@
+/** Render a physical slice while retaining the original Markdown's source coordinates. */
+export declare function sliceTelegramMarkdown(text: string, precedingText: string, capacity: number): {
+    readonly html: string;
+    readonly acceptedText: string;
+    readonly exhausted: boolean;
+};

package/lib/stream-markdown.js

@@ -0,0 +1,66 @@
+import { EndpointDeliveryError } from '@zhin.js/im-contract';
+import { projectTelegramMarkdown } from './markdown-to-html.js';
+/** Render a physical slice while retaining the original Markdown's source coordinates. */
+export function sliceTelegramMarkdown(text, precedingText, capacity) {
+    const full = precedingText + text;
+    const projection = projectTelegramMarkdown(full);
+    const units = [];
+    const tags = [];
+    const trimStart = projection.html.length - projection.html.trimStart().length;
+    const trimEnd = projection.html.trimEnd().length;
+    const html = projection.html.slice(trimStart, trimEnd);
+    const matcher = /<\/?[a-z][^>]*>|&(?:amp|lt|gt|quot);|[\s\S]/gu;
+    for (const match of html.matchAll(matcher)) {
+        const raw = match[0];
+        if (raw.startsWith('<')) {
+            const tag = /^<(\/?)([a-z]+)/.exec(raw);
+            if (tag[1]) {
+                if (tags.at(-1)?.name !== tag[2])
+                    throw unsupportedProjection();
+                tags.pop();
+            }
+            else
+                tags.push({ name: tag[2], html: raw });
+            continue;
+        }
+        const origins = projection.source.slice(trimStart + match.index, trimStart + match.index + raw.length).filter(position => position >= 0);
+        if (!origins.length)
+            throw unsupportedProjection();
+        const sourceStart = Math.min(...origins), sourceEnd = Math.max(...origins) + 1;
+        if (sourceEnd > precedingText.length)
+            units.push({ html: raw, sourceStart, sourceEnd, tags: [...tags] });
+    }
+    if (tags.length)
+        throw unsupportedProjection();
+    if (!units.length)
+        return { html: '', acceptedText: text, exhausted: false };
+    // One decoded code point is one unit. Keep replacement expansions together
+    // when their source positions coincide (for example a Markdown bullet).
+    let take = Math.min(capacity, units.length);
+    while (take > 0 && take < units.length && units[take].sourceStart < units[take - 1].sourceEnd)
+        take--;
+    if (take <= 0)
+        throw new EndpointDeliveryError('stream_capacity', 'Telegram prefix leaves no room for a Markdown unit', 'not_sent');
+    const end = take < units.length ? units[take].sourceStart : full.length;
+    if (end <= precedingText.length)
+        throw unsupportedProjection();
+    let rendered = '';
+    let active = [];
+    for (const unit of units.slice(0, take)) {
+        let common = 0;
+        while (common < active.length && common < unit.tags.length && active[common].html === unit.tags[common].html)
+            common++;
+        for (let index = active.length - 1; index >= common; index--)
+            rendered += `</${active[index].name}>`;
+        for (const tag of unit.tags.slice(common))
+            rendered += tag.html;
+        rendered += unit.html;
+        active = unit.tags;
+    }
+    for (let index = active.length - 1; index >= 0; index--)
+        rendered += `</${active[index].name}>`;
+    return { html: rendered, acceptedText: text.slice(0, end - precedingText.length), exhausted: take < units.length || take === capacity };
+}
+function unsupportedProjection() {
+    return new EndpointDeliveryError('unsupported_operation', 'Telegram Markdown projection has no safe source mapping', 'not_sent');
+}

package/lib/streaming.d.ts

@@ -0,0 +1,4 @@
+import type { EndpointStreaming } from 'zhin.js/adapter';
+import type { TelegramClientApi } from './telegram-client.js';
+/** Drafts are previews; only finish performs a persistent send. */
+export declare function createTelegramStreaming(getClient: () => Pick<TelegramClientApi, 'callApi'>, minIntervalMs?: number): EndpointStreaming;

package/lib/streaming.js

@@ -0,0 +1,118 @@
+import { randomInt } from 'node:crypto';
+import { EndpointDeliveryError } from '@zhin.js/im-contract';
+import { formatOutboundPlan } from './protocol.js';
+import { escapeTelegramHtml } from './markdown-to-html.js';
+import { sliceTelegramMarkdown } from './stream-markdown.js';
+function supportsTelegramStream(request) {
+    return request.conversation.kind === 'private' && !request.conversation.parent;
+}
+/** Drafts are previews; only finish performs a persistent send. */
+export function createTelegramStreaming(getClient, minIntervalMs = 500) {
+    return {
+        mode: 'draft',
+        minIntervalMs,
+        supports: supportsTelegramStream,
+        open(request) {
+            if (!supportsTelegramStream(request))
+                return undefined;
+            if (request.prefix?.some(segment => segment.type !== 'reply' && segment.type !== 'mention'))
+                return undefined;
+            const prefix = (request.prefix ?? []).map(segment => segment.type === 'mention'
+                ? { type: 'at', data: { id: 'target' in segment.data ? segment.data.target : undefined,
+                        name: 'name' in segment.data ? segment.data.name : undefined } }
+                : { type: segment.type, data: { ...segment.data } });
+            const draftId = randomInt(1, 2_147_483_647);
+            const cancellation = new AbortController();
+            const signal = request.signal ? AbortSignal.any([request.signal, cancellation.signal]) : cancellation.signal;
+            const threadId = request.conversation.threadId === undefined ? undefined : Number(request.conversation.threadId);
+            if (threadId !== undefined && (!Number.isSafeInteger(threadId) || threadId <= 0)) {
+                throw new EndpointDeliveryError('invalid_payload', 'Telegram topic id must be a positive integer', 'not_sent');
+            }
+            let acceptedText = '';
+            let messageId;
+            let exhausted = false;
+            let contentUnavailable = false;
+            let confirmed;
+            let failure;
+            let completion;
+            const acknowledgement = () => ({
+                status: messageId ? 'sent' : acceptedText ? 'preview' : 'buffered', acceptedText,
+                ...(messageId ? { messageId } : {}),
+                ...(exhausted ? { exhausted: true } : {}),
+                ...(contentUnavailable ? { contentUnavailable: true } : {}),
+            });
+            const prepare = (text) => {
+                const mentionText = prefix.map(segment => segment.type === 'at' && segment.data?.id
+                    ? `@${segment.data.name || segment.data.id}` : '').join('');
+                const mentionLength = Array.from(mentionText).length;
+                const capacity = 4096 - mentionLength;
+                if (capacity <= 0)
+                    throw new EndpointDeliveryError('stream_capacity', 'Telegram prefix exceeds its text container', 'not_sent');
+                const markdown = request.format === 'markdown'
+                    ? sliceTelegramMarkdown(text, request.continuation?.precedingText ?? '', capacity) : undefined;
+                const source = markdown?.acceptedText ?? Array.from(text).slice(0, capacity).join('');
+                const plan = formatOutboundPlan(request.conversation.id, [...prefix, request.format === 'markdown'
+                        ? { type: 'markdown', data: { content: source } }
+                        : { type: 'text', data: { text: source } }]);
+                const action = plan.actions[0];
+                if (plan.actions.length !== 1 || action?.method !== 'sendMessage') {
+                    throw new EndpointDeliveryError('unsupported_operation', 'Telegram draft requires one text container', 'not_sent');
+                }
+                const params = { ...action.params,
+                    ...(markdown ? { text: escapeTelegramHtml(mentionText) + markdown.html } : {}),
+                    ...(threadId !== undefined ? { message_thread_id: threadId } : {}) };
+                return { source, params, exhausted: markdown?.exhausted ?? (source.length < text.length || Array.from(params.text).length === 4096) };
+            };
+            const send = async (text, final) => {
+                if (failure)
+                    throw failure;
+                if (signal.aborted)
+                    throw new EndpointDeliveryError('endpoint_inactive', 'Telegram draft cancelled', 'not_sent');
+                if (!text.startsWith(acceptedText))
+                    throw new EndpointDeliveryError('invalid_payload', 'Telegram draft cannot replace its accepted source prefix', 'not_sent');
+                if (!text.trim() || (!final && text === acceptedText))
+                    return acknowledgement();
+                const next = final && text === acceptedText && confirmed ? confirmed : prepare(text);
+                const { source, params } = next;
+                if (!final && source === acceptedText)
+                    return acknowledgement();
+                if (!params.text)
+                    return acknowledgement();
+                try {
+                    if (final) {
+                        const result = await getClient().callApi('sendMessage', params, signal);
+                        if (!Number.isSafeInteger(result?.message_id) || result.message_id <= 0) {
+                            throw new EndpointDeliveryError('delivery_unconfirmed', 'Telegram final send returned no valid message_id', 'unknown');
+                        }
+                        messageId = String(result.message_id);
+                    }
+                    else {
+                        const { reply_parameters: _reply, ...draftParams } = params;
+                        const result = await getClient().callApi('sendMessageDraft', { ...draftParams, draft_id: draftId }, signal);
+                        if (result !== true)
+                            throw new EndpointDeliveryError('delivery_unconfirmed', 'Telegram draft response is unconfirmed', 'unknown');
+                    }
+                    acceptedText = source;
+                    // A temporary Markdown preview can still reinterpret an unfinished fence/link.
+                    // Rollover persists this container, so only the final source may trigger it.
+                    exhausted = next.exhausted && (final || request.format !== 'markdown');
+                    contentUnavailable = request.format === 'markdown'
+                        && (Boolean(request.continuation?.precedingText) || exhausted || source.length < text.length);
+                    confirmed = next;
+                    return acknowledgement();
+                }
+                catch (error) {
+                    failure = error;
+                    throw error;
+                }
+            };
+            return {
+                write: text => completion
+                    ? Promise.reject(new EndpointDeliveryError('stream_closed', 'Telegram draft is finishing', 'not_sent'))
+                    : send(text, false),
+                finish: text => completion ??= send(text, true),
+                cancel: () => { cancellation.abort(); },
+            };
+        },
+    };
+}

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@zhin.js/adapter-telegram",
-  "version": "1.1.20",
+  "version": "1.1.22",
   "description": "Zhin.js Telegram Bot API adapter for Plugin Runtime (long-poll getUpdates)",
   "type": "module",
   "main": "./lib/index.js",
@@ -31,26 +31,26 @@
     "directory": "plugins/adapters/telegram"
   },
   "dependencies": {
-    "@zhin.js/adapter": "1.1.26",
-    "@zhin.js/agent-feature": "1.1.11",
-    "@zhin.js/client": "1.1.22",
+    "@zhin.js/adapter": "1.1.28",
+    "@zhin.js/agent-feature": "1.1.13",
+    "@zhin.js/client": "1.1.24",
     "@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/core": "1.1.56",
+    "@zhin.js/feature-kit": "1.1.12",
+    "@zhin.js/host-http": "1.1.14",
+    "@zhin.js/im-contract": "1.1.11",
     "@zhin.js/logger": "1.1.2",
-    "@zhin.js/page": "1.1.12",
-    "@zhin.js/skill": "1.1.11",
-    "@zhin.js/tool": "1.1.13"
+    "@zhin.js/page": "1.1.14",
+    "@zhin.js/skill": "1.1.13",
+    "@zhin.js/tool": "1.1.15"
   },
   "peerDependencies": {
     "zod": "^4.0.0",
-    "@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"
+    "@zhin.js/adapter": "^1.1.28",
+    "@zhin.js/command": "^1.1.14",
+    "@zhin.js/core": "^1.1.56",
+    "@zhin.js/permission": "^1.1.12",
+    "zhin.js": "^1.1.21"
   },
   "peerDependenciesMeta": {
     "@zhin.js/command": {
@@ -65,12 +65,13 @@
   },
   "devDependencies": {
     "@types/node": "^26.1.2",
+    "htmlparser2": "12.0.0",
     "typescript": "^6.0.3",
     "vitest": "^4.1.10",
     "zod": "^4.4.3",
-    "@zhin.js/host-http": "1.1.12",
-    "@zhin.js/pagemanager": "1.1.19",
-    "zhin.js": "1.1.19"
+    "@zhin.js/host-http": "1.1.14",
+    "@zhin.js/pagemanager": "1.1.21",
+    "zhin.js": "1.1.21"
   },
   "files": [
     "adapters",
@@ -102,7 +103,7 @@
     "features": [
       {
         "package": "@zhin.js/adapter",
-        "api": "^2.0.0"
+        "api": "^2.1.0"
       },
       {
         "package": "@zhin.js/command",
@@ -110,7 +111,7 @@
       },
       {
         "package": "@zhin.js/tool",
-        "api": "^1.0.0"
+        "api": "^1.1.0"
       },
       {
         "package": "@zhin.js/skill",

package/plugin.js

@@ -5,6 +5,7 @@ import { checkTelegramPlatformPermit } from "./lib/platform-permit.js";
 import { createTelegramConsoleRpc } from "./lib/console.js";
 export default definePlugin({
     name: 'telegram',
+    configUpdate: { featurePaths: [['nickname'], ['profile'], ['endpoints']] },
     metadata: {
         displayName: 'Telegram Bot API Adapter',
     },

package/schema.json

@@ -141,6 +141,36 @@
           "id": {
             "type": "string",
             "description": "Telegram bot name"
+          },
+          "streaming": {
+            "type": "boolean",
+            "description": "Publish supported replies while generating. Set false to send only complete replies."
+          },
+          "streamingIntervalMs": {
+            "type": "number",
+            "minimum": 0,
+            "description": "Minimum delay in milliseconds between reply updates; the first update is immediate."
+          },
+          "nickname": {
+            "type": [
+              "string",
+              "null"
+            ],
+            "description": "账号昵称兜底",
+            "x-i18n": {
+              "en": {
+                "description": "Fallback account nickname"
+              }
+            }
+          },
+          "profile": {
+            "$ref": "#/$defs/selfProfileFallback",
+            "description": "账号资料兜底",
+            "x-i18n": {
+              "en": {
+                "description": "Fallback account profile"
+              }
+            }
           }
         },
         "required": [
@@ -163,9 +193,104 @@
           "description": "Command prefix. The default empty string allows unprefixed commands; '/' requires a leading slash. Each endpoints[i] can override it."
         }
       }
+    },
+    "streaming": {
+      "type": "boolean",
+      "default": true,
+      "description": "Publish supported replies while generating. Set false to send only complete replies."
+    },
+    "streamingIntervalMs": {
+      "type": "number",
+      "minimum": 0,
+      "default": 500,
+      "description": "Minimum delay in milliseconds between reply updates; the first update is immediate."
+    },
+    "nickname": {
+      "type": [
+        "string",
+        "null"
+      ],
+      "description": "账号昵称兜底",
+      "x-i18n": {
+        "en": {
+          "description": "Fallback account nickname"
+        }
+      }
+    },
+    "profile": {
+      "$ref": "#/$defs/selfProfileFallback",
+      "description": "账号资料兜底",
+      "x-i18n": {
+        "en": {
+          "description": "Fallback account profile"
+        }
+      }
     }
   },
   "required": [
     "endpoints"
-  ]
+  ],
+  "$defs": {
+    "selfProfileFallback": {
+      "type": "object",
+      "additionalProperties": false,
+      "properties": {
+        "gender": {
+          "type": [
+            "string",
+            "null"
+          ],
+          "enum": [
+            "male",
+            "female",
+            "other",
+            "unknown",
+            null
+          ]
+        },
+        "age": {
+          "type": [
+            "integer",
+            "null"
+          ],
+          "minimum": 0
+        },
+        "birthday": {
+          "type": [
+            "string",
+            "null"
+          ],
+          "pattern": "^\\d{4}-(0[1-9]|1[0-2])-(0[1-9]|[12]\\d|3[01])$"
+        },
+        "signature": {
+          "type": [
+            "string",
+            "null"
+          ]
+        },
+        "avatar": {
+          "type": [
+            "string",
+            "null"
+          ],
+          "pattern": "^(https?://[^\\s/?#]+(?:[/?#].*)?|)$"
+        },
+        "interests": {
+          "type": [
+            "array",
+            "null"
+          ],
+          "items": {
+            "type": "string"
+          }
+        },
+        "bio": {
+          "type": [
+            "string",
+            "null"
+          ]
+        }
+      }
+    }
+  }
 }

package/src/adapter.ts

@@ -10,7 +10,7 @@ export class TelegramAdapter extends Adapter<TelegramEndpoint, TelegramEndpointC
     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',
+  override get configurationUpdateFields(): readonly string[] { return ['token', 'polling', 'streaming', 'streamingIntervalMs', '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> {

package/src/console-spec.ts

@@ -10,6 +10,8 @@ export const telegramConsoleSpec = {
     { 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: 'streaming', type: 'boolean', description: 'Show private-chat drafts while generating (default true)' },
+    { key: 'streamingIntervalMs', type: 'number', description: 'Delay between draft updates in milliseconds (default 500)' },
     { key: 'webhook.domain', description: 'Public webhook origin' },
     { key: 'webhook.path', description: 'Local webhook route' },
     { key: 'webhook.secretToken', env: true, description: 'Webhook secret token' },

package/src/endpoint.ts

@@ -1,4 +1,5 @@
 import { TelegramClient, type TelegramFetch } from './telegram-client.js';
+import { createTelegramStreaming } from './streaming.js';
 import {
   createEndpointSpecification, endpointSpec, type Endpoint, type EndpointSpecification, createEndpointLifecycle,
   type EndpointLifecycle, type EndpointContentPort, type EndpointContentResolveContext,
@@ -40,6 +41,7 @@ import {
   type TelegramUpdate,
 } from './protocol.js';
 import { registerTelegramWebhookRoutes } from './webhook.js';
+import { createTelegramSelfProfile } from './self-profile.js';
 
 const CHAT_MEMBER_CACHE_TTL_MS = 60_000;
 const CHAT_MEMBER_CACHE_MAX = 2_000;
@@ -93,6 +95,7 @@ export class TelegramEndpoint extends TelegramClient implements Endpoint {
   readonly #inflightUpdates = new Map<number, Promise<void>>();
   #botUserId?: number;
   #botUsername?: string;
+  #botName?: string;
   readonly #chatMemberCache = new Map<string, ChatMemberPermit>();
   readonly #control: EndpointControl = Object.freeze<EndpointControl>({
     recall: ({ message, signal }) => this.recallMessage(message, signal),
@@ -112,6 +115,11 @@ export class TelegramEndpoint extends TelegramClient implements Endpoint {
       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,
+      streaming: options.config.streaming !== false ? createTelegramStreaming(() => this, options.config.streamingIntervalMs) : undefined,
+      profile: createTelegramSelfProfile({ client: this,
+        current: () => this.#botName === undefined ? {} : { nickname: this.#botName },
+        nicknameChanged: nickname => { this.#botName = nickname; },
+      }),
     });
   }
 
@@ -168,6 +176,8 @@ export class TelegramEndpoint extends TelegramClient implements Endpoint {
         if (abort.signal.aborted) return;
         this.#botUserId = me.id;
         this.#botUsername = me.username;
+        this.#botName = me.first_name;
+        if (me.id) this[endpointSpec].reportSelfUserId(String(me.id));
 
         if (this.#options.config.mode === 'webhook') {
           if (!this.#options.http) {