@llblab/pi-telegram 0.2.0

package/lib/updates.ts

@@ -0,0 +1,397 @@
+/**
+ * Telegram updates domain helpers
+ * Owns update extraction, authorization, classification, execution planning, and runtime execution for Telegram updates
+ */
+
+import type { ExtensionContext } from "@mariozechner/pi-coding-agent";
+
+// --- Extraction ---
+
+export interface TelegramReactionTypeEmojiLike {
+  type: "emoji";
+  emoji: string;
+}
+
+export interface TelegramReactionTypeNonEmojiLike {
+  type: string;
+}
+
+export type TelegramReactionTypeLike =
+  | TelegramReactionTypeEmojiLike
+  | TelegramReactionTypeNonEmojiLike;
+
+export interface TelegramUpdateLike {
+  deleted_business_messages?: { message_ids?: unknown };
+  _: string;
+  messages?: unknown;
+}
+
+function isTelegramMessageIdList(value: unknown): value is number[] {
+  return Array.isArray(value) && value.every((item) => Number.isInteger(item));
+}
+
+export function normalizeTelegramReactionEmoji(emoji: string): string {
+  return emoji.replace(/\uFE0F/g, "");
+}
+
+export function collectTelegramReactionEmojis(
+  reactions: TelegramReactionTypeLike[],
+): Set<string> {
+  return new Set(
+    reactions
+      .filter(
+        (reaction): reaction is TelegramReactionTypeEmojiLike =>
+          reaction.type === "emoji",
+      )
+      .map((reaction) => normalizeTelegramReactionEmoji(reaction.emoji)),
+  );
+}
+
+export function extractDeletedTelegramMessageIds(
+  update: TelegramUpdateLike,
+): number[] {
+  const deletedBusinessMessageIds =
+    update.deleted_business_messages?.message_ids;
+  if (isTelegramMessageIdList(deletedBusinessMessageIds)) {
+    return deletedBusinessMessageIds;
+  }
+  if (
+    update._ === "updateDeleteMessages" &&
+    isTelegramMessageIdList(update.messages)
+  ) {
+    return update.messages;
+  }
+  return [];
+}
+
+// --- Routing ---
+
+export interface TelegramUserLike {
+  id: number;
+  is_bot: boolean;
+}
+
+export interface TelegramChatLike {
+  id?: number;
+  type: string;
+}
+
+export interface TelegramMessageLike {
+  chat: TelegramChatLike;
+  from?: TelegramUserLike;
+  message_id?: number;
+}
+
+export interface TelegramCallbackQueryLike {
+  id?: string;
+  from: TelegramUserLike;
+  message?: TelegramMessageLike;
+}
+
+export interface TelegramUpdateRoutingLike {
+  message?: TelegramMessageLike;
+  edited_message?: TelegramMessageLike;
+  callback_query?: TelegramCallbackQueryLike;
+}
+
+export type TelegramAuthorizationState =
+  | { kind: "pair"; userId: number }
+  | { kind: "allow" }
+  | { kind: "deny" };
+
+export function getTelegramAuthorizationState(
+  userId: number,
+  allowedUserId?: number,
+): TelegramAuthorizationState {
+  if (allowedUserId === undefined) {
+    return { kind: "pair", userId };
+  }
+  if (userId === allowedUserId) {
+    return { kind: "allow" };
+  }
+  return { kind: "deny" };
+}
+
+export function getAuthorizedTelegramCallbackQuery(
+  update: TelegramUpdateRoutingLike,
+): TelegramCallbackQueryLike | undefined {
+  const query = update.callback_query;
+  if (!query) return undefined;
+  const message = query.message;
+  if (!message || message.chat.type !== "private" || query.from.is_bot) {
+    return undefined;
+  }
+  return query;
+}
+
+export function getAuthorizedTelegramMessage(
+  update: TelegramUpdateRoutingLike,
+): TelegramMessageLike | undefined {
+  const message = update.message || update.edited_message;
+  if (
+    !message ||
+    message.chat.type !== "private" ||
+    !message.from ||
+    message.from.is_bot
+  ) {
+    return undefined;
+  }
+  return message;
+}
+
+// --- Flow ---
+
+export interface TelegramMessageReactionUpdatedLike {
+  chat: { type: string };
+  user?: TelegramUserLike;
+}
+
+export interface TelegramUpdateFlowLike
+  extends TelegramUpdateRoutingLike, TelegramUpdateLike {
+  message_reaction?: TelegramMessageReactionUpdatedLike;
+}
+
+export type TelegramUpdateFlowAction =
+  | { kind: "ignore" }
+  | { kind: "deleted"; messageIds: number[] }
+  | { kind: "reaction"; reactionUpdate: TelegramMessageReactionUpdatedLike }
+  | {
+      kind: "callback";
+      query: TelegramCallbackQueryLike;
+      authorization: TelegramAuthorizationState;
+    }
+  | {
+      kind: "message";
+      message: TelegramMessageLike & { from: TelegramUserLike };
+      authorization: TelegramAuthorizationState;
+    };
+
+export function buildTelegramUpdateFlowAction(
+  update: TelegramUpdateFlowLike,
+  allowedUserId?: number,
+): TelegramUpdateFlowAction {
+  const deletedMessageIds = extractDeletedTelegramMessageIds(update);
+  if (deletedMessageIds.length > 0) {
+    return { kind: "deleted", messageIds: deletedMessageIds };
+  }
+  if (update.message_reaction) {
+    return { kind: "reaction", reactionUpdate: update.message_reaction };
+  }
+  const query = getAuthorizedTelegramCallbackQuery(update);
+  if (query) {
+    return {
+      kind: "callback",
+      query,
+      authorization: getTelegramAuthorizationState(
+        query.from.id,
+        allowedUserId,
+      ),
+    };
+  }
+  const message = getAuthorizedTelegramMessage(update);
+  if (message?.from) {
+    return {
+      kind: "message",
+      message: message as TelegramMessageLike & { from: TelegramUserLike },
+      authorization: getTelegramAuthorizationState(
+        message.from.id,
+        allowedUserId,
+      ),
+    };
+  }
+  return { kind: "ignore" };
+}
+
+// --- Execution Planning ---
+
+export type TelegramUpdateExecutionPlan =
+  | { kind: "ignore" }
+  | { kind: "deleted"; messageIds: number[] }
+  | {
+      kind: "reaction";
+      reactionUpdate: NonNullable<TelegramUpdateFlowLike["message_reaction"]>;
+    }
+  | {
+      kind: "callback";
+      query: TelegramCallbackQueryLike;
+      shouldPair: boolean;
+      shouldDeny: boolean;
+    }
+  | {
+      kind: "message";
+      message: TelegramMessageLike & { from: TelegramUserLike };
+      shouldPair: boolean;
+      shouldNotifyPaired: boolean;
+      shouldDeny: boolean;
+    };
+
+export function buildTelegramUpdateExecutionPlan(
+  action: TelegramUpdateFlowAction,
+): TelegramUpdateExecutionPlan {
+  switch (action.kind) {
+    case "ignore":
+      return { kind: "ignore" };
+    case "deleted":
+      return { kind: "deleted", messageIds: action.messageIds };
+    case "reaction":
+      return { kind: "reaction", reactionUpdate: action.reactionUpdate };
+    case "callback":
+      return {
+        kind: "callback",
+        query: action.query,
+        shouldPair: action.authorization.kind === "pair",
+        shouldDeny: action.authorization.kind === "deny",
+      };
+    case "message":
+      return {
+        kind: "message",
+        message: action.message,
+        shouldPair: action.authorization.kind === "pair",
+        shouldNotifyPaired: action.authorization.kind === "pair",
+        shouldDeny: action.authorization.kind === "deny",
+      };
+  }
+}
+
+export function buildTelegramUpdateExecutionPlanFromUpdate(
+  update: TelegramUpdateFlowLike,
+  allowedUserId?: number,
+): TelegramUpdateExecutionPlan {
+  return buildTelegramUpdateExecutionPlan(
+    buildTelegramUpdateFlowAction(update, allowedUserId),
+  );
+}
+
+// --- Runtime ---
+
+export interface TelegramUpdateRuntimeDeps {
+  ctx: ExtensionContext;
+  removePendingMediaGroupMessages: (messageIds: number[]) => void;
+  removeQueuedTelegramTurnsByMessageIds: (
+    messageIds: number[],
+    ctx: ExtensionContext,
+  ) => number;
+  handleAuthorizedTelegramReactionUpdate: (
+    reactionUpdate: NonNullable<
+      Extract<
+        TelegramUpdateExecutionPlan,
+        { kind: "reaction" }
+      >["reactionUpdate"]
+    >,
+    ctx: ExtensionContext,
+  ) => Promise<void>;
+  pairTelegramUserIfNeeded: (
+    userId: number,
+    ctx: ExtensionContext,
+  ) => Promise<boolean>;
+  answerCallbackQuery: (
+    callbackQueryId: string,
+    text?: string,
+  ) => Promise<void>;
+  handleAuthorizedTelegramCallbackQuery: (
+    query: Extract<TelegramUpdateExecutionPlan, { kind: "callback" }>["query"],
+    ctx: ExtensionContext,
+  ) => Promise<void>;
+  sendTextReply: (
+    chatId: number,
+    replyToMessageId: number,
+    text: string,
+  ) => Promise<number | undefined>;
+  handleAuthorizedTelegramMessage: (
+    message: Extract<
+      TelegramUpdateExecutionPlan,
+      { kind: "message" }
+    >["message"],
+    ctx: ExtensionContext,
+  ) => Promise<void>;
+}
+
+function getTelegramCallbackQueryId(
+  query: TelegramCallbackQueryLike,
+): string | undefined {
+  return typeof query.id === "string" ? query.id : undefined;
+}
+
+function getTelegramMessageReplyTarget(
+  message: TelegramMessageLike,
+): { chatId: number; messageId: number } | undefined {
+  if (
+    typeof message.chat.id !== "number" ||
+    typeof message.message_id !== "number"
+  ) {
+    return undefined;
+  }
+  return {
+    chatId: message.chat.id,
+    messageId: message.message_id,
+  };
+}
+
+export async function executeTelegramUpdate(
+  update: TelegramUpdateFlowLike,
+  allowedUserId: number | undefined,
+  deps: TelegramUpdateRuntimeDeps,
+): Promise<void> {
+  await executeTelegramUpdatePlan(
+    buildTelegramUpdateExecutionPlanFromUpdate(update, allowedUserId),
+    deps,
+  );
+}
+
+export async function executeTelegramUpdatePlan(
+  plan: TelegramUpdateExecutionPlan,
+  deps: TelegramUpdateRuntimeDeps,
+): Promise<void> {
+  if (plan.kind === "ignore") return;
+  if (plan.kind === "deleted") {
+    deps.removePendingMediaGroupMessages(plan.messageIds);
+    deps.removeQueuedTelegramTurnsByMessageIds(plan.messageIds, deps.ctx);
+    return;
+  }
+  if (plan.kind === "reaction") {
+    await deps.handleAuthorizedTelegramReactionUpdate(
+      plan.reactionUpdate,
+      deps.ctx,
+    );
+    return;
+  }
+  if (plan.kind === "callback") {
+    if (plan.shouldPair) {
+      await deps.pairTelegramUserIfNeeded(plan.query.from.id, deps.ctx);
+    }
+    if (plan.shouldDeny) {
+      const callbackQueryId = getTelegramCallbackQueryId(plan.query);
+      if (callbackQueryId) {
+        await deps.answerCallbackQuery(
+          callbackQueryId,
+          "This bot is not authorized for your account.",
+        );
+      }
+      return;
+    }
+    await deps.handleAuthorizedTelegramCallbackQuery(plan.query, deps.ctx);
+    return;
+  }
+  const pairedNow = plan.shouldPair
+    ? await deps.pairTelegramUserIfNeeded(plan.message.from.id, deps.ctx)
+    : false;
+  const replyTarget = getTelegramMessageReplyTarget(plan.message);
+  if (pairedNow && plan.shouldNotifyPaired && replyTarget) {
+    await deps.sendTextReply(
+      replyTarget.chatId,
+      replyTarget.messageId,
+      "Telegram bridge paired with this account.",
+    );
+  }
+  if (plan.shouldDeny) {
+    if (replyTarget) {
+      await deps.sendTextReply(
+        replyTarget.chatId,
+        replyTarget.messageId,
+        "This bot is not authorized for your account.",
+      );
+    }
+    return;
+  }
+  await deps.handleAuthorizedTelegramMessage(plan.message, deps.ctx);
+}

