@mulmobridge/client 0.1.0

package/README.md

@@ -0,0 +1,62 @@
+# @mulmobridge/client
+
+Shared socket.io client library for all MulmoBridge bridges. Handles connection setup, bearer-token authentication, and the send/receive wire protocol so each bridge only needs to implement its platform adapter.
+
+## Install
+
+```bash
+npm install @mulmobridge/client
+# or
+yarn add @mulmobridge/client
+```
+
+## Exports
+
+| Export | Description |
+|---|---|
+| `createBridgeClient(opts)` | Create a connected socket.io client with auth |
+| `requireBearerToken()` | Read the bearer token or exit with a helpful message |
+| `readBridgeToken()` | Read the bearer token (returns `null` if absent) |
+| `TOKEN_FILE_PATH` | Path to `~/mulmoclaude/.session-token` |
+| `mimeFromExtension(ext)` | Map file extension to MIME type |
+| `isImageMime(mime)` | Check if MIME is an image type |
+| `isPdfMime(mime)` | Check if MIME is PDF |
+| `isSupportedAttachmentMime(mime)` | Check if MIME can be sent to Claude |
+| `parseDataUrl(url)` | Parse `data:mime;base64,data` strings |
+| `buildDataUrl(mime, b64)` | Build a data URL from components |
+| `MessageAck` | Acknowledgement returned by `client.send()` |
+| `PushEvent` | Server-push event delivered to `client.onPush()` |
+| `BridgeClientOptions` | Options accepted by `createBridgeClient()` |
+| `BridgeClient` | Client interface returned by `createBridgeClient()` |
+| `ParsedDataUrl` | Parsed data URL components |
+
+## Usage
+
+```typescript
+import { createBridgeClient } from "@mulmobridge/client";
+
+const client = createBridgeClient({ transportId: "my-bridge" });
+
+const ack = await client.send("chat-123", "Hello!");
+if (ack.ok) {
+  console.log(ack.reply);
+}
+
+client.onPush((ev) => {
+  console.log(`Push from ${ev.chatId}: ${ev.message}`);
+});
+```
+
+## Ecosystem
+
+Part of the `@mulmobridge/*` package family:
+
+- **@mulmobridge/protocol** — shared types and constants
+- **@mulmobridge/client** — this package
+- **@mulmobridge/cli** — interactive terminal bridge
+- **@mulmobridge/telegram** — Telegram bot bridge
+- **@mulmobridge/chat-service** — server-side chat service
+
+## License
+
+MIT

package/dist/client.d.ts

@@ -0,0 +1,41 @@
+import { type Socket } from "socket.io-client";
+import { type Attachment } from "@mulmobridge/protocol";
+export interface MessageAck {
+    ok: boolean;
+    reply?: string;
+    error?: string;
+    status?: number;
+}
+export interface PushEvent {
+    chatId: string;
+    message: string;
+}
+export interface BridgeClientOptions {
+    /** Required. Identifier for this bridge in the handshake.
+     *  Matches `handshake.auth.transportId` server-side. */
+    transportId: string;
+    /** Defaults to `$MULMOCLAUDE_API_URL` or `http://localhost:3001`. */
+    apiUrl?: string;
+}
+export interface BridgeClient {
+    /** Send a user turn to MulmoClaude, wait for the assistant reply. */
+    send(externalChatId: string, text: string, attachments?: Attachment[]): Promise<MessageAck>;
+    /** Subscribe to server → bridge async pushes (Phase B of #268). */
+    onPush(handler: (event: PushEvent) => void): void;
+    /** Called each time the socket (re-)establishes a connection. */
+    onConnect(handler: () => void): void;
+    /** Called when the socket disconnects. */
+    onDisconnect(handler: (reason: string) => void): void;
+    /** Explicit shutdown. */
+    close(): void;
+    /** Escape hatch — raw socket for anything the helpers don't cover. */
+    socket: Socket;
+}
+/**
+ * Resolve the bearer token from the workspace / env var, exit with
+ * a clear error if absent. Kept separate so bridges that want to
+ * surface the error differently (e.g. print to a platform channel)
+ * can call `readBridgeToken()` directly.
+ */
+export declare function requireBearerToken(): string;
+export declare function createBridgeClient(opts: BridgeClientOptions): BridgeClient;

