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

package/dist/api/workflow.js

@@ -1,232 +1,149 @@
-import { isAxiosError } from "axios";
+import { pageParams, request, requireWorkspace } from "./request.js";
 //#region src/api/workflow.ts
 var baseUrl = "workflows";
 /**
 * Runs a workflow asynchronously.
 *
 * Starts the workflow in a non-blocking way: the response carries a workflow execution
-* with a non-terminal status (e.g. "RUNNING"). Use polling to wait for the terminal state.
+* with a non-terminal status (e.g. "RUNNING"). `useRunWorkflow` waits for the end over
+* the websocket.
 *
 * @param api - Axios instance used to make the HTTP request.
 * @param id - The unique identifier of the workflow to run.
 * @param workspace - The workspace in which the workflow will be executed.
 * @param parameters - Key-value parameters to pass to the workflow.
-* @returns A promise that resolves with the workflow execution response data.
+* @returns The execution the run started, still `RUNNING`. It used to be the raw body,
+*   `{ workflow_execution, result: null }`, where every other function returns the entity.
 * @throws {Error} If `workspace` is not provided.
 * @throws {Error} If the request fails.
 */
 var runWorkflow = async (api, id, workspace, parameters) => {
-	if (!workspace) throw new Error("Workspace is required to run workflow");
-	try {
-		const body = {
-			workspace,
-			parameters
-		};
-		return (await api.post(`${baseUrl}/${id}/run`, body)).data;
-	} catch (error) {
-		if (isAxiosError(error)) throw new Error(error.message || "", { cause: error });
-		if (error instanceof Error) throw error;
-		throw new Error("Error while running workflow", { cause: error });
-	}
+	requireWorkspace(workspace, "run a workflow");
+	return (await request(() => api.post(`${baseUrl}/${id}/run`, {
+		workspace,
+		parameters
+	}), "Error running workflow")).workflow_execution;
 };
 /**
-* Run statuses that indicate a workflow execution has reached a terminal state
-* (i.e. it is no longer running and will not change again).
-*
-* Union of the backend's `WORKFLOW_EXECUTION_STATUS_FINISHED` set and the API's documented
-* terminal `run_status` values (`SUCCEEDED`/`FAILED`/`KILLED`). `KILLED` is included so a
-* killed execution is detected as terminal instead of polling until timeout.
+* The run statuses a workflow execution can end with. The backend writes `RUNNING` when the run
+* starts, and `SUCCEEDED` or `FAILED` once its Ender finishes; `CANCELED` is reserved for a
+* cancellation it does not write yet. This list used to carry `KILLED`, which the backend never
+* writes, and `COMPLETED`, the value of the deprecated `status` field, seen in `run_status` only
+* on executions from before 2024-10-03.
 */
 var TERMINAL_RUN_STATUSES = [
-	"CANCELED",
-	"COMPLETED",
 	"SUCCEEDED",
 	"FAILED",
-	"KILLED"
+	"CANCELED"
 ];
-var isTerminalRunStatus = (runStatus) => TERMINAL_RUN_STATUSES.includes(String(runStatus ?? "").toUpperCase());
-var sleep = (ms) => new Promise((resolve) => setTimeout(resolve, ms));
 /**
-* Polls a workflow execution until it reaches a terminal run status (see {@link TERMINAL_RUN_STATUSES}).
-*
-* This is the interim, non-blocking replacement for synchronous (`synchronous: true`) execution:
-* the workflow is started asynchronously and its status is checked periodically until it completes.
-*
-* @param api - Axios instance used to make the HTTP request.
-* @param workflowId - The unique identifier of the workflow.
-* @param executionId - The unique identifier of the workflow execution to poll.
-* @param workspace - The workspace in which the workflow execution resides.
-* @param options - Polling configuration (interval, timeout, abort signal).
-* @returns A promise that resolves with the terminal {@link WorkflowExecution}.
-* @throws {Error} If `workspace` is not provided.
-* @throws {Error} If polling is aborted via `options.signal`.
-* @throws {Error} If a terminal status is not reached before `options.timeoutMs` elapses.
+* The status a run ended with, read whatever its case; `null` while it has not ended. A missing
+* status — a projection can drop the field, and JSON can carry it as `null` — is a run not known
+* to have ended. The one place a run's status is read, so a comparison against it is typed.
 */
