@colixsystems/datastore-client 0.3.0 → 0.4.0

package/README.md

@@ -6,7 +6,9 @@ See the design reference: [`docs/architecture/widget-marketplace.md`](../../docs
 
 ## Status
 
-`v0.3.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.
 
@@ -57,6 +59,14 @@ const byStatus = await client
 
 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
@@ -71,6 +81,10 @@ const myGroups = await client.groups.listMine(); // { data, meta }
 | `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>` |

package/dist/client.js

@@ -59,6 +59,42 @@ 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
@@ -158,6 +194,44 @@ export function createDatastoreClient(opts) {
           "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)}`),
+        };
+      },
     };
   }
 

package/dist/client.test.js

@@ -119,3 +119,97 @@ test("tables.list / tables.get paths", async () => {
   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

@@ -80,6 +80,59 @@ export interface Group {
   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 {
   list(query?: Query): Promise<Page<Record_>>;
   get(id: string): Promise<Record_>;
@@ -87,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 {

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@colixsystems/datastore-client",
-  "version": "0.3.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",