@everysk/apps-sdk 0.1.0-beta.0

package/src/hooks/portfolio/usePortfolioMutations.ts

@@ -0,0 +1,250 @@
+import { useMutation, useQueryClient } from "@tanstack/react-query";
+
+import { useAxios } from "@/hooks/useAxios";
+import { useAppAlert } from "@/contexts/appAlertContext/useAppAlert";
+import type { Portfolio } from "@/types/portfolio";
+import { deletePortfolio, createPortfolio, updatePortfolio } from "@/api/portfolio";
+
+type CreatePortfolioProps = {
+    data: Partial<Portfolio>;
+};
+
+type UpdatePortfolioProps = {
+    id: string;
+    data: Partial<Portfolio>;
+};
+
+type DeletePortfolioProps = {
+    id: string;
+    workspace: string;
+};
+
+type UsePortfolioMutationsProps = {
+    queryKey?: unknown[];
+};
+
+const getErrorMessage = (err: unknown, fallback: string) =>
+    err instanceof Error && err.message ? err.message : fallback;
+
+/**
+ * usePortfolioMutations
+ *
+ * Mutation hook built on TanStack Query to perform Portfolio write operations:
+ * - create a portfolio (POST)
+ * - update a portfolio (PUT)
+ * - delete a portfolio (DELETE)
+ *
+ * It also:
+ * - optionally invalidates a target query cache key after successful mutations
+ * - displays success/error alerts via `useAppAlert`
+ *
+ * Important notes:
+ * - This hook is intended for side-effect operations only. Reading/retrieving data should be done via `useQuery` or `useFetchPortfolio`.
+ * - Cache invalidation is controlled by `queryKey`. If `queryKey` is not provided, the hook will still run
+ *   mutations and show alerts, but it will NOT invalidate any cached queries.
+ * - `remove` requires a `workspace` parameter because the underlying API helper `deletePortfolio(api, id, workspace)`
+ *   expects it as a query param.
+ *
+ * Parameters (UsePortfolioMutationsProps):
+ * @param {unknown[]} [queryKey]
+ *  Query key to invalidate after successful mutations. Use the same `queryKey` you pass to the relevant `useQuery`
+ *  (e.g., portfolio list/detail) so UI data is refreshed automatically after a write.
+ *
+ *  Tip:
+ *  - If you're using `useFetchPortfolio`, you can pass its returned `queryKey` directly:
+ *    `const fetch = useFetchPortfolio(...);`
+ *    `usePortfolioMutations({ queryKey: fetch.queryKey });`
+ *
+ * Mutations:
+ * - `create`:
+ *   - mutationFn: `createPortfolio(api, data)`
+ *   - variables: `{ data: Partial<Portfolio> }`
+ *   - success message: "Portfolio created successfully."
+ *   - error message: "We couldn't create the portfolio. Please review your inputs and try again." (fallback)
+ *
+ * - `update`:
+ *   - mutationFn: `updatePortfolio(api, id, data)`
+ *   - variables: `{ id: string; data: Partial<Portfolio> }`
+ *   - success message: "Portfolio updated successfully."
+ *   - error message: "We couldn't update the portfolio. Please try again." (fallback)
+ *
+ * - `remove`:
+ *   - mutationFn: `deletePortfolio(api, id, workspace)`
+ *   - variables: `{ id: string; workspace: string }`
+ *   - success message: "Portfolio deleted successfully."
+ *   - error message: "We couldn't delete the portfolio. Please try again." (fallback)
+ *
+ * Return value:
+ * @returns {object}
+ *  Returns an object with the three TanStack Query mutation results:
+ *  - `create`: UseMutationResult<Portfolio, Error, CreatePortfolioProps, unknown>
+ *  - `update`: UseMutationResult<Portfolio, Error, UpdatePortfolioProps, unknown>
+ *  - `remove`: UseMutationResult<Portfolio, Error, DeletePortfolioProps, unknown>
+ *
+ * Each mutation includes standard TanStack Query helpers:
+ * - `mutate(variables, options?)`
+ * - `mutateAsync(variables, options?)`
+ * - `isPending`, `isSuccess`, `isError`, `error`, `data`, etc.
+ *
+ * Examples:
+ *
+ * 1) Invalidate a portfolio list query after mutations:
+ * ```ts
+ * const { create, update, remove } = usePortfolioMutations({ queryKey: ["portfolio"] });
+ *
+  * // Create (minimal example - other Security fields omitted for brevity)
+ * create.mutate({
+ *   data: {
+ *     name: "My Portfolio",
+ *     description: "Test portfolio",
+ *     base_currency: "USD",
+ *     date: "2026-01-08",
+ *     workspace: "ws-1",
+ *     securities: [
+ *       {
+ *         id: "sec-1",
+ *         ticker: "AAPL",
+ *         symbol: "AAPL",
+ *         name: "Apple Inc.",
+ *         currency: "USD",
+ *         quantity: 10,
+ *         market_price: 200,
+ *         market_value: 2000,
+ *         market_value_in_base: 2000,
+ *         fx_rate: 1,
+ *         instrument_type: "Equity",
+ *         instrument_class: "Equity",
+ *         asset_class: "Equity",
+ *         exchange: "NASDAQ",
+ *         status: "active",
+ *         // Other fields are nullable in the Security type and can be omitted here for documentation purposes.
+ *       } as Security,
+ *     ],
+ *   }
+ * });
+ *
+ * // Update (partial)
+ * update.mutate({
+ *   id: "pf-123",
+ *   data: {
+ *     name: "Renamed Portfolio",
+ *     tags: ["tag-1", "tag-2"],
+ *     check_securities: true,
+ *   }
+ * });
+ *
+ * // Delete
+ * remove.mutate({ id: "pf-123", workspace: "ws-1" });
+ * ```
+ *
+ * 2) Using async/await with `mutateAsync`:
+ * ```ts
+ * const { create } = usePortfolioMutations({ queryKey: ["portfolio"] });
+ *
+ * await create.mutateAsync({
+ *   data: {
+ *     name: "My Portfolio",
+ *     base_currency: "USD",
+ *     date: "2026-01-08",
+ *     workspace: "ws-1",
+ *     securities: [],
+ *   }
+ * });
+ * ```
+ *
+ * 3) Without cache invalidation (no queryKey):
+ * ```ts
+ * const { update } = usePortfolioMutations({});
+ *
+ * update.mutate({
+ *   id: "pf-123",
+ *   data: { description: "Updated description" }
+ * });
+ * // Mutation still runs and alerts are shown, but cached queries are not invalidated.
+ * ```
+ *
+ * 4) Using `useFetchPortfolio` queryKey for automatic invalidation:
+ * ```ts
+ * const fetch = useFetchPortfolio({
+ *   id: null,
+ *   filters: [{ field: "workspace", value: "ws-1" }],
+ * });
+ *
+ * const { remove } = usePortfolioMutations({ queryKey: fetch.queryKey });
+ *
+ * await remove.mutateAsync({ id: "pf-123", workspace: "ws-1" });
+ * ```
+ */
+
+export const usePortfolioMutations = ({ queryKey }: UsePortfolioMutationsProps) => {
+    const { api } = useAxios();
+    const { showAlert } = useAppAlert();
+    const queryClient = useQueryClient();
+
+    const invalidate = async () => {
+        if (!queryKey?.length) return;
+        await queryClient.invalidateQueries({ queryKey });
+    };
+
+    const create = useMutation({
+        mutationFn: async ({ data }: CreatePortfolioProps) => createPortfolio(api, data),
+        onSuccess: async () => {
+            await invalidate();
+            showAlert({
+                severity: "success",
+                message: "Portfolio created successfully.",
+            });
+        },
+        onError: (err: unknown) => {
+            showAlert({
+                severity: "error",
+                message: getErrorMessage(
+                    err,
+                    "We couldn't create the portfolio. Please review your inputs and try again."
+                ),
+            });
+        },
+    });
+
+    const update = useMutation({
+        mutationFn: async ({ id, data }: UpdatePortfolioProps) => updatePortfolio(api, id, data),
+        onSuccess: async () => {
+            await invalidate();
+            showAlert({
+                severity: "success",
+                message: "Portfolio updated successfully.",
+            });
+        },
+        onError: (err: unknown) => {
+            showAlert({
+                severity: "error",
+                message: getErrorMessage(
+                    err,
+                    "We couldn't update the portfolio. Please try again."
+                ),
+            });
+        },
+    });
+
+    const remove = useMutation({
+        mutationFn: async ({ id, workspace }: DeletePortfolioProps) => deletePortfolio(api, id, workspace),
+        onSuccess: async () => {
+            await invalidate();
+            showAlert({
+                severity: "success",
+                message: "Portfolio deleted successfully.",
+            });
+        },
+        onError: (err: unknown) => {
+            showAlert({
+                severity: "error",
+                message: getErrorMessage(
+                    err,
+                    "We couldn't delete the portfolio. Please try again."
+                ),
+            });
+        },
+    });
+
+    return { create, update, remove };
+};

