@colixsystems/datastore-client 0.5.0 → 0.6.0

package/README.md

@@ -5,6 +5,7 @@ Typed, scoped **data-plane** client for the [AppStudio](https://github.com/appst
 - **tables** — table schema (id, name, columns) via `tables.{list,get}` and the `schema(tableId)` alias.
 - **records** — record CRUD, querying, and aggregation via `records(tableId).{list,get,create,update,delete,aggregate}`.
 - **record-level permissions** — RLS grants on a single record (REQ-ACL-06) via `records(tableId).permissions(recordId).{list,grant,update,revoke}`.
+- **realtime** — subscribe to a table's live change stream (REQ-RT-07) via `records(tableId).subscribe({ onCreated, onUpdated, onDeleted, onStatus })`, returning an unsubscribe function.
 
 It does **not** cover users, groups, files, or payments — those live in sibling packages ([`files-client`](../files-client), [`directory-client`](../directory-client), [`payments-client`](../payments-client)). This is a standalone `fetch`-based client you instantiate yourself with `createDatastoreClient({ baseUrl, getToken, getTenantId })`.
 
@@ -14,7 +15,9 @@ It does **not** cover users, groups, files, or payments — those live in siblin
 
 ## Status
 
-`v0.5.0` — pre-publish. Not yet published to npm.
+`v0.6.0` — pre-publish. Not yet published to npm.
+
+> **0.6.0 (additive):** added `records(tableId).subscribe({ onCreated, onUpdated, onDeleted, onStatus }, { fallbackAfterMs? })` (REQ-RT-07) — a WebSocket subscription to the table's realtime change stream at `<baseUrl>/datastore/ws`, returning a synchronous unsubscribe function. Server-gated by the same read ACL as REST. New optional `webSocketImpl` factory option (defaults to `globalThis.WebSocket`, present in browsers and React Native); when no impl is available `onStatus` reports `"fallback"` so callers poll. No existing method changed.
 
 > **0.5.0 (breaking):** the client is now **snake_case end to end with NO transform** (REQ-GEN-09) and is scoped to the **data plane only**.
 > - The old camelCase↔snake_case permission mappers are **deleted**. Permission bodies are sent snake_case verbatim (`{ user_id, can_read, … }`) and rows are returned snake_case verbatim (`{ id, table_id, can_read, … }`).
@@ -101,6 +104,7 @@ await perms.revoke(grant.id);
 | `records(t).permissions(r).grant(body)` | `POST /tables/{t}/records/{r}/permissions` | `RecordPermission` |
 | `records(t).permissions(r).update(pid, patch)` | `PUT /tables/{t}/records/{r}/permissions/{pid}` | `RecordPermission` |
 | `records(t).permissions(r).revoke(pid)` | `DELETE /tables/{t}/records/{r}/permissions/{pid}` | `void` |
+| `records(t).subscribe(handlers, opts?)` | `WS <baseUrl>/datastore/ws` (`{type:"subscribe",tableId}`) | `() => void` (unsubscribe) |
 
 ### Query params (snake_case on the wire)
 
@@ -124,6 +128,7 @@ await perms.revoke(grant.id);
 | `getTenantId` | `() => string \| Promise<string>` | Required. Returns the `x-tenant-id` value. |
 | `getRequestHeaders` | `({ namespace, operation }) => object \| Promise<object>` | Optional. Extra headers merged per request (e.g. scope tokens). `namespace` is one of `tables` / `records` / `permissions`. |
 | `fetchImpl` | `typeof fetch` | Optional. Defaults to `globalThis.fetch`. |
+| `webSocketImpl` | `typeof WebSocket` | Optional. Used by `records(t).subscribe(...)`. Defaults to `globalThis.WebSocket` (browser + React Native). When absent, `subscribe` reports `"fallback"` and opens no socket. |
 
 ## Transport
 

package/dist/client.js

@@ -25,6 +25,35 @@ function joinUrl(base, path) {
   return `${b}${p}`;
 }
 
+// REQ-RT-07: derive the realtime WebSocket URL from the REST baseUrl. The
+// datastore broadcast plane lives at `<api-base>/datastore/ws` (the same
+// `/api/v1` mount, so we append `/datastore/ws` to the base path). The
+// baseUrl may be absolute ("https://host/api/v1", the native export) or a
+// same-origin relative path ("/api/v1", the web build) — the latter is
+// resolved against the page origin via globalThis.location. Returns null
+// when no usable URL can be formed (a relative base with no page origin,
+// e.g. SSR), so the caller can degrade to its polling fallback instead of
+// throwing. Pure string parsing (no `new URL`) so it works identically in
+// the browser and under React Native, whose URL support is incomplete.
+// http→ws, https→wss.
+function wsUrlFromBase(baseUrl) {
+  let base = baseUrl;
+  if (base.startsWith("/")) {
+    const origin =
+      typeof globalThis !== "undefined" &&
+      globalThis.location &&
+      globalThis.location.origin;
+    if (!origin) return null;
+    base = origin + base;
+  }
+  const m = base.match(/^(https?):\/\/([^/]+)(\/.*)?$/i);
+  if (!m) return null;
+  const wsProto = m[1].toLowerCase() === "https" ? "wss" : "ws";
+  const host = m[2];
+  const path = (m[3] || "").replace(/\/$/, "");
+  return `${wsProto}://${host}${path}/datastore/ws`;
+}
+
 // Serialise a column-filter map into the backend's bracket form
 // (`filter[col]=op:value`). The column names are author-authored and pass
 // through verbatim (the backend exempts the `filter` subtree from its
@@ -86,6 +115,7 @@ function buildAggregateQueryString(spec) {
  * @param {() => string | Promise<string>} opts.getTenantId Returns the x-tenant-id header value.
  * @param {(ctx: { namespace: string, operation: string }) => object | Promise<object>} [opts.getRequestHeaders] Optional per-request extra headers (e.g. { 'X-Widget-Scopes': '...' }).
  * @param {typeof fetch} [opts.fetchImpl] Defaults to globalThis.fetch.
+ * @param {typeof WebSocket} [opts.webSocketImpl] WebSocket constructor for records(t).subscribe(). Defaults to globalThis.WebSocket (present in browsers AND React Native). When absent, subscribe() reports "fallback" so callers poll.
  */
 export function createDatastoreClient(opts) {
   if (!opts || typeof opts !== "object") {
@@ -114,6 +144,14 @@ export function createDatastoreClient(opts) {
       "createDatastoreClient: no fetch available. Pass fetchImpl or run in an environment with global fetch.",
     );
   }
+  // REQ-RT-07: WebSocket impl for records(t).subscribe(). Defaults to the
+  // platform global (browser AND React Native both provide `WebSocket`), so
+  // the same client streams realtime on web and in the Expo export with no
+  // host change. Overridable for tests / unusual runtimes. When absent,
+  // subscribe() degrades to an immediate "fallback" status (callers poll).
+  const WebSocketImpl =
+    opts.webSocketImpl ??
+    (typeof globalThis !== "undefined" ? globalThis.WebSocket : undefined);
 
   async function request(method, path, { body, timeoutMs, namespace, operation } = {}) {
     const url = joinUrl(baseUrl, path);
@@ -170,6 +208,204 @@ export function createDatastoreClient(opts) {
     });
   }
 
+  // REQ-RT-07: realtime subscription lifecycle for records(t).subscribe().
+  // One implementation shared by web and the native export (both pass the
+  // platform-global WebSocket). connect() resolves the token + tenant per
+  // attempt — so a refreshed token rides the next reconnect — opens the
+  // socket, sends { type: "subscribe", tableId }, and dispatches record.*
+  // envelopes to the handlers. Backoff is capped exponential; a "fallback"
+  // status fires if the first subscribe doesn't land within fallbackAfterMs
+  // or the socket drops, so the caller can switch to REST polling.
+  function subscribeRecords(table, handlers, options) {
+    const h = handlers && typeof handlers === "object" ? handlers : {};
+    const fallbackAfterMs =
+      options && Number.isFinite(options.fallbackAfterMs)
+        ? options.fallbackAfterMs
+        : 3000;
+
+    let socket = null;
+    let stopped = false;
+    let attempt = 0;
+    let reconnectTimer = null;
+    let fallbackTimer = null;
+    let didEmitFallback = false;
+    let status = "connecting";
+
+    const emitStatus = (next) => {
+      if (status === next) return;
+      status = next;
+      if (typeof h.onStatus === "function") {
+        try {
+          h.onStatus(next);
+        } catch {
+          /* ignore subscriber error */
+        }
+      }
+    };
+    const fire = (fn, record) => {
+      if (typeof fn === "function") {
+        try {
+          fn(record);
+        } catch {
+          /* ignore subscriber error */
+        }
+      }
+    };
+    const clearFallback = () => {
+      if (fallbackTimer) {
+        clearTimeout(fallbackTimer);
+        fallbackTimer = null;
+      }
+    };
+    const scheduleFallback = () => {
+      if (didEmitFallback) return;
+      clearFallback();
+      fallbackTimer = setTimeout(() => {
+        if (stopped) return;
+        didEmitFallback = true;
+        emitStatus("fallback");
+      }, fallbackAfterMs);
+    };
+    const scheduleReconnect = () => {
+      if (stopped) return;
+      if (reconnectTimer) clearTimeout(reconnectTimer);
+      const delay = Math.min(1000 * 2 ** attempt, 16000);
+      attempt += 1;
+      emitStatus(didEmitFallback ? "fallback" : "reconnecting");
+      reconnectTimer = setTimeout(() => {
+        void connect();
+      }, delay);
+    };
+
+    async function connect() {
+      if (stopped) return;
+      if (typeof WebSocketImpl !== "function") {
+        didEmitFallback = true;
+        emitStatus("fallback");
+        return;
+      }
+      const wsBase = wsUrlFromBase(baseUrl);
+      if (!wsBase) {
+        didEmitFallback = true;
+        emitStatus("fallback");
+        return;
+      }
+
+      let token = "";
+      let tenantId = "";
+      try {
+        token = (await getToken()) || "";
+        tenantId = (await getTenantId()) || "";
+      } catch {
+        /* anonymous attempt — leave empty */
+      }
+      if (stopped) return;
+
+      const params = new URLSearchParams();
+      const rawToken = token.startsWith("Bearer ") ? token.slice(7) : token;
+      // Server reads the token for claims; an anonymous subscribe needs the
+      // tenantId for routing. Token path wins, mirroring the REST headers.
+      if (rawToken) params.set("token", rawToken);
+      else if (tenantId) params.set("tenantId", tenantId);
+      const qs = params.toString();
+      const url = qs ? `${wsBase}?${qs}` : wsBase;
+
+      let ws;
+      try {
+        ws = new WebSocketImpl(url);
+      } catch {
+        scheduleReconnect();
+        scheduleFallback();
+        return;
+      }
+      socket = ws;
+      scheduleFallback();
+      emitStatus(status === "live" ? "reconnecting" : "connecting");
+
+      const send = (obj) => {
+        try {
+          ws.send(JSON.stringify(obj));
+        } catch {
+          /* socket closing — the down handler will reconnect */
+        }
+      };
+
+      // `on*` property assignment (not addEventListener) for the widest
+      // cross-platform support — both the browser and React Native guarantee
+      // these handler properties on WebSocket.
+      ws.onopen = () => send({ type: "subscribe", tableId: table });
+      ws.onmessage = (ev) => {
+        let env;
+        try {
+          env = JSON.parse(ev.data);
+        } catch {
+          return;
+        }
+        if (!env || typeof env !== "object") return;
+        switch (env.type) {
+          case "ping":
+            send({ type: "pong" });
+            return;
+          case "subscribed":
+            attempt = 0;
+            clearFallback();
+            didEmitFallback = false;
+            emitStatus("live");
+            return;
+          case "record.created":
+            fire(h.onCreated, env.record);
+            return;
+          case "record.updated":
+            fire(h.onUpdated, env.record);
+            return;
+          case "record.deleted":
+            fire(h.onDeleted, env.record);
+            return;
+          case "error":
+            // FORBIDDEN / NOT_FOUND on subscribe → reconnecting won't help.
+            if (env.code === "FORBIDDEN" || env.code === "NOT_FOUND") {
+              didEmitFallback = true;
+              emitStatus("fallback");
+              try {
+                ws.close(4000, "subscribe-rejected");
+              } catch {
+                /* ignore */
+              }
+            }
+            return;
+          default:
+            return;
+        }
+      };
+      const onDown = () => {
+        if (socket === ws) socket = null;
+        if (stopped) return;
+        scheduleReconnect();
+      };
+      ws.onclose = onDown;
+      ws.onerror = onDown;
+    }
+
+    void connect();
+
+    return function unsubscribe() {
+      stopped = true;
+      if (reconnectTimer) {
+        clearTimeout(reconnectTimer);
+        reconnectTimer = null;
+      }
+      clearFallback();
+      if (socket) {
+        try {
+          socket.close(1000, "unsubscribe");
+        } catch {
+          /* ignore */
+        }
+        socket = null;
+      }
+    };
+  }
+
   function recordsNs(table) {
     if (typeof table !== "string" || table.length === 0) {
       throw new TypeError("records(table): table must be a non-empty string");
@@ -215,6 +451,18 @@ export function createDatastoreClient(opts) {
           `/tables/${enc}/records/aggregate${buildAggregateQueryString(spec)}`,
           { namespace: "records", operation: "aggregate" },
         ),
+      // REQ-RT-07: subscribe to this table's realtime change stream over the
+      // `/datastore/ws` broadcast plane. Returns a synchronous unsubscribe
+      // function. `handlers`: { onCreated, onUpdated, onDeleted, onStatus }.
+      // `onStatus(state)` reports the transport: "connecting" | "live" |
+      // "reconnecting" | "fallback". The server gates each subscribe by the
+      // same read ACL REST honours; on a FORBIDDEN/NOT_FOUND reject (or when
+      // no WebSocket impl is available) the helper emits "fallback" so the
+      // caller can poll instead. record envelopes carry the snake_case row
+      // verbatim, exactly like the REST responses. Reconnect uses capped
+      // exponential backoff; a ping/pong heartbeat keeps the socket alive.
+      subscribe: (handlers, options) =>
+        subscribeRecords(table, handlers, options),
       // REQ-ACL-06: row-level permission grants on a single record. A grant
       // to a user OR group with `can_read` is what membership means — see the
       // Chat widget's channel model. Bodies are sent snake_case verbatim and

package/dist/client.test.js

@@ -318,3 +318,133 @@ test("non-OK responses throw a typed error", async () => {
     return true;
   });
 });
+
+// ---------------------------------------------------------------------------
+// REQ-RT-07 — records(t).subscribe() realtime transport.
+// ---------------------------------------------------------------------------
+
+// Minimal WebSocket double: records the URL, exposes the on* handlers the
+// client assigns, and lets the test drive open/message events + inspect sends.
+class MockWS {
+  constructor(url) {
+    this.url = url;
+    this.sent = [];
+    this.closed = false;
+    MockWS.last = this;
+  }
+  send(data) {
+    this.sent.push(JSON.parse(data));
+  }
+  close() {
+    this.closed = true;
+    if (this.onclose) this.onclose();
+  }
+  emitOpen() {
+    if (this.onopen) this.onopen();
+  }
+  emitMessage(obj) {
+    if (this.onmessage) this.onmessage({ data: JSON.stringify(obj) });
+  }
+}
+
+// connect() awaits getToken + getTenantId, so the socket is created on a
+// later microtask/timer turn — flush with a macrotask tick.
+const tick = () => new Promise((r) => setTimeout(r, 0));
+
+function subClient(extra = {}) {
+  return createDatastoreClient({
+    baseUrl: "https://api.example.com/api/v1",
+    getToken: () => "Bearer as_testkey",
+    getTenantId: () => "tenant-1",
+    fetchImpl: async () => ({ ok: true, status: 200, text: async () => "{}" }),
+    webSocketImpl: MockWS,
+    ...extra,
+  });
+}
+
+test("subscribe: derives wss URL, sends subscribe on open, dispatches record.* + ping", async () => {
+  MockWS.last = null;
+  const events = [];
+  const statuses = [];
+  const stop = subClient().records("t1").subscribe({
+    onCreated: (r) => events.push(["created", r]),
+    onUpdated: (r) => events.push(["updated", r]),
+    onDeleted: (r) => events.push(["deleted", r]),
+    onStatus: (s) => statuses.push(s),
+  });
+  await tick();
+
+  const ws = MockWS.last;
+  assert.ok(ws, "socket constructed");
+  // wss (from https), the /api/v1 mount + /datastore/ws, raw token (Bearer stripped).
+  assert.match(ws.url, /^wss:\/\/api\.example\.com\/api\/v1\/datastore\/ws\?/);
+  assert.match(ws.url, /token=as_testkey/);
+  assert.ok(!ws.url.includes("Bearer"), "Bearer prefix stripped from query token");
+
+  ws.emitOpen();
+  assert.deepEqual(ws.sent[0], { type: "subscribe", tableId: "t1" });
+
+  ws.emitMessage({ type: "subscribed" });
+  assert.ok(statuses.includes("live"), "subscribed → live");
+
+  ws.emitMessage({ type: "record.created", record: { id: "r1" } });
+  ws.emitMessage({ type: "record.updated", record: { id: "r1", x: 2 } });
+  ws.emitMessage({ type: "record.deleted", record: { id: "r1" } });
+  assert.deepEqual(events, [
+    ["created", { id: "r1" }],
+    ["updated", { id: "r1", x: 2 }],
+    ["deleted", { id: "r1" }],
+  ]);
+
+  ws.emitMessage({ type: "ping" });
+  assert.deepEqual(ws.sent[ws.sent.length - 1], { type: "pong" });
+
+  stop();
+  assert.equal(ws.closed, true, "unsubscribe closes the socket");
+});
+
+test("subscribe: anonymous (no token) routes via tenantId query", async () => {
+  MockWS.last = null;
+  const stop = subClient({ getToken: () => "" })
+    .records("t1")
+    .subscribe({ onStatus: () => {} });
+  await tick();
+  assert.match(MockWS.last.url, /tenantId=tenant-1/);
+  assert.ok(!MockWS.last.url.includes("token="), "no token param when anonymous");
+  stop();
+});
+
+test("subscribe: FORBIDDEN reject → fallback + socket closed", async () => {
+  MockWS.last = null;
+  const statuses = [];
+  const stop = subClient()
+    .records("t1")
+    .subscribe({ onStatus: (s) => statuses.push(s) });
+  await tick();
+  MockWS.last.emitMessage({ type: "error", code: "FORBIDDEN" });
+  assert.ok(statuses.includes("fallback"), "ACL reject → fallback");
+  assert.equal(MockWS.last.closed, true);
+  stop();
+});
+
+test("subscribe: emits fallback when the first subscribe never lands", async () => {
+  MockWS.last = null;
+  const statuses = [];
+  const stop = subClient()
+    .records("t1")
+    .subscribe({ onStatus: (s) => statuses.push(s) }, { fallbackAfterMs: 5 });
+  await new Promise((r) => setTimeout(r, 30)); // never emit "subscribed"
+  assert.ok(statuses.includes("fallback"), "timeout → fallback");
+  stop();
+});
+
+test("subscribe: no WebSocket impl → immediate fallback", async () => {
+  const statuses = [];
+  // A non-function impl trips the same guard as a missing global.
+  const stop = subClient({ webSocketImpl: 0 })
+    .records("t1")
+    .subscribe({ onStatus: (s) => statuses.push(s) });
+  await tick();
+  assert.deepEqual(statuses, ["fallback"]);
+  stop();
+});

package/dist/index.d.ts

@@ -151,6 +151,29 @@ export interface RecordPermissionsNamespace {
   revoke(permissionId: string): Promise<void>;
 }
 
+// REQ-RT-07 realtime subscription transport state, reported via
+// `subscribe({ onStatus })`. "live" = socket open + subscribe acked;
+// "fallback" = the caller should poll (no WebSocket impl, subscribe rejected
+// by ACL, or the first connect timed out).
+export type SubscriptionStatus =
+  | "connecting"
+  | "live"
+  | "reconnecting"
+  | "fallback";
+
+export interface SubscriptionHandlers {
+  onCreated?: (record: Record_) => void;
+  onUpdated?: (record: Record_) => void;
+  onDeleted?: (record: Record_) => void;
+  onStatus?: (status: SubscriptionStatus) => void;
+}
+
+export interface SubscriptionOptions {
+  // Emit "fallback" if the first subscribe doesn't land within this many ms
+  // (default 3000) so the caller can start polling without waiting forever.
+  fallbackAfterMs?: number;
+}
+
 export interface RecordsNamespace {
   list(query?: Query): Promise<Page<Record_>>;
   get(id: string): Promise<Record_>;
@@ -159,6 +182,12 @@ export interface RecordsNamespace {
   delete(id: string): Promise<void>;
   aggregate(spec: AggregateSpec): Promise<AggregateResult>;
   permissions(recordId: string): RecordPermissionsNamespace;
+  // REQ-RT-07: subscribe to this table's realtime change stream. Returns a
+  // synchronous unsubscribe function.
+  subscribe(
+    handlers: SubscriptionHandlers,
+    options?: SubscriptionOptions,
+  ): () => void;
 }
 
 export interface DatastoreClient {
@@ -185,6 +214,10 @@ export interface CreateDatastoreClientOptions {
     ctx: RequestHeadersContext,
   ) => Record<string, string> | Promise<Record<string, string>>;
   fetchImpl?: typeof fetch;
+  // REQ-RT-07: WebSocket constructor for records(t).subscribe(). Defaults to
+  // globalThis.WebSocket (browser + React Native). Omit in environments
+  // without one — subscribe() then reports "fallback".
+  webSocketImpl?: typeof WebSocket;
 }
 
 export function createDatastoreClient(

package/package.json

@@ -1,7 +1,7 @@
 {
   "name": "@colixsystems/datastore-client",
-  "version": "0.5.0",
-  "description": "Typed, scoped data-plane client for the AppStudio datastore API (tables, records, aggregates, record-level permissions). snake_case wire contract, no transform.",
+  "version": "0.6.0",
+  "description": "Typed, scoped data-plane client for the AppStudio datastore API (tables, records, aggregates, record-level permissions, realtime subscribe). snake_case wire contract, no transform.",
   "type": "module",
   "main": "./dist/index.js",
   "module": "./dist/index.js",