@openmarket/rooms-client 0.1.0

package/dist/ws-client.js

@@ -0,0 +1,491 @@
+import { RoomClientMessageType, RoomServerMessageType, SUPPORTED_ROOM_PROTOCOL_VERSION, } from "./types.js";
+import { VERSION } from "./version.js";
+export class RoomProtocolError extends Error {
+    name = "RoomProtocolError";
+    code;
+    details;
+    requestId;
+    constructor(payload) {
+        super(payload.message);
+        this.code = payload.code;
+        if (payload.details !== undefined)
+            this.details = payload.details;
+        if (payload.requestId)
+            this.requestId = payload.requestId;
+    }
+}
+export class RoomTransportError extends Error {
+    name = "RoomTransportError";
+}
+export class RoomWsClient {
+    url;
+    // Mutable: a guest session re-mints its key via refreshAuthToken.
+    apiKey;
+    agentIdentity;
+    webSocketCtor;
+    timeoutMs;
+    ws = null;
+    auth = null;
+    serverProtocolVersionValue = null;
+    listeners = new Set();
+    connectionListeners = new Set();
+    pending = [];
+    connected = false;
+    reconnectEnabled;
+    reconnectBaseMs;
+    reconnectMaxMs;
+    reconnectHerdJitterMs;
+    reconnectMaxAttempts;
+    refreshAuthToken;
+    onProtocolMismatch;
+    reconnectAttempts = 0;
+    reconnectTimer = null;
+    closedByClient = false;
+    authRefreshRequested = false;
+    authRefreshInFlight = false;
+    /** True after a successful re-mint whose refreshed attempt hasn't authed yet.
+     *  Caps the mint-succeeds-but-server-rejects cycle (config skew) at ONE
+     *  refreshed attempt per episode — without it, openSocket → fail → re-mint →
+     *  openSocket recurses in a hot loop with no backoff. Reset on AUTH_SUCCESS.
+     *  A FAILED re-mint does not set it: that path already backs off through
+     *  maybeReconnect, so transient auth-service outages keep retrying. */
+    authRefreshAttempted = false;
+    constructor(options) {
+        this.url = options.url;
+        this.apiKey = options.apiKey;
+        this.agentIdentity = options.agentIdentity;
+        this.webSocketCtor = options.webSocketCtor ?? globalThis.WebSocket;
+        this.timeoutMs = options.timeoutMs ?? 15_000;
+        this.reconnectEnabled = options.reconnect ?? false;
+        this.reconnectBaseMs = options.reconnectBaseMs ?? 500;
+        this.reconnectMaxMs = options.reconnectMaxMs ?? 15_000;
+        this.reconnectHerdJitterMs = options.reconnectHerdJitterMs ?? 5_000;
+        this.reconnectMaxAttempts = options.reconnectMaxAttempts ?? Number.POSITIVE_INFINITY;
+        this.refreshAuthToken = options.refreshAuthToken;
+        this.onProtocolMismatch = options.onProtocolMismatch;
+    }
+    /** Subscribe to connection-state transitions (reconnecting/reconnected/failed). */
+    onConnectionChange(listener) {
+        this.connectionListeners.add(listener);
+        return () => {
+            this.connectionListeners.delete(listener);
+        };
+    }
+    emitConnectionState(state, detail) {
+        for (const listener of this.connectionListeners) {
+            try {
+                listener(state, detail);
+            }
+            catch {
+                // A listener error must not break reconnection.
+            }
+        }
+    }
+    connect() {
+        if (this.ws) {
+            if (this.auth)
+                return Promise.resolve(this.auth);
+            return this.waitFor(RoomServerMessageType.AUTH_SUCCESS).then((msg) => msg.payload);
+        }
+        this.closedByClient = false;
+        return this.openSocket();
+    }
+    openSocket() {
+        // Fence any prior socket so a slow-to-die predecessor (e.g. one whose auth
+        // timed out while still connecting) can't feed record() or null out the
+        // fresh socket. Handlers below no-op unless they belong to the current ws.
+        const previous = this.ws;
+        if (previous) {
+            this.ws = null;
+            try {
+                previous.close(1000, "superseded");
+            }
+            catch {
+                // best-effort
+            }
+        }
+        let ws;
+        try {
+            ws = new this.webSocketCtor(this.url);
+        }
+        catch (err) {
+            throw new RoomTransportError(errorMessage(err));
+        }
+        this.ws = ws;
+        ws.addEventListener("open", () => {
+            if (this.ws !== ws)
+                return;
+            this.connected = true;
+            this.send({
+                type: RoomClientMessageType.AUTHENTICATE,
+                payload: {
+                    token: this.apiKey,
+                    protocolVersion: SUPPORTED_ROOM_PROTOCOL_VERSION,
+                    // Sidekick sessions assert their agenthood and display name;
+                    // ghost and user sessions send the bare frame unchanged.
+                    ...(this.agentIdentity ? { isAgent: true, username: this.agentIdentity.name } : {}),
+                },
+                timestamp: Date.now(),
+            });
+        });
+        ws.addEventListener("message", (event) => {
+            if (this.ws !== ws)
+                return;
+            const data = event.data;
+            if (typeof data !== "string" || data.length === 0)
+                return;
+            let parsed;
+            try {
+                parsed = JSON.parse(data);
+            }
+            catch {
+                this.rejectAll(new RoomTransportError("rooms ws: dropped non-json frame"));
+                return;
+            }
+            if (!isRoomShapedFrame(parsed)) {
+                this.rejectAll(new RoomTransportError("rooms ws: dropped malformed frame"));
+                return;
+            }
+            if (!isRoomServerMessage(parsed)) {
+                // Additive-only protocol: a newer relay may send frame types this
+                // client does not know yet. Ignore them; never fail the session.
+                return;
+            }
+            this.record(parsed);
+        });
+        ws.addEventListener("close", (event) => {
+            // A superseded socket's close must not touch current state or trigger
+            // another reconnect.
+            if (this.ws !== ws)
+                return;
+            const e = event;
+            const hadAuth = this.auth !== null;
+            this.connected = false;
+            this.auth = null;
+            this.ws = null;
+            if (!this.closedByClient && !hadAuth && e.code === 1008 && this.refreshAuthToken) {
+                this.authRefreshRequested = true;
+            }
+            this.rejectAll(new RoomTransportError(`rooms ws closed${e.code ? ` (${e.code})` : ""}${e.reason ? `: ${e.reason}` : ""}`));
+            this.maybeReconnect(e.reason || (e.code ? `code ${e.code}` : undefined));
+        });
+        ws.addEventListener("error", () => {
+            if (this.ws !== ws)
+                return;
+            this.rejectAll(new RoomTransportError("rooms ws error"));
+        });
+        return this.waitFor(RoomServerMessageType.AUTH_SUCCESS)
+            .then((msg) => {
+            this.reconnectAttempts = 0;
+            this.authRefreshAttempted = false;
+            return msg.payload;
+        })
+            .catch(async (error) => this.retryGuestAuthentication(error));
+    }
+    maybeReconnect(reason) {
+        if (!this.reconnectEnabled ||
+            this.closedByClient ||
+            this.authRefreshRequested ||
+            this.authRefreshInFlight) {
+            return;
+        }
+        if (this.reconnectTimer)
+            return;
+        if (this.reconnectAttempts >= this.reconnectMaxAttempts) {
+            this.emitConnectionState("failed", {
+                attempt: this.reconnectAttempts,
+                ...(reason ? { error: reason } : {}),
+            });
+            return;
+        }
+        const attempt = this.reconnectAttempts + 1;
+        this.reconnectAttempts = attempt;
+        // Exponential backoff with full jitter, capped.
+        const ceiling = Math.min(this.reconnectMaxMs, this.reconnectBaseMs * 2 ** (attempt - 1));
+        const delay = Math.floor(ceiling * (0.5 + Math.random() * 0.5) + Math.random() * this.reconnectHerdJitterMs);
+        this.emitConnectionState("reconnecting", {
+            attempt,
+            ...(reason ? { error: reason } : {}),
+        });
+        this.reconnectTimer = setTimeout(() => {
+            this.reconnectTimer = null;
+            if (this.closedByClient)
+                return;
+            try {
+                this.openSocket()
+                    .then(() => {
+                    this.emitConnectionState("reconnected", { attempt });
+                })
+                    .catch((err) => {
+                    // Re-auth failed; drive the next backoff attempt.
+                    this.maybeReconnect(errorMessage(err));
+                });
+            }
+            catch (err) {
+                // openSocket can throw synchronously (constructor failure) before it
+                // returns a promise — that must not escape the timer as an uncaught
+                // exception. Fold it back into the backoff loop.
+                this.maybeReconnect(errorMessage(err));
+            }
+        }, delay);
+        if (typeof this.reconnectTimer.unref === "function") {
+            this.reconnectTimer.unref();
+        }
+    }
+    send(msg) {
+        if (!this.ws || !this.connected) {
+            throw new RoomTransportError("rooms ws: not open");
+        }
+        this.ws.send(JSON.stringify(msg));
+    }
+    waitFor(type, predicate, timeoutMs = this.timeoutMs, requestId) {
+        return new Promise((resolve, reject) => {
+            let pending;
+            const timer = setTimeout(() => {
+                this.pending = this.pending.filter((wait) => wait !== pending);
+                reject(new RoomTransportError(`timed out waiting for ${type}`));
+            }, timeoutMs);
+            pending = {
+                type,
+                ...(predicate
+                    ? { predicate: (msg) => predicate(msg) }
+                    : {}),
+                ...(requestId ? { requestId } : {}),
+                resolve: (msg) => resolve(msg),
+                reject,
+                timer,
+            };
+            this.pending.push(pending);
+        });
+    }
+    waitForAny(types, predicate, timeoutMs = this.timeoutMs, requestId) {
+        return new Promise((resolve, reject) => {
+            let pending;
+            const timer = setTimeout(() => {
+                this.pending = this.pending.filter((wait) => wait !== pending);
+                reject(new RoomTransportError(`timed out waiting for ${types.join(" or ")}`));
+            }, timeoutMs);
+            const typeSet = new Set(types);
+            pending = {
+                type: types[0],
+                types: typeSet,
+                predicate: (msg) => typeSet.has(msg.type) &&
+                    (!predicate || predicate(msg)),
+                ...(requestId ? { requestId } : {}),
+                resolve: (msg) => resolve(msg),
+                reject,
+                timer,
+            };
+            this.pending.push(pending);
+        });
+    }
+    onMessage(listener) {
+        this.listeners.add(listener);
+        return () => {
+            this.listeners.delete(listener);
+        };
+    }
+    close() {
+        this.closedByClient = true;
+        if (this.reconnectTimer) {
+            clearTimeout(this.reconnectTimer);
+            this.reconnectTimer = null;
+        }
+        const ws = this.ws;
+        this.ws = null;
+        this.auth = null;
+        this.connected = false;
+        this.rejectAll(new RoomTransportError("rooms ws closed by client"));
+        ws?.close(1000, "client closed");
+    }
+    waiterHandledErrors = new WeakSet();
+    serverProtocolVersion() {
+        return this.serverProtocolVersionValue;
+    }
+    isGuest() {
+        return this.auth?.isGuest === true;
+    }
+    record(msg) {
+        if (msg.type === RoomServerMessageType.AUTH_SUCCESS) {
+            if (!this.handleAuthSuccess(msg.payload))
+                return;
+        }
+        if (msg.type === RoomServerMessageType.ERROR) {
+            if (!this.auth &&
+                this.refreshAuthToken &&
+                isAuthenticationError(msg.payload.code) &&
+                !this.closedByClient) {
+                this.authRefreshRequested = true;
+            }
+            const err = new RoomProtocolError(msg.payload);
+            if (msg.payload.requestId) {
+                if (this.rejectByRequestId(msg.payload.requestId, err)) {
+                    // Precisely correlated: the request's caller owns this failure. Mark
+                    // the frame so passive listeners (the tape pump) don't ALSO surface
+                    // it — background requests against older relays degrade silently.
+                    this.waiterHandledErrors.add(msg);
+                }
+                // A requestId we don't recognize is someone else's request (another
+                // session, a stale retry): never misattribute it to an unrelated
+                // waiter. Passive surfaces still see the frame.
+            }
+            else if (this.rejectOldest(err)) {
+                // Heuristic old-relay fallback: the oldest waiter got the rejection,
+                // but the correlation is a guess. Only hide pure protocol noise;
+                // user-actionable errors (MUTED, READ_ONLY, …) must stay visible.
+                if (msg.payload.code === "BAD_FRAME")
+                    this.waiterHandledErrors.add(msg);
+            }
+        }
+        else {
+            this.resolvePending(msg);
+        }
+        for (const listener of this.listeners)
+            listener(msg);
+    }
+    handleAuthSuccess(payload) {
+        this.auth = payload;
+        this.serverProtocolVersionValue = payload.protocolVersion;
+        if (payload.protocolVersion !== SUPPORTED_ROOM_PROTOCOL_VERSION) {
+            this.onProtocolMismatch?.({
+                supported: SUPPORTED_ROOM_PROTOCOL_VERSION,
+                server: payload.protocolVersion,
+            });
+            const err = new RoomTransportError(`rooms protocol mismatch: server v${payload.protocolVersion}, client supports v${SUPPORTED_ROOM_PROTOCOL_VERSION}`);
+            this.closedByClient = true;
+            this.rejectAll(err);
+            this.ws?.close(1002, "protocol mismatch");
+            return false;
+        }
+        if (!payload.minClientBuild ||
+            !isRoomClientBuildBelowMinimum(VERSION, payload.minClientBuild)) {
+            return true;
+        }
+        const err = new RoomTransportError(`rooms client upgrade required: server requires om v${payload.minClientBuild} or newer (this build is v${VERSION})`);
+        this.closedByClient = true;
+        this.rejectAll(err);
+        this.ws?.close(1008, "client upgrade required");
+        return false;
+    }
+    async retryGuestAuthentication(error) {
+        if (!this.authRefreshRequested || !this.refreshAuthToken || this.closedByClient) {
+            throw error;
+        }
+        if (this.authRefreshAttempted) {
+            // The previous re-mint SUCCEEDED and the server still refused the fresh
+            // key — retrying would mint in a hot loop. Fail the episode instead.
+            throw error;
+        }
+        this.authRefreshRequested = false;
+        this.authRefreshInFlight = true;
+        try {
+            this.apiKey = await this.refreshAuthToken();
+            this.authRefreshAttempted = true;
+            return await this.openSocket();
+        }
+        catch (refreshError) {
+            this.authRefreshInFlight = false;
+            this.maybeReconnect(errorMessage(refreshError));
+            throw refreshError;
+        }
+        finally {
+            this.authRefreshInFlight = false;
+        }
+    }
+    resolvePending(msg) {
+        const remaining = [];
+        for (const wait of this.pending) {
+            if (wait.types ? !wait.types.has(msg.type) : wait.type !== msg.type) {
+                remaining.push(wait);
+                continue;
+            }
+            if (wait.predicate && !wait.predicate(msg)) {
+                remaining.push(wait);
+                continue;
+            }
+            clearTimeout(wait.timer);
+            wait.resolve(msg);
+        }
+        this.pending = remaining;
+    }
+    rejectAll(err) {
+        for (const wait of this.pending) {
+            clearTimeout(wait.timer);
+            wait.reject(err);
+        }
+        this.pending = [];
+    }
+    rejectByRequestId(requestId, err) {
+        if (!requestId)
+            return false;
+        const index = this.pending.findIndex((wait) => wait.requestId === requestId);
+        if (index < 0)
+            return false;
+        const [wait] = this.pending.splice(index, 1);
+        if (!wait)
+            return false;
+        clearTimeout(wait.timer);
+        wait.reject(err);
+        return true;
+    }
+    // Fallback for old relays that do not include requestId on ERROR frames.
+    rejectOldest(err) {
+        const wait = this.pending.shift();
+        if (!wait)
+            return false;
+        clearTimeout(wait.timer);
+        wait.reject(err);
+        return true;
+    }
+    /** Was this ERROR frame already delivered to a waiting request's caller? */
+    errorHandledByWaiter(msg) {
+        return this.waiterHandledErrors.has(msg);
+    }
+}
+/** Returns false for an invalid server value so a typo cannot lock out every client. */
+export function isRoomClientBuildBelowMinimum(clientBuild, minimumBuild) {
+    const client = parseBuild(clientBuild);
+    const minimum = parseBuild(minimumBuild);
+    if (!client || !minimum)
+        return false;
+    for (const index of [0, 1, 2]) {
+        const clientPart = client[index];
+        const minimumPart = minimum[index];
+        if (clientPart !== minimumPart)
+            return clientPart < minimumPart;
+    }
+    return false;
+}
+function parseBuild(value) {
+    const match = /^v?(\d+)(?:\.(\d+))?(?:\.(\d+))?$/.exec(value.trim());
+    if (!match)
+        return null;
+    const parts = [match[1], match[2] ?? "0", match[3] ?? "0"].map(Number);
+    if (parts.some((part) => !Number.isSafeInteger(part)))
+        return null;
+    return parts;
+}
+const KNOWN_SERVER_MESSAGE_TYPES = new Set(Object.values(RoomServerMessageType));
+function isRoomShapedFrame(value) {
+    if (!value || typeof value !== "object")
+        return false;
+    const candidate = value;
+    if (typeof candidate.type !== "string")
+        return false;
+    if (typeof candidate.timestamp !== "number")
+        return false;
+    if (!candidate.payload || typeof candidate.payload !== "object")
+        return false;
+    return true;
+}
+function isRoomServerMessage(value) {
+    // A hostile or buggy relay cannot smuggle an unexpected shape past the
+    // type switch that consumers rely on: only known frame types pass.
+    return isRoomShapedFrame(value) && KNOWN_SERVER_MESSAGE_TYPES.has(value.type);
+}
+function errorMessage(err) {
+    return err instanceof Error ? err.message : String(err);
+}
+function isAuthenticationError(code) {
+    return code === "AUTH_FAILED" || code === "AUTH_TIMEOUT" || code === "TOKEN_REQUIRED";
+}

