@everysk/apps-sdk 0.1.0-beta.0

package/dist/hooks/datastore/useFetchDatastore.js

@@ -0,0 +1,85 @@
+import { useAppAlert } from "../../contexts/appAlertContext/useAppAlert.js";
+import { useAxios } from "../useAxios.js";
+import { getDatastore } from "../../api/datastore.js";
+import { tableToObjects } from "../../lib/datastoreTable.js";
+import { useEffect } from "react";
+import { useQuery } from "@tanstack/react-query";
+//#region src/hooks/datastore/useFetchDatastore.ts
+var defaultQueryOptions = {
+	refetchOnMount: "always",
+	staleTime: 0,
+	gcTime: 0
+};
+/**
+* useFetchDatastore
+*
+* Data-fetching hook built on TanStack Query to retrieve a single datastore by ID.
+*
+* It also:
+* - triggers an error alert via `useAppAlert` whenever `query.error` is present
+*
+* Important notes:
+* - Returns a `DatastoreWithRows` object: the full `Datastore` shape with `data`
+*   replaced by `AnyRecord[]` (rows transformed via `tableToObjects`).
+*
+* Parameters (FetchDatastoreProps):
+* @param {string} id
+*   Datastore identifier (required).
+*
+* @param {string} workspace
+*   Workspace the datastore belongs to (required by `getDatastore`).
+*
+* @param {EntityQueryOptions<DatastoreWithRows>} [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
+*
+* Example:
+* ```ts
+* const { data, isLoading } = useFetchDatastore({
+*   id: "abc123",
+*   workspace: "my-workspace",
+* });
+* // data -> DatastoreWithRows (datastore metadata + rows as AnyRecord[])
+* // data.name -> "my-datastore"
+* // data.data -> [{ datastoreId: "abc123", col1: "value", ... }]
+* ```
+*/
+var useFetchDatastore = ({ id, workspace, queryOptions = defaultQueryOptions }) => {
+	const { api } = useAxios();
+	const { showAlert } = useAppAlert();
+	const queryKey = [
+		"datastore",
+		id,
+		workspace
+	];
+	const query = useQuery({
+		queryKey,
+		queryFn: async () => {
+			const datastore = await getDatastore(api, id, workspace);
+			return {
+				...datastore,
+				data: tableToObjects(datastore.id, datastore.data?.[0], datastore.data)
+			};
+		},
+		...queryOptions ?? {}
+	});
+	useEffect(() => {
+		if (!query.error) return;
+		showAlert({
+			severity: "error",
+			message: query.error.message
+		});
+	}, [query.error, showAlert]);
+	return {
+		...query,
+		queryKey
+	};
+};
+//#endregion
+export { useFetchDatastore };
+
+//# sourceMappingURL=useFetchDatastore.js.map

