@colixsystems/widget-sdk 0.267.1 → 0.268.0

package/README.md

@@ -86,7 +86,11 @@ See the design reference for the full architecture: [`docs/architecture/widget-m
 
 ## Status
 
-`v0.267.1` — 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.268.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.268.0 (contract 1.218.0)
+
+**`useAction().available` tells the truth about the Action.** It used to be true whenever an Action was bound, so a widget offered a run that could never happen. It now turns false once the server says a run would not reach the script: the Action is switched off or paused, not allowed from the app, gone, or the viewer is not a signed-in app user (signed-out visitors and anonymous accounts can't run Actions). It is asked again when the binding or the signed-in user changes, and stays true while no answer has come. The actions client (`@colixsystems/actions-client` 0.2.0) gains `status(actionId)` for it.
 
 ### What's new in 0.267.1 (contract 1.217.0)
 

package/dist/contract.cjs

@@ -2184,7 +2184,12 @@ const HOOKS = [
       "`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 " +
+      "'pick an action' state, NEVER a blank box. sc-14224: `available` also " +
+      "turns false once the server says a run would not reach the script — " +
+      "the Action is switched off or paused, not allowed from the app, gone, " +
+      "or the viewer is not a signed-in app user (signed-out visitors and " +
+      "anonymous accounts can't run Actions) — so render an 'isn't available' " +
+      "state then too. It stays true while no answer has come. 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; " +
@@ -2195,7 +2200,7 @@ const HOOKS = [
       "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",
+      available: "boolean  // false when no Action is bound, the host brokers none, or the server says a run would not reach the script",
       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",
@@ -4150,13 +4155,14 @@ const WIDGET_CONTEXT_SHAPE = {
   actions: {
     description:
       "sc-13843 — injected @colixsystems/actions-client instance. " +
-      "{ run(actionId, input?) -> Promise<{ ok, result }> }. Backs useAction(). " +
+      "{ run(actionId, input?) -> Promise<{ ok, result }>, status(actionId) -> " +
+      "Promise<{ available, reason }> }. 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" },
+    fields: { run: "function", status: "function" },
   },
   linkPreviews: {
     description:
@@ -6472,7 +6478,10 @@ const CONTRACT = deepFreeze({
   // 1.217.0: additive (sc-4747) — `TextInput` documents `keyboardType`,
   //    `autoCapitalize`, `autoCorrect`, `autoComplete`, `secureTextEntry`;
   //    `useDatastoreSchema` columns document `text_format` (snake_case wire).
-  version: "1.217.0",
+  // 1.218.0: additive (sc-14224) — the actions client's `status(actionId)`;
+  //    `useAction().available` turns false when the server says a run would
+  //    not reach the script.
+  version: "1.218.0",
   sharedTranslationKeys: SHARED_TRANSLATION_KEYS,
   hooks: HOOKS,
   primitives: PRIMITIVES,

package/dist/contract.js

@@ -2181,7 +2181,12 @@ const HOOKS = [
       "`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 " +
+      "'pick an action' state, NEVER a blank box. sc-14224: `available` also " +
+      "turns false once the server says a run would not reach the script — " +
+      "the Action is switched off or paused, not allowed from the app, gone, " +
+      "or the viewer is not a signed-in app user (signed-out visitors and " +
+      "anonymous accounts can't run Actions) — so render an 'isn't available' " +
+      "state then too. It stays true while no answer has come. 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; " +
@@ -2192,7 +2197,7 @@ const HOOKS = [
       "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",
+      available: "boolean  // false when no Action is bound, the host brokers none, or the server says a run would not reach the script",
       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",
@@ -4147,13 +4152,14 @@ const WIDGET_CONTEXT_SHAPE = {
   actions: {
     description:
       "sc-13843 — injected @colixsystems/actions-client instance. " +
-      "{ run(actionId, input?) -> Promise<{ ok, result }> }. Backs useAction(). " +
+      "{ run(actionId, input?) -> Promise<{ ok, result }>, status(actionId) -> " +
+      "Promise<{ available, reason }> }. 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" },
+    fields: { run: "function", status: "function" },
   },
   linkPreviews: {
     description:
@@ -6469,7 +6475,10 @@ const CONTRACT = deepFreeze({
   // 1.217.0: additive (sc-4747) — `TextInput` documents `keyboardType`,
   //    `autoCapitalize`, `autoCorrect`, `autoComplete`, `secureTextEntry`;
   //    `useDatastoreSchema` columns document `text_format` (snake_case wire).
-  version: "1.217.0",
+  // 1.218.0: additive (sc-14224) — the actions client's `status(actionId)`;
+  //    `useAction().available` turns false when the server says a run would
+  //    not reach the script.
+  version: "1.218.0",
   sharedTranslationKeys: SHARED_TRANSLATION_KEYS,
   hooks: HOOKS,
   primitives: PRIMITIVES,

package/dist/hooks.js

@@ -3893,18 +3893,46 @@ function toActionError(err) {
  * `available` is false and `run` rejects UNAVAILABLE rather than throwing at
  * render — the widget must render a visible unbound state (CLAUDE.md §8).
  *
+ * sc-14224 — `available` also turns false once the server says a run would
+ * not reach the script: the Action is switched off, paused, not allowed from
+ * the app, gone, or the viewer is not a signed-in app user. It is asked again
+ * when the binding or the signed-in user changes. With no answer (offline, an
+ * older host) it stays true and `run` reports the refusal.
+ *
  * Routes through the injected `@colixsystems/actions-client` at `ctx.actions`,
  * so the Player and the Expo export resolve against the identical client.
  */
 export function useAction(actionRef) {
   const ctx = useWidgetContextOrThrow("useAction");
-  const available =
+  const bound =
     Boolean(actionRef) &&
     Boolean(ctx.actions) &&
     typeof ctx.actions.run === "function";
+  const canAsk = bound && typeof ctx.actions.status === "function";
+  const askedAs = `${actionRef}|${(ctx.user && ctx.user.id) || ""}`;
 
   const clientRef = useRef(null);
-  clientRef.current = available ? ctx.actions : null;
+  clientRef.current = bound ? ctx.actions : null;
+
+  // The binding and viewer the server last refused, so a rebind starts fresh.
+  const [refusedAs, setRefusedAs] = useState(null);
+  useEffect(() => {
+    const client = clientRef.current;
+    if (!canAsk || !client) return undefined;
+    let live = true;
+    client.status(actionRef).then(
+      (answer) => {
+        if (live) setRefusedAs(answer && answer.available === false ? askedAs : null);
+      },
+      // No answer is not a refusal: keep offering the run.
+      () => {},
+    );
+    return () => {
+      live = false;
+    };
+    // eslint-disable-next-line react-hooks/exhaustive-deps
+  }, [askedAs, canAsk]);
+  const available = bound && refusedAs !== askedAs;
   const actionIdRef = useRef(actionRef);
   actionIdRef.current = actionRef;
 

package/dist/index.d.ts

@@ -890,6 +890,8 @@ export interface WidgetContext<TProps = unknown> {
   /** sc-13843 — injected @colixsystems/actions-client backing useAction(). */
   actions?: {
     run(actionId: string, input?: Record<string, unknown> | null): Promise<{ ok: boolean; result: unknown }>;
+    /** sc-14224 — whether a run would reach the script; optional on older hosts. */
+    status?(actionId: string): Promise<{ available: boolean; reason: string | null }>;
   };
   /** Injected @colixsystems/link-preview-client backing useLinkPreview(). */
   linkPreviews?: { get(url: string): Promise<LinkPreview> };
@@ -1893,7 +1895,11 @@ export interface AgentApi {
 export function useAgent(agentRef: string | null | undefined): AgentApi;
 
 export interface ActionApi {
-  /** False when no Action is bound, or the host brokers no actions client. */
+  /**
+   * False when no Action is bound, the host brokers no actions client, or the
+   * server says a run would not reach the script (switched off, not allowed
+   * from the app, or the viewer is not a signed-in app user).
+   */
   available: boolean;
   /**
    * Imperative — call from an event handler, never on mount. Resolves with the

package/package.json

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

@@ -2181,7 +2181,12 @@ const HOOKS = [
       "`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 " +
+      "'pick an action' state, NEVER a blank box. sc-14224: `available` also " +
+      "turns false once the server says a run would not reach the script — " +
+      "the Action is switched off or paused, not allowed from the app, gone, " +
+      "or the viewer is not a signed-in app user (signed-out visitors and " +
+      "anonymous accounts can't run Actions) — so render an 'isn't available' " +
+      "state then too. It stays true while no answer has come. 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; " +
@@ -2192,7 +2197,7 @@ const HOOKS = [
       "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",
+      available: "boolean  // false when no Action is bound, the host brokers none, or the server says a run would not reach the script",
       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",
@@ -4147,13 +4152,14 @@ const WIDGET_CONTEXT_SHAPE = {
   actions: {
     description:
       "sc-13843 — injected @colixsystems/actions-client instance. " +
-      "{ run(actionId, input?) -> Promise<{ ok, result }> }. Backs useAction(). " +
+      "{ run(actionId, input?) -> Promise<{ ok, result }>, status(actionId) -> " +
+      "Promise<{ available, reason }> }. 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" },
+    fields: { run: "function", status: "function" },
   },
   linkPreviews: {
     description:
@@ -6469,7 +6475,10 @@ const CONTRACT = deepFreeze({
   // 1.217.0: additive (sc-4747) — `TextInput` documents `keyboardType`,
   //    `autoCapitalize`, `autoCorrect`, `autoComplete`, `secureTextEntry`;
   //    `useDatastoreSchema` columns document `text_format` (snake_case wire).
-  version: "1.217.0",
+  // 1.218.0: additive (sc-14224) — the actions client's `status(actionId)`;
+  //    `useAction().available` turns false when the server says a run would
+  //    not reach the script.
+  version: "1.218.0",
   sharedTranslationKeys: SHARED_TRANSLATION_KEYS,
   hooks: HOOKS,
   primitives: PRIMITIVES,