@mulmobridge/telegram 0.1.0

package/README.md

@@ -0,0 +1,59 @@
+# @mulmobridge/telegram
+
+Telegram bot bridge for MulmoBridge. Connect a Telegram bot to MulmoClaude.
+
+## Usage
+
+1. Create a bot via [@BotFather](https://t.me/BotFather)
+2. Start the MulmoClaude server (`yarn dev` in the main repo)
+3. Run the Telegram bridge:
+
+```bash
+# npx (no install needed)
+TELEGRAM_BOT_TOKEN=your-token TELEGRAM_ALLOWED_CHAT_IDS=123,456 \
+  npx @mulmobridge/telegram@latest
+
+# or install globally
+npm install -g @mulmobridge/telegram
+TELEGRAM_BOT_TOKEN=your-token TELEGRAM_ALLOWED_CHAT_IDS=123,456 \
+  mulmobridge-telegram
+
+# or from the monorepo
+yarn telegram
+```
+
+## Environment Variables
+
+| Variable | Required | Description | Default |
+|---|---|---|---|
+| `TELEGRAM_BOT_TOKEN` | Yes | BotFather token | - |
+| `TELEGRAM_ALLOWED_CHAT_IDS` | Yes | Comma-separated integer chat IDs | empty (deny all) |
+| `MULMOCLAUDE_API_URL` | No | Server URL | `http://localhost:3001` |
+| `MULMOCLAUDE_AUTH_TOKEN` | No | Bearer token override | reads from file |
+| `TELEGRAM_POLL_TIMEOUT_SEC` | No | Long-poll timeout | `25` |
+
+## Security
+
+The bridge enforces a **chat-ID allowlist**. Only messages from listed chat IDs are forwarded to MulmoClaude. All other messages receive a one-time "Access denied" reply.
+
+## Features
+
+- Long-polling (no webhook setup needed)
+- Photo attachment support (downloads and forwards to Claude vision)
+- Long-message chunking (splits replies > 4096 chars)
+- Server push delivery (Phase B of #268)
+- Graceful shutdown on SIGINT
+
+## 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
+
+## License
+
+MIT

package/dist/allowlist.d.ts

@@ -0,0 +1,13 @@
+export interface Allowlist {
+    allows(chatId: number): boolean;
+    size(): number;
+    /** For logging — never returns a mutable reference. */
+    snapshot(): readonly number[];
+}
+/**
+ * Parse a comma-separated list of integer chat IDs. Throws if any
+ * entry isn't a valid integer so the operator notices a typo at
+ * startup instead of silently denying messages.
+ */
+export declare function parseAllowlist(raw: string | undefined): Allowlist;
+export declare function createAllowlist(ids: Iterable<number>): Allowlist;

package/dist/allowlist.js

@@ -0,0 +1,44 @@
+// Telegram chat-ID allowlist. Telegram bots accept messages from any
+// user who knows the bot's username — this is the one gate that keeps
+// the operator's MulmoClaude from being driven by the entire
+// internet. Default = empty set = deny everyone.
+//
+// Chat IDs are Telegram integers (positive for user chats, negative
+// for group chats). We parse strictly: a non-integer entry in the
+// CSV is a misconfiguration and should halt startup, not get silently
+// dropped.
+/**
+ * Parse a comma-separated list of integer chat IDs. Throws if any
+ * entry isn't a valid integer so the operator notices a typo at
+ * startup instead of silently denying messages.
+ */
+export function parseAllowlist(raw) {
+    const ids = new Set();
+    if (raw && raw.trim().length > 0) {
+        for (const part of raw.split(",")) {
+            const trimmed = part.trim();
+            if (trimmed.length === 0)
+                continue;
+            const n = Number(trimmed);
+            if (!Number.isInteger(n)) {
+                throw new Error(`TELEGRAM_ALLOWED_CHAT_IDS: "${trimmed}" is not an integer chat id`);
+            }
+            ids.add(n);
+        }
+    }
+    return createAllowlist(ids);
+}
+export function createAllowlist(ids) {
+    const set = new Set(ids);
+    return {
+        allows(chatId) {
+            return set.has(chatId);
+        },
+        size() {
+            return set.size;
+        },
+        snapshot() {
+            return Array.from(set).sort((a, b) => a - b);
+        },
+    };
+}

package/dist/api.d.ts

@@ -0,0 +1,50 @@
+export interface TelegramUpdate {
+    update_id: number;
+    message?: TelegramMessage;
+}
+export interface TelegramPhotoSize {
+    file_id: string;
+    file_unique_id: string;
+    width: number;
+    height: number;
+    file_size?: number;
+}
+export interface TelegramMessage {
+    message_id: number;
+    chat: TelegramChat;
+    from?: TelegramUser;
+    text?: string;
+    photo?: TelegramPhotoSize[];
+    caption?: string;
+    date: number;
+}
+export interface TelegramChat {
+    id: number;
+    type: "private" | "group" | "supergroup" | "channel";
+    username?: string;
+    title?: string;
+}
+export interface TelegramUser {
+    id: number;
+    is_bot: boolean;
+    username?: string;
+    first_name: string;
+}
+export interface TelegramApiOptions {
+    botToken: string;
+    /** Base URL override for tests / self-hosted Telegram Bot API. */
+    baseUrl?: string;
+    /** Injectable fetch for tests — defaults to global. */
+    fetchImpl?: typeof fetch;
+}
+export interface GetUpdatesOptions {
+    offset?: number;
+    timeoutSec?: number;
+    signal?: AbortSignal;
+}
+export interface TelegramApi {
+    getUpdates(opts?: GetUpdatesOptions): Promise<TelegramUpdate[]>;
+    sendMessage(chatId: number, text: string): Promise<void>;
+    downloadPhoto(fileId: string): Promise<string>;
+}
+export declare function createTelegramApi(opts: TelegramApiOptions): TelegramApi;

package/dist/api.js

@@ -0,0 +1,69 @@
+import { mimeFromExtension, buildDataUrl } from "@mulmobridge/client";
+const DEFAULT_BASE = "https://api.telegram.org";
+export function createTelegramApi(opts) {
+    const baseUrl = opts.baseUrl ?? DEFAULT_BASE;
+    const fetchImpl = opts.fetchImpl ?? fetch;
+    const base = `${baseUrl}/bot${opts.botToken}`;
+    return {
+        async getUpdates(gu = {}) {
+            const params = new URLSearchParams();
+            if (gu.offset !== undefined)
+                params.set("offset", String(gu.offset));
+            if (gu.timeoutSec !== undefined) {
+                params.set("timeout", String(gu.timeoutSec));
+            }
+            const url = `${base}/getUpdates?${params.toString()}`;
+            const res = await fetchImpl(url, { signal: gu.signal });
+            if (!res.ok) {
+                throw new Error(`getUpdates failed: ${res.status} ${await safeText(res)}`);
+            }
+            const body = (await res.json());
+            if (!body.ok || !Array.isArray(body.result)) {
+                throw new Error(`getUpdates API error: ${body.description ?? "unknown"}`);
+            }
+            return body.result;
+        },
+        async sendMessage(chatId, text) {
+            const res = await fetchImpl(`${base}/sendMessage`, {
+                method: "POST",
+                headers: { "Content-Type": "application/json" },
+                body: JSON.stringify({ chat_id: chatId, text }),
+            });
+            if (!res.ok) {
+                throw new Error(`sendMessage failed: ${res.status} ${await safeText(res)}`);
+            }
+            const body = (await res.json());
+            if (!body.ok) {
+                throw new Error(`sendMessage API error: ${body.description ?? "unknown"}`);
+            }
+        },
+        async downloadPhoto(fileId) {
+            const getFileRes = await fetchImpl(`${base}/getFile?file_id=${encodeURIComponent(fileId)}`);
+            if (!getFileRes.ok) {
+                throw new Error(`getFile failed: ${getFileRes.status} ${await safeText(getFileRes)}`);
+            }
+            const getFileBody = (await getFileRes.json());
+            if (!getFileBody.ok || !getFileBody.result?.file_path) {
+                throw new Error(`getFile API error: ${getFileBody.description ?? "no file_path"}`);
+            }
+            const fileUrl = `${baseUrl}/file/bot${opts.botToken}/${getFileBody.result.file_path}`;
+            const fileRes = await fetchImpl(fileUrl);
+            if (!fileRes.ok) {
+                throw new Error(`file download failed: ${fileRes.status}`);
+            }
+            const buffer = await fileRes.arrayBuffer();
+            const b64 = Buffer.from(buffer).toString("base64");
+            const ext = getFileBody.result.file_path.split(".").pop() ?? "";
+            const mediaType = mimeFromExtension(ext, "image/jpeg");
+            return buildDataUrl(mediaType, b64);
+        },
+    };
+}
+async function safeText(res) {
+    try {
+        return await res.text();
+    }
+    catch {
+        return "<unreadable body>";
+    }
+}

package/dist/index.d.ts

@@ -0,0 +1,2 @@
+#!/usr/bin/env node
+import "dotenv/config";

package/dist/index.js

@@ -0,0 +1,105 @@
+#!/usr/bin/env node
+// Telegram bridge (issue #321). Polls Telegram for incoming
+// messages and dispatches them through the shared message router,
+// which enforces the chat-ID allowlist, forwards to MulmoClaude,
+// and delivers Phase-B pushes back through sendMessage.
+//
+// Env surface (see docs/message_apps/telegram/README.md):
+//   TELEGRAM_BOT_TOKEN          — BotFather token (required)
+//   TELEGRAM_ALLOWED_CHAT_IDS   — CSV of integer chat IDs (required
+//                                 in practice; empty = deny everyone)
+//   MULMOCLAUDE_API_URL         — optional override
+//   MULMOCLAUDE_AUTH_TOKEN      — optional override
+//   TELEGRAM_POLL_TIMEOUT_SEC   — optional, default 25
+import "dotenv/config";
+import { createBridgeClient } from "@mulmobridge/client";
+import { createTelegramApi } from "./api.js";
+import { parseAllowlist } from "./allowlist.js";
+import { createMessageRouter } from "./router.js";
+const TRANSPORT_ID = "telegram";
+function readEnv() {
+    const botToken = process.env.TELEGRAM_BOT_TOKEN;
+    if (!botToken || botToken.trim().length === 0) {
+        console.error("TELEGRAM_BOT_TOKEN is required. See docs/message_apps/telegram/.");
+        process.exit(1);
+    }
+    let allowlist;
+    try {
+        allowlist = parseAllowlist(process.env.TELEGRAM_ALLOWED_CHAT_IDS);
+    }
+    catch (err) {
+        console.error(err instanceof Error ? err.message : String(err));
+        process.exit(1);
+    }
+    const pollTimeoutSec = Number(process.env.TELEGRAM_POLL_TIMEOUT_SEC ?? "25");
+    if (!Number.isInteger(pollTimeoutSec) || pollTimeoutSec < 0) {
+        console.error("TELEGRAM_POLL_TIMEOUT_SEC must be a non-negative integer");
+        process.exit(1);
+    }
+    return { botToken, allowlist, pollTimeoutSec };
+}
+async function pollLoop(api, router, opts) {
+    let offset;
+    while (!opts.abortSignal.aborted) {
+        let updates;
+        try {
+            updates = await api.getUpdates({
+                offset,
+                timeoutSec: opts.pollTimeoutSec,
+                signal: opts.abortSignal,
+            });
+        }
+        catch (err) {
+            if (opts.abortSignal.aborted)
+                return;
+            console.error(`[telegram] getUpdates error: ${String(err)}`);
+            // Back off briefly so a broken network doesn't busy-loop.
+            await delay(1000);
+            continue;
+        }
+        for (const update of updates) {
+            offset = update.update_id + 1;
+            if (update.message) {
+                await router.handleMessage(update.message);
+            }
+        }
+    }
+}
+function delay(ms) {
+    return new Promise((r) => setTimeout(r, 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)"}`);
+    const api = createTelegramApi({ botToken });
+    const client = createBridgeClient({ transportId: TRANSPORT_ID });
+    const router = createMessageRouter({
+        api,
+        allowlist,
+        sendToMulmo: (chatId, text, attachments) => client.send(chatId, text, attachments),
+    });
+    // Server → Telegram async push (Phase B of #268).
+    client.onPush((ev) => {
+        router
+            .handlePush(ev)
+            .catch((err) => console.error(`[telegram] handlePush failed: ${String(err)}`));
+    });
+    const abortController = new AbortController();
+    process.on("SIGINT", () => {
+        console.log("\nShutting down...");
+        abortController.abort();
+        client.close();
+        process.exit(0);
+    });
+    await pollLoop(api, router, {
+        pollTimeoutSec,
+        abortSignal: abortController.signal,
+    });
+}
+main().catch((err) => {
+    console.error("Fatal:", err);
+    process.exit(1);
+});

package/dist/router.d.ts

@@ -0,0 +1,25 @@
+import type { TelegramApi, TelegramMessage } from "./api.js";
+import type { Allowlist } from "./allowlist.js";
+import type { Attachment } from "@mulmobridge/protocol";
+import { type MessageAck, type PushEvent } from "@mulmobridge/client";
+export type SendToMulmoFn = (externalChatId: string, text: string, attachments?: Attachment[]) => Promise<MessageAck>;
+export interface RouterDeps {
+    api: TelegramApi;
+    allowlist: Allowlist;
+    sendToMulmo: SendToMulmoFn;
+    /** Structured logger. Console-compatible shape — `[telegram]`
+     *  prefix is the router's responsibility. */
+    log?: {
+        info: (msg: string) => void;
+        warn: (msg: string) => void;
+        error: (msg: string) => void;
+    };
+}
+export interface MessageRouter {
+    handleMessage(msg: TelegramMessage): Promise<void>;
+    handlePush(ev: PushEvent): Promise<void>;
+    /** For tests / debugging: chat IDs we've already sent the
+     *  access-denied notice to. */
+    deniedAlreadyNotified(): ReadonlySet<number>;
+}
+export declare function createMessageRouter(deps: RouterDeps): MessageRouter;

package/dist/router.js

@@ -0,0 +1,135 @@
+// Message-routing logic for the Telegram bridge. Kept separate from
+// `index.ts` so it can be exercised with stubbed deps (no real
+// 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";
+// 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.
+const TELEGRAM_MAX_MESSAGE_CHARS = 4096;
+const defaultLog = {
+    info: (m) => console.log(m),
+    warn: (m) => console.warn(m),
+    error: (m) => console.error(m),
+};
+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,
+                };
+            }
+        }
+        catch (err) {
+            log.error(`[telegram] photo download failed: ${String(err)}`);
+        }
+        return { attachments: [], failed: true };
+    }
+    async function sendReply(chatId, ack) {
+        if (ack.ok) {
+            await sendChunked(api, chatId, ack.reply ?? "");
+        }
+        else {
+            const status = ack.status ? ` (${ack.status})` : "";
+            await sendChunked(api, chatId, `Error${status}: ${ack.error ?? "unknown"}`);
+        }
+    }
+    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)
+            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.
+        if (failed && text.trim().length === 0) {
+            await api
+                .sendMessage(chatId, "Sorry, I could not download the photo. Please try again.")
+                .catch(() => { });
+            return;
+        }
+        // Surface the photo-drop so the user knows the image was lost.
+        const messageText = resolveMessageText(text, failed);
+        const ack = await sendToMulmo(String(chatId), messageText, attachments.length > 0 ? attachments : undefined);
+        await sendReply(chatId, ack);
+    }
+    async function handleDenied(msg) {
+        const chatId = msg.chat.id;
+        log.warn(`[telegram] denied chat=${chatId} user=@${userLabel(msg)} — not on allowlist`);
+        if (deniedAlreadyNotified.has(chatId))
+            return;
+        deniedAlreadyNotified.add(chatId);
+        try {
+            await api.sendMessage(chatId, "Access denied. Contact the operator to be added to the allowlist.");
+        }
+        catch (err) {
+            log.error(`[telegram] access-denied reply failed: ${String(err)}`);
+        }
+    }
+    return {
+        async handleMessage(msg) {
+            if (allowlist.allows(msg.chat.id)) {
+                await handleAllowed(msg);
+            }
+            else {
+                await handleDenied(msg);
+            }
+        },
+        async handlePush(ev) {
+            const chatId = Number(ev.chatId);
+            if (!Number.isInteger(chatId)) {
+                log.warn(`[telegram] push chatId is not integer: ${ev.chatId}`);
+                return;
+            }
+            if (!allowlist.allows(chatId)) {
+                log.warn(`[telegram] push denied: chat ${chatId} not on allowlist`);
+                return;
+            }
+            try {
+                await sendChunked(api, chatId, ev.message);
+            }
+            catch (err) {
+                log.error(`[telegram] push sendMessage failed: ${String(err)}`);
+            }
+        },
+        deniedAlreadyNotified() {
+            return deniedAlreadyNotified;
+        },
+    };
+}
+async function sendChunked(api, chatId, text) {
+    if (text.length === 0) {
+        await api.sendMessage(chatId, "(empty reply)");
+        return;
+    }
+    for (let i = 0; i < text.length; i += TELEGRAM_MAX_MESSAGE_CHARS) {
+        await api.sendMessage(chatId, text.slice(i, i + TELEGRAM_MAX_MESSAGE_CHARS));
+    }
+}
+function resolveMessageText(text, photoFailed) {
+    const hasText = text.trim().length > 0;
+    if (photoFailed && hasText) {
+        return `${text}\n\n(note: attached photo could not be downloaded)`;
+    }
+    if (hasText)
+        return text;
+    return "What is this image?";
+}
+function userLabel(msg) {
+    return msg.from?.username ?? msg.from?.first_name ?? "unknown";
+}

package/package.json

@@ -0,0 +1,33 @@
+{
+  "name": "@mulmobridge/telegram",
+  "version": "0.1.0",
+  "description": "Telegram bridge for MulmoBridge — connect a Telegram bot to MulmoClaude",
+  "type": "module",
+  "main": "./dist/index.js",
+  "types": "./dist/index.d.ts",
+  "bin": {
+    "mulmobridge-telegram": "dist/index.js"
+  },
+  "files": [
+    "dist",
+    "README.md"
+  ],
+  "scripts": {
+    "build": "tsc",
+    "prepack": "yarn build",
+    "typecheck": "tsc --noEmit",
+    "test": "tsx --test test/test_*.ts",
+    "lint": "eslint src test"
+  },
+  "license": "MIT",
+  "author": "Receptron Team",
+  "dependencies": {
+    "@mulmobridge/client": "^0.1.0",
+    "@mulmobridge/protocol": "^0.1.0",
+    "dotenv": "^17.0.0"
+  },
+  "devDependencies": {
+    "@types/node": "^22.0.0",
+    "typescript": "^5.8.0"
+  }
+}