package/dist/hooks/datastore/useFetchDatastore.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"useFetchDatastore.js","names":[],"sources":["../../../src/hooks/datastore/useFetchDatastore.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 { getDatastore } from \"@/api/datastore\";\nimport { tableToObjects } from \"@/lib/datastoreTable\";\nimport type { DatastoreWithRows } from \"@/types/datastore\";\nimport type { EntityQueryOptions, FetchEntityParams } from \"@/types/entityQuery\";\n\nexport type FetchDatastoreProps = FetchEntityParams<DatastoreWithRows>;\n\nconst defaultQueryOptions: EntityQueryOptions<DatastoreWithRows> = {\n    refetchOnMount: \"always\",\n    staleTime: 0,\n    gcTime: 0,\n};\n\n/**\n * useFetchDatastore\n *\n * Data-fetching hook built on TanStack Query to retrieve a single datastore by ID.\n *\n * It also:\n * - triggers an error alert via `useAppAlert` whenever `query.error` is present\n *\n * Important notes:\n * - Returns a `DatastoreWithRows` object: the full `Datastore` shape with `data`\n *   replaced by `AnyRecord[]` (rows transformed via `tableToObjects`).\n *\n * Parameters (FetchDatastoreProps):\n * @param {string} id\n *   Datastore identifier (required).\n *\n * @param {string} workspace\n *   Workspace the datastore belongs to (required by `getDatastore`).\n *\n * @param {EntityQueryOptions<DatastoreWithRows>} [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 * Example:\n * ```ts\n * const { data, isLoading } = useFetchDatastore({\n *   id: \"abc123\",\n *   workspace: \"my-workspace\",\n * });\n * // data -> DatastoreWithRows (datastore metadata + rows as AnyRecord[])\n * // data.name -> \"my-datastore\"\n * // data.data -> [{ datastoreId: \"abc123\", col1: \"value\", ... }]\n * ```\n */\nexport const useFetchDatastore = ({ id, workspace, queryOptions = defaultQueryOptions }: FetchDatastoreProps) => {\n\n    const { api } = useAxios();\n    const { showAlert } = useAppAlert();\n\n    const queryKey = [\"datastore\", id, workspace];\n\n    const query = useQuery<DatastoreWithRows>({\n        queryKey,\n        queryFn: async () => {\n            const datastore = await getDatastore(api, id, workspace);\n\n            return {\n                ...datastore,\n                data: tableToObjects(\n                    datastore.id,\n                    datastore.data?.[0] as string[],\n                    datastore.data\n                ),\n            };\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":";;;;;;;AAaA,IAAM,sBAA6D;CAC/D,gBAAgB;CAChB,WAAW;CACX,QAAQ;AACZ;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;AAwCA,IAAa,qBAAqB,EAAE,IAAI,WAAW,eAAe,0BAA+C;CAE7G,MAAM,EAAE,QAAQ,SAAS;CACzB,MAAM,EAAE,cAAc,YAAY;CAElC,MAAM,WAAW;EAAC;EAAa;EAAI;CAAS;CAE5C,MAAM,QAAQ,SAA4B;EACtC;EACA,SAAS,YAAY;GACjB,MAAM,YAAY,MAAM,aAAa,KAAK,IAAI,SAAS;GAEvD,OAAO;IACH,GAAG;IACH,MAAM,eACF,UAAU,IACV,UAAU,OAAO,IACjB,UAAU,IACd;GACJ;EACJ;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/datastore/useFetchDatastores.d.ts

@@ -0,0 +1,70 @@
+import { type UseInfiniteQueryOptions, type QueryKey } from "@tanstack/react-query";
+import type { DatastoreWithRows } from "../../types/datastore.d.ts";
+import type { FetchEntitiesParams, EntityDefaultResponse } from "../../types/entityQuery.d.ts";
+type PageToken = string | null;
+type InfiniteOptions<TData> = Omit<UseInfiniteQueryOptions<DatastoreQueryPage, Error, TData, QueryKey, PageToken>, "queryKey" | "queryFn" | "initialPageParam" | "getNextPageParam">;
+export type DatastoreQueryPage = EntityDefaultResponse & {
+    datastores: DatastoreWithRows[];
+};
+export type FetchInfiniteDatastoreProps = FetchEntitiesParams<DatastoreWithRows[], InfiniteOptions<DatastoreWithRows[]>> & {
+    pageSize?: number;
+};
+/**
+ * useFetchDatastores
+ *
+ * Data-fetching hook built on TanStack Query's `useInfiniteQuery` to retrieve
+ * datastores with cursor-based pagination.
+ *
+ * It also:
+ * - flattens all pages into a single `DatastoreWithRows[]` via `select`
+ * - exposes `actions` for cache management
+ * - exposes `events` for ag-Grid integration
+ *
+ * Important notes:
+ * - `query.data` returns a flat `DatastoreWithRows[]` (all pages merged).
+ * - Each item retains the full `Datastore` shape, with `data` replaced by `AnyRecord[]` (rows transformed via `tableToObjects`).
+ *
+ * Parameters (FetchInfiniteDatastoreProps):
+ * @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 datastores to fetch per page.
+ *
+ * @param {InfiniteOptions<DatastoreWithRows[]>} [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
+ *   - `events.handleFetchIfGridEmptyOrNearEnd(gridApi)`: triggers next page fetch when the ag-Grid is empty or near the end of the list
+ *
+ * Example:
+ * ```ts
+ * const { query, events } = useFetchDatastores({
+ *   filters: [{ field: "workspace", value: "ws-1" }],
+ *   pageSize: 20,
+ * });
+ *
+ * // Flat list of all fetched datastores with transformed rows
+ * const datastores = query.data ?? [];
+ *
+ * // Load next page when grid is near end
+ * <AgGridReact onBodyScroll={() => events.handleFetchIfGridEmptyOrNearEnd(gridApi)} />
+ * ```
+ */
+export declare function useFetchDatastores({ filters, order, projection, pageSize, queryOptions }: FetchInfiniteDatastoreProps): {
+    query: import("@tanstack/react-query").UseInfiniteQueryResult<DatastoreWithRows[], Error>;
+    queryKey: unknown[];
+};
+export {};
+//# sourceMappingURL=useFetchDatastores.d.ts.map

package/dist/hooks/datastore/useFetchDatastores.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"useFetchDatastores.d.ts","sourceRoot":"","sources":["../../../src/hooks/datastore/useFetchDatastores.ts"],"names":[],"mappings":"AAEA,OAAO,EAAoB,KAAK,uBAAuB,EAAE,KAAK,QAAQ,EAAE,MAAM,uBAAuB,CAAC;AAQtG,OAAO,KAAK,EAAoC,iBAAiB,EAAE,MAAM,mBAAmB,CAAC;AAC7F,OAAO,KAAK,EAAE,mBAAmB,EAAE,qBAAqB,EAAE,MAAM,qBAAqB,CAAC;AAGtF,KAAK,SAAS,GAAG,MAAM,GAAG,IAAI,CAAC;AAE/B,KAAK,eAAe,CAAC,KAAK,IAAI,IAAI,CAC9B,uBAAuB,CAAC,kBAAkB,EAAE,KAAK,EAAE,KAAK,EAAE,QAAQ,EAAE,SAAS,CAAC,EAC9E,UAAU,GAAG,SAAS,GAAG,kBAAkB,GAAG,kBAAkB,CACnE,CAAC;AAGF,MAAM,MAAM,kBAAkB,GAAG,qBAAqB,GAAG;IACrD,UAAU,EAAE,iBAAiB,EAAE,CAAC;CACnC,CAAC;AAEF,MAAM,MAAM,2BAA2B,GAAG,mBAAmB,CAAC,iBAAiB,EAAE,EAAE,eAAe,CAAC,iBAAiB,EAAE,CAAC,CAAC,GAAG;IACvH,QAAQ,CAAC,EAAE,MAAM,CAAC;CACrB,CAAC;AAQF;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;GAoDG;AACH,wBAAgB,kBAAkB,CAAC,EAAE,OAAY,EAAE,KAAU,EAAE,UAAe,EAAE,QAAa,EAAE,YAAY,EAAE,EAAE,2BAA2B;;;EAwEzI"}