package/package.json

@@ -0,0 +1,40 @@
+{
+  "name": "@llblab/pi-telegram",
+  "version": "0.2.0",
+  "private": false,
+  "description": "Telegram DM bridge extension for pi",
+  "type": "module",
+  "keywords": [
+    "pi-package",
+    "pi",
+    "telegram",
+    "bot",
+    "extension"
+  ],
+  "license": "MIT",
+  "repository": {
+    "type": "git",
+    "url": "https://github.com/llblab/pi-telegram.git"
+  },
+  "homepage": "https://github.com/llblab/pi-telegram",
+  "bugs": {
+    "url": "https://github.com/llblab/pi-telegram/issues"
+  },
+  "scripts": {
+    "test": "node --experimental-strip-types --test tests/*.test.ts"
+  },
+  "publishConfig": {
+    "access": "public"
+  },
+  "pi": {
+    "extensions": [
+      "./index.ts"
+    ]
+  },
+  "peerDependencies": {
+    "@mariozechner/pi-ai": "*",
+    "@mariozechner/pi-agent-core": "*",
+    "@mariozechner/pi-coding-agent": "*",
+    "@sinclair/typebox": "*"
+  }
+}

package/tests/api.test.ts

@@ -0,0 +1,89 @@
+/**
+ * Regression tests for Telegram API and config helpers
+ * Verifies config persistence and direct helper behavior around missing tokens and callback-query failures
+ */
+
+import assert from "node:assert/strict";
+import { mkdtemp, readFile } from "node:fs/promises";
+import { tmpdir } from "node:os";
+import { join } from "node:path";
+import test from "node:test";
+
+import {
+  answerTelegramCallbackQuery,
+  callTelegram,
+  createTelegramApiClient,
+  downloadTelegramFile,
+  readTelegramConfig,
+  writeTelegramConfig,
+} from "../lib/api.ts";
+
+test("Telegram config helpers persist and reload config", async () => {
+  const agentDir = await mkdtemp(join(tmpdir(), "pi-telegram-config-"));
+  const configPath = join(agentDir, "telegram.json");
+  const config = {
+    botToken: "123:abc",
+    botUsername: "demo_bot",
+    allowedUserId: 42,
+  };
+  await writeTelegramConfig(agentDir, configPath, config);
+  const reloaded = await readTelegramConfig(configPath);
+  assert.deepEqual(reloaded, config);
+  const raw = await readFile(configPath, "utf8");
+  assert.match(raw, /demo_bot/);
+});
+
+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",
+  });
+  await assert.rejects(
+    () =>
+      downloadTelegramFile(
+        undefined,
+        "file-id",
+        "demo.txt",
+        join(tmpdir(), "pi-telegram-missing-token"),
+      ),
+    {
+      message: "Telegram bot token is not configured",
+    },
+  );
+});
+
+test("answerTelegramCallbackQuery ignores Telegram API failures", async () => {
+  const originalFetch = globalThis.fetch;
+  globalThis.fetch = (async () => {
+    throw new Error("network down");
+  }) as typeof fetch;
+  try {
+    await assert.doesNotReject(() =>
+      answerTelegramCallbackQuery("123:abc", "callback-id", "ok"),
+    );
+  } finally {
+    globalThis.fetch = originalFetch;
+  }
+});
+
+test("Telegram API client resolves bot tokens lazily for wrapped calls", async () => {
+  const originalFetch = globalThis.fetch;
+  const calls: string[] = [];
+  let botToken = "123:abc";
+  globalThis.fetch = (async (input) => {
+    calls.push(typeof input === "string" ? input : input.toString());
+    return {
+      ok: true,
+      json: async () => ({ ok: true, result: true }),
+    } as Response;
+  }) as typeof fetch;
+  try {
+    const client = createTelegramApiClient(() => botToken);
+    await client.call("sendChatAction", { chat_id: 1, action: "typing" });
+    botToken = "456:def";
+    await client.answerCallbackQuery("cb-1", "ok");
+    assert.match(calls[0] ?? "", /bot123:abc\/sendChatAction$/);
+    assert.match(calls[1] ?? "", /bot456:def\/answerCallbackQuery$/);
+  } finally {
+    globalThis.fetch = originalFetch;
+  }
+});

