@catalyst-cloud/sdk 0.1.0

package/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 Coalesce Labs
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

package/README.md

@@ -0,0 +1,207 @@
+# @catalyst-cloud/sdk
+
+The **isomorphic read-layer-over-WebSocket client** for the catalyst-cloud change-feed.
+
+`catalyst-cloud` mirrors each tenant's Linear + GitHub state into a per-tenant Cloudflare Durable
+Object and exposes it as a `change_log` feed. This SDK is the **push** consumer of that feed: it opens
+an outbound WebSocket to a tenant's Mirror DO (`{baseUrl}/connect`), sends a cursor-replay request on
+every (re)connect, and hands you each pushed change so you can land it into your own store.
+
+It is the standalone extraction of the host daemon's live client, generalized to run **unchanged in a
+browser, in Node (>=22), or in Bun**. It is the single push transport behind both the host replicas
+and the web UI per [ADR-0008](https://github.com/coalesce-labs/catalyst-cloud/blob/main/docs/adr/0008-catalyst-host-local-replica-consumption.md)
+(host reads from an SDK-managed per-host replica) and [ADR-0009](https://github.com/coalesce-labs/catalyst-cloud/blob/main/docs/adr/0009-browser-live-updates-over-websocket.md)
+(browser live updates over a **hibernating** WebSocket, not SSE — so an idle tab can't pin the DO).
+
+## Install
+
+```sh
+npm install @catalyst-cloud/sdk
+```
+
+Requires a platform `WebSocket` global (browser, Bun, or Node >=22). On older Node, inject a
+`wsFactory` (e.g. wrapping the [`ws`](https://www.npmjs.com/package/ws) package) — the shared core has
+no node-only import.
+
+## Design
+
+The client is **transport-only and storage-agnostic**. It knows nothing about where your data lives
+(`bun:sqlite`, OPFS, in-memory) or how you authenticate — both are **injected**:
+
+- **`auth`** — `{ kind: "token", token }` (a trusted backend appends `?token=`; the Worker strips it
+  before forwarding to the DO) **or** `{ kind: "cookie" }` (the browser appends nothing; the
+  same-origin session cookie rides the upgrade). The cookie path can never leak a token.
+- **`reseed`** — an async callback returning the fresh cursor after a full re-seed. Called on a
+  `{type:"resync"}` underflow frame (and before the first connect if you have no cursor). A host pulls
+  `/snapshot` into SQLite here; a browser re-runs its own seed.
+- **`getCursor` / `onChange`** — you own the cursor and the writes; the client drives the wire.
+- **`onStatus`** — connection lifecycle (`connecting` / `live` / `reconnecting` / `resyncing` /
+  `error` / `stopped`) so a UI can show "live" vs "reconnecting".
+
+It reconnects with **capped exponential backoff** (1 s → ×2 → 30 s ceiling) and never throws out of
+the event loop. There is **no client-side keepalive** — re-implementing the WebSocket heartbeat would
+re-pin the hibernating DO, defeating ADR-0009.
+
+## Usage
+
+### Browser (cookie auth, no token)
+
+In the browser there is **no token**: pass `auth: { kind: "cookie" }` and the same-origin session
+cookie rides the WebSocket upgrade automatically. The SDK appends nothing secret to the URL, so a
+token can never leak from a browser tab. Storage is yours — here it is a trivial in-memory map; in a
+real app you would seed from your own `/snapshot` fetch into OPFS / IndexedDB.
+
+```ts
+import { LiveSyncClient } from "@catalyst-cloud/sdk";
+
+const issues = new Map<string, unknown>();
+let cursor: number | null = null;
+
+const client = new LiveSyncClient({
+  baseUrl: "https://app.example.com/api/v1", // same origin as the page
+  accountId: "tenant-0",
+  auth: { kind: "cookie" }, // same-origin cookie rides the upgrade; no token ever in the URL
+
+  // Full (re)seed from your own snapshot endpoint; resolve to the fresh cursor.
+  reseed: async () => {
+    const snap = (await (await fetch("/api/v1/snapshot?account=tenant-0")).json()) as {
+      cursor: number;
+      issues: { id: string }[];
+    };
+    issues.clear();
+    for (const row of snap.issues) issues.set(row.id, row);
+    cursor = snap.cursor;
+    return snap.cursor;
+  },
+
+  getCursor: () => cursor,
+  onChange: (frame) => {
+    if (frame.op === "delete") issues.delete(frame.entityId);
+    else issues.set(frame.entityId, frame.row);
+    cursor = frame.seq;
+  },
+  onStatus: (s) => setConnectionBadge(s), // "live" / "reconnecting" / …
+});
+
+void client.start(); // never await in the browser — it resolves only on stop()
+// on teardown (component unmount, page hide):
+client.stop();
+```
+
+### Backend / host daemon (token auth, `bun:sqlite` reseed)
+
+A trusted backend authenticates with a service token (`?token=`, stripped by the Worker before it
+reaches the DO) and lands every frame into a local SQLite replica. On a `{type:"resync"}` underflow
+(or the very first run with no cursor) it pulls a full `/snapshot` and rewrites the table:
+
+```ts
+import { Database } from "bun:sqlite"; // node: use better-sqlite3 with the same calls
+import { LiveSyncClient } from "@catalyst-cloud/sdk";
+
+const db = new Database("replica.sqlite");
+db.run("CREATE TABLE IF NOT EXISTS issues (id TEXT PRIMARY KEY, row TEXT, seq INTEGER)");
+db.run("CREATE TABLE IF NOT EXISTS sync_state (k TEXT PRIMARY KEY, cursor INTEGER)");
+
+const baseUrl = process.env.CATALYST_CLOUD_BASE_URL!; // incl. /api/v1
+const token = process.env.ADMIN_TOKEN!;
+
+const client = new LiveSyncClient({
+  baseUrl,
+  accountId: "tenant-0",
+  auth: { kind: "token", token },
+
+  // Full re-seed: pull /snapshot over HTTPS and rewrite the replica in one transaction.
+  // Must resolve to the fresh cursor (the snapshot's max change_log.seq).
+  reseed: async () => {
+    const res = await fetch(`${baseUrl}/snapshot?account=tenant-0`, {
+      headers: { authorization: `Bearer ${token}` },
+    });
+    const snap = (await res.json()) as { cursor: number; issues: { id: string }[] };
+    const tx = db.transaction(() => {
+      db.run("DELETE FROM issues");
+      const ins = db.prepare("INSERT INTO issues (id, row, seq) VALUES (?, ?, ?)");
+      for (const row of snap.issues) ins.run(row.id, JSON.stringify(row), snap.cursor);
+      db.run(
+        "INSERT INTO sync_state (k, cursor) VALUES ('replica', ?) " +
+          "ON CONFLICT(k) DO UPDATE SET cursor = excluded.cursor",
+        [snap.cursor],
+      );
+    });
+    tx();
+    return snap.cursor;
+  },
+
+  // Own the cursor + the writes; the client just drives the wire.
+  getCursor: () =>
+    (db.query("SELECT cursor FROM sync_state WHERE k = 'replica'").get() as
+      | { cursor: number }
+      | undefined)?.cursor ?? null,
+
+  onChange: (frame) => {
+    const tx = db.transaction(() => {
+      if (frame.op === "delete") {
+        db.run("DELETE FROM issues WHERE id = ?", [frame.entityId]);
+      } else {
+        db.run(
+          "INSERT INTO issues (id, row, seq) VALUES (?, ?, ?) " +
+            "ON CONFLICT(id) DO UPDATE SET row = excluded.row, seq = excluded.seq",
+          [frame.entityId, JSON.stringify(frame.row), frame.seq],
+        );
+      }
+      db.run("UPDATE sync_state SET cursor = ? WHERE k = 'replica'", [frame.seq]);
+    });
+    tx();
+  },
+});
+
+await client.start(); // resolves only when stop() is called — keeps the process alive between deltas
+```
+
+> On Node older than 22, inject a `wsFactory` that wraps the [`ws`](https://www.npmjs.com/package/ws)
+> package: `wsFactory: (url) => new WebSocket(url) as unknown as WebSocketLike`. Node 22+ and Bun
+> expose a global `WebSocket`, so no factory is needed.
+
+## API
+
+| Export | What it is |
+| --- | --- |
+| `LiveSyncClient` | The client. `new LiveSyncClient(opts)`, then `start()` / `stop()` / `connectUrl()`. |
+| `LiveSyncClientOptions` | The full options shape (auth, reseed, getCursor, onChange, onStatus, backoff, wsFactory, log). |
+| `AuthStrategy` | `{ kind: "token"; token }` (backend) or `{ kind: "cookie" }` (browser). |
+| `LiveSyncStatus` | `"connecting"` · `"live"` · `"reconnecting"` · `"resyncing"` · `"error"` · `"stopped"`. |
+| `WebSocketLike` / `WebSocketFactory` | The minimal structural WS surface + the injectable factory (for old Node / tests). |
+| `ChangeFrame` · `ResyncFrame` · `SyncFrame` · `ServerFrame` | The wire frames (see below). |
+| `EntityName` · `ChangeOp` · `ENTITY_NAMES` · `CHANGE_OPS` | The canonical table / op contract (types + frozen runtime arrays). |
+| `buildConnectUrl` · `parseFrame` · `toWsOrigin` | The pure helpers the client is built from (exported for diagnostics/tests). |
+
+`start()` returns a Promise that resolves **only** when `stop()` is called — on a backend `await` it
+to keep the process alive; in a browser never await it and just call `stop()` on teardown.
+
+## Wire contract
+
+The frame shapes (`ChangeFrame`, `ResyncFrame`, `SyncFrame`, `EntityName`, `ChangeOp`) are vendored as
+a self-contained copy of the catalyst-cloud `@catalyst-cloud/types` contract
+([`src/types.ts`](https://github.com/coalesce-labs/catalyst-cloud-sdk/blob/main/src/types.ts)) — the
+SDK has **no dependency** on that internal package. A contract test pins the literal members so drift
+from the monorepo is caught.
+
+## Contributing
+
+The source of truth is `src/`; the published `dist/` is generated by `tsc` and must stay byte-stable
+(the catalyst-cloud monorepo consumes it via a `file:` dependency). Workflow:
+
+```sh
+bun install
+bun run build        # tsc -p tsconfig.build.json → dist/
+bun run typecheck    # tsc --noEmit over src + test
+bunx vitest run      # the test suite (contract + client)
+```
+
+Before opening a PR, run all three and confirm `dist/` has no unexpected diff. CI (GitHub Actions)
+runs install + build + test on every push and PR. Releases are cut by bumping `version` and running
+`npm publish` (the `prepublishOnly` hook rebuilds `dist/` first; the package is published with public
+access via `publishConfig`).
+
+## License
+
+MIT © Coalesce Labs — see [LICENSE](LICENSE).

package/dist/index.d.ts

@@ -0,0 +1,3 @@
+export { LiveSyncClient, buildConnectUrl, parseFrame, toWsOrigin, type AuthStrategy, type LiveSyncClientOptions, type LiveSyncStatus, type LogLevel, type WebSocketLike, type WebSocketFactory, } from "./live-sync-client.js";
+export { ENTITY_NAMES, CHANGE_OPS, type AccountId, type EntityName, type ChangeOp, type ChangeFrame, type ResyncFrame, type SyncFrame, type ServerFrame, } from "./types.js";
+//# sourceMappingURL=index.d.ts.map

package/dist/index.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"index.d.ts","sourceRoot":"","sources":["../src/index.ts"],"names":[],"mappings":"AAQA,OAAO,EACL,cAAc,EACd,eAAe,EACf,UAAU,EACV,UAAU,EACV,KAAK,YAAY,EACjB,KAAK,qBAAqB,EAC1B,KAAK,cAAc,EACnB,KAAK,QAAQ,EACb,KAAK,aAAa,EAClB,KAAK,gBAAgB,GACtB,MAAM,uBAAuB,CAAC;AAE/B,OAAO,EACL,YAAY,EACZ,UAAU,EACV,KAAK,SAAS,EACd,KAAK,UAAU,EACf,KAAK,QAAQ,EACb,KAAK,WAAW,EAChB,KAAK,WAAW,EAChB,KAAK,SAAS,EACd,KAAK,WAAW,GACjB,MAAM,YAAY,CAAC"}

package/dist/index.js

@@ -0,0 +1,10 @@
+// @catalyst-cloud/sdk — public entrypoint.
+//
+// The isomorphic (browser + node/bun) read-layer-over-WebSocket client for the catalyst-cloud
+// change-feed (ADR-0008/0009). Open a WebSocket to a tenant's Mirror Durable Object, send a
+// cursor-replay request on every (re)connect, and apply each pushed change into your own store.
+//
+// The class is storage-agnostic and auth-injected: see {@link LiveSyncClient}.
+export { LiveSyncClient, buildConnectUrl, parseFrame, toWsOrigin, } from "./live-sync-client.js";
+export { ENTITY_NAMES, CHANGE_OPS, } from "./types.js";
+//# sourceMappingURL=index.js.map

package/dist/index.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"index.js","sourceRoot":"","sources":["../src/index.ts"],"names":[],"mappings":"AAAA,2CAA2C;AAC3C,EAAE;AACF,8FAA8F;AAC9F,4FAA4F;AAC5F,gGAAgG;AAChG,EAAE;AACF,+EAA+E;AAE/E,OAAO,EACL,cAAc,EACd,eAAe,EACf,UAAU,EACV,UAAU,GAOX,MAAM,uBAAuB,CAAC;AAE/B,OAAO,EACL,YAAY,EACZ,UAAU,GAQX,MAAM,YAAY,CAAC"}

package/dist/live-sync-client.d.ts

@@ -0,0 +1,151 @@
+import type { ChangeFrame, ServerFrame } from "./types.js";
+/**
+ * The minimal WHATWG-WebSocket surface LiveSyncClient drives. Declared structurally (not via a DOM /
+ * Node lib type) so (a) the package needs no `@types/ws` / DOM lib and (b) tests inject a fake. The
+ * browser, Bun, and Node (>=22) global `WebSocket` are all structurally assignable to this.
+ */
+export interface WebSocketLike {
+    send(data: string): void;
+    close(code?: number, reason?: string): void;
+    onopen: ((ev: unknown) => void) | null;
+    onmessage: ((ev: {
+        data: unknown;
+    }) => void) | null;
+    onclose: ((ev: unknown) => void) | null;
+    onerror: ((ev: unknown) => void) | null;
+}
+/** Opens a WebSocket to `url`. Defaults to the runtime global `WebSocket`; tests/node inject one. */
+export type WebSocketFactory = (url: string) => WebSocketLike;
+/**
+ * How the consumer proves it may open `/connect`.
+ *
+ *  • `token`  — a SERVICE bearer (e.g. the host's ADMIN_TOKEN). The WHATWG WebSocket constructor
+ *    cannot set an Authorization header, so the token rides the URL as `?token=`. The Worker
+ *    constant-time compares it against the configured secret and STRIPS it before forwarding to the
+ *    DO. Use this ONLY on a trusted backend (the host daemon) — never the browser.
+ *  • `cookie` — append NOTHING to the URL. The browser's same-origin session cookie rides the
+ *    WebSocket upgrade automatically. This makes it impossible to leak a token from the browser path.
+ */
+export type AuthStrategy = {
+    kind: "token";
+    token: string;
+} | {
+    kind: "cookie";
+};
+/** Connection lifecycle, surfaced via `onStatus` so a consumer can drive UI. */
+export type LiveSyncStatus = "connecting" | "live" | "reconnecting" | "resyncing" | "error" | "stopped";
+/** Structured log levels (matches the host-sync logger contract). */
+export type LogLevel = "info" | "warn" | "error";
+/** Configuration for a {@link LiveSyncClient}. */
+export interface LiveSyncClientOptions {
+    /**
+     * The Worker public origin, http(s), INCLUDING any versioned path prefix (e.g.
+     * "https://api.example/api/v1"). The scheme is swapped to ws(s) and `connectPath` is appended
+     * verbatim (path-preserving). A trailing slash is trimmed.
+     */
+    baseUrl: string;
+    /** The tenant id = the Mirror DO name; sent as `?account=` on the connect URL. */
+    accountId: string;
+    /**
+     * The connect route. Default "/connect"; the Worker dual-serves it at "/api/v1/connect" too, so a
+     * path-prefixed `baseUrl` ("…/api/v1") with the default "/connect" resolves to "…/api/v1/connect".
+     */
+    connectPath?: string;
+    /** How to authorize the upgrade. token → ?token= (host); cookie → nothing (browser). */
+    auth: AuthStrategy;
+    /**
+     * Re-seed the consumer's store from a full snapshot and resolve to the FRESH cursor. Called on a
+     * `{type:"resync"}` underflow frame and (optionally) before the first connect. The host pulls
+     * /snapshot into bun:sqlite; the browser re-runs its OPFS seed(). The client closes the socket
+     * before calling this so no live frame interleaves with the seed.
+     */
+    reseed: () => Promise<number>;
+    /**
+     * Read the consumer's durable cursor (the last applied change_log.seq), or null/undefined if it has
+     * never seeded. Drives the `{type:"sync", after}` catch-up request. Return `null` to send
+     * `after: -1` (replay from the start).
+     */
+    getCursor: () => number | null | undefined;
+    /**
+     * Land one applied change frame into the consumer's store. The client does NOT persist for you —
+     * this is where the host upserts into bun:sqlite and advances its cursor, or the browser writes
+     * OPFS. Errors thrown here are caught and logged (one bad frame won't wedge the stream).
+     */
+    onChange: (frame: ChangeFrame) => void;
+    /** Optional: every parsed server frame (change OR resync), before the type-specific handling. */
+    onFrame?: (frame: ServerFrame) => void;
+    /** Optional: connection lifecycle, for UI ("live"/"reconnecting"/…). */
+    onStatus?: (status: LiveSyncStatus) => void;
+    /** Base reconnect backoff in ms; doubles each failed attempt up to maxBackoffMs. Default 1000. */
+    backoffMs?: number;
+    /** Reconnect backoff ceiling in ms. Default 30_000. */
+    maxBackoffMs?: number;
+    /** Injectable WebSocket factory (tests / a node polyfill). Defaults to `globalThis.WebSocket`. */
+    wsFactory?: WebSocketFactory;
+    /** Optional structured logger; defaults to console. */
+    log?: (level: LogLevel, msg: string, extra?: unknown) => void;
+}
+/** http(s)://host → ws(s)://host, leaving the rest of the origin + path intact (https→wss, http→ws). */
+export declare function toWsOrigin(baseUrl: string): string;
+/**
+ * Build the `/connect` URL with `?account=` and, for token auth, `?token=`. For cookie auth NO token
+ * is ever appended (the type system + this single construction point make a browser token leak
+ * impossible). Token is ordered FIRST so a truncated log line still reveals the account.
+ */
+export declare function buildConnectUrl(opts: {
+    baseUrl: string;
+    connectPath: string;
+    accountId: string;
+    auth: AuthStrategy;
+}): string;
+export declare class LiveSyncClient {
+    private readonly baseUrl;
+    private readonly accountId;
+    private readonly connectPath;
+    private readonly auth;
+    private readonly reseed;
+    private readonly getCursor;
+    private readonly onChange;
+    private readonly onFrame?;
+    private readonly onStatus?;
+    private readonly backoffMs;
+    private readonly maxBackoffMs;
+    private readonly wsFactory;
+    private readonly log;
+    private ws;
+    private stopped;
+    private resyncing;
+    private backoff;
+    private reconnectTimer;
+    private resolveDone;
+    constructor(opts: LiveSyncClientOptions);
+    /**
+     * Start the client: seed first if the consumer has no cursor, then open the live socket and keep it
+     * open. Returns a Promise that resolves ONLY when stop() is called (mirrors the host daemon's "runs
+     * forever" contract) — the open WebSocket keeps the process alive between deltas. In a browser the
+     * returned Promise is simply never awaited; call stop() on teardown.
+     */
+    start(): Promise<void>;
+    /** Stop the client: close the socket, cancel any pending reconnect, resolve start(). Idempotent. */
+    stop(): void;
+    /** The ws(s):// URL this client opens, for diagnostics/tests. Re-derived from the options. */
+    connectUrl(): string;
+    private setStatus;
+    private openSocket;
+    /** Detach handlers BEFORE closing so a programmatic close can't re-enter scheduleReconnect. */
+    private closeSocket;
+    private scheduleReconnect;
+    /** Ask the DO to replay everything after our durable cursor. */
+    private sendSync;
+    private handleFrame;
+    /**
+     * Cursor underflow: the deltas we need were evicted from the DO's change_log ring. Close the socket
+     * (so no live frame interleaves with the re-seed), re-seed via the injected callback, then reconnect
+     * — which re-sends {type:"sync"} from the fresh cursor. `resyncing` guards against a second resync
+     * frame and suppresses scheduleReconnect for the duration so we reopen exactly once.
+     */
+    private handleResync;
+}
+/** Parse a WS frame (string or ArrayBuffer) into a known server frame, or null for anything malformed. */
+export declare function parseFrame(data: unknown): ServerFrame | null;
+//# sourceMappingURL=live-sync-client.d.ts.map

package/dist/live-sync-client.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"live-sync-client.d.ts","sourceRoot":"","sources":["../src/live-sync-client.ts"],"names":[],"mappings":"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"}

package/dist/live-sync-client.js

@@ -0,0 +1,293 @@
+// @catalyst-cloud/sdk — LiveSyncClient: the isomorphic read-layer-over-WebSocket client.
+//
+// The push transport for the catalyst-cloud change-feed (ADR-0008/0009). It opens an OUTBOUND
+// WebSocket to a tenant's Mirror Durable Object (`{baseUrl}{connectPath}`) and lets the DO push each
+// change_log delta the instant it lands. On every (re)connect it sends `{type:"sync", after:<cursor>}`
+// so the DO replays — in seq order — everything the consumer missed; a `{type:"resync"}` frame
+// (cursor underflow) triggers a full re-seed via the injected `reseed` callback. It reconnects with
+// capped exponential backoff and never throws out of the event loop.
+//
+// This is the STANDALONE extraction of apps/host-sync/src/live-client.ts. It is deliberately
+// transport-only and storage-agnostic: it does NOT know about bun:sqlite, /snapshot, ADMIN_TOKEN, or
+// any host-only assumption. Those are INJECTED:
+//
+//   • auth      — {kind:"token", token} (host → ?token=) OR {kind:"cookie"} (browser → nothing; the
+//                 same-origin cookie rides the upgrade). A cookie-kind client can never leak a token.
+//   • reseed    — async callback returning the fresh cursor. The host pulls /snapshot into bun:sqlite;
+//                 the browser re-runs its own OPFS seed(). The class never hardcodes a snapshot path.
+//   • onChange  — each applied change frame (the consumer lands it into its own store).
+//   • onStatus  — connection lifecycle ("connecting"/"live"/"reconnecting"/"resyncing"/"error"/
+//                 "stopped"), so a UI can render "live"/"reconnecting".
+//   • wsFactory — injectable WebSocket constructor (tests / a node polyfill). Defaults to the
+//                 platform global `WebSocket` (browser, Bun, Node >=22) so the shared core has NO
+//                 node-only import like 'ws'.
+//
+// There is intentionally NO setInterval keepalive: the WHATWG WebSocket ping/pong is handled by the
+// platform and a re-implemented heartbeat would re-pin the hibernating DO (ADR-0009), defeating the
+// whole point of moving off SSE.
+/** Resolve the runtime global WebSocket, or fail with an actionable message. */
+function defaultWsFactory(url) {
+    const Ctor = globalThis.WebSocket;
+    if (!Ctor) {
+        throw new Error("global WebSocket unavailable; pass wsFactory (browser, Bun, or Node >=22 expose one)");
+    }
+    return new Ctor(url);
+}
+/** http(s)://host → ws(s)://host, leaving the rest of the origin + path intact (https→wss, http→ws). */
+export function toWsOrigin(baseUrl) {
+    return baseUrl.replace(/^http/i, "ws");
+}
+/**
+ * Build the `/connect` URL with `?account=` and, for token auth, `?token=`. For cookie auth NO token
+ * is ever appended (the type system + this single construction point make a browser token leak
+ * impossible). Token is ordered FIRST so a truncated log line still reveals the account.
+ */
+export function buildConnectUrl(opts) {
+    const origin = toWsOrigin(opts.baseUrl.replace(/\/+$/, ""));
+    const params = new URLSearchParams();
+    if (opts.auth.kind === "token")
+        params.set("token", opts.auth.token);
+    params.set("account", opts.accountId);
+    return `${origin}${opts.connectPath}?${params.toString()}`;
+}
+export class LiveSyncClient {
+    baseUrl;
+    accountId;
+    connectPath;
+    auth;
+    reseed;
+    getCursor;
+    onChange;
+    onFrame;
+    onStatus;
+    backoffMs;
+    maxBackoffMs;
+    wsFactory;
+    log;
+    ws = null;
+    stopped = false;
+    resyncing = false;
+    backoff;
+    reconnectTimer = null;
+    resolveDone = null;
+    constructor(opts) {
+        this.baseUrl = opts.baseUrl.replace(/\/+$/, "");
+        this.accountId = opts.accountId;
+        this.connectPath = opts.connectPath ?? "/connect";
+        this.auth = opts.auth;
+        this.reseed = opts.reseed;
+        this.getCursor = opts.getCursor;
+        this.onChange = opts.onChange;
+        this.onFrame = opts.onFrame;
+        this.onStatus = opts.onStatus;
+        this.backoffMs = opts.backoffMs ?? 1000;
+        this.maxBackoffMs = opts.maxBackoffMs ?? 30_000;
+        this.wsFactory = opts.wsFactory ?? defaultWsFactory;
+        this.log =
+            opts.log ??
+                ((lvl, msg, extra) => console[lvl === "error" ? "error" : "log"](`[catalyst-sdk:live] ${msg}`, extra ?? ""));
+        this.backoff = this.backoffMs;
+    }
+    /**
+     * Start the client: seed first if the consumer has no cursor, then open the live socket and keep it
+     * open. Returns a Promise that resolves ONLY when stop() is called (mirrors the host daemon's "runs
+     * forever" contract) — the open WebSocket keeps the process alive between deltas. In a browser the
+     * returned Promise is simply never awaited; call stop() on teardown.
+     */
+    async start() {
+        this.stopped = false;
+        const saved = this.getCursor();
+        if (saved == null) {
+            this.setStatus("resyncing");
+            await this.reseed();
+        }
+        this.openSocket();
+        return new Promise((resolve) => {
+            this.resolveDone = resolve;
+        });
+    }
+    /** Stop the client: close the socket, cancel any pending reconnect, resolve start(). Idempotent. */
+    stop() {
+        this.stopped = true;
+        if (this.reconnectTimer != null) {
+            clearTimeout(this.reconnectTimer);
+            this.reconnectTimer = null;
+        }
+        this.closeSocket();
+        this.setStatus("stopped");
+        const done = this.resolveDone;
+        this.resolveDone = null;
+        done?.();
+    }
+    /** The ws(s):// URL this client opens, for diagnostics/tests. Re-derived from the options. */
+    connectUrl() {
+        return buildConnectUrl({
+            baseUrl: this.baseUrl,
+            connectPath: this.connectPath,
+            accountId: this.accountId,
+            auth: this.auth,
+        });
+    }
+    setStatus(status) {
+        try {
+            this.onStatus?.(status);
+        }
+        catch (err) {
+            this.log("warn", "onStatus handler threw", err);
+        }
+    }
+    openSocket() {
+        if (this.stopped)
+            return;
+        this.setStatus("connecting");
+        const wsUrl = this.connectUrl();
+        let ws;
+        try {
+            ws = this.wsFactory(wsUrl);
+        }
+        catch (err) {
+            this.log("error", "ws construction failed; scheduling reconnect", err);
+            this.setStatus("error");
+            this.scheduleReconnect();
+            return;
+        }
+        this.ws = ws;
+        ws.onopen = () => {
+            this.backoff = this.backoffMs; // a successful open resets the backoff ramp
+            this.setStatus("live");
+            this.sendSync();
+        };
+        ws.onmessage = (ev) => {
+            void this.handleFrame(ev.data);
+        };
+        ws.onclose = () => {
+            if (this.ws === ws)
+                this.ws = null;
+            if (!this.stopped && !this.resyncing)
+                this.setStatus("reconnecting");
+            this.scheduleReconnect();
+        };
+        ws.onerror = (err) => {
+            // Some implementations fire error THEN close; close() here is best-effort and onclose drives the
+            // reconnect so we never double-schedule.
+            this.log("warn", "ws error", err);
+            this.setStatus("error");
+            try {
+                ws.close();
+            }
+            catch {
+                // already closing/closed
+            }
+        };
+    }
+    /** Detach handlers BEFORE closing so a programmatic close can't re-enter scheduleReconnect. */
+    closeSocket() {
+        const ws = this.ws;
+        this.ws = null;
+        if (!ws)
+            return;
+        ws.onopen = null;
+        ws.onmessage = null;
+        ws.onclose = null;
+        ws.onerror = null;
+        try {
+            ws.close();
+        }
+        catch {
+            // already closed
+        }
+    }
+    scheduleReconnect() {
+        if (this.stopped || this.resyncing || this.reconnectTimer != null)
+            return;
+        const delay = this.backoff;
+        this.backoff = Math.min(this.backoff * 2, this.maxBackoffMs);
+        this.reconnectTimer = setTimeout(() => {
+            this.reconnectTimer = null;
+            this.openSocket();
+        }, delay);
+    }
+    /** Ask the DO to replay everything after our durable cursor. */
+    sendSync() {
+        const after = this.getCursor() ?? -1;
+        const frame = { type: "sync", after };
+        try {
+            this.ws?.send(JSON.stringify(frame));
+        }
+        catch (err) {
+            this.log("error", "sync send failed", err);
+        }
+    }
+    async handleFrame(data) {
+        const frame = parseFrame(data);
+        if (!frame)
+            return;
+        try {
+            this.onFrame?.(frame);
+        }
+        catch (err) {
+            this.log("warn", "onFrame handler threw", err);
+        }
+        if (frame.type === "resync") {
+            await this.handleResync();
+            return;
+        }
+        try {
+            this.onChange(frame);
+        }
+        catch (err) {
+            this.log("error", `onChange failed for ${frame.entity} seq=${frame.seq}`, err);
+        }
+    }
+    /**
+     * Cursor underflow: the deltas we need were evicted from the DO's change_log ring. Close the socket
+     * (so no live frame interleaves with the re-seed), re-seed via the injected callback, then reconnect
+     * — which re-sends {type:"sync"} from the fresh cursor. `resyncing` guards against a second resync
+     * frame and suppresses scheduleReconnect for the duration so we reopen exactly once.
+     */
+    async handleResync() {
+        if (this.resyncing)
+            return;
+        this.resyncing = true;
+        this.setStatus("resyncing");
+        this.closeSocket();
+        try {
+            const cursor = await this.reseed();
+            this.log("info", `resynced, cursor=${cursor}`);
+        }
+        catch (err) {
+            this.log("error", "resync reseed failed; will retry on reconnect", err);
+        }
+        finally {
+            this.resyncing = false;
+        }
+        if (!this.stopped)
+            this.openSocket();
+    }
+}
+/** Parse a WS frame (string or ArrayBuffer) into a known server frame, or null for anything malformed. */
+export function parseFrame(data) {
+    const text = typeof data === "string"
+        ? data
+        : data instanceof ArrayBuffer
+            ? new TextDecoder().decode(data)
+            : null;
+    if (text == null)
+        return null;
+    let parsed;
+    try {
+        parsed = JSON.parse(text);
+    }
+    catch {
+        return null;
+    }
+    if (typeof parsed !== "object" || parsed === null)
+        return null;
+    const type = parsed.type;
+    if (type === "resync")
+        return parsed;
+    if (type === "change")
+        return parsed;
+    return null;
+}
+//# sourceMappingURL=live-sync-client.js.map

package/dist/live-sync-client.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"live-sync-client.js","sourceRoot":"","sources":["../src/live-sync-client.ts"],"names":[],"mappings":"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"}

package/dist/types.d.ts

@@ -0,0 +1,57 @@
+/** The tenant id. Also the Mirror DO name. `"tenant-0"` is Ryan's own workspace (Phase 0). */
+export type AccountId = string;
+/**
+ * Canonical mirror table names — the `entity` field in change_log + the change-feed wire.
+ *
+ * Mirrors @catalyst-cloud/types `EntityName` exactly. The runtime list `ENTITY_NAMES` below is the
+ * same set as an array so the contract test can assert membership at runtime (a bare `type` alias
+ * erases to nothing and can't be checked).
+ */
+export type EntityName = "issues" | "labels" | "users" | "issue_labels" | "relations" | "issue_history" | "projects" | "cycles" | "initiatives" | "project_initiatives" | "comments" | "pull_requests" | "check_runs" | "commit_statuses" | "reviews";
+/**
+ * The `EntityName` union as a runtime array, in the SAME ORDER as the type above. Frozen so consumers
+ * (and the contract test) can iterate the canonical table set. Kept in lockstep with `EntityName` —
+ * the contract test asserts the two agree.
+ */
+export declare const ENTITY_NAMES: readonly ["issues", "labels", "users", "issue_labels", "relations", "issue_history", "projects", "cycles", "initiatives", "project_initiatives", "comments", "pull_requests", "check_runs", "commit_statuses", "reviews"];
+/** change_log.op — the change-feed wire contract. */
+export type ChangeOp = "upsert" | "delete";
+/** The `ChangeOp` union as a runtime array (same lockstep contract as `ENTITY_NAMES`). */
+export declare const CHANGE_OPS: readonly ["upsert", "delete"];
+/**
+ * A live change frame off the `/connect` WebSocket — the exact shape `apps/mirror/src/do/ws.ts`
+ * broadcasts and replays. One row of the change_log, serialized.
+ */
+export interface ChangeFrame {
+    type: "change";
+    accountId: AccountId;
+    /** The change_log seq — the monotonic cursor the replica advances to. */
+    seq: number;
+    entity: EntityName;
+    /** The change_log.entity_id — the PK (composite PKs joined with ':'). */
+    entityId: string;
+    op: ChangeOp;
+    /** The full normalized row for "upsert"; absent / partial for "delete". */
+    row?: Record<string, unknown>;
+}
+/**
+ * The underflow control frame: the consumer's cursor predates the DO's retained change_log ring →
+ * the consumer must re-seed from a full /snapshot.
+ */
+export interface ResyncFrame {
+    type: "resync";
+    accountId?: AccountId;
+}
+/**
+ * The catch-up request the consumer sends on every (re)connect: "replay everything after this
+ * cursor, in seq order". The DO answers with the missed `ChangeFrame`s, or a `ResyncFrame` if `after`
+ * predates the retained ring (cursor underflow).
+ */
+export interface SyncFrame {
+    type: "sync";
+    /** The durable cursor: the last change_log.seq the consumer has applied (-1 if none). */
+    after: number;
+}
+/** Any frame the DO can push to a consumer over `/connect`. */
+export type ServerFrame = ChangeFrame | ResyncFrame;
+//# sourceMappingURL=types.d.ts.map

package/dist/types.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"types.d.ts","sourceRoot":"","sources":["../src/types.ts"],"names":[],"mappings":"AAcA,8FAA8F;AAC9F,MAAM,MAAM,SAAS,GAAG,MAAM,CAAC;AAE/B;;;;;;GAMG;AACH,MAAM,MAAM,UAAU,GAClB,QAAQ,GACR,QAAQ,GACR,OAAO,GACP,cAAc,GACd,WAAW,GACX,eAAe,GACf,UAAU,GACV,QAAQ,GACR,aAAa,GACb,qBAAqB,GACrB,UAAU,GACV,eAAe,GACf,YAAY,GACZ,iBAAiB,GACjB,SAAS,CAAC;AAEd;;;;GAIG;AACH,eAAO,MAAM,YAAY,2NAgBiB,CAAC;AAE3C,qDAAqD;AACrD,MAAM,MAAM,QAAQ,GAAG,QAAQ,GAAG,QAAQ,CAAC;AAE3C,0FAA0F;AAC1F,eAAO,MAAM,UAAU,+BAA8D,CAAC;AAEtF;;;GAGG;AACH,MAAM,WAAW,WAAW;IAC1B,IAAI,EAAE,QAAQ,CAAC;IACf,SAAS,EAAE,SAAS,CAAC;IACrB,yEAAyE;IACzE,GAAG,EAAE,MAAM,CAAC;IACZ,MAAM,EAAE,UAAU,CAAC;IACnB,yEAAyE;IACzE,QAAQ,EAAE,MAAM,CAAC;IACjB,EAAE,EAAE,QAAQ,CAAC;IACb,2EAA2E;IAC3E,GAAG,CAAC,EAAE,MAAM,CAAC,MAAM,EAAE,OAAO,CAAC,CAAC;CAC/B;AAED;;;GAGG;AACH,MAAM,WAAW,WAAW;IAC1B,IAAI,EAAE,QAAQ,CAAC;IACf,SAAS,CAAC,EAAE,SAAS,CAAC;CACvB;AAED;;;;GAIG;AACH,MAAM,WAAW,SAAS;IACxB,IAAI,EAAE,MAAM,CAAC;IACb,yFAAyF;IACzF,KAAK,EAAE,MAAM,CAAC;CACf;AAED,+DAA+D;AAC/D,MAAM,MAAM,WAAW,GAAG,WAAW,GAAG,WAAW,CAAC"}

package/dist/types.js

@@ -0,0 +1,38 @@
+// catalyst-cloud-sdk wire types — the change-feed contract, SELF-CONTAINED.
+//
+// This file is a deliberate, byte-for-byte copy of the portable wire contract from the
+// catalyst-cloud monorepo's @catalyst-cloud/types package (packages/types/src/index.ts): the
+// `EntityName` table-name union, the `ChangeOp` op union, and the change/sync/resync frame shapes
+// the Mirror Durable Object broadcasts over `/connect`. The SDK is published standalone, so it must
+// NOT depend on the internal @catalyst-cloud/types workspace package — instead it owns its own copy
+// of the contract, and a contract test (test/contract.test.ts) pins the literal members so any drift
+// from the monorepo is caught.
+//
+// Like @catalyst-cloud/types, this module is Cloudflare-Workers-free and DOM-free: it is pure type
+// declarations + plain JS runtime constants, so it imports cleanly into a browser bundle, a node/bun
+// app, and a Worker alike.
+/**
+ * The `EntityName` union as a runtime array, in the SAME ORDER as the type above. Frozen so consumers
+ * (and the contract test) can iterate the canonical table set. Kept in lockstep with `EntityName` —
+ * the contract test asserts the two agree.
+ */
+export const ENTITY_NAMES = [
+    "issues",
+    "labels",
+    "users",
+    "issue_labels",
+    "relations",
+    "issue_history",
+    "projects",
+    "cycles",
+    "initiatives",
+    "project_initiatives",
+    "comments",
+    "pull_requests",
+    "check_runs",
+    "commit_statuses",
+    "reviews",
+];
+/** The `ChangeOp` union as a runtime array (same lockstep contract as `ENTITY_NAMES`). */
+export const CHANGE_OPS = ["upsert", "delete"];
+//# sourceMappingURL=types.js.map

package/dist/types.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"types.js","sourceRoot":"","sources":["../src/types.ts"],"names":[],"mappings":"AAAA,4EAA4E;AAC5E,EAAE;AACF,uFAAuF;AACvF,6FAA6F;AAC7F,kGAAkG;AAClG,oGAAoG;AACpG,oGAAoG;AACpG,qGAAqG;AACrG,+BAA+B;AAC/B,EAAE;AACF,mGAAmG;AACnG,qGAAqG;AACrG,2BAA2B;AA6B3B;;;;GAIG;AACH,MAAM,CAAC,MAAM,YAAY,GAAG;IAC1B,QAAQ;IACR,QAAQ;IACR,OAAO;IACP,cAAc;IACd,WAAW;IACX,eAAe;IACf,UAAU;IACV,QAAQ;IACR,aAAa;IACb,qBAAqB;IACrB,UAAU;IACV,eAAe;IACf,YAAY;IACZ,iBAAiB;IACjB,SAAS;CAC+B,CAAC;AAK3C,0FAA0F;AAC1F,MAAM,CAAC,MAAM,UAAU,GAAG,CAAC,QAAQ,EAAE,QAAQ,CAAwC,CAAC"}

package/package.json

@@ -0,0 +1,55 @@
+{
+  "name": "@catalyst-cloud/sdk",
+  "version": "0.1.0",
+  "description": "Isomorphic (browser + node/bun) read-layer-over-WebSocket client for the catalyst-cloud change-feed (ADR-0008/0009).",
+  "license": "MIT",
+  "author": "Coalesce Labs",
+  "homepage": "https://github.com/coalesce-labs/catalyst-cloud-sdk#readme",
+  "repository": {
+    "type": "git",
+    "url": "git+https://github.com/coalesce-labs/catalyst-cloud-sdk.git"
+  },
+  "bugs": {
+    "url": "https://github.com/coalesce-labs/catalyst-cloud-sdk/issues"
+  },
+  "publishConfig": {
+    "access": "public"
+  },
+  "type": "module",
+  "main": "./dist/index.js",
+  "module": "./dist/index.js",
+  "types": "./dist/index.d.ts",
+  "exports": {
+    ".": {
+      "types": "./dist/index.d.ts",
+      "import": "./dist/index.js",
+      "default": "./dist/index.js"
+    }
+  },
+  "files": [
+    "dist"
+  ],
+  "sideEffects": false,
+  "engines": {
+    "node": ">=22"
+  },
+  "scripts": {
+    "build": "tsc -p tsconfig.build.json",
+    "typecheck": "tsc --noEmit",
+    "test": "vitest run",
+    "prepublishOnly": "npm run build"
+  },
+  "keywords": [
+    "catalyst",
+    "websocket",
+    "change-feed",
+    "live-sync",
+    "isomorphic",
+    "cloudflare",
+    "durable-objects"
+  ],
+  "devDependencies": {
+    "typescript": "^5.6.3",
+    "vitest": "^2.1.8"
+  }
+}