@colixsystems/datastore-client 0.4.0 → 0.5.0

package/README.md

@@ -1,27 +1,36 @@
 # @colixsystems/datastore-client
 
-Typed, scoped client for the [AppStudio](https://github.com/appstudio) datastore API. Widgets receive an instance through the injected `WidgetContext.datastore` — they never instantiate this client themselves.
+Typed, scoped **data-plane** client for the [AppStudio](https://github.com/appstudio) datastore API. It covers exactly three things:
 
-See the design reference: [`docs/architecture/widget-marketplace.md`](../../docs/architecture/widget-marketplace.md), specifically section 3.2.
+- **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}`.
+
+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 })`.
+
+> **Two surfaces, one package.** This client serves two callers:
+> 1. **External / server-side integrations** instantiate it directly with an API key (`getToken` returns the key, `getTenantId` the tenant) and call the methods below.
+> 2. **The widget runtime** — the Player and exported Expo app instantiate the *same* package and inject it into `WidgetContext.datastore`. Widgets never import this package; they call the SDK hooks from `@colixsystems/widget-sdk` (`useDatastoreQuery`, `useDatastoreMutation`, `useDatastoreSchema`, `useRecordPermissions`, …), which read `ctx.datastore`. Both surfaces speak the identical snake_case REST contract.
 
 ## Status
 
-`v0.4.0` — pre-publish. Not yet published to npm.
+`v0.5.0` — pre-publish. Not yet published to npm.
 
-> **0.4.0 (additive):** added the `records(t).permissions(recordId)` namespace — `list()`, `grant()`, `update(permissionId, patch)`, `revoke(permissionId)` — covering REQ-ACL-06 row-level grants. The client presents the camelCase shape (`userId`, `canRead`, …) and translates to the snake_case wire contract in both directions.
+> **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, … }`).
+> - `records().list()` returns the `{ data, meta }` envelope verbatim (no unwrap). `tables.list()` likewise.
+> - Added `schema(tableId)` as an alias of `tables.get` for the column structure (the host calls `ctx.datastore.schema(t)`).
+> - Added an optional `getRequestHeaders({ namespace, operation })` factory option for attaching per-request headers (e.g. per-widget scope tokens) without the SDK knowing about scope-token issuance.
+> - `record list` now accepts a `sort` param (e.g. `-created_at`).
+> - **Removed** the `users` / `groups` namespaces — they belong in sibling packages.
 
-> **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.
+## Contract: snake_case, no transform
 
-## Differences from `frontend/src/api/client.js`
+The wire format is snake_case in **both** directions and that is the client contract too. The SDK does **no** case mapping:
 
-| Concern | `frontend/src/api/client.js` | `@colixsystems/datastore-client` |
-| --- | --- | --- |
-| Auth header | Reads `useAuthStore` directly | Token injected by host |
-| Tenant header | Pulled from store | Injected by host; widget cannot override |
-| Retries | None | Idempotent GETs retried 3x with exponential backoff |
-| Timeouts | Browser default | 10s default, configurable per call |
-| Error model | Raw axios error | Typed `DatastoreError` hierarchy |
-| Platform | Browser only | Browser **and** React Native (uses `fetch`) |
+- Request bodies are sent **snake_case verbatim** — you pass `{ user_id, can_read }`, not `{ userId, canRead }`.
+- Response objects are returned **snake_case verbatim** — you read `row.created_at`, `row.table_id`, `perm.can_read`.
+- The only camelCase is JS method names (`filterMode`, `groupBy`, `sumField`) and factory option names.
 
 ## Public API
 
@@ -38,34 +47,40 @@ import {
 
 const client = createDatastoreClient({
   baseUrl: "https://api.appstudio.io",
-  getToken: () => "Bearer ...",
+  getToken: () => "Bearer ...",        // "Bearer " prefix added if missing
   getTenantId: () => "tenant_abc",
+  getRequestHeaders: ({ namespace, operation }) => ({ "X-Widget-Scopes": "..." }), // optional
   // fetchImpl defaults to globalThis.fetch
 });
 
-const tables = await client.tables.list();
+// Tables (schema)
+const { data: tables, meta } = await client.tables.list();   // { data, meta } verbatim
+const table = await client.tables.get("Tasks");              // { id, name, columns: [...] }
+const sameTable = await client.schema("Tasks");              // alias of tables.get
 
-// 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 — filter values are `op:value` expressions (eq, neq, lt, gt, gte,
+// lte, contains, empty, nempty). Pagination is limit + offset.
+const { data: orders } = await client
   .records("orders")
-  .list({ filter: { status: "eq:PAID" }, limit: 50, offset: 0 });
+  .list({ filter: { status: "eq:PAID" }, sort: "-created_at", limit: 50, offset: 0 });
+
+const rec = await client.records("orders").get("r1");
+await client.records("orders").create({ status: "PAID", amount_cents: 1200 });
+await client.records("orders").update("r1", { status: "REFUNDED" }); // PATCH
+await client.records("orders").delete("r1");
 
 // Aggregate: group by one column, optionally sum one numeric field.
 const byStatus = await client
   .records("orders")
-  .aggregate({ groupBy: "status", sumField: "total" });
+  .aggregate({ groupBy: "status", sumField: "amount_cents" });
 // → [{ group: "PAID", count: 12, sum: 4200 }, ...]
 
-const me = await client.users.me();        // GET /auth/app/me
-const myGroups = await client.groups.listMine(); // { data, meta }
-
 // Row-level permissions (REQ-ACL-06): a grant to a user OR group with
-// `canRead` is what membership means. Provide exactly one of userId/groupId.
+// can_read is what membership means. Provide exactly one of user_id/group_id.
 const perms = client.records("channels").permissions(channelId);
-const { data: members } = await perms.list();
-const grant = await perms.grant({ userId: "user_123", canRead: true });
-await perms.update(grant.id, { canWrite: true });
+const { data: members } = await perms.list();                // { data, meta } verbatim
+const grant = await perms.grant({ user_id: "user_123", can_read: true });
+await perms.update(grant.id, { can_write: true });
 await perms.revoke(grant.id);
 ```
 
