@colixsystems/datastore-client 0.2.0 → 0.3.0

package/README.md

@@ -6,7 +6,9 @@ See the design reference: [`docs/architecture/widget-marketplace.md`](../../docs
 
 ## Status
 
-`v0.2.0` — pre-publish. Not yet published to npm.
+`v0.3.0` — pre-publish. Not yet published to npm.
+
+> **0.3.0 (breaking):** the client now matches the AppStudio backend's real REST contract. `records().list()` takes `{ limit, offset, q, filterMode, filter }` (the old `cursor` / JSON `filter` and `sort` are gone) and returns the `{ data, meta }` envelope. `records().aggregate({ groupBy, sumField, filter })` is a `GET` returning `[{ group, count, sum }]`. `users.me()` resolves the current principal via `/auth/app/me`. Filter values are `op:value` expressions.
 
 ## Differences from `frontend/src/api/client.js`
 
@@ -40,9 +42,39 @@ const client = createDatastoreClient({
 });
 
 const tables = await client.tables.list();
-const orders = await client.records("orders").list({ filter: { status: "PAID" } });
+
+// Filter values are `op:value` expressions (eq, neq, lt, gt, gte, lte,
+// contains, empty, nempty). Pagination is limit + offset.
+const { data: orders, meta } = await client
+  .records("orders")
+  .list({ filter: { status: "eq:PAID" }, limit: 50, offset: 0 });
+
+// Aggregate: group by one column, optionally sum one numeric field.
+const byStatus = await client
+  .records("orders")
+  .aggregate({ groupBy: "status", sumField: "total" });
+// → [{ group: "PAID", count: 12, sum: 4200 }, ...]
+
+const me = await client.users.me();        // GET /auth/app/me
+const myGroups = await client.groups.listMine(); // { data, meta }
 ```
 
+## Surface
+
+| Method | HTTP | Returns |
+| --- | --- | --- |
+| `tables.list()` | `GET /tables` | `Page<TableMeta>` |
+| `tables.get(idOrName)` | `GET /tables/{id}` | `TableMeta` |
+| `records(t).list(query?)` | `GET /tables/{t}/records` | `Page<Record>` |
+| `records(t).get(id)` | `GET /tables/{t}/records/{id}` | `Record` |
+| `records(t).create(values)` | `POST /tables/{t}/records` | `Record` |
+| `records(t).update(id, values)` | `PATCH /tables/{t}/records/{id}` | `Record` |
+| `records(t).delete(id)` | `DELETE /tables/{t}/records/{id}` | `void` |
+| `records(t).aggregate(spec)` | `GET /tables/{t}/records/aggregate` | `AggregateResult` |
+| `users.me()` | `GET /auth/app/me` | `AppUser` |
+| `users.get(id)` | `GET /app/users/{id}` | `AppUser` |
+| `groups.listMine()` | `GET /app/groups/mine` | `Page<Group>` |
+
 ## Dependencies
 
 None. The client uses only platform `fetch` and `AbortController`, both available in modern browsers, Node 18+, and React Native.

package/dist/client.js

@@ -12,20 +12,50 @@ function joinUrl(base, path) {
   return `${b}${p}`;
 }
 
+// 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.
+function appendFilter(parts, filter) {
+  if (!filter || typeof filter !== "object") return;
+  for (const [col, expr] of Object.entries(filter)) {
+    if (expr == null) continue;
+    parts.push(
+      `filter[${encodeURIComponent(col)}]=${encodeURIComponent(expr)}`,
+    );
+  }
+}
+
+// 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.
 function buildQueryString(query) {
   if (!query || typeof query !== "object") return "";
   const parts = [];
-  if (query.limit != null) parts.push(`limit=${encodeURIComponent(query.limit)}`);
-  if (query.cursor) parts.push(`cursor=${encodeURIComponent(query.cursor)}`);
-  if (query.sort && Array.isArray(query.sort)) {
-    const sortStr = query.sort
-      .map((s) => `${s.dir === "desc" ? "-" : ""}${s.field}`)
-      .join(",");
-    if (sortStr) parts.push(`sort=${encodeURIComponent(sortStr)}`);
-  }
-  if (query.filter && typeof query.filter === "object") {
-    parts.push(`filter=${encodeURIComponent(JSON.stringify(query.filter))}`);
+  if (query.limit != null)
+    parts.push(`limit=${encodeURIComponent(query.limit)}`);
+  if (query.offset != null)
+    parts.push(`offset=${encodeURIComponent(query.offset)}`);
+  if (query.q != null && query.q !== "")
+    parts.push(`q=${encodeURIComponent(query.q)}`);
+  if (query.filterMode === "or" || query.filterMode === "and") {
+    parts.push(`filter_mode=${query.filterMode}`);
   }
+  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.
+function buildAggregateQueryString(spec) {
+  if (!spec || typeof spec !== "object") return "";
+  const parts = [];
+  if (spec.groupBy) parts.push(`group_by=${encodeURIComponent(spec.groupBy)}`);
+  if (spec.sumField)
+    parts.push(`sum_field=${encodeURIComponent(spec.sumField)}`);
+  appendFilter(parts, spec.filter);
   return parts.length ? `?${parts.join("&")}` : "";
 }
 
@@ -48,12 +78,14 @@ export function createDatastoreClient(opts) {
     throw new TypeError("createDatastoreClient: getToken must be a function");
   }
   if (typeof getTenantId !== "function") {
-    throw new TypeError("createDatastoreClient: getTenantId must be a function");
+    throw new TypeError(
+      "createDatastoreClient: getTenantId must be a function",
+    );
   }
   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."
+      "createDatastoreClient: no fetch available. Pass fetchImpl or run in an environment with global fetch.",
     );
   }
 
@@ -63,7 +95,10 @@ export function createDatastoreClient(opts) {
     const tenantId = await getTenantId();
 
     const headers = { accept: "application/json" };
-    if (token) headers.authorization = token.startsWith("Bearer ") ? token : `Bearer ${token}`;
+    if (token)
+      headers.authorization = token.startsWith("Bearer ")
+        ? token
+        : `Bearer ${token}`;
     if (tenantId) headers["x-tenant-id"] = tenantId;
     if (body !== undefined) headers["content-type"] = "application/json";
 
@@ -106,27 +141,41 @@ export function createDatastoreClient(opts) {
     }
     const enc = encodeURIComponent(table);
     return {
-      list: (query) => request("GET", `/tables/${enc}/records${buildQueryString(query)}`),
-      get: (id) => request("GET", `/tables/${enc}/records/${encodeURIComponent(id)}`),
-      create: (values) => request("POST", `/tables/${enc}/records`, { body: values }),
+      list: (query) =>
+        request("GET", `/tables/${enc}/records${buildQueryString(query)}`),
+      get: (id) =>
+        request("GET", `/tables/${enc}/records/${encodeURIComponent(id)}`),
+      create: (values) =>
+        request("POST", `/tables/${enc}/records`, { body: values }),
       update: (id, values) =>
-        request("PATCH", `/tables/${enc}/records/${encodeURIComponent(id)}`, { body: values }),
-      delete: (id) => request("DELETE", `/tables/${enc}/records/${encodeURIComponent(id)}`),
-      aggregate: (spec) => request("POST", `/tables/${enc}/aggregate`, { body: spec }),
+        request("PATCH", `/tables/${enc}/records/${encodeURIComponent(id)}`, {
+          body: values,
+        }),
+      delete: (id) =>
+        request("DELETE", `/tables/${enc}/records/${encodeURIComponent(id)}`),
+      aggregate: (spec) =>
+        request(
+          "GET",
+          `/tables/${enc}/records/aggregate${buildAggregateQueryString(spec)}`,
+        ),
     };
   }
 
   return {
     tables: {
       list: () => request("GET", `/tables`),
-      get: (idOrName) => request("GET", `/tables/${encodeURIComponent(idOrName)}`),
+      get: (idOrName) =>
+        request("GET", `/tables/${encodeURIComponent(idOrName)}`),
     },
     records: recordsNs,
     users: {
-      me: () => request("GET", `/app/users/me`),
+      // 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`),
     },
   };

