@everysk/apps-sdk 0.1.0-beta.0

package/src/hooks/file/useFetchFile.ts

@@ -0,0 +1,93 @@
+import { useEffect } from "react";
+
+import { useQuery } from "@tanstack/react-query";
+
+import { useAxios } from "@/hooks/useAxios";
+import type { EveryskFile } from "@/types/file";
+import { useAppAlert } from "@/contexts/appAlertContext/useAppAlert";
+import { getFile } from "@/api/file";
+import type { EntityQueryOptions, FetchEntityParams } from "@/types/entityQuery";
+
+export type FetchFileProps<TData = EveryskFile, TSelected = TData> = FetchEntityParams<TData, TSelected>;
+
+const defaultQueryOptions: EntityQueryOptions<EveryskFile> = {
+    refetchOnMount: "always",
+    staleTime: 0,
+    gcTime: 0
+}
+
+/**
+ * useFetchFile
+ *
+ * Data-fetching hook built on TanStack Query to retrieve a single file 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
+ *
+ * Important notes:
+ * - Always returns a single `EveryskFile` object.
+ * - `EveryskFile.data` represents the file content and is expected to be a Base64-encoded string
+ *   when provided by the API (or when sending content through mutations).
+ *
+ * Parameters (FetchFileProps):
+ * @param {string} id
+ *   EveryskFile identifier (required).
+ *
+ * @param {string} workspace
+ *   Workspace the file belongs to (required by `getFile`).
+ *
+ * @param {EntityQueryOptions<any>} [queryOptions=defaultQueryOptions]
+ *   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
+ *
+ * Tip:
+ * - The returned `queryKey` can be reused by mutation hooks for cache invalidation:
+ *   ```ts
+ *   const fetch = useFetchFile({ id: "file-123", workspace: "ws-1" });
+ *   useFileMutations({ queryKey: fetch.queryKey });
+ *   ```
+ *
+ * Example:
+ * ```ts
+ * const { data, isLoading } = useFetchFile({
+ *   id: "file-123",
+ *   workspace: "ws-1",
+ * });
+ * // data -> EveryskFile
+ * ```
+ */
+export const useFetchFile = ({ id, workspace, queryOptions = defaultQueryOptions }: FetchFileProps) => {
+
+    const { api } = useAxios();
+    const { showAlert } = useAppAlert();
+
+    const queryKey = ["file", id, workspace];
+
+    const query = useQuery<EveryskFile>({
+        queryKey,
+        queryFn: async () => {
+            const file = await getFile(api, id, workspace);
+            return file;
+        },
+        ...queryOptions ?? {}
+    });
+
+    useEffect(() => {
+        if (!query.error) return;
+
+        showAlert({
+            severity: "error",
+            message: query.error.message,
+        });
+    }, [query.error, showAlert]);
+
+    return {
+        ...query,
+        queryKey,
+    };
+};

package/src/hooks/file/useFetchFiles.ts

