@mulmobridge/telegram 0.1.1 → 0.1.3

package/README.md

@@ -46,13 +46,43 @@ The bridge enforces a **chat-ID allowlist**. Only messages from listed chat IDs
 
 ## Ecosystem
 
-Part of the `@mulmobridge/*` package family:
-
-- **@mulmobridge/protocol** — shared types and constants
-- **@mulmobridge/client** — socket.io client library
-- **@mulmobridge/cli** — interactive terminal bridge
-- **@mulmobridge/telegram** — this package
-- **@mulmobridge/chat-service** — server-side chat service
+Part of the [`@mulmobridge/*`](https://www.npmjs.com/~mulmobridge) package family.
+
+**Shared libraries:**
+
+- [`@mulmobridge/client`](https://www.npmjs.com/package/@mulmobridge/client) — socket.io client library used by every bridge below
+- [`@mulmobridge/protocol`](https://www.npmjs.com/package/@mulmobridge/protocol) — wire types and constants
+- [`@mulmobridge/chat-service`](https://www.npmjs.com/package/@mulmobridge/chat-service) — server-side relay + session store
+- [`@mulmobridge/relay`](https://www.npmjs.com/package/@mulmobridge/relay) — Cloudflare Workers webhook proxy
+- [`@mulmobridge/mock-server`](https://www.npmjs.com/package/@mulmobridge/mock-server) — mock server for local bridge development
+
+**Bridges** (one npm package per platform):
+
+- [`@mulmobridge/bluesky`](https://www.npmjs.com/package/@mulmobridge/bluesky) — Bluesky DMs over atproto
+- [`@mulmobridge/chatwork`](https://www.npmjs.com/package/@mulmobridge/chatwork) — Chatwork (Japanese business chat)
+- [`@mulmobridge/cli`](https://www.npmjs.com/package/@mulmobridge/cli) — interactive terminal bridge
+- [`@mulmobridge/discord`](https://www.npmjs.com/package/@mulmobridge/discord) — Discord bot via Gateway
+- [`@mulmobridge/email`](https://www.npmjs.com/package/@mulmobridge/email) — IMAP poll + SMTP reply, threading preserved
+- [`@mulmobridge/google-chat`](https://www.npmjs.com/package/@mulmobridge/google-chat) — Google Chat via MulmoBridge relay
+- [`@mulmobridge/irc`](https://www.npmjs.com/package/@mulmobridge/irc) — IRC (Libera, Freenode, custom)
+- [`@mulmobridge/line`](https://www.npmjs.com/package/@mulmobridge/line) — LINE Messaging API via MulmoBridge relay
+- [`@mulmobridge/line-works`](https://www.npmjs.com/package/@mulmobridge/line-works) — LINE Works (enterprise LINE)
+- [`@mulmobridge/mastodon`](https://www.npmjs.com/package/@mulmobridge/mastodon) — Mastodon DMs + mentions
+- [`@mulmobridge/matrix`](https://www.npmjs.com/package/@mulmobridge/matrix) — Matrix / Element
+- [`@mulmobridge/mattermost`](https://www.npmjs.com/package/@mulmobridge/mattermost) — Mattermost
+- [`@mulmobridge/messenger`](https://www.npmjs.com/package/@mulmobridge/messenger) — Facebook Messenger via MulmoBridge relay
+- [`@mulmobridge/nostr`](https://www.npmjs.com/package/@mulmobridge/nostr) — Nostr NIP-04 encrypted DMs
+- [`@mulmobridge/rocketchat`](https://www.npmjs.com/package/@mulmobridge/rocketchat) — Rocket.Chat
+- [`@mulmobridge/signal`](https://www.npmjs.com/package/@mulmobridge/signal) — Signal via signal-cli-rest-api
+- [`@mulmobridge/slack`](https://www.npmjs.com/package/@mulmobridge/slack) — Slack Socket Mode
+- [`@mulmobridge/teams`](https://www.npmjs.com/package/@mulmobridge/teams) — Microsoft Teams via Bot Framework
+- [`@mulmobridge/telegram`](https://www.npmjs.com/package/@mulmobridge/telegram) — Telegram bot  ← **this package**
+- [`@mulmobridge/twilio-sms`](https://www.npmjs.com/package/@mulmobridge/twilio-sms) — SMS via Twilio Programmable Messaging
+- [`@mulmobridge/viber`](https://www.npmjs.com/package/@mulmobridge/viber) — Viber Public Account bots
+- [`@mulmobridge/webhook`](https://www.npmjs.com/package/@mulmobridge/webhook) — generic HTTP webhook bridge
+- [`@mulmobridge/whatsapp`](https://www.npmjs.com/package/@mulmobridge/whatsapp) — WhatsApp Cloud API via MulmoBridge relay
+- [`@mulmobridge/xmpp`](https://www.npmjs.com/package/@mulmobridge/xmpp) — XMPP / Jabber
+- [`@mulmobridge/zulip`](https://www.npmjs.com/package/@mulmobridge/zulip) — Zulip
 
 ## License
 

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,11 @@ 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

@@ -71,9 +71,7 @@ function delay(ms) {
 async function main() {
     const { botToken, allowlist, pollTimeoutSec } = readEnv();
     console.log("MulmoClaude Telegram bridge");
-    console.log(`Allowlist: ${allowlist.size() > 0
-        ? allowlist.snapshot().join(", ")
-        : "(empty — all chats will be denied)"}`);
+    console.log(`Allowlist: ${allowlist.size() > 0 ? allowlist.snapshot().join(", ") : "(empty — all chats will be denied)"}`);
     const api = createTelegramApi({ botToken });
     const client = createBridgeClient({ transportId: TRANSPORT_ID });
     const router = createMessageRouter({
@@ -81,11 +79,13 @@ 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
-            .handlePush(ev)
-            .catch((err) => console.error(`[telegram] handlePush failed: ${String(err)}`));
+        router.handlePush(ev).catch((err) => console.error(`[telegram] handlePush failed: ${String(err)}`));
     });
     const abortController = new AbortController();
     process.on("SIGINT", () => {

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

@@ -3,7 +3,7 @@
 // Telegram API, no real MulmoClaude socket, no env reads). The
 // entrypoint in index.ts is then just: read env → wire real deps →
 // drive the polling loop.
-import { parseDataUrl, } from "@mulmobridge/client";
+import { parseDataUrl } from "@mulmobridge/client";
 // Telegram caps a single message at 4096 chars. We split long
 // replies naively; pretty formatting (preserve markdown, break on
 // sentence boundaries) is a follow-up.
@@ -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;
+            }
+        }
+        if (attachments.length === 0 && anyFailed) {
+            return { attachments: [], failed: true };
         }
-        return { attachments: [], failed: true };
+        return { attachments, failed: false };
     }
     async function sendReply(chatId, ack) {
         if (ack.ok) {
@@ -50,23 +127,37 @@ 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.")
-                .catch(() => { });
+            await api.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 +198,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 +218,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.3",
   "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"
   },
@@ -22,12 +30,12 @@
   "license": "MIT",
   "author": "Receptron Team",
   "dependencies": {
-    "@mulmobridge/client": "^0.1.0",
-    "@mulmobridge/protocol": "^0.1.0",
+    "@mulmobridge/client": "^0.1.4",
+    "@mulmobridge/protocol": "^0.1.4",
     "dotenv": "^17.0.0"
   },
   "devDependencies": {
-    "@types/node": "^22.0.0",
-    "typescript": "^5.8.0"
+    "@types/node": "^25.6.0",
+    "typescript": "^6.0.3"
   }
 }