@classytic/arc-next 0.10.0 → 0.11.1

package/README.md

@@ -8,6 +8,20 @@ React + TanStack Query SDK for the Arc backend framework. Typed CRUD hooks, opti
 npm install @classytic/arc-next
 ```
 
+## Type flow — use WIRE types for `T`
+
+`createCrudApi<T>`'s generic should be the kernel/module's exported **wire type**
+(plain JSON shape) — never a mongoose-flavored document type. Kernel → API →
+frontend then stays one type flow with zero casts:
+
+```ts
+import type { OrderWire } from '@classytic/order/wire'; // plain JSON shape
+const orders = createCrudApi<OrderWire>('orders');
+```
+
+Server-side counterpart: arc-* modules export their wire types per the
+module-publishing convention.
+
 ## Setup
 
 Call once at app init from a `"use client"` provider:

package/dist/api.d.ts

@@ -123,6 +123,50 @@ declare class BaseApi<TDoc = Record<string, unknown>, TCreate = Partial<TDoc>, T
     params?: QueryParams;
     options?: Omit<RequestOptions, 'token' | 'organizationId'>;
   }): Promise<PaginatedResult<TDoc>>;
+  /**
+   * Count records matching the filters — arc's list-route dispatch verb
+   * (`?_count=true`): same permissions/row-filters/tenant scoping as
+   * `getAll`, ZERO documents fetched. Cheapest way to answer "how many".
+   */
+  count({
+    token,
+    organizationId,
+    params,
+    options
+  }?: {
+    token?: string | null;
+    organizationId?: string | null;
+    params?: QueryParams;
+    options?: Omit<RequestOptions, 'token' | 'organizationId'>;
+  }): Promise<number>;
+  /** Whether ANY record matches the filters (`?_exists=true`). */
+  exists({
+    token,
+    organizationId,
+    params,
+    options
+  }?: {
+    token?: string | null;
+    organizationId?: string | null;
+    params?: QueryParams;
+    options?: Omit<RequestOptions, 'token' | 'organizationId'>;
+  }): Promise<boolean>;
+  /** Distinct values of a field across matching records (`?_distinct=field`). */
+  distinct<TValue = unknown>({
+    token,
+    organizationId,
+    field,
+    params,
+    options
+  }: {
+    token?: string | null;
+    organizationId?: string | null;
+    field: string;
+    params?: QueryParams;
+    options?: Omit<RequestOptions, 'token' | 'organizationId'>;
+  }): Promise<TValue[]>;
+  /** Shared raw GET against the list route (dispatch verbs bypass pagination parsing). */
+  private getAllRaw;
   getById({
     token,
     organizationId,

package/dist/api.js

@@ -105,6 +105,60 @@ var BaseApi = class {
 		if (organizationId) requestOptions.organizationId = organizationId;
 		return this.requestFn("GET", `${this.baseUrl}?${queryString}`, this.withHeaders(requestOptions));
 	}
+	/**
+	* Count records matching the filters — arc's list-route dispatch verb
+	* (`?_count=true`): same permissions/row-filters/tenant scoping as
+	* `getAll`, ZERO documents fetched. Cheapest way to answer "how many".
+	*/
+	async count({ token = null, organizationId = null, params = {}, options = {} } = {}) {
+		return extractVerbField(await this.getAllRaw({
+			token,
+			organizationId,
+			params: {
+				...params,
+				_count: true
+			},
+			options
+		}), "count");
+	}
+	/** Whether ANY record matches the filters (`?_exists=true`). */
+	async exists({ token = null, organizationId = null, params = {}, options = {} } = {}) {
+		return extractVerbField(await this.getAllRaw({
+			token,
+			organizationId,
+			params: {
+				...params,
+				_exists: true
+			},
+			options
+		}), "exists");
+	}
+	/** Distinct values of a field across matching records (`?_distinct=field`). */
+	async distinct({ token = null, organizationId = null, field, params = {}, options = {} }) {
+		if (!field) throw new Error("field is required");
+		return extractVerbField(await this.getAllRaw({
+			token,
+			organizationId,
+			params: {
+				...params,
+				_distinct: field
+			},
+			options
+		}), "values");
+	}
+	/** Shared raw GET against the list route (dispatch verbs bypass pagination parsing). */
+	async getAllRaw({ token = null, organizationId = null, params = {}, options = {} }) {
+		const mergedParams = {
+			...this.config.defaultParams,
+			...params
+		};
+		const processedParams = this.prepareParams(mergedParams);
+		const queryString = this.createQueryString(processedParams);
+		const requestOptions = { ...this.withCacheDefault(options) };
+		if (token) requestOptions.token = token;
+		if (organizationId) requestOptions.organizationId = organizationId;
+		return this.requestFn("GET", `${this.baseUrl}?${queryString}`, this.withHeaders(requestOptions));
+	}
 	async getById({ token = null, organizationId = null, id, params = {}, options = {} }) {
 		if (!id) throw new Error("ID is required");
 		const queryString = this.createQueryString(params);
@@ -255,6 +309,18 @@ function isKeysetPagination(response) {
 function isAggregatePagination(response) {
 	return "method" in response && response.method === "aggregate";
 }
+/**
+* Dispatch-verb responses are small objects (`{ count }`, `{ exists }`,
+* `{ values }`). Parse defensively across envelope variants (bare vs
+* `{ data: ... }`) so minor server envelope changes don't break clients.
+*/
+function extractVerbField(res, field) {
+	const r = res;
+	if (r && field in r) return r[field];
+	const d = r?.data ?? null;
+	if (d && field in d) return d[field];
+	throw new Error(`[arc-next] unexpected dispatch-verb response shape (missing '${field}')`);
+}
 
 //#endregion
 export { BaseApi, createCrudApi, isAggregatePagination, isKeysetPagination, isOffsetPagination };

package/dist/client.d.ts

@@ -141,6 +141,33 @@ declare function isAbortError(error: unknown): boolean;
  * if (isArcErrorCode(error, 'ORG_CONTEXT_REQUIRED')) promptOrgSelector();
  */
 declare function isArcErrorCode(error: unknown, code: ArcErrorCode): error is ArcApiError;
+/** `details` payload of arc's `quota.exceeded` 429 (`requireQuota`). */
+interface QuotaDetails {
+  /** The metered counter, e.g. `ai.tokens`, `export.runs`. */
+  kind: string;
+  used: number;
+  limit: number;
+  /** Billing period key, `YYYY-MM`. */
+  period: string;
+  /** ISO timestamp of the next period start — render "resets {date}". */
+  resetsAt: string;
+}
+/**
+ * Type guard for arc's quota denial (429 `quota.exceeded` from
+ * `requireQuota`). Render a meter, not a generic failure:
+ *
+ * @example
+ * if (isQuotaExceeded(err)) {
+ *   const q = getQuotaDetails(err);
+ *   toast(`${q.used.toLocaleString()} of ${q.limit.toLocaleString()} ${q.kind} used — resets ${new Date(q.resetsAt).toLocaleDateString()}`);
+ * }
+ *
+ * NEVER auto-retry these — a monthly quota doesn't reset between retries
+ * (the shared query client already refuses; see query-client.ts).
+ */
+declare function isQuotaExceeded(error: unknown): error is ArcApiError;
+/** Structured quota details from a `quota.exceeded` error (null when absent/malformed). */
+declare function getQuotaDetails(error: unknown): QuotaDetails | null;
 /**
  * Specific predicate for arc's bulk-preset + orgGuard safety code.
  *
@@ -623,7 +650,19 @@ interface NextFetchOptions {
 }
 interface ApiRequestOptions {
   body?: unknown;
+  /**
+   * Bearer token for this request. THREE-STATE contract:
+   * - **omitted / `undefined`** → inherit the global `configureAuth()` context
+   *   (auto-injected by `handleApiRequest`, per-client instances, and hooks)
+   * - **explicit `null`** → deliberately unauthenticated (public endpoint)
+   * - **string** → use exactly this token (wins over the global context)
+   */
   token?: string | null;
+  /**
+   * Tenant/org id sent as `x-organization-id`. Same three-state contract as
+   * `token`: `undefined` = inherit `configureAuth().getOrgId`, `null` = send
+   * no org header (platform-scope calls), string = exactly this org.
+   */
   organizationId?: string | null;
   /** Flattened Next `revalidate` (see `next`). `false` = cache indefinitely. */
   revalidate?: number | false;
@@ -864,4 +903,4 @@ declare const arc: {
   delete: <T = unknown>(path: string, opts?: ArcFetchOptions) => Promise<T>;
 };
 //#endregion
-export { AfterResponseContext, AfterResponseInterceptor, ApiRequestOptions, ArcApiError, ArcApiErrorOptions, ArcClient, ArcClientConfig, ArcErrorCode, ArcFetchOptions, AuthConfig, AuthErrorContext, AuthErrorHandler, BeforeRequestContext, BeforeRequestInterceptor, BlobResponse, ClientConfig, ClientEncryptionConfig, HttpMethod, KNOWN_ARC_ERROR_CODES, NextFetchOptions, RetryConfig, StreamUrlProtocol, TextResponse, ToastHandler, UseRouterHook, _getAuthErrorHandler, _isAuthRecoverable, _resetArcFetchClient, _resetAuthRecovery, _resetAuthWarnings, _resolveRefreshedToken, _runAuthRecovery, arc, arcAuthHeaders, arcFetch, buildStreamUrl, configureAuth, configureClient, createAuthAwareClient, createAuthRefreshHandler, createClient, createQueryString, getAuthContext, getAuthMode, getBaseUrl, getClientAuthContext, handleApiRequest, hasGlobalStaticAuth, isAbortError, isArcApiError, isArcErrorCode, isAutoIdempotency, isDuplicateKeyError, isOrgContextRequiredError, isValidationError };
+export { AfterResponseContext, AfterResponseInterceptor, ApiRequestOptions, ArcApiError, ArcApiErrorOptions, ArcClient, ArcClientConfig, ArcErrorCode, ArcFetchOptions, AuthConfig, AuthErrorContext, AuthErrorHandler, BeforeRequestContext, BeforeRequestInterceptor, BlobResponse, ClientConfig, ClientEncryptionConfig, HttpMethod, KNOWN_ARC_ERROR_CODES, NextFetchOptions, QuotaDetails, RetryConfig, StreamUrlProtocol, TextResponse, ToastHandler, UseRouterHook, _getAuthErrorHandler, _isAuthRecoverable, _resetArcFetchClient, _resetAuthRecovery, _resetAuthWarnings, _resolveRefreshedToken, _runAuthRecovery, arc, arcAuthHeaders, arcFetch, buildStreamUrl, configureAuth, configureClient, createAuthAwareClient, createAuthRefreshHandler, createClient, createQueryString, getAuthContext, getAuthMode, getBaseUrl, getClientAuthContext, getQuotaDetails, handleApiRequest, hasGlobalStaticAuth, isAbortError, isArcApiError, isArcErrorCode, isAutoIdempotency, isDuplicateKeyError, isOrgContextRequiredError, isQuotaExceeded, isValidationError };

package/dist/client.js

@@ -201,6 +201,29 @@ function isArcErrorCode(error, code) {
 	return isArcApiError(error) && error.code === code;
 }
 /**
+* Type guard for arc's quota denial (429 `quota.exceeded` from
+* `requireQuota`). Render a meter, not a generic failure:
+*
+* @example
+* if (isQuotaExceeded(err)) {
+*   const q = getQuotaDetails(err);
+*   toast(`${q.used.toLocaleString()} of ${q.limit.toLocaleString()} ${q.kind} used — resets ${new Date(q.resetsAt).toLocaleDateString()}`);
+* }
+*
+* NEVER auto-retry these — a monthly quota doesn't reset between retries
+* (the shared query client already refuses; see query-client.ts).
+*/
+function isQuotaExceeded(error) {
+	return isArcApiError(error) && error.status === 429 && error.code === "quota.exceeded";
+}
+/** Structured quota details from a `quota.exceeded` error (null when absent/malformed). */
+function getQuotaDetails(error) {
+	if (!isQuotaExceeded(error)) return null;
+	const d = error.json?.details;
+	if (!d || typeof d.kind !== "string" || typeof d.limit !== "number") return null;
+	return d;
+}
+/**
 * Specific predicate for arc's bulk-preset + orgGuard safety code.
 *
 * Arc's bulk endpoints (`POST/PATCH/DELETE /:resource/bulk`) reject any call
@@ -877,6 +900,12 @@ async function executeAttempt(config, method, endpoint, options, attempt) {
 */
 async function handleApiRequest(method, endpoint, options = {}) {
 	if (!clientConfig) throw new Error("arc-next: Client not configured. Call configureClient({ baseUrl }) before making API requests.");
+	if (authConfig) {
+		const resolved = { ...options };
+		if (resolved.token === void 0) resolved.token = readToken(authConfig.getToken);
+		if (resolved.organizationId === void 0) resolved.organizationId = authConfig.getOrgId?.() ?? null;
+		return executeRequest(clientConfig, method, endpoint, resolved);
+	}
 	return executeRequest(clientConfig, method, endpoint, options);
 }
 /**
@@ -1110,4 +1139,4 @@ const arc = {
 };
 
 //#endregion
-export { ArcApiError, KNOWN_ARC_ERROR_CODES, _getAuthErrorHandler, _isAuthRecoverable, _resetArcFetchClient, _resetAuthRecovery, _resetAuthWarnings, _resolveRefreshedToken, _runAuthRecovery, arc, arcAuthHeaders, arcFetch, buildStreamUrl, configureAuth, configureClient, createAuthAwareClient, createAuthRefreshHandler, createClient, createQueryString, getAuthContext, getAuthMode, getBaseUrl, getClientAuthContext, handleApiRequest, hasGlobalStaticAuth, isAbortError, isArcApiError, isArcErrorCode, isAutoIdempotency, isDuplicateKeyError, isOrgContextRequiredError, isValidationError };
+export { ArcApiError, KNOWN_ARC_ERROR_CODES, _getAuthErrorHandler, _isAuthRecoverable, _resetArcFetchClient, _resetAuthRecovery, _resetAuthWarnings, _resolveRefreshedToken, _runAuthRecovery, arc, arcAuthHeaders, arcFetch, buildStreamUrl, configureAuth, configureClient, createAuthAwareClient, createAuthRefreshHandler, createClient, createQueryString, getAuthContext, getAuthMode, getBaseUrl, getClientAuthContext, getQuotaDetails, handleApiRequest, hasGlobalStaticAuth, isAbortError, isArcApiError, isArcErrorCode, isAutoIdempotency, isDuplicateKeyError, isOrgContextRequiredError, isQuotaExceeded, isValidationError };

package/dist/hooks.d.ts

@@ -9,6 +9,7 @@ import { SlugLookupMethods } from "./presets/slug.js";
 import { TreeMethods } from "./presets/tree.js";
 import { SearchPresetMethods } from "./presets/search.js";
 import { QueryKey, UseQueryResult } from "@tanstack/react-query";
+import { PaginatedResult } from "@classytic/repo-core/pagination";
 
 //#region src/hooks.d.ts
 /**
@@ -21,7 +22,7 @@ import { QueryKey, UseQueryResult } from "@tanstack/react-query";
  * any cast — yet a vanilla `createCrudApi('todos')` instance has none of them
  * in autocomplete unless you opt in.
  */
-type CrudApi<T = unknown, TCreate = Partial<T>, TUpdate = Partial<T>> = Pick<BaseApi<T, TCreate, TUpdate>, 'getAll' | 'getById' | 'create' | 'update' | 'delete'> & {
+type CrudApi<T = unknown, TCreate = Partial<T>, TUpdate = Partial<T>> = Pick<BaseApi<T, TCreate, TUpdate>, 'getAll' | 'getById' | 'create' | 'update' | 'delete' | 'count'> & {
   upload?: BaseApi<T, TCreate, TUpdate>['upload'];
   dispatchAction?: BaseApi<T, TCreate, TUpdate>['dispatchAction'];
   invokeRoute?: BaseApi<T, TCreate, TUpdate>['invokeRoute']; /** Declared aggregations (arc 2.13+). Always available on BaseApi. */
@@ -207,6 +208,12 @@ interface CrudHooksReturn<T, TCreate, TUpdate> {
   useActions: () => CrudActions<T, TCreate, TUpdate>;
   useBulkActions: () => BulkActions<T, TCreate>;
   useDeleted: (params?: Record<string, unknown>, options?: ListQueryOptions<T>) => ListQueryResult<T>;
+  /** Count-only query via arc's `?_count=true` dispatch verb — zero documents fetched. */
+  useCount: (params?: Record<string, unknown>, options?: {
+    enabled?: boolean;
+    staleTime?: number;
+    gcTime?: number;
+  }) => UseQueryResult<number, Error>;
   useDetailBySlug: (slug: string | null, options?: DetailQueryOptions<T>) => DetailQueryResult<T>;
   useTree: (params?: Record<string, unknown>, options?: ListQueryOptions<T>) => ListQueryResult<T>;
   useChildren: (parentId: string | null, params?: Record<string, unknown>, options?: ListQueryOptions<T>) => ListQueryResult<T>;
@@ -218,7 +225,11 @@ interface CrudHooksReturn<T, TCreate, TUpdate> {
   useAction: <TResult = T, TBody extends Record<string, unknown> = Record<string, unknown>>(options?: {
     invalidateQueries?: QueryKey[]; /** Default action name. Can be overridden per-call via `mutate({ action })`. */
     action?: string;
-    messages?: MutationMessages;
+    messages?: MutationMessages<TResult, {
+      id: string;
+      action?: string;
+      data?: TBody;
+    }>;
     onSuccess?: (data: TResult, variables: {
       id: string;
       action: string;
@@ -242,18 +253,25 @@ interface CrudHooksReturn<T, TCreate, TUpdate> {
   /** Mutation against the search-preset POST `/search` route. */
   useSearchEngine: <TResult = T, TBody extends Record<string, unknown> = Record<string, unknown>>(options?: {
     path?: string;
-    messages?: MutationMessages;
+    messages?: MutationMessages<TResult[] | PaginatedResult<TResult>, {
+      query?: string;
+      body?: TBody;
+    }>;
     invalidateQueries?: QueryKey[];
-  }) => TransitionMutationReturn<unknown, {
+  }) => TransitionMutationReturn<TResult[] | PaginatedResult<TResult>, {
     query?: string;
     body?: TBody;
   }>;
   /** Mutation against the search-preset POST `/search-similar` route. */
   useSearchSimilar: <TResult = T, TBody extends Record<string, unknown> = Record<string, unknown>>(options?: {
     path?: string;
-    messages?: MutationMessages;
+    messages?: MutationMessages<TResult[] | PaginatedResult<TResult>, {
+      query?: string;
+      vector?: number[];
+      body?: TBody;
+    }>;
     invalidateQueries?: QueryKey[];
-  }) => TransitionMutationReturn<unknown, {
+  }) => TransitionMutationReturn<TResult[] | PaginatedResult<TResult>, {
     query?: string;
     vector?: number[];
     body?: TBody;
@@ -303,7 +321,7 @@ interface CrudHooksReturn<T, TCreate, TUpdate> {
   useCustomMutation: <TData = unknown, TVariables = unknown>(config: {
     mutationFn: (variables: TVariables) => Promise<TData>;
     invalidateQueries?: QueryKey[];
-    messages?: MutationMessages;
+    messages?: MutationMessages<TData, TVariables>;
     onSuccess?: (data: TData, variables: TVariables) => void;
     onError?: (error: Error, variables: TVariables) => void;
     onSettled?: (data: TData | undefined, error: Error | null, variables: TVariables) => void;

package/dist/hooks.js

@@ -601,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;
@@ -1029,6 +1046,7 @@ function createCrudHooks({ api, entityKey, singular, plural, idField, defaults =
 		useInfiniteList,
 		useActions,
 		useBulkActions,
+		useCount,
 		useDeleted,
 		useDetailBySlug,
 		useTree,

package/dist/mutation.d.ts

@@ -3,9 +3,16 @@ import * as _$_tanstack_react_query0 from "@tanstack/react-query";
 import { QueryClient, QueryKey, UseMutateAsyncFunction, UseMutateFunction } from "@tanstack/react-query";
 
 //#region src/mutation.d.ts
-interface MutationMessages {
-  success?: string | ((data: unknown, variables: unknown) => string);
-  error?: string | ((error: Error, variables: unknown) => string);
+/**
+ * Toast copy for a mutation. Generic over the mutation's result/variables so
+ * `success: (result) => ...` sees the TYPED FLAT action result (arc 2.13+
+ * returns results with no `{ data }` envelope) — the stale-envelope
+ * `(data as { data: T }).data` cast class is a compile error now. Defaults
+ * keep pre-0.11.1 unparameterized usage compiling unchanged.
+ */
+interface MutationMessages<TData = unknown, TVariables = unknown> {
+  success?: string | ((data: TData, variables: TVariables) => string);
+  error?: string | ((error: Error, variables: TVariables) => string);
 }
 interface MutationCallbacks<TData, TVariables, TContext = unknown> {
   onMutate?: (variables: TVariables) => TContext | Promise<TContext>;
@@ -56,7 +63,7 @@ interface TransitionMutationConfig<TData, TVariables> {
   onSuccess?: (data: TData, variables: TVariables) => void;
   onError?: (error: Error, variables: TVariables) => void;
   onSettled?: (data: TData | undefined, error: Error | null, variables: TVariables) => void;
-  messages?: MutationMessages;
+  messages?: MutationMessages<TData, TVariables>;
   useTransition?: boolean;
   showToast?: boolean;
   /** Per-call toast guard — return false to suppress toast for this invocation */
@@ -80,7 +87,7 @@ interface OptimisticMutationConfig<TData, TVariables> {
   onSuccess?: (data: TData, variables: TVariables) => void;
   onError?: (error: Error, variables: TVariables) => void;
   onSettled?: (data: TData | undefined, error: Error | null, variables: TVariables) => void;
-  messages?: MutationMessages;
+  messages?: MutationMessages<TData, TVariables>;
   showToast?: boolean;
   toastHandler?: ToastHandler;
 }
@@ -112,7 +119,7 @@ interface CreateOptimisticMutationConfig<TData, TVariables> {
   onSuccess?: (data: TData, variables: TVariables) => void;
   onError?: (error: Error, variables: TVariables) => void;
   onSettled?: (data: TData | undefined, error: Error | null, variables: TVariables) => void;
-  messages?: MutationMessages;
+  messages?: MutationMessages<TData, TVariables>;
   /** Per-call toast guard — return false to suppress toast for this invocation */
   shouldToast?: () => boolean;
   toastHandler?: ToastHandler;

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/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

package/llms.txt

@@ -0,0 +1,22 @@
+# @classytic/arc-next
+
+> React + TanStack Query SDK for @classytic/arc backends. Typed CRUD hooks,
+> optimistic updates with rollback, tenant-scoped cache keys, pagination
+> normalization (offset + keyset), SSE, uploads.
+
+IMPORTANT for coding agents: hand-rolled `fetch()`/axios against an arc API is a
+bug in apps using this package. Before writing any data-fetching code, check:
+
+- CRUD + queries      → createCrudApi<T>('resource') + createCrudHooks (useList, useDetail, useInfiniteList, useSuspense*)
+- "How many?"         → api.count() / useCount() — arc's ?_count=true verb, zero documents fetched (also api.exists / api.distinct)
+- Mutations           → useActions/useBulkActions/useCustomMutation (optimistic updates + rollback + toast built in)
+- Custom actions      → useAction (arc's POST /:id/action router)
+- Server presets      → compose the matching wrapper: withSoftDelete/withBulk/withTree/withSlugLookup/withSearch/withHistory
+- Record timeline     → withHistory(api) + api.history(id) — arc 2.22 `history: true` audit timeline
+- Quota 429s          → isQuotaExceeded(err) + getQuotaDetails(err) → render "X of Y {kind}, resets {date}"; NEVER auto-retry (the shared query client already refuses)
+- Aggregations        → useAggregation(name, filter)
+- Realtime            → SSE/WS modules; uploads → useUpload/useFileUpload
+- Auth/org context    → configureClient/configureAuth once at app init; hooks read it — never thread tokens by hand
+
+Type flow: the generic T in createCrudApi<T> should be the kernel/module's exported
+WIRE type (plain JSON shape) — never a mongoose-flavored document type.

package/package.json

@@ -1,173 +1,178 @@
-{
-  "name": "@classytic/arc-next",
-  "version": "0.10.0",
-  "description": "React + TanStack Query SDK for Arc resources",
-  "type": "module",
-  "sideEffects": false,
-  "license": "MIT",
-  "author": "Classytic",
-  "repository": {
-    "type": "git",
-    "url": "https://github.com/classytic/arc-next"
-  },
-  "keywords": [
-    "react",
-    "tanstack-query",
-    "react-query",
-    "crud",
-    "api-client",
-    "hooks",
-    "optimistic-updates",
-    "pagination",
-    "multi-tenant",
-    "arc",
-    "mongokit",
-    "sse",
-    "real-time",
-    "soft-delete",
-    "bulk-operations"
-  ],
-  "main": "./dist/hooks.js",
-  "types": "./dist/hooks.d.ts",
-  "exports": {
-    ".": {
-      "types": "./dist/hooks.d.ts",
-      "default": "./dist/hooks.js"
-    },
-    "./client": {
-      "types": "./dist/client.d.ts",
-      "default": "./dist/client.js"
-    },
-    "./encryption": {
-      "types": "./dist/encryption.d.ts",
-      "default": "./dist/encryption.js"
-    },
-    "./field-encryption": {
-      "types": "./dist/field-encryption.d.ts",
-      "default": "./dist/field-encryption.js"
-    },
-    "./api": {
-      "types": "./dist/api.d.ts",
-      "default": "./dist/api.js"
-    },
-    "./cache": {
-      "types": "./dist/cache.d.ts",
-      "default": "./dist/cache.js"
-    },
-    "./query": {
-      "types": "./dist/query.d.ts",
-      "default": "./dist/query.js"
-    },
-    "./mutation": {
-      "types": "./dist/mutation.d.ts",
-      "default": "./dist/mutation.js"
-    },
-    "./hooks": {
-      "types": "./dist/hooks.d.ts",
-      "default": "./dist/hooks.js"
-    },
-    "./query-client": {
-      "types": "./dist/query-client.d.ts",
-      "default": "./dist/query-client.js"
-    },
-    "./prefetch": {
-      "types": "./dist/prefetch.d.ts",
-      "default": "./dist/prefetch.js"
-    },
-    "./sse": {
-      "types": "./dist/sse.d.ts",
-      "default": "./dist/sse.js"
-    },
-    "./ws": {
-      "types": "./dist/ws.d.ts",
-      "default": "./dist/ws.js"
-    },
-    "./upload": {
-      "types": "./dist/upload.d.ts",
-      "default": "./dist/upload.js"
-    },
-    "./presets/soft-delete": {
-      "types": "./dist/presets/soft-delete.d.ts",
-      "default": "./dist/presets/soft-delete.js"
-    },
-    "./presets/bulk": {
-      "types": "./dist/presets/bulk.d.ts",
-      "default": "./dist/presets/bulk.js"
-    },
-    "./presets/slug": {
-      "types": "./dist/presets/slug.d.ts",
-      "default": "./dist/presets/slug.js"
-    },
-    "./presets/tree": {
-      "types": "./dist/presets/tree.d.ts",
-      "default": "./dist/presets/tree.js"
-    },
-    "./presets/search": {
-      "types": "./dist/presets/search.d.ts",
-      "default": "./dist/presets/search.js"
-    },
-    "./package.json": "./package.json",
-    "./query-options": {
-      "types": "./dist/query-options.d.ts",
-      "default": "./dist/query-options.js"
-    }
-  },
-  "files": [
-    "dist"
-  ],
-  "publishConfig": {
-    "access": "public",
-    "registry": "https://registry.npmjs.org/"
-  },
-  "engines": {
-    "node": ">=20"
-  },
-  "scripts": {
-    "build": "tsdown",
-    "dev": "tsdown --watch",
-    "test": "vitest run",
-    "test:watch": "vitest",
-    "typecheck": "tsc --noEmit",
-    "push": "classytic-push",
-    "release:tag": "node -e \"require('child_process').execSync('npm run push -- v'+require('./package.json').version,{stdio:'inherit'})\"",
-    "release": "npm run push -- main && npm run release:tag && npm publish",
-    "prepublishOnly": "npm run typecheck && npm test && npm run build",
-    "typecheck:tests": "tsc --noEmit -p tsconfig.test.json"
-  },
-  "peerDependencies": {
-    "@classytic/repo-core": ">=0.4.0",
-    "@tanstack/react-query": ">=5.62.0",
-    "jose": ">=5.0.0",
-    "react": ">=19.0.0"
-  },
-  "peerDependenciesMeta": {
-    "react": {
-      "optional": false
-    },
-    "@tanstack/react-query": {
-      "optional": false
-    },
-    "@classytic/repo-core": {
-      "optional": false
-    },
-    "jose": {
-      "optional": true
-    }
-  },
-  "devDependencies": {
-    "@classytic/dev-tools": "^0.2.0",
-    "@classytic/repo-core": "^0.5.0",
-    "@tanstack/react-query": "^5.97.0",
-    "@testing-library/jest-dom": "^6.9.1",
-    "@testing-library/react": "^16.3.2",
-    "@types/react": "^19.2.14",
-    "@types/react-dom": "^19.2.3",
-    "jose": "^6.2.3",
-    "jsdom": "^29.0.2",
-    "react": "^19.2.5",
-    "react-dom": "^19.2.5",
-    "tsdown": "^0.21.7",
-    "typescript": "^6.0.2",
-    "vitest": "^4.1.4"
-  }
-}
+{
+  "name": "@classytic/arc-next",
+  "version": "0.11.1",
+  "description": "React + TanStack Query SDK for Arc resources",
+  "type": "module",
+  "sideEffects": false,
+  "license": "MIT",
+  "author": "Classytic",
+  "repository": {
+    "type": "git",
+    "url": "https://github.com/classytic/arc-next"
+  },
+  "keywords": [
+    "react",
+    "tanstack-query",
+    "react-query",
+    "crud",
+    "api-client",
+    "hooks",
+    "optimistic-updates",
+    "pagination",
+    "multi-tenant",
+    "arc",
+    "mongokit",
+    "sse",
+    "real-time",
+    "soft-delete",
+    "bulk-operations"
+  ],
+  "main": "./dist/hooks.js",
+  "types": "./dist/hooks.d.ts",
+  "exports": {
+    ".": {
+      "types": "./dist/hooks.d.ts",
+      "default": "./dist/hooks.js"
+    },
+    "./client": {
+      "types": "./dist/client.d.ts",
+      "default": "./dist/client.js"
+    },
+    "./encryption": {
+      "types": "./dist/encryption.d.ts",
+      "default": "./dist/encryption.js"
+    },
+    "./field-encryption": {
+      "types": "./dist/field-encryption.d.ts",
+      "default": "./dist/field-encryption.js"
+    },
+    "./api": {
+      "types": "./dist/api.d.ts",
+      "default": "./dist/api.js"
+    },
+    "./cache": {
+      "types": "./dist/cache.d.ts",
+      "default": "./dist/cache.js"
+    },
+    "./query": {
+      "types": "./dist/query.d.ts",
+      "default": "./dist/query.js"
+    },
+    "./mutation": {
+      "types": "./dist/mutation.d.ts",
+      "default": "./dist/mutation.js"
+    },
+    "./hooks": {
+      "types": "./dist/hooks.d.ts",
+      "default": "./dist/hooks.js"
+    },
+    "./query-client": {
+      "types": "./dist/query-client.d.ts",
+      "default": "./dist/query-client.js"
+    },
+    "./prefetch": {
+      "types": "./dist/prefetch.d.ts",
+      "default": "./dist/prefetch.js"
+    },
+    "./sse": {
+      "types": "./dist/sse.d.ts",
+      "default": "./dist/sse.js"
+    },
+    "./ws": {
+      "types": "./dist/ws.d.ts",
+      "default": "./dist/ws.js"
+    },
+    "./upload": {
+      "types": "./dist/upload.d.ts",
+      "default": "./dist/upload.js"
+    },
+    "./presets/soft-delete": {
+      "types": "./dist/presets/soft-delete.d.ts",
+      "default": "./dist/presets/soft-delete.js"
+    },
+    "./presets/history": {
+      "types": "./dist/presets/history.d.ts",
+      "default": "./dist/presets/history.js"
+    },
+    "./presets/bulk": {
+      "types": "./dist/presets/bulk.d.ts",
+      "default": "./dist/presets/bulk.js"
+    },
+    "./presets/slug": {
+      "types": "./dist/presets/slug.d.ts",
+      "default": "./dist/presets/slug.js"
+    },
+    "./presets/tree": {
+      "types": "./dist/presets/tree.d.ts",
+      "default": "./dist/presets/tree.js"
+    },
+    "./presets/search": {
+      "types": "./dist/presets/search.d.ts",
+      "default": "./dist/presets/search.js"
+    },
+    "./package.json": "./package.json",
+    "./query-options": {
+      "types": "./dist/query-options.d.ts",
+      "default": "./dist/query-options.js"
+    }
+  },
+  "files": [
+    "dist",
+    "llms.txt"
+  ],
+  "publishConfig": {
+    "access": "public",
+    "registry": "https://registry.npmjs.org/"
+  },
+  "engines": {
+    "node": ">=20"
+  },
+  "scripts": {
+    "build": "tsdown",
+    "dev": "tsdown --watch",
+    "test": "vitest run",
+    "test:watch": "vitest",
+    "typecheck": "tsc --noEmit",
+    "push": "classytic-push",
+    "release:tag": "node -e \"require('child_process').execSync('npm run push -- v'+require('./package.json').version,{stdio:'inherit'})\"",
+    "release": "npm run push -- main && npm run release:tag && npm publish",
+    "prepublishOnly": "npm run typecheck && npm test && npm run build",
+    "typecheck:tests": "tsc --noEmit -p tsconfig.test.json"
+  },
+  "peerDependencies": {
+    "@classytic/repo-core": ">=0.4.0",
+    "@tanstack/react-query": ">=5.62.0",
+    "jose": ">=5.0.0",
+    "react": ">=19.0.0"
+  },
+  "peerDependenciesMeta": {
+    "react": {
+      "optional": false
+    },
+    "@tanstack/react-query": {
+      "optional": false
+    },
+    "@classytic/repo-core": {
+      "optional": false
+    },
+    "jose": {
+      "optional": true
+    }
+  },
+  "devDependencies": {
+    "@classytic/dev-tools": "^0.2.0",
+    "@classytic/repo-core": "^0.5.0",
+    "@tanstack/react-query": "^5.97.0",
+    "@testing-library/jest-dom": "^6.9.1",
+    "@testing-library/react": "^16.3.2",
+    "@types/react": "^19.2.14",
+    "@types/react-dom": "^19.2.3",
+    "jose": "^6.2.3",
+    "jsdom": "^29.0.2",
+    "react": "^19.2.5",
+    "react-dom": "^19.2.5",
+    "tsdown": "^0.21.7",
+    "typescript": "^6.0.2",
+    "vitest": "^4.1.4"
+  }
+}