@colixsystems/datastore-client 0.4.0 → 0.6.0

package/README.md

@@ -1,27 +1,39 @@
 # @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}`.
+- **realtime** — subscribe to a table's live change stream (REQ-RT-07) via `records(tableId).subscribe({ onCreated, onUpdated, onDeleted, onStatus })`, returning an unsubscribe function.
+
+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.6.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.6.0 (additive):** added `records(tableId).subscribe({ onCreated, onUpdated, onDeleted, onStatus }, { fallbackAfterMs? })` (REQ-RT-07) — a WebSocket subscription to the table's realtime change stream at `<baseUrl>/datastore/ws`, returning a synchronous unsubscribe function. Server-gated by the same read ACL as REST. New optional `webSocketImpl` factory option (defaults to `globalThis.WebSocket`, present in browsers and React Native); when no impl is available `onStatus` reports `"fallback"` so callers poll. No existing method changed.
 
-> **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.
+> **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.
 
-## Differences from `frontend/src/api/client.js`
+## Contract: snake_case, no transform
 
-| 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`) |
+The wire format is snake_case in **both** directions and that is the client contract too. The SDK does **no** case mapping:
+
+- 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 +50,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 +91,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 +101,54 @@ 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>` |
+| `records(t).subscribe(handlers, opts?)` | `WS <baseUrl>/datastore/ws` (`{type:"subscribe",tableId}`) | `() => void` (unsubscribe) |
+
+### 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`. |
+| `webSocketImpl` | `typeof WebSocket` | Optional. Used by `records(t).subscribe(...)`. Defaults to `globalThis.WebSocket` (browser + React Native). When absent, `subscribe` reports `"fallback"` and opens no socket. |
+
+## 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.