@classytic/arc-next 0.5.0 → 0.7.0

package/dist/hooks.d.ts

@@ -1,14 +1,14 @@
 import { ArcClient, UseRouterHook } from "./client.js";
-import { ApiResponse, BaseApi } from "./api.js";
+import { AggResult, AggRow, BaseApi } from "./api.js";
 import { CacheUtils, QueryKeys } from "./cache.js";
 import { MutationCallbacks, MutationMessages, TransitionMutationReturn } from "./mutation.js";
-import { DetailQueryOptions, DetailQueryResult, InfiniteListQueryOptions, InfiniteListQueryResult, ListQueryOptions, ListQueryResult } from "./query.js";
+import { DetailQueryOptions, DetailQueryResult, InfiniteListQueryOptions, InfiniteListQueryResult, ListQueryOptions, ListQueryResult, RequestPassthrough } from "./query.js";
 import { SoftDeleteMethods } from "./presets/soft-delete.js";
 import { BulkMethods } from "./presets/bulk.js";
 import { SlugLookupMethods } from "./presets/slug.js";
 import { TreeMethods } from "./presets/tree.js";
 import { SearchPresetMethods } from "./presets/search.js";
-import { QueryKey } from "@tanstack/react-query";
+import { QueryKey, UseQueryResult } from "@tanstack/react-query";
 
 //#region src/hooks.d.ts
 /**
@@ -24,8 +24,50 @@ import { QueryKey } from "@tanstack/react-query";
 type CrudApi<T = unknown, TCreate = Partial<T>, TUpdate = Partial<T>> = Pick<BaseApi<T, TCreate, TUpdate>, 'getAll' | 'getById' | 'create' | 'update' | 'delete'> & {
   upload?: BaseApi<T, TCreate, TUpdate>['upload'];
   dispatchAction?: BaseApi<T, TCreate, TUpdate>['dispatchAction'];
-  invokeRoute?: BaseApi<T, TCreate, TUpdate>['invokeRoute'];
+  invokeRoute?: BaseApi<T, TCreate, TUpdate>['invokeRoute']; /** Declared aggregations (arc 2.13+). Always available on BaseApi. */
+  aggregate?: BaseApi<T, TCreate, TUpdate>['aggregate'];
 } & Partial<SoftDeleteMethods<T>> & Partial<BulkMethods<T, TCreate, TUpdate>> & Partial<SlugLookupMethods<T>> & Partial<TreeMethods<T>> & Partial<SearchPresetMethods<T>>;