package/dist/client.js

@@ -0,0 +1,101 @@
+// Shared socket.io client wrapper for every MulmoClaude bridge.
+//
+// A bridge is a small process that glues one external messaging
+// platform (CLI / Telegram / LINE / Slack / …) to MulmoClaude's
+// chat-service. Every bridge needs the exact same socket setup:
+// read the bearer token, connect to `/ws/chat` with
+// `{ transportId, token }`, handle connect / disconnect / token-
+// mismatch, and send / receive on the two wire events (`message`
+// with ack, `push` from the server). That machinery lives here so
+// each new bridge file is just the platform adapter.
+//
+// See `docs/bridge-protocol.md` for the wire-level contract and a
+// minimal non-Node equivalent.
+import { io } from "socket.io-client";
+import { CHAT_SOCKET_EVENTS, CHAT_SOCKET_PATH, } from "@mulmobridge/protocol";
+import { readBridgeToken, TOKEN_FILE_PATH } from "./token.js";
+// 6 min > the server's REPLY_TIMEOUT_MS (5 min) so the server's
+// timeout surfaces as a reply, not a client-side cancellation.
+const REPLY_TIMEOUT_MS = 6 * 60 * 1000;
+const DEFAULT_API_URL = "http://localhost:3001";
+/**
+ * Resolve the bearer token from the workspace / env var, exit with
+ * a clear error if absent. Kept separate so bridges that want to
+ * surface the error differently (e.g. print to a platform channel)
+ * can call `readBridgeToken()` directly.
+ */
+export function requireBearerToken() {
+    const token = readBridgeToken();
+    if (token !== null)
+        return token;
+    process.stderr.write(`No bearer token found. The MulmoClaude server writes one to\n` +
+        `  ${TOKEN_FILE_PATH}\n` +
+        `at startup (mode 0600). Start the server with \`yarn dev\` (or\n` +
+        `\`npm run dev\`) first, or set MULMOCLAUDE_AUTH_TOKEN to the\n` +
+        `same value the server is using.\n`);
+    process.exit(1);
+}
+export function createBridgeClient(opts) {
+    const apiUrl = opts.apiUrl ?? process.env.MULMOCLAUDE_API_URL ?? DEFAULT_API_URL;
+    const token = requireBearerToken();
+    const socket = io(apiUrl, {
+        path: CHAT_SOCKET_PATH,
+        auth: { transportId: opts.transportId, token },
+        transports: ["websocket"],
+    });
+    installDefaultLogging(socket);
+    return {
+        send: (externalChatId, text, attachments) => sendMessage(socket, externalChatId, text, attachments),
+        onPush: (handler) => {
+            socket.on(CHAT_SOCKET_EVENTS.push, handler);
+        },
+        onConnect: (handler) => {
+            socket.on("connect", handler);
+        },
+        onDisconnect: (handler) => {
+            socket.on("disconnect", handler);
+        },
+        close: () => {
+            socket.disconnect();
+        },
+        socket,
+    };
+}
+function sendMessage(socket, externalChatId, text, attachments) {
+    const payload = { externalChatId, text };
+    if (attachments && attachments.length > 0)
+        payload.attachments = attachments;
+    return new Promise((resolve) => {
+        socket
+            .timeout(REPLY_TIMEOUT_MS)
+            .emit(CHAT_SOCKET_EVENTS.message, payload, (err, ack) => {
+            if (err) {
+                resolve({ ok: false, error: `timeout: ${err.message}` });
+                return;
+            }
+            resolve(ack ?? { ok: false, error: "no ack from server" });
+        });
+    });
+}
+function installDefaultLogging(socket) {
+    socket.on("connect", () => {
+        console.log(`Connected (${socket.id}).`);
+    });
+    socket.on("disconnect", (reason) => {
+        console.error(`\nDisconnected: ${reason}`);
+    });
+    socket.on("connect_error", (err) => {
+        const msg = err.message;
+        // Token-mismatch recovery: the server rewrites its token on
+        // every restart, so an old bridge will see "invalid token"
+        // right after the server bounces. Tell the user instead of
+        // spinning silently.
+        if (msg === "invalid token" || msg === "server auth not ready") {
+            console.error("\nConnect error: bearer token rejected. The server likely\n" +
+                "restarted since this bridge started — re-run the bridge to\n" +
+                "pick up the new token.\n");
+            return;
+        }
+        console.error(`\nConnect error: ${msg}`);
+    });
+}

