@colixsystems/widget-sdk 0.192.0 → 0.193.0

package/README.md

@@ -53,7 +53,7 @@ The data layer lives in **four separate domain-client packages**, each instantia
 | **DATASTORE** | `useInterpretDraft(tableId)` | `{ interpret, interpreting, error, result, available }` | `interpret(tableId, body)` — `datastore.read:<table>`. Turns ONE sentence a user typed ("walk at 11 am tomorrow") into DRAFT column values so a form can prefill itself. IMPERATIVE: call `interpret(text, { fields?, timeZone? })` from an event handler, never on mount. It DRAFTS and writes nothing — show the values for review, then submit through `useDatastoreMutation().create`. Resolves to `{ values, unresolved }`; `values` is keyed by column NAME (the shape `create()` takes) and `unresolved` names the fields the sentence did not state. Only text / number / boolean / date / datetime / array columns are drafted — `FILE`, `RELATION`, `USER` and `USER_GROUP` carry ids and are never guessed. Fails closed to an empty draft. **Every call spends the workspace's AI credits** and is rate-limited per actor, so call it once per user action (never on mount or in a render loop); once the workspace runs out the call is refused with a generic 429 — an app user is deliberately **not** told the workspace's billing state, since they have never heard of an AI credit and cannot buy one. Never surface a raw error to the person filling the form: say drafting is unavailable and keep every field editable by hand. `available` is false where the host brokers no interpreter. |
 | **AGENTS** | `useAgent(agentRef)` | `{ send, cancel, reset, messages, sending, resuming, error, available }` | `ctx.agents` — `ai.invoke:*`. Hold a conversation with one of the WORKSPACE's own AI agents (an author-written name + system prompt). Sending is IMPERATIVE: call `send(text)` from an event handler, never on mount — the first send opens the conversation, so a widget nobody types into costs nothing. On mount the hook DOES reopen the caller's most recent thread with this agent, so a refresh or a navigation keeps the conversation instead of starting a blank one; that resume only READS and spends no credit. `resuming` is true while it runs — render a loading state, not an empty thread. `messages` is the running transcript, oldest first. You **cannot** set or read the system prompt, replay an edited transcript, or pick a model: the server assembles every turn from the stored prompt plus the stored history, and `content` is the only thing that reaches the wire. `reset()` drops the thread (a "new chat" affordance), and the new thread is the one a later mount resumes. **Every send spends the workspace's AI credits** and is rate-limited per caller AND per workspace. Rejects with `AgentError`; branch on `.code` — `AI_QUOTA_EXCEEDED` (429) is the workspace's credit ceiling and will NOT clear on a retry, unlike `RATE_LIMITED`, so never offer "try again" for it, and `AGENT_DISABLED` (409) means the author turned it off, so hide the affordance. Never surface a raw error or the workspace's billing state to an app user. `available` is false when no agent is bound or the host brokers none — render a visible unbound state, never a blank box. An assistant message that used a tool also carries **`activity`** — what the agent DID with the user's data: the table it read, or the table and columns it CHANGED (never the values, and never a row the permissions refused). **Render a write.** A reply saying "done!" is not evidence a row was written, and if the agent got it wrong the user has no other way to notice. A talk-only turn omits the key entirely. |
 | **DATASTORE** | `useDatastoreMutation(table)` | `{ create, update, delete }` | `records(table).{ create, update (PATCH), delete }` — `datastore.write:*`. **To CLEAR a cell, pass it empty** — `update(id, { when: null })` (also `""` or `[]`) empties that cell and it reads back as `null` (`[]` on an array column). There is no separate clear call, so never write a sentinel such as `0` or a placeholder date to mean "no value". `false` and `0` are values, not clears, and a REQUIRED column cannot be cleared. |
