@colixsystems/widget-sdk 0.291.0 → 0.292.0

package/README.md

@@ -90,7 +90,11 @@ See the design reference for the full architecture: [`docs/architecture/widget-m
 
 ## Status
 
-`v0.291.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.292.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.292.0 (contract 1.239.0)
+
+**An Action a widget runs must be done 250 ms after the press.** The time counts from when the press reaches the server, so waiting for a free sandbox and setting the run up spend from it too. A run started by `useAction()` (or a Button's Run action) that is still going then is stopped, and `run()` rejects with `ACTION_TIMEOUT` (504). Its outcome is unknown: open requests and connector calls are cut and no new work starts, but a write that had already finished stays, and a notification already sent can't be recalled. So an Action the app waits on must do its writes as one call (a bulk write) or be safe to repeat, and never tell the user it did nothing. Move slow or multi-step work to an Action triggered by a record the widget writes. Scheduled, record-triggered and Run now runs keep their own limits.
 
 ### What's new in 0.291.0 (contract 1.238.0)
 
@@ -299,7 +303,7 @@ const { available, run, running, result, error } = useAction(props.actionId);
 
 **Bind it with an `actionRef` property.** Declare `{ type: "actionRef" }` in your `propertySchema` and the Studio renders an Action picker that warns when the chosen Action lacks the app trigger. The value is a bare Action id, so Copy Workspace remaps it like `pageRef`.
 
-When nothing is bound, 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 the widget unmounted writes nothing. When runs overlap, `result` and `error` follow the newest one. Branch on `error.code`: `ACTION_NOT_APP_INVOKABLE` and `ACTION_NOT_FOUND` will not clear on a retry, `RATE_LIMITED` will, `INVALID_ACTION_INPUT` means the input was refused, `AUTH_REQUIRED`, `TOKEN_EXPIRED` and `TOKEN_INVALID` mean the app user must sign in, and `ACTION_FAILED` means the Action ran and failed. Never show an app user the raw message. A text answer from a bot is often markdown, so render it with `<RichText>`.
+When nothing is bound, 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 the widget unmounted writes nothing. When runs overlap, `result` and `error` follow the newest one. Branch on `error.code`: `ACTION_NOT_APP_INVOKABLE` and `ACTION_NOT_FOUND` will not clear on a retry, `RATE_LIMITED` will, `INVALID_ACTION_INPUT` means the input was refused, `AUTH_REQUIRED`, `TOKEN_EXPIRED` and `TOKEN_INVALID` mean the app user must sign in, `ACTION_FAILED` means the Action ran and failed, and `ACTION_TIMEOUT` means it was still running 250 ms after the press and was stopped, so its outcome is unknown: some of its writes may have happened. Never show an app user the raw message. A text answer from a bot is often markdown, so render it with `<RichText>`.
 
 The linter rejects `useAction()` unless your manifest declares `actions.run:*` in `requestedScopes`.
 

package/dist/contract.cjs

@@ -2285,6 +2285,12 @@ const HOOKS = [
       "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_TIMEOUT (504) — the run was still going 250 ms after the press " +
+      "and was stopped, so its OUTCOME IS UNKNOWN: some of its writes may " +
+      "have happened. Never retry it blindly and never tell the user it did " +
+      "nothing; an Action a widget runs must do its writes as one call or be " +
+      "safe to repeat, and slow or multi-step work belongs in a " +
+      "record-triggered Action; " +
       "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>. " +
@@ -6805,7 +6811,10 @@ const CONTRACT = deepFreeze({
   // 1.238.0: additive (sc-15659) — `useConnector(connectorRef)` + the
   //    `connectors` host client + the `connectorRef` propertySchema type + the
   //    `connectors.call:*` scope. A widget calls a REST connector's listed operations.
-  version: "1.238.0",
+  // 1.239.0: additive (sc-15658) — an app-triggered run must finish within 250 ms
+  //    of the press; `useAction` errors carry the new code ACTION_TIMEOUT
+  //    (504), whose outcome is unknown.
+  version: "1.239.0",
   sharedTranslationKeys: SHARED_TRANSLATION_KEYS,
   hooks: HOOKS,
   primitives: PRIMITIVES,

package/dist/contract.js

@@ -2281,6 +2281,12 @@ const HOOKS = [
       "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_TIMEOUT (504) — the run was still going 250 ms after the press " +
+      "and was stopped, so its OUTCOME IS UNKNOWN: some of its writes may " +
+      "have happened. Never retry it blindly and never tell the user it did " +
+      "nothing; an Action a widget runs must do its writes as one call or be " +
+      "safe to repeat, and slow or multi-step work belongs in a " +
+      "record-triggered Action; " +
       "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>. " +
@@ -6801,7 +6807,10 @@ const CONTRACT = deepFreeze({
   // 1.238.0: additive (sc-15659) — `useConnector(connectorRef)` + the
   //    `connectors` host client + the `connectorRef` propertySchema type + the
   //    `connectors.call:*` scope. A widget calls a REST connector's listed operations.
-  version: "1.238.0",
+  // 1.239.0: additive (sc-15658) — an app-triggered run must finish within 250 ms
+  //    of the press; `useAction` errors carry the new code ACTION_TIMEOUT
+  //    (504), whose outcome is unknown.
+  version: "1.239.0",
   sharedTranslationKeys: SHARED_TRANSLATION_KEYS,
   hooks: HOOKS,
   primitives: PRIMITIVES,

package/dist/index.d.ts

@@ -3513,6 +3513,7 @@ export class ActionError extends Error {
     | "AUTH_REQUIRED"
     | "TOKEN_EXPIRED"
     | "TOKEN_INVALID"
+    | "ACTION_TIMEOUT"
     | "ACTION_FAILED"
     | (string & {});
   constructor(code: string, message: string, opts?: { cause?: unknown });

package/package.json

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

@@ -2281,6 +2281,12 @@ const HOOKS = [
       "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_TIMEOUT (504) — the run was still going 250 ms after the press " +
+      "and was stopped, so its OUTCOME IS UNKNOWN: some of its writes may " +
+      "have happened. Never retry it blindly and never tell the user it did " +
+      "nothing; an Action a widget runs must do its writes as one call or be " +
+      "safe to repeat, and slow or multi-step work belongs in a " +
+      "record-triggered Action; " +
       "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>. " +
@@ -6801,7 +6807,10 @@ const CONTRACT = deepFreeze({
   // 1.238.0: additive (sc-15659) — `useConnector(connectorRef)` + the
   //    `connectors` host client + the `connectorRef` propertySchema type + the
   //    `connectors.call:*` scope. A widget calls a REST connector's listed operations.
-  version: "1.238.0",
+  // 1.239.0: additive (sc-15658) — an app-triggered run must finish within 250 ms
+  //    of the press; `useAction` errors carry the new code ACTION_TIMEOUT
+  //    (504), whose outcome is unknown.
+  version: "1.239.0",
   sharedTranslationKeys: SHARED_TRANSLATION_KEYS,
   hooks: HOOKS,
   primitives: PRIMITIVES,