@classytic/arc-next 0.5.0 → 0.6.0

package/dist/client.d.ts

@@ -1,3 +1,5 @@
+import { ErrorDetail } from "@classytic/repo-core/errors";
+
 //#region src/client.d.ts
 interface ToastHandler {
   success: (message: string) => void;
@@ -12,39 +14,33 @@ type UseRouterHook = () => {
   }) => void;
 };
 /**
- * Top-level error codes arc's `errorHandlerPlugin` emits on the response root
- * (`json.code`). Mirrors `statusCodeToCode()` + the special `VALIDATION_ERROR`
- * / `DUPLICATE_KEY` / `INTERNAL_ERROR` branches.
+ * Canonical error codes arc and repo-core emit on `json.code`. Single
+ * top-level slot — arc 2.13's `createError` lifts business codes from
+ * `details` to top-level so `repo-core`'s `toErrorContract` round-trips
+ * them on the wire. There is no separate `detailsCode` slot; everything
+ * lives at `error.code`.
  *
- * Open via intersection with `(string & {})` so unknown codes from custom
- * `errorMappers` / `errorMap` still satisfy the type.
- */
-/**
- * Top-level HTTP-status error codes arc's `errorHandlerPlugin` emits on
- * `json.code`. Exported as a `const` array first so callers get both
- * compile-time exhaustiveness AND runtime iteration (e.g. building a
- * client-side i18n lookup, or whitelisting which codes get retried).
- */
-declare const KNOWN_TOP_LEVEL_CODES: readonly ["BAD_REQUEST", "UNAUTHORIZED", "FORBIDDEN", "NOT_FOUND", "METHOD_NOT_ALLOWED", "CONFLICT", "UNPROCESSABLE_ENTITY", "RATE_LIMITED", "INTERNAL_ERROR", "BAD_GATEWAY", "SERVICE_UNAVAILABLE", "GATEWAY_TIMEOUT", "VALIDATION_ERROR", "DUPLICATE_KEY", "DOMAIN_ERROR"];
-/**
- * Top-level HTTP-status error code union derived from {@link KNOWN_TOP_LEVEL_CODES}.
- * `(string & {})` keeps the type open so non-arc backends or custom error mappers
- * still satisfy it.
- */
-type ArcTopLevelErrorCode = (typeof KNOWN_TOP_LEVEL_CODES)[number] | (string & {});
-/**
- * Nested business-logic codes arc's mixins / preset routes / org guards emit
- * on `json.details.code`. These are distinct from the HTTP-status code above —
- * `error.code` (top-level) vs `error.detailsCode` (nested). When a route
- * returns 403 with `details.code: 'ORG_CONTEXT_REQUIRED'`, hosts read
- * `detailsCode` to disambiguate "missing org context" from "permission denied".
+ * Three families compose this list:
+ *  1. **repo-core canonical** (`validation_error`, `not_found`, ...) — RFC 7807
+ *     / Stripe-shaped lowercase + snake_case. Cross-package universals.
+ *  2. **arc hierarchical** (`arc.forbidden`, `arc.validation_error`,
+ *     `arc.org.access_denied`, ...) — what arc's `errorHandlerPlugin`
+ *     emits for HTTP-status throws + arc-classified errors.
+ *  3. **arc business** (`ORG_CONTEXT_REQUIRED`, `ALL_FIELDS_STRIPPED`,
+ *     `OWNERSHIP_DENIED`, ...) — emitted by mixins / org guards via
+ *     `createError(status, msg, { code })`. The UPPER_SNAKE form is
+ *     intentional: these are reason codes, not HTTP-status codes.
+ *
+ * `(string & {})` keeps the type open so domain packages and custom
+ * `errorMappers` codes still satisfy it.
  */
-declare const KNOWN_DETAILS_CODES: readonly ["ORG_CONTEXT_REQUIRED", "ORG_ROLE_REQUIRED", "OWNERSHIP_DENIED", "MIXED_UPDATE_SHAPE", "ALL_FIELDS_STRIPPED", "BEFORE_RESTORE_HOOK_ERROR"];
+declare const KNOWN_ARC_ERROR_CODES: readonly ["validation_error", "not_found", "conflict", "unauthorized", "forbidden", "rate_limited", "idempotency_conflict", "precondition_failed", "internal_error", "service_unavailable", "timeout", "arc.bad_request", "arc.unauthorized", "arc.forbidden", "arc.not_found", "arc.conflict", "arc.unprocessable_entity", "arc.rate_limited", "arc.internal_error", "arc.bad_gateway", "arc.service_unavailable", "arc.gateway_timeout", "arc.validation_error", "arc.invalid_id", "arc.org.selection_required", "arc.org.access_denied", "ORG_CONTEXT_REQUIRED", "ORG_ROLE_REQUIRED", "OWNERSHIP_DENIED", "MIXED_UPDATE_SHAPE", "ALL_FIELDS_STRIPPED", "BEFORE_RESTORE_HOOK_ERROR", "duplicate_key"];
 /**
- * Nested business-logic error code union derived from {@link KNOWN_DETAILS_CODES}.
- * Same `(string & {})` escape hatch as {@link ArcTopLevelErrorCode}.
+ * Canonical arc error code union. `(string & {})` keeps the type open so
+ * domain packages can extend hierarchically (`'order.cart.locked'`,
+ * `'payment.gateway.timeout'`) and still satisfy the type.
  */