package/package.json

@@ -0,0 +1,180 @@
+{
+  "name": "@openmarket/rooms-client",
+  "version": "0.1.0",
+  "description": "OM Rooms protocol client: wire types, WebSocket + REST clients, and chat view-models. Browser-safe (no node:/bun: imports).",
+  "type": "module",
+  "license": "Apache-2.0",
+  "author": "OpenMarket",
+  "homepage": "https://github.com/openmarket-xyz/openmarket-releases#readme",
+  "bugs": {
+    "url": "https://github.com/openmarket-xyz/openmarket-releases/issues"
+  },
+  "repository": {
+    "type": "git",
+    "url": "git+https://github.com/openmarket-xyz/openmarket-releases.git"
+  },
+  "engines": {
+    "bun": ">=1.3.0",
+    "node": ">=22"
+  },
+  "files": ["src", "dist", "README.md", "LICENSE"],
+  "publishConfig": {
+    "access": "public"
+  },
+  "exports": {
+    "./client": {
+      "bun": "./src/client.ts",
+      "types": "./dist/client.d.ts",
+      "default": "./dist/client.js"
+    },
+    "./ws-client": {
+      "bun": "./src/ws-client.ts",
+      "types": "./dist/ws-client.d.ts",
+      "default": "./dist/ws-client.js"
+    },
+    "./social-client": {
+      "bun": "./src/social-client.ts",
+      "types": "./dist/social-client.d.ts",
+      "default": "./dist/social-client.js"
+    },
+    "./social-types": {
+      "bun": "./src/social-types.ts",
+      "types": "./dist/social-types.d.ts",
+      "default": "./dist/social-types.js"
+    },
+    "./library-publisher": {
+      "bun": "./src/library-publisher.ts",
+      "types": "./dist/library-publisher.d.ts",
+      "default": "./dist/library-publisher.js"
+    },
+    "./doc-reconcile": {
+      "bun": "./src/doc-reconcile.ts",
+      "types": "./dist/doc-reconcile.d.ts",
+      "default": "./dist/doc-reconcile.js"
+    },
+    "./topic-uri": {
+      "bun": "./src/topic-uri.ts",
+      "types": "./dist/topic-uri.d.ts",
+      "default": "./dist/topic-uri.js"
+    },
+    "./doc-uri": {
+      "bun": "./src/doc-uri.ts",
+      "types": "./dist/doc-uri.d.ts",
+      "default": "./dist/doc-uri.js"
+    },
+    "./endpoints": {
+      "bun": "./src/endpoints.ts",
+      "types": "./dist/endpoints.d.ts",
+      "default": "./dist/endpoints.js"
+    },
+    "./jwt": {
+      "bun": "./src/jwt.ts",
+      "types": "./dist/jwt.d.ts",
+      "default": "./dist/jwt.js"
+    },
+    "./names": {
+      "bun": "./src/names.ts",
+      "types": "./dist/names.d.ts",
+      "default": "./dist/names.js"
+    },
+    "./suggestion-attribution": {
+      "bun": "./src/suggestion-attribution.ts",
+      "types": "./dist/suggestion-attribution.d.ts",
+      "default": "./dist/suggestion-attribution.js"
+    },
+    "./merge3": {
+      "bun": "./src/merge3.ts",
+      "types": "./dist/merge3.d.ts",
+      "default": "./dist/merge3.js"
+    },
+    "./types": {
+      "bun": "./src/types.ts",
+      "types": "./dist/types.d.ts",
+      "default": "./dist/types.js"
+    },
+    "./agent/armed-mode": {
+      "bun": "./src/agent/armed-mode.ts",
+      "types": "./dist/agent/armed-mode.d.ts",
+      "default": "./dist/agent/armed-mode.js"
+    },
+    "./agent/lane-draft": {
+      "bun": "./src/agent/lane-draft.ts",
+      "types": "./dist/agent/lane-draft.d.ts",
+      "default": "./dist/agent/lane-draft.js"
+    },
+    "./agent/lane-prompts": {
+      "bun": "./src/agent/lane-prompts.ts",
+      "types": "./dist/agent/lane-prompts.d.ts",
+      "default": "./dist/agent/lane-prompts.js"
+    },
+    "./agent/library-context": {
+      "bun": "./src/agent/library-context.ts",
+      "types": "./dist/agent/library-context.d.ts",
+      "default": "./dist/agent/library-context.js"
+    },
+    "./agent/library-model": {
+      "bun": "./src/agent/library-model.ts",
+      "types": "./dist/agent/library-model.d.ts",
+      "default": "./dist/agent/library-model.js"
+    },
+    "./agent/room-context": {
+      "bun": "./src/agent/room-context.ts",
+      "types": "./dist/agent/room-context.d.ts",
+      "default": "./dist/agent/room-context.js"
+    },
+    "./agent/sidebar-model": {
+      "bun": "./src/agent/sidebar-model.ts",
+      "types": "./dist/agent/sidebar-model.d.ts",
+      "default": "./dist/agent/sidebar-model.js"
+    },
+    "./agent/topic-inbox": {
+      "bun": "./src/agent/topic-inbox.ts",
+      "types": "./dist/agent/topic-inbox.d.ts",
+      "default": "./dist/agent/topic-inbox.js"
+    },
+    "./agent/topic-view-batcher": {
+      "bun": "./src/agent/topic-view-batcher.ts",
+      "types": "./dist/agent/topic-view-batcher.d.ts",
+      "default": "./dist/agent/topic-view-batcher.js"
+    },
+    "./agent/clients/common": {
+      "bun": "./src/agent/clients/common.ts",
+      "types": "./dist/agent/clients/common.d.ts",
+      "default": "./dist/agent/clients/common.js"
+    },
+    "./shared/rooms-protocol": {
+      "bun": "./src/shared/rooms-protocol.ts",
+      "types": "./dist/shared/rooms-protocol.d.ts",
+      "default": "./dist/shared/rooms-protocol.js"
+    },
+    "./shared/mentions": {
+      "bun": "./src/shared/mentions.ts",
+      "types": "./dist/shared/mentions.d.ts",
+      "default": "./dist/shared/mentions.js"
+    },
+    "./shared/emoji-data": {
+      "bun": "./src/shared/emoji-data.ts",
+      "types": "./dist/shared/emoji-data.d.ts",
+      "default": "./dist/shared/emoji-data.js"
+    },
+    "./version": {
+      "bun": "./src/version.ts",
+      "types": "./dist/version.d.ts",
+      "default": "./dist/version.js"
+    },
+    "./package.json": "./package.json"
+  },
+  "scripts": {
+    "build": "rm -rf dist && tsc -p tsconfig.build.json",
+    "prepublishOnly": "bun run build",
+    "test": "bun test",
+    "typecheck": "tsc --noEmit -p tsconfig.json"
+  },
+  "dependencies": {
+    "@earendil-works/pi-ai": "0.78.1",
+    "picocolors": "1.1.1"
+  },
+  "devDependencies": {
+    "@types/node": "25.9.2"
+  }
+}