@classytic/arc-next 0.5.0 → 0.6.0

package/dist/hooks.js

@@ -7,7 +7,7 @@ import { 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
@@ -166,7 +166,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 +199,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 +254,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 +284,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`,
@@ -608,7 +616,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 +634,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 +655,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 +784,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(), hasStaticAuth),
+			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 +857,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,
@@ -894,6 +939,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.

package/dist/query.d.ts

@@ -169,13 +169,13 @@ declare function useInfiniteListQuery<T>({
 /** Recognized data-freshness presets. Maps to QUERY_CONFIGS. */
 type QueryFreshness = keyof typeof QUERY_CONFIGS;
 /**
- * Extracts the inner type of an Arc envelope `{ success, data: T }`.
- * Falls through to `T` itself when the response isn't an envelope.
+ * Identity passthrough — arc emits raw data on success (no envelope; HTTP
+ * status discriminates errors via thrown `ArcApiError`). Kept as a named
+ * type for the `useApiQuery` default param so the public signature stays
+ * `useApiQuery<TResponse, TData = ExtractData<TResponse>>` for callers
+ * that want a custom select projection.
  */
-type ExtractData<T> = T extends {
-  success: unknown;
-  data: infer D;
-} ? D : T;
+type ExtractData<T> = T;
 /** Per-call request pass-through and TanStack Query overrides. */
 interface UseApiQueryOptions {
   staleTime?: number;
@@ -196,9 +196,9 @@ interface UseApiQueryConfig<TResponse, TData> {
   /** Freshness preset name (`realtime` | `frequent` | `stable` | `static`). */
   freshness?: QueryFreshness;
   /**
-   * Custom projection from the raw response. When omitted, the hook auto-unwraps
-   * Arc envelopes (`{ success, data }`) and returns `data`. Non-envelope responses
-   * pass through unchanged.
+   * Custom projection from the raw response. When omitted, the response is
+   * returned unchanged — arc 2.13+ has no wire envelope, so the response
+   * already IS the data.
    */
   select?: (response: TResponse) => TData;
   /** TanStack Query overrides (staleTime, refetchInterval, retry, etc.). */
@@ -216,29 +216,29 @@ interface UseApiQueryResult<TData> {
 }
 /**
  * Generic query hook for non-CRUD reads (reports, aggregates, lookups, RPC-style
- * endpoints). Wraps TanStack Query with three ergonomics on top:
+ * endpoints). Wraps TanStack Query with two ergonomics on top:
  *
- * 1. **Envelope auto-unwrap.** `{ success, data: T }` responses are projected to
- *    `T` automatically. Override with a custom `select` for shape changes or
- *    multi-field projections.
- * 2. **Freshness presets.** Pass `freshness: 'realtime' | 'frequent' | 'stable' |
+ * 1. **Freshness presets.** Pass `freshness: 'realtime' | 'frequent' | 'stable' |
  *    'static'` to map onto `QUERY_CONFIGS`. Per-option overrides still win.
- * 3. **Standardized result shape.** `{ data, isLoading, isFetching, isError,
+ * 2. **Standardized result shape.** `{ data, isLoading, isFetching, isError,
  *    isSuccess, isStale, error, refetch }` — same contract as the CRUD hooks.
  *
+ * Arc emits raw data on success (no envelope), so the response IS the data.
+ * Use `select` for shape transformations / multi-field projections.
+ *
  * @example
- * // Auto-unwrap envelope
- * const { data } = useApiQuery<ApiResponse<DashboardStats>>({
+ * // Direct typing — response IS the data
+ * const { data } = useApiQuery<DashboardStats>({
  *   queryKey: ['dashboard', 'stats'],
  *   queryFn: ({ signal }) => api.request('GET', '/dashboard/stats', { options: { signal } }),
  *   freshness: 'realtime',
  * });
  *
- * // Custom projection
+ * // Custom projection (e.g. extract a sub-field)
  * const { data } = useApiQuery({
  *   queryKey: ['ledger', accountId],
- *   queryFn: ({ signal }) => api.request('GET', `/ledger/${accountId}`, { options: { signal } }),
- *   select: (res) => res.data?.entries ?? [],
+ *   queryFn: ({ signal }) => api.request<{ entries: Entry[] }>('GET', `/ledger/${accountId}`, { options: { signal } }),
+ *   select: (res) => res.entries,
  * });
  */
 declare function useApiQuery<TResponse = unknown, TData = ExtractData<TResponse>>({

package/dist/query.js

@@ -98,40 +98,30 @@ function useInfiniteListQuery({ queryKey, queryFn, enabled = true, options = {},
 	};
 }
 /**
-* Strict Arc envelope detector — requires BOTH `success` and `data` keys.
-*
-* Stricter than checking only `data` so we don't mis-unwrap responses that happen
-* to use a `data` field for unrelated semantics (e.g. a chart that returns
-* `{ data: number[], labels: [] }`).
-*/
-function isArcEnvelope(value) {
-	return typeof value === "object" && value !== null && "success" in value && "data" in value;
-}
-/**
 * Generic query hook for non-CRUD reads (reports, aggregates, lookups, RPC-style
-* endpoints). Wraps TanStack Query with three ergonomics on top:
+* endpoints). Wraps TanStack Query with two ergonomics on top:
 *
-* 1. **Envelope auto-unwrap.** `{ success, data: T }` responses are projected to
-*    `T` automatically. Override with a custom `select` for shape changes or
-*    multi-field projections.
-* 2. **Freshness presets.** Pass `freshness: 'realtime' | 'frequent' | 'stable' |
+* 1. **Freshness presets.** Pass `freshness: 'realtime' | 'frequent' | 'stable' |
 *    'static'` to map onto `QUERY_CONFIGS`. Per-option overrides still win.
-* 3. **Standardized result shape.** `{ data, isLoading, isFetching, isError,
+* 2. **Standardized result shape.** `{ data, isLoading, isFetching, isError,
 *    isSuccess, isStale, error, refetch }` — same contract as the CRUD hooks.
 *
+* Arc emits raw data on success (no envelope), so the response IS the data.
+* Use `select` for shape transformations / multi-field projections.
+*
 * @example
-* // Auto-unwrap envelope
-* const { data } = useApiQuery<ApiResponse<DashboardStats>>({
+* // Direct typing — response IS the data
+* const { data } = useApiQuery<DashboardStats>({
 *   queryKey: ['dashboard', 'stats'],
 *   queryFn: ({ signal }) => api.request('GET', '/dashboard/stats', { options: { signal } }),
 *   freshness: 'realtime',
 * });
 *
-* // Custom projection
+* // Custom projection (e.g. extract a sub-field)
 * const { data } = useApiQuery({
 *   queryKey: ['ledger', accountId],
-*   queryFn: ({ signal }) => api.request('GET', `/ledger/${accountId}`, { options: { signal } }),
-*   select: (res) => res.data?.entries ?? [],
+*   queryFn: ({ signal }) => api.request<{ entries: Entry[] }>('GET', `/ledger/${accountId}`, { options: { signal } }),
+*   select: (res) => res.entries,
 * });
 */
 function useApiQuery({ queryKey, queryFn, enabled = true, freshness, select, options = {} }) {
@@ -140,7 +130,7 @@ function useApiQuery({ queryKey, queryFn, enabled = true, freshness, select, opt
 	const projection = useCallback((response) => {
 		const fn = selectRef.current;
 		if (fn) return fn(response);
-		return isArcEnvelope(response) ? response.data : response;
+		return response;
 	}, []);
 	const preset = freshness ? QUERY_CONFIGS[freshness] : void 0;
 	const query = useQuery({

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@classytic/arc-next",
-  "version": "0.5.0",
+  "version": "0.6.0",
   "description": "React + TanStack Query SDK for Arc resources",
   "type": "module",
   "sideEffects": false,
@@ -122,11 +122,13 @@
     "prepublishOnly": "npm run typecheck && npm test && npm run build"
   },
   "peerDependencies": {
+    "@classytic/repo-core": ">=0.4.0",
     "@tanstack/react-query": ">=5.0.0",
     "react": ">=19.0.0"
   },
   "devDependencies": {
     "@classytic/dev-tools": "^0.2.0",
+    "@classytic/repo-core": "^0.4.0",
     "@tanstack/react-query": "^5.97.0",
     "@testing-library/jest-dom": "^6.9.1",
     "@testing-library/react": "^16.3.2",