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

package/dist/hooks/file/useFileMutations.js.map

@@ -1 +1 @@
-{"version":3,"file":"useFileMutations.js","names":[],"sources":["../../../src/hooks/file/useFileMutations.ts"],"sourcesContent":["import { useMutation, useQueryClient } from \"@tanstack/react-query\";\n\nimport { useAxios } from \"@/hooks/useAxios\";\nimport { useAppAlert } from \"@/contexts/appAlertContext/useAppAlert\";\nimport type { EveryskFile } from \"@/types/file\";\nimport { deleteFile, createFile, updateFile } from \"@/api/file\";\n\ntype CreateFileProps = {\n    data: Partial<EveryskFile>;\n};\n\ntype UpdateFileProps = {\n    id: string;\n    data: Partial<EveryskFile>;\n};\n\ntype DeleteFileProps = {\n    id: string;\n    workspace: string;\n};\n\ntype UseFileMutationsProps = {\n    queryKey?: unknown[];\n};\n\nconst getErrorMessage = (err: unknown, fallback: string) =>\n    err instanceof Error && err.message ? err.message : fallback;\n\n/**\n * useFileMutations\n *\n * Mutation hook built on TanStack Query to perform EveryskFile write operations:\n * - create a file (POST)\n * - update a file (PUT)\n * - delete a file (DELETE)\n *\n * It also:\n * - optionally invalidates a target query cache key after successful mutations\n * - displays success/error alerts via `useAppAlert`\n *\n * Important notes:\n * - This hook is intended for side-effect operations only. Reading/retrieving data should be done via `useQuery` or `useFetchFile`.\n * - Cache invalidation is controlled by `queryKey`. If `queryKey` is not provided, the hook will still run\n *   mutations and show alerts, but it will NOT invalidate any cached queries.\n * - `remove` requires a `workspace` parameter because the underlying API helper `deleteFile(api, id, workspace)`\n *   expects it as a query param.\n * \n * - EveryskFile content (`data`):\n *   - When creating/updating a file, the file content must be provided in `data` as a Base64-encoded string.\n *   - Send only the raw Base64 content (do not include a data URL prefix like `data:<mime>;base64,`)\n *   - `content_type` should match the file MIME type (e.g., \"text/csv\", \"application/pdf\").\n *\n * Parameters (UseFileMutationsProps):\n * @param {unknown[]} [queryKey]\n *  Query key to invalidate after successful mutations. Use the same `queryKey` you pass to the relevant `useQuery`\n *  (e.g., file list/detail) so UI data is refreshed automatically after a write.\n *\n *  Tip:\n *  - If you're using `useFetchFile`, you can pass its returned `queryKey` directly:\n *    `const fetch = useFetchFile(...);`\n *    `useFileMutations({ queryKey: fetch.queryKey });`\n *\n * Mutations:\n * - `create`:\n *   - mutationFn: `createFile(api, data)`\n *   - variables: `{ data: Partial<EveryskFile> }`\n *   - success message: \"EveryskFile created successfully.\"\n *   - error message: \"Unable to create the file. Please try again.\" (fallback)\n *\n * - `update`:\n *   - mutationFn: `updateFile(api, id, data)`\n *   - variables: `{ id: string; data: Partial<EveryskFile> }`\n *   - success message: \"EveryskFile updated successfully.\"\n *   - error message: \"Unable to update the file. Please try again.\" (fallback)\n *\n * - `remove`:\n *   - mutationFn: `deleteFile(api, id, workspace)`\n *   - variables: `{ id: string; workspace: string }`\n *   - success message: \"EveryskFile deleted successfully.\"\n *   - error message: \"Unable to delete the file. Please try again.\" (fallback)\n *\n * Return value:\n * @returns {object}\n *  Returns an object with the three TanStack Query mutation results:\n *  - `create`: UseMutationResult<EveryskFile, Error, CreateFileProps, unknown>\n *  - `update`: UseMutationResult<EveryskFile, Error, UpdateFileProps, unknown>\n *  - `remove`: UseMutationResult<EveryskFile, Error, DeleteFileProps, unknown>\n *\n * Each mutation includes standard TanStack Query helpers:\n * - `mutate(variables, options?)`\n * - `mutateAsync(variables, options?)`\n * - `isPending`, `isSuccess`, `isError`, `error`, `data`, etc.\n *\n * Examples:\n *\n * 1) Invalidate a file list query after mutations:\n * ```ts\n * const { create, update, remove } = useFileMutations({ queryKey: [\"file\"] });\n *\n * // Create\n * create.mutate({\n *   data: {\n *     name: \"My file\",\n *     workspace: \"ws-1\",\n *     content_type: \"text/plain\",\n *     version: \"1\",\n *     link_uid: null,\n *     data: \"SGVsbG8gd29ybGQ=\", // Base64 content\n *   }\n * });\n *\n * // Update\n * update.mutate({\n *   id: \"file-123\",\n *   data: {\n *     name: \"Renamed file\",\n *     content_type: \"text/plain\",\n *     data: \"SGVsbG8gd29ybGQ=\", // Base64 content (optional if only renaming)\n *   }\n * });\n *\n * // Delete\n * remove.mutate({ id: \"file-123\", workspace: \"ws-1\" });\n * ```\n *\n * 2) Using async/await with `mutateAsync`:\n * ```ts\n * const { create } = useFileMutations({ queryKey: [\"file\"] });\n *\n * await create.mutateAsync({\n *   data: {\n *     name: \"My file\",\n *     workspace: \"ws-1\",\n *     content_type: \"text/plain\",\n *     version: \"1\",\n *     link_uid: null,\n *     data: \"SGVsbG8gd29ybGQ=\",\n *   }\n * });\n * ```\n *\n * 3) Without cache invalidation (no queryKey):\n * ```ts\n * const { update } = useFileMutations({});\n *\n * update.mutate({\n *   id: \"file-123\",\n *   data: {\n *     name: \"New name\",\n *     content_type: \"text/plain\",\n *   }\n * });\n * // Mutation still runs and alerts are shown, but cached queries are not invalidated.\n * ```\n *\n * 4) Using `useFetchFile` queryKey for automatic invalidation:\n * ```ts\n * const fetch = useFetchFile({\n *   id: null,\n *   filters: [{ field: \"workspace\", value: \"ws-1\" }],\n * });\n *\n * const { remove } = useFileMutations({ queryKey: fetch.queryKey });\n *\n * await remove.mutateAsync({ id: \"file-123\", workspace: \"ws-1\" });\n * ```\n */\n\nexport const useFileMutations = ({ queryKey }: UseFileMutationsProps) => {\n    const { api } = useAxios();\n    const { showAlert } = useAppAlert();\n    const queryClient = useQueryClient();\n\n    const invalidate = async () => {\n        if (!queryKey?.length) return;\n        await queryClient.invalidateQueries({ queryKey });\n    };\n\n    const create = useMutation({\n        mutationFn: async ({ data }: CreateFileProps) => createFile(api, data),\n        onSuccess: async () => {\n            await invalidate();\n            showAlert({\n                severity: \"success\",\n                message: \"EveryskFile created successfully.\",\n            });\n        },\n        onError: (err: unknown) => {\n            showAlert({\n                severity: \"error\",\n                message: getErrorMessage(\n                    err,\n                    \"Unable to create the file. Please try again.\"\n                ),\n            });\n        },\n    });\n\n    const update = useMutation({\n        mutationFn: async ({ id, data }: UpdateFileProps) => updateFile(api, id, data),\n        onSuccess: async () => {\n            await invalidate();\n            showAlert({\n                severity: \"success\",\n                message: \"EveryskFile updated successfully.\",\n            });\n        },\n        onError: (err: unknown) => {\n            showAlert({\n                severity: \"error\",\n                message: getErrorMessage(\n                    err,\n                    \"Unable to update the file. Please try again.\"\n                ),\n            });\n        },\n    });\n\n    const remove = useMutation({\n        mutationFn: async ({ id, workspace }: DeleteFileProps) => deleteFile(api, id, workspace),\n        onSuccess: async () => {\n            await invalidate();\n            showAlert({\n                severity: \"success\",\n                message: \"EveryskFile deleted successfully.\",\n            });\n        },\n        onError: (err: unknown) => {\n            showAlert({\n                severity: \"error\",\n                message: getErrorMessage(\n                    err,\n                    \"Unable to delete the file. Please try again.\"\n                ),\n            });\n        },\n    });\n\n    return { create, update, remove };\n};\n"],"mappings":";;;;;AAyBA,IAAM,mBAAmB,KAAc,aACnC,eAAe,SAAS,IAAI,UAAU,IAAI,UAAU;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;AA8IxD,IAAa,oBAAoB,EAAE,eAAsC;CACrE,MAAM,EAAE,QAAQ,SAAS;CACzB,MAAM,EAAE,cAAc,YAAY;CAClC,MAAM,cAAc,eAAe;CAEnC,MAAM,aAAa,YAAY;EAC3B,IAAI,CAAC,UAAU,QAAQ;EACvB,MAAM,YAAY,kBAAkB,EAAE,SAAS,CAAC;CACpD;CA8DA,OAAO;EAAE,QA5DM,YAAY;GACvB,YAAY,OAAO,EAAE,WAA4B,WAAW,KAAK,IAAI;GACrE,WAAW,YAAY;IACnB,MAAM,WAAW;IACjB,UAAU;KACN,UAAU;KACV,SAAS;IACb,CAAC;GACL;GACA,UAAU,QAAiB;IACvB,UAAU;KACN,UAAU;KACV,SAAS,gBACL,KACA,8CACJ;IACJ,CAAC;GACL;EACJ,CA0CS;EAAQ,QAxCF,YAAY;GACvB,YAAY,OAAO,EAAE,IAAI,WAA4B,WAAW,KAAK,IAAI,IAAI;GAC7E,WAAW,YAAY;IACnB,MAAM,WAAW;IACjB,UAAU;KACN,UAAU;KACV,SAAS;IACb,CAAC;GACL;GACA,UAAU,QAAiB;IACvB,UAAU;KACN,UAAU;KACV,SAAS,gBACL,KACA,8CACJ;IACJ,CAAC;GACL;EACJ,CAsBiB;EAAQ,QApBV,YAAY;GACvB,YAAY,OAAO,EAAE,IAAI,gBAAiC,WAAW,KAAK,IAAI,SAAS;GACvF,WAAW,YAAY;IACnB,MAAM,WAAW;IACjB,UAAU;KACN,UAAU;KACV,SAAS;IACb,CAAC;GACL;GACA,UAAU,QAAiB;IACvB,UAAU;KACN,UAAU;KACV,SAAS,gBACL,KACA,8CACJ;IACJ,CAAC;GACL;EACJ,CAEyB;CAAO;AACpC"}
+{"version":3,"file":"useFileMutations.js","names":[],"sources":["../../../src/hooks/file/useFileMutations.ts"],"sourcesContent":["import { useAxios } from \"@/hooks/useAxios\";\nimport { useEntityMutation } from \"@/hooks/useEntityMutation\";\nimport type { EveryskFile } from \"@/types/file\";\nimport { deleteFile, createFile, updateFile } from \"@/api/file\";\n\ntype CreateFileProps = {\n    data: Partial<EveryskFile>;\n};\n\ntype UpdateFileProps = {\n    id: string;\n    data: Partial<EveryskFile>;\n};\n\ntype DeleteFileProps = {\n    id: string;\n    workspace: string;\n};\n\ntype UseFileMutationsProps = {\n    queryKey?: unknown[];\n};\n\n/**\n * useFileMutations\n *\n * Mutation hook built on TanStack Query to perform EveryskFile write operations:\n * - create a file (POST)\n * - update a file (PUT)\n * - delete a file (DELETE)\n *\n * It also:\n * - optionally invalidates a target query cache key after successful mutations\n * - displays success/error alerts via `useAppAlert`\n *\n * Important notes:\n * - This hook is intended for side-effect operations only. Reading/retrieving data should be done via `useQuery` or `useFetchFile`.\n * - Cache invalidation is controlled by `queryKey`. If `queryKey` is not provided, the hook will still run\n *   mutations and show alerts, but it will NOT invalidate any cached queries.\n * - `remove` requires a `workspace` parameter because the underlying API helper `deleteFile(api, id, workspace)`\n *   expects it as a query param.\n *\n * - EveryskFile content (`data`):\n *   - When creating/updating a file, the file content must be provided in `data` as a Base64-encoded string.\n *   - Send only the raw Base64 content (do not include a data URL prefix like `data:<mime>;base64,`):\n *     `fileToBase64(file)` gives it from a `File`, and a data URL is refused before the request\n *   - `content_type` should match the file MIME type (e.g., \"text/csv\", \"application/pdf\").\n *\n * Parameters (UseFileMutationsProps):\n * @param {unknown[]} [queryKey]\n *  Query key to invalidate after successful mutations. Use the same `queryKey` you pass to the relevant `useQuery`\n *  (e.g., file list/detail) so UI data is refreshed automatically after a write.\n *\n *  Tip:\n *  - If you're using `useFetchFile`, you can pass its returned `queryKey` directly:\n *    `const fetch = useFetchFile(...);`\n *    `useFileMutations({ queryKey: fetch.queryKey });`\n *\n * Mutations:\n * - `create`:\n *   - mutationFn: `createFile(api, data)`\n *   - variables: `{ data: Partial<EveryskFile> }`\n *   - success message: \"File created successfully.\"\n *   - error message: \"Unable to create the file. Please try again.\" (fallback)\n *\n * - `update`:\n *   - mutationFn: `updateFile(api, id, data)`\n *   - variables: `{ id: string; data: Partial<EveryskFile> }`\n *   - success message: \"File updated successfully.\"\n *   - error message: \"Unable to update the file. Please try again.\" (fallback)\n *\n * - `remove`:\n *   - mutationFn: `deleteFile(api, id, workspace)`\n *   - variables: `{ id: string; workspace: string }`\n *   - success message: \"File deleted successfully.\"\n *   - error message: \"Unable to delete the file. Please try again.\" (fallback)\n *\n * Return value:\n * @returns {object}\n *  Returns an object with the three TanStack Query mutation results:\n *  - `create`: UseMutationResult<EveryskFile, Error, CreateFileProps, unknown>\n *  - `update`: UseMutationResult<EveryskFile, Error, UpdateFileProps, unknown>\n *  - `remove`: UseMutationResult<DeletedEntity, Error, DeleteFileProps, unknown>\n *\n * Each mutation includes standard TanStack Query helpers:\n * - `mutate(variables, options?)`\n * - `mutateAsync(variables, options?)`\n * - `isPending`, `isSuccess`, `isError`, `error`, `data`, etc.\n *\n * Examples:\n *\n * 1) Invalidate a file list query after mutations:\n * ```ts\n * const { create, update, remove } = useFileMutations({ queryKey: [\"file\"] });\n *\n * // Create\n * create.mutate({\n *   data: {\n *     name: \"My file\",\n *     workspace: \"ws-1\",\n *     content_type: \"text/plain\",\n *     version: \"1\",\n *     link_uid: null,\n *     data: \"SGVsbG8gd29ybGQ=\", // Base64 content\n *   }\n * });\n *\n * // Update\n * update.mutate({\n *   id: \"file-123\",\n *   data: {\n *     name: \"Renamed file\",\n *     content_type: \"text/plain\",\n *     data: \"SGVsbG8gd29ybGQ=\", // Base64 content (optional if only renaming)\n *   }\n * });\n *\n * // Delete\n * remove.mutate({ id: \"file-123\", workspace: \"ws-1\" });\n * ```\n *\n * 2) Using async/await with `mutateAsync`:\n * ```ts\n * const { create } = useFileMutations({ queryKey: [\"file\"] });\n *\n * await create.mutateAsync({\n *   data: {\n *     name: \"My file\",\n *     workspace: \"ws-1\",\n *     content_type: \"text/plain\",\n *     version: \"1\",\n *     link_uid: null,\n *     data: \"SGVsbG8gd29ybGQ=\",\n *   }\n * });\n * ```\n *\n * 3) Without cache invalidation (no queryKey):\n * ```ts\n * const { update } = useFileMutations({});\n *\n * update.mutate({\n *   id: \"file-123\",\n *   data: {\n *     name: \"New name\",\n *     content_type: \"text/plain\",\n *   }\n * });\n * // Mutation still runs and alerts are shown, but cached queries are not invalidated.\n * ```\n *\n * 4) Using `useFetchFile` queryKey for automatic invalidation:\n * ```ts\n * const fetch = useFetchFile({\n *   id: null,\n *   filters: [{ field: \"workspace\", value: \"ws-1\" }],\n * });\n *\n * const { remove } = useFileMutations({ queryKey: fetch.queryKey });\n *\n * await remove.mutateAsync({ id: \"file-123\", workspace: \"ws-1\" });\n * ```\n */\n\nexport const useFileMutations = ({ queryKey }: UseFileMutationsProps) => {\n    const { api } = useAxios();\n\n    const create = useEntityMutation({\n        mutationFn: ({ data }: CreateFileProps) => createFile(api, data),\n        queryKey,\n        successMessage: \"File created successfully.\",\n        errorMessage: \"Unable to create the file. Please try again.\",\n    });\n\n    const update = useEntityMutation({\n        mutationFn: ({ id, data }: UpdateFileProps) => updateFile(api, id, data),\n        queryKey,\n        successMessage: \"File updated successfully.\",\n        errorMessage: \"Unable to update the file. Please try again.\",\n    });\n\n    const remove = useEntityMutation({\n        mutationFn: ({ id, workspace }: DeleteFileProps) => deleteFile(api, id, workspace),\n        queryKey,\n        successMessage: \"File deleted successfully.\",\n        errorMessage: \"Unable to delete the file. Please try again.\",\n    });\n\n    return { create, update, remove };\n};\n"],"mappings":";;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;AAoKA,IAAa,oBAAoB,EAAE,eAAsC;CACrE,MAAM,EAAE,QAAQ,SAAS;CAuBzB,OAAO;EAAE,QArBM,kBAAkB;GAC7B,aAAa,EAAE,WAA4B,WAAW,KAAK,IAAI;GAC/D;GACA,gBAAgB;GAChB,cAAc;EAClB,CAgBS;EAAQ,QAdF,kBAAkB;GAC7B,aAAa,EAAE,IAAI,WAA4B,WAAW,KAAK,IAAI,IAAI;GACvE;GACA,gBAAgB;GAChB,cAAc;EAClB,CASiB;EAAQ,QAPV,kBAAkB;GAC7B,aAAa,EAAE,IAAI,gBAAiC,WAAW,KAAK,IAAI,SAAS;GACjF;GACA,gBAAgB;GAChB,cAAc;EAClB,CAEyB;CAAO;AACpC"}