package/src/hooks/profile/useFetchProfile.ts

@@ -0,0 +1,93 @@
+import { useEffect } from "react";
+
+import { useQuery } from "@tanstack/react-query";
+
+import { useAxios } from "@/hooks/useAxios";
+import { useAppAlert } from "@/contexts/appAlertContext/useAppAlert";
+import type { Profile } from "@/types/profile";
+import { getProfile } from "@/api/profile";
+import type { EntityQueryOptions } from "@/types/entityQuery";
+
+export type FetchProfileProps<TData = Profile, TSelected = TData> = {
+    queryOptions?: EntityQueryOptions<TData, TSelected>;
+    /**
+     * Served instead of calling the API. Pass `DEV_PROFILE` while running the dev server,
+     * where `/api/profile` has no session to resolve.
+     */
+    fallback?: Profile;
+};
+
+// The logged user's profile does not change during a session, so it is fetched once and kept —
+// unlike the entity hooks (staleTime/gcTime 0, refetch on every mount), which read data the
+// platform keeps changing.
+const defaultQueryOptions: EntityQueryOptions<Profile> = {
+    staleTime: Infinity,
+    refetchOnMount: false,
+    refetchOnWindowFocus: false,
+};
+
+/**
+ * useFetchProfile
+ *
+ * Data-fetching hook built on TanStack Query to retrieve the profile of the logged user. It takes
+ * no identifier: the API resolves the user from the session.
+ *
+ * It also:
+ * - builds a stable React Query `queryKey`, shared by every consumer, so the profile is fetched
+ *   once per session and read from cache afterwards
+ * - triggers an error alert via `useAppAlert` whenever `query.error` is present
+ *
+ * Parameters (FetchProfileProps):
+ * @param queryOptions
+ *   TanStack Query options passed through to `useQuery` (e.g., enabled, staleTime, gcTime, etc.).
+ *   Defaults keep the profile cached for the whole session.
+ * @param fallback
+ *   Served instead of calling the API. `/api/profile` only resolves in production, so an app
+ *   running the dev server passes `DEV_PROFILE` here:
+ *   `useFetchProfile({ fallback: import.meta.env.DEV ? DEV_PROFILE : undefined })`.
+ *   The SDK cannot make that choice itself — see `getProfile`.
+ *
+ * Returns:
+ * @returns {object}
+ *   TanStack Query's `query` object extended with:
+ *   - `queryKey`: the cache key used by React Query
+ *
+ * Example:
+ * ```ts
+ * const { data, isPending } = useFetchProfile();
+ * // data -> Profile
+ * ```
+ */
+export const useFetchProfile = ({
+    queryOptions = defaultQueryOptions,
+    fallback,
+}: FetchProfileProps = {}) => {
+
+    const { api } = useAxios();
+    const { showAlert } = useAppAlert();
+
+    const queryKey = ["profile"];
+
+    const query = useQuery<Profile>({
+        queryKey,
+        queryFn: async () => {
+            const profile = await getProfile(api, fallback);
+            return profile;
+        },
+        ...queryOptions ?? {}
+    });
+
+    useEffect(() => {
+        if (!query.error) return;
+
+        showAlert({
+            severity: "error",
+            message: query.error.message,
+        });
+    }, [query.error, showAlert]);
+
+    return {
+        ...query,
+        queryKey,
+    };
+};