package/dist/index.d.ts

@@ -0,0 +1,3 @@
+export { createBridgeClient, requireBearerToken, type MessageAck, type PushEvent, type BridgeClientOptions, type BridgeClient, } from "./client.js";
+export { readBridgeToken, TOKEN_FILE_PATH } from "./token.js";
+export { mimeFromExtension, isImageMime, isPdfMime, isSupportedAttachmentMime, parseDataUrl, buildDataUrl, type ParsedDataUrl, } from "./mime.js";

package/dist/index.js

@@ -0,0 +1,4 @@
+// @mulmobridge/client — shared socket.io client for all MulmoBridge bridges.
+export { createBridgeClient, requireBearerToken, } from "./client.js";
+export { readBridgeToken, TOKEN_FILE_PATH } from "./token.js";
+export { mimeFromExtension, isImageMime, isPdfMime, isSupportedAttachmentMime, parseDataUrl, buildDataUrl, } from "./mime.js";

package/dist/mime.d.ts

@@ -0,0 +1,21 @@
+/** Infer MIME type from a file extension (case-insensitive).
+ *  Returns the fallback if the extension is not recognised. */
+export declare function mimeFromExtension(ext: string, fallback?: string): string;
+/** True when the MIME type is an image Claude can see via vision. */
+export declare function isImageMime(mimeType: string): boolean;
+/** True when the MIME type is a PDF document Claude can read natively
+ *  via `type: "document"` content blocks. */
+export declare function isPdfMime(mimeType: string): boolean;
+/** True when the attachment can be sent to Claude as a content block
+ *  (image vision or PDF document). */
+export declare function isSupportedAttachmentMime(mimeType: string): boolean;
+export interface ParsedDataUrl {
+    mimeType: string;
+    data: string;
+}
+/** Parse a `data:<mime>;base64,<data>` string. Returns null if the
+ *  format doesn't match. Also handles parameterised data URLs like
+ *  `data:image/png;charset=binary;base64,…`. */
+export declare function parseDataUrl(dataUrl: string): ParsedDataUrl | null;
+/** Build a `data:<mime>;base64,<data>` string from components. */
+export declare function buildDataUrl(mimeType: string, base64Data: string): string;

package/dist/mime.js

