@colixsystems/widget-sdk 0.89.0 → 0.90.0

package/README.md

@@ -61,7 +61,7 @@ See the design reference for the full architecture: [`docs/architecture/widget-m
 
 ## Status
 
-`v0.89.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.90.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.89.0 (contract unchanged)
 
@@ -172,6 +172,10 @@ See the design reference for the full architecture: [`docs/architecture/widget-m
 - **The colour maths ignores alpha, on purpose.** `hexChannels` reads the R/G/B pair and skips any alpha, so contrast, readable text and the derived accent tints reason about the opaque colour. None of them can composite without knowing the backdrop, which a token table does not have — so transparency lives in the VALUE your widget renders, not in the decision about whether that colour reads as light or dark.
 - **`CONTRACT.version` → `1.61.0`** (additive: `themeTokens.spacingScale` + `widgetStyles` and their bounds, `themeComponents.card.universalFields`, and the `normaliseWidgetStyles` / `deriveSurfaceTokens` host exports). No author-facing export changed signature, and a theme that sets none of it resolves exactly as before.
 
+### What's new in 0.90.0 (contract 1.63.0)
+
+**A manifest action declares `triggerTypes` — a set — and the script learns which one fired (sc-4915).** An action could carry exactly one trigger, so a widget that needed the same work done on create *and* on delete had to ship the script twice: two `actions` entries, two operator bindings, two run histories, and the usual drift between the copies. `triggerTypes` replaces `triggerType`: a non-empty array of unique values from `schedule`, `record_created`, `record_updated`, `record_deleted`, freely combined (`scheduleCron` is required iff the array contains `schedule`). The pre-0.90.0 scalar `triggerType` is still read and normalised into the array, so a widget already published against it keeps validating and nothing needs republishing. What makes the combination useful is the other half: the script's `triggerType` global now names the trigger that **actually fired this run** — including `"manual"` (an operator's Run now) and `"app"` (a button press) — instead of echoing the row's configuration, so one script can branch on whether its record was created or deleted. `CONTRACT.version` → `1.63.0`. Additive for every existing manifest.
+
 ### What's new in 0.85.1 (contract 1.60.1)
 
 **`useWidgetEvent(name)` returns the emitter FUNCTION — the declared contract said otherwise (sc-4753).** `CONTRACT.hooks`'s entry for the hook declared `returnShape: { emit }`, so every surface derived from it — chiefly the Widget Builder Agent's hooks table — told authors the hook resolves to an object. It never did: `useWidgetEvent("slotChosen")` hands back the callable you invoke directly (`emitSlot({ courtId })`), exactly as the typings and the Developer guide have always documented. A widget written against the declared shape destructured a function, got `undefined`, and threw the moment a user interacted — a cross-widget wire that rendered perfectly and only failed on click. The declaration is now a bare callable and the publish-time render harness models the same shape, so a wrong destructure is caught instead of waved through. `CONTRACT.version` → `1.60.1`. Documentation-only correction: no export, signature, or runtime behaviour changed — a widget already calling the result is unaffected.
@@ -619,7 +623,7 @@ Two additive features land in this version.
 
 **A widget may declare server-side actions in its manifest.**
 
-- **`WidgetManifest.actions` is now part of the public contract.** An optional array; each entry is `{ key, name, description?, triggerType, scheduleCron?, timeoutMs?, scriptSource }`. `triggerType` is one of `schedule`, `record_created`, `record_updated`, `record_deleted`; `scheduleCron` is required when `triggerType === "schedule"`. The `scriptSource` (≤ 200 KiB) runs in the **shared isolated-vm action runner** — against `datastore` / `fetch` / `connectors` / `console` / `record` / `tenantId` (the runner surface, **not** the React/SDK widget surface, so SDK imports and hooks are unavailable there and the component linter does not scan it). `connectors.call(slug, { method, path, query, body, headers })` resolves a tenant-configured REST connector by slug and returns `{ status, headers, body }` (auth + SSRF handled by the platform; an unknown slug / SSRF / timeout throws a catchable Error). Actions never run in the rendered app, so they have **no effect on Player ↔ export parity**.
+- **`WidgetManifest.actions` is now part of the public contract.** An optional array; each entry is `{ key, name, description?, triggerTypes, scheduleCron?, timeoutMs?, scriptSource }`. `triggerTypes` is a non-empty array of unique values from `schedule`, `record_created`, `record_updated`, `record_deleted` — combine them so one script serves several events; `scheduleCron` is required when it contains `schedule`. The `scriptSource` (≤ 200 KiB) runs in the **shared isolated-vm action runner** — against `datastore` / `fetch` / `connectors` / `console` / `record` / `tenantId` (the runner surface, **not** the React/SDK widget surface, so SDK imports and hooks are unavailable there and the component linter does not scan it). `connectors.call(slug, { method, path, query, body, headers })` resolves a tenant-configured REST connector by slug and returns `{ status, headers, body }` (auth + SSRF handled by the platform; an unknown slug / SSRF / timeout throws a catchable Error). Actions never run in the rendered app, so they have **no effect on Player ↔ export parity**.
 - **Operators enable actions per tenant** from the Properties Panel. An enabled action materialises a tenant `Action` row **DISABLED** until the operator binds an integration API key (and, for `record_*` triggers, a target table) in the Actions admin page — those bindings are tenant-local, so `triggerTableId` / `apiKeyId` must **not** appear in the manifest (the validator and linter reject them).
 - **New contract fields** `CONTRACT.actionTriggerTypes`, `CONTRACT.actionScriptGlobals`, `CONTRACT.actionScriptMaxBytes` expose the grammar so the Developer page, the AI agent prompt, and `validateManifest` derive it from one source. `validateManifest` now structurally validates `actions`; the marketplace linter rejects malformed / oversized declarations.
 - **New manifest category `ADMINISTRATION`** for app-administration widgets such as User Management. Added to `CONTRACT.manifestCategories`, `validateManifest`, the `WidgetCategory` type, the marketplace category list, and the master-DB `WidgetCategory` enum.

package/dist/contract.cjs

@@ -1373,6 +1373,34 @@ const ACTION_SCRIPT_GLOBALS = [
 // Mirrors action.service.js SCRIPT_MAX_BYTES.
 const ACTION_SCRIPT_MAX_BYTES = 200 * 1024;
 
+/**
+ * sc-4915 — the trigger set a manifest action declares, canonically ordered.
+ *
+ * `triggerTypes` is the current shape; the pre-sc-4915 scalar `triggerType` is
+ * still read so a widget published before the change keeps validating. Returns
+ * null when the declaration is empty, holds an unknown value, or repeats one —
+ * every caller reports that as a manifest error. ONE reader, so the SDK
+ * validator, the CLI linter and the backend cannot disagree about what a
+ * manifest declared.
+ */
+function normaliseActionTriggerTypes(action) {
+  const a = action !== null && typeof action === "object" ? action : {};
+  const raw = Array.isArray(a.triggerTypes)
+    ? a.triggerTypes
+    : a.triggerTypes === undefined && a.triggerType !== undefined
+      ? [a.triggerType]
+      : null;
+  if (raw === null || raw.length === 0) return null;
+  const seen = new Set();
+  for (const t of raw) {
+    if (typeof t !== "string" || !ACTION_TRIGGER_TYPES.includes(t)) return null;
+    if (seen.has(t)) return null;
+    seen.add(t);
+  }
+  return ACTION_TRIGGER_TYPES.filter((t) => seen.has(t));
+}
+
+
 // Reverse-DNS-ish manifest id, e.g. "com.acme.charts.barchart". Two or
 // more labels, lowercase alnum + hyphen, label starts with a letter. The
 // analyzer + the SDK validator both read this from the contract so a
@@ -1501,9 +1529,9 @@ const MANIFEST_SCHEMA = {
     type: "object[]",
     required: false,
     description:
-      "Optional. Server-side actions the widget declares. Each runs in the shared isolated-vm action runner (cron- or record-triggered) — NEVER in the rendered app. Operators enable them per tenant from the Properties Panel; the action materialises DISABLED until they bind an integration API key (and, for record_* triggers, a target table) in the Actions admin page. Each entry: { key (stable, unique within the manifest), name, description?, triggerType (one of " +
+      "Optional. Server-side actions the widget declares. Each runs in the shared isolated-vm action runner (cron- or record-triggered) — NEVER in the rendered app. Operators enable them per tenant from the Properties Panel; the action materialises DISABLED until they bind an integration API key (and, for record_* triggers, a target table) in the Actions admin page. Each entry: { key (stable, unique within the manifest), name, description?, triggerTypes (a non-empty array of unique values from " +
       ACTION_TRIGGER_TYPES.join(", ") +
-      "), scheduleCron? (required iff triggerType=='schedule'; node-cron syntax), timeoutMs? (100–300000), scriptSource (≤200 KiB; runs against " +
+      "; combine them so one script serves several events — the script's `triggerType` global names the event that actually fired), scheduleCron? (required iff triggerTypes contains 'schedule'; node-cron syntax), timeoutMs? (100–300000), scriptSource (≤200 KiB; runs against " +
       ACTION_SCRIPT_GLOBALS.join(", ") +
       " — NOT the React surface, so SDK imports/hooks are unavailable) }. Do NOT include triggerTableId or apiKeyId — those are tenant-local and bound after install.",
     default: [],
@@ -2787,7 +2815,14 @@ const CONTRACT = deepFreeze({
   //    Naming one widget is strictly more specific than restyling a scope, and
   //    the Properties Panel stays the final word. Additive throughout: a theme
   //    that sets none of it resolves exactly as before.
-  version: "1.62.0",
+  // 1.63.0: additive (sc-4915) — a manifest action declares `triggerTypes`, a
+  //    non-empty ARRAY, so one script can serve a create, an update and a
+  //    delete instead of being copied into three actions. The pre-sc-4915
+  //    scalar `triggerType` is still read and normalised, so an already
+  //    published widget keeps validating. The script's `triggerType` global
+  //    now names the trigger that actually FIRED the run ('manual' and 'app'
+  //    included), which is what makes a multi-trigger script able to branch.
+  version: "1.63.0",
   sharedTranslationKeys: SHARED_TRANSLATION_KEYS,
   hooks: HOOKS,
   primitives: PRIMITIVES,
@@ -3073,6 +3108,7 @@ module.exports = {
   CONTRACT,
   clampSpacingScale,
   scaleSpacing,
+  normaliseActionTriggerTypes,
   isHookAllowed,
   requiredContextKeys,
   isHexColor,

package/dist/contract.js

@@ -1373,6 +1373,34 @@ const ACTION_SCRIPT_GLOBALS = [
 // Mirrors action.service.js SCRIPT_MAX_BYTES.
 const ACTION_SCRIPT_MAX_BYTES = 200 * 1024;
 
+/**
+ * sc-4915 — the trigger set a manifest action declares, canonically ordered.
+ *
+ * `triggerTypes` is the current shape; the pre-sc-4915 scalar `triggerType` is
+ * still read so a widget published before the change keeps validating. Returns
+ * null when the declaration is empty, holds an unknown value, or repeats one —
+ * every caller reports that as a manifest error. ONE reader, so the SDK
+ * validator, the CLI linter and the backend cannot disagree about what a
+ * manifest declared.
+ */
+function normaliseActionTriggerTypes(action) {
+  const a = action !== null && typeof action === "object" ? action : {};
+  const raw = Array.isArray(a.triggerTypes)
+    ? a.triggerTypes
+    : a.triggerTypes === undefined && a.triggerType !== undefined
+      ? [a.triggerType]
+      : null;
+  if (raw === null || raw.length === 0) return null;
+  const seen = new Set();
+  for (const t of raw) {
+    if (typeof t !== "string" || !ACTION_TRIGGER_TYPES.includes(t)) return null;
+    if (seen.has(t)) return null;
+    seen.add(t);
+  }
+  return ACTION_TRIGGER_TYPES.filter((t) => seen.has(t));
+}
+
+
 // Reverse-DNS-ish manifest id, e.g. "com.acme.charts.barchart". Two or
 // more labels, lowercase alnum + hyphen, label starts with a letter. The
 // analyzer + the SDK validator both read this from the contract so a
@@ -1501,9 +1529,9 @@ const MANIFEST_SCHEMA = {
     type: "object[]",
     required: false,
     description:
-      "Optional. Server-side actions the widget declares. Each runs in the shared isolated-vm action runner (cron- or record-triggered) — NEVER in the rendered app. Operators enable them per tenant from the Properties Panel; the action materialises DISABLED until they bind an integration API key (and, for record_* triggers, a target table) in the Actions admin page. Each entry: { key (stable, unique within the manifest), name, description?, triggerType (one of " +
+      "Optional. Server-side actions the widget declares. Each runs in the shared isolated-vm action runner (cron- or record-triggered) — NEVER in the rendered app. Operators enable them per tenant from the Properties Panel; the action materialises DISABLED until they bind an integration API key (and, for record_* triggers, a target table) in the Actions admin page. Each entry: { key (stable, unique within the manifest), name, description?, triggerTypes (a non-empty array of unique values from " +
       ACTION_TRIGGER_TYPES.join(", ") +
-      "), scheduleCron? (required iff triggerType=='schedule'; node-cron syntax), timeoutMs? (100–300000), scriptSource (≤200 KiB; runs against " +
+      "; combine them so one script serves several events — the script's `triggerType` global names the event that actually fired), scheduleCron? (required iff triggerTypes contains 'schedule'; node-cron syntax), timeoutMs? (100–300000), scriptSource (≤200 KiB; runs against " +
       ACTION_SCRIPT_GLOBALS.join(", ") +
       " — NOT the React surface, so SDK imports/hooks are unavailable) }. Do NOT include triggerTableId or apiKeyId — those are tenant-local and bound after install.",
     default: [],
@@ -2787,7 +2815,14 @@ const CONTRACT = deepFreeze({
   //    Naming one widget is strictly more specific than restyling a scope, and
   //    the Properties Panel stays the final word. Additive throughout: a theme
   //    that sets none of it resolves exactly as before.
-  version: "1.62.0",
+  // 1.63.0: additive (sc-4915) — a manifest action declares `triggerTypes`, a
+  //    non-empty ARRAY, so one script can serve a create, an update and a
+  //    delete instead of being copied into three actions. The pre-sc-4915
+  //    scalar `triggerType` is still read and normalised, so an already
+  //    published widget keeps validating. The script's `triggerType` global
+  //    now names the trigger that actually FIRED the run ('manual' and 'app'
+  //    included), which is what makes a multi-trigger script able to branch.
+  version: "1.63.0",
   sharedTranslationKeys: SHARED_TRANSLATION_KEYS,
   hooks: HOOKS,
   primitives: PRIMITIVES,
@@ -3073,6 +3108,7 @@ export {
   CONTRACT,
   clampSpacingScale,
   scaleSpacing,
+  normaliseActionTriggerTypes,
   isHookAllowed,
   requiredContextKeys,
   isHexColor,

package/dist/index.d.ts

@@ -223,18 +223,23 @@ export interface WidgetManifestAction {
   key: string;
   name: string;
   description?: string;
-  triggerType:
-    | "schedule"
-    | "record_created"
-    | "record_updated"
-    | "record_deleted";
-  /** Required iff `triggerType === "schedule"`. node-cron syntax. */
+  /**
+   * sc-4915 — a non-empty set of unique triggers. Combine them so one script
+   * serves several events; the script's `triggerType` global names the one
+   * that actually fired.
+   */
+  triggerTypes: Array<
+    "schedule" | "record_created" | "record_updated" | "record_deleted"
+  >;
+  /** Required iff `triggerTypes` contains `"schedule"`. node-cron syntax. */
   scheduleCron?: string;
   /** 100–300000. Defaults to 30000 on materialise. */
   timeoutMs?: number;
   /**
    * Runs against `datastore`, `fetch`, `console`, `record`, `tenantId`,
    * `triggerType`, `triggerTableId` — NOT the React/SDK surface. ≤ 200 KiB.
+   * `triggerType` is the trigger that fired THIS run — one of the declared
+   * `triggerTypes`, or `"manual"` / `"app"` for an operator or button run.
    */
   scriptSource: string;
 }

package/dist/linter.cjs

@@ -10,7 +10,7 @@
 
 "use strict";
 
-const { CONTRACT } = require("./contract.cjs");
+const { CONTRACT, normaliseActionTriggerTypes } = require("./contract.cjs");
 const { LUCIDE_ICON_NAMES, LUCIDE_VERSION } = require("./lucideIconNames.cjs");
 
 function _ruleForIdentifier(identifier, reason) {
@@ -579,10 +579,11 @@ function _manifestActionRules(manifest) {
     if (typeof a.name !== "string" || a.name.length === 0) {
       push("manifest.actions[].name must be a non-empty string");
     }
-    if (!validTriggers.has(a.triggerType)) {
-      push(`manifest.actions[].triggerType must be one of ${[...validTriggers].join(", ")}`);
-    } else if (a.triggerType === "schedule" && (typeof a.scheduleCron !== "string" || !a.scheduleCron)) {
-      push("manifest.actions[].scheduleCron is required when triggerType is 'schedule'");
+    const triggerTypes = normaliseActionTriggerTypes(a);
+    if (triggerTypes === null) {
+      push(`manifest.actions[].triggerTypes must be a non-empty array of unique values from ${[...validTriggers].join(", ")}`);
+    } else if (triggerTypes.includes("schedule") && (typeof a.scheduleCron !== "string" || !a.scheduleCron)) {
+      push("manifest.actions[].scheduleCron is required when triggerTypes contains 'schedule'");
     }
     if (typeof a.scriptSource !== "string" || a.scriptSource.length === 0) {
       push("manifest.actions[].scriptSource must be a non-empty string");

package/dist/linter.js

@@ -6,7 +6,7 @@
 // The banned-identifier list is derived from `CONTRACT.bannedApis` so the
 // system prompt, the linter, and the runtime allowlist agree.
 
-import { CONTRACT } from "./contract.js";
+import { CONTRACT, normaliseActionTriggerTypes } from "./contract.js";
 import { LUCIDE_ICON_NAMES, LUCIDE_VERSION } from "./lucideIconNames.js";
 
 // Per-identifier match rule. Most banned identifiers compile to a
@@ -674,16 +674,17 @@ function _manifestActionRules(manifest) {
     if (typeof a.name !== "string" || a.name.length === 0) {
       push("manifest.actions[].name must be a non-empty string");
     }
-    if (!validTriggers.has(a.triggerType)) {
+    const triggerTypes = normaliseActionTriggerTypes(a);
+    if (triggerTypes === null) {
       push(
-        `manifest.actions[].triggerType must be one of ${[...validTriggers].join(", ")}`,
+        `manifest.actions[].triggerTypes must be a non-empty array of unique values from ${[...validTriggers].join(", ")}`,
       );
     } else if (
-      a.triggerType === "schedule" &&
+      triggerTypes.includes("schedule") &&
       (typeof a.scheduleCron !== "string" || !a.scheduleCron)
     ) {
       push(
-        "manifest.actions[].scheduleCron is required when triggerType is 'schedule'",
+        "manifest.actions[].scheduleCron is required when triggerTypes contains 'schedule'",
       );
     }
     if (typeof a.scriptSource !== "string" || a.scriptSource.length === 0) {

package/dist/manifest.cjs

@@ -4,7 +4,7 @@
 // re-exports the same functions defined here so there is exactly one
 // implementation.
 
-const { CONTRACT } = require("./contract.cjs");
+const { CONTRACT, normaliseActionTriggerTypes } = require("./contract.cjs");
 
 const PAYLOAD_VALUE_TYPES = CONTRACT.payloadValueTypes;
 
@@ -152,15 +152,16 @@ function validateManifestActions(actions, errors) {
       seenKeys.add(a.key);
     }
     pushIf(errors, isNonEmptyString(a.name), "manifest.actions[].name must be a non-empty string");
-    if (!VALID_ACTION_TRIGGERS.has(a.triggerType)) {
+    const triggerTypes = normaliseActionTriggerTypes(a);
+    if (triggerTypes === null) {
       errors.push(
-        `manifest.actions[].triggerType must be one of ${[...VALID_ACTION_TRIGGERS].join(", ")}`,
+        `manifest.actions[].triggerTypes must be a non-empty array of unique values from ${[...VALID_ACTION_TRIGGERS].join(", ")}`,
       );
-    } else if (a.triggerType === "schedule") {
+    } else if (triggerTypes.includes("schedule")) {
       pushIf(
         errors,
         isNonEmptyString(a.scheduleCron),
-        "manifest.actions[].scheduleCron is required when triggerType is 'schedule'",
+        "manifest.actions[].scheduleCron is required when triggerTypes contains 'schedule'",
       );
     }
     if (!isNonEmptyString(a.scriptSource)) {

package/dist/manifest.js

@@ -4,7 +4,7 @@
 // re-exports the same functions defined here so there is exactly one
 // implementation.
 
-import { CONTRACT } from "./contract.js";
+import { CONTRACT, normaliseActionTriggerTypes } from "./contract.js";
 
 const PAYLOAD_VALUE_TYPES = CONTRACT.payloadValueTypes;
 
@@ -152,15 +152,16 @@ function validateManifestActions(actions, errors) {
       seenKeys.add(a.key);
     }
     pushIf(errors, isNonEmptyString(a.name), "manifest.actions[].name must be a non-empty string");
-    if (!VALID_ACTION_TRIGGERS.has(a.triggerType)) {
+    const triggerTypes = normaliseActionTriggerTypes(a);
+    if (triggerTypes === null) {
       errors.push(
-        `manifest.actions[].triggerType must be one of ${[...VALID_ACTION_TRIGGERS].join(", ")}`,
+        `manifest.actions[].triggerTypes must be a non-empty array of unique values from ${[...VALID_ACTION_TRIGGERS].join(", ")}`,
       );
-    } else if (a.triggerType === "schedule") {
+    } else if (triggerTypes.includes("schedule")) {
       pushIf(
         errors,
         isNonEmptyString(a.scheduleCron),
-        "manifest.actions[].scheduleCron is required when triggerType is 'schedule'",
+        "manifest.actions[].scheduleCron is required when triggerTypes contains 'schedule'",
       );
     }
     if (!isNonEmptyString(a.scriptSource)) {

package/package.json

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