@everysk/apps-sdk 0.1.0-beta.0

package/dist/hooks/portfolio/usePortfolioMutations.js

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

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

@@ -0,0 +1 @@
+{"version":3,"file":"usePortfolioMutations.js","names":[],"sources":["../../../src/hooks/portfolio/usePortfolioMutations.ts"],"sourcesContent":["import { useMutation, useQueryClient } from \"@tanstack/react-query\";\n\nimport { useAxios } from \"@/hooks/useAxios\";\nimport { useAppAlert } from \"@/contexts/appAlertContext/useAppAlert\";\nimport type { Portfolio } from \"@/types/portfolio\";\nimport { deletePortfolio, createPortfolio, updatePortfolio } from \"@/api/portfolio\";\n\ntype CreatePortfolioProps = {\n    data: Partial<Portfolio>;\n};\n\ntype UpdatePortfolioProps = {\n    id: string;\n    data: Partial<Portfolio>;\n};\n\ntype DeletePortfolioProps = {\n    id: string;\n    workspace: string;\n};\n\ntype UsePortfolioMutationsProps = {\n    queryKey?: unknown[];\n};\n\nconst getErrorMessage = (err: unknown, fallback: string) =>\n    err instanceof Error && err.message ? err.message : fallback;\n\n/**\n * usePortfolioMutations\n *\n * Mutation hook built on TanStack Query to perform Portfolio write operations:\n * - create a portfolio (POST)\n * - update a portfolio (PUT)\n * - delete a portfolio (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 `useFetchPortfolio`.\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 `deletePortfolio(api, id, workspace)`\n *   expects it as a query param.\n *\n * Parameters (UsePortfolioMutationsProps):\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., portfolio list/detail) so UI data is refreshed automatically after a write.\n *\n *  Tip:\n *  - If you're using `useFetchPortfolio`, you can pass its returned `queryKey` directly:\n *    `const fetch = useFetchPortfolio(...);`\n *    `usePortfolioMutations({ queryKey: fetch.queryKey });`\n *\n * Mutations:\n * - `create`:\n *   - mutationFn: `createPortfolio(api, data)`\n *   - variables: `{ data: Partial<Portfolio> }`\n *   - success message: \"Portfolio created successfully.\"\n *   - error message: \"We couldn't create the portfolio. Please review your inputs and try again.\" (fallback)\n *\n * - `update`:\n *   - mutationFn: `updatePortfolio(api, id, data)`\n *   - variables: `{ id: string; data: Partial<Portfolio> }`\n *   - success message: \"Portfolio updated successfully.\"\n *   - error message: \"We couldn't update the portfolio. Please try again.\" (fallback)\n *\n * - `remove`:\n *   - mutationFn: `deletePortfolio(api, id, workspace)`\n *   - variables: `{ id: string; workspace: string }`\n *   - success message: \"Portfolio deleted successfully.\"\n *   - error message: \"We couldn't delete the portfolio. 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<Portfolio, Error, CreatePortfolioProps, unknown>\n *  - `update`: UseMutationResult<Portfolio, Error, UpdatePortfolioProps, unknown>\n *  - `remove`: UseMutationResult<Portfolio, Error, DeletePortfolioProps, 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 portfolio list query after mutations:\n * ```ts\n * const { create, update, remove } = usePortfolioMutations({ queryKey: [\"portfolio\"] });\n *\n  * // Create (minimal example - other Security fields omitted for brevity)\n * create.mutate({\n *   data: {\n *     name: \"My Portfolio\",\n *     description: \"Test portfolio\",\n *     base_currency: \"USD\",\n *     date: \"2026-01-08\",\n *     workspace: \"ws-1\",\n *     securities: [\n *       {\n *         id: \"sec-1\",\n *         ticker: \"AAPL\",\n *         symbol: \"AAPL\",\n *         name: \"Apple Inc.\",\n *         currency: \"USD\",\n *         quantity: 10,\n *         market_price: 200,\n *         market_value: 2000,\n *         market_value_in_base: 2000,\n *         fx_rate: 1,\n *         instrument_type: \"Equity\",\n *         instrument_class: \"Equity\",\n *         asset_class: \"Equity\",\n *         exchange: \"NASDAQ\",\n *         status: \"active\",\n *         // Other fields are nullable in the Security type and can be omitted here for documentation purposes.\n *       } as Security,\n *     ],\n *   }\n * });\n *\n * // Update (partial)\n * update.mutate({\n *   id: \"pf-123\",\n *   data: {\n *     name: \"Renamed Portfolio\",\n *     tags: [\"tag-1\", \"tag-2\"],\n *     check_securities: true,\n *   }\n * });\n *\n * // Delete\n * remove.mutate({ id: \"pf-123\", workspace: \"ws-1\" });\n * ```\n *\n * 2) Using async/await with `mutateAsync`:\n * ```ts\n * const { create } = usePortfolioMutations({ queryKey: [\"portfolio\"] });\n *\n * await create.mutateAsync({\n *   data: {\n *     name: \"My Portfolio\",\n *     base_currency: \"USD\",\n *     date: \"2026-01-08\",\n *     workspace: \"ws-1\",\n *     securities: [],\n *   }\n * });\n * ```\n *\n * 3) Without cache invalidation (no queryKey):\n * ```ts\n * const { update } = usePortfolioMutations({});\n *\n * update.mutate({\n *   id: \"pf-123\",\n *   data: { description: \"Updated description\" }\n * });\n * // Mutation still runs and alerts are shown, but cached queries are not invalidated.\n * ```\n *\n * 4) Using `useFetchPortfolio` queryKey for automatic invalidation:\n * ```ts\n * const fetch = useFetchPortfolio({\n *   id: null,\n *   filters: [{ field: \"workspace\", value: \"ws-1\" }],\n * });\n *\n * const { remove } = usePortfolioMutations({ queryKey: fetch.queryKey });\n *\n * await remove.mutateAsync({ id: \"pf-123\", workspace: \"ws-1\" });\n * ```\n */\n\nexport const usePortfolioMutations = ({ queryKey }: UsePortfolioMutationsProps) => {\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 }: CreatePortfolioProps) => createPortfolio(api, data),\n        onSuccess: async () => {\n            await invalidate();\n            showAlert({\n                severity: \"success\",\n                message: \"Portfolio created successfully.\",\n            });\n        },\n        onError: (err: unknown) => {\n            showAlert({\n                severity: \"error\",\n                message: getErrorMessage(\n                    err,\n                    \"We couldn't create the portfolio. Please review your inputs and try again.\"\n                ),\n            });\n        },\n    });\n\n    const update = useMutation({\n        mutationFn: async ({ id, data }: UpdatePortfolioProps) => updatePortfolio(api, id, data),\n        onSuccess: async () => {\n            await invalidate();\n            showAlert({\n                severity: \"success\",\n                message: \"Portfolio updated successfully.\",\n            });\n        },\n        onError: (err: unknown) => {\n            showAlert({\n                severity: \"error\",\n                message: getErrorMessage(\n                    err,\n                    \"We couldn't update the portfolio. Please try again.\"\n                ),\n            });\n        },\n    });\n\n    const remove = useMutation({\n        mutationFn: async ({ id, workspace }: DeletePortfolioProps) => deletePortfolio(api, id, workspace),\n        onSuccess: async () => {\n            await invalidate();\n            showAlert({\n                severity: \"success\",\n                message: \"Portfolio deleted successfully.\",\n            });\n        },\n        onError: (err: unknown) => {\n            showAlert({\n                severity: \"error\",\n                message: getErrorMessage(\n                    err,\n                    \"We couldn't delete the portfolio. 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;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;AAwJxD,IAAa,yBAAyB,EAAE,eAA2C;CAC/E,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,WAAiC,gBAAgB,KAAK,IAAI;GAC/E,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,4EACJ;IACJ,CAAC;GACL;EACJ,CA0CS;EAAQ,QAxCF,YAAY;GACvB,YAAY,OAAO,EAAE,IAAI,WAAiC,gBAAgB,KAAK,IAAI,IAAI;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,qDACJ;IACJ,CAAC;GACL;EACJ,CAsBiB;EAAQ,QApBV,YAAY;GACvB,YAAY,OAAO,EAAE,IAAI,gBAAsC,gBAAgB,KAAK,IAAI,SAAS;GACjG,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,qDACJ;IACJ,CAAC;GACL;EACJ,CAEyB;CAAO;AACpC"}

package/dist/hooks/profile/useFetchProfile.d.ts

@@ -0,0 +1,206 @@
+import type { Profile } from "../../types/profile.d.ts";
+import type { EntityQueryOptions } from "../../types/entityQuery.d.ts";
+export type FetchProfileProps<TData = Profile, TSelected = TData> = {
+    queryOptions?: EntityQueryOptions<TData, TSelected>;
+    /**
+     * Served instead of calling the API. Pass `DEV_PROFILE` while running the dev server,
+     * where `/api/profile` has no session to resolve.
+     */
+    fallback?: Profile;
+};
+/**
+ * useFetchProfile
+ *
+ * Data-fetching hook built on TanStack Query to retrieve the profile of the logged user. It takes
+ * no identifier: the API resolves the user from the session.
+ *
+ * It also:
+ * - builds a stable React Query `queryKey`, shared by every consumer, so the profile is fetched
+ *   once per session and read from cache afterwards
+ * - triggers an error alert via `useAppAlert` whenever `query.error` is present
+ *
+ * Parameters (FetchProfileProps):
+ * @param queryOptions
+ *   TanStack Query options passed through to `useQuery` (e.g., enabled, staleTime, gcTime, etc.).
+ *   Defaults keep the profile cached for the whole session.
+ * @param fallback
+ *   Served instead of calling the API. `/api/profile` only resolves in production, so an app
+ *   running the dev server passes `DEV_PROFILE` here:
+ *   `useFetchProfile({ fallback: import.meta.env.DEV ? DEV_PROFILE : undefined })`.
+ *   The SDK cannot make that choice itself — see `getProfile`.
+ *
+ * Returns:
+ * @returns {object}
+ *   TanStack Query's `query` object extended with:
+ *   - `queryKey`: the cache key used by React Query
+ *
+ * Example:
+ * ```ts
+ * const { data, isPending } = useFetchProfile();
+ * // data -> Profile
+ * ```
+ */
+export declare const useFetchProfile: ({ queryOptions, fallback, }?: FetchProfileProps) => {
+    queryKey: string[];
+    data: Profile;
+    error: Error;
+    isError: true;
+    isPending: false;
+    isLoading: false;
+    isLoadingError: false;
+    isRefetchError: true;
+    isSuccess: false;
+    isPlaceholderData: false;
+    status: "error";
+    dataUpdatedAt: number;
+    errorUpdatedAt: number;
+    failureCount: number;
+    failureReason: Error | null;
+    errorUpdateCount: number;
+    isFetched: boolean;
+    isFetchedAfterMount: boolean;
+    isFetching: boolean;
+    isInitialLoading: boolean;
+    isPaused: boolean;
+    isRefetching: boolean;
+    isStale: boolean;
+    isEnabled: boolean;
+    refetch: (options?: import("@tanstack/query-core").RefetchOptions) => Promise<import("@tanstack/query-core").QueryObserverResult<Profile, Error>>;
+    fetchStatus: import("@tanstack/query-core").FetchStatus;
+} | {
+    queryKey: string[];
+    data: Profile;
+    error: null;
+    isError: false;
+    isPending: false;
+    isLoading: false;
+    isLoadingError: false;
+    isRefetchError: false;
+    isSuccess: true;
+    isPlaceholderData: false;
+    status: "success";
+    dataUpdatedAt: number;
+    errorUpdatedAt: number;
+    failureCount: number;
+    failureReason: Error | null;
+    errorUpdateCount: number;
+    isFetched: boolean;
+    isFetchedAfterMount: boolean;
+    isFetching: boolean;
+    isInitialLoading: boolean;
+    isPaused: boolean;
+    isRefetching: boolean;
+    isStale: boolean;
+    isEnabled: boolean;
+    refetch: (options?: import("@tanstack/query-core").RefetchOptions) => Promise<import("@tanstack/query-core").QueryObserverResult<Profile, Error>>;
+    fetchStatus: import("@tanstack/query-core").FetchStatus;
+} | {
+    queryKey: string[];
+    data: undefined;
+    error: Error;
+    isError: true;
+    isPending: false;
+    isLoading: false;
+    isLoadingError: true;
+    isRefetchError: false;
+    isSuccess: false;
+    isPlaceholderData: false;
+    status: "error";
+    dataUpdatedAt: number;
+    errorUpdatedAt: number;
+    failureCount: number;
+    failureReason: Error | null;
+    errorUpdateCount: number;
+    isFetched: boolean;
+    isFetchedAfterMount: boolean;
+    isFetching: boolean;
+    isInitialLoading: boolean;
+    isPaused: boolean;
+    isRefetching: boolean;
+    isStale: boolean;
+    isEnabled: boolean;
+    refetch: (options?: import("@tanstack/query-core").RefetchOptions) => Promise<import("@tanstack/query-core").QueryObserverResult<Profile, Error>>;
+    fetchStatus: import("@tanstack/query-core").FetchStatus;
+} | {
+    queryKey: string[];
+    data: undefined;
+    error: null;
+    isError: false;
+    isPending: true;
+    isLoading: true;
+    isLoadingError: false;
+    isRefetchError: false;
+    isSuccess: false;
+    isPlaceholderData: false;
+    status: "pending";
+    dataUpdatedAt: number;
+    errorUpdatedAt: number;
+    failureCount: number;
+    failureReason: Error | null;
+    errorUpdateCount: number;
+    isFetched: boolean;
+    isFetchedAfterMount: boolean;
+    isFetching: boolean;
+    isInitialLoading: boolean;
+    isPaused: boolean;
+    isRefetching: boolean;
+    isStale: boolean;
+    isEnabled: boolean;
+    refetch: (options?: import("@tanstack/query-core").RefetchOptions) => Promise<import("@tanstack/query-core").QueryObserverResult<Profile, Error>>;
+    fetchStatus: import("@tanstack/query-core").FetchStatus;
+} | {
+    queryKey: string[];
+    data: undefined;
+    error: null;
+    isError: false;
+    isPending: true;
+    isLoadingError: false;
+    isRefetchError: false;
+    isSuccess: false;
+    isPlaceholderData: false;
+    status: "pending";
+    dataUpdatedAt: number;
+    errorUpdatedAt: number;
+    failureCount: number;
+    failureReason: Error | null;
+    errorUpdateCount: number;
+    isFetched: boolean;
+    isFetchedAfterMount: boolean;
+    isFetching: boolean;
+    isLoading: boolean;
+    isInitialLoading: boolean;
+    isPaused: boolean;
+    isRefetching: boolean;
+    isStale: boolean;
+    isEnabled: boolean;
+    refetch: (options?: import("@tanstack/query-core").RefetchOptions) => Promise<import("@tanstack/query-core").QueryObserverResult<Profile, Error>>;
+    fetchStatus: import("@tanstack/query-core").FetchStatus;
+} | {
+    queryKey: string[];
+    data: Profile;
+    isError: false;
+    error: null;
+    isPending: false;
+    isLoading: false;
+    isLoadingError: false;
+    isRefetchError: false;
+    isSuccess: true;
+    isPlaceholderData: true;
+    status: "success";
+    dataUpdatedAt: number;
+    errorUpdatedAt: number;
+    failureCount: number;
+    failureReason: Error | null;
+    errorUpdateCount: number;
+    isFetched: boolean;
+    isFetchedAfterMount: boolean;
+    isFetching: boolean;
+    isInitialLoading: boolean;
+    isPaused: boolean;
+    isRefetching: boolean;
+    isStale: boolean;
+    isEnabled: boolean;
+    refetch: (options?: import("@tanstack/query-core").RefetchOptions) => Promise<import("@tanstack/query-core").QueryObserverResult<Profile, Error>>;
+    fetchStatus: import("@tanstack/query-core").FetchStatus;
+};
+//# sourceMappingURL=useFetchProfile.d.ts.map

package/dist/hooks/profile/useFetchProfile.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"useFetchProfile.d.ts","sourceRoot":"","sources":["../../../src/hooks/profile/useFetchProfile.ts"],"names":[],"mappings":"AAMA,OAAO,KAAK,EAAE,OAAO,EAAE,MAAM,iBAAiB,CAAC;AAE/C,OAAO,KAAK,EAAE,kBAAkB,EAAE,MAAM,qBAAqB,CAAC;AAE9D,MAAM,MAAM,iBAAiB,CAAC,KAAK,GAAG,OAAO,EAAE,SAAS,GAAG,KAAK,IAAI;IAChE,YAAY,CAAC,EAAE,kBAAkB,CAAC,KAAK,EAAE,SAAS,CAAC,CAAC;IACpD;;;OAGG;IACH,QAAQ,CAAC,EAAE,OAAO,CAAC;CACtB,CAAC;AAWF;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;GA+BG;AACH,eAAO,MAAM,eAAe,GAAI,8BAG7B,iBAAsB;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;CA6BxB,CAAC"}

