@classytic/arc-next 0.5.0 → 0.7.0

package/README.md

@@ -85,31 +85,49 @@ function Products() {
 ## Core Hooks (from `createCrudHooks`)
 
 ```ts
-const { items, pagination, isLoading, refetch } = useList(token, params, options);
-const { item, isLoading } = useDetail(id, token, options);
+const { items, pagination, isLoading, refetch } = useList(params, options);
+const { item, isLoading, isPlaceholderData } = useDetail(id, options);
 const { create, update, remove, isMutating } = useActions();
-const { items, hasNextPage, fetchNextPage } = useInfiniteList(token, params);
+const { items, hasNextPage, fetchNextPage } = useInfiniteList(params);
 
 await create({ data, organizationId }, { onSuccess: (item) => navigate(...) });
 ```
 
-All mutations are optimistic with automatic rollback on error. Lists prefill the detail cache. Cache keys auto-scope by `organizationId` when present.
+- All mutations are optimistic with automatic rollback on error.
+- Cache keys auto-scope by `organizationId` when present.
+- **List → detail handoff:** when a parent `useList` has the entity in cache,
+  `useDetail` reads it via TanStack's `placeholderData` factory — instant
+  preview, but the real detail GET still fires (rich payload swap, no
+  cache pollution). Use `isPlaceholderData` to dim the preview while it
+  resolves. See [CHANGELOG 0.7](./CHANGELOG.md#070) for why this replaced
+  the old setQueryData-based prefill.
+- **Detail → list pseudo-normalization:** after a `useDetail` GET resolves,
+  arc-next shallow-merges the fresh fields into every list cache holding
+  this id. The list view stays in sync without a refetch. Direction is
+  one-way (detail → list, never the reverse) — see
+  [CHANGELOG → "pseudo-normalization"](./CHANGELOG.md#070) for the
+  rationale. For true entity-level normalization (one copy per id, field-
+  level invalidation), use Apollo Client or Relay; arc-next stays in the
+  REST + React Query niche.
+
+`useList(token, params, options)` (legacy 3-arg form) still compiles —
+both signatures are kept stable across the 0.x line.
 
 ### `useApiQuery` — non-CRUD reads
 
-For reports, aggregates, RPC-style endpoints. Auto-unwraps `{ success, data }`:
+For reports, aggregates, RPC-style endpoints. Response IS the data — arc 2.13+ has no envelope:
 
 ```ts
 import { useApiQuery } from "@classytic/arc-next/query";
 
-const { data, isLoading } = useApiQuery<ApiResponse<DashboardStats>>({
+const { data, isLoading } = useApiQuery<DashboardStats>({
   queryKey: ["dashboard", "stats"],
   queryFn: ({ signal }) => api.request("GET", "/dashboard/stats", { options: { signal } }),
   freshness: "realtime",  // 'realtime' | 'frequent' | 'stable' | 'static'
 });
 ```
 
-Pass a custom `select` to override auto-unwrap.
+Pass a custom `select` to project a sub-field from the response.
 
 ## Actions & Custom Routes
 
@@ -126,14 +144,16 @@ const stats = await api.invokeRoute<{ data: { total: number } }>({
   method: "GET",
   path: "/stats",
 });
-const recent = await api.invokeRoute<PaginatedResponse<Todo>>({
+import type { OffsetPaginationResult } from "@classytic/repo-core/pagination";
+
+const recent = await api.invokeRoute<OffsetPaginationResult<Todo>>({
   method: "GET",
   path: "/recent",
   params: { limit: 5 },
 });
 ```
 
-The `useAction` hook (returned from `createCrudHooks`) wraps `api.dispatchAction()` with toast + invalidation. For custom GETs, compose `api.invokeRoute()` with `useApiQuery` — it auto-unwraps the `{ success, data }` envelope:
+The `useAction` hook (returned from `createCrudHooks`) wraps `api.dispatchAction()` with toast + invalidation. For custom GETs, compose `api.invokeRoute()` with `useApiQuery` — the response IS the data (no envelope since arc 2.13):
 
 ```ts
 const { data } = useApiQuery({
@@ -411,13 +431,132 @@ configureClient({
 
 Interceptors are async-supported and compose with retry — `beforeRequest` re-runs each attempt (so a refreshed token mid-flight is picked up). Aborting via `AbortSignal` cancels both the pending fetch AND any in-flight backoff sleep.
 
+## `arcFetch` — one-line authenticated fetch for non-hook contexts (0.7+)
+
+When you need to hit an arc endpoint from outside a hook — event handler, service worker, server action, custom MDX submit, background poll — `arcFetch` collapses the auth/org/content-type/error/parse boilerplate into one call:
+
+```ts
+import { arc } from "@classytic/arc-next/client";
+
+// Before — 15 lines of header dance + error parse + JSON parse:
+//   const { token } = getAuthContext();
+//   if (!token) throw ...
+//   const res = await fetch(`${apiBaseUrl()}/api/statements`, {
+//     method: "POST",
+//     headers: { "content-type": "application/json", authorization: `Bearer ${token}`, ... },
+//     body: JSON.stringify(statements),
+//   });
+//   if (!res.ok) throw ...
+//   return await res.json();
+//
+// After:
+const result = await arc.post<{ ok: boolean }>("/api/statements", statements);
+```
+
+Auto-injects `Authorization` (or your `headerName` for `authMode: "header"`), `x-organization-id`, `x-internal-api-key`, `Idempotency-Key`, `x-arc-scope`, and `Content-Type: application/json` (only for plain object/array bodies). Composes with everything else — `retry`, `onAuthError`, `beforeRequest`, `afterResponse`.
+
+**Method shorthands:**
+
+```ts
+arc.get<T>(path, opts?)
+arc.post<T>(path, body?, opts?)
+arc.put<T>(path, body?, opts?)
+arc.patch<T>(path, body?, opts?)
+arc.delete<T>(path, opts?)
+
+// Or call arcFetch directly for full RequestInit control:
+arcFetch<T>(path, { method, body, headers, signal, elevated, idempotencyKey, revalidate, tags, cache, client })
+```
+
+**Body sniffing.** `FormData`, `Blob`, `URLSearchParams`, `ArrayBuffer`, `ReadableStream`, and `string` pass through unchanged — caller controls `Content-Type` for those. Plain objects and arrays get `JSON.stringify`d and the JSON content-type header.
+
+**Protected headers.** `Authorization`, `x-organization-id`, `x-internal-api-key`, and the custom header for `authMode: "header"` cannot be overridden by `options.headers`. A caller can't accidentally strip the bearer token by spreading their own header map. Non-auth headers (`X-Trace-Id`, `Accept-Version`, etc.) pass through normally.
+
+**Error handling.** Non-2xx throws `ArcApiError` with parsed body, status, endpoint, method — same contract as the CRUD hooks. Use `isArcApiError(err)` + `err.code` to discriminate.
+
+**Escape hatch.** When you need full `Response` control (rare — streaming downloads, custom redirect logic), use plain `fetch` with `arcAuthHeaders()`:
+
+```ts
+import { arcAuthHeaders, getAuthMode } from "@classytic/arc-next/client";
+
+const res = await fetch(url, {
+  headers: { ...arcAuthHeaders(), "X-Custom": "1" },
+  credentials: getAuthMode() === "cookie" ? "include" : "same-origin",
+});
+```
+
+## Auth Recovery (0.7+) — 401 → refresh → retry
+
+When a session token expires mid-page, the SDK transparently refreshes and retries — no flash of unauthenticated UI, no manual reload. Wire it once at app boot:
+
+```ts
+import { configureAuth, createAuthRefreshHandler } from "@classytic/arc-next/client";
+import { authClient } from "@/lib/auth-client";
+
+configureAuth({
+  getToken: () => authClient.getSession().data?.session.token ?? null,
+  onAuthError: createAuthRefreshHandler({
+    refresh: async () => {
+      // Whatever your auth lib calls to mint a fresh access token.
+      const { data } = await authClient.getSession({ disableCookieCache: true });
+      return data?.session.token ?? null; // null → session truly expired; original 401 surfaces
+    },
+  }),
+});
+```
+
+Every `useList`, `useDetail`, `useActions`, and any code path going through `createAuthAwareClient()` or `createClient(...)` now survives token expiry transparently. Apps that don't wire `onAuthError` see the original behavior (401 surfaces immediately).
+
+**Concurrent-refresh dedup.** When N requests hit 401 at the same time, the handler fires **once**. All N concurrent callers await the same refresh promise and retry with the token it produces — no stampeding the refresh endpoint under burst auth-expiry.
+
+**Tuning knobs.**
+
+```ts
+configureAuth({
+  // ...
+  onAuthError,
+  retryOn403: true,    // also recover from 403 (default: 401 only)
+  maxAuthRetries: 1,   // cap per individual request (default: 1; prevents loops)
+});
+```
+
+**Custom handler.** Bypass `createAuthRefreshHandler` if you need full control over the recovery cycle:
+
+```ts
+configureAuth({
+  onAuthError: async ({ error, request, attempt, setToken }) => {
+    if (error.code === "session.revoked") return "skip"; // route to /login
+    const fresh = await myRefreshFn();
+    if (!fresh) return "skip";
+    setToken(fresh);
+    return "retry";
+  },
+});
+```
+
+The handler receives the full `ArcApiError`, the failing request descriptor, the 1-indexed attempt counter, and a `setToken(value)` callback that supplies the refreshed token for the retry. Throwing from the handler short-circuits — the thrown error propagates instead of the 401.
+
+**Transport coverage.** Auth recovery fires across every transport arc-next exposes:
+
+| Transport | Trigger | Mechanism |
+|---|---|---|
+| Fetch (CRUD hooks, `arcFetch`, `handleApiRequest`) | 401 / 403 response | Inline retry in `executeRequest` |
+| XHR upload (`uploadWithProgress`, `useUploadWithProgress`) | 401 / 403 response | Outer retry loop in `upload.ts` |
+| WebSocket | close code `1008` / `3401` / `4001` / `4401` | `ws.onclose` handler routes through recovery, reconnect with refreshed token |
+| SSE (`subscribeToEvents`, `useEventStream`) | `EventSource` error | Pre-flight `fetch` probe classifies as auth-failure → recovery → reopen |
+
+All four transports share **one** dedup'd refresh promise — concurrent failures across mixed transports (5 in-flight uploads + 3 WebSocket reconnects + 10 fetch calls, all 401 at once) collapse to a single `onAuthError` call.
+
 ## Cache & Keys
 
 ```ts
 KEYS.detail(id);                        // ["products", "detail", id]
 KEYS.scopedDetail(id, orgId);           // tenant-scoped variant
 
+// Writes/reads the raw doc — no `{ data: TDoc }` envelope (0.7+). Matches
+// what useDetail, prefetchDetail, and useNavigation all produce.
 cache.setDetail(qc, id, data);
+cache.getDetail(qc, id);                // TDoc | undefined
 cache.invalidateDetail(qc, id);         // matches all scoped variants
 cache.invalidateLists(qc);
 ```

package/dist/api.d.ts

@@ -1,4 +1,7 @@
 import { ArcClient } from "./client.js";
+import { AggregatePaginationResult, KeysetPaginationResult, OffsetPaginationResult, PaginatedResult } from "@classytic/repo-core/pagination";
+import { AggResult, AggRow, BulkCreateResult, DeleteManyResult, DeleteResult, UpdateManyResult } from "@classytic/repo-core/repository";
+import { BracketOperator, BracketOperator as BracketOperator$1 } from "@classytic/repo-core/query-parser";
 
 //#region src/api.d.ts
 interface PopulateOption {
@@ -6,68 +9,24 @@ interface PopulateOption {
   select?: string;
   match?: Record<string, unknown>;
 }
-interface ApiResponse<T = unknown> {
-  success: boolean;
-  data?: T;
-  message?: string;
-}
-interface OffsetPaginationResponse<T = unknown> {
-  success: boolean;
-  method: 'offset';
-  docs: T[];
-  page: number;
-  limit: number;
-  total: number;
-  pages: number;
-  hasNext: boolean;
-  hasPrev: boolean;
-  warning?: string;
-}
-interface KeysetPaginationResponse<T = unknown> {
-  success: boolean;
-  method: 'keyset';
-  docs: T[];
-  limit: number;
-  hasMore: boolean;
-  next: string | null;
-}
-interface AggregatePaginationResponse<T = unknown> {
-  success: boolean;
-  method: 'aggregate';
-  docs: T[];
-  page: number;
-  limit: number;
-  total: number;
-  pages: number;
-  hasNext: boolean;
-  hasPrev: boolean;
-  warning?: string;
-}
-type PaginatedResponse<T = unknown> = OffsetPaginationResponse<T> | KeysetPaginationResponse<T> | AggregatePaginationResponse<T>;
-interface DeleteResponse {
-  success: boolean;
-  data?: {
-    message?: string;
-    id?: string;
-    soft?: boolean;
-  };
-}
-interface BulkCreateResponse<T = unknown> {
-  success: boolean;
-  data?: T[];
-  count?: number;
-}
-interface BulkUpdateResponse {
-  success: boolean;
-  modifiedCount?: number;
-}
-interface BulkDeleteResponse {
-  success: boolean;
-  deletedCount?: number;
-}
 type SortDirection = 1 | -1 | 'asc' | 'desc';
 type SortSpec = Record<string, SortDirection> | string;
-type FilterOperator = 'eq' | 'ne' | 'gt' | 'gte' | 'lt' | 'lte' | 'in' | 'nin' | 'contains' | 'startsWith' | 'endsWith' | 'regex' | 'like' | 'exists' | 'size' | 'type' | 'between' | 'near' | 'nearSphere' | 'geoWithin' | 'withinRadius';
+/**
+ * Filter operators supported by arc-next URL emission.
+ *
+ * Composes:
+ *  - **Canonical** ({@link BracketOperator}) — every operator repo-core's
+ *    `parseUrl` reverses. Cross-kit portable: mongokit, sqlitekit, prismakit,
+ *    and any future kit that consumes the canonical Filter IR all support
+ *    these out of the box.
+ *  - **Driver-specific extensions** — operators that require kit-native
+ *    support. Geo (`near`, `nearSphere`, `geoWithin`, `withinRadius`) is
+ *    mongokit + sqlitekit-spatialite. `size` / `type` are mongokit
+ *    array/BSON helpers. Hosts using kits without these features just
+ *    don't emit them; the union stays open with `(string & {})` so custom
+ *    domain operators still satisfy the type.
+ */
+type FilterOperator = BracketOperator$1 | 'size' | 'type' | 'near' | 'nearSphere' | 'geoWithin' | 'withinRadius' | (string & {});
 interface QueryParams {
   page?: number;
   limit?: number;
@@ -140,7 +99,7 @@ declare class BaseApi<TDoc = Record<string, unknown>, TCreate = Partial<TDoc>, T
     organizationId?: string | null;
     params?: QueryParams;
     options?: Omit<RequestOptions, 'token' | 'organizationId'>;
-  }): Promise<PaginatedResponse<TDoc>>;
+  }): Promise<PaginatedResult<TDoc>>;
   getById({
     token,
     organizationId,
@@ -156,7 +115,7 @@ declare class BaseApi<TDoc = Record<string, unknown>, TCreate = Partial<TDoc>, T
       populate?: string | string[];
     };
     options?: Omit<RequestOptions, 'token' | 'organizationId'>;
-  }): Promise<ApiResponse<TDoc>>;
+  }): Promise<TDoc>;
   create({
     token,
     organizationId,
@@ -167,7 +126,7 @@ declare class BaseApi<TDoc = Record<string, unknown>, TCreate = Partial<TDoc>, T
     organizationId?: string | null;
     data: TCreate;
     options?: Omit<RequestOptions, 'token' | 'organizationId'>;
-  }): Promise<ApiResponse<TDoc>>;
+  }): Promise<TDoc>;
   update({
     token,
     organizationId,
@@ -180,7 +139,7 @@ declare class BaseApi<TDoc = Record<string, unknown>, TCreate = Partial<TDoc>, T
     id: string;
     data: TUpdate;
     options?: Omit<RequestOptions, 'token' | 'organizationId'>;
-  }): Promise<ApiResponse<TDoc>>;
+  }): Promise<TDoc>;
   delete({
     token,
     organizationId,
@@ -191,7 +150,7 @@ declare class BaseApi<TDoc = Record<string, unknown>, TCreate = Partial<TDoc>, T
     organizationId?: string | null;
     id: string;
     options?: Omit<RequestOptions, 'token' | 'organizationId'>;
-  }): Promise<DeleteResponse>;
+  }): Promise<DeleteResult>;
   upload({
     token,
     organizationId,
@@ -203,7 +162,7 @@ declare class BaseApi<TDoc = Record<string, unknown>, TCreate = Partial<TDoc>, T
     data: FormData; /** Resource ID — shorthand for path, appended as `baseUrl/{id}/upload` */
     id?: string; /** Custom sub-path appended as `baseUrl/{path}`. Takes precedence over `id`. */
     path?: string;
-  }): Promise<ApiResponse<TDoc>>;
+  }): Promise<TDoc>;
   request<TResponse = unknown>(method: 'GET' | 'POST' | 'PATCH' | 'PUT' | 'DELETE', endpoint: string, {
     token,
     organizationId,
@@ -223,17 +182,18 @@ declare class BaseApi<TDoc = Record<string, unknown>, TCreate = Partial<TDoc>, T
    * Arc's escape hatch for endpoints that don't fit CRUD or actions.
    *
    * For aggregates / reports, prefer the response-aware {@link useApiQuery} hook
-   * (which auto-unwraps `{ success, data }`) and pass `invokeRoute` as the queryFn.
+   * and pass `invokeRoute` as the queryFn — arc 2.13+ emits raw payloads, so
+   * the response IS the data.
    *
    * @example
-   * // GET /todos/stats → { success, data: { total, byStatus } }
+   * // GET /todos/stats → { total, byStatus }
    * const stats = await api.invokeRoute<{ total: number; byStatus: Record<string, number> }>({
    *   method: 'GET',
    *   path: '/stats',
    * });
    *
    * // GET /todos/recent?limit=5 → paginated shape spread to root
-   * const recent = await api.invokeRoute<PaginatedResponse<Todo>>({
+   * const recent = await api.invokeRoute<PaginatedResult<Todo>>({
    *   method: 'GET',
    *   path: '/recent',
    *   params: { limit: 5 },
@@ -260,6 +220,30 @@ declare class BaseApi<TDoc = Record<string, unknown>, TCreate = Partial<TDoc>, T
     data?: unknown;
     params?: QueryParams;
   }): Promise<TResponse>;
+  /**
+   * Fetch a declared aggregation by name.
+   *
+   * @example
+   * const { rows } = await api.aggregate<{ day: string; total: number }>({
+   *   name: 'salesByDay',
+   *   filter: { from: '2025-01-01', to: '2025-12-31' },
+   * });
+   */
+  aggregate<TRow extends AggRow = AggRow>({
+    token,
+    organizationId,
+    name,
+    filter,
+    options
+  }: ScopedArgs & {
+    /** Aggregation name as declared on the resource. */name: string;
+    /**
+     * URL-encoded filter narrows + dimension args. Reserved keys (`page`,
+     * `limit`, etc.) are stripped server-side; everything else flows into
+     * the AggRequest filter via shallow merge with the host's base filter.
+     */
+    filter?: Record<string, unknown>;
+  }): Promise<AggResult<TRow>>;
   dispatchAction<TResult = unknown, TBody extends Record<string, unknown> = Record<string, unknown>>({
     token,
     organizationId,
@@ -271,12 +255,12 @@ declare class BaseApi<TDoc = Record<string, unknown>, TCreate = Partial<TDoc>, T
     id: string;
     action: string;
     data?: TBody;
-  }): Promise<ApiResponse<TResult>>;
+  }): Promise<TResult>;
 }
 declare function createCrudApi<TDoc = Record<string, unknown>, TCreate = Partial<TDoc>, TUpdate = Partial<TDoc>>(entity: string, config?: BaseApiConfig): BaseApi<TDoc, TCreate, TUpdate>;
-type ExtractDoc<T> = T extends PaginatedResponse<infer D> ? D : never;
-declare function isOffsetPagination<T>(response: PaginatedResponse<T>): response is OffsetPaginationResponse<T>;
-declare function isKeysetPagination<T>(response: PaginatedResponse<T>): response is KeysetPaginationResponse<T>;
-declare function isAggregatePagination<T>(response: PaginatedResponse<T>): response is AggregatePaginationResponse<T>;
+type ExtractDoc<T> = T extends PaginatedResult<infer D> ? D : never;
+declare function isOffsetPagination<T>(response: PaginatedResult<T>): response is OffsetPaginationResult<T>;
+declare function isKeysetPagination<T>(response: PaginatedResult<T>): response is KeysetPaginationResult<T>;
+declare function isAggregatePagination<T>(response: PaginatedResult<T>): response is AggregatePaginationResult<T>;
 //#endregion
-export { AggregatePaginationResponse, ApiResponse, BaseApi, BaseApiConfig, BulkCreateResponse, BulkDeleteResponse, BulkUpdateResponse, DeleteResponse, ExtractDoc, FilterOperator, KeysetPaginationResponse, OffsetPaginationResponse, PaginatedResponse, PopulateOption, QueryParams, RequestOptions, ScopedArgs, SortDirection, SortSpec, createCrudApi, isAggregatePagination, isKeysetPagination, isOffsetPagination };
+export { type AggResult, type AggRow, BaseApi, BaseApiConfig, type BracketOperator, type BulkCreateResult, type DeleteManyResult, type DeleteResult, ExtractDoc, FilterOperator, PopulateOption, QueryParams, RequestOptions, ScopedArgs, SortDirection, SortSpec, type UpdateManyResult, createCrudApi, isAggregatePagination, isKeysetPagination, isOffsetPagination };

package/dist/api.js

@@ -158,17 +158,18 @@ var BaseApi = class {
 	* Arc's escape hatch for endpoints that don't fit CRUD or actions.
 	*
 	* For aggregates / reports, prefer the response-aware {@link useApiQuery} hook
-	* (which auto-unwraps `{ success, data }`) and pass `invokeRoute` as the queryFn.
+	* and pass `invokeRoute` as the queryFn — arc 2.13+ emits raw payloads, so
+	* the response IS the data.
 	*
 	* @example
-	* // GET /todos/stats → { success, data: { total, byStatus } }
+	* // GET /todos/stats → { total, byStatus }
 	* const stats = await api.invokeRoute<{ total: number; byStatus: Record<string, number> }>({
 	*   method: 'GET',
 	*   path: '/stats',
 	* });
 	*
 	* // GET /todos/recent?limit=5 → paginated shape spread to root
-	* const recent = await api.invokeRoute<PaginatedResponse<Todo>>({
+	* const recent = await api.invokeRoute<PaginatedResult<Todo>>({
 	*   method: 'GET',
 	*   path: '/recent',
 	*   params: { limit: 5 },
@@ -193,6 +194,24 @@ var BaseApi = class {
 			options
 		});
 	}
+	/**
+	* Fetch a declared aggregation by name.
+	*
+	* @example
+	* const { rows } = await api.aggregate<{ day: string; total: number }>({
+	*   name: 'salesByDay',
+	*   filter: { from: '2025-01-01', to: '2025-12-31' },
+	* });
+	*/
+	async aggregate({ token = null, organizationId = null, name, filter, options = {} }) {
+		if (!name) throw new Error("Aggregation name is required");
+		const queryString = filter ? this.createQueryString(filter) : "";
+		const endpoint = `${this.baseUrl}/aggregations/${name}${queryString ? `?${queryString}` : ""}`;
+		const requestOptions = { ...options };
+		if (token) requestOptions.token = token;
+		if (organizationId) requestOptions.organizationId = organizationId;
+		return this.requestFn("GET", endpoint, this.withHeaders(requestOptions));
+	}
 	async dispatchAction({ token = null, organizationId = null, id, action, data, options = {} }) {
 		if (!id) throw new Error("ID is required");
 		if (!action) throw new Error("Action name is required");
@@ -212,13 +231,13 @@ function createCrudApi(entity, config = {}) {
 	return new BaseApi(entity, config);
 }
 function isOffsetPagination(response) {
-	return response.method === "offset";
+	return "method" in response && response.method === "offset";
 }
 function isKeysetPagination(response) {
-	return response.method === "keyset";
+	return "method" in response && response.method === "keyset";
 }
 function isAggregatePagination(response) {
-	return response.method === "aggregate";
+	return "method" in response && response.method === "aggregate";
 }
 
 //#endregion

package/dist/cache.d.ts

@@ -53,9 +53,10 @@ declare function normalizePagination(data: unknown): PaginationData | null;
  */
 declare function extractItems<T>(data: unknown): T[];
 /**
- * Strict detail extractor. Checks well-known keys (`data`, `doc`, `item`,
- * `result`); falls back to returning the response as-is. Primitive responses
- * (string/number/boolean) pass through.
+ * Detail extractor. Arc emits the doc directly (no envelope wrapper) — this
+ * function is identity-with-null-guard. Kept as a named helper so callers
+ * have a stable seam if a future backend ever ships an envelope, and so
+ * `null` / `undefined` responses normalize to `null` consistently.
  */
 declare function extractItem<T>(data: unknown): T | null;
 /**
@@ -64,6 +65,27 @@ declare function extractItem<T>(data: unknown): T | null;
  * the array length changes.
  */
 declare function updateListCache<T>(listData: unknown, updater: (items: T[]) => T[]): unknown;
+/**
+ * After a detail fetch lands, propagate the fresh values into every cached
+ * list entry that contains this item. The item's ID is resolved via
+ * `idField`, falling back to `_id` / `id`. Handles both flat list payloads
+ * and infinite-query page arrays.
+ *
+ * Only updates EXISTING list entries — never creates new caches or new items
+ * in lists. If the item moved between filter buckets (e.g. status changed),
+ * the relevant lists will refetch on their own; we don't try to predict
+ * filter membership.
+ *
+ * Returns the number of cache entries updated (useful for tests + telemetry).
+ *
+ * @param qc TanStack QueryClient
+ * @param listsKey Prefix key for this entity's lists (typically `KEYS.lists()`)
+ * @param item Fresh entity to merge into matching list items
+ * @param opts.idField Custom ID field name (defaults to `_id` / `id` lookup)
+ */
+declare function syncDetailToLists<TItem extends Record<string, unknown>>(qc: QueryClient, listsKey: QueryKey, item: TItem, opts?: {
+  idField?: string;
+}): number;
 interface QueryKeys {
   all: string[];
   lists: () => QueryKey;
@@ -74,6 +96,14 @@ interface QueryKeys {
   scopedDetail: (id: string, organizationId: string | null) => QueryKey;
   custom: (key: string, ...args: unknown[]) => QueryKey;
   scopedList: (scope: string, params?: unknown) => QueryKey;
+  /** Prefix for every aggregation on this resource — invalidate all at once. */
+  aggregations: () => QueryKey;
+  /**
+   * Aggregation key (`arc 2.13+ /aggregations/:name`). The `filter` arg is
+   * structurally hashed by TanStack — pass the same object identity (or
+   * structurally identical) you pass to `useAggregation` so the cache hits.
+   */
+  aggregation: (name: string, filter?: unknown) => QueryKey;
 }
 /**
  * Build a hierarchical query-key factory for a resource. The returned shape
@@ -97,12 +127,26 @@ interface CacheUtils<T> {
   getScopedDetail: (client: QueryClient, id: string, organizationId: string | null) => T | undefined;
   /** Remove tenant-scoped detail from cache. */
   removeScopedDetail: (client: QueryClient, id: string, organizationId: string | null) => void;
+  /**
+   * Invalidate every aggregation for this resource. Call from mutation
+   * `onSuccess` so dashboards refresh after CRUD writes.
+   *
+   * For targeted invalidation of a single aggregation pass the name —
+   * prefix-matches every parameterized variant.
+   */
+  invalidateAggregations: (client: QueryClient, name?: string) => Promise<void>;
 }
 /**
  * Build cache read/write/invalidate helpers bound to the given key factory.
  * Server-safe — operates on a `QueryClient` instance which can be a per-request
  * server client (during prefetch) or the browser singleton.
+ *
+ * **Wire shape:** Arc 2.13+ emits raw documents on `GET /:resource/:id` — no
+ * `{ data: ... }` envelope. `setDetail` / `getDetail` write and read the raw
+ * doc directly so the cache shape matches `useDetail`'s `queryFn` output,
+ * `useNavigation`'s pre-populated entries, and `prefetchDetail`'s server seed.
+ * All four paths converge on the same shape: TDoc, not `{ data: TDoc }`.
  */
 declare function createCacheUtils<T>(KEYS: QueryKeys): CacheUtils<T>;
 //#endregion
-export { CacheUtils, DEFAULT_QUERY_CONFIG, PaginationData, QUERY_CONFIGS, QueryKeys, createCacheUtils, createQueryKeys, extractItem, extractItems, getItemId, normalizePagination, updateListCache };
+export { CacheUtils, DEFAULT_QUERY_CONFIG, PaginationData, QUERY_CONFIGS, QueryKeys, createCacheUtils, createQueryKeys, extractItem, extractItems, getItemId, normalizePagination, syncDetailToLists, updateListCache };