@mulmobridge/telegram 0.1.1 → 0.1.2

package/dist/api.d.ts

@@ -9,12 +9,20 @@ export interface TelegramPhotoSize {
     height: number;
     file_size?: number;
 }
+export interface TelegramDocument {
+    file_id: string;
+    file_unique_id: string;
+    file_name?: string;
+    mime_type?: string;
+    file_size?: number;
+}
 export interface TelegramMessage {
     message_id: number;
     chat: TelegramChat;
     from?: TelegramUser;
     text?: string;
     photo?: TelegramPhotoSize[];
+    document?: TelegramDocument;
     caption?: string;
     date: number;
 }
@@ -44,7 +52,13 @@ export interface GetUpdatesOptions {
 }
 export interface TelegramApi {
     getUpdates(opts?: GetUpdatesOptions): Promise<TelegramUpdate[]>;
-    sendMessage(chatId: number, text: string): Promise<void>;
-    downloadPhoto(fileId: string): Promise<string>;
+    /** Send a message and return its message_id (needed for editMessageText). */
+    sendMessage(chatId: number, text: string): Promise<number>;
+    /** Edit an existing message in place. Used for streaming text updates. */
+    editMessageText(chatId: number, messageId: number, text: string): Promise<void>;
+    /** Download any file by file_id via the Telegram getFile API.
+     *  Returns a data URL (`data:<mime>;base64,...`).
+     *  Works for photos, documents, audio, etc. */
+    downloadFile(fileId: string, fallbackMime?: string): Promise<string>;
 }
 export declare function createTelegramApi(opts: TelegramApiOptions): TelegramApi;

package/dist/api.js

@@ -36,8 +36,25 @@ export function createTelegramApi(opts) {
             if (!body.ok) {
                 throw new Error(`sendMessage API error: ${body.description ?? "unknown"}`);
             }
+            return body.result?.message_id ?? 0;
         },
-        async downloadPhoto(fileId) {
+        async editMessageText(chatId, messageId, text) {
+            const res = await fetchImpl(`${base}/editMessageText`, {
+                method: "POST",
+                headers: { "Content-Type": "application/json" },
+                body: JSON.stringify({
+                    chat_id: chatId,
+                    message_id: messageId,
+                    text,
+                }),
+            });
+            if (!res.ok) {
+                // editMessageText fails if the text is unchanged (Telegram
+                // returns 400 "message is not modified"). Swallow silently.
+                return;
+            }
+        },
+        async downloadFile(fileId, fallbackMime = "application/octet-stream") {
             const getFileRes = await fetchImpl(`${base}/getFile?file_id=${encodeURIComponent(fileId)}`);
             if (!getFileRes.ok) {
                 throw new Error(`getFile failed: ${getFileRes.status} ${await safeText(getFileRes)}`);
@@ -53,8 +70,13 @@ export function createTelegramApi(opts) {
             }
             const buffer = await fileRes.arrayBuffer();
             const b64 = Buffer.from(buffer).toString("base64");
+            // Prefer the caller-supplied MIME (Telegram's doc.mime_type is
+            // authoritative). Fall back to extension-based inference only
+            // when the caller passed the generic default.
             const ext = getFileBody.result.file_path.split(".").pop() ?? "";
-            const mediaType = mimeFromExtension(ext, "image/jpeg");
+            const mediaType = fallbackMime !== "application/octet-stream"
+                ? fallbackMime
+                : mimeFromExtension(ext, fallbackMime);
             return buildDataUrl(mediaType, b64);
         },
     };

package/dist/index.js

@@ -81,6 +81,10 @@ async function main() {
         allowlist,
         sendToMulmo: (chatId, text, attachments) => client.send(chatId, text, attachments),
     });