package/dist/hooks/profile/useFetchProfile.js

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

package/dist/hooks/profile/useFetchProfile.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"useFetchProfile.js","names":[],"sources":["../../../src/hooks/profile/useFetchProfile.ts"],"sourcesContent":["import { useEffect } from \"react\";\n\nimport { useQuery } from \"@tanstack/react-query\";\n\nimport { useAxios } from \"@/hooks/useAxios\";\nimport { useAppAlert } from \"@/contexts/appAlertContext/useAppAlert\";\nimport type { Profile } from \"@/types/profile\";\nimport { getProfile } from \"@/api/profile\";\nimport type { EntityQueryOptions } from \"@/types/entityQuery\";\n\nexport type FetchProfileProps<TData = Profile, TSelected = TData> = {\n    queryOptions?: EntityQueryOptions<TData, TSelected>;\n    /**\n     * Served instead of calling the API. Pass `DEV_PROFILE` while running the dev server,\n     * where `/api/profile` has no session to resolve.\n     */\n    fallback?: Profile;\n};\n\n// The logged user's profile does not change during a session, so it is fetched once and kept —\n// unlike the entity hooks (staleTime/gcTime 0, refetch on every mount), which read data the\n// platform keeps changing.\nconst defaultQueryOptions: EntityQueryOptions<Profile> = {\n    staleTime: Infinity,\n    refetchOnMount: false,\n    refetchOnWindowFocus: false,\n};\n\n/**\n * useFetchProfile\n *\n * Data-fetching hook built on TanStack Query to retrieve the profile of the logged user. It takes\n * no identifier: the API resolves the user from the session.\n *\n * It also:\n * - builds a stable React Query `queryKey`, shared by every consumer, so the profile is fetched\n *   once per session and read from cache afterwards\n * - triggers an error alert via `useAppAlert` whenever `query.error` is present\n *\n * Parameters (FetchProfileProps):\n * @param queryOptions\n *   TanStack Query options passed through to `useQuery` (e.g., enabled, staleTime, gcTime, etc.).\n *   Defaults keep the profile cached for the whole session.\n * @param fallback\n *   Served instead of calling the API. `/api/profile` only resolves in production, so an app\n *   running the dev server passes `DEV_PROFILE` here:\n *   `useFetchProfile({ fallback: import.meta.env.DEV ? DEV_PROFILE : undefined })`.\n *   The SDK cannot make that choice itself — see `getProfile`.\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 * Example:\n * ```ts\n * const { data, isPending } = useFetchProfile();\n * // data -> Profile\n * ```\n */\nexport const useFetchProfile = ({\n    queryOptions = defaultQueryOptions,\n    fallback,\n}: FetchProfileProps = {}) => {\n\n    const { api } = useAxios();\n    const { showAlert } = useAppAlert();\n\n    const queryKey = [\"profile\"];\n\n    const query = useQuery<Profile>({\n        queryKey,\n        queryFn: async () => {\n            const profile = await getProfile(api, fallback);\n            return profile;\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":";;;;;;AAsBA,IAAM,sBAAmD;CACrD,WAAW;CACX,gBAAgB;CAChB,sBAAsB;AAC1B;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;AAkCA,IAAa,mBAAmB,EAC5B,eAAe,qBACf,aACmB,CAAC,MAAM;CAE1B,MAAM,EAAE,QAAQ,SAAS;CACzB,MAAM,EAAE,cAAc,YAAY;CAElC,MAAM,WAAW,CAAC,SAAS;CAE3B,MAAM,QAAQ,SAAkB;EAC5B;EACA,SAAS,YAAY;GAEjB,OAAO,MADe,WAAW,KAAK,QAAQ;EAElD;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"}

