@everysk/apps-sdk 0.1.0 → 0.3.0-beta-20261016180126

package/src/api/request.ts

@@ -0,0 +1,168 @@
+import { isAxiosError, isCancel, type AxiosResponse } from "axios";
+
+import type { AnyRecord } from "@/types/anyRecord";
+import type { FilterExpression, QueryObject } from "@/types/entityQuery";
+
+/**
+ * request
+ *
+ * Sends one request and returns its body, with the error handling every `api/` function shares.
+ * Each of them used to carry its own copy of this `catch`, and the copies drifted: some
+ * rethrew a cancellation and some did not, and `runWorkflow` had lost its fallback message.
+ *
+ * The request goes in as a function rather than a config so each call site keeps calling
+ * `api.get`, `api.post`… itself, which is what reads as the endpoint and what the tests stub.
+ *
+ * - A cancellation is rethrown as axios made it: an abort is not a failure to report, and
+ *   wrapped in a new Error `isCancel` would no longer see it.
+ * - An axios error becomes an Error with its message, or `failure` when it has none, and the
+ *   axios error as `cause` — the only place the API's own `{ code, message }` body survives.
+ * - Any other Error is rethrown untouched, and anything else is wrapped, so a caller never
+ *   catches a bare string.
+ *
+ * @param send - Makes the request.
+ * @param failure - The message when the error carries none.
+ * @returns The response body.
+ */
+export const request = async <T>(
+    send: () => Promise<AxiosResponse<T>>,
+    failure: string,
+): Promise<T> => {
+    try {
+        const response = await send();
+        return response.data;
+    } catch (error: unknown) {
+        if (isCancel(error)) throw error;
+
+        if (isAxiosError<AnyRecord>(error)) {
+            throw new Error(error.message || failure, { cause: error });
+        }
+
+        if (error instanceof Error) {
+            throw error;
+        }
+
+        throw new Error(failure, { cause: error });
+    }
+};
+
+/**
+ * isRetryableFailure
+ *
+ * Whether a failure `request()` reported may pass if the request is sent again: one that got no
+ * response (a network error), a 5XX, or a 429. It is read from the axios error `request()` keeps
+ * as `cause`. Anything else will fail the same way next time: any other 4XX, and anything that is
+ * not a request failure at all — a bug, or a body that is not the expected JSON, such as the HTML
+ * page an expired session gets.
+ *
+ * @param error - What a request function threw.
+ * @returns True when retrying may succeed.
+ */
+export const isRetryableFailure = (error: unknown): boolean => {
+    const cause = error instanceof Error ? error.cause : undefined;
+    if (!isAxiosError(cause)) return false;
+
+    const status = cause.response?.status;
+    return status === undefined || status >= 500 || status === 429;
+};
+
+/**
+ * workspaceOf
+ *
+ * The workspace a list request names: the **first** `workspace` filter, when it is an equality
+ * on a name. One reading, shared by the request and by `hasWorkspaceFilter`, so the hooks' check
+ * cannot pass on a filter the request then reads another way — which is what happened while
+ * each read it its own way.
+ *
+ * Only an equality counts. The query's filters are what scope the data, so `["workspace", "!=",
+ * "ws-1"]` reads every *other* workspace; it named a workspace, so the check used to pass. A
+ * value that is not a name (an `IN` list) went out as `workspace[]=…`.
+ *
+ * @param filters - The query's filters, as tuples.
+ * @returns The workspace name, or `undefined` when the first `workspace` filter is missing or is
+ *   not an equality on a name.
+ */
+export const workspaceOf = (filters: FilterExpression[]): string | undefined => {
+    const filter = filters.find((expression) => expression[0] === "workspace");
+    if (!filter) return undefined;
+
+    const isEquality = filter.length === 2 || filter[1] === "=";
+    const value = filter[filter.length - 1];
+
+    return isEquality && typeof value === "string" ? value : undefined;
+};
+
+/**
+ * requireWorkspace
+ *
+ * Refuses a call without a workspace before it reaches the API. The API would not say why: a
+ * get or delete by id with `workspace=""` answers a bare 403, one without the parameter skips the
+ * check altogether, and a create falls back to `main`. One wording for every function: each used
+ * to carry its own check, two phrasings of it ("Workspace filter is required…" for a plain
+ * string), and three had lost it altogether.
+ *
+ * @param workspace - The workspace the call was given.
+ * @param action - What the call does, completing "Workspace is required to …".
+ * @throws {Error} When `workspace` is empty.
+ */
+export function requireWorkspace(
+    workspace: string | null | undefined,
+    action: string,
+): asserts workspace is string {
+    if (!workspace) throw new Error(`Workspace is required to ${action}`);
+}
+
+/**
+ * pageParams
+ *
+ * The query string of a list endpoint that takes a workspace and a cursor rather than a query
+ * object — workflows and workspaces, whose `query` is a name or tag search, not filters. The
+ * search goes out as `query`. Only what was given is sent: an empty value means "none", and sent
+ * as `""` it would read as one.
+ *
+ * @param page - The workspace, search, page size and page token, each optional.
+ * @returns The `workspace`, `query`, `page_size` and `page_token` parameters that carry a value.
+ */
+export const pageParams = ({
+    workspace,
+    search,
+    pageSize,
+    pageToken,
+}: {
+    workspace?: string;
+    search?: string;
+    pageSize?: number;
+    pageToken?: string;
+}): AnyRecord => ({
+    ...(workspace ? { workspace } : {}),
+    ...(search ? { query: search } : {}),
+    ...(pageSize ? { page_size: pageSize } : {}),
+    ...(pageToken ? { page_token: pageToken } : {}),
+});
+
+/** The query string of a list endpoint, as `listParams` builds it. */
+export type ListParams = {
+    workspace: string;
+    query: string;
+};
+
+/**
+ * listParams
+ *
+ * The query string of a list endpoint: the workspace on its own, beside the serialized query
+ * that also carries it. They do different jobs. The query's filters are what scope the data — on
+ * this path the API ignores the parameter for that — while the parameter is what the API checks
+ * a sub-user's role against.
+ *
+ * @param query - The query object built with `buildQueryObject`.
+ * @param action - What the call does, for the missing-workspace message.
+ * @returns `{ workspace, query }`.
+ * @throws {Error} When the first `workspace` filter is absent, empty, or not an equality on a name.
+ */
+export const listParams = (query: QueryObject, action: string): ListParams => {
+    const workspace = workspaceOf(query.filters);
+
+    requireWorkspace(workspace, action);
+
+    return { workspace, query: JSON.stringify(query) };
+};

