@everysk/apps-sdk 0.2.0 → 0.3.0-beta-20261019175049

package/dist/hooks/workflow/useFetchWorkflows.js

@@ -1,62 +1,47 @@
 import { useAxios } from "../useAxios.js";
+import { useEntityInfiniteQuery } from "../useEntityInfiniteQuery.js";
+import { buildQueryKey, missingWorkspaceError } from "../../api/entityQuery.js";
 import { listWorkflows } from "../../api/workflow.js";
-import { useMemo } from "react";
-import { useInfiniteQuery } from "@tanstack/react-query";
 //#region src/hooks/workflow/useFetchWorkflows.ts
-var defaultQueryOptions = {
-	refetchOnMount: "always",
-	staleTime: 0,
-	gcTime: 0
-};
 /**
 * useFetchWorkflows
 *
-* Data-fetching hook built on TanStack Query's `useInfiniteQuery` to retrieve
-* workflows with cursor-based pagination using the legacy method (workspace as query param).
+* Lists workflows with cursor pagination; `query.data` is every loaded page merged, or
+* whatever `select` makes of it. `select` and `fetchAllPages` behave as in
+* `useFetchDatastores`. This endpoint takes a workspace and a text `search` rather than
+* filters.
 *
-* Automatically flattens all pages into a single `Workflow[]` via `select`.
+* A missing workspace fails loudly, without a request, as in every other hook. This hook used to
+* allow one, documented as listing the account's workflows; the API reads `main` instead.
 *
-* Note: `query.data` returns a flat `Workflow[]` with all fetched items merged across pages.
-*
-* @param {string} [workspace]
-*   Current workspace name. Sent as a query param via the legacy method, required by some API configurations.
-*
-* @param {number} [pageSize=10]
-*   Number of workflows to fetch per page.
-*
-* @param {InfiniteOptions<Workflow[]>} [queryOptions]
-*   TanStack Query options passed through to `useInfiniteQuery`
-*   (e.g., enabled, staleTime, gcTime, etc.).
-*
-* @returns {{ query, queryKey }}
-*   - `query`: the full `useInfiniteQuery` result (data, isLoading, hasNextPage, fetchNextPage, etc.)
-*   - `queryKey`: the cache key used by React Query
-*
-* @example
-* ```ts
-* const { query } = useFetchWorkflows({ workspace: "ws-1", pageSize: 20 });
-*
-* // Flat list of all fetched workflows
-* const workflows = query.data ?? [];
-* ```
+* @param {FetchWorkflowsProps} props - Workspace, search, page size, `select`,
+*   `fetchAllPages` and TanStack `queryOptions`.
+* @returns {object} `query` (the `useInfiniteQuery` result) and `queryKey`.
 */