package/dist/hooks/portfolio/useFetchPortfolio.d.ts

@@ -1,52 +1,18 @@
 import type { Portfolio } from "../../types/portfolio.d.ts";
-import type { FetchEntityParams } from "../../types/entityQuery.d.ts";
-export type FetchPortfolioProps<TData = Portfolio, TSelected = TData> = FetchEntityParams<TData, TSelected>;
+import type { FetchEntityByIdProps } from "../../types/entityQuery.d.ts";
+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.
+ * 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.
  *
- * 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
- * ```
+ * @param {FetchPortfolioProps} props - `id`, `workspace`, `select` and TanStack `queryOptions`.
+ * @returns {object} The `useQuery` result, plus `queryKey`.
  */
-export declare const useFetchPortfolio: ({ id, workspace, queryOptions }: FetchPortfolioProps) => {
+export declare const useFetchPortfolio: <TSelected = Portfolio>({ id, workspace, select, queryOptions, }: FetchPortfolioProps<Portfolio, TSelected>) => {
     queryKey: string[];
-    data: Portfolio;
+    data: TSelected;
     error: Error;
     isError: true;
     isPending: false;
@@ -69,11 +35,11 @@ export declare const useFetchPortfolio: ({ id, workspace, queryOptions }: FetchP
     isRefetching: boolean;
     isStale: boolean;
     isEnabled: boolean;
-    refetch: (options?: import("@tanstack/query-core").RefetchOptions) => Promise<import("@tanstack/query-core").QueryObserverResult<Portfolio, Error>>;
+    refetch: (options?: import("@tanstack/query-core").RefetchOptions) => Promise<import("@tanstack/query-core").QueryObserverResult<TSelected, Error>>;
     fetchStatus: import("@tanstack/query-core").FetchStatus;
 } | {
     queryKey: string[];
-    data: Portfolio;
+    data: TSelected;
     error: null;
     isError: false;
     isPending: false;
@@ -96,7 +62,7 @@ export declare const useFetchPortfolio: ({ id, workspace, queryOptions }: FetchP
     isRefetching: boolean;
     isStale: boolean;
     isEnabled: boolean;
-    refetch: (options?: import("@tanstack/query-core").RefetchOptions) => Promise<import("@tanstack/query-core").QueryObserverResult<Portfolio, Error>>;
+    refetch: (options?: import("@tanstack/query-core").RefetchOptions) => Promise<import("@tanstack/query-core").QueryObserverResult<TSelected, Error>>;
     fetchStatus: import("@tanstack/query-core").FetchStatus;
 } | {
     queryKey: string[];
@@ -123,7 +89,7 @@ export declare const useFetchPortfolio: ({ id, workspace, queryOptions }: FetchP
     isRefetching: boolean;
     isStale: boolean;
     isEnabled: boolean;
-    refetch: (options?: import("@tanstack/query-core").RefetchOptions) => Promise<import("@tanstack/query-core").QueryObserverResult<Portfolio, Error>>;
+    refetch: (options?: import("@tanstack/query-core").RefetchOptions) => Promise<import("@tanstack/query-core").QueryObserverResult<TSelected, Error>>;
     fetchStatus: import("@tanstack/query-core").FetchStatus;
 } | {
     queryKey: string[];
@@ -150,7 +116,7 @@ export declare const useFetchPortfolio: ({ id, workspace, queryOptions }: FetchP
     isRefetching: boolean;
     isStale: boolean;
     isEnabled: boolean;
-    refetch: (options?: import("@tanstack/query-core").RefetchOptions) => Promise<import("@tanstack/query-core").QueryObserverResult<Portfolio, Error>>;
+    refetch: (options?: import("@tanstack/query-core").RefetchOptions) => Promise<import("@tanstack/query-core").QueryObserverResult<TSelected, Error>>;
     fetchStatus: import("@tanstack/query-core").FetchStatus;
 } | {
     queryKey: string[];
@@ -177,11 +143,11 @@ export declare const useFetchPortfolio: ({ id, workspace, queryOptions }: FetchP
     isRefetching: boolean;
     isStale: boolean;
     isEnabled: boolean;
-    refetch: (options?: import("@tanstack/query-core").RefetchOptions) => Promise<import("@tanstack/query-core").QueryObserverResult<Portfolio, Error>>;
+    refetch: (options?: import("@tanstack/query-core").RefetchOptions) => Promise<import("@tanstack/query-core").QueryObserverResult<TSelected, Error>>;
     fetchStatus: import("@tanstack/query-core").FetchStatus;
 } | {
     queryKey: string[];
-    data: Portfolio;
+    data: TSelected;
     isError: false;
     error: null;
     isPending: false;
@@ -204,7 +170,7 @@ export declare const useFetchPortfolio: ({ id, workspace, queryOptions }: FetchP
     isRefetching: boolean;
     isStale: boolean;
     isEnabled: boolean;
-    refetch: (options?: import("@tanstack/query-core").RefetchOptions) => Promise<import("@tanstack/query-core").QueryObserverResult<Portfolio, Error>>;
+    refetch: (options?: import("@tanstack/query-core").RefetchOptions) => Promise<import("@tanstack/query-core").QueryObserverResult<TSelected, Error>>;
     fetchStatus: import("@tanstack/query-core").FetchStatus;
 };
 //# sourceMappingURL=useFetchPortfolio.d.ts.map

package/dist/hooks/portfolio/useFetchPortfolio.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"useFetchPortfolio.d.ts","sourceRoot":"","sources":["../../../src/hooks/portfolio/useFetchPortfolio.ts"],"names":[],"mappings":"AAKA,OAAO,KAAK,EAAE,SAAS,EAAE,MAAM,mBAAmB,CAAC;AAEnD,OAAO,KAAK,EAAsB,iBAAiB,EAAE,MAAM,qBAAqB,CAAC;AAEjF,MAAM,MAAM,mBAAmB,CAAC,KAAK,GAAG,SAAS,EAAE,SAAS,GAAG,KAAK,IAAI,iBAAiB,CAAC,KAAK,EAAE,SAAS,CAAC,CAAC;AAQ5G;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;GA0CG;AACH,eAAO,MAAM,iBAAiB,GAAI,iCAAuD,mBAAmB;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;CAiC3G,CAAC"}
+{"version":3,"file":"useFetchPortfolio.d.ts","sourceRoot":"","sources":["../../../src/hooks/portfolio/useFetchPortfolio.ts"],"names":[],"mappings":"AAIA,OAAO,KAAK,EAAE,SAAS,EAAE,MAAM,mBAAmB,CAAC;AACnD,OAAO,KAAK,EAAE,oBAAoB,EAAE,MAAM,qBAAqB,CAAC;AAEhE,MAAM,MAAM,mBAAmB,CAAC,KAAK,GAAG,SAAS,EAAE,SAAS,GAAG,KAAK,IAAI,oBAAoB,CACxF,KAAK,EACL,SAAS,CACZ,CAAC;AAEF;;;;;;;;GAQG;AACH,eAAO,MAAM,iBAAiB,GAAI,SAAS,GAAG,SAAS,EAAE,0CAKtD,mBAAmB,CAAC,SAAS,EAAE,SAAS,CAAC;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;CAe3C,CAAC"}

package/dist/hooks/portfolio/useFetchPortfolio.js

@@ -1,81 +1,33 @@
-import { useAppAlert } from "../../contexts/appAlertContext/useAppAlert.js";
 import { useAxios } from "../useAxios.js";
+import { useEntityQuery } from "../useEntityQuery.js";
+import { missingWorkspaceError } from "../../api/entityQuery.js";
 import { getPortfolio } from "../../api/portfolio.js";
-import { useEffect } from "react";
-import { useQuery } from "@tanstack/react-query";
 //#region src/hooks/portfolio/useFetchPortfolio.ts
-var defaultQueryOptions = {
-	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 });
-*   ```
+* 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.
 *
