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

package/dist/index.d.ts

@@ -1,10 +1,20 @@
-import { type AdminUser, type ChatSurfaceAdapter, type ChatSurfaceEventSink, type ChatSurfaceIncomingMessage, type ChatSurfaceRequestContext, type IAdminForth } from "adminforth";
+import { type ChatSurfaceAdapter, type ChatSurfaceEventSink, type ChatSurfaceIncomingMessage, type ChatSurfaceRequestContext } from "adminforth";
 import { AdapterOptions } from "./types.js";
 export type { AdapterOptions, TelegramStreamingMode } from "./types.js";
 export { getFinalMessageStreamPreview, renderFinalMessageImages, renderHtmlBlockToPng, renderTablePng, renderVegaLitePng, type RenderedMessage, type RenderedMessageImage, type RenderTableColumn, type RenderTablePngInput, type VegaLiteSpec, } from "./renderers.js";
 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;
         };
@@ -17,9 +27,17 @@ type TelegramUpdate = {
         };
     };
 };
+type ChatSurfaceConnectAction = {
+    type: "url";
+    label: string;
+    url: string;
+};
 export declare class TelegramChatSurfaceAdapter implements ChatSurfaceAdapter {
     private options;
     name: string;
+    createConnectAction?: (input: {
+        token: string;
+    }) => ChatSurfaceConnectAction;
     constructor(options: AdapterOptions);
     validate(): void;
     parseIncomingMessage(ctx: ChatSurfaceRequestContext): Promise<{
@@ -29,18 +47,37 @@ 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;
         };
     } | null>;
     createEventSink(ctx: ChatSurfaceRequestContext, incoming: ChatSurfaceIncomingMessage): ChatSurfaceEventSink;
-    resolveAdminUser(input: {
-        adminforth: IAdminForth;
-        incoming: ChatSurfaceIncomingMessage;
-    }): Promise<AdminUser | null>;
     private sendMessage;
     private sendFinalMessage;
     private sendPhoto;
     private sendChatAction;
+    private downloadTelegramFile;
+    private sendAudioFile;
+    private telegramMultipart;
+    private telegramJson;
     private sendMessageDraft;
 }
 export default TelegramChatSurfaceAdapter;

package/dist/index.js

@@ -7,7 +7,6 @@ var __awaiter = (this && this.__awaiter) || function (thisArg, _arguments, P, ge
         step((generator = generator.apply(thisArg, _arguments || [])).next());
     });
 };
-import { AdminForthFilterOperators, } from "adminforth";
 import { getFinalMessageStreamPreview, renderFinalMessageImages } from "./renderers.js";
 import { randomInt } from "node:crypto";
 export { getFinalMessageStreamPreview, renderFinalMessageImages, renderHtmlBlockToPng, renderTablePng, renderVegaLitePng, } from "./renderers.js";
@@ -17,8 +16,8 @@ const TELEGRAM_MESSAGE_MAX_LENGTH = 4096;
 const TELEGRAM_DRAFT_MAX_LENGTH = 4096;
 const DEFAULT_DRAFT_UPDATE_INTERVAL_MS = 650;
 const DEFAULT_TYPING_INTERVAL_MS = 4000;
-const DEFAULT_ADMIN_USER_RESOURCE_ID = "adminuser";
-const DEFAULT_ADMIN_USER_TELEGRAM_ID_FIELD = "telegramId";
+const TELEGRAM_START_COMMAND_PREFIX = "/start";
+const TELEGRAM_COMMAND_PARTS_RE = /\s+/;
 function createTelegramDraftId() {
     return randomInt(1, 2147483647);
 }
@@ -46,10 +45,26 @@ function splitTelegramMessage(text) {
     }
     return chunks;
 }
