@colixsystems/widget-sdk 0.260.0 → 0.262.0

package/src/contract.js

@@ -2155,6 +2155,41 @@ const HOOKS = [
     requiredContextSlice: ["agents.conversations"],
     scopes: ["ai.invoke:*"],
   },
+  {
+    name: "useAction",
+    signature: "useAction(actionRef)",
+    description:
+      "sc-13843 — run one of the WORKSPACE's Actions (a server-side script) " +
+      "and read what it returned. IMPERATIVE: call run(input) from an event " +
+      "handler, never on mount or in render — an Action can write data and " +
+      "send messages, so placing a widget must not run it. run resolves with " +
+      "the value the Action passed to respond() (any JSON, or null when it " +
+      "responded with nothing) and `result` holds the last one. The Action " +
+      "must carry the app trigger, or the server refuses the run with " +
+      "ACTION_NOT_APP_INVOKABLE — the same gate a Button's Run action meets. " +
+      "`actionRef` is an Action id an author bound through an `actionRef` " +
+      "property — when it is missing, or the host brokers no actions client, " +
+      "`available` is false and run() rejects UNAVAILABLE; render a visible " +
+      "'pick an action' state, NEVER a blank box. A changed binding clears " +
+      "`result` and `error`, and a run that settles after the binding changed " +
+      "(or after unmount) writes nothing. ActionError.code: " +
+      "INVALID_ACTION_INPUT (400) — the input was refused; " +
+      "ACTION_NOT_APP_INVOKABLE (403) and ACTION_NOT_FOUND (404) will NOT " +
+      "clear on a retry, so hide the affordance; RATE_LIMITED (429) will; " +
+      "ACTION_FAILED — the Action ran and failed, or no answer arrived. NEVER " +
+      "show an app user a raw error. A text answer from a bot is often " +
+      "MARKDOWN, so render it with <RichText value={result} />, not <Text>. " +
+      "Reads ctx.actions.",
+    returnShape: {
+      available: "boolean  // false when no Action is bound, or the host brokers none",
+      run: "(input) => Promise<unknown>  // input is optional; resolves with the Action's respond() value, or null; rejects with ActionError",
+      running: "boolean  // true while any run is in flight",
+      result: "unknown  // the last successful run's result; null before the first run",
+      error: "ActionError | null",
+    },
+    requiredContextSlice: ["actions.run"],
+    scopes: ["actions.run:*"],
+  },
   {
     name: "useDatastoreMutation",
     signature: "useDatastoreMutation(tableId)",
@@ -3725,6 +3760,8 @@ const ACTION_SCRIPT_GLOBALS = [
   "triggeredBy",
   // sc-9031 — a Run action event's parameters; null on every other trigger.
   "input",
+  // sc-13843 — hands the app run its one JSON result.
+  "respond",
 ];
 // Mirrors action.service.js SCRIPT_MAX_BYTES.
 const ACTION_SCRIPT_MAX_BYTES = 200 * 1024;
@@ -3878,7 +3915,7 @@ const MANIFEST_SCHEMA = {
     type: "boolean",
     required: false,
     description:
-      "Optional (default false). TRUE when every platform entry also exports useBadgeCount(props): a hook returning the count the widget puts on its page's menu entry with usePageBadge, so the app keeps that badge live while the page is closed. The host runs counters for installed marketplace widgets (the workspace's own published widgets included); the platform's built-in widgets declare none. It calls the hook with the instance's resolved props, inside the widget's own context; the hook returns a whole number, or null while the count is not known yet. It only reads, and the host enforces that: the counter's datastore and directory expose only their read methods (plus realtime subscriptions) and notification mutes only get/list, while writes, typing signals, payments, notifications.send, files, assets, AI agents, translation, link previews, device capabilities, identification and account actions all answer as unavailable. It also renders nothing, navigates nowhere, emits no events or toasts, marks nothing read, and calls none of usePageBadge, useScreenTitle, useSectionEmpty or useWidgetRoute's setter. The linter refuses a declared counter whose entry has no useBadgeCount export. The AppStudio widget agent leaves this unset: a generated widget never declares a badge counter.",
+      "Optional (default false). TRUE when every platform entry also exports useBadgeCount(props): a hook returning the count the widget puts on its page's menu entry with usePageBadge, so the app keeps that badge live while the page is closed. The host runs counters for installed marketplace widgets (the workspace's own published widgets included); the platform's built-in widgets declare none. It calls the hook with the instance's resolved props, inside the widget's own context; the hook returns a whole number, or null while the count is not known yet. It only reads, and the host enforces that: the counter's datastore and directory expose only their read methods (plus realtime subscriptions) and notification mutes only get/list, while writes, typing signals, payments, notifications.send, files, assets, AI agents, translation, link previews, device capabilities, identification, account actions and Actions (useAction) all answer as unavailable. It also renders nothing, navigates nowhere, emits no events or toasts, marks nothing read, and calls none of usePageBadge, useScreenTitle, useSectionEmpty or useWidgetRoute's setter. The linter refuses a declared counter whose entry has no useBadgeCount export. The AppStudio widget agent leaves this unset: a generated widget never declares a badge counter.",
     default: false,
   },
   prefersFitToScreen: {
@@ -4079,6 +4116,17 @@ const WIDGET_CONTEXT_SHAPE = {
     required: false,
     fields: { conversations: "function" },
   },
+  actions: {
+    description:
+      "sc-13843 — injected @colixsystems/actions-client instance. " +
+      "{ run(actionId, input?) -> Promise<{ ok, result }> }. Backs useAction(). " +
+      "Runs one Action as the signed-in caller; the server refuses an Action " +
+      "without the app trigger. Errors carry the server's `code` and `status`. " +
+      "Absent on a host that brokers no actions client, where useAction() " +
+      "degrades to available: false rather than throwing.",
+    required: false,
+    fields: { run: "function" },
+  },
   linkPreviews: {
     description:
       "Injected @colixsystems/link-preview-client instance. { get(url) -> Promise<{ url, title, description, site_name, image_url }> }. " +
@@ -6376,7 +6424,10 @@ const CONTRACT = deepFreeze({
   //    initials when its picture fails to load. No API change.
   // 1.211.0: additive (sc-9168) — `maxFontSizeMultiplier`: native `<Text>` /
   //    `<TextInput>` follow the device font scale up to this bound.
-  version: "1.211.0",
+  // 1.212.0: additive (sc-13843) — `useAction(actionRef)` + the `actions` host
+  //    client + the `actionRef` propertySchema type + the `actions.run:*`
+  //    scope. A widget runs one of the workspace's Actions and reads its result.
+  version: "1.212.0",
   sharedTranslationKeys: SHARED_TRANSLATION_KEYS,
   hooks: HOOKS,
   primitives: PRIMITIVES,