@colixsystems/widget-sdk 0.192.0 → 0.194.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. |
@@ -62,7 +62,7 @@ The data layer lives in **four separate domain-client packages**, each instantia
 | **DIRECTORY** (`ctx.directory`) | `useDirectory(query)` (optional: query) | `{ users, loading, error, refetch }` | `directory.users.list` — `directory.read:users` |
 | **DIRECTORY** | `useUsers(query)` (optional: query) | `{ users, loading, error, refetch, invite, deactivate, reactivate, remove, sendPasswordReset }` | `directory.users.*` — `users.read:*` plus the `users.read` (or `users.write`) capability, else `FORBIDDEN` (edits, incl. `sendPasswordReset()`, also `users.write:*`; `remove()` also `users.delete:*`) |
 | **DIRECTORY** | `useGroups(query)` (optional: query) | `{ groups, loading, error, refetch, create, remove, addMember, removeMember }` | `directory.groups.*` — `groups.read:*` (mutations also `groups.write:*`) |
-| **DIRECTORY** | `useInvites(query)` (optional: query) | `{ invites, loading, error, refetch, resend, revoke }` | `directory.invites.*` — `users.write:*` + the SystemAcl `users.write` capability (the whole invite surface, list included). `query` is `{ status?, q?, app_user_id?, limit?, offset? }` with `status` ∈ `pending \| accepted \| revoked \| expired \| not_sent \| open \| all` (endpoint default `all`; `open` = `pending`, `not_sent` or `expired`); `q` matches the invite's name or email, `app_user_id` returns the invites reserving that user id. `resend(inviteId)` sends the invitation — the first send of a `not_sent` one included. |
+| **DIRECTORY** | `useInvites(query)` (optional: query) | `{ invites, loading, error, refetch, resend, revoke }` | `directory.invites.*` — `users.write:*` + the SystemAcl `users.write` capability (the whole invite surface, list included). `query` is `{ status?, q?, app_user_id?, limit?, offset? }` with `status` ∈ `pending \| accepted \| revoked \| expired \| open \| all` (endpoint default `all`; `open` = `pending` or `expired`); `q` matches the invite's name or email, `app_user_id` returns the invites reserving that user id. |
 | **DIRECTORY** | `useBankIdLink()` | `{ linked, available, status, qr, message, startLink, refresh, cancel, unlink, refetchStatus, … }` | `directory.bankid.*` — no scope (JWT-gated self-service) |
 | **FILESTORE** (`ctx.filestore`) | `usePdfExport({ spaceType, folderId })` (optional: spaceType, folderId) | `{ openPdf, opening, canOpenPdf, exportToPdf, exporting, error, lastExported }` | `ctx.filestore.files.renderPdf` + `ctx.device.pdfViewer`, `ctx.filestore.files.exportPdf` — `files.write:*`. `openPdf(html, { fileName? })` renders the HTML to a PDF server-side and OPENS it (web: PDF tab; native: print / share sheet) without saving. `exportToPdf(html, { fileName?, folderId? })` renders it and saves it as a file (`application/pdf`). Same server-side renderer on web + native. |
 | **PAYMENTS** (`ctx.payments`) | `usePayments()` | `{ requestPayment, getPayment }` | `ctx.payments.*` — `payments.charge:appUser`. Rejects with `PaymentError { code, message, retryable }`; when `retryable` is `false` show `message` and drop the retry. Charges are accepted ONLY in the currency the workspace sells in — omit `currency` and the platform applies it (a disagreeing literal is a publish-blocking `payment-currency` finding). |
@@ -77,7 +77,33 @@ 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.194.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.194.0 (contract 1.155.0)
+
+**Send-later invitations are withdrawn.** 0.183.0 let `useUsers().invite()` take `send_invitation: false` to store an invitation without emailing it. That argument, the `not_sent` invite status and the `sent_at` field are removed: `invite()` emails the invitation at once, as it did before, and `useInvites().resend(inviteId)` re-sends a pending one. A widget that wants to line people up first keeps its own list and calls `invite()` when it is ready.
+
+### 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)
 
@@ -228,24 +254,7 @@ An installed widget is not rebuilt or republished for this. The web Player hands
 
 ### What's new in 0.183.0 (contract 1.144.0)
 