@@ -73,8 +88,9 @@ await perms.revoke(grant.id);
 
 | Method | HTTP | Returns |
 | --- | --- | --- |
-| `tables.list()` | `GET /tables` | `Page<TableMeta>` |
-| `tables.get(idOrName)` | `GET /tables/{id}` | `TableMeta` |
+| `tables.list()` | `GET /tables` | `Page<Table>` |
+| `tables.get(idOrName)` | `GET /tables/{id}` | `Table` (with `columns`) |
+| `schema(tableId)` | `GET /tables/{id}` | `Table` (alias of `tables.get`) |
 | `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` |
@@ -82,13 +98,52 @@ await perms.revoke(grant.id);
 | `records(t).delete(id)` | `DELETE /tables/{t}/records/{id}` | `void` |
 | `records(t).aggregate(spec)` | `GET /tables/{t}/records/aggregate` | `AggregateResult` |
 | `records(t).permissions(r).list()` | `GET /tables/{t}/records/{r}/permissions` | `Page<RecordPermission>` |
-| `records(t).permissions(r).grant(grant)` | `POST /tables/{t}/records/{r}/permissions` | `RecordPermission` |
+| `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` |
-| `users.me()` | `GET /auth/app/me` | `AppUser` |
-| `users.get(id)` | `GET /app/users/{id}` | `AppUser` |
-| `groups.listMine()` | `GET /app/groups/mine` | `Page<Group>` |
+
+### Query params (snake_case on the wire)
+
+| Caller key | Wire param |
+| --- | --- |
+| `limit` | `limit` |
+| `offset` | `offset` |
+| `q` | `q` |
+| `filterMode` | `filter_mode` (`and` \| `or`) |
+| `sort` | `sort` (e.g. `-created_at`) |
+| `filter[col]` | `filter[col]=op:value` (inner key is the author's column name, verbatim) |
+| `groupBy` | `group_by` |
+| `sumField` | `sum_field` |
+
+## Factory options
+
+| Option | Type | Notes |
+| --- | --- | --- |
+| `baseUrl` | `string` | Required. |
+| `getToken` | `() => string \| Promise<string>` | Required. Returns the Authorization value; `Bearer ` prefix added if missing. |
+| `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`. |
+
+## Transport
+
+| Concern | Behaviour |
+| --- | --- |
+| Auth header | From `getToken` (host-injected); `Bearer ` prefix normalised. |
+| Tenant header | `x-tenant-id` from `getTenantId` (host-injected). |
+| Retries | Idempotent GETs retried 3× with exponential backoff (200/400/800 ms). |
+| Timeouts | 10 s default, configurable per call via `timeoutMs`. |
+| Error model | Typed `DatastoreError` hierarchy (`NotFoundError`, `ForbiddenError`, `ValidationError`, `RateLimitedError`, `ServerError`). |
+| Platform | Browser **and** React Native (uses `fetch` + `AbortController`). |
 
 ## Dependencies
 
 None. The client uses only platform `fetch` and `AbortController`, both available in modern browsers, Node 18+, and React Native.
+
+## Tests
+
+```
+node --test src
+```
+
+Fully self-contained — no `npm install`, no cross-package deps.

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";
@@ -13,10 +26,10 @@ function joinUrl(base, path) {
 }
 
 // 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 +41,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 +58,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 +79,19 @@ 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.
  */
 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,6 +103,11 @@ 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(
@@ -125,7 +115,7 @@ export function createDatastoreClient(opts) {
     );
   }
 
-  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 +128,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 {
@@ -177,28 +176,51 @@ export function createDatastoreClient(opts) {
     }
     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-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 +231,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),
   };
 }

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 () => {
-  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 () => {
+test("records.permissions.list returns { data, meta } snake_case verbatim", 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,65 @@ 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;
+  });
+});