+/** Args + options for `useAggregation`. Mirrors `ListQueryOptions` for DX consistency. */
+interface AggregationQueryOptions<TRow extends AggRow = AggRow, TData = AggResult<TRow>> {
+  /** Bypass auth gate (for public dashboards behind `allowPublic` permissions). */
+  public?: boolean;
+  /** Skip the query (e.g. while a parent filter is being assembled). */
+  enabled?: boolean;
+  /** Per-call staleTime override. Defaults to factory's `defaults.staleTime`. */
+  staleTime?: number;
+  /** Per-call gcTime override. */
+  gcTime?: number;
+  /**
+   * Refetch on window focus. Aggregations / dashboards usually want this OFF —
+   * long-running compute. Defaults to `false` regardless of factory config.
+   */
+  refetchOnWindowFocus?: boolean;
+  /** Periodic refetch (ms or `false`). Set for live dashboards. */
+  refetchInterval?: number | false;
+  /** Continue polling while the tab is in the background. */
+  refetchIntervalInBackground?: boolean;
+  /**
+   * Transform `AggResult<TRow>` before exposing it. Common pattern is to
+   * pluck the rows array directly:
+   *   `select: (r) => r.rows`
+   * Or compute a derived value:
+   *   `select: (r) => r.rows.reduce((acc, x) => acc + x.total, 0)`
+   * Runs on each render after structural-sharing dedupe.
+   */
+  select?: (data: AggResult<TRow>) => TData;
+  /**
+   * Pass-through to the underlying fetch call. Use for Next.js ISR — pass
+   * `request: { revalidate: 60, tags: ['orders'] }` so the server-side fetch
+   * cache participates in `revalidateTag('orders')` invalidations alongside
+   * TanStack's client cache.
+   */
+  request?: RequestPassthrough;
+  /**
+   * Show this data while the real query is loading / re-fetching with
+   * different filters. Smooths fast filter switches on dashboards.
+   */
+  placeholderData?: AggResult<TRow> | ((prev: AggResult<TRow> | undefined) => AggResult<TRow> | undefined);
+}
 interface CrudHooksConfig<T, TCreate = Partial<T>, TUpdate = Partial<T>> {
   api: CrudApi<T, TCreate, TUpdate>;
   entityKey: string;
@@ -157,7 +199,7 @@ interface CrudHooksReturn<T, TCreate, TUpdate> {
     invalidateQueries?: QueryKey[]; /** Default action name. Can be overridden per-call via `mutate({ action })`. */
     action?: string;
     messages?: MutationMessages;
-    onSuccess?: (data: ApiResponse<TResult>, variables: {
+    onSuccess?: (data: TResult, variables: {
       id: string;
       action: string;
       data?: TBody;
@@ -167,12 +209,12 @@ interface CrudHooksReturn<T, TCreate, TUpdate> {
       action: string;
       data?: TBody;
     }) => void;
-    onSettled?: (data: ApiResponse<TResult> | undefined, error: Error | null, variables: {
+    onSettled?: (data: TResult | undefined, error: Error | null, variables: {
       id: string;
       action: string;
       data?: TBody;
     }) => void;
-  }) => TransitionMutationReturn<ApiResponse<TResult>, {
+  }) => TransitionMutationReturn<TResult, {
     id: string;
     action?: string;
     data?: TBody;
@@ -205,6 +247,28 @@ interface CrudHooksReturn<T, TCreate, TUpdate> {
     input: string | string[];
     body?: Record<string, unknown>;
   }>;
+  /**
+   * Query against arc's declarative aggregations (arc v2.13+).
+   * `GET /:resource/aggregations/:name` — wire shape `{ rows: TRow[] }`.
+   *
+   * Cached under `KEYS.aggregation(name, filter)` so multiple call sites with
+   * the same args share one cache entry. Mutation hooks
+   * (`useActions`/`useBulkActions`) auto-invalidate `KEYS.aggregations()` so
+   * dashboards refresh after CRUD writes — opt out via the mutation's
+   * `invalidateQueries` override if you want stale-on-write.
+   *
+   * @example
+   * const { data } = useAggregation<{ day: string; total: number }>({
+   *   name: 'salesByDay',
+   *   filter: { from: '2025-01-01' },
+   *   refetchOnWindowFocus: false,
+   * });
+   * // data.rows: Array<{ day: string; total: number }>
+   */
+  useAggregation: <TRow extends AggRow = AggRow, TData = AggResult<TRow>>(args: {
+    name: string;
+    filter?: Record<string, unknown>;
+  } & AggregationQueryOptions<TRow, TData>) => UseQueryResult<TData>;
   useUpload: (options?: {
     invalidateQueries?: QueryKey[];
     messages?: MutationMessages;
@@ -269,4 +333,4 @@ declare function createCrudHooks<T, TCreate = Partial<T>, TUpdate = Partial<T>>(
   client
 }: CrudHooksConfig<T, TCreate, TUpdate>): CrudHooksReturn<T, TCreate, TUpdate>;
 //#endregion
-export { BulkActions, CallOptions, CrudActions, CrudApi, CrudHooksConfig, CrudHooksReturn, DeleteParams, MutationParams, NavigateFn, NavigationOptions, UpdateParams, configureNavigation, createCrudHooks };
+export { AggregationQueryOptions, BulkActions, CallOptions, CrudActions, CrudApi, CrudHooksConfig, CrudHooksReturn, DeleteParams, MutationParams, NavigateFn, NavigationOptions, UpdateParams, configureNavigation, createCrudHooks };

package/dist/hooks.js

@@ -1,13 +1,13 @@
 "use client";
 
-import { getAuthMode, getClientAuthContext } from "./client.js";
+import { getAuthMode, getClientAuthContext, hasGlobalStaticAuth } from "./client.js";
 import { isKeysetPagination, isOffsetPagination } from "./api.js";
-import { DEFAULT_QUERY_CONFIG, createCacheUtils, createQueryKeys, extractItem, getItemId, updateListCache } from "./cache.js";
-import { useDetailQuery, useInfiniteListQuery, useListQuery } from "./query.js";
+import { DEFAULT_QUERY_CONFIG, createCacheUtils, createQueryKeys, extractItem, getItemId, syncDetailToLists, updateListCache } from "./cache.js";
+import { findItemInListCache, useDetailQuery, useInfiniteListQuery, useListQuery } from "./query.js";
 import { useMutationWithTransition, useOptimisticMutation } from "./mutation.js";
 import { subscribeToEvents } from "./sse.js";
 import { connectWs } from "./ws.js";
-import { useQueryClient } from "@tanstack/react-query";
+import { useQuery, useQueryClient } from "@tanstack/react-query";
 import { useCallback, useEffect, useRef, useState } from "react";
 
 //#region src/hooks.ts
@@ -33,8 +33,19 @@ function createCrudHooks({ api, entityKey, singular, plural, idField, defaults =
 	const pluralName = plural ?? `${singular}s`;
 	/** Resolve auth context — per-client auth takes priority over global */
 	const resolveAuth = () => getClientAuthContext(client);
-	/** Whether auth is provided via static config (headers, internalApiKey, per-client auth) — no token needed for enablement */
-	const hasStaticAuth = !!(client?.config?.defaultHeaders || client?.config?.internalApiKey || client?.auth);
+	/**
+	* Whether auth is provided via static config — no per-request token needed.
+	* Sources (in priority order):
+	*   1. Per-client `defaultHeaders` / `internalApiKey` (when `client` is passed in).
+	*   2. Per-client custom auth (e.g. `createClient({ getToken })`).
+	*   3. Global `configureClient({ internalApiKey | defaultHeaders | authMode: 'cookie' })`.
+	*
+	* Resolved lazily on every render so that an app calling `configureClient`
+	* inside a "use client" provider after factory creation still picks up the
+	* global static-auth signal — previously a global `internalApiKey` was
+	* ignored, leaving every protected query stuck in a permanently-disabled state.
+	*/
+	const resolveHasStaticAuth = () => !!(client?.config?.defaultHeaders || client?.config?.internalApiKey || client?.auth) || hasGlobalStaticAuth();
 	/** Extract ID from an item using configured idField, falling back to _id → id */
 	function resolveItemId(item) {
 		if (!item || typeof item !== "object") return null;
@@ -99,7 +110,7 @@ function createCrudHooks({ api, entityKey, singular, plural, idField, defaults =
 					...requestOpts
 				}
 			}),
-			enabled: createEnabledRule(token, queryOpts, resolveAuthMode(), hasStaticAuth),
+			enabled: createEnabledRule(token, queryOpts, resolveAuthMode(), resolveHasStaticAuth()),
 			options: {
 				staleTime: queryOpts.staleTime ?? config.staleTime,
 				gcTime: queryOpts.gcTime ?? config.gcTime,
@@ -108,9 +119,6 @@ function createCrudHooks({ api, entityKey, singular, plural, idField, defaults =
 				refetchInterval: queryOpts.refetchInterval,
 				refetchIntervalInBackground: queryOpts.refetchIntervalInBackground
 			},
-			prefillDetailCache: queryOpts.prefillDetailCache ?? true,
-			detailKeyBuilder: (id) => KEYS.scopedDetail(id, organizationId ?? null),
-			itemIdResolver: resolveItemId,
 			select: queryOpts.select
 		});
 	}
@@ -131,8 +139,11 @@ function createCrudHooks({ api, entityKey, singular, plural, idField, defaults =
 		}
 		const { organizationId, params: queryParams, request: requestOpts, ...restOptions } = options;
 		const detailKey = KEYS.scopedDetail(id || "", organizationId ?? null);
-		return useDetailQuery({
-			queryKey: queryParams ? [...detailKey, queryParams] : detailKey,
+		const fullDetailKey = queryParams ? [...detailKey, queryParams] : detailKey;
+		const queryClient = useQueryClient();
+		const listPlaceholder = useCallback(() => id ? findItemInListCache(queryClient, KEYS.lists(), id, idField) : void 0, [queryClient, id]);
+		const detailResult = useDetailQuery({
+			queryKey: fullDetailKey,
 			queryFn: ({ signal }) => api.getById({
 				id,
 				token,
@@ -143,7 +154,7 @@ function createCrudHooks({ api, entityKey, singular, plural, idField, defaults =
 					...requestOpts
 				}
 			}),
-			enabled: !!id && createEnabledRule(token, restOptions, resolveAuthMode(), hasStaticAuth),
+			enabled: !!id && createEnabledRule(token, restOptions, resolveAuthMode(), resolveHasStaticAuth()),
 			options: {
 				staleTime: restOptions.staleTime ?? config.staleTime,
 				gcTime: restOptions.gcTime ?? config.gcTime,
@@ -152,8 +163,18 @@ function createCrudHooks({ api, entityKey, singular, plural, idField, defaults =
 				refetchInterval: restOptions.refetchInterval,
 				refetchIntervalInBackground: restOptions.refetchIntervalInBackground
 			},
-			select: restOptions.select
+			select: restOptions.select,
+			placeholderData: listPlaceholder
 		});
+		useEffect(() => {
+			if (!detailResult.item || detailResult.isPlaceholderData) return;
+			syncDetailToLists(queryClient, KEYS.lists(), detailResult.item, idField ? { idField } : {});
+		}, [
+			detailResult.item,
+			detailResult.isPlaceholderData,
+			queryClient
+		]);
+		return detailResult;
 	}
 	function useActions() {
 		const queryClient = useQueryClient();
@@ -166,7 +187,7 @@ function createCrudHooks({ api, entityKey, singular, plural, idField, defaults =
 				data
 			}),
 			queryClient,
-			queryKeys: [KEYS.lists()],
+			queryKeys: [KEYS.lists(), KEYS.aggregations()],
 			shouldToast,
 			optimisticUpdate: (oldData, { data }) => {
 				const optimisticItem = {
@@ -199,7 +220,11 @@ function createCrudHooks({ api, entityKey, singular, plural, idField, defaults =
 				data
 			}),
 			queryClient,
-			queryKeys: [KEYS.lists(), KEYS.details()],
+			queryKeys: [
+				KEYS.lists(),
+				KEYS.details(),
+				KEYS.aggregations()
+			],
 			shouldToast,
 			optimisticUpdate: (oldData, { id, data }) => {
 				const updated = updateListCache(oldData, (arr) => (arr || []).map((item) => resolveItemId(item) === id ? {
@@ -250,7 +275,7 @@ function createCrudHooks({ api, entityKey, singular, plural, idField, defaults =
 				id
 			}),
 			queryClient,
-			queryKeys: [KEYS.lists()],
+			queryKeys: [KEYS.lists(), KEYS.aggregations()],
 			shouldToast,
 			optimisticUpdate: (oldData, { id }) => {
 				return updateListCache(oldData, (arr) => (arr || []).filter((item) => resolveItemId(item) !== id));
@@ -280,7 +305,11 @@ function createCrudHooks({ api, entityKey, singular, plural, idField, defaults =
 					id
 				});
 			},
-			invalidateQueries: [KEYS.lists(), KEYS.custom("deleted")],
+			invalidateQueries: [
+				KEYS.lists(),
+				KEYS.custom("deleted"),
+				KEYS.aggregations()
+			],
 			shouldToast,
 			messages: {
 				success: `${singular} restored successfully`,
@@ -405,7 +434,7 @@ function createCrudHooks({ api, entityKey, singular, plural, idField, defaults =
 					}
 				});
 			},
-			enabled: createEnabledRule(token, queryOpts, resolveAuthMode(), hasStaticAuth),
+			enabled: createEnabledRule(token, queryOpts, resolveAuthMode(), resolveHasStaticAuth()),
 			initialPageParam: restParams.after ? restParams.after : 1,
 			getNextPageParam: (lastPage) => {
 				const page = lastPage;
@@ -490,7 +519,7 @@ function createCrudHooks({ api, entityKey, singular, plural, idField, defaults =
 					}
 				});
 			},
-			enabled: !!api.getDeleted && createEnabledRule(token, queryOpts, resolveAuthMode(), hasStaticAuth),
+			enabled: !!api.getDeleted && createEnabledRule(token, queryOpts, resolveAuthMode(), resolveHasStaticAuth()),
 			options: {
 				staleTime: queryOpts.staleTime ?? config.staleTime,
 				gcTime: queryOpts.gcTime ?? config.gcTime
@@ -504,7 +533,9 @@ function createCrudHooks({ api, entityKey, singular, plural, idField, defaults =
 		const resolvedOptions = options ?? {};
 		const organizationId = resolvedOptions.organizationId ?? auth.organizationId;
 		const { params: queryParams, request: requestOpts, ...restOptions } = resolvedOptions;
-		return useDetailQuery({
+		const queryClient = useQueryClient();
+		const listPlaceholder = useCallback(() => slug ? findItemInListCache(queryClient, KEYS.lists(), slug, "slug") : void 0, [queryClient, slug]);
+		const slugResult = useDetailQuery({
 			queryKey: queryParams ? KEYS.custom("slug", slug, queryParams) : KEYS.custom("slug", slug),
 			queryFn: ({ signal }) => {
 				if (!api.getBySlug) return Promise.reject(/* @__PURE__ */ new Error(`[arc-next] "${entityKey}" api does not define a getBySlug method`));
@@ -519,15 +550,25 @@ function createCrudHooks({ api, entityKey, singular, plural, idField, defaults =
 					}
 				});
 			},
-			enabled: !!api.getBySlug && !!slug && createEnabledRule(token, restOptions, resolveAuthMode(), hasStaticAuth),
+			enabled: !!api.getBySlug && !!slug && createEnabledRule(token, restOptions, resolveAuthMode(), resolveHasStaticAuth()),
 			options: {
 				staleTime: restOptions.staleTime ?? config.staleTime,
 				gcTime: restOptions.gcTime ?? config.gcTime,
 				refetchOnWindowFocus: restOptions.refetchOnWindowFocus ?? config.refetchOnWindowFocus,
 				structuralSharing: restOptions.structuralSharing ?? config.structuralSharing
 			},
-			select: restOptions.select
+			select: restOptions.select,
+			placeholderData: listPlaceholder
 		});
+		useEffect(() => {
+			if (!slugResult.item || slugResult.isPlaceholderData) return;
+			syncDetailToLists(queryClient, KEYS.lists(), slugResult.item, idField ? { idField } : {});
+		}, [
+			slugResult.item,
+			slugResult.isPlaceholderData,
+			queryClient
+		]);
+		return slugResult;
 	}
 	function useTree(params, options) {
 		const auth = resolveAuth();
@@ -553,7 +594,7 @@ function createCrudHooks({ api, entityKey, singular, plural, idField, defaults =
 					}
 				});
 			},
-			enabled: !!api.getTree && createEnabledRule(token, queryOpts, resolveAuthMode(), hasStaticAuth),
+			enabled: !!api.getTree && createEnabledRule(token, queryOpts, resolveAuthMode(), resolveHasStaticAuth()),
 			options: {
 				staleTime: queryOpts.staleTime ?? config.staleTime,
 				gcTime: queryOpts.gcTime ?? config.gcTime
@@ -586,14 +627,11 @@ function createCrudHooks({ api, entityKey, singular, plural, idField, defaults =
 					}
 				});
 			},
-			enabled: !!api.getChildren && !!parentId && createEnabledRule(token, queryOpts, resolveAuthMode(), hasStaticAuth),
+			enabled: !!api.getChildren && !!parentId && createEnabledRule(token, queryOpts, resolveAuthMode(), resolveHasStaticAuth()),
 			options: {
 				staleTime: queryOpts.staleTime ?? config.staleTime,
 				gcTime: queryOpts.gcTime ?? config.gcTime
 			},
-			prefillDetailCache: queryOpts.prefillDetailCache ?? true,
-			detailKeyBuilder: (id) => KEYS.scopedDetail(id, organizationId ?? null),
-			itemIdResolver: resolveItemId,
 			select: queryOpts.select
 		});
 	}
@@ -608,7 +646,7 @@ function createCrudHooks({ api, entityKey, singular, plural, idField, defaults =
 					data: vars.data
 				});
 			},
-			invalidateQueries: [KEYS.lists()],
+			invalidateQueries: [KEYS.lists(), KEYS.aggregations()],
 			messages: {
 				success: `${pluralName} created successfully`,
 				error: `Failed to create ${pluralName.toLowerCase()}`
@@ -626,7 +664,11 @@ function createCrudHooks({ api, entityKey, singular, plural, idField, defaults =
 					data: vars.data
 				});
 			},
-			invalidateQueries: [KEYS.lists(), KEYS.details()],
+			invalidateQueries: [
+				KEYS.lists(),
+				KEYS.details(),
+				KEYS.aggregations()
+			],
 			messages: {
 				success: `${pluralName} updated successfully`,
 				error: `Failed to update ${pluralName.toLowerCase()}`
@@ -643,7 +685,7 @@ function createCrudHooks({ api, entityKey, singular, plural, idField, defaults =
 					filter: vars.filter
 				});
 			},
-			invalidateQueries: [KEYS.lists()],
+			invalidateQueries: [KEYS.lists(), KEYS.aggregations()],
 			messages: {
 				success: `${pluralName} deleted successfully`,
 				error: `Failed to delete ${pluralName.toLowerCase()}`
@@ -772,6 +814,38 @@ function createCrudHooks({ api, entityKey, singular, plural, idField, defaults =
 			toastHandler: instanceToast
 		});
 	}
+	function useAggregation(args) {
+		const { name, filter, public: isPublic, enabled = true, staleTime = config.staleTime, gcTime = config.gcTime, refetchOnWindowFocus = false, refetchInterval, refetchIntervalInBackground, select, request, placeholderData } = args;
+		const auth = resolveAuth();
+		const filterKey = auth.organizationId ? {
+			_org: auth.organizationId,
+			...filter ?? {}
+		} : filter ?? {};
+		return useQuery({
+			queryKey: KEYS.aggregation(name, filterKey),
+			queryFn: () => {
+				if (!api.aggregate) return Promise.reject(/* @__PURE__ */ new Error(`[arc-next] "${entityKey}" api does not define an aggregate method (requires arc 2.13+)`));
+				return api.aggregate({
+					name,
+					filter,
+					token: auth.token,
+					organizationId: auth.organizationId,
+					...request ? { options: request } : {}
+				});
+			},
+			enabled: !!name && !!api.aggregate && createEnabledRule(auth.token, {
+				public: isPublic,
+				enabled
+			}, resolveAuthMode(), resolveHasStaticAuth()),
+			staleTime,
+			gcTime,
+			refetchOnWindowFocus,
+			...select ? { select } : {},
+			...refetchInterval !== void 0 ? { refetchInterval } : {},
+			...refetchIntervalInBackground !== void 0 ? { refetchIntervalInBackground } : {},
+			...placeholderData !== void 0 ? { placeholderData } : {}
+		});
+	}
 	/**
 	* Subscribe to live `<resource>.<operation>` broadcasts from arc and
 	* auto-invalidate this entity's TanStack Query cache.
@@ -813,6 +887,7 @@ function createCrudHooks({ api, entityKey, singular, plural, idField, defaults =
 					return raw != null ? String(raw) : void 0;
 				})() : void 0;
 				queryClient.invalidateQueries({ queryKey: KEYS.lists() });
+				queryClient.invalidateQueries({ queryKey: KEYS.aggregations() });
 				if (id && (operation === "updated" || operation === "deleted")) queryClient.invalidateQueries({ queryKey: KEYS.detail(id) });
 				onEventRef.current?.({
 					operation,
@@ -867,8 +942,8 @@ function createCrudHooks({ api, entityKey, singular, plural, idField, defaults =
 			const id = resolveItemId(item);
 			if (id) {
 				const orgId = resolveAuth().organizationId;
-				queryClient.setQueryData(KEYS.scopedDetail(id, orgId), { data: item });
-				if (orgId) queryClient.setQueryData(KEYS.detail(id), { data: item });
+				queryClient.setQueryData(KEYS.scopedDetail(id, orgId), item);
+				if (orgId) queryClient.setQueryData(KEYS.detail(id), item);
 			}
 			if (!router) return;
 			const { scroll = true, replace = false } = options;
@@ -894,6 +969,7 @@ function createCrudHooks({ api, entityKey, singular, plural, idField, defaults =
 		useSearchEngine,
 		useSearchSimilar,
 		useEmbed,
+		useAggregation,
 		useResourceSync,
 		useNavigation
 	};

package/dist/prefetch.d.ts

@@ -61,6 +61,20 @@ interface CrudPrefetcher {
    * @example
    * await productsPrefetcher.prefetchInfiniteList(queryClient, { limit: 20 });
    */
+  /**
+   * Prefetch a declared aggregation (arc 2.13+). Uses the same query key as
+   * `useAggregation` so RSC-pre-rendered dashboard rows hydrate without a
+   * client refetch.
+   *
+   * @example
+   * await ordersPrefetcher.prefetchAggregation(
+   *   queryClient,
+   *   'salesByDay',
+   *   { from: '2025-01-01', to: '2025-12-31' },
+   *   { token: jwt, organizationId: orgId, staleTime: 60_000 },
+   * );
+   */
+  prefetchAggregation: (queryClient: QueryClient, name: string, filter?: Record<string, unknown>, options?: PrefetchOptions) => Promise<void>;
   prefetchInfiniteList: (queryClient: QueryClient, params?: Record<string, unknown>, options?: PrefetchOptions) => Promise<void>;
 }
 /**
@@ -122,6 +136,15 @@ declare function createCrudPrefetcher(api: {
       headerOptions?: Record<string, string>;
     };
   }) => Promise<unknown>;
+  aggregate?: (opts: {
+    name: string;
+    filter?: Record<string, unknown>;
+    token?: string | null;
+    organizationId?: string | null;
+    options?: {
+      headerOptions?: Record<string, string>;
+    };
+  }) => Promise<unknown>;
   getTree?: (opts: {
     params?: Record<string, unknown>;
     token?: string | null;

package/dist/prefetch.js

@@ -100,6 +100,26 @@ function createCrudPrefetcher(api, entityKey) {
 				staleTime: options.staleTime
 			});
 		},
+		async prefetchAggregation(queryClient, name, filter, options = {}) {
+			if (!api.aggregate) throw new Error(`[arc-next] prefetchAggregation requires an api with aggregate (arc 2.13+)`);
+			if (!name) throw new Error("[arc-next] prefetchAggregation: aggregation name is required");
+			const orgId = options.organizationId ?? null;
+			const filterKey = orgId ? {
+				_org: orgId,
+				...filter ?? {}
+			} : filter ?? {};
+			await queryClient.prefetchQuery({
+				queryKey: KEYS.aggregation(name, filterKey),
+				queryFn: () => api.aggregate({
+					name,
+					filter,
+					token: options.token ?? null,
+					organizationId: orgId,
+					...options.headers ? { options: { headerOptions: options.headers } } : {}
+				}),
+				staleTime: options.staleTime
+			});
+		},
 		async prefetchTree(queryClient, params = {}, options = {}) {
 			if (!api.getTree) throw new Error(`[arc-next] prefetchTree requires an api with getTree (tree preset)`);
 			const { organizationId: paramOrgId, ...restParams } = params;

package/dist/presets/bulk.d.ts

@@ -1,11 +1,12 @@
-import { BaseApi, BulkCreateResponse, BulkDeleteResponse, BulkUpdateResponse, ScopedArgs } from "../api.js";
+import { BaseApi, ScopedArgs } from "../api.js";
+import { BulkCreateResult, DeleteManyResult, UpdateManyResult } from "@classytic/repo-core/repository";
 
 //#region src/presets/bulk.d.ts
 interface BulkMethods<TDoc, TCreate = Partial<TDoc>, TUpdate = Partial<TDoc>> {
   /** Insert many docs in one round-trip. Backend mounts `POST /:resource/bulk`. */
   bulkCreate(args: ScopedArgs & {
     data: TCreate[];
-  }): Promise<BulkCreateResponse<TDoc>>;
+  }): Promise<BulkCreateResult<TDoc>>;
   /**
    * Update all docs matching `filter` with `data`.
    * Backend mounts `PATCH /:resource/bulk`.
@@ -13,14 +14,14 @@ interface BulkMethods<TDoc, TCreate = Partial<TDoc>, TUpdate = Partial<TDoc>> {
   bulkUpdate(args: ScopedArgs & {
     filter: Record<string, unknown>;
     data: TUpdate;
-  }): Promise<BulkUpdateResponse>;
+  }): Promise<UpdateManyResult>;
   /**
    * Delete all docs matching `filter`.
    * Backend mounts `DELETE /:resource/bulk`.
    */
   bulkDelete(args: ScopedArgs & {
     filter: Record<string, unknown>;
-  }): Promise<BulkDeleteResponse>;
+  }): Promise<DeleteManyResult>;
 }
 /**
  * Adds bulk preset methods to a BaseApi.

package/dist/presets/search.d.ts

@@ -1,4 +1,5 @@
-import { ApiResponse, BaseApi, PaginatedResponse, ScopedArgs } from "../api.js";
+import { BaseApi, ScopedArgs } from "../api.js";
+import { PaginatedResult } from "@classytic/repo-core/pagination";
 
 //#region src/presets/search.d.ts
 interface SearchPresetMethods<TDoc> {
@@ -10,7 +11,7 @@ interface SearchPresetMethods<TDoc> {
     /** Free-text query forwarded as `body.query`. */query?: string; /** Engine-specific options merged into the request body. */
     body?: TBody; /** Override path (default `/search`). */
     path?: string;
-  }): Promise<ApiResponse<TResult[]> | PaginatedResponse<TResult>>;
+  }): Promise<TResult[] | PaginatedResult<TResult>>;
   /**
    * Vector / semantic similarity (Atlas, Pinecone, Qdrant...).
    * Backend mounts `POST /:resource/search-similar`.
@@ -20,7 +21,7 @@ interface SearchPresetMethods<TDoc> {
     vector?: number[]; /** Vector-engine options (`topK`, `filter`, `index`, ...). */
     body?: TBody; /** Override path (default `/search-similar`). */
     path?: string;
-  }): Promise<ApiResponse<TResult[]>>;
+  }): Promise<TResult[]>;
   /**
    * Convert text/media to a vector embedding via the engine the resource is wired to.
    * Backend mounts `POST /:resource/embed`.
@@ -29,7 +30,7 @@ interface SearchPresetMethods<TDoc> {
     /** Text or array of texts to embed. */input: string | string[]; /** Embed-engine options (`model`, `dimensions`, ...). */
     body?: Record<string, unknown>; /** Override path (default `/embed`). */
     path?: string;
