@llblab/pi-telegram 0.2.9 → 0.3.0

package/lib/config.ts

@@ -0,0 +1,157 @@
+/**
+ * Telegram bridge config and pairing helpers
+ * Owns persisted bot/session pairing state, local config storage, authorization policy, and first-user pairing side effects
+ */
+
+import { chmod, mkdir, readFile, writeFile } from "node:fs/promises";
+import { homedir } from "node:os";
+import { join } from "node:path";
+
+const AGENT_DIR = join(homedir(), ".pi", "agent");
+const CONFIG_PATH = join(AGENT_DIR, "telegram.json");
+
+export interface TelegramConfig {
+  botToken?: string;
+  botUsername?: string;
+  botId?: number;
+  allowedUserId?: number;
+  lastUpdateId?: number;
+}
+
+export interface TelegramConfigStore {
+  get: () => TelegramConfig;
+  set: (config: TelegramConfig) => void;
+  update: (mutate: (config: TelegramConfig) => void) => void;
+  getBotToken: () => string | undefined;
+  hasBotToken: () => boolean;
+  getAllowedUserId: () => number | undefined;
+  setAllowedUserId: (userId: number) => void;
+  load: () => Promise<void>;
+  persist: (config?: TelegramConfig) => Promise<void>;
+}
+
+export interface TelegramConfigStoreOptions {
+  initialConfig?: TelegramConfig;
+  agentDir?: string;
+  configPath?: string;
+}
+
+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", {
+    encoding: "utf8",
+    mode: 0o600,
+  });
+  await chmod(configPath, 0o600);
+}
+
+export function createTelegramConfigStore(
+  options: TelegramConfigStoreOptions = {},
+): TelegramConfigStore {
+  let config: TelegramConfig = options.initialConfig ?? {};
+  const agentDir = options.agentDir ?? AGENT_DIR;
+  const configPath = options.configPath ?? CONFIG_PATH;
+  return {
+    get: () => config,
+    set: (nextConfig) => {
+      config = nextConfig;
+    },
+    update: (mutate) => {
+      mutate(config);
+    },
+    getBotToken: () => config.botToken,
+    hasBotToken: () => !!config.botToken,
+    getAllowedUserId: () => config.allowedUserId,
+    setAllowedUserId: (userId) => {
+      config.allowedUserId = userId;
+    },
+    load: async () => {
+      config = await readTelegramConfig(configPath);
+    },
+    persist: async (nextConfig = config) => {
+      await writeTelegramConfig(agentDir, configPath, nextConfig);
+    },
+  };
+}
+
+export type TelegramAuthorizationState =
+  | { kind: "pair"; userId: number }
+  | { kind: "allow" }
+  | { kind: "deny" };
+
+export interface TelegramUserPairingDeps<TContext> {
+  allowedUserId?: number;
+  ctx: TContext;
+  setAllowedUserId: (userId: number) => void;
+  persistConfig: () => Promise<void>;
+  updateStatus: (ctx: TContext) => void;
+}
+
+export interface TelegramUserPairingRuntimeDeps<TContext> {
+  getAllowedUserId: () => number | undefined;
+  setAllowedUserId: (userId: number) => void;
+  persistConfig: () => Promise<void>;
+  updateStatus: (ctx: TContext) => void;
+}
+
+export interface TelegramUserPairingRuntime<TContext> {
+  pairIfNeeded: (userId: number, ctx: TContext) => Promise<boolean>;
+}
+
+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 async function pairTelegramUserIfNeeded<TContext>(
+  userId: number,
+  deps: TelegramUserPairingDeps<TContext>,
+): Promise<boolean> {
+  const authorization = getTelegramAuthorizationState(
+    userId,
+    deps.allowedUserId,
+  );
+  if (authorization.kind !== "pair") return false;
+  deps.setAllowedUserId(authorization.userId);
+  await deps.persistConfig();
+  deps.updateStatus(deps.ctx);
+  return true;
+}
+
+export function createTelegramUserPairingRuntime<TContext>(
+  deps: TelegramUserPairingRuntimeDeps<TContext>,
+): TelegramUserPairingRuntime<TContext> {
+  return {
+    pairIfNeeded: (userId, ctx) =>
+      pairTelegramUserIfNeeded(userId, {
+        allowedUserId: deps.getAllowedUserId(),
+        ctx,
+        setAllowedUserId: deps.setAllowedUserId,
+        persistConfig: deps.persistConfig,
+        updateStatus: deps.updateStatus,
+      }),
+  };
+}

