ctb 1.0.0

package/src/handlers/media-group.ts

@@ -0,0 +1,205 @@
+/**
+ * Shared media group handling for Claude Telegram Bot.
+ *
+ * Provides a generic buffer for handling Telegram media groups (albums)
+ * with configurable processing callbacks.
+ */
+
+import type { Context } from "grammy";
+import type { Message } from "grammy/types";
+import type { PendingMediaGroup } from "../types";
+import { MEDIA_GROUP_TIMEOUT } from "../config";
+import { rateLimiter } from "../security";
+import { auditLogRateLimit } from "../utils";
+import { session } from "../session";
+
+/**
+ * Configuration for a media group handler.
+ */
+export interface MediaGroupConfig {
+  /** Emoji for status messages (e.g., "📷" or "📄") */
+  emoji: string;
+  /** Label for items (e.g., "photo" or "document") */
+  itemLabel: string;
+  /** Plural label for items (e.g., "photos" or "documents") */
+  itemLabelPlural: string;
+}
+
+/**
+ * Callback to process a completed media group.
+ */
+export type ProcessGroupCallback = (
+  ctx: Context,
+  items: string[],
+  caption: string | undefined,
+  userId: number,
+  username: string,
+  chatId: number
+) => Promise<void>;
+
+/**
+ * Creates a media group buffer with the specified configuration.
+ *
+ * Returns functions for adding items and processing groups.
+ */
+export function createMediaGroupBuffer(config: MediaGroupConfig) {
+  const pendingGroups = new Map<string, PendingMediaGroup>();
+
+  /**
+   * Process a completed media group.
+   */
+  async function processGroup(
+    groupId: string,
+    processCallback: ProcessGroupCallback
+  ): Promise<void> {
+    const group = pendingGroups.get(groupId);
+    if (!group) return;
+
+    pendingGroups.delete(groupId);
+
+    const userId = group.ctx.from?.id;
+    const username = group.ctx.from?.username || "unknown";
+    const chatId = group.ctx.chat?.id;
+
+    if (!userId || !chatId) return;
+
+    console.log(
+      `Processing ${group.items.length} ${config.itemLabelPlural} from @${username}`
+    );
+
+    // Update status message
+    if (group.statusMsg) {
+      try {
+        await group.ctx.api.editMessageText(
+          group.statusMsg.chat.id,
+          group.statusMsg.message_id,
+          `${config.emoji} Processing ${group.items.length} ${config.itemLabelPlural}...`
+        );
+      } catch (error) {
+        console.debug("Failed to update status message:", error);
+      }
+    }
+
+    await processCallback(
+      group.ctx,
+      group.items,
+      group.caption,
+      userId,
+      username,
+      chatId
+    );
+
+    // Delete status message
+    if (group.statusMsg) {
+      try {
+        await group.ctx.api.deleteMessage(
+          group.statusMsg.chat.id,
+          group.statusMsg.message_id
+        );
+      } catch (error) {
+        console.debug("Failed to delete status message:", error);
+      }
+    }
+  }
+
+  /**
+   * Add an item to a media group buffer.
+   *
+   * @returns true if the item was added successfully, false if rate limited
+   */
+  async function addToGroup(
+    mediaGroupId: string,
+    itemPath: string,
+    ctx: Context,
+    userId: number,
+    username: string,
+    processCallback: ProcessGroupCallback
+  ): Promise<boolean> {
+    if (!pendingGroups.has(mediaGroupId)) {
+      // Rate limit on first item only
+      const [allowed, retryAfter] = rateLimiter.check(userId);
+      if (!allowed) {
+        await auditLogRateLimit(userId, username, retryAfter!);
+        await ctx.reply(
+          `⏳ Rate limited. Please wait ${retryAfter!.toFixed(1)} seconds.`
+        );
+        return false;
+      }
+
+      // Create new group
+      console.log(`Receiving ${config.itemLabel} album from @${username}`);
+      const statusMsg = await ctx.reply(
+        `${config.emoji} Receiving ${config.itemLabelPlural}...`
+      );
+
+      pendingGroups.set(mediaGroupId, {
+        items: [itemPath],
+        ctx,
+        caption: ctx.message?.caption,
+        statusMsg,
+        timeout: setTimeout(
+          () => processGroup(mediaGroupId, processCallback),
+          MEDIA_GROUP_TIMEOUT
+        ),
+      });
+    } else {
+      // Add to existing group
+      const group = pendingGroups.get(mediaGroupId)!;
+      group.items.push(itemPath);
+
+      // Update caption if this message has one
+      if (ctx.message?.caption && !group.caption) {
+        group.caption = ctx.message.caption;
+      }
+
+      // Reset timeout
+      clearTimeout(group.timeout);
+      group.timeout = setTimeout(
+        () => processGroup(mediaGroupId, processCallback),
+        MEDIA_GROUP_TIMEOUT
+      );
+    }
+
+    return true;
+  }
+
+  return {
+    addToGroup,
+    processGroup,
+    pendingGroups,
+  };
+}
+
+/**
+ * Shared error handler for media processing.
+ *
+ * Cleans up tool messages and sends appropriate error response.
+ */
+export async function handleProcessingError(
+  ctx: Context,
+  error: unknown,
+  toolMessages: Message[]
+): Promise<void> {
+  console.error("Error processing media:", error);
+
+  // Clean up tool messages
+  for (const toolMsg of toolMessages) {
+    try {
+      await ctx.api.deleteMessage(toolMsg.chat.id, toolMsg.message_id);
+    } catch (cleanupError) {
+      console.debug("Failed to delete tool message:", cleanupError);
+    }
+  }
+
+  // Send error message
+  const errorStr = String(error);
+  if (errorStr.includes("abort") || errorStr.includes("cancel")) {
+    // Only show "Query stopped" if it was an explicit stop, not an interrupt from a new message
+    const wasInterrupt = session.consumeInterruptFlag();
+    if (!wasInterrupt) {
+      await ctx.reply("🛑 Query stopped.");
+    }
+  } else {
+    await ctx.reply(`❌ Error: ${errorStr.slice(0, 200)}`);
+  }
+}

