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

package/src/hooks/workflow/useFetchWorkflowExecutions.ts

@@ -1,95 +1,86 @@
-import { useMemo } from "react";
-import { useInfiniteQuery, type UseInfiniteQueryOptions, type QueryKey } from "@tanstack/react-query";
-
 import { useAxios } from "@/hooks/useAxios";
+import { useEntityInfiniteQuery } from "@/hooks/useEntityInfiniteQuery";
 import { listWorkflowExecutions } from "@/api/workflow";
-import type { FetchEntitiesParams } from "@/types/entityQuery";
-import { buildQueryKey, buildQueryObject } from "@/api/entityQuery";
+import type { FetchEntitiesProps, ListCache } from "@/types/entityQuery";
+import { buildQueryKey, missingWorkspaceError } from "@/api/entityQuery";
 import type { WorkflowExecution, WorkflowExecutionListResponse } from "@/types/workflow";
 
-type PageToken = string | null;
-
-type InfiniteOptions<TData> = Omit<UseInfiniteQueryOptions<WorkflowExecutionListResponse, Error, TData, QueryKey, PageToken>, "queryKey" | "queryFn" | "initialPageParam" | "getNextPageParam">;
+/** The query cache of `useFetchWorkflowExecutions`, for typing `setQueryData`. */
+export type WorkflowExecutionsCache = ListCache<WorkflowExecutionListResponse>;
 