-* 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`.
 */
-var useFetchPortfolio = ({ id, workspace, queryOptions = defaultQueryOptions }) => {
+var useFetchPortfolio = ({ id, workspace, select, queryOptions }) => {
 	const { api } = useAxios();
-	const { showAlert } = useAppAlert();
 	const queryKey = [
 		"portfolio",
 		id,
 		workspace
 	];
-	const query = useQuery({
-		queryKey,
-		queryFn: async () => {
-			return (await getPortfolio(api, id, workspace)).portfolio;
-		},
-		...queryOptions ?? {}
-	});
-	useEffect(() => {
-		if (!query.error) return;
-		showAlert({
-			severity: "error",
-			message: query.error.message
-		});
-	}, [query.error, showAlert]);
 	return {
-		...query,
+		...useEntityQuery({
+			queryKey,
+			fetchEntity: (signal) => getPortfolio(api, id, workspace, signal),
+			select,
+			enabled: Boolean(id),
+			configError: workspace ? void 0 : missingWorkspaceError("useFetchPortfolio"),
+			queryOptions
+		}),
 		queryKey
 	};
 };

package/dist/hooks/portfolio/useFetchPortfolio.js.map

@@ -1 +1 @@
-{"version":3,"file":"useFetchPortfolio.js","names":[],"sources":["../../../src/hooks/portfolio/useFetchPortfolio.ts"],"sourcesContent":["import { useEffect } from \"react\";\nimport { useQuery } from \"@tanstack/react-query\";\n\nimport { useAxios } from \"@/hooks/useAxios\";\nimport { useAppAlert } from \"@/contexts/appAlertContext/useAppAlert\";\nimport type { Portfolio } from \"@/types/portfolio\";\nimport { getPortfolio } from \"@/api/portfolio\";\nimport type { EntityQueryOptions, FetchEntityParams } from \"@/types/entityQuery\";\n\nexport type FetchPortfolioProps<TData = Portfolio, TSelected = TData> = FetchEntityParams<TData, TSelected>;\n\nconst defaultQueryOptions: EntityQueryOptions<Portfolio> = {\n    refetchOnMount: \"always\",\n    staleTime: 0,\n    gcTime: 0\n}\n\n/**\n * useFetchPortfolio\n *\n * Data-fetching hook built on TanStack Query to retrieve a single portfolio by ID.\n *\n * It also:\n * - builds a stable React Query `queryKey` that can be reused by mutation hooks for cache invalidation\n * - triggers an error alert via `useAppAlert` whenever `query.error` is present\n *\n * Important notes:\n * - Always returns a single `Portfolio` object.\n *\n * Parameters (FetchPortfolioProps):\n * @param {string} id\n *   Portfolio identifier (required).\n *\n * @param {string} workspace\n *   Workspace the portfolio belongs to (required by `getPortfolio`).\n *\n * @param {EntityQueryOptions<Portfolio>} [queryOptions=defaultQueryOptions]\n *   TanStack Query options passed through to `useQuery` (e.g., enabled, staleTime, gcTime, etc.).\n *\n * Returns:\n * @returns {object}\n *   TanStack Query's `query` object extended with:\n *   - `queryKey`: the cache key used by React Query\n *\n * Tip:\n * - The returned `queryKey` can be reused by mutation hooks for cache invalidation:\n *   ```ts\n *   const fetch = useFetchPortfolio({ id: \"pf-123\", workspace: \"ws-1\" });\n *   usePortfolioMutations({ queryKey: fetch.queryKey });\n *   ```\n *\n * Example:\n * ```ts\n * const { data, isLoading } = useFetchPortfolio({\n *   id: \"pf-123\",\n *   workspace: \"ws-1\",\n * });\n * // data -> Portfolio\n * ```\n */\nexport const useFetchPortfolio = ({ id, workspace, queryOptions = defaultQueryOptions }: FetchPortfolioProps) => {\n\n    const { api } = useAxios();\n    const { showAlert } = useAppAlert();\n\n    const queryKey = [\n        \"portfolio\",\n        id,\n        workspace\n    ];\n\n    const query = useQuery<Portfolio>({\n        queryKey,\n        queryFn: async () => {\n            const response = await getPortfolio(api, id, workspace);\n            return response.portfolio;\n        },\n        ...queryOptions ?? {}\n    });\n\n    useEffect(() => {\n        if (!query.error) return;\n\n        showAlert({\n            severity: \"error\",\n            message: query.error.message,\n        });\n    }, [query.error, showAlert]);\n\n    return {\n        ...query,\n        queryKey,\n    };\n};\n"],"mappings":";;;;;;AAWA,IAAM,sBAAqD;CACvD,gBAAgB;CAChB,WAAW;CACX,QAAQ;AACZ;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;AA6CA,IAAa,qBAAqB,EAAE,IAAI,WAAW,eAAe,0BAA+C;CAE7G,MAAM,EAAE,QAAQ,SAAS;CACzB,MAAM,EAAE,cAAc,YAAY;CAElC,MAAM,WAAW;EACb;EACA;EACA;CACJ;CAEA,MAAM,QAAQ,SAAoB;EAC9B;EACA,SAAS,YAAY;GAEjB,QAAO,MADgB,aAAa,KAAK,IAAI,SAAS,EAAA,CACtC;EACpB;EACA,GAAG,gBAAgB,CAAC;CACxB,CAAC;CAED,gBAAgB;EACZ,IAAI,CAAC,MAAM,OAAO;EAElB,UAAU;GACN,UAAU;GACV,SAAS,MAAM,MAAM;EACzB,CAAC;CACL,GAAG,CAAC,MAAM,OAAO,SAAS,CAAC;CAE3B,OAAO;EACH,GAAG;EACH;CACJ;AACJ"}
+{"version":3,"file":"useFetchPortfolio.js","names":[],"sources":["../../../src/hooks/portfolio/useFetchPortfolio.ts"],"sourcesContent":["import { useAxios } from \"@/hooks/useAxios\";\nimport { useEntityQuery } from \"@/hooks/useEntityQuery\";\nimport { missingWorkspaceError } from \"@/api/entityQuery\";\nimport { getPortfolio } from \"@/api/portfolio\";\nimport type { Portfolio } from \"@/types/portfolio\";\nimport type { FetchEntityByIdProps } from \"@/types/entityQuery\";\n\nexport type FetchPortfolioProps<TData = Portfolio, TSelected = TData> = FetchEntityByIdProps<\n    TData,\n    TSelected\n>;\n\n/**\n * useFetchPortfolio\n *\n * Fetches one portfolio; `data` is the portfolio, or whatever `select` makes of it. Idle while\n * `id` is empty; fails loudly, without a request, while `workspace` is. A failure is shown as an error alert.\n *\n * @param {FetchPortfolioProps} props - `id`, `workspace`, `select` and TanStack `queryOptions`.\n * @returns {object} The `useQuery` result, plus `queryKey`.\n */\nexport const useFetchPortfolio = <TSelected = Portfolio>({\n    id,\n    workspace,\n    select,\n    queryOptions,\n}: FetchPortfolioProps<Portfolio, TSelected>) => {\n    const { api } = useAxios();\n\n    const queryKey = [\"portfolio\", id, workspace];\n\n    const query = useEntityQuery<Portfolio, TSelected>({\n        queryKey,\n        fetchEntity: (signal) => getPortfolio(api, id, workspace, signal),\n        select,\n        enabled: Boolean(id),\n        configError: workspace ? undefined : missingWorkspaceError(\"useFetchPortfolio\"),\n        queryOptions,\n    });\n\n    return { ...query, queryKey };\n};\n"],"mappings":";;;;;;;;;;;;;;AAqBA,IAAa,qBAA4C,EACrD,IACA,WACA,QACA,mBAC6C;CAC7C,MAAM,EAAE,QAAQ,SAAS;CAEzB,MAAM,WAAW;EAAC;EAAa;EAAI;CAAS;CAW5C,OAAO;EAAE,GATK,eAAqC;GAC/C;GACA,cAAc,WAAW,aAAa,KAAK,IAAI,WAAW,MAAM;GAChE;GACA,SAAS,QAAQ,EAAE;GACnB,aAAa,YAAY,KAAA,IAAY,sBAAsB,mBAAmB;GAC9E;EACJ,CAEY;EAAO;CAAS;AAChC"}