package/dist/index.d.ts

@@ -1,27 +1,60 @@
 // Hand-written ambient types for @colixsystems/datastore-client.
 // The package is plain ESM JavaScript; this file is shipped for IDE
 // IntelliSense. Keep in sync with src/index.js when adding exports.
+//
+// CONTRACT: snake_case in BOTH directions. Wire fields are snake_case
+// verbatim (`table_id`, `created_at`, `can_read`, …) and the client does NO
+// case transform. The only camelCase here is JS method names and the factory
+// option names. This is the DATA PLANE only — tables, records, aggregates,
+// and record-level permissions. Users / groups / files / payments live in
+// sibling packages.
+
+// A column on a virtual table (snake_case wire shape).
+export interface Column {
+  id: string;
+  table_id: string;
+  name: string;
+  data_type: string;
+  required?: boolean;
+  target_table_id?: string | null;
+  relation_type?: string | null;
+  is_identification_column?: boolean;
+  encrypted?: boolean;
+  inherit_acl?: boolean;
+  default_value?: unknown;
+  created_at?: string;
+  updated_at?: string;
+  [key: string]: unknown;
+}
 
-export interface TableMeta {
+// The full table schema returned by `tables.get(idOrName)` / `schema(t)`.
+export interface Table {
   id: string;
+  tenant_id?: string;
   name: string;
-  displayName?: string;
-  columns: Array<{
-    name: string;
-    type: string;
-    required?: boolean;
-  }>;
+  grant_creator_permissions?: boolean;
+  allow_anonymous_create?: boolean;
+  html_template?: string | null;
+  columns?: Column[];
+  created_at?: string;
+  updated_at?: string;
+  deleted_at?: string | null;
+  [key: string]: unknown;
 }
 
+// A free-form record. Keys correspond to the table's column `name`s; the
+// host-managed fields are snake_case (`id`, `created_at`, `updated_at`).
 export interface Record_ {
   id: string;
+  created_at?: string;
+  updated_at?: string;
   [key: string]: unknown;
 }
 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.
+// (`{ data, meta }`), returned VERBATIM. `meta.total` is the ACL-aware row
+// count; use it with `limit` / `offset` to page.
 export interface Page<T> {
   data: T[];
   meta: {
@@ -34,93 +67,78 @@ export interface Page<T> {
 // 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`.
+// `me` sentinel for USER / USER_GROUP columns). `filterMode` ANDs conditions
+// by default, or ORs them (sent as `filter_mode`). `q` is a free-text search
+// across the table's string/text columns. `sort` is a column name optionally
+// prefixed with `-` for descending (e.g. `-created_at`). Pagination is
+// `limit` + `offset`.
 export interface Query {
-  filter?: Record<string, string>;
+  filter?: { [column: string]: string };
   filterMode?: "and" | "or";
   q?: string;
+  sort?: string;
   limit?: number;
   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.
+// single numeric field, with the same `filter` map the list accepts. Sent as
+// `group_by` / `sum_field` on the wire.
 export interface AggregateSpec {
   groupBy?: string;
   sumField?: string;
-  filter?: Record<string, string>;
+  filter?: { [column: string]: string };
 }
 
 // Aggregate response: one row per group with the row count and the sum of
-// `sumField` (0 when no `sumField` was requested).
+// `sum_field` (0 when no `sum_field` 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;
-  name: string | null;
-  email?: string | null;
-  role?: string;
-  groupIds?: string[];
-}
-
-export interface Group {
-  id: string;
-  name: string;
-  tenantId?: string;
-  createdAt?: string;
-  updatedAt?: string;
-}
-
-// A single row-level grant on a record (REQ-ACL-06). Exactly one of
-// `userId` / `groupId` is set; the four `can*` flags are the capability
-// bits. `sourceKind` / `sourceId` are non-null only for grants cascaded
-// from a parent record through an inheriting relation — directly-authored
-// grants have both null.
+// A single row-level grant on a record (REQ-ACL-06), snake_case verbatim.
+// Exactly one of `user_id` / `group_id` is set; the four `can_*` flags are
+// the capability bits. `source_kind` / `source_id` are non-null only for
+// grants cascaded from a parent record through an inheriting relation —
+// directly-authored grants have both null.
 export interface RecordPermission {
   id: string;
-  tableId: string;
-  recordId: string | null;
-  userId: string | null;
-  groupId: string | null;
-  canRead: boolean;
-  canWrite: boolean;
-  canDelete: boolean;
-  canGrant: boolean;
-  sourceKind: string | null;
-  sourceId: string | null;
-  createdAt: string;
-  updatedAt: string;
+  table_id: string;
+  record_id: string | null;
+  user_id: string | null;
+  group_id: string | null;
+  can_read: boolean;
+  can_write: boolean;
+  can_delete: boolean;
+  can_grant: boolean;
+  source_kind: string | null;
+  source_id: string | null;
+  created_at: string;
+  updated_at: string;
 }
 
-// Grant body for `permissions(recordId).grant(...)`. Provide exactly ONE of
-// `userId` or `groupId`. Flags default server-side to `canRead: true` and
-// the rest `false` when omitted.
+// Grant body for `permissions(recordId).grant(...)`, sent snake_case
+// verbatim. Provide exactly ONE of `user_id` or `group_id`. Flags default
+// server-side to `can_read: true` and the rest `false` when omitted.
 export interface RecordPermissionGrant {
-  userId?: string | null;
-  groupId?: string | null;
-  canRead?: boolean;
-  canWrite?: boolean;
-  canDelete?: boolean;
-  canGrant?: boolean;
+  user_id?: string | null;
+  group_id?: string | null;
+  can_read?: boolean;
+  can_write?: boolean;
+  can_delete?: boolean;
+  can_grant?: boolean;
 }
 
-// Flag patch for `permissions(recordId).update(...)`. Only the four
-// capability bits are mutable; the grantee is fixed at grant time. Omitted
-// flags are left unchanged.
+// Flag patch for `permissions(recordId).update(...)`, sent snake_case
+// verbatim. Only the four capability bits are mutable; the grantee is fixed
+// at grant time. Omitted flags are left unchanged.
 export interface RecordPermissionPatch {
-  canRead?: boolean;
-  canWrite?: boolean;
-  canDelete?: boolean;
-  canGrant?: boolean;
+  can_read?: boolean;
+  can_write?: boolean;
+  can_delete?: boolean;
+  can_grant?: boolean;
 }
 
 export interface RecordPermissionsNamespace {
@@ -145,23 +163,27 @@ export interface RecordsNamespace {
 
 export interface DatastoreClient {
   tables: {
-    list(): Promise<TableMeta[]>;
-    get(idOrName: string): Promise<TableMeta>;
+    list(): Promise<Page<Table>>;
+    get(idOrName: string): Promise<Table>;
   };
+  // Alias of tables.get for the table's column structure (the host calls
+  // ctx.datastore.schema(t)).
+  schema(tableId: string): Promise<Table>;
   records(table: string): RecordsNamespace;
-  users: {
-    me(): Promise<AppUser>;
-    get(id: string): Promise<AppUser>;
-  };
-  groups: {
-    listMine(): Promise<Group[]>;
-  };
+}
+
+export interface RequestHeadersContext {
+  namespace: string;
+  operation: string;
 }
 
 export interface CreateDatastoreClientOptions {
   baseUrl: string;
   getToken: () => string | Promise<string>;
   getTenantId: () => string | Promise<string>;
+  getRequestHeaders?: (
+    ctx: RequestHeadersContext,
+  ) => Record<string, string> | Promise<Record<string, string>>;
   fetchImpl?: typeof fetch;
 }
 

package/package.json

@@ -1,7 +1,7 @@
 {
   "name": "@colixsystems/datastore-client",
-  "version": "0.4.0",
-  "description": "Typed, scoped client for the AppStudio datastore API. Used by widgets through the injected WidgetContext.",
+  "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.",
   "type": "module",
   "main": "./dist/index.js",
   "module": "./dist/index.js",