@classytic/arc-next 0.4.1 → 0.5.0

package/dist/presets/slug.js

@@ -0,0 +1,27 @@
+//#region src/presets/slug.ts
+/**
+* Adds slug-lookup preset methods to a BaseApi.
+*
+* Mirrors arc's `slugLookup` preset — exposes `getBySlug` for resources keyed
+* by URL-friendly slugs alongside the canonical id.
+*
+* @example
+* import { withSlugLookup } from '@classytic/arc-next/presets/slug';
+* const categories = withSlugLookup(createCrudApi<Category>('categories'));
+*
+* const cat = await categories.getBySlug({ slug: 'engineering' });
+*/
+function withSlugLookup(api) {
+	return Object.assign(api, { async getBySlug({ token = null, organizationId = null, slug, params = {}, options = {} }) {
+		if (!slug) throw new Error("Slug is required");
+		return api.request("GET", `${api.baseUrl}/slug/${slug}`, {
+			token,
+			organizationId,
+			params,
+			options
+		});
+	} });
+}
+
+//#endregion
+export { withSlugLookup };

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

@@ -0,0 +1,33 @@
+import { ApiResponse, BaseApi, PaginatedResponse, QueryParams, ScopedArgs } from "../api.js";
+
+//#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>>;
+  /** Undo a soft-delete. Backend mounts `POST /:resource/:id/restore`. */
+  restore(args: ScopedArgs & {
+    id: string;
+  }): Promise<ApiResponse<TDoc>>;
+}
+/**
+ * Adds soft-delete preset methods to a BaseApi.
+ *
+ * Mirrors arc's server-side `softDelete` preset routes. Use when your resource
+ * is registered with `presets: ['softDelete']`. With this preset, `delete()`
+ * becomes soft-delete on the backend and {@link SoftDeleteMethods.restore}
+ * undoes it; {@link SoftDeleteMethods.getDeleted} lists the tombstones.
+ *
+ * @example
+ * import { createCrudApi } from '@classytic/arc-next/api';
+ * import { withSoftDelete } from '@classytic/arc-next/presets/soft-delete';
+ *
+ * const todos = withSoftDelete(createCrudApi<Todo>('todos'));
+ * await todos.delete({ id });             // soft delete (backend)
+ * await todos.restore({ id });            // undo
+ * const trash = await todos.getDeleted();
+ */
+declare function withSoftDelete<TDoc, TCreate, TUpdate>(api: BaseApi<TDoc, TCreate, TUpdate>): BaseApi<TDoc, TCreate, TUpdate> & SoftDeleteMethods<TDoc>;
+//#endregion
+export { SoftDeleteMethods, withSoftDelete };

package/dist/presets/soft-delete.js

@@ -0,0 +1,45 @@
+//#region src/presets/soft-delete.ts
+/**
+* Adds soft-delete preset methods to a BaseApi.
+*
+* Mirrors arc's server-side `softDelete` preset routes. Use when your resource
+* is registered with `presets: ['softDelete']`. With this preset, `delete()`
+* becomes soft-delete on the backend and {@link SoftDeleteMethods.restore}
+* undoes it; {@link SoftDeleteMethods.getDeleted} lists the tombstones.
+*
+* @example
+* import { createCrudApi } from '@classytic/arc-next/api';
+* import { withSoftDelete } from '@classytic/arc-next/presets/soft-delete';
+*
+* const todos = withSoftDelete(createCrudApi<Todo>('todos'));
+* await todos.delete({ id });             // soft delete (backend)
+* await todos.restore({ id });            // undo
+* const trash = await todos.getDeleted();
+*/
+function withSoftDelete(api) {
+	return Object.assign(api, {
+		async getDeleted({ token = null, organizationId = null, params = {}, options = {} } = {}) {
+			const merged = {
+				...api.config.defaultParams,
+				...params
+			};
+			return api.request("GET", `${api.baseUrl}/deleted`, {
+				token,
+				organizationId,
+				params: merged,
+				options
+			});
+		},
+		async restore({ token = null, organizationId = null, id, options = {} }) {
+			if (!id) throw new Error("ID is required");
+			return api.request("POST", `${api.baseUrl}/${id}/restore`, {
+				token,
+				organizationId,
+				options
+			});
+		}
+	});
+}
+
+//#endregion
+export { withSoftDelete };