package/dist/hooks/useAxios.d.ts

@@ -0,0 +1,40 @@
+import { type AxiosInstance } from "axios";
+/**
+ * useAxios
+ *
+ * Axios client hook that returns a memoized `AxiosInstance` configured with:
+ * - `baseURL` derived from:
+ *   - the optional `url` parameter, or
+ *   - the relative `/api` by default. In dev, `/api` is proxied to `EVERYSK_API_URL`
+ *     (see `vite/serverProxy.ts`); in production it is served behind the same host.
+ *
+ * Request behavior:
+ * - Sets the `X-Everysk-Source` header on every request, identifying the app to the API as
+ *   `everysk-user-app-<appId>` (the `appId` from `useAppConfig()`). When there is no app id (dev,
+ *   where the host page hasn't injected `window.APP_ID`), it falls back to
+ *   `everysk-user-app-development`.
+ * - Registers a request interceptor that, for `GET` and `DELETE` requests, attempts to parse
+ *   `config.params.query` (expected to be a JSON string) and extract a `workspace` filter from it.
+ * - If a `workspace` value is found, it is injected into `config.params.workspace`.
+ *
+ * Lifecycle / cleanup:
+ * - The interceptor is attached in `useEffect` and ejected on cleanup to avoid stacking interceptors
+ *   across re-renders or unmount/mount cycles.
+ *
+ * Notes:
+ * - `params.query` parsing is best-effort. Invalid JSON is ignored.
+ * - This hook assumes a query structure containing `filters`, where the workspace filter is identified by
+ *   `filter[0] === "workspace"`.
+ *
+ * Parameters:
+ * @param {string | null} [url=null]
+ *  Optional base URL override. If omitted/null, defaults to the relative `/api`.
+ *
+ * Return value:
+ * @returns {{ api: AxiosInstance }}
+ *  Returns an object containing the configured Axios instance.
+ */
+export declare const useAxios: (url?: string | null) => {
+    api: AxiosInstance;
+};
+//# sourceMappingURL=useAxios.d.ts.map

