@colixsystems/datastore-client 0.4.0 → 0.6.0

package/dist/client.js

@@ -1,7 +1,20 @@
-// Datastore client factory.
-// The host injects baseUrl, a token provider, a tenant-id provider, and an
-// optional fetch implementation. Widgets never touch this directly — they
-// receive a built client through WidgetContext.datastore.
+// Datastore client factory (DATA PLANE only).
+//
+// This package is the typed data-plane client: tables (schema), records
+// (CRUD + query + aggregate), and record-level permissions (RLS). It does
+// NOT carry users, groups, files, or payments — those live in sibling
+// packages. The host injects baseUrl, a token provider, a tenant-id
+// provider, an optional per-request header provider (used to attach
+// per-widget scope tokens without this SDK knowing about /widgets/
+// scope-token), and an optional fetch implementation.
+//
+// CRITICAL — snake_case, NO transform. The wire format is snake_case in
+// BOTH directions (REQ-GEN-09) and that is the client contract too. Request
+// bodies are sent snake_case VERBATIM (e.g. { user_id, can_read }). Response
+// objects are returned snake_case VERBATIM (e.g. { id, created_at,
+// table_id }). There is no case-mapping helper anywhere in this package.
+// List endpoints return the { data, meta } envelope verbatim — list methods
+// do not unwrap or remap.
 
 import { errorFromResponse, DatastoreError } from "./errors.js";
 import { withRetry } from "./retry.js";
