@colixsystems/widget-sdk 0.108.0 → 0.109.0

package/README.md

@@ -46,6 +46,7 @@ The data layer lives in **four separate domain-client packages**, each instantia
 | **DATASTORE** | `useBoundColumns(tableId, shape, props)` | `{ columns, resolved, missing, loading, error }` | `schema(tableId)` (built on `useDatastoreSchema`) — `datastore.read:<table>`. Resolves author-bound column NAMES from `props` by exact name → case-insensitive name → first unclaimed column matching `shape[key].dataType`, so a column an author renamed after install still resolves instead of `record[props.titleField]` reading `undefined`. `columns` holds the resolved NAME (`record[columns.titleField]`); `resolved` holds the full `Column`; `missing` lists non-`optional` keys that never resolved. Falsy `tableId` collapses to `{ columns: {}, resolved: {}, missing: Object.keys(shape), loading: false, error: null }`. |
 | **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. |
 | **DATASTORE** | `useDatastoreMutation(table)` | `{ create, update, delete }` | `records(table).{ create, update (PATCH), delete }` — `datastore.write:*` |
+| **DATASTORE** | `useDatastoreSubscription(table, handlers, 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** | `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?)` | `{ canWrite, loading, error, refetch }` | `myPermissions(tableId, { recordId? })` — scope `datastore.read:<table>`. A FLOOR, not a full replacement for domain-specific write rules: answers "is this caller signed in AND permitted", reading the same table-ACL answer the write endpoint enforces. 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. |
 | **FILES** (`ctx.assets`) | `useAsset(id)` | `{ url, file, loading, error, refetch }` | `ctx.assets.get` — no scope |

package/dist/contract.cjs

@@ -1469,7 +1469,15 @@ const HOOKS = [
       "{ status: 'fallback' } WITHOUT throwing so the widget can poll instead. " +
       "Reads the same datastore.read scope as useDatastoreQuery — declare " +
       "datastore.read for the table you subscribe to. Pair with " +
-      "useDatastoreQuery for the initial load and merge the streamed envelopes.",
+      "useDatastoreQuery for the initial load and merge the streamed " +
+      "envelopes. `options.scope` narrows the subscription: " +
+      "{ kind: 'record', record_id } streams one record, and " +
+      "{ kind: 'parent', relation_column, record_id } streams the rows whose " +
+      "RELATION column points at that parent — the only way to subscribe to a " +
+      "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' }.",
     returnShape: {
       status:
         "'connecting' | 'live' | 'reconnecting' | 'fallback'  // transport state; 'fallback' → poll",
@@ -3341,7 +3349,20 @@ const CONTRACT = deepFreeze({
   //    dark theme's spinner visible instead of grey-on-grey.
   //    `useTheme().colors.loader` is the value a widget reads for its own
   //    loading state; both hosts paint their chrome spinners from the same key.
-  version: "1.82.0",
+  //
+  // 1.83.0: additive (sc-6270) — `useDatastoreSubscription` gains
+  //    `options.scope`, narrowing a subscription from the whole table to one
+  //    record (`{ kind: "record", record_id }`) or to a parent's inheriting
+  //    children (`{ kind: "parent", relation_column, record_id }`). Without it
+  //    a table whose rows are governed by PER-RECORD grants could not stream
+  //    at all: the plane fans one envelope to every subscriber, so a
+  //    scope-less subscribe must prove read-every-row (sc-4311) and a channel
+  //    member never can. A scoped subscribe is gated on the per-record read
+  //    check instead — the same predicate REST applies per row — and `parent`
+  //    additionally requires an `inheritAcl` RELATION column, which is what
+  //    makes the stream a strict subset of what `list()` already returns.
+  //    Backed by datastore-client 0.15.0. Omitting `scope` is unchanged.
+  version: "1.83.0",
   sharedTranslationKeys: SHARED_TRANSLATION_KEYS,
   hooks: HOOKS,
   primitives: PRIMITIVES,

package/dist/contract.js

@@ -1469,7 +1469,15 @@ const HOOKS = [
       "{ status: 'fallback' } WITHOUT throwing so the widget can poll instead. " +
       "Reads the same datastore.read scope as useDatastoreQuery — declare " +
       "datastore.read for the table you subscribe to. Pair with " +
-      "useDatastoreQuery for the initial load and merge the streamed envelopes.",
+      "useDatastoreQuery for the initial load and merge the streamed " +
+      "envelopes. `options.scope` narrows the subscription: " +
+      "{ kind: 'record', record_id } streams one record, and " +
+      "{ kind: 'parent', relation_column, record_id } streams the rows whose " +
+      "RELATION column points at that parent — the only way to subscribe to a " +
+      "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' }.",
     returnShape: {
       status:
         "'connecting' | 'live' | 'reconnecting' | 'fallback'  // transport state; 'fallback' → poll",
@@ -3341,7 +3349,20 @@ const CONTRACT = deepFreeze({
   //    dark theme's spinner visible instead of grey-on-grey.
   //    `useTheme().colors.loader` is the value a widget reads for its own
   //    loading state; both hosts paint their chrome spinners from the same key.
-  version: "1.82.0",
+  //
+  // 1.83.0: additive (sc-6270) — `useDatastoreSubscription` gains
+  //    `options.scope`, narrowing a subscription from the whole table to one
+  //    record (`{ kind: "record", record_id }`) or to a parent's inheriting
+  //    children (`{ kind: "parent", relation_column, record_id }`). Without it
+  //    a table whose rows are governed by PER-RECORD grants could not stream
+  //    at all: the plane fans one envelope to every subscriber, so a
+  //    scope-less subscribe must prove read-every-row (sc-4311) and a channel
+  //    member never can. A scoped subscribe is gated on the per-record read
+  //    check instead — the same predicate REST applies per row — and `parent`
+  //    additionally requires an `inheritAcl` RELATION column, which is what
+  //    makes the stream a strict subset of what `list()` already returns.
+  //    Backed by datastore-client 0.15.0. Omitting `scope` is unchanged.
+  version: "1.83.0",
   sharedTranslationKeys: SHARED_TRANSLATION_KEYS,
   hooks: HOOKS,
   primitives: PRIMITIVES,

package/dist/hooks.js

@@ -2482,7 +2482,9 @@ export function useCanWrite(tableId, options) {
  *
  * @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 }} [options]
+ * @param {{ fallbackAfterMs?: number, scope?: { kind: "record"|"parent", 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.
  * @returns {{ status: "connecting" | "live" | "reconnecting" | "fallback" }}
  */
 export function useDatastoreSubscription(table, handlers, options) {
@@ -2510,7 +2512,23 @@ export function useDatastoreSubscription(table, handlers, options) {
       ? options.fallbackAfterMs
       : undefined;
 
+  // sc-6270: a scope narrows the subscription to one record or to a parent's
+  // inheriting children. Authors pass a fresh object literal every render, so
+  // the effect keys on the scope's VALUES — depending on its identity would
+  // tear down and reopen the socket on each render.
+  const scope = options && options.scope ? options.scope : null;
+  const scopeKey = scope
+    ? [scope.kind, scope.relation_column, scope.record_id]
+        .map((part) => part || "")
+        .join("|")
+    : "";
+  const scopeRef = useRef(scope);
+  scopeRef.current = scope;
+
   useEffect(() => {
+    // Re-scoping starts a new connection, so a stale "live" from the previous
+    // scope must not mask the gap while it opens.
+    setStatus("connecting");
     if (!table || typeof recordsRef.current !== "function") {
       setStatus("fallback");
       return undefined;
@@ -2527,6 +2545,9 @@ export function useDatastoreSubscription(table, handlers, options) {
       setStatus("fallback");
       return undefined;
     }
+    const subscribeOptions = {};
+    if (fallbackAfterMs != null) subscribeOptions.fallbackAfterMs = fallbackAfterMs;
+    if (scopeRef.current) subscribeOptions.scope = scopeRef.current;
     const stop = ns.subscribe(
       {
         onCreated: (r) => handlersRef.current?.onCreated?.(r),
@@ -2534,13 +2555,13 @@ export function useDatastoreSubscription(table, handlers, options) {
         onDeleted: (r) => handlersRef.current?.onDeleted?.(r),
         onStatus: (s) => setStatus(s),
       },
-      fallbackAfterMs != null ? { fallbackAfterMs } : undefined,
+      Object.keys(subscribeOptions).length > 0 ? subscribeOptions : undefined,
     );
     return () => {
       if (typeof stop === "function") stop();
     };
     // eslint-disable-next-line react-hooks/exhaustive-deps
-  }, [table, fallbackAfterMs]);
+  }, [table, fallbackAfterMs, scopeKey]);
 
   return { status };
 }

package/dist/index.d.ts

@@ -1137,8 +1137,16 @@ export interface DatastoreSubscriptionHandlers {
   onDeleted?: (record: Record<string, unknown>) => void;
 }
 
+// sc-6270: see SubscriptionScope in @colixsystems/datastore-client. A scoped
+// subscribe is gated on the per-record read check instead of read-every-row,
+// 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 };
+
 export interface DatastoreSubscriptionOptions {
   fallbackAfterMs?: number;
+  scope?: DatastoreSubscriptionScope;
 }
 
 /**
@@ -1148,6 +1156,10 @@ export interface DatastoreSubscriptionOptions {
  * is `"fallback"` (no socket support, ACL-rejected, or connect timed out) run
  * 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.
  */
 export function useDatastoreSubscription(
   tableId: string | null | undefined,

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@colixsystems/widget-sdk",
-  "version": "0.108.0",
+  "version": "0.109.0",
   "description": "Common widget interface for AppStudio. Implements WidgetManifest, WidgetContext, property schema, and helper hooks.",
   "type": "module",
   "main": "./dist/index.js",