+function parseTelegramStartCommand(text) {
+    const [command, ...payloadParts] = text.trim().split(TELEGRAM_COMMAND_PARTS_RE);
+    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) {
         this.options = options;
         this.name = "telegram";
+        if (options.botUsername) {
+            this.createConnectAction = ({ token }) => ({
+                type: "url",
+                label: "Connect Telegram",
+                url: `https://t.me/${options.botUsername}?start=${encodeURIComponent(token)}`,
+            });
+        }
     }
     validate() {
         if (!this.options.botToken) {
@@ -58,25 +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 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: {
+                    isStartCommand: startCommand.isStartCommand,
+                    startPayload: startCommand.payload,
                     telegramUpdate: update,
                 },
             };
@@ -167,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();
@@ -181,48 +233,17 @@ export class TelegramChatSurfaceAdapter {
             }),
         };
     }
-    resolveAdminUser(input) {
-        return __awaiter(this, void 0, void 0, function* () {
-            var _a, _b;
-            const adminUserResourceId = (_a = this.options.adminUserResourceId) !== null && _a !== void 0 ? _a : DEFAULT_ADMIN_USER_RESOURCE_ID;
-            const telegramIdField = (_b = this.options.adminUserTelegramIdField) !== null && _b !== void 0 ? _b : DEFAULT_ADMIN_USER_TELEGRAM_ID_FIELD;
-            const adminUser = yield input.adminforth.resource(adminUserResourceId).get([
-                {
-                    field: telegramIdField,
-                    operator: AdminForthFilterOperators.EQ,
-                    value: input.incoming.externalUserId,
-                },
-            ]);
-            if (!adminUser) {
-                return null;
-            }
-            return {
-                pk: adminUser.id,
-                username: adminUser[input.adminforth.config.auth.usernameField],
-                dbUser: adminUser,
-            };
-        });
-    }
     sendMessage(chatId, text) {
         return __awaiter(this, void 0, void 0, function* () {
             if (!text) {
                 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()}`);
-                }
             }
         });
     }
@@ -243,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/dist/types.d.ts

@@ -4,6 +4,10 @@ export type AdapterOptions = {
      * Telegram bot token from BotFather.
      */
     botToken: string;
+    /**
+     * Telegram bot username used to build the AdminForth account-link URL.
+     */
+    botUsername?: string;
     /**
      * Optional secret token configured in Telegram setWebhook.
      */
@@ -18,14 +22,4 @@ export type AdapterOptions = {
      * Default is 650ms.
      */
     draftUpdateIntervalMs?: number;
-    /**
-     * AdminForth admin user field that stores Telegram user id.
-     * Default is `telegramId`.
-     */
-    adminUserTelegramIdField?: string;
-    /**
-     * AdminForth admin users resource id.
-     * Default is `adminuser`.
-     */
-    adminUserResourceId?: string;
 };

package/index.ts

@@ -1,11 +1,9 @@
 import {
-  AdminForthFilterOperators,
-  type AdminUser,
   type ChatSurfaceAdapter,
+  type ChatSurfaceEvent,
   type ChatSurfaceEventSink,
   type ChatSurfaceIncomingMessage,
   type ChatSurfaceRequestContext,
-  type IAdminForth,
 } from "adminforth";
 import { AdapterOptions } from "./types.js";
 import { getFinalMessageStreamPreview, renderFinalMessageImages } from "./renderers.js";
@@ -27,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;
     };
@@ -40,14 +48,37 @@ 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;
 const TELEGRAM_DRAFT_MAX_LENGTH = 4096;
 const DEFAULT_DRAFT_UPDATE_INTERVAL_MS = 650;
 const DEFAULT_TYPING_INTERVAL_MS = 4000;
-const DEFAULT_ADMIN_USER_RESOURCE_ID = "adminuser";
-const DEFAULT_ADMIN_USER_TELEGRAM_ID_FIELD = "telegramId";
+const TELEGRAM_START_COMMAND_PREFIX = "/start";
+const TELEGRAM_COMMAND_PARTS_RE = /\s+/;
 
 function createTelegramDraftId() {
   return randomInt(1, 2147483647);
@@ -90,10 +121,31 @@ function splitTelegramMessage(text: string) {
   return chunks;
 }
 
+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}@`);
+
+  return {
+    isStartCommand,
+    payload: isStartCommand ? payloadParts.join(" ") || null : null,
+  };
+}
+
 export class TelegramChatSurfaceAdapter implements ChatSurfaceAdapter {
   name = "telegram";
-
-  constructor(private options: AdapterOptions) {}
+  createConnectAction?: (input: { token: string }) => ChatSurfaceConnectAction;
+
+  constructor(private options: AdapterOptions) {
+    if (options.botUsername) {
+      this.createConnectAction = ({ token }) => ({
+        type: "url",
+        label: "Connect Telegram",
+        url: `https://t.me/${options.botUsername}?start=${encodeURIComponent(token)}`,
+      });
+    }
+  }
 
   validate() {
     if (!this.options.botToken) {
@@ -110,21 +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 (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 = message?.voice?.file_id;
+    const audioFileId = message?.audio?.file_id;
+    const fileId = voiceFileId ?? audioFileId;
 
-    if (!text || chatId === undefined || userId === undefined) {
+    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: {
+        isStartCommand: startCommand.isStartCommand,
+        startPayload: startCommand.payload,
         telegramUpdate: update,
       },
     };
@@ -220,7 +310,7 @@ export class TelegramChatSurfaceAdapter implements ChatSurfaceAdapter {
     startTyping();
 
     return {
-      emit: async (event) => {
+      emit: async (event: TelegramChatSurfaceEvent) => {
         if (closed) {
           return;
         }
@@ -240,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;
         }
@@ -267,52 +364,17 @@ export class TelegramChatSurfaceAdapter implements ChatSurfaceAdapter {
     };
   }
 
-  async resolveAdminUser(input: {
-    adminforth: IAdminForth;
-    incoming: ChatSurfaceIncomingMessage;
-  }): Promise<AdminUser | null> {
-    const adminUserResourceId = this.options.adminUserResourceId ?? DEFAULT_ADMIN_USER_RESOURCE_ID;
-    const telegramIdField = this.options.adminUserTelegramIdField ?? DEFAULT_ADMIN_USER_TELEGRAM_ID_FIELD;
-    const adminUser = await input.adminforth.resource(adminUserResourceId).get([
-      {
-        field: telegramIdField,
-        operator: AdminForthFilterOperators.EQ,
-        value: input.incoming.externalUserId,
-      },
-    ]);
-
-    if (!adminUser) {
-      return null;
-    }
-
-    return {
-      pk: adminUser.id,
-      username: adminUser[input.adminforth.config.auth!.usernameField],
-      dbUser: adminUser,
-    };
-  }
-
   private async sendMessage(chatId: string, text: string) {
     if (!text) {
       return;
     }
 
     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.0",
+  "version": "1.2.0",
   "main": "dist/index.js",
   "types": "dist/index.d.ts",
   "type": "module",
@@ -33,8 +33,7 @@
     "playwright": "^1.57.0"
   },
   "peerDependencies": {
-    "@adminforth/agent": ">=1.0.2",
-    "adminforth": ">=2.59.0"
+    "adminforth": ">=2.60.0"
   },
   "release": {
     "plugins": [

package/types.ts

@@ -6,6 +6,11 @@ export type AdapterOptions = {
    */
   botToken: string;
 
+  /**
+   * Telegram bot username used to build the AdminForth account-link URL.
+   */
+  botUsername?: string;
+
   /**
    * Optional secret token configured in Telegram setWebhook.
    */
@@ -22,16 +27,4 @@ export type AdapterOptions = {
    * Default is 650ms.
    */
   draftUpdateIntervalMs?: number;
-
-  /**
-   * AdminForth admin user field that stores Telegram user id.
-   * Default is `telegramId`.
-   */
-  adminUserTelegramIdField?: string;
-
-  /**
-   * AdminForth admin users resource id.
-   * Default is `adminuser`.
-   */
-  adminUserResourceId?: string;
 };