@classytic/arc-next 0.11.1 → 0.13.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'`,
@@ -47,6 +46,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 +69,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`).
@@ -185,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
@@ -240,7 +285,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).
@@ -258,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.
@@ -271,6 +323,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 +393,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 +401,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 +454,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 +553,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 +591,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 +615,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 +671,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 +688,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 +747,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 +834,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 +922,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 +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, 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, 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

@@ -1,3 +1,5 @@
+import { ERROR_CODES } from "@classytic/repo-core/errors";
+
 //#region src/client.ts
 /**
 * Canonical error codes arc and repo-core emit on `json.code`. Single
@@ -21,17 +23,7 @@
 * `errorMappers` codes still satisfy it.
 */
 const KNOWN_ARC_ERROR_CODES = [
-	"validation_error",
-	"not_found",
-	"conflict",
-	"unauthorized",
-	"forbidden",
-	"rate_limited",
-	"idempotency_conflict",
-	"precondition_failed",
-	"internal_error",
-	"service_unavailable",
-	"timeout",
+	...Object.values(ERROR_CODES),
 	"arc.bad_request",
 	"arc.unauthorized",
 	"arc.forbidden",
@@ -45,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",
@@ -75,6 +68,13 @@ var ArcApiError = class extends Error {
 	json;
 	endpoint;
 	method;
+	/**
+	* 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.
+	*/
+	retryAfterMs;
 	constructor(message, options) {
 		super(message);
 		this.name = "ArcApiError";
@@ -83,6 +83,7 @@ var ArcApiError = class extends Error {
 		this.json = options.json;
 		this.endpoint = options.endpoint;
 		this.method = options.method;
+		this.retryAfterMs = options.retryAfterMs ?? null;
 	}
 	/**
 	* Canonical error code from arc's wire envelope (`json.code`).
@@ -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
@@ -435,7 +478,7 @@ function isAuthRecoverable(error, retryOn403) {
 function runAuthRecovery(handler, ctx) {
 	if (pendingAuthRecovery) return pendingAuthRecovery;
 	pendingAuthRecovery = (async () => {
-		let overrideToken = void 0;
+		let overrideToken;
 		const setToken = (token) => {
 			overrideToken = token;
 		};
@@ -652,6 +695,44 @@ function createAuthAwareClient(overrides = {}) {
 	};
 }
 /**
+* 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'] } } });
+* }
+* ```
+*/
+function createServerClient(config) {
+	const { token = null, organizationId = null, ...rest } = config;
+	return createClient({
+		...rest,
+		getToken: () => token,
+		getOrgId: () => organizationId
+	});
+}
+/**
 * Get auth context for a specific client instance, falling back to global.
 */
 function getClientAuthContext(client) {
@@ -668,11 +749,11 @@ function defaultShouldRetry(error) {
 	return error instanceof Error;
 }
 /** Compute the delay in ms before the Nth retry. */
-function computeBackoff(retry, attempt) {
+function computeBackoff(retry, attempt, error) {
+	if (isArcApiError(error) && error.retryAfterMs != null && (error.status === 429 || error.status === 503)) return error.retryAfterMs;
 	const strategy = retry.backoff ?? "exponential";
-	if (typeof strategy === "function") return Math.max(0, strategy(attempt));
-	if (strategy === "linear") return 300 * (attempt + 1);
-	return Math.min(300 * Math.pow(2, attempt), 1e4);
+	const base = typeof strategy === "function" ? Math.max(0, strategy(attempt)) : strategy === "linear" ? 300 * (attempt + 1) : Math.min(300 * 2 ** attempt, 1e4);
+	return retry.jitter === "full" ? Math.random() * base : base;
 }
 /**
 * Inner request loop — handles 5xx + network-failure backoff per
@@ -695,7 +776,7 @@ async function executeWithBackoff(config, method, endpoint, options = {}) {
 	} catch (error) {
 		lastError = error;
 		if (attempt === totalAttempts - 1 || !shouldRetry(error)) throw error;
-		const delay = computeBackoff(config.retry ?? {}, attempt);
+		const delay = computeBackoff(config.retry ?? {}, attempt, error);
 		if (delay > 0) await sleepAbortable(delay, options.signal);
 	}
 	throw lastError;
@@ -714,6 +795,14 @@ async function executeWithBackoff(config, method, endpoint, options = {}) {
 * surfaces immediately, no extra round-trip).
 */
 async function executeRequest(config, method, endpoint, options = {}) {
+	if (config.autoIdempotency && options.idempotencyKey === void 0 && (method === "POST" || method === "PUT" || method === "PATCH")) 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;
@@ -741,6 +830,15 @@ async function executeRequest(config, method, endpoint, options = {}) {
 	}
 	throw new Error("arc-next: auth retry loop terminated without resolution");
 }
+/** Parse `Retry-After` (delta-seconds or HTTP-date) to ms; null when absent/invalid. */
+function parseRetryAfterMs(header) {
+	if (!header) return null;
+	const seconds = Number(header);
+	if (Number.isFinite(seconds) && seconds >= 0) return Math.round(seconds * 1e3);
+	const date = Date.parse(header);
+	if (!Number.isNaN(date)) return Math.max(0, date - Date.now());
+	return null;
+}
 /** Sleep that resolves early if the signal aborts. */
 function sleepAbortable(ms, signal) {
 	return new Promise((resolve, reject) => {
@@ -759,9 +857,42 @@ function sleepAbortable(ms, signal) {
 		signal?.addEventListener("abort", onAbort, { once: true });
 	});
 }
+/**
+* Compose the caller's AbortSignal with a per-attempt timeout. Returns the
+* effective signal plus a `timedOut()` probe so the catch path can tell a
+* timeout abort (retryable failure) apart from a deliberate caller abort
+* (silent cancellation).
+*/
+function withTimeoutSignal(signal, timeoutMs) {
+	if (!(timeoutMs > 0)) return {
+		signal,
+		timedOut: () => false,
+		cleanup: () => {}
+	};
+	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 });
+	const timer = setTimeout(() => {
+		timedOut = true;
+		controller.abort();
+	}, timeoutMs);
+	return {
+		signal: controller.signal,
+		timedOut: () => timedOut,
+		cleanup: () => {
+			clearTimeout(timer);
+			signal?.removeEventListener("abort", onCallerAbort);
+		}
+	};
+}
 /** A single fetch attempt — used by executeRequest's retry loop. */
 async function executeAttempt(config, method, endpoint, options, attempt) {
-	const { body, token, organizationId, revalidate, headerOptions, tags, next, cache, signal, idempotencyKey, elevated } = options;
+	const { body, token, organizationId, revalidate, headerOptions, tags, next, cache, signal: callerSignal, idempotencyKey, elevated } = options;
+	const timeoutMs = options.timeoutMs ?? config.timeoutMs ?? 0;
+	const timeout = withTimeoutSignal(callerSignal, timeoutMs);
+	const signal = timeout.signal;
 	const startTime = Date.now();
 	try {
 		let headers = {
@@ -773,7 +904,7 @@ async function executeAttempt(config, method, endpoint, options, attempt) {
 			if (config.authMode === "header") {
 				const headerName = authConfig?.headerName ?? "x-api-key";
 				headers[headerName] = token;
-			} else if (config.authMode !== "cookie") headers["Authorization"] = `Bearer ${token}`;
+			} else if (config.authMode !== "cookie") headers.Authorization = `Bearer ${token}`;
 		}
 		if (config.apiVersion) headers["Accept-Version"] = config.apiVersion;
 		if (idempotencyKey) headers["Idempotency-Key"] = idempotencyKey;
@@ -784,7 +915,7 @@ async function executeAttempt(config, method, endpoint, options, attempt) {
 			...headerOptions
 		};
 		const credentials = config.credentials ?? (config.authMode === "cookie" ? "include" : "same-origin");
-		let serializedBody = void 0;
+		let serializedBody;
 		if (body !== void 0 && body !== null) serializedBody = isNonJsonBody(body) ? body : JSON.stringify(body);
 		const encryption = config.encryption;
 		if (encryption?.encryptRequests && encryption.encrypt && typeof serializedBody === "string") {
@@ -815,7 +946,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;
@@ -838,7 +969,8 @@ async function executeAttempt(config, method, endpoint, options, attempt) {
 				statusText: response.statusText,
 				json,
 				endpoint,
-				method
+				method,
+				retryAfterMs: parseRetryAfterMs(response.headers.get("Retry-After"))
 			});
 		}
 		const contentType = response.headers.get("Content-Type");
@@ -886,8 +1018,11 @@ async function executeAttempt(config, method, endpoint, options, attempt) {
 		})).body;
 		return data;
 	} catch (error) {
+		if (timeout.timedOut() && isAbortError(error)) throw Object.assign(/* @__PURE__ */ new Error(`[arc-next] Request timed out after ${timeoutMs}ms: ${method} ${endpoint}`), { name: "TimeoutError" });
 		if (error instanceof Error) throw error;
 		throw new Error("An error occurred while fetching data.");
+	} finally {
+		timeout.cleanup();
 	}
 }
 /**
@@ -1017,7 +1152,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"
@@ -1139,4 +1274,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, 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;
@@ -31,6 +30,6 @@ interface JoseEncryptionOptions {
  * using `jose`. Spread the result into `encryption` and add `encryptRequests`
  * / content-type overrides as needed.
  */
-declare function createJoseEncryption(options: JoseEncryptionOptions): Pick<ClientEncryptionConfig, 'encrypt' | 'decrypt'>;
+declare function createJoseEncryption(options: JoseEncryptionOptions): Pick<ClientEncryptionConfig, "encrypt" | "decrypt">;
 //#endregion
 export { JoseEncryptionOptions, createJoseEncryption };