package/dist/presets/tree.d.ts

@@ -0,0 +1,31 @@
+import { ApiResponse, BaseApi, PaginatedResponse, QueryParams, ScopedArgs } from "../api.js";
+
+//#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[]>>;
+  /** Fetch direct children of a node. Backend mounts `GET /:resource/:id/children`. */
+  getChildren(args: ScopedArgs & {
+    parentId: string;
+    params?: QueryParams;
+  }): Promise<PaginatedResponse<TDoc>>;
+}
+/**
+ * Adds tree preset methods to a BaseApi.
+ *
+ * Mirrors arc's `tree` preset — for resources with a `parentId` field, exposes
+ * `getTree` (full hierarchy) and `getChildren` (one level deep). Backend caps
+ * tree depth via the preset config.
+ *
+ * @example
+ * import { withTree } from '@classytic/arc-next/presets/tree';
+ * const categories = withTree(createCrudApi<Category>('categories'));
+ *
+ * const root = await categories.getTree();
+ * const kids = await categories.getChildren({ parentId: 'engineering' });
+ */
+declare function withTree<TDoc, TCreate, TUpdate>(api: BaseApi<TDoc, TCreate, TUpdate>): BaseApi<TDoc, TCreate, TUpdate> & TreeMethods<TDoc>;
+//#endregion
+export { TreeMethods, withTree };

package/dist/presets/tree.js

@@ -0,0 +1,47 @@
+//#region src/presets/tree.ts
+/**
+* Adds tree preset methods to a BaseApi.
+*
+* Mirrors arc's `tree` preset — for resources with a `parentId` field, exposes
+* `getTree` (full hierarchy) and `getChildren` (one level deep). Backend caps
+* tree depth via the preset config.
+*
+* @example
+* import { withTree } from '@classytic/arc-next/presets/tree';
+* const categories = withTree(createCrudApi<Category>('categories'));
+*
+* const root = await categories.getTree();
+* const kids = await categories.getChildren({ parentId: 'engineering' });
+*/
+function withTree(api) {
+	return Object.assign(api, {
+		async getTree({ token = null, organizationId = null, params = {}, options = {} } = {}) {
+			const merged = {
+				...api.config.defaultParams,
+				...params
+			};
+			return api.request("GET", `${api.baseUrl}/tree`, {
+				token,
+				organizationId,
+				params: merged,
+				options
+			});
+		},
+		async getChildren({ token = null, organizationId = null, parentId, params = {}, options = {} }) {
+			if (!parentId) throw new Error("Parent ID is required");
+			const merged = {
+				...api.config.defaultParams,
+				...params
+			};
+			return api.request("GET", `${api.baseUrl}/${parentId}/children`, {
+				token,
+				organizationId,
+				params: merged,
+				options
+			});
+		}
+	});
+}
+
+//#endregion
+export { withTree };

package/dist/query.d.ts

@@ -1,18 +1,7 @@
-import { InfiniteData, QueryClient, QueryKey } from "@tanstack/react-query";
+import { CacheUtils, DEFAULT_QUERY_CONFIG, PaginationData, QUERY_CONFIGS, QueryKeys, createCacheUtils, createQueryKeys, extractItem, extractItems, getItemId, normalizePagination, updateListCache } from "./cache.js";
+import { InfiniteData, QueryKey } from "@tanstack/react-query";
 
 //#region src/query.d.ts