package/tests/attachments.test.ts

@@ -0,0 +1,132 @@
+/**
+ * Regression tests for the Telegram attachments domain
+ * Covers attachment queueing and attachment delivery behavior in one domain-level suite
+ */
+
+import assert from "node:assert/strict";
+import test from "node:test";
+
+import {
+  queueTelegramAttachments,
+  sendQueuedTelegramAttachments,
+} from "../lib/attachments.ts";
+
+test("Attachment queueing adds files to the active Telegram turn", async () => {
+  const activeTurn = {
+    queuedAttachments: [],
+  } as unknown as {
+    queuedAttachments: Array<{ path: string; fileName: string }>;
+  } & Parameters<typeof queueTelegramAttachments>[0]["activeTurn"];
+  const result = await queueTelegramAttachments({
+    activeTurn,
+    paths: ["/tmp/demo.txt"],
+    maxAttachmentsPerTurn: 2,
+    statPath: async () => ({ isFile: () => true }),
+  });
+  assert.deepEqual(activeTurn.queuedAttachments, [
+    { path: "/tmp/demo.txt", fileName: "demo.txt" },
+  ]);
+  assert.deepEqual(result.details.paths, ["/tmp/demo.txt"]);
+});
+
+test("Attachment queueing rejects missing turns, non-files, and full queues", async () => {
+  await assert.rejects(
+    () =>
+      queueTelegramAttachments({
+        activeTurn: undefined,
+        paths: ["/tmp/demo.txt"],
+        maxAttachmentsPerTurn: 1,
+        statPath: async () => ({ isFile: () => true }),
+      }),
+    { message: /active Telegram turn/ },
+  );
+  await assert.rejects(
+    () =>
+      queueTelegramAttachments({
+        activeTurn: { queuedAttachments: [] } as never,
+        paths: ["/tmp/demo.txt"],
+        maxAttachmentsPerTurn: 1,
+        statPath: async () => ({ isFile: () => false }),
+      }),
+    { message: "Not a file: /tmp/demo.txt" },
+  );
+  await assert.rejects(
+    () =>
+      queueTelegramAttachments({
+        activeTurn: {
+          queuedAttachments: [{ path: "/tmp/a.txt", fileName: "a.txt" }],
+        } as never,
+        paths: ["/tmp/demo.txt"],
+        maxAttachmentsPerTurn: 1,
+        statPath: async () => ({ isFile: () => true }),
+      }),
+    { message: "Attachment limit reached (1)" },
+  );
+});
+
+test("Attachment delivery chooses photo vs document methods from file paths", async () => {
+  const sent: Array<string> = [];
+  await sendQueuedTelegramAttachments(
+    {
+      kind: "prompt",
+      chatId: 1,
+      replyToMessageId: 2,
+      sourceMessageIds: [],
+      queueOrder: 1,
+      queueLane: "default",
+      laneOrder: 1,
+      queuedAttachments: [
+        { path: "/tmp/a.png", fileName: "a.png" },
+        { path: "/tmp/b.txt", fileName: "b.txt" },
+      ],
+      content: [{ type: "text", text: "prompt" }],
+      historyText: "history",
+      statusSummary: "summary",
+    },
+    {
+      sendMultipart: async (
+        method,
+        _fields,
+        fileField,
+        _filePath,
+        fileName,
+      ) => {
+        sent.push(`${method}:${fileField}:${fileName}`);
+      },
+      sendTextReply: async () => undefined,
+    },
+  );
+  assert.deepEqual(sent, [
+    "sendPhoto:photo:a.png",
+    "sendDocument:document:b.txt",
+  ]);
+});
+
+test("Attachment delivery reports per-file failures via text replies", async () => {
+  const replies: string[] = [];
+  await sendQueuedTelegramAttachments(
+    {
+      kind: "prompt",
+      chatId: 1,
+      replyToMessageId: 2,
+      sourceMessageIds: [],
+      queueOrder: 1,
+      queueLane: "default",
+      laneOrder: 1,
+      queuedAttachments: [{ path: "/tmp/a.png", fileName: "a.png" }],
+      content: [{ type: "text", text: "prompt" }],
+      historyText: "history",
+      statusSummary: "summary",
+    },
+    {
+      sendMultipart: async () => {
+        throw new Error("upload failed");
+      },
+      sendTextReply: async (_chatId, _replyToMessageId, text) => {
+        replies.push(text);
+        return undefined;
+      },
+    },
+  );
+  assert.deepEqual(replies, ["Failed to send attachment a.png: upload failed"]);
+});