@@ -0,0 +1,109 @@
+import { useMemo } from "react";
+import { useInfiniteQuery, type UseInfiniteQueryOptions, type QueryKey } from "@tanstack/react-query";
+
+import { useAxios } from "@/hooks/useAxios";
+import { listFiles } from "@/api/file";
+import type { EveryskFile, FileListResponse } from "@/types/file";
+import type { FetchEntitiesParams } from "@/types/entityQuery";
+import { buildQueryKey, buildQueryObject } from "@/api/entityQuery";
+
+type PageToken = string | null;
+
+type InfiniteOptions<TData> = Omit<
+    UseInfiniteQueryOptions<FileListResponse, Error, TData, QueryKey, PageToken>,
+    "queryKey" | "queryFn" | "initialPageParam" | "getNextPageParam"
+>;
+
+export type FetchInfiniteFileProps = FetchEntitiesParams<EveryskFile[], InfiniteOptions<EveryskFile[]>> & {
+    pageSize?: number;
+};
+
+const defaultQueryOptions: InfiniteOptions<EveryskFile[]> = {
+    refetchOnMount: "always",
+    staleTime: 0,
+    gcTime: 0,
+};
+
+/**
+ * useFetchFiles
+ *
+ * Data-fetching hook built on TanStack Query's `useInfiniteQuery` to retrieve
+ * files with cursor-based pagination.
+ *
+ * It also:
+ * - flattens all pages into a single `EveryskFile[]` via `select`
+ *
+ * Important notes:
+ * - `query.data` returns a flat `EveryskFile[]` (all pages merged).
+ *
+ * Parameters (FetchInfiniteFileProps):
+ * @param {FilterClause[]} [filters=[]]
+ *   Filters applied to every page request. Must include a `workspace` filter.
+ *
+ * @param {string[]} [order=[]]
+ *   Sorting applied to every page request.
+ *
+ * @param {string} [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 {number} [pageSize=10]
+ *   Number of files to fetch per page.
+ *
+ * @param {InfiniteOptions<EveryskFile[]>} [queryOptions]
+ *   TanStack Query options passed through to `useInfiniteQuery`
+ *   (e.g., enabled, staleTime, gcTime, etc.).
+ *
+ * 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 } = useFetchFiles({
+ *   filters: [{ field: "workspace", value: "ws-1" }],
+ *   pageSize: 20,
+ * });
+ *
+ * // Flat list of all fetched files
+ * const files = query.data ?? [];
+ * ```
+ */
+export function useFetchFiles({ filters = [], order = [], projection = "", pageSize = 10, queryOptions }: FetchInfiniteFileProps) {
+    const { api } = useAxios();
+
+    const queryKey = buildQueryKey(["files"], filters);
+
+    const mergedQueryOptions = useMemo<InfiniteOptions<EveryskFile[]>>(() => ({
+        ...defaultQueryOptions,
+        ...(queryOptions ?? {}),
+    }), [queryOptions]);
+
+    const query = useInfiniteQuery<FileListResponse, Error, EveryskFile[], 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 listFiles(api, queryFilter);
+        },
+
+        select: (data) => data.pages.flatMap((p) => p.files),
+
+        ...mergedQueryOptions,
+    });
+
+    return {
+        query,
+        queryKey,
+    };
+}

package/src/hooks/file/useFileMutations.ts

