@colixsystems/widget-sdk 0.189.0 → 0.190.0

package/README.md

@@ -53,6 +53,7 @@ The data layer lives in **four separate domain-client packages**, each instantia
 | **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** | `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. |
 | **FILES** (`ctx.assets`) | `useAsset(id)` | `{ url, file, loading, error, refetch }` | `ctx.assets.get` — no scope |
@@ -75,7 +76,21 @@ See the design reference for the full architecture: [`docs/architecture/widget-m
 
 ## Status
 
-`v0.189.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.190.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.190.0 (contract 1.151.0)
+
+**New `useTyping(tableId, recordId)` hook: a typing indicator for one record.** It returns `{ typingUserIds, setTyping, status }`. Call `setTyping(true)` on every keystroke in your composer and `setTyping(false)` when the message is sent, the field is cleared or it loses focus. The hook throttles for you: it sends at most one signal every 3 s, and sends `false` on its own after 5 s without a keystroke. `typingUserIds` lists the other users typing in that record (never yourself); each one drops out 6 s after their last signal, so a closed tab never leaves a stale indicator. Signals carry no message content and are never stored.
+
+Key it on the record the conversation lives in (a thread or channel row), which the user must be able to read. It rides the same realtime connection as `useDatastoreSubscription`, so a widget holds one socket for both. `status` is `"connecting"`, `"live"` or `"unavailable"`; it is `"unavailable"` for an anonymous visitor, a refused subscription, a preview with no backend, and a host whose datastore client predates typing. The hook never throws, so render the indicator only when `typingUserIds` is non-empty:
+
+```jsx
+const { typingUserIds, setTyping } = useTyping(threadsTableId, threadId);
+// <TextInput onChangeText={(t) => { setDraft(t); setTyping(t.length > 0); }} onBlur={() => setTyping(false)} />
+// {typingUserIds.length > 0 && <Text>{typingUserIds.length === 1 ? "Someone is typing…" : "Several people are typing…"}</Text>}
+```
+
+Declare `datastore.read` for the table. Additive; works identically in the web Player and the native export.
 
 ### What's new in 0.189.0 (contract 1.150.0)
 

package/dist/contract.cjs

@@ -2043,6 +2043,40 @@ const HOOKS = [
     requiredContextSlice: ["datastore.records"],
     scopes: ["datastore.read:<table>"],
   },
+  // REQ-RT-08 — typing signals for one record.
+  {
+    name: "useTyping",
+    signature: "useTyping(tableId, recordId)",
+    description:
+      "Who else is typing in one record, and announcing your own typing, via " +
+      "ctx.datastore.records(tableId).typing(recordId, ...). It shares the " +
+      "datastore client's one realtime socket with useDatastoreSubscription. " +
+      "Call setTyping(true) on every keystroke (throttled inside: one signal " +
+      "per 3 s at most, and false is sent after 5 s without a keystroke) and " +
+      "setTyping(false) on send, clear or blur. typingUserIds lists the OTHER " +
+      "users typing (user ids, never yourself); each drops out 6 s after their " +
+      "last signal. Signals carry no message content and are never stored. " +
+      "Typing needs a signed-in user who can read the record; key it on the " +
+      "record the conversation lives in (a thread or channel row). Gate the " +
+      "composer that calls setTyping on useCanWrite as usual. status is " +
+      "'connecting' | 'live' | 'unavailable'. " +
+      "Never throws: with a falsy id, an anonymous visitor, a refused " +
+      "subscription, a host whose datastore client predates typing, or a " +
+      "preview with no backend, it returns { typingUserIds: [], setTyping: no-op, " +
+      "status: 'unavailable' }, so render the indicator only when " +
+      "typingUserIds is non-empty. Re-subscribes when tableId or recordId " +
+      "changes. Declare datastore.read for the table.",
+    returnShape: {
+      typingUserIds:
+        "string[]  // other users typing in this record; empty when unavailable",
+      setTyping:
+        "(active: boolean) => void  // true per keystroke, false on send/clear/blur",
+      status:
+        "'connecting' | 'live' | 'unavailable'  // 'unavailable' → hide the indicator",
+    },
+    requiredContextSlice: ["datastore.records"],
+    scopes: ["datastore.read:<table>"],
+  },
   // REQ-WSDK-PLATFORM §6 — Tier A SDK hooks. Mirror of contract.js.
   {
     name: "useClipboard",
@@ -4923,7 +4957,11 @@ const CONTRACT = deepFreeze({
   //    native-only file keeps every vetted subpath (Metro resolves them).
   //    New `hostExternalSpecifiers` / `subpathImportRoots` lists and the
   //    linter export `subpathImportRootsFor(manifest)`.
-  version: "1.150.0",
+  // 1.151.0: additive (sc-10538) — new `useTyping(tableId, recordId)` returns
+  //    `{ typingUserIds, setTyping, status }`: the other users typing in one
+  //    record, over the datastore client's single realtime socket. A host
+  //    whose client lacks `records(t).typing` reads `status: "unavailable"`.
+  version: "1.151.0",
   sharedTranslationKeys: SHARED_TRANSLATION_KEYS,
   hooks: HOOKS,
   primitives: PRIMITIVES,

package/dist/contract.js

@@ -2043,6 +2043,40 @@ const HOOKS = [
     requiredContextSlice: ["datastore.records"],
     scopes: ["datastore.read:<table>"],
   },
+  // REQ-RT-08 — typing signals for one record.
+  {
+    name: "useTyping",
+    signature: "useTyping(tableId, recordId)",
+    description:
+      "Who else is typing in one record, and announcing your own typing, via " +
+      "ctx.datastore.records(tableId).typing(recordId, ...). It shares the " +
+      "datastore client's one realtime socket with useDatastoreSubscription. " +
+      "Call setTyping(true) on every keystroke (throttled inside: one signal " +
+      "per 3 s at most, and false is sent after 5 s without a keystroke) and " +
+      "setTyping(false) on send, clear or blur. typingUserIds lists the OTHER " +
+      "users typing (user ids, never yourself); each drops out 6 s after their " +
+      "last signal. Signals carry no message content and are never stored. " +
+      "Typing needs a signed-in user who can read the record; key it on the " +
+      "record the conversation lives in (a thread or channel row). Gate the " +
+      "composer that calls setTyping on useCanWrite as usual. status is " +
+      "'connecting' | 'live' | 'unavailable'. " +
+      "Never throws: with a falsy id, an anonymous visitor, a refused " +
+      "subscription, a host whose datastore client predates typing, or a " +
+      "preview with no backend, it returns { typingUserIds: [], setTyping: no-op, " +
+      "status: 'unavailable' }, so render the indicator only when " +
+      "typingUserIds is non-empty. Re-subscribes when tableId or recordId " +
+      "changes. Declare datastore.read for the table.",
+    returnShape: {
+      typingUserIds:
+        "string[]  // other users typing in this record; empty when unavailable",
+      setTyping:
+        "(active: boolean) => void  // true per keystroke, false on send/clear/blur",
+      status:
+        "'connecting' | 'live' | 'unavailable'  // 'unavailable' → hide the indicator",
+    },
+    requiredContextSlice: ["datastore.records"],
+    scopes: ["datastore.read:<table>"],
+  },
   // REQ-WSDK-PLATFORM §6 — Tier A SDK hooks. Mirror of contract.js.
   {
     name: "useClipboard",
@@ -4919,7 +4953,11 @@ const CONTRACT = deepFreeze({
   //    native-only file keeps every vetted subpath (Metro resolves them).
   //    New `hostExternalSpecifiers` / `subpathImportRoots` lists and the
   //    linter export `subpathImportRootsFor(manifest)`.
-  version: "1.150.0",
+  // 1.151.0: additive (sc-10538) — new `useTyping(tableId, recordId)` returns
+  //    `{ typingUserIds, setTyping, status }`: the other users typing in one
+  //    record, over the datastore client's single realtime socket. A host
+  //    whose client lacks `records(t).typing` reads `status: "unavailable"`.
+  version: "1.151.0",
   sharedTranslationKeys: SHARED_TRANSLATION_KEYS,
   hooks: HOOKS,
   primitives: PRIMITIVES,

package/dist/hooks.js

@@ -3834,6 +3834,71 @@ export function useDatastoreSubscription(table, handlers, options) {
   return { status };
 }
 
+const _NO_TYPERS = Object.freeze([]);
+
+/**
+ * Who else is typing in one record; call `setTyping` per keystroke.
+ * Never throws: a client without typing reports status "unavailable".
+ *
+ * @param {string} tableId
+ * @param {string} recordId
+ * @returns {{ typingUserIds: string[], setTyping: (active: boolean) => void, status: "connecting" | "live" | "unavailable" }}
+ */
+export function useTyping(tableId, recordId) {
+  const ctx = useWidgetContextOrThrow("useTyping");
+  const [typingUserIds, setTypingUserIds] = useState(_NO_TYPERS);
+  const [status, setStatus] = useState("connecting");
+  const handleRef = useRef(null);
+  // `ctx` is a fresh identity per host render; the effect keys on the ids.
+  const recordsRef = useRef(null);
+  recordsRef.current =
+    ctx.datastore && typeof ctx.datastore.records === "function"
+      ? ctx.datastore.records
+      : null;
+
+  useEffect(() => {
+    setTypingUserIds(_NO_TYPERS);
+    setStatus("connecting");
+    const unavailable = () => {
+      setStatus("unavailable");
+      return undefined;
+    };
+    if (!tableId || !recordId || typeof recordsRef.current !== "function") {
+      return unavailable();
+    }
+    try {
+      const ns = recordsRef.current(tableId);
+      if (!ns || typeof ns.typing !== "function") return unavailable();
+      let current = true;
+      const handle = ns.typing(recordId, {
+        onChange: (ids) => {
+          if (current) setTypingUserIds(ids);
+        },
+        onStatus: (s) => {
+          if (current) setStatus(s);
+        },
+      });
+      handleRef.current = handle;
+      return () => {
+        current = false;
+        handleRef.current = null;
+        if (handle && typeof handle.stop === "function") handle.stop();
+      };
+    } catch (_) {
+      return unavailable();
+    }
+  }, [tableId, recordId]);
+
+  const setTyping = useCallback((active) => {
+    const handle = handleRef.current;
+    if (handle && typeof handle.setTyping === "function") {
+      handle.setTyping(active === true);
+    }
+  }, []);
+
+  return { typingUserIds, setTyping, status };
+}
+
 /* ============================================================================
  * ASSETS CLIENT — ctx.assets (@colixsystems/assets-client)
  *

package/dist/index.d.ts

@@ -496,6 +496,14 @@ export interface DatastoreClient {
       ): Promise<unknown>;
       revoke(permissionId: string): Promise<void>;
     };
+    /** REQ-RT-08 — backs `useTyping`; optional, the hook degrades without it. */
+    typing?(
+      recordId: string,
+      handlers: {
+        onChange?(typingUserIds: string[]): void;
+        onStatus?(status: TypingStatus): void;
+      },
+    ): { setTyping(active: boolean): void; stop(): void };
   };
 }
 
@@ -1410,6 +1418,27 @@ export function useDatastoreSubscription(
   options?: DatastoreSubscriptionOptions,
 ): { status: DatastoreSubscriptionStatus };
 
+export type TypingStatus = "connecting" | "live" | "unavailable";
+
+/**
+ * REQ-RT-08: who else is typing in one record, and announcing your own typing,
+ * via `ctx.datastore.records(tableId).typing(recordId, ...)`. Call
+ * `setTyping(true)` on every keystroke (throttled inside; `false` is sent
+ * after 5 s idle) and `setTyping(false)` on send, clear or blur.
+ * `typingUserIds` lists the other users typing; each drops out 6 s after
+ * their last signal. Needs a signed-in user who can read the record.
+ * Re-subscribes when `tableId` or `recordId` changes. Never throws — a host
+ * whose datastore client lacks typing reports `status: "unavailable"`.
+ */
+export function useTyping(
+  tableId: string | null | undefined,
+  recordId: string | null | undefined,
+): {
+  typingUserIds: string[];
+  setTyping(active: boolean): void;
+  status: TypingStatus;
+};
+
 /**
  * Stateful file-asset resolver hook. Returns `{ url, file, loading, error,
  * refetch }`. The `url` is an absolute URL composed against the host's API

package/dist/index.js

@@ -60,6 +60,7 @@ export {
   IdentificationError,
   useRecordPermissions,
   useDatastoreSubscription,
+  useTyping,
   useWidgetEvent,
   useWidgetInput,
   usePayments,

package/dist/index.native.js

@@ -60,6 +60,7 @@ export {
   IdentificationError,
   useRecordPermissions,
   useDatastoreSubscription,
+  useTyping,
   useWidgetEvent,
   useWidgetInput,
   usePayments,

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@colixsystems/widget-sdk",
-  "version": "0.189.0",
+  "version": "0.190.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

@@ -2043,6 +2043,40 @@ const HOOKS = [
     requiredContextSlice: ["datastore.records"],
     scopes: ["datastore.read:<table>"],
   },
+  // REQ-RT-08 — typing signals for one record.
+  {
+    name: "useTyping",
+    signature: "useTyping(tableId, recordId)",
+    description:
+      "Who else is typing in one record, and announcing your own typing, via " +
+      "ctx.datastore.records(tableId).typing(recordId, ...). It shares the " +
+      "datastore client's one realtime socket with useDatastoreSubscription. " +
+      "Call setTyping(true) on every keystroke (throttled inside: one signal " +
+      "per 3 s at most, and false is sent after 5 s without a keystroke) and " +
+      "setTyping(false) on send, clear or blur. typingUserIds lists the OTHER " +
+      "users typing (user ids, never yourself); each drops out 6 s after their " +
+      "last signal. Signals carry no message content and are never stored. " +
+      "Typing needs a signed-in user who can read the record; key it on the " +
+      "record the conversation lives in (a thread or channel row). Gate the " +
+      "composer that calls setTyping on useCanWrite as usual. status is " +
+      "'connecting' | 'live' | 'unavailable'. " +
+      "Never throws: with a falsy id, an anonymous visitor, a refused " +
+      "subscription, a host whose datastore client predates typing, or a " +
+      "preview with no backend, it returns { typingUserIds: [], setTyping: no-op, " +
+      "status: 'unavailable' }, so render the indicator only when " +
+      "typingUserIds is non-empty. Re-subscribes when tableId or recordId " +
+      "changes. Declare datastore.read for the table.",
+    returnShape: {
+      typingUserIds:
+        "string[]  // other users typing in this record; empty when unavailable",
+      setTyping:
+        "(active: boolean) => void  // true per keystroke, false on send/clear/blur",
+      status:
+        "'connecting' | 'live' | 'unavailable'  // 'unavailable' → hide the indicator",
+    },
+    requiredContextSlice: ["datastore.records"],
+    scopes: ["datastore.read:<table>"],
+  },
   // REQ-WSDK-PLATFORM §6 — Tier A SDK hooks. Mirror of contract.js.
   {
     name: "useClipboard",
@@ -4919,7 +4953,11 @@ const CONTRACT = deepFreeze({
   //    native-only file keeps every vetted subpath (Metro resolves them).
   //    New `hostExternalSpecifiers` / `subpathImportRoots` lists and the
   //    linter export `subpathImportRootsFor(manifest)`.
-  version: "1.150.0",
+  // 1.151.0: additive (sc-10538) — new `useTyping(tableId, recordId)` returns
+  //    `{ typingUserIds, setTyping, status }`: the other users typing in one
+  //    record, over the datastore client's single realtime socket. A host
+  //    whose client lacks `records(t).typing` reads `status: "unavailable"`.
+  version: "1.151.0",
   sharedTranslationKeys: SHARED_TRANSLATION_KEYS,
   hooks: HOOKS,
   primitives: PRIMITIVES,