package/dist/hooks/portfolio/useFetchPortfolios.d.ts

@@ -1,60 +1,21 @@
-import { type UseInfiniteQueryOptions, type QueryKey } from "@tanstack/react-query";
-import type { FetchEntitiesParams } from "../../types/entityQuery.d.ts";
 import type { Portfolio, PortfolioListResponse } from "../../types/portfolio.d.ts";
-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;
-};
+import type { FetchEntitiesProps, ListQueryProps, ListCache } from "../../types/entityQuery.d.ts";
+/** The query cache of `useFetchPortfolios`, for typing `setQueryData`. */
+export type PortfoliosCache = ListCache<PortfolioListResponse>;
+export type FetchPortfoliosProps<TData = Portfolio[]> = ListQueryProps & FetchEntitiesProps<Portfolio, TData, PortfolioListResponse>;
 /**
- * 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
+ * useFetchPortfolios
  *
- * Example:
- * ```ts
- * const { query } = useFetchInfinitePortfolios({
- *   filters: [{ field: "workspace", value: "ws-1" }],
- *   pageSize: 20,
- * });
+ * Lists portfolios 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`.
  *
- * // Flat list of all fetched portfolios
- * const portfolios = query.data ?? [];
- * ```
+ * @param {FetchPortfoliosProps} props - Filters (one must be `workspace`), order,
+ *   projection, page size, `select`, `fetchAllPages` and TanStack `queryOptions`.
+ * @returns {object} `query` (the `useInfiniteQuery` result) and `queryKey`.
  */
