@everysk/apps-sdk 0.1.0-beta.0

package/src/hooks/workflow/useFetchWorkflowExecution.ts

@@ -0,0 +1,79 @@
+import { useEffect } from "react";
+
+import { useQuery } from "@tanstack/react-query";
+
+import { useAxios } from "@/hooks/useAxios";
+import { useAppAlert } from "@/contexts/appAlertContext/useAppAlert";
+import { getWorkflowExecution } from "@/api/workflow";
+import type { WorkflowExecution } from "@/types/workflow";
+import type { EntityQueryOptions } from "@/types/entityQuery";
+
+export type FetchWorkflowExecutionProps<TData = WorkflowExecution, TSelected = TData> = {
+    workflowId: string;
+    workflowExecutionId: string;
+    workspace: string;
+    queryOptions?: EntityQueryOptions<TData, TSelected>;
+};
+
+const defaultQueryOptions: EntityQueryOptions<WorkflowExecution> = {
+    refetchOnMount: "always",
+    staleTime: 0,
+    gcTime: 0,
+};
+
+/**
+ * useFetchWorkflowExecution
+ *
+ * Data-fetching hook built on TanStack Query to retrieve a single workflow 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 execution belongs to (required).
+ * @param workflowExecutionId - Workflow 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 } = useFetchWorkflowExecution({
+ *   workflowId: "wf-123",
+ *   workflowExecutionId: "exec-456",
+ *   workspace: "main",
+ * });
+ * // data -> WorkflowExecution
+ * ```
+ */
+export const useFetchWorkflowExecution = ({ workflowId, workflowExecutionId, workspace, queryOptions = defaultQueryOptions }: FetchWorkflowExecutionProps) => {
+
+    const { api } = useAxios();
+    const { showAlert } = useAppAlert();
+
+    const queryKey = ["workflow_execution", workflowId, workflowExecutionId, workspace];
+
+    const query = useQuery<WorkflowExecution>({
+        queryKey,
+        queryFn: async () => {
+            const execution = await getWorkflowExecution(api, workflowId, workflowExecutionId, workspace);
+            return execution;
+        },
+        ...queryOptions ?? {}
+    });
+
+    useEffect(() => {
+        if (!query.error) return;
+
+        showAlert({
+            severity: "error",
+            message: query.error.message,
+        });
+    }, [query.error, showAlert]);
+
+    return {
+        ...query,
+        queryKey,
+    };
+};

package/src/hooks/workflow/useFetchWorkflowExecutions.ts

@@ -0,0 +1,95 @@
+import { useMemo } from "react";
+import { useInfiniteQuery, type UseInfiniteQueryOptions, type QueryKey } from "@tanstack/react-query";
+
+import { useAxios } from "@/hooks/useAxios";
+import { listWorkflowExecutions } from "@/api/workflow";
+import type { FetchEntitiesParams } from "@/types/entityQuery";
+import { buildQueryKey, buildQueryObject } 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">;
+
+export type FetchInfiniteWorkflowExecutionProps = FetchEntitiesParams<WorkflowExecution[], InfiniteOptions<WorkflowExecution[]>> & {
+    workflowId: string;
+    pageSize?: number;
+};
+
+const defaultQueryOptions: InfiniteOptions<WorkflowExecution[]> = {
+    refetchOnMount: "always",
+    staleTime: 0,
+    gcTime: 0,
+};
+
+/**
+ * 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`.
+ *
+ * @returns
+ *   - `query`: the full `useInfiniteQuery` result (data, isLoading, hasNextPage, fetchNextPage, etc.)
+ *   - `queryKey`: the cache key used by React Query
+ *
+ * @example
+ * ```ts
+ * const { query } = useFetchWorkflowExecutions({
+ *   workflowId: "wf-123",
+ *   filters: [{ field: "workspace", value: "main" }],
+ *   pageSize: 20,
+ * });
+ *
+ * // Flat list of all fetched executions
+ * const executions = query.data ?? [];
+ * ```
+ */
+export function useFetchWorkflowExecutions({ workflowId, filters = [], order = [], projection = "", pageSize = 10, queryOptions }: FetchInfiniteWorkflowExecutionProps) {
+    const { api } = useAxios();
+
+    const queryKey = buildQueryKey(["workflow_executions", workflowId], filters);
+
+    const mergedQueryOptions = useMemo<InfiniteOptions<WorkflowExecution[]>>(() => ({
+        ...defaultQueryOptions,
+        ...(queryOptions ?? {}),
+    }), [queryOptions]);
+
+    const query = useInfiniteQuery<WorkflowExecutionListResponse, Error, WorkflowExecution[], 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 listWorkflowExecutions(api, workflowId, queryFilter);
+        },
+
+        select: (data) => data.pages.flatMap((p) => p.workflow_executions),
+
+        ...mergedQueryOptions,
+    });
+
+    return {
+        query,
+        queryKey,
+    };
+}