package/dist/client.test.js

@@ -0,0 +1,121 @@
+// 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`.
+
+import { test } from "node:test";
+import assert from "node:assert/strict";
+import { createDatastoreClient } from "./client.js";
+
+function makeClient(captured, responseBody = { data: [], meta: {} }) {
+  const fetchImpl = async (url, init) => {
+    captured.url = url;
+    captured.method = init.method;
+    captured.body = init.body;
+    return {
+      ok: true,
+      status: 200,
+      text: async () => JSON.stringify(responseBody),
+    };
+  };
+  return createDatastoreClient({
+    baseUrl: "https://api.example.com/api/v1",
+    getToken: () => "Bearer as_testkey",
+    getTenantId: () => "tenant-1",
+    fetchImpl,
+  });
+}
+
+test("records.list serialises limit/offset/q/filter_mode/filter[col]", async () => {
+  const cap = {};
+  const client = makeClient(cap);
+  await client.records("Tasks").list({
+    limit: 25,
+    offset: 50,
+    q: "urgent",
+    filterMode: "or",
+    filter: { status: "eq:Open", priority: "gte:3" },
+  });
+  assert.equal(cap.method, "GET");
+  const u = new URL(cap.url);
+  assert.equal(u.pathname, "/api/v1/tables/Tasks/records");
+  assert.equal(u.searchParams.get("limit"), "25");
+  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("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.aggregate is a GET on /records/aggregate with group_by/sum_field", async () => {
+  const cap = {};
+  const client = makeClient(cap, []);
+  await client.records("Sales").aggregate({
+    groupBy: "region",
+    sumField: "amount",
+    filter: { status: "eq:Closed" },
+  });
+  assert.equal(cap.method, "GET");
+  assert.equal(cap.body, undefined);
+  const u = new URL(cap.url);
+  assert.equal(u.pathname, "/api/v1/tables/Sales/records/aggregate");
+  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");
+});
+
+test("record CRUD verbs + paths", async () => {
+  const cap = {};
+  const client = makeClient(cap, { id: "r1" });
+  const ns = client.records("Tasks");
+
+  await ns.get("r1");
+  assert.equal(cap.method, "GET");
+  assert.equal(new URL(cap.url).pathname, "/api/v1/tables/Tasks/records/r1");
+
+  await ns.create({ title: "x" });
+  assert.equal(cap.method, "POST");
+  assert.equal(new URL(cap.url).pathname, "/api/v1/tables/Tasks/records");
+
+  await ns.update("r1", { title: "y" });
+  assert.equal(cap.method, "PATCH");
+  assert.equal(new URL(cap.url).pathname, "/api/v1/tables/Tasks/records/r1");
+
+  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 () => {
+  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");
+});

package/dist/index.d.ts

@@ -19,43 +19,65 @@ export interface Record_ {
 }
 export { Record_ as Record };
 
+// The uniform list envelope every collection endpoint returns
+// (`{ data, meta }`). `meta.total` is the ACL-aware row count; use it
+// with `limit`/`offset` to page.
 export interface Page<T> {
   data: T[];
-  nextCursor?: string | null;
+  meta: {
+    total: number;
+    limit: number;
+    offset: number;
+  };
 }
 
+// Record-list query. A `filter` maps a column name to an `op:value`
+// expression — e.g. `{ status: "eq:Open", priority: "gte:3" }`. Supported
+// operators: eq, neq, lt, gt, gte, lte, contains, empty, nempty (and the
+// `me` sentinel for USER columns). `filterMode` ANDs conditions by
+// default, or ORs them. `q` is a free-text search across the table's
+// string/text columns. Pagination is `limit` + `offset`.
 export interface Query {
-  filter?: Record<string, unknown>;
-  sort?: Array<{ field: string; dir: "asc" | "desc" }>;
+  filter?: Record<string, string>;
+  filterMode?: "and" | "or";
+  q?: string;
   limit?: number;
-  cursor?: string;
+  offset?: number;
 }
 
+// Aggregate request: group rows by a single column and (optionally) sum a
+// single numeric field, with the same `filter` map the list accepts.
 export interface AggregateSpec {
-  groupBy?: string[];
-  metrics: Array<{
-    field?: string;
-    op: "count" | "sum" | "avg" | "min" | "max";
-    alias?: string;
-  }>;
-  filter?: Record<string, unknown>;
+  groupBy?: string;
+  sumField?: string;
+  filter?: Record<string, string>;
 }
 
-export interface AggregateResult {
-  rows: Array<Record<string, unknown>>;
-}
+// Aggregate response: one row per group with the row count and the sum of
+// `sumField` (0 when no `sumField` was requested).
+export type AggregateResult = Array<{
+  group: string;
+  count: number;
+  sum: number;
+}>;
 
+// The principal returned by `users.me()` (`GET /auth/app/me`). `email` is
+// present for the logged-in user; the directory projection from
+// `users.get(id)` returns `{ id, name, role }` for non-Studio callers.
 export interface AppUser {
   id: string;
-  email: string | null;
-  displayName: string | null;
-  roles: string[];
-  groupIds: string[];
+  name: string | null;
+  email?: string | null;
+  role?: string;
+  groupIds?: string[];
 }
 
 export interface Group {
   id: string;
   name: string;
+  tenantId?: string;
+  createdAt?: string;
+  updatedAt?: string;
 }
 
 export interface RecordsNamespace {
@@ -90,7 +112,7 @@ export interface CreateDatastoreClientOptions {
 }
 
 export function createDatastoreClient(
-  opts: CreateDatastoreClientOptions
+  opts: CreateDatastoreClientOptions,
 ): DatastoreClient;
 
 export class DatastoreError extends Error {
@@ -99,7 +121,7 @@ export class DatastoreError extends Error {
   details: unknown;
   constructor(
     message: string,
-    init?: { code?: string; status?: number; details?: unknown }
+    init?: { code?: string; status?: number; details?: unknown },
   );
 }
 export class NotFoundError extends DatastoreError {}
@@ -108,9 +130,12 @@ export class ValidationError extends DatastoreError {}
 export class RateLimitedError extends DatastoreError {}
 export class ServerError extends DatastoreError {}
 
-export function errorFromResponse(status: number, body: unknown): DatastoreError;
+export function errorFromResponse(
+  status: number,
+  body: unknown,
+): DatastoreError;
 
 export function withRetry<T>(
   opts: { method: string; timeoutMs?: number },
-  attempt: (signal: AbortSignal) => Promise<T>
+  attempt: (signal: AbortSignal) => Promise<T>,
 ): Promise<T>;

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@colixsystems/datastore-client",
-  "version": "0.2.0",
+  "version": "0.3.0",
   "description": "Typed, scoped client for the AppStudio datastore API. Used by widgets through the injected WidgetContext.",
   "type": "module",
   "main": "./dist/index.js",