package/lib/media.ts

@@ -1,57 +1,92 @@
 /**
  * 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 {
+const TELEGRAM_MEDIA_GROUP_DEBOUNCE_MS = 1200;
+
+export interface TelegramPhotoSize {
   file_id: string;
   file_size?: number;
 }
 
-export interface TelegramDocumentLike {
+export interface TelegramDocument {
   file_id: string;
   file_name?: string;
   mime_type?: string;
 }
 
-export interface TelegramVideoLike {
+export type TelegramVideo = TelegramDocument;
+export type TelegramAudio = TelegramDocument;
+export type TelegramAnimation = TelegramDocument;
+
+export interface TelegramVoice {
   file_id: string;
-  file_name?: string;
   mime_type?: string;
 }
 
-export interface TelegramAudioLike {
+export interface TelegramSticker {
   file_id: string;
-  file_name?: string;
-  mime_type?: string;
 }
 
-export interface TelegramVoiceLike {
-  file_id: string;
-  mime_type?: string;
+export interface TelegramMediaMessage {
+  message_id: number;
+  text?: string;
+  caption?: string;
+  media_group_id?: string;
+  photo?: TelegramPhotoSize[];
+  document?: TelegramDocument;
+  video?: TelegramVideo;
+  audio?: TelegramAudio;
+  voice?: TelegramVoice;
+  animation?: TelegramAnimation;
+  sticker?: TelegramSticker;
 }
 
-export interface TelegramAnimationLike {
-  file_id: string;
-  file_name?: string;
-  mime_type?: string;
+export interface TelegramMediaGroupMessage {
+  message_id: number;
+  chat: { id: number };
+  media_group_id?: string;
 }
 
-export interface TelegramStickerLike {
-  file_id: string;
+export interface TelegramMediaGroupState<TMessage> {
+  messages: TMessage[];
+  flushTimer?: ReturnType<typeof setTimeout>;
 }
 
-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 TelegramMediaGroupController<
+  TMessage extends TelegramMediaGroupMessage,
+> {
+  queueMessage: (options: {
+    message: TMessage;
+    dispatchMessages: (messages: TMessage[]) => void;
+  }) => boolean;
+  removeMessages: (messageIds: number[]) => number;
+  clear: () => void;
+}
+
+export interface TelegramMediaGroupDispatchRuntimeDeps<
+  TMessage extends TelegramMediaGroupMessage,
+  TContext,
+> {
+  mediaGroups: TelegramMediaGroupController<TMessage>;
+  dispatchMessages: (messages: TMessage[], ctx: TContext) => Promise<void>;
+}
+
+export interface TelegramMediaGroupDispatchRuntime<
+  TMessage extends TelegramMediaGroupMessage,
+  TContext,
+> {
+  handleMessage: (message: TMessage, ctx: TContext) => Promise<void>;
+}
+
+export interface TelegramMediaGroupControllerOptions {
+  debounceMs?: number;
+  setTimer?: (
+    callback: () => void,
+    ms: number,
+  ) => ReturnType<typeof setTimeout>;
+  clearTimer?: (timer: ReturnType<typeof setTimeout>) => void;
 }
 
 export interface TelegramFileInfo {
@@ -61,8 +96,22 @@ export interface TelegramFileInfo {
   isImage: boolean;
 }
 
-export interface DownloadedTelegramFileLike {
+export interface DownloadedTelegramFile {
+  path: string;
+  fileName?: string;
+  isImage?: boolean;
+  mimeType?: string;
+}
+
+export interface DownloadedTelegramMessageFile {
   path: string;
+  fileName: string;
+  isImage: boolean;
+  mimeType?: string;
+}
+
+export interface DownloadTelegramMessageFilesDeps {
+  downloadFile: (fileId: string, fileName: string) => Promise<string>;
 }
 
 export function guessExtensionFromMime(
@@ -94,37 +143,147 @@ export function guessMediaType(path: string): string | undefined {
   return undefined;
 }
 
-export function isImageMimeType(mimeType: string | undefined): boolean {
+function isImageMimeType(mimeType: string | undefined): boolean {
   return mimeType?.toLowerCase().startsWith("image/") ?? false;
 }
 
 export function extractTelegramMessageText(
-  message: TelegramMessageLike,
+  message: TelegramMediaMessage,
 ): string {
   return (message.text || message.caption || "").trim();
 }
 
 export function extractTelegramMessagesText(
-  messages: TelegramMessageLike[],
+  messages: TelegramMediaMessage[],
 ): string {
   return messages.map(extractTelegramMessageText).filter(Boolean).join("\n\n");
 }
 
 export function extractFirstTelegramMessageText(
-  messages: TelegramMessageLike[],
+  messages: TelegramMediaMessage[],
 ): string {
   return messages.map(extractTelegramMessageText).find(Boolean) ?? "";
 }
 
 export function collectTelegramMessageIds(
-  messages: TelegramMessageLike[],
+  messages: TelegramMediaMessage[],
 ): number[] {
   return [...new Set(messages.map((message) => message.message_id))];
 }
 
+export function getTelegramMediaGroupKey(
+  message: TelegramMediaGroupMessage,
+): string | undefined {
+  if (!message.media_group_id) return undefined;
+  return `${message.chat.id}:${message.media_group_id}`;
+}
+
+export function removePendingTelegramMediaGroupMessages<
+  TMessage extends TelegramMediaGroupMessage,
+>(
+  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 TelegramMediaGroupMessage,
+>(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 createTelegramMediaGroupController<
+  TMessage extends TelegramMediaGroupMessage,
+>(
+  options: TelegramMediaGroupControllerOptions = {},
+): TelegramMediaGroupController<TMessage> {
+  const groups = new Map<string, TelegramMediaGroupState<TMessage>>();
+  const debounceMs = options.debounceMs ?? TELEGRAM_MEDIA_GROUP_DEBOUNCE_MS;
+  const setTimer =
+    options.setTimer ??
+    ((callback: () => void, ms: number): ReturnType<typeof setTimeout> =>
+      setTimeout(callback, ms));
+  const clearTimer = options.clearTimer ?? clearTimeout;
+  return {
+    queueMessage: ({ message, dispatchMessages }) =>
+      queueTelegramMediaGroupMessage({
+        message,
+        groups,
+        debounceMs,
+        setTimer,
+        clearTimer,
+        dispatchMessages,
+      }),
+    removeMessages: (messageIds) =>
+      removePendingTelegramMediaGroupMessages(groups, messageIds, clearTimer),
+    clear: () => {
+      for (const state of groups.values()) {
+        if (state.flushTimer) clearTimer(state.flushTimer);
+      }
+      groups.clear();
+    },
+  };
+}
+
+export function createTelegramMediaGroupDispatchRuntime<
+  TMessage extends TelegramMediaGroupMessage,
+  TContext,
+>(
+  deps: TelegramMediaGroupDispatchRuntimeDeps<TMessage, TContext>,
+): TelegramMediaGroupDispatchRuntime<TMessage, TContext> {
+  return {
+    handleMessage: async (message, ctx) => {
+      const queuedMediaGroup = deps.mediaGroups.queueMessage({
+        message,
+        dispatchMessages: (messages) => {
+          void deps.dispatchMessages(messages, ctx);
+        },
+      });
+      if (queuedMediaGroup) return;
+      await deps.dispatchMessages([message], ctx);
+    },
+  };
+}
+
 export function formatTelegramHistoryText(
   rawText: string,
-  files: DownloadedTelegramFileLike[],
+  files: DownloadedTelegramFile[],
 ): string {
   let summary = rawText.length > 0 ? rawText : "(no text)";
   if (files.length > 0) {
@@ -136,8 +295,24 @@ export function formatTelegramHistoryText(
   return summary;
 }
 
+export async function downloadTelegramMessageFiles(
+  messages: TelegramMediaMessage[],
+  deps: DownloadTelegramMessageFilesDeps,
+): Promise<DownloadedTelegramMessageFile[]> {
+  const downloaded: DownloadedTelegramMessageFile[] = [];
+  for (const file of collectTelegramFileInfos(messages)) {
+    downloaded.push({
+      path: await deps.downloadFile(file.file_id, file.fileName),
+      fileName: file.fileName,
+      isImage: file.isImage,
+      mimeType: file.mimeType,
+    });
+  }
+  return downloaded;
+}
+
 export function collectTelegramFileInfos(
-  messages: TelegramMessageLike[],
+  messages: TelegramMediaMessage[],
 ): TelegramFileInfo[] {
   const files: TelegramFileInfo[] = [];
   for (const message of messages) {