-export declare function useFetchPortfolios({ filters, order, projection, pageSize, queryOptions }: FetchInfinitePortfolioProps): {
-    query: import("@tanstack/react-query").UseInfiniteQueryResult<Portfolio[], Error>;
+export declare function useFetchPortfolios<TData = Portfolio[]>({ filters, order, projection, pageSize, select, fetchAllPages, queryOptions, }: FetchPortfoliosProps<TData>): {
+    query: import("@tanstack/react-query").UseInfiniteQueryResult<TData, Error>;
     queryKey: unknown[];
 };
-export {};
 //# sourceMappingURL=useFetchPortfolios.d.ts.map

package/dist/hooks/portfolio/useFetchPortfolios.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"useFetchPortfolios.d.ts","sourceRoot":"","sources":["../../../src/hooks/portfolio/useFetchPortfolios.ts"],"names":[],"mappings":"AACA,OAAO,EAAoB,KAAK,uBAAuB,EAAE,KAAK,QAAQ,EAAE,MAAM,uBAAuB,CAAC;AAItG,OAAO,KAAK,EAAE,mBAAmB,EAAE,MAAM,qBAAqB,CAAC;AAC/D,OAAO,KAAK,EAAE,SAAS,EAAE,qBAAqB,EAAE,MAAM,mBAAmB,CAAC;AAG1E,KAAK,SAAS,GAAG,MAAM,GAAG,IAAI,CAAC;AAE/B,KAAK,eAAe,CAAC,KAAK,IAAI,IAAI,CAC9B,uBAAuB,CAAC,qBAAqB,EAAE,KAAK,EAAE,KAAK,EAAE,QAAQ,EAAE,SAAS,CAAC,EACjF,UAAU,GAAG,SAAS,GAAG,kBAAkB,GAAG,kBAAkB,CACnE,CAAC;AAEF,MAAM,MAAM,2BAA2B,GAAG,mBAAmB,CAAC,SAAS,EAAE,EAAE,eAAe,CAAC,SAAS,EAAE,CAAC,CAAC,GAAG;IACvG,QAAQ,CAAC,EAAE,MAAM,CAAC;CACrB,CAAC;AAQF;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;GA6CG;AACH,wBAAgB,kBAAkB,CAAC,EAAE,OAAY,EAAE,KAAU,EAAE,UAAe,EAAE,QAAa,EAAE,YAAY,EAAE,EAAE,2BAA2B;;;EAoCzI"}
+{"version":3,"file":"useFetchPortfolios.d.ts","sourceRoot":"","sources":["../../../src/hooks/portfolio/useFetchPortfolios.ts"],"names":[],"mappings":"AAGA,OAAO,KAAK,EAAE,SAAS,EAAE,qBAAqB,EAAE,MAAM,mBAAmB,CAAC;AAC1E,OAAO,KAAK,EAAE,kBAAkB,EAAE,cAAc,EAAE,SAAS,EAAE,MAAM,qBAAqB,CAAC;AAQzF,0EAA0E;AAC1E,MAAM,MAAM,eAAe,GAAG,SAAS,CAAC,qBAAqB,CAAC,CAAC;AAE/D,MAAM,MAAM,oBAAoB,CAAC,KAAK,GAAG,SAAS,EAAE,IAAI,cAAc,GAClE,kBAAkB,CAAC,SAAS,EAAE,KAAK,EAAE,qBAAqB,CAAC,CAAC;AAEhE;;;;;;;;;;GAUG;AACH,wBAAgB,kBAAkB,CAAC,KAAK,GAAG,SAAS,EAAE,EAAE,EACpD,OAAY,EACZ,KAAU,EACV,UAAe,EACf,QAAa,EACb,MAAM,EACN,aAAqB,EACrB,YAAY,GACf,EAAE,oBAAoB,CAAC,KAAK,CAAC;;;EA4B7B"}