-**A widget can prepare an invitation now and send it later.** `useUsers().invite()` always emailed the invitation the moment it was created, so a widget could not line people up ahead of a launch day or let a second person check the list first. `invite()` now takes an optional `send_invitation`:
-
-```js
-const { invite } = useUsers();
-const { invites, resend } = useInvites({ status: "not_sent" });
-
-const prepared = await invite({ email: "bo@example.com", name: "Bo", send_invitation: false });
-// prepared.status === "not_sent", prepared.sent_at === null — nobody was emailed.
-
-await resend(prepared.id);   // emails it; the row is now "pending" with a fresh 7-day expiry
-```
-
-- **`send_invitation`** defaults to `true`, so an existing `invite({ email, name, group_ids })` call emails at once exactly as before. `false` stores the invitation and emails nobody. A value that is not a boolean rejects with a `DirectoryError` coded `VALIDATION`.
-- **`not_sent` joins the invite `status` values**, and every invite row carries **`sent_at`** (`null` until the first send). A `not_sent` invitation cannot be accepted yet and its `expires_at` means nothing until it is sent, so show no expiry for it. `useInvites({ status: "not_sent" })` lists just the prepared ones. Where several states apply the first of accepted, revoked, not_sent, expired, pending wins.
-- **`useInvites().resend(inviteId)` is the one call that sends**, whether or not the invitation was sent before. There is no separate `send` method: on a `not_sent` row it is the first send, on a `pending` or `expired` one it sends again, and either way it stamps `sent_at`, restarts the expiry and resolves the row as `pending`. Label the button to match the row — "Send invitation" when `status === "not_sent"`, "Resend" otherwise.
-- **A widget that switches on `status` should handle the new value.** A `not_sent` row falls through an `if (status === "pending")` check, so a list that offers its actions only to pending rows would leave a prepared invitation with no way to send it.
-
-The built-in User Management widget offers the choice on its invite form ("Send the invitation later", off by default) and a "Send invitation" action on each row that has not been sent. No new scope: both calls sit under `users.write:*`, as before.
+Send-later invitations (`send_invitation`, the `not_sent` status, `sent_at`). Withdrawn in 0.194.0.
 
 ### What's new in 0.182.0 (contract 1.143.0)
 
@@ -2272,13 +2281,11 @@ The matching manifest declares the scopes:
 }
 ```
 
-`invite()` emails the invitation at once. Pass `send_invitation: false` to store it without emailing anyone — the row comes back with `status: "not_sent"` and `sent_at: null` — and send it later with `useInvites().resend(inviteId)`.
-
 The host rejects calls whose scope is not declared in the manifest (the SDK linter catches this statically too). Declaring a write scope is also a consent prompt the Studio admin sees at install time — the wider the scope set, the more careful the admin is about granting the install.
 
 ## Listing pending invitations from a widget
 
-`useInvites(query?)` lists the workspace's invites and sends / revokes them:
+`useInvites(query?)` lists the workspace's invites and resends / revokes them:
 
 ```jsx
 import { useInvites, View, Text, Pressable } from '@colixsystems/widget-sdk';