-| **DATASTORE** | `useDatastoreSubscription(table, handlers, options)` (optional: options) | `{ status }` — `"connecting" \| "live" \| "reconnecting" \| "fallback"` | `records(table).subscribe` — `datastore.read:<table>`. Live `onCreated` / `onUpdated` / `onDeleted` off the REQ-RT-07 socket; never throws, resolving to `{ status: "fallback" }` so the widget polls instead. A whole-table subscribe is gated on read-EVERY-row, because one envelope reaches every subscriber of the table — so for a table governed by per-record grants pass `options.scope`: `{ kind: "record", record_id }` for one row, or `{ kind: "parent", relation_column, record_id }` for the rows whose RELATION column points at that parent (the column must carry `inheritAcl`, else the subscribe reports `"fallback"`). Re-subscribes on the scope's VALUES, so a fresh object literal each render is fine. |
+| **DATASTORE** | `useDatastoreSubscription(table, handlers, options)` (optional: options) | `{ status }` — `"connecting" \| "live" \| "reconnecting" \| "fallback"` | `records(table).subscribe` — `datastore.read:<table>`. Live `onCreated` / `onUpdated` / `onDeleted` off the REQ-RT-07 socket; never throws, resolving to `{ status: "fallback" }` so the widget polls instead. A whole-table subscribe is gated on read-EVERY-row, because one envelope reaches every subscriber of the table — so for a table governed by per-record grants pass `options.scope`: `{ kind: "record", record_id }` for one row, or `{ kind: "parent", relation_column, record_id }` for the rows whose RELATION column points at that parent (the column must carry `inheritAcl`, else the subscribe reports `"fallback"`). For a live list of the signed-in user's own rows pass `{ kind: "granted" }`: every row they read through a grant to them or one of their groups, plus `onAccessGained(record)` / `onAccessLost({ id })` as rows enter and leave that set. Re-subscribes on the scope's VALUES, so a fresh object literal each render is fine. |
 | **DATASTORE** | `useTyping(tableId, recordId)` | `{ typingUserIds, setTyping, status }` — status `"connecting" \| "live" \| "unavailable"` | `records(table).typing` — `datastore.read:<table>`. Who else is typing in one record, over the same socket as `useDatastoreSubscription`. Call `setTyping(true)` on every keystroke (throttled to one signal per 3 s; `false` is sent after 5 s idle) and `setTyping(false)` on send, clear or blur. `typingUserIds` lists the OTHER users' ids; each drops out 6 s after their last signal. Needs a signed-in user who can read the record. Never throws: an anonymous visitor, a refused subscription or a host whose client lacks `typing` reads `{ typingUserIds: [], status: "unavailable" }`. Re-subscribes when either id changes. |
 | **DATASTORE** | `useRecordPermissions(tableId, recordId)` | `{ permissions, loading, error, grant, revoke, update, refetch }` | `records(table).permissions(record).{ list, grant, update, revoke }` — `acl.write:records` (+ `can_grant` on the record) |
 | **DATASTORE** | `useCanWrite(tableId, options)` (optional: options) | `{ canWrite, loading, error, refetch }` | `myPermissions(tableId, { recordId? })` — scope `datastore.read:<table>`. A FLOOR, not a full replacement for domain-specific write rules: answers "may this caller write", reading the same table-ACL answer the write endpoint enforces — so a table granting Create to Everyone answers `true` for a logged-out visitor, and this hook alone is the right gate for a widget meant to work without signing in. Pass `{ recordId }` for a per-row check. A widget whose own rule is MORE SPECIFIC than the table ACL (e.g. "only the assigned user may edit this row") must still hand-check that in addition. Pair with `useUser()` to also tell "not signed in" apart from "signed in but forbidden" — both resolve `canWrite: false` here. Falsy `tableId`, or a host that hasn't injected `myPermissions` (an older host), collapses to `{ canWrite: false, loading: false, error: null, refetch: async () => undefined }` rather than throwing. |