package/dist/hooks/portfolio/useFetchPortfolios.js

@@ -1,84 +1,42 @@
 import { useAxios } from "../useAxios.js";
-import { buildQueryKey, buildQueryObject } from "../../api/entityQuery.js";
+import { useEntityInfiniteQuery } from "../useEntityInfiniteQuery.js";
+import { buildQueryKey, buildQueryObject, hasWorkspaceFilter, missingWorkspaceError } from "../../api/entityQuery.js";
 import { listPortfolios } from "../../api/portfolio.js";
-import { useMemo } from "react";
-import { useInfiniteQuery } from "@tanstack/react-query";
 //#region src/hooks/portfolio/useFetchPortfolios.ts
-var defaultQueryOptions = {
-	refetchOnMount: "always",
-	staleTime: 0,
-	gcTime: 0
-};
 /**
-* useFetchInfinitePortfolios
+* useFetchPortfolios
 *
-* Data-fetching hook built on TanStack Query's `useInfiniteQuery` to retrieve
-* portfolios with cursor-based pagination.
+* Lists portfolios 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`.
 *
-* 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 ?? [];
-* ```
+* @param {FetchPortfoliosProps} props - Filters (one must be `workspace`), order,
+*   projection, page size, `select`, `fetchAllPages` and TanStack `queryOptions`.
+* @returns {object} `query` (the `useInfiniteQuery` result) and `queryKey`.
 */