package/src/handlers/photo.ts

@@ -0,0 +1,215 @@
+/**
+ * Photo message handler for Claude Telegram Bot.
+ *
+ * Supports single photos and media groups (albums) with 1s buffering.
+ */
+
+import { unlinkSync } from "node:fs";
+import type { Context } from "grammy";
+import { ALLOWED_USERS, TEMP_DIR } from "../config";
+import { isAuthorized, rateLimiter } from "../security";
+import { session } from "../session";
+import { auditLog, auditLogRateLimit, startTypingIndicator } from "../utils";
+import { createMediaGroupBuffer, handleProcessingError } from "./media-group";
+import { createStatusCallback, StreamingState } from "./streaming";
+
+/**
+ * Safely delete a temp file, ignoring errors.
+ */
+function cleanupTempFile(filePath: string): void {
+	try {
+		unlinkSync(filePath);
+	} catch {
+		// Ignore cleanup errors
+	}
+}
+
+/**
+ * Cleanup multiple temp files.
+ */
+function cleanupTempFiles(filePaths: string[]): void {
+	for (const path of filePaths) {
+		cleanupTempFile(path);
+	}
+}
+
+// Create photo-specific media group buffer
+const photoBuffer = createMediaGroupBuffer({
+	emoji: "📷",
+	itemLabel: "photo",
+	itemLabelPlural: "photos",
+});
+
+/**
+ * Download a photo and return the local path.
+ */
+async function downloadPhoto(ctx: Context): Promise<string> {
+	const photos = ctx.message?.photo;
+	if (!photos || photos.length === 0) {
+		throw new Error("No photo in message");
+	}
+
+	// Get the largest photo
+	const file = await ctx.getFile();
+
+	const timestamp = Date.now();
+	const random = Math.random().toString(36).slice(2, 8);
+	const photoPath = `${TEMP_DIR}/photo_${timestamp}_${random}.jpg`;
+
+	// Download
+	const response = await fetch(
+		`https://api.telegram.org/file/bot${ctx.api.token}/${file.file_path}`,
+	);
+	const buffer = await response.arrayBuffer();
+	await Bun.write(photoPath, buffer);
+
+	return photoPath;
+}
+
+/**
+ * Process photos with Claude.
+ */
+async function processPhotos(
+	ctx: Context,
+	photoPaths: string[],
+	caption: string | undefined,
+	userId: number,
+	username: string,
+	chatId: number,
+): Promise<void> {
+	// Mark processing started
+	const stopProcessing = session.startProcessing();
+
+	// Build prompt
+	let prompt: string;
+	if (photoPaths.length === 1) {
+		prompt = caption
+			? `[Photo: ${photoPaths[0]}]\n\n${caption}`
+			: `Please analyze this image: ${photoPaths[0]}`;
+	} else {
+		const pathsList = photoPaths.map((p, i) => `${i + 1}. ${p}`).join("\n");
+		prompt = caption
+			? `[Photos:\n${pathsList}]\n\n${caption}`
+			: `Please analyze these ${photoPaths.length} images:\n${pathsList}`;
+	}
+
+	// Start typing
+	const typing = startTypingIndicator(ctx);
+
+	// Create streaming state
+	const state = new StreamingState();
+	const statusCallback = createStatusCallback(ctx, state);
+
+	try {
+		const response = await session.sendMessageStreaming(
+			prompt,
+			username,
+			userId,
+			statusCallback,
+			chatId,
+			ctx,
+		);
+
+		await auditLog(userId, username, "PHOTO", prompt, response);
+	} catch (error) {
+		await handleProcessingError(ctx, error, state.toolMessages);
+	} finally {
+		stopProcessing();
+		typing.stop();
+		// Clean up temp files
+		cleanupTempFiles(photoPaths);
+	}
+}
+
+/**
+ * Handle incoming photo messages.
+ */
+export async function handlePhoto(ctx: Context): Promise<void> {
+	const userId = ctx.from?.id;
+	const username = ctx.from?.username || "unknown";
+	const chatId = ctx.chat?.id;
+	const mediaGroupId = ctx.message?.media_group_id;
+
+	if (!userId || !chatId) {
+		return;
+	}
+
+	// 1. Authorization check
+	if (!isAuthorized(userId, ALLOWED_USERS)) {
+		await ctx.reply("Unauthorized. Contact the bot owner for access.");
+		return;
+	}
+
+	// 2. For single photos, show status and rate limit early
+	let statusMsg: Awaited<ReturnType<typeof ctx.reply>> | null = null;
+	if (!mediaGroupId) {
+		console.log(`Received photo from @${username}`);
+		// Rate limit
+		const [allowed, retryAfter] = rateLimiter.check(userId);
+		if (!allowed && retryAfter !== undefined) {
+			await auditLogRateLimit(userId, username, retryAfter);
+			await ctx.reply(
+				`⏳ Rate limited. Please wait ${retryAfter.toFixed(1)} seconds.`,
+			);
+			return;
+		}
+
+		// Show status immediately
+		statusMsg = await ctx.reply("📷 Processing image...");
+	}
+
+	// 3. Download photo
+	let photoPath: string;
+	try {
+		photoPath = await downloadPhoto(ctx);
+	} catch (error) {
+		console.error("Failed to download photo:", error);
+		if (statusMsg) {
+			try {
+				await ctx.api.editMessageText(
+					statusMsg.chat.id,
+					statusMsg.message_id,
+					"❌ Failed to download photo.",
+				);
+			} catch (editError) {
+				console.debug("Failed to edit status message:", editError);
+				await ctx.reply("❌ Failed to download photo.");
+			}
+		} else {
+			await ctx.reply("❌ Failed to download photo.");
+		}
+		return;
+	}
+
+	// 4. Single photo - process immediately
+	if (!mediaGroupId && statusMsg) {
+		await processPhotos(
+			ctx,
+			[photoPath],
+			ctx.message?.caption,
+			userId,
+			username,
+			chatId,
+		);
+
+		// Clean up status message
+		try {
+			await ctx.api.deleteMessage(statusMsg.chat.id, statusMsg.message_id);
+		} catch (error) {
+			console.debug("Failed to delete status message:", error);
+		}
+		return;
+	}
+
+	// 5. Media group - buffer with timeout
+	if (!mediaGroupId) return; // TypeScript guard
+
+	await photoBuffer.addToGroup(
+		mediaGroupId,
+		photoPath,
+		ctx,
+		userId,
+		username,
+		processPhotos,
+	);
+}

