@adminforth/chat-surface-adapter-telegram 1.1.1 → 1.2.0

package/dist/index.d.ts

@@ -5,6 +5,16 @@ export { getFinalMessageStreamPreview, renderFinalMessageImages, renderHtmlBlock
 type TelegramUpdate = {
     message?: {
         text?: string;
+        caption?: string;
+        voice?: {
+            file_id?: string;
+            mime_type?: string;
+        };
+        audio?: {
+            file_id?: string;
+            file_name?: string;
+            mime_type?: string;
+        };
         chat?: {
             id?: number | string;
         };
@@ -37,6 +47,24 @@ export declare class TelegramChatSurfaceAdapter implements ChatSurfaceAdapter {
         externalUserId: string;
         userTimeZone: string;
         metadata: {
+            isStartCommand: boolean;
+            startPayload: string | null;
+            telegramUpdate: TelegramUpdate;
+        };
+        audio?: undefined;
+    } | {
+        surface: string;
+        prompt: string;
+        audio: {
+            buffer: Buffer<ArrayBuffer>;
+            filename: string;
+            mimeType: string;
+        };
+        externalConversationId: string;
+        externalUserId: string;
+        userTimeZone: string;
+        metadata: {
+            isStartCommand: boolean;
             startPayload: string | null;
             telegramUpdate: TelegramUpdate;
         };
@@ -46,6 +74,10 @@ export declare class TelegramChatSurfaceAdapter implements ChatSurfaceAdapter {
     private sendFinalMessage;
     private sendPhoto;
     private sendChatAction;
+    private downloadTelegramFile;
+    private sendAudioFile;
+    private telegramMultipart;
+    private telegramJson;
     private sendMessageDraft;
 }
 export default TelegramChatSurfaceAdapter;

package/dist/index.js

@@ -45,12 +45,14 @@ function splitTelegramMessage(text) {
     }
     return chunks;
 }
-function parseTelegramStartPayload(text) {
+function parseTelegramStartCommand(text) {
     const [command, ...payloadParts] = text.trim().split(TELEGRAM_COMMAND_PARTS_RE);
-    if (command !== TELEGRAM_START_COMMAND_PREFIX && !command.startsWith(`${TELEGRAM_START_COMMAND_PREFIX}@`)) {
-        return null;
-    }
-    return payloadParts.join(" ") || null;
+    const isStartCommand = command === TELEGRAM_START_COMMAND_PREFIX ||
+        command.startsWith(`${TELEGRAM_START_COMMAND_PREFIX}@`);
+    return {
+        isStartCommand,
+        payload: isStartCommand ? payloadParts.join(" ") || null : null,
+    };
 }
 export class TelegramChatSurfaceAdapter {
     constructor(options) {
@@ -71,27 +73,58 @@ export class TelegramChatSurfaceAdapter {
     }
     parseIncomingMessage(ctx) {
         return __awaiter(this, void 0, void 0, function* () {
-            var _a, _b, _c, _d, _e;
+            var _a, _b, _c, _d, _e, _f, _g, _h, _j, _k, _l;
             if (this.options.webhookSecret
                 && getHeaderValue(ctx.headers, TELEGRAM_SECRET_HEADER) !== this.options.webhookSecret) {
                 return null;
             }
             const update = ctx.body;
-            const text = (_a = update.message) === null || _a === void 0 ? void 0 : _a.text;
-            const chatId = (_c = (_b = update.message) === null || _b === void 0 ? void 0 : _b.chat) === null || _c === void 0 ? void 0 : _c.id;
-            const userId = (_e = (_d = update.message) === null || _d === void 0 ? void 0 : _d.from) === null || _e === void 0 ? void 0 : _e.id;
-            if (!text || chatId === undefined || userId === undefined) {
+            const message = update.message;
+            const text = message === null || message === void 0 ? void 0 : message.text;
+            const chatId = (_a = message === null || message === void 0 ? void 0 : message.chat) === null || _a === void 0 ? void 0 : _a.id;
+            const userId = (_b = message === null || message === void 0 ? void 0 : message.from) === null || _b === void 0 ? void 0 : _b.id;
+            if (chatId === undefined || userId === undefined) {
+                return null;
+            }
+            const startCommand = text
+                ? parseTelegramStartCommand(text)
+                : { isStartCommand: false, payload: null };
+            if (text) {
+                return {
+                    surface: this.name,
+                    prompt: text,
+                    externalConversationId: String(chatId),
+                    externalUserId: String(userId),
+                    userTimeZone: "UTC",
+                    metadata: {
+                        isStartCommand: startCommand.isStartCommand,
+                        startPayload: startCommand.payload,
+                        telegramUpdate: update,
+                    },
+                };
+            }
+            const voiceFileId = (_c = message === null || message === void 0 ? void 0 : message.voice) === null || _c === void 0 ? void 0 : _c.file_id;
+            const audioFileId = (_d = message === null || message === void 0 ? void 0 : message.audio) === null || _d === void 0 ? void 0 : _d.file_id;
+            const fileId = voiceFileId !== null && voiceFileId !== void 0 ? voiceFileId : audioFileId;
+            if (!fileId) {
                 return null;
             }
-            const startPayload = parseTelegramStartPayload(text);
+            const audio = yield this.downloadTelegramFile({
+                fileId,
+                filename: (_f = (_e = message === null || message === void 0 ? void 0 : message.audio) === null || _e === void 0 ? void 0 : _e.file_name) !== null && _f !== void 0 ? _f : (voiceFileId ? "telegram-voice.ogg" : "telegram-audio"),
+                mimeType: (_k = (_h = (_g = message === null || message === void 0 ? void 0 : message.voice) === null || _g === void 0 ? void 0 : _g.mime_type) !== null && _h !== void 0 ? _h : (_j = message === null || message === void 0 ? void 0 : message.audio) === null || _j === void 0 ? void 0 : _j.mime_type) !== null && _k !== void 0 ? _k : "application/octet-stream",
+                abortSignal: ctx.abortSignal,
+            });
             return {
                 surface: this.name,
-                prompt: text,
+                prompt: (_l = message === null || message === void 0 ? void 0 : message.caption) !== null && _l !== void 0 ? _l : "",
+                audio,
                 externalConversationId: String(chatId),
                 externalUserId: String(userId),
                 userTimeZone: "UTC",
                 metadata: {
-                    startPayload,
+                    isStartCommand: startCommand.isStartCommand,
+                    startPayload: startCommand.payload,
                     telegramUpdate: update,
                 },
             };
@@ -182,6 +215,10 @@ export class TelegramChatSurfaceAdapter {
                     yield this.sendFinalMessage(chatId, text || event.text);
                     return;
                 }
+                if (event.type === "audio") {
+                    yield this.sendAudioFile(chatId, event.audio, event.filename, event.mimeType);
+                    return;
+                }
                 if (event.type === "error") {
                     done = true;
                     stopTyping();
@@ -202,20 +239,11 @@ export class TelegramChatSurfaceAdapter {
                 return;
             }
             for (const chunk of splitTelegramMessage(text)) {
-                const response = yield fetch(`${TELEGRAM_API_BASE_URL}/bot${this.options.botToken}/sendMessage`, {
-                    method: "POST",
-                    headers: {
-                        "Content-Type": "application/json",
-                    },
-                    body: JSON.stringify({
-                        chat_id: chatId,
-                        text: chunk,
-                        parse_mode: "Markdown",
-                    }),
+                yield this.telegramJson("sendMessage", {
+                    chat_id: chatId,
+                    text: chunk,
+                    parse_mode: "Markdown",
                 });
-                if (!response.ok) {
-                    throw new Error(`Telegram sendMessage failed: ${response.status} ${yield response.text()}`);
-                }
             }
         });
     }
@@ -236,49 +264,87 @@ export class TelegramChatSurfaceAdapter {
             formData.append("photo", new Blob([photoBytes], {
                 type: "image/png",
             }), filename);
-            const response = yield fetch(`${TELEGRAM_API_BASE_URL}/bot${this.options.botToken}/sendPhoto`, {
+            yield this.telegramMultipart("sendPhoto", formData);
+        });
+    }
+    sendChatAction(chatId, action) {
+        return __awaiter(this, void 0, void 0, function* () {
+            yield this.telegramJson("sendChatAction", {
+                chat_id: chatId,
+                action,
+            });
+        });
+    }
+    downloadTelegramFile(input) {
+        return __awaiter(this, void 0, void 0, function* () {
+            var _a, _b;
+            const fileResponse = yield fetch(`${TELEGRAM_API_BASE_URL}/bot${this.options.botToken}/getFile?file_id=${encodeURIComponent(input.fileId)}`, { signal: input.abortSignal });
+            if (!fileResponse.ok) {
+                throw new Error(`Telegram getFile failed: ${fileResponse.status} ${yield fileResponse.text()}`);
+            }
+            const fileData = yield fileResponse.json();
+            const filePath = (_a = fileData.result) === null || _a === void 0 ? void 0 : _a.file_path;
+            if (!fileData.ok || !filePath) {
+                throw new Error(`Telegram getFile failed: ${(_b = fileData.description) !== null && _b !== void 0 ? _b : "file_path is missing"}`);
+            }
+            const downloadResponse = yield fetch(`${TELEGRAM_API_BASE_URL}/file/bot${this.options.botToken}/${filePath}`, { signal: input.abortSignal });
+            if (!downloadResponse.ok) {
+                throw new Error(`Telegram file download failed: ${downloadResponse.status} ${yield downloadResponse.text()}`);
+            }
+            return {
+                buffer: Buffer.from(yield downloadResponse.arrayBuffer()),
+                filename: input.filename,
+                mimeType: input.mimeType,
+            };
+        });
+    }
+    sendAudioFile(chatId, audio, filename, mimeType) {
+        return __awaiter(this, void 0, void 0, function* () {
+            const sendAsVoice = ["audio/ogg", "audio/opus"].includes(mimeType) || filename.endsWith(".ogg") || filename.endsWith(".opus");
+            const method = sendAsVoice ? "sendVoice" : "sendAudio";
+            const fieldName = sendAsVoice ? "voice" : "audio";
+            const audioBytes = new Uint8Array(audio);
+            const formData = new FormData();
+            formData.append("chat_id", chatId);
+            formData.append(fieldName, new Blob([audioBytes], {
+                type: mimeType,
+            }), filename);
+            yield this.telegramMultipart(method, formData);
+        });
+    }
+    telegramMultipart(method, formData) {
+        return __awaiter(this, void 0, void 0, function* () {
+            const response = yield fetch(`${TELEGRAM_API_BASE_URL}/bot${this.options.botToken}/${method}`, {
                 method: "POST",
                 body: formData,
             });
             if (!response.ok) {
-                throw new Error(`Telegram sendPhoto failed: ${response.status} ${yield response.text()}`);
+                throw new Error(`Telegram ${method} failed: ${response.status} ${yield response.text()}`);
             }
         });
     }
-    sendChatAction(chatId, action) {
+    telegramJson(method, body) {
         return __awaiter(this, void 0, void 0, function* () {
-            const response = yield fetch(`${TELEGRAM_API_BASE_URL}/bot${this.options.botToken}/sendChatAction`, {
+            const response = yield fetch(`${TELEGRAM_API_BASE_URL}/bot${this.options.botToken}/${method}`, {
                 method: "POST",
                 headers: {
                     "Content-Type": "application/json",
                 },
-                body: JSON.stringify({
-                    chat_id: chatId,
-                    action,
-                }),
+                body: JSON.stringify(body),
             });
             if (!response.ok) {
-                throw new Error(`Telegram sendChatAction failed: ${response.status} ${yield response.text()}`);
+                throw new Error(`Telegram ${method} failed: ${response.status} ${yield response.text()}`);
             }
         });
     }
     sendMessageDraft(input) {
         return __awaiter(this, void 0, void 0, function* () {
-            const response = yield fetch(`${TELEGRAM_API_BASE_URL}/bot${this.options.botToken}/sendMessageDraft`, {
-                method: "POST",
-                headers: {
-                    "Content-Type": "application/json",
-                },
-                body: JSON.stringify({
-                    chat_id: Number(input.chatId),
-                    draft_id: input.draftId,
-                    text: input.text,
-                    parse_mode: input.parseMode,
-                }),
+            yield this.telegramJson("sendMessageDraft", {
+                chat_id: Number(input.chatId),
+                draft_id: input.draftId,
+                text: input.text,
+                parse_mode: input.parseMode,
             });
-            if (!response.ok) {
-                throw new Error(`Telegram sendMessageDraft failed: ${response.status} ${yield response.text()}`);
-            }
         });
     }
 }

package/index.ts

@@ -1,5 +1,6 @@
 import {
   type ChatSurfaceAdapter,
+  type ChatSurfaceEvent,
   type ChatSurfaceEventSink,
   type ChatSurfaceIncomingMessage,
   type ChatSurfaceRequestContext,
@@ -24,6 +25,16 @@ export {
 type TelegramUpdate = {
   message?: {
     text?: string;
+    caption?: string;
+    voice?: {
+      file_id?: string;
+      mime_type?: string;
+    };
+    audio?: {
+      file_id?: string;
+      file_name?: string;
+      mime_type?: string;
+    };
     chat?: {
       id?: number | string;
     };
@@ -37,12 +48,29 @@ type TelegramUpdate = {
   };
 };
 
+type TelegramGetFileResponse = {
+  ok: boolean;
+  result?: {
+    file_path?: string;
+  };
+  description?: string;
+};
+
 type ChatSurfaceConnectAction = {
   type: "url";
   label: string;
   url: string;
 };
 
+type TelegramChatSurfaceEvent =
+  | ChatSurfaceEvent
+  | {
+      type: "audio";
+      audio: Buffer;
+      filename: string;
+      mimeType: string;
+    };
+
 const TELEGRAM_API_BASE_URL = "https://api.telegram.org";
 const TELEGRAM_SECRET_HEADER = "x-telegram-bot-api-secret-token";
 const TELEGRAM_MESSAGE_MAX_LENGTH = 4096;
@@ -93,14 +121,16 @@ function splitTelegramMessage(text: string) {
   return chunks;
 }
 
-function parseTelegramStartPayload(text: string) {
+function parseTelegramStartCommand(text: string) {
   const [command, ...payloadParts] = text.trim().split(TELEGRAM_COMMAND_PARTS_RE);
+  const isStartCommand =
+    command === TELEGRAM_START_COMMAND_PREFIX ||
+    command.startsWith(`${TELEGRAM_START_COMMAND_PREFIX}@`);
 
-  if (command !== TELEGRAM_START_COMMAND_PREFIX && !command.startsWith(`${TELEGRAM_START_COMMAND_PREFIX}@`)) {
-    return null;
-  }
-
-  return payloadParts.join(" ") || null;
+  return {
+    isStartCommand,
+    payload: isStartCommand ? payloadParts.join(" ") || null : null,
+  };
 }
 
 export class TelegramChatSurfaceAdapter implements ChatSurfaceAdapter {
@@ -132,24 +162,59 @@ export class TelegramChatSurfaceAdapter implements ChatSurfaceAdapter {
     }
 
     const update = ctx.body as TelegramUpdate;
-    const text = update.message?.text;
-    const chatId = update.message?.chat?.id;
-    const userId = update.message?.from?.id;
+    const message = update.message;
+    const text = message?.text;
+    const chatId = message?.chat?.id;
+    const userId = message?.from?.id;
 
-    if (!text || chatId === undefined || userId === undefined) {
+    if (chatId === undefined || userId === undefined) {
       return null;
     }
 
-    const startPayload = parseTelegramStartPayload(text);
+    const startCommand = text
+      ? parseTelegramStartCommand(text)
+      : { isStartCommand: false, payload: null };
+
+    if (text) {
+      return {
+        surface: this.name,
+        prompt: text,
+        externalConversationId: String(chatId),
+        externalUserId: String(userId),
+        userTimeZone: "UTC",
+        metadata: {
+          isStartCommand: startCommand.isStartCommand,
+          startPayload: startCommand.payload,
+          telegramUpdate: update,
+        },
+      };
+    }
+
+    const voiceFileId = message?.voice?.file_id;
+    const audioFileId = message?.audio?.file_id;
+    const fileId = voiceFileId ?? audioFileId;
+
+    if (!fileId) {
+      return null;
+    }
+
+    const audio = await this.downloadTelegramFile({
+      fileId,
+      filename: message?.audio?.file_name ?? (voiceFileId ? "telegram-voice.ogg" : "telegram-audio"),
+      mimeType: message?.voice?.mime_type ?? message?.audio?.mime_type ?? "application/octet-stream",
+      abortSignal: ctx.abortSignal,
+    });
 
     return {
       surface: this.name,
-      prompt: text,
+      prompt: message?.caption ?? "",
+      audio,
       externalConversationId: String(chatId),
       externalUserId: String(userId),
       userTimeZone: "UTC",
       metadata: {
-        startPayload,
+        isStartCommand: startCommand.isStartCommand,
+        startPayload: startCommand.payload,
         telegramUpdate: update,
       },
     };
@@ -245,7 +310,7 @@ export class TelegramChatSurfaceAdapter implements ChatSurfaceAdapter {
     startTyping();
 
     return {
-      emit: async (event) => {
+      emit: async (event: TelegramChatSurfaceEvent) => {
         if (closed) {
           return;
         }
@@ -265,9 +330,16 @@ export class TelegramChatSurfaceAdapter implements ChatSurfaceAdapter {
           stopTyping();
           clearDraftTimer();
 
-          await this.sendFinalMessage(
+          await this.sendFinalMessage(chatId, text || event.text);
+          return;
+        }
+
+        if (event.type === "audio") {
+          await this.sendAudioFile(
             chatId,
-            text || event.text,
+            event.audio,
+            event.filename,
+            event.mimeType,
           );
           return;
         }
@@ -298,21 +370,11 @@ export class TelegramChatSurfaceAdapter implements ChatSurfaceAdapter {
     }
 
     for (const chunk of splitTelegramMessage(text)) {
-      const response = await fetch(`${TELEGRAM_API_BASE_URL}/bot${this.options.botToken}/sendMessage`, {
-        method: "POST",
-        headers: {
-          "Content-Type": "application/json",
-        },
-        body: JSON.stringify({
-          chat_id: chatId,
-          text: chunk,
-          parse_mode: "Markdown",
-        }),
+      await this.telegramJson("sendMessage", {
+        chat_id: chatId,
+        text: chunk,
+        parse_mode: "Markdown",
       });
-
-      if (!response.ok) {
-        throw new Error(`Telegram sendMessage failed: ${response.status} ${await response.text()}`);
-      }
     }
   }
 
@@ -334,30 +396,95 @@ export class TelegramChatSurfaceAdapter implements ChatSurfaceAdapter {
       type: "image/png",
     }), filename);
 
-    const response = await fetch(`${TELEGRAM_API_BASE_URL}/bot${this.options.botToken}/sendPhoto`, {
+    await this.telegramMultipart("sendPhoto", formData);
+  }
+
+  private async sendChatAction(chatId: string, action: "typing" | "upload_voice" | "upload_audio") {
+    await this.telegramJson("sendChatAction", {
+      chat_id: chatId,
+      action,
+    });
+  }
+
+  private async downloadTelegramFile(input: {
+    fileId: string;
+    filename: string;
+    mimeType: string;
+    abortSignal: AbortSignal;
+  }) {
+    const fileResponse = await fetch(
+      `${TELEGRAM_API_BASE_URL}/bot${this.options.botToken}/getFile?file_id=${encodeURIComponent(input.fileId)}`,
+      { signal: input.abortSignal },
+    );
+
+    if (!fileResponse.ok) {
+      throw new Error(`Telegram getFile failed: ${fileResponse.status} ${await fileResponse.text()}`);
+    }
+
+    const fileData = await fileResponse.json() as TelegramGetFileResponse;
+    const filePath = fileData.result?.file_path;
+
+    if (!fileData.ok || !filePath) {
+      throw new Error(`Telegram getFile failed: ${fileData.description ?? "file_path is missing"}`);
+    }
+
+    const downloadResponse = await fetch(
+      `${TELEGRAM_API_BASE_URL}/file/bot${this.options.botToken}/${filePath}`,
+      { signal: input.abortSignal },
+    );
+
+    if (!downloadResponse.ok) {
+      throw new Error(`Telegram file download failed: ${downloadResponse.status} ${await downloadResponse.text()}`);
+    }
+
+    return {
+      buffer: Buffer.from(await downloadResponse.arrayBuffer()),
+      filename: input.filename,
+      mimeType: input.mimeType,
+    };
+  }
+
+  private async sendAudioFile(
+    chatId: string,
+    audio: Buffer,
+    filename: string,
+    mimeType: string,
+  ) {
+    const sendAsVoice = ["audio/ogg", "audio/opus"].includes(mimeType) || filename.endsWith(".ogg") || filename.endsWith(".opus");
+    const method = sendAsVoice ? "sendVoice" : "sendAudio";
+    const fieldName = sendAsVoice ? "voice" : "audio";
+    const audioBytes = new Uint8Array(audio);
+    const formData = new FormData();
+    formData.append("chat_id", chatId);
+    formData.append(fieldName, new Blob([audioBytes], {
+      type: mimeType,
+    }), filename);
+
+    await this.telegramMultipart(method, formData);
+  }
+
+  private async telegramMultipart(method: string, formData: FormData) {
+    const response = await fetch(`${TELEGRAM_API_BASE_URL}/bot${this.options.botToken}/${method}`, {
       method: "POST",
       body: formData,
     });
 
     if (!response.ok) {
-      throw new Error(`Telegram sendPhoto failed: ${response.status} ${await response.text()}`);
+      throw new Error(`Telegram ${method} failed: ${response.status} ${await response.text()}`);
     }
   }
 
-  private async sendChatAction(chatId: string, action: "typing") {
-    const response = await fetch(`${TELEGRAM_API_BASE_URL}/bot${this.options.botToken}/sendChatAction`, {
+  private async telegramJson(method: string, body: unknown) {
+    const response = await fetch(`${TELEGRAM_API_BASE_URL}/bot${this.options.botToken}/${method}`, {
       method: "POST",
       headers: {
         "Content-Type": "application/json",
       },
-      body: JSON.stringify({
-        chat_id: chatId,
-        action,
-      }),
+      body: JSON.stringify(body),
     });
 
     if (!response.ok) {
-      throw new Error(`Telegram sendChatAction failed: ${response.status} ${await response.text()}`);
+      throw new Error(`Telegram ${method} failed: ${response.status} ${await response.text()}`);
     }
   }
 
@@ -367,22 +494,12 @@ export class TelegramChatSurfaceAdapter implements ChatSurfaceAdapter {
     text: string;
     parseMode?: "Markdown" | "MarkdownV2" | "HTML";
   }) {
-    const response = await fetch(`${TELEGRAM_API_BASE_URL}/bot${this.options.botToken}/sendMessageDraft`, {
-      method: "POST",
-      headers: {
-        "Content-Type": "application/json",
-      },
-      body: JSON.stringify({
-        chat_id: Number(input.chatId),
-        draft_id: input.draftId,
-        text: input.text,
-        parse_mode: input.parseMode,
-      }),
+    await this.telegramJson("sendMessageDraft", {
+      chat_id: Number(input.chatId),
+      draft_id: input.draftId,
+      text: input.text,
+      parse_mode: input.parseMode,
     });
-
-    if (!response.ok) {
-      throw new Error(`Telegram sendMessageDraft failed: ${response.status} ${await response.text()}`);
-    }
   }
 }
 

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@adminforth/chat-surface-adapter-telegram",
-  "version": "1.1.1",
+  "version": "1.2.0",
   "main": "dist/index.js",
   "types": "dist/index.d.ts",
   "type": "module",
@@ -33,7 +33,6 @@
     "playwright": "^1.57.0"
   },
   "peerDependencies": {
-    "@adminforth/agent": ">=1.0.2",
     "adminforth": ">=2.60.0"
   },
   "release": {