@@ -0,0 +1,60 @@
+// Shared MIME type helpers used by both bridges and the server.
+// Pure functions — no I/O, no deps.
+const EXT_TO_MIME = {
+    // Images
+    jpg: "image/jpeg",
+    jpeg: "image/jpeg",
+    png: "image/png",
+    gif: "image/gif",
+    webp: "image/webp",
+    svg: "image/svg+xml",
+    heic: "image/heic",
+    heif: "image/heif",
+    bmp: "image/bmp",
+    tiff: "image/tiff",
+    tif: "image/tiff",
+    avif: "image/avif",
+    // Documents
+    pdf: "application/pdf",
+    doc: "application/msword",
+    docx: "application/vnd.openxmlformats-officedocument.wordprocessingml.document",
+    pptx: "application/vnd.openxmlformats-officedocument.presentationml.presentation",
+    xlsx: "application/vnd.openxmlformats-officedocument.spreadsheetml.sheet",
+    // Video / audio
+    mp4: "video/mp4",
+    webm: "video/webm",
+    mp3: "audio/mpeg",
+    ogg: "audio/ogg",
+};
+/** Infer MIME type from a file extension (case-insensitive).
+ *  Returns the fallback if the extension is not recognised. */
+export function mimeFromExtension(ext, fallback = "application/octet-stream") {
+    return EXT_TO_MIME[ext.toLowerCase()] ?? fallback;
+}
+/** True when the MIME type is an image Claude can see via vision. */
+export function isImageMime(mimeType) {
+    return mimeType.startsWith("image/");
+}
+/** True when the MIME type is a PDF document Claude can read natively
+ *  via `type: "document"` content blocks. */
+export function isPdfMime(mimeType) {
+    return mimeType === "application/pdf";
+}
+/** True when the attachment can be sent to Claude as a content block
+ *  (image vision or PDF document). */
+export function isSupportedAttachmentMime(mimeType) {
+    return isImageMime(mimeType) || isPdfMime(mimeType);
+}
+/** Parse a `data:<mime>;base64,<data>` string. Returns null if the
+ *  format doesn't match. Also handles parameterised data URLs like
+ *  `data:image/png;charset=binary;base64,…`. */
+export function parseDataUrl(dataUrl) {
+    const match = dataUrl.match(/^data:([^;,]+)(?:;[^,]*)?;base64,(.+)$/);
+    if (!match)
+        return null;
+    return { mimeType: match[1], data: match[2] };
+}
+/** Build a `data:<mime>;base64,<data>` string from components. */
+export function buildDataUrl(mimeType, base64Data) {
+    return `data:${mimeType};base64,${base64Data}`;
+}

package/dist/token.d.ts

@@ -0,0 +1,2 @@
+export declare const TOKEN_FILE_PATH: string;
+export declare function readBridgeToken(): string | null;

package/dist/token.js

@@ -0,0 +1,29 @@
+// Resolve the bearer token the CLI bridge sends to /api/*. Used by
+// @mulmobridge/cli at startup (#272 Phase 2).
+//
+// Resolution order:
+//   1. `MULMOCLAUDE_AUTH_TOKEN` env var (useful for parallel shells,
+//      CI, or when the user runs the bridge against a different
+//      workspace than ~/mulmoclaude/)
+//   2. `<homedir>/mulmoclaude/.session-token` — the file the server
+//      writes at startup. Same path the Vite dev plugin reads from.
+//
+// Returns null if neither source yields a non-empty string — the
+// caller decides how to react (exit with a helpful message, in the
+// bridge's case).
+import fs from "fs";
+import os from "os";
+import path from "path";
+export const TOKEN_FILE_PATH = path.join(os.homedir(), "mulmoclaude", ".session-token");
+export function readBridgeToken() {
+    const fromEnv = process.env.MULMOCLAUDE_AUTH_TOKEN;
+    if (typeof fromEnv === "string" && fromEnv.length > 0)
+        return fromEnv;
+    try {
+        const raw = fs.readFileSync(TOKEN_FILE_PATH, "utf-8").trim();
+        return raw.length > 0 ? raw : null;
+    }
+    catch {
+        return null;
+    }
+}

package/package.json

@@ -0,0 +1,34 @@
+{
+  "name": "@mulmobridge/client",
+  "version": "0.1.0",
+  "description": "Socket.io client library for MulmoBridge — shared by all bridge implementations",
+  "type": "module",
+  "main": "./dist/index.js",
+  "types": "./dist/index.d.ts",
+  "exports": {
+    ".": {
+      "types": "./dist/index.d.ts",
+      "import": "./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/protocol": "^0.1.0",
+    "socket.io-client": "^4.0.0"
+  },
+  "devDependencies": {
+    "typescript": "^5.8.0"
+  }
+}