@classytic/arc-next 0.5.0 → 0.6.0

package/README.md

@@ -97,19 +97,19 @@ All mutations are optimistic with automatic rollback on error. Lists prefill the
 
 ### `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 +126,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({

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;
 /**
@@ -74,6 +75,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,6 +106,14 @@ 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.

package/dist/cache.js

@@ -7,28 +7,32 @@ const DEFAULT_QUERY_CONFIG = {
 };
 /** Pre-built query config presets for common data freshness patterns. */
 const QUERY_CONFIGS = {
+	/** Live data: 20s stale, 30s polling */
 	realtime: {
 		staleTime: 2e4,
 		refetchInterval: 3e4
 	},
+	/** Frequently updated: 60s stale */
 	frequent: { staleTime: 6e4 },
+	/** Stable data: 5min stale (same as default) */
 	stable: { staleTime: 3e5 },
+	/** Rarely changes: 10min stale */
 	static: { staleTime: 6e5 }
 };
-/** Well-known keys checked in order for list responses. */
+/**
+* Well-known keys checked in order for list responses.
+*
+* Arc emits `{data: T[]}` for both paginated and bare-list endpoints, so
+* `docs` is the canonical key. `items` / `results` cover non-arc backends
+* the permissive detector still supports — the any-array fallback below
+* keeps `{products: [...]}` / `{users: [...]}` working without per-resource
+* configuration.
+*/
 const LIST_KEYS = [
-	"docs",
 	"data",
 	"items",
 	"results"
 ];
-/** Well-known keys checked in order for detail responses. */
-const DETAIL_KEYS = [
-	"data",
-	"doc",
-	"item",
-	"result"
-];
 /**
 * Extract `_id` or `id` from any item. Returns `null` if neither exists.
 * Coerces numeric IDs to strings so cache keys stay consistent.
@@ -78,16 +82,14 @@ function extractItems(data) {
 	return [];
 }
 /**
-* 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.
 */
 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;
+	return data;
 }
 /**
 * Optimistic-update helper that mutates the items array of a list cache
@@ -166,6 +168,17 @@ function createQueryKeys(entityKey) {
 				_scope: scope,
 				...params
 			}
+		],
+		aggregations: () => [entityKey, "aggregation"],
+		aggregation: (name, filter) => filter !== void 0 ? [
+			entityKey,
+			"aggregation",
+			name,
+			filter
+		] : [
+			entityKey,
+			"aggregation",
+			name
 		]
 	};
 }
@@ -189,7 +202,8 @@ function createCacheUtils(KEYS) {
 		getScopedDetail: (client, id, organizationId) => {
 			return client.getQueryData(KEYS.scopedDetail(id, organizationId))?.data;
 		},
-		removeScopedDetail: (client, id, organizationId) => client.removeQueries({ queryKey: KEYS.scopedDetail(id, organizationId) })
+		removeScopedDetail: (client, id, organizationId) => client.removeQueries({ queryKey: KEYS.scopedDetail(id, organizationId) }),
+		invalidateAggregations: (client, name) => client.invalidateQueries({ queryKey: name ? KEYS.aggregation(name) : KEYS.aggregations() })
 	};
 }