@colixsystems/widget-sdk 0.141.0 → 0.142.0

package/README.md

@@ -70,7 +70,26 @@ See the design reference for the full architecture: [`docs/architecture/widget-m
 
 ## Status
 
-`v0.141.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.142.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.142.0 (contract 1.110.0)
+
+**An action script can finally tell WHO started the run — `triggeredBy` joins `CONTRACT.actionScriptGlobals` (sc-7885).** The identity was already captured (the run history has recorded an `actorId` since REQ-ACTION-RUNLOG) but never reached the sandbox, so a script could do the work and not attribute it: no "X submitted this" notification back to the submitter, no audit row naming the actor. Authors worked around it by writing the user id into a record first and switching to a `record_*` trigger — plumbing in the app's data model, and not available to a plain button press at all.
+
+```js
+if (triggeredBy && triggeredBy.type === "app_user") {
+  await notifications.notifyUser(triggeredBy.id, {
+    title: "Request received",
+    body: "Thanks " + triggeredBy.name + ", we have started on it.",
+  });
+}
+```
+
+- The shape is `{ type, id, name, email, role }`, frozen, or **`null` when nothing initiated the run** — a `schedule` tick or a `record_*` event. `null` is the normal case for the automation triggers, so guard before reading it.
+- **`type` is load-bearing, not decoration.** It is `"app_user"` on an `app` button press and an `http_post` webhook, and `"studio_user"` on an operator's Run now. One id column, two directories behind it: check `type` before handing the id to `notifications.notifyUser` or a USER column, or a studio user's id will silently resolve to nobody. `role` carries the app-user vocabulary (`USER` / `INTEGRATION`) and is `null` for a studio user, whose workspace role is a different axis entirely. `email` is likewise `null` for a studio user: nothing in a script can address an operator, so shipping their real address to an installed third-party Action would be PII with no consumer.
+- **It grants nothing.** The script still runs as the Action's bound integration identity, exactly as before; `triggeredBy` describes the caller and does not widen the data the script can reach. Resolution is host-side and tenant-scoped, so a stale or foreign id resolves to `null` rather than leaking a row across workspaces.
+- Actions never render, so this has **no effect on Player ↔ export parity** (CLAUDE.md §8).
+- Also in this release: **`properties` was added to `CONTRACT.actionScriptGlobals`**, which the `@colixsystems/action-sdk` copy of the list had carried since 1.50.0 while this one had not — the two hand-mirrored lists had drifted. A parity test now pins them together. `CONTRACT.version` → `1.110.0`. Additive for every existing manifest and script.
 
 ### What's new in 0.141.0 (contract 1.109.0)
 

package/dist/contract.cjs

@@ -1990,12 +1990,23 @@ const ACTION_TRIGGER_TYPES = [
 // Globals the action script runs against (the runner's surface) — distinct
 // from the React/SDK widget surface, so the component import/banned-API
 // linter does NOT scan action scripts.
+// sc-7877 deliberately does NOT add `directory` here. That global is
+// reachable only by a MARKETPLACE action whose install consented to a
+// `directory:` scope; a widget-declared action has no install, so
+// resolveForActionRow grants it nothing and the global is never defined.
 const ACTION_SCRIPT_GLOBALS = [
   "datastore",
   "secrets",
+  // Was missing here while action-sdk listed it — the two hand-mirrored lists
+  // had drifted. action-script-globals-parity.test.cjs now pins them together.
+  "properties",
   "fetch",
   "connectors",
   "notifications",
+  // Conditionally defined — only when the install consented to a `directory:`
+  // scope. Added to the WIDGET-sdk copy here: sc-7891 put it in the action-sdk
+  // list alone, the same drift this commit's parity test now catches.
+  "directory",
   "console",
   "record",
   // sc-5366 — `{ body }` on a run fired by the inbound `http_post` trigger,
@@ -2004,6 +2015,8 @@ const ACTION_SCRIPT_GLOBALS = [
   "tenantId",
   "triggerType",
   "triggerTableId",
+  // sc-7885 — who initiated the run; null on `schedule` / `record_*`.
+  "triggeredBy",
 ];
 // Mirrors action.service.js SCRIPT_MAX_BYTES.
 const ACTION_SCRIPT_MAX_BYTES = 200 * 1024;
@@ -3970,7 +3983,16 @@ const CONTRACT = deepFreeze({
   //    and the sc-7352 backfill deletes the stored key (a bottom-tabs app's
   //    strip becomes the sidebar's quick bar) BEFORE this ships.
   //    `menuItemCap` / `quickBarCap` keep their signatures.
-  version: "1.109.0",
+  // 1.110.0: additive (sc-7885) — `triggeredBy` joins `actionScriptGlobals`:
+  //    WHO initiated this run, as `{ type, id, name, email, role }`, or `null`
+  //    on `schedule` / `record_*` where nothing did. `type` is `"app_user"` (an
+  //    `app` button press or an `http_post` webhook) or `"studio_user"` (an
+  //    operator's Run now) — load-bearing, because those are two different
+  //    directories behind one id. The script still runs as the Action's bound
+  //    integration identity; this describes the caller, it does not grant
+  //    anything. The same commit adds `properties` to this list, which the
+  //    action-sdk copy had carried since 1.50.0 while this one had not.
+  version: "1.110.0",
   sharedTranslationKeys: SHARED_TRANSLATION_KEYS,
   hooks: HOOKS,
   primitives: PRIMITIVES,

package/dist/contract.js

@@ -1993,9 +1993,16 @@ const ACTION_TRIGGER_TYPES = [
 const ACTION_SCRIPT_GLOBALS = [
   "datastore",
   "secrets",
+  // Was missing here while action-sdk listed it — the two hand-mirrored lists
+  // had drifted. action-script-globals-parity.test.cjs now pins them together.
+  "properties",
   "fetch",
   "connectors",
   "notifications",
+  // Conditionally defined — only when the install consented to a `directory:`
+  // scope. Added to the WIDGET-sdk copy here: sc-7891 put it in the action-sdk
+  // list alone, the same drift this commit's parity test now catches.
+  "directory",
   "console",
   "record",
   // sc-5366 — `{ body }` on a run fired by the inbound `http_post` trigger,
@@ -2004,6 +2011,8 @@ const ACTION_SCRIPT_GLOBALS = [
   "tenantId",
   "triggerType",
   "triggerTableId",
+  // sc-7885 — who initiated the run; null on `schedule` / `record_*`.
+  "triggeredBy",
 ];
 // Mirrors action.service.js SCRIPT_MAX_BYTES.
 const ACTION_SCRIPT_MAX_BYTES = 200 * 1024;
@@ -3970,7 +3979,16 @@ const CONTRACT = deepFreeze({
   //    and the sc-7352 backfill deletes the stored key (a bottom-tabs app's
   //    strip becomes the sidebar's quick bar) BEFORE this ships.
   //    `menuItemCap` / `quickBarCap` keep their signatures.
-  version: "1.109.0",
+  // 1.110.0: additive (sc-7885) — `triggeredBy` joins `actionScriptGlobals`:
+  //    WHO initiated this run, as `{ type, id, name, email, role }`, or `null`
+  //    on `schedule` / `record_*` where nothing did. `type` is `"app_user"` (an
+  //    `app` button press or an `http_post` webhook) or `"studio_user"` (an
+  //    operator's Run now) — load-bearing, because those are two different
+  //    directories behind one id. The script still runs as the Action's bound
+  //    integration identity; this describes the caller, it does not grant
+  //    anything. The same commit adds `properties` to this list, which the
+  //    action-sdk copy had carried since 1.50.0 while this one had not.
+  version: "1.110.0",
   sharedTranslationKeys: SHARED_TRANSLATION_KEYS,
   hooks: HOOKS,
   primitives: PRIMITIVES,

package/package.json

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