-  }): Promise<ApiResponse<number[] | number[][]>>;
+  }): Promise<number[] | number[][]>;
 }
 /**
  * Adds search preset methods to a BaseApi.

package/dist/presets/slug.d.ts

@@ -1,4 +1,4 @@
-import { ApiResponse, BaseApi, ScopedArgs } from "../api.js";
+import { BaseApi, ScopedArgs } from "../api.js";
 
 //#region src/presets/slug.d.ts
 interface SlugLookupMethods<TDoc> {
@@ -9,7 +9,7 @@ interface SlugLookupMethods<TDoc> {
       select?: string;
       populate?: string | string[];
     };
-  }): Promise<ApiResponse<TDoc>>;
+  }): Promise<TDoc>;
 }
 /**
  * Adds slug-lookup preset methods to a BaseApi.

package/dist/presets/soft-delete.d.ts

@@ -1,15 +1,16 @@
-import { ApiResponse, BaseApi, PaginatedResponse, QueryParams, ScopedArgs } from "../api.js";
+import { BaseApi, QueryParams, ScopedArgs } from "../api.js";
+import { PaginatedResult } from "@classytic/repo-core/pagination";
 
 //#region src/presets/soft-delete.d.ts
 interface SoftDeleteMethods<TDoc> {
   /** List soft-deleted docs. Backend mounts `GET /:resource/deleted`. */
   getDeleted(args?: ScopedArgs & {
     params?: QueryParams;
-  }): Promise<PaginatedResponse<TDoc>>;
+  }): Promise<PaginatedResult<TDoc>>;
   /** Undo a soft-delete. Backend mounts `POST /:resource/:id/restore`. */
   restore(args: ScopedArgs & {
     id: string;
-  }): Promise<ApiResponse<TDoc>>;
+  }): Promise<TDoc>;
 }
 /**
  * Adds soft-delete preset methods to a BaseApi.

package/dist/presets/tree.d.ts

@@ -1,16 +1,17 @@
-import { ApiResponse, BaseApi, PaginatedResponse, QueryParams, ScopedArgs } from "../api.js";
+import { BaseApi, QueryParams, ScopedArgs } from "../api.js";
+import { PaginatedResult } from "@classytic/repo-core/pagination";
 
 //#region src/presets/tree.d.ts
 interface TreeMethods<TDoc> {
   /** Fetch the full hierarchy. Backend mounts `GET /:resource/tree`. */
   getTree(args?: ScopedArgs & {
     params?: QueryParams;
-  }): Promise<ApiResponse<TDoc[]>>;
+  }): Promise<TDoc[]>;
   /** Fetch direct children of a node. Backend mounts `GET /:resource/:id/children`. */
   getChildren(args: ScopedArgs & {
     parentId: string;
     params?: QueryParams;
-  }): Promise<PaginatedResponse<TDoc>>;
+  }): Promise<PaginatedResult<TDoc>>;
 }
 /**
  * Adds tree preset methods to a BaseApi.