@@ -2293,9 +2300,7 @@ function PendingInvites() {
       {invites.map((i) => (
         <View key={i.id}>
           <Text>{i.email} · {i.status}</Text>
-          <Pressable onPress={() => resend(i.id).catch(() => {})}>
-            <Text>{i.status === 'not_sent' ? 'Send invitation' : 'Resend'}</Text>
-          </Pressable>
+          <Pressable onPress={() => resend(i.id).catch(() => {})}><Text>Resend</Text></Pressable>
           <Pressable onPress={() => revoke(i.id).catch(() => {})}><Text>Revoke</Text></Pressable>
         </View>
       ))}
@@ -2304,16 +2309,9 @@ function PendingInvites() {
 }
 ```
 
-Rows are snake_case: `{ id, app_user_id, email, name, group_ids, status, sent_at,
-expires_at, accepted_at, revoked_at, created_at }`. `status` is one of `pending`,
-`accepted`, `revoked`, `expired` or `not_sent`; trust the server-computed value rather
-than comparing `expires_at` against the device clock.
-
-A `not_sent` row is an invitation created with `send_invitation: false`: nobody has
-been emailed and `sent_at` is `null`. `resend(inviteId)` is the one call that sends
-an invitation, a first send and a repeat send alike — it emails the invitee, stamps
-`sent_at`, restarts the 7-day expiry and resolves the row as `pending`. Pass
-`{ status: 'not_sent' }` to list only the prepared ones.
+Rows are snake_case: `{ id, app_user_id, email, name, group_ids, status, expires_at,
+accepted_at, revoked_at, created_at }`. Trust the server-computed `status` rather than
+comparing `expires_at` against the device clock.
 
 `query` also takes `q` (a case-insensitive substring match on the invite's name or
 email) and `app_user_id`. Each row's `app_user_id` is the id the invitee's user account
@@ -2321,7 +2319,7 @@ will have once they accept. A `USER` column may hold that id before the person h
 joined — it then reads back as `{ id, name, invited: true }`, with no `email` — and
 `useInvites({ app_user_id: value.id, status: 'open', limit: 1 })` returns the invite
 behind it. `status: 'open'` is every invite that is neither accepted nor revoked
-(`pending`, `not_sent` or `expired`); a re-invite keeps the id, so without it earlier invites match too.
+(`pending` or `expired`); a re-invite keeps the id, so without it earlier invites match too.
 
 **The gate is `users.write`, not `users.read`.** A pending invite exposes the email of
 someone who is not a member yet, so the backend gates the entire invite surface —

package/dist/contract.cjs

@@ -1749,9 +1749,8 @@ const HOOKS = [
   // deactivate / reactivate / sendPasswordReset) additionally need
   // `users.write:*`, and the
   // destructive `remove` needs `users.delete:*` (SC-902). The `invite`
-  // call accepts `{ email, name, group_ids?, send_invitation? }` and returns
-  // the resulting AppUserInvite row (the host sends the email, unless
-  // `send_invitation` is false). Mutating users from
+  // call accepts `{ email, name, groupIds? }` and returns the resulting
+  // AppUserInvite row (the email is sent by the host). Mutating users from
   // a widget requires the corresponding SystemAcl capability grant in the
   // tenant (`users.write` for edits, `users.delete` for removal); widgets
   // that only call read methods need only `users.read:*`.
@@ -1769,13 +1768,8 @@ const HOOKS = [
       "scope; edit-style mutations (invite/deactivate/reactivate/" +
       "sendPasswordReset) need users.write:*, and the destructive remove() " +
       "additionally needs users.delete:* (SC-902). The `invite` call accepts " +
-      "{ email, name, group_ids?, send_invitation? } and returns the resulting " +
-      "AppUserInvite row { id, email, name, expires_at, sent_at, status }. " +
-      "The host emails the invitation at once unless send_invitation is " +
-      "false: then nothing is emailed, the row comes back with sent_at null " +
-      "and status 'not_sent', and useInvites().resend(inviteId) sends it " +
-      "later. A send_invitation that is not a boolean rejects with " +
-      "DirectoryError code VALIDATION. sendPasswordReset(userId) mails the " +
+      "{ email, name, group_ids? } and returns the resulting AppUserInvite row " +
+      "(the email is sent by the host). sendPasswordReset(userId) mails the " +
       "standard self-serve reset link to that user's own registered address " +
       "and resolves { sent, email_masked } — never the token or the link, so " +
       "it cannot be used to sign in as them. It rejects with a DirectoryError " +
@@ -1788,7 +1782,7 @@ const HOOKS = [
       error: "DirectoryError | null  // { code, message, retryable }",
       refetch: "() => Promise<void>",
       invite:
-        "({ email, name, group_ids?, send_invitation? }) => Promise<Invite>  // send_invitation: false stores it unsent (status 'not_sent'); rejects with DirectoryError",
+        "({ email, name, group_ids? }) => Promise<Invite>  // rejects with DirectoryError",
       deactivate: "(userId) => Promise<User>  // rejects with DirectoryError",
       reactivate: "(userId) => Promise<User>  // rejects with DirectoryError",
       remove: "(userId) => Promise<void>  // rejects with DirectoryError",
@@ -1833,8 +1827,7 @@ const HOOKS = [
   // sc-5097 — pending AppUser invite administration. Returns
   // `{ invites, loading, error, refetch, resend, revoke }`. Reads need
   // `invites.read:*`; resend/revoke need `invites.write:*` plus the
-  // caller's `users.write` SystemAcl capability. sc-9714: `resend` is also
-  // the first send of a `not_sent` invite — there is no separate `send`.
+  // caller's `users.write` SystemAcl capability.
   {
     name: "useInvites",
     signature: "useInvites(query)",
@@ -1844,23 +1837,13 @@ const HOOKS = [
       "directory-client at ctx.directory.invites.{list,resend,revoke}. " +
       "Returns { invites, loading, error, refetch, resend, revoke }. list " +
       "returns the { data, meta } envelope verbatim — the hook unwraps " +
-      "res.data; rows are snake_case (email, status, sent_at, expires_at, …) " +
-      "and status is the server-computed pending/accepted/revoked/expired/" +
-      "not_sent value. not_sent is an invitation created with " +
-      "send_invitation: false that has not been emailed yet: its sent_at is " +
-      "null, it cannot be accepted until it is sent, and its expires_at " +
-      "means nothing yet, so show no expiry for it. resend(inviteId) is the " +
-      "ONE call that sends an invitation — the first send of a not_sent one " +
-      "and a repeat send of a sent one alike: it emails the invitee, stamps " +
-      "sent_at, restarts the 7-day expiry and resolves the row with status " +
-      "'pending'. There is no separate send method; label the button " +
-      "'Send invitation' on a not_sent row and 'Resend' on a pending one. " +
-      "query is { status?, q?, app_user_id?, limit?, offset? } passed " +
+      "res.data; rows are snake_case (email, status, expires_at, …) and " +
+      "status is the server-computed pending/accepted/revoked/expired " +
+      "value. query is { status?, q?, app_user_id?, limit?, offset? } passed " +
       "verbatim; the endpoint defaults to status 'all', so pass " +
-      "{ status: 'pending' } for the usual outstanding-invite list and " +
-      "{ status: 'not_sent' } for the prepared ones; " +
-      "status 'open' is every invite neither accepted nor revoked (pending, " +
-      "not_sent or expired). q is a " +
+      "{ status: 'pending' } for the usual outstanding-invite list; " +
+      "status 'open' is every invite neither accepted nor revoked (pending " +
+      "or expired). q is a " +
       "case-insensitive substring match on the invite's name or email. " +
       "Each row's app_user_id is the id the invitee's user account will " +
       "have once they accept; a USER column may already hold it, and " +
@@ -1877,12 +1860,12 @@ const HOOKS = [
       "refetch on success.",
     returnShape: {
       invites:
-        "Array<{ id, app_user_id, email, name, group_ids, status, sent_at, expires_at, accepted_at, revoked_at, created_at }>  // snake_case rows; status is pending | accepted | revoked | expired | not_sent; unwrapped from { data, meta }",
+        "Array<{ id, app_user_id, email, name, group_ids, status, expires_at, accepted_at, revoked_at, created_at }>  // snake_case rows; unwrapped from { data, meta }",
       loading: "boolean",
       error: "DirectoryError | null  // { code, message, retryable }",
       refetch: "() => Promise<void>",
       resend:
-        "(inviteId) => Promise<Invite>  // sends it (first send of a not_sent invite too); refetches; rejects with DirectoryError",
+        "(inviteId) => Promise<Invite>  // refetches; rejects with DirectoryError",
       revoke:
         "(inviteId) => Promise<void>  // refetches; rejects with DirectoryError",
     },
@@ -2060,6 +2043,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:
@@ -3042,7 +3032,7 @@ const WIDGET_CONTEXT_SHAPE = {
       "groups: { list(query?) -> Promise<{ data, meta }>, create(body), remove(id), addMember(groupId, userId), removeMember(groupId, userId), listMine() }, " +
       "invites: { list(), revoke(id), resend(id) }, " +
       "bankid: { status() -> { linked, available }, startLink() -> { order_ref, qr, ... }, collect(orderRef), cancel(orderRef), unlink() } }. " +
-      "users backs useDirectory() + useUsers(); groups backs useGroups(); invites backs useInvites() (list/resend/revoke invites — resend also sends one created with send_invitation: false — gated by users.write:* + the users.write capability); bankid backs useBankIdLink() (REQ-BANKID-AUTH — self-service account linking, JWT-gated, no widget scope). List methods return the { data, meta } envelope verbatim (hooks unwrap res.data); rows/bodies are snake_case. Reads gated by directory.read:users / users.read:* / groups.read:*; mutations by users.write:* / groups.write:* (destructive user removal by users.delete:*).",
+      "users backs useDirectory() + useUsers(); groups backs useGroups(); invites backs useInvites() (list/resend/revoke pending invites, gated by users.write:* + the users.write capability); bankid backs useBankIdLink() (REQ-BANKID-AUTH — self-service account linking, JWT-gated, no widget scope). List methods return the { data, meta } envelope verbatim (hooks unwrap res.data); rows/bodies are snake_case. Reads gated by directory.read:users / users.read:* / groups.read:*; mutations by users.write:* / groups.write:* (destructive user removal by users.delete:*).",
     required: true,
     fields: { users: "object", groups: "object", invites: "object", bankid: "object" },
   },
@@ -5070,7 +5060,14 @@ 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.
+  // 1.155.0: narrowing (sc-10566) — withdraws 1.144.0: `useUsers().invite`
+  //    takes no `send_invitation` and always emails, invite rows carry no
+  //    `sent_at`, and `not_sent` is no longer a status.
+  version: "1.155.0",
   sharedTranslationKeys: SHARED_TRANSLATION_KEYS,
   hooks: HOOKS,
   primitives: PRIMITIVES,

package/dist/contract.js

@@ -1749,9 +1749,8 @@ const HOOKS = [
   // deactivate / reactivate / sendPasswordReset) additionally need
   // `users.write:*`, and the
   // destructive `remove` needs `users.delete:*` (SC-902). The `invite`
-  // call accepts `{ email, name, group_ids?, send_invitation? }` and returns
-  // the resulting AppUserInvite row (the host sends the email, unless
-  // `send_invitation` is false). Mutating users from
+  // call accepts `{ email, name, groupIds? }` and returns the resulting
+  // AppUserInvite row (the email is sent by the host). Mutating users from
   // a widget requires the corresponding SystemAcl capability grant in the
   // tenant (`users.write` for edits, `users.delete` for removal); widgets
   // that only call read methods need only `users.read:*`.
@@ -1769,13 +1768,8 @@ const HOOKS = [
       "scope; edit-style mutations (invite/deactivate/reactivate/" +
       "sendPasswordReset) need users.write:*, and the destructive remove() " +
       "additionally needs users.delete:* (SC-902). The `invite` call accepts " +
-      "{ email, name, group_ids?, send_invitation? } and returns the resulting " +
-      "AppUserInvite row { id, email, name, expires_at, sent_at, status }. " +
-      "The host emails the invitation at once unless send_invitation is " +
-      "false: then nothing is emailed, the row comes back with sent_at null " +
-      "and status 'not_sent', and useInvites().resend(inviteId) sends it " +
-      "later. A send_invitation that is not a boolean rejects with " +
-      "DirectoryError code VALIDATION. sendPasswordReset(userId) mails the " +
+      "{ email, name, group_ids? } and returns the resulting AppUserInvite row " +
+      "(the email is sent by the host). sendPasswordReset(userId) mails the " +
       "standard self-serve reset link to that user's own registered address " +
       "and resolves { sent, email_masked } — never the token or the link, so " +
       "it cannot be used to sign in as them. It rejects with a DirectoryError " +
@@ -1788,7 +1782,7 @@ const HOOKS = [
       error: "DirectoryError | null  // { code, message, retryable }",
       refetch: "() => Promise<void>",
       invite:
-        "({ email, name, group_ids?, send_invitation? }) => Promise<Invite>  // send_invitation: false stores it unsent (status 'not_sent'); rejects with DirectoryError",
+        "({ email, name, group_ids? }) => Promise<Invite>  // rejects with DirectoryError",
       deactivate: "(userId) => Promise<User>  // rejects with DirectoryError",
       reactivate: "(userId) => Promise<User>  // rejects with DirectoryError",
       remove: "(userId) => Promise<void>  // rejects with DirectoryError",
@@ -1833,8 +1827,7 @@ const HOOKS = [
   // sc-5097 — pending AppUser invite administration. Returns
   // `{ invites, loading, error, refetch, resend, revoke }`. Reads need
   // `invites.read:*`; resend/revoke need `invites.write:*` plus the
-  // caller's `users.write` SystemAcl capability. sc-9714: `resend` is also
-  // the first send of a `not_sent` invite — there is no separate `send`.
+  // caller's `users.write` SystemAcl capability.
   {
     name: "useInvites",
     signature: "useInvites(query)",
@@ -1844,23 +1837,13 @@ const HOOKS = [
       "directory-client at ctx.directory.invites.{list,resend,revoke}. " +
       "Returns { invites, loading, error, refetch, resend, revoke }. list " +
       "returns the { data, meta } envelope verbatim — the hook unwraps " +
-      "res.data; rows are snake_case (email, status, sent_at, expires_at, …) " +
-      "and status is the server-computed pending/accepted/revoked/expired/" +
-      "not_sent value. not_sent is an invitation created with " +
-      "send_invitation: false that has not been emailed yet: its sent_at is " +
-      "null, it cannot be accepted until it is sent, and its expires_at " +
-      "means nothing yet, so show no expiry for it. resend(inviteId) is the " +
-      "ONE call that sends an invitation — the first send of a not_sent one " +
-      "and a repeat send of a sent one alike: it emails the invitee, stamps " +
-      "sent_at, restarts the 7-day expiry and resolves the row with status " +
-      "'pending'. There is no separate send method; label the button " +
-      "'Send invitation' on a not_sent row and 'Resend' on a pending one. " +
-      "query is { status?, q?, app_user_id?, limit?, offset? } passed " +
+      "res.data; rows are snake_case (email, status, expires_at, …) and " +
+      "status is the server-computed pending/accepted/revoked/expired " +
+      "value. query is { status?, q?, app_user_id?, limit?, offset? } passed " +
       "verbatim; the endpoint defaults to status 'all', so pass " +
-      "{ status: 'pending' } for the usual outstanding-invite list and " +
-      "{ status: 'not_sent' } for the prepared ones; " +
-      "status 'open' is every invite neither accepted nor revoked (pending, " +
-      "not_sent or expired). q is a " +
+      "{ status: 'pending' } for the usual outstanding-invite list; " +
+      "status 'open' is every invite neither accepted nor revoked (pending " +
+      "or expired). q is a " +
       "case-insensitive substring match on the invite's name or email. " +
       "Each row's app_user_id is the id the invitee's user account will " +
       "have once they accept; a USER column may already hold it, and " +
@@ -1877,12 +1860,12 @@ const HOOKS = [
       "refetch on success.",
     returnShape: {
       invites:
-        "Array<{ id, app_user_id, email, name, group_ids, status, sent_at, expires_at, accepted_at, revoked_at, created_at }>  // snake_case rows; status is pending | accepted | revoked | expired | not_sent; unwrapped from { data, meta }",
+        "Array<{ id, app_user_id, email, name, group_ids, status, expires_at, accepted_at, revoked_at, created_at }>  // snake_case rows; unwrapped from { data, meta }",
       loading: "boolean",
       error: "DirectoryError | null  // { code, message, retryable }",
       refetch: "() => Promise<void>",
       resend:
-        "(inviteId) => Promise<Invite>  // sends it (first send of a not_sent invite too); refetches; rejects with DirectoryError",
+        "(inviteId) => Promise<Invite>  // refetches; rejects with DirectoryError",
       revoke:
         "(inviteId) => Promise<void>  // refetches; rejects with DirectoryError",
     },
@@ -2060,6 +2043,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:
@@ -3038,7 +3028,7 @@ const WIDGET_CONTEXT_SHAPE = {
       "groups: { list(query?) -> Promise<{ data, meta }>, create(body), remove(id), addMember(groupId, userId), removeMember(groupId, userId), listMine() }, " +
       "invites: { list(), revoke(id), resend(id) }, " +
       "bankid: { status() -> { linked, available }, startLink() -> { order_ref, qr, ... }, collect(orderRef), cancel(orderRef), unlink() } }. " +
-      "users backs useDirectory() + useUsers(); groups backs useGroups(); invites backs useInvites() (list/resend/revoke invites — resend also sends one created with send_invitation: false — gated by users.write:* + the users.write capability); bankid backs useBankIdLink() (REQ-BANKID-AUTH — self-service account linking, JWT-gated, no widget scope). List methods return the { data, meta } envelope verbatim (hooks unwrap res.data); rows/bodies are snake_case. Reads gated by directory.read:users / users.read:* / groups.read:*; mutations by users.write:* / groups.write:* (destructive user removal by users.delete:*).",
+      "users backs useDirectory() + useUsers(); groups backs useGroups(); invites backs useInvites() (list/resend/revoke pending invites, gated by users.write:* + the users.write capability); bankid backs useBankIdLink() (REQ-BANKID-AUTH — self-service account linking, JWT-gated, no widget scope). List methods return the { data, meta } envelope verbatim (hooks unwrap res.data); rows/bodies are snake_case. Reads gated by directory.read:users / users.read:* / groups.read:*; mutations by users.write:* / groups.write:* (destructive user removal by users.delete:*).",
     required: true,
     fields: { users: "object", groups: "object", invites: "object", bankid: "object" },
   },
@@ -5066,7 +5056,14 @@ 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.
+  // 1.155.0: narrowing (sc-10566) — withdraws 1.144.0: `useUsers().invite`
+  //    takes no `send_invitation` and always emails, invite rows carry no
+  //    `sent_at`, and `not_sent` is no longer a status.
+  version: "1.155.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,
@@ -5534,7 +5539,7 @@ export function useDirectory(query) {
  * invite, deactivate, reactivate}` — `list` resolves to the `{ data, meta }`
  * envelope VERBATIM, so we unwrap `res.data` (default `[]`). User rows are
  * snake_case (`id`, `name`, `email`, `role`, `is_active`, …) and bodies
- * (e.g. `{ email, name, group_ids?, send_invitation? }`) pass through verbatim. `query` is an
+ * (e.g. `{ email, name, group_ids? }`) pass through verbatim. `query` is an
  * optional `{ q?, role?, is_active?, group_id?, limit?, offset? }`; `group_id`
  * (the `id` of a `useGroups()` row) narrows the list to that group's members.
  * The list refetches whenever `JSON.stringify(query)` changes; the imperative methods
@@ -5771,20 +5776,15 @@ export function useGroups(query) {
  * `{ data, meta }` envelope VERBATIM, so we unwrap `res.data` (default `[]`).
  *
  * Rows are snake_case exactly as the backend projects them: `{ id, tenant_id,
- * email, name, group_ids, status, sent_at, expires_at, accepted_at,
- * revoked_at, created_at, invited_by_studio_user_id }`. `status` is the
- * server-computed lifecycle value (`"pending" | "accepted" | "revoked" |
- * "expired" | "not_sent"`) — prefer it over re-deriving expiry on the client,
- * whose clock may disagree.
- *
- * `not_sent` is an invite created with `send_invitation: false`: `sent_at` is
- * null and nothing was emailed. `resend(inviteId)` is the one call that sends
- * — a first send and a repeat send alike — and resolves the row as `pending`.
+ * email, name, group_ids, status, expires_at, accepted_at, revoked_at,
+ * created_at, invited_by_studio_user_id }`. `status` is the server-computed
+ * lifecycle value (`"pending" | "accepted" | "revoked" | "expired"`) — prefer
+ * it over re-deriving expiry on the client, whose clock may disagree.
  *
  * `query` is an optional `{ status?, limit?, offset? }` passed through
  * verbatim; `status` accepts `"pending" | "accepted" | "revoked" | "expired" |
- * "not_sent" | "all"` and the endpoint defaults to `"all"`, so pass
- * `{ status: "pending" }` for the usual "who hasn't accepted yet" list.
+ * "all"` and the endpoint defaults to `"all"`, so pass `{ status: "pending" }`
+ * for the usual "who hasn't accepted yet" list.
  *
  * The WHOLE invite surface — list included — is gated on the `users.write`
  * capability plus a signed `users.write:*` scope: a pending invite exposes
@@ -5851,8 +5851,7 @@ export function useInvites(query) {
   }, [doFetch]);
 
   // Both mutations re-list on success: revoking drops the row and resending