package/dist/hooks/datastore/useFetchDatastores.js

@@ -0,0 +1,105 @@
+import { useAxios } from "../useAxios.js";
+import { buildQueryKey, buildQueryObject } from "../../api/entityQuery.js";
+import { listDatastores } from "../../api/datastore.js";
+import { tableToObjects } from "../../lib/datastoreTable.js";
+import { useMemo } from "react";
+import { useInfiniteQuery } from "@tanstack/react-query";
+//#region src/hooks/datastore/useFetchDatastores.ts
+var defaultQueryOptions = {
+	refetchOnMount: "always",
+	staleTime: 0,
+	gcTime: 0
+};
+/**
+* useFetchDatastores
+*
+* Data-fetching hook built on TanStack Query's `useInfiniteQuery` to retrieve
+* datastores with cursor-based pagination.
+*
+* It also:
+* - flattens all pages into a single `DatastoreWithRows[]` via `select`
+* - exposes `actions` for cache management
+* - exposes `events` for ag-Grid integration
+*
+* Important notes:
+* - `query.data` returns a flat `DatastoreWithRows[]` (all pages merged).
+* - Each item retains the full `Datastore` shape, with `data` replaced by `AnyRecord[]` (rows transformed via `tableToObjects`).
+*
+* Parameters (FetchInfiniteDatastoreProps):
+* @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 datastores to fetch per page.
+*
+* @param {InfiniteOptions<DatastoreWithRows[]>} [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
+*   - `events.handleFetchIfGridEmptyOrNearEnd(gridApi)`: triggers next page fetch when the ag-Grid is empty or near the end of the list
+*
+* Example:
+* ```ts
+* const { query, events } = useFetchDatastores({
+*   filters: [{ field: "workspace", value: "ws-1" }],
+*   pageSize: 20,
+* });
+*
+* // Flat list of all fetched datastores with transformed rows
+* const datastores = query.data ?? [];
+*
+* // Load next page when grid is near end
+* <AgGridReact onBodyScroll={() => events.handleFetchIfGridEmptyOrNearEnd(gridApi)} />
+* ```
+*/
+function useFetchDatastores({ filters = [], order = [], projection = "", pageSize = 10, queryOptions }) {
+	const { api } = useAxios();
+	const queryKey = buildQueryKey(["datastores"], filters);
+	const mergedQueryOptions = useMemo(() => ({
+		...defaultQueryOptions,
+		...queryOptions ?? {}
+	}), [queryOptions]);
+	return {
+		query: useInfiniteQuery({
+			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
+				});
+				const response = await listDatastores(api, queryFilter);
+				const nested = response.datastores.map((datastore) => ({
+					...datastore,
+					data: tableToObjects(datastore.id, datastore.data?.[0], datastore.data)
+				}));
+				return {
+					next_page_token: response.next_page_token,
+					datastores: nested
+				};
+			},
+			select: (data) => data.pages.flatMap((p) => p.datastores),
+			...mergedQueryOptions
+		}),
+		queryKey
+	};
+}
+//#endregion
+export { useFetchDatastores };
+
+//# sourceMappingURL=useFetchDatastores.js.map