package/src/hooks/workflow/useFetchWorkflows.ts

@@ -0,0 +1,84 @@
+import { useMemo } from "react";
+import { useInfiniteQuery, type UseInfiniteQueryOptions, type QueryKey } from "@tanstack/react-query";
+
+import { useAxios } from "@/hooks/useAxios";
+import { listWorkflows } from "@/api/workflow";
+import type { Workflow, WorkflowListResponse } from "@/types/workflow";
+
+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[]>;
+};
+
+const defaultQueryOptions: InfiniteOptions<Workflow[]> = {
+    refetchOnMount: "always",
+    staleTime: 0,
+    gcTime: 0,
+};
+
+/**
+ * useFetchWorkflows
+ *
+ * Data-fetching hook built on TanStack Query's `useInfiniteQuery` to retrieve
+ * workflows with cursor-based pagination using the legacy method (workspace as query param).
+ *
+ * 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.
+ *
+ * @param {InfiniteOptions<Workflow[]>} [queryOptions]
+ *   TanStack Query options passed through to `useInfiniteQuery`
+ *   (e.g., enabled, staleTime, gcTime, etc.).
+ *
+ * @returns {{ query, queryKey }}
+ *   - `query`: the full `useInfiniteQuery` result (data, isLoading, hasNextPage, fetchNextPage, etc.)
+ *   - `queryKey`: the cache key used by React Query
+ *
+ * @example
+ * ```ts
+ * const { query } = useFetchWorkflows({ workspace: "ws-1", pageSize: 20 });
+ *
+ * // Flat list of all fetched workflows
+ * const workflows = query.data ?? [];
+ * ```
+ */
+export function useFetchWorkflows({ workspace, pageSize = 10, queryOptions }: FetchInfiniteWorkflowProps) {
+    const { api } = useAxios();
+
+    const queryKey: QueryKey = ["workflows", workspace ?? null];
+
+    const mergedQueryOptions = useMemo<InfiniteOptions<Workflow[]>>(() => ({
+        ...defaultQueryOptions,
+        ...(queryOptions ?? {}),
+    }), [queryOptions]);
+
+    const query = useInfiniteQuery<WorkflowListResponse, Error, Workflow[], QueryKey, PageToken>({
+        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,
+    });
+
+    return {
+        query,
+        queryKey,
+    };
+}

package/src/hooks/workflow/useRunWorkflow.ts