-  // moves `expires_at` (and a first send's status), so a stale list would
-  // show the operator the old state.
+  // moves `expires_at`, so a stale list would show the operator the old state.
   const resend = useCallback(
     async (inviteId) => {
       try {

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,
@@ -2436,25 +2442,13 @@ export interface InviteArgs {
   email: string;
   name?: string;
   group_ids?: string[];
-  /**
-   * Defaults to `true`: the invitation is emailed at once. `false` stores it
-   * without emailing anyone (`status: "not_sent"`); send it later with
-   * `useInvites().resend(inviteId)`.
-   */
-  send_invitation?: boolean;
 }
 
-/**
- * When several apply the first of accepted, revoked, not_sent, expired,
- * pending wins. `not_sent` is an invitation created with
- * `send_invitation: false` that has not been emailed yet.
- */
 export type AppUserInviteStatus =
   | "pending"
   | "accepted"
   | "revoked"
-  | "expired"
-  | "not_sent";
+  | "expired";
 
 export interface AppUserInviteRow {
   id: string;
@@ -2469,9 +2463,7 @@ export interface AppUserInviteRow {
   status: AppUserInviteStatus;
   name?: string;
   group_ids?: string[];
-  /** When the invitation email last left; `null` until it is first sent. */
-  sent_at: string | null;
-  /** Meaningless while `status` is `"not_sent"` — it restarts on the send. */
+  invited_at?: string;
   expires_at?: string;
   accepted_at?: string | null;
   revoked_at?: string | null;
@@ -2540,9 +2532,8 @@ export function useGroups(query?: GroupsQuery): GroupsApi;
 
 export interface InvitesQuery {
   /**
-   * Defaults to "all" server-side; pass "pending" for outstanding invites and
-   * "not_sent" for the ones prepared but not emailed yet.
-   * "open" is "pending", "not_sent" or "expired": neither accepted nor revoked.
+   * Defaults to "all" server-side; pass "pending" for outstanding invites.
+   * "open" is "pending" or "expired": neither accepted nor revoked.
    */
   status?: AppUserInviteStatus | "open" | "all";
   /** Case-insensitive substring match on the invite's name or email. */
@@ -2563,12 +2554,7 @@ export interface InvitesApi {
   loading: boolean;
   error: DirectoryError | null;
   refetch(): Promise<void>;
-  /**
-   * Email the invitation and restart its 7-day expiry. The one call that
-   * sends: the first send of a `not_sent` invitation and a repeat send of a
-   * sent one alike. Resolves the row with `status: "pending"`; refetches on
-   * success.
-   */
+  /** Re-send the invitation email. Refetches on success. */
   resend(inviteId: string): Promise<AppUserInviteRow>;
   /** Cancel a pending invitation. Refetches on success. */
   revoke(inviteId: string): Promise<void>;

package/package.json

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

@@ -1749,9 +1749,8 @@ const HOOKS = [
   // deactivate / reactivate / sendPasswordReset) additionally need
   // `users.write:*`, and the
   // destructive `remove` needs `users.delete:*` (SC-902). The `invite`
-  // call accepts `{ email, name, group_ids?, send_invitation? }` and returns
-  // the resulting AppUserInvite row (the host sends the email, unless
-  // `send_invitation` is false). Mutating users from
+  // call accepts `{ email, name, groupIds? }` and returns the resulting
+  // AppUserInvite row (the email is sent by the host). Mutating users from
   // a widget requires the corresponding SystemAcl capability grant in the
   // tenant (`users.write` for edits, `users.delete` for removal); widgets
   // that only call read methods need only `users.read:*`.
@@ -1769,13 +1768,8 @@ const HOOKS = [
       "scope; edit-style mutations (invite/deactivate/reactivate/" +
       "sendPasswordReset) need users.write:*, and the destructive remove() " +
       "additionally needs users.delete:* (SC-902). The `invite` call accepts " +
-      "{ email, name, group_ids?, send_invitation? } and returns the resulting " +
-      "AppUserInvite row { id, email, name, expires_at, sent_at, status }. " +
-      "The host emails the invitation at once unless send_invitation is " +
-      "false: then nothing is emailed, the row comes back with sent_at null " +
-      "and status 'not_sent', and useInvites().resend(inviteId) sends it " +
-      "later. A send_invitation that is not a boolean rejects with " +
-      "DirectoryError code VALIDATION. sendPasswordReset(userId) mails the " +
+      "{ email, name, group_ids? } and returns the resulting AppUserInvite row " +
+      "(the email is sent by the host). sendPasswordReset(userId) mails the " +
       "standard self-serve reset link to that user's own registered address " +
       "and resolves { sent, email_masked } — never the token or the link, so " +
       "it cannot be used to sign in as them. It rejects with a DirectoryError " +
@@ -1788,7 +1782,7 @@ const HOOKS = [
       error: "DirectoryError | null  // { code, message, retryable }",
       refetch: "() => Promise<void>",
       invite:
-        "({ email, name, group_ids?, send_invitation? }) => Promise<Invite>  // send_invitation: false stores it unsent (status 'not_sent'); rejects with DirectoryError",
+        "({ email, name, group_ids? }) => Promise<Invite>  // rejects with DirectoryError",
       deactivate: "(userId) => Promise<User>  // rejects with DirectoryError",
       reactivate: "(userId) => Promise<User>  // rejects with DirectoryError",
       remove: "(userId) => Promise<void>  // rejects with DirectoryError",
@@ -1833,8 +1827,7 @@ const HOOKS = [
   // sc-5097 — pending AppUser invite administration. Returns
   // `{ invites, loading, error, refetch, resend, revoke }`. Reads need
   // `invites.read:*`; resend/revoke need `invites.write:*` plus the
-  // caller's `users.write` SystemAcl capability. sc-9714: `resend` is also
-  // the first send of a `not_sent` invite — there is no separate `send`.
+  // caller's `users.write` SystemAcl capability.
   {
     name: "useInvites",
     signature: "useInvites(query)",
@@ -1844,23 +1837,13 @@ const HOOKS = [
       "directory-client at ctx.directory.invites.{list,resend,revoke}. " +
       "Returns { invites, loading, error, refetch, resend, revoke }. list " +
       "returns the { data, meta } envelope verbatim — the hook unwraps " +
-      "res.data; rows are snake_case (email, status, sent_at, expires_at, …) " +
-      "and status is the server-computed pending/accepted/revoked/expired/" +
-      "not_sent value. not_sent is an invitation created with " +
-      "send_invitation: false that has not been emailed yet: its sent_at is " +
-      "null, it cannot be accepted until it is sent, and its expires_at " +
-      "means nothing yet, so show no expiry for it. resend(inviteId) is the " +
-      "ONE call that sends an invitation — the first send of a not_sent one " +
-      "and a repeat send of a sent one alike: it emails the invitee, stamps " +
-      "sent_at, restarts the 7-day expiry and resolves the row with status " +
-      "'pending'. There is no separate send method; label the button " +
-      "'Send invitation' on a not_sent row and 'Resend' on a pending one. " +
-      "query is { status?, q?, app_user_id?, limit?, offset? } passed " +
+      "res.data; rows are snake_case (email, status, expires_at, …) and " +
+      "status is the server-computed pending/accepted/revoked/expired " +
+      "value. query is { status?, q?, app_user_id?, limit?, offset? } passed " +
       "verbatim; the endpoint defaults to status 'all', so pass " +
-      "{ status: 'pending' } for the usual outstanding-invite list and " +
-      "{ status: 'not_sent' } for the prepared ones; " +
-      "status 'open' is every invite neither accepted nor revoked (pending, " +
-      "not_sent or expired). q is a " +
+      "{ status: 'pending' } for the usual outstanding-invite list; " +
+      "status 'open' is every invite neither accepted nor revoked (pending " +
+      "or expired). q is a " +
       "case-insensitive substring match on the invite's name or email. " +
       "Each row's app_user_id is the id the invitee's user account will " +
       "have once they accept; a USER column may already hold it, and " +
@@ -1877,12 +1860,12 @@ const HOOKS = [
       "refetch on success.",
     returnShape: {
       invites:
-        "Array<{ id, app_user_id, email, name, group_ids, status, sent_at, expires_at, accepted_at, revoked_at, created_at }>  // snake_case rows; status is pending | accepted | revoked | expired | not_sent; unwrapped from { data, meta }",
+        "Array<{ id, app_user_id, email, name, group_ids, status, expires_at, accepted_at, revoked_at, created_at }>  // snake_case rows; unwrapped from { data, meta }",
       loading: "boolean",
       error: "DirectoryError | null  // { code, message, retryable }",
       refetch: "() => Promise<void>",
       resend:
-        "(inviteId) => Promise<Invite>  // sends it (first send of a not_sent invite too); refetches; rejects with DirectoryError",
+        "(inviteId) => Promise<Invite>  // refetches; rejects with DirectoryError",
       revoke:
         "(inviteId) => Promise<void>  // refetches; rejects with DirectoryError",
     },
@@ -2060,6 +2043,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:
@@ -3038,7 +3028,7 @@ const WIDGET_CONTEXT_SHAPE = {
       "groups: { list(query?) -> Promise<{ data, meta }>, create(body), remove(id), addMember(groupId, userId), removeMember(groupId, userId), listMine() }, " +
       "invites: { list(), revoke(id), resend(id) }, " +
       "bankid: { status() -> { linked, available }, startLink() -> { order_ref, qr, ... }, collect(orderRef), cancel(orderRef), unlink() } }. " +
-      "users backs useDirectory() + useUsers(); groups backs useGroups(); invites backs useInvites() (list/resend/revoke invites — resend also sends one created with send_invitation: false — gated by users.write:* + the users.write capability); bankid backs useBankIdLink() (REQ-BANKID-AUTH — self-service account linking, JWT-gated, no widget scope). List methods return the { data, meta } envelope verbatim (hooks unwrap res.data); rows/bodies are snake_case. Reads gated by directory.read:users / users.read:* / groups.read:*; mutations by users.write:* / groups.write:* (destructive user removal by users.delete:*).",
+      "users backs useDirectory() + useUsers(); groups backs useGroups(); invites backs useInvites() (list/resend/revoke pending invites, gated by users.write:* + the users.write capability); bankid backs useBankIdLink() (REQ-BANKID-AUTH — self-service account linking, JWT-gated, no widget scope). List methods return the { data, meta } envelope verbatim (hooks unwrap res.data); rows/bodies are snake_case. Reads gated by directory.read:users / users.read:* / groups.read:*; mutations by users.write:* / groups.write:* (destructive user removal by users.delete:*).",
     required: true,
     fields: { users: "object", groups: "object", invites: "object", bankid: "object" },
   },
@@ -5066,7 +5056,14 @@ 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.
+  // 1.155.0: narrowing (sc-10566) — withdraws 1.144.0: `useUsers().invite`
+  //    takes no `send_invitation` and always emails, invite rows carry no
+  //    `sent_at`, and `not_sent` is no longer a status.
+  version: "1.155.0",
   sharedTranslationKeys: SHARED_TRANSLATION_KEYS,
   hooks: HOOKS,
   primitives: PRIMITIVES,