@colixsystems/datastore-client 0.2.0 → 0.4.0

package/README.md

@@ -6,7 +6,11 @@ See the design reference: [`docs/architecture/widget-marketplace.md`](../../docs
 
 ## Status
 
-`v0.2.0` — pre-publish. Not yet published to npm.
+`v0.4.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.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 +44,51 @@ 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 }
+
+// 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.
+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 });
+await perms.revoke(grant.id);
 ```
 
+## 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` |
+| `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).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>` |
+
 ## 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,23 +12,89 @@ 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("&")}` : "";
 }
 
+// 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
@@ -48,12 +114,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 +131,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 +177,79 @@ 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)}`,
+        ),
+      // 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:
+      //   GET    …/permissions               list grants ({ data, meta })
+      //   POST   …/permissions               grant one (provide userId XOR groupId)
+      //   PUT    …/permissions/{permissionId} update one grant's flags
+      //   DELETE …/permissions/{permissionId} revoke one grant
+      permissions: (recordId) => {
+        if (typeof recordId !== "string" || recordId.length === 0) {
+          throw new TypeError(
+            "records(table).permissions(recordId): recordId must be a non-empty string",
+          );
+        }
+        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) },
+              ),
+            ),
+          revoke: (permissionId) =>
+            request("DELETE", `${base}/${encodeURIComponent(permissionId)}`),
+        };
+      },
     };
   }
 
   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,215 @@
+// 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");
+});
+
+test("records.permissions.list maps {data,meta} rows to camelCase", async () => {
+  const cap = {};
+  const client = makeClient(cap, {
+    data: [
+      {
+        id: "p1",
+        table_id: "Channels",
+        record_id: "c1",
+        user_id: "u1",
+        group_id: null,
+        can_read: true,
+        can_write: false,
+        can_delete: false,
+        can_grant: false,
+        source_kind: null,
+        source_id: null,
+        created_at: "2026-01-01T00:00:00Z",
+        updated_at: "2026-01-02T00:00:00Z",
+      },
+    ],
+    meta: { total: 1, limit: 1, offset: 0 },
+  });
+  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);
+});
+
+test("records.permissions.grant POSTs a snake_case body", async () => {
+  const cap = {};
+  const client = makeClient(cap, {
+    id: "p2",
+    table_id: "Channels",
+    record_id: "c1",
+    user_id: "u2",
+    can_read: true,
+    can_write: true,
+  });
+  const row = await client
+    .records("Channels")
+    .permissions("c1")
+    .grant({ userId: "u2", canRead: true, canWrite: 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);
+});
+
+test("records.permissions.update PUTs flags by permissionId", async () => {
+  const cap = {};
+  const client = makeClient(cap, { id: "p2", can_delete: true });
+  await client
+    .records("Channels")
+    .permissions("c1")
+    .update("p2", { canDelete: true });
+  assert.equal(cap.method, "PUT");
+  assert.equal(
+    new URL(cap.url).pathname,
+    "/api/v1/tables/Channels/records/c1/permissions/p2",
+  );
+  assert.deepEqual(JSON.parse(cap.body), { can_delete: true });
+});
+
+test("records.permissions.revoke DELETEs by permissionId", async () => {
+  const cap = {};
+  const client = makeClient(cap, {});
+  await client.records("Channels").permissions("c1").revoke("p2");
+  assert.equal(cap.method, "DELETE");
+  assert.equal(
+    new URL(cap.url).pathname,
+    "/api/v1/tables/Channels/records/c1/permissions/p2",
+  );
+});
+
+test("records.permissions requires a non-empty recordId", () => {
+  const cap = {};
+  const client = makeClient(cap);
+  assert.throws(() => client.records("Channels").permissions(""), TypeError);
+});

package/dist/index.d.ts

@@ -19,43 +19,118 @@ 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;
+}
+
+// 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.
+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;
+}
+
+// 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.
+export interface RecordPermissionGrant {
+  userId?: string | null;
+  groupId?: string | null;
+  canRead?: boolean;
+  canWrite?: boolean;
+  canDelete?: boolean;
+  canGrant?: 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.
+export interface RecordPermissionPatch {
+  canRead?: boolean;
+  canWrite?: boolean;
+  canDelete?: boolean;
+  canGrant?: boolean;
+}
+
+export interface RecordPermissionsNamespace {
+  list(): Promise<Page<RecordPermission>>;
+  grant(grant: RecordPermissionGrant): Promise<RecordPermission>;
+  update(
+    permissionId: string,
+    patch: RecordPermissionPatch,
+  ): Promise<RecordPermission>;
+  revoke(permissionId: string): Promise<void>;
 }
 
 export interface RecordsNamespace {
@@ -65,6 +140,7 @@ export interface RecordsNamespace {
   update(id: string, values: Partial<Record_>): Promise<Record_>;
   delete(id: string): Promise<void>;
   aggregate(spec: AggregateSpec): Promise<AggregateResult>;
+  permissions(recordId: string): RecordPermissionsNamespace;
 }
 
 export interface DatastoreClient {
@@ -90,7 +166,7 @@ export interface CreateDatastoreClientOptions {
 }
 
 export function createDatastoreClient(
-  opts: CreateDatastoreClientOptions
+  opts: CreateDatastoreClientOptions,
 ): DatastoreClient;
 
 export class DatastoreError extends Error {
@@ -99,7 +175,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 +184,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.4.0",
   "description": "Typed, scoped client for the AppStudio datastore API. Used by widgets through the injected WidgetContext.",
   "type": "module",
   "main": "./dist/index.js",