@colixsystems/widget-sdk 0.81.0 → 0.82.0

package/README.md

@@ -62,6 +62,14 @@ See the design reference for the full architecture: [`docs/architecture/widget-m
 
 `v0.77.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.82.0 (contract 1.57.0)
+
+**Server-action scripts can notify a record's permission subjects (REQ-ACTION-NOTIFY-SUBJECTS, sc-4586).** `await notifications.notifyRecordSubjects(tableId, recordId, { title, body, link, emit_email, emit_push, exclude_user_id })` resolves to `{ recipients }` and notifies every app user whose per-record grant lets them **read** that record. This addresses the one audience the other two primitives cannot name: when membership *is* the ACL, there is no recipient column to read. The Chat widget is the case in point — a channel's participants ARE that channel record's grants, so neither a `recipient_expr` (which resolves only a fixed id or a single user/group reference column) nor a `notifyUser` loop over a column that does not exist can reach them. Subject kinds follow REQ-ACL-09: a `user` grant notifies its user, a `group` grant expands through its memberships, and the two synthetic kinds (`authenticated`, `everyone`) are skipped because they address the whole workspace rather than a membership. Recipients are **deduplicated**, so someone reachable through both a direct grant and a granted group is notified once, and `exclude_user_id` drops one — pass the author so nobody is notified of their own write. Dispatch goes through the same `notifyUser` path as before, so the always-written inbox row, the preference-gated email + push mirrors, the link sanitiser and the title/body caps are inherited unchanged, and written rows count toward the same per-run cap of 500. The tenant is bound host-side and the table/record pair is verified against it, so a foreign or missing id resolves to `{ recipients: 0 }` rather than distinguishing "absent" from "not yours". **The script never receives the member list — only the count.** `CONTRACT.version` → `1.57.0`. Additive; no widget hook, primitive, manifest field, or token changed shape.
+
+### 0.82.0 also carries (contract 1.56.0)
+
+**Server-action scripts gain a `notifications` global (REQ-ACTION-NOTIFY, sc-4514).** A `scriptSource` action can now send a real notification to a recipient it resolves at run time: `await notifications.notifyUser(userId, { title, body, link, emit_email, emit_push })` and `await notifications.notifyGroup(groupId, opts)`. Options are **snake_case**, matching every other shape a script sees. `notifyUser` resolves to the created notification row (or `null` when the recipient was skipped); `notifyGroup` resolves to `{ recipients }`. This is a directness change rather than a new capability: an action could already notify indirectly by writing into a table carrying an enabled `NotificationRule`, but that costs a throwaway table, a per-table rule, a recipient expressible only as a fixed id or one reference column — and it fails silently, since with no rule attached the row just lands and the run still reports success. `POST /notifications/send` is no alternative (it needs an app-user JWT an action cannot hold). The direct call removes the intermediary and makes a non-delivery throw. Both methods delegate to the platform's one notification dispatch path, so the inbox row is always written, the email + push mirrors respect the recipient's channel preferences, and the push ping never carries the title or body. The tenant is bound host-side: a recipient in another workspace, a soft-deleted group, or a deactivated user is a silent skip, never a cross-tenant write. A blank `title`, a non-string `body`, or exceeding the per-run cap of 500 written notifications throws a catchable Error. New entry in `CONTRACT.actionScriptGlobals`; `CONTRACT.version` → `1.56.0`. Additive — no widget hook, primitive, manifest field, or token changed shape.
+
 ### What's new in 0.78.0
 
 **New `useIdentification()` hook — identify a visitor who is NOT signed in (REQ-IDENT, sc-4313).** A new IDENTIFICATION hook reading a newly-injected `ctx.identification` slice (the new `@colixsystems/identification-client`, constructed by both the web Player and the native Expo export). Returns `{ available, availabilityLoading, status, qr, autoStartToken, message, identity, identificationId, loading, error, start, refresh, cancel, reset }`.

package/dist/contract.cjs

@@ -1269,6 +1269,7 @@ const ACTION_SCRIPT_GLOBALS = [
   "secrets",
   "fetch",
   "connectors",
+  "notifications",
   "console",
   "record",
   "tenantId",
@@ -2506,7 +2507,24 @@ const CONTRACT = deepFreeze({
   //    already measured its own box with onLayout; this promotes that one
   //    pattern to the SDK so custom and marketplace widgets get it too,
   //    instead of each rolling its own.
-  version: "1.55.0",
+  // 1.55.0: additive (sc-4505) — `useWidgetInput(inputName)` + the
+  //    `PAYLOAD_VALUE_TYPES` a widget event payload field may declare, so
+  //    widgets on one page relate through declared inputs.
+  // 1.56.0: additive (sc-4514) — `notifications` joins
+  //    `actionScriptGlobals`. `notifications.notifyUser(id, opts)` /
+  //    `notifyGroup(id, opts)` delegate to the one notification dispatch path.
+  //    Directness, not a new capability: an action could already notify by
+  //    writing into a table carrying a NotificationRule, but that needs a
+  //    throwaway table plus a per-table rule and fails SILENTLY when no rule
+  //    is attached — the row lands and the run still reports success.
+  // 1.57.0: additive (sc-4586) — `notifications.notifyRecordSubjects(tableId,
+  //    recordId, opts)`, resolving to { recipients }. Notifies whoever a
+  //    record's per-record grants let read it, which is the only way to address
+  //    membership-by-ACL: a Chat channel's participants ARE its grants, so no
+  //    `recipient_expr` shape and no recipient column can name them. The member
+  //    list stays host-side — a script receives a count, never the ids — and
+  //    `exclude_user_id` keeps an author off their own message.
+  version: "1.57.0",
   sharedTranslationKeys: SHARED_TRANSLATION_KEYS,
   hooks: HOOKS,
   primitives: PRIMITIVES,

package/dist/contract.js

@@ -1269,6 +1269,7 @@ const ACTION_SCRIPT_GLOBALS = [
   "secrets",
   "fetch",
   "connectors",
+  "notifications",
   "console",
   "record",
   "tenantId",
@@ -2506,7 +2507,24 @@ const CONTRACT = deepFreeze({
   //    already measured its own box with onLayout; this promotes that one
   //    pattern to the SDK so custom and marketplace widgets get it too,
   //    instead of each rolling its own.
-  version: "1.55.0",
+  // 1.55.0: additive (sc-4505) — `useWidgetInput(inputName)` + the
+  //    `PAYLOAD_VALUE_TYPES` a widget event payload field may declare, so
+  //    widgets on one page relate through declared inputs.
+  // 1.56.0: additive (sc-4514) — `notifications` joins
+  //    `actionScriptGlobals`. `notifications.notifyUser(id, opts)` /
+  //    `notifyGroup(id, opts)` delegate to the one notification dispatch path.
+  //    Directness, not a new capability: an action could already notify by
+  //    writing into a table carrying a NotificationRule, but that needs a
+  //    throwaway table plus a per-table rule and fails SILENTLY when no rule
+  //    is attached — the row lands and the run still reports success.
+  // 1.57.0: additive (sc-4586) — `notifications.notifyRecordSubjects(tableId,
+  //    recordId, opts)`, resolving to { recipients }. Notifies whoever a
+  //    record's per-record grants let read it, which is the only way to address
+  //    membership-by-ACL: a Chat channel's participants ARE its grants, so no
+  //    `recipient_expr` shape and no recipient column can name them. The member
+  //    list stays host-side — a script receives a count, never the ids — and
+  //    `exclude_user_id` keeps an author off their own message.
+  version: "1.57.0",
   sharedTranslationKeys: SHARED_TRANSLATION_KEYS,
   hooks: HOOKS,
   primitives: PRIMITIVES,

package/package.json

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