@@ -0,0 +1,240 @@
+import { useMutation, useQueryClient } from "@tanstack/react-query";
+
+import { useAxios } from "@/hooks/useAxios";
+import { useAppAlert } from "@/contexts/appAlertContext/useAppAlert";
+import type { EveryskFile } from "@/types/file";
+import { deleteFile, createFile, updateFile } from "@/api/file";
+
+type CreateFileProps = {
+    data: Partial<EveryskFile>;
+};
+
+type UpdateFileProps = {
+    id: string;
+    data: Partial<EveryskFile>;
+};
+
+type DeleteFileProps = {
+    id: string;
+    workspace: string;
+};
+
+type UseFileMutationsProps = {
+    queryKey?: unknown[];
+};
+
+const getErrorMessage = (err: unknown, fallback: string) =>
+    err instanceof Error && err.message ? err.message : fallback;
+
+/**
+ * useFileMutations
+ *
+ * Mutation hook built on TanStack Query to perform EveryskFile write operations:
+ * - create a file (POST)
+ * - update a file (PUT)
+ * - delete a file (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 `useFetchFile`.
+ * - 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 `deleteFile(api, id, workspace)`
+ *   expects it as a query param.
+ * 
+ * - EveryskFile content (`data`):
+ *   - When creating/updating a file, the file content must be provided in `data` as a Base64-encoded string.
+ *   - Send only the raw Base64 content (do not include a data URL prefix like `data:<mime>;base64,`)
+ *   - `content_type` should match the file MIME type (e.g., "text/csv", "application/pdf").
+ *
+ * Parameters (UseFileMutationsProps):
+ * @param {unknown[]} [queryKey]
+ *  Query key to invalidate after successful mutations. Use the same `queryKey` you pass to the relevant `useQuery`
+ *  (e.g., file list/detail) so UI data is refreshed automatically after a write.
+ *
+ *  Tip:
+ *  - If you're using `useFetchFile`, you can pass its returned `queryKey` directly:
+ *    `const fetch = useFetchFile(...);`
+ *    `useFileMutations({ queryKey: fetch.queryKey });`
+ *
+ * Mutations:
+ * - `create`:
+ *   - mutationFn: `createFile(api, data)`
+ *   - variables: `{ data: Partial<EveryskFile> }`
+ *   - success message: "EveryskFile created successfully."
+ *   - error message: "Unable to create the file. Please try again." (fallback)
+ *
+ * - `update`:
+ *   - mutationFn: `updateFile(api, id, data)`
+ *   - variables: `{ id: string; data: Partial<EveryskFile> }`
+ *   - success message: "EveryskFile updated successfully."
+ *   - error message: "Unable to update the file. Please try again." (fallback)
+ *
+ * - `remove`:
+ *   - mutationFn: `deleteFile(api, id, workspace)`
+ *   - variables: `{ id: string; workspace: string }`
+ *   - success message: "EveryskFile deleted successfully."
+ *   - error message: "Unable to delete the file. Please try again." (fallback)
+ *
+ * Return value:
+ * @returns {object}
+ *  Returns an object with the three TanStack Query mutation results:
+ *  - `create`: UseMutationResult<EveryskFile, Error, CreateFileProps, unknown>
+ *  - `update`: UseMutationResult<EveryskFile, Error, UpdateFileProps, unknown>
+ *  - `remove`: UseMutationResult<EveryskFile, Error, DeleteFileProps, unknown>
+ *
+ * Each mutation includes standard TanStack Query helpers:
+ * - `mutate(variables, options?)`
+ * - `mutateAsync(variables, options?)`
+ * - `isPending`, `isSuccess`, `isError`, `error`, `data`, etc.
+ *
+ * Examples:
+ *
+ * 1) Invalidate a file list query after mutations:
+ * ```ts
+ * const { create, update, remove } = useFileMutations({ queryKey: ["file"] });
+ *
+ * // Create
+ * create.mutate({
+ *   data: {
+ *     name: "My file",
+ *     workspace: "ws-1",
+ *     content_type: "text/plain",
+ *     version: "1",
+ *     link_uid: null,
+ *     data: "SGVsbG8gd29ybGQ=", // Base64 content
+ *   }
+ * });
+ *
+ * // Update
+ * update.mutate({
+ *   id: "file-123",
+ *   data: {
+ *     name: "Renamed file",
+ *     content_type: "text/plain",
+ *     data: "SGVsbG8gd29ybGQ=", // Base64 content (optional if only renaming)
+ *   }
+ * });
+ *
+ * // Delete
+ * remove.mutate({ id: "file-123", workspace: "ws-1" });
+ * ```
+ *
+ * 2) Using async/await with `mutateAsync`:
+ * ```ts
+ * const { create } = useFileMutations({ queryKey: ["file"] });
+ *
+ * await create.mutateAsync({
+ *   data: {
+ *     name: "My file",
+ *     workspace: "ws-1",
+ *     content_type: "text/plain",
+ *     version: "1",
+ *     link_uid: null,
+ *     data: "SGVsbG8gd29ybGQ=",
+ *   }
+ * });
+ * ```
+ *
+ * 3) Without cache invalidation (no queryKey):
+ * ```ts
+ * const { update } = useFileMutations({});
+ *
+ * update.mutate({
+ *   id: "file-123",
+ *   data: {
+ *     name: "New name",
+ *     content_type: "text/plain",
+ *   }
+ * });
+ * // Mutation still runs and alerts are shown, but cached queries are not invalidated.
+ * ```
+ *
+ * 4) Using `useFetchFile` queryKey for automatic invalidation:
+ * ```ts
+ * const fetch = useFetchFile({
+ *   id: null,
+ *   filters: [{ field: "workspace", value: "ws-1" }],
+ * });
+ *
+ * const { remove } = useFileMutations({ queryKey: fetch.queryKey });
+ *
+ * await remove.mutateAsync({ id: "file-123", workspace: "ws-1" });
+ * ```
+ */
+
+export const useFileMutations = ({ queryKey }: UseFileMutationsProps) => {
+    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 }: CreateFileProps) => createFile(api, data),
+        onSuccess: async () => {
+            await invalidate();
+            showAlert({
+                severity: "success",
+                message: "EveryskFile created successfully.",
+            });
+        },
+        onError: (err: unknown) => {
+            showAlert({
+                severity: "error",
+                message: getErrorMessage(
+                    err,
+                    "Unable to create the file. Please try again."
+                ),
+            });
+        },
+    });
+
+    const update = useMutation({
+        mutationFn: async ({ id, data }: UpdateFileProps) => updateFile(api, id, data),
+        onSuccess: async () => {
+            await invalidate();
+            showAlert({
+                severity: "success",
+                message: "EveryskFile updated successfully.",
+            });
+        },
+        onError: (err: unknown) => {
+            showAlert({
+                severity: "error",
+                message: getErrorMessage(
+                    err,
+                    "Unable to update the file. Please try again."
+                ),
+            });
+        },
+    });
+
+    const remove = useMutation({
+        mutationFn: async ({ id, workspace }: DeleteFileProps) => deleteFile(api, id, workspace),
+        onSuccess: async () => {
+            await invalidate();
+            showAlert({
+                severity: "success",
+                message: "EveryskFile deleted successfully.",
+            });
+        },
+        onError: (err: unknown) => {
+            showAlert({
+                severity: "error",
+                message: getErrorMessage(
+                    err,
+                    "Unable to delete the file. Please try again."
+                ),
+            });
+        },
+    });
+
+    return { create, update, remove };
+};