package/src/handlers/streaming.ts

@@ -0,0 +1,231 @@
+/**
+ * Shared streaming callback for Claude Telegram Bot handlers.
+ *
+ * Provides a reusable status callback for streaming Claude responses.
+ */
+
+import type { Context } from "grammy";
+import type { Message } from "grammy/types";
+import { InlineKeyboard } from "grammy";
+import type { StatusCallback } from "../types";
+import { convertMarkdownToHtml, escapeHtml } from "../formatting";
+import {
+  TELEGRAM_MESSAGE_LIMIT,
+  TELEGRAM_SAFE_LIMIT,
+  STREAMING_THROTTLE_MS,
+  BUTTON_LABEL_MAX_LENGTH,
+} from "../config";
+
+/**
+ * Create inline keyboard for ask_user options.
+ */
+export function createAskUserKeyboard(
+  requestId: string,
+  options: string[]
+): InlineKeyboard {
+  const keyboard = new InlineKeyboard();
+  for (let idx = 0; idx < options.length; idx++) {
+    const option = options[idx]!;
+    // Truncate long options for button display
+    const display =
+      option.length > BUTTON_LABEL_MAX_LENGTH
+        ? option.slice(0, BUTTON_LABEL_MAX_LENGTH) + "..."
+        : option;
+    const callbackData = `askuser:${requestId}:${idx}`;
+    keyboard.text(display, callbackData).row();
+  }
+  return keyboard;
+}
+
+/**
+ * Check for pending ask-user requests and send inline keyboards.
+ */
+export async function checkPendingAskUserRequests(
+  ctx: Context,
+  chatId: number
+): Promise<boolean> {
+  const glob = new Bun.Glob("ask-user-*.json");
+  let buttonsSent = false;
+
+  for await (const filename of glob.scan({ cwd: "/tmp", absolute: false })) {
+    const filepath = `/tmp/${filename}`;
+    try {
+      const file = Bun.file(filepath);
+      const text = await file.text();
+      const data = JSON.parse(text);
+
+      // Only process pending requests for this chat
+      if (data.status !== "pending") continue;
+      if (String(data.chat_id) !== String(chatId)) continue;
+
+      const question = data.question || "Please choose:";
+      const options = data.options || [];
+      const requestId = data.request_id || "";
+
+      if (options.length > 0 && requestId) {
+        const keyboard = createAskUserKeyboard(requestId, options);
+        await ctx.reply(`❓ ${question}`, { reply_markup: keyboard });
+        buttonsSent = true;
+
+        // Mark as sent
+        data.status = "sent";
+        await Bun.write(filepath, JSON.stringify(data));
+      }
+    } catch (error) {
+      console.warn(`Failed to process ask-user file ${filepath}:`, error);
+    }
+  }
+
+  return buttonsSent;
+}
+
+/**
+ * Tracks state for streaming message updates.
+ */
+export class StreamingState {
+  textMessages = new Map<number, Message>(); // segment_id -> telegram message
+  toolMessages: Message[] = []; // ephemeral tool status messages
+  lastEditTimes = new Map<number, number>(); // segment_id -> last edit time
+  lastContent = new Map<number, string>(); // segment_id -> last sent content
+}
+
+/**
+ * Create a status callback for streaming updates.
+ */
+export function createStatusCallback(
+  ctx: Context,
+  state: StreamingState
+): StatusCallback {
+  return async (statusType: string, content: string, segmentId?: number) => {
+    try {
+      if (statusType === "thinking") {
+        // Show thinking inline, compact (first 500 chars)
+        const preview =
+          content.length > 500 ? content.slice(0, 500) + "..." : content;
+        const escaped = escapeHtml(preview);
+        const thinkingMsg = await ctx.reply(`🧠 <i>${escaped}</i>`, {
+          parse_mode: "HTML",
+        });
+        state.toolMessages.push(thinkingMsg);
+      } else if (statusType === "tool") {
+        const toolMsg = await ctx.reply(content, { parse_mode: "HTML" });
+        state.toolMessages.push(toolMsg);
+      } else if (statusType === "text" && segmentId !== undefined) {
+        const now = Date.now();
+        const lastEdit = state.lastEditTimes.get(segmentId) || 0;
+
+        if (!state.textMessages.has(segmentId)) {
+          // New segment - create message
+          const display =
+            content.length > TELEGRAM_SAFE_LIMIT
+              ? content.slice(0, TELEGRAM_SAFE_LIMIT) + "..."
+              : content;
+          const formatted = convertMarkdownToHtml(display);
+          try {
+            const msg = await ctx.reply(formatted, { parse_mode: "HTML" });
+            state.textMessages.set(segmentId, msg);
+            state.lastContent.set(segmentId, formatted);
+          } catch (htmlError) {
+            // HTML parse failed, fall back to plain text
+            console.debug("HTML reply failed, using plain text:", htmlError);
+            const msg = await ctx.reply(formatted);
+            state.textMessages.set(segmentId, msg);
+            state.lastContent.set(segmentId, formatted);
+          }
+          state.lastEditTimes.set(segmentId, now);
+        } else if (now - lastEdit > STREAMING_THROTTLE_MS) {
+          // Update existing segment message (throttled)
+          const msg = state.textMessages.get(segmentId)!;
+          const display =
+            content.length > TELEGRAM_SAFE_LIMIT
+              ? content.slice(0, TELEGRAM_SAFE_LIMIT) + "..."
+              : content;
+          const formatted = convertMarkdownToHtml(display);
+          // Skip if content unchanged
+          if (formatted === state.lastContent.get(segmentId)) {
+            return;
+          }
+          try {
+            await ctx.api.editMessageText(
+              msg.chat.id,
+              msg.message_id,
+              formatted,
+              {
+                parse_mode: "HTML",
+              }
+            );
+            state.lastContent.set(segmentId, formatted);
+          } catch (htmlError) {
+            console.debug("HTML edit failed, trying plain text:", htmlError);
+            try {
+              await ctx.api.editMessageText(
+                msg.chat.id,
+                msg.message_id,
+                formatted
+              );
+              state.lastContent.set(segmentId, formatted);
+            } catch (editError) {
+              console.debug("Edit message failed:", editError);
+            }
+          }
+          state.lastEditTimes.set(segmentId, now);
+        }
+      } else if (statusType === "segment_end" && segmentId !== undefined) {
+        if (state.textMessages.has(segmentId) && content) {
+          const msg = state.textMessages.get(segmentId)!;
+          const formatted = convertMarkdownToHtml(content);
+
+          // Skip if content unchanged
+          if (formatted === state.lastContent.get(segmentId)) {
+            return;
+          }
+
+          if (formatted.length <= TELEGRAM_MESSAGE_LIMIT) {
+            try {
+              await ctx.api.editMessageText(
+                msg.chat.id,
+                msg.message_id,
+                formatted,
+                {
+                  parse_mode: "HTML",
+                }
+              );
+            } catch (error) {
+              console.debug("Failed to edit final message:", error);
+            }
+          } else {
+            // Too long - delete and split
+            try {
+              await ctx.api.deleteMessage(msg.chat.id, msg.message_id);
+            } catch (error) {
+              console.debug("Failed to delete message for splitting:", error);
+            }
+            for (let i = 0; i < formatted.length; i += TELEGRAM_SAFE_LIMIT) {
+              const chunk = formatted.slice(i, i + TELEGRAM_SAFE_LIMIT);
+              try {
+                await ctx.reply(chunk, { parse_mode: "HTML" });
+              } catch (htmlError) {
+                console.debug(
+                  "HTML chunk failed, using plain text:",
+                  htmlError
+                );
+                await ctx.reply(chunk);
+              }
+            }
+          }
+        }
+      } else if (statusType === "done") {
+        // Delete tool messages - text messages stay
+        for (const toolMsg of state.toolMessages) {
+          try {
+            await ctx.api.deleteMessage(toolMsg.chat.id, toolMsg.message_id);
+          } catch (error) {
+            console.debug("Failed to delete tool message:", error);
+          }
+        }
+      }
+    } catch (error) {
+      console.error("Status callback error:", error);
+    }
+  };
+}