@mulmobridge/client 0.1.2 → 0.1.4

package/README.md

@@ -49,13 +49,43 @@ client.onPush((ev) => {
 
 ## Ecosystem
 
-Part of the `@mulmobridge/*` package family:
+Part of the [`@mulmobridge/*`](https://www.npmjs.com/~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
+**Shared libraries:**
+
+- [`@mulmobridge/client`](https://www.npmjs.com/package/@mulmobridge/client) — socket.io client library used by every bridge below  ← **this package**
+- [`@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
+- [`@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/client.d.ts

@@ -1,5 +1,5 @@
 import { type Socket } from "socket.io-client";
-import { type Attachment } from "@mulmobridge/protocol";
+import { type Attachment, type BridgeOptions } from "@mulmobridge/protocol";
 export interface MessageAck {
     ok: boolean;
     reply?: string;
@@ -16,6 +16,14 @@ export interface BridgeClientOptions {
     transportId: string;
     /** Defaults to `$MULMOCLAUDE_API_URL` or `http://localhost:3001`. */
     apiUrl?: string;
+    /** Flat primitive bag forwarded to the host app's startChat
+     *  callback via the handshake (`BridgeOptions` from the
+     *  protocol). Values must be string / number / boolean — nested
+     *  objects are rejected server-side by the chat-service. If
+     *  omitted, the client auto-scrapes `<TRANSPORT>_BRIDGE_*` /
+     *  `BRIDGE_*` env vars (producing string values). Pass `{}`
+     *  explicitly to opt out of the scrape. */
+    options?: BridgeOptions;
 }
 export interface BridgeClient {
     /** Send a user turn to MulmoClaude, wait for the assistant reply. */

package/dist/client.js

@@ -14,6 +14,7 @@
 import { io } from "socket.io-client";
 import { CHAT_SOCKET_EVENTS, CHAT_SOCKET_PATH } from "@mulmobridge/protocol";
 import { readBridgeToken, TOKEN_FILE_PATH } from "./token.js";
+import { readBridgeEnvOptions } from "./options.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;
@@ -38,9 +39,18 @@ export function requireBearerToken() {
 export function createBridgeClient(opts) {
     const apiUrl = opts.apiUrl ?? process.env.MULMOCLAUDE_API_URL ?? DEFAULT_API_URL;
     const token = requireBearerToken();
+    // `opts.options === undefined` → scrape env automatically.
+    // `opts.options === {}` → opt out of the scrape explicitly.
+    const options = opts.options ?? readBridgeEnvOptions(opts.transportId, process.env);
+    // Only include the `options` key in the handshake when there's
+    // something to send — keeps old servers unaware of the field from
+    // ever seeing an empty object on the wire.
+    const auth = { transportId: opts.transportId, token };
+    if (Object.keys(options).length > 0)
+        auth.options = options;
     const socket = io(apiUrl, {
         path: CHAT_SOCKET_PATH,
-        auth: { transportId: opts.transportId, token },
+        auth,
         transports: ["websocket"],
     });
     installDefaultLogging(socket);

package/dist/index.d.ts

@@ -1,4 +1,5 @@
 export { createBridgeClient, requireBearerToken, type MessageAck, type PushEvent, type BridgeClientOptions, type BridgeClient } from "./client.js";
 export { readBridgeToken, TOKEN_FILE_PATH } from "./token.js";
+export { readBridgeEnvOptions } from "./options.js";
 export { chunkText } from "./text.js";
 export { mimeFromExtension, isImageMime, isPdfMime, isSupportedAttachmentMime, isNativeAttachmentMime, parseDataUrl, buildDataUrl, type ParsedDataUrl, } from "./mime.js";

package/dist/index.js

@@ -1,5 +1,6 @@
 // @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 { readBridgeEnvOptions } from "./options.js";
 export { chunkText } from "./text.js";
 export { mimeFromExtension, isImageMime, isPdfMime, isSupportedAttachmentMime, isNativeAttachmentMime, parseDataUrl, buildDataUrl, } from "./mime.js";

package/dist/options.d.ts

@@ -0,0 +1,22 @@
+/**
+ * Read `<TRANSPORT>_BRIDGE_*` and `BRIDGE_*` env vars into a
+ * lowerCamelCase-keyed bag ready to hand to `createBridgeClient`.
+ *
+ * Precedence when the same key resolves from both forms:
+ * transport-specific wins over shared.
+ *
+ * Transport ids with dashes (`google-chat`, `line-works`,
+ * `twilio-sms`, …) are normalised to underscores when building the
+ * env prefix: `google-chat` → `GOOGLE_CHAT_BRIDGE_*`. Dashes in env
+ * var names break shells, so `_` is the portable convention.
+ *
+ * Example:
+ *   SLACK_BRIDGE_DEFAULT_ROLE=slack
+ *   BRIDGE_DEFAULT_ROLE=general
+ *   → `{ defaultRole: "slack" }`
+ *
+ *   GOOGLE_CHAT_BRIDGE_DEFAULT_ROLE=support
+ *   (with transportId="google-chat")
+ *   → `{ defaultRole: "support" }`
+ */
+export declare function readBridgeEnvOptions(transportId: string, env: Readonly<Record<string, string | undefined>>): Record<string, string>;

package/dist/options.js

@@ -0,0 +1,88 @@
+// Env-var scraper for the bridge options bag.
+//
+// Bridges don't want to hand-maintain a forward-list of env vars
+// that should travel to the host app. Instead we scrape a single
+// dedicated prefix pattern at `createBridgeClient()` time:
+//
+//   <TRANSPORT>_BRIDGE_<KEY>  — transport-specific, wins on clash
+//   BRIDGE_<KEY>              — shared default across every bridge
+//
+// Both forms strip the prefix and convert the `UPPER_SNAKE` tail to
+// `lowerCamel`. Empty string values are dropped so a stray
+// `FOO=""` doesn't shadow `BAR`'s match.
+//
+// The `_BRIDGE_` segment is deliberate: it lets the bridge keep its
+// own secrets (`SLACK_BOT_TOKEN`, `SLACK_APP_TOKEN`, …) naturally
+// outside the scrape — they have no `_BRIDGE_` segment so they're
+// never picked up, no reserved-list needed.
+// Convert UPPER_SNAKE_CASE → lowerCamelCase. Leading digits and
+// adjacent underscores degrade gracefully (adjacent underscores
+// collapse to a single word break; leading digits are allowed but
+// kept as-is after the first segment is lowercased).
+function snakeToLowerCamel(snake) {
+    const parts = snake
+        .toLowerCase()
+        .split("_")
+        .filter((segment) => segment.length > 0);
+    if (parts.length === 0)
+        return "";
+    const [head, ...rest] = parts;
+    return head + rest.map((part) => (part ? part[0].toUpperCase() + part.slice(1) : "")).join("");
+}
+// Strip the prefix, return null if the name doesn't match.
+function matchBridgePrefix(name, transportPrefix) {
+    if (name.startsWith(transportPrefix)) {
+        const tail = name.slice(transportPrefix.length);
+        return tail.length > 0 ? tail : null;
+    }
+    if (name.startsWith("BRIDGE_")) {
+        const tail = name.slice("BRIDGE_".length);
+        return tail.length > 0 ? tail : null;
+    }
+    return null;
+}
+/**
+ * Read `<TRANSPORT>_BRIDGE_*` and `BRIDGE_*` env vars into a
+ * lowerCamelCase-keyed bag ready to hand to `createBridgeClient`.
+ *
+ * Precedence when the same key resolves from both forms:
+ * transport-specific wins over shared.
+ *
+ * Transport ids with dashes (`google-chat`, `line-works`,
+ * `twilio-sms`, …) are normalised to underscores when building the
+ * env prefix: `google-chat` → `GOOGLE_CHAT_BRIDGE_*`. Dashes in env
+ * var names break shells, so `_` is the portable convention.
+ *
+ * Example:
+ *   SLACK_BRIDGE_DEFAULT_ROLE=slack
+ *   BRIDGE_DEFAULT_ROLE=general
+ *   → `{ defaultRole: "slack" }`
+ *
+ *   GOOGLE_CHAT_BRIDGE_DEFAULT_ROLE=support
+ *   (with transportId="google-chat")
+ *   → `{ defaultRole: "support" }`
+ */
+export function readBridgeEnvOptions(transportId, env) {
+    const transportPrefix = `${transportId.toUpperCase().replace(/-/g, "_")}_BRIDGE_`;
+    const shared = {};
+    const specific = {};
+    for (const [name, value] of Object.entries(env)) {
+        if (typeof value !== "string" || value.length === 0)
+            continue;
+        const tail = matchBridgePrefix(name, transportPrefix);
+        if (tail === null)
+            continue;
+        const key = snakeToLowerCamel(tail);
+        if (!key)
+            continue;
+        if (name.startsWith(transportPrefix)) {
+            specific[key] = value;
+        }
+        else {
+            shared[key] = value;
+        }
+    }
+    // Transport-specific overrides shared on conflict — spread order
+    // (shared first, then specific) gives exactly that behaviour.
+    return { ...shared, ...specific };
+}

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@mulmobridge/client",
-  "version": "0.1.2",
+  "version": "0.1.4",
   "description": "Socket.io client library for MulmoBridge — shared by all bridge implementations",
   "type": "module",
   "main": "./dist/index.js",
@@ -45,7 +45,7 @@
   "license": "MIT",
   "author": "Receptron Team",
   "dependencies": {
-    "@mulmobridge/protocol": "^0.1.0",
+    "@mulmobridge/protocol": "^0.1.4",
     "socket.io-client": "^4.0.0"
   },
   "devDependencies": {