@@ -12,11 +25,40 @@ 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 snake_case query normalisation); the `op:value` expression is URL-
-// encoded. Used by both the record list and the aggregate query.
+// (`filter[col]=op:value`). The column names are author-authored and pass
+// through verbatim (the backend exempts the `filter` subtree from its
+// snake_case query normalisation); the `op:value` expression is URL-encoded.
+// Used by both the record list and the aggregate query.
 function appendFilter(parts, filter) {
   if (!filter || typeof filter !== "object") return;
   for (const [col, expr] of Object.entries(filter)) {
@@ -28,8 +70,11 @@ function appendFilter(parts, filter) {
 }
 
 // Record-list query string. Mirrors the backend contract
-// (`GET /tables/:id/records`): `limit` + `offset` pagination, free-text
-// `q`, `filter_mode` (and|or), and `filter[col]=op:value` conditions.
+// (`GET /tables/:id/records`): `limit` + `offset` pagination, free-text `q`,
+// `filter_mode` (and|or), `sort` (e.g. `-created_at`), and
+// `filter[col]=op:value` conditions. Query keys are snake_case on the wire;
+// the caller passes `filterMode` (a JS method-name convenience) which maps to
+// `filter_mode`.
 function buildQueryString(query) {
   if (!query || typeof query !== "object") return "";
   const parts = [];
@@ -42,13 +87,17 @@ function buildQueryString(query) {
   if (query.filterMode === "or" || query.filterMode === "and") {
     parts.push(`filter_mode=${query.filterMode}`);
   }
+  if (query.sort != null && query.sort !== "")
+    parts.push(`sort=${encodeURIComponent(query.sort)}`);
   appendFilter(parts, query.filter);
   return parts.length ? `?${parts.join("&")}` : "";
 }
 
 // Aggregate query string. Mirrors the backend contract
-// (`GET /tables/:id/records/aggregate`): a single `group_by` column, a
-// single `sum_field`, and optional `filter[col]=op:value` conditions.
+// (`GET /tables/:id/records/aggregate`): a single `group_by` column, a single
+// `sum_field`, and optional `filter[col]=op:value` conditions. The caller
+// passes `groupBy` / `sumField` (JS-name convenience) which map to the
+// snake_case wire params.
 function buildAggregateQueryString(spec) {
   if (!spec || typeof spec !== "object") return "";
   const parts = [];
@@ -59,54 +108,20 @@ function buildAggregateQueryString(spec) {
   return parts.length ? `?${parts.join("&")}` : "";
 }
 
-// Record-permission grants (REQ-ACL-06) cross the wire in the project's
-// snake_case contract; this client presents the same camelCase face every
-// other namespace uses (`filterMode`, `groupBy`, `AppUser.groupIds`, …).
-// The field set is small and fixed, so an explicit map stays clearer than a
-// generic deep transform — which this package intentionally avoids.
-function serializePermissionBody(input) {
-  if (!input || typeof input !== "object") return {};
-  const out = {};
-  if (input.userId !== undefined) out.user_id = input.userId;
-  if (input.groupId !== undefined) out.group_id = input.groupId;
-  if (input.canRead !== undefined) out.can_read = input.canRead;
-  if (input.canWrite !== undefined) out.can_write = input.canWrite;
-  if (input.canDelete !== undefined) out.can_delete = input.canDelete;
-  if (input.canGrant !== undefined) out.can_grant = input.canGrant;
-  return out;
-}
-
-function deserializePermission(row) {
-  if (!row || typeof row !== "object") return row;
-  return {
-    id: row.id,
-    tableId: row.table_id,
-    recordId: row.record_id ?? null,
-    userId: row.user_id ?? null,
-    groupId: row.group_id ?? null,
-    canRead: !!row.can_read,
-    canWrite: !!row.can_write,
-    canDelete: !!row.can_delete,
-    canGrant: !!row.can_grant,
-    sourceKind: row.source_kind ?? null,
-    sourceId: row.source_id ?? null,
-    createdAt: row.created_at,
-    updatedAt: row.updated_at,
-  };
-}
-
 /**
  * @param {object} opts
  * @param {string} opts.baseUrl
- * @param {() => string | Promise<string>} opts.getToken  Returns the Authorization header value (e.g. "Bearer <jwt>").
+ * @param {() => string | Promise<string>} opts.getToken  Returns the Authorization header value (e.g. "Bearer <jwt>"); the "Bearer " prefix is added if missing.
  * @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") {
     throw new TypeError("createDatastoreClient: opts is required");
   }
-  const { baseUrl, getToken, getTenantId } = opts;
+  const { baseUrl, getToken, getTenantId, getRequestHeaders } = opts;
   if (typeof baseUrl !== "string" || baseUrl.length === 0) {
     throw new TypeError("createDatastoreClient: baseUrl is required");
   }
@@ -118,14 +133,27 @@ export function createDatastoreClient(opts) {
       "createDatastoreClient: getTenantId must be a function",
     );
   }
+  if (getRequestHeaders !== undefined && typeof getRequestHeaders !== "function") {
+    throw new TypeError(
+      "createDatastoreClient: getRequestHeaders must be a function when provided",
+    );
+  }
   const fetchImpl = opts.fetchImpl ?? globalThis.fetch;
   if (typeof fetchImpl !== "function") {
     throw new TypeError(
       "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 } = {}) {
+  async function request(method, path, { body, timeoutMs, namespace, operation } = {}) {
     const url = joinUrl(baseUrl, path);
     const token = await getToken();
     const tenantId = await getTenantId();
@@ -138,6 +166,15 @@ export function createDatastoreClient(opts) {
     if (tenantId) headers["x-tenant-id"] = tenantId;
     if (body !== undefined) headers["content-type"] = "application/json";
 
+    if (getRequestHeaders) {
+      const extra = await getRequestHeaders({ namespace, operation });
+      if (extra && typeof extra === "object") {
+        for (const [k, v] of Object.entries(extra)) {
+          if (v !== undefined && v !== null) headers[k] = v;
+        }
+      }
+    }
+
     return withRetry({ method, timeoutMs }, async (signal) => {
       let res;
       try {
@@ -171,34 +208,267 @@ 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");
     }
     const enc = encodeURIComponent(table);
     return {
+      // GET /tables/{t}/records — returns the { data, meta } envelope verbatim.
       list: (query) =>
-        request("GET", `/tables/${enc}/records${buildQueryString(query)}`),
+        request("GET", `/tables/${enc}/records${buildQueryString(query)}`, {
+          namespace: "records",
+          operation: "list",
+        }),
+      // GET /tables/{t}/records/{id}
       get: (id) =>
-        request("GET", `/tables/${enc}/records/${encodeURIComponent(id)}`),
+        request("GET", `/tables/${enc}/records/${encodeURIComponent(id)}`, {
+          namespace: "records",
+          operation: "get",
+        }),
+      // POST /tables/{t}/records — values sent snake_case verbatim.
       create: (values) =>
-        request("POST", `/tables/${enc}/records`, { body: values }),
+        request("POST", `/tables/${enc}/records`, {
+          body: values,
+          namespace: "records",
+          operation: "create",
+        }),
+      // PATCH /tables/{t}/records/{id} — partial update (PATCH, not PUT).
       update: (id, values) =>
         request("PATCH", `/tables/${enc}/records/${encodeURIComponent(id)}`, {
           body: values,
+          namespace: "records",
+          operation: "update",
         }),
+      // DELETE /tables/{t}/records/{id}
       delete: (id) =>
-        request("DELETE", `/tables/${enc}/records/${encodeURIComponent(id)}`),
+        request("DELETE", `/tables/${enc}/records/${encodeURIComponent(id)}`, {
+          namespace: "records",
+          operation: "delete",
+        }),
+      // GET /tables/{t}/records/aggregate — returns [{ group, count, sum }].
       aggregate: (spec) =>
         request(
           "GET",
           `/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 `canRead` is what membership means — see the
-      // Chat widget's channel model. Mirrors the backend routes:
+      // 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
+      // rows are returned snake_case verbatim. Mirrors the backend routes:
       //   GET    …/permissions               list grants ({ data, meta })
-      //   POST   …/permissions               grant one (provide userId XOR groupId)
+      //   POST   …/permissions               grant one (provide user_id XOR group_id)
       //   PUT    …/permissions/{permissionId} update one grant's flags
       //   DELETE …/permissions/{permissionId} revoke one grant
       permissions: (recordId) => {
@@ -209,48 +479,49 @@ export function createDatastoreClient(opts) {
         }
         const base = `/tables/${enc}/records/${encodeURIComponent(recordId)}/permissions`;
         return {
-          list: async () => {
-            const res = await request("GET", base);
-            const rows = Array.isArray(res?.data) ? res.data : [];
-            return { data: rows.map(deserializePermission), meta: res?.meta };
-          },
-          grant: async (grant) =>
-            deserializePermission(
-              await request("POST", base, {
-                body: serializePermissionBody(grant),
-              }),
-            ),
-          update: async (permissionId, patch) =>
-            deserializePermission(
-              await request(
-                "PUT",
-                `${base}/${encodeURIComponent(permissionId)}`,
-                { body: serializePermissionBody(patch) },
-              ),
-            ),
+          list: () =>
+            request("GET", base, {
+              namespace: "permissions",
+              operation: "list",
+            }),
+          grant: (body) =>
+            request("POST", base, {
+              body,
+              namespace: "permissions",
+              operation: "grant",
+            }),
+          update: (permissionId, patch) =>
+            request("PUT", `${base}/${encodeURIComponent(permissionId)}`, {
+              body: patch,
+              namespace: "permissions",
+              operation: "update",
+            }),
           revoke: (permissionId) =>
-            request("DELETE", `${base}/${encodeURIComponent(permissionId)}`),
+            request("DELETE", `${base}/${encodeURIComponent(permissionId)}`, {
+              namespace: "permissions",
+              operation: "revoke",
+            }),
         };
       },
     };
   }
 
+  const tables = {
+    // GET /tables — returns the { data, meta } envelope verbatim.
+    list: () => request("GET", `/tables`, { namespace: "tables", operation: "list" }),
+    // GET /tables/{id} — full table schema { id, name, columns, ... }.
+    get: (idOrName) =>
+      request("GET", `/tables/${encodeURIComponent(idOrName)}`, {
+        namespace: "tables",
+        operation: "get",
+      }),
+  };
+
   return {
-    tables: {
-      list: () => request("GET", `/tables`),
-      get: (idOrName) =>
-        request("GET", `/tables/${encodeURIComponent(idOrName)}`),
-    },
+    tables,
     records: recordsNs,
-    users: {
-      // The current principal. For an app-user JWT this is the logged-in
-      // user; for an INTEGRATION API key it is the bound service account.
-      me: () => request("GET", `/auth/app/me`),
-      get: (id) => request("GET", `/app/users/${encodeURIComponent(id)}`),
-    },
-    groups: {
-      // The groups the calling principal belongs to.
-      listMine: () => request("GET", `/app/groups/mine`),
-    },
+    // schema(tableId) is an alias of tables.get for the table's column
+    // structure — the host calls ctx.datastore.schema(t).
+    schema: (tableId) => tables.get(tableId),
   };
 }