package/src/hooks/useAxios.ts

@@ -0,0 +1,98 @@
+import { useEffect, useMemo, useRef } from "react";
+
+import axios, { type AxiosInstance, type InternalAxiosRequestConfig } from "axios";
+
+import type { AnyRecord } from "@/types/anyRecord";
+import type { FilterExpression } from "@/types/entityQuery";
+import { useAppConfig } from "@/contexts/appConfigContext/useAppConfig";
+
+/**
+ * useAxios
+ *
+ * Axios client hook that returns a memoized `AxiosInstance` configured with:
+ * - `baseURL` derived from:
+ *   - the optional `url` parameter, or
+ *   - the relative `/api` by default. In dev, `/api` is proxied to `EVERYSK_API_URL`
+ *     (see `vite/serverProxy.ts`); in production it is served behind the same host.
+ *
+ * Request behavior:
+ * - Sets the `X-Everysk-Source` header on every request, identifying the app to the API as
+ *   `everysk-user-app-<appId>` (the `appId` from `useAppConfig()`). When there is no app id (dev,
+ *   where the host page hasn't injected `window.APP_ID`), it falls back to
+ *   `everysk-user-app-development`.
+ * - Registers a request interceptor that, for `GET` and `DELETE` requests, attempts to parse
+ *   `config.params.query` (expected to be a JSON string) and extract a `workspace` filter from it.
+ * - If a `workspace` value is found, it is injected into `config.params.workspace`.
+ *
+ * Lifecycle / cleanup:
+ * - The interceptor is attached in `useEffect` and ejected on cleanup to avoid stacking interceptors
+ *   across re-renders or unmount/mount cycles.
+ *
+ * Notes:
+ * - `params.query` parsing is best-effort. Invalid JSON is ignored.
+ * - This hook assumes a query structure containing `filters`, where the workspace filter is identified by
+ *   `filter[0] === "workspace"`.
+ *
+ * Parameters:
+ * @param {string | null} [url=null]
+ *  Optional base URL override. If omitted/null, defaults to the relative `/api`.
+ *
+ * Return value:
+ * @returns {{ api: AxiosInstance }}
+ *  Returns an object containing the configured Axios instance.
+ */
+
+export const useAxios = (url: string | null = null) => {
+
+    const reqInterceptorId = useRef<number | null>(null);
+    const { appId } = useAppConfig();
+
+    const source = appId ? `everysk-user-app-${appId}` : "everysk-user-app-development";
+
+    const api: AxiosInstance = useMemo(() => {
+        const instance = axios.create({ baseURL: url ?? "/api" });
+        instance.defaults.headers.common["X-Everysk-Source"] = source;
+        return instance;
+    }, [url, source]);
+
+    useEffect(() => {
+        reqInterceptorId.current = api.interceptors.request.use(
+            (config: InternalAxiosRequestConfig<AnyRecord>) => {
+                const method = (config.method ?? "").toLowerCase();
+
+                if (method === "get" || method === "delete") {
+                    const params = (config.params ?? {}) as Record<string, unknown>;
+
+                    try {
+                        const rawQuery = params.query;
+                        const queryObj = typeof rawQuery === "string" ? JSON.parse(rawQuery) : null;
+
+                        const workspaceFilter = queryObj?.filters?.find(
+                            (filter: FilterExpression) => filter?.[0] === "workspace"
+                        );
+
+                        const workspace =
+                            Array.isArray(workspaceFilter) ? workspaceFilter[workspaceFilter.length - 1] : null;
+
+                        if (workspace) {
+                            config.params = { ...params, workspace };
+                        }
+                    } catch {
+                        // ignore invalid query JSON
+                    }
+                }
+
+                return config;
+            }
+        );
+
+        return () => {
+            if (reqInterceptorId.current != null) {
+                api.interceptors.request.eject(reqInterceptorId.current);
+            }
+            reqInterceptorId.current = null;
+        };
+    }, [api]);
+
+    return { api };
+};

