daycare-cli 0.0.0-canary.00a24ac

package/dist/plugins/telegram/connector.js

@@ -0,0 +1,903 @@
+import { promises as fs } from "node:fs";
+import path from "node:path";
+import TelegramBot from "node-telegram-bot-api";
+import { agentPathConnector } from "../../engine/agents/ops/agentPathBuild.js";
+import { agentPath } from "../../engine/agents/ops/agentPathTypes.js";
+import { getLogger } from "../../log.js";
+import { markdownToTelegramHtml } from "./markdownToTelegramHtml.js";
+import { telegramMessageSplit } from "./telegramMessageSplit.js";
+const logger = getLogger("plugin.telegram");
+const TELEGRAM_MESSAGE_FORMAT_PROMPT = [
+    "Format messages using GitHub-flavored markdown (GFM).",
+    "Supported: **bold**, *italic*, ~~strikethrough~~, `inline code`, ```code blocks``` (with optional language), [links](url), > blockquotes, and lists (- or 1.).",
+    "Headers (# Title) render as bold text.",
+    "Tables render as plain text.",
+    "Task lists (- [x] item) render with checkbox symbols.",
+    "Do NOT use raw HTML tags; they will be escaped.",
+    "Keep formatting simple and well-nested."
+].join(" ");
+const TELEGRAM_MESSAGE_MAX_LENGTH = 4096;
+const TELEGRAM_CAPTION_MAX_LENGTH = 1024;
+const TELEGRAM_COMMAND_UPDATE_DEBOUNCE_MS = 1000;
+const TELEGRAM_UNAUTHORIZED_MESSAGE = "🚫 You are not authorized to use this bot. Please contact the system administrator to request access.";
+export class TelegramConnector {
+    capabilities = {
+        sendText: true,
+        sendFiles: {
+            modes: ["document", "photo", "video", "voice"]
+        },
+        messageFormatPrompt: TELEGRAM_MESSAGE_FORMAT_PROMPT,
+        reactions: true,
+        typing: true
+    };
+    bot;
+    handlers = [];
+    commandHandlers = [];
+    pollingEnabled;
+    statePath;
+    lastUpdateId = null;
+    fileStore;
+    dataDir;
+    persistTimer = null;
+    typingTimers = new Map();
+    startingPolling = false;
+    commandSyncEnabled = false;
+    pendingCommands = [];
+    commandSyncTimer = null;
+    webAppUrl = null;
+    allowedUids;
+    mode;
+    sendReplies;
+    sendRepliesInGroups;
+    shuttingDown = false;
+    clearWebhookOnStart;
+    clearedWebhook = false;
+    cachedFilesByTelegramId = new Map();
+    pendingFileDownloads = new Map();
+    constructor(options) {
+        logger.debug(`init: TelegramConnector constructor polling=${options.polling} clearWebhook=${options.clearWebhook} dataDir=${options.dataDir}`);
+        this.pollingEnabled = options.polling ?? true;
+        this.clearWebhookOnStart = options.clearWebhook ?? true;
+        this.webAppUrl = options.webAppUrl?.trim() ? options.webAppUrl.trim() : null;
+        this.fileStore = options.fileStore;
+        this.dataDir = options.dataDir;
+        this.mode = options.mode ?? "private";
+        this.sendReplies = options.sendReplies ?? false;
+        this.sendRepliesInGroups = options.sendRepliesInGroups ?? true;
+        this.allowedUids = new Set(options.allowedUids.map((uid) => String(uid)));
+        this.statePath =
+            options.statePath === undefined ? path.join(this.dataDir, "telegram-offset.json") : options.statePath;
+        if (this.statePath) {
+            this.statePath = path.resolve(this.statePath);
+        }
+        logger.debug(`event: State path configured statePath=${this.statePath} pollingEnabled=${this.pollingEnabled}`);
+        this.bot = new TelegramBot(options.token, { polling: false });
+        logger.debug("create: TelegramBot instance created");
+        const originalProcessUpdate = this.bot.processUpdate.bind(this.bot);
+        this.bot.processUpdate = (update) => {
+            logger.debug(`update: Processing Telegram update updateId=${update.update_id}`);
+            this.trackUpdate(update);
+            return originalProcessUpdate(update);
+        };
+        this.bot.on("message", async (message) => {
+            const chatType = message.chat?.type;
+            if (chatType !== "private" && chatType !== "group" && chatType !== "supergroup") {
+                logger.debug(`skip: Skipping unsupported chat type=${chatType} chatId=${message.chat?.id}`);
+                return;
+            }
+            const senderId = message.from?.id ?? message.chat?.id;
+            if (!this.isAllowedUid(senderId)) {
+                logger.info({ senderId, chatId: message.chat?.id }, "skip: Skipping telegram message from unapproved uid");
+                if (this.mode === "private") {
+                    await this.bot.sendMessage(String(message.chat.id), TELEGRAM_UNAUTHORIZED_MESSAGE);
+                }
+                return;
+            }
+            logger.debug(`receive: Received Telegram message chatId=${message.chat.id} fromId=${message.from?.id} messageId=${message.message_id} hasText=${!!message.text} hasCaption=${!!message.caption} hasPhoto=${!!message.photo} hasDocument=${!!message.document} hasVoice=${!!message.voice} hasAudio=${!!message.audio} hasSticker=${!!message.sticker}`);
+            const rawText = typeof message.text === "string" ? message.text : null;
+            const trimmedText = rawText?.trim() ?? "";
+            const isCommand = trimmedText.startsWith("/");
+            const channelId = String(message.chat.id);
+            const telegramUserId = String(senderId);
+            const path = agentPath(`${agentPathConnector(telegramUserId, "telegram")}/${channelId}/${telegramUserId}`);
+            const context = {
+                messageId: message.message_id ? String(message.message_id) : undefined
+            };
+            if (isCommand && rawText) {
+                logger.debug(`event: Dispatching to command handlers handlerCount=${this.commandHandlers.length} path=${path}`);
+                for (const handler of this.commandHandlers) {
+                    await handler(rawText, context, path);
+                }
+                logger.debug(`event: All command handlers completed path=${path}`);
+                return;
+            }
+            const files = await this.extractFiles(message);
+            logger.debug(`event: Extracted files from message fileCount=${files.length}`);
+            const documentNoticeText = this.documentNoticeText(message, files);
+            const payload = {
+                text: rawText ?? message.caption ?? documentNoticeText,
+                files: files.length > 0 ? files : undefined
+            };
+            logger.debug(`event: Dispatching to handlers handlerCount=${this.handlers.length} path=${path}`);
+            for (const handler of this.handlers) {
+                await handler(payload, context, path);
+            }
+            logger.debug(`event: All handlers completed path=${path}`);
+        });
+        this.bot.on("polling_error", (error) => {
+            if (this.shuttingDown) {
+                return;
+            }
+            this.handlePollingError(error);
+        });
+        if (options.enableGracefulShutdown ?? true) {
+            this.attachSignalHandlers();
+        }
+        void this.initialize();
+    }
+    onMessage(handler) {
+        this.handlers.push(handler);
+        return () => {
+            const index = this.handlers.indexOf(handler);
+            if (index !== -1) {
+                this.handlers.splice(index, 1);
+            }
+        };
+    }
+    onCommand(handler) {
+        this.commandHandlers.push(handler);
+        return () => {
+            const index = this.commandHandlers.indexOf(handler);
+            if (index !== -1) {
+                this.commandHandlers.splice(index, 1);
+            }
+        };
+    }
+    botGet() {
+        return this.bot;
+    }
+    updateCommands(commands) {
+        this.pendingCommands = commands;
+        if (!this.commandSyncEnabled) {
+            return;
+        }
+        this.scheduleCommandSync();
+    }
+    commandSyncStart() {
+        this.commandSyncEnabled = true;
+        this.scheduleCommandSync();
+    }
+    async sendMessage(targetId, message) {
+        logger.debug(`event: sendMessage() called targetId=${targetId} hasText=${!!message.text} textLength=${message.text?.length ?? 0} fileCount=${message.files?.length ?? 0}`);
+        if (!this.isAllowedTarget(targetId, "sendMessage")) {
+            return;
+        }
+        const chatId = telegramTargetChatIdResolve(targetId);
+        const files = message.files ?? [];
+        if (files.length === 0) {
+            logger.debug(`send: Sending text-only message targetId=${targetId} chatId=${chatId}`);
+            await this.sendTextWithFallback(chatId, message.text ?? "", {
+                ...messageReplyOptionsBuild(message, chatId, this.sendReplies, this.sendRepliesInGroups),
+                ...(message.buttons?.length ? { reply_markup: messageButtonsBuild(message.buttons) } : {})
+            });
+            logger.debug(`send: Text message sent targetId=${targetId} chatId=${chatId}`);
+            return;
+        }
+        const first = files[0];
+        if (!first) {
+            logger.debug("event: No first file found, returning");
+            return;
+        }
+        const rest = files.slice(1);
+        const caption = message.text ?? undefined;
+        const captionChunks = caption ? telegramMessageSplit(caption, TELEGRAM_CAPTION_MAX_LENGTH) : [];
+        const sendCaption = captionChunks.length === 1 ? captionChunks[0] : undefined;
+        if (!sendCaption && caption) {
+            logger.debug(`send: Caption too long for Telegram; sending as separate message targetId=${targetId} captionLength=${caption.length}`);
+        }
+        logger.debug(`send: Sending first file targetId=${targetId} chatId=${chatId} fileName=${first.name} mimeType=${first.mimeType} hasCaption=${!!sendCaption}`);
+        await this.sendFile(chatId, first, sendCaption, message.replyToMessageId);
+        for (const file of rest) {
+            logger.debug(`send: Sending additional file targetId=${targetId} chatId=${chatId} fileName=${file.name} mimeType=${file.mimeType}`);
+            await this.sendFile(chatId, file);
+        }
+        if (!sendCaption && caption) {
+            await this.sendTextWithFallback(chatId, caption);
+        }
+        logger.debug(`send: All files sent targetId=${targetId} chatId=${chatId} totalFiles=${files.length}`);
+    }
+    startTyping(targetId) {
+        if (!this.isAllowedTarget(targetId, "startTyping")) {
+            return () => undefined;
+        }
+        const chatId = telegramTargetChatIdResolve(targetId);
+        const key = chatId;
+        if (this.typingTimers.has(key)) {
+            return () => {
+                this.stopTyping(key);
+            };
+        }
+        const send = () => {
+            void this.bot.sendChatAction(chatId, "typing").catch((error) => {
+                logger.warn({ error }, "error: Telegram typing failed");
+            });
+        };
+        send();
+        const timer = setInterval(send, 4000);
+        this.typingTimers.set(key, timer);
+        return () => {
+            this.stopTyping(key);
+        };
+    }
+    async setReaction(targetId, messageId, reaction) {
+        if (!this.isAllowedTarget(targetId, "setReaction")) {
+            return;
+        }
+        const chatId = telegramTargetChatIdResolve(targetId);
+        const emoji = reaction;
+        await this.bot.setMessageReaction(chatId, Number(messageId), {
+            reaction: [{ type: "emoji", emoji }]
+        });
+    }
+    async sendFile(targetId, file, caption, replyToMessageId) {
+        const htmlCaption = caption ? markdownToTelegramHtml(caption) : undefined;
+        const useHtmlCaption = !!htmlCaption && htmlCaption.length <= TELEGRAM_CAPTION_MAX_LENGTH;
+        const options = useHtmlCaption
+            ? {
+                caption: htmlCaption,
+                parse_mode: "HTML",
+                ...messageReplyOptionsBuild({ replyToMessageId }, targetId, this.sendReplies, this.sendRepliesInGroups)
+            }
+            : caption
+                ? {
+                    caption,
+                    ...messageReplyOptionsBuild({ replyToMessageId }, targetId, this.sendReplies, this.sendRepliesInGroups)
+                }
+                : messageReplyOptionsBuild({ replyToMessageId }, targetId, this.sendReplies, this.sendRepliesInGroups);
+        const sendAs = file.sendAs ?? "auto";
+        try {
+            await this.sendFileWithOptions(targetId, file, sendAs, options);
+        }
+        catch (error) {
+            if (!caption || !useHtmlCaption || !isTelegramParseError(error)) {
+                throw error;
+            }
+            logger.warn({ error }, "error: Telegram HTML caption parse error; retrying without parse_mode");
+            await this.sendFileWithOptions(targetId, file, sendAs, {
+                caption,
+                ...messageReplyOptionsBuild({ replyToMessageId }, targetId, this.sendReplies, this.sendRepliesInGroups)
+            });
+        }
+    }
+    async sendTextWithFallback(targetId, text, options) {
+        const chunks = telegramMessageSplit(text, TELEGRAM_MESSAGE_MAX_LENGTH);
+        for (const [index, chunk] of chunks.entries()) {
+            await this.sendTextChunk(targetId, chunk, index === chunks.length - 1 ? options : undefined);
+        }
+    }
+    async sendTextChunk(targetId, text, options) {
+        const html = markdownToTelegramHtml(text);
+        const useHtml = html.length <= TELEGRAM_MESSAGE_MAX_LENGTH;
+        try {
+            if (useHtml) {
+                await this.bot.sendMessage(targetId, html, {
+                    ...options,
+                    parse_mode: "HTML"
+                });
+                return;
+            }
+            await this.bot.sendMessage(targetId, text, options);
+        }
+        catch (error) {
+            if (!useHtml || !isTelegramParseError(error)) {
+                throw error;
+            }
+            logger.warn({ error }, "error: Telegram HTML parse error; retrying without parse_mode");
+            await this.bot.sendMessage(targetId, text, options);
+        }
+    }
+    async sendFileWithOptions(targetId, file, sendAs, options) {
+        const fileOptions = {
+            filename: file.name,
+            contentType: file.mimeType
+        };
+        if (sendAs === "photo") {
+            await this.bot.sendPhoto(targetId, file.path, options, fileOptions);
+            return;
+        }
+        if (sendAs === "video") {
+            await this.bot.sendVideo(targetId, file.path, options, fileOptions);
+            return;
+        }
+        if (sendAs === "document") {
+            await this.bot.sendDocument(targetId, file.path, options, fileOptions);
+            return;
+        }
+        if (sendAs === "voice") {
+            await this.bot.sendVoice(targetId, file.path, options, fileOptions);
+            return;
+        }
+        if (file.mimeType.startsWith("image/")) {
+            await this.bot.sendPhoto(targetId, file.path, options, fileOptions);
+            return;
+        }
+        if (file.mimeType.startsWith("video/")) {
+            await this.bot.sendVideo(targetId, file.path, options, fileOptions);
+            return;
+        }
+        await this.bot.sendDocument(targetId, file.path, options, fileOptions);
+    }
+    async initialize() {
+        logger.debug(`init: initialize() starting pollingEnabled=${this.pollingEnabled} clearWebhookOnStart=${this.clearWebhookOnStart}`);
+        if (this.pollingEnabled && this.clearWebhookOnStart) {
+            logger.debug("event: Clearing webhook before polling");
+            await this.ensureWebhookCleared();
+        }
+        logger.debug("load: Loading state");
+        await this.loadState();
+        if (this.pollingEnabled) {
+            logger.debug("start: Starting polling");
+            await this.startPolling();
+        }
+        logger.debug("init: initialize() complete");
+    }
+    trackUpdate(update) {
+        if (typeof update.update_id !== "number") {
+            return;
+        }
+        if (this.lastUpdateId === null || update.update_id > this.lastUpdateId) {
+            this.lastUpdateId = update.update_id;
+            this.schedulePersist();
+        }
+    }
+    async loadState() {
+        if (!this.statePath) {
+            return;
+        }
+        try {
+            const content = await fs.readFile(this.statePath, "utf8");
+            const trimmed = content.trim();
+            if (!trimmed) {
+                return;
+            }
+            try {
+                const parsed = JSON.parse(trimmed);
+                const state = connectorStateParse(parsed);
+                if (!state) {
+                    throw new Error("invalid connector state schema");
+                }
+                if (typeof state.lastUpdateId === "number") {
+                    this.lastUpdateId = state.lastUpdateId;
+                }
+                if (state.filesByTelegramId && typeof state.filesByTelegramId === "object") {
+                    for (const [fileId, reference] of Object.entries(state.filesByTelegramId)) {
+                        this.cachedFilesByTelegramId.set(fileId, reference);
+                    }
+                }
+                return;
+            }
+            catch (error) {
+                const recovered = recoverLastUpdateId(trimmed);
+                if (recovered !== null) {
+                    this.lastUpdateId = recovered;
+                    logger.warn({ statePath: this.statePath, lastUpdateId: recovered }, "event: Telegram connector state was invalid JSON; recovered lastUpdateId");
+                    await this.persistState();
+                    return;
+                }
+                await this.quarantineStateFile();
+                logger.warn({ error, statePath: this.statePath }, "error: Telegram connector state load failed");
+            }
+        }
+        catch (error) {
+            if (error.code !== "ENOENT") {
+                logger.warn({ error, statePath: this.statePath }, "error: Telegram connector state load failed");
+            }
+        }
+    }
+    schedulePersist() {
+        if (!this.statePath || this.persistTimer) {
+            return;
+        }
+        this.persistTimer = setTimeout(() => {
+            void this.persistState();
+        }, 500);
+    }
+    async persistState() {
+        if (!this.statePath || (this.lastUpdateId === null && this.cachedFilesByTelegramId.size === 0)) {
+            return;
+        }
+        if (this.persistTimer) {
+            clearTimeout(this.persistTimer);
+            this.persistTimer = null;
+        }
+        try {
+            await fs.mkdir(path.dirname(this.statePath), { recursive: true });
+            const state = {};
+            if (this.lastUpdateId !== null) {
+                state.lastUpdateId = this.lastUpdateId;
+            }
+            if (this.cachedFilesByTelegramId.size > 0) {
+                state.filesByTelegramId = Object.fromEntries(this.cachedFilesByTelegramId.entries());
+            }
+            const payload = JSON.stringify(state);
+            const tmpPath = `${this.statePath}.tmp-${process.pid}-${Date.now()}`;
+            await fs.writeFile(tmpPath, payload, "utf8");
+            await fs.rename(tmpPath, this.statePath);
+        }
+        catch (error) {
+            logger.warn({ error, statePath: this.statePath }, "error: Telegram connector state persist failed");
+        }
+    }
+    async quarantineStateFile() {
+        if (!this.statePath) {
+            return;
+        }
+        try {
+            const dir = path.dirname(this.statePath);
+            const name = path.basename(this.statePath);
+            const target = path.join(dir, `${name}.corrupt-${Date.now()}`);
+            await fs.rename(this.statePath, target);
+            logger.warn({ statePath: this.statePath, quarantinePath: target }, "event: Telegram state file quarantined");
+        }
+        catch (error) {
+            logger.warn({ error, statePath: this.statePath }, "error: Failed to quarantine telegram state file");
+        }
+    }
+    async startPolling() {
+        logger.debug(`event: startPolling() called pollingEnabled=${this.pollingEnabled} isPolling=${this.bot.isPolling()}`);
+        if (!this.pollingEnabled) {
+            logger.debug("event: Polling disabled, returning");
+            return;
+        }
+        if (this.startingPolling) {
+            logger.debug("start: Polling start already in progress, returning");
+            return;
+        }
+        if (this.bot.isPolling()) {
+            logger.debug("event: Already polling, returning");
+            return;
+        }
+        const pollingOptions = {
+            autoStart: true,
+            params: {}
+        };
+        if (this.lastUpdateId !== null) {
+            pollingOptions.params = {
+                offset: this.lastUpdateId + 1
+            };
+            logger.debug(`update: Resuming from last update ID offset=${this.lastUpdateId + 1}`);
+        }
+        this.startingPolling = true;
+        try {
+            logger.debug("start: Starting Telegram polling");
+            await this.bot.startPolling({
+                restart: true,
+                polling: pollingOptions
+            });
+            if (this.shuttingDown || !this.pollingEnabled) {
+                logger.debug("start: Polling disabled after start, stopping");
+                await this.stopPolling("disabled");
+                return;
+            }
+            logger.debug("start: Telegram polling started successfully");
+        }
+        catch (error) {
+            this.handlePollingError(error);
+        }
+        finally {
+            this.startingPolling = false;
+        }
+    }
+    handlePollingError(error) {
+        if (isTelegramConflictError(error) && !this.clearedWebhook) {
+            logger.warn({ error }, "event: Telegram polling conflict; clearing webhook");
+            void this.ensureWebhookCleared();
+            return;
+        }
+        logger.warn({ error }, "error: Telegram polling error; relying on library restart");
+    }
+    isAllowedUid(uid) {
+        if (this.mode === "public") {
+            return true;
+        }
+        if (uid === null || uid === undefined) {
+            return false;
+        }
+        return this.allowedUids.has(String(uid));
+    }
+    isAllowedTarget(targetId, action) {
+        const candidates = telegramTargetAllowedCandidatesResolve(targetId);
+        for (const candidate of candidates) {
+            if (this.isAllowedUid(candidate)) {
+                return true;
+            }
+        }
+        logger.warn({
+            targetId,
+            action,
+            chatId: telegramTargetChatIdResolve(targetId),
+            senderId: telegramTargetSenderIdResolve(targetId)
+        }, "event: Blocked telegram action for unapproved uid");
+        return false;
+    }
+    attachSignalHandlers() {
+        const handler = (signal) => {
+            void this.shutdown(signal);
+        };
+        process.once("SIGINT", handler);
+        process.once("SIGTERM", handler);
+    }
+    async shutdown(reason = "shutdown") {
+        logger.debug(`event: shutdown() called reason=${reason} alreadyShuttingDown=${this.shuttingDown}`);
+        if (this.shuttingDown) {
+            logger.debug("event: Already shutting down, returning");
+            return;
+        }
+        this.shuttingDown = true;
+        logger.debug("event: Beginning shutdown sequence");
+        if (this.persistTimer) {
+            logger.debug("event: Clearing persist timer");
+            clearTimeout(this.persistTimer);
+            this.persistTimer = null;
+        }
+        if (this.commandSyncTimer) {
+            logger.debug("event: Clearing command sync timer");
+            clearTimeout(this.commandSyncTimer);
+            this.commandSyncTimer = null;
+        }
+        logger.debug(`event: Clearing typing timers typingTimerCount=${this.typingTimers.size}`);
+        for (const timer of this.typingTimers.values()) {
+            clearInterval(timer);
+        }
+        this.typingTimers.clear();
+        try {
+            logger.debug("stop: Stopping polling");
+            await this.bot.stopPolling({ cancel: true, reason });
+            logger.debug("stop: Polling stopped");
+        }
+        catch (error) {
+            logger.warn({ error }, "error: Telegram polling stop failed");
+        }
+        logger.debug("event: Persisting state");
+        await this.persistState();
+        logger.debug("event: Shutdown complete");
+    }
+    async stopPolling(reason) {
+        try {
+            if (this.bot.isPolling()) {
+                await this.bot.stopPolling({ cancel: true, reason });
+            }
+        }
+        catch (error) {
+            logger.warn({ error }, "error: Telegram polling stop failed");
+        }
+    }
+    async ensureWebhookCleared() {
+        if (this.clearedWebhook) {
+            return;
+        }
+        try {
+            await this.bot.deleteWebHook();
+            this.clearedWebhook = true;
+            logger.info("event: Telegram webhook cleared for polling");
+        }
+        catch (error) {
+            logger.warn({ error }, "error: Failed to clear Telegram webhook");
+        }
+    }
+    stopTyping(key) {
+        const timer = this.typingTimers.get(key);
+        if (!timer) {
+            return;
+        }
+        clearInterval(timer);
+        this.typingTimers.delete(key);
+    }
+    async extractFiles(message) {
+        const files = [];
+        if (message.photo && message.photo.length > 0) {
+            const largest = message.photo.reduce((prev, current) => (current.file_size ?? 0) > (prev.file_size ?? 0) ? current : prev);
+            const stored = await this.downloadFile(largest.file_id, `photo-${largest.file_id}.jpg`, "image/jpeg");
+            if (stored) {
+                files.push(stored);
+            }
+        }
+        if (message.document?.file_id) {
+            const stored = await this.downloadFile(message.document.file_id, message.document.file_name ?? `document-${message.document.file_id}`, message.document.mime_type ?? "application/octet-stream");
+            if (stored) {
+                files.push(stored);
+            }
+        }
+        if (message.voice?.file_id) {
+            const stored = await this.downloadFile(message.voice.file_id, `voice-${message.voice.file_id}.ogg`, message.voice.mime_type ?? "audio/ogg");
+            if (stored) {
+                files.push(stored);
+            }
+        }
+        if (message.audio?.file_id) {
+            const mimeType = message.audio.mime_type ?? "audio/mpeg";
+            const stored = await this.downloadFile(message.audio.file_id, (message.audio.title?.trim() ? `${message.audio.title.trim()}.mp3` : null) ??
+                `audio-${message.audio.file_id}.mp3`, mimeType);
+            if (stored) {
+                files.push(stored);
+            }
+        }
+        if (message.sticker?.file_id) {
+            const stickerType = this.stickerTypeResolve(message.sticker);
+            const stored = await this.downloadFile(message.sticker.file_id, `sticker-${message.sticker.file_id}.${stickerType.extension}`, stickerType.mimeType);
+            if (stored) {
+                files.push(stored);
+            }
+        }
+        return files;
+    }
+    stickerTypeResolve(sticker) {
+        if (sticker.is_video) {
+            return { extension: "webm", mimeType: "video/webm" };
+        }
+        if (sticker.is_animated) {
+            return { extension: "tgs", mimeType: "application/x-tgsticker" };
+        }
+        return { extension: "webp", mimeType: "image/webp" };
+    }
+    documentNoticeText(message, files) {
+        if (!message.document?.file_id) {
+            return null;
+        }
+        const fileName = message.document.file_name?.trim();
+        if (files.length > 0) {
+            if (fileName) {
+                return `Document received: ${fileName}.`;
+            }
+            return "Document received.";
+        }
+        if (fileName) {
+            return `Document received: ${fileName} (download failed).`;
+        }
+        return "Document received (download failed).";
+    }
+    async downloadFile(fileId, name, mimeType) {
+        const cached = this.cachedFilesByTelegramId.get(fileId);
+        if (cached) {
+            logger.debug({ fileId, path: cached.path }, "event: Reusing cached Telegram file by file_id");
+            return cached;
+        }
+        const pending = this.pendingFileDownloads.get(fileId);
+        if (pending) {
+            return pending;
+        }
+        const downloadPromise = this.downloadFileFromTelegram(fileId, name, mimeType);
+        this.pendingFileDownloads.set(fileId, downloadPromise);
+        try {
+            const stored = await downloadPromise;
+            if (stored) {
+                this.cachedFilesByTelegramId.set(fileId, stored);
+                this.schedulePersist();
+            }
+            return stored;
+        }
+        finally {
+            this.pendingFileDownloads.delete(fileId);
+        }
+    }
+    async downloadFileFromTelegram(fileId, name, mimeType) {
+        const downloadDir = path.join(this.dataDir, "downloads");
+        await fs.mkdir(downloadDir, { recursive: true });
+        try {
+            const downloadedPath = await this.bot.downloadFile(fileId, downloadDir);
+            const stored = await this.fileStore.saveFromPath({
+                name,
+                mimeType,
+                path: downloadedPath
+            });
+            await fs.rm(downloadedPath, { force: true });
+            return {
+                id: stored.id,
+                name: stored.name,
+                mimeType: stored.mimeType,
+                size: stored.size,
+                path: stored.path
+            };
+        }
+        catch (error) {
+            logger.warn({ error }, "error: Telegram file download failed");
+            return null;
+        }
+    }
+    scheduleCommandSync() {
+        if (this.commandSyncTimer) {
+            clearTimeout(this.commandSyncTimer);
+            this.commandSyncTimer = null;
+        }
+        this.commandSyncTimer = setTimeout(() => {
+            void this.commandSyncFlush();
+        }, TELEGRAM_COMMAND_UPDATE_DEBOUNCE_MS);
+    }
+    async commandSyncFlush() {
+        this.commandSyncTimer = null;
+        try {
+            await this.bot.setMyCommands(this.pendingCommands.map((command) => ({
+                command: command.command,
+                description: command.description
+            })), {
+                scope: {
+                    type: "all_private_chats"
+                }
+            });
+            logger.debug(`register: Telegram slash commands updated commandCount=${this.pendingCommands.length}`);
+        }
+        catch (error) {
+            logger.warn({ error }, "error: Failed to update Telegram slash commands");
+        }
+        try {
+            await this.menuButtonSync();
+        }
+        catch (error) {
+            logger.warn({ error }, "error: Failed to update Telegram chat menu button");
+        }
+    }
+    async menuButtonSync() {
+        const botWithMenu = this.bot;
+        if (typeof botWithMenu.setChatMenuButton !== "function") {
+            logger.debug("skip: Telegram API does not expose setChatMenuButton");
+            return;
+        }
+        if (!this.webAppUrl) {
+            await botWithMenu.setChatMenuButton({
+                menu_button: JSON.stringify({ type: "commands" })
+            });
+            logger.debug("register: Telegram chat menu button set to commands");
+            return;
+        }
+        await botWithMenu.setChatMenuButton({
+            menu_button: JSON.stringify({
+                type: "web_app",
+                text: "Open Daycare",
+                web_app: { url: this.webAppUrl }
+            })
+        });
+        logger.debug({ webAppUrl: this.webAppUrl }, "register: Telegram chat menu button set to web app");
+    }
+}
+function recoverLastUpdateId(content) {
+    const match = /"lastUpdateId"\s*:\s*(\d+)/.exec(content);
+    if (match?.[1]) {
+        const value = Number(match[1]);
+        return Number.isFinite(value) ? value : null;
+    }
+    return null;
+}
+function telegramTargetPartsResolve(targetId) {
+    const segments = targetId
+        .split("/")
+        .map((segment) => segment.trim())
+        .filter((segment) => segment.length > 0);
+    if (segments.length === 0) {
+        return { chatId: targetId.trim(), senderId: null };
+    }
+    if (segments.length === 1) {
+        return { chatId: segments[0], senderId: null };
+    }
+    return { chatId: segments[0], senderId: segments[1] ?? null };
+}
+function telegramTargetChatIdResolve(targetId) {
+    return telegramTargetPartsResolve(targetId).chatId;
+}
+function telegramTargetSenderIdResolve(targetId) {
+    return telegramTargetPartsResolve(targetId).senderId;
+}
+function telegramTargetAllowedCandidatesResolve(targetId) {
+    const { chatId, senderId } = telegramTargetPartsResolve(targetId);
+    const candidates = [targetId.trim(), chatId, senderId ?? ""].filter((value) => value.length > 0);
+    return Array.from(new Set(candidates));
+}
+function messageReplyOptionsBuild(message, targetId, sendReplies, sendRepliesInGroups) {
+    const shouldSendReply = sendReplies || (sendRepliesInGroups && targetIdIsGroupChat(targetId));
+    if (!shouldSendReply) {
+        return undefined;
+    }
+    const replyToMessageId = message.replyToMessageId;
+    if (!replyToMessageId) {
+        return undefined;
+    }
+    const parsed = Number(replyToMessageId);
+    if (!Number.isFinite(parsed)) {
+        return undefined;
+    }
+    return {
+        reply_to_message_id: parsed
+    };
+}
+function targetIdIsGroupChat(targetId) {
+    const parsed = Number(telegramTargetChatIdResolve(targetId));
+    return Number.isFinite(parsed) && parsed < 0;
+}
+function messageButtonsBuild(buttons) {
+    return {
+        inline_keyboard: buttons.map((button) => [
+            {
+                text: button.text,
+                url: button.url
+            }
+        ])
+    };
+}
+function connectorStateParse(value) {
+    if (!value || typeof value !== "object" || Array.isArray(value)) {
+        return null;
+    }
+    const record = value;
+    const state = {};
+    if (record.lastUpdateId !== undefined) {
+        if (typeof record.lastUpdateId !== "number") {
+            return null;
+        }
+        state.lastUpdateId = record.lastUpdateId;
+    }
+    if (record.filesByTelegramId !== undefined) {
+        const parsedFiles = connectorStateFilesParse(record.filesByTelegramId);
+        if (!parsedFiles) {
+            return null;
+        }
+        state.filesByTelegramId = parsedFiles;
+    }
+    return state;
+}
+function connectorStateFilesParse(value) {
+    if (!value || typeof value !== "object" || Array.isArray(value)) {
+        return null;
+    }
+    const parsed = {};
+    for (const [fileId, entry] of Object.entries(value)) {
+        const reference = fileReferenceParse(entry);
+        if (!reference) {
+            return null;
+        }
+        parsed[fileId] = reference;
+    }
+    return parsed;
+}
+function fileReferenceParse(value) {
+    if (!value || typeof value !== "object" || Array.isArray(value)) {
+        return null;
+    }
+    const record = value;
+    if (typeof record.id !== "string" ||
+        typeof record.name !== "string" ||
+        typeof record.path !== "string" ||
+        typeof record.mimeType !== "string" ||
+        typeof record.size !== "number") {
+        return null;
+    }
+    return {
+        id: record.id,
+        name: record.name,
+        path: record.path,
+        mimeType: record.mimeType,
+        size: record.size
+    };
+}
+function isTelegramParseError(error) {
+    if (!error || typeof error !== "object") {
+        return false;
+    }
+    const maybe = error;
+    if (maybe.code !== "ETELEGRAM") {
+        return false;
+    }
+    const description = maybe.response?.body?.description ?? maybe.message ?? "";
+    if (typeof description !== "string") {
+        return false;
+    }
+    const normalized = description.toLowerCase();
+    return normalized.includes("can't parse entities") || normalized.includes("cant parse entities");
+}
+function isTelegramConflictError(error) {
+    if (!error || typeof error !== "object") {
+        return false;
+    }
+    const maybe = error;
+    const status = maybe.response?.statusCode ?? maybe.response?.body?.error_code;
+    return maybe.code === "ETELEGRAM" && status === 409;
+}
+//# sourceMappingURL=connector.js.map