package/dist/hooks/datastore/useFetchDatastores.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"useFetchDatastores.js","names":[],"sources":["../../../src/hooks/datastore/useFetchDatastores.ts"],"sourcesContent":["//import { useCallback, useMemo, useRef } from \"react\";\nimport { useMemo } from \"react\";\nimport { useInfiniteQuery, type UseInfiniteQueryOptions, type QueryKey } from \"@tanstack/react-query\";\n\n//import type { GridApi } from \"ag-grid-community\";\n\nimport { useAxios } from \"@/hooks/useAxios\";\nimport { tableToObjects } from \"@/lib/datastoreTable\";\nimport { listDatastores } from \"@/api/datastore\";\n\nimport type { Datastore, DatastoreListResponse, DatastoreWithRows } from \"@/types/datastore\";\nimport type { FetchEntitiesParams, EntityDefaultResponse } from \"@/types/entityQuery\";\nimport { buildQueryKey, buildQueryObject } from \"@/api/entityQuery\";\n\ntype PageToken = string | null;\n\ntype InfiniteOptions<TData> = Omit<\n    UseInfiniteQueryOptions<DatastoreQueryPage, Error, TData, QueryKey, PageToken>,\n    \"queryKey\" | \"queryFn\" | \"initialPageParam\" | \"getNextPageParam\"\n>;\n\n\nexport type DatastoreQueryPage = EntityDefaultResponse & {\n    datastores: DatastoreWithRows[];\n};\n\nexport type FetchInfiniteDatastoreProps = FetchEntitiesParams<DatastoreWithRows[], InfiniteOptions<DatastoreWithRows[]>> & {\n    pageSize?: number;\n};\n\nconst defaultQueryOptions: InfiniteOptions<DatastoreWithRows[]> = {\n    refetchOnMount: \"always\",\n    staleTime: 0,\n    gcTime: 0,\n};\n\n/**\n * useFetchDatastores\n *\n * Data-fetching hook built on TanStack Query's `useInfiniteQuery` to retrieve\n * datastores with cursor-based pagination.\n *\n * It also:\n * - flattens all pages into a single `DatastoreWithRows[]` via `select`\n * - exposes `actions` for cache management\n * - exposes `events` for ag-Grid integration\n *\n * Important notes:\n * - `query.data` returns a flat `DatastoreWithRows[]` (all pages merged).\n * - Each item retains the full `Datastore` shape, with `data` replaced by `AnyRecord[]` (rows transformed via `tableToObjects`).\n *\n * Parameters (FetchInfiniteDatastoreProps):\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 datastores to fetch per page.\n *\n * @param {InfiniteOptions<DatastoreWithRows[]>} [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 *   - `events.handleFetchIfGridEmptyOrNearEnd(gridApi)`: triggers next page fetch when the ag-Grid is empty or near the end of the list\n *\n * Example:\n * ```ts\n * const { query, events } = useFetchDatastores({\n *   filters: [{ field: \"workspace\", value: \"ws-1\" }],\n *   pageSize: 20,\n * });\n *\n * // Flat list of all fetched datastores with transformed rows\n * const datastores = query.data ?? [];\n *\n * // Load next page when grid is near end\n * <AgGridReact onBodyScroll={() => events.handleFetchIfGridEmptyOrNearEnd(gridApi)} />\n * ```\n */\nexport function useFetchDatastores({ filters = [], order = [], projection = \"\", pageSize = 10, queryOptions }: FetchInfiniteDatastoreProps) {\n    const { api } = useAxios();\n\n    //const fetchingGuardRef = useRef(false);\n    const queryKey = buildQueryKey([\"datastores\"], filters);\n\n    const mergedQueryOptions = useMemo<InfiniteOptions<DatastoreWithRows[]>>(() => ({\n        ...defaultQueryOptions,\n        ...(queryOptions ?? {}),\n    }), [queryOptions]);\n\n    const query = useInfiniteQuery<DatastoreQueryPage, Error, DatastoreWithRows[], 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            const response: DatastoreListResponse = await listDatastores(api, queryFilter);\n\n            const nested: DatastoreWithRows[] = response.datastores.map((datastore: Datastore) => ({\n                ...datastore,\n                data: tableToObjects(\n                    datastore.id,\n                    datastore.data?.[0] as string[],\n                    datastore.data\n                ),\n            }));\n\n            return {\n                next_page_token: response.next_page_token,\n                datastores: nested,\n            };\n        },\n\n        select: (data) => data.pages.flatMap((p) => p.datastores),\n\n        ...mergedQueryOptions,\n    });\n\n    /*\n    const { hasNextPage, isFetchingNextPage, fetchNextPage } = query;\n    const handleFetchIfGridEmptyOrNearEnd = useCallback((gridApi: GridApi) => {\n        if (!hasNextPage || isFetchingNextPage || fetchingGuardRef.current) return;\n\n        const total = gridApi.getDisplayedRowCount();\n        const last = gridApi.getLastDisplayedRowIndex();\n\n        const isEmpty = total === 0 || last < 0;\n        const isNearEnd = !isEmpty && (total - 1 - last) <= 30;\n\n        if (!isEmpty && !isNearEnd) return;\n\n        fetchingGuardRef.current = true;\n        fetchNextPage().finally(() => {\n            fetchingGuardRef.current = false;\n        });\n    }, [hasNextPage, isFetchingNextPage, fetchNextPage]);\n    */\n\n    return {\n        query,\n        queryKey,\n        //events: { handleFetchIfGridEmptyOrNearEnd },\n    };\n}"],"mappings":";;;;;;;AA8BA,IAAM,sBAA4D;CAC9D,gBAAgB;CAChB,WAAW;CACX,QAAQ;AACZ;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;AAuDA,SAAgB,mBAAmB,EAAE,UAAU,CAAC,GAAG,QAAQ,CAAC,GAAG,aAAa,IAAI,WAAW,IAAI,gBAA6C;CACxI,MAAM,EAAE,QAAQ,SAAS;CAGzB,MAAM,WAAW,cAAc,CAAC,YAAY,GAAG,OAAO;CAEtD,MAAM,qBAAqB,eAAqD;EAC5E,GAAG;EACH,GAAI,gBAAgB,CAAC;CACzB,IAAI,CAAC,YAAY,CAAC;CA0DlB,OAAO;EACH,OAzDU,iBAAsF;GAChG;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,MAAM,WAAkC,MAAM,eAAe,KAAK,WAAW;IAE7E,MAAM,SAA8B,SAAS,WAAW,KAAK,eAA0B;KACnF,GAAG;KACH,MAAM,eACF,UAAU,IACV,UAAU,OAAO,IACjB,UAAU,IACd;IACJ,EAAE;IAEF,OAAO;KACH,iBAAiB,SAAS;KAC1B,YAAY;IAChB;GACJ;GAEA,SAAS,SAAS,KAAK,MAAM,SAAS,MAAM,EAAE,UAAU;GAExD,GAAG;EACP,CAuBI;EACA;CAEJ;AACJ"}

