@andreprado/agentkit 0.1.0-alpha.9 → 0.1.1

package/src/runtime/channels/telegram.ts

@@ -1,11 +1,19 @@
 import type {
   ChannelAdapter,
+  ChannelMediaDownloadInput,
+  ChannelMediaDownloadResult,
   ChannelSendInput,
   ChannelStatusResult,
   RawWebhookEvent,
   WebhookVerificationResult,
 } from "../channels";
 import { AgentKitError } from "../errors";
+import {
+  CHANNEL_DOWNLOAD_TIMEOUT_MS,
+  CHANNEL_SEND_TIMEOUT_MS,
+  classifySendRequestError,
+  isRetryableReadRequestError,
+} from "./provider-fetch";
 
 export const telegramChannelAdapter: ChannelAdapter = {
   type: "telegram",
@@ -86,13 +94,37 @@ export const telegramChannelAdapter: ChannelAdapter = {
 
     const text = readString(message, "text");
 
-    if (!text) {
+    if (text) {
       return [
         {
           ...base,
-          kind: "unsupported",
+          kind: "message",
           externalIdentity: identity,
-          unsupportedReason: "unsupported_message_type:non_text",
+          message: {
+            role: "user",
+            contentType: "text",
+            content: text,
+            providerMessageId: readNumberishString(message, "message_id"),
+          },
+        },
+      ];
+    }
+
+    const audio = normalizeTelegramAudio(message);
+
+    if (audio) {
+      return [
+        {
+          ...base,
+          kind: "message",
+          externalIdentity: identity,
+          message: {
+            role: "user",
+            contentType: "audio",
+            content: "",
+            providerMessageId: readNumberishString(message, "message_id"),
+            audio,
+          },
         },
       ];
     }
@@ -100,17 +132,15 @@ export const telegramChannelAdapter: ChannelAdapter = {
     return [
       {
         ...base,
-        kind: "message",
+        kind: "unsupported",
         externalIdentity: identity,
-        message: {
-          role: "user",
-          contentType: "text",
-          content: text,
-          providerMessageId: readNumberishString(message, "message_id"),
-        },
+        unsupportedReason: "unsupported_message_type:non_text",
       },
     ];
   },
+  async downloadMedia(input) {
+    return downloadTelegramMedia(input);
+  },
   async sendMessage(input) {
     return sendTelegramMessage(input);
   },
@@ -142,6 +172,7 @@ export type TelegramSendMessageRequest = {
 };
 
 type TelegramFetch = (url: string, init: RequestInit) => Promise<Response>;
+const TELEGRAM_MAX_DOWNLOAD_BYTES = 20_000_000;
 
 export function buildTelegramSendMessageRequest(input: ChannelSendInput): TelegramSendMessageRequest {
   return buildTelegramSendMessageRequestInternal(input, "<redacted>");
@@ -156,7 +187,7 @@ export async function sendTelegramMessage(
 
     return {
       ok: true,
-      status: "sent",
+      status: "stubbed",
       providerRequestId: request.idempotencyKey,
       providerMetadata: {
         method: request.method,
@@ -196,6 +227,7 @@ export async function sendTelegramMessage(
 
   try {
     response = await fetcher(actualRequest.url, {
+      signal: AbortSignal.timeout(CHANNEL_SEND_TIMEOUT_MS),
       method: actualRequest.method,
       headers: {
         "Content-Type": "application/json",
@@ -203,13 +235,14 @@ export async function sendTelegramMessage(
       body: JSON.stringify(actualRequest.body),
     });
   } catch (error) {
+    const failure = classifySendRequestError(error);
     const errorMessage = (error instanceof Error ? error.message : String(error)).replace(token, "<redacted>");
 
     return {
       ok: false,
-      retryable: true,
-      code: "channel_provider_unavailable",
-      message: `Telegram sendMessage request failed before a response: ${errorMessage}`,
+      retryable: failure.retryable,
+      code: failure.code,
+      message: `Telegram sendMessage request ${failure.reason}: ${errorMessage}`,
       providerRequestId: request.idempotencyKey,
       providerMetadata: {
         method: request.method,
@@ -247,11 +280,26 @@ export async function sendTelegramMessage(
   const result = isRecord(payload.result) ? payload.result : undefined;
   const messageId = readNumberishString(result ?? {}, "message_id");
 
+  if (!messageId) {
+    return {
+      ok: false,
+      retryable: false,
+      code: "channel_send_failed",
+      message: "Telegram sendMessage did not return result.message_id.",
+      providerRequestId: request.idempotencyKey,
+      providerMetadata: {
+        method: request.method,
+        url: request.url,
+        body: request.body,
+      },
+    };
+  }
+
   return {
     ok: true,
     status: "sent",
     providerRequestId: request.idempotencyKey,
-    ...(messageId ? { providerMessageId: messageId } : {}),
+    providerMessageId: messageId,
     providerMetadata: {
       method: request.method,
       url: request.url,
@@ -260,6 +308,155 @@ export async function sendTelegramMessage(
   };
 }
 
+export async function downloadTelegramMedia(
+  input: ChannelMediaDownloadInput,
+  fetcher: TelegramFetch = fetch,
+): Promise<ChannelMediaDownloadResult> {
+  const token = input.secrets.TELEGRAM_BOT_TOKEN;
+
+  if (!token) {
+    return {
+      ok: false,
+      retryable: false,
+      code: "channel_secret_missing",
+      message: "Secret TELEGRAM_BOT_TOKEN is not set for this channel.",
+    };
+  }
+
+  const audio = input.message.audio;
+
+  if (!audio?.providerMediaId) {
+    return {
+      ok: false,
+      retryable: false,
+      code: "channel_audio_download_unavailable",
+      message: "Telegram audio message is missing file_id.",
+    };
+  }
+
+  let fileResponse: Response;
+
+  try {
+    const url = new URL(`/bot${token}/getFile`, telegramApiBaseUrl(input.secrets));
+    url.searchParams.set("file_id", audio.providerMediaId);
+    fileResponse = await fetcher(url.href, {
+      method: "GET",
+      signal: AbortSignal.timeout(CHANNEL_DOWNLOAD_TIMEOUT_MS),
+    });
+  } catch (error) {
+    return {
+      ok: false,
+      retryable: isRetryableReadRequestError(error),
+      code: "channel_provider_unavailable",
+      message: `Telegram getFile request failed before a response: ${redactToken(
+        error instanceof Error ? error.message : String(error),
+        token,
+      )}`,
+    };
+  }
+
+  const filePayload = await fileResponse.json().catch(() => null);
+
+  if (!fileResponse.ok || !isRecord(filePayload) || filePayload.ok !== true || !isRecord(filePayload.result)) {
+    const description =
+      isRecord(filePayload) && typeof filePayload.description === "string"
+        ? filePayload.description
+        : `Telegram getFile returned HTTP ${fileResponse.status}.`;
+
+    return {
+      ok: false,
+      retryable: fileResponse.status === 429 || fileResponse.status >= 500,
+      code: fileResponse.status === 429 || fileResponse.status >= 500
+        ? "channel_provider_unavailable"
+        : "channel_media_download_failed",
+      message: redactToken(description, token),
+      providerMetadata: {
+        status: fileResponse.status,
+      },
+    };
+  }
+
+  const filePath = readString(filePayload.result, "file_path");
+
+  if (!filePath) {
+    return {
+      ok: false,
+      retryable: false,
+      code: "channel_media_download_failed",
+      message: "Telegram getFile did not return result.file_path.",
+      providerMetadata: {
+        status: fileResponse.status,
+      },
+    };
+  }
+
+  const maxDownloadBytes = Math.min(input.maxBytes ?? TELEGRAM_MAX_DOWNLOAD_BYTES, TELEGRAM_MAX_DOWNLOAD_BYTES);
+  const fileSize = readNumber(filePayload.result, "file_size") ?? audio.sizeBytes;
+
+  if (fileSize !== undefined && fileSize > maxDownloadBytes) {
+    return {
+      ok: false,
+      retryable: false,
+      code: "channel_audio_too_large",
+      message: `Telegram audio is ${fileSize} bytes, which exceeds the configured ${maxDownloadBytes} byte limit.`,
+      providerMetadata: {
+        sizeBytes: fileSize,
+      },
+    };
+  }
+
+  let mediaResponse: Response;
+
+  try {
+    mediaResponse = await fetcher(`${telegramApiBaseUrl(input.secrets)}/file/bot${token}/${filePath}`, {
+      method: "GET",
+      signal: AbortSignal.timeout(CHANNEL_DOWNLOAD_TIMEOUT_MS),
+    });
+  } catch (error) {
+    return {
+      ok: false,
+      retryable: isRetryableReadRequestError(error),
+      code: "channel_provider_unavailable",
+      message: `Telegram file download failed before a response: ${redactToken(
+        error instanceof Error ? error.message : String(error),
+        token,
+      )}`,
+    };
+  }
+
+  if (!mediaResponse.ok) {
+    return {
+      ok: false,
+      retryable: mediaResponse.status === 429 || mediaResponse.status >= 500,
+      code: mediaResponse.status === 429 || mediaResponse.status >= 500
+        ? "channel_provider_unavailable"
+        : "channel_media_download_failed",
+      message: `Telegram file download returned HTTP ${mediaResponse.status}.`,
+      providerMetadata: {
+        status: mediaResponse.status,
+      },
+    };
+  }
+
+  const bytes = await readResponseBytesWithLimit(mediaResponse, maxDownloadBytes);
+
+  if (!bytes.ok) {
+    return bytes;
+  }
+
+  return {
+    ok: true,
+    audio: bytes.audio,
+    filename: audio.filename ?? basename(filePath) ?? `${audio.providerMediaId}.ogg`,
+    ...(audio.mimeType ? { mimeType: audio.mimeType } : {}),
+    ...(audio.durationSeconds !== undefined ? { durationSeconds: audio.durationSeconds } : {}),
+    sizeBytes: bytes.audio.byteLength,
+    providerMetadata: {
+      fileSize: fileSize ?? bytes.audio.byteLength,
+    },
+  };
+}
+
 function isSyntheticTelegramChatId(chatId: string): boolean {
   return chatId === "456" || chatId.startsWith("agentkit-synthetic-");
 }
@@ -282,6 +479,48 @@ function buildTelegramSendMessageRequestInternal(input: ChannelSendInput, token:
   };
 }
 
+function normalizeTelegramAudio(message: Record<string, unknown>) {
+  const voice = readRecord(message, "voice");
+
+  if (Object.keys(voice).length > 0) {
+    const fileId = readString(voice, "file_id");
+
+    if (!fileId) {
+      return null;
+    }
+
+    return {
+      providerMediaId: fileId,
+      kind: "voice" as const,
+      mimeType: readString(voice, "mime_type") ?? "audio/ogg",
+      filename: `${fileId}.ogg`,
+      ...(readNumber(voice, "duration") !== undefined ? { durationSeconds: readNumber(voice, "duration") } : {}),
+      ...(readNumber(voice, "file_size") !== undefined ? { sizeBytes: readNumber(voice, "file_size") } : {}),
+    };
+  }
+
+  const audio = readRecord(message, "audio");
+
+  if (Object.keys(audio).length > 0) {
+    const fileId = readString(audio, "file_id");
+
+    if (!fileId) {
+      return null;
+    }
+
+    return {
+      providerMediaId: fileId,
+      kind: "audio" as const,
+      ...(readString(audio, "mime_type") ? { mimeType: readString(audio, "mime_type") } : {}),
+      filename: readString(audio, "file_name") ?? `${fileId}.mp3`,
+      ...(readNumber(audio, "duration") !== undefined ? { durationSeconds: readNumber(audio, "duration") } : {}),
+      ...(readNumber(audio, "file_size") !== undefined ? { sizeBytes: readNumber(audio, "file_size") } : {}),
+    };
+  }
+
+  return null;
+}
+
 export function parseTelegramWebhookInfo(input: unknown, checkedAt: string): ChannelStatusResult {
   if (!isRecord(input) || input.ok !== true || !isRecord(input.result)) {
     return {
@@ -347,6 +586,131 @@ function readNumberishString(value: Record<string, unknown>, key: string): strin
   return undefined;
 }
 
+function telegramApiBaseUrl(env: Record<string, string | undefined>): string {
+  return env.AGENTKIT_TELEGRAM_API_BASE_URL ?? "https://api.telegram.org";
+}
+
+function basename(path: string): string | null {
+  const name = path.split("/").filter(Boolean).at(-1);
+  return name && name.length > 0 ? name : null;
+}
+
+async function readResponseBytesWithLimit(
+  response: Response,
+  maxBytes: number,
+): Promise<
+  | {
+      ok: true;
+      audio: Uint8Array;
+    }
+  | {
+      ok: false;
+      retryable: boolean;
+      code: "channel_audio_too_large" | "channel_provider_unavailable";
+      message: string;
+      providerMetadata?: Record<string, unknown>;
+    }
+> {
+  const contentLength = response.headers.get("content-length");
+  const declaredBytes = contentLength ? Number(contentLength) : undefined;
+
+  if (declaredBytes !== undefined && Number.isFinite(declaredBytes) && declaredBytes > maxBytes) {
+    return {
+      ok: false,
+      retryable: false,
+      code: "channel_audio_too_large",
+      message: `Audio response declares ${declaredBytes} bytes, which exceeds the configured ${maxBytes} byte limit.`,
+      providerMetadata: {
+        sizeBytes: declaredBytes,
+      },
+    };
+  }
+
+  if (!response.body) {
+    let audio: Uint8Array;
+
+    try {
+      audio = new Uint8Array(await response.arrayBuffer());
+    } catch (error) {
+      return {
+        ok: false,
+        retryable: true,
+        code: "channel_provider_unavailable",
+        message: `Media download response could not be read: ${error instanceof Error ? error.message : String(error)}`,
+      };
+    }
+
+    if (audio.byteLength > maxBytes) {
+      return {
+        ok: false,
+        retryable: false,
+        code: "channel_audio_too_large",
+        message: `Audio response is ${audio.byteLength} bytes, which exceeds the configured ${maxBytes} byte limit.`,
+        providerMetadata: {
+          sizeBytes: audio.byteLength,
+        },
+      };
+    }
+
+    return { ok: true, audio };
+  }
+
+  const reader = response.body.getReader();
+  const chunks: Uint8Array[] = [];
+  let totalBytes = 0;
+
+  try {
+    while (true) {
+      const chunk = await reader.read();
+
+      if (chunk.done) {
+        break;
+      }
+
+      totalBytes += chunk.value.byteLength;
+
+      if (totalBytes > maxBytes) {
+        await reader.cancel().catch(() => undefined);
+        return {
+          ok: false,
+          retryable: false,
+          code: "channel_audio_too_large",
+          message: `Audio response exceeded the configured ${maxBytes} byte limit while downloading.`,
+          providerMetadata: {
+            sizeBytes: totalBytes,
+          },
+        };
+      }
+
+      chunks.push(chunk.value);
+    }
+  } catch (error) {
+    await reader.cancel().catch(() => undefined);
+    return {
+      ok: false,
+      retryable: true,
+      code: "channel_provider_unavailable",
+      message: `Media download response could not be read: ${error instanceof Error ? error.message : String(error)}`,
+    };
+  } finally {
+    reader.releaseLock();
+  }
+
+  const audio = new Uint8Array(totalBytes);
+  let offset = 0;
+
+  for (const chunk of chunks) {
+    audio.set(chunk, offset);
+    offset += chunk.byteLength;
+  }
+
+  return { ok: true, audio };
+}
+
+function redactToken(value: string, token: string): string {
+  return token ? value.replaceAll(token, "<redacted>") : value;
+}
+
 function redactId(value: string): string {
   if (value.length <= 2) {
     return "*".repeat(value.length);