@classytic/arc-next 0.11.0 → 0.12.0

package/README.md

@@ -1,5 +1,7 @@
 # @classytic/arc-next
 
+[![Sponsor](https://img.shields.io/github/sponsors/classytic?style=flat-square&label=Sponsor&logo=GitHub&color=EA4AAA)](https://github.com/sponsors/classytic)
+
 React + TanStack Query SDK for the Arc backend framework. Typed CRUD hooks, optimistic updates with rollback, multi-tenant cache scoping, pagination normalization, real-time SSE.
 
 **Peers:** React 19+, TanStack React Query 5+
@@ -37,6 +39,10 @@ configureToast({ success: toast.success, error: toast.error });
 configureNavigation(useRouter);
 ```
 
+Without `configureToast`, mutation feedback is a silent no-op (0.12+) — the SDK never writes to your console; errors still reach `onError` / the rejected promise.
+
+> **Targets:** React 19 browser apps + Next.js App Router. React Native is NOT officially supported — the fetch client may work, but SSE needs an `EventSource` polyfill, uploads depend on RN's XHR/FormData behavior, and field encryption needs Web Crypto. File an issue if you need an RN adapter.
+
 `getToken` **must be synchronous** — cache async tokens out-of-band. Promise returns are dropped + warned in dev.
 
 ## Quick Start
@@ -388,6 +394,44 @@ Pure helpers (`createQueryKeys`, `extractItem`, `updateListCache`, etc.) live in
 
 TanStack Query manages a client-side cache; data fetched through arc-next hooks should NOT be wrapped in a Server Component's `'use cache'` directive (which would bake the hook output into the static render). Use `'use cache'` for non-arc Server Component fetches (e.g., direct DB queries, third-party APIs). The two layers compose cleanly because they target different cache tiers.
 
+## Request-Scoped Server Clients (0.12+)
+
+`configureClient` / `configureAuth` set module singletons — correct for the browser, wrong for servers where concurrent requests would share state. On the server, build a **request-scoped** client instead. The SDK never imports `next` or reads cookies itself: your framework code reads the request, the SDK gets plain values.
+
+```ts
+// app/orders/page.tsx (Server Component) — host reads cookies, SDK stays framework-free
+import { cookies } from 'next/headers';
+import { createServerClient } from '@classytic/arc-next/client';
+import { createCrudApi } from '@classytic/arc-next/api';
+
+export default async function OrdersPage() {
+  const client = createServerClient({
+    baseUrl: process.env.API_URL!,
+    token: (await cookies()).get('session')?.value ?? null,
+    organizationId: null,
+  });
+  const orders = createCrudApi<Order>('orders', { client });
+  const page = await orders.getAll({
+    options: { next: { revalidate: 60, tags: ['orders'] } },  // Next fetch-cache passthrough
+  });
+  // render...
+}
+```
+
+`next: { tags, revalidate }` and `cache:` are typed pass-throughs to `fetch` — inert on non-Next runtimes, no `next` peer dependency.
+
+## Optimistic Updates — the guarantees (0.12+)
+
+`useActions()` mutations uphold, in order:
+
+1. **Cancel-before-write** — in-flight refetches for affected keys are cancelled before the snapshot, so a late response can't be captured as "previous" state.
+2. **Every affected cache** — detail (bare + org-scoped + parameterized), flat lists, **infinite lists** (per-page; a create inserts into the first page only), while aggregation caches are never optimistically mutated (refetch-only).
+3. **Exact rollback** — on failure every touched entry is restored to its snapshot; untouched entries are never rewritten.
+4. **Temp-ID reconciliation** — `create` inserts a `_optimistic` placeholder with a `temp-…` id, then swaps it in place for the server document on success (and seeds `KEYS.detail(realId)`), so the row never flickers and the real id is immediately navigable.
+5. **Per-record ordering** — sequential `update`/`remove`/`restore` calls to the same record are chained (call order = server order); different records stay parallel.
+6. **Last-standing invalidation** — rapid sequential writes trigger ONE settled refetch (from the last pending write), so an early write's refetch can never overwrite a later write's optimistic state.
+7. **Bulk partial success** — `bulkUpdate`/`bulkRemove` reporting zero changes skip invalidation entirely; `bulkCreate` seeds detail caches from the returned documents.
+
 ## Errors
 
 ```ts
@@ -425,11 +469,17 @@ Network resilience for mutations + direct `handleApiRequest` calls (TanStack Que
 ```ts
 configureClient({
   baseUrl: process.env.NEXT_PUBLIC_API_URL!,
+  timeoutMs: 15_000,                   // per-attempt request timeout; hung fetches fail
+                                       // with a RETRYABLE TimeoutError. Default: disabled.
+                                       // Per-request override: options.timeoutMs (0 disables).
   retry: {
     attempts: 3,                       // 1 initial + 2 retries; default off
     backoff: 'exponential',            // 'exponential' | 'linear' | (attempt) => ms
+    jitter: 'full',                    // randomize delays in [0, computed] — anti-stampede. Default 'none'.
     // retryOn: [502, 503, 504],       // optional whitelist; default = network failures + 5xx, never 4xx, never AbortError
   },
+  // 429/503 responses with a Retry-After header override computed backoff —
+  // the parsed value is also exposed as ArcApiError.retryAfterMs.
   // Mutate outgoing requests (per attempt — retries re-run this)
   beforeRequest: (ctx) => ({
     ...ctx,

package/dist/api.d.ts

@@ -1,15 +1,26 @@
 import { ArcClient, NextFetchOptions } from "./client.js";
-import { AggregatePaginationResult, KeysetPaginationResult, OffsetPaginationResult, PaginatedResult } from "@classytic/repo-core/pagination";
+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";
-import { BracketOperator, BracketOperator as BracketOperator$1 } from "@classytic/repo-core/query-parser";
 
 //#region src/api.d.ts
-interface PopulateOption {
-  path: string;
-  select?: string;
-  match?: Record<string, unknown>;
-}
-type SortDirection = 1 | -1 | 'asc' | 'desc';
+/**
+ * URL-emittable subset of repo-core's canonical {@link ParsedPopulate} —
+ * the exact three fields `populate[path][select]` / `populate[path][match]`
+ * bracket emission supports. Derived (not re-declared) so a canonical field
+ * rename breaks HERE at compile time instead of silently drifting.
+ * `options` / nested `populate` are parse-side-only in repo-core and have
+ * no URL grammar, so they're intentionally absent.
+ */
+type PopulateOption = Pick<ParsedPopulate, "path" | "select" | "match">;
+/**
+ * Canonical repo-core sort direction (`1 | -1`) plus the URL-ergonomic
+ * string forms. The numeric core comes from `@classytic/repo-core/pagination`
+ * so the wire vocabulary can't drift; `'asc' | 'desc'` are an SDK-side
+ * convenience serialized to the same URL grammar.
+ */
+type SortDirection = SortDirection$1 | "asc" | "desc";
+/** Sort spec: record form (repo-core `SortSpec` widened to string directions) or the raw URL string. */
 type SortSpec = Record<string, SortDirection> | string;
 /**
  * Filter operators supported by arc-next URL emission.
@@ -26,17 +37,23 @@ type SortSpec = Record<string, SortDirection> | string;
  *    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 & {});
+type FilterOperator = BracketOperator$1 | "size" | "type" | "near" | "nearSphere" | "geoWithin" | "withinRadius" | (string & {});
 interface QueryParams {
   page?: number;
   limit?: number;
+  /** Keyset cursor — the CANONICAL wire param (repo-core `STANDARD_RESERVED_PARAMS`). */
   after?: string;
+  /**
+   * Alias for {@link QueryParams.after}. The server only knows `after`;
+   * `prepareParams` rewrites `cursor` → `after` at emission (explicit
+   * `after` wins when both are set). Prefer `after` in new code.
+   */
   cursor?: string;
   sort?: string;
   select?: string;
   populate?: string | string[];
   populateOptions?: PopulateOption[];
-  lean?: boolean | 'true' | 'false';
+  lean?: boolean | "true" | "false";
   /** Database-agnostic joins. Maps alias → collection or full lookup config. */
   lookup?: Record<string, string | {
     from: string;
@@ -59,7 +76,7 @@ interface RequestOptions {
    */
   next?: NextFetchOptions;
   headerOptions?: Record<string, string>;
-  responseType?: 'json' | 'blob' | 'text';
+  responseType?: "json" | "blob" | "text";
   signal?: AbortSignal;
 }
 /**
@@ -72,7 +89,7 @@ interface RequestOptions {
 interface ScopedArgs {
   token?: string | null;
   organizationId?: string | null;
-  options?: Omit<RequestOptions, 'token' | 'organizationId'>;
+  options?: Omit<RequestOptions, "token" | "organizationId">;
 }
 interface BaseApiConfig {
   basePath?: string;
@@ -87,7 +104,7 @@ interface BaseApiConfig {
 }
 declare class BaseApi<TDoc = Record<string, unknown>, TCreate = Partial<TDoc>, TUpdate = Partial<TDoc>> {
   readonly entity: string;
-  readonly config: Required<Omit<BaseApiConfig, 'client'>>;
+  readonly config: Required<Omit<BaseApiConfig, "client">>;
   readonly baseUrl: string;
   private readonly requestFn;
   constructor(entity: string, config?: BaseApiConfig);
@@ -121,7 +138,7 @@ declare class BaseApi<TDoc = Record<string, unknown>, TCreate = Partial<TDoc>, T
     token?: string | null;
     organizationId?: string | null;
     params?: QueryParams;
-    options?: Omit<RequestOptions, 'token' | 'organizationId'>;
+    options?: Omit<RequestOptions, "token" | "organizationId">;
   }): Promise<PaginatedResult<TDoc>>;
   /**
    * Count records matching the filters — arc's list-route dispatch verb
@@ -137,7 +154,7 @@ declare class BaseApi<TDoc = Record<string, unknown>, TCreate = Partial<TDoc>, T
     token?: string | null;
     organizationId?: string | null;
     params?: QueryParams;
-    options?: Omit<RequestOptions, 'token' | 'organizationId'>;
+    options?: Omit<RequestOptions, "token" | "organizationId">;
   }): Promise<number>;
   /** Whether ANY record matches the filters (`?_exists=true`). */
   exists({
@@ -149,7 +166,7 @@ declare class BaseApi<TDoc = Record<string, unknown>, TCreate = Partial<TDoc>, T
     token?: string | null;
     organizationId?: string | null;
     params?: QueryParams;
-    options?: Omit<RequestOptions, 'token' | 'organizationId'>;
+    options?: Omit<RequestOptions, "token" | "organizationId">;
   }): Promise<boolean>;
   /** Distinct values of a field across matching records (`?_distinct=field`). */
   distinct<TValue = unknown>({
@@ -163,7 +180,7 @@ declare class BaseApi<TDoc = Record<string, unknown>, TCreate = Partial<TDoc>, T
     organizationId?: string | null;
     field: string;
     params?: QueryParams;
-    options?: Omit<RequestOptions, 'token' | 'organizationId'>;
+    options?: Omit<RequestOptions, "token" | "organizationId">;
   }): Promise<TValue[]>;
   /** Shared raw GET against the list route (dispatch verbs bypass pagination parsing). */
   private getAllRaw;
@@ -181,7 +198,7 @@ declare class BaseApi<TDoc = Record<string, unknown>, TCreate = Partial<TDoc>, T
       select?: string;
       populate?: string | string[];
     };
-    options?: Omit<RequestOptions, 'token' | 'organizationId'>;
+    options?: Omit<RequestOptions, "token" | "organizationId">;
   }): Promise<TDoc>;
   create({
     token,
@@ -192,7 +209,7 @@ declare class BaseApi<TDoc = Record<string, unknown>, TCreate = Partial<TDoc>, T
     token?: string | null;
     organizationId?: string | null;
     data: TCreate;
-    options?: Omit<RequestOptions, 'token' | 'organizationId'>;
+    options?: Omit<RequestOptions, "token" | "organizationId">;
   }): Promise<TDoc>;
   update({
     token,
@@ -205,7 +222,7 @@ declare class BaseApi<TDoc = Record<string, unknown>, TCreate = Partial<TDoc>, T
     organizationId?: string | null;
     id: string;
     data: TUpdate;
-    options?: Omit<RequestOptions, 'token' | 'organizationId'>;
+    options?: Omit<RequestOptions, "token" | "organizationId">;
   }): Promise<TDoc>;
   delete({
     token,
@@ -216,7 +233,7 @@ declare class BaseApi<TDoc = Record<string, unknown>, TCreate = Partial<TDoc>, T
     token?: string | null;
     organizationId?: string | null;
     id: string;
-    options?: Omit<RequestOptions, 'token' | 'organizationId'>;
+    options?: Omit<RequestOptions, "token" | "organizationId">;
   }): Promise<DeleteResult>;
   upload({
     token,
@@ -230,7 +247,7 @@ declare class BaseApi<TDoc = Record<string, unknown>, TCreate = Partial<TDoc>, T
     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, {
+  request<TResponse = unknown>(method: "GET" | "POST" | "PATCH" | "PUT" | "DELETE", endpoint: string, {
     token,
     organizationId,
     data,
@@ -282,7 +299,7 @@ declare class BaseApi<TDoc = Record<string, unknown>, TCreate = Partial<TDoc>, T
     params,
     options
   }: ScopedArgs & {
-    method?: 'GET' | 'POST' | 'PATCH' | 'PUT' | 'DELETE'; /** Path relative to the resource baseUrl. Leading slash optional. */
+    method?: "GET" | "POST" | "PATCH" | "PUT" | "DELETE"; /** Path relative to the resource baseUrl. Leading slash optional. */
     path: string;
     data?: unknown;
     params?: QueryParams;

package/dist/api.js

@@ -1,6 +1,12 @@
 import { createQueryString, handleApiRequest } from "./client.js";
+import { STANDARD_RESERVED_PARAMS } from "@classytic/repo-core/query-parser";
 
 //#region src/api.ts
+for (const verb of [
+	"_count",
+	"_exists",
+	"_distinct"
+]) if (!STANDARD_RESERVED_PARAMS.has(verb)) throw new Error(`[arc-next] dispatch verb '${verb}' is not in repo-core STANDARD_RESERVED_PARAMS`);
 var BaseApi = class {
 	entity;
 	config;
@@ -62,6 +68,13 @@ var BaseApi = class {
 	prepareParams(params = {}) {
 		const result = {};
 		const CRITICAL_FILTERS = ["organizationId", "ownerId"];
+		if (params.cursor !== void 0) {
+			const { cursor, ...rest } = params;
+			params = params.after !== void 0 ? rest : {
+				...rest,
+				after: cursor
+			};
+		}
 		Object.entries(params).forEach(([key, value]) => {
 			if (CRITICAL_FILTERS.includes(key)) {
 				result[key] = value || null;
@@ -84,7 +97,7 @@ var BaseApi = class {
 				});
 				return;
 			}
-			if (value !== void 0 && value !== "") if (["page", "limit"].includes(key)) result[key] = parseInt(String(value)) || (key === "page" ? 1 : 10);
+			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(",");

package/dist/cache.d.ts

@@ -3,7 +3,7 @@ import { QueryClient, QueryKey } from "@tanstack/react-query";
 //#region src/cache.d.ts
 interface PaginationData {
   /** Pagination method detected from response (offset | keyset | aggregate) */
-  method: 'offset' | 'keyset' | 'aggregate' | null;
+  method: "offset" | "keyset" | "aggregate" | null;
   total: number;
   pages: number;
   page: number;
@@ -65,6 +65,24 @@ declare function extractItem<T>(data: unknown): T | null;
  * the array length changes.
  */
 declare function updateListCache<T>(listData: unknown, updater: (items: T[]) => T[]): unknown;
+/**
+ * Insert an item at the head of a list cache entry — the optimistic-create
+ * primitive. Unlike {@link updateListCache} with a prepending updater (which,
+ * on an infinite cache, would insert into EVERY page), this targets exactly
+ * one location: the first page of an infinite cache, or the single payload of
+ * a flat list. Totals adjust via `updateListCache`'s existing delta logic.
+ */
+declare function prependToListCache(listData: unknown, item: unknown): unknown;
+/**
+ * Replace an item (matched by id) across a list cache entry — the
+ * temp-ID-reconciliation primitive. After a create succeeds, the optimistic
+ * placeholder (`temp-…` id) is swapped for the server document in place, so
+ * the UI keeps the row (no flicker) while the id becomes real. Works on flat
+ * and infinite shapes via {@link updateListCache}.
+ */
+declare function replaceItemInListCache(listData: unknown, matchId: string, replacement: unknown, opts?: {
+  idField?: string;
+}): unknown;
 /**
  * After a detail fetch lands, propagate the fresh values into every cached
  * list entry that contains this item. The item's ID is resolved via
@@ -163,4 +181,4 @@ interface CacheUtils<T> {
  */
 declare function createCacheUtils<T>(KEYS: QueryKeys): CacheUtils<T>;
 //#endregion
-export { CacheUtils, DEFAULT_QUERY_CONFIG, PaginationData, QUERY_CONFIGS, QueryKeys, createCacheUtils, createQueryKeys, extractItem, extractItems, getItemId, normalizePagination, syncDetailToLists, updateListCache, withOrgParams };
+export { CacheUtils, DEFAULT_QUERY_CONFIG, PaginationData, QUERY_CONFIGS, QueryKeys, createCacheUtils, createQueryKeys, extractItem, extractItems, getItemId, normalizePagination, prependToListCache, replaceItemInListCache, syncDetailToLists, updateListCache, withOrgParams };

package/dist/cache.js

@@ -101,6 +101,18 @@ function updateListCache(listData, updater) {
 	if (Array.isArray(listData)) return updater(listData);
 	if (typeof listData !== "object") return listData;
 	const d = listData;
+	if (Array.isArray(d.pages) && Array.isArray(d.pageParams)) {
+		let changed = false;
+		const nextPages = d.pages.map((page) => {
+			const next = updateListCache(page, updater);
+			if (next !== page) changed = true;
+			return next;
+		});
+		return changed ? {
+			...d,
+			pages: nextPages
+		} : listData;
+	}
 	let arrayField = null;
 	for (const key of LIST_KEYS) if (Array.isArray(d[key])) {
 		arrayField = key;
@@ -127,6 +139,45 @@ function updateListCache(listData, updater) {
 	}
 	return result;
 }
+/**
+* Insert an item at the head of a list cache entry — the optimistic-create
+* primitive. Unlike {@link updateListCache} with a prepending updater (which,
+* on an infinite cache, would insert into EVERY page), this targets exactly
+* one location: the first page of an infinite cache, or the single payload of
+* a flat list. Totals adjust via `updateListCache`'s existing delta logic.
+*/
+function prependToListCache(listData, item) {
+	if (!listData) return listData;
+	if (typeof listData === "object" && !Array.isArray(listData) && Array.isArray(listData.pages) && Array.isArray(listData.pageParams)) {
+		const d = listData;
+		if (d.pages.length === 0) return listData;
+		const first = updateListCache(d.pages[0], (items) => [item, ...items || []]);
+		if (first === d.pages[0]) return listData;
+		return {
+			...d,
+			pages: [first, ...d.pages.slice(1)]
+		};
+	}
+	return updateListCache(listData, (items) => [item, ...items || []]);
+}
+/**
+* Replace an item (matched by id) across a list cache entry — the
+* temp-ID-reconciliation primitive. After a create succeeds, the optimistic
+* placeholder (`temp-…` id) is swapped for the server document in place, so
+* the UI keeps the row (no flicker) while the id becomes real. Works on flat
+* and infinite shapes via {@link updateListCache}.
+*/
+function replaceItemInListCache(listData, matchId, replacement, opts = {}) {
+	return updateListCache(listData, (items) => {
+		let changed = false;
+		const next = items.map((item) => {
+			if ((opts.idField ? String(item?.[opts.idField] ?? "") || getItemId(item) : getItemId(item)) !== matchId) return item;
+			changed = true;
+			return replacement;
+		});
+		return changed ? next : items;
+	});
+}
 /** Item-identity helper that respects a custom idField, falling back to `_id` / `id`. */
 function resolveId(item, idField) {
 	if (!item || typeof item !== "object") return null;
@@ -320,4 +371,4 @@ function createCacheUtils(KEYS) {
 }
 
 //#endregion
-export { DEFAULT_QUERY_CONFIG, QUERY_CONFIGS, createCacheUtils, createQueryKeys, extractItem, extractItems, getItemId, normalizePagination, syncDetailToLists, updateListCache, withOrgParams };
+export { DEFAULT_QUERY_CONFIG, QUERY_CONFIGS, createCacheUtils, createQueryKeys, extractItem, extractItems, getItemId, normalizePagination, prependToListCache, replaceItemInListCache, syncDetailToLists, updateListCache, withOrgParams };

package/dist/client.d.ts

@@ -34,7 +34,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.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'`,
@@ -47,6 +47,8 @@ interface ArcApiErrorOptions {
   json: unknown;
   endpoint: string;
   method: HttpMethod;
+  /** Parsed `Retry-After` response header in ms (429/503 pacing), if present. */
+  retryAfterMs?: number | null;
 }
 /**
  * Rich API error with status code, response payload, and request metadata.
@@ -68,6 +70,13 @@ declare class ArcApiError extends Error {
   readonly json: unknown;
   readonly endpoint: string;
   readonly method: HttpMethod;
+  /**
+   * Server-directed retry pacing from the `Retry-After` response header
+   * (seconds or HTTP-date form, normalized to ms). Populated on 429/503;
+   * the SDK's retry loop honors it INSTEAD of computed backoff so clients
+   * come back exactly when the server says capacity returns.
+   */
+  readonly retryAfterMs: number | null;
   constructor(message: string, options: ArcApiErrorOptions);
   /**
    * Canonical error code from arc's wire envelope (`json.code`).
@@ -240,7 +249,7 @@ interface ClientConfig {
    * - 'bearer' (default): Requires a token for authenticated requests. Queries are disabled until a token is provided.
    * - 'cookie': Auth is handled via HTTP-only cookies (e.g. Better Auth). Queries are always enabled — no token needed.
    */
-  authMode?: 'bearer' | 'cookie' | 'header';
+  authMode?: "bearer" | "cookie" | "header";
   /**
    * Fetch credentials policy.
    * - 'include': Always send cookies cross-origin (required for cookie-based auth).
@@ -271,6 +280,17 @@ interface ClientConfig {
    * Per-request override: set `elevated: true | false` on `RequestOptions`.
    */
   elevated?: boolean;
+  /**
+   * Per-attempt request timeout in ms. When set (> 0), every fetch attempt is
+   * aborted after this long and fails with a retryable `TimeoutError` —
+   * WITHOUT it, a hung connection pends forever unless the caller wires an
+   * `AbortSignal` themselves. Composed with the caller's signal (whichever
+   * fires first wins); each retry attempt gets a fresh timeout window.
+   * Default: disabled (0) — deliberate, to avoid killing legitimately slow
+   * report/export endpoints; set it explicitly (10–30s is typical).
+   * Per-request override: `ApiRequestOptions.timeoutMs` (0 disables).
+   */
+  timeoutMs?: number;
   /**
    * Network-failure + 5xx retry policy. Off by default — TanStack Query already
    * retries query reads (3× by default), but the SDK's mutation flow and any
@@ -330,7 +350,7 @@ interface RetryConfig {
    * - `'linear'`: `300 * (n + 1)` ms
    * - `(attempt) => number`: custom delay in ms; receives the 0-indexed retry attempt
    */
-  backoff?: 'exponential' | 'linear' | ((attempt: number) => number);
+  backoff?: "exponential" | "linear" | ((attempt: number) => number);
   /**
    * Whitelist of statuses to retry on, OR a predicate. Defaults to a function
    * that returns true for: any non-`ArcApiError` (network failure / fetch
@@ -338,6 +358,13 @@ interface RetryConfig {
    * AbortError or 4xx.
    */
   retryOn?: number[] | ((error: unknown) => boolean);
+  /**
+   * Backoff jitter. `'full'` randomizes each delay uniformly in
+   * `[0, computed]` (AWS full-jitter) so a fleet of clients recovering from
+   * the same outage doesn't retry in lockstep and re-stampede the backend.
+   * Default `'none'` keeps the historical deterministic delays.
+   */
+  jitter?: "none" | "full";
 }
 /** Context handed to {@link ClientConfig.beforeRequest}. Mutate + return to override. */
 interface BeforeRequestContext {
@@ -384,7 +411,7 @@ declare function configureClient(config: ClientConfig): void;
 /**
  * Get the configured auth mode. Returns 'bearer' if not configured.
  */
-declare function getAuthMode(): 'bearer' | 'cookie' | 'header';
+declare function getAuthMode(): "bearer" | "cookie" | "header";
 /** Get the configured base URL. Returns empty string if not configured. */
 declare function getBaseUrl(): string;
 /** Whether auto-idempotency is enabled on the global client. */
@@ -483,7 +510,7 @@ interface AuthErrorContext {
   setToken: (token: string | null) => void;
 }
 /** {@link AuthConfig.onAuthError} signature. */
-type AuthErrorHandler = (ctx: AuthErrorContext) => Promise<'retry' | 'skip'>;
+type AuthErrorHandler = (ctx: AuthErrorContext) => Promise<"retry" | "skip">;
 /**
  * Configure auth context for automatic token/orgId injection.
  * When configured, hooks auto-inject these values so you don't need to pass them manually.
@@ -521,7 +548,7 @@ declare function _resetAuthWarnings(): void;
  * "retry without a token" (rare but valid for public endpoints).
  */
 interface AuthRecoveryResult {
-  decision: 'retry' | 'skip';
+  decision: "retry" | "skip";
   overrideToken: string | null | undefined;
 }
 /** @internal — exposed for tests; clears the dedup so they don't bleed. */
@@ -545,7 +572,7 @@ declare function _getAuthErrorHandler(): {
  * as the fetch path — concurrent callers (XHR upload + WebSocket reconnect
  * + SSE probe firing at once) collapse to one refresh.
  */
-declare function _runAuthRecovery(handler: AuthErrorHandler, ctx: Omit<AuthErrorContext, 'setToken'>): Promise<AuthRecoveryResult>;
+declare function _runAuthRecovery(handler: AuthErrorHandler, ctx: Omit<AuthErrorContext, "setToken">): Promise<AuthRecoveryResult>;
 /**
  * @internal
  * Resolve the next-attempt token. Mirrors the priority in `executeRequest`'s
@@ -601,10 +628,10 @@ declare function createAuthRefreshHandler(opts: {
    * Behavior when the `refresh()` call itself throws. Default: `'skip'`
    * (the original 401 surfaces; consumers handle "session expired" once).
    */
-  onRefreshError?: 'skip' | 'throw';
+  onRefreshError?: "skip" | "throw";
 }): AuthErrorHandler;
 /** Protocol family the URL should target. `http` keeps `getBaseUrl()` as-is; `ws` rewrites `http(s)://` → `ws(s)://`. */
-type StreamUrlProtocol = 'http' | 'ws';
+type StreamUrlProtocol = "http" | "ws";
 /**
  * Build an auth-aware URL using the global client + auth singletons.
  *
@@ -618,7 +645,7 @@ type StreamUrlProtocol = 'http' | 'ws';
  * @param protocol `'http'` (default) or `'ws'` — controls the protocol rewrite.
  */
 declare function buildStreamUrl(path: string, params?: Record<string, string | number | boolean | null | undefined>, protocol?: StreamUrlProtocol): string;
-type HttpMethod = 'GET' | 'POST' | 'PATCH' | 'PUT' | 'DELETE';
+type HttpMethod = "GET" | "POST" | "PATCH" | "PUT" | "DELETE";
 /** Returned by `handleApiRequest` for PDF, image, and CSV responses. */
 interface BlobResponse {
   data: Blob;
@@ -677,6 +704,8 @@ interface ApiRequestOptions {
   next?: NextFetchOptions;
   cache?: RequestCache;
   signal?: AbortSignal;
+  /** Per-request timeout in ms — overrides `ClientConfig.timeoutMs`. `0` disables for this request. */
+  timeoutMs?: number;
   /** Explicit idempotency key for this request. Sent as `Idempotency-Key` header. */
   idempotencyKey?: string;
   /**
@@ -762,6 +791,47 @@ declare function createClient(config: ArcClientConfig): ArcClient;
  * });
  */
 declare function createAuthAwareClient(overrides?: Partial<ArcClientConfig>): ArcClient;
+/**
+ * Request-scoped server client config — static credentials for exactly one
+ * request, no module singletons.
+ */
+interface ServerClientConfig extends Omit<ArcClientConfig, "getToken" | "getOrgId" | "toast" | "navigation"> {
+  /** Bearer token for this request. `null`/omitted = unauthenticated. */
+  token?: string | null;
+  /** Tenant/org for this request, sent as `x-organization-id`. */
+  organizationId?: string | null;
+}
+/**
+ * Create a **request-scoped** client for server environments (Next.js App
+ * Router route handlers / Server Components, or any SSR runtime).
+ *
+ * Unlike `configureClient`/`configureAuth` — which set module-level state
+ * that leaks across concurrent server requests — this returns an isolated
+ * client whose credentials live only in the returned instance. Construct one
+ * per request, read cookies/headers in YOUR framework code, and pass the
+ * values in. The SDK stays framework-free: no `next` dependency, no
+ * `next/headers` import, no hidden cookie access.
+ *
+ * @example Next.js App Router (Server Component or route handler)
+ * ```ts
+ * import { cookies, headers } from 'next/headers';   // host code, not SDK code
+ * import { createServerClient } from '@classytic/arc-next/client';
+ * import { createCrudApi } from '@classytic/arc-next/api';
+ *
+ * export async function loadOrders() {
+ *   const jar = await cookies();
+ *   const client = createServerClient({
+ *     baseUrl: process.env.API_URL!,
+ *     token: jar.get('session')?.value ?? null,
+ *     organizationId: (await headers()).get('x-organization-id'),
+ *   });
+ *   const orders = createCrudApi<Order>('orders', { client });
+ *   // Next fetch-cache passthrough works per call:
+ *   return orders.getAll({ options: { next: { revalidate: 60, tags: ['orders'] } } });
+ * }
+ * ```
+ */
+declare function createServerClient(config: ServerClientConfig): ArcClient;
 /**
  * Get auth context for a specific client instance, falling back to global.
  */
@@ -809,7 +879,7 @@ declare function createQueryString<T extends Record<string, unknown>>(params?: T
  * });
  */
 declare function arcAuthHeaders(): Record<string, string>;
-interface ArcFetchOptions extends Omit<RequestInit, 'body' | 'headers'> {
+interface ArcFetchOptions extends Omit<RequestInit, "body" | "headers"> {
   /**
    * Request body. Plain objects and arrays are auto-`JSON.stringify`d and
    * sent with `Content-Type: application/json`. Binary bodies (`FormData`,
@@ -903,4 +973,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, StreamUrlProtocol, TextResponse, ToastHandler, UseRouterHook, _getAuthErrorHandler, _isAuthRecoverable, _resetArcFetchClient, _resetAuthRecovery, _resetAuthWarnings, _resolveRefreshedToken, _runAuthRecovery, arc, arcAuthHeaders, arcFetch, buildStreamUrl, configureAuth, configureClient, createAuthAwareClient, createAuthRefreshHandler, createClient, createQueryString, 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, 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 };