@classytic/arc-next 0.12.0 → 0.14.0

package/LICENSE

@@ -1,6 +1,6 @@
 MIT License
 
-Copyright (c) 2025 Classytic
+Copyright (c) 2025 Classytic LLC
 
 Permission is hereby granted, free of charge, to any person obtaining a copy
 of this software and associated documentation files (the "Software"), to deal

package/README.md

@@ -650,3 +650,10 @@ const { mutateAsync: publish, isPending } = useMutationWithTransition({
 ## License
 
 MIT
+
+
+## Trademark
+
+The code is MIT-licensed. **"Classytic", "arc", and the logos are trademarks of
+Classytic LLC** and are **not** licensed under MIT — see [TRADEMARK.md](TRADEMARK.md).
+Forks must be renamed; the license covers the code, not the brand.

package/dist/api.d.ts

@@ -2,7 +2,6 @@ import { ArcClient, NextFetchOptions } from "./client.js";
 import { BracketOperator, BracketOperator as BracketOperator$1, ParsedPopulate } from "@classytic/repo-core/query-parser";
 import { AggregatePaginationResult, KeysetPaginationResult, OffsetPaginationResult, PaginatedResult, SortDirection as SortDirection$1 } from "@classytic/repo-core/pagination";
 import { AggResult, AggRow, BulkCreateResult, DeleteManyResult, DeleteResult, UpdateManyResult } from "@classytic/repo-core/repository";
-
 //#region src/api.d.ts
 /**
  * URL-emittable subset of repo-core's canonical {@link ParsedPopulate} —
@@ -100,7 +99,18 @@ interface BaseApiConfig {
   };
   cache?: RequestCache;
   headers?: Record<string, string>;
-  client?: ArcClient;
+  /**
+   * Transport for this API instance.
+   *
+   * - `ArcClient` — RETAINED: the instance is captured and every request goes
+   *   through it (isolated multi-client setups, tests, background jobs).
+   * - `() => ArcClient` — PROVIDER: re-resolved on EVERY request, so a
+   *   consumer SDK can swap/reconfigure the underlying client after APIs are
+   *   constructed without Proxy tricks or stale-capture bugs (the reason the
+   *   commerce SDK previously wrapped its default client in a `Proxy`).
+   * - omitted — the module-global transport (`configureClient`/`configureAuth`).
+   */
+  client?: ArcClient | (() => ArcClient);
 }
 declare class BaseApi<TDoc = Record<string, unknown>, TCreate = Partial<TDoc>, TUpdate = Partial<TDoc>> {
   readonly entity: string;
@@ -129,12 +139,7 @@ declare class BaseApi<TDoc = Record<string, unknown>, TCreate = Partial<TDoc>, T
   private withCacheDefault;
   createQueryString(params?: Record<string, unknown>): string;
   prepareParams(params?: QueryParams): Record<string, unknown>;
-  getAll({
-    token,
-    organizationId,
-    params,
-    options
-  }?: {
+  getAll({ token, organizationId, params, options }?: {
     token?: string | null;
     organizationId?: string | null;
     params?: QueryParams;
@@ -145,37 +150,21 @@ declare class BaseApi<TDoc = Record<string, unknown>, TCreate = Partial<TDoc>, T
    * (`?_count=true`): same permissions/row-filters/tenant scoping as
    * `getAll`, ZERO documents fetched. Cheapest way to answer "how many".
    */
-  count({
-    token,
-    organizationId,
-    params,
-    options
-  }?: {
+  count({ token, organizationId, params, options }?: {
     token?: string | null;
     organizationId?: string | null;
     params?: QueryParams;
     options?: Omit<RequestOptions, "token" | "organizationId">;
   }): Promise<number>;
   /** Whether ANY record matches the filters (`?_exists=true`). */
-  exists({
-    token,
-    organizationId,
-    params,
-    options
-  }?: {
+  exists({ token, organizationId, params, options }?: {
     token?: string | null;
     organizationId?: string | null;
     params?: QueryParams;
     options?: Omit<RequestOptions, "token" | "organizationId">;
   }): Promise<boolean>;
   /** Distinct values of a field across matching records (`?_distinct=field`). */
-  distinct<TValue = unknown>({
-    token,
-    organizationId,
-    field,
-    params,
-    options
-  }: {
+  distinct<TValue = unknown>({ token, organizationId, field, params, options }: {
     token?: string | null;
     organizationId?: string | null;
     field: string;
@@ -184,13 +173,7 @@ declare class BaseApi<TDoc = Record<string, unknown>, TCreate = Partial<TDoc>, T
   }): Promise<TValue[]>;
   /** Shared raw GET against the list route (dispatch verbs bypass pagination parsing). */
   private getAllRaw;
-  getById({
-    token,
-    organizationId,
-    id,
-    params,
-    options
-  }: {
+  getById({ token, organizationId, id, params, options }: {
     token?: string | null;
     organizationId?: string | null;
     id: string;
@@ -200,60 +183,33 @@ declare class BaseApi<TDoc = Record<string, unknown>, TCreate = Partial<TDoc>, T
     };
     options?: Omit<RequestOptions, "token" | "organizationId">;
   }): Promise<TDoc>;
-  create({
-    token,
-    organizationId,
-    data,
-    options
-  }: {
+  create({ token, organizationId, data, options }: {
     token?: string | null;
     organizationId?: string | null;
     data: TCreate;
     options?: Omit<RequestOptions, "token" | "organizationId">;
   }): Promise<TDoc>;
-  update({
-    token,
-    organizationId,
-    id,
-    data,
-    options
-  }: {
+  update({ token, organizationId, id, data, options }: {
     token?: string | null;
     organizationId?: string | null;
     id: string;
     data: TUpdate;
     options?: Omit<RequestOptions, "token" | "organizationId">;
   }): Promise<TDoc>;
-  delete({
-    token,
-    organizationId,
-    id,
-    options
-  }: {
+  delete({ token, organizationId, id, options }: {
     token?: string | null;
     organizationId?: string | null;
     id: string;
     options?: Omit<RequestOptions, "token" | "organizationId">;
   }): Promise<DeleteResult>;
-  upload({
-    token,
-    organizationId,
-    data,
-    id,
-    path,
-    options
-  }: ScopedArgs & {
-    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`. */
+  upload({ token, organizationId, data, id, path, options }: ScopedArgs & {
+    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<TDoc>;
-  request<TResponse = unknown>(method: "GET" | "POST" | "PATCH" | "PUT" | "DELETE", endpoint: string, {
-    token,
-    organizationId,
-    data,
-    params,
-    options
-  }?: ScopedArgs & {
+  request<TResponse = unknown>(method: "GET" | "POST" | "PATCH" | "PUT" | "DELETE", endpoint: string, { token, organizationId, data, params, options }?: ScopedArgs & {
     data?: unknown;
     params?: QueryParams;
   }): Promise<TResponse>;
@@ -290,16 +246,9 @@ declare class BaseApi<TDoc = Record<string, unknown>, TCreate = Partial<TDoc>, T
    *   data: { source: 'csv', items: [...] },
    * });
    */
-  invokeRoute<TResponse = unknown>({
-    token,
-    organizationId,
-    method,
-    path,
-    data,
-    params,
-    options
-  }: ScopedArgs & {
-    method?: "GET" | "POST" | "PATCH" | "PUT" | "DELETE"; /** Path relative to the resource baseUrl. Leading slash optional. */
+  invokeRoute<TResponse = unknown>({ token, organizationId, method, path, data, params, options }: ScopedArgs & {
+    method?: "GET" | "POST" | "PATCH" | "PUT" | "DELETE";
+    /** Path relative to the resource baseUrl. Leading slash optional. */
     path: string;
     data?: unknown;
     params?: QueryParams;
@@ -313,14 +262,9 @@ declare class BaseApi<TDoc = Record<string, unknown>, TCreate = Partial<TDoc>, T
    *   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;
+  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
@@ -328,14 +272,7 @@ declare class BaseApi<TDoc = Record<string, unknown>, TCreate = Partial<TDoc>, T
      */
     filter?: Record<string, unknown>;
   }): Promise<AggResult<TRow>>;
-  dispatchAction<TResult = unknown, TBody extends Record<string, unknown> = Record<string, unknown>>({
-    token,
-    organizationId,
-    id,
-    action,
-    data,
-    options
-  }: ScopedArgs & {
+  dispatchAction<TResult = unknown, TBody extends Record<string, unknown> = Record<string, unknown>>({ token, organizationId, id, action, data, options }: ScopedArgs & {
     id: string;
     action: string;
     data?: TBody;

package/dist/api.js

@@ -14,7 +14,8 @@ var BaseApi = class {
 	requestFn;
 	constructor(entity, config = {}) {
 		this.entity = entity;
-		this.requestFn = config.client?.request ?? handleApiRequest;
+		const client = config.client;
+		this.requestFn = typeof client === "function" ? (method, endpoint, options) => client().request(method, endpoint, options) : client?.request ?? handleApiRequest;
 		this.config = {
 			basePath: config.basePath ?? "/api/v1",
 			defaultParams: {
@@ -97,12 +98,14 @@ var BaseApi = class {
 				});
 				return;
 			}
-			if (value !== void 0 && value !== "") if (["page", "limit"].includes(key)) result[key] = parseInt(String(value), 10) || (key === "page" ? 1 : 10);
-			else if (Array.isArray(value)) {
-				if (/\[([^\]]+)\]$/.test(key)) result[key] = value.join(",");
-				else if (value.length > 1) result[`${key}[in]`] = value.join(",");
-				else if (value.length === 1) result[key] = value[0];
-			} else result[key] = value;
+			if (value !== void 0 && value !== "") {
+				if (["page", "limit"].includes(key)) result[key] = parseInt(String(value), 10) || (key === "page" ? 1 : 10);
+				else if (Array.isArray(value)) {
+					if (/\[([^\]]+)\]$/.test(key)) result[key] = value.join(",");
+					else if (value.length > 1) result[`${key}[in]`] = value.join(",");
+					else if (value.length === 1) result[key] = value[0];
+				} else result[key] = value;
+			}
 		});
 		return result;
 	}

package/dist/cache.d.ts

@@ -1,5 +1,4 @@
 import { QueryClient, QueryKey } from "@tanstack/react-query";
-
 //#region src/cache.d.ts
 interface PaginationData {
   /** Pagination method detected from response (offset | keyset | aggregate) */
@@ -21,16 +20,20 @@ declare const DEFAULT_QUERY_CONFIG: {
 };
 /** Pre-built query config presets for common data freshness patterns. */
 declare const QUERY_CONFIGS: {
-  /** Live data: 20s stale, 30s polling */readonly realtime: {
+  /** Live data: 20s stale, 30s polling */
+  readonly realtime: {
     readonly staleTime: 20000;
     readonly refetchInterval: 30000;
-  }; /** Frequently updated: 60s stale */
+  };
+  /** Frequently updated: 60s stale */
   readonly frequent: {
     readonly staleTime: 60000;
-  }; /** Stable data: 5min stale (same as default) */
+  };
+  /** Stable data: 5min stale (same as default) */
   readonly stable: {
     readonly staleTime: 300000;
-  }; /** Rarely changes: 10min stale */
+  };
+  /** Rarely changes: 10min stale */
   readonly static: {
     readonly staleTime: 600000;
   };

package/dist/cache.js

@@ -1,7 +1,7 @@
 //#region src/cache.ts
 const DEFAULT_QUERY_CONFIG = {
-	staleTime: 300 * 1e3,
-	gcTime: 1800 * 1e3,
+	staleTime: 3e5,
+	gcTime: 18e5,
 	refetchOnWindowFocus: false,
 	retry: 0
 };

package/dist/client.d.ts

@@ -1,5 +1,4 @@
 import { ErrorDetail } from "@classytic/repo-core/errors";
-
 //#region src/client.d.ts
 interface ToastHandler {
   success: (message: string) => void;
@@ -34,7 +33,7 @@ type UseRouterHook = () => {
  * `(string & {})` keeps the type open so domain packages and custom
  * `errorMappers` codes still satisfy it.
  */
-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"];
+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.tier_required", "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"];
 /**
  * Canonical arc error code union. `(string & {})` keeps the type open so
  * domain packages can extend hierarchically (`'order.cart.locked'`,
@@ -194,6 +193,43 @@ declare function getQuotaDetails(error: unknown): QuotaDetails | null;
  * }
  */
 declare function isOrgContextRequiredError(error: unknown): error is ArcApiError;
+/** The tier/mode a `arc.tier_required` error asked for, plus the active one. */
+interface TierRequirement {
+  /** Minimum tier/mode the feature needs (e.g. `"enterprise"`). */
+  requiredMode: string;
+  /** The deployment's current tier/mode (e.g. `"standard"`). */
+  currentMode?: string;
+}
+/**
+ * TIER/CAPABILITY gate predicate. True when the backend refused because the
+ * deployment's tier (FLOW_MODE / feature tier) is below what the route needs —
+ * a `arc.tier_required` error (arc-inventory's mode gate → arc's
+ * `createDomainError`). This is the DISCRIMINABLE counterpart to a bare
+ * `arc.forbidden` (a role/permission denial): switch on THIS to render an
+ * "upgrade required / requires Enterprise" surface, and on `arc.forbidden` for
+ * "access denied". The required tier is available via {@link getTierRequirement}.
+ *
+ * @example
+ * if (isTierRequiredError(error)) {
+ *   const { requiredMode } = getTierRequirement(error)!;
+ *   showUpgradePanel(requiredMode);           // "requires Enterprise"
+ * } else if (isArcErrorCode(error, "arc.forbidden")) {
+ *   showAccessDenied();                        // role/branch problem
+ * }
+ */
+declare function isTierRequiredError(error: unknown): error is ArcApiError;
+/**
+ * Extract the tier requirement from a `arc.tier_required` error's structured
+ * machine-readable context (`{ requiredMode, currentMode }`). Returns `null` for
+ * any other error, so the FE never has to hardcode a route→tier map or
+ * string-match a message.
+ *
+ * Reads `meta` (the canonical ErrorContract Record — where both arc gate paths
+ * put it: the global error handler serializes `ArcError.meta`, and the
+ * permission-slot applier emits the same `meta`). Falls back to `details` for
+ * resilience against any backend still emitting the pre-2026-07 shape.
+ */
+declare function getTierRequirement(error: unknown): TierRequirement | null;
 /**
  * Specific predicate for validation failures (Fastify AJV + Mongoose
  * ValidationError). When true, `error.fieldErrors` is populated with the
@@ -267,6 +303,13 @@ interface ClientConfig {
    * @example '2' // sends Accept-Version: 2
    */
   apiVersion?: string;
+  /**
+   * Default request cache mode applied to every request that expresses no
+   * caching intent of its own (no per-call `cache`, `revalidate`, or `next`) —
+   * the client-level analog of `BaseApiConfig.cache`, same precedence rule.
+   * Unset = the runtime's fetch default.
+   */
+  cache?: RequestCache;
   /**
    * Auto-generate `Idempotency-Key` header for POST/PUT/PATCH requests.
    * Prevents duplicate mutations on network retries.
@@ -973,4 +1016,4 @@ declare const arc: {
   delete: <T = unknown>(path: string, opts?: ArcFetchOptions) => Promise<T>;
 };
 //#endregion
-export { AfterResponseContext, AfterResponseInterceptor, ApiRequestOptions, ArcApiError, ArcApiErrorOptions, ArcClient, ArcClientConfig, ArcErrorCode, ArcFetchOptions, AuthConfig, AuthErrorContext, AuthErrorHandler, BeforeRequestContext, BeforeRequestInterceptor, BlobResponse, ClientConfig, ClientEncryptionConfig, HttpMethod, KNOWN_ARC_ERROR_CODES, NextFetchOptions, QuotaDetails, RetryConfig, ServerClientConfig, StreamUrlProtocol, TextResponse, ToastHandler, UseRouterHook, _getAuthErrorHandler, _isAuthRecoverable, _resetArcFetchClient, _resetAuthRecovery, _resetAuthWarnings, _resolveRefreshedToken, _runAuthRecovery, arc, arcAuthHeaders, arcFetch, buildStreamUrl, configureAuth, configureClient, createAuthAwareClient, createAuthRefreshHandler, createClient, createQueryString, createServerClient, getAuthContext, getAuthMode, getBaseUrl, getClientAuthContext, getQuotaDetails, handleApiRequest, hasGlobalStaticAuth, isAbortError, isArcApiError, isArcErrorCode, isAutoIdempotency, isDuplicateKeyError, isOrgContextRequiredError, isQuotaExceeded, isValidationError };
+export { AfterResponseContext, AfterResponseInterceptor, ApiRequestOptions, ArcApiError, ArcApiErrorOptions, ArcClient, ArcClientConfig, ArcErrorCode, ArcFetchOptions, AuthConfig, AuthErrorContext, AuthErrorHandler, BeforeRequestContext, BeforeRequestInterceptor, BlobResponse, ClientConfig, ClientEncryptionConfig, HttpMethod, KNOWN_ARC_ERROR_CODES, NextFetchOptions, QuotaDetails, RetryConfig, ServerClientConfig, StreamUrlProtocol, TextResponse, TierRequirement, ToastHandler, UseRouterHook, _getAuthErrorHandler, _isAuthRecoverable, _resetArcFetchClient, _resetAuthRecovery, _resetAuthWarnings, _resolveRefreshedToken, _runAuthRecovery, arc, arcAuthHeaders, arcFetch, buildStreamUrl, configureAuth, configureClient, createAuthAwareClient, createAuthRefreshHandler, createClient, createQueryString, createServerClient, getAuthContext, getAuthMode, getBaseUrl, getClientAuthContext, getQuotaDetails, getTierRequirement, handleApiRequest, hasGlobalStaticAuth, isAbortError, isArcApiError, isArcErrorCode, isAutoIdempotency, isDuplicateKeyError, isOrgContextRequiredError, isQuotaExceeded, isTierRequiredError, isValidationError };

package/dist/client.js

@@ -37,6 +37,7 @@ const KNOWN_ARC_ERROR_CODES = [
 	"arc.gateway_timeout",
 	"arc.validation_error",
 	"arc.invalid_id",
+	"arc.tier_required",
 	"arc.org.selection_required",
 	"arc.org.access_denied",
 	"ORG_CONTEXT_REQUIRED",
@@ -243,6 +244,48 @@ function isOrgContextRequiredError(error) {
 	return isArcErrorCode(error, "ORG_CONTEXT_REQUIRED");
 }
 /**
+* TIER/CAPABILITY gate predicate. True when the backend refused because the
+* deployment's tier (FLOW_MODE / feature tier) is below what the route needs —
+* a `arc.tier_required` error (arc-inventory's mode gate → arc's
+* `createDomainError`). This is the DISCRIMINABLE counterpart to a bare
+* `arc.forbidden` (a role/permission denial): switch on THIS to render an
+* "upgrade required / requires Enterprise" surface, and on `arc.forbidden` for
+* "access denied". The required tier is available via {@link getTierRequirement}.
+*
+* @example
+* if (isTierRequiredError(error)) {
+*   const { requiredMode } = getTierRequirement(error)!;
+*   showUpgradePanel(requiredMode);           // "requires Enterprise"
+* } else if (isArcErrorCode(error, "arc.forbidden")) {
+*   showAccessDenied();                        // role/branch problem
+* }
+*/
+function isTierRequiredError(error) {
+	return isArcErrorCode(error, "arc.tier_required");
+}
+/**
+* Extract the tier requirement from a `arc.tier_required` error's structured
+* machine-readable context (`{ requiredMode, currentMode }`). Returns `null` for
+* any other error, so the FE never has to hardcode a route→tier map or
+* string-match a message.
+*
+* Reads `meta` (the canonical ErrorContract Record — where both arc gate paths
+* put it: the global error handler serializes `ArcError.meta`, and the
+* permission-slot applier emits the same `meta`). Falls back to `details` for
+* resilience against any backend still emitting the pre-2026-07 shape.
+*/
+function getTierRequirement(error) {
+	if (!isTierRequiredError(error)) return null;
+	const j = error.json ?? {};
+	const bag = j.meta ?? j.details ?? {};
+	const requiredMode = bag.requiredMode;
+	if (typeof requiredMode !== "string") return null;
+	return {
+		requiredMode,
+		...typeof bag.currentMode === "string" ? { currentMode: bag.currentMode } : {}
+	};
+}
+/**
 * Specific predicate for validation failures (Fastify AJV + Mongoose
 * ValidationError). When true, `error.fieldErrors` is populated with the
 * `{ field: message }` map. Matches arc's `arc.validation_error` and the
@@ -756,6 +799,10 @@ async function executeRequest(config, method, endpoint, options = {}) {
 		...options,
 		idempotencyKey: globalThis.crypto.randomUUID()
 	};
+	if (config.cache !== void 0 && options.cache === void 0 && options.revalidate === void 0 && options.next === void 0) options = {
+		...options,
+		cache: config.cache
+	};
 	const handler = authConfig?.onAuthError;
 	if (!handler) return executeWithBackoff(config, method, endpoint, options);
 	const retryOn403 = authConfig?.retryOn403 ?? false;
@@ -825,8 +872,10 @@ function withTimeoutSignal(signal, timeoutMs) {
 	const controller = new AbortController();
 	let timedOut = false;
 	const onCallerAbort = () => controller.abort();
-	if (signal) if (signal.aborted) controller.abort();
-	else signal.addEventListener("abort", onCallerAbort, { once: true });
+	if (signal) {
+		if (signal.aborted) controller.abort();
+		else signal.addEventListener("abort", onCallerAbort, { once: true });
+	}
 	const timer = setTimeout(() => {
 		timedOut = true;
 		controller.abort();
@@ -899,7 +948,7 @@ async function executeAttempt(config, method, endpoint, options, attempt) {
 		if (revalidate !== void 0) nextCfg.revalidate = revalidate;
 		if (tags) nextCfg.tags = nextCfg.tags ? [...nextCfg.tags, ...tags] : tags;
 		if (nextCfg.revalidate !== void 0 || nextCfg.tags) fetchOptions.next = nextCfg;
-		if (!/^https?:\/\//i.test(endpoint) && !config.baseUrl) throw new Error(`[arc-next] handleApiRequest(${method} ${endpoint}): baseUrl is empty. Call configureClient({ baseUrl: '...' }) BEFORE the first request. If you use createAuthAwareClient() at module top-level, make sure the Providers component runs configureClient() first (e.g. in a useState() initializer, before the children render).`);
+		if (!/^https?:\/\//i.test(endpoint) && !config.baseUrl) throw new Error(`[arc-next] handleApiRequest(${method} ${endpoint}): baseUrl is empty. ` + (typeof window === "undefined" ? "On the server, configureClient() is a no-op — configure a request-scoped client instead: createServerClient({ baseUrl }), or your SDK's server config (e.g. a server env baseUrl / runWithSDKConfig) so SSR reads resolve." : "Call configureClient({ baseUrl: '...' }) at app boot (Providers) BEFORE the first request — e.g. in a useState() initializer, before the children render."));
 		const response = await fetch(`${config.baseUrl}${endpoint}`, fetchOptions);
 		if (!response.ok) {
 			let json = null;
@@ -1105,7 +1154,7 @@ function arcAuthHeaders() {
 * Lower-cased on lookup so case-insensitive HTTP header semantics are
 * honored (`Authorization` vs `authorization` both protected).
 */
-const ARC_FETCH_PROTECTED_HEADERS = new Set([
+const ARC_FETCH_PROTECTED_HEADERS = /* @__PURE__ */ new Set([
 	"authorization",
 	"x-organization-id",
 	"x-internal-api-key"
@@ -1227,4 +1276,4 @@ const arc = {
 };
 
 //#endregion
-export { ArcApiError, KNOWN_ARC_ERROR_CODES, _getAuthErrorHandler, _isAuthRecoverable, _resetArcFetchClient, _resetAuthRecovery, _resetAuthWarnings, _resolveRefreshedToken, _runAuthRecovery, arc, arcAuthHeaders, arcFetch, buildStreamUrl, configureAuth, configureClient, createAuthAwareClient, createAuthRefreshHandler, createClient, createQueryString, createServerClient, getAuthContext, getAuthMode, getBaseUrl, getClientAuthContext, getQuotaDetails, handleApiRequest, hasGlobalStaticAuth, isAbortError, isArcApiError, isArcErrorCode, isAutoIdempotency, isDuplicateKeyError, isOrgContextRequiredError, isQuotaExceeded, isValidationError };
+export { ArcApiError, KNOWN_ARC_ERROR_CODES, _getAuthErrorHandler, _isAuthRecoverable, _resetArcFetchClient, _resetAuthRecovery, _resetAuthWarnings, _resolveRefreshedToken, _runAuthRecovery, arc, arcAuthHeaders, arcFetch, buildStreamUrl, configureAuth, configureClient, createAuthAwareClient, createAuthRefreshHandler, createClient, createQueryString, createServerClient, getAuthContext, getAuthMode, getBaseUrl, getClientAuthContext, getQuotaDetails, getTierRequirement, handleApiRequest, hasGlobalStaticAuth, isAbortError, isArcApiError, isArcErrorCode, isAutoIdempotency, isDuplicateKeyError, isOrgContextRequiredError, isQuotaExceeded, isTierRequiredError, isValidationError };

package/dist/encryption.d.ts

@@ -1,5 +1,4 @@
 import { ClientEncryptionConfig } from "./client.js";
-
 //#region src/encryption.d.ts
 /** Key material accepted by jose in browser + Node (Web Crypto). */
 type JoseKey = CryptoKey | Uint8Array;

package/dist/hooks.d.ts

@@ -10,7 +10,6 @@ import { TreeMethods } from "./presets/tree.js";
 import { DetailQueryOptions, DetailQueryResult, InfiniteListQueryOptions, InfiniteListQueryResult, ListQueryOptions, ListQueryResult, RequestPassthrough } from "./query.js";
 import { QueryKey, UseQueryResult } from "@tanstack/react-query";
 import { PaginatedResult } from "@classytic/repo-core/pagination";
-
 //#region src/hooks.d.ts
 /**
  * CRUD API interface accepted by createCrudHooks.
@@ -25,7 +24,8 @@ import { PaginatedResult } from "@classytic/repo-core/pagination";
 type CrudApi<T = unknown, TCreate = Partial<T>, TUpdate = Partial<T>> = Pick<BaseApi<T, TCreate, TUpdate>, "getAll" | "getById" | "create" | "update" | "delete" | "count"> & {
   upload?: BaseApi<T, TCreate, TUpdate>["upload"];
   dispatchAction?: BaseApi<T, TCreate, TUpdate>["dispatchAction"];
-  invokeRoute?: BaseApi<T, TCreate, TUpdate>["invokeRoute"]; /** Declared aggregations (arc 2.13+). Always available on BaseApi. */
+  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. */
@@ -182,11 +182,15 @@ interface CrudHooksReturn<T, TCreate, TUpdate> {
   KEYS: QueryKeys;
   cache: CacheUtils<T>;
   useList: {
-    /** New signature — auto-injects token/orgId from configureAuth() context */(params?: Record<string, unknown>, options?: ListQueryOptions<T>): ListQueryResult<T>; /** Legacy signature — explicit token */
+    /** New signature — auto-injects token/orgId from configureAuth() context */
+    (params?: Record<string, unknown>, options?: ListQueryOptions<T>): ListQueryResult<T>;
+    /** Legacy signature — explicit token */
     (token: string | null, params?: Record<string, unknown>, options?: ListQueryOptions<T>): ListQueryResult<T>;
   };
   useDetail: {
-    /** New signature — auto-injects token from configureAuth() context */(id: string | null, options?: DetailQueryOptions<T>): DetailQueryResult<T>; /** Legacy signature — explicit token */
+    /** New signature — auto-injects token from configureAuth() context */
+    (id: string | null, options?: DetailQueryOptions<T>): DetailQueryResult<T>;
+    /** Legacy signature — explicit token */
     (id: string | null, token: string | null, options?: DetailQueryOptions<T>): DetailQueryResult<T>;
   };
   /**
@@ -202,7 +206,9 @@ interface CrudHooksReturn<T, TCreate, TUpdate> {
    */
   useSuspenseDetail: (id: string, options?: Omit<DetailQueryOptions<T>, "enabled">) => DetailQueryResult<T>;
   useInfiniteList: {
-    /** New signature — auto-injects token/orgId from configureAuth() context */(params?: Record<string, unknown>, options?: InfiniteListQueryOptions): InfiniteListQueryResult<T>; /** Legacy signature — explicit token */
+    /** New signature — auto-injects token/orgId from configureAuth() context */
+    (params?: Record<string, unknown>, options?: InfiniteListQueryOptions): InfiniteListQueryResult<T>;
+    /** Legacy signature — explicit token */
     (token: string | null, params?: Record<string, unknown>, options?: InfiniteListQueryOptions): InfiniteListQueryResult<T>;
   };
   useActions: () => CrudActions<T, TCreate, TUpdate>;
@@ -223,7 +229,8 @@ interface CrudHooksReturn<T, TCreate, TUpdate> {
    * (approve/cancel/dispatch) instead of bespoke routes.
    */
   useAction: <TResult = T, TBody extends Record<string, unknown> = Record<string, unknown>>(options?: {
-    invalidateQueries?: QueryKey[]; /** Default action name. Can be overridden per-call via `mutate({ action })`. */
+    invalidateQueries?: QueryKey[];
+    /** Default action name. Can be overridden per-call via `mutate({ action })`. */
     action?: string;
     messages?: MutationMessages<TResult, {
       id: string;
@@ -335,15 +342,20 @@ interface CrudHooksReturn<T, TCreate, TUpdate> {
    * `ssePlugin` (`/events/stream`). Pass `enabled: false` to opt out.
    */
   useResourceSync: (options?: {
-    source?: "ws" | "sse"; /** Override resource name. Defaults to the factory's `entityKey`. */
-    resource?: string; /** Override path (default: `/ws` or `/events/stream`). */
-    path?: string; /** Whether the connection is active. Default: true. */
-    enabled?: boolean; /** Per-event hook fired AFTER cache invalidation. */
+    source?: "ws" | "sse";
+    /** Override resource name. Defaults to the factory's `entityKey`. */
+    resource?: string;
+    /** Override path (default: `/ws` or `/events/stream`). */
+    path?: string;
+    /** Whether the connection is active. Default: true. */
+    enabled?: boolean;
+    /** Per-event hook fired AFTER cache invalidation. */
     onEvent?: (event: {
       operation: "created" | "updated" | "deleted";
       id?: string;
       data: unknown;
-    }) => void; /** Connection-state listener. */
+    }) => void;
+    /** Connection-state listener. */
     onConnectionChange?: (connected: boolean) => void;
   }) => {
     isConnected: boolean;
@@ -360,15 +372,6 @@ interface CrudHooksReturn<T, TCreate, TUpdate> {
  * configureNavigation(useRouter);
  */
 declare function configureNavigation(hook: UseRouterHook): void;
-declare function createCrudHooks<T, TCreate = Partial<T>, TUpdate = Partial<T>>({
-  api,
-  entityKey,
-  singular,
-  plural,
-  idField,
-  defaults,
-  callbacks,
-  client
-}: CrudHooksConfig<T, TCreate, TUpdate>): CrudHooksReturn<T, TCreate, TUpdate>;
+declare function createCrudHooks<T, TCreate = Partial<T>, TUpdate = Partial<T>>({ api, entityKey, singular, plural, idField, defaults, callbacks, client }: CrudHooksConfig<T, TCreate, TUpdate>): CrudHooksReturn<T, TCreate, TUpdate>;
 //#endregion
 export { AggregationQueryOptions, BulkActions, CallOptions, CrudActions, CrudApi, CrudHooksConfig, CrudHooksReturn, DeleteParams, MutationParams, NavigateFn, NavigationOptions, UpdateParams, configureNavigation, createCrudHooks };

package/dist/hooks.js

@@ -305,11 +305,12 @@ function createCrudHooks({ api, entityKey, singular, plural, idField, defaults =
 					tempId = resolveItemId(data) ?? `temp-${globalThis.crypto?.randomUUID?.() ?? Date.now()}`;
 					tempIdsRef.current.set(variables, tempId);
 				}
-				return prependToListCache(oldData, {
+				const optimisticItem = {
 					...data,
 					_optimistic: true,
 					[idField ?? (resolveItemId(data) ? "id" : "_id")]: tempId
-				});
+				};
+				return prependToListCache(oldData, optimisticItem);
 			},
 			reconcile: (raw, variables) => {
 				const serverDoc = extractItem(raw);
@@ -462,7 +463,8 @@ function createCrudHooks({ api, entityKey, singular, plural, idField, defaults =
 			create: useCallback(async (params, options) => {
 				silentRef.current = options?.silent ?? false;
 				try {
-					const entity = extractItem(await createMutation.mutateAsync(resolveActionAuth(params)));
+					const raw = await createMutation.mutateAsync(resolveActionAuth(params));
+					const entity = extractItem(raw);
 					options?.onSuccess?.(entity);
 					options?.onSettled?.(entity, null);
 					return entity;
@@ -477,7 +479,8 @@ function createCrudHooks({ api, entityKey, singular, plural, idField, defaults =
 			update: useCallback(async (params, options) => {
 				silentRef.current = options?.silent ?? false;
 				try {
-					const entity = extractItem(await enqueueWrite(params.id, () => updateMutation.mutateAsync(resolveActionAuth(params))));
+					const raw = await enqueueWrite(params.id, () => updateMutation.mutateAsync(resolveActionAuth(params)));
+					const entity = extractItem(raw);
 					options?.onSuccess?.(entity);
 					options?.onSettled?.(entity, null);
 					return entity;
@@ -507,7 +510,8 @@ function createCrudHooks({ api, entityKey, singular, plural, idField, defaults =
 			restore: useCallback(async (params, options) => {
 				silentRef.current = options?.silent ?? false;
 				try {
-					const entity = extractItem(await enqueueWrite(params.id, () => restoreMutation.mutateAsync(resolveActionAuth(params))));
+					const raw = await enqueueWrite(params.id, () => restoreMutation.mutateAsync(resolveActionAuth(params)));
+					const entity = extractItem(raw);
 					options?.onSuccess?.(entity);
 					options?.onSettled?.(entity, null);
 					return entity;

package/dist/mutation.d.ts

@@ -1,7 +1,5 @@
 import { ToastHandler } from "./client.js";
-import * as _$_tanstack_react_query0 from "@tanstack/react-query";
 import { QueryClient, QueryKey, UseMutateAsyncFunction, UseMutateFunction } from "@tanstack/react-query";
-
 //#region src/mutation.d.ts
 /**
  * Toast copy for a mutation. Generic over the mutation's result/variables so
@@ -152,7 +150,7 @@ interface CreateOptimisticMutationConfig<TData, TVariables> {
   shouldToast?: () => boolean;
   toastHandler?: ToastHandler;
 }
-declare function useOptimisticMutation<TData, TVariables>(config: CreateOptimisticMutationConfig<TData, TVariables>): _$_tanstack_react_query0.UseMutationResult<TData, Error, TVariables, {
+declare function useOptimisticMutation<TData, TVariables>(config: CreateOptimisticMutationConfig<TData, TVariables>): import("@tanstack/react-query").UseMutationResult<TData, Error, TVariables, {
   previous: {
     key: readonly unknown[];
     data: [readonly unknown[], unknown][];

package/dist/mutation.js

@@ -82,8 +82,10 @@ function useMutationWithTransition(config) {
 					queryClient.invalidateQueries({ queryKey: key });
 				});
 			};
-			if (invalidateQueries.length > 0 && (config.shouldInvalidate?.(data) ?? true)) if (withTransition) startTransition(invalidate);
-			else invalidate();
+			if (invalidateQueries.length > 0 && (config.shouldInvalidate?.(data) ?? true)) {
+				if (withTransition) startTransition(invalidate);
+				else invalidate();
+			}
 			if (toast && (config.shouldToast?.() ?? true)) showToast("success", messages, data, variables, void 0, instanceToast);
 			onSuccess?.(data, variables);
 		},

package/dist/prefetch.d.ts

@@ -1,6 +1,5 @@
 import { EntityReadApi } from "./query-options.js";
 import { HydrationBoundary, InfiniteData, QueryClient, dehydrate } from "@tanstack/react-query";
-
 //#region src/prefetch.d.ts
 interface PrefetchAuthContext {
   /** Auth token for protected endpoints. Required for bearer/header auth on server. */

package/dist/presets/bulk.d.ts

@@ -1,6 +1,5 @@
 import { AnyBaseApi, CreateOf, DocOf, ScopedArgs, UpdateOf } from "../api.js";
 import { BulkCreateResult, DeleteManyResult, UpdateManyResult } from "@classytic/repo-core/repository";
-
 //#region src/presets/bulk.d.ts
 interface BulkMethods<TDoc, TCreate = Partial<TDoc>, TUpdate = Partial<TDoc>> {
   /** Insert many docs in one round-trip. Backend mounts `POST /:resource/bulk`. */

package/dist/presets/history.d.ts

@@ -1,5 +1,4 @@
 import { AnyBaseApi, ScopedArgs } from "../api.js";
-
 //#region src/presets/history.d.ts
 /** One audit-trail entry — arc's `AuditEntry` wire shape for a single record. */
 interface HistoryEntry {

package/dist/presets/search.d.ts

@@ -1,6 +1,5 @@
 import { AnyBaseApi, DocOf, ScopedArgs } from "../api.js";
 import { PaginatedResult } from "@classytic/repo-core/pagination";
-
 //#region src/presets/search.d.ts
 interface SearchPresetMethods<TDoc> {
   /**
@@ -8,8 +7,11 @@ interface SearchPresetMethods<TDoc> {
    * Backend mounts `POST /:resource/search` via `searchPreset()`.
    */
   searchEngine<TResult = TDoc, TBody extends Record<string, unknown> = Record<string, unknown>>(args?: ScopedArgs & {
-    /** Free-text query forwarded as `body.query`. */query?: string; /** Engine-specific options merged into the request body. */
-    body?: TBody; /** Override path (default `/search`). */
+    /** Free-text query forwarded as `body.query`. */
+    query?: string;
+    /** Engine-specific options merged into the request body. */
+    body?: TBody;
+    /** Override path (default `/search`). */
     path?: string;
   }): Promise<TResult[] | PaginatedResult<TResult>>;
   /**
@@ -17,9 +19,13 @@ interface SearchPresetMethods<TDoc> {
    * Backend mounts `POST /:resource/search-similar`.
    */
   searchSimilar<TResult = TDoc, TBody extends Record<string, unknown> = Record<string, unknown>>(args?: ScopedArgs & {
-    /** Text query — backend embeds and searches for nearest neighbors. */query?: string; /** Pre-computed embedding vector — used directly for similarity search. */
-    vector?: number[]; /** Vector-engine options (`topK`, `filter`, `index`, ...). */
-    body?: TBody; /** Override path (default `/search-similar`). */
+    /** Text query — backend embeds and searches for nearest neighbors. */
+    query?: string;
+    /** Pre-computed embedding vector — used directly for similarity search. */
+    vector?: number[];
+    /** Vector-engine options (`topK`, `filter`, `index`, ...). */
+    body?: TBody;
+    /** Override path (default `/search-similar`). */
     path?: string;
   }): Promise<TResult[]>;
   /**
@@ -27,8 +33,11 @@ interface SearchPresetMethods<TDoc> {
    * Backend mounts `POST /:resource/embed`.
    */
   embed(args: ScopedArgs & {
-    /** Text or array of texts to embed. */input: string | string[]; /** Embed-engine options (`model`, `dimensions`, ...). */
-    body?: Record<string, unknown>; /** Override path (default `/embed`). */
+    /** Text or array of texts to embed. */
+    input: string | string[];
+    /** Embed-engine options (`model`, `dimensions`, ...). */
+    body?: Record<string, unknown>;
+    /** Override path (default `/embed`). */
     path?: string;
   }): Promise<number[] | number[][]>;
 }

package/dist/presets/slug.d.ts

@@ -1,5 +1,4 @@
 import { AnyBaseApi, DocOf, ScopedArgs } from "../api.js";
-
 //#region src/presets/slug.d.ts
 interface SlugLookupMethods<TDoc> {
   /** Fetch a single doc by slug. Backend mounts `GET /:resource/slug/:slug`. */

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

@@ -1,6 +1,5 @@
 import { AnyBaseApi, DocOf, QueryParams, ScopedArgs } from "../api.js";
 import { PaginatedResult } from "@classytic/repo-core/pagination";
-
 //#region src/presets/soft-delete.d.ts
 interface SoftDeleteMethods<TDoc> {
   /** List soft-deleted docs. Backend mounts `GET /:resource/deleted`. */

package/dist/presets/tree.d.ts

@@ -1,6 +1,5 @@
 import { AnyBaseApi, DocOf, QueryParams, ScopedArgs } from "../api.js";
 import { PaginatedResult } from "@classytic/repo-core/pagination";
-
 //#region src/presets/tree.d.ts
 interface TreeMethods<TDoc> {
   /** Fetch the full hierarchy. Backend mounts `GET /:resource/tree`. */

package/dist/query-client.d.ts

@@ -1,5 +1,4 @@
 import { QueryClient } from "@tanstack/react-query";
-
 //#region src/query-client.d.ts
 interface QueryClientOverrides {
   staleTime?: number;

package/dist/query-client.js

@@ -3,8 +3,8 @@ import { QueryClient, defaultShouldDehydrateQuery, isServer } from "@tanstack/re
 
 //#region src/query-client.ts
 const DEFAULTS = {
-	staleTime: 300 * 1e3,
-	gcTime: 1800 * 1e3,
+	staleTime: 3e5,
+	gcTime: 18e5,
 	retry: 0,
 	refetchOnWindowFocus: false
 };

package/dist/query-options.d.ts

@@ -1,6 +1,4 @@
 import { QueryKeys } from "./cache.js";
-import * as _$_tanstack_react_query0 from "@tanstack/react-query";
-
 //#region src/query-options.d.ts
 /** Per-call request context: auth + Next.js fetch caching passthrough. */
 interface QueryFnContext {
@@ -91,57 +89,65 @@ type EntityQueries = ReturnType<typeof createEntityQueries>;
  * await queryClient.ensureQueryData(productQueries.detail(id, { token }));
  */
 declare function createEntityQueries(api: EntityReadApi, entityKey: string): {
-  /** The entity's key factory — for invalidation / setQueryData at call sites. */keys: QueryKeys; /** GET /:resource — mirrors `useList`'s key (scoped, org-normalized). */
-  list(params?: Record<string, unknown>, ctx?: QueryFnContext): _$_tanstack_react_query0.OmitKeyof<_$_tanstack_react_query0.UseQueryOptions<unknown, Error, unknown, readonly unknown[]>, "queryFn"> & {
-    queryFn?: _$_tanstack_react_query0.QueryFunction<unknown, readonly unknown[], never> | undefined;
+  /** The entity's key factory — for invalidation / setQueryData at call sites. */
+  keys: QueryKeys;
+  /** GET /:resource — mirrors `useList`'s key (scoped, org-normalized). */
+  list(params?: Record<string, unknown>, ctx?: QueryFnContext): import("@tanstack/react-query").OmitKeyof<import("@tanstack/react-query").UseQueryOptions<unknown, Error, unknown, readonly unknown[]>, "queryFn"> & {
+    queryFn?: import("@tanstack/react-query").QueryFunction<unknown, readonly unknown[], never> | undefined;
   } & {
     queryKey: readonly unknown[] & {
       [dataTagSymbol]: unknown;
       [dataTagErrorSymbol]: Error;
     };
-  }; /** GET /:resource/:id — mirrors `useDetail`'s scoped key (+ params variant). */
-  detail(id: string, opts?: DetailQueryOpts): _$_tanstack_react_query0.OmitKeyof<_$_tanstack_react_query0.UseQueryOptions<unknown, Error, unknown, readonly unknown[]>, "queryFn"> & {
-    queryFn?: _$_tanstack_react_query0.QueryFunction<unknown, readonly unknown[], never> | undefined;
+  };
+  /** GET /:resource/:id — mirrors `useDetail`'s scoped key (+ params variant). */
+  detail(id: string, opts?: DetailQueryOpts): import("@tanstack/react-query").OmitKeyof<import("@tanstack/react-query").UseQueryOptions<unknown, Error, unknown, readonly unknown[]>, "queryFn"> & {
+    queryFn?: import("@tanstack/react-query").QueryFunction<unknown, readonly unknown[], never> | undefined;
   } & {
     queryKey: readonly unknown[] & {
       [dataTagSymbol]: unknown;
       [dataTagErrorSymbol]: Error;
     };
-  }; /** GET /:resource/slug/:slug — mirrors `useDetailBySlug`'s key. */
-  bySlug(slug: string, opts?: DetailQueryOpts): _$_tanstack_react_query0.OmitKeyof<_$_tanstack_react_query0.UseQueryOptions<unknown, Error, unknown, readonly unknown[]>, "queryFn"> & {
-    queryFn?: _$_tanstack_react_query0.QueryFunction<unknown, readonly unknown[], never> | undefined;
+  };
+  /** GET /:resource/slug/:slug — mirrors `useDetailBySlug`'s key. */
+  bySlug(slug: string, opts?: DetailQueryOpts): import("@tanstack/react-query").OmitKeyof<import("@tanstack/react-query").UseQueryOptions<unknown, Error, unknown, readonly unknown[]>, "queryFn"> & {
+    queryFn?: import("@tanstack/react-query").QueryFunction<unknown, readonly unknown[], never> | undefined;
   } & {
     queryKey: readonly unknown[] & {
       [dataTagSymbol]: unknown;
       [dataTagErrorSymbol]: Error;
     };
-  }; /** GET /:resource/deleted — mirrors `useDeleted`'s key. */
-  deleted(params?: Record<string, unknown>, ctx?: QueryFnContext): _$_tanstack_react_query0.OmitKeyof<_$_tanstack_react_query0.UseQueryOptions<unknown, Error, unknown, readonly unknown[]>, "queryFn"> & {
-    queryFn?: _$_tanstack_react_query0.QueryFunction<unknown, readonly unknown[], never> | undefined;
+  };
+  /** GET /:resource/deleted — mirrors `useDeleted`'s key. */
+  deleted(params?: Record<string, unknown>, ctx?: QueryFnContext): import("@tanstack/react-query").OmitKeyof<import("@tanstack/react-query").UseQueryOptions<unknown, Error, unknown, readonly unknown[]>, "queryFn"> & {
+    queryFn?: import("@tanstack/react-query").QueryFunction<unknown, readonly unknown[], never> | undefined;
   } & {
     queryKey: readonly unknown[] & {
       [dataTagSymbol]: unknown;
       [dataTagErrorSymbol]: Error;
     };
-  }; /** GET /:resource/tree — mirrors `useTree`'s key. */
-  tree(params?: Record<string, unknown>, ctx?: QueryFnContext): _$_tanstack_react_query0.OmitKeyof<_$_tanstack_react_query0.UseQueryOptions<unknown, Error, unknown, readonly unknown[]>, "queryFn"> & {
-    queryFn?: _$_tanstack_react_query0.QueryFunction<unknown, readonly unknown[], never> | undefined;
+  };
+  /** GET /:resource/tree — mirrors `useTree`'s key. */
+  tree(params?: Record<string, unknown>, ctx?: QueryFnContext): import("@tanstack/react-query").OmitKeyof<import("@tanstack/react-query").UseQueryOptions<unknown, Error, unknown, readonly unknown[]>, "queryFn"> & {
+    queryFn?: import("@tanstack/react-query").QueryFunction<unknown, readonly unknown[], never> | undefined;
   } & {
     queryKey: readonly unknown[] & {
       [dataTagSymbol]: unknown;
       [dataTagErrorSymbol]: Error;
     };
-  }; /** GET /:resource/:parentId/children — mirrors `useChildren`'s key. */
-  children(parentId: string, params?: Record<string, unknown>, ctx?: QueryFnContext): _$_tanstack_react_query0.OmitKeyof<_$_tanstack_react_query0.UseQueryOptions<unknown, Error, unknown, readonly unknown[]>, "queryFn"> & {
-    queryFn?: _$_tanstack_react_query0.QueryFunction<unknown, readonly unknown[], never> | undefined;
+  };
+  /** GET /:resource/:parentId/children — mirrors `useChildren`'s key. */
+  children(parentId: string, params?: Record<string, unknown>, ctx?: QueryFnContext): import("@tanstack/react-query").OmitKeyof<import("@tanstack/react-query").UseQueryOptions<unknown, Error, unknown, readonly unknown[]>, "queryFn"> & {
+    queryFn?: import("@tanstack/react-query").QueryFunction<unknown, readonly unknown[], never> | undefined;
   } & {
     queryKey: readonly unknown[] & {
       [dataTagSymbol]: unknown;
       [dataTagErrorSymbol]: Error;
     };
-  }; /** GET /:resource/aggregations/:name — mirrors `useAggregation`'s tenant-scoped key. */
-  aggregation(name: string, filter?: Record<string, unknown>, ctx?: QueryFnContext): _$_tanstack_react_query0.OmitKeyof<_$_tanstack_react_query0.UseQueryOptions<unknown, Error, unknown, readonly unknown[]>, "queryFn"> & {
-    queryFn?: _$_tanstack_react_query0.QueryFunction<unknown, readonly unknown[], never> | undefined;
+  };
+  /** GET /:resource/aggregations/:name — mirrors `useAggregation`'s tenant-scoped key. */
+  aggregation(name: string, filter?: Record<string, unknown>, ctx?: QueryFnContext): import("@tanstack/react-query").OmitKeyof<import("@tanstack/react-query").UseQueryOptions<unknown, Error, unknown, readonly unknown[]>, "queryFn"> & {
+    queryFn?: import("@tanstack/react-query").QueryFunction<unknown, readonly unknown[], never> | undefined;
   } & {
     queryKey: readonly unknown[] & {
       [dataTagSymbol]: unknown;
@@ -152,11 +158,11 @@ declare function createEntityQueries(api: EntityReadApi, entityKey: string): {
    * Infinite list — mirrors `useInfiniteList`'s key (`scopedList + 'infinite'`)
    * and its page-param semantics (keyset cursor or offset page + 1).
    */
-  infiniteList(params?: Record<string, unknown>, ctx?: QueryFnContext): _$_tanstack_react_query0.OmitKeyof<_$_tanstack_react_query0.UseInfiniteQueryOptions<unknown, Error, _$_tanstack_react_query0.InfiniteData<unknown, unknown>, unknown[], unknown>, "queryFn"> & {
-    queryFn?: _$_tanstack_react_query0.QueryFunction<unknown, unknown[], unknown> | undefined;
+  infiniteList(params?: Record<string, unknown>, ctx?: QueryFnContext): import("@tanstack/react-query").OmitKeyof<import("@tanstack/react-query").UseInfiniteQueryOptions<unknown, Error, import("@tanstack/react-query").InfiniteData<unknown, unknown>, unknown[], unknown>, "queryFn"> & {
+    queryFn?: import("@tanstack/react-query").QueryFunction<unknown, unknown[], unknown> | undefined;
   } & {
     queryKey: unknown[] & {
-      [dataTagSymbol]: _$_tanstack_react_query0.InfiniteData<unknown, unknown>;
+      [dataTagSymbol]: import("@tanstack/react-query").InfiniteData<unknown, unknown>;
       [dataTagErrorSymbol]: Error;
     };
   };

package/dist/query.d.ts

@@ -1,6 +1,5 @@
 import { CacheUtils, DEFAULT_QUERY_CONFIG, PaginationData, QUERY_CONFIGS, QueryKeys, createCacheUtils, createQueryKeys, extractItem, extractItems, getItemId, normalizePagination, updateListCache } from "./cache.js";
 import { InfiniteData, QueryClient, QueryKey } from "@tanstack/react-query";
-
 //#region src/query.d.ts
 /** Request-level options passed through to the fetch call */
 interface RequestPassthrough {
@@ -143,13 +142,7 @@ interface CreateListQueryConfig {
  * directly via `placeholderData`, so the detail GET still fires while the
  * consumer sees an instant list-shaped preview. See `findItemInListCache`.
  */
-declare function useListQuery<T>({
-  queryKey,
-  queryFn,
-  enabled,
-  options,
-  select
-}: CreateListQueryConfig): ListQueryResult<T>;
+declare function useListQuery<T>({ queryKey, queryFn, enabled, options, select }: CreateListQueryConfig): ListQueryResult<T>;
 /**
  * Find an item in any list cache for this entity by ID.
  *
@@ -187,28 +180,11 @@ interface CreateDetailQueryConfig<T = unknown> {
    */
   placeholderData?: () => T | undefined;
 }
-declare function useDetailQuery<T>({
-  queryKey,
-  queryFn,
-  enabled,
-  options,
-  select,
-  placeholderData
-}: CreateDetailQueryConfig<T>): DetailQueryResult<T>;
+declare function useDetailQuery<T>({ queryKey, queryFn, enabled, options, select, placeholderData }: CreateDetailQueryConfig<T>): DetailQueryResult<T>;
 /** Suspense variant of {@link useListQuery}. Always enabled; suspends until resolved. */
-declare function useSuspenseListQuery<T>({
-  queryKey,
-  queryFn,
-  options,
-  select
-}: Omit<CreateListQueryConfig, "enabled">): ListQueryResult<T>;
+declare function useSuspenseListQuery<T>({ queryKey, queryFn, options, select }: Omit<CreateListQueryConfig, "enabled">): ListQueryResult<T>;
 /** Suspense variant of {@link useDetailQuery}. Always enabled; suspends until resolved. */
-declare function useSuspenseDetailQuery<T>({
-  queryKey,
-  queryFn,
-  options,
-  select
-}: Omit<CreateDetailQueryConfig<T>, "enabled" | "placeholderData">): DetailQueryResult<T>;
+declare function useSuspenseDetailQuery<T>({ queryKey, queryFn, options, select }: Omit<CreateDetailQueryConfig<T>, "enabled" | "placeholderData">): DetailQueryResult<T>;
 interface InfiniteListQueryOptions {
   public?: boolean;
   enabled?: boolean;
@@ -257,16 +233,7 @@ interface CreateInfiniteListQueryConfig {
   /** Max pages to keep in memory. Old pages are evicted when exceeded. */
   maxPages?: number;
 }
-declare function useInfiniteListQuery<T>({
-  queryKey,
-  queryFn,
-  enabled,
-  options,
-  initialPageParam,
-  getNextPageParam,
-  getPreviousPageParam,
-  maxPages
-}: CreateInfiniteListQueryConfig): InfiniteListQueryResult<T>;
+declare function useInfiniteListQuery<T>({ queryKey, queryFn, enabled, options, initialPageParam, getNextPageParam, getPreviousPageParam, maxPages }: CreateInfiniteListQueryConfig): InfiniteListQueryResult<T>;
 /** Recognized data-freshness presets. Maps to QUERY_CONFIGS. */
 type QueryFreshness = keyof typeof QUERY_CONFIGS;
 /**
@@ -342,13 +309,6 @@ interface UseApiQueryResult<TData> {
  *   select: (res) => res.entries,
  * });
  */
-declare function useApiQuery<TResponse = unknown, TData = ExtractData<TResponse>>({
-  queryKey,
-  queryFn,
-  enabled,
-  freshness,
-  select,
-  options
-}: UseApiQueryConfig<TResponse, TData>): UseApiQueryResult<TData>;
+declare function useApiQuery<TResponse = unknown, TData = ExtractData<TResponse>>({ queryKey, queryFn, enabled, freshness, select, options }: UseApiQueryConfig<TResponse, TData>): UseApiQueryResult<TData>;
 //#endregion
 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, findItemInListCache, getItemId, normalizePagination, updateListCache, useApiQuery, useDetailQuery, useInfiniteListQuery, useListQuery, useSuspenseDetailQuery, useSuspenseListQuery };

package/dist/sse.d.ts

@@ -1,5 +1,4 @@
 import { QueryKey } from "@tanstack/react-query";
-
 //#region src/sse.d.ts
 /**
  * Build an authenticated SSE URL using the global client + auth singletons.

package/dist/sse.js

@@ -113,13 +113,14 @@ function subscribeToEvents(options) {
 			} catch {
 				payload = event.data;
 			}
-			dispatch(typeof payload === "object" && payload !== null && "type" in payload && "data" in payload ? payload : {
+			const parsed = typeof payload === "object" && payload !== null && "type" in payload && "data" in payload ? payload : {
 				type: eventType,
 				resource: resource ?? eventType.split(".")[0] ?? "",
 				data: payload,
 				timestamp: (/* @__PURE__ */ new Date()).toISOString(),
 				...event.lastEventId ? { id: event.lastEventId } : {}
-			});
+			};
+			dispatch(parsed);
 		});
 		es.onerror = () => {
 			try {

package/dist/upload.d.ts

@@ -1,7 +1,6 @@
 import { ArcClient, HttpMethod, ToastHandler } from "./client.js";
 import { MutationMessages } from "./mutation.js";
 import { QueryKey } from "@tanstack/react-query";
-
 //#region src/upload.d.ts
 /**
  * Upload-progress snapshot. Emitted on every native `xhr.upload.progress`

package/dist/upload.js

@@ -150,8 +150,9 @@ function uploadAttempt(options) {
 			const lengthComputable = event.lengthComputable;
 			const total = lengthComputable ? event.total : 0;
 			const loaded = event.loaded;
+			const percent = lengthComputable && total > 0 ? Math.min(100, Math.round(loaded / total * 100)) : 0;
 			onProgress({
-				percent: lengthComputable && total > 0 ? Math.min(100, Math.round(loaded / total * 100)) : 0,
+				percent,
 				loaded,
 				total,
 				lengthComputable
@@ -180,7 +181,8 @@ function uploadAttempt(options) {
 				resolve(body);
 				return;
 			}
-			reject(new ArcApiError(extractErrorMessage(body, statusText), {
+			const message = extractErrorMessage(body, statusText);
+			reject(new ArcApiError(message, {
 				status,
 				statusText,
 				json: body,

package/dist/ws.d.ts

@@ -1,5 +1,4 @@
 import { QueryKey } from "@tanstack/react-query";
-
 //#region src/ws.d.ts
 /**
  * Inbound message shape from Arc's `websocketPlugin` broadcasts.

package/dist/ws.js

@@ -123,18 +123,19 @@ function connectWs(options = {}) {
 			const isAuthClose = event.code === 1008 || event.code === 3401 || event.code === 4001 || event.code === 4401;
 			if (handler && isAuthClose && wsAuthRetries < maxAuthRetries) {
 				wsAuthRetries += 1;
+				const synthError = new ArcApiError(event.reason || `WebSocket closed with auth code ${event.code}`, {
+					status: 401,
+					statusText: "WebSocket auth failure",
+					json: {
+						code: "arc.websocket.unauthorized",
+						wsCloseCode: event.code,
+						reason: event.reason
+					},
+					endpoint: url ?? path,
+					method: "GET"
+				});
 				_runAuthRecovery(handler, {
-					error: new ArcApiError(event.reason || `WebSocket closed with auth code ${event.code}`, {
-						status: 401,
-						statusText: "WebSocket auth failure",
-						json: {
-							code: "arc.websocket.unauthorized",
-							wsCloseCode: event.code,
-							reason: event.reason
-						},
-						endpoint: url ?? path,
-						method: "GET"
-					}),
+					error: synthError,
 					request: {
 						method: "GET",
 						endpoint: url ?? path

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@classytic/arc-next",
-  "version": "0.12.0",
+  "version": "0.14.0",
   "description": "React + TanStack Query SDK for Arc resources",
   "type": "module",
   "sideEffects": false,
@@ -148,7 +148,7 @@
     "check:dead-code": "knip"
   },
   "peerDependencies": {
-    "@classytic/repo-core": ">=0.14.0",
+    "@classytic/repo-core": ">=0.24.0",
     "@tanstack/react-query": ">=5.62.0",
     "jose": ">=5.0.0",
     "react": ">=19.0.0"
@@ -171,7 +171,7 @@
     "@arethetypeswrong/cli": "^0.18.5",
     "@biomejs/biome": "^2.5.5",
     "@classytic/dev-tools": "^0.2.0",
-    "@classytic/repo-core": "^0.14.0",
+    "@classytic/repo-core": ">=0.24.0",
     "@tanstack/react-query": "^5.97.0",
     "@testing-library/react": "^16.3.2",
     "@types/react": "^19.2.14",
@@ -182,7 +182,7 @@
     "publint": "^0.3.21",
     "react": "^19.2.5",
     "react-dom": "^19.2.5",
-    "tsdown": "^0.21.7",
+    "tsdown": "^0.22.14",
     "typescript": "^6.0.2",
     "vitest": "^4.1.4"
   }