-type ArcDetailsErrorCode = (typeof KNOWN_DETAILS_CODES)[number] | (string & {});
+type ArcErrorCode = (typeof KNOWN_ARC_ERROR_CODES)[number] | (string & {});
 interface ArcApiErrorOptions {
   status: number;
   statusText: string;
@@ -74,39 +70,36 @@ declare class ArcApiError extends Error {
   readonly method: HttpMethod;
   constructor(message: string, options: ArcApiErrorOptions);
   /**
-   * Top-level error code from arc's response envelope (`json.code`).
+   * Canonical error code from arc's wire envelope (`json.code`).
    *
-   * One of {@link ArcTopLevelErrorCode} — covers HTTP-status codes (`FORBIDDEN`,
-   * `CONFLICT`...) plus the dedicated `VALIDATION_ERROR` / `DUPLICATE_KEY`
-   * branches arc emits. Returns `null` if the response carries no envelope.
+   * Arc 2.13 + `repo-core` 0.4 emit one canonical {@link ErrorContract}
+   * shape — `{ code, message, status, details? }` — with the business
+   * code at top-level. Hosts switch on `error.code` directly:
    *
    * @example
-   * if (error.code === 'DUPLICATE_KEY') showRetryAsAdmin();
+   * if (error.code === 'ORG_CONTEXT_REQUIRED') promptOrgSelector();
+   * if (error.code === 'arc.not_found') router.replace('/404');
+   * if (error.code === 'duplicate_key') showRetryAsAdmin();
    */
-  get code(): ArcTopLevelErrorCode | null;
+  get code(): ArcErrorCode | null;
   /**
-   * Nested business-logic code from arc's `json.details.code` slot.
-   *
-   * Arc's preset mixins (bulk, softDelete) and org guards emit specific reason
-   * codes here — distinct from the HTTP-status `code` above. The most common
-   * is `ORG_CONTEXT_REQUIRED` (bulk operations + orgGuard reject when the
-   * caller's `request.scope.organizationId` is missing).
-   *
-   * @example
-   * if (error.detailsCode === 'ORG_CONTEXT_REQUIRED') {
-   *   alert('Configure auth before bulk operations: configureAuth({ getOrgId })');
-   * }
+   * Canonical structured details — populated for validation failures
+   * (one entry per offending field) and duplicate-key conflicts (one entry
+   * per offending field). Shape matches `repo-core`'s {@link ErrorDetail}:
+   * `{ path?, code, message, meta? }`. Returns `null` for non-arc backends
+   * or responses without details.
    */
-  get detailsCode(): ArcDetailsErrorCode | null;
+  get details(): readonly ErrorDetail[] | null;
   /**
    * Extract field-level validation errors as `{ field: message }` map.
    *
-   * Reads three response shapes used by Arc:
-   * 1. `{ errors: { email: 'invalid' } }` — record form (legacy / app-level handlers).
-   * 2. `{ details: { errors: [{ field, message }] } }` — Fastify AJV + Arc errorHandler emit this.
-   * 3. `{ details: { errors: [{ instancePath, message, params }] } }` — raw AJV passthrough.
-   *
-   * Returns null when none of the shapes match.
+   * Reads the canonical `ErrorContract.details: ErrorDetail[]` shape first
+   * (what arc 2.13 + repo-core emit), then falls back to legacy shapes for
+   * non-arc backends:
+   *  1. `details: [{ path, code, message }]` — canonical (arc / repo-core).
+   *  2. `errors: { email: 'invalid' }` — record form (legacy app handlers).
+   *  3. `details: { errors: [{ field|instancePath, message }] }` — pre-2.13 AJV.
+   *  4. `errors: [...]` at the top level — third-party frameworks.
    */
   get fieldErrors(): Record<string, string> | null;
 }
@@ -137,23 +130,24 @@ declare function isArcApiError(error: unknown): error is ArcApiError;
  */
 declare function isAbortError(error: unknown): boolean;
 /**
- * Generic check: is this an `ArcApiError` carrying a specific top-level OR
- * nested `details.code`? Matches whichever slot the code lives in — saves
- * call sites from having to know whether arc emitted it at the root or under
- * `details`.
+ * Generic check: is this an `ArcApiError` carrying a specific `code`?
+ * Single-slot — arc 2.13 + repo-core 0.4 emit one canonical `code` at
+ * top-level. Pass either the canonical lowercase form (`'arc.not_found'`,
+ * `'validation_error'`) or arc's UPPER_SNAKE business form
+ * (`'ORG_CONTEXT_REQUIRED'`).
  *
  * @example
- * if (isArcErrorCode(error, 'DUPLICATE_KEY')) showRetryUI();
+ * if (isArcErrorCode(error, 'duplicate_key')) showRetryUI();
  * if (isArcErrorCode(error, 'ORG_CONTEXT_REQUIRED')) promptOrgSelector();
  */
-declare function isArcErrorCode(error: unknown, code: ArcTopLevelErrorCode | ArcDetailsErrorCode): error is ArcApiError;
+declare function isArcErrorCode(error: unknown, code: ArcErrorCode): error is ArcApiError;
 /**
  * Specific predicate for arc's bulk-preset + orgGuard safety code.
  *
  * Arc's bulk endpoints (`POST/PATCH/DELETE /:resource/bulk`) reject any call
  * where `request.scope.organizationId` is missing — the wire signal is
- * `403 { details: { code: 'ORG_CONTEXT_REQUIRED' } }`. Hosts hitting this
- * need to call `configureAuth({ getOrgId })` before retrying.
+ * `403 { code: 'ORG_CONTEXT_REQUIRED', message, status: 403 }`. Hosts hitting
+ * this need to call `configureAuth({ getOrgId })` before retrying.
  *
  * @example
  * try { await api.bulkCreate({ data: [...] }); }
@@ -165,15 +159,16 @@ declare function isArcErrorCode(error: unknown, code: ArcTopLevelErrorCode | Arc
  */
 declare function isOrgContextRequiredError(error: unknown): error is ArcApiError;
 /**
- * Specific predicate for arc's `VALIDATION_ERROR` (Fastify AJV + Mongoose
+ * Specific predicate for validation failures (Fastify AJV + Mongoose
  * ValidationError). When true, `error.fieldErrors` is populated with the
- * `{ field: message }` map.
+ * `{ field: message }` map. Matches arc's `arc.validation_error` and the
+ * canonical `validation_error` from repo-core.
  */
 declare function isValidationError(error: unknown): error is ArcApiError;
 /**
- * Specific predicate for arc's `DUPLICATE_KEY` (unique-constraint violation).
- * Arc's errorHandler classifies these uniformly across MongoDB E11000,
- * Postgres 23505, and Prisma P2002.
+ * Specific predicate for unique-constraint violations. Arc's errorHandler
+ * classifies these uniformly across MongoDB E11000, Postgres 23505,
+ * Prisma P2002 → `arc.conflict` (with `details[].code === 'duplicate_key'`).
  */
 declare function isDuplicateKeyError(error: unknown): error is ArcApiError;
 interface ClientConfig {
@@ -505,8 +500,8 @@ declare function getClientAuthContext(client?: ArcClient): {
  * Handles JSON, binary (PDF, images), CSV, and text responses.
  *
  * @example
- * const { success, data } = await handleApiRequest<ApiResponse<User>>('GET', '/users/me');
- * const response = await handleApiRequest<PaginatedResponse<Product>>('GET', '/products?page=1');
+ * const user = await handleApiRequest<User>('GET', '/users/me');
+ * const response = await handleApiRequest<PaginatedResult<Product>>('GET', '/products?page=1');
  */
 declare function handleApiRequest<T = unknown>(method: HttpMethod, endpoint: string, options?: ApiRequestOptions): Promise<T>;
 /**
@@ -527,4 +522,4 @@ declare function handleApiRequest<T = unknown>(method: HttpMethod, endpoint: str
  */
 declare function createQueryString<T extends Record<string, unknown>>(params?: T): string;
 //#endregion
-export { AfterResponseContext, AfterResponseInterceptor, ApiRequestOptions, ArcApiError, ArcApiErrorOptions, ArcClient, ArcClientConfig, ArcDetailsErrorCode, ArcTopLevelErrorCode, AuthConfig, BeforeRequestContext, BeforeRequestInterceptor, BlobResponse, ClientConfig, HttpMethod, KNOWN_DETAILS_CODES, KNOWN_TOP_LEVEL_CODES, RetryConfig, StreamUrlProtocol, TextResponse, ToastHandler, UseRouterHook, _resetAuthWarnings, buildStreamUrl, configureAuth, configureClient, createAuthAwareClient, createClient, createQueryString, getAuthContext, getAuthMode, getBaseUrl, getClientAuthContext, handleApiRequest, isAbortError, isArcApiError, isArcErrorCode, isAutoIdempotency, isDuplicateKeyError, isOrgContextRequiredError, isValidationError };
+export { AfterResponseContext, AfterResponseInterceptor, ApiRequestOptions, ArcApiError, ArcApiErrorOptions, ArcClient, ArcClientConfig, ArcErrorCode, AuthConfig, BeforeRequestContext, BeforeRequestInterceptor, BlobResponse, ClientConfig, HttpMethod, KNOWN_ARC_ERROR_CODES, RetryConfig, StreamUrlProtocol, TextResponse, ToastHandler, UseRouterHook, _resetAuthWarnings, buildStreamUrl, configureAuth, configureClient, createAuthAwareClient, createClient, createQueryString, getAuthContext, getAuthMode, getBaseUrl, getClientAuthContext, handleApiRequest, isAbortError, isArcApiError, isArcErrorCode, isAutoIdempotency, isDuplicateKeyError, isOrgContextRequiredError, isValidationError };

package/dist/client.js

@@ -1,49 +1,59 @@
 //#region src/client.ts
 /**
-* Top-level error codes arc's `errorHandlerPlugin` emits on the response root
-* (`json.code`). Mirrors `statusCodeToCode()` + the special `VALIDATION_ERROR`
-* / `DUPLICATE_KEY` / `INTERNAL_ERROR` branches.
+* Canonical error codes arc and repo-core emit on `json.code`. Single
+* top-level slot — arc 2.13's `createError` lifts business codes from
+* `details` to top-level so `repo-core`'s `toErrorContract` round-trips
+* them on the wire. There is no separate `detailsCode` slot; everything
+* lives at `error.code`.
 *
-* Open via intersection with `(string & {})` so unknown codes from custom
-* `errorMappers` / `errorMap` still satisfy the type.
-*/
-/**
-* Top-level HTTP-status error codes arc's `errorHandlerPlugin` emits on
-* `json.code`. Exported as a `const` array first so callers get both
-* compile-time exhaustiveness AND runtime iteration (e.g. building a
-* client-side i18n lookup, or whitelisting which codes get retried).
-*/
-const KNOWN_TOP_LEVEL_CODES = [
-	"BAD_REQUEST",
-	"UNAUTHORIZED",
-	"FORBIDDEN",
-	"NOT_FOUND",
-	"METHOD_NOT_ALLOWED",
-	"CONFLICT",
-	"UNPROCESSABLE_ENTITY",
-	"RATE_LIMITED",
-	"INTERNAL_ERROR",
-	"BAD_GATEWAY",
-	"SERVICE_UNAVAILABLE",
-	"GATEWAY_TIMEOUT",
-	"VALIDATION_ERROR",
-	"DUPLICATE_KEY",
-	"DOMAIN_ERROR"
-];
-/**
-* Nested business-logic codes arc's mixins / preset routes / org guards emit
-* on `json.details.code`. These are distinct from the HTTP-status code above —
-* `error.code` (top-level) vs `error.detailsCode` (nested). When a route
-* returns 403 with `details.code: 'ORG_CONTEXT_REQUIRED'`, hosts read
-* `detailsCode` to disambiguate "missing org context" from "permission denied".
+* Three families compose this list:
+*  1. **repo-core canonical** (`validation_error`, `not_found`, ...) — RFC 7807
+*     / Stripe-shaped lowercase + snake_case. Cross-package universals.
+*  2. **arc hierarchical** (`arc.forbidden`, `arc.validation_error`,
+*     `arc.org.access_denied`, ...) — what arc's `errorHandlerPlugin`
+*     emits for HTTP-status throws + arc-classified errors.
+*  3. **arc business** (`ORG_CONTEXT_REQUIRED`, `ALL_FIELDS_STRIPPED`,
+*     `OWNERSHIP_DENIED`, ...) — emitted by mixins / org guards via
+*     `createError(status, msg, { code })`. The UPPER_SNAKE form is
+*     intentional: these are reason codes, not HTTP-status codes.
+*
+* `(string & {})` keeps the type open so domain packages and custom
+* `errorMappers` codes still satisfy it.
 */
-const KNOWN_DETAILS_CODES = [
+const KNOWN_ARC_ERROR_CODES = [
+	"validation_error",
+	"not_found",
+	"conflict",
+	"unauthorized",
+	"forbidden",
+	"rate_limited",
+	"idempotency_conflict",
+	"precondition_failed",
+	"internal_error",
+	"service_unavailable",
+	"timeout",
+	"arc.bad_request",
+	"arc.unauthorized",
+	"arc.forbidden",
+	"arc.not_found",
+	"arc.conflict",
+	"arc.unprocessable_entity",
+	"arc.rate_limited",
+	"arc.internal_error",
+	"arc.bad_gateway",
+	"arc.service_unavailable",
+	"arc.gateway_timeout",
+	"arc.validation_error",
+	"arc.invalid_id",
+	"arc.org.selection_required",
+	"arc.org.access_denied",
 	"ORG_CONTEXT_REQUIRED",
 	"ORG_ROLE_REQUIRED",
 	"OWNERSHIP_DENIED",
 	"MIXED_UPDATE_SHAPE",
 	"ALL_FIELDS_STRIPPED",
-	"BEFORE_RESTORE_HOOK_ERROR"
+	"BEFORE_RESTORE_HOOK_ERROR",
+	"duplicate_key"
 ];
 /**
 * Rich API error with status code, response payload, and request metadata.
@@ -75,51 +85,59 @@ var ArcApiError = class extends Error {
 		this.method = options.method;
 	}
 	/**
-	* Top-level error code from arc's response envelope (`json.code`).
+	* Canonical error code from arc's wire envelope (`json.code`).
 	*
-	* One of {@link ArcTopLevelErrorCode} — covers HTTP-status codes (`FORBIDDEN`,
-	* `CONFLICT`...) plus the dedicated `VALIDATION_ERROR` / `DUPLICATE_KEY`
-	* branches arc emits. Returns `null` if the response carries no envelope.
+	* Arc 2.13 + `repo-core` 0.4 emit one canonical {@link ErrorContract}
+	* shape — `{ code, message, status, details? }` — with the business
+	* code at top-level. Hosts switch on `error.code` directly:
 	*
 	* @example
-	* if (error.code === 'DUPLICATE_KEY') showRetryAsAdmin();
+	* if (error.code === 'ORG_CONTEXT_REQUIRED') promptOrgSelector();
+	* if (error.code === 'arc.not_found') router.replace('/404');
+	* if (error.code === 'duplicate_key') showRetryAsAdmin();
 	*/
 	get code() {
 		const j = this.json;
 		return j && typeof j.code === "string" ? j.code : null;
 	}
 	/**
-	* Nested business-logic code from arc's `json.details.code` slot.
-	*
-	* Arc's preset mixins (bulk, softDelete) and org guards emit specific reason
-	* codes here — distinct from the HTTP-status `code` above. The most common
-	* is `ORG_CONTEXT_REQUIRED` (bulk operations + orgGuard reject when the
-	* caller's `request.scope.organizationId` is missing).
-	*
-	* @example
-	* if (error.detailsCode === 'ORG_CONTEXT_REQUIRED') {
-	*   alert('Configure auth before bulk operations: configureAuth({ getOrgId })');
-	* }
+	* Canonical structured details — populated for validation failures
+	* (one entry per offending field) and duplicate-key conflicts (one entry
+	* per offending field). Shape matches `repo-core`'s {@link ErrorDetail}:
+	* `{ path?, code, message, meta? }`. Returns `null` for non-arc backends
+	* or responses without details.
 	*/
-	get detailsCode() {
-		const c = this.json?.details?.code;
-		return typeof c === "string" ? c : null;
+	get details() {
+		const j = this.json;
+		return Array.isArray(j?.details) ? j.details : null;
 	}
 	/**
 	* Extract field-level validation errors as `{ field: message }` map.
 	*
-	* Reads three response shapes used by Arc:
-	* 1. `{ errors: { email: 'invalid' } }` — record form (legacy / app-level handlers).
-	* 2. `{ details: { errors: [{ field, message }] } }` — Fastify AJV + Arc errorHandler emit this.
-	* 3. `{ details: { errors: [{ instancePath, message, params }] } }` — raw AJV passthrough.
-	*
-	* Returns null when none of the shapes match.
+	* Reads the canonical `ErrorContract.details: ErrorDetail[]` shape first
+	* (what arc 2.13 + repo-core emit), then falls back to legacy shapes for
+	* non-arc backends:
+	*  1. `details: [{ path, code, message }]` — canonical (arc / repo-core).
+	*  2. `errors: { email: 'invalid' }` — record form (legacy app handlers).
+	*  3. `details: { errors: [{ field|instancePath, message }] }` — pre-2.13 AJV.
+	*  4. `errors: [...]` at the top level — third-party frameworks.
 	*/
 	get fieldErrors() {
 		const j = this.json;
 		if (!j) return null;
+		if (Array.isArray(j.details) && j.details.length > 0) {
+			const map = {};
+			for (const d of j.details) {
+				if (!d || typeof d !== "object") continue;
+				const key = typeof d.path === "string" ? d.path : "";
+				const msg = typeof d.message === "string" ? d.message : "Invalid value";
+				if (key && !(key in map)) map[key] = msg;
+			}
+			if (Object.keys(map).length > 0) return map;
+		}
 		if (j.errors && !Array.isArray(j.errors) && typeof j.errors === "object") return j.errors;
-		const errorList = Array.isArray(j.errors) ? j.errors : Array.isArray(j.details?.errors) ? j.details.errors : null;
+		const detailsObj = j.details;
+		const errorList = Array.isArray(j.errors) ? j.errors : Array.isArray(detailsObj?.errors) ? detailsObj.errors : null;
 		if (!errorList) return null;
 		const map = {};
 		for (const item of errorList) {
@@ -169,26 +187,26 @@ function isAbortError(error) {
 	return false;
 }
 /**
-* Generic check: is this an `ArcApiError` carrying a specific top-level OR
-* nested `details.code`? Matches whichever slot the code lives in — saves
-* call sites from having to know whether arc emitted it at the root or under
-* `details`.
+* Generic check: is this an `ArcApiError` carrying a specific `code`?
+* Single-slot — arc 2.13 + repo-core 0.4 emit one canonical `code` at
+* top-level. Pass either the canonical lowercase form (`'arc.not_found'`,
+* `'validation_error'`) or arc's UPPER_SNAKE business form
+* (`'ORG_CONTEXT_REQUIRED'`).
 *
 * @example
-* if (isArcErrorCode(error, 'DUPLICATE_KEY')) showRetryUI();
+* if (isArcErrorCode(error, 'duplicate_key')) showRetryUI();
 * if (isArcErrorCode(error, 'ORG_CONTEXT_REQUIRED')) promptOrgSelector();
 */
 function isArcErrorCode(error, code) {
-	if (!isArcApiError(error)) return false;
-	return error.code === code || error.detailsCode === code;
+	return isArcApiError(error) && error.code === code;
 }
 /**
 * Specific predicate for arc's bulk-preset + orgGuard safety code.
 *
 * Arc's bulk endpoints (`POST/PATCH/DELETE /:resource/bulk`) reject any call
 * where `request.scope.organizationId` is missing — the wire signal is
-* `403 { details: { code: 'ORG_CONTEXT_REQUIRED' } }`. Hosts hitting this
-* need to call `configureAuth({ getOrgId })` before retrying.
+* `403 { code: 'ORG_CONTEXT_REQUIRED', message, status: 403 }`. Hosts hitting
+* this need to call `configureAuth({ getOrgId })` before retrying.
 *
 * @example
 * try { await api.bulkCreate({ data: [...] }); }
@@ -202,20 +220,27 @@ function isOrgContextRequiredError(error) {
 	return isArcErrorCode(error, "ORG_CONTEXT_REQUIRED");
 }
 /**
-* Specific predicate for arc's `VALIDATION_ERROR` (Fastify AJV + Mongoose
+* Specific predicate for validation failures (Fastify AJV + Mongoose
 * ValidationError). When true, `error.fieldErrors` is populated with the
-* `{ field: message }` map.
+* `{ field: message }` map. Matches arc's `arc.validation_error` and the
+* canonical `validation_error` from repo-core.
 */
 function isValidationError(error) {
-	return isArcErrorCode(error, "VALIDATION_ERROR");
+	if (!isArcApiError(error)) return false;
+	return error.code === "arc.validation_error" || error.code === "validation_error";
 }
 /**
-* Specific predicate for arc's `DUPLICATE_KEY` (unique-constraint violation).
-* Arc's errorHandler classifies these uniformly across MongoDB E11000,
-* Postgres 23505, and Prisma P2002.
+* Specific predicate for unique-constraint violations. Arc's errorHandler
+* classifies these uniformly across MongoDB E11000, Postgres 23505,
+* Prisma P2002 → `arc.conflict` (with `details[].code === 'duplicate_key'`).
 */
 function isDuplicateKeyError(error) {
-	return isArcErrorCode(error, "DUPLICATE_KEY");
+	if (!isArcApiError(error)) return false;
+	if (error.code === "arc.conflict" || error.code === "duplicate_key" || error.code === "conflict") {
+		if (error.code === "arc.conflict") return error.details?.some((d) => d.code === "duplicate_key") ?? false;
+		return true;
+	}
+	return false;
 }
 let clientConfig = null;
 /**
@@ -609,8 +634,8 @@ async function executeAttempt(config, method, endpoint, options, attempt) {
 * Handles JSON, binary (PDF, images), CSV, and text responses.
 *
 * @example
-* const { success, data } = await handleApiRequest<ApiResponse<User>>('GET', '/users/me');
-* const response = await handleApiRequest<PaginatedResponse<Product>>('GET', '/products?page=1');
+* const user = await handleApiRequest<User>('GET', '/users/me');
+* const response = await handleApiRequest<PaginatedResult<Product>>('GET', '/products?page=1');
 */
 async function handleApiRequest(method, endpoint, options = {}) {
 	if (!clientConfig) throw new Error("arc-next: Client not configured. Call configureClient({ baseUrl }) before making API requests.");
@@ -655,10 +680,18 @@ function createQueryString(params = {}) {
 			if (value.length > 1) searchParams.append(`${key}[in]`, value.join(","));
 			else if (value.length === 1) searchParams.append(key, String(value[0]));
 		} else if (value === null) searchParams.append(key, "null");
+		else if (typeof value === "object") for (const [op, opValue] of Object.entries(value)) {
+			if (opValue === void 0 || opValue === "") continue;
+			const bracketKey = `${key}[${op}]`;
+			if (Array.isArray(opValue)) {
+				if (opValue.length > 0) searchParams.append(bracketKey, opValue.join(","));
+			} else if (opValue === null) searchParams.append(bracketKey, "null");
+			else searchParams.append(bracketKey, String(opValue));
+		}
 		else searchParams.append(key, String(value));
 	});
 	return searchParams.toString();
 }
 
 //#endregion
-export { ArcApiError, KNOWN_DETAILS_CODES, KNOWN_TOP_LEVEL_CODES, _resetAuthWarnings, buildStreamUrl, configureAuth, configureClient, createAuthAwareClient, createClient, createQueryString, getAuthContext, getAuthMode, getBaseUrl, getClientAuthContext, handleApiRequest, isAbortError, isArcApiError, isArcErrorCode, isAutoIdempotency, isDuplicateKeyError, isOrgContextRequiredError, isValidationError };
+export { ArcApiError, KNOWN_ARC_ERROR_CODES, _resetAuthWarnings, buildStreamUrl, configureAuth, configureClient, createAuthAwareClient, createClient, createQueryString, getAuthContext, getAuthMode, getBaseUrl, getClientAuthContext, handleApiRequest, isAbortError, isArcApiError, isArcErrorCode, isAutoIdempotency, isDuplicateKeyError, isOrgContextRequiredError, isValidationError };

package/dist/hooks.d.ts

@@ -1,14 +1,14 @@
 import { ArcClient, UseRouterHook } from "./client.js";
-import { ApiResponse, BaseApi } from "./api.js";
+import { AggResult, AggRow, BaseApi } from "./api.js";
 import { CacheUtils, QueryKeys } from "./cache.js";
 import { MutationCallbacks, MutationMessages, TransitionMutationReturn } from "./mutation.js";
-import { DetailQueryOptions, DetailQueryResult, InfiniteListQueryOptions, InfiniteListQueryResult, ListQueryOptions, ListQueryResult } from "./query.js";
+import { DetailQueryOptions, DetailQueryResult, InfiniteListQueryOptions, InfiniteListQueryResult, ListQueryOptions, ListQueryResult, RequestPassthrough } from "./query.js";
 import { SoftDeleteMethods } from "./presets/soft-delete.js";
 import { BulkMethods } from "./presets/bulk.js";
 import { SlugLookupMethods } from "./presets/slug.js";
 import { TreeMethods } from "./presets/tree.js";
 import { SearchPresetMethods } from "./presets/search.js";
-import { QueryKey } from "@tanstack/react-query";
+import { QueryKey, UseQueryResult } from "@tanstack/react-query";
 
 //#region src/hooks.d.ts
 /**
@@ -24,8 +24,50 @@ import { QueryKey } from "@tanstack/react-query";
 type CrudApi<T = unknown, TCreate = Partial<T>, TUpdate = Partial<T>> = Pick<BaseApi<T, TCreate, TUpdate>, 'getAll' | 'getById' | 'create' | 'update' | 'delete'> & {
   upload?: BaseApi<T, TCreate, TUpdate>['upload'];
   dispatchAction?: BaseApi<T, TCreate, TUpdate>['dispatchAction'];
-  invokeRoute?: BaseApi<T, TCreate, TUpdate>['invokeRoute'];
+  invokeRoute?: BaseApi<T, TCreate, TUpdate>['invokeRoute']; /** Declared aggregations (arc 2.13+). Always available on BaseApi. */
+  aggregate?: BaseApi<T, TCreate, TUpdate>['aggregate'];
 } & Partial<SoftDeleteMethods<T>> & Partial<BulkMethods<T, TCreate, TUpdate>> & Partial<SlugLookupMethods<T>> & Partial<TreeMethods<T>> & Partial<SearchPresetMethods<T>>;
+/** Args + options for `useAggregation`. Mirrors `ListQueryOptions` for DX consistency. */
+interface AggregationQueryOptions<TRow extends AggRow = AggRow, TData = AggResult<TRow>> {
+  /** Bypass auth gate (for public dashboards behind `allowPublic` permissions). */
+  public?: boolean;
+  /** Skip the query (e.g. while a parent filter is being assembled). */
+  enabled?: boolean;
+  /** Per-call staleTime override. Defaults to factory's `defaults.staleTime`. */
+  staleTime?: number;
+  /** Per-call gcTime override. */
+  gcTime?: number;
+  /**
+   * Refetch on window focus. Aggregations / dashboards usually want this OFF —
+   * long-running compute. Defaults to `false` regardless of factory config.
+   */
+  refetchOnWindowFocus?: boolean;
+  /** Periodic refetch (ms or `false`). Set for live dashboards. */
+  refetchInterval?: number | false;
+  /** Continue polling while the tab is in the background. */
+  refetchIntervalInBackground?: boolean;
+  /**
+   * Transform `AggResult<TRow>` before exposing it. Common pattern is to
+   * pluck the rows array directly:
+   *   `select: (r) => r.rows`
+   * Or compute a derived value:
+   *   `select: (r) => r.rows.reduce((acc, x) => acc + x.total, 0)`
+   * Runs on each render after structural-sharing dedupe.
+   */
+  select?: (data: AggResult<TRow>) => TData;
+  /**
+   * Pass-through to the underlying fetch call. Use for Next.js ISR — pass
+   * `request: { revalidate: 60, tags: ['orders'] }` so the server-side fetch
+   * cache participates in `revalidateTag('orders')` invalidations alongside
+   * TanStack's client cache.
+   */
+  request?: RequestPassthrough;
+  /**
+   * Show this data while the real query is loading / re-fetching with
+   * different filters. Smooths fast filter switches on dashboards.
+   */
+  placeholderData?: AggResult<TRow> | ((prev: AggResult<TRow> | undefined) => AggResult<TRow> | undefined);
+}
 interface CrudHooksConfig<T, TCreate = Partial<T>, TUpdate = Partial<T>> {
   api: CrudApi<T, TCreate, TUpdate>;
   entityKey: string;
@@ -157,7 +199,7 @@ interface CrudHooksReturn<T, TCreate, TUpdate> {
     invalidateQueries?: QueryKey[]; /** Default action name. Can be overridden per-call via `mutate({ action })`. */
     action?: string;
     messages?: MutationMessages;
-    onSuccess?: (data: ApiResponse<TResult>, variables: {
+    onSuccess?: (data: TResult, variables: {
       id: string;
       action: string;
       data?: TBody;
@@ -167,12 +209,12 @@ interface CrudHooksReturn<T, TCreate, TUpdate> {
       action: string;
       data?: TBody;
     }) => void;
-    onSettled?: (data: ApiResponse<TResult> | undefined, error: Error | null, variables: {
+    onSettled?: (data: TResult | undefined, error: Error | null, variables: {
       id: string;
       action: string;
       data?: TBody;
     }) => void;
-  }) => TransitionMutationReturn<ApiResponse<TResult>, {
+  }) => TransitionMutationReturn<TResult, {
     id: string;
     action?: string;
     data?: TBody;
@@ -205,6 +247,28 @@ interface CrudHooksReturn<T, TCreate, TUpdate> {
     input: string | string[];
     body?: Record<string, unknown>;
   }>;
+  /**
+   * Query against arc's declarative aggregations (arc v2.13+).
+   * `GET /:resource/aggregations/:name` — wire shape `{ rows: TRow[] }`.
+   *
+   * Cached under `KEYS.aggregation(name, filter)` so multiple call sites with
+   * the same args share one cache entry. Mutation hooks
+   * (`useActions`/`useBulkActions`) auto-invalidate `KEYS.aggregations()` so
+   * dashboards refresh after CRUD writes — opt out via the mutation's
+   * `invalidateQueries` override if you want stale-on-write.
+   *
+   * @example
+   * const { data } = useAggregation<{ day: string; total: number }>({
+   *   name: 'salesByDay',
+   *   filter: { from: '2025-01-01' },
+   *   refetchOnWindowFocus: false,
+   * });
+   * // data.rows: Array<{ day: string; total: number }>
+   */
+  useAggregation: <TRow extends AggRow = AggRow, TData = AggResult<TRow>>(args: {
+    name: string;
+    filter?: Record<string, unknown>;
+  } & AggregationQueryOptions<TRow, TData>) => UseQueryResult<TData>;
   useUpload: (options?: {
     invalidateQueries?: QueryKey[];
     messages?: MutationMessages;
@@ -269,4 +333,4 @@ declare function createCrudHooks<T, TCreate = Partial<T>, TUpdate = Partial<T>>(
   client
 }: CrudHooksConfig<T, TCreate, TUpdate>): CrudHooksReturn<T, TCreate, TUpdate>;
 //#endregion
-export { BulkActions, CallOptions, CrudActions, CrudApi, CrudHooksConfig, CrudHooksReturn, DeleteParams, MutationParams, NavigateFn, NavigationOptions, UpdateParams, configureNavigation, createCrudHooks };
+export { AggregationQueryOptions, BulkActions, CallOptions, CrudActions, CrudApi, CrudHooksConfig, CrudHooksReturn, DeleteParams, MutationParams, NavigateFn, NavigationOptions, UpdateParams, configureNavigation, createCrudHooks };