@@ -0,0 +1,62 @@
+import { useMutation } from "@tanstack/react-query";
+
+import { useAxios } from "@/hooks/useAxios";
+import { useAppAlert } from "@/contexts/appAlertContext/useAppAlert";
+import type { AnyRecord } from "@/types/anyRecord";
+import type { PollWorkflowExecutionOptions } from "@/api/workflow";
+import { runWorkflow, runWorkflowAndGetResult } from "@/api/workflow";
+
+type RunWorkflowProps = {
+    id: string;
+    workspace: string;
+    parameters: AnyRecord;
+    pollOptions?: PollWorkflowExecutionOptions;
+};
+
+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.
+ *
+ * - `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.
+ *
+ * Both surface the standard mutation helpers (`mutate`, `mutateAsync`, `isPending`, `data`, ...)
+ * and report failures through `useAppAlert`.
+ */
+export const useRunWorkflow = () => {
+    const { api } = useAxios();
+    const { showAlert } = useAppAlert();
+
+    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."),
+            });
+        },
+    });
+
+    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."),
+            });
+        },
+    });
+
+    return { runAsync, runAndGetResult };
+};

package/src/hooks/workspace/useFetchWorkspace.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 type { Workspace } from "@/types/workspace";
+import { getWorkspace } from "@/api/workspace";
+import type { EntityQueryOptions } from "@/types/entityQuery";
+
+export type FetchWorkspaceProps<TData = Workspace, TSelected = TData> = {
+    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
+ *
+ * Parameters (FetchWorkspaceProps):
+ * @param {string} name
+ *   Workspace name (required).
+ *
+ * @param queryOptions
+ *   TanStack Query options passed through to `useQuery` (e.g., enabled, staleTime, gcTime, etc.).
+ *
+ * Returns:
+ * @returns {object}
+ *   TanStack Query's `query` object extended with:
+ *   - `queryKey`: the cache key used by React Query
+ *
+ * Example:
+ * ```ts
+ * const { data, isLoading } = useFetchWorkspace({ name: "main" });
+ * // data -> Workspace
+ * ```
+ */
+export const useFetchWorkspace = ({ name, queryOptions = defaultQueryOptions }: FetchWorkspaceProps) => {
+
+    const { api } = useAxios();
+    const { showAlert } = useAppAlert();
+
+    const queryKey = ["workspace", name];
+
+    const query = useQuery<Workspace>({
+        queryKey,
+        queryFn: async () => {
+            const workspace = await getWorkspace(api, name);
+            return workspace;
+        },
+        ...queryOptions ?? {}
+    });
+
+    useEffect(() => {
+        if (!query.error) return;
+
+        showAlert({
+            severity: "error",
+            message: query.error.message,
+        });
+    }, [query.error, showAlert]);
+
+    return {
+        ...query,
+        queryKey,
+    };
+};

package/src/hooks/workspace/useFetchWorkspaces.ts

@@ -0,0 +1,86 @@
+import { useMemo } from "react";
+import { useInfiniteQuery, type UseInfiniteQueryOptions, type QueryKey } from "@tanstack/react-query";
+
+import { useAxios } from "@/hooks/useAxios";
+import { listWorkspaces } from "@/api/workspace";
+import type { Workspace, WorkspaceListResponse } from "@/types/workspace";
+
+type PageToken = string | null;
+
+type InfiniteOptions<TData> = Omit<
+    UseInfiniteQueryOptions<WorkspaceListResponse, Error, TData, QueryKey, PageToken>,
+    "queryKey" | "queryFn" | "initialPageParam" | "getNextPageParam"
+>;
+
+export type FetchInfiniteWorkspaceProps = {
+    workspace?: string;
+    pageSize?: number;
+    queryOptions?: InfiniteOptions<Workspace[]>;
+};
+
+const defaultQueryOptions: InfiniteOptions<Workspace[]> = {
+    refetchOnMount: "always",
+    staleTime: 0,
+    gcTime: 0,
+};
+
+/**
+ * useFetchWorkspaces
+ *
+ * Data-fetching hook built on TanStack Query's `useInfiniteQuery` to retrieve
+ * workspaces with cursor-based pagination.
+ *
+ * It also:
+ * - flattens all pages into a single `Workspace[]` via `select`
+ *
+ * Important notes:
+ * - `query.data` returns a flat `Workspace[]` (all pages merged).
+ * - `workspace` is required by some API configurations to avoid being blocked.
+ *
+ * @param props - FetchInfiniteWorkspaceProps
+ *   - `workspace`: Current workspace name sent as a query param.
+ *   - `pageSize`: Number of workspaces to fetch per page.
+ *   - `queryOptions`: TanStack Query options passed through to `useInfiniteQuery`.
+ *
+ * Returns:
+ * @returns {object}
+ *   - `query`: the full `useInfiniteQuery` result (data, isLoading, hasNextPage, fetchNextPage, etc.)
+ *   - `queryKey`: the cache key used by React Query
+ *
+ * Example:
+ * ```ts
+ * const { query } = useFetchWorkspaces({ workspace: "main", pageSize: 20 });
+ *
+ * // Flat list of all fetched workspaces
+ * const workspaces = query.data ?? [];
+ * ```
+ */
+export function useFetchWorkspaces({ workspace, pageSize = 10, queryOptions }: FetchInfiniteWorkspaceProps) {
+    const { api } = useAxios();
+
+    const queryKey: QueryKey = ["workspaces", workspace ?? null];
+
+    const mergedQueryOptions = useMemo<InfiniteOptions<Workspace[]>>(() => ({
+        ...defaultQueryOptions,
+        ...(queryOptions ?? {}),
+    }), [queryOptions]);
+
+    const query = useInfiniteQuery<WorkspaceListResponse, Error, Workspace[], QueryKey, PageToken>({
+        queryKey,
+        initialPageParam: null,
+        getNextPageParam: (lastPage) => lastPage.next_page_token ?? undefined,
+
+        queryFn: async ({ pageParam }) => {
+            return await listWorkspaces(api, workspace, pageSize, pageParam ?? undefined);
+        },
+
+        select: (data) => data.pages.flatMap((p) => p.workspaces),
+
+        ...mergedQueryOptions,
+    });
+
+    return {
+        query,
+        queryKey,
+    };
+}

package/src/index.ts

@@ -0,0 +1,72 @@
+// `@everysk/apps-sdk` — the entry point.
+//
+// One entry for everything whose dependencies are required peers, which npm installs with the
+// SDK: the providers, the entity slices, the UI components and the theme. A bundler drops what
+// an app does not import — measured, importing one function through this barrel produces the
+// same bytes as importing it from a dedicated subpath, so splitting these apart bought nothing.
+//
+// What stays behind its own subpath is only what carries an OPTIONAL peer: `/ag-grid`,
+// `/socket` and the `/test` helpers. That is not a style choice. A bundler resolves a module
+// before it can tree-shake it, so re-exporting the AG Grid layer from here would fail to build
+// in an app that never installed ag-grid — even one importing nothing but createQueryClient.
+
+export { EveryskApp } from "./EveryskApp";
+export type { EveryskAppProps, ProviderComponent } from "./EveryskApp";
+
+// Contexts — app configuration
+export { AppConfigContext } from "./contexts/appConfigContext";
+export { AppConfigProvider } from "./contexts/appConfigContext/provider";
+export { useAppConfig } from "./contexts/appConfigContext/useAppConfig";
+export type {
+    AppConfigContextType,
+    AppConfigProviderProps,
+} from "./contexts/appConfigContext/types";
+
+// Contexts — alerts
+export { AppAlertContext } from "./contexts/appAlertContext";
+export { AppAlertProvider } from "./contexts/appAlertContext/provider";
+export { useAppAlert } from "./contexts/appAlertContext/useAppAlert";
+export type {
+    AppAlertContextType,
+    AppAlertState,
+    ShowAlertOptions,
+} from "./contexts/appAlertContext/types";
+
+// Hooks
+export { useAxios } from "./hooks/useAxios";
+
+// API helpers
+export { toFilterTuple, buildQueryObject, buildQueryKey } from "./api/entityQuery";
+
+// Query client
+export { createQueryClient, getQueryFn } from "./lib/queryClient";
+
+// Types
+export type { AnyRecord } from "./types/anyRecord";
+export type {
+    BaseQueryParams,
+    DeleteEntityDefaultResponse,
+    DeleteEntityResponse,
+    EntityDefaultResponse,
+    EntityListResponse,
+    EntityQueryOptions,
+    EntityQueryParams,
+    EntitySingleResponse,
+    FetchEntitiesParams,
+    FetchEntityParams,
+    FilterClause,
+    FilterExpression,
+    FilterOperator,
+    QueryObject,
+} from "./types/entityQuery";
+
+// Entity slices, UI and theme. `export *` because each is exactly "everything these modules
+// expose"; the names are collision-free across all of them, checked before merging.
+export * from "./portfolio";
+export * from "./datastore";
+export * from "./file";
+export * from "./profile";
+export * from "./workflow";
+export * from "./workspace";
+export * from "./ui";
+export * from "./theme";