@colixsystems/datastore-client 0.4.0 → 0.6.0

package/dist/client.test.js

@@ -1,17 +1,18 @@
 // Wire-contract tests for createDatastoreClient. A capturing fetch
-// implementation records the method + URL each namespace method emits so
-// we lock the client to the backend's real REST surface (REQ-OPS-DOC-EXT
-// reconciliation). These run under `node --test`.
+// implementation records the method + URL + body each namespace method emits
+// so we lock the client to the backend's real snake_case REST surface
+// (REQ-GEN-09). These run under `node --test` with NO npm install.
 
 import { test } from "node:test";
 import assert from "node:assert/strict";
 import { createDatastoreClient } from "./client.js";
 
-function makeClient(captured, responseBody = { data: [], meta: {} }) {
+function makeClient(captured, responseBody = { data: [], meta: {} }, extra = {}) {
   const fetchImpl = async (url, init) => {
     captured.url = url;
     captured.method = init.method;
     captured.body = init.body;
+    captured.headers = init.headers;
     return {
       ok: true,
       status: 200,
@@ -23,10 +24,63 @@ function makeClient(captured, responseBody = { data: [], meta: {} }) {
     getToken: () => "Bearer as_testkey",
     getTenantId: () => "tenant-1",
     fetchImpl,
+    ...extra,
   });
 }
 
-test("records.list serialises limit/offset/q/filter_mode/filter[col]", async () => {
+test("factory validates opts", () => {
+  assert.throws(() => createDatastoreClient(), TypeError);
+  assert.throws(
+    () => createDatastoreClient({ getToken: () => "", getTenantId: () => "" }),
+    TypeError,
+  );
+  assert.throws(
+    () => createDatastoreClient({ baseUrl: "x", getTenantId: () => "" }),
+    TypeError,
+  );
+  assert.throws(
+    () => createDatastoreClient({ baseUrl: "x", getToken: () => "" }),
+    TypeError,
+  );
+  assert.throws(
+    () =>
+      createDatastoreClient({
+        baseUrl: "x",
+        getToken: () => "",
+        getTenantId: () => "",
+        getRequestHeaders: "nope",
+      }),
+    TypeError,
+  );
+});
+
+test("tables.list / tables.get paths return the envelope/schema verbatim", async () => {
+  const cap = {};
+  const client = makeClient(cap, { data: [{ id: "t1", name: "Tasks" }], meta: { total: 1, limit: 50, offset: 0 } });
+  const list = await client.tables.list();
+  assert.equal(cap.method, "GET");
+  assert.equal(new URL(cap.url).pathname, "/api/v1/tables");
+  assert.deepEqual(list, { data: [{ id: "t1", name: "Tasks" }], meta: { total: 1, limit: 50, offset: 0 } });
+
+  const tableSchema = { id: "t1", name: "Tasks", columns: [{ id: "c1", table_id: "t1", name: "title", data_type: "STRING" }] };
+  const cap2 = {};
+  const client2 = makeClient(cap2, tableSchema);
+  const got = await client2.tables.get("Tasks");
+  assert.equal(new URL(cap2.url).pathname, "/api/v1/tables/Tasks");
+  assert.deepEqual(got, tableSchema);
+});
+
+test("schema(t) is an alias of tables.get", async () => {
+  const cap = {};
+  const tableSchema = { id: "t1", name: "Tasks", columns: [] };
+  const client = makeClient(cap, tableSchema);
+  const got = await client.schema("t1");
+  assert.equal(cap.method, "GET");
+  assert.equal(new URL(cap.url).pathname, "/api/v1/tables/t1");
+  assert.deepEqual(got, tableSchema);
+});
+
+test("records.list serialises limit/offset/q/filter_mode/sort/filter[col]", async () => {
   const cap = {};
   const client = makeClient(cap);
   await client.records("Tasks").list({
@@ -34,6 +88,7 @@ test("records.list serialises limit/offset/q/filter_mode/filter[col]", async ()
     offset: 50,
     q: "urgent",
     filterMode: "or",
+    sort: "-created_at",
     filter: { status: "eq:Open", priority: "gte:3" },
   });
   assert.equal(cap.method, "GET");
@@ -43,17 +98,26 @@ test("records.list serialises limit/offset/q/filter_mode/filter[col]", async ()
   assert.equal(u.searchParams.get("offset"), "50");
   assert.equal(u.searchParams.get("q"), "urgent");
   assert.equal(u.searchParams.get("filter_mode"), "or");
+  assert.equal(u.searchParams.get("sort"), "-created_at");
   assert.equal(u.searchParams.get("filter[status]"), "eq:Open");
   assert.equal(u.searchParams.get("filter[priority]"), "gte:3");
-  // The legacy `cursor` / JSON `filter=` forms must be gone.
-  assert.equal(u.searchParams.get("cursor"), null);
-  assert.equal(u.searchParams.get("filter"), null);
+});
+
+test("records.list returns the { data, meta } envelope verbatim (no unwrap)", async () => {
+  const cap = {};
+  const body = {
+    data: [{ id: "r1", title: "x", created_at: "2026-01-01T00:00:00Z" }],
+    meta: { total: 1, limit: 50, offset: 0 },
+  };
+  const client = makeClient(cap, body);
+  const res = await client.records("Tasks").list();
+  assert.deepEqual(res, body);
 });
 
 test("records.aggregate is a GET on /records/aggregate with group_by/sum_field", async () => {
   const cap = {};
   const client = makeClient(cap, []);
-  await client.records("Sales").aggregate({
+  const res = await client.records("Sales").aggregate({
     groupBy: "region",
     sumField: "amount",
     filter: { status: "eq:Closed" },
@@ -65,9 +129,10 @@ test("records.aggregate is a GET on /records/aggregate with group_by/sum_field",
   assert.equal(u.searchParams.get("group_by"), "region");
   assert.equal(u.searchParams.get("sum_field"), "amount");
   assert.equal(u.searchParams.get("filter[status]"), "eq:Closed");
+  assert.deepEqual(res, []);
 });
 
-test("record CRUD verbs + paths", async () => {
+test("record CRUD verbs + paths; create/update send the body verbatim", async () => {
   const cap = {};
   const client = makeClient(cap, { id: "r1" });
   const ns = client.records("Tasks");
@@ -76,53 +141,24 @@ test("record CRUD verbs + paths", async () => {
   assert.equal(cap.method, "GET");
   assert.equal(new URL(cap.url).pathname, "/api/v1/tables/Tasks/records/r1");
 
-  await ns.create({ title: "x" });
+  await ns.create({ title: "x", due_date: "2026-01-01" });
   assert.equal(cap.method, "POST");
   assert.equal(new URL(cap.url).pathname, "/api/v1/tables/Tasks/records");
+  assert.deepEqual(JSON.parse(cap.body), { title: "x", due_date: "2026-01-01" });
 
   await ns.update("r1", { title: "y" });
   assert.equal(cap.method, "PATCH");
   assert.equal(new URL(cap.url).pathname, "/api/v1/tables/Tasks/records/r1");
+  assert.deepEqual(JSON.parse(cap.body), { title: "y" });
 
   await ns.delete("r1");
   assert.equal(cap.method, "DELETE");
   assert.equal(new URL(cap.url).pathname, "/api/v1/tables/Tasks/records/r1");
 });
 
-test("users.me targets /auth/app/me (not /app/users/me)", async () => {
-  const cap = {};
-  const client = makeClient(cap, { id: "u1", name: "A", email: "a@b.c" });
-  await client.users.me();
-  assert.equal(cap.method, "GET");
-  assert.equal(new URL(cap.url).pathname, "/api/v1/auth/app/me");
-});
-
-test("users.get targets /app/users/{id}", async () => {
+test("records.permissions.list returns { data, meta } snake_case verbatim", async () => {
   const cap = {};
-  const client = makeClient(cap, { id: "u9", name: "B" });
-  await client.users.get("u9");
-  assert.equal(new URL(cap.url).pathname, "/api/v1/app/users/u9");
-});
-
-test("groups.listMine targets /app/groups/mine", async () => {
-  const cap = {};
-  const client = makeClient(cap);
-  await client.groups.listMine();
-  assert.equal(new URL(cap.url).pathname, "/api/v1/app/groups/mine");
-});
-
-test("tables.list / tables.get paths", async () => {
-  const cap = {};
-  const client = makeClient(cap);
-  await client.tables.list();
-  assert.equal(new URL(cap.url).pathname, "/api/v1/tables");
-  await client.tables.get("Tasks");
-  assert.equal(new URL(cap.url).pathname, "/api/v1/tables/Tasks");
-});
-
-test("records.permissions.list maps {data,meta} rows to camelCase", async () => {
-  const cap = {};
-  const client = makeClient(cap, {
+  const body = {
     data: [
       {
         id: "p1",
@@ -141,54 +177,61 @@ test("records.permissions.list maps {data,meta} rows to camelCase", async () =>
       },
     ],
     meta: { total: 1, limit: 1, offset: 0 },
-  });
+  };
+  const client = makeClient(cap, body);
   const res = await client.records("Channels").permissions("c1").list();
   assert.equal(cap.method, "GET");
   assert.equal(
     new URL(cap.url).pathname,
     "/api/v1/tables/Channels/records/c1/permissions",
   );
-  assert.deepEqual(res.meta, { total: 1, limit: 1, offset: 0 });
-  assert.equal(res.data[0].tableId, "Channels");
-  assert.equal(res.data[0].userId, "u1");
-  assert.equal(res.data[0].canRead, true);
-  assert.equal(res.data[0].canWrite, false);
+  // No transform — the row is returned snake_case verbatim.
+  assert.deepEqual(res, body);
 });
 
-test("records.permissions.grant POSTs a snake_case body", async () => {
+test("records.permissions.grant POSTs the snake_case body verbatim and returns the row verbatim", async () => {
   const cap = {};
-  const client = makeClient(cap, {
+  const row = {
     id: "p2",
     table_id: "Channels",
     record_id: "c1",
     user_id: "u2",
+    group_id: null,
     can_read: true,
     can_write: true,
-  });
-  const row = await client
+    can_delete: false,
+    can_grant: false,
+    source_kind: null,
+    source_id: null,
+    created_at: "2026-01-01T00:00:00Z",
+    updated_at: "2026-01-01T00:00:00Z",
+  };
+  const client = makeClient(cap, row);
+  const out = await client
     .records("Channels")
     .permissions("c1")
-    .grant({ userId: "u2", canRead: true, canWrite: true });
+    .grant({ user_id: "u2", can_read: true, can_write: true });
   assert.equal(cap.method, "POST");
   assert.equal(
     new URL(cap.url).pathname,
     "/api/v1/tables/Channels/records/c1/permissions",
   );
-  const sent = JSON.parse(cap.body);
-  assert.deepEqual(sent, { user_id: "u2", can_read: true, can_write: true });
-  // Response is mapped back to camelCase.
-  assert.equal(row.id, "p2");
-  assert.equal(row.userId, "u2");
-  assert.equal(row.canWrite, true);
+  // Body is forwarded verbatim — no camel->snake mapping.
+  assert.deepEqual(JSON.parse(cap.body), {
+    user_id: "u2",
+    can_read: true,
+    can_write: true,
+  });
+  assert.deepEqual(out, row);
 });
 
-test("records.permissions.update PUTs flags by permissionId", async () => {
+test("records.permissions.update PUTs flags by permissionId, verbatim", async () => {
   const cap = {};
   const client = makeClient(cap, { id: "p2", can_delete: true });
   await client
     .records("Channels")
     .permissions("c1")
-    .update("p2", { canDelete: true });
+    .update("p2", { can_delete: true });
   assert.equal(cap.method, "PUT");
   assert.equal(
     new URL(cap.url).pathname,
@@ -213,3 +256,195 @@ test("records.permissions requires a non-empty recordId", () => {
   const client = makeClient(cap);
   assert.throws(() => client.records("Channels").permissions(""), TypeError);
 });
+
+test("records(table) requires a non-empty table", () => {
+  const cap = {};
+  const client = makeClient(cap);
+  assert.throws(() => client.records(""), TypeError);
+});
+
+test("request sends auth + tenant headers; adds Bearer prefix when missing", async () => {
+  const cap = {};
+  const client = makeClient(cap, { data: [], meta: {} }, {
+    getToken: () => "as_rawkey",
+  });
+  await client.tables.list();
+  assert.equal(cap.headers.authorization, "Bearer as_rawkey");
+  assert.equal(cap.headers["x-tenant-id"], "tenant-1");
+  assert.equal(cap.headers.accept, "application/json");
+});
+
+test("getRequestHeaders is invoked per request with {namespace, operation} and merged", async () => {
+  const cap = {};
+  const seen = [];
+  const client = makeClient(cap, { data: [], meta: {} }, {
+    getRequestHeaders: ({ namespace, operation }) => {
+      seen.push(`${namespace}:${operation}`);
+      return { "X-Widget-Scopes": "records:read" };
+    },
+  });
+  await client.records("Tasks").list();
+  assert.equal(cap.headers["X-Widget-Scopes"], "records:read");
+  assert.deepEqual(seen, ["records:list"]);
+
+  await client.records("Tasks").permissions("r1").grant({ user_id: "u1" });
+  assert.deepEqual(seen, ["records:list", "permissions:grant"]);
+});
+
+test("data-plane only: no users/groups/files/payments namespaces", () => {
+  const cap = {};
+  const client = makeClient(cap);
+  assert.equal(client.users, undefined);
+  assert.equal(client.groups, undefined);
+  assert.equal(client.files, undefined);
+  assert.equal(client.payments, undefined);
+});
+
+test("non-OK responses throw a typed error", async () => {
+  const fetchImpl = async () => ({
+    ok: false,
+    status: 404,
+    text: async () => JSON.stringify({ error: { message: "nope" } }),
+  });
+  const client = createDatastoreClient({
+    baseUrl: "https://api.example.com/api/v1",
+    getToken: () => "Bearer x",
+    getTenantId: () => "t1",
+    fetchImpl,
+  });
+  await assert.rejects(() => client.records("Tasks").get("r1"), (err) => {
+    assert.equal(err.status, 404);
+    assert.equal(err.code, "NOT_FOUND");
+    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();
+});