package/src/hooks/portfolio/useFetchPortfolio.ts

@@ -0,0 +1,94 @@
+import { useEffect } from "react";
+import { useQuery } from "@tanstack/react-query";
+
+import { useAxios } from "@/hooks/useAxios";
+import { useAppAlert } from "@/contexts/appAlertContext/useAppAlert";
+import type { Portfolio } from "@/types/portfolio";
+import { getPortfolio } from "@/api/portfolio";
+import type { EntityQueryOptions, FetchEntityParams } from "@/types/entityQuery";
+
+export type FetchPortfolioProps<TData = Portfolio, TSelected = TData> = FetchEntityParams<TData, TSelected>;
+
+const defaultQueryOptions: EntityQueryOptions<Portfolio> = {
+    refetchOnMount: "always",
+    staleTime: 0,
+    gcTime: 0
+}
+
+/**
+ * useFetchPortfolio
+ *
+ * Data-fetching hook built on TanStack Query to retrieve a single portfolio 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
+ *
+ * Important notes:
+ * - Always returns a single `Portfolio` object.
+ *
+ * Parameters (FetchPortfolioProps):
+ * @param {string} id
+ *   Portfolio identifier (required).
+ *
+ * @param {string} workspace
+ *   Workspace the portfolio belongs to (required by `getPortfolio`).
+ *
+ * @param {EntityQueryOptions<Portfolio>} [queryOptions=defaultQueryOptions]
+ *   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
+ *
+ * Tip:
+ * - The returned `queryKey` can be reused by mutation hooks for cache invalidation:
+ *   ```ts
+ *   const fetch = useFetchPortfolio({ id: "pf-123", workspace: "ws-1" });
+ *   usePortfolioMutations({ queryKey: fetch.queryKey });
+ *   ```
+ *
+ * Example:
+ * ```ts
+ * const { data, isLoading } = useFetchPortfolio({
+ *   id: "pf-123",
+ *   workspace: "ws-1",
+ * });
+ * // data -> Portfolio
+ * ```
+ */
+export const useFetchPortfolio = ({ id, workspace, queryOptions = defaultQueryOptions }: FetchPortfolioProps) => {
+
+    const { api } = useAxios();
+    const { showAlert } = useAppAlert();
+
+    const queryKey = [
+        "portfolio",
+        id,
+        workspace
+    ];
+
+    const query = useQuery<Portfolio>({
+        queryKey,
+        queryFn: async () => {
+            const response = await getPortfolio(api, id, workspace);
+            return response.portfolio;
+        },
+        ...queryOptions ?? {}
+    });
+
+    useEffect(() => {
+        if (!query.error) return;
+
+        showAlert({
+            severity: "error",
+            message: query.error.message,
+        });
+    }, [query.error, showAlert]);
+
+    return {
+        ...query,
+        queryKey,
+    };
+};

