@llblab/pi-telegram 0.2.0

package/lib/api.ts

@@ -0,0 +1,222 @@
+/**
+ * Telegram API and config persistence helpers
+ * Wraps bot API calls, file downloads, and local config reads and writes for the bridge runtime
+ */
+
+import { mkdir, readFile, writeFile } from "node:fs/promises";
+import { join } from "node:path";
+
+export interface TelegramConfig {
+  botToken?: string;
+  botUsername?: string;
+  botId?: number;
+  allowedUserId?: number;
+  lastUpdateId?: number;
+}
+
+interface TelegramApiResponse<T> {
+  ok: boolean;
+  result?: T;
+  description?: string;
+  error_code?: number;
+}
+
+interface TelegramGetFileResult {
+  file_path: string;
+}
+
+export interface TelegramApiClient {
+  call: <TResponse>(
+    method: string,
+    body: Record<string, unknown>,
+    options?: { signal?: AbortSignal },
+  ) => Promise<TResponse>;
+  callMultipart: <TResponse>(
+    method: string,
+    fields: Record<string, string>,
+    fileField: string,
+    filePath: string,
+    fileName: string,
+    options?: { signal?: AbortSignal },
+  ) => Promise<TResponse>;
+  downloadFile: (
+    fileId: string,
+    suggestedName: string,
+    tempDir: string,
+  ) => Promise<string>;
+  answerCallbackQuery: (
+    callbackQueryId: string,
+    text?: string,
+  ) => Promise<void>;
+}
+
+function sanitizeFileName(name: string): string {
+  return name.replace(/[^a-zA-Z0-9._-]+/g, "_");
+}
+
+export async function readTelegramConfig(
+  configPath: string,
+): Promise<TelegramConfig> {
+  try {
+    const content = await readFile(configPath, "utf8");
+    return JSON.parse(content) as TelegramConfig;
+  } catch {
+    return {};
+  }
+}
+
+export async function writeTelegramConfig(
+  agentDir: string,
+  configPath: string,
+  config: TelegramConfig,
+): Promise<void> {
+  await mkdir(agentDir, { recursive: true });
+  await writeFile(
+    configPath,
+    JSON.stringify(config, null, "\t") + "\n",
+    "utf8",
+  );
+}
+
+export async function callTelegram<TResponse>(
+  botToken: string | undefined,
+  method: string,
+  body: Record<string, unknown>,
+  options?: { signal?: AbortSignal },
+): Promise<TResponse> {
+  if (!botToken) {
+    throw new Error("Telegram bot token is not configured");
+  }
+  const response = await fetch(
+    `https://api.telegram.org/bot${botToken}/${method}`,
+    {
+      method: "POST",
+      headers: { "content-type": "application/json" },
+      body: JSON.stringify(body),
+      signal: options?.signal,
+    },
+  );
+  const data = (await response.json()) as TelegramApiResponse<TResponse>;
+  if (!data.ok || data.result === undefined) {
+    throw new Error(data.description || `Telegram API ${method} failed`);
+  }
+  return data.result;
+}
+
+export async function callTelegramMultipart<TResponse>(
+  botToken: string | undefined,
+  method: string,
+  fields: Record<string, string>,
+  fileField: string,
+  filePath: string,
+  fileName: string,
+  options?: { signal?: AbortSignal },
+): Promise<TResponse> {
+  if (!botToken) {
+    throw new Error("Telegram bot token is not configured");
+  }
+  const form = new FormData();
+  for (const [key, value] of Object.entries(fields)) {
+    form.set(key, value);
+  }
+  const buffer = await readFile(filePath);
+  form.set(fileField, new Blob([buffer]), fileName);
+  const response = await fetch(
+    `https://api.telegram.org/bot${botToken}/${method}`,
+    {
+      method: "POST",
+      body: form,
+      signal: options?.signal,
+    },
+  );
+  const data = (await response.json()) as TelegramApiResponse<TResponse>;
+  if (!data.ok || data.result === undefined) {
+    throw new Error(data.description || `Telegram API ${method} failed`);
+  }
+  return data.result;
+}
+
+export async function downloadTelegramFile(
+  botToken: string | undefined,
+  fileId: string,
+  suggestedName: string,
+  tempDir: string,
+): Promise<string> {
+  if (!botToken) {
+    throw new Error("Telegram bot token is not configured");
+  }
+  const file = await callTelegram<TelegramGetFileResult>(botToken, "getFile", {
+    file_id: fileId,
+  });
+  await mkdir(tempDir, { recursive: true });
+  const targetPath = join(
+    tempDir,
+    `${Date.now()}-${sanitizeFileName(suggestedName)}`,
+  );
+  const response = await fetch(
+    `https://api.telegram.org/file/bot${botToken}/${file.file_path}`,
+  );
+  if (!response.ok) {
+    throw new Error(`Failed to download Telegram file: ${response.status}`);
+  }
+  const arrayBuffer = await response.arrayBuffer();
+  await writeFile(targetPath, Buffer.from(arrayBuffer));
+  return targetPath;
+}
+
+export async function answerTelegramCallbackQuery(
+  botToken: string | undefined,
+  callbackQueryId: string,
+  text?: string,
+): Promise<void> {
+  try {
+    await callTelegram<boolean>(
+      botToken,
+      "answerCallbackQuery",
+      text
+        ? { callback_query_id: callbackQueryId, text }
+        : { callback_query_id: callbackQueryId },
+    );
+  } catch {
+    // ignore
+  }
+}
+
+export function createTelegramApiClient(
+  getBotToken: () => string | undefined,
+): TelegramApiClient {
+  return {
+    call: async (method, body, options) => {
+      return callTelegram(getBotToken(), method, body, options);
+    },
+    callMultipart: async (
+      method,
+      fields,
+      fileField,
+      filePath,
+      fileName,
+      options,
+    ) => {
+      return callTelegramMultipart(
+        getBotToken(),
+        method,
+        fields,
+        fileField,
+        filePath,
+        fileName,
+        options,
+      );
+    },
+    downloadFile: async (fileId, suggestedName, tempDir) => {
+      return downloadTelegramFile(
+        getBotToken(),
+        fileId,
+        suggestedName,
+        tempDir,
+      );
+    },
+    answerCallbackQuery: async (callbackQueryId, text) => {
+      await answerTelegramCallbackQuery(getBotToken(), callbackQueryId, text);
+    },
+  };
+}