-export type FetchInfiniteWorkflowExecutionProps = FetchEntitiesParams<WorkflowExecution[], InfiniteOptions<WorkflowExecution[]>> & {
+export type FetchWorkflowExecutionsProps<TData = WorkflowExecution[]> = FetchEntitiesProps<
+    WorkflowExecution,
+    TData,
+    WorkflowExecutionListResponse
+> & {
     workflowId: string;
-    pageSize?: number;
-};
-
-const defaultQueryOptions: InfiniteOptions<WorkflowExecution[]> = {
-    refetchOnMount: "always",
-    staleTime: 0,
-    gcTime: 0,
+    workspace: string;
+    /** Only the executions this worker took part in. */
+    workerId?: string;
+    /** Include each execution's `resume`, the per-worker summary. */
+    withResume?: boolean;
 };
 
 /**
  * useFetchWorkflowExecutions
  *
- * Data-fetching hook built on TanStack Query's `useInfiniteQuery` to retrieve
- * workflow executions for a given workflow with cursor-based pagination.
- *
- * Automatically flattens all pages into a single `WorkflowExecution[]` via `select`.
- *
- * Note: `query.data` returns a flat `WorkflowExecution[]` with all fetched items merged across pages.
- *
- * @param workflowId - Workflow identifier whose executions to fetch (required).
- * @param filters - Filters applied to every page request. Must include a `workspace` filter.
- * @param order - Sorting applied to every page request.
- * @param projection - Single field to project: `"field"` returns only that field (others come
- *   back null), `"-field"` returns every field except that one. One field only — lists 500. Omitted when empty.
- * @param pageSize - Number of executions to fetch per page. Defaults to `10`.
- * @param queryOptions - TanStack Query options passed through to `useInfiniteQuery`.
+ * Lists the executions of one workflow, newest first, with cursor pagination; `query.data` is
+ * every loaded page merged, or whatever `select` makes of it. `select`, `fetchAllPages` and the
+ * missing-workspace error behave as in `useFetchDatastores`. Idle while `workflowId` is empty.
  *
- * @returns
- *   - `query`: the full `useInfiniteQuery` result (data, isLoading, hasNextPage, fetchNextPage, etc.)
- *   - `queryKey`: the cache key used by React Query
+ * The endpoint takes no filters, order or projection: only a worker id and `withResume`. It used
+ * to accept them as props and send them in a JSON query the endpoint ignores, along with the
+ * cursor, so every "next page" was the first one.
  *
- * @example
- * ```ts
- * const { query } = useFetchWorkflowExecutions({
- *   workflowId: "wf-123",
- *   filters: [{ field: "workspace", value: "main" }],
- *   pageSize: 20,
- * });
+ * The key starts with `["workflow_executions", workflowId]`, which is what apps invalidate to
+ * refresh the list after running a workflow.
  *
- * // Flat list of all fetched executions
- * const executions = query.data ?? [];
- * ```
+ * @param {FetchWorkflowExecutionsProps} props - Workflow id, workspace, worker id,
+ *   `withResume`, page size, `select`, `fetchAllPages`, `queryOptions`.
+ * @returns {object} `query` (the `useInfiniteQuery` result) and `queryKey`.
  */
-export function useFetchWorkflowExecutions({ workflowId, filters = [], order = [], projection = "", pageSize = 10, queryOptions }: FetchInfiniteWorkflowExecutionProps) {
+export function useFetchWorkflowExecutions<TData = WorkflowExecution[]>({
+    workflowId,
+    workspace,
+    workerId,
+    withResume,
+    pageSize = 10,
+    select,
+    fetchAllPages = false,
+    queryOptions,
+}: FetchWorkflowExecutionsProps<TData>) {
     const { api } = useAxios();
 
-    const queryKey = buildQueryKey(["workflow_executions", workflowId], filters);
-
-    const mergedQueryOptions = useMemo<InfiniteOptions<WorkflowExecution[]>>(() => ({
-        ...defaultQueryOptions,
-        ...(queryOptions ?? {}),
-    }), [queryOptions]);
+    // The endpoint's two filters go in the key as filters, so a list per worker gets its own entry.
+    const filters = [
+        ...(workerId ? [{ field: "worker_id", value: workerId }] : []),
+        ...(withResume !== undefined ? [{ field: "with_resume", value: withResume }] : []),
+    ];
+    const queryKey = buildQueryKey(["workflow_executions", workflowId, workspace], filters, {
+        pageSize,
+        fetchAllPages,
+    });
 
-    const query = useInfiniteQuery<WorkflowExecutionListResponse, Error, WorkflowExecution[], QueryKey, PageToken>({
+    const query = useEntityInfiniteQuery<
+        WorkflowExecutionListResponse,
+        "workflow_executions",
+        TData
+    >({
         queryKey,
-        initialPageParam: null,
-        getNextPageParam: (lastPage) => lastPage.next_page_token ?? undefined,
-
-        queryFn: async ({ pageParam }) => {
-            const queryFilter = buildQueryObject({
-                filters,
-                order,
-                projection,
-                pageSize,
-                pageToken: pageParam ?? undefined,
-            });
-
-            return await listWorkflowExecutions(api, workflowId, queryFilter);
-        },
-
-        select: (data) => data.pages.flatMap((p) => p.workflow_executions),
-
-        ...mergedQueryOptions,
+        itemsKey: "workflow_executions",
+        fetchPage: (pageToken, signal) =>
+            listWorkflowExecutions(
+                api,
+                workflowId,
+                { workspace, pageSize, pageToken: pageToken ?? undefined, workerId, withResume },
+                signal,
+            ),
+        select,
+        fetchAllPages,
+        enabled: Boolean(workflowId),
+        configError: workspace ? undefined : missingWorkspaceError("useFetchWorkflowExecutions"),
+        queryOptions,
     });
 
-    return {
-        query,
-        queryKey,
-    };
+    return { query, queryKey };
 }

package/src/hooks/workflow/useFetchWorkflows.ts

@@ -1,84 +1,68 @@
-import { useMemo } from "react";
-import { useInfiniteQuery, type UseInfiniteQueryOptions, type QueryKey } from "@tanstack/react-query";
-
 import { useAxios } from "@/hooks/useAxios";
+import { useEntityInfiniteQuery } from "@/hooks/useEntityInfiniteQuery";
 import { listWorkflows } from "@/api/workflow";
+import { buildQueryKey, missingWorkspaceError } from "@/api/entityQuery";
 import type { Workflow, WorkflowListResponse } from "@/types/workflow";
+import type { FetchEntitiesProps, ListCache } from "@/types/entityQuery";
 
-type PageToken = string | null;
-
-type InfiniteOptions<TData> = Omit<UseInfiniteQueryOptions<WorkflowListResponse, Error, TData, QueryKey, PageToken>,"queryKey" | "queryFn" | "initialPageParam" | "getNextPageParam">;
-
-export type FetchInfiniteWorkflowProps = {
-    workspace?: string;
-    pageSize?: number;
-    queryOptions?: InfiniteOptions<Workflow[]>;
-};
+/** The query cache of `useFetchWorkflows`, for typing `setQueryData`. */
+export type WorkflowsCache = ListCache<WorkflowListResponse>;
 
-const defaultQueryOptions: InfiniteOptions<Workflow[]> = {
-    refetchOnMount: "always",
-    staleTime: 0,
-    gcTime: 0,
+export type FetchWorkflowsProps<TData = Workflow[]> = FetchEntitiesProps<
+    Workflow,
+    TData,
+    WorkflowListResponse
+> & {
+    /** Workspace to list. Required: without one the API reads `main`, not the account. */
+    workspace: string;
+    /** A name prefix, an id, `#tag #tag` (every tag), or `&link_uid`. */
+    search?: string;
 };
 
 /**
  * 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).
- *
- * Automatically flattens all pages into a single `Workflow[]` via `select`.
- *
- * 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.
+ * 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.
  *
- * @param {InfiniteOptions<Workflow[]>} [queryOptions]
- *   TanStack Query options passed through to `useInfiniteQuery`
- *   (e.g., enabled, staleTime, gcTime, etc.).
+ * 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.
  *
- * @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`.
  */
-export function useFetchWorkflows({ workspace, pageSize = 10, queryOptions }: FetchInfiniteWorkflowProps) {
+export function useFetchWorkflows<TData = Workflow[]>({
+    workspace,
+    search,
+    pageSize = 10,
+    select,
+    fetchAllPages = false,
+    queryOptions,
+}: FetchWorkflowsProps<TData>) {
     const { api } = useAxios();
 
-    const queryKey: QueryKey = ["workflows", workspace ?? null];
-
-    const mergedQueryOptions = useMemo<InfiniteOptions<Workflow[]>>(() => ({
-        ...defaultQueryOptions,
-        ...(queryOptions ?? {}),
-    }), [queryOptions]);
+    const queryKey = buildQueryKey(["workflows", workspace, search ?? null], [], {
+        pageSize,
+        fetchAllPages,
+    });
 
-    const query = useInfiniteQuery<WorkflowListResponse, Error, Workflow[], QueryKey, PageToken>({
+    const query = useEntityInfiniteQuery<WorkflowListResponse, "workflows", TData>({
         queryKey,
-        initialPageParam: null,
-        getNextPageParam: (lastPage) => lastPage.next_page_token ?? undefined,
-
-        queryFn: async ({ pageParam }) => {
-            return await listWorkflows(api, workspace, pageSize, pageParam ?? undefined);
-        },
-
-        select: (data) => data.pages.flatMap((p) => p.workflows),
-
-        ...mergedQueryOptions,
+        itemsKey: "workflows",
+        fetchPage: (pageToken, signal) =>
+            listWorkflows(
+                api,
+                { workspace, search, pageSize, pageToken: pageToken ?? undefined },
+                signal,
+            ),
+        select,
+        fetchAllPages,
+        configError: workspace ? undefined : missingWorkspaceError("useFetchWorkflows"),
+        queryOptions,
     });
 
-    return {
-        query,
-        queryKey,
-    };
+    return { query, queryKey };
 }

package/src/hooks/workflow/useRunWorkflow.ts

@@ -1,62 +1,108 @@
+import { useEffect, useRef } from "react";
 import { useMutation } from "@tanstack/react-query";
 
 import { useAxios } from "@/hooks/useAxios";
 import { useAppAlert } from "@/contexts/appAlertContext/useAppAlert";
+import { useWebSocket } from "@/contexts/webSocketContext/hooks/useWebSocket";
+import {
+    getWorkerExecution,
+    getWorkflowExecution,
+    runWorkflow,
+    terminalRunStatusOf,
+} from "@/api/workflow";
+import { anySignal, unlessAborted } from "@/lib/abort";
+import {
+    RUN_FAILED_MESSAGE,
+    WorkflowRunAbortedError,
+    runWorkflowToEnd,
+    type WorkflowWaitOptions,
+} from "@/lib/workflowRun";
 import type { AnyRecord } from "@/types/anyRecord";
-import type { PollWorkflowExecutionOptions } from "@/api/workflow";
-import { runWorkflow, runWorkflowAndGetResult } from "@/api/workflow";
+import type { WorkflowResult } from "@/types/workflow";
 
 type RunWorkflowProps = {
     id: string;
     workspace: string;
     parameters: AnyRecord;
-    pollOptions?: PollWorkflowExecutionOptions;
+    /** How the run is waited for; see `WorkflowWaitOptions`. */
+    waitOptions?: WorkflowWaitOptions;
 };
 
-const getErrorMessage = (err: unknown, fallback: string) =>
-    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`.
+ *
+ * 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`.
  *
- * - `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.
+ * 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.
  *
- * Both surface the standard mutation helpers (`mutate`, `mutateAsync`, `isPending`, `data`, ...)
- * and report failures through `useAppAlert`.
+ * @returns {UseMutationResult} The mutation; `mutate({ id, workspace, parameters, waitOptions })`
+ *   starts a run and waits for it.
  */
 export const useRunWorkflow = () => {
     const { api } = useAxios();
     const { showAlert } = useAppAlert();
+    const socket = useWebSocket();
+    const unmounted = useRef<AbortSignal | undefined>(undefined);
 
-    const runAsync = useMutation({
-        mutationFn: ({ id, workspace, parameters }: RunWorkflowProps) =>
-            runWorkflow(api, id, workspace, parameters),
-        onError: (err) => {
-            showAlert({
-                severity: "error",
-                message: getErrorMessage(err, "Unable to run the workflow. Please try again."),
-            });
-        },
-    });
+    useEffect(() => {
+        const controller = new AbortController();
+        unmounted.current = controller.signal;
+        return () => controller.abort();
+    }, []);
+
+    return useMutation({
+        mutationFn: async ({
+            id,
+            workspace,
+            parameters,
+            waitOptions,
+        }: RunWorkflowProps): Promise<WorkflowResult> => {
+            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,
+                });
 
-    const runAndGetResult = useMutation({
-        mutationFn: ({ id, workspace, parameters, pollOptions }: RunWorkflowProps) =>
-            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: unknown) => {
+                    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 || RUN_FAILED_MESSAGE });
         },
     });
-
-    return { runAsync, runAndGetResult };
 };

package/src/hooks/workflow/useTriggerWorkflow.ts

@@ -0,0 +1,36 @@
+import { useMutation } from "@tanstack/react-query";
+
+import { useAxios } from "@/hooks/useAxios";
+import { useAppAlert } from "@/contexts/appAlertContext/useAppAlert";
+import { runWorkflow } from "@/api/workflow";
+import { RUN_FAILED_MESSAGE } from "@/lib/workflowRun";
+import type { AnyRecord } from "@/types/anyRecord";
+
+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 const useTriggerWorkflow = () => {
+    const { api } = useAxios();
+    const { showAlert } = useAppAlert();
+
+    return useMutation({
+        mutationFn: ({ id, workspace, parameters }: TriggerWorkflowProps) =>
+            runWorkflow(api, id, workspace, parameters),
+        onError: (error) =>
+            showAlert({ severity: "error", message: error.message || RUN_FAILED_MESSAGE }),
+    });
+};

package/src/hooks/workspace/useFetchWorkspace.ts

@@ -1,78 +1,45 @@
-import { useEffect } from "react";
-
-import { useQuery } from "@tanstack/react-query";
-
 import { useAxios } from "@/hooks/useAxios";
-import { useAppAlert } from "@/contexts/appAlertContext/useAppAlert";
-import type { Workspace } from "@/types/workspace";
+import { useEntityQuery } from "@/hooks/useEntityQuery";
 import { getWorkspace } from "@/api/workspace";
-import type { EntityQueryOptions } from "@/types/entityQuery";
+import type { Workspace } from "@/types/workspace";
+import type { FetchEntityProps } from "@/types/entityQuery";
 
-export type FetchWorkspaceProps<TData = Workspace, TSelected = TData> = {
+export type FetchWorkspaceProps<TData = Workspace, TSelected = TData> = FetchEntityProps<
+    TData,
+    TSelected
+> & {
     name: string;
-    queryOptions?: EntityQueryOptions<TData, TSelected>;
-};
-
-const defaultQueryOptions: EntityQueryOptions<Workspace> = {
-    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
+ * Fetches one workspace by name; `data` is the workspace, or whatever `select` makes of it.
  *
- * Parameters (FetchWorkspaceProps):
- * @param {string} name
- *   Workspace name (required).
+ * 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.
  *
- * @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 const useFetchWorkspace = ({ name, queryOptions = defaultQueryOptions }: FetchWorkspaceProps) => {
-
+export const useFetchWorkspace = <TSelected = Workspace>({
+    name,
+    select,
+    queryOptions,
+}: FetchWorkspaceProps<Workspace, TSelected>) => {
     const { api } = useAxios();
-    const { showAlert } = useAppAlert();
 
     const queryKey = ["workspace", name];
 
-    const query = useQuery<Workspace>({
+    const query = useEntityQuery<Workspace, TSelected>({
         queryKey,
-        queryFn: async () => {
-            const workspace = await getWorkspace(api, name);
-            return workspace;
-        },
-        ...queryOptions ?? {}
+        fetchEntity: (signal) => getWorkspace(api, name, signal),
+        select,
+        enabled: Boolean(name),
+        queryOptions,
     });
 
-    useEffect(() => {
-        if (!query.error) return;
-
-        showAlert({
-            severity: "error",
-            message: query.error.message,
-        });
-    }, [query.error, showAlert]);
-
-    return {
-        ...query,
-        queryKey,
-    };
+    return { ...query, queryKey };
 };