@colixsystems/actions-client 0.1.0 → 0.2.0

This diff represents the content of publicly available package versions that have been released to one of the supported registries. The information contained in this diff is provided for informational purposes only and reflects changes between package versions as they appear in their respective public registries.
package/README.md CHANGED
@@ -10,7 +10,7 @@ An Action is a server-side script the workspace owns. The app may run one only w
10
10
 
11
11
  ## Status
12
12
 
13
- `v0.1.0` — pre-publish. Not yet published to npm.
13
+ `v0.2.0` — adds `status(actionId)`, which says whether a run would reach the script.
14
14
 
15
15
  ## Public API
16
16
 
@@ -36,6 +36,9 @@ const actions = createActionsClient({
36
36
  });
37
37
 
38
38
  const { ok, result } = await actions.run(actionId, { client_id: "c-123" });
39
+
40
+ // Whether a run would reach the script, before offering one.
41
+ const { available, reason } = await actions.status(actionId); // reason: "ACTION_DISABLED", "AUTH_REQUIRED", …
39
42
  ```
40
43
 
41
44
  The request is `POST {baseUrl}/app-actions/:actionId/run` with `Authorization: Bearer <token>` and `x-tenant-id`. The body is `{ input }`; when `input` is omitted or `null` no body is sent. It answers `{ ok, result }`, where `result` is the value the script passed to `respond()`, or `null`.
package/dist/client.js CHANGED
@@ -53,7 +53,7 @@ export function createActionsClient(opts) {
53
53
  );
54
54
  }
55
55
 
56
- async function post(path, body, operation) {
56
+ async function send(method, path, body, operation) {
57
57
  const token = await getToken();
58
58
  const tenantId = await getTenantId();
59
59
  const headers = { accept: "application/json" };
@@ -67,7 +67,7 @@ export function createActionsClient(opts) {
67
67
  }
68
68
 
69
69
  const res = await fetchImpl(joinUrl(baseUrl, path), {
70
- method: "POST",
70
+ method,
71
71
  headers,
72
72
  body: body !== undefined ? JSON.stringify(body) : undefined,
73
73
  });
@@ -84,25 +84,56 @@ export function createActionsClient(opts) {
84
84
  return parsed;
85
85
  }
86
86
 
87
+ function assertActionId(actionId, operation) {
88
+ // "." and ".." survive encodeURIComponent and fetch would resolve them.
89
+ if (
90
+ typeof actionId !== "string" ||
91
+ actionId.trim().length === 0 ||
92
+ actionId === "." ||
93
+ actionId === ".."
94
+ ) {
95
+ throw new TypeError(`${operation}(actionId): actionId must be a non-empty string`);
96
+ }
97
+ }
98
+
87
99
  return {
100
+ /**
101
+ * Whether this caller's run would reach the Action's script. Resolves
102
+ * `{ available, reason }`: reason is null when available, else the server's
103
+ * code (ACTION_DISABLED, ACTION_PAUSED, ACTION_NOT_APP_INVOKABLE,
104
+ * ACTION_NOT_FOUND, or AUTH_REQUIRED for a caller with no app session).
105
+ * Rejects only when no answer came (offline, rate limited, a server error).
106
+ */
107
+ async status(actionId) {
108
+ assertActionId(actionId, "status");
109
+ try {
110
+ const body = await send("GET", `/app-actions/${encodeURIComponent(actionId)}`, undefined, "status");
111
+ const available = body?.available === true;
112
+ return { available, reason: available ? null : (body?.reason ?? "ACTION_FAILED") };
113
+ } catch (err) {
114
+ if (err instanceof ActionError && [401, 403, 404].includes(err.status)) {
115
+ return { available: false, reason: err.code };
116
+ }
117
+ if (err instanceof ActionError) throw err;
118
+ throw new ActionError(`Action request failed: ${err?.message || err}`, {
119
+ code: "ACTION_FAILED",
120
+ status: 0,
121
+ cause: err,
122
+ });
123
+ }
124
+ },
125
+
88
126
  /**
89
127
  * Run one Action and resolve to `{ ok, result }`. `result` is the value
90
128
  * the script passed to `respond()` (any JSON), or null. Omit `input` (or
91
129
  * pass null) to send no body. Never retried: a run can have side effects.
92
130
  */
93
131
  async run(actionId, input) {
94
- // "." and ".." survive encodeURIComponent and fetch would resolve them.
95
- if (
96
- typeof actionId !== "string" ||
97
- actionId.trim().length === 0 ||
98
- actionId === "." ||
99
- actionId === ".."
100
- ) {
101
- throw new TypeError("run(actionId): actionId must be a non-empty string");
102
- }
132
+ assertActionId(actionId, "run");
103
133
  let body;
104
134
  try {
105
- body = await post(
135
+ body = await send(
136
+ "POST",
106
137
  `/app-actions/${encodeURIComponent(actionId)}/run`,
107
138
  input == null ? undefined : { input },
108
139
  "run",
@@ -202,3 +202,35 @@ test("the factory validates its providers", () => {
202
202
  TypeError,
203
203
  );
204
204
  });
205
+
206
+ // sc-14224 — what useAction reads before it offers a run.
207
+ test("status GETs the Action's availability and answers it", async () => {
208
+ const { fetchImpl, calls } = makeFetch({ status: 200, body: { available: true, reason: null } });
209
+ assert.deepEqual(await makeClient(fetchImpl).status("act-1"), { available: true, reason: null });
210
+ assert.equal(calls[0].url, "https://api.example.test/api/v1/app-actions/act-1");
211
+ assert.equal(calls[0].init.method, "GET");
212
+ assert.equal(calls[0].init.body, undefined);
213
+ assert.equal(calls[0].init.headers.authorization, "Bearer jwt-token");
214
+ });
215
+
216
+ test("status reports a switched-off Action unavailable, with the server's reason", async () => {
217
+ const { fetchImpl } = makeFetch({ status: 200, body: { available: false, reason: "ACTION_DISABLED" } });
218
+ assert.deepEqual(await makeClient(fetchImpl).status("act-1"), { available: false, reason: "ACTION_DISABLED" });
219
+ });
220
+
221
+ test("status answers unavailable for a signed-out caller, a refusal and a missing Action", async () => {
222
+ for (const [status, reason] of [[401, "AUTH_REQUIRED"], [403, "ACTION_NOT_APP_INVOKABLE"], [404, "ACTION_NOT_FOUND"]]) {
223
+ const { fetchImpl } = makeFetch({ status });
224
+ assert.deepEqual(await makeClient(fetchImpl).status("act-1"), { available: false, reason });
225
+ }
226
+ });
227
+
228
+ test("status rejects when no answer came, so the caller keeps what it knew", async () => {
229
+ await assert.rejects(makeClient(makeFetch({ throws: new TypeError("Failed to fetch") }).fetchImpl).status("a"), {
230
+ code: "ACTION_FAILED",
231
+ status: 0,
232
+ });
233
+ await assert.rejects(makeClient(makeFetch({ status: 429 }).fetchImpl).status("a"), { code: "RATE_LIMITED" });
234
+ await assert.rejects(makeClient(makeFetch({ status: 500 }).fetchImpl).status("a"), { status: 500 });
235
+ await assert.rejects(makeClient(makeFetch({ status: 200 }).fetchImpl).status(".."), TypeError);
236
+ });
package/dist/index.d.ts CHANGED
@@ -8,7 +8,18 @@ export interface ActionRunResult {
8
8
  result: unknown;
9
9
  }
10
10
 
11
+ /** Whether a run would reach the script; `reason` is the server's code when not. */
12
+ export interface ActionStatus {
13
+ available: boolean;
14
+ reason: string | null;
15
+ }
16
+
11
17
  export interface ActionsClient {
18
+ /**
19
+ * GET /app-actions/:actionId. A signed-out caller, a refusal or a missing
20
+ * Action answers `available: false`; rejects only when no answer came.
21
+ */
22
+ status(actionId: string): Promise<ActionStatus>;
12
23
  /**
13
24
  * POST /app-actions/:actionId/run. Omit `input` (or pass null) to send no body.
14
25
  * An empty, ".", or ".." id rejects with a TypeError before any request.
package/package.json CHANGED
@@ -1,6 +1,6 @@
1
1
  {
2
2
  "name": "@colixsystems/actions-client",
3
- "version": "0.1.0",
3
+ "version": "0.2.0",
4
4
  "description": "Scoped client for running a workspace's Actions from an AppStudio app. Used by widgets through the injected WidgetContext.actions.",
5
5
  "homepage": "https://github.com/Colix-AB/AppStudio",
6
6
  "type": "module",