package/lib/attachments.ts

@@ -0,0 +1,98 @@
+/**
+ * Telegram attachment domain helpers
+ * Owns attachment queueing and attachment delivery so Telegram file output stays in one domain module
+ */
+
+import { basename } from "node:path";
+
+import { guessMediaType } from "./media.ts";
+import type { PendingTelegramTurn } from "./queue.ts";
+
+export interface TelegramAttachmentToolResult {
+  content: Array<{ type: "text"; text: string }>;
+  details: { paths: string[] };
+}
+
+export interface TelegramQueuedAttachmentDeliveryDeps {
+  sendMultipart: (
+    method: string,
+    fields: Record<string, string>,
+    fileField: string,
+    filePath: string,
+    fileName: string,
+  ) => Promise<unknown>;
+  sendTextReply: (
+    chatId: number,
+    replyToMessageId: number,
+    text: string,
+  ) => Promise<unknown>;
+}
+
+export async function queueTelegramAttachments(options: {
+  activeTurn: PendingTelegramTurn | undefined;
+  paths: string[];
+  maxAttachmentsPerTurn: number;
+  statPath: (path: string) => Promise<{ isFile(): boolean }>;
+}): Promise<TelegramAttachmentToolResult> {
+  if (!options.activeTurn) {
+    throw new Error(
+      "telegram_attach can only be used while replying to an active Telegram turn",
+    );
+  }
+  const added: string[] = [];
+  for (const inputPath of options.paths) {
+    const stats = await options.statPath(inputPath);
+    if (!stats.isFile()) {
+      throw new Error(`Not a file: ${inputPath}`);
+    }
+    if (
+      options.activeTurn.queuedAttachments.length >=
+      options.maxAttachmentsPerTurn
+    ) {
+      throw new Error(
+        `Attachment limit reached (${options.maxAttachmentsPerTurn})`,
+      );
+    }
+    options.activeTurn.queuedAttachments.push({
+      path: inputPath,
+      fileName: basename(inputPath),
+    });
+    added.push(inputPath);
+  }
+  return {
+    content: [
+      {
+        type: "text",
+        text: `Queued ${added.length} Telegram attachment(s).`,
+      },
+    ],
+    details: { paths: added },
+  };
+}
+
+export async function sendQueuedTelegramAttachments(
+  turn: PendingTelegramTurn,
+  deps: TelegramQueuedAttachmentDeliveryDeps,
+): Promise<void> {
+  for (const attachment of turn.queuedAttachments) {
+    try {
+      const mediaType = guessMediaType(attachment.path);
+      const method = mediaType ? "sendPhoto" : "sendDocument";
+      const fieldName = mediaType ? "photo" : "document";
+      await deps.sendMultipart(
+        method,
+        { chat_id: String(turn.chatId) },
+        fieldName,
+        attachment.path,
+        attachment.fileName,
+      );
+    } catch (error) {
+      const message = error instanceof Error ? error.message : String(error);
+      await deps.sendTextReply(
+        turn.chatId,
+        turn.replyToMessageId,
+        `Failed to send attachment ${attachment.fileName}: ${message}`,
+      );
+    }
+  }
+}