-interface PaginationData {
-  /** Pagination method detected from response (offset | keyset | aggregate) */
-  method: 'offset' | 'keyset' | 'aggregate' | null;
-  total: number;
-  pages: number;
-  page: number;
-  limit: number;
-  hasNext: boolean;
-  hasPrev: boolean;
-  /** Keyset cursor for next page (keyset pagination only) */
-  next?: string | null;
-}
 /** Request-level options passed through to the fetch call */
 interface RequestPassthrough {
   cache?: RequestCache;
@@ -80,61 +69,6 @@ interface DetailQueryResult<T> {
   refetch: () => Promise<unknown>;
   data: unknown;
 }
-interface QueryKeys {
-  all: string[];
-  lists: () => QueryKey;
-  list: (params?: unknown) => QueryKey;
-  details: () => QueryKey;
-  detail: (id: string) => QueryKey;
-  /** Tenant-scoped detail key. Use when IDs are only unique within an org. */
-  scopedDetail: (id: string, organizationId: string | null) => QueryKey;
-  custom: (key: string, ...args: unknown[]) => QueryKey;
-  scopedList: (scope: string, params?: unknown) => QueryKey;
-}
-interface CacheUtils<T> {
-  invalidateAll: (client: QueryClient) => Promise<void>;
-  invalidateLists: (client: QueryClient) => Promise<void>;
-  /** Invalidate detail by ID (prefix-matches all scoped/parameterized variants). */
-  invalidateDetail: (client: QueryClient, id: string) => Promise<void>;
-  setDetail: (client: QueryClient, id: string, data: T) => void;
-  getDetail: (client: QueryClient, id: string) => T | undefined;
-  removeDetail: (client: QueryClient, id: string) => void;
-  /** Invalidate tenant-scoped detail (prefix-matches parameterized variants within org). */
-  invalidateScopedDetail: (client: QueryClient, id: string, organizationId: string | null) => Promise<void>;
-  /** Set tenant-scoped detail cache. */
-  setScopedDetail: (client: QueryClient, id: string, organizationId: string | null, data: T) => void;
-  /** Get tenant-scoped detail from cache. */
-  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;
-}
-declare const DEFAULT_QUERY_CONFIG: {
-  readonly staleTime: number;
-  readonly gcTime: number;
-  readonly refetchOnWindowFocus: false;
-  readonly retry: 0;
-};
-/** Pre-built query config presets for common data freshness patterns. */
-declare const QUERY_CONFIGS: {
-  /** Live data: 20s stale, 30s polling */readonly realtime: {
-    readonly staleTime: 20000;
-    readonly refetchInterval: 30000;
-  }; /** Frequently updated: 60s stale */
-  readonly frequent: {
-    readonly staleTime: 60000;
-  }; /** Stable data: 5min stale (same as default) */
-  readonly stable: {
-    readonly staleTime: 300000;
-  }; /** Rarely changes: 10min stale */
-  readonly static: {
-    readonly staleTime: 600000;
-  };
-};
-declare function getItemId(item: unknown): string | null;
-declare function extractItem<T>(data: unknown): T | null;
-declare function updateListCache<T>(listData: unknown, updater: (items: T[]) => T[]): unknown;
-declare function createQueryKeys(entityKey: string): QueryKeys;
-declare function createCacheUtils<T>(KEYS: QueryKeys): CacheUtils<T>;
 interface CreateListQueryConfig {
   queryKey: QueryKey;
   queryFn: (context: {
@@ -232,5 +166,88 @@ declare function useInfiniteListQuery<T>({
   getPreviousPageParam,
   maxPages
 }: CreateInfiniteListQueryConfig): InfiniteListQueryResult<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.
+ */
+type ExtractData<T> = T extends {
+  success: unknown;
+  data: infer D;
+} ? D : T;
+/** Per-call request pass-through and TanStack Query overrides. */
+interface UseApiQueryOptions {
+  staleTime?: number;
+  gcTime?: number;
+  refetchOnWindowFocus?: boolean;
+  refetchInterval?: number | false;
+  refetchIntervalInBackground?: boolean;
+  retry?: boolean | number;
+  /** Limit re-renders to changes in these specific fields (perf optimization). */
+  notifyOnChangeProps?: ('data' | 'error' | 'isLoading' | 'isFetching' | 'isError' | 'isSuccess' | 'isStale')[];
+}
+interface UseApiQueryConfig<TResponse, TData> {
+  queryKey: QueryKey;
+  queryFn: (context: {
+    signal: AbortSignal;
+  }) => Promise<TResponse>;
+  enabled?: boolean;
+  /** 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.
+   */
+  select?: (response: TResponse) => TData;
+  /** TanStack Query overrides (staleTime, refetchInterval, retry, etc.). */
+  options?: UseApiQueryOptions;
+}
+interface UseApiQueryResult<TData> {
+  data: TData | null;
+  isLoading: boolean;
+  isFetching: boolean;
+  isError: boolean;
+  isSuccess: boolean;
+  isStale: boolean;
+  error: Error | null;
+  refetch: () => Promise<unknown>;
+}
+/**
+ * Generic query hook for non-CRUD reads (reports, aggregates, lookups, RPC-style
+ * endpoints). Wraps TanStack Query with three 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' |
+ *    'static'` to map onto `QUERY_CONFIGS`. Per-option overrides still win.
+ * 3. **Standardized result shape.** `{ data, isLoading, isFetching, isError,
+ *    isSuccess, isStale, error, refetch }` — same contract as the CRUD hooks.
+ *
+ * @example
+ * // Auto-unwrap envelope
+ * const { data } = useApiQuery<ApiResponse<DashboardStats>>({
+ *   queryKey: ['dashboard', 'stats'],
+ *   queryFn: ({ signal }) => api.request('GET', '/dashboard/stats', { options: { signal } }),
+ *   freshness: 'realtime',
+ * });
+ *
+ * // Custom projection
+ * const { data } = useApiQuery({
+ *   queryKey: ['ledger', accountId],
+ *   queryFn: ({ signal }) => api.request('GET', `/ledger/${accountId}`, { options: { signal } }),
+ *   select: (res) => res.data?.entries ?? [],
+ * });
+ */
+declare function useApiQuery<TResponse = unknown, TData = ExtractData<TResponse>>({
+  queryKey,
+  queryFn,
+  enabled,
+  freshness,
+  select,
+  options
+}: UseApiQueryConfig<TResponse, TData>): UseApiQueryResult<TData>;
 //#endregion
-export { CacheUtils, CreateDetailQueryConfig, CreateInfiniteListQueryConfig, CreateListQueryConfig, DEFAULT_QUERY_CONFIG, DetailQueryOptions, DetailQueryResult, InfiniteListQueryOptions, InfiniteListQueryResult, ListQueryOptions, ListQueryResult, PaginationData, QUERY_CONFIGS, QueryKeys, RequestPassthrough, createCacheUtils, createQueryKeys, extractItem, getItemId, updateListCache, useDetailQuery, useInfiniteListQuery, useListQuery };
+export { type CacheUtils, CreateDetailQueryConfig, CreateInfiniteListQueryConfig, CreateListQueryConfig, DEFAULT_QUERY_CONFIG, DetailQueryOptions, DetailQueryResult, ExtractData, InfiniteListQueryOptions, InfiniteListQueryResult, ListQueryOptions, ListQueryResult, type PaginationData, QUERY_CONFIGS, QueryFreshness, type QueryKeys, RequestPassthrough, UseApiQueryConfig, UseApiQueryOptions, UseApiQueryResult, createCacheUtils, createQueryKeys, extractItem, extractItems, getItemId, normalizePagination, updateListCache, useApiQuery, useDetailQuery, useInfiniteListQuery, useListQuery };

package/dist/query.js

@@ -1,168 +1,10 @@
 "use client";
 
+import { DEFAULT_QUERY_CONFIG, QUERY_CONFIGS, createCacheUtils, createQueryKeys, extractItem, extractItems, getItemId, normalizePagination, updateListCache } from "./cache.js";
 import { keepPreviousData, useInfiniteQuery, useQuery, useQueryClient } from "@tanstack/react-query";
-import { useEffect, useMemo } from "react";
+import { useCallback, useEffect, useMemo, useRef } from "react";
 
 //#region src/query.ts
-const DEFAULT_QUERY_CONFIG = {
-	staleTime: 300 * 1e3,
-	gcTime: 1800 * 1e3,
-	refetchOnWindowFocus: false,
-	retry: 0
-};
-/** Pre-built query config presets for common data freshness patterns. */
-const QUERY_CONFIGS = {
-	realtime: {
-		staleTime: 2e4,
-		refetchInterval: 3e4
-	},
-	frequent: { staleTime: 6e4 },
-	stable: { staleTime: 3e5 },
-	static: { staleTime: 6e5 }
-};
-function getItemId(item) {
-	if (!item || typeof item !== "object") return null;
-	const obj = item;
-	const id = obj._id ?? obj.id;
-	return typeof id === "string" ? id : id ? String(id) : null;
-}
-function normalizePagination(data) {
-	if (!data || typeof data !== "object") return null;
-	const d = data;
-	const method = d.method ?? null;
-	const isKeyset = method === "keyset" || d.hasMore != null && d.total == null && d.pages == null;
-	const hasTotal = d.total != null || d.totalDocs != null;
-	const hasPages = d.pages != null || d.totalPages != null;
-	if (!hasTotal && !hasPages && !isKeyset) return null;
-	return {
-		method,
-		total: Number(d.total ?? d.totalDocs ?? 0),
-		pages: Number(d.pages ?? d.totalPages ?? (isKeyset ? 0 : 1)),
-		page: Number(d.page ?? d.currentPage ?? (isKeyset ? 0 : 1)),
-		limit: Number(d.limit ?? 10),
-		hasNext: Boolean(d.hasNext ?? d.hasNextPage ?? d.hasMore ?? false),
-		hasPrev: Boolean(d.hasPrev ?? d.hasPrevPage ?? false),
-		...isKeyset ? { next: d.next ?? null } : {}
-	};
-}
-/** Well-known keys checked in order for list responses. */
-const LIST_KEYS = [
-	"docs",
-	"data",
-	"items",
-	"results"
-];
-/** Well-known keys checked in order for detail responses. */
-const DETAIL_KEYS = [
-	"data",
-	"doc",
-	"item",
-	"result"
-];
-function extractItems(data) {
-	if (!data) return [];
-	if (Array.isArray(data)) return data;
-	if (typeof data !== "object") return [];
-	const d = data;
-	for (const key of LIST_KEYS) if (Array.isArray(d[key])) return d[key];
-	for (const value of Object.values(d)) if (Array.isArray(value)) return value;
-	return [];
-}
-function extractItem(data) {
-	if (data == null) return null;
-	if (typeof data !== "object") return data;
-	const d = data;
-	for (const key of DETAIL_KEYS) if (d[key] != null) return d[key];
-	return d;
-}
-function updateListCache(listData, updater) {
-	if (!listData) return listData;
-	if (Array.isArray(listData)) return updater(listData);
-	if (typeof listData !== "object") return listData;
-	const d = listData;
-	let arrayField = null;
-	for (const key of LIST_KEYS) if (Array.isArray(d[key])) {
-		arrayField = key;
-		break;
-	}
-	if (!arrayField) {
-		for (const [key, value] of Object.entries(d)) if (Array.isArray(value)) {
-			arrayField = key;
-			break;
-		}
-	}
-	if (!arrayField) return listData;
-	const updated = updater(d[arrayField]);
-	const original = d[arrayField];
-	const delta = updated.length - original.length;
-	const result = {
-		...d,
-		[arrayField]: updated
-	};
-	if (delta !== 0) {
-		if (d.total != null) result.total = Math.max(0, Number(d.total) + delta);
-		if (d.totalDocs != null) result.totalDocs = Math.max(0, Number(d.totalDocs) + delta);
-	}
-	return result;
-}
-function createQueryKeys(entityKey) {
-	return {
-		all: [entityKey],
-		lists: () => [entityKey, "list"],
-		list: (params) => [
-			entityKey,
-			"list",
-			params
-		],
-		details: () => [entityKey, "detail"],
-		detail: (id) => [
-			entityKey,
-			"detail",
-			id
-		],
-		scopedDetail: (id, organizationId) => organizationId ? [
-			entityKey,
-			"detail",
-			id,
-			{ _org: organizationId }
-		] : [
-			entityKey,
-			"detail",
-			id
-		],
-		custom: (key, ...args) => [
-			entityKey,
-			key,
-			...args
-		],
-		scopedList: (scope, params) => [
-			entityKey,
-			"list",
-			{
-				_scope: scope,
-				...params
-			}
-		]
-	};
-}
-function createCacheUtils(KEYS) {
-	return {
-		invalidateAll: (client) => client.invalidateQueries({ queryKey: KEYS.all }),
-		invalidateLists: (client) => client.invalidateQueries({ queryKey: KEYS.lists() }),
-		invalidateDetail: (client, id) => client.invalidateQueries({ queryKey: KEYS.detail(id) }),
-		setDetail: (client, id, data) => client.setQueryData(KEYS.detail(id), { data }),
-		getDetail: (client, id) => {
-			return client.getQueryData(KEYS.detail(id))?.data;
-		},
-		removeDetail: (client, id) => client.removeQueries({ queryKey: KEYS.detail(id) }),
-		invalidateScopedDetail: (client, id, organizationId) => client.invalidateQueries({ queryKey: KEYS.scopedDetail(id, organizationId) }),
-		setScopedDetail: (client, id, organizationId, data) => client.setQueryData(KEYS.scopedDetail(id, organizationId), { data }),
-		getScopedDetail: (client, id, organizationId) => {
-			return client.getQueryData(KEYS.scopedDetail(id, organizationId))?.data;
-		},
-		removeScopedDetail: (client, id, organizationId) => client.removeQueries({ queryKey: KEYS.scopedDetail(id, organizationId) })
-	};
-}
 function useListQuery({ queryKey, queryFn, enabled = true, options = {}, prefillDetailCache = true, detailKeyBuilder, itemIdResolver, select }) {
 	const queryClient = useQueryClient();
 	const query = useQuery({
@@ -255,6 +97,72 @@ function useInfiniteListQuery({ queryKey, queryFn, enabled = true, options = {},
 		data: query.data
 	};
 }
+/**
+* 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:
+*
+* 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' |
+*    'static'` to map onto `QUERY_CONFIGS`. Per-option overrides still win.
+* 3. **Standardized result shape.** `{ data, isLoading, isFetching, isError,
+*    isSuccess, isStale, error, refetch }` — same contract as the CRUD hooks.
+*
+* @example
+* // Auto-unwrap envelope
+* const { data } = useApiQuery<ApiResponse<DashboardStats>>({
+*   queryKey: ['dashboard', 'stats'],
+*   queryFn: ({ signal }) => api.request('GET', '/dashboard/stats', { options: { signal } }),
+*   freshness: 'realtime',
+* });
+*
+* // Custom projection
+* const { data } = useApiQuery({
+*   queryKey: ['ledger', accountId],
+*   queryFn: ({ signal }) => api.request('GET', `/ledger/${accountId}`, { options: { signal } }),
+*   select: (res) => res.data?.entries ?? [],
+* });
+*/
+function useApiQuery({ queryKey, queryFn, enabled = true, freshness, select, options = {} }) {
+	const selectRef = useRef(select);
+	selectRef.current = select;
+	const projection = useCallback((response) => {
+		const fn = selectRef.current;
+		if (fn) return fn(response);
+		return isArcEnvelope(response) ? response.data : response;
+	}, []);
+	const preset = freshness ? QUERY_CONFIGS[freshness] : void 0;
+	const query = useQuery({
+		queryKey,
+		queryFn: ({ signal }) => queryFn({ signal }),
+		enabled,
+		...DEFAULT_QUERY_CONFIG,
+		...preset,
+		...options,
+		select: projection
+	});
+	return {
+		data: query.data ?? null,
+		isLoading: query.isLoading,
+		isFetching: query.isFetching,
+		isError: query.isError,
+		isSuccess: query.isSuccess,
+		isStale: query.isStale,
+		error: query.error,
+		refetch: query.refetch
+	};
+}
 
 //#endregion
-export { DEFAULT_QUERY_CONFIG, QUERY_CONFIGS, createCacheUtils, createQueryKeys, extractItem, getItemId, updateListCache, useDetailQuery, useInfiniteListQuery, useListQuery };
+export { DEFAULT_QUERY_CONFIG, QUERY_CONFIGS, createCacheUtils, createQueryKeys, extractItem, extractItems, getItemId, normalizePagination, updateListCache, useApiQuery, useDetailQuery, useInfiniteListQuery, useListQuery };