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

package/src/hooks/file/useFetchFile.ts

@@ -1,93 +1,58 @@
-import { useEffect } from "react";
-
-import { useQuery } from "@tanstack/react-query";
+import { useCallback } from "react";
 
 import { useAxios } from "@/hooks/useAxios";
-import type { EveryskFile } from "@/types/file";
-import { useAppAlert } from "@/contexts/appAlertContext/useAppAlert";
+import { useEntityQuery } from "@/hooks/useEntityQuery";
+import { missingWorkspaceError } from "@/api/entityQuery";
 import { getFile } from "@/api/file";
-import type { EntityQueryOptions, FetchEntityParams } from "@/types/entityQuery";
-
-export type FetchFileProps<TData = EveryskFile, TSelected = TData> = FetchEntityParams<TData, TSelected>;
+import type { EveryskFile } from "@/types/file";
+import type { FetchEntityByIdProps } from "@/types/entityQuery";
+import { withoutData, type FileDataProps } from "./fileData";
 
-const defaultQueryOptions: EntityQueryOptions<EveryskFile> = {
-    refetchOnMount: "always",
-    staleTime: 0,
-    gcTime: 0
-}
+export type FetchFileProps<TData = EveryskFile, TSelected = TData> = FetchEntityByIdProps<
+    TData,
+    TSelected
+> &
+    FileDataProps;
 
 /**
  * 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.).
+ * Fetches one file; `data` is the file, or whatever `select` makes of it. Idle while `id` is
+ * empty; fails loudly, without a request, while `workspace` is. A failure is shown as an error
+ * alert. The file comes without its content unless `withData` asks for it: show or download it
+ * through its `url`.
  *
- * 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
- * ```
+ * @param {FetchFileProps} props - `id`, `workspace`, `withData`, `select` and TanStack
+ *   `queryOptions`.
+ * @returns {object} The `useQuery` result, plus `queryKey`.
  */
