@llblab/pi-telegram 0.2.8 → 0.2.10

package/lib/api.ts

@@ -3,8 +3,19 @@
  * 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 { randomUUID } from "node:crypto";
+import { createWriteStream, openAsBlob } from "node:fs";
+import {
+  mkdir,
+  readFile,
+  readdir,
+  stat,
+  unlink,
+  writeFile,
+} from "node:fs/promises";
 import { join } from "node:path";
+import { Readable, Transform } from "node:stream";
+import { pipeline } from "node:stream/promises";
 
 export interface TelegramConfig {
   botToken?: string;
@@ -19,17 +30,31 @@ interface TelegramApiResponse<T> {
   result?: T;
   description?: string;
   error_code?: number;
+  parameters?: { retry_after?: number };
+}
+
+export interface TelegramApiCallOptions {
+  signal?: AbortSignal;
+  maxAttempts?: number;
+  retryBaseDelayMs?: number;
+  sleep?: (ms: number) => Promise<void>;
 }
 
 interface TelegramGetFileResult {
   file_path: string;
+  file_size?: number;
+}
+
+export interface TelegramFileDownloadOptions {
+  signal?: AbortSignal;
+  maxFileSizeBytes?: number;
 }
 
 export interface TelegramApiClient {
   call: <TResponse>(
     method: string,
     body: Record<string, unknown>,
-    options?: { signal?: AbortSignal },
+    options?: TelegramApiCallOptions,
   ) => Promise<TResponse>;
   callMultipart: <TResponse>(
     method: string,
@@ -37,12 +62,13 @@ export interface TelegramApiClient {
     fileField: string,
     filePath: string,
     fileName: string,
-    options?: { signal?: AbortSignal },
+    options?: TelegramApiCallOptions,
   ) => Promise<TResponse>;
   downloadFile: (
     fileId: string,
     suggestedName: string,
     tempDir: string,
+    options?: TelegramFileDownloadOptions,
   ) => Promise<string>;
   answerCallbackQuery: (
     callbackQueryId: string,
@@ -54,6 +80,173 @@ function sanitizeFileName(name: string): string {
   return name.replace(/[^a-zA-Z0-9._-]+/g, "_");
 }
 
+class TelegramApiHttpError extends Error {
+  readonly status: number | undefined;
+  readonly retryAfterSeconds: number | undefined;
+  constructor(
+    message: string,
+    status: number | undefined,
+    retryAfterSeconds: number | undefined,
+  ) {
+    super(message);
+    this.status = status;
+    this.retryAfterSeconds = retryAfterSeconds;
+  }
+}
+
+function isRetryableTelegramApiError(error: unknown): boolean {
+  return (
+    error instanceof TelegramApiHttpError &&
+    (error.status === 429 ||
+      (error.status !== undefined && error.status >= 500))
+  );
+}
+
+function getTelegramRetryDelayMs(
+  error: unknown,
+  attempt: number,
+  baseDelayMs: number,
+): number {
+  if (
+    error instanceof TelegramApiHttpError &&
+    error.retryAfterSeconds !== undefined
+  ) {
+    return Math.max(0, error.retryAfterSeconds * 1000);
+  }
+  return Math.max(0, baseDelayMs * 2 ** attempt);
+}
+
+function sleepTelegramRetry(ms: number): Promise<void> {
+  return new Promise((resolve) => setTimeout(resolve, ms));
+}
+
+function assertTelegramFileSizeWithinLimit(
+  size: number | undefined,
+  maxFileSizeBytes: number | undefined,
+): void {
+  if (size === undefined || maxFileSizeBytes === undefined) return;
+  if (size <= maxFileSizeBytes) return;
+  throw new Error(
+    `Telegram file exceeds size limit (${size} bytes > ${maxFileSizeBytes} bytes)`,
+  );
+}
+
+function createTelegramDownloadLimitTransform(
+  maxFileSizeBytes: number | undefined,
+): Transform {
+  let downloadedBytes = 0;
+  return new Transform({
+    transform(chunk: Buffer, _encoding, callback) {
+      downloadedBytes += chunk.byteLength;
+      try {
+        assertTelegramFileSizeWithinLimit(downloadedBytes, maxFileSizeBytes);
+        callback(undefined, chunk);
+      } catch (error) {
+        callback(error instanceof Error ? error : new Error(String(error)));
+      }
+    },
+  });
+}
+
+async function writeTelegramDownloadResponse(
+  response: Response,
+  targetPath: string,
+  maxFileSizeBytes: number | undefined,
+): Promise<void> {
+  if (!response.body) {
+    const buffer = Buffer.from(await response.arrayBuffer());
+    assertTelegramFileSizeWithinLimit(buffer.byteLength, maxFileSizeBytes);
+    await writeFile(targetPath, buffer);
+    return;
+  }
+  await pipeline(
+    Readable.fromWeb(
+      response.body as unknown as Parameters<typeof Readable.fromWeb>[0],
+    ),
+    createTelegramDownloadLimitTransform(maxFileSizeBytes),
+    createWriteStream(targetPath),
+  );
+}
+
+async function removeTelegramPartialDownload(path: string): Promise<void> {
+  try {
+    await unlink(path);
+  } catch {
+    // ignore
+  }
+}
+
+async function parseTelegramApiResponse<TResponse>(
+  response: Response,
+  method: string,
+): Promise<TelegramApiResponse<TResponse>> {
+  let data: TelegramApiResponse<TResponse> | undefined;
+  try {
+    if (typeof response.text === "function") {
+      const text = await response.text();
+      data = text
+        ? (JSON.parse(text) as TelegramApiResponse<TResponse>)
+        : undefined;
+    } else {
+      data = (await response.json()) as TelegramApiResponse<TResponse>;
+    }
+  } catch {
+    data = undefined;
+  }
+  if (response.ok === false) {
+    const status = `HTTP ${response.status}`;
+    const description = data?.description ? `: ${data.description}` : "";
+    const retryAfterHeader = response.headers?.get("retry-after");
+    const retryAfterSeconds =
+      data?.parameters?.retry_after ??
+      (retryAfterHeader ? Number.parseInt(retryAfterHeader, 10) : undefined);
+    throw new TelegramApiHttpError(
+      `Telegram API ${method} failed: ${status}${description}`,
+      response.status,
+      Number.isFinite(retryAfterSeconds) ? retryAfterSeconds : undefined,
+    );
+  }
+  return (
+    data ?? {
+      ok: false,
+      description: `Telegram API ${method} returned invalid JSON`,
+    }
+  );
+}
+
+function unwrapTelegramApiResult<TResponse>(
+  method: string,
+  data: TelegramApiResponse<TResponse>,
+): TResponse {
+  if (!data.ok || data.result === undefined) {
+    throw new Error(data.description || `Telegram API ${method} failed`);
+  }
+  return data.result;
+}
+
+async function callTelegramWithRetry<TResponse>(
+  method: string,
+  request: () => Promise<Response>,
+  options: TelegramApiCallOptions | undefined,
+): Promise<TResponse> {
+  const maxAttempts = Math.max(1, options?.maxAttempts ?? 3);
+  const retryBaseDelayMs = options?.retryBaseDelayMs ?? 500;
+  const sleep = options?.sleep ?? sleepTelegramRetry;
+  for (let attempt = 0; ; attempt += 1) {
+    try {
+      return unwrapTelegramApiResult(
+        method,
+        await parseTelegramApiResponse<TResponse>(await request(), method),
+      );
+    } catch (error) {
+      if (attempt >= maxAttempts - 1 || !isRetryableTelegramApiError(error)) {
+        throw error;
+      }
+      await sleep(getTelegramRetryDelayMs(error, attempt, retryBaseDelayMs));
+    }
+  }
+}
+
 export async function readTelegramConfig(
   configPath: string,
 ): Promise<TelegramConfig> {
@@ -78,29 +271,53 @@ export async function writeTelegramConfig(
   );
 }
 
+export async function cleanupTelegramTempFiles(
+  tempDir: string,
+  maxAgeMs: number,
+  now = Date.now(),
+): Promise<number> {
+  let removedCount = 0;
+  let entries: Array<{ isFile(): boolean; name: string }>;
+  try {
+    entries = await readdir(tempDir, { withFileTypes: true });
+  } catch {
+    return 0;
+  }
+  for (const entry of entries) {
+    if (!entry.isFile()) continue;
+    const path = join(tempDir, entry.name);
+    try {
+      const stats = await stat(path);
+      if (now - stats.mtimeMs <= maxAgeMs) continue;
+      await unlink(path);
+      removedCount += 1;
+    } catch {
+      // ignore
+    }
+  }
+  return removedCount;
+}
+
 export async function callTelegram<TResponse>(
   botToken: string | undefined,
   method: string,
   body: Record<string, unknown>,
-  options?: { signal?: AbortSignal },
+  options?: TelegramApiCallOptions,
 ): 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,
-    },
+  return callTelegramWithRetry(
+    method,
+    async () =>
+      fetch(`https://api.telegram.org/bot${botToken}/${method}`, {
+        method: "POST",
+        headers: { "content-type": "application/json" },
+        body: JSON.stringify(body),
+        signal: options?.signal,
+      }),
+    options,
   );
-  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>(
@@ -110,30 +327,28 @@ export async function callTelegramMultipart<TResponse>(
   fileField: string,
   filePath: string,
   fileName: string,
-  options?: { signal?: AbortSignal },
+  options?: TelegramApiCallOptions,
 ): 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 fileBlob = await openAsBlob(filePath);
+  return callTelegramWithRetry(
+    method,
+    async () => {
+      const form = new FormData();
+      for (const [key, value] of Object.entries(fields)) {
+        form.set(key, value);
+      }
+      form.set(fileField, fileBlob, fileName);
+      return fetch(`https://api.telegram.org/bot${botToken}/${method}`, {
+        method: "POST",
+        body: form,
+        signal: options?.signal,
+      });
     },
+    options,
   );
-  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(
@@ -141,26 +356,45 @@ export async function downloadTelegramFile(
   fileId: string,
   suggestedName: string,
   tempDir: string,
+  options?: TelegramFileDownloadOptions,
 ): Promise<string> {
   if (!botToken) {
     throw new Error("Telegram bot token is not configured");
   }
-  const file = await callTelegram<TelegramGetFileResult>(botToken, "getFile", {
-    file_id: fileId,
-  });
+  const file = await callTelegram<TelegramGetFileResult>(
+    botToken,
+    "getFile",
+    { file_id: fileId },
+    { signal: options?.signal },
+  );
+  assertTelegramFileSizeWithinLimit(file.file_size, options?.maxFileSizeBytes);
   await mkdir(tempDir, { recursive: true });
   const targetPath = join(
     tempDir,
-    `${Date.now()}-${sanitizeFileName(suggestedName)}`,
+    `${randomUUID()}-${sanitizeFileName(suggestedName)}`,
   );
   const response = await fetch(
     `https://api.telegram.org/file/bot${botToken}/${file.file_path}`,
+    { signal: options?.signal },
   );
   if (!response.ok) {
     throw new Error(`Failed to download Telegram file: ${response.status}`);
   }
-  const arrayBuffer = await response.arrayBuffer();
-  await writeFile(targetPath, Buffer.from(arrayBuffer));
+  const contentLength = response.headers?.get("content-length");
+  assertTelegramFileSizeWithinLimit(
+    contentLength ? Number.parseInt(contentLength, 10) : undefined,
+    options?.maxFileSizeBytes,
+  );
+  try {
+    await writeTelegramDownloadResponse(
+      response,
+      targetPath,
+      options?.maxFileSizeBytes,
+    );
+  } catch (error) {
+    await removeTelegramPartialDownload(targetPath);
+    throw error;
+  }
   return targetPath;
 }
 
@@ -207,12 +441,13 @@ export function createTelegramApiClient(
         options,
       );
     },
-    downloadFile: async (fileId, suggestedName, tempDir) => {
+    downloadFile: async (fileId, suggestedName, tempDir, options) => {
       return downloadTelegramFile(
         getBotToken(),
         fileId,
         suggestedName,
         tempDir,
+        options,
       );
     },
     answerCallbackQuery: async (callbackQueryId, text) => {

package/lib/commands.ts

@@ -0,0 +1,87 @@
+/**
+ * Telegram command parsing helpers
+ * Owns slash-command normalization so command routing stays separate from transport update handling
+ */
+
+export interface ParsedTelegramCommand {
+  name: string;
+  args: string;
+}
+
+export type TelegramCommandAction =
+  | { kind: "ignore" }
+  | { kind: "stop" }
+  | { kind: "compact" }
+  | { kind: "status" }
+  | { kind: "model" }
+  | { kind: "help"; commandName: "help" | "start" };
+
+export interface TelegramCommandActionDeps<TMessage, TContext> {
+  handleStop: (message: TMessage, ctx: TContext) => Promise<void>;
+  handleCompact: (message: TMessage, ctx: TContext) => Promise<void>;
+  handleStatus: (message: TMessage, ctx: TContext) => Promise<void>;
+  handleModel: (message: TMessage, ctx: TContext) => Promise<void>;
+  handleHelp: (
+    message: TMessage,
+    commandName: "help" | "start",
+    ctx: TContext,
+  ) => Promise<void>;
+}
+
+export function parseTelegramCommand(
+  text: string,
+): ParsedTelegramCommand | undefined {
+  const trimmed = text.trim();
+  if (!trimmed.startsWith("/")) return undefined;
+  const [head, ...tail] = trimmed.split(/\s+/);
+  const name = head.slice(1).split("@")[0]?.toLowerCase();
+  if (!name) return undefined;
+  return { name, args: tail.join(" ").trim() };
+}
+
+export function buildTelegramCommandAction(
+  commandName: string | undefined,
+): TelegramCommandAction {
+  switch (commandName) {
+    case "stop":
+      return { kind: "stop" };
+    case "compact":
+      return { kind: "compact" };
+    case "status":
+      return { kind: "status" };
+    case "model":
+      return { kind: "model" };
+    case "help":
+    case "start":
+      return { kind: "help", commandName };
+    default:
+      return { kind: "ignore" };
+  }
+}
+
+export async function executeTelegramCommandAction<TMessage, TContext>(
+  action: TelegramCommandAction,
+  message: TMessage,
+  ctx: TContext,
+  deps: TelegramCommandActionDeps<TMessage, TContext>,
+): Promise<boolean> {
+  switch (action.kind) {
+    case "ignore":
+      return false;
+    case "stop":
+      await deps.handleStop(message, ctx);
+      return true;
+    case "compact":
+      await deps.handleCompact(message, ctx);
+      return true;
+    case "status":
+      await deps.handleStatus(message, ctx);
+      return true;
+    case "model":
+      await deps.handleModel(message, ctx);
+      return true;
+    case "help":
+      await deps.handleHelp(message, action.commandName, ctx);
+      return true;
+  }
+}

package/lib/media.ts

@@ -1,6 +1,6 @@
 /**
  * Telegram media and text extraction helpers
- * Normalizes inbound Telegram messages into reusable file, text, id, and history metadata
+ * Normalizes inbound Telegram messages into reusable file, text, id, history, and media-group metadata
  */
 
 export interface TelegramPhotoSizeLike {
@@ -45,6 +45,7 @@ export interface TelegramMessageLike {
   message_id: number;
   text?: string;
   caption?: string;
+  media_group_id?: string;
   photo?: TelegramPhotoSizeLike[];
   document?: TelegramDocumentLike;
   video?: TelegramVideoLike;
@@ -54,6 +55,17 @@ export interface TelegramMessageLike {
   sticker?: TelegramStickerLike;
 }
 
+export interface TelegramMediaGroupMessageLike {
+  message_id: number;
+  chat: { id: number };
+  media_group_id?: string;
+}
+
+export interface TelegramMediaGroupState<TMessage> {
+  messages: TMessage[];
+  flushTimer?: ReturnType<typeof setTimeout>;
+}
+
 export interface TelegramFileInfo {
   file_id: string;
   fileName: string;
@@ -122,6 +134,63 @@ export function collectTelegramMessageIds(
   return [...new Set(messages.map((message) => message.message_id))];
 }
 
+export function getTelegramMediaGroupKey(
+  message: TelegramMediaGroupMessageLike,
+): string | undefined {
+  if (!message.media_group_id) return undefined;
+  return `${message.chat.id}:${message.media_group_id}`;
+}
+
+export function removePendingTelegramMediaGroupMessages<
+  TMessage extends TelegramMediaGroupMessageLike,
+>(
+  groups: Map<string, TelegramMediaGroupState<TMessage>>,
+  messageIds: number[],
+  clearTimer: (timer: ReturnType<typeof setTimeout>) => void,
+): number {
+  if (messageIds.length === 0 || groups.size === 0) return 0;
+  const deletedMessageIds = new Set(messageIds);
+  let removedGroups = 0;
+  for (const [key, state] of groups.entries()) {
+    if (
+      !state.messages.some((message) =>
+        deletedMessageIds.has(message.message_id),
+      )
+    ) {
+      continue;
+    }
+    if (state.flushTimer) clearTimer(state.flushTimer);
+    groups.delete(key);
+    removedGroups += 1;
+  }
+  return removedGroups;
+}
+
+export function queueTelegramMediaGroupMessage<
+  TMessage extends TelegramMediaGroupMessageLike,
+>(options: {
+  message: TMessage;
+  groups: Map<string, TelegramMediaGroupState<TMessage>>;
+  debounceMs: number;
+  setTimer: (callback: () => void, ms: number) => ReturnType<typeof setTimeout>;
+  clearTimer: (timer: ReturnType<typeof setTimeout>) => void;
+  dispatchMessages: (messages: TMessage[]) => void;
+}): boolean {
+  const key = getTelegramMediaGroupKey(options.message);
+  if (!key) return false;
+  const existing = options.groups.get(key) ?? { messages: [] };
+  existing.messages.push(options.message);
+  if (existing.flushTimer) options.clearTimer(existing.flushTimer);
+  existing.flushTimer = options.setTimer(() => {
+    const state = options.groups.get(key);
+    options.groups.delete(key);
+    if (!state) return;
+    options.dispatchMessages(state.messages);
+  }, options.debounceMs);
+  options.groups.set(key, existing);
+  return true;
+}
+
 export function formatTelegramHistoryText(
   rawText: string,
   files: DownloadedTelegramFileLike[],

package/lib/polling.ts

@@ -76,6 +76,11 @@ export interface TelegramPollLoopDeps<TUpdate extends TelegramUpdateLike> {
   onErrorStatus: (message: string) => void;
   onStatusReset: () => void;
   sleep: (ms: number) => Promise<void>;
+  maxUpdateFailures?: number;
+}
+
+function getTelegramPollingErrorMessage(error: unknown): string {
+  return error instanceof Error ? error.message : String(error);
 }
 
 export async function runTelegramPollLoop<TUpdate extends TelegramUpdateLike>(
@@ -102,6 +107,8 @@ export async function runTelegramPollLoop<TUpdate extends TelegramUpdateLike>(
       // ignore
     }
   }
+  const maxUpdateFailures = Math.max(1, deps.maxUpdateFailures ?? 3);
+  const updateFailures = new Map<number, number>();
   while (!deps.signal.aborted) {
     try {
       const updates = await deps.getUpdates(
@@ -109,14 +116,27 @@ export async function runTelegramPollLoop<TUpdate extends TelegramUpdateLike>(
         deps.signal,
       );
       for (const update of updates) {
-        deps.config.lastUpdateId = update.update_id;
-        await deps.persistConfig();
-        await deps.handleUpdate(update, deps.ctx);
+        try {
+          await deps.handleUpdate(update, deps.ctx);
+          deps.config.lastUpdateId = update.update_id;
+          updateFailures.delete(update.update_id);
+          await deps.persistConfig();
+        } catch (error) {
+          const failureCount = (updateFailures.get(update.update_id) ?? 0) + 1;
+          updateFailures.set(update.update_id, failureCount);
+          if (failureCount < maxUpdateFailures) throw error;
+          const message = getTelegramPollingErrorMessage(error);
+          deps.onErrorStatus(
+            `skipping Telegram update ${update.update_id} after ${failureCount} failures: ${message}`,
+          );
+          deps.config.lastUpdateId = update.update_id;
+          updateFailures.delete(update.update_id);
+          await deps.persistConfig();
+        }
       }
     } catch (error) {
       if (shouldStopTelegramPolling(deps.signal.aborted, error)) return;
-      const message = error instanceof Error ? error.message : String(error);
-      deps.onErrorStatus(message);
+      deps.onErrorStatus(getTelegramPollingErrorMessage(error));
       await deps.sleep(3000);
       deps.onStatusReset();
     }