package/src/hooks/workflow/useFetchWorkerExecution.ts

@@ -0,0 +1,78 @@
+import { useEffect } from "react";
+
+import { useQuery } from "@tanstack/react-query";
+
+import { useAxios } from "@/hooks/useAxios";
+import { useAppAlert } from "@/contexts/appAlertContext/useAppAlert";
+import { getWorkerExecution } from "@/api/workflow";
+import type { WorkerExecution } from "@/types/workflow";
+import type { EntityQueryOptions } from "@/types/entityQuery";
+
+export type FetchWorkerExecutionProps<TData = WorkerExecution, TSelected = TData> = {
+    workflowId: string;
+    workerExecutionId: string;
+    workspace: string;
+    queryOptions?: EntityQueryOptions<TData, TSelected>;
+};
+
+const defaultQueryOptions: EntityQueryOptions<WorkerExecution> = {
+    refetchOnMount: "always",
+    staleTime: 0,
+    gcTime: 0,
+};
+
+/**
+ * useFetchWorkerExecution
+ *
+ * Data-fetching hook built on TanStack Query to retrieve a single worker execution.
+ *
+ * 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
+ *
+ * @param workflowId - Workflow identifier the worker execution belongs to (required).
+ * @param workerExecutionId - Worker execution identifier (required).
+ * @param workspace - Workspace the workflow belongs to (required).
+ * @param queryOptions - TanStack Query options passed through to `useQuery` (e.g., enabled, staleTime, gcTime, etc.).
+ *
+ * @returns TanStack Query result extended with `queryKey`.
+ *
+ * Example:
+ * ```ts
+ * const { data, isLoading } = useFetchWorkerExecution({
+ *   workflowId: "wf-123",
+ *   workerExecutionId: "wkex-456",
+ *   workspace: "main",
+ * });
+ * // data -> WorkerExecution
+ * ```
+ */
+export const useFetchWorkerExecution = ({ workflowId, workerExecutionId, workspace, queryOptions = defaultQueryOptions }: FetchWorkerExecutionProps) => {
+
+    const { api } = useAxios();
+    const { showAlert } = useAppAlert();
+
+    const queryKey = ["worker_execution", workflowId, workerExecutionId, workspace];
+
+    const query = useQuery<WorkerExecution>({
+        queryKey,
+        queryFn: async () => {
+            return await getWorkerExecution(api, workflowId, workerExecutionId, workspace);
+        },
+        ...queryOptions ?? {}
+    });
+
+    useEffect(() => {
+        if (!query.error) return;
+
+        showAlert({
+            severity: "error",
+            message: query.error.message,
+        });
+    }, [query.error, showAlert]);
+
+    return {
+        ...query,
+        queryKey,
+    };
+};