package/src/api/websocketsConfig.ts

@@ -1,10 +1,16 @@
-import { isAxiosError, type AxiosInstance, type AxiosResponse } from "axios";
+import type { AxiosInstance } from "axios";
 
-import type { AnyRecord } from "@/types/anyRecord";
-import type { WebsocketsConfig } from "@/contexts/webSocketContext/types";
+import { request } from "./request";
 
 const baseUrl = "websockets_config";
 
+/** What the provider connects with. Not public: only `WebSocketProvider` reads it. */
+export type WebsocketsConfig = {
+    appConnectionURL: string;
+    appChannelID: string;
+    everyskUID: string;
+};
+
 /**
  * getWebsocketsConfig
  *
@@ -14,19 +20,5 @@ const baseUrl = "websockets_config";
  * @returns {Promise<WebsocketsConfig>} Connection URL, channel id, and session uid.
  * @throws {Error} If the request fails.
  */
-export const getWebsocketsConfig = async (api: AxiosInstance): Promise<WebsocketsConfig> => {
-    try {
-        const response: AxiosResponse<WebsocketsConfig> = await api.get(baseUrl);
-        return response.data;
-    } catch (error: unknown) {
-        if (isAxiosError<AnyRecord>(error)) {
-            throw new Error(error.message || "Error fetching websockets config");
-        }
-
-        if (error instanceof Error) {
-            throw error;
-        }
-
-        throw new Error("Error fetching websockets config");
-    }
-};
+export const getWebsocketsConfig = async (api: AxiosInstance): Promise<WebsocketsConfig> =>
+    request(() => api.get<WebsocketsConfig>(baseUrl), "Error fetching websockets config");