@classytic/arc-next 0.9.1 → 0.11.0

package/dist/hooks.js

@@ -2,7 +2,7 @@
 
 import { getAuthMode, getClientAuthContext, hasGlobalStaticAuth } from "./client.js";
 import { isKeysetPagination, isOffsetPagination } from "./api.js";
-import { DEFAULT_QUERY_CONFIG, createCacheUtils, createQueryKeys, extractItem, getItemId, syncDetailToLists, updateListCache } from "./cache.js";
+import { DEFAULT_QUERY_CONFIG, createCacheUtils, createQueryKeys, extractItem, getItemId, syncDetailToLists, updateListCache, withOrgParams } from "./cache.js";
 import { findItemInListCache, useDetailQuery, useInfiniteListQuery, useListQuery, useSuspenseDetailQuery, useSuspenseListQuery } from "./query.js";
 import { useMutationWithTransition, useOptimisticMutation } from "./mutation.js";
 import { subscribeToEvents } from "./sse.js";
@@ -75,6 +75,13 @@ function createCrudHooks({ api, entityKey, singular, plural, idField, defaults =
 			...defaults.messages
 		}
 	};
+	const computeEnabled = (token, options, extraGate = true) => {
+		const merged = options.public === void 0 && config.defaultPublic ? {
+			...options,
+			public: true
+		} : options;
+		return extraGate && createEnabledRule(token, merged, resolveAuthMode(), resolveHasStaticAuth());
+	};
 	function useList(tokenOrParams, paramsOrOptions, maybeOptions) {
 		let token;
 		let params;
@@ -97,10 +104,7 @@ function createCrudHooks({ api, entityKey, singular, plural, idField, defaults =
 		const scope = options._scope || (organizationId ? "tenant" : "super-admin");
 		const { request: requestOpts, ...queryOpts } = options;
 		return useListQuery({
-			queryKey: KEYS.scopedList(scope, {
-				organizationId,
-				...restParams
-			}),
+			queryKey: KEYS.scopedList(scope, withOrgParams(organizationId, restParams)),
 			queryFn: ({ signal }) => api.getAll({
 				token,
 				organizationId,
@@ -110,7 +114,7 @@ function createCrudHooks({ api, entityKey, singular, plural, idField, defaults =
 					...requestOpts
 				}
 			}),
-			enabled: createEnabledRule(token, queryOpts, resolveAuthMode(), resolveHasStaticAuth()),
+			enabled: computeEnabled(token, queryOpts),
 			options: {
 				staleTime: queryOpts.staleTime ?? config.staleTime,
 				gcTime: queryOpts.gcTime ?? config.gcTime,
@@ -154,7 +158,7 @@ function createCrudHooks({ api, entityKey, singular, plural, idField, defaults =
 					...requestOpts
 				}
 			}),
-			enabled: !!id && createEnabledRule(token, restOptions, resolveAuthMode(), resolveHasStaticAuth()),
+			enabled: computeEnabled(token, restOptions, !!id),
 			options: {
 				staleTime: restOptions.staleTime ?? config.staleTime,
 				gcTime: restOptions.gcTime ?? config.gcTime,
@@ -491,10 +495,7 @@ function createCrudHooks({ api, entityKey, singular, plural, idField, defaults =
 		const scope = options._scope || (organizationId ? "tenant" : "super-admin");
 		const { request: requestOpts, ...queryOpts } = options;
 		return useInfiniteListQuery({
-			queryKey: [...KEYS.scopedList(scope, {
-				organizationId,
-				...restParams
-			}), "infinite"],
+			queryKey: [...KEYS.scopedList(scope, withOrgParams(organizationId, restParams)), "infinite"],
 			queryFn: ({ pageParam, signal }) => {
 				const paginationParams = typeof pageParam === "string" ? { after: pageParam } : { page: pageParam };
 				return api.getAll({
@@ -510,7 +511,7 @@ function createCrudHooks({ api, entityKey, singular, plural, idField, defaults =
 					}
 				});
 			},
-			enabled: createEnabledRule(token, queryOpts, resolveAuthMode(), resolveHasStaticAuth()),
+			enabled: computeEnabled(token, queryOpts),
 			initialPageParam: restParams.after ? restParams.after : 1,
 			getNextPageParam: (lastPage) => {
 				const page = lastPage;
@@ -579,10 +580,7 @@ function createCrudHooks({ api, entityKey, singular, plural, idField, defaults =
 		const { organizationId: _, ...restParams } = mergedParams;
 		const { request: requestOpts, ...queryOpts } = options ?? {};
 		return useListQuery({
-			queryKey: KEYS.custom("deleted", {
-				organizationId,
-				...restParams
-			}),
+			queryKey: KEYS.custom("deleted", withOrgParams(organizationId, restParams)),
 			queryFn: ({ signal }) => {
 				if (!api.getDeleted) return Promise.reject(/* @__PURE__ */ new Error(`[arc-next] "${entityKey}" api does not define a getDeleted method`));
 				return api.getDeleted({
@@ -595,7 +593,7 @@ function createCrudHooks({ api, entityKey, singular, plural, idField, defaults =
 					}
 				});
 			},
-			enabled: !!api.getDeleted && createEnabledRule(token, queryOpts, resolveAuthMode(), resolveHasStaticAuth()),
+			enabled: computeEnabled(token, queryOpts, !!api.getDeleted),
 			options: {
 				staleTime: queryOpts.staleTime ?? config.staleTime,
 				gcTime: queryOpts.gcTime ?? config.gcTime
@@ -603,6 +601,23 @@ function createCrudHooks({ api, entityKey, singular, plural, idField, defaults =
 			select: queryOpts.select
 		});
 	}
+	function useCount(params, options) {
+		const auth = resolveAuth();
+		const mergedParams = params ?? {};
+		const organizationId = mergedParams.organizationId ?? auth.organizationId;
+		const { organizationId: _, ...restParams } = mergedParams;
+		return useQuery({
+			queryKey: KEYS.custom("count", withOrgParams(organizationId, restParams)),
+			queryFn: () => api.count({
+				token: auth.token,
+				organizationId,
+				params: restParams
+			}),
+			enabled: options?.enabled ?? true,
+			staleTime: options?.staleTime ?? config.staleTime,
+			gcTime: options?.gcTime ?? config.gcTime
+		});
+	}
 	function useDetailBySlug(slug, options) {
 		const auth = resolveAuth();
 		const token = auth.token;
@@ -626,7 +641,7 @@ function createCrudHooks({ api, entityKey, singular, plural, idField, defaults =
 					}
 				});
 			},
-			enabled: !!api.getBySlug && !!slug && createEnabledRule(token, restOptions, resolveAuthMode(), resolveHasStaticAuth()),
+			enabled: computeEnabled(token, restOptions, !!api.getBySlug && !!slug),
 			options: {
 				staleTime: restOptions.staleTime ?? config.staleTime,
 				gcTime: restOptions.gcTime ?? config.gcTime,
@@ -654,10 +669,7 @@ function createCrudHooks({ api, entityKey, singular, plural, idField, defaults =
 		const { organizationId: _, ...restParams } = mergedParams;
 		const { request: requestOpts, ...queryOpts } = options ?? {};
 		return useListQuery({
-			queryKey: KEYS.custom("tree", {
-				organizationId,
-				...restParams
-			}),
+			queryKey: KEYS.custom("tree", withOrgParams(organizationId, restParams)),
 			queryFn: ({ signal }) => {
 				if (!api.getTree) return Promise.reject(/* @__PURE__ */ new Error(`[arc-next] "${entityKey}" api does not define a getTree method`));
 				return api.getTree({
@@ -670,7 +682,7 @@ function createCrudHooks({ api, entityKey, singular, plural, idField, defaults =
 					}
 				});
 			},
-			enabled: !!api.getTree && createEnabledRule(token, queryOpts, resolveAuthMode(), resolveHasStaticAuth()),
+			enabled: computeEnabled(token, queryOpts, !!api.getTree),
 			options: {
 				staleTime: queryOpts.staleTime ?? config.staleTime,
 				gcTime: queryOpts.gcTime ?? config.gcTime
@@ -686,10 +698,7 @@ function createCrudHooks({ api, entityKey, singular, plural, idField, defaults =
 		const { organizationId: _, ...restParams } = mergedParams;
 		const { request: requestOpts, ...queryOpts } = options ?? {};
 		return useListQuery({
-			queryKey: KEYS.custom("children", parentId, {
-				organizationId,
-				...restParams
-			}),
+			queryKey: KEYS.custom("children", parentId, withOrgParams(organizationId, restParams)),
 			queryFn: ({ signal }) => {
 				if (!api.getChildren) return Promise.reject(/* @__PURE__ */ new Error(`[arc-next] "${entityKey}" api does not define a getChildren method`));
 				return api.getChildren({
@@ -703,7 +712,7 @@ function createCrudHooks({ api, entityKey, singular, plural, idField, defaults =
 					}
 				});
 			},
-			enabled: !!api.getChildren && !!parentId && createEnabledRule(token, queryOpts, resolveAuthMode(), resolveHasStaticAuth()),
+			enabled: computeEnabled(token, queryOpts, !!api.getChildren && !!parentId),
 			options: {
 				staleTime: queryOpts.staleTime ?? config.staleTime,
 				gcTime: queryOpts.gcTime ?? config.gcTime
@@ -1037,6 +1046,7 @@ function createCrudHooks({ api, entityKey, singular, plural, idField, defaults =
 		useInfiniteList,
 		useActions,
 		useBulkActions,
+		useCount,
 		useDeleted,
 		useDetailBySlug,
 		useTree,

package/dist/mutation.js

@@ -1,6 +1,6 @@
 "use client";
 
-import { isArcApiError, isAutoIdempotency } from "./client.js";
+import { getQuotaDetails, isArcApiError, isAutoIdempotency } from "./client.js";
 import { useMutation, useQueryClient } from "@tanstack/react-query";
 import { useCallback, useRef, useTransition } from "react";
 
@@ -50,7 +50,9 @@ function showToast(type, messages, data, variables, error, handler) {
 	} else {
 		const msg = messages?.error;
 		let defaultMsg = error?.message || "An error occurred";
-		if (isArcApiError(error) && error.fieldErrors) {
+		const quota = getQuotaDetails(error);
+		if (quota) defaultMsg = `${quota.used.toLocaleString()} of ${quota.limit.toLocaleString()} ${quota.kind} used this period — resets ${new Date(quota.resetsAt).toLocaleDateString()}`;
+		else if (isArcApiError(error) && error.fieldErrors) {
 			const fields = Object.entries(error.fieldErrors);
 			if (fields.length > 0) defaultMsg = fields.map(([k, v]) => `${k}: ${v}`).join(", ");
 		}

package/dist/prefetch.d.ts

@@ -1,3 +1,4 @@
+import { EntityReadApi } from "./query-options.js";
 import { HydrationBoundary, InfiniteData, QueryClient, dehydrate } from "@tanstack/react-query";
 
 //#region src/prefetch.d.ts
@@ -22,13 +23,6 @@ interface PrefetchOptions extends PrefetchAuthContext {
   revalidate?: number | false;
   tags?: string[];
 }
-/** Per-call API `options` the prefetcher forwards (caching + custom headers). */
-type ForwardedApiOptions = {
-  headerOptions?: Record<string, string>;
-  cache?: RequestCache;
-  revalidate?: number | false;
-  tags?: string[];
-};
 interface PrefetchDetailOptions extends PrefetchOptions {
   /** Query params (select, populate) — key must match useDetail's params to share cache */
   params?: {
@@ -46,11 +40,8 @@ interface CrudPrefetcher {
    */
   prefetchList: (queryClient: QueryClient, params?: Record<string, unknown>, options?: PrefetchOptions) => Promise<void>;
   /**
-   * Prefetch a detail query on the server. Uses the same query keys as useDetail.
-   *
-   * @example
-   * const queryClient = getQueryClient();
-   * await productsPrefetcher.prefetchDetail(queryClient, productId);
+   * Prefetch a detail query on the server. Uses the same query keys as useDetail
+   * (tenant-scoped when `organizationId` is provided).
    */
   prefetchDetail: (queryClient: QueryClient, id: string, options?: PrefetchDetailOptions) => Promise<void>;
   /**
@@ -68,16 +59,6 @@ interface CrudPrefetcher {
    * Only available when the API has a `getTree` method (tree preset).
    */
   prefetchTree: (queryClient: QueryClient, params?: Record<string, unknown>, options?: PrefetchOptions) => Promise<void>;
-  /**
-   * Prefetch an infinite list query (cursor / page-based pagination). Uses the
-   * same query keys as `useInfiniteList` and seeds the `{ pages, pageParams }`
-   * shape TanStack Query expects for `useInfiniteQuery` — a flat
-   * `prefetchQuery` would NOT match the cache shape and the client hook would
-   * re-fetch from scratch, defeating the prefetch.
-   *
-   * @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
@@ -92,12 +73,31 @@ interface CrudPrefetcher {
    * );
    */
   prefetchAggregation: (queryClient: QueryClient, name: string, filter?: Record<string, unknown>, options?: PrefetchOptions) => Promise<void>;
+  /**
+   * Prefetch an infinite list query (cursor / page-based pagination). Uses the
+   * same query keys as `useInfiniteList` and seeds the `{ pages, pageParams }`
+   * shape TanStack Query expects for `useInfiniteQuery` — a flat
+   * `prefetchQuery` would NOT match the cache shape and the client hook would
+   * re-fetch from scratch, defeating the prefetch.
+   *
+   * @example
+   * await productsPrefetcher.prefetchInfiniteList(queryClient, { limit: 20 });
+   */
   prefetchInfiniteList: (queryClient: QueryClient, params?: Record<string, unknown>, options?: PrefetchOptions) => Promise<void>;
 }
 /**
  * Create server-safe prefetch helpers for CRUD queries.
  * Use in Next.js server components to pre-populate the query cache before rendering.
  *
+ * Since 0.10 this is a thin layer over `createEntityQueries`
+ * (@classytic/arc-next/query-options) — the queryOptions factories are the
+ * single source of key + queryFn, shared with the client CRUD hooks, so
+ * prefetch keys can never drift from hook keys. Prefer the factories directly
+ * for new code that also needs `ensureQueryData` / router-loader integration:
+ *
+ *   const products = createEntityQueries(productApi, 'products');
+ *   await queryClient.prefetchQuery({ ...products.list({ limit: 20 }, { token }), staleTime: 60_000 });
+ *
  * @example
  * // products-prefetch.ts
  * import { productsApi } from '@/api/products-api';
@@ -119,45 +119,6 @@ interface CrudPrefetcher {
  *   );
  * }
  */
-declare function createCrudPrefetcher(api: {
-  getAll: (opts: {
-    params?: Record<string, unknown>;
-    token?: string | null;
-    organizationId?: string | null;
-    options?: ForwardedApiOptions;
-  }) => Promise<unknown>;
-  getById: (opts: {
-    id: string;
-    token?: string | null;
-    organizationId?: string | null;
-    options?: ForwardedApiOptions;
-  }) => Promise<unknown>;
-  getBySlug?: (opts: {
-    slug: string;
-    token?: string | null;
-    organizationId?: string | null;
-    params?: Record<string, unknown>;
-    options?: ForwardedApiOptions;
-  }) => Promise<unknown>;
-  getDeleted?: (opts: {
-    params?: Record<string, unknown>;
-    token?: string | null;
-    organizationId?: string | null;
-    options?: ForwardedApiOptions;
-  }) => Promise<unknown>;
-  aggregate?: (opts: {
-    name: string;
-    filter?: Record<string, unknown>;
-    token?: string | null;
-    organizationId?: string | null;
-    options?: ForwardedApiOptions;
-  }) => Promise<unknown>;
-  getTree?: (opts: {
-    params?: Record<string, unknown>;
-    token?: string | null;
-    organizationId?: string | null;
-    options?: ForwardedApiOptions;
-  }) => Promise<unknown>;
-}, entityKey: string): CrudPrefetcher;
+declare function createCrudPrefetcher(api: EntityReadApi, entityKey: string): CrudPrefetcher;
 //#endregion
 export { CrudPrefetcher, HydrationBoundary, type InfiniteData, PrefetchAuthContext, PrefetchDetailOptions, PrefetchOptions, createCrudPrefetcher, dehydrate };

package/dist/prefetch.js

@@ -1,11 +1,25 @@
-import { createQueryKeys } from "./cache.js";
+import { createEntityQueries } from "./query-options.js";
 import { HydrationBoundary, dehydrate } from "@tanstack/react-query";
 
 //#region src/prefetch.ts
+/** Extract the queryFn context (auth + fetch caching) from prefetch options. */
+function toCtx(options) {
+	const { staleTime: _staleTime, ...ctx } = options;
+	return ctx;
+}
 /**
 * Create server-safe prefetch helpers for CRUD queries.
 * Use in Next.js server components to pre-populate the query cache before rendering.
 *
+* Since 0.10 this is a thin layer over `createEntityQueries`
+* (@classytic/arc-next/query-options) — the queryOptions factories are the
+* single source of key + queryFn, shared with the client CRUD hooks, so
+* prefetch keys can never drift from hook keys. Prefer the factories directly
+* for new code that also needs `ensureQueryData` / router-loader integration:
+*
+*   const products = createEntityQueries(productApi, 'products');
+*   await queryClient.prefetchQuery({ ...products.list({ limit: 20 }, { token }), staleTime: 60_000 });
+*
 * @example
 * // products-prefetch.ts
 * import { productsApi } from '@/api/products-api';
@@ -28,146 +42,54 @@ import { HydrationBoundary, dehydrate } from "@tanstack/react-query";
 * }
 */
 function createCrudPrefetcher(api, entityKey) {
-	const KEYS = createQueryKeys(entityKey);
-	const apiOptions = (o) => {
-		const opt = {};
-		if (o.headers) opt.headerOptions = o.headers;
-		if (o.cache !== void 0) opt.cache = o.cache;
-		if (o.revalidate !== void 0) opt.revalidate = o.revalidate;
-		if (o.tags !== void 0) opt.tags = o.tags;
-		return Object.keys(opt).length ? { options: opt } : {};
-	};
+	const queries = createEntityQueries(api, entityKey);
 	return {
 		async prefetchList(queryClient, params = {}, options = {}) {
-			const { organizationId: paramOrgId, ...restParams } = params;
-			const orgId = paramOrgId ?? options.organizationId ?? null;
-			const scope = orgId ? "tenant" : "super-admin";
-			const queryKey = KEYS.scopedList(scope, {
-				...orgId ? { organizationId: orgId } : {},
-				...restParams
-			});
 			await queryClient.prefetchQuery({
-				queryKey,
-				queryFn: () => api.getAll({
-					params: restParams,
-					token: options.token ?? null,
-					organizationId: orgId,
-					...apiOptions(options)
-				}),
+				...queries.list(params, toCtx(options)),
 				staleTime: options.staleTime
 			});
 		},
 		async prefetchDetail(queryClient, id, options = {}) {
-			const { params, staleTime, token, organizationId } = options;
-			const baseKey = KEYS.detail(id);
-			const queryKey = params ? [...baseKey, params] : baseKey;
+			const { staleTime, ...detailOpts } = options;
 			await queryClient.prefetchQuery({
-				queryKey,
-				queryFn: () => api.getById({
-					id,
-					token: token ?? null,
-					organizationId: organizationId ?? null,
-					...params ? { params } : {},
-					...apiOptions(options)
-				}),
+				...queries.detail(id, detailOpts),
 				staleTime
 			});
 		},
 		async prefetchBySlug(queryClient, slug, options = {}) {
 			if (!api.getBySlug) throw new Error(`[arc-next] prefetchBySlug requires an api with getBySlug (slugLookup preset)`);
-			const { params, staleTime, token, organizationId } = options;
-			const queryKey = params ? KEYS.custom("slug", slug, params) : KEYS.custom("slug", slug);
+			const { staleTime, ...detailOpts } = options;
 			await queryClient.prefetchQuery({
-				queryKey,
-				queryFn: () => api.getBySlug({
-					slug,
-					token: token ?? null,
-					organizationId: organizationId ?? null,
-					...params ? { params } : {},
-					...apiOptions(options)
-				}),
+				...queries.bySlug(slug, detailOpts),
 				staleTime
 			});
 		},
 		async prefetchDeleted(queryClient, params = {}, options = {}) {
 			if (!api.getDeleted) throw new Error(`[arc-next] prefetchDeleted requires an api with getDeleted (softDelete preset)`);
-			const { organizationId: paramOrgId, ...restParams } = params;
-			const orgId = paramOrgId ?? options.organizationId ?? null;
-			const queryKey = KEYS.custom("deleted", {
-				...orgId ? { organizationId: orgId } : {},
-				...restParams
-			});
 			await queryClient.prefetchQuery({
-				queryKey,
-				queryFn: () => api.getDeleted({
-					params: restParams,
-					token: options.token ?? null,
-					organizationId: orgId,
-					...apiOptions(options)
-				}),
+				...queries.deleted(params, toCtx(options)),
 				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,
-					...apiOptions(options)
-				}),
+				...queries.aggregation(name, filter, toCtx(options)),
 				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;
-			const orgId = paramOrgId ?? options.organizationId ?? null;
-			const queryKey = KEYS.custom("tree", {
-				...orgId ? { organizationId: orgId } : {},
-				...restParams
-			});
 			await queryClient.prefetchQuery({
-				queryKey,
-				queryFn: () => api.getTree({
-					params: restParams,
-					token: options.token ?? null,
-					organizationId: orgId,
-					...apiOptions(options)
-				}),
+				...queries.tree(params, toCtx(options)),
 				staleTime: options.staleTime
 			});
 		},
 		async prefetchInfiniteList(queryClient, params = {}, options = {}) {
-			const { organizationId: paramOrgId, ...restParams } = params;
-			const orgId = paramOrgId ?? options.organizationId ?? null;
-			const scope = orgId ? "tenant" : "super-admin";
-			const queryKey = [...KEYS.scopedList(scope, {
-				...orgId ? { organizationId: orgId } : {},
-				...restParams
-			}), "infinite"];
 			await queryClient.prefetchInfiniteQuery({
-				queryKey,
-				queryFn: ({ pageParam }) => api.getAll({
-					params: {
-						...restParams,
-						...pageParam ? { page: pageParam } : {}
-					},
-					token: options.token ?? null,
-					organizationId: orgId,
-					...apiOptions(options)
-				}),
-				initialPageParam: 1,
-				getNextPageParam: () => void 0,
+				...queries.infiniteList(params, toCtx(options)),
 				staleTime: options.staleTime
 			});
 		}

package/dist/presets/history.d.ts

@@ -0,0 +1,56 @@
+import { AnyBaseApi, ScopedArgs } from "../api.js";
+
+//#region src/presets/history.d.ts
+/** One audit-trail entry — arc's `AuditEntry` wire shape for a single record. */
+interface HistoryEntry {
+  id: string;
+  resource: string;
+  documentId: string;
+  action: 'create' | 'update' | 'delete' | 'restore' | 'custom';
+  userId?: string;
+  organizationId?: string;
+  before?: Record<string, unknown>;
+  after?: Record<string, unknown>;
+  /** Field names that changed (updates). */
+  changes?: string[];
+  requestId?: string;
+  timestamp: string;
+  metadata?: Record<string, unknown>;
+}
+/** Wire shape of `GET /:resource/:id/history`. */
+interface HistoryPage {
+  data: HistoryEntry[];
+  limit: number;
+  offset: number;
+}
+interface HistoryMethods {
+  /**
+   * Per-record change timeline. Backend mounts `GET /:resource/:id/history`
+   * when the resource declares `history: true` (arc 2.22) — audit-backed,
+   * newest first, gated stricter than reads (update → get → auth).
+   */
+  history(args: ScopedArgs & {
+    id: string;
+    params?: {
+      limit?: number;
+      offset?: number;
+    };
+  }): Promise<HistoryPage>;
+}
+/**
+ * Adds the per-record history method to a BaseApi.
+ *
+ * Mirrors arc's server-side `history: true` flag (2.22). Compose like every
+ * other preset wrapper:
+ *
+ * @example
+ * import { createCrudApi } from '@classytic/arc-next/api';
+ * import { withHistory } from '@classytic/arc-next/presets/history';
+ *
+ * const orders = withHistory(createCrudApi<Order>('orders'));
+ * const page = await orders.history({ id, params: { limit: 25 } });
+ * // page.data[0] → { action: 'update', changes: ['status'], before, after, ... }
+ */
+declare function withHistory<TApi extends AnyBaseApi>(api: TApi): TApi & HistoryMethods;
+//#endregion
+export { HistoryEntry, HistoryMethods, HistoryPage, withHistory };

package/dist/presets/history.js

@@ -0,0 +1,29 @@
+//#region src/presets/history.ts
+/**
+* Adds the per-record history method to a BaseApi.
+*
+* Mirrors arc's server-side `history: true` flag (2.22). Compose like every
+* other preset wrapper:
+*
+* @example
+* import { createCrudApi } from '@classytic/arc-next/api';
+* import { withHistory } from '@classytic/arc-next/presets/history';
+*
+* const orders = withHistory(createCrudApi<Order>('orders'));
+* const page = await orders.history({ id, params: { limit: 25 } });
+* // page.data[0] → { action: 'update', changes: ['status'], before, after, ... }
+*/
+function withHistory(api) {
+	return Object.assign(api, { async history({ token = null, organizationId = null, id, params = {}, options = {} }) {
+		if (!id) throw new Error("ID is required");
+		return api.request("GET", `${api.baseUrl}/${id}/history`, {
+			token,
+			organizationId,
+			params,
+			options
+		});
+	} });
+}
+
+//#endregion
+export { withHistory };

package/dist/query-client.js

@@ -1,3 +1,4 @@
+import { isQuotaExceeded } from "./client.js";
 import { QueryClient, defaultShouldDehydrateQuery, isServer } from "@tanstack/react-query";
 
 //#region src/query-client.ts
@@ -14,7 +15,7 @@ function makeQueryClient(overrides) {
 	};
 	return new QueryClient({ defaultOptions: {
 		queries: {
-			retry: opts.retry,
+			retry: (failureCount, error) => !isQuotaExceeded(error) && failureCount < (opts.retry || 0),
 			staleTime: opts.staleTime,
 			gcTime: opts.gcTime,
 			refetchOnWindowFocus: opts.refetchOnWindowFocus