package/src/hooks/workflow/useFetchWorkerExecutions.ts

@@ -0,0 +1,98 @@
+import { useMemo } from "react";
+import { useInfiniteQuery, type UseInfiniteQueryOptions, type QueryKey } from "@tanstack/react-query";
+
+import { useAxios } from "@/hooks/useAxios";
+import { listWorkerExecutions } from "@/api/workflow";
+import type { FetchEntitiesParams } from "@/types/entityQuery";
+import { buildQueryKey, buildQueryObject } from "@/api/entityQuery";
+import type { WorkerExecution, WorkerExecutionListResponse } from "@/types/workflow";
+
+type PageToken = string | null;
+
+type InfiniteOptions<TData> = Omit<UseInfiniteQueryOptions<WorkerExecutionListResponse, Error, TData, QueryKey, PageToken>, "queryKey" | "queryFn" | "initialPageParam" | "getNextPageParam">;
+
+export type FetchInfiniteWorkerExecutionProps = FetchEntitiesParams<WorkerExecution[], InfiniteOptions<WorkerExecution[]>> & {
+    workflowId: string;
+    workflowExecutionId: string;
+    pageSize?: number;
+};
+
+const defaultQueryOptions: InfiniteOptions<WorkerExecution[]> = {
+    refetchOnMount: "always",
+    staleTime: 0,
+    gcTime: 0,
+};
+
+/**
+ * useFetchWorkerExecutions
+ *
+ * Data-fetching hook built on TanStack Query's `useInfiniteQuery` to retrieve
+ * worker executions for a given workflow with cursor-based pagination.
+ *
+ * Automatically flattens all pages into a single `WorkerExecution[]` via `select`.
+ *
+ * Note: `query.data` returns a flat `WorkerExecution[]` with all fetched items merged across pages.
+ *
+ * @param workflowId - Workflow identifier whose worker executions to fetch (required).
+ * @param workflowExecutionId - Workflow execution identifier to filter worker executions (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`.
+ *
+ * @returns
+ *   - `query`: the full `useInfiniteQuery` result (data, isLoading, hasNextPage, fetchNextPage, etc.)
+ *   - `queryKey`: the cache key used by React Query
+ *
+ * @example
+ * ```ts
+ * const { query } = useFetchWorkerExecutions({
+ *   workflowId: "wf-123",
+ *   workflowExecutionId: "wfex-456",
+ *   filters: [{ field: "workspace", value: "main" }],
+ *   pageSize: 20,
+ * });
+ *
+ * // Flat list of all fetched worker executions
+ * const workerExecutions = query.data ?? [];
+ * ```
+ */
+export function useFetchWorkerExecutions({ workflowId, workflowExecutionId, filters = [], order = [], projection = "", pageSize = 10, queryOptions }: FetchInfiniteWorkerExecutionProps) {
+    const { api } = useAxios();
+
+    const queryKey = buildQueryKey(["worker_executions", workflowId, workflowExecutionId], filters);
+
+    const mergedQueryOptions = useMemo<InfiniteOptions<WorkerExecution[]>>(() => ({
+        ...defaultQueryOptions,
+        ...(queryOptions ?? {}),
+    }), [queryOptions]);
+
+    const query = useInfiniteQuery<WorkerExecutionListResponse, Error, WorkerExecution[], QueryKey, PageToken>({
+        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 listWorkerExecutions(api, workflowId, workflowExecutionId, queryFilter);
+        },
+
+        select: (data) => data.pages.flatMap((p) => p.worker_executions),
+
+        ...mergedQueryOptions,
+    });
+
+    return {
+        query,
+        queryKey,
+    };
+}

