@zhin.js/adapter-telegram 1.1.4 → 1.1.5

package/lib/protocol.js

@@ -2,7 +2,7 @@
  * Telegram Bot API protocol helpers — no legacy Adapter/Endpoint / segment-mapper.
  * Canonicalization is owned by gateway/core before endpoint.send.
  */
-import { isMediaRef } from '@zhin.js/im-contract';
+import { EndpointDeliveryError, isMediaRef } from '@zhin.js/im-contract';
 import { formatCompact, getLogger } from '@zhin.js/logger';
 import { escapeTelegramHtml, markdownToTelegramHtml } from './markdown-to-html.js';
 const logger = getLogger('telegram');
@@ -219,7 +219,7 @@ function buildOutboundActions(target, payload, uploads) {
         : payload && typeof payload === 'object' && 'type' in payload
             ? [payload]
             : [];
-    const hasMarkdown = items.some((item) => typeof item !== 'string' && item.type === 'markdown');
+    const hasMarkdown = items.some((item) => typeof item !== 'string' && ['markdown', 'share'].includes(item.type));
     const appendPlain = (value) => hasMarkdown
         ? escapeTelegramHtml(String(value ?? ''))
         : String(value ?? '');
@@ -295,6 +295,24 @@ function buildOutboundActions(target, payload, uploads) {
             case 'markdown':
                 textContent += markdownToTelegramHtml(String(data.content ?? data.text ?? ''));
                 break;
+            case 'share': {
+                let url;
+                try {
+                    url = new URL(String(data.url ?? ''));
+                }
+                catch {
+                    throw new EndpointDeliveryError('invalid_payload', 'Telegram share requires an HTTP(S) URL', 'not_sent');
+                }
+                if (!['http:', 'https:'].includes(url.protocol) || typeof data.title !== 'string' || !data.title.trim())
+                    throw new EndpointDeliveryError('invalid_payload', 'Telegram share requires an HTTP(S) URL and title', 'not_sent');
+                if (['image', 'audio', 'artist', 'duration', 'config'].some(key => data[key] !== undefined))
+                    throw new EndpointDeliveryError('unsupported_operation', 'Telegram share media and app metadata are not implemented', 'not_sent');
+                textContent += `<a href="${escapeTelegramHtml(url.href)}">${escapeTelegramHtml(data.title)}</a>`;
+                for (const value of [data.description, data.content])
+                    if (typeof value === 'string' && value)
+                        textContent += `\n${escapeTelegramHtml(value)}`;
+                break;
+            }
             case 'at':
                 if (data.id)
                     textContent += `@${appendPlain(data.name || data.id)}`;
@@ -307,15 +325,23 @@ function buildOutboundActions(target, payload, uploads) {
             }
             case 'keyboard': {
                 const rows = Array.isArray(data.rows) ? data.rows : [];
+                if (!rows.length || rows.some(row => !Array.isArray(row) || !row.length))
+                    throw new EndpointDeliveryError('invalid_payload', 'Telegram keyboard requires nonempty rows', 'not_sent');
                 keyboard = rows.map((row) => {
                     const buttons = Array.isArray(row) ? row : [];
                     return buttons.map((btn) => {
                         const record = btn && typeof btn === 'object'
                             ? btn
                             : {};
+                        const text = String(record.label ?? record.text ?? '');
+                        const callback = String(record.payload ?? record.callback_data ?? '');
+                        if (record.disabled || record.mode === 'command')
+                            throw new EndpointDeliveryError('unsupported_operation', 'Telegram disabled/command buttons are not implemented', 'not_sent');
+                        if (!text.trim() || Buffer.byteLength(callback, 'utf8') < 1 || Buffer.byteLength(callback, 'utf8') > 64)
+                            throw new EndpointDeliveryError('invalid_payload', 'Telegram callback payload must be 1-64 UTF-8 bytes and label nonempty', 'not_sent');
                         return {
-                            text: String(record.label ?? record.text ?? ''),
-                            callback_data: String(record.payload ?? record.callback_data ?? '').slice(0, 64),
+                            text,
+                            callback_data: callback,
                         };
                     });
                 });

package/lib/webhook.d.ts

@@ -6,7 +6,7 @@ export declare function safeTokenEqual(a: string, b: string): boolean;
 export interface TelegramWebhookHandler {
     readonly config: ResolvedTelegramConfig;
     readonly isOpen: boolean;
-    handleUpdate(update: TelegramUpdate): void;
+    handleUpdate(update: TelegramUpdate): void | Promise<void>;
 }
 export declare function registerTelegramWebhookRoutes(http: HttpHost, handler: TelegramWebhookHandler): HttpRouteRegistration[];
 export declare function handleTelegramWebhookRequest(request: IncomingMessage, response: ServerResponse, handler: TelegramWebhookHandler): Promise<void>;

package/lib/webhook.js

@@ -37,19 +37,24 @@ export async function handleTelegramWebhookRequest(request, response, handler) {
             update = JSON.parse(rawBody);
         }
         catch {
-            response.writeHead(200, { 'Content-Type': 'application/json' });
-            response.end(JSON.stringify({ ok: true }));
+            response.writeHead(400, { 'Content-Type': 'application/json' });
+            response.end(JSON.stringify({ ok: false, description: 'Invalid JSON' }));
             return;
         }
-        if (handler.isOpen) {
-            handler.handleUpdate(update);
+        if (!update || !Number.isSafeInteger(update.update_id) || update.update_id < 0) {
+            response.writeHead(400, { 'Content-Type': 'application/json' });
+            response.end(JSON.stringify({ ok: false, description: 'Invalid update_id' }));
+            return;
         }
+        if (!handler.isOpen)
+            throw new Error('Telegram endpoint is not accepting updates');
+        await handler.handleUpdate(update);
         response.writeHead(200, { 'Content-Type': 'application/json' });
         response.end(JSON.stringify({ ok: true }));
     }
     catch (error) {
         logger.error('Telegram webhook error:', error);
-        response.writeHead(200, { 'Content-Type': 'application/json' });
-        response.end(JSON.stringify({ ok: true }));
+        response.writeHead(503, { 'Content-Type': 'application/json' });
+        response.end(JSON.stringify({ ok: false, description: 'Update was not admitted' }));
     }
 }

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@zhin.js/adapter-telegram",
-  "version": "1.1.4",
+  "version": "1.1.5",
   "description": "Zhin.js Telegram Bot API adapter for Plugin Runtime (long-poll getUpdates)",
   "type": "module",
   "main": "./lib/index.js",
@@ -32,23 +32,23 @@
     "directory": "plugins/adapters/telegram"
   },
   "dependencies": {
-    "@zhin.js/adapter": "1.1.15",
-    "@zhin.js/agent-feature": "1.1.2",
-    "@zhin.js/core": "1.1.39",
+    "@zhin.js/adapter": "1.1.16",
+    "@zhin.js/agent-feature": "1.1.3",
+    "@zhin.js/core": "1.1.40",
     "@zhin.js/feature-kit": "1.1.2",
-    "@zhin.js/host-http": "1.1.2",
-    "@zhin.js/im-contract": "1.1.2",
+    "@zhin.js/host-http": "1.1.3",
+    "@zhin.js/im-contract": "1.1.3",
     "@zhin.js/logger": "1.1.1",
-    "@zhin.js/skill": "1.1.2",
-    "@zhin.js/tool": "1.1.2"
+    "@zhin.js/skill": "1.1.3",
+    "@zhin.js/tool": "1.1.3"
   },
   "peerDependencies": {
     "zod": "^4.0.0",
-    "@zhin.js/adapter": "^1.1.15",
-    "@zhin.js/command": "^1.1.3",
-    "@zhin.js/core": "^1.1.39",
+    "@zhin.js/adapter": "^1.1.16",
+    "@zhin.js/command": "^1.1.4",
+    "@zhin.js/core": "^1.1.40",
     "@zhin.js/permission": "^1.1.3",
-    "zhin.js": "^1.1.4"
+    "zhin.js": "^1.1.5"
   },
   "peerDependenciesMeta": {
     "@zhin.js/command": {
@@ -66,8 +66,8 @@
     "typescript": "^6.0.3",
     "vitest": "^4.1.10",
     "zod": "^4.4.3",
-    "@zhin.js/host-http": "1.1.2",
-    "zhin.js": "1.1.4"
+    "@zhin.js/host-http": "1.1.3",
+    "zhin.js": "1.1.5"
   },
   "files": [
     "adapters",

package/src/api-error.ts

@@ -0,0 +1,33 @@
+import { EndpointDeliveryError } from '@zhin.js/im-contract';
+
+/** Machine-readable failures. Sending is never automatically retried. */
+export type TelegramApiErrorKind =
+  | 'timeout' | 'cancelled' | 'network' | 'http' | 'authentication'
+  | 'rate_limit' | 'api' | 'invalid_response';
+
+export class TelegramApiError extends EndpointDeliveryError {
+  readonly kind: TelegramApiErrorKind;
+  readonly status?: number;
+  readonly retryAfterSeconds?: number;
+
+  constructor(
+    kind: TelegramApiErrorKind,
+    message: string,
+    details: {
+      readonly status?: number;
+      readonly retryAfterSeconds?: number;
+      readonly disposition?: EndpointDeliveryError['disposition'];
+    } = {},
+  ) {
+    const disposition = details.disposition ?? (
+      kind === 'authentication' || kind === 'rate_limit' || kind === 'api' ? 'rejected' : 'unknown'
+    );
+    super(disposition === 'rejected' ? 'platform_rejected'
+      : kind === 'timeout' ? 'endpoint_timeout'
+        : kind === 'cancelled' ? 'endpoint_cancelled' : 'delivery_unconfirmed', message, disposition);
+    this.name = 'TelegramApiError';
+    this.kind = kind;
+    this.status = details.status;
+    this.retryAfterSeconds = details.retryAfterSeconds;
+  }
+}