+    // Server → Telegram streaming text chunks (Phase C of #268).
+    client.onTextChunk((chunk) => {
+        router.handleTextChunk(chunk);
+    });
     // Server → Telegram async push (Phase B of #268).
     client.onPush((ev) => {
         router

package/dist/router.d.ts

@@ -18,6 +18,8 @@ export interface RouterDeps {
 export interface MessageRouter {
     handleMessage(msg: TelegramMessage): Promise<void>;
     handlePush(ev: PushEvent): Promise<void>;
+    /** Called for each streaming text chunk from the server. */
+    handleTextChunk(chunk: string): void;
     /** For tests / debugging: chat IDs we've already sent the
      *  access-denied notice to. */
     deniedAlreadyNotified(): ReadonlySet<number>;

package/dist/router.js

@@ -13,30 +13,107 @@ const defaultLog = {
     warn: (m) => console.warn(m),
     error: (m) => console.error(m),
 };
+// Minimum interval between editMessageText calls to avoid Telegram
+// rate limits. 1 second is conservative; Telegram allows ~30 edits
+// per minute per chat.
+const STREAM_EDIT_INTERVAL_MS = 1000;
 export function createMessageRouter(deps) {
     const { api, allowlist, sendToMulmo } = deps;
     const log = deps.log ?? defaultLog;
     // One denial reply per chat per bridge lifetime — restart clears.
     const deniedAlreadyNotified = new Set();
-    async function tryDownloadPhoto(msg) {
-        const hasPhoto = Array.isArray(msg.photo) && msg.photo.length > 0;
-        if (!hasPhoto)
-            return { attachments: [], failed: false };
-        const largest = msg.photo[msg.photo.length - 1];
-        try {
-            const dataUrl = await api.downloadPhoto(largest.file_id);
-            const parsed = parseDataUrl(dataUrl);
-            if (parsed) {
-                return {
-                    attachments: [{ mimeType: parsed.mimeType, data: parsed.data }],
-                    failed: false,
-                };
+    // Streaming state: while a relay is in flight, chunks accumulate
+    // here. A timer periodically flushes them via editMessageText.
+    let streamChatId = null;
+    let streamMessageId = null;
+    let streamAccumulated = "";
+    let streamDirty = false;
+    let streamTimer = null;
+    function startStream(chatId) {
+        streamChatId = chatId;
+        streamMessageId = null;
+        streamAccumulated = "";
+        streamDirty = false;
+        streamTimer = setInterval(flushStream, STREAM_EDIT_INTERVAL_MS);
+    }
+    function stopStream() {
+        if (streamTimer !== null) {
+            clearInterval(streamTimer);
+            streamTimer = null;
+        }
+        streamChatId = null;
+        streamMessageId = null;
+        streamAccumulated = "";
+        streamDirty = false;
+    }
+    function flushStream() {
+        if (!streamDirty || streamChatId === null)
+            return;
+        streamDirty = false;
+        const chatId = streamChatId;
+        const text = streamAccumulated || "…";
+        if (streamMessageId === null) {
+            // First flush: send a new message
+            api
+                .sendMessage(chatId, text)
+                .then((msgId) => {
+                streamMessageId = msgId;
+            })
+                .catch((err) => {
+                log.error(`[telegram] stream sendMessage failed: ${String(err)}`);
+            });
+        }
+        else {
+            // Subsequent flushes: edit existing message
+            api.editMessageText(chatId, streamMessageId, text).catch((err) => {
+                log.error(`[telegram] stream editMessage failed: ${String(err)}`);
+            });
+        }
+    }
+    // Download all media from a message. Telegram messages are usually
+    // exclusive (photo OR document), but forwarded messages or future
+    // API changes could carry both. We collect all available attachments
+    // rather than picking one.
+    async function tryDownloadAttachments(msg) {
+        const attachments = [];
+        let anyFailed = false;
+        if (Array.isArray(msg.photo) && msg.photo.length > 0) {
+            const largest = msg.photo[msg.photo.length - 1];
+            try {
+                const dataUrl = await api.downloadFile(largest.file_id, "image/jpeg");
+                const parsed = parseDataUrl(dataUrl);
+                if (parsed) {
+                    attachments.push({ mimeType: parsed.mimeType, data: parsed.data });
+                }
+            }
+            catch (err) {
+                log.error(`[telegram] photo download failed: ${String(err)}`);
+                anyFailed = true;
             }
         }
-        catch (err) {
-            log.error(`[telegram] photo download failed: ${String(err)}`);
+        if (msg.document) {
+            const doc = msg.document;
+            const fallbackMime = doc.mime_type ?? "application/octet-stream";
+            try {
+                const dataUrl = await api.downloadFile(doc.file_id, fallbackMime);
+                const parsed = parseDataUrl(dataUrl);
+                if (parsed) {
+                    attachments.push({
+                        mimeType: parsed.mimeType,
+                        data: parsed.data,
+                        filename: doc.file_name,
+                    });
+                }
+            }
+            catch (err) {
+                log.error(`[telegram] document download failed: ${String(err)}`);
+                anyFailed = true;
+            }
         }
-        return { attachments: [], failed: true };
+        if (attachments.length === 0 && anyFailed) {
+            return { attachments: [], failed: true };
+        }
+        return { attachments, failed: false };
     }
     async function sendReply(chatId, ack) {
         if (ack.ok) {
@@ -50,23 +127,42 @@ export function createMessageRouter(deps) {
     async function handleAllowed(msg) {
         const chatId = msg.chat.id;
         const text = msg.text ?? msg.caption ?? "";
-        const hasPhoto = Array.isArray(msg.photo) && msg.photo.length > 0;
-        if (text.trim().length === 0 && !hasPhoto)
+        const hasMedia = (Array.isArray(msg.photo) && msg.photo.length > 0) ||
+            msg.document !== undefined;
+        if (text.trim().length === 0 && !hasMedia)
             return;
-        log.info(`[telegram] accepted chat=${chatId} user=@${userLabel(msg)} len=${text.length}${hasPhoto ? " +photo" : ""}`);
-        const { attachments, failed } = await tryDownloadPhoto(msg);
-        // Photo-only message where download failed: bail out instead
-        // of sending "What is this image?" without the actual image.
+        const mediaLabel = buildMediaLabel(msg);
+        log.info(`[telegram] accepted chat=${chatId} user=@${userLabel(msg)} len=${text.length}${mediaLabel}`);
+        const { attachments, failed } = await tryDownloadAttachments(msg);
+        // Attachment-only message where download failed: bail out instead
+        // of sending a query without the actual file.
         if (failed && text.trim().length === 0) {
             await api
-                .sendMessage(chatId, "Sorry, I could not download the photo. Please try again.")
+                .sendMessage(chatId, "Sorry, I could not download the attachment. Please try again.")
                 .catch(() => { });
             return;
         }
-        // Surface the photo-drop so the user knows the image was lost.
+        // Surface the attachment failure so the user knows the file was lost.
         const messageText = resolveMessageText(text, failed);
+        // Start streaming: chunks will arrive via handleTextChunk and
+        // be sent/edited in the Telegram chat in real time.
+        startStream(chatId);
         const ack = await sendToMulmo(String(chatId), messageText, attachments.length > 0 ? attachments : undefined);
-        await sendReply(chatId, ack);
+        // Final flush + capture the message id before stopStream clears it.
+        flushStream();
+        const sentMsgId = streamMessageId;
+        stopStream();
+        // If streaming sent the text, do a final edit with the full ack
+        // to catch any trailing chunks. If no streaming happened,
+        // send the full reply as a new message.
+        if (sentMsgId !== null && ack.ok) {
+            await api
+                .editMessageText(chatId, sentMsgId, ack.reply ?? "")
+                .catch(() => { });
+        }
+        else if (sentMsgId === null) {
+            await sendReply(chatId, ack);
+        }
     }
     async function handleDenied(msg) {
         const chatId = msg.chat.id;
@@ -107,6 +203,12 @@ export function createMessageRouter(deps) {
                 log.error(`[telegram] push sendMessage failed: ${String(err)}`);
             }
         },
+        handleTextChunk(chunk) {
+            if (streamChatId === null)
+                return;
+            streamAccumulated += chunk;
+            streamDirty = true;
+        },
         deniedAlreadyNotified() {
             return deniedAlreadyNotified;
         },
@@ -121,14 +223,23 @@ async function sendChunked(api, chatId, text) {
         await api.sendMessage(chatId, text.slice(i, i + TELEGRAM_MAX_MESSAGE_CHARS));
     }
 }
-function resolveMessageText(text, photoFailed) {
+function resolveMessageText(text, attachmentFailed) {
     const hasText = text.trim().length > 0;
-    if (photoFailed && hasText) {
-        return `${text}\n\n(note: attached photo could not be downloaded)`;
+    if (attachmentFailed && hasText) {
+        return `${text}\n\n(note: attached file could not be downloaded)`;
     }
     if (hasText)
         return text;
-    return "What is this image?";
+    return "Describe / analyze this file.";
+}
+function buildMediaLabel(msg) {
+    if (msg.document) {
+        const hint = msg.document.file_name ?? msg.document.mime_type ?? "unknown";
+        return ` +file(${hint})`;
+    }
+    if (Array.isArray(msg.photo) && msg.photo.length > 0)
+        return " +photo";
+    return "";
 }
 function userLabel(msg) {
     return msg.from?.username ?? msg.from?.first_name ?? "unknown";

package/package.json

@@ -1,10 +1,18 @@
 {
   "name": "@mulmobridge/telegram",
-  "version": "0.1.1",
+  "version": "0.1.2",
   "description": "Telegram bridge for MulmoBridge — connect a Telegram bot to MulmoClaude",
   "type": "module",
   "main": "./dist/index.js",
   "types": "./dist/index.d.ts",
+  "exports": {
+    ".": {
+      "types": "./dist/index.d.ts",
+      "import": "./dist/index.js",
+      "require": "./dist/index.js",
+      "default": "./dist/index.js"
+    }
+  },
   "bin": {
     "mulmobridge-telegram": "./dist/index.js"
   },
@@ -27,7 +35,7 @@
     "dotenv": "^17.0.0"
   },
   "devDependencies": {
-    "@types/node": "^22.0.0",
-    "typescript": "^5.8.0"
+    "@types/node": "^25.6.0",
+    "typescript": "^6.0.3"
   }
 }