package/src/hooks/workflow/useFetchWorkflow.ts

@@ -0,0 +1,76 @@
+import { useEffect } from "react";
+
+import { useQuery } from "@tanstack/react-query";
+
+import { useAxios } from "@/hooks/useAxios";
+import { useAppAlert } from "@/contexts/appAlertContext/useAppAlert";
+import { getWorkflow } from "@/api/workflow";
+import type { Workflow } from "@/types/workflow";
+import type { EntityQueryOptions, FetchEntityParams } from "@/types/entityQuery";
+
+export type FetchWorkflowProps<TData = Workflow, TSelected = TData> = FetchEntityParams<TData, TSelected>;
+
+const defaultQueryOptions: EntityQueryOptions<Workflow> = {
+    refetchOnMount: "always",
+    staleTime: 0,
+    gcTime: 0
+}
+
+/**
+ * useFetchWorkflow
+ *
+ * Data-fetching hook built on TanStack Query to retrieve a single workflow by ID.
+ *
+ * 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
+ *
+ * @param id - Workflow identifier (required).
+ * @param workspace - Workspace the workflow belongs to (required).
+ * @param queryOptions - TanStack Query options passed through to `useQuery` (e.g., enabled, staleTime, gcTime, etc.).
+ *
+ * @returns TanStack Query result extended with `queryKey`.
+ *
+ * Tip:
+ * - The returned `queryKey` can be reused by mutation hooks for cache invalidation:
+ *   ```ts
+ *   const fetch = useFetchWorkflow({ id: "wf-123", workspace: "main" });
+ *   useWorkflowMutations({ queryKey: fetch.queryKey });
+ *   ```
+ *
+ * Example:
+ * ```ts
+ * const { data, isLoading } = useFetchWorkflow({ id: "wf-123", workspace: "main" });
+ * // data -> Workflow
+ * ```
+ */
+export const useFetchWorkflow = ({ id, workspace, queryOptions = defaultQueryOptions }: FetchWorkflowProps) => {
+
+    const { api } = useAxios();
+    const { showAlert } = useAppAlert();
+
+    const queryKey = ["workflow", id, workspace];
+
+    const query = useQuery<Workflow>({
+        queryKey,
+        queryFn: async () => {
+            const workflow = await getWorkflow(api, id, workspace);
+            return workflow;
+        },
+        ...queryOptions ?? {}
+    });
+
+    useEffect(() => {
+        if (!query.error) return;
+
+        showAlert({
+            severity: "error",
+            message: query.error.message,
+        });
+    }, [query.error, showAlert]);
+
+    return {
+        ...query,
+        queryKey,
+    };
+};