@llblab/pi-telegram 0.2.8 → 0.2.10

package/tests/api.test.ts

@@ -4,7 +4,7 @@
  */
 
 import assert from "node:assert/strict";
-import { mkdtemp, readFile } from "node:fs/promises";
+import { mkdir, mkdtemp, readFile, readdir, utimes, writeFile } from "node:fs/promises";
 import { tmpdir } from "node:os";
 import { join } from "node:path";
 import test from "node:test";
@@ -12,6 +12,8 @@ import test from "node:test";
 import {
   answerTelegramCallbackQuery,
   callTelegram,
+  callTelegramMultipart,
+  cleanupTelegramTempFiles,
   createTelegramApiClient,
   downloadTelegramFile,
   readTelegramConfig,
@@ -33,6 +35,21 @@ test("Telegram config helpers persist and reload config", async () => {
   assert.match(raw, /demo_bot/);
 });
 
+test("Telegram temp cleanup removes only stale files", async () => {
+  const tempDir = await mkdtemp(join(tmpdir(), "pi-telegram-cleanup-"));
+  const oldFile = join(tempDir, "old.txt");
+  const freshFile = join(tempDir, "fresh.txt");
+  const nestedDir = join(tempDir, "nested");
+  await writeFile(oldFile, "old", "utf8");
+  await writeFile(freshFile, "fresh", "utf8");
+  await mkdir(nestedDir);
+  await writeFile(join(nestedDir, "keep.txt"), "keep", "utf8");
+  await utimes(oldFile, new Date(1_000), new Date(1_000));
+  await utimes(freshFile, new Date(10_000), new Date(10_000));
+  assert.equal(await cleanupTelegramTempFiles(tempDir, 5_000, 11_000), 1);
+  assert.deepEqual((await readdir(tempDir)).sort(), ["fresh.txt", "nested"]);
+});
+
 test("Telegram API helpers reject missing bot token for direct calls", async () => {
   await assert.rejects(() => callTelegram(undefined, "getMe", {}), {
     message: "Telegram bot token is not configured",
@@ -51,6 +68,231 @@ test("Telegram API helpers reject missing bot token for direct calls", async ()
   );
 });
 
+test("Telegram API helpers include HTTP status details for failed responses", async () => {
+  const originalFetch = globalThis.fetch;
+  globalThis.fetch = (async () => {
+    return {
+      ok: false,
+      status: 429,
+      text: async () => JSON.stringify({ ok: false, description: "Too Many Requests" }),
+    } as Response;
+  }) as typeof fetch;
+  try {
+    await assert.rejects(
+      () => callTelegram("123:abc", "sendMessage", {}, { maxAttempts: 1 }),
+      {
+        message: "Telegram API sendMessage failed: HTTP 429: Too Many Requests",
+      },
+    );
+  } finally {
+    globalThis.fetch = originalFetch;
+  }
+});
+
+test("Telegram API helpers retry 429 and 5xx responses", async () => {
+  const originalFetch = globalThis.fetch;
+  const sleeps: number[] = [];
+  let calls = 0;
+  globalThis.fetch = (async () => {
+    calls += 1;
+    if (calls === 1) {
+      return {
+        ok: false,
+        status: 429,
+        headers: new Headers({ "retry-after": "2" }),
+        text: async () => JSON.stringify({ ok: false, description: "Too Many Requests" }),
+      } as Response;
+    }
+    if (calls === 2) {
+      return {
+        ok: false,
+        status: 502,
+        text: async () => JSON.stringify({ ok: false, description: "Bad Gateway" }),
+      } as Response;
+    }
+    return {
+      ok: true,
+      status: 200,
+      text: async () => JSON.stringify({ ok: true, result: "sent" }),
+    } as Response;
+  }) as typeof fetch;
+  try {
+    const result = await callTelegram<string>("123:abc", "sendMessage", {}, {
+      retryBaseDelayMs: 10,
+      sleep: async (ms) => {
+        sleeps.push(ms);
+      },
+    });
+    assert.equal(result, "sent");
+    assert.equal(calls, 3);
+    assert.deepEqual(sleeps, [2000, 20]);
+  } finally {
+    globalThis.fetch = originalFetch;
+  }
+});
+
+test("Telegram multipart API rebuilds forms for retryable responses", async () => {
+  const originalFetch = globalThis.fetch;
+  const tempDir = await mkdtemp(join(tmpdir(), "pi-telegram-upload-"));
+  const filePath = join(tempDir, "demo.txt");
+  await writeFile(filePath, "hello", "utf8");
+  const contentTypes: string[] = [];
+  let calls = 0;
+  globalThis.fetch = (async (_input, init) => {
+    calls += 1;
+    contentTypes.push((init?.body as FormData).get("document") instanceof Blob ? "blob" : "missing");
+    if (calls === 1) {
+      return {
+        ok: false,
+        status: 500,
+        text: async () => JSON.stringify({ ok: false, description: "Server Error" }),
+      } as Response;
+    }
+    return {
+      ok: true,
+      status: 200,
+      text: async () => JSON.stringify({ ok: true, result: true }),
+    } as Response;
+  }) as typeof fetch;
+  try {
+    assert.equal(
+      await callTelegramMultipart<boolean>(
+        "123:abc",
+        "sendDocument",
+        { chat_id: "1" },
+        "document",
+        filePath,
+        "demo.txt",
+        { retryBaseDelayMs: 0, sleep: async () => {} },
+      ),
+      true,
+    );
+    assert.equal(calls, 2);
+    assert.deepEqual(contentTypes, ["blob", "blob"]);
+  } finally {
+    globalThis.fetch = originalFetch;
+  }
+});
+
+test("Telegram file downloads use unique sanitized temp file names", async () => {
+  const originalFetch = globalThis.fetch;
+  const tempDir = await mkdtemp(join(tmpdir(), "pi-telegram-download-"));
+  globalThis.fetch = (async (input) => {
+    const url = typeof input === "string" ? input : input.toString();
+    if (url.includes("/getFile")) {
+      return {
+        ok: true,
+        status: 200,
+        text: async () =>
+          JSON.stringify({ ok: true, result: { file_path: "files/demo" } }),
+      } as Response;
+    }
+    return new Response("hello", { status: 200 });
+  }) as typeof fetch;
+  try {
+    const path = await downloadTelegramFile(
+      "123:abc",
+      "file-id",
+      "bad name?.txt",
+      tempDir,
+    );
+    assert.match(path, /[0-9a-f-]{36}-bad_name_\.txt$/);
+    assert.equal(await readFile(path, "utf8"), "hello");
+  } finally {
+    globalThis.fetch = originalFetch;
+  }
+});
+
+test("Telegram file downloads reject files above configured limits", async () => {
+  const originalFetch = globalThis.fetch;
+  const tempDir = await mkdtemp(join(tmpdir(), "pi-telegram-download-limit-"));
+  let calls = 0;
+  globalThis.fetch = (async (input) => {
+    calls += 1;
+    const url = typeof input === "string" ? input : input.toString();
+    if (url.includes("/getFile")) {
+      return {
+        ok: true,
+        status: 200,
+        text: async () =>
+          JSON.stringify({
+            ok: true,
+            result: { file_path: "files/demo", file_size: 10 },
+          }),
+      } as Response;
+    }
+    return new Response("too large", { status: 200 });
+  }) as typeof fetch;
+  try {
+    await assert.rejects(
+      () =>
+        downloadTelegramFile(
+          "123:abc",
+          "file-id",
+          "demo.txt",
+          tempDir,
+          { maxFileSizeBytes: 5 },
+        ),
+      { message: "Telegram file exceeds size limit (10 bytes > 5 bytes)" },
+    );
+    assert.equal(calls, 1);
+    assert.deepEqual(await readdir(tempDir), []);
+  } finally {
+    globalThis.fetch = originalFetch;
+  }
+});
+
+test("Telegram streaming downloads remove partial files after limit failures", async () => {
+  const originalFetch = globalThis.fetch;
+  const tempDir = await mkdtemp(join(tmpdir(), "pi-telegram-download-partial-"));
+  globalThis.fetch = (async (input) => {
+    const url = typeof input === "string" ? input : input.toString();
+    if (url.includes("/getFile")) {
+      return {
+        ok: true,
+        status: 200,
+        text: async () =>
+          JSON.stringify({ ok: true, result: { file_path: "files/demo" } }),
+      } as Response;
+    }
+    return new Response("too large", { status: 200 });
+  }) as typeof fetch;
+  try {
+    await assert.rejects(
+      () =>
+        downloadTelegramFile(
+          "123:abc",
+          "file-id",
+          "demo.txt",
+          tempDir,
+          { maxFileSizeBytes: 5 },
+        ),
+      { message: "Telegram file exceeds size limit (9 bytes > 5 bytes)" },
+    );
+    assert.deepEqual(await readdir(tempDir), []);
+  } finally {
+    globalThis.fetch = originalFetch;
+  }
+});
+
+test("Telegram API helpers reject malformed successful responses", async () => {
+  const originalFetch = globalThis.fetch;
+  globalThis.fetch = (async () => {
+    return {
+      ok: true,
+      status: 200,
+      text: async () => "not json",
+    } as Response;
+  }) as typeof fetch;
+  try {
+    await assert.rejects(() => callTelegram("123:abc", "getMe", {}), {
+      message: "Telegram API getMe returned invalid JSON",
+    });
+  } finally {
+    globalThis.fetch = originalFetch;
+  }
+});
+
 test("answerTelegramCallbackQuery ignores Telegram API failures", async () => {
   const originalFetch = globalThis.fetch;
   globalThis.fetch = (async () => {

package/tests/commands.test.ts

@@ -0,0 +1,85 @@
+/**
+ * Regression tests for Telegram command helpers
+ * Covers slash-command normalization, bot suffix stripping, arguments, and non-command input
+ */
+
+import assert from "node:assert/strict";
+import test from "node:test";
+
+import {
+  buildTelegramCommandAction,
+  executeTelegramCommandAction,
+  parseTelegramCommand,
+} from "../lib/commands.ts";
+
+test("Command helpers parse slash commands with args", () => {
+  assert.deepEqual(parseTelegramCommand(" /Model@DemoBot  claude opus "), {
+    name: "model",
+    args: "claude opus",
+  });
+  assert.deepEqual(parseTelegramCommand("/status"), {
+    name: "status",
+    args: "",
+  });
+});
+
+test("Command helpers ignore non-command input and empty names", () => {
+  assert.equal(parseTelegramCommand("hello /status"), undefined);
+  assert.equal(parseTelegramCommand("/"), undefined);
+});
+
+test("Command helpers build command actions", () => {
+  assert.deepEqual(buildTelegramCommandAction("stop"), { kind: "stop" });
+  assert.deepEqual(buildTelegramCommandAction("compact"), { kind: "compact" });
+  assert.deepEqual(buildTelegramCommandAction("status"), { kind: "status" });
+  assert.deepEqual(buildTelegramCommandAction("model"), { kind: "model" });
+  assert.deepEqual(buildTelegramCommandAction("help"), {
+    kind: "help",
+    commandName: "help",
+  });
+  assert.deepEqual(buildTelegramCommandAction("start"), {
+    kind: "help",
+    commandName: "start",
+  });
+  assert.deepEqual(buildTelegramCommandAction("unknown"), { kind: "ignore" });
+  assert.deepEqual(buildTelegramCommandAction(undefined), { kind: "ignore" });
+});
+
+test("Command helpers execute command actions through provided handlers", async () => {
+  const events: string[] = [];
+  const deps = {
+    handleStop: async () => {
+      events.push("stop");
+    },
+    handleCompact: async () => {
+      events.push("compact");
+    },
+    handleStatus: async () => {
+      events.push("status");
+    },
+    handleModel: async () => {
+      events.push("model");
+    },
+    handleHelp: async (_message: unknown, commandName: "help" | "start") => {
+      events.push(`help:${commandName}`);
+    },
+  };
+  assert.equal(
+    await executeTelegramCommandAction({ kind: "ignore" }, {}, {}, deps),
+    false,
+  );
+  assert.equal(
+    await executeTelegramCommandAction({ kind: "stop" }, {}, {}, deps),
+    true,
+  );
+  assert.equal(
+    await executeTelegramCommandAction(
+      { kind: "help", commandName: "start" },
+      {},
+      {},
+      deps,
+    ),
+    true,
+  );
+  assert.deepEqual(events, ["stop", "help:start"]);
+});

package/tests/media.test.ts

@@ -1,6 +1,6 @@
 /**
  * Regression tests for Telegram media and text extraction helpers
- * Covers inbound file-info collection, text extraction, id collection, and history formatting
+ * Covers inbound file-info collection, text extraction, media groups, id collection, and history formatting
  */
 
 import assert from "node:assert/strict";
@@ -12,7 +12,11 @@ import {
   extractFirstTelegramMessageText,
   extractTelegramMessagesText,
   formatTelegramHistoryText,
+  getTelegramMediaGroupKey,
   guessMediaType,
+  queueTelegramMediaGroupMessage,
+  removePendingTelegramMediaGroupMessages,
+  type TelegramMediaGroupState,
 } from "../lib/media.ts";
 
 test("Media helpers collect file infos across Telegram message variants", () => {
@@ -75,3 +79,88 @@ test("Media helpers infer outgoing image media types from file paths", () => {
   assert.equal(guessMediaType("/tmp/demo.png"), "image/png");
   assert.equal(guessMediaType("/tmp/demo.txt"), undefined);
 });
+
+test("Media helpers key messages by chat and media group", () => {
+  assert.equal(
+    getTelegramMediaGroupKey({
+      message_id: 1,
+      chat: { id: 7 },
+      media_group_id: "album",
+    }),
+    "7:album",
+  );
+  assert.equal(
+    getTelegramMediaGroupKey({ message_id: 1, chat: { id: 7 } }),
+    undefined,
+  );
+});
+
+test("Media helpers replace debounce timers and dispatch grouped messages", () => {
+  const groups = new Map<
+    string,
+    TelegramMediaGroupState<{
+      message_id: number;
+      chat: { id: number };
+      media_group_id?: string;
+    }>
+  >();
+  const cleared: number[] = [];
+  const callbacks: Array<() => void> = [];
+  const dispatched: number[][] = [];
+  let nextTimer = 1;
+  const setTimer = (callback: () => void): ReturnType<typeof setTimeout> => {
+    callbacks.push(callback);
+    return nextTimer++ as unknown as ReturnType<typeof setTimeout>;
+  };
+  const clearTimer = (timer: ReturnType<typeof setTimeout>): void => {
+    cleared.push(timer as unknown as number);
+  };
+  assert.equal(
+    queueTelegramMediaGroupMessage({
+      message: { message_id: 1, chat: { id: 7 }, media_group_id: "album" },
+      groups,
+      debounceMs: 100,
+      setTimer,
+      clearTimer,
+      dispatchMessages: (messages) =>
+        dispatched.push(messages.map((message) => message.message_id)),
+    }),
+    true,
+  );
+  queueTelegramMediaGroupMessage({
+    message: { message_id: 2, chat: { id: 7 }, media_group_id: "album" },
+    groups,
+    debounceMs: 100,
+    setTimer,
+    clearTimer,
+    dispatchMessages: (messages) =>
+      dispatched.push(messages.map((message) => message.message_id)),
+  });
+  assert.deepEqual(cleared, [1]);
+  callbacks.at(-1)?.();
+  assert.deepEqual(dispatched, [[1, 2]]);
+  assert.equal(groups.size, 0);
+});
+
+test("Media helpers remove pending groups by message id", () => {
+  const groups = new Map<
+    string,
+    TelegramMediaGroupState<{ message_id: number; chat: { id: number } }>
+  >();
+  groups.set("7:album", {
+    messages: [
+      { message_id: 1, chat: { id: 7 } },
+      { message_id: 2, chat: { id: 7 } },
+    ],
+    flushTimer: 10 as unknown as ReturnType<typeof setTimeout>,
+  });
+  const cleared: number[] = [];
+  assert.equal(
+    removePendingTelegramMediaGroupMessages(groups, [2], (timer) => {
+      cleared.push(timer as unknown as number);
+    }),
+    1,
+  );
+  assert.deepEqual(cleared, [10]);
+  assert.equal(groups.size, 0);
+});

package/tests/menu.test.ts

@@ -144,7 +144,9 @@ test("Menu helpers apply menu mutations and resolve model selections", () => {
   assert.equal(state.page, 2);
   assert.equal(applyTelegramModelPageSelection(state, "2"), "unchanged");
   assert.equal(applyTelegramModelPageSelection(state, "bad"), "invalid");
-  assert.deepEqual(getTelegramModelSelection(state, "bad"), { kind: "invalid" });
+  assert.deepEqual(getTelegramModelSelection(state, "bad"), {
+    kind: "invalid",
+  });
   assert.deepEqual(getTelegramModelSelection(state, "9"), { kind: "missing" });
   assert.equal(getTelegramModelSelection(state, "0").kind, "selected");
 });
@@ -174,7 +176,11 @@ test("Menu helpers derive normalized menu pages without mutating state", () => {
 
 test("Menu helpers build model callback plans for paging, selection, and restart modes", () => {
   const modelA = { provider: "openai", id: "gpt-5", reasoning: true } as const;
-  const modelB = { provider: "anthropic", id: "claude-3", reasoning: false } as const;
+  const modelB = {
+    provider: "anthropic",
+    id: "claude-3",
+    reasoning: false,
+  } as const;
   const state = {
     chatId: 1,
     messageId: 2,
@@ -227,7 +233,8 @@ test("Menu helpers build model callback plans for paging, selection, and restart
       kind: "switch-model",
       selection: state.allModels[1],
       mode: "restart-after-tool",
-      callbackText: "Switched to claude-3. Restarting after the current tool finishes…",
+      callbackText:
+        "Switched to claude-3. Restarting after the current tool finishes…",
     },
   );
   assert.deepEqual(
@@ -254,14 +261,19 @@ test("Menu helpers route callback entry states before action handlers", async ()
       events.push(`answer:${text ?? ""}`);
     },
   });
-  await handleTelegramMenuCallbackEntry("callback-2", "status:model", undefined, {
-    handleStatusAction: async () => false,
-    handleThinkingAction: async () => false,
-    handleModelAction: async () => false,
-    answerCallbackQuery: async (_id, text) => {
-      events.push(`answer:${text ?? ""}`);
+  await handleTelegramMenuCallbackEntry(
+    "callback-2",
+    "status:model",
+    undefined,
+    {
+      handleStatusAction: async () => false,
+      handleThinkingAction: async () => false,
+      handleModelAction: async () => false,
+      answerCallbackQuery: async (_id, text) => {
+        events.push(`answer:${text ?? ""}`);
+      },
     },
-  });
+  );
   await handleTelegramMenuCallbackEntry(
     "callback-3",
     "status:model",
@@ -296,7 +308,11 @@ test("Menu helpers route callback entry states before action handlers", async ()
 test("Menu helpers execute model callback actions across update, switch, and restart paths", async () => {
   const events: string[] = [];
   const modelA = { provider: "openai", id: "gpt-5", reasoning: true } as const;
-  const modelB = { provider: "anthropic", id: "claude-3", reasoning: false } as const;
+  const modelB = {
+    provider: "anthropic",
+    id: "claude-3",
+    reasoning: false,
+  } as const;
   const state = {
     chatId: 1,
     messageId: 2,
@@ -530,8 +546,14 @@ test("Menu helpers build pure render payloads before transport", () => {
     allModels: [{ model: modelA }],
     mode: "status" as const,
   } as unknown as TelegramModelMenuState;
-  const modelPayload = buildTelegramModelMenuRenderPayload(state, modelA as never);
-  const thinkingPayload = buildTelegramThinkingMenuRenderPayload(modelA as never, "medium");
+  const modelPayload = buildTelegramModelMenuRenderPayload(
+    state,
+    modelA as never,
+  );
+  const thinkingPayload = buildTelegramThinkingMenuRenderPayload(
+    modelA as never,
+    "medium",
+  );
   const statusPayload = buildTelegramStatusMenuRenderPayload(
     "<b>Status</b>",
     modelA as never,
@@ -580,7 +602,12 @@ test("Menu helpers update and send interactive menu messages", async () => {
     },
   };
   await updateTelegramModelMenuMessage(state, modelA as never, deps);
-  await updateTelegramThinkingMenuMessage(state, modelA as never, "medium", deps);
+  await updateTelegramThinkingMenuMessage(
+    state,
+    modelA as never,
+    "medium",
+    deps,
+  );
   await updateTelegramStatusMessage(
     state,
     "<b>Status</b>",
@@ -595,7 +622,11 @@ test("Menu helpers update and send interactive menu messages", async () => {
     "medium",
     deps,
   );
-  const sentModelId = await sendTelegramModelMenuMessage(state, modelA as never, deps);
+  const sentModelId = await sendTelegramModelMenuMessage(
+    state,
+    modelA as never,
+    deps,
+  );
   assert.equal(sentStatusId, 99);
   assert.equal(sentModelId, 99);
   assert.equal(events[0], "edit:1:2:html:<b>Choose a model:</b>");

package/tests/polling.test.ts

@@ -93,6 +93,79 @@ test("Poll loop initializes lastUpdateId and processes updates", async () => {
   assert.equal(persistCount, 3);
 });
 
+test("Poll loop persists long-poll offsets only after handling updates", async () => {
+  const config = { botToken: "123:abc", lastUpdateId: 5 };
+  const handled: number[] = [];
+  const persisted: number[] = [];
+  let calls = 0;
+  await runTelegramPollLoop({
+    ctx: {} as never,
+    signal: new AbortController().signal,
+    config,
+    deleteWebhook: async () => {},
+    getUpdates: async () => {
+      calls += 1;
+      if (calls === 1) return [{ update_id: 6 }];
+      throw new DOMException("stop", "AbortError");
+    },
+    persistConfig: async () => {
+      persisted.push(config.lastUpdateId ?? -1);
+    },
+    handleUpdate: async (update) => {
+      handled.push(update.update_id);
+      throw new Error("handler failed");
+    },
+    onErrorStatus: () => {},
+    onStatusReset: () => {},
+    sleep: async () => {},
+  });
+  assert.deepEqual(handled, [6]);
+  assert.equal(config.lastUpdateId, 5);
+  assert.deepEqual(persisted, []);
+});
+
+test("Poll loop skips repeatedly failing updates after the configured threshold", async () => {
+  const config = { botToken: "123:abc", lastUpdateId: 5 };
+  const persisted: number[] = [];
+  const statusMessages: string[] = [];
+  let calls = 0;
+  await runTelegramPollLoop({
+    ctx: {} as never,
+    signal: new AbortController().signal,
+    config,
+    maxUpdateFailures: 2,
+    deleteWebhook: async () => {},
+    getUpdates: async () => {
+      calls += 1;
+      if (calls <= 2) return [{ update_id: 6 }];
+      throw new DOMException("stop", "AbortError");
+    },
+    persistConfig: async () => {
+      persisted.push(config.lastUpdateId ?? -1);
+    },
+    handleUpdate: async () => {
+      throw new Error("handler failed");
+    },
+    onErrorStatus: (message) => {
+      statusMessages.push(message);
+    },
+    onStatusReset: () => {
+      statusMessages.push("reset");
+    },
+    sleep: async (ms) => {
+      statusMessages.push(`sleep:${ms}`);
+    },
+  });
+  assert.equal(config.lastUpdateId, 6);
+  assert.deepEqual(persisted, [6]);
+  assert.deepEqual(statusMessages, [
+    "handler failed",
+    "sleep:3000",
+    "reset",
+    "skipping Telegram update 6 after 2 failures: handler failed",
+  ]);
+});
+
 test("Poll loop reports retryable errors and sleeps before retrying", async () => {
   const config = { botToken: "123:abc", lastUpdateId: 1 };
   const statusMessages: string[] = [];