-function useFetchPortfolios({ filters = [], order = [], projection = "", pageSize = 10, queryOptions }) {
+function useFetchPortfolios({ filters = [], order = [], projection = "", pageSize = 10, select, fetchAllPages = false, queryOptions }) {
 	const { api } = useAxios();
-	const queryKey = buildQueryKey(["portfolios"], filters);
-	const mergedQueryOptions = useMemo(() => ({
-		...defaultQueryOptions,
-		...queryOptions ?? {}
-	}), [queryOptions]);
+	const queryKey = buildQueryKey(["portfolios"], filters, {
+		order,
+		projection,
+		pageSize,
+		fetchAllPages
+	});
 	return {
-		query: useInfiniteQuery({
+		query: useEntityInfiniteQuery({
 			queryKey,
-			initialPageParam: null,
-			getNextPageParam: (lastPage) => lastPage.next_page_token ?? void 0,
-			queryFn: async ({ pageParam }) => {
-				const queryFilter = buildQueryObject({
-					filters,
-					order,
-					projection,
-					pageSize,
-					pageToken: pageParam ?? void 0
-				});
-				return await listPortfolios(api, queryFilter);
-			},
-			select: (data) => data.pages.flatMap((p) => p.portfolios),
-			...mergedQueryOptions
+			itemsKey: "portfolios",
+			fetchPage: (pageToken, signal) => listPortfolios(api, buildQueryObject({
+				filters,
+				order,
+				projection,
+				pageSize,
+				pageToken
+			}), signal),
+			select,
+			fetchAllPages,
+			configError: hasWorkspaceFilter(filters) ? void 0 : missingWorkspaceError("useFetchPortfolios"),
+			queryOptions
 		}),
 		queryKey
 	};

package/dist/hooks/portfolio/useFetchPortfolios.js.map

@@ -1 +1 @@
-{"version":3,"file":"useFetchPortfolios.js","names":[],"sources":["../../../src/hooks/portfolio/useFetchPortfolios.ts"],"sourcesContent":["import { useMemo } from \"react\";\nimport { useInfiniteQuery, type UseInfiniteQueryOptions, type QueryKey } from \"@tanstack/react-query\";\n\nimport { useAxios } from \"@/hooks/useAxios\";\nimport { listPortfolios } from \"@/api/portfolio\";\nimport type { FetchEntitiesParams } from \"@/types/entityQuery\";\nimport type { Portfolio, PortfolioListResponse } from \"@/types/portfolio\";\nimport { buildQueryKey, buildQueryObject } from \"@/api/entityQuery\";\n\ntype PageToken = string | null;\n\ntype InfiniteOptions<TData> = Omit<\n    UseInfiniteQueryOptions<PortfolioListResponse, Error, TData, QueryKey, PageToken>,\n    \"queryKey\" | \"queryFn\" | \"initialPageParam\" | \"getNextPageParam\"\n>;\n\nexport type FetchInfinitePortfolioProps = FetchEntitiesParams<Portfolio[], InfiniteOptions<Portfolio[]>> & {\n    pageSize?: number;\n};\n\nconst defaultQueryOptions: InfiniteOptions<Portfolio[]> = {\n    refetchOnMount: \"always\",\n    staleTime: 0,\n    gcTime: 0,\n};\n\n/**\n * useFetchInfinitePortfolios\n *\n * Data-fetching hook built on TanStack Query's `useInfiniteQuery` to retrieve\n * portfolios with cursor-based pagination.\n *\n * It also:\n * - flattens all pages into a single `Portfolio[]` via `select`\n *\n * Important notes:\n * - `query.data` returns a flat `Portfolio[]` (all pages merged).\n *\n * Parameters (FetchInfinitePortfolioProps):\n * @param {FilterClause[]} [filters=[]]\n *   Filters applied to every page request. Must include a `workspace` filter.\n *\n * @param {string[]} [order=[]]\n *   Sorting applied to every page request.\n *\n * @param {string} [projection=\"\"]\n *   Single field to project: `\"field\"` returns only that field (others come back null),\n *   `\"-field\"` returns every field except that one. One field only — lists 500. Omitted when empty.\n *\n * @param {number} [pageSize=10]\n *   Number of portfolios to fetch per page.\n *\n * @param {InfiniteOptions<Portfolio[]>} [queryOptions]\n *   TanStack Query options passed through to `useInfiniteQuery`\n *   (e.g., enabled, staleTime, gcTime, etc.).\n *\n * Returns:\n * @returns {object}\n *   - `query`: the full `useInfiniteQuery` result (data, isLoading, hasNextPage, fetchNextPage, etc.)\n *   - `queryKey`: the cache key used by React Query\n *\n * Example:\n * ```ts\n * const { query } = useFetchInfinitePortfolios({\n *   filters: [{ field: \"workspace\", value: \"ws-1\" }],\n *   pageSize: 20,\n * });\n *\n * // Flat list of all fetched portfolios\n * const portfolios = query.data ?? [];\n * ```\n */\nexport function useFetchPortfolios({ filters = [], order = [], projection = \"\", pageSize = 10, queryOptions }: FetchInfinitePortfolioProps) {\n    const { api } = useAxios();\n\n    const queryKey = buildQueryKey([\"portfolios\"], filters);\n\n    const mergedQueryOptions = useMemo<InfiniteOptions<Portfolio[]>>(() => ({\n        ...defaultQueryOptions,\n        ...(queryOptions ?? {}),\n    }), [queryOptions]);\n\n    const query = useInfiniteQuery<PortfolioListResponse, Error, Portfolio[], QueryKey, PageToken>({\n        queryKey,\n        initialPageParam: null,\n        getNextPageParam: (lastPage) => lastPage.next_page_token ?? undefined,\n\n        queryFn: async ({ pageParam }) => {\n            const queryFilter = buildQueryObject({\n                filters,\n                order,\n                projection,\n                pageSize,\n                pageToken: pageParam ?? undefined,\n            });\n\n            return await listPortfolios(api, queryFilter);\n        },\n\n        select: (data) => data.pages.flatMap((p) => p.portfolios),\n\n        ...mergedQueryOptions,\n    });\n\n    return {\n        query,\n        queryKey,\n    };\n}"],"mappings":";;;;;;AAoBA,IAAM,sBAAoD;CACtD,gBAAgB;CAChB,WAAW;CACX,QAAQ;AACZ;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;AAgDA,SAAgB,mBAAmB,EAAE,UAAU,CAAC,GAAG,QAAQ,CAAC,GAAG,aAAa,IAAI,WAAW,IAAI,gBAA6C;CACxI,MAAM,EAAE,QAAQ,SAAS;CAEzB,MAAM,WAAW,cAAc,CAAC,YAAY,GAAG,OAAO;CAEtD,MAAM,qBAAqB,eAA6C;EACpE,GAAG;EACH,GAAI,gBAAgB,CAAC;CACzB,IAAI,CAAC,YAAY,CAAC;CAwBlB,OAAO;EACH,OAvBU,iBAAiF;GAC3F;GACA,kBAAkB;GAClB,mBAAmB,aAAa,SAAS,mBAAmB,KAAA;GAE5D,SAAS,OAAO,EAAE,gBAAgB;IAC9B,MAAM,cAAc,iBAAiB;KACjC;KACA;KACA;KACA;KACA,WAAW,aAAa,KAAA;IAC5B,CAAC;IAED,OAAO,MAAM,eAAe,KAAK,WAAW;GAChD;GAEA,SAAS,SAAS,KAAK,MAAM,SAAS,MAAM,EAAE,UAAU;GAExD,GAAG;EACP,CAGI;EACA;CACJ;AACJ"}
+{"version":3,"file":"useFetchPortfolios.js","names":[],"sources":["../../../src/hooks/portfolio/useFetchPortfolios.ts"],"sourcesContent":["import { useAxios } from \"@/hooks/useAxios\";\nimport { useEntityInfiniteQuery } from \"@/hooks/useEntityInfiniteQuery\";\nimport { listPortfolios } from \"@/api/portfolio\";\nimport type { Portfolio, PortfolioListResponse } from \"@/types/portfolio\";\nimport type { FetchEntitiesProps, ListQueryProps, ListCache } from \"@/types/entityQuery\";\nimport {\n    buildQueryKey,\n    buildQueryObject,\n    hasWorkspaceFilter,\n    missingWorkspaceError,\n} from \"@/api/entityQuery\";\n\n/** The query cache of `useFetchPortfolios`, for typing `setQueryData`. */\nexport type PortfoliosCache = ListCache<PortfolioListResponse>;\n\nexport type FetchPortfoliosProps<TData = Portfolio[]> = ListQueryProps &\n    FetchEntitiesProps<Portfolio, TData, PortfolioListResponse>;\n\n/**\n * useFetchPortfolios\n *\n * Lists portfolios with cursor pagination; `query.data` is every loaded page merged, or\n * whatever `select` makes of it. Paging, `select`, `fetchAllPages` and the\n * missing-workspace error behave as in `useFetchDatastores`.\n *\n * @param {FetchPortfoliosProps} props - Filters (one must be `workspace`), order,\n *   projection, page size, `select`, `fetchAllPages` and TanStack `queryOptions`.\n * @returns {object} `query` (the `useInfiniteQuery` result) and `queryKey`.\n */\nexport function useFetchPortfolios<TData = Portfolio[]>({\n    filters = [],\n    order = [],\n    projection = \"\",\n    pageSize = 10,\n    select,\n    fetchAllPages = false,\n    queryOptions,\n}: FetchPortfoliosProps<TData>) {\n    const { api } = useAxios();\n\n    const queryKey = buildQueryKey([\"portfolios\"], filters, {\n        order,\n        projection,\n        pageSize,\n        fetchAllPages,\n    });\n\n    const query = useEntityInfiniteQuery<PortfolioListResponse, \"portfolios\", TData>({\n        queryKey,\n        itemsKey: \"portfolios\",\n        fetchPage: (pageToken, signal) =>\n            listPortfolios(\n                api,\n                buildQueryObject({ filters, order, projection, pageSize, pageToken }),\n                signal,\n            ),\n        select,\n        fetchAllPages,\n        configError: hasWorkspaceFilter(filters)\n            ? undefined\n            : missingWorkspaceError(\"useFetchPortfolios\"),\n        queryOptions,\n    });\n\n    return { query, queryKey };\n}\n"],"mappings":";;;;;;;;;;;;;;;;AA6BA,SAAgB,mBAAwC,EACpD,UAAU,CAAC,GACX,QAAQ,CAAC,GACT,aAAa,IACb,WAAW,IACX,QACA,gBAAgB,OAChB,gBAC4B;CAC5B,MAAM,EAAE,QAAQ,SAAS;CAEzB,MAAM,WAAW,cAAc,CAAC,YAAY,GAAG,SAAS;EACpD;EACA;EACA;EACA;CACJ,CAAC;CAmBD,OAAO;EAAE,OAjBK,uBAAmE;GAC7E;GACA,UAAU;GACV,YAAY,WAAW,WACnB,eACI,KACA,iBAAiB;IAAE;IAAS;IAAO;IAAY;IAAU;GAAU,CAAC,GACpE,MACJ;GACJ;GACA;GACA,aAAa,mBAAmB,OAAO,IACjC,KAAA,IACA,sBAAsB,oBAAoB;GAChD;EACJ,CAES;EAAO;CAAS;AAC7B"}

package/dist/hooks/portfolio/usePortfolioMutations.d.ts

@@ -47,26 +47,26 @@ type UsePortfolioMutationsProps = {
  *   - 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)
+ *   - error message: "Unable to create the portfolio. Please 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)
+ *   - error message: "Unable to 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)
+ *   - error message: "Unable to 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>
+ *  - `remove`: UseMutationResult<DeletedEntity, Error, DeletePortfolioProps, unknown>
  *
  * Each mutation includes standard TanStack Query helpers:
  * - `mutate(variables, options?)`
@@ -79,7 +79,7 @@ type UsePortfolioMutationsProps = {
  * ```ts
  * const { create, update, remove } = usePortfolioMutations({ queryKey: ["portfolio"] });
  *
-  * // Create (minimal example - other Security fields omitted for brevity)
+ * // Create (minimal example - other Security fields omitted for brevity)
  * create.mutate({
  *   data: {
  *     name: "My Portfolio",
@@ -163,9 +163,9 @@ type UsePortfolioMutationsProps = {
  * ```
  */
 export declare const usePortfolioMutations: ({ queryKey }: UsePortfolioMutationsProps) => {
-    create: import("@tanstack/react-query").UseMutationResult<Portfolio, unknown, CreatePortfolioProps, unknown>;
-    update: import("@tanstack/react-query").UseMutationResult<Portfolio, unknown, UpdatePortfolioProps, unknown>;
-    remove: import("@tanstack/react-query").UseMutationResult<Portfolio, unknown, DeletePortfolioProps, unknown>;
+    create: import("@tanstack/react-query").UseMutationResult<Portfolio, Error, CreatePortfolioProps, unknown>;
+    update: import("@tanstack/react-query").UseMutationResult<Portfolio, Error, UpdatePortfolioProps, unknown>;
+    remove: import("@tanstack/react-query").UseMutationResult<import("../..").DeletedEntity, Error, DeletePortfolioProps, unknown>;
 };
 export {};
 //# sourceMappingURL=usePortfolioMutations.d.ts.map

package/dist/hooks/portfolio/usePortfolioMutations.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"usePortfolioMutations.d.ts","sourceRoot":"","sources":["../../../src/hooks/portfolio/usePortfolioMutations.ts"],"names":[],"mappings":"AAIA,OAAO,KAAK,EAAE,SAAS,EAAE,MAAM,mBAAmB,CAAC;AAGnD,KAAK,oBAAoB,GAAG;IACxB,IAAI,EAAE,OAAO,CAAC,SAAS,CAAC,CAAC;CAC5B,CAAC;AAEF,KAAK,oBAAoB,GAAG;IACxB,EAAE,EAAE,MAAM,CAAC;IACX,IAAI,EAAE,OAAO,CAAC,SAAS,CAAC,CAAC;CAC5B,CAAC;AAEF,KAAK,oBAAoB,GAAG;IACxB,EAAE,EAAE,MAAM,CAAC;IACX,SAAS,EAAE,MAAM,CAAC;CACrB,CAAC;AAEF,KAAK,0BAA0B,GAAG;IAC9B,QAAQ,CAAC,EAAE,OAAO,EAAE,CAAC;CACxB,CAAC;AAKF;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;GAoJG;AAEH,eAAO,MAAM,qBAAqB,GAAI,cAAc,0BAA0B;;;;CAuE7E,CAAC"}
+{"version":3,"file":"usePortfolioMutations.d.ts","sourceRoot":"","sources":["../../../src/hooks/portfolio/usePortfolioMutations.ts"],"names":[],"mappings":"AAEA,OAAO,KAAK,EAAE,SAAS,EAAE,MAAM,mBAAmB,CAAC;AAGnD,KAAK,oBAAoB,GAAG;IACxB,IAAI,EAAE,OAAO,CAAC,SAAS,CAAC,CAAC;CAC5B,CAAC;AAEF,KAAK,oBAAoB,GAAG;IACxB,EAAE,EAAE,MAAM,CAAC;IACX,IAAI,EAAE,OAAO,CAAC,SAAS,CAAC,CAAC;CAC5B,CAAC;AAEF,KAAK,oBAAoB,GAAG;IACxB,EAAE,EAAE,MAAM,CAAC;IACX,SAAS,EAAE,MAAM,CAAC;CACrB,CAAC;AAEF,KAAK,0BAA0B,GAAG;IAC9B,QAAQ,CAAC,EAAE,OAAO,EAAE,CAAC;CACxB,CAAC;AAEF;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;GAoJG;AAEH,eAAO,MAAM,qBAAqB,GAAI,cAAc,0BAA0B;;;;CA0B7E,CAAC"}