@andreprado/agentkit 0.1.0-alpha.8 → 0.1.0

package/src/runtime/channels/telegram.ts

@@ -1,5 +1,7 @@
 import type {
   ChannelAdapter,
+  ChannelMediaDownloadInput,
+  ChannelMediaDownloadResult,
   ChannelSendInput,
   ChannelStatusResult,
   RawWebhookEvent,
@@ -86,13 +88,37 @@ export const telegramChannelAdapter: ChannelAdapter = {
 
     const text = readString(message, "text");
 
-    if (!text) {
+    if (text) {
       return [
         {
           ...base,
-          kind: "unsupported",
+          kind: "message",
+          externalIdentity: identity,
+          message: {
+            role: "user",
+            contentType: "text",
+            content: text,
+            providerMessageId: readNumberishString(message, "message_id"),
+          },
+        },
+      ];
+    }
+
+    const audio = normalizeTelegramAudio(message);
+
+    if (audio) {
+      return [
+        {
+          ...base,
+          kind: "message",
           externalIdentity: identity,
-          unsupportedReason: "unsupported_message_type:non_text",
+          message: {
+            role: "user",
+            contentType: "audio",
+            content: "",
+            providerMessageId: readNumberishString(message, "message_id"),
+            audio,
+          },
         },
       ];
     }
@@ -100,30 +126,17 @@ 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) {
-    const request = buildTelegramSendMessageRequest(input);
-
-    return {
-      ok: true,
-      status: "sent",
-      providerRequestId: request.idempotencyKey,
-      providerMetadata: {
-        method: request.method,
-        url: request.url,
-        body: request.body,
-      },
-    };
+    return sendTelegramMessage(input);
   },
   getStatus(input) {
     if (!input.secrets.TELEGRAM_BOT_TOKEN) {
@@ -152,7 +165,289 @@ export type TelegramSendMessageRequest = {
   idempotencyKey: string;
 };
 
+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>");
+}
+
+export async function sendTelegramMessage(
+  input: ChannelSendInput,
+  fetcher: TelegramFetch = fetch,
+): Promise<Awaited<ReturnType<ChannelAdapter["sendMessage"]>>> {
+  if (input.secrets.AGENTKIT_CHANNEL_SEND_DRY_RUN === "1") {
+    const request = buildTelegramSendMessageRequest(input);
+
+    return {
+      ok: true,
+      status: "stubbed",
+      providerRequestId: request.idempotencyKey,
+      providerMetadata: {
+        method: request.method,
+        url: request.url,
+        body: request.body,
+      },
+    };
+  }
+
+  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.",
+    };
+  }
+
+  let request: TelegramSendMessageRequest;
+  let actualRequest: TelegramSendMessageRequest;
+
+  try {
+    request = buildTelegramSendMessageRequest(input);
+    actualRequest = buildTelegramSendMessageRequestInternal(input, token);
+  } catch (error) {
+    return {
+      ok: false,
+      retryable: false,
+      code: "channel_send_failed",
+      message: error instanceof Error ? error.message : String(error),
+    };
+  }
+
+  let response: Response;
+
+  try {
+    response = await fetcher(actualRequest.url, {
+      method: actualRequest.method,
+      headers: {
+        "Content-Type": "application/json",
+      },
+      body: JSON.stringify(actualRequest.body),
+    });
+  } catch (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}`,
+      providerRequestId: request.idempotencyKey,
+      providerMetadata: {
+        method: request.method,
+        url: request.url,
+        body: request.body,
+      },
+    };
+  }
+
+  const payload = await response.json().catch(() => null);
+
+  if (!response.ok || !isRecord(payload) || payload.ok !== true) {
+    const description =
+      isRecord(payload) && typeof payload.description === "string"
+        ? payload.description
+        : `Telegram sendMessage returned HTTP ${response.status}.`;
+    const syntheticExpectedFailure = isSyntheticTelegramChatId(request.body.chat_id) && /chat not found/i.test(description);
+
+    return {
+      ok: false,
+      retryable: syntheticExpectedFailure ? false : response.status === 429 || response.status >= 500,
+      code: syntheticExpectedFailure ? "synthetic_expected_failure" : "channel_send_failed",
+      message: syntheticExpectedFailure
+        ? "Synthetic Telegram smoke reached AgentKit. Telegram correctly rejected the fake chat ID."
+        : description,
+      providerRequestId: request.idempotencyKey,
+      providerMetadata: {
+        method: request.method,
+        url: request.url,
+        body: request.body,
+      },
+    };
+  }
+
+  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,
+    providerMessageId: messageId,
+    providerMetadata: {
+      method: request.method,
+      url: request.url,
+      body: request.body,
+    },
+  };
+}
+
+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" });
+  } catch (error) {
+    return {
+      ok: false,
+      retryable: true,
+      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" });
+  } catch (error) {
+    return {
+      ok: false,
+      retryable: true,
+      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-");
+}
+
+function buildTelegramSendMessageRequestInternal(input: ChannelSendInput, token: string): TelegramSendMessageRequest {
   const chatId = input.externalIdentity.key.match(/:chat:([^:]+)$/)?.[1];
 
   if (!chatId) {
@@ -161,7 +456,7 @@ export function buildTelegramSendMessageRequest(input: ChannelSendInput): Telegr
 
   return {
     method: "POST",
-    url: "https://api.telegram.org/bot<redacted>/sendMessage",
+    url: `https://api.telegram.org/bot${token}/sendMessage`,
     body: {
       chat_id: chatId,
       text: input.message.content,
@@ -170,6 +465,48 @@ export function buildTelegramSendMessageRequest(input: ChannelSendInput): Telegr
   };
 }
 
+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 {
@@ -235,6 +572,112 @@ 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: false;
+      code: "channel_audio_too_large";
+      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) {
+    const audio = new Uint8Array(await response.arrayBuffer());
+
+    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);
+    }
+  } 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);