-export const useFetchFile = ({ id, workspace, queryOptions = defaultQueryOptions }: FetchFileProps) => {
-
+export const useFetchFile = <TSelected = EveryskFile>({
+    id,
+    workspace,
+    select,
+    queryOptions,
+    withData = false,
+}: FetchFileProps<EveryskFile, TSelected>) => {
     const { api } = useAxios();
-    const { showAlert } = useAppAlert();
 
-    const queryKey = ["file", id, workspace];
+    const queryKey = ["file", id, workspace, { withData }];
 
-    const query = useQuery<EveryskFile>({
-        queryKey,
-        queryFn: async () => {
-            const file = await getFile(api, id, workspace);
-            return file;
+    const selectFile = useCallback(
+        (file: EveryskFile): TSelected => {
+            const visible = withData ? file : withoutData(file);
+            return select ? select(visible) : (visible as TSelected);
         },
-        ...queryOptions ?? {}
-    });
+        [withData, select],
+    );
 
-    useEffect(() => {
-        if (!query.error) return;
-
-        showAlert({
-            severity: "error",
-            message: query.error.message,
-        });
-    }, [query.error, showAlert]);
-
-    return {
-        ...query,
+    const query = useEntityQuery<EveryskFile, TSelected>({
         queryKey,
-    };
+        fetchEntity: (signal) => getFile(api, id, workspace, { withData }, signal),
+        select: selectFile,
+        enabled: Boolean(id),
+        configError: workspace ? undefined : missingWorkspaceError("useFetchFile"),
+        queryOptions,
+    });
+
+    return { ...query, queryKey };
 };

package/src/hooks/file/useFetchFiles.ts

@@ -1,109 +1,114 @@
-import { useMemo } from "react";
-import { useInfiniteQuery, type UseInfiniteQueryOptions, type QueryKey } from "@tanstack/react-query";
+import { useCallback } from "react";
 
 import { useAxios } from "@/hooks/useAxios";
+import { useEntityInfiniteQuery } from "@/hooks/useEntityInfiniteQuery";
 import { listFiles } from "@/api/file";
 import type { EveryskFile, FileListResponse } from "@/types/file";
-import type { FetchEntitiesParams } from "@/types/entityQuery";
-import { buildQueryKey, buildQueryObject } from "@/api/entityQuery";
+import type {
+    FetchEntitiesProps,
+    ListQueryProps,
+    ListCache,
+    Projection,
+} from "@/types/entityQuery";
+import {
+    buildQueryKey,
+    buildQueryObject,
+    hasWorkspaceFilter,
+    missingWorkspaceError,
+} from "@/api/entityQuery";
+import { withoutData, type FileDataProps } from "./fileData";
 
-type PageToken = string | null;
+/** The query cache of `useFetchFiles`, for typing `setQueryData`. */
+export type FilesCache = ListCache<FileListResponse>;
 
-type InfiniteOptions<TData> = Omit<
-    UseInfiniteQueryOptions<FileListResponse, Error, TData, QueryKey, PageToken>,
-    "queryKey" | "queryFn" | "initialPageParam" | "getNextPageParam"
->;
+export type FetchFilesProps<TData = EveryskFile[]> = ListQueryProps &
+    FetchEntitiesProps<EveryskFile, TData, FileListResponse> &
+    FileDataProps;
 
-export type FetchInfiniteFileProps = FetchEntitiesParams<EveryskFile[], InfiniteOptions<EveryskFile[]>> & {
-    pageSize?: number;
-};
+/** What leaves the content out of a list: the JSON query returns `data` in full otherwise. */
+const WITHOUT_DATA_PROJECTION = "-data";
+
+/**
+ * The projection a list read sends. The content is left out unless asked for: alone when the app
+ * gave no projection, and added to one that only excludes fields. A projection that includes
+ * fields is sent as given, since mixing an inclusion with an exclusion is a 500; it then decides
+ * itself whether `data` is read.
+ */
+const projectionToSend = (projection: Projection, withData: boolean): Projection => {
+    if (withData) return projection;
 
-const defaultQueryOptions: InfiniteOptions<EveryskFile[]> = {
-    refetchOnMount: "always",
-    staleTime: 0,
-    gcTime: 0,
+    const fields = typeof projection === "string" ? [projection].filter(Boolean) : projection;
+    if (fields.length === 0) return WITHOUT_DATA_PROJECTION;
+    if (!fields.every((field) => field.startsWith("-")) || fields.includes(WITHOUT_DATA_PROJECTION))
+        return projection;
+    return [...fields, WITHOUT_DATA_PROJECTION];
 };
 
 /**
  * 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.).
+ * Lists files with cursor pagination; `query.data` is every loaded page merged, or whatever
+ * `select` makes of it. Paging, `select`, `fetchAllPages` and the missing-workspace error
+ * behave as in `useFetchDatastores`. The files come without their content unless `withData`
+ * asks for it: show or download each through its `url`. The exclusion of `data` is added to a
+ * `projection` of the app's own that only excludes fields; one that includes fields is sent as
+ * given (see `projectionToSend`). Either way the content is left out of what the hook returns
+ * unless `withData` asks for it.
  *
- * 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 ?? [];
- * ```
+ * @param {FetchFilesProps} props - Filters (one must be `workspace`), order, projection,
+ *   page size, `withData`, `select`, `fetchAllPages` and TanStack `queryOptions`.
+ * @returns {object} `query` (the `useInfiniteQuery` result) and `queryKey`.
  */
-export function useFetchFiles({ filters = [], order = [], projection = "", pageSize = 10, queryOptions }: FetchInfiniteFileProps) {
+export function useFetchFiles<TData = EveryskFile[]>({
+    filters = [],
+    order = [],
+    projection = "",
+    pageSize = 10,
+    select,
+    fetchAllPages = false,
+    queryOptions,
+    withData = false,
+}: FetchFilesProps<TData>) {
     const { api } = useAxios();
+    const sentProjection = projectionToSend(projection, withData);
 
-    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,
-            });
+    const queryKey = buildQueryKey(["files"], filters, {
+        order,
+        projection: sentProjection,
+        pageSize,
+        fetchAllPages,
+    });
 
-            return await listFiles(api, queryFilter);
+    const selectFiles = useCallback(
+        (files: EveryskFile[]): TData => {
+            const visible = withData ? files : files.map(withoutData);
+            return select ? select(visible) : (visible as TData);
         },
+        [withData, select],
+    );
 
-        select: (data) => data.pages.flatMap((p) => p.files),
-
-        ...mergedQueryOptions,
+    const query = useEntityInfiniteQuery<FileListResponse, "files", TData>({
+        queryKey,
+        itemsKey: "files",
+        fetchPage: (pageToken, signal) =>
+            listFiles(
+                api,
+                buildQueryObject({
+                    filters,
+                    order,
+                    projection: sentProjection,
+                    pageSize,
+                    pageToken,
+                }),
+                signal,
+            ),
+        select: selectFiles,
+        fetchAllPages,
+        configError: hasWorkspaceFilter(filters)
+            ? undefined
+            : missingWorkspaceError("useFetchFiles"),
+        queryOptions,
     });
 
-    return {
-        query,
-        queryKey,
-    };
-}
+    return { query, queryKey };
+}

package/src/hooks/file/useFileMutations.ts

@@ -1,7 +1,5 @@
-import { useMutation, useQueryClient } from "@tanstack/react-query";
-
 import { useAxios } from "@/hooks/useAxios";
-import { useAppAlert } from "@/contexts/appAlertContext/useAppAlert";
+import { useEntityMutation } from "@/hooks/useEntityMutation";
 import type { EveryskFile } from "@/types/file";
 import { deleteFile, createFile, updateFile } from "@/api/file";
 
@@ -23,9 +21,6 @@ type UseFileMutationsProps = {
     queryKey?: unknown[];
 };
 
-const getErrorMessage = (err: unknown, fallback: string) =>
-    err instanceof Error && err.message ? err.message : fallback;
-
 /**
  * useFileMutations
  *
@@ -44,10 +39,11 @@ const getErrorMessage = (err: unknown, fallback: string) =>
  *   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,`)
+ *   - Send only the raw Base64 content (do not include a data URL prefix like `data:<mime>;base64,`):
+ *     `fileToBase64(file)` gives it from a `File`, and a data URL is refused before the request
  *   - `content_type` should match the file MIME type (e.g., "text/csv", "application/pdf").
  *
  * Parameters (UseFileMutationsProps):
@@ -64,19 +60,19 @@ const getErrorMessage = (err: unknown, fallback: string) =>
  * - `create`:
  *   - mutationFn: `createFile(api, data)`
  *   - variables: `{ data: Partial<EveryskFile> }`
- *   - success message: "EveryskFile created successfully."
+ *   - success message: "File 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."
+ *   - success message: "File 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."
+ *   - success message: "File deleted successfully."
  *   - error message: "Unable to delete the file. Please try again." (fallback)
  *
  * Return value:
@@ -84,7 +80,7 @@ const getErrorMessage = (err: unknown, fallback: string) =>
  *  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>
+ *  - `remove`: UseMutationResult<DeletedEntity, Error, DeleteFileProps, unknown>
  *
  * Each mutation includes standard TanStack Query helpers:
  * - `mutate(variables, options?)`
@@ -168,72 +164,26 @@ const getErrorMessage = (err: unknown, fallback: string) =>
 
 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 create = useEntityMutation({
+        mutationFn: ({ data }: CreateFileProps) => createFile(api, data),
+        queryKey,
+        successMessage: "File created successfully.",
+        errorMessage: "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 update = useEntityMutation({
+        mutationFn: ({ id, data }: UpdateFileProps) => updateFile(api, id, data),
+        queryKey,
+        successMessage: "File updated successfully.",
+        errorMessage: "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."
-                ),
-            });
-        },
+    const remove = useEntityMutation({
+        mutationFn: ({ id, workspace }: DeleteFileProps) => deleteFile(api, id, workspace),
+        queryKey,
+        successMessage: "File deleted successfully.",
+        errorMessage: "Unable to delete the file. Please try again.",
     });
 
     return { create, update, remove };

package/src/hooks/portfolio/useFetchPortfolio.ts

@@ -1,94 +1,42 @@
-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 { useEntityQuery } from "@/hooks/useEntityQuery";
+import { missingWorkspaceError } from "@/api/entityQuery";
 import { getPortfolio } from "@/api/portfolio";
-import type { EntityQueryOptions, FetchEntityParams } from "@/types/entityQuery";
-
-export type FetchPortfolioProps<TData = Portfolio, TSelected = TData> = FetchEntityParams<TData, TSelected>;
+import type { Portfolio } from "@/types/portfolio";
+import type { FetchEntityByIdProps } from "@/types/entityQuery";
 
-const defaultQueryOptions: EntityQueryOptions<Portfolio> = {
-    refetchOnMount: "always",
-    staleTime: 0,
-    gcTime: 0
-}
+export type FetchPortfolioProps<TData = Portfolio, TSelected = TData> = FetchEntityByIdProps<
+    TData,
+    TSelected
+>;
 
 /**
  * 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`).
+ * Fetches one portfolio; `data` is the portfolio, or whatever `select` makes of it. Idle while
+ * `id` is empty; fails loudly, without a request, while `workspace` is. A failure is shown as an error alert.
  *
- * @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
- * ```
+ * @param {FetchPortfolioProps} props - `id`, `workspace`, `select` and TanStack `queryOptions`.
+ * @returns {object} The `useQuery` result, plus `queryKey`.
  */
-export const useFetchPortfolio = ({ id, workspace, queryOptions = defaultQueryOptions }: FetchPortfolioProps) => {
-
+export const useFetchPortfolio = <TSelected = Portfolio>({
+    id,
+    workspace,
+    select,
+    queryOptions,
+}: FetchPortfolioProps<Portfolio, TSelected>) => {
     const { api } = useAxios();
-    const { showAlert } = useAppAlert();
 
-    const queryKey = [
-        "portfolio",
-        id,
-        workspace
-    ];
+    const queryKey = ["portfolio", id, workspace];
 
-    const query = useQuery<Portfolio>({
+    const query = useEntityQuery<Portfolio, TSelected>({
         queryKey,
-        queryFn: async () => {
-            const response = await getPortfolio(api, id, workspace);
-            return response.portfolio;
-        },
-        ...queryOptions ?? {}
+        fetchEntity: (signal) => getPortfolio(api, id, workspace, signal),
+        select,
+        enabled: Boolean(id),
+        configError: workspace ? undefined : missingWorkspaceError("useFetchPortfolio"),
+        queryOptions,
     });
 
-    useEffect(() => {
-        if (!query.error) return;
-
-        showAlert({
-            severity: "error",
-            message: query.error.message,
-        });
-    }, [query.error, showAlert]);
-
-    return {
-        ...query,
-        queryKey,
-    };
+    return { ...query, queryKey };
 };