-function useFetchWorkflows({ workspace, pageSize = 10, queryOptions }) {
+function useFetchWorkflows({ workspace, search, pageSize = 10, select, fetchAllPages = false, queryOptions }) {
 	const { api } = useAxios();
-	const queryKey = ["workflows", workspace ?? null];
-	const mergedQueryOptions = useMemo(() => ({
-		...defaultQueryOptions,
-		...queryOptions ?? {}
-	}), [queryOptions]);
+	const queryKey = buildQueryKey([
+		"workflows",
+		workspace,
+		search ?? null
+	], [], {
+		pageSize,
+		fetchAllPages
+	});
 	return {
-		query: useInfiniteQuery({
+		query: useEntityInfiniteQuery({
 			queryKey,
-			initialPageParam: null,
-			getNextPageParam: (lastPage) => lastPage.next_page_token ?? void 0,
-			queryFn: async ({ pageParam }) => {
-				return await listWorkflows(api, workspace, pageSize, pageParam ?? void 0);
-			},
-			select: (data) => data.pages.flatMap((p) => p.workflows),
-			...mergedQueryOptions
+			itemsKey: "workflows",
+			fetchPage: (pageToken, signal) => listWorkflows(api, {
+				workspace,
+				search,
+				pageSize,
+				pageToken: pageToken ?? void 0
+			}, signal),
+			select,
+			fetchAllPages,
+			configError: workspace ? void 0 : missingWorkspaceError("useFetchWorkflows"),
+			queryOptions
 		}),
 		queryKey
 	};

package/dist/hooks/workflow/useFetchWorkflows.js.map

@@ -1 +1 @@
-{"version":3,"file":"useFetchWorkflows.js","names":[],"sources":["../../../src/hooks/workflow/useFetchWorkflows.ts"],"sourcesContent":["import { useMemo } from \"react\";\nimport { useInfiniteQuery, type UseInfiniteQueryOptions, type QueryKey } from \"@tanstack/react-query\";\n\nimport { useAxios } from \"@/hooks/useAxios\";\nimport { listWorkflows } from \"@/api/workflow\";\nimport type { Workflow, WorkflowListResponse } from \"@/types/workflow\";\n\ntype PageToken = string | null;\n\ntype InfiniteOptions<TData> = Omit<UseInfiniteQueryOptions<WorkflowListResponse, Error, TData, QueryKey, PageToken>,\"queryKey\" | \"queryFn\" | \"initialPageParam\" | \"getNextPageParam\">;\n\nexport type FetchInfiniteWorkflowProps = {\n    workspace?: string;\n    pageSize?: number;\n    queryOptions?: InfiniteOptions<Workflow[]>;\n};\n\nconst defaultQueryOptions: InfiniteOptions<Workflow[]> = {\n    refetchOnMount: \"always\",\n    staleTime: 0,\n    gcTime: 0,\n};\n\n/**\n * useFetchWorkflows\n *\n * Data-fetching hook built on TanStack Query's `useInfiniteQuery` to retrieve\n * workflows with cursor-based pagination using the legacy method (workspace as query param).\n *\n * Automatically flattens all pages into a single `Workflow[]` via `select`.\n *\n * Note: `query.data` returns a flat `Workflow[]` with all fetched items merged across pages.\n *\n * @param {string} [workspace]\n *   Current workspace name. Sent as a query param via the legacy method, required by some API configurations.\n *\n * @param {number} [pageSize=10]\n *   Number of workflows to fetch per page.\n *\n * @param {InfiniteOptions<Workflow[]>} [queryOptions]\n *   TanStack Query options passed through to `useInfiniteQuery`\n *   (e.g., enabled, staleTime, gcTime, etc.).\n *\n * @returns {{ query, queryKey }}\n *   - `query`: the full `useInfiniteQuery` result (data, isLoading, hasNextPage, fetchNextPage, etc.)\n *   - `queryKey`: the cache key used by React Query\n *\n * @example\n * ```ts\n * const { query } = useFetchWorkflows({ workspace: \"ws-1\", pageSize: 20 });\n *\n * // Flat list of all fetched workflows\n * const workflows = query.data ?? [];\n * ```\n */\nexport function useFetchWorkflows({ workspace, pageSize = 10, queryOptions }: FetchInfiniteWorkflowProps) {\n    const { api } = useAxios();\n\n    const queryKey: QueryKey = [\"workflows\", workspace ?? null];\n\n    const mergedQueryOptions = useMemo<InfiniteOptions<Workflow[]>>(() => ({\n        ...defaultQueryOptions,\n        ...(queryOptions ?? {}),\n    }), [queryOptions]);\n\n    const query = useInfiniteQuery<WorkflowListResponse, Error, Workflow[], QueryKey, PageToken>({\n        queryKey,\n        initialPageParam: null,\n        getNextPageParam: (lastPage) => lastPage.next_page_token ?? undefined,\n\n        queryFn: async ({ pageParam }) => {\n            return await listWorkflows(api, workspace, pageSize, pageParam ?? undefined);\n        },\n\n        select: (data) => data.pages.flatMap((p) => p.workflows),\n\n        ...mergedQueryOptions,\n    });\n\n    return {\n        query,\n        queryKey,\n    };\n}\n"],"mappings":";;;;;AAiBA,IAAM,sBAAmD;CACrD,gBAAgB;CAChB,WAAW;CACX,QAAQ;AACZ;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;AAkCA,SAAgB,kBAAkB,EAAE,WAAW,WAAW,IAAI,gBAA4C;CACtG,MAAM,EAAE,QAAQ,SAAS;CAEzB,MAAM,WAAqB,CAAC,aAAa,aAAa,IAAI;CAE1D,MAAM,qBAAqB,eAA4C;EACnE,GAAG;EACH,GAAI,gBAAgB,CAAC;CACzB,IAAI,CAAC,YAAY,CAAC;CAgBlB,OAAO;EACH,OAfU,iBAA+E;GACzF;GACA,kBAAkB;GAClB,mBAAmB,aAAa,SAAS,mBAAmB,KAAA;GAE5D,SAAS,OAAO,EAAE,gBAAgB;IAC9B,OAAO,MAAM,cAAc,KAAK,WAAW,UAAU,aAAa,KAAA,CAAS;GAC/E;GAEA,SAAS,SAAS,KAAK,MAAM,SAAS,MAAM,EAAE,SAAS;GAEvD,GAAG;EACP,CAGI;EACA;CACJ;AACJ"}
+{"version":3,"file":"useFetchWorkflows.js","names":[],"sources":["../../../src/hooks/workflow/useFetchWorkflows.ts"],"sourcesContent":["import { useAxios } from \"@/hooks/useAxios\";\nimport { useEntityInfiniteQuery } from \"@/hooks/useEntityInfiniteQuery\";\nimport { listWorkflows } from \"@/api/workflow\";\nimport { buildQueryKey, missingWorkspaceError } from \"@/api/entityQuery\";\nimport type { Workflow, WorkflowListResponse } from \"@/types/workflow\";\nimport type { FetchEntitiesProps, ListCache } from \"@/types/entityQuery\";\n\n/** The query cache of `useFetchWorkflows`, for typing `setQueryData`. */\nexport type WorkflowsCache = ListCache<WorkflowListResponse>;\n\nexport type FetchWorkflowsProps<TData = Workflow[]> = FetchEntitiesProps<\n    Workflow,\n    TData,\n    WorkflowListResponse\n> & {\n    /** Workspace to list. Required: without one the API reads `main`, not the account. */\n    workspace: string;\n    /** A name prefix, an id, `#tag #tag` (every tag), or `&link_uid`. */\n    search?: string;\n};\n\n/**\n * useFetchWorkflows\n *\n * Lists workflows with cursor pagination; `query.data` is every loaded page merged, or\n * whatever `select` makes of it. `select` and `fetchAllPages` behave as in\n * `useFetchDatastores`. This endpoint takes a workspace and a text `search` rather than\n * filters.\n *\n * A missing workspace fails loudly, without a request, as in every other hook. This hook used to\n * allow one, documented as listing the account's workflows; the API reads `main` instead.\n *\n * @param {FetchWorkflowsProps} props - Workspace, search, page size, `select`,\n *   `fetchAllPages` and TanStack `queryOptions`.\n * @returns {object} `query` (the `useInfiniteQuery` result) and `queryKey`.\n */\nexport function useFetchWorkflows<TData = Workflow[]>({\n    workspace,\n    search,\n    pageSize = 10,\n    select,\n    fetchAllPages = false,\n    queryOptions,\n}: FetchWorkflowsProps<TData>) {\n    const { api } = useAxios();\n\n    const queryKey = buildQueryKey([\"workflows\", workspace, search ?? null], [], {\n        pageSize,\n        fetchAllPages,\n    });\n\n    const query = useEntityInfiniteQuery<WorkflowListResponse, \"workflows\", TData>({\n        queryKey,\n        itemsKey: \"workflows\",\n        fetchPage: (pageToken, signal) =>\n            listWorkflows(\n                api,\n                { workspace, search, pageSize, pageToken: pageToken ?? undefined },\n                signal,\n            ),\n        select,\n        fetchAllPages,\n        configError: workspace ? undefined : missingWorkspaceError(\"useFetchWorkflows\"),\n        queryOptions,\n    });\n\n    return { query, queryKey };\n}\n"],"mappings":";;;;;;;;;;;;;;;;;;;;AAoCA,SAAgB,kBAAsC,EAClD,WACA,QACA,WAAW,IACX,QACA,gBAAgB,OAChB,gBAC2B;CAC3B,MAAM,EAAE,QAAQ,SAAS;CAEzB,MAAM,WAAW,cAAc;EAAC;EAAa;EAAW,UAAU;CAAI,GAAG,CAAC,GAAG;EACzE;EACA;CACJ,CAAC;CAiBD,OAAO;EAAE,OAfK,uBAAiE;GAC3E;GACA,UAAU;GACV,YAAY,WAAW,WACnB,cACI,KACA;IAAE;IAAW;IAAQ;IAAU,WAAW,aAAa,KAAA;GAAU,GACjE,MACJ;GACJ;GACA;GACA,aAAa,YAAY,KAAA,IAAY,sBAAsB,mBAAmB;GAC9E;EACJ,CAES;EAAO;CAAS;AAC7B"}

package/dist/hooks/workflow/useRunWorkflow.d.ts

@@ -1,30 +1,35 @@
+import { type WorkflowWaitOptions } from "../../lib/workflowRun.js";
 import type { AnyRecord } from "../../types/anyRecord.d.ts";
-import type { PollWorkflowExecutionOptions } from "../../api/workflow.js";
+import type { WorkflowResult } from "../../types/workflow.d.ts";
 type RunWorkflowProps = {
     id: string;
     workspace: string;
     parameters: AnyRecord;
-    pollOptions?: PollWorkflowExecutionOptions;
+    /** How the run is waited for; see `WorkflowWaitOptions`. */
+    waitOptions?: WorkflowWaitOptions;
 };
 /**
  * useRunWorkflow
  *
- * TanStack Query mutations to run a workflow. Synchronous execution (`synchronous: true`) is
- * intentionally not used; instead the workflow is started asynchronously and, when the result
- * is needed, its execution is polled until it reaches a terminal state.
+ * A TanStack Query mutation that starts a workflow run, waits for it to end, then reads the
+ * Ender's worker execution. Resolves with `{ execution, workerExecution, result }` (`result` is
+ * `null` when the run has no output), and fails unless the run ended `SUCCEEDED`.
  *
- * - `runAsync`: starts the workflow and returns immediately (fire-and-forget). Use when you do
- *   not need to wait for completion or consume the output.
- * - `runAndGetResult`: starts the workflow, polls until it finishes, then fetches the output of
- *   the ender worker. Resolves with `{ execution, workerExecution, result }`; `result` is `null`
- *   when the workflow produces no output. This is the replacement for the old synchronous flow.
+ * It waits over the websocket (see `runWorkflowToEnd`), not by polling: the backend announces
+ * each worker and the run's end on the app's channel, and the end itself is then read from the
+ * API. So it requires `WebSocketProvider`, and throws on render without it. To start a run
+ * without waiting, and without a websocket, use `useTriggerWorkflow`.
  *
- * Both surface the standard mutation helpers (`mutate`, `mutateAsync`, `isPending`, `data`, ...)
- * and report failures through `useAppAlert`.
+ * Leaving the screen stops it — listening, reads in flight and the result read — and so does
+ * `waitOptions.signal`. Neither is alerted: there is no screen left, or the app asked for it. Both
+ * fail the mutation with a `WorkflowRunAbortedError`, the signal's reason as the cause. The run itself goes
+ * on on the server. `waitOptions.timeoutMs` bounds only the wait for the end; the result read
+ * after it is a single request that the timeout does not cover. Any other failure is shown as an
+ * error alert through `useAppAlert`, and logged with its cause, which says why a wait timed out.
+ *
+ * @returns {UseMutationResult} The mutation; `mutate({ id, workspace, parameters, waitOptions })`
+ *   starts a run and waits for it.
  */
-export declare const useRunWorkflow: () => {
-    runAsync: import("@tanstack/react-query").UseMutationResult<AnyRecord, Error, RunWorkflowProps, unknown>;
-    runAndGetResult: import("@tanstack/react-query").UseMutationResult<import("../../api/workflow.js").WorkflowResult, Error, RunWorkflowProps, unknown>;
-};
+export declare const useRunWorkflow: () => import("@tanstack/react-query").UseMutationResult<WorkflowResult, Error, RunWorkflowProps, unknown>;
 export {};
 //# sourceMappingURL=useRunWorkflow.d.ts.map

package/dist/hooks/workflow/useRunWorkflow.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"useRunWorkflow.d.ts","sourceRoot":"","sources":["../../../src/hooks/workflow/useRunWorkflow.ts"],"names":[],"mappings":"AAIA,OAAO,KAAK,EAAE,SAAS,EAAE,MAAM,mBAAmB,CAAC;AACnD,OAAO,KAAK,EAAE,4BAA4B,EAAE,MAAM,gBAAgB,CAAC;AAGnE,KAAK,gBAAgB,GAAG;IACpB,EAAE,EAAE,MAAM,CAAC;IACX,SAAS,EAAE,MAAM,CAAC;IAClB,UAAU,EAAE,SAAS,CAAC;IACtB,WAAW,CAAC,EAAE,4BAA4B,CAAC;CAC9C,CAAC;AAKF;;;;;;;;;;;;;;;GAeG;AACH,eAAO,MAAM,cAAc;;;CA2B1B,CAAC"}
+{"version":3,"file":"useRunWorkflow.d.ts","sourceRoot":"","sources":["../../../src/hooks/workflow/useRunWorkflow.ts"],"names":[],"mappings":"AAaA,OAAO,EAIH,KAAK,mBAAmB,EAC3B,MAAM,mBAAmB,CAAC;AAC3B,OAAO,KAAK,EAAE,SAAS,EAAE,MAAM,mBAAmB,CAAC;AACnD,OAAO,KAAK,EAAE,cAAc,EAAE,MAAM,kBAAkB,CAAC;AAEvD,KAAK,gBAAgB,GAAG;IACpB,EAAE,EAAE,MAAM,CAAC;IACX,SAAS,EAAE,MAAM,CAAC;IAClB,UAAU,EAAE,SAAS,CAAC;IACtB,4DAA4D;IAC5D,WAAW,CAAC,EAAE,mBAAmB,CAAC;CACrC,CAAC;AAEF;;;;;;;;;;;;;;;;;;;;;GAqBG;AACH,eAAO,MAAM,cAAc,2GAuD1B,CAAC"}

package/dist/hooks/workflow/useRunWorkflow.js

@@ -1,48 +1,85 @@
 import { useAppAlert } from "../../contexts/appAlertContext/useAppAlert.js";
 import { useAxios } from "../useAxios.js";
-import { runWorkflow, runWorkflowAndGetResult } from "../../api/workflow.js";
+import { getWorkerExecution, getWorkflowExecution, runWorkflow, terminalRunStatusOf } from "../../api/workflow.js";
+import { useWebSocket } from "../../contexts/webSocketContext/hooks/useWebSocket/index.js";
+import { anySignal, unlessAborted } from "../../lib/abort.js";
+import { WorkflowRunAbortedError, runWorkflowToEnd } from "../../lib/workflowRun.js";
+import { useEffect, useRef } from "react";
 import { useMutation } from "@tanstack/react-query";
 //#region src/hooks/workflow/useRunWorkflow.ts
-var getErrorMessage = (err, fallback) => err instanceof Error && err.message ? err.message : fallback;
 /**
 * useRunWorkflow
 *
-* TanStack Query mutations to run a workflow. Synchronous execution (`synchronous: true`) is
-* intentionally not used; instead the workflow is started asynchronously and, when the result
-* is needed, its execution is polled until it reaches a terminal state.
+* A TanStack Query mutation that starts a workflow run, waits for it to end, then reads the
+* Ender's worker execution. Resolves with `{ execution, workerExecution, result }` (`result` is
+* `null` when the run has no output), and fails unless the run ended `SUCCEEDED`.
 *
-* - `runAsync`: starts the workflow and returns immediately (fire-and-forget). Use when you do
-*   not need to wait for completion or consume the output.
-* - `runAndGetResult`: starts the workflow, polls until it finishes, then fetches the output of
-*   the ender worker. Resolves with `{ execution, workerExecution, result }`; `result` is `null`
-*   when the workflow produces no output. This is the replacement for the old synchronous flow.
+* It waits over the websocket (see `runWorkflowToEnd`), not by polling: the backend announces
+* each worker and the run's end on the app's channel, and the end itself is then read from the
+* API. So it requires `WebSocketProvider`, and throws on render without it. To start a run
+* without waiting, and without a websocket, use `useTriggerWorkflow`.
 *
-* Both surface the standard mutation helpers (`mutate`, `mutateAsync`, `isPending`, `data`, ...)
-* and report failures through `useAppAlert`.
+* Leaving the screen stops it — listening, reads in flight and the result read — and so does
+* `waitOptions.signal`. Neither is alerted: there is no screen left, or the app asked for it. Both
+* fail the mutation with a `WorkflowRunAbortedError`, the signal's reason as the cause. The run itself goes
+* on on the server. `waitOptions.timeoutMs` bounds only the wait for the end; the result read
+* after it is a single request that the timeout does not cover. Any other failure is shown as an
+* error alert through `useAppAlert`, and logged with its cause, which says why a wait timed out.
+*
+* @returns {UseMutationResult} The mutation; `mutate({ id, workspace, parameters, waitOptions })`
+*   starts a run and waits for it.
 */
 var useRunWorkflow = () => {
 	const { api } = useAxios();
 	const { showAlert } = useAppAlert();
-	return {
-		runAsync: useMutation({
-			mutationFn: ({ id, workspace, parameters }) => runWorkflow(api, id, workspace, parameters),
-			onError: (err) => {
-				showAlert({
-					severity: "error",
-					message: getErrorMessage(err, "Unable to run the workflow. Please try again.")
+	const socket = useWebSocket();
+	const unmounted = useRef(void 0);
+	useEffect(() => {
+		const controller = new AbortController();
+		unmounted.current = controller.signal;
+		return () => controller.abort();
+	}, []);
+	return useMutation({
+		mutationFn: async ({ id, workspace, parameters, waitOptions }) => {
+			const { signal, dispose } = anySignal([waitOptions?.signal, unmounted.current]);
+			try {
+				const execution = await runWorkflowToEnd({
+					startRun: () => runWorkflow(api, id, workspace, parameters),
+					getExecution: (workflowExecutionId, readSignal) => getWorkflowExecution(api, id, workflowExecutionId, workspace, readSignal),
+					subscribeToEvents: socket.subscribe,
+					subscribeToStatus: socket.subscribeStatus,
+					...waitOptions,
+					signal
 				});
-			}
-		}),
-		runAndGetResult: useMutation({
-			mutationFn: ({ id, workspace, parameters, pollOptions }) => runWorkflowAndGetResult(api, id, workspace, parameters, pollOptions),
-			onError: (err) => {
-				showAlert({
-					severity: "error",
-					message: getErrorMessage(err, "Unable to run the workflow. Please try again.")
+				const runStatus = terminalRunStatusOf(execution.run_status);
+				if (runStatus !== "SUCCEEDED") throw new Error(`Workflow execution ${runStatus?.toLowerCase()}`);
+				const enderId = execution.ender_worker_execution_id;
+				if (!enderId) return {
+					execution,
+					workerExecution: null,
+					result: null
+				};
+				const workerExecution = await unlessAborted(getWorkerExecution(api, id, enderId, workspace, signal), signal).catch((error) => {
+					throw signal.aborted ? new WorkflowRunAbortedError(signal.reason) : error;
 				});
+				return {
+					execution,
+					workerExecution,
+					result: workerExecution.result ?? null
+				};
+			} finally {
+				dispose();
 			}
-		})
-	};
+		},
+		onError: (error) => {
+			if (error instanceof WorkflowRunAbortedError || unmounted.current?.aborted) return;
+			console.error("Workflow run failed:", error);
+			showAlert({
+				severity: "error",
+				message: error.message || "Unable to run the workflow. Please try again."
+			});
+		}
+	});
 };
 //#endregion
 export { useRunWorkflow };

package/dist/hooks/workflow/useRunWorkflow.js.map

@@ -1 +1 @@
-{"version":3,"file":"useRunWorkflow.js","names":[],"sources":["../../../src/hooks/workflow/useRunWorkflow.ts"],"sourcesContent":["import { useMutation } from \"@tanstack/react-query\";\n\nimport { useAxios } from \"@/hooks/useAxios\";\nimport { useAppAlert } from \"@/contexts/appAlertContext/useAppAlert\";\nimport type { AnyRecord } from \"@/types/anyRecord\";\nimport type { PollWorkflowExecutionOptions } from \"@/api/workflow\";\nimport { runWorkflow, runWorkflowAndGetResult } from \"@/api/workflow\";\n\ntype RunWorkflowProps = {\n    id: string;\n    workspace: string;\n    parameters: AnyRecord;\n    pollOptions?: PollWorkflowExecutionOptions;\n};\n\nconst getErrorMessage = (err: unknown, fallback: string) =>\n    err instanceof Error && err.message ? err.message : fallback;\n\n/**\n * useRunWorkflow\n *\n * TanStack Query mutations to run a workflow. Synchronous execution (`synchronous: true`) is\n * intentionally not used; instead the workflow is started asynchronously and, when the result\n * is needed, its execution is polled until it reaches a terminal state.\n *\n * - `runAsync`: starts the workflow and returns immediately (fire-and-forget). Use when you do\n *   not need to wait for completion or consume the output.\n * - `runAndGetResult`: starts the workflow, polls until it finishes, then fetches the output of\n *   the ender worker. Resolves with `{ execution, workerExecution, result }`; `result` is `null`\n *   when the workflow produces no output. This is the replacement for the old synchronous flow.\n *\n * Both surface the standard mutation helpers (`mutate`, `mutateAsync`, `isPending`, `data`, ...)\n * and report failures through `useAppAlert`.\n */\nexport const useRunWorkflow = () => {\n    const { api } = useAxios();\n    const { showAlert } = useAppAlert();\n\n    const runAsync = useMutation({\n        mutationFn: ({ id, workspace, parameters }: RunWorkflowProps) =>\n            runWorkflow(api, id, workspace, parameters),\n        onError: (err) => {\n            showAlert({\n                severity: \"error\",\n                message: getErrorMessage(err, \"Unable to run the workflow. Please try again.\"),\n            });\n        },\n    });\n\n    const runAndGetResult = useMutation({\n        mutationFn: ({ id, workspace, parameters, pollOptions }: RunWorkflowProps) =>\n            runWorkflowAndGetResult(api, id, workspace, parameters, pollOptions),\n        onError: (err) => {\n            showAlert({\n                severity: \"error\",\n                message: getErrorMessage(err, \"Unable to run the workflow. Please try again.\"),\n            });\n        },\n    });\n\n    return { runAsync, runAndGetResult };\n};\n"],"mappings":";;;;;AAeA,IAAM,mBAAmB,KAAc,aACnC,eAAe,SAAS,IAAI,UAAU,IAAI,UAAU;;;;;;;;;;;;;;;;;AAkBxD,IAAa,uBAAuB;CAChC,MAAM,EAAE,QAAQ,SAAS;CACzB,MAAM,EAAE,cAAc,YAAY;CAwBlC,OAAO;EAAE,UAtBQ,YAAY;GACzB,aAAa,EAAE,IAAI,WAAW,iBAC1B,YAAY,KAAK,IAAI,WAAW,UAAU;GAC9C,UAAU,QAAQ;IACd,UAAU;KACN,UAAU;KACV,SAAS,gBAAgB,KAAK,+CAA+C;IACjF,CAAC;GACL;EACJ,CAaS;EAAU,iBAXK,YAAY;GAChC,aAAa,EAAE,IAAI,WAAW,YAAY,kBACtC,wBAAwB,KAAK,IAAI,WAAW,YAAY,WAAW;GACvE,UAAU,QAAQ;IACd,UAAU;KACN,UAAU;KACV,SAAS,gBAAgB,KAAK,+CAA+C;IACjF,CAAC;GACL;EACJ,CAEmB;CAAgB;AACvC"}
+{"version":3,"file":"useRunWorkflow.js","names":[],"sources":["../../../src/hooks/workflow/useRunWorkflow.ts"],"sourcesContent":["import { useEffect, useRef } from \"react\";\nimport { useMutation } from \"@tanstack/react-query\";\n\nimport { useAxios } from \"@/hooks/useAxios\";\nimport { useAppAlert } from \"@/contexts/appAlertContext/useAppAlert\";\nimport { useWebSocket } from \"@/contexts/webSocketContext/hooks/useWebSocket\";\nimport {\n    getWorkerExecution,\n    getWorkflowExecution,\n    runWorkflow,\n    terminalRunStatusOf,\n} from \"@/api/workflow\";\nimport { anySignal, unlessAborted } from \"@/lib/abort\";\nimport {\n    RUN_FAILED_MESSAGE,\n    WorkflowRunAbortedError,\n    runWorkflowToEnd,\n    type WorkflowWaitOptions,\n} from \"@/lib/workflowRun\";\nimport type { AnyRecord } from \"@/types/anyRecord\";\nimport type { WorkflowResult } from \"@/types/workflow\";\n\ntype RunWorkflowProps = {\n    id: string;\n    workspace: string;\n    parameters: AnyRecord;\n    /** How the run is waited for; see `WorkflowWaitOptions`. */\n    waitOptions?: WorkflowWaitOptions;\n};\n\n/**\n * useRunWorkflow\n *\n * A TanStack Query mutation that starts a workflow run, waits for it to end, then reads the\n * Ender's worker execution. Resolves with `{ execution, workerExecution, result }` (`result` is\n * `null` when the run has no output), and fails unless the run ended `SUCCEEDED`.\n *\n * It waits over the websocket (see `runWorkflowToEnd`), not by polling: the backend announces\n * each worker and the run's end on the app's channel, and the end itself is then read from the\n * API. So it requires `WebSocketProvider`, and throws on render without it. To start a run\n * without waiting, and without a websocket, use `useTriggerWorkflow`.\n *\n * Leaving the screen stops it — listening, reads in flight and the result read — and so does\n * `waitOptions.signal`. Neither is alerted: there is no screen left, or the app asked for it. Both\n * fail the mutation with a `WorkflowRunAbortedError`, the signal's reason as the cause. The run itself goes\n * on on the server. `waitOptions.timeoutMs` bounds only the wait for the end; the result read\n * after it is a single request that the timeout does not cover. Any other failure is shown as an\n * error alert through `useAppAlert`, and logged with its cause, which says why a wait timed out.\n *\n * @returns {UseMutationResult} The mutation; `mutate({ id, workspace, parameters, waitOptions })`\n *   starts a run and waits for it.\n */\nexport const useRunWorkflow = () => {\n    const { api } = useAxios();\n    const { showAlert } = useAppAlert();\n    const socket = useWebSocket();\n    const unmounted = useRef<AbortSignal | undefined>(undefined);\n\n    useEffect(() => {\n        const controller = new AbortController();\n        unmounted.current = controller.signal;\n        return () => controller.abort();\n    }, []);\n\n    return useMutation({\n        mutationFn: async ({\n            id,\n            workspace,\n            parameters,\n            waitOptions,\n        }: RunWorkflowProps): Promise<WorkflowResult> => {\n            const { signal, dispose } = anySignal([waitOptions?.signal, unmounted.current]);\n            try {\n                const execution = await runWorkflowToEnd({\n                    startRun: () => runWorkflow(api, id, workspace, parameters),\n                    getExecution: (workflowExecutionId, readSignal) =>\n                        getWorkflowExecution(api, id, workflowExecutionId, workspace, readSignal),\n                    subscribeToEvents: socket.subscribe,\n                    subscribeToStatus: socket.subscribeStatus,\n                    ...waitOptions,\n                    signal,\n                });\n\n                const runStatus = terminalRunStatusOf(execution.run_status);\n                if (runStatus !== \"SUCCEEDED\")\n                    throw new Error(`Workflow execution ${runStatus?.toLowerCase()}`);\n\n                const enderId = execution.ender_worker_execution_id;\n                if (!enderId) return { execution, workerExecution: null, result: null };\n\n                const workerExecution = await unlessAborted(\n                    getWorkerExecution(api, id, enderId, workspace, signal),\n                    signal,\n                ).catch((error: unknown) => {\n                    throw signal.aborted ? new WorkflowRunAbortedError(signal.reason) : error;\n                });\n                return { execution, workerExecution, result: workerExecution.result ?? null };\n            } finally {\n                dispose();\n            }\n        },\n        onError: (error) => {\n            if (error instanceof WorkflowRunAbortedError || unmounted.current?.aborted) return;\n            console.error(\"Workflow run failed:\", error);\n            showAlert({ severity: \"error\", message: error.message || RUN_FAILED_MESSAGE });\n        },\n    });\n};\n"],"mappings":";;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;AAoDA,IAAa,uBAAuB;CAChC,MAAM,EAAE,QAAQ,SAAS;CACzB,MAAM,EAAE,cAAc,YAAY;CAClC,MAAM,SAAS,aAAa;CAC5B,MAAM,YAAY,OAAgC,KAAA,CAAS;CAE3D,gBAAgB;EACZ,MAAM,aAAa,IAAI,gBAAgB;EACvC,UAAU,UAAU,WAAW;EAC/B,aAAa,WAAW,MAAM;CAClC,GAAG,CAAC,CAAC;CAEL,OAAO,YAAY;EACf,YAAY,OAAO,EACf,IACA,WACA,YACA,kBAC6C;GAC7C,MAAM,EAAE,QAAQ,YAAY,UAAU,CAAC,aAAa,QAAQ,UAAU,OAAO,CAAC;GAC9E,IAAI;IACA,MAAM,YAAY,MAAM,iBAAiB;KACrC,gBAAgB,YAAY,KAAK,IAAI,WAAW,UAAU;KAC1D,eAAe,qBAAqB,eAChC,qBAAqB,KAAK,IAAI,qBAAqB,WAAW,UAAU;KAC5E,mBAAmB,OAAO;KAC1B,mBAAmB,OAAO;KAC1B,GAAG;KACH;IACJ,CAAC;IAED,MAAM,YAAY,oBAAoB,UAAU,UAAU;IAC1D,IAAI,cAAc,aACd,MAAM,IAAI,MAAM,sBAAsB,WAAW,YAAY,GAAG;IAEpE,MAAM,UAAU,UAAU;IAC1B,IAAI,CAAC,SAAS,OAAO;KAAE;KAAW,iBAAiB;KAAM,QAAQ;IAAK;IAEtE,MAAM,kBAAkB,MAAM,cAC1B,mBAAmB,KAAK,IAAI,SAAS,WAAW,MAAM,GACtD,MACJ,CAAC,CAAC,OAAO,UAAmB;KACxB,MAAM,OAAO,UAAU,IAAI,wBAAwB,OAAO,MAAM,IAAI;IACxE,CAAC;IACD,OAAO;KAAE;KAAW;KAAiB,QAAQ,gBAAgB,UAAU;IAAK;GAChF,UAAU;IACN,QAAQ;GACZ;EACJ;EACA,UAAU,UAAU;GAChB,IAAI,iBAAiB,2BAA2B,UAAU,SAAS,SAAS;GAC5E,QAAQ,MAAM,wBAAwB,KAAK;GAC3C,UAAU;IAAE,UAAU;IAAS,SAAS,MAAM,WAAA;GAA8B,CAAC;EACjF;CACJ,CAAC;AACL"}

package/dist/hooks/workflow/useTriggerWorkflow.d.ts

@@ -0,0 +1,20 @@
+import type { AnyRecord } from "../../types/anyRecord.d.ts";
+type TriggerWorkflowProps = {
+    id: string;
+    workspace: string;
+    parameters: AnyRecord;
+};
+/**
+ * useTriggerWorkflow
+ *
+ * A TanStack Query mutation that starts a workflow run and resolves with the execution it started,
+ * still `RUNNING`. Fire-and-forget, for when nothing waits for the output; it needs no websocket.
+ * To wait for the run and read its result, use `useRunWorkflow`.
+ *
+ * A failure is shown as an error alert through `useAppAlert`.
+ *
+ * @returns {UseMutationResult} The mutation; `mutate({ id, workspace, parameters })` starts a run.
+ */
+export declare const useTriggerWorkflow: () => import("@tanstack/react-query").UseMutationResult<import("../..").WorkflowExecution, Error, TriggerWorkflowProps, unknown>;
+export {};
+//# sourceMappingURL=useTriggerWorkflow.d.ts.map

package/dist/hooks/workflow/useTriggerWorkflow.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"useTriggerWorkflow.d.ts","sourceRoot":"","sources":["../../../src/hooks/workflow/useTriggerWorkflow.ts"],"names":[],"mappings":"AAMA,OAAO,KAAK,EAAE,SAAS,EAAE,MAAM,mBAAmB,CAAC;AAEnD,KAAK,oBAAoB,GAAG;IACxB,EAAE,EAAE,MAAM,CAAC;IACX,SAAS,EAAE,MAAM,CAAC;IAClB,UAAU,EAAE,SAAS,CAAC;CACzB,CAAC;AAEF;;;;;;;;;;GAUG;AACH,eAAO,MAAM,kBAAkB,kIAU9B,CAAC"}

package/dist/hooks/workflow/useTriggerWorkflow.js

@@ -0,0 +1,32 @@
+import { useAppAlert } from "../../contexts/appAlertContext/useAppAlert.js";
+import { useAxios } from "../useAxios.js";
+import { runWorkflow } from "../../api/workflow.js";
+import "../../lib/workflowRun.js";
+import { useMutation } from "@tanstack/react-query";
+//#region src/hooks/workflow/useTriggerWorkflow.ts
+/**
+* useTriggerWorkflow
+*
+* A TanStack Query mutation that starts a workflow run and resolves with the execution it started,
+* still `RUNNING`. Fire-and-forget, for when nothing waits for the output; it needs no websocket.
+* To wait for the run and read its result, use `useRunWorkflow`.
+*
+* A failure is shown as an error alert through `useAppAlert`.
+*
+* @returns {UseMutationResult} The mutation; `mutate({ id, workspace, parameters })` starts a run.
+*/
+var useTriggerWorkflow = () => {
+	const { api } = useAxios();
+	const { showAlert } = useAppAlert();
+	return useMutation({
+		mutationFn: ({ id, workspace, parameters }) => runWorkflow(api, id, workspace, parameters),
+		onError: (error) => showAlert({
+			severity: "error",
+			message: error.message || "Unable to run the workflow. Please try again."
+		})
+	});
+};
+//#endregion
+export { useTriggerWorkflow };
+
+//# sourceMappingURL=useTriggerWorkflow.js.map

package/dist/hooks/workflow/useTriggerWorkflow.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"useTriggerWorkflow.js","names":[],"sources":["../../../src/hooks/workflow/useTriggerWorkflow.ts"],"sourcesContent":["import { useMutation } from \"@tanstack/react-query\";\n\nimport { useAxios } from \"@/hooks/useAxios\";\nimport { useAppAlert } from \"@/contexts/appAlertContext/useAppAlert\";\nimport { runWorkflow } from \"@/api/workflow\";\nimport { RUN_FAILED_MESSAGE } from \"@/lib/workflowRun\";\nimport type { AnyRecord } from \"@/types/anyRecord\";\n\ntype TriggerWorkflowProps = {\n    id: string;\n    workspace: string;\n    parameters: AnyRecord;\n};\n\n/**\n * useTriggerWorkflow\n *\n * A TanStack Query mutation that starts a workflow run and resolves with the execution it started,\n * still `RUNNING`. Fire-and-forget, for when nothing waits for the output; it needs no websocket.\n * To wait for the run and read its result, use `useRunWorkflow`.\n *\n * A failure is shown as an error alert through `useAppAlert`.\n *\n * @returns {UseMutationResult} The mutation; `mutate({ id, workspace, parameters })` starts a run.\n */\nexport const useTriggerWorkflow = () => {\n    const { api } = useAxios();\n    const { showAlert } = useAppAlert();\n\n    return useMutation({\n        mutationFn: ({ id, workspace, parameters }: TriggerWorkflowProps) =>\n            runWorkflow(api, id, workspace, parameters),\n        onError: (error) =>\n            showAlert({ severity: \"error\", message: error.message || RUN_FAILED_MESSAGE }),\n    });\n};\n"],"mappings":";;;;;;;;;;;;;;;;;AAyBA,IAAa,2BAA2B;CACpC,MAAM,EAAE,QAAQ,SAAS;CACzB,MAAM,EAAE,cAAc,YAAY;CAElC,OAAO,YAAY;EACf,aAAa,EAAE,IAAI,WAAW,iBAC1B,YAAY,KAAK,IAAI,WAAW,UAAU;EAC9C,UAAU,UACN,UAAU;GAAE,UAAU;GAAS,SAAS,MAAM,WAAA;EAA8B,CAAC;CACrF,CAAC;AACL"}

package/dist/hooks/workspace/useFetchWorkspace.d.ts

@@ -1,39 +1,24 @@
 import type { Workspace } from "../../types/workspace.d.ts";
-import type { EntityQueryOptions } from "../../types/entityQuery.d.ts";
-export type FetchWorkspaceProps<TData = Workspace, TSelected = TData> = {
+import type { FetchEntityProps } from "../../types/entityQuery.d.ts";
+export type FetchWorkspaceProps<TData = Workspace, TSelected = TData> = FetchEntityProps<TData, TSelected> & {
     name: string;
-    queryOptions?: EntityQueryOptions<TData, TSelected>;
 };
 /**
  * useFetchWorkspace
  *
- * Data-fetching hook built on TanStack Query to retrieve a single workspace by name.
+ * Fetches one workspace by name; `data` is the workspace, or whatever `select` makes of it.
  *
- * It also:
- * - builds a stable React Query `queryKey` that can be reused by mutation hooks for cache invalidation
- * - triggers an error alert via `useAppAlert` whenever `query.error` is present
+ * A workspace is identified by its name — the API's `GET /workspaces/:id` takes the name, its
+ * UID — so `name` is this hook's id, and like the other hooks' id it usually comes from a
+ * selection the user has not made yet: while it is empty the hook stays idle, rather than fail
+ * as a misconfigured app. A failure is shown as an error alert.
  *
- * Parameters (FetchWorkspaceProps):
- * @param {string} name
- *   Workspace name (required).
- *
- * @param queryOptions
- *   TanStack Query options passed through to `useQuery` (e.g., enabled, staleTime, gcTime, etc.).
- *
- * Returns:
- * @returns {object}
- *   TanStack Query's `query` object extended with:
- *   - `queryKey`: the cache key used by React Query
- *
- * Example:
- * ```ts
- * const { data, isLoading } = useFetchWorkspace({ name: "main" });
- * // data -> Workspace
- * ```
+ * @param {FetchWorkspaceProps} props - `name`, `select` and TanStack `queryOptions`.
+ * @returns {object} The `useQuery` result, plus `queryKey`.
  */
-export declare const useFetchWorkspace: ({ name, queryOptions }: FetchWorkspaceProps) => {
+export declare const useFetchWorkspace: <TSelected = Workspace>({ name, select, queryOptions, }: FetchWorkspaceProps<Workspace, TSelected>) => {
     queryKey: string[];
-    data: Workspace;
+    data: TSelected;
     error: Error;
     isError: true;
     isPending: false;
@@ -56,11 +41,11 @@ export declare const useFetchWorkspace: ({ name, queryOptions }: FetchWorkspaceP
     isRefetching: boolean;
     isStale: boolean;
     isEnabled: boolean;
-    refetch: (options?: import("@tanstack/query-core").RefetchOptions) => Promise<import("@tanstack/query-core").QueryObserverResult<Workspace, Error>>;
+    refetch: (options?: import("@tanstack/query-core").RefetchOptions) => Promise<import("@tanstack/query-core").QueryObserverResult<TSelected, Error>>;
     fetchStatus: import("@tanstack/query-core").FetchStatus;
 } | {
     queryKey: string[];
-    data: Workspace;
+    data: TSelected;
     error: null;
     isError: false;
     isPending: false;
@@ -83,7 +68,7 @@ export declare const useFetchWorkspace: ({ name, queryOptions }: FetchWorkspaceP
     isRefetching: boolean;
     isStale: boolean;
     isEnabled: boolean;
-    refetch: (options?: import("@tanstack/query-core").RefetchOptions) => Promise<import("@tanstack/query-core").QueryObserverResult<Workspace, Error>>;
+    refetch: (options?: import("@tanstack/query-core").RefetchOptions) => Promise<import("@tanstack/query-core").QueryObserverResult<TSelected, Error>>;
     fetchStatus: import("@tanstack/query-core").FetchStatus;
 } | {
     queryKey: string[];
@@ -110,7 +95,7 @@ export declare const useFetchWorkspace: ({ name, queryOptions }: FetchWorkspaceP
     isRefetching: boolean;
     isStale: boolean;
     isEnabled: boolean;
-    refetch: (options?: import("@tanstack/query-core").RefetchOptions) => Promise<import("@tanstack/query-core").QueryObserverResult<Workspace, Error>>;
+    refetch: (options?: import("@tanstack/query-core").RefetchOptions) => Promise<import("@tanstack/query-core").QueryObserverResult<TSelected, Error>>;
     fetchStatus: import("@tanstack/query-core").FetchStatus;
 } | {
     queryKey: string[];
@@ -137,7 +122,7 @@ export declare const useFetchWorkspace: ({ name, queryOptions }: FetchWorkspaceP
     isRefetching: boolean;
     isStale: boolean;
     isEnabled: boolean;
-    refetch: (options?: import("@tanstack/query-core").RefetchOptions) => Promise<import("@tanstack/query-core").QueryObserverResult<Workspace, Error>>;
+    refetch: (options?: import("@tanstack/query-core").RefetchOptions) => Promise<import("@tanstack/query-core").QueryObserverResult<TSelected, Error>>;
     fetchStatus: import("@tanstack/query-core").FetchStatus;
 } | {
     queryKey: string[];
@@ -164,11 +149,11 @@ export declare const useFetchWorkspace: ({ name, queryOptions }: FetchWorkspaceP
     isRefetching: boolean;
     isStale: boolean;
     isEnabled: boolean;
-    refetch: (options?: import("@tanstack/query-core").RefetchOptions) => Promise<import("@tanstack/query-core").QueryObserverResult<Workspace, Error>>;
+    refetch: (options?: import("@tanstack/query-core").RefetchOptions) => Promise<import("@tanstack/query-core").QueryObserverResult<TSelected, Error>>;
     fetchStatus: import("@tanstack/query-core").FetchStatus;
 } | {
     queryKey: string[];
-    data: Workspace;
+    data: TSelected;
     isError: false;
     error: null;
     isPending: false;
@@ -191,7 +176,7 @@ export declare const useFetchWorkspace: ({ name, queryOptions }: FetchWorkspaceP
     isRefetching: boolean;
     isStale: boolean;
     isEnabled: boolean;
-    refetch: (options?: import("@tanstack/query-core").RefetchOptions) => Promise<import("@tanstack/query-core").QueryObserverResult<Workspace, Error>>;
+    refetch: (options?: import("@tanstack/query-core").RefetchOptions) => Promise<import("@tanstack/query-core").QueryObserverResult<TSelected, Error>>;
     fetchStatus: import("@tanstack/query-core").FetchStatus;
 };
 //# sourceMappingURL=useFetchWorkspace.d.ts.map

package/dist/hooks/workspace/useFetchWorkspace.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"useFetchWorkspace.d.ts","sourceRoot":"","sources":["../../../src/hooks/workspace/useFetchWorkspace.ts"],"names":[],"mappings":"AAMA,OAAO,KAAK,EAAE,SAAS,EAAE,MAAM,mBAAmB,CAAC;AAEnD,OAAO,KAAK,EAAE,kBAAkB,EAAE,MAAM,qBAAqB,CAAC;AAE9D,MAAM,MAAM,mBAAmB,CAAC,KAAK,GAAG,SAAS,EAAE,SAAS,GAAG,KAAK,IAAI;IACpE,IAAI,EAAE,MAAM,CAAC;IACb,YAAY,CAAC,EAAE,kBAAkB,CAAC,KAAK,EAAE,SAAS,CAAC,CAAC;CACvD,CAAC;AAQF;;;;;;;;;;;;;;;;;;;;;;;;;;GA0BG;AACH,eAAO,MAAM,iBAAiB,GAAI,wBAA8C,mBAAmB;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;CA6BlG,CAAC"}
+{"version":3,"file":"useFetchWorkspace.d.ts","sourceRoot":"","sources":["../../../src/hooks/workspace/useFetchWorkspace.ts"],"names":[],"mappings":"AAGA,OAAO,KAAK,EAAE,SAAS,EAAE,MAAM,mBAAmB,CAAC;AACnD,OAAO,KAAK,EAAE,gBAAgB,EAAE,MAAM,qBAAqB,CAAC;AAE5D,MAAM,MAAM,mBAAmB,CAAC,KAAK,GAAG,SAAS,EAAE,SAAS,GAAG,KAAK,IAAI,gBAAgB,CACpF,KAAK,EACL,SAAS,CACZ,GAAG;IACA,IAAI,EAAE,MAAM,CAAC;CAChB,CAAC;AAEF;;;;;;;;;;;;GAYG;AACH,eAAO,MAAM,iBAAiB,GAAI,SAAS,GAAG,SAAS,EAAE,iCAItD,mBAAmB,CAAC,SAAS,EAAE,SAAS,CAAC;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;CAc3C,CAAC"}

package/dist/hooks/workspace/useFetchWorkspace.js

@@ -1,61 +1,31 @@
-import { useAppAlert } from "../../contexts/appAlertContext/useAppAlert.js";
 import { useAxios } from "../useAxios.js";
+import { useEntityQuery } from "../useEntityQuery.js";
 import { getWorkspace } from "../../api/workspace.js";
-import { useEffect } from "react";
-import { useQuery } from "@tanstack/react-query";
 //#region src/hooks/workspace/useFetchWorkspace.ts
-var defaultQueryOptions = {
-	refetchOnMount: "always",
-	staleTime: 0,
-	gcTime: 0
-};
 /**
 * useFetchWorkspace
 *
-* Data-fetching hook built on TanStack Query to retrieve a single workspace by name.
-*
-* It also:
-* - builds a stable React Query `queryKey` that can be reused by mutation hooks for cache invalidation
-* - triggers an error alert via `useAppAlert` whenever `query.error` is present
-*
-* Parameters (FetchWorkspaceProps):
-* @param {string} name
-*   Workspace name (required).
-*
-* @param queryOptions
-*   TanStack Query options passed through to `useQuery` (e.g., enabled, staleTime, gcTime, etc.).
+* Fetches one workspace by name; `data` is the workspace, or whatever `select` makes of it.
 *
-* Returns:
-* @returns {object}
-*   TanStack Query's `query` object extended with:
-*   - `queryKey`: the cache key used by React Query
+* A workspace is identified by its name — the API's `GET /workspaces/:id` takes the name, its
+* UID — so `name` is this hook's id, and like the other hooks' id it usually comes from a
+* selection the user has not made yet: while it is empty the hook stays idle, rather than fail
+* as a misconfigured app. A failure is shown as an error alert.
 *
-* Example:
-* ```ts
-* const { data, isLoading } = useFetchWorkspace({ name: "main" });
-* // data -> Workspace
-* ```
+* @param {FetchWorkspaceProps} props - `name`, `select` and TanStack `queryOptions`.
+* @returns {object} The `useQuery` result, plus `queryKey`.
 */
-var useFetchWorkspace = ({ name, queryOptions = defaultQueryOptions }) => {
+var useFetchWorkspace = ({ name, select, queryOptions }) => {
 	const { api } = useAxios();
-	const { showAlert } = useAppAlert();
 	const queryKey = ["workspace", name];
-	const query = useQuery({
-		queryKey,
-		queryFn: async () => {
-			return await getWorkspace(api, name);
-		},
-		...queryOptions ?? {}
-	});
-	useEffect(() => {
-		if (!query.error) return;
-		showAlert({
-			severity: "error",
-			message: query.error.message
-		});
-	}, [query.error, showAlert]);
 	return {
-		...query,
+		...useEntityQuery({
+			queryKey,
+			fetchEntity: (signal) => getWorkspace(api, name, signal),
+			select,
+			enabled: Boolean(name),
+			queryOptions
+		}),
 		queryKey
 	};
 };