@@ -77,7 +77,29 @@ See the design reference for the full architecture: [`docs/architecture/widget-m
 
 ## Status
 
-`v0.192.0` — pre-publish. The package surface (types, function names, export paths) is the v1 contract; runtime behaviour for some hooks is stubbed (each hook documents what's wired and what isn't). It is **not yet published to npm**.
+`v0.193.0` — pre-publish. The package surface (types, function names, export paths) is the v1 contract; runtime behaviour for some hooks is stubbed (each hook documents what's wired and what isn't). It is **not yet published to npm**.
+
+### What's new in 0.193.0 (contract 1.154.0)
+
+**`useDatastoreSubscription` can keep a list of the user's own rows live.** Pass `{ scope: { kind: "granted" } }` and the hook streams every row of the table the signed-in user can read through a grant to them or to one of their groups — their conversations, their cases. Without it such a list had to poll: a whole-table subscribe needs read on every row, and one record scope per row runs out of subscriptions.
+
+Two new handlers report changes to the set itself. `onAccessGained(record)` fires with the full row when a grant starts letting the user read it, for example when they are added to a conversation. `onAccessLost({ id })` fires when they can no longer read it, and no further event for that row arrives. Merge `onCreated` / `onUpdated` / `onAccessGained` into your list by `id`, and remove the row on `onDeleted` or `onAccessLost`:
+
+```jsx
+const { data, refetch } = useDatastoreQuery(conversationsTableId);
+const [live, setLive] = useState([]);
+useEffect(() => setLive(data), [data]);
+const upsert = (row) => setLive((list) => [row, ...list.filter((r) => r.id !== row.id)]);
+const drop = ({ id }) => setLive((list) => list.filter((r) => r.id !== id));
+const { status } = useDatastoreSubscription(
+  conversationsTableId,
+  { onCreated: upsert, onUpdated: upsert, onAccessGained: upsert, onDeleted: drop, onAccessLost: drop },
+  { scope: { kind: "granted" } },
+);
+// Poll with refetch() only while status === "fallback".
+```
+
+A logged-out visitor's granted subscribe resolves to `{ status: "fallback" }`. Backed by datastore-client 0.21.0. Additive; works identically in the web Player and the native export.
 
 ### What's new in 0.192.0 (contract 1.153.0)
 

package/dist/contract.cjs

@@ -2060,6 +2060,13 @@ const HOOKS = [
       "table governed by per-record grants, since a scope-less subscribe must " +
       "prove read-every-row. A `parent` scope requires the column be an " +
       "inheritAcl RELATION, else the subscribe resolves to " +
+      "{ status: 'fallback' }. { kind: 'granted' } streams every row the " +
+      "signed-in user can read through a grant to them or to one of their " +
+      "groups — the way to keep a list of 'my conversations' or 'my cases' " +
+      "live — and adds two handlers: onAccessGained(record) when a row " +
+      "becomes readable (the full row) and onAccessLost({ id }) when it stops " +
+      "being readable, after which no further event for it arrives. A " +
+      "logged-out visitor's granted subscribe resolves to " +
       "{ status: 'fallback' }.",
     returnShape: {
       status:
@@ -5070,7 +5077,11 @@ const CONTRACT = deepFreeze({
   //    `useAudioPlayer(uri)`, backed by the optional `device.audioRecorder` /
   //    `device.audioPlayer` slices (MediaRecorder + <audio> on web, expo-audio
   //    on native), with `AudioRecorderError` / `AudioPlayerError`.
-  version: "1.153.0",
+  // 1.154.0: additive (sc-10589) — `useDatastoreSubscription` accepts
+  //    `scope: { kind: "granted" }` (the rows the signed-in user reads through
+  //    a user or group grant) and the `onAccessGained` / `onAccessLost`
+  //    handlers that report rows entering and leaving that set.
+  version: "1.154.0",
   sharedTranslationKeys: SHARED_TRANSLATION_KEYS,
   hooks: HOOKS,
   primitives: PRIMITIVES,

package/dist/contract.js

@@ -2060,6 +2060,13 @@ const HOOKS = [
       "table governed by per-record grants, since a scope-less subscribe must " +
       "prove read-every-row. A `parent` scope requires the column be an " +
       "inheritAcl RELATION, else the subscribe resolves to " +
+      "{ status: 'fallback' }. { kind: 'granted' } streams every row the " +
+      "signed-in user can read through a grant to them or to one of their " +
+      "groups — the way to keep a list of 'my conversations' or 'my cases' " +
+      "live — and adds two handlers: onAccessGained(record) when a row " +
+      "becomes readable (the full row) and onAccessLost({ id }) when it stops " +
+      "being readable, after which no further event for it arrives. A " +
+      "logged-out visitor's granted subscribe resolves to " +
       "{ status: 'fallback' }.",
     returnShape: {
       status:
@@ -5066,7 +5073,11 @@ const CONTRACT = deepFreeze({
   //    `useAudioPlayer(uri)`, backed by the optional `device.audioRecorder` /
   //    `device.audioPlayer` slices (MediaRecorder + <audio> on web, expo-audio
   //    on native), with `AudioRecorderError` / `AudioPlayerError`.
-  version: "1.153.0",
+  // 1.154.0: additive (sc-10589) — `useDatastoreSubscription` accepts
+  //    `scope: { kind: "granted" }` (the rows the signed-in user reads through
+  //    a user or group grant) and the `onAccessGained` / `onAccessLost`
+  //    handlers that report rows entering and leaving that set.
+  version: "1.154.0",
   sharedTranslationKeys: SHARED_TRANSLATION_KEYS,
   hooks: HOOKS,
   primitives: PRIMITIVES,

package/dist/hooks.js

@@ -3979,10 +3979,13 @@ export function useCanWrite(tableId, options) {
  * rather than crashing at render (widget-parity skill).
  *
  * @param {string} table  Bound table id (falsy → no subscription, status "fallback").
- * @param {{ onCreated?, onUpdated?, onDeleted? }} [handlers]  Per-event callbacks; each receives the snake_case record.
- * @param {{ fallbackAfterMs?: number, scope?: { kind: "record"|"parent", relation_column?: string, record_id: string } }} [options]
+ * @param {{ onCreated?, onUpdated?, onDeleted?, onAccessGained?, onAccessLost? }} [handlers]  Per-event callbacks; each receives the snake_case record.
+ * @param {{ fallbackAfterMs?: number, scope?: { kind: "record"|"parent"|"granted", relation_column?: string, record_id?: string } }} [options]
  *   `scope` narrows the stream below whole-table — required for a table
  *   governed by per-record grants. Re-subscribes on its VALUES, not identity.
+ *   `{ kind: "granted" }` streams every row the signed-in user reads through
+ *   a user or group grant; `onAccessGained` / `onAccessLost` report rows
+ *   entering (the full row) and leaving (`{ id }`) that set.
  * @returns {{ status: "connecting" | "live" | "reconnecting" | "fallback" }}
  */
 export function useDatastoreSubscription(table, handlers, options) {
@@ -4051,6 +4054,8 @@ export function useDatastoreSubscription(table, handlers, options) {
         onCreated: (r) => handlersRef.current?.onCreated?.(r),
         onUpdated: (r) => handlersRef.current?.onUpdated?.(r),
         onDeleted: (r) => handlersRef.current?.onDeleted?.(r),
+        onAccessGained: (r) => handlersRef.current?.onAccessGained?.(r),
+        onAccessLost: (r) => handlersRef.current?.onAccessLost?.(r),
         onStatus: (s) => setStatus(s),
       },
       Object.keys(subscribeOptions).length > 0 ? subscribeOptions : undefined,

package/dist/index.d.ts

@@ -1418,6 +1418,10 @@ export interface DatastoreSubscriptionHandlers {
   onCreated?: (record: Record<string, unknown>) => void;
   onUpdated?: (record: Record<string, unknown>) => void;
   onDeleted?: (record: Record<string, unknown>) => void;
+  /** Granted scope: a row the user can now read, in full. */
+  onAccessGained?: (record: Record<string, unknown>) => void;
+  /** Granted scope: a row the user can no longer read; nothing follows it. */
+  onAccessLost?: (record: { id: string }) => void;
 }
 
 // sc-6270: see SubscriptionScope in @colixsystems/datastore-client. A scoped
@@ -1425,7 +1429,8 @@ export interface DatastoreSubscriptionHandlers {
 // which is what lets a per-record-ACL table stream at all.
 export type DatastoreSubscriptionScope =
   | { kind: "record"; record_id: string }
-  | { kind: "parent"; relation_column: string; record_id: string };
+  | { kind: "parent"; relation_column: string; record_id: string }
+  | { kind: "granted" };
 
 export interface DatastoreSubscriptionOptions {
   fallbackAfterMs?: number;
@@ -1440,9 +1445,10 @@ export interface DatastoreSubscriptionOptions {
  * REST polling instead. Never throws — degrades to `{ status: "fallback" }` on
  * a host whose datastore client predates realtime.
  *
- * `options.scope` narrows the stream to one record or to a parent's
- * inheriting children; re-subscribes when the scope's values change, not on
- * every render.
+ * `options.scope` narrows the stream to one record, to a parent's
+ * inheriting children, or (`{ kind: "granted" }`) to the rows the signed-in
+ * user reads through a user or group grant; re-subscribes when the scope's
+ * values change, not on every render.
  */
 export function useDatastoreSubscription(
   tableId: string | null | undefined,

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@colixsystems/widget-sdk",
-  "version": "0.192.0",
+  "version": "0.193.0",
   "description": "Common widget interface for AppStudio. Implements WidgetManifest, WidgetContext, property schema, and helper hooks.",
   "homepage": "https://github.com/Colix-AB/AppStudio",
   "type": "module",

package/src/contract.js

@@ -2060,6 +2060,13 @@ const HOOKS = [
       "table governed by per-record grants, since a scope-less subscribe must " +
       "prove read-every-row. A `parent` scope requires the column be an " +
       "inheritAcl RELATION, else the subscribe resolves to " +
+      "{ status: 'fallback' }. { kind: 'granted' } streams every row the " +
+      "signed-in user can read through a grant to them or to one of their " +
+      "groups — the way to keep a list of 'my conversations' or 'my cases' " +
+      "live — and adds two handlers: onAccessGained(record) when a row " +
+      "becomes readable (the full row) and onAccessLost({ id }) when it stops " +
+      "being readable, after which no further event for it arrives. A " +
+      "logged-out visitor's granted subscribe resolves to " +
       "{ status: 'fallback' }.",
     returnShape: {
       status:
@@ -5066,7 +5073,11 @@ const CONTRACT = deepFreeze({
   //    `useAudioPlayer(uri)`, backed by the optional `device.audioRecorder` /
   //    `device.audioPlayer` slices (MediaRecorder + <audio> on web, expo-audio
   //    on native), with `AudioRecorderError` / `AudioPlayerError`.
-  version: "1.153.0",
+  // 1.154.0: additive (sc-10589) — `useDatastoreSubscription` accepts
+  //    `scope: { kind: "granted" }` (the rows the signed-in user reads through
+  //    a user or group grant) and the `onAccessGained` / `onAccessLost`
+  //    handlers that report rows entering and leaving that set.
+  version: "1.154.0",
   sharedTranslationKeys: SHARED_TRANSLATION_KEYS,
   hooks: HOOKS,
   primitives: PRIMITIVES,