package/lib/media.ts

@@ -0,0 +1,234 @@
+/**
+ * Telegram media and text extraction helpers
+ * Normalizes inbound Telegram messages into reusable file, text, id, and history metadata
+ */
+
+export interface TelegramPhotoSizeLike {
+  file_id: string;
+  file_size?: number;
+}
+
+export interface TelegramDocumentLike {
+  file_id: string;
+  file_name?: string;
+  mime_type?: string;
+}
+
+export interface TelegramVideoLike {
+  file_id: string;
+  file_name?: string;
+  mime_type?: string;
+}
+
+export interface TelegramAudioLike {
+  file_id: string;
+  file_name?: string;
+  mime_type?: string;
+}
+
+export interface TelegramVoiceLike {
+  file_id: string;
+  mime_type?: string;
+}
+
+export interface TelegramAnimationLike {
+  file_id: string;
+  file_name?: string;
+  mime_type?: string;
+}
+
+export interface TelegramStickerLike {
+  file_id: string;
+}
+
+export interface TelegramMessageLike {
+  message_id: number;
+  text?: string;
+  caption?: string;
+  photo?: TelegramPhotoSizeLike[];
+  document?: TelegramDocumentLike;
+  video?: TelegramVideoLike;
+  audio?: TelegramAudioLike;
+  voice?: TelegramVoiceLike;
+  animation?: TelegramAnimationLike;
+  sticker?: TelegramStickerLike;
+}
+
+export interface TelegramFileInfo {
+  file_id: string;
+  fileName: string;
+  mimeType?: string;
+  isImage: boolean;
+}
+
+export interface DownloadedTelegramFileLike {
+  path: string;
+}
+
+export function guessExtensionFromMime(
+  mimeType: string | undefined,
+  fallback: string,
+): string {
+  if (!mimeType) return fallback;
+  const normalized = mimeType.toLowerCase();
+  if (normalized === "image/jpeg") return ".jpg";
+  if (normalized === "image/png") return ".png";
+  if (normalized === "image/webp") return ".webp";
+  if (normalized === "image/gif") return ".gif";
+  if (normalized === "audio/ogg") return ".ogg";
+  if (normalized === "audio/mpeg") return ".mp3";
+  if (normalized === "audio/wav") return ".wav";
+  if (normalized === "video/mp4") return ".mp4";
+  if (normalized === "application/pdf") return ".pdf";
+  return fallback;
+}
+
+export function guessMediaType(path: string): string | undefined {
+  const normalized = path.toLowerCase();
+  if (normalized.endsWith(".jpg") || normalized.endsWith(".jpeg")) {
+    return "image/jpeg";
+  }
+  if (normalized.endsWith(".png")) return "image/png";
+  if (normalized.endsWith(".webp")) return "image/webp";
+  if (normalized.endsWith(".gif")) return "image/gif";
+  return undefined;
+}
+
+export function isImageMimeType(mimeType: string | undefined): boolean {
+  return mimeType?.toLowerCase().startsWith("image/") ?? false;
+}
+
+export function extractTelegramMessageText(
+  message: TelegramMessageLike,
+): string {
+  return (message.text || message.caption || "").trim();
+}
+
+export function extractTelegramMessagesText(
+  messages: TelegramMessageLike[],
+): string {
+  return messages.map(extractTelegramMessageText).filter(Boolean).join("\n\n");
+}
+
+export function extractFirstTelegramMessageText(
+  messages: TelegramMessageLike[],
+): string {
+  return messages.map(extractTelegramMessageText).find(Boolean) ?? "";
+}
+
+export function collectTelegramMessageIds(
+  messages: TelegramMessageLike[],
+): number[] {
+  return [...new Set(messages.map((message) => message.message_id))];
+}
+
+export function formatTelegramHistoryText(
+  rawText: string,
+  files: DownloadedTelegramFileLike[],
+): string {
+  let summary = rawText.length > 0 ? rawText : "(no text)";
+  if (files.length > 0) {
+    summary += `\nAttachments:`;
+    for (const file of files) {
+      summary += `\n- ${file.path}`;
+    }
+  }
+  return summary;
+}
+
+export function collectTelegramFileInfos(
+  messages: TelegramMessageLike[],
+): TelegramFileInfo[] {
+  const files: TelegramFileInfo[] = [];
+  for (const message of messages) {
+    if (Array.isArray(message.photo) && message.photo.length > 0) {
+      const photo = [...message.photo]
+        .sort((a, b) => (a.file_size ?? 0) - (b.file_size ?? 0))
+        .pop();
+      if (photo) {
+        files.push({
+          file_id: photo.file_id,
+          fileName: `photo-${message.message_id}.jpg`,
+          mimeType: "image/jpeg",
+          isImage: true,
+        });
+      }
+    }
+    if (message.document) {
+      const fileName =
+        message.document.file_name ||
+        `document-${message.message_id}${guessExtensionFromMime(
+          message.document.mime_type,
+          "",
+        )}`;
+      files.push({
+        file_id: message.document.file_id,
+        fileName,
+        mimeType: message.document.mime_type,
+        isImage: isImageMimeType(message.document.mime_type),
+      });
+    }
+    if (message.video) {
+      const fileName =
+        message.video.file_name ||
+        `video-${message.message_id}${guessExtensionFromMime(
+          message.video.mime_type,
+          ".mp4",
+        )}`;
+      files.push({
+        file_id: message.video.file_id,
+        fileName,
+        mimeType: message.video.mime_type,
+        isImage: false,
+      });
+    }
+    if (message.audio) {
+      const fileName =
+        message.audio.file_name ||
+        `audio-${message.message_id}${guessExtensionFromMime(
+          message.audio.mime_type,
+          ".mp3",
+        )}`;
+      files.push({
+        file_id: message.audio.file_id,
+        fileName,
+        mimeType: message.audio.mime_type,
+        isImage: false,
+      });
+    }
+    if (message.voice) {
+      files.push({
+        file_id: message.voice.file_id,
+        fileName: `voice-${message.message_id}${guessExtensionFromMime(
+          message.voice.mime_type,
+          ".ogg",
+        )}`,
+        mimeType: message.voice.mime_type,
+        isImage: false,
+      });
+    }
+    if (message.animation) {
+      const fileName =
+        message.animation.file_name ||
+        `animation-${message.message_id}${guessExtensionFromMime(
+          message.animation.mime_type,
+          ".mp4",
+        )}`;
+      files.push({
+        file_id: message.animation.file_id,
+        fileName,
+        mimeType: message.animation.mime_type,
+        isImage: false,
+      });
+    }
+    if (message.sticker) {
+      files.push({
+        file_id: message.sticker.file_id,
+        fileName: `sticker-${message.message_id}.webp`,
+        mimeType: "image/webp",
+        isImage: true,
+      });
+    }
+  }
+  return files;
+}