package/dist/hooks/useAxios.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"useAxios.d.ts","sourceRoot":"","sources":["../../src/hooks/useAxios.ts"],"names":[],"mappings":"AAEA,OAAc,EAAE,KAAK,aAAa,EAAmC,MAAM,OAAO,CAAC;AAMnF;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;GAkCG;AAEH,eAAO,MAAM,QAAQ,GAAI,MAAK,MAAM,GAAG,IAAW;;CAqDjD,CAAC"}

package/dist/hooks/useAxios.js

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

package/dist/hooks/useAxios.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"useAxios.js","names":[],"sources":["../../src/hooks/useAxios.ts"],"sourcesContent":["import { useEffect, useMemo, useRef } from \"react\";\n\nimport axios, { type AxiosInstance, type InternalAxiosRequestConfig } from \"axios\";\n\nimport type { AnyRecord } from \"@/types/anyRecord\";\nimport type { FilterExpression } from \"@/types/entityQuery\";\nimport { useAppConfig } from \"@/contexts/appConfigContext/useAppConfig\";\n\n/**\n * useAxios\n *\n * Axios client hook that returns a memoized `AxiosInstance` configured with:\n * - `baseURL` derived from:\n *   - the optional `url` parameter, or\n *   - the relative `/api` by default. In dev, `/api` is proxied to `EVERYSK_API_URL`\n *     (see `vite/serverProxy.ts`); in production it is served behind the same host.\n *\n * Request behavior:\n * - Sets the `X-Everysk-Source` header on every request, identifying the app to the API as\n *   `everysk-user-app-<appId>` (the `appId` from `useAppConfig()`). When there is no app id (dev,\n *   where the host page hasn't injected `window.APP_ID`), it falls back to\n *   `everysk-user-app-development`.\n * - Registers a request interceptor that, for `GET` and `DELETE` requests, attempts to parse\n *   `config.params.query` (expected to be a JSON string) and extract a `workspace` filter from it.\n * - If a `workspace` value is found, it is injected into `config.params.workspace`.\n *\n * Lifecycle / cleanup:\n * - The interceptor is attached in `useEffect` and ejected on cleanup to avoid stacking interceptors\n *   across re-renders or unmount/mount cycles.\n *\n * Notes:\n * - `params.query` parsing is best-effort. Invalid JSON is ignored.\n * - This hook assumes a query structure containing `filters`, where the workspace filter is identified by\n *   `filter[0] === \"workspace\"`.\n *\n * Parameters:\n * @param {string | null} [url=null]\n *  Optional base URL override. If omitted/null, defaults to the relative `/api`.\n *\n * Return value:\n * @returns {{ api: AxiosInstance }}\n *  Returns an object containing the configured Axios instance.\n */\n\nexport const useAxios = (url: string | null = null) => {\n\n    const reqInterceptorId = useRef<number | null>(null);\n    const { appId } = useAppConfig();\n\n    const source = appId ? `everysk-user-app-${appId}` : \"everysk-user-app-development\";\n\n    const api: AxiosInstance = useMemo(() => {\n        const instance = axios.create({ baseURL: url ?? \"/api\" });\n        instance.defaults.headers.common[\"X-Everysk-Source\"] = source;\n        return instance;\n    }, [url, source]);\n\n    useEffect(() => {\n        reqInterceptorId.current = api.interceptors.request.use(\n            (config: InternalAxiosRequestConfig<AnyRecord>) => {\n                const method = (config.method ?? \"\").toLowerCase();\n\n                if (method === \"get\" || method === \"delete\") {\n                    const params = (config.params ?? {}) as Record<string, unknown>;\n\n                    try {\n                        const rawQuery = params.query;\n                        const queryObj = typeof rawQuery === \"string\" ? JSON.parse(rawQuery) : null;\n\n                        const workspaceFilter = queryObj?.filters?.find(\n                            (filter: FilterExpression) => filter?.[0] === \"workspace\"\n                        );\n\n                        const workspace =\n                            Array.isArray(workspaceFilter) ? workspaceFilter[workspaceFilter.length - 1] : null;\n\n                        if (workspace) {\n                            config.params = { ...params, workspace };\n                        }\n                    } catch {\n                        // ignore invalid query JSON\n                    }\n                }\n\n                return config;\n            }\n        );\n\n        return () => {\n            if (reqInterceptorId.current != null) {\n                api.interceptors.request.eject(reqInterceptorId.current);\n            }\n            reqInterceptorId.current = null;\n        };\n    }, [api]);\n\n    return { api };\n};\n"],"mappings":";;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;AA4CA,IAAa,YAAY,MAAqB,SAAS;CAEnD,MAAM,mBAAmB,OAAsB,IAAI;CACnD,MAAM,EAAE,UAAU,aAAa;CAE/B,MAAM,SAAS,QAAQ,oBAAoB,UAAU;CAErD,MAAM,MAAqB,cAAc;EACrC,MAAM,WAAW,MAAM,OAAO,EAAE,SAAS,OAAO,OAAO,CAAC;EACxD,SAAS,SAAS,QAAQ,OAAO,sBAAsB;EACvD,OAAO;CACX,GAAG,CAAC,KAAK,MAAM,CAAC;CAEhB,gBAAgB;EACZ,iBAAiB,UAAU,IAAI,aAAa,QAAQ,KAC/C,WAAkD;GAC/C,MAAM,UAAU,OAAO,UAAU,GAAA,CAAI,YAAY;GAEjD,IAAI,WAAW,SAAS,WAAW,UAAU;IACzC,MAAM,SAAU,OAAO,UAAU,CAAC;IAElC,IAAI;KACA,MAAM,WAAW,OAAO;KAGxB,MAAM,mBAFW,OAAO,aAAa,WAAW,KAAK,MAAM,QAAQ,IAAI,KAAA,EAErC,SAAS,MACtC,WAA6B,SAAS,OAAO,WAClD;KAEA,MAAM,YACF,MAAM,QAAQ,eAAe,IAAI,gBAAgB,gBAAgB,SAAS,KAAK;KAEnF,IAAI,WACA,OAAO,SAAS;MAAE,GAAG;MAAQ;KAAU;IAE/C,QAAQ,CAER;GACJ;GAEA,OAAO;EACX,CACJ;EAEA,aAAa;GACT,IAAI,iBAAiB,WAAW,MAC5B,IAAI,aAAa,QAAQ,MAAM,iBAAiB,OAAO;GAE3D,iBAAiB,UAAU;EAC/B;CACJ,GAAG,CAAC,GAAG,CAAC;CAER,OAAO,EAAE,IAAI;AACjB"}