-var pollWorkflowExecution = async (api, workflowId, executionId, workspace, options = {}) => {
-	if (!workspace) throw new Error("Workspace is required to poll a workflow execution");
-	const { intervalMs = 2e3, timeoutMs = 3e5, signal } = options;
-	const startedAt = Date.now();
-	while (true) {
-		if (signal?.aborted) throw new Error("Workflow execution polling was aborted");
-		const execution = await getWorkflowExecution(api, workflowId, executionId, workspace);
-		if (isTerminalRunStatus(execution.run_status)) return execution;
-		if (Date.now() - startedAt >= timeoutMs) throw new Error("Timed out while waiting for the workflow execution to complete");
-		await sleep(intervalMs);
-	}
-};
-/**
-* Starts a workflow asynchronously and polls its execution until completion.
-*
-* Interim replacement for synchronous execution: instead of holding the request open with
-* `synchronous: true`, the workflow is started in a non-blocking way and its status is polled
-* until it reaches a terminal state, at which point the final execution (with its result) is returned.
-*
-* @param api - Axios instance used to make the HTTP request.
-* @param id - The unique identifier of the workflow to run.
-* @param workspace - The workspace in which the workflow will be executed.
-* @param parameters - Key-value parameters to pass to the workflow.
-* @param options - Polling configuration (interval, timeout, abort signal).
-* @returns A promise that resolves with the terminal {@link WorkflowExecution}.
-* @throws {Error} If `workspace` is not provided.
-* @throws {Error} If the run response does not contain a workflow execution id.
-* @throws {Error} If the workflow execution ends in a "FAILED" run status.
-* @throws {Error} If polling times out or is aborted.
-*/
-var runWorkflowAndPoll = async (api, id, workspace, parameters, options = {}) => {
-	if (!workspace) throw new Error("Workspace is required to run workflow");
-	const executionId = (await runWorkflow(api, id, workspace, parameters)).workflow_execution?.id;
-	if (!executionId) throw new Error("Workflow run did not return an execution id to poll");
-	const execution = await pollWorkflowExecution(api, id, executionId, workspace, options);
-	if (String(execution.run_status ?? "").toUpperCase() === "FAILED") throw new Error("Workflow execution failed");
-	return execution;
-};
-/**
-* Starts a workflow, polls it to completion, then fetches the output produced by its final worker.
-*
-* A workflow execution does not carry the output payload itself — it references the final worker via
-* `ender_worker_execution_id`, and that worker execution's `result` field holds the actual data.
-* This helper performs the full flow: start (async) → poll → fetch ender worker → return its `result`.
-*
-* @param api - Axios instance used to make the HTTP request.
-* @param id - The unique identifier of the workflow to run.
-* @param workspace - The workspace in which the workflow will be executed.
-* @param parameters - Key-value parameters to pass to the workflow.
-* @param options - Polling configuration (interval, timeout, abort signal).
-* @returns A promise that resolves with the {@link WorkflowResult} (execution, ender worker execution, and its result).
-* @throws {Error} If `workspace` is not provided.
-* @throws {Error} If the workflow execution ends in a "FAILED" run status.
-* @throws {Error} If polling times out or is aborted.
-*/
-var runWorkflowAndGetResult = async (api, id, workspace, parameters, options = {}) => {
-	const execution = await runWorkflowAndPoll(api, id, workspace, parameters, options);
-	const enderWorkerExecutionId = execution.ender_worker_execution_id;
-	if (!enderWorkerExecutionId) return {
-		execution,
-		workerExecution: null,
-		result: null
-	};
-	const workerExecution = await getWorkerExecution(api, id, enderWorkerExecutionId, workspace);
-	return {
-		execution,
-		workerExecution,
-		result: workerExecution.result ?? null
-	};
+var terminalRunStatusOf = (runStatus) => {
+	const upper = runStatus?.toUpperCase();
+	return TERMINAL_RUN_STATUSES.find((status) => status === upper) ?? null;
 };
+/** Whether a run with this `run_status` has ended; see `terminalRunStatusOf`. */
+var isTerminalRunStatus = (runStatus) => terminalRunStatusOf(runStatus) !== null;
 /**
 * Fetches a single workflow by ID.
 *
 * @param api - Axios instance used to make the HTTP request.
 * @param id - The unique identifier of the workflow to fetch.
 * @param workspace - The workspace in which the workflow resides.
+* @param {AbortSignal} [signal] - Aborts the request itself; the entity hooks pass the query's own.
 * @returns A promise that resolves with the {@link Workflow} object.
 * @throws {Error} If `workspace` is not provided.
 * @throws {Error} If the request fails.
 */
-var getWorkflow = async (api, id, workspace) => {
-	if (!workspace) throw new Error("Workspace is required to fetch a workflow");
-	try {
-		const params = { workspace };
-		return (await api.get(`${baseUrl}/${id}`, { params })).data.workflow;
-	} catch (error) {
-		if (isAxiosError(error)) throw new Error(error.message || "Error while fetching workflow", { cause: error });
-		if (error instanceof Error) throw error;
-		throw new Error("Error while fetching workflow", { cause: error });
-	}
+var getWorkflow = async (api, id, workspace, signal) => {
+	requireWorkspace(workspace, "fetch a workflow");
+	return (await request(() => api.get(`${baseUrl}/${id}`, {
+		params: { workspace },
+		signal
+	}), "Error fetching workflow")).workflow;
 };
 /**
-* Fetches a paginated list of workflows using the legacy method (workspace as query param).
+* Lists the workflows of a workspace, a page at a time.
+*
+* The endpoint takes a text search rather than the JSON query the other lists take, so this
+* takes `search` rather than a `QueryObject`.
 *
 * @param api - Axios instance used to make the HTTP request.
-* @param workspace - Current workspace name. Sent as a query param via the legacy method, required by some API configurations.
-* @param pageSize - Number of items per page.
-* @param pageToken - Cursor token for the next page.
-* @returns A promise that resolves with a {@link WorkflowListResponse} containing the matched workflows.
+* @param params - Workspace, search and paging.
+* @param {AbortSignal} [signal] - Aborts the request itself; the list hooks pass the query's own.
+* @returns A page of workflows, with the cursor to the next one.
+* @throws {Error} If `workspace` is empty.
 * @throws {Error} If the request fails.
 */
-var listWorkflows = async (api, workspace, pageSize, pageToken) => {
-	const params = {};
-	if (workspace) params.workspace = workspace;
-	if (pageSize) params.page_size = pageSize;
-	if (pageToken) params.page_token = pageToken;
-	try {
-		return (await api.get(baseUrl, { params })).data;
-	} catch (error) {
-		if (isAxiosError(error)) throw new Error(error.message || "Error listing workflows", { cause: error });
-		if (error instanceof Error) throw error;
-		throw new Error("Error listing workflows", { cause: error });
-	}
+var listWorkflows = async (api, { workspace, search, pageSize, pageToken }, signal) => {
+	requireWorkspace(workspace, "list workflows");
+	const params = pageParams({
+		workspace,
+		search,
+		pageSize,
+		pageToken
+	});
+	return request(() => api.get(baseUrl, {
+		params,
+		signal
+	}), "Error listing workflows");
 };
 /**
 * Fetches a single workflow execution by ID.
 *
 * @param api - Axios instance used to make the HTTP request.
 * @param workflowId - The unique identifier of the workflow.
-* @param executionId - The unique identifier of the workflow execution to fetch.
+* @param workflowExecutionId - The unique identifier of the workflow execution to fetch.
 * @param workspace - The workspace in which the workflow execution resides.
+* @param {AbortSignal} [signal] - Aborts the request itself; the entity hooks pass the query's own.
 * @returns A promise that resolves with the {@link WorkflowExecution} object.
 * @throws {Error} If `workspace` is not provided.
 * @throws {Error} If the request fails.
 */
-var getWorkflowExecution = async (api, workflowId, executionId, workspace) => {
-	if (!workspace) throw new Error("Workspace is required to fetch a workflow execution");
-	try {
-		const params = {
-			workspace,
-			workflow_execution_id: executionId
-		};
-		return (await api.get(`${baseUrl}/${workflowId}/workflow_executions`, { params })).data.workflow_execution;
-	} catch (error) {
-		if (isAxiosError(error)) throw new Error(error.message || "Error fetching workflow execution", { cause: error });
-		if (error instanceof Error) throw error;
-		throw new Error("Error fetching workflow execution", { cause: error });
-	}
+var getWorkflowExecution = async (api, workflowId, workflowExecutionId, workspace, signal) => {
+	requireWorkspace(workspace, "fetch a workflow execution");
+	const params = {
+		workspace,
+		workflow_execution_id: workflowExecutionId
+	};
+	return (await request(() => api.get(`${baseUrl}/${workflowId}/workflow_executions`, {
+		params,
+		signal
+	}), "Error fetching workflow execution")).workflow_execution;
 };
 /**
-* Fetches a paginated list of workflow executions matching the given query.
+* Lists the executions of one workflow, newest first, a page at a time.
+*
+* Everything goes in the URL. The endpoint reads `page_size`, `page_token`, `worker_id` and
+* `with_resume` from there and ignores a JSON `query`, which is what this function used to send:
+* the page size had no effect and every "next page" came back as the first one.
 *
 * @param api - Axios instance used to make the HTTP request.
-* @param workflowId - The unique identifier of the workflow whose executions to list.
-* @param query - Query object containing filters, pagination, and sorting options.
-*   Must include a `workspace` filter expression.
-* @returns A promise that resolves with a {@link WorkflowExecutionListResponse} containing the matched executions.
-* @throws {Error} If the `workspace` filter is not present in `query.filters`.
+* @param workflowId - The workflow whose executions to list.
+* @param params - Workspace, paging, and the endpoint's two filters.
+* @param {AbortSignal} [signal] - Aborts the request itself; the list hooks pass the query's own.
+* @returns A page of executions, with the cursor to the next one.
+* @throws {Error} If `workspace` is empty.
 * @throws {Error} If the request fails.
 */
-var listWorkflowExecutions = async (api, workflowId, query) => {
-	const workspaceFilter = query.filters.find((filter) => filter[0] === "workspace");
-	const workspace = workspaceFilter?.[workspaceFilter.length - 1];
-	if (!workspace) throw new Error("Workspace filter is required to list workflows");
-	try {
-		const params = {
+var listWorkflowExecutions = async (api, workflowId, { workspace, pageSize, pageToken, workerId, withResume }, signal) => {
+	requireWorkspace(workspace, "list workflow executions");
+	const params = {
+		...pageParams({
 			workspace,
-			...query ? { query: JSON.stringify(query) } : {}
-		};
-		return (await api.get(`${baseUrl}/${workflowId}/workflow_executions`, { params })).data;
-	} catch (error) {
-		if (isAxiosError(error)) throw new Error(error.message || "Error listing workflow executions", { cause: error });
-		if (error instanceof Error) throw error;
-		throw new Error("Error listing workflow executions", { cause: error });
-	}
+			pageSize,
+			pageToken
+		}),
+		...workerId ? { worker_id: workerId } : {},
+		...withResume !== void 0 ? { with_resume: withResume } : {}
+	};
+	return request(() => api.get(`${baseUrl}/${workflowId}/workflow_executions`, {
+		params,
+		signal
+	}), "Error listing workflow executions");
 };
 /**
 * Fetches a single worker execution by ID.
@@ -235,55 +152,51 @@ var listWorkflowExecutions = async (api, workflowId, query) => {
 * @param workflowId - The unique identifier of the parent workflow.
 * @param workerExecutionId - The unique identifier of the worker execution to fetch.
 * @param workspace - The workspace in which the worker execution resides.
+* @param {AbortSignal} [signal] - Aborts the request itself; the entity hooks pass the query's own.
 * @returns A promise that resolves with the {@link WorkerExecution} object.
 * @throws {Error} If `workspace` is not provided.
 * @throws {Error} If the request fails.
 */
-var getWorkerExecution = async (api, workflowId, workerExecutionId, workspace) => {
-	if (!workspace) throw new Error("Workspace is required to fetch a worker execution");
-	try {
-		const params = {
-			workspace,
-			worker_execution_id: workerExecutionId,
-			with_result: true
-		};
-		return (await api.get(`${baseUrl}/${workflowId}/worker_executions`, { params })).data.worker_execution;
-	} catch (error) {
-		if (isAxiosError(error)) throw new Error(error.message || "Error fetching worker execution", { cause: error });
-		if (error instanceof Error) throw error;
-		throw new Error("Error fetching worker execution", { cause: error });
-	}
+var getWorkerExecution = async (api, workflowId, workerExecutionId, workspace, signal) => {
+	requireWorkspace(workspace, "fetch a worker execution");
+	const params = {
+		workspace,
+		worker_execution_id: workerExecutionId,
+		with_result: true
+	};
+	return (await request(() => api.get(`${baseUrl}/${workflowId}/worker_executions`, {
+		params,
+		signal
+	}), "Error fetching worker execution")).worker_execution;
 };
 /**
-* Fetches a paginated list of worker executions for a given workflow.
+* Lists every worker execution of one workflow execution, grouped by worker.
+*
+* The endpoint returns them all at once: it is not paginated and takes no query. Each group is
+* one worker, with its run as `execution`, or every parallel run as `executions`.
 *
 * @param api - Axios instance used to make the HTTP request.
-* @param workflowId - The unique identifier of the parent workflow.
-* @param workflowExecutionId - The unique identifier of the workflow execution to filter by.
-* @param query - Query object containing filters, pagination, and sorting options.
-*   Must include a `workspace` filter expression.
-* @returns A promise that resolves with a {@link WorkerExecutionListResponse} containing the matched worker executions.
-* @throws {Error} If the `workspace` filter is not present in `query.filters`.
+* @param workflowId - The parent workflow.
+* @param workflowExecutionId - The workflow execution whose workers to list.
+* @param params - Workspace, and whether to include results.
+* @param {AbortSignal} [signal] - Aborts the request itself; the hooks pass the query's own.
+* @returns The groups, and the highest parallel index among them.
+* @throws {Error} If `workspace` is empty.
 * @throws {Error} If the request fails.
 */
-var listWorkerExecutions = async (api, workflowId, workflowExecutionId, query) => {
-	const workspaceFilter = query.filters.find((filter) => filter[0] === "workspace");
-	const workspace = workspaceFilter?.[workspaceFilter.length - 1];
-	if (!workspace) throw new Error("Workspace filter is required to list worker executions");
-	try {
-		const params = {
-			workspace,
-			workflow_execution_id: workflowExecutionId,
-			...query ? { query: JSON.stringify(query) } : {}
-		};
-		return (await api.get(`${baseUrl}/${workflowId}/worker_executions`, { params })).data;
-	} catch (error) {
-		if (isAxiosError(error)) throw new Error(error.message || "Error listing worker executions", { cause: error });
-		if (error instanceof Error) throw error;
-		throw new Error("Error listing worker executions", { cause: error });
-	}
+var listWorkerExecutions = async (api, workflowId, workflowExecutionId, { workspace, withResult }, signal) => {
+	requireWorkspace(workspace, "list worker executions");
+	const params = {
+		workspace,
+		workflow_execution_id: workflowExecutionId,
+		...withResult !== void 0 ? { with_result: withResult } : {}
+	};
+	return request(() => api.get(`${baseUrl}/${workflowId}/worker_executions`, {
+		params,
+		signal
+	}), "Error listing worker executions");
 };
 //#endregion
-export { TERMINAL_RUN_STATUSES, getWorkerExecution, getWorkflow, getWorkflowExecution, listWorkerExecutions, listWorkflowExecutions, listWorkflows, pollWorkflowExecution, runWorkflow, runWorkflowAndGetResult };
+export { TERMINAL_RUN_STATUSES, getWorkerExecution, getWorkflow, getWorkflowExecution, isTerminalRunStatus, listWorkerExecutions, listWorkflowExecutions, listWorkflows, runWorkflow, terminalRunStatusOf };
 
 //# sourceMappingURL=workflow.js.map

package/dist/api/workflow.js.map

@@ -1 +1 @@
-{"version":3,"file":"workflow.js","names":[],"sources":["../../src/api/workflow.ts"],"sourcesContent":["import { isAxiosError, type AxiosInstance, type AxiosResponse } from \"axios\";\n\nimport type { AnyRecord } from \"@/types/anyRecord\";\nimport type { FilterExpression, QueryObject } from \"@/types/entityQuery\";\nimport type { WorkerExecution, WorkerExecutionListResponse, WorkerExecutionSingleResponse, Workflow, WorkflowExecution, WorkflowExecutionListResponse, WorkflowExecutionSingleResponse, WorkflowListResponse, WorkflowSingleResponse } from \"@/types/workflow\";\n\nconst baseUrl = \"workflows\";\n\n/**\n * Runs a workflow asynchronously.\n *\n * Starts the workflow in a non-blocking way: the response carries a workflow execution\n * with a non-terminal status (e.g. \"RUNNING\"). Use polling to wait for the terminal state.\n *\n * @param api - Axios instance used to make the HTTP request.\n * @param id - The unique identifier of the workflow to run.\n * @param workspace - The workspace in which the workflow will be executed.\n * @param parameters - Key-value parameters to pass to the workflow.\n * @returns A promise that resolves with the workflow execution response data.\n * @throws {Error} If `workspace` is not provided.\n * @throws {Error} If the request fails.\n */\nexport const runWorkflow = async (api: AxiosInstance, id: string, workspace: string, parameters: AnyRecord): Promise<AnyRecord> => {\n  \n  if (!workspace) {\n    throw new Error(\"Workspace is required to run workflow\");\n  } \n\n  try {\n    const body: AnyRecord = {\n      workspace,\n      parameters,\n    };\n\n    // eslint-disable-next-line @typescript-eslint/no-explicit-any\n    const response: AxiosResponse<any> = await api.post(`${baseUrl}/${id}/run`, body);\n\n    return response.data;\n  } catch (error: unknown) {\n    if (isAxiosError<AnyRecord>(error)) {\n      throw new Error(error.message || \"\", { cause: error });\n    }\n\n    if (error instanceof Error) {\n      throw error;\n    }\n\n    throw new Error(\"Error while running workflow\", { cause: error });\n  }\n};\n\n/**\n * Run statuses that indicate a workflow execution has reached a terminal state\n * (i.e. it is no longer running and will not change again).\n *\n * Union of the backend's `WORKFLOW_EXECUTION_STATUS_FINISHED` set and the API's documented\n * terminal `run_status` values (`SUCCEEDED`/`FAILED`/`KILLED`). `KILLED` is included so a\n * killed execution is detected as terminal instead of polling until timeout.\n */\nexport const TERMINAL_RUN_STATUSES = [\"CANCELED\", \"COMPLETED\", \"SUCCEEDED\", \"FAILED\", \"KILLED\"] as const;\n\nconst isTerminalRunStatus = (runStatus: unknown): boolean =>\n  TERMINAL_RUN_STATUSES.includes(String(runStatus ?? \"\").toUpperCase() as (typeof TERMINAL_RUN_STATUSES)[number]);\n\nconst sleep = (ms: number): Promise<void> => new Promise((resolve) => setTimeout(resolve, ms));\n\nexport type PollWorkflowExecutionOptions = {\n  /** Delay between status checks, in milliseconds. Defaults to 2000ms. */\n  intervalMs?: number;\n  /** Maximum time to wait for a terminal status before giving up, in milliseconds. Defaults to 5 minutes. */\n  timeoutMs?: number;\n  /** Optional abort signal to cancel polling (e.g. on unmount). */\n  signal?: AbortSignal;\n};\n\n/**\n * Polls a workflow execution until it reaches a terminal run status (see {@link TERMINAL_RUN_STATUSES}).\n *\n * This is the interim, non-blocking replacement for synchronous (`synchronous: true`) execution:\n * the workflow is started asynchronously and its status is checked periodically until it completes.\n *\n * @param api - Axios instance used to make the HTTP request.\n * @param workflowId - The unique identifier of the workflow.\n * @param executionId - The unique identifier of the workflow execution to poll.\n * @param workspace - The workspace in which the workflow execution resides.\n * @param options - Polling configuration (interval, timeout, abort signal).\n * @returns A promise that resolves with the terminal {@link WorkflowExecution}.\n * @throws {Error} If `workspace` is not provided.\n * @throws {Error} If polling is aborted via `options.signal`.\n * @throws {Error} If a terminal status is not reached before `options.timeoutMs` elapses.\n */\nexport const pollWorkflowExecution = async (\n  api: AxiosInstance,\n  workflowId: string,\n  executionId: string,\n  workspace: string,\n  options: PollWorkflowExecutionOptions = {}\n): Promise<WorkflowExecution> => {\n  if (!workspace) {\n    throw new Error(\"Workspace is required to poll a workflow execution\");\n  }\n\n  const { intervalMs = 2000, timeoutMs = 5 * 60 * 1000, signal } = options;\n  const startedAt = Date.now();\n\n  while (true) {\n    if (signal?.aborted) {\n      throw new Error(\"Workflow execution polling was aborted\");\n    }\n\n    const execution = await getWorkflowExecution(api, workflowId, executionId, workspace);\n\n    if (isTerminalRunStatus(execution.run_status)) {\n      return execution;\n    }\n\n    if (Date.now() - startedAt >= timeoutMs) {\n      throw new Error(\"Timed out while waiting for the workflow execution to complete\");\n    }\n\n    await sleep(intervalMs);\n  }\n};\n\n/**\n * Starts a workflow asynchronously and polls its execution until completion.\n *\n * Interim replacement for synchronous execution: instead of holding the request open with\n * `synchronous: true`, the workflow is started in a non-blocking way and its status is polled\n * until it reaches a terminal state, at which point the final execution (with its result) is returned.\n *\n * @param api - Axios instance used to make the HTTP request.\n * @param id - The unique identifier of the workflow to run.\n * @param workspace - The workspace in which the workflow will be executed.\n * @param parameters - Key-value parameters to pass to the workflow.\n * @param options - Polling configuration (interval, timeout, abort signal).\n * @returns A promise that resolves with the terminal {@link WorkflowExecution}.\n * @throws {Error} If `workspace` is not provided.\n * @throws {Error} If the run response does not contain a workflow execution id.\n * @throws {Error} If the workflow execution ends in a \"FAILED\" run status.\n * @throws {Error} If polling times out or is aborted.\n */\nconst runWorkflowAndPoll = async (\n  api: AxiosInstance,\n  id: string,\n  workspace: string,\n  parameters: AnyRecord,\n  options: PollWorkflowExecutionOptions = {}\n): Promise<WorkflowExecution> => {\n  if (!workspace) {\n    throw new Error(\"Workspace is required to run workflow\");\n  }\n\n  // Start the workflow asynchronously (non-blocking).\n  const startResponse = await runWorkflow(api, id, workspace, parameters);\n  const executionId = (startResponse.workflow_execution as WorkflowExecution | undefined)?.id;\n\n  if (!executionId) {\n    throw new Error(\"Workflow run did not return an execution id to poll\");\n  }\n\n  // Poll the execution status until it completes, then consume the result.\n  const execution = await pollWorkflowExecution(api, id, executionId, workspace, options);\n\n  if (String(execution.run_status ?? \"\").toUpperCase() === \"FAILED\") {\n    throw new Error(\"Workflow execution failed\");\n  }\n\n  return execution;\n};\n\n/**\n * The terminal workflow execution together with the output produced by its final (ender) worker.\n */\nexport type WorkflowResult = {\n  /** The terminal workflow execution. */\n  execution: WorkflowExecution;\n  /** The ender worker execution, or `null` if the execution did not reference one. */\n  workerExecution: WorkerExecution | null;\n  /** The output data produced by the ender worker (`workerExecution.result`), or `null`. */\n  result: Record<string, unknown> | null;\n};\n\n/**\n * Starts a workflow, polls it to completion, then fetches the output produced by its final worker.\n *\n * A workflow execution does not carry the output payload itself — it references the final worker via\n * `ender_worker_execution_id`, and that worker execution's `result` field holds the actual data.\n * This helper performs the full flow: start (async) → poll → fetch ender worker → return its `result`.\n *\n * @param api - Axios instance used to make the HTTP request.\n * @param id - The unique identifier of the workflow to run.\n * @param workspace - The workspace in which the workflow will be executed.\n * @param parameters - Key-value parameters to pass to the workflow.\n * @param options - Polling configuration (interval, timeout, abort signal).\n * @returns A promise that resolves with the {@link WorkflowResult} (execution, ender worker execution, and its result).\n * @throws {Error} If `workspace` is not provided.\n * @throws {Error} If the workflow execution ends in a \"FAILED\" run status.\n * @throws {Error} If polling times out or is aborted.\n */\nexport const runWorkflowAndGetResult = async (\n  api: AxiosInstance,\n  id: string,\n  workspace: string,\n  parameters: AnyRecord,\n  options: PollWorkflowExecutionOptions = {}\n): Promise<WorkflowResult> => {\n  const execution = await runWorkflowAndPoll(api, id, workspace, parameters, options);\n\n  const enderWorkerExecutionId = execution.ender_worker_execution_id;\n  if (!enderWorkerExecutionId) {\n    return { execution, workerExecution: null, result: null };\n  }\n\n  const workerExecution = await getWorkerExecution(api, id, enderWorkerExecutionId, workspace);\n\n  return { execution, workerExecution, result: workerExecution.result ?? null };\n};\n\n/**\n * Fetches a single workflow by ID.\n *\n * @param api - Axios instance used to make the HTTP request.\n * @param id - The unique identifier of the workflow to fetch.\n * @param workspace - The workspace in which the workflow resides.\n * @returns A promise that resolves with the {@link Workflow} object.\n * @throws {Error} If `workspace` is not provided.\n * @throws {Error} If the request fails.\n */\nexport const getWorkflow = async (api: AxiosInstance, id: string, workspace: string): Promise<Workflow> => {\n  if (!workspace) {\n    throw new Error(\"Workspace is required to fetch a workflow\");\n  }\n  \n  try {\n    const params: AnyRecord = { workspace };\n    const response: AxiosResponse<WorkflowSingleResponse> = await api.get(`${baseUrl}/${id}`, { params });\n\n    return response.data.workflow;\n  } catch (error: unknown) {\n    if (isAxiosError<AnyRecord>(error)) {\n      throw new Error(error.message || \"Error while fetching workflow\", { cause: error });\n    } \n    if (error instanceof Error) {\n      throw error;\n    }\n\n    throw new Error(\"Error while fetching workflow\", { cause: error });\n  }\n};\n\n/**\n * Fetches a paginated list of workflows using the legacy method (workspace as query param).\n *\n * @param api - Axios instance used to make the HTTP request.\n * @param workspace - Current workspace name. Sent as a query param via the legacy method, required by some API configurations.\n * @param pageSize - Number of items per page.\n * @param pageToken - Cursor token for the next page.\n * @returns A promise that resolves with a {@link WorkflowListResponse} containing the matched workflows.\n * @throws {Error} If the request fails.\n */\nexport const listWorkflows = async (api: AxiosInstance, workspace?: string, pageSize?: number, pageToken?: string): Promise<WorkflowListResponse> => {\n  const params: AnyRecord = {};\n\n  if (workspace) params.workspace = workspace;\n  if (pageSize) params.page_size = pageSize;\n  if (pageToken) params.page_token = pageToken;\n\n  try {\n    const response: AxiosResponse<WorkflowListResponse> = await api.get(baseUrl, { params });\n    return response.data;\n  } catch (error: unknown) {\n    if (isAxiosError<AnyRecord>(error)) {\n      throw new Error(error.message || \"Error listing workflows\", { cause: error });\n    }\n\n    if (error instanceof Error) {\n      throw error;\n    }\n\n    throw new Error(\"Error listing workflows\", { cause: error });\n  }\n};\n\n/**\n * Fetches a single workflow execution by ID.\n *\n * @param api - Axios instance used to make the HTTP request.\n * @param workflowId - The unique identifier of the workflow.\n * @param executionId - The unique identifier of the workflow execution to fetch.\n * @param workspace - The workspace in which the workflow execution resides.\n * @returns A promise that resolves with the {@link WorkflowExecution} object.\n * @throws {Error} If `workspace` is not provided.\n * @throws {Error} If the request fails.\n */\nexport const getWorkflowExecution = async (api: AxiosInstance, workflowId: string, executionId: string, workspace: string): Promise<WorkflowExecution> => {\n  if (!workspace) {\n    throw new Error(\"Workspace is required to fetch a workflow execution\");\n  }\n\n  try {\n    const params: AnyRecord = { workspace, workflow_execution_id: executionId };\n    const response: AxiosResponse<WorkflowExecutionSingleResponse> = await api.get(`${baseUrl}/${workflowId}/workflow_executions`, { params });\n    return response.data.workflow_execution;\n  } catch (error: unknown) {\n    if (isAxiosError<AnyRecord>(error)) {\n      throw new Error(error.message || \"Error fetching workflow execution\", { cause: error });\n    }\n\n    if (error instanceof Error) {\n      throw error;\n    }\n\n    throw new Error(\"Error fetching workflow execution\", { cause: error });\n  }\n};\n\n/**\n * Fetches a paginated list of workflow executions matching the given query.\n *\n * @param api - Axios instance used to make the HTTP request.\n * @param workflowId - The unique identifier of the workflow whose executions to list.\n * @param query - Query object containing filters, pagination, and sorting options.\n *   Must include a `workspace` filter expression.\n * @returns A promise that resolves with a {@link WorkflowExecutionListResponse} containing the matched executions.\n * @throws {Error} If the `workspace` filter is not present in `query.filters`.\n * @throws {Error} If the request fails.\n */\nexport const listWorkflowExecutions = async (api: AxiosInstance, workflowId: string, query: QueryObject): Promise<WorkflowExecutionListResponse> => {\n  const workspaceFilter = query.filters.find((filter: FilterExpression) => filter[0] === \"workspace\");\n  const workspace = workspaceFilter?.[workspaceFilter.length - 1];\n\n  if (!workspace) throw new Error(\"Workspace filter is required to list workflows\");\n\n  try {\n    const params: AnyRecord = {\n      workspace,\n      ...(query ? { query: JSON.stringify(query) } : {}),\n    };\n\n    const response: AxiosResponse<WorkflowExecutionListResponse> = await api.get(`${baseUrl}/${workflowId}/workflow_executions`, { params });\n    return response.data;\n  } catch (error: unknown) {\n    if (isAxiosError<AnyRecord>(error)) {\n      throw new Error(error.message || \"Error listing workflow executions\", { cause: error });\n    }\n\n    if (error instanceof Error) {\n      throw error;\n    }\n\n    throw new Error(\"Error listing workflow executions\", { cause: error });\n  }\n};\n\n/**\n * Fetches a single worker execution by ID.\n *\n * @param api - Axios instance used to make the HTTP request.\n * @param workflowId - The unique identifier of the parent workflow.\n * @param workerExecutionId - The unique identifier of the worker execution to fetch.\n * @param workspace - The workspace in which the worker execution resides.\n * @returns A promise that resolves with the {@link WorkerExecution} object.\n * @throws {Error} If `workspace` is not provided.\n * @throws {Error} If the request fails.\n */\nexport const getWorkerExecution = async (api: AxiosInstance, workflowId: string, workerExecutionId: string, workspace: string): Promise<WorkerExecution> => {\n  if (!workspace) {\n    throw new Error(\"Workspace is required to fetch a worker execution\");\n  }\n\n  try {\n    const params: AnyRecord = { workspace, worker_execution_id: workerExecutionId, with_result: true };\n    const response: AxiosResponse<WorkerExecutionSingleResponse> = await api.get(`${baseUrl}/${workflowId}/worker_executions`, { params });\n    return response.data.worker_execution;\n  } catch (error: unknown) {\n    if (isAxiosError<AnyRecord>(error)) {\n      throw new Error(error.message || \"Error fetching worker execution\", { cause: error });\n    }\n\n    if (error instanceof Error) {\n      throw error;\n    }\n\n    throw new Error(\"Error fetching worker execution\", { cause: error });\n  }\n}\n\n/**\n * Fetches a paginated list of worker executions for a given workflow.\n *\n * @param api - Axios instance used to make the HTTP request.\n * @param workflowId - The unique identifier of the parent workflow.\n * @param workflowExecutionId - The unique identifier of the workflow execution to filter by.\n * @param query - Query object containing filters, pagination, and sorting options.\n *   Must include a `workspace` filter expression.\n * @returns A promise that resolves with a {@link WorkerExecutionListResponse} containing the matched worker executions.\n * @throws {Error} If the `workspace` filter is not present in `query.filters`.\n * @throws {Error} If the request fails.\n */\nexport const listWorkerExecutions = async (api: AxiosInstance, workflowId: string, workflowExecutionId: string, query: QueryObject): Promise<WorkerExecutionListResponse> => {\n  const workspaceFilter = query.filters.find((filter: FilterExpression) => filter[0] === \"workspace\");\n  const workspace = workspaceFilter?.[workspaceFilter.length - 1];\n\n  if (!workspace) throw new Error(\"Workspace filter is required to list worker executions\");\n\n  try {\n    const params: AnyRecord = {\n      workspace,\n      workflow_execution_id: workflowExecutionId,\n      ...(query ? { query: JSON.stringify(query) } : {}),\n    };\n\n    const response: AxiosResponse<WorkerExecutionListResponse> = await api.get(`${baseUrl}/${workflowId}/worker_executions`, { params });\n    return response.data;\n  } catch (error: unknown) {\n    if (isAxiosError<AnyRecord>(error)) {\n      throw new Error(error.message || \"Error listing worker executions\", { cause: error });\n    }\n\n    if (error instanceof Error) {\n      throw error;\n    }\n\n    throw new Error(\"Error listing worker executions\", { cause: error });\n  }\n};"],"mappings":";;AAMA,IAAM,UAAU;;;;;;;;;;;;;;;AAgBhB,IAAa,cAAc,OAAO,KAAoB,IAAY,WAAmB,eAA8C;CAEjI,IAAI,CAAC,WACH,MAAM,IAAI,MAAM,uCAAuC;CAGzD,IAAI;EACF,MAAM,OAAkB;GACtB;GACA;EACF;EAKA,QAAO,MAFoC,IAAI,KAAK,GAAG,QAAQ,GAAG,GAAG,OAAO,IAAI,EAAA,CAEhE;CAClB,SAAS,OAAgB;EACvB,IAAI,aAAwB,KAAK,GAC/B,MAAM,IAAI,MAAM,MAAM,WAAW,IAAI,EAAE,OAAO,MAAM,CAAC;EAGvD,IAAI,iBAAiB,OACnB,MAAM;EAGR,MAAM,IAAI,MAAM,gCAAgC,EAAE,OAAO,MAAM,CAAC;CAClE;AACF;;;;;;;;;AAUA,IAAa,wBAAwB;CAAC;CAAY;CAAa;CAAa;CAAU;AAAQ;AAE9F,IAAM,uBAAuB,cAC3B,sBAAsB,SAAS,OAAO,aAAa,EAAE,CAAC,CAAC,YAAY,CAA2C;AAEhH,IAAM,SAAS,OAA8B,IAAI,SAAS,YAAY,WAAW,SAAS,EAAE,CAAC;;;;;;;;;;;;;;;;;AA2B7F,IAAa,wBAAwB,OACnC,KACA,YACA,aACA,WACA,UAAwC,CAAC,MACV;CAC/B,IAAI,CAAC,WACH,MAAM,IAAI,MAAM,oDAAoD;CAGtE,MAAM,EAAE,aAAa,KAAM,YAAY,KAAe,WAAW;CACjE,MAAM,YAAY,KAAK,IAAI;CAE3B,OAAO,MAAM;EACX,IAAI,QAAQ,SACV,MAAM,IAAI,MAAM,wCAAwC;EAG1D,MAAM,YAAY,MAAM,qBAAqB,KAAK,YAAY,aAAa,SAAS;EAEpF,IAAI,oBAAoB,UAAU,UAAU,GAC1C,OAAO;EAGT,IAAI,KAAK,IAAI,IAAI,aAAa,WAC5B,MAAM,IAAI,MAAM,gEAAgE;EAGlF,MAAM,MAAM,UAAU;CACxB;AACF;;;;;;;;;;;;;;;;;;;AAoBA,IAAM,qBAAqB,OACzB,KACA,IACA,WACA,YACA,UAAwC,CAAC,MACV;CAC/B,IAAI,CAAC,WACH,MAAM,IAAI,MAAM,uCAAuC;CAKzD,MAAM,eAAe,MADO,YAAY,KAAK,IAAI,WAAW,UAAU,EAAA,CACnC,oBAAsD;CAEzF,IAAI,CAAC,aACH,MAAM,IAAI,MAAM,qDAAqD;CAIvE,MAAM,YAAY,MAAM,sBAAsB,KAAK,IAAI,aAAa,WAAW,OAAO;CAEtF,IAAI,OAAO,UAAU,cAAc,EAAE,CAAC,CAAC,YAAY,MAAM,UACvD,MAAM,IAAI,MAAM,2BAA2B;CAG7C,OAAO;AACT;;;;;;;;;;;;;;;;;;AA+BA,IAAa,0BAA0B,OACrC,KACA,IACA,WACA,YACA,UAAwC,CAAC,MACb;CAC5B,MAAM,YAAY,MAAM,mBAAmB,KAAK,IAAI,WAAW,YAAY,OAAO;CAElF,MAAM,yBAAyB,UAAU;CACzC,IAAI,CAAC,wBACH,OAAO;EAAE;EAAW,iBAAiB;EAAM,QAAQ;CAAK;CAG1D,MAAM,kBAAkB,MAAM,mBAAmB,KAAK,IAAI,wBAAwB,SAAS;CAE3F,OAAO;EAAE;EAAW;EAAiB,QAAQ,gBAAgB,UAAU;CAAK;AAC9E;;;;;;;;;;;AAYA,IAAa,cAAc,OAAO,KAAoB,IAAY,cAAyC;CACzG,IAAI,CAAC,WACH,MAAM,IAAI,MAAM,2CAA2C;CAG7D,IAAI;EACF,MAAM,SAAoB,EAAE,UAAU;EAGtC,QAAO,MAFuD,IAAI,IAAI,GAAG,QAAQ,GAAG,MAAM,EAAE,OAAO,CAAC,EAAA,CAEpF,KAAK;CACvB,SAAS,OAAgB;EACvB,IAAI,aAAwB,KAAK,GAC/B,MAAM,IAAI,MAAM,MAAM,WAAW,iCAAiC,EAAE,OAAO,MAAM,CAAC;EAEpF,IAAI,iBAAiB,OACnB,MAAM;EAGR,MAAM,IAAI,MAAM,iCAAiC,EAAE,OAAO,MAAM,CAAC;CACnE;AACF;;;;;;;;;;;AAYA,IAAa,gBAAgB,OAAO,KAAoB,WAAoB,UAAmB,cAAsD;CACnJ,MAAM,SAAoB,CAAC;CAE3B,IAAI,WAAW,OAAO,YAAY;CAClC,IAAI,UAAU,OAAO,YAAY;CACjC,IAAI,WAAW,OAAO,aAAa;CAEnC,IAAI;EAEF,QAAO,MADqD,IAAI,IAAI,SAAS,EAAE,OAAO,CAAC,EAAA,CACvE;CAClB,SAAS,OAAgB;EACvB,IAAI,aAAwB,KAAK,GAC/B,MAAM,IAAI,MAAM,MAAM,WAAW,2BAA2B,EAAE,OAAO,MAAM,CAAC;EAG9E,IAAI,iBAAiB,OACnB,MAAM;EAGR,MAAM,IAAI,MAAM,2BAA2B,EAAE,OAAO,MAAM,CAAC;CAC7D;AACF;;;;;;;;;;;;AAaA,IAAa,uBAAuB,OAAO,KAAoB,YAAoB,aAAqB,cAAkD;CACxJ,IAAI,CAAC,WACH,MAAM,IAAI,MAAM,qDAAqD;CAGvE,IAAI;EACF,MAAM,SAAoB;GAAE;GAAW,uBAAuB;EAAY;EAE1E,QAAO,MADgE,IAAI,IAAI,GAAG,QAAQ,GAAG,WAAW,uBAAuB,EAAE,OAAO,CAAC,EAAA,CACzH,KAAK;CACvB,SAAS,OAAgB;EACvB,IAAI,aAAwB,KAAK,GAC/B,MAAM,IAAI,MAAM,MAAM,WAAW,qCAAqC,EAAE,OAAO,MAAM,CAAC;EAGxF,IAAI,iBAAiB,OACnB,MAAM;EAGR,MAAM,IAAI,MAAM,qCAAqC,EAAE,OAAO,MAAM,CAAC;CACvE;AACF;;;;;;;;;;;;AAaA,IAAa,yBAAyB,OAAO,KAAoB,YAAoB,UAA+D;CAClJ,MAAM,kBAAkB,MAAM,QAAQ,MAAM,WAA6B,OAAO,OAAO,WAAW;CAClG,MAAM,YAAY,kBAAkB,gBAAgB,SAAS;CAE7D,IAAI,CAAC,WAAW,MAAM,IAAI,MAAM,gDAAgD;CAEhF,IAAI;EACF,MAAM,SAAoB;GACxB;GACA,GAAI,QAAQ,EAAE,OAAO,KAAK,UAAU,KAAK,EAAE,IAAI,CAAC;EAClD;EAGA,QAAO,MAD8D,IAAI,IAAI,GAAG,QAAQ,GAAG,WAAW,uBAAuB,EAAE,OAAO,CAAC,EAAA,CACvH;CAClB,SAAS,OAAgB;EACvB,IAAI,aAAwB,KAAK,GAC/B,MAAM,IAAI,MAAM,MAAM,WAAW,qCAAqC,EAAE,OAAO,MAAM,CAAC;EAGxF,IAAI,iBAAiB,OACnB,MAAM;EAGR,MAAM,IAAI,MAAM,qCAAqC,EAAE,OAAO,MAAM,CAAC;CACvE;AACF;;;;;;;;;;;;AAaA,IAAa,qBAAqB,OAAO,KAAoB,YAAoB,mBAA2B,cAAgD;CAC1J,IAAI,CAAC,WACH,MAAM,IAAI,MAAM,mDAAmD;CAGrE,IAAI;EACF,MAAM,SAAoB;GAAE;GAAW,qBAAqB;GAAmB,aAAa;EAAK;EAEjG,QAAO,MAD8D,IAAI,IAAI,GAAG,QAAQ,GAAG,WAAW,qBAAqB,EAAE,OAAO,CAAC,EAAA,CACrH,KAAK;CACvB,SAAS,OAAgB;EACvB,IAAI,aAAwB,KAAK,GAC/B,MAAM,IAAI,MAAM,MAAM,WAAW,mCAAmC,EAAE,OAAO,MAAM,CAAC;EAGtF,IAAI,iBAAiB,OACnB,MAAM;EAGR,MAAM,IAAI,MAAM,mCAAmC,EAAE,OAAO,MAAM,CAAC;CACrE;AACF;;;;;;;;;;;;;AAcA,IAAa,uBAAuB,OAAO,KAAoB,YAAoB,qBAA6B,UAA6D;CAC3K,MAAM,kBAAkB,MAAM,QAAQ,MAAM,WAA6B,OAAO,OAAO,WAAW;CAClG,MAAM,YAAY,kBAAkB,gBAAgB,SAAS;CAE7D,IAAI,CAAC,WAAW,MAAM,IAAI,MAAM,wDAAwD;CAExF,IAAI;EACF,MAAM,SAAoB;GACxB;GACA,uBAAuB;GACvB,GAAI,QAAQ,EAAE,OAAO,KAAK,UAAU,KAAK,EAAE,IAAI,CAAC;EAClD;EAGA,QAAO,MAD4D,IAAI,IAAI,GAAG,QAAQ,GAAG,WAAW,qBAAqB,EAAE,OAAO,CAAC,EAAA,CACnH;CAClB,SAAS,OAAgB;EACvB,IAAI,aAAwB,KAAK,GAC/B,MAAM,IAAI,MAAM,MAAM,WAAW,mCAAmC,EAAE,OAAO,MAAM,CAAC;EAGtF,IAAI,iBAAiB,OACnB,MAAM;EAGR,MAAM,IAAI,MAAM,mCAAmC,EAAE,OAAO,MAAM,CAAC;CACrE;AACF"}
+{"version":3,"file":"workflow.js","names":[],"sources":["../../src/api/workflow.ts"],"sourcesContent":["import type { AxiosInstance } from \"axios\";\n\nimport type { AnyRecord } from \"@/types/anyRecord\";\nimport { pageParams, request, requireWorkspace } from \"./request\";\nimport type { EntitySingleResponse } from \"@/types/entityQuery\";\nimport type {\n    WorkerExecution,\n    WorkerExecutionListResponse,\n    Workflow,\n    WorkflowExecution,\n    WorkflowExecutionListResponse,\n    WorkflowListResponse,\n} from \"@/types/workflow\";\n\nconst baseUrl = \"workflows\";\n\n/** The endpoints' envelopes, private: every function here returns the entity itself. */\ntype WorkflowSingleResponse = EntitySingleResponse<\"workflow\", Workflow>;\ntype WorkflowExecutionSingleResponse = EntitySingleResponse<\n    \"workflow_execution\",\n    WorkflowExecution\n>;\ntype WorkerExecutionSingleResponse = EntitySingleResponse<\"worker_execution\", WorkerExecution>;\n\n/**\n * What `POST /workflows/:id/run` answers: the execution it started, still `RUNNING`, and a\n * `result` that is always `null` — the run is asynchronous, and the output is read from the\n * Ender's worker execution once it finishes. Private: `runWorkflow` returns the execution.\n */\ntype RunWorkflowResponse = {\n    workflow_execution: WorkflowExecution;\n    result: null;\n};\n\n/**\n * Runs a workflow asynchronously.\n *\n * Starts the workflow in a non-blocking way: the response carries a workflow execution\n * with a non-terminal status (e.g. \"RUNNING\"). `useRunWorkflow` waits for the end over\n * the websocket.\n *\n * @param api - Axios instance used to make the HTTP request.\n * @param id - The unique identifier of the workflow to run.\n * @param workspace - The workspace in which the workflow will be executed.\n * @param parameters - Key-value parameters to pass to the workflow.\n * @returns The execution the run started, still `RUNNING`. It used to be the raw body,\n *   `{ workflow_execution, result: null }`, where every other function returns the entity.\n * @throws {Error} If `workspace` is not provided.\n * @throws {Error} If the request fails.\n */\nexport const runWorkflow = async (\n    api: AxiosInstance,\n    id: string,\n    workspace: string,\n    parameters: AnyRecord,\n): Promise<WorkflowExecution> => {\n    requireWorkspace(workspace, \"run a workflow\");\n\n    const body = await request(\n        () => api.post<RunWorkflowResponse>(`${baseUrl}/${id}/run`, { workspace, parameters }),\n        \"Error running workflow\",\n    );\n    return body.workflow_execution;\n};\n\n/**\n * The run statuses a workflow execution can end with. The backend writes `RUNNING` when the run\n * starts, and `SUCCEEDED` or `FAILED` once its Ender finishes; `CANCELED` is reserved for a\n * cancellation it does not write yet. This list used to carry `KILLED`, which the backend never\n * writes, and `COMPLETED`, the value of the deprecated `status` field, seen in `run_status` only\n * on executions from before 2024-10-03.\n */\nexport const TERMINAL_RUN_STATUSES = [\"SUCCEEDED\", \"FAILED\", \"CANCELED\"] as const;\n\nexport type TerminalRunStatus = (typeof TERMINAL_RUN_STATUSES)[number];\n\n/**\n * The status a run ended with, read whatever its case; `null` while it has not ended. A missing\n * status — a projection can drop the field, and JSON can carry it as `null` — is a run not known\n * to have ended. The one place a run's status is read, so a comparison against it is typed.\n */\nexport const terminalRunStatusOf = (\n    runStatus: string | null | undefined,\n): TerminalRunStatus | null => {\n    const upper = runStatus?.toUpperCase();\n    return TERMINAL_RUN_STATUSES.find((status) => status === upper) ?? null;\n};\n\n/** Whether a run with this `run_status` has ended; see `terminalRunStatusOf`. */\nexport const isTerminalRunStatus = (runStatus: string | null | undefined): boolean =>\n    terminalRunStatusOf(runStatus) !== null;\n\n/**\n * Fetches a single workflow by ID.\n *\n * @param api - Axios instance used to make the HTTP request.\n * @param id - The unique identifier of the workflow to fetch.\n * @param workspace - The workspace in which the workflow resides.\n * @param {AbortSignal} [signal] - Aborts the request itself; the entity hooks pass the query's own.\n * @returns A promise that resolves with the {@link Workflow} object.\n * @throws {Error} If `workspace` is not provided.\n * @throws {Error} If the request fails.\n */\nexport const getWorkflow = async (\n    api: AxiosInstance,\n    id: string,\n    workspace: string,\n    signal?: AbortSignal,\n): Promise<Workflow> => {\n    requireWorkspace(workspace, \"fetch a workflow\");\n\n    const body = await request(\n        () =>\n            api.get<WorkflowSingleResponse>(`${baseUrl}/${id}`, { params: { workspace }, signal }),\n        \"Error fetching workflow\",\n    );\n    return body.workflow;\n};\n\n/** What `listWorkflows` sends. */\nexport type WorkflowListParams = {\n    /** Required: without one the API lists `main` rather than failing, and refuses a sub-user. */\n    workspace: string;\n    /** A name prefix, an id, `#tag #tag` (every tag), or `&link_uid`. Sent as `query`. */\n    search?: string;\n    pageSize?: number;\n    pageToken?: string;\n};\n\n/**\n * Lists the workflows of a workspace, a page at a time.\n *\n * The endpoint takes a text search rather than the JSON query the other lists take, so this\n * takes `search` rather than a `QueryObject`.\n *\n * @param api - Axios instance used to make the HTTP request.\n * @param params - Workspace, search and paging.\n * @param {AbortSignal} [signal] - Aborts the request itself; the list hooks pass the query's own.\n * @returns A page of workflows, with the cursor to the next one.\n * @throws {Error} If `workspace` is empty.\n * @throws {Error} If the request fails.\n */\nexport const listWorkflows = async (\n    api: AxiosInstance,\n    { workspace, search, pageSize, pageToken }: WorkflowListParams,\n    signal?: AbortSignal,\n): Promise<WorkflowListResponse> => {\n    requireWorkspace(workspace, \"list workflows\");\n\n    const params = pageParams({ workspace, search, pageSize, pageToken });\n\n    return request(\n        () => api.get<WorkflowListResponse>(baseUrl, { params, signal }),\n        \"Error listing workflows\",\n    );\n};\n\n/**\n * Fetches a single workflow execution by ID.\n *\n * @param api - Axios instance used to make the HTTP request.\n * @param workflowId - The unique identifier of the workflow.\n * @param workflowExecutionId - The unique identifier of the workflow execution to fetch.\n * @param workspace - The workspace in which the workflow execution resides.\n * @param {AbortSignal} [signal] - Aborts the request itself; the entity hooks pass the query's own.\n * @returns A promise that resolves with the {@link WorkflowExecution} object.\n * @throws {Error} If `workspace` is not provided.\n * @throws {Error} If the request fails.\n */\nexport const getWorkflowExecution = async (\n    api: AxiosInstance,\n    workflowId: string,\n    workflowExecutionId: string,\n    workspace: string,\n    signal?: AbortSignal,\n): Promise<WorkflowExecution> => {\n    requireWorkspace(workspace, \"fetch a workflow execution\");\n\n    const params: AnyRecord = { workspace, workflow_execution_id: workflowExecutionId };\n    const body = await request(\n        () =>\n            api.get<WorkflowExecutionSingleResponse>(\n                `${baseUrl}/${workflowId}/workflow_executions`,\n                { params, signal },\n            ),\n        \"Error fetching workflow execution\",\n    );\n    return body.workflow_execution;\n};\n\n/** What `listWorkflowExecutions` sends: the parameters the endpoint reads, each from the URL. */\nexport type WorkflowExecutionListParams = {\n    /** Not used to filter: the endpoint lists the workflow's executions. A sub-user's role check needs it. */\n    workspace: string;\n    pageSize?: number;\n    pageToken?: string;\n    /** Only the executions this worker took part in. */\n    workerId?: string;\n    /** Include each execution's `resume`, the per-worker summary. The API leaves it out by default. */\n    withResume?: boolean;\n};\n\n/**\n * Lists the executions of one workflow, newest first, a page at a time.\n *\n * Everything goes in the URL. The endpoint reads `page_size`, `page_token`, `worker_id` and\n * `with_resume` from there and ignores a JSON `query`, which is what this function used to send:\n * the page size had no effect and every \"next page\" came back as the first one.\n *\n * @param api - Axios instance used to make the HTTP request.\n * @param workflowId - The workflow whose executions to list.\n * @param params - Workspace, paging, and the endpoint's two filters.\n * @param {AbortSignal} [signal] - Aborts the request itself; the list hooks pass the query's own.\n * @returns A page of executions, with the cursor to the next one.\n * @throws {Error} If `workspace` is empty.\n * @throws {Error} If the request fails.\n */\nexport const listWorkflowExecutions = async (\n    api: AxiosInstance,\n    workflowId: string,\n    { workspace, pageSize, pageToken, workerId, withResume }: WorkflowExecutionListParams,\n    signal?: AbortSignal,\n): Promise<WorkflowExecutionListResponse> => {\n    requireWorkspace(workspace, \"list workflow executions\");\n\n    const params = {\n        ...pageParams({ workspace, pageSize, pageToken }),\n        ...(workerId ? { worker_id: workerId } : {}),\n        ...(withResume !== undefined ? { with_resume: withResume } : {}),\n    };\n\n    return request(\n        () =>\n            api.get<WorkflowExecutionListResponse>(`${baseUrl}/${workflowId}/workflow_executions`, {\n                params,\n                signal,\n            }),\n        \"Error listing workflow executions\",\n    );\n};\n\n/**\n * Fetches a single worker execution by ID.\n *\n * @param api - Axios instance used to make the HTTP request.\n * @param workflowId - The unique identifier of the parent workflow.\n * @param workerExecutionId - The unique identifier of the worker execution to fetch.\n * @param workspace - The workspace in which the worker execution resides.\n * @param {AbortSignal} [signal] - Aborts the request itself; the entity hooks pass the query's own.\n * @returns A promise that resolves with the {@link WorkerExecution} object.\n * @throws {Error} If `workspace` is not provided.\n * @throws {Error} If the request fails.\n */\nexport const getWorkerExecution = async (\n    api: AxiosInstance,\n    workflowId: string,\n    workerExecutionId: string,\n    workspace: string,\n    signal?: AbortSignal,\n): Promise<WorkerExecution> => {\n    requireWorkspace(workspace, \"fetch a worker execution\");\n\n    const params: AnyRecord = {\n        workspace,\n        worker_execution_id: workerExecutionId,\n        with_result: true,\n    };\n    const body = await request(\n        () =>\n            api.get<WorkerExecutionSingleResponse>(`${baseUrl}/${workflowId}/worker_executions`, {\n                params,\n                signal,\n            }),\n        \"Error fetching worker execution\",\n    );\n    return body.worker_execution;\n};\n\n/** What `listWorkerExecutions` sends besides the execution id. */\nexport type WorkerExecutionListParams = {\n    /** Not used to filter. A sub-user's role check needs it. */\n    workspace: string;\n    /** Include each run's `result` and `input_params`. The API leaves them out by default. */\n    withResult?: boolean;\n};\n\n/**\n * Lists every worker execution of one workflow execution, grouped by worker.\n *\n * The endpoint returns them all at once: it is not paginated and takes no query. Each group is\n * one worker, with its run as `execution`, or every parallel run as `executions`.\n *\n * @param api - Axios instance used to make the HTTP request.\n * @param workflowId - The parent workflow.\n * @param workflowExecutionId - The workflow execution whose workers to list.\n * @param params - Workspace, and whether to include results.\n * @param {AbortSignal} [signal] - Aborts the request itself; the hooks pass the query's own.\n * @returns The groups, and the highest parallel index among them.\n * @throws {Error} If `workspace` is empty.\n * @throws {Error} If the request fails.\n */\nexport const listWorkerExecutions = async (\n    api: AxiosInstance,\n    workflowId: string,\n    workflowExecutionId: string,\n    { workspace, withResult }: WorkerExecutionListParams,\n    signal?: AbortSignal,\n): Promise<WorkerExecutionListResponse> => {\n    requireWorkspace(workspace, \"list worker executions\");\n\n    const params = {\n        workspace,\n        workflow_execution_id: workflowExecutionId,\n        ...(withResult !== undefined ? { with_result: withResult } : {}),\n    };\n\n    return request(\n        () =>\n            api.get<WorkerExecutionListResponse>(`${baseUrl}/${workflowId}/worker_executions`, {\n                params,\n                signal,\n            }),\n        \"Error listing worker executions\",\n    );\n};\n"],"mappings":";;AAcA,IAAM,UAAU;;;;;;;;;;;;;;;;;AAoChB,IAAa,cAAc,OACvB,KACA,IACA,WACA,eAC6B;CAC7B,iBAAiB,WAAW,gBAAgB;CAM5C,QAAO,MAJY,cACT,IAAI,KAA0B,GAAG,QAAQ,GAAG,GAAG,OAAO;EAAE;EAAW;CAAW,CAAC,GACrF,wBACJ,EAAA,CACY;AAChB;;;;;;;;AASA,IAAa,wBAAwB;CAAC;CAAa;CAAU;AAAU;;;;;;AASvE,IAAa,uBACT,cAC2B;CAC3B,MAAM,QAAQ,WAAW,YAAY;CACrC,OAAO,sBAAsB,MAAM,WAAW,WAAW,KAAK,KAAK;AACvE;;AAGA,IAAa,uBAAuB,cAChC,oBAAoB,SAAS,MAAM;;;;;;;;;;;;AAavC,IAAa,cAAc,OACvB,KACA,IACA,WACA,WACoB;CACpB,iBAAiB,WAAW,kBAAkB;CAO9C,QAAO,MALY,cAEX,IAAI,IAA4B,GAAG,QAAQ,GAAG,MAAM;EAAE,QAAQ,EAAE,UAAU;EAAG;CAAO,CAAC,GACzF,yBACJ,EAAA,CACY;AAChB;;;;;;;;;;;;;;AAyBA,IAAa,gBAAgB,OACzB,KACA,EAAE,WAAW,QAAQ,UAAU,aAC/B,WACgC;CAChC,iBAAiB,WAAW,gBAAgB;CAE5C,MAAM,SAAS,WAAW;EAAE;EAAW;EAAQ;EAAU;CAAU,CAAC;CAEpE,OAAO,cACG,IAAI,IAA0B,SAAS;EAAE;EAAQ;CAAO,CAAC,GAC/D,yBACJ;AACJ;;;;;;;;;;;;;AAcA,IAAa,uBAAuB,OAChC,KACA,YACA,qBACA,WACA,WAC6B;CAC7B,iBAAiB,WAAW,4BAA4B;CAExD,MAAM,SAAoB;EAAE;EAAW,uBAAuB;CAAoB;CASlF,QAAO,MARY,cAEX,IAAI,IACA,GAAG,QAAQ,GAAG,WAAW,uBACzB;EAAE;EAAQ;CAAO,CACrB,GACJ,mCACJ,EAAA,CACY;AAChB;;;;;;;;;;;;;;;;AA6BA,IAAa,yBAAyB,OAClC,KACA,YACA,EAAE,WAAW,UAAU,WAAW,UAAU,cAC5C,WACyC;CACzC,iBAAiB,WAAW,0BAA0B;CAEtD,MAAM,SAAS;EACX,GAAG,WAAW;GAAE;GAAW;GAAU;EAAU,CAAC;EAChD,GAAI,WAAW,EAAE,WAAW,SAAS,IAAI,CAAC;EAC1C,GAAI,eAAe,KAAA,IAAY,EAAE,aAAa,WAAW,IAAI,CAAC;CAClE;CAEA,OAAO,cAEC,IAAI,IAAmC,GAAG,QAAQ,GAAG,WAAW,uBAAuB;EACnF;EACA;CACJ,CAAC,GACL,mCACJ;AACJ;;;;;;;;;;;;;AAcA,IAAa,qBAAqB,OAC9B,KACA,YACA,mBACA,WACA,WAC2B;CAC3B,iBAAiB,WAAW,0BAA0B;CAEtD,MAAM,SAAoB;EACtB;EACA,qBAAqB;EACrB,aAAa;CACjB;CASA,QAAO,MARY,cAEX,IAAI,IAAmC,GAAG,QAAQ,GAAG,WAAW,qBAAqB;EACjF;EACA;CACJ,CAAC,GACL,iCACJ,EAAA,CACY;AAChB;;;;;;;;;;;;;;;;AAyBA,IAAa,uBAAuB,OAChC,KACA,YACA,qBACA,EAAE,WAAW,cACb,WACuC;CACvC,iBAAiB,WAAW,wBAAwB;CAEpD,MAAM,SAAS;EACX;EACA,uBAAuB;EACvB,GAAI,eAAe,KAAA,IAAY,EAAE,aAAa,WAAW,IAAI,CAAC;CAClE;CAEA,OAAO,cAEC,IAAI,IAAiC,GAAG,QAAQ,GAAG,WAAW,qBAAqB;EAC/E;EACA;CACJ,CAAC,GACL,iCACJ;AACJ"}

package/dist/api/workspace.d.ts

@@ -1,4 +1,4 @@
-import { type AxiosInstance } from "axios";
+import type { AxiosInstance } from "axios";
 import type { Workspace, WorkspaceListResponse } from "../types/workspace.d.ts";
 /**
  * getWorkspace
@@ -7,23 +7,33 @@ import type { Workspace, WorkspaceListResponse } from "../types/workspace.d.ts";
  *
  * @param {AxiosInstance} api - Axios instance.
  * @param {string} name - Workspace name.
+ * @param {AbortSignal} [signal] - Aborts the request itself; the entity hooks pass the query's own.
  * @returns {Promise<Workspace>} The fetched workspace.
  *
  * @throws {Error} If the request fails.
  */
-export declare const getWorkspace: (api: AxiosInstance, name: string) => Promise<Workspace>;
+export declare const getWorkspace: (api: AxiosInstance, name: string, signal?: AbortSignal) => Promise<Workspace>;
+/** What `listWorkspaces` sends. */
+export type WorkspaceListParams = {
+    /** A name prefix. Sent as `query`. */
+    search?: string;
+    pageSize?: number;
+    pageToken?: string;
+};
 /**
  * listWorkspaces
  *
- * Fetches a list of workspaces with optional cursor-based pagination.
+ * Lists the account's workspaces, a page at a time.
+ *
+ * The one list that takes no workspace: the docs exempt it, and the endpoint ignores one. This
+ * function used to send it anyway, documented as "required by some API configurations".
  *
  * @param {AxiosInstance} api - Axios instance.
- * @param {string} [workspace] - Current workspace name. Sent as a query param via the legacy method, required by some API configurations.
- * @param {number} [pageSize] - Number of items per page.
- * @param {string} [pageToken] - Cursor token for the next page.
- * @returns {Promise<WorkspaceListResponse>} List of workspaces.
+ * @param {WorkspaceListParams} [params] - Search and paging.
+ * @param {AbortSignal} [signal] - Aborts the request itself; the list hooks pass the query's own.
+ * @returns {Promise<WorkspaceListResponse>} A page of workspaces, with the cursor to the next one.
  *
  * @throws {Error} If the request fails.
  */
-export declare const listWorkspaces: (api: AxiosInstance, workspace?: string, pageSize?: number, pageToken?: string) => Promise<WorkspaceListResponse>;
+export declare const listWorkspaces: (api: AxiosInstance, { search, pageSize, pageToken }?: WorkspaceListParams, signal?: AbortSignal) => Promise<WorkspaceListResponse>;
 //# sourceMappingURL=workspace.d.ts.map

package/dist/api/workspace.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"workspace.d.ts","sourceRoot":"","sources":["../../src/api/workspace.ts"],"names":[],"mappings":"AAAA,OAAO,EAAgB,KAAK,aAAa,EAAsB,MAAM,OAAO,CAAC;AAG7E,OAAO,KAAK,EAAE,SAAS,EAAE,qBAAqB,EAA2B,MAAM,mBAAmB,CAAC;AAInG;;;;;;;;;;GAUG;AACH,eAAO,MAAM,YAAY,GAAU,KAAK,aAAa,EAAE,MAAM,MAAM,KAAG,OAAO,CAAC,SAAS,CAiBtF,CAAC;AAEF;;;;;;;;;;;;GAYG;AACH,eAAO,MAAM,cAAc,GAAU,KAAK,aAAa,EAAE,YAAY,MAAM,EAAE,WAAW,MAAM,EAAE,YAAY,MAAM,KAAG,OAAO,CAAC,qBAAqB,CAqBjJ,CAAC"}
+{"version":3,"file":"workspace.d.ts","sourceRoot":"","sources":["../../src/api/workspace.ts"],"names":[],"mappings":"AAAA,OAAO,KAAK,EAAE,aAAa,EAAE,MAAM,OAAO,CAAC;AAG3C,OAAO,KAAK,EAAE,SAAS,EAAE,qBAAqB,EAAE,MAAM,mBAAmB,CAAC;AAQ1E;;;;;;;;;;;GAWG;AACH,eAAO,MAAM,YAAY,GACrB,KAAK,aAAa,EAClB,MAAM,MAAM,EACZ,SAAS,WAAW,KACrB,OAAO,CAAC,SAAS,CAQnB,CAAC;AAEF,mCAAmC;AACnC,MAAM,MAAM,mBAAmB,GAAG;IAC9B,sCAAsC;IACtC,MAAM,CAAC,EAAE,MAAM,CAAC;IAChB,QAAQ,CAAC,EAAE,MAAM,CAAC;IAClB,SAAS,CAAC,EAAE,MAAM,CAAC;CACtB,CAAC;AAEF;;;;;;;;;;;;;;GAcG;AACH,eAAO,MAAM,cAAc,GACvB,KAAK,aAAa,EAClB,kCAAiC,mBAAwB,EACzD,SAAS,WAAW,KACrB,OAAO,CAAC,qBAAqB,CAO/B,CAAC"}