package/src/hooks/portfolio/useFetchPortfolios.ts

@@ -0,0 +1,109 @@
+import { useMemo } from "react";
+import { useInfiniteQuery, type UseInfiniteQueryOptions, type QueryKey } from "@tanstack/react-query";
+
+import { useAxios } from "@/hooks/useAxios";
+import { listPortfolios } from "@/api/portfolio";
+import type { FetchEntitiesParams } from "@/types/entityQuery";
+import type { Portfolio, PortfolioListResponse } from "@/types/portfolio";
+import { buildQueryKey, buildQueryObject } from "@/api/entityQuery";
+
+type PageToken = string | null;
+
+type InfiniteOptions<TData> = Omit<
+    UseInfiniteQueryOptions<PortfolioListResponse, Error, TData, QueryKey, PageToken>,
+    "queryKey" | "queryFn" | "initialPageParam" | "getNextPageParam"
+>;
+
+export type FetchInfinitePortfolioProps = FetchEntitiesParams<Portfolio[], InfiniteOptions<Portfolio[]>> & {
+    pageSize?: number;
+};
+
+const defaultQueryOptions: InfiniteOptions<Portfolio[]> = {
+    refetchOnMount: "always",
+    staleTime: 0,
+    gcTime: 0,
+};
+
+/**
+ * useFetchInfinitePortfolios
+ *
+ * Data-fetching hook built on TanStack Query's `useInfiniteQuery` to retrieve
+ * portfolios with cursor-based pagination.
+ *
+ * It also:
+ * - flattens all pages into a single `Portfolio[]` via `select`
+ *
+ * Important notes:
+ * - `query.data` returns a flat `Portfolio[]` (all pages merged).
+ *
+ * Parameters (FetchInfinitePortfolioProps):
+ * @param {FilterClause[]} [filters=[]]
+ *   Filters applied to every page request. Must include a `workspace` filter.
+ *
+ * @param {string[]} [order=[]]
+ *   Sorting applied to every page request.
+ *
+ * @param {string} [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 {number} [pageSize=10]
+ *   Number of portfolios to fetch per page.
+ *
+ * @param {InfiniteOptions<Portfolio[]>} [queryOptions]
+ *   TanStack Query options passed through to `useInfiniteQuery`
+ *   (e.g., enabled, staleTime, gcTime, etc.).
+ *
+ * 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 } = useFetchInfinitePortfolios({
+ *   filters: [{ field: "workspace", value: "ws-1" }],
+ *   pageSize: 20,
+ * });
+ *
+ * // Flat list of all fetched portfolios
+ * const portfolios = query.data ?? [];
+ * ```
+ */
+export function useFetchPortfolios({ filters = [], order = [], projection = "", pageSize = 10, queryOptions }: FetchInfinitePortfolioProps) {
+    const { api } = useAxios();
+
+    const queryKey = buildQueryKey(["portfolios"], filters);
+
+    const mergedQueryOptions = useMemo<InfiniteOptions<Portfolio[]>>(() => ({
+        ...defaultQueryOptions,
+        ...(queryOptions ?? {}),
+    }), [queryOptions]);
+
+    const query = useInfiniteQuery<PortfolioListResponse, Error, Portfolio[], 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 listPortfolios(api, queryFilter);
+        },
+
+        select: (data) => data.pages.flatMap((p) => p.portfolios),
+
+        ...mergedQueryOptions,
+    });
+
+    return {
+        query,
+        queryKey,
+    };
+}