package/dist/hooks/file/useFetchFile.d.ts

@@ -0,0 +1,212 @@
+import type { EveryskFile } from "../../types/file.d.ts";
+import type { FetchEntityParams } from "../../types/entityQuery.d.ts";
+export type FetchFileProps<TData = EveryskFile, TSelected = TData> = FetchEntityParams<TData, TSelected>;
+/**
+ * useFetchFile
+ *
+ * Data-fetching hook built on TanStack Query to retrieve a single file by ID.
+ *
+ * It also:
+ * - builds a stable React Query `queryKey` that can be reused by mutation hooks for cache invalidation
+ * - triggers an error alert via `useAppAlert` whenever `query.error` is present
+ *
+ * Important notes:
+ * - Always returns a single `EveryskFile` object.
+ * - `EveryskFile.data` represents the file content and is expected to be a Base64-encoded string
+ *   when provided by the API (or when sending content through mutations).
+ *
+ * Parameters (FetchFileProps):
+ * @param {string} id
+ *   EveryskFile identifier (required).
+ *
+ * @param {string} workspace
+ *   Workspace the file belongs to (required by `getFile`).
+ *
+ * @param {EntityQueryOptions<any>} [queryOptions=defaultQueryOptions]
+ *   TanStack Query options passed through to `useQuery` (e.g., enabled, staleTime, gcTime, etc.).
+ *
+ * Returns:
+ * @returns {object}
+ *   TanStack Query's `query` object extended with:
+ *   - `queryKey`: the cache key used by React Query
+ *
+ * Tip:
+ * - The returned `queryKey` can be reused by mutation hooks for cache invalidation:
+ *   ```ts
+ *   const fetch = useFetchFile({ id: "file-123", workspace: "ws-1" });
+ *   useFileMutations({ queryKey: fetch.queryKey });
+ *   ```
+ *
+ * Example:
+ * ```ts
+ * const { data, isLoading } = useFetchFile({
+ *   id: "file-123",
+ *   workspace: "ws-1",
+ * });
+ * // data -> EveryskFile
+ * ```
+ */
+export declare const useFetchFile: ({ id, workspace, queryOptions }: FetchFileProps) => {
+    queryKey: string[];
+    data: EveryskFile;
+    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<EveryskFile, Error>>;
+    fetchStatus: import("@tanstack/query-core").FetchStatus;
+} | {
+    queryKey: string[];
+    data: EveryskFile;
+    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<EveryskFile, 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<EveryskFile, 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<EveryskFile, 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<EveryskFile, Error>>;
+    fetchStatus: import("@tanstack/query-core").FetchStatus;
+} | {
+    queryKey: string[];
+    data: EveryskFile;
+    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<EveryskFile, Error>>;
+    fetchStatus: import("@tanstack/query-core").FetchStatus;
+};
+//# sourceMappingURL=useFetchFile.d.ts.map

package/dist/hooks/file/useFetchFile.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"useFetchFile.d.ts","sourceRoot":"","sources":["../../../src/hooks/file/useFetchFile.ts"],"names":[],"mappings":"AAKA,OAAO,KAAK,EAAE,WAAW,EAAE,MAAM,cAAc,CAAC;AAGhD,OAAO,KAAK,EAAsB,iBAAiB,EAAE,MAAM,qBAAqB,CAAC;AAEjF,MAAM,MAAM,cAAc,CAAC,KAAK,GAAG,WAAW,EAAE,SAAS,GAAG,KAAK,IAAI,iBAAiB,CAAC,KAAK,EAAE,SAAS,CAAC,CAAC;AAQzG;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;GA4CG;AACH,eAAO,MAAM,YAAY,GAAI,iCAAuD,cAAc;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;CA6BjG,CAAC"}

package/dist/hooks/file/useFetchFile.js

@@ -0,0 +1,87 @@
+import { useAppAlert } from "../../contexts/appAlertContext/useAppAlert.js";
+import { useAxios } from "../useAxios.js";
+import { getFile } from "../../api/file.js";
+import { useEffect } from "react";
+import { useQuery } from "@tanstack/react-query";
+//#region src/hooks/file/useFetchFile.ts
+var defaultQueryOptions = {
+	refetchOnMount: "always",
+	staleTime: 0,
+	gcTime: 0
+};
+/**
+* useFetchFile
+*
+* Data-fetching hook built on TanStack Query to retrieve a single file by ID.
+*
+* It also:
+* - builds a stable React Query `queryKey` that can be reused by mutation hooks for cache invalidation
+* - triggers an error alert via `useAppAlert` whenever `query.error` is present
+*
+* Important notes:
+* - Always returns a single `EveryskFile` object.
+* - `EveryskFile.data` represents the file content and is expected to be a Base64-encoded string
+*   when provided by the API (or when sending content through mutations).
+*
+* Parameters (FetchFileProps):
+* @param {string} id
+*   EveryskFile identifier (required).
+*
+* @param {string} workspace
+*   Workspace the file belongs to (required by `getFile`).
+*
+* @param {EntityQueryOptions<any>} [queryOptions=defaultQueryOptions]
+*   TanStack Query options passed through to `useQuery` (e.g., enabled, staleTime, gcTime, etc.).
+*
+* Returns:
+* @returns {object}
+*   TanStack Query's `query` object extended with:
+*   - `queryKey`: the cache key used by React Query
+*
+* Tip:
+* - The returned `queryKey` can be reused by mutation hooks for cache invalidation:
+*   ```ts
+*   const fetch = useFetchFile({ id: "file-123", workspace: "ws-1" });
+*   useFileMutations({ queryKey: fetch.queryKey });
+*   ```
+*
+* Example:
+* ```ts
+* const { data, isLoading } = useFetchFile({
+*   id: "file-123",
+*   workspace: "ws-1",
+* });
+* // data -> EveryskFile
+* ```
+*/
+var useFetchFile = ({ id, workspace, queryOptions = defaultQueryOptions }) => {
+	const { api } = useAxios();
+	const { showAlert } = useAppAlert();
+	const queryKey = [
+		"file",
+		id,
+		workspace
+	];
+	const query = useQuery({
+		queryKey,
+		queryFn: async () => {
+			return await getFile(api, id, workspace);
+		},
+		...queryOptions ?? {}
+	});
+	useEffect(() => {
+		if (!query.error) return;
+		showAlert({
+			severity: "error",
+			message: query.error.message
+		});
+	}, [query.error, showAlert]);
+	return {
+		...query,
+		queryKey
+	};
+};
+//#endregion
+export { useFetchFile };
+
+//# sourceMappingURL=useFetchFile.js.map

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

@@ -0,0 +1 @@
+{"version":3,"file":"useFetchFile.js","names":[],"sources":["../../../src/hooks/file/useFetchFile.ts"],"sourcesContent":["import { useEffect } from \"react\";\n\nimport { useQuery } from \"@tanstack/react-query\";\n\nimport { useAxios } from \"@/hooks/useAxios\";\nimport type { EveryskFile } from \"@/types/file\";\nimport { useAppAlert } from \"@/contexts/appAlertContext/useAppAlert\";\nimport { getFile } from \"@/api/file\";\nimport type { EntityQueryOptions, FetchEntityParams } from \"@/types/entityQuery\";\n\nexport type FetchFileProps<TData = EveryskFile, TSelected = TData> = FetchEntityParams<TData, TSelected>;\n\nconst defaultQueryOptions: EntityQueryOptions<EveryskFile> = {\n    refetchOnMount: \"always\",\n    staleTime: 0,\n    gcTime: 0\n}\n\n/**\n * useFetchFile\n *\n * Data-fetching hook built on TanStack Query to retrieve a single file 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 `EveryskFile` object.\n * - `EveryskFile.data` represents the file content and is expected to be a Base64-encoded string\n *   when provided by the API (or when sending content through mutations).\n *\n * Parameters (FetchFileProps):\n * @param {string} id\n *   EveryskFile identifier (required).\n *\n * @param {string} workspace\n *   Workspace the file belongs to (required by `getFile`).\n *\n * @param {EntityQueryOptions<any>} [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 = useFetchFile({ id: \"file-123\", workspace: \"ws-1\" });\n *   useFileMutations({ queryKey: fetch.queryKey });\n *   ```\n *\n * Example:\n * ```ts\n * const { data, isLoading } = useFetchFile({\n *   id: \"file-123\",\n *   workspace: \"ws-1\",\n * });\n * // data -> EveryskFile\n * ```\n */\nexport const useFetchFile = ({ id, workspace, queryOptions = defaultQueryOptions }: FetchFileProps) => {\n\n    const { api } = useAxios();\n    const { showAlert } = useAppAlert();\n\n    const queryKey = [\"file\", id, workspace];\n\n    const query = useQuery<EveryskFile>({\n        queryKey,\n        queryFn: async () => {\n            const file = await getFile(api, id, workspace);\n            return file;\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":";;;;;;AAYA,IAAM,sBAAuD;CACzD,gBAAgB;CAChB,WAAW;CACX,QAAQ;AACZ;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;AA+CA,IAAa,gBAAgB,EAAE,IAAI,WAAW,eAAe,0BAA0C;CAEnG,MAAM,EAAE,QAAQ,SAAS;CACzB,MAAM,EAAE,cAAc,YAAY;CAElC,MAAM,WAAW;EAAC;EAAQ;EAAI;CAAS;CAEvC,MAAM,QAAQ,SAAsB;EAChC;EACA,SAAS,YAAY;GAEjB,OAAO,MADY,QAAQ,KAAK,IAAI,SAAS;EAEjD;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/file/useFetchFiles.d.ts

@@ -0,0 +1,60 @@
+import { type UseInfiniteQueryOptions, type QueryKey } from "@tanstack/react-query";
+import type { EveryskFile, FileListResponse } from "../../types/file.d.ts";
+import type { FetchEntitiesParams } from "../../types/entityQuery.d.ts";
+type PageToken = string | null;
+type InfiniteOptions<TData> = Omit<UseInfiniteQueryOptions<FileListResponse, Error, TData, QueryKey, PageToken>, "queryKey" | "queryFn" | "initialPageParam" | "getNextPageParam">;
+export type FetchInfiniteFileProps = FetchEntitiesParams<EveryskFile[], InfiniteOptions<EveryskFile[]>> & {
+    pageSize?: number;
+};
+/**
+ * useFetchFiles
+ *
+ * Data-fetching hook built on TanStack Query's `useInfiniteQuery` to retrieve
+ * files with cursor-based pagination.
+ *
+ * It also:
+ * - flattens all pages into a single `EveryskFile[]` via `select`
+ *
+ * Important notes:
+ * - `query.data` returns a flat `EveryskFile[]` (all pages merged).
+ *
+ * Parameters (FetchInfiniteFileProps):
+ * @param {FilterClause[]} [filters=[]]
+ *   Filters applied to every page request. Must include a `workspace` filter.
+ *
+ * @param {string[]} [order=[]]
+ *   Sorting applied to every page request.
+ *
+ * @param {string} [projection=""]
+ *   Single field to project: `"field"` returns only that field (others come back null),
+ *   `"-field"` returns every field except that one. One field only — lists 500. Omitted when empty.
+ *
+ * @param {number} [pageSize=10]
+ *   Number of files to fetch per page.
+ *
+ * @param {InfiniteOptions<EveryskFile[]>} [queryOptions]
+ *   TanStack Query options passed through to `useInfiniteQuery`
+ *   (e.g., enabled, staleTime, gcTime, etc.).
+ *
+ * Returns:
+ * @returns {object}
+ *   - `query`: the full `useInfiniteQuery` result (data, isLoading, hasNextPage, fetchNextPage, etc.)
+ *   - `queryKey`: the cache key used by React Query
+ *
+ * Example:
+ * ```ts
+ * const { query } = useFetchFiles({
+ *   filters: [{ field: "workspace", value: "ws-1" }],
+ *   pageSize: 20,
+ * });
+ *
+ * // Flat list of all fetched files
+ * const files = query.data ?? [];
+ * ```
+ */
+export declare function useFetchFiles({ filters, order, projection, pageSize, queryOptions }: FetchInfiniteFileProps): {
+    query: import("@tanstack/react-query").UseInfiniteQueryResult<EveryskFile[], Error>;
+    queryKey: unknown[];
+};
+export {};
+//# sourceMappingURL=useFetchFiles.d.ts.map

package/dist/hooks/file/useFetchFiles.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"useFetchFiles.d.ts","sourceRoot":"","sources":["../../../src/hooks/file/useFetchFiles.ts"],"names":[],"mappings":"AACA,OAAO,EAAoB,KAAK,uBAAuB,EAAE,KAAK,QAAQ,EAAE,MAAM,uBAAuB,CAAC;AAItG,OAAO,KAAK,EAAE,WAAW,EAAE,gBAAgB,EAAE,MAAM,cAAc,CAAC;AAClE,OAAO,KAAK,EAAE,mBAAmB,EAAE,MAAM,qBAAqB,CAAC;AAG/D,KAAK,SAAS,GAAG,MAAM,GAAG,IAAI,CAAC;AAE/B,KAAK,eAAe,CAAC,KAAK,IAAI,IAAI,CAC9B,uBAAuB,CAAC,gBAAgB,EAAE,KAAK,EAAE,KAAK,EAAE,QAAQ,EAAE,SAAS,CAAC,EAC5E,UAAU,GAAG,SAAS,GAAG,kBAAkB,GAAG,kBAAkB,CACnE,CAAC;AAEF,MAAM,MAAM,sBAAsB,GAAG,mBAAmB,CAAC,WAAW,EAAE,EAAE,eAAe,CAAC,WAAW,EAAE,CAAC,CAAC,GAAG;IACtG,QAAQ,CAAC,EAAE,MAAM,CAAC;CACrB,CAAC;AAQF;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;GA6CG;AACH,wBAAgB,aAAa,CAAC,EAAE,OAAY,EAAE,KAAU,EAAE,UAAe,EAAE,QAAa,EAAE,YAAY,EAAE,EAAE,sBAAsB;;;EAoC/H"}