@classytic/arc-next 0.5.0 → 0.7.0

package/dist/client.js

@@ -1,49 +1,59 @@
 //#region src/client.ts
 /**
-* Top-level error codes arc's `errorHandlerPlugin` emits on the response root
-* (`json.code`). Mirrors `statusCodeToCode()` + the special `VALIDATION_ERROR`
-* / `DUPLICATE_KEY` / `INTERNAL_ERROR` branches.
-*
-* Open via intersection with `(string & {})` so unknown codes from custom
-* `errorMappers` / `errorMap` still satisfy the type.
-*/
-/**
-* Top-level HTTP-status error codes arc's `errorHandlerPlugin` emits on
-* `json.code`. Exported as a `const` array first so callers get both
-* compile-time exhaustiveness AND runtime iteration (e.g. building a
-* client-side i18n lookup, or whitelisting which codes get retried).
-*/
-const KNOWN_TOP_LEVEL_CODES = [
-	"BAD_REQUEST",
-	"UNAUTHORIZED",
-	"FORBIDDEN",
-	"NOT_FOUND",
-	"METHOD_NOT_ALLOWED",
-	"CONFLICT",
-	"UNPROCESSABLE_ENTITY",
-	"RATE_LIMITED",
-	"INTERNAL_ERROR",
-	"BAD_GATEWAY",
-	"SERVICE_UNAVAILABLE",
-	"GATEWAY_TIMEOUT",
-	"VALIDATION_ERROR",
-	"DUPLICATE_KEY",
-	"DOMAIN_ERROR"
-];
-/**
-* Nested business-logic codes arc's mixins / preset routes / org guards emit
-* on `json.details.code`. These are distinct from the HTTP-status code above —
-* `error.code` (top-level) vs `error.detailsCode` (nested). When a route
-* returns 403 with `details.code: 'ORG_CONTEXT_REQUIRED'`, hosts read
-* `detailsCode` to disambiguate "missing org context" from "permission denied".
+* Canonical error codes arc and repo-core emit on `json.code`. Single
+* top-level slot — arc 2.13's `createError` lifts business codes from
+* `details` to top-level so `repo-core`'s `toErrorContract` round-trips
+* them on the wire. There is no separate `detailsCode` slot; everything
+* lives at `error.code`.
+*
+* Three families compose this list:
+*  1. **repo-core canonical** (`validation_error`, `not_found`, ...) — RFC 7807
+*     / Stripe-shaped lowercase + snake_case. Cross-package universals.
+*  2. **arc hierarchical** (`arc.forbidden`, `arc.validation_error`,
+*     `arc.org.access_denied`, ...) — what arc's `errorHandlerPlugin`
+*     emits for HTTP-status throws + arc-classified errors.
+*  3. **arc business** (`ORG_CONTEXT_REQUIRED`, `ALL_FIELDS_STRIPPED`,
+*     `OWNERSHIP_DENIED`, ...) — emitted by mixins / org guards via
+*     `createError(status, msg, { code })`. The UPPER_SNAKE form is
+*     intentional: these are reason codes, not HTTP-status codes.
+*
+* `(string & {})` keeps the type open so domain packages and custom
+* `errorMappers` codes still satisfy it.
 */
-const KNOWN_DETAILS_CODES = [
+const KNOWN_ARC_ERROR_CODES = [
+	"validation_error",
+	"not_found",
+	"conflict",
+	"unauthorized",
+	"forbidden",
+	"rate_limited",
+	"idempotency_conflict",
+	"precondition_failed",
+	"internal_error",
+	"service_unavailable",
+	"timeout",
+	"arc.bad_request",
+	"arc.unauthorized",
+	"arc.forbidden",
+	"arc.not_found",
+	"arc.conflict",
+	"arc.unprocessable_entity",
+	"arc.rate_limited",
+	"arc.internal_error",
+	"arc.bad_gateway",
+	"arc.service_unavailable",
+	"arc.gateway_timeout",
+	"arc.validation_error",
+	"arc.invalid_id",
+	"arc.org.selection_required",
+	"arc.org.access_denied",
 	"ORG_CONTEXT_REQUIRED",
 	"ORG_ROLE_REQUIRED",
 	"OWNERSHIP_DENIED",
 	"MIXED_UPDATE_SHAPE",
 	"ALL_FIELDS_STRIPPED",
-	"BEFORE_RESTORE_HOOK_ERROR"
+	"BEFORE_RESTORE_HOOK_ERROR",
+	"duplicate_key"
 ];
 /**
 * Rich API error with status code, response payload, and request metadata.
@@ -75,51 +85,59 @@ var ArcApiError = class extends Error {
 		this.method = options.method;
 	}
 	/**
-	* Top-level error code from arc's response envelope (`json.code`).
+	* Canonical error code from arc's wire envelope (`json.code`).
 	*
-	* One of {@link ArcTopLevelErrorCode} — covers HTTP-status codes (`FORBIDDEN`,
-	* `CONFLICT`...) plus the dedicated `VALIDATION_ERROR` / `DUPLICATE_KEY`
-	* branches arc emits. Returns `null` if the response carries no envelope.
+	* Arc 2.13 + `repo-core` 0.4 emit one canonical {@link ErrorContract}
+	* shape — `{ code, message, status, details? }` — with the business
+	* code at top-level. Hosts switch on `error.code` directly:
 	*
 	* @example
-	* if (error.code === 'DUPLICATE_KEY') showRetryAsAdmin();
+	* if (error.code === 'ORG_CONTEXT_REQUIRED') promptOrgSelector();
+	* if (error.code === 'arc.not_found') router.replace('/404');
+	* if (error.code === 'duplicate_key') showRetryAsAdmin();
 	*/
 	get code() {
 		const j = this.json;
 		return j && typeof j.code === "string" ? j.code : null;
 	}
 	/**
-	* Nested business-logic code from arc's `json.details.code` slot.
-	*
-	* Arc's preset mixins (bulk, softDelete) and org guards emit specific reason
-	* codes here — distinct from the HTTP-status `code` above. The most common
-	* is `ORG_CONTEXT_REQUIRED` (bulk operations + orgGuard reject when the
-	* caller's `request.scope.organizationId` is missing).
-	*
-	* @example
-	* if (error.detailsCode === 'ORG_CONTEXT_REQUIRED') {
-	*   alert('Configure auth before bulk operations: configureAuth({ getOrgId })');
-	* }
+	* Canonical structured details — populated for validation failures
+	* (one entry per offending field) and duplicate-key conflicts (one entry
+	* per offending field). Shape matches `repo-core`'s {@link ErrorDetail}:
+	* `{ path?, code, message, meta? }`. Returns `null` for non-arc backends
+	* or responses without details.
 	*/
-	get detailsCode() {
-		const c = this.json?.details?.code;
-		return typeof c === "string" ? c : null;
+	get details() {
+		const j = this.json;
+		return Array.isArray(j?.details) ? j.details : null;
 	}
 	/**
 	* Extract field-level validation errors as `{ field: message }` map.
 	*
-	* Reads three response shapes used by Arc:
-	* 1. `{ errors: { email: 'invalid' } }` — record form (legacy / app-level handlers).
-	* 2. `{ details: { errors: [{ field, message }] } }` — Fastify AJV + Arc errorHandler emit this.
-	* 3. `{ details: { errors: [{ instancePath, message, params }] } }` — raw AJV passthrough.
-	*
-	* Returns null when none of the shapes match.
+	* Reads the canonical `ErrorContract.details: ErrorDetail[]` shape first
+	* (what arc 2.13 + repo-core emit), then falls back to legacy shapes for
+	* non-arc backends:
+	*  1. `details: [{ path, code, message }]` — canonical (arc / repo-core).
+	*  2. `errors: { email: 'invalid' }` — record form (legacy app handlers).
+	*  3. `details: { errors: [{ field|instancePath, message }] }` — pre-2.13 AJV.
+	*  4. `errors: [...]` at the top level — third-party frameworks.
 	*/
 	get fieldErrors() {
 		const j = this.json;
 		if (!j) return null;
+		if (Array.isArray(j.details) && j.details.length > 0) {
+			const map = {};
+			for (const d of j.details) {
+				if (!d || typeof d !== "object") continue;
+				const key = typeof d.path === "string" ? d.path : "";
+				const msg = typeof d.message === "string" ? d.message : "Invalid value";
+				if (key && !(key in map)) map[key] = msg;
+			}
+			if (Object.keys(map).length > 0) return map;
+		}
 		if (j.errors && !Array.isArray(j.errors) && typeof j.errors === "object") return j.errors;
-		const errorList = Array.isArray(j.errors) ? j.errors : Array.isArray(j.details?.errors) ? j.details.errors : null;
+		const detailsObj = j.details;
+		const errorList = Array.isArray(j.errors) ? j.errors : Array.isArray(detailsObj?.errors) ? detailsObj.errors : null;
 		if (!errorList) return null;
 		const map = {};
 		for (const item of errorList) {
@@ -169,26 +187,26 @@ function isAbortError(error) {
 	return false;
 }
 /**
-* Generic check: is this an `ArcApiError` carrying a specific top-level OR
-* nested `details.code`? Matches whichever slot the code lives in — saves
-* call sites from having to know whether arc emitted it at the root or under
-* `details`.
+* Generic check: is this an `ArcApiError` carrying a specific `code`?
+* Single-slot — arc 2.13 + repo-core 0.4 emit one canonical `code` at
+* top-level. Pass either the canonical lowercase form (`'arc.not_found'`,
+* `'validation_error'`) or arc's UPPER_SNAKE business form
+* (`'ORG_CONTEXT_REQUIRED'`).
 *
 * @example
-* if (isArcErrorCode(error, 'DUPLICATE_KEY')) showRetryUI();
+* if (isArcErrorCode(error, 'duplicate_key')) showRetryUI();
 * if (isArcErrorCode(error, 'ORG_CONTEXT_REQUIRED')) promptOrgSelector();
 */
 function isArcErrorCode(error, code) {
-	if (!isArcApiError(error)) return false;
-	return error.code === code || error.detailsCode === code;
+	return isArcApiError(error) && error.code === code;
 }
 /**
 * Specific predicate for arc's bulk-preset + orgGuard safety code.
 *
 * Arc's bulk endpoints (`POST/PATCH/DELETE /:resource/bulk`) reject any call
 * where `request.scope.organizationId` is missing — the wire signal is
-* `403 { details: { code: 'ORG_CONTEXT_REQUIRED' } }`. Hosts hitting this
-* need to call `configureAuth({ getOrgId })` before retrying.
+* `403 { code: 'ORG_CONTEXT_REQUIRED', message, status: 403 }`. Hosts hitting
+* this need to call `configureAuth({ getOrgId })` before retrying.
 *
 * @example
 * try { await api.bulkCreate({ data: [...] }); }
@@ -202,20 +220,27 @@ function isOrgContextRequiredError(error) {
 	return isArcErrorCode(error, "ORG_CONTEXT_REQUIRED");
 }
 /**
-* Specific predicate for arc's `VALIDATION_ERROR` (Fastify AJV + Mongoose
+* Specific predicate for validation failures (Fastify AJV + Mongoose
 * ValidationError). When true, `error.fieldErrors` is populated with the
-* `{ field: message }` map.
+* `{ field: message }` map. Matches arc's `arc.validation_error` and the
+* canonical `validation_error` from repo-core.
 */
 function isValidationError(error) {
-	return isArcErrorCode(error, "VALIDATION_ERROR");
+	if (!isArcApiError(error)) return false;
+	return error.code === "arc.validation_error" || error.code === "validation_error";
 }
 /**
-* Specific predicate for arc's `DUPLICATE_KEY` (unique-constraint violation).
-* Arc's errorHandler classifies these uniformly across MongoDB E11000,
-* Postgres 23505, and Prisma P2002.
+* Specific predicate for unique-constraint violations. Arc's errorHandler
+* classifies these uniformly across MongoDB E11000, Postgres 23505,
+* Prisma P2002 → `arc.conflict` (with `details[].code === 'duplicate_key'`).
 */
 function isDuplicateKeyError(error) {
-	return isArcErrorCode(error, "DUPLICATE_KEY");
+	if (!isArcApiError(error)) return false;
+	if (error.code === "arc.conflict" || error.code === "duplicate_key" || error.code === "conflict") {
+		if (error.code === "arc.conflict") return error.details?.some((d) => d.code === "duplicate_key") ?? false;
+		return true;
+	}
+	return false;
 }
 let clientConfig = null;
 /**
@@ -250,6 +275,23 @@ function getBaseUrl() {
 function isAutoIdempotency() {
 	return clientConfig?.autoIdempotency ?? false;
 }
+/**
+* Whether the globally-configured client carries enough auth to satisfy a
+* protected endpoint without a per-request token. True when any of
+* `internalApiKey`, `defaultHeaders`, or `authMode: 'cookie'` is configured.
+*
+* Read by `createCrudHooks` to decide whether queries should be enabled when
+* `getToken()` returns null — without this, an app that authenticates via a
+* global `internalApiKey` or static headers would see every query stuck in
+* a permanently-disabled state, looking like a clean empty success.
+*/
+function hasGlobalStaticAuth() {
+	if (!clientConfig) return false;
+	if (clientConfig.authMode === "cookie") return true;
+	if (clientConfig.internalApiKey) return true;
+	if (clientConfig.defaultHeaders && Object.keys(clientConfig.defaultHeaders).length > 0) return true;
+	return false;
+}
 let authConfig = null;
 let hasWarnedAsyncToken = false;
 /**
@@ -283,7 +325,7 @@ function readToken(getToken) {
 	if (result && typeof result.then === "function") {
 		if (!hasWarnedAsyncToken) {
 			hasWarnedAsyncToken = true;
-			console.warn("[arc-next] configureAuth({ getToken }) returned a Promise. Tokens MUST resolve synchronously — async returns are dropped and requests will be unauthenticated. Cache your token (localStorage, memory, signal) and have getToken() return the cached value.");
+			console.error(/* @__PURE__ */ new Error("[arc-next] configureAuth({ getToken }) returned a Promise. Tokens MUST resolve synchronously — async returns are dropped and every authenticated query will be silently disabled (no GET fires, isLoading:false, item:null). Fix: cache the token outside getToken (localStorage, memory, signal, useState) and have getToken() return the cached value. See README → 'Authentication'."));
 		}
 		return null;
 	}
@@ -303,6 +345,138 @@ function _resetAuthWarnings() {
 	hasWarnedAsyncToken = false;
 }
 /**
+* Shared in-flight refresh. Multiple concurrent 401s collapse onto one
+* `onAuthError` invocation — the dedup happens here. Cleared in `.finally`
+* so the NEXT 401 (after settlement) triggers a fresh recovery cycle.
+*/
+let pendingAuthRecovery = null;
+/** @internal — exposed for tests; clears the dedup so they don't bleed. */
+function _resetAuthRecovery() {
+	pendingAuthRecovery = null;
+}
+/**
+* @internal
+* Cross-transport access to the configured auth-recovery handler.
+* Upload (XHR) and WebSocket / SSE plumbing share the same dedup as the
+* fetch path — they read the handler here and call {@link _runAuthRecovery}
+* when they detect a transport-specific auth failure (XHR 401, WS close
+* code 1008/4401, SSE pre-flight probe 401).
+*/
+function _getAuthErrorHandler() {
+	return {
+		handler: authConfig?.onAuthError,
+		retryOn403: authConfig?.retryOn403 ?? false,
+		maxAuthRetries: Math.max(0, authConfig?.maxAuthRetries ?? 1)
+	};
+}
+/**
+* @internal
+* Drive the shared recovery cycle from a non-fetch transport. Same dedup
+* as the fetch path — concurrent callers (XHR upload + WebSocket reconnect
+* + SSE probe firing at once) collapse to one refresh.
+*/
+function _runAuthRecovery(handler, ctx) {
+	return runAuthRecovery(handler, ctx);
+}
+/**
+* @internal
+* Resolve the next-attempt token. Mirrors the priority in `executeRequest`'s
+* auth loop — `setToken` override beats re-reading `getToken()`. Exported so
+* transports outside the fetch path apply the same precedence.
+*/
+function _resolveRefreshedToken(overrideToken) {
+	if (overrideToken !== void 0) return overrideToken;
+	return readToken(authConfig?.getToken);
+}
+/**
+* @internal
+* True for any error a transport should run through `onAuthError`. Matches
+* the fetch path's predicate so XHR / WS / SSE failures classify the same
+* way (401, or 403 when `retryOn403`).
+*/
+function _isAuthRecoverable(error, retryOn403) {
+	return isAuthRecoverable(error, retryOn403);
+}
+/** True for status codes that should trigger {@link AuthConfig.onAuthError}. */
+function isAuthRecoverable(error, retryOn403) {
+	if (!isArcApiError(error)) return false;
+	if (error.status === 401) return true;
+	if (retryOn403 && error.status === 403) return true;
+	return false;
+}
+/**
+* Run the recovery handler with concurrent-request dedup. Every concurrent
+* 401 awaits the same promise and gets the same decision + override token.
+* Cleared on settlement so a later (post-settlement) 401 starts a new cycle.
+*/
+function runAuthRecovery(handler, ctx) {
+	if (pendingAuthRecovery) return pendingAuthRecovery;
+	pendingAuthRecovery = (async () => {
+		let overrideToken = void 0;
+		const setToken = (token) => {
+			overrideToken = token;
+		};
+		return {
+			decision: await handler({
+				...ctx,
+				setToken
+			}),
+			overrideToken
+		};
+	})().finally(() => {
+		pendingAuthRecovery = null;
+	});
+	return pendingAuthRecovery;
+}
+/**
+* Build an {@link AuthErrorHandler} from any `refresh()` function that
+* returns the new token (or `null` if the session is truly expired).
+*
+* Catches refresh errors and surfaces them as `'skip'` by default so the
+* original 401 reaches the consumer instead of a misleading "refresh failed"
+* trace — consumers expect to handle "session expired" once, not twice. Pass
+* `onRefreshError: 'throw'` to opt in to propagation.
+*
+* @example Better Auth (or any session-based lib)
+* ```ts
+* import { configureAuth, createAuthRefreshHandler } from '@classytic/arc-next/client';
+* import { authClient } from '@/lib/auth-client';
+*
+* configureAuth({
+*   getToken: () => authClient.getSession().data?.session.token ?? null,
+*   onAuthError: createAuthRefreshHandler({
+*     refresh: async () => {
+*       const { data } = await authClient.getSession({ disableCookieCache: true });
+*       return data?.session.token ?? null;
+*     },
+*   }),
+* });
+* ```
+*
+* @example Custom OAuth refresh
+* ```ts
+* configureAuth({
+*   getToken: () => tokenStore.getAccessToken(),
+*   onAuthError: createAuthRefreshHandler({
+*     refresh: () => oauthClient.refresh(tokenStore.getRefreshToken()),
+*   }),
+* });
+* ```
+*/
+function createAuthRefreshHandler(opts) {
+	return async ({ setToken }) => {
+		try {
+			const token = await opts.refresh();
+			if (token == null) return "skip";
+			setToken(token);
+			return "retry";
+		} catch (err) {
+			if (opts.onRefreshError === "throw") throw err;
+			return "skip";
+		}
+	};
+}
+/**
 * Build an auth-aware URL using the global client + auth singletons.
 *
 * Single source of truth for {@link import('./sse.js').buildSseUrl} (HTTP) and
@@ -445,7 +619,14 @@ function computeBackoff(retry, attempt) {
 	if (strategy === "linear") return 300 * (attempt + 1);
 	return Math.min(300 * Math.pow(2, attempt), 1e4);
 }
-async function executeRequest(config, method, endpoint, options = {}) {
+/**
+* Inner request loop — handles 5xx + network-failure backoff per
+* {@link ClientConfig.retry}. Knows nothing about 401 recovery; that's the
+* outer {@link executeRequest} wrapper. Split so the two retry families don't
+* tangle: the backoff loop has its own attempt counter and predicate, the
+* auth loop has its own cap and dedup.
+*/
+async function executeWithBackoff(config, method, endpoint, options = {}) {
 	const totalAttempts = Math.max(1, config.retry?.attempts ?? 1);
 	const shouldRetry = (() => {
 		const r = config.retry?.retryOn;
@@ -464,6 +645,47 @@ async function executeRequest(config, method, endpoint, options = {}) {
 	}
 	throw lastError;
 }
+/**
+* Top-level request entry. Wraps the 5xx-backoff loop with the 401-recovery
+* loop so the two retry families compose cleanly:
+*
+*   401 (auth) ─→ onAuthError ─→ retry with fresh token ─→ may 5xx ─→ backoff
+*
+* `maxAuthRetries` (default 1) caps the auth loop independently of the
+* backoff loop's `attempts`. AbortSignal propagates through both loops.
+*
+* The auth loop only fires when {@link AuthConfig.onAuthError} is configured —
+* apps that haven't wired a refresh handler see the original behavior (401
+* surfaces immediately, no extra round-trip).
+*/
+async function executeRequest(config, method, endpoint, options = {}) {
+	const handler = authConfig?.onAuthError;
+	if (!handler) return executeWithBackoff(config, method, endpoint, options);
+	const retryOn403 = authConfig?.retryOn403 ?? false;
+	const maxAuthRetries = Math.max(0, authConfig?.maxAuthRetries ?? 1);
+	let currentOptions = options;
+	for (let authAttempt = 0; authAttempt <= maxAuthRetries; authAttempt++) try {
+		return await executeWithBackoff(config, method, endpoint, currentOptions);
+	} catch (error) {
+		if (authAttempt >= maxAuthRetries || !isAuthRecoverable(error, retryOn403)) throw error;
+		if (currentOptions.signal?.aborted) throw error;
+		const { decision, overrideToken } = await runAuthRecovery(handler, {
+			error,
+			request: {
+				method,
+				endpoint
+			},
+			attempt: authAttempt + 1
+		});
+		if (decision !== "retry") throw error;
+		const nextToken = overrideToken !== void 0 ? overrideToken : readToken(authConfig?.getToken);
+		currentOptions = {
+			...currentOptions,
+			token: nextToken
+		};
+	}
+	throw new Error("arc-next: auth retry loop terminated without resolution");
+}
 /** Sleep that resolves early if the signal aborts. */
 function sleepAbortable(ms, signal) {
 	return new Promise((resolve, reject) => {
@@ -492,21 +714,23 @@ async function executeAttempt(config, method, endpoint, options, attempt) {
 			...config.defaultHeaders ?? {}
 		};
 		if (config.internalApiKey) headers["x-internal-api-key"] = config.internalApiKey;
-		if (token) if (config.authMode === "header") {
-			const headerName = authConfig?.headerName ?? "x-api-key";
-			headers[headerName] = token;
-		} else headers["Authorization"] = `Bearer ${token}`;
+		if (token) {
+			if (config.authMode === "header") {
+				const headerName = authConfig?.headerName ?? "x-api-key";
+				headers[headerName] = token;
+			} else if (config.authMode !== "cookie") headers["Authorization"] = `Bearer ${token}`;
+		}
 		if (config.apiVersion) headers["Accept-Version"] = config.apiVersion;
 		if (idempotencyKey) headers["Idempotency-Key"] = idempotencyKey;
 		if (elevated ?? config.elevated ?? false) headers["x-arc-scope"] = "platform";
-		if (body !== void 0 && body !== null && !(body instanceof FormData)) headers["Content-Type"] = "application/json";
+		if (body !== void 0 && body !== null && !isNonJsonBody(body)) headers["Content-Type"] = "application/json";
 		if (headerOptions) headers = {
 			...headers,
 			...headerOptions
 		};
 		const credentials = config.credentials ?? (config.authMode === "cookie" ? "include" : "same-origin");
 		let serializedBody = void 0;
-		if (body !== void 0 && body !== null) serializedBody = body instanceof FormData ? body : JSON.stringify(body);
+		if (body !== void 0 && body !== null) serializedBody = isNonJsonBody(body) ? body : JSON.stringify(body);
 		if (config.beforeRequest) {
 			const ctx = await config.beforeRequest({
 				method,
@@ -609,8 +833,8 @@ async function executeAttempt(config, method, endpoint, options, attempt) {
 * Handles JSON, binary (PDF, images), CSV, and text responses.
 *
 * @example
-* const { success, data } = await handleApiRequest<ApiResponse<User>>('GET', '/users/me');
-* const response = await handleApiRequest<PaginatedResponse<Product>>('GET', '/products?page=1');
+* const user = await handleApiRequest<User>('GET', '/users/me');
+* const response = await handleApiRequest<PaginatedResult<Product>>('GET', '/products?page=1');
 */
 async function handleApiRequest(method, endpoint, options = {}) {
 	if (!clientConfig) throw new Error("arc-next: Client not configured. Call configureClient({ baseUrl }) before making API requests.");
@@ -655,10 +879,195 @@ function createQueryString(params = {}) {
 			if (value.length > 1) searchParams.append(`${key}[in]`, value.join(","));
 			else if (value.length === 1) searchParams.append(key, String(value[0]));
 		} else if (value === null) searchParams.append(key, "null");
+		else if (typeof value === "object") for (const [op, opValue] of Object.entries(value)) {
+			if (opValue === void 0 || opValue === "") continue;
+			const bracketKey = `${key}[${op}]`;
+			if (Array.isArray(opValue)) {
+				if (opValue.length > 0) searchParams.append(bracketKey, opValue.join(","));
+			} else if (opValue === null) searchParams.append(bracketKey, "null");
+			else searchParams.append(bracketKey, String(opValue));
+		}
 		else searchParams.append(key, String(value));
 	});
 	return searchParams.toString();
 }
+/**
+* Body shapes that carry their own Content-Type and must NOT be re-serialized
+* by arc-next:
+*
+*  - `FormData` — multipart with a runtime-computed boundary.
+*  - `Blob` / `File` — carries `.type`.
+*  - `URLSearchParams` — `application/x-www-form-urlencoded`.
+*  - `ArrayBuffer` / typed arrays — raw bytes; caller controls Content-Type.
+*  - `ReadableStream` — caller controls Content-Type.
+*  - `string` — caller controls Content-Type (could be plain text, XML, etc.).
+*
+* Plain objects and arrays fall through and get `JSON.stringify`d with
+* `Content-Type: application/json`.
+*/
+function isNonJsonBody(body) {
+	if (body == null) return false;
+	if (typeof body === "string") return true;
+	if (typeof FormData !== "undefined" && body instanceof FormData) return true;
+	if (typeof Blob !== "undefined" && body instanceof Blob) return true;
+	if (typeof URLSearchParams !== "undefined" && body instanceof URLSearchParams) return true;
+	if (typeof ArrayBuffer !== "undefined" && body instanceof ArrayBuffer) return true;
+	if (typeof ArrayBuffer !== "undefined" && ArrayBuffer.isView(body)) return true;
+	if (typeof ReadableStream !== "undefined" && body instanceof ReadableStream) return true;
+	return false;
+}
+/**
+* Returns the auth headers arc-next would inject on a fetch right now —
+* `Authorization` (or the configured custom `headerName` for `authMode:
+* 'header'`), `x-organization-id`, and `x-internal-api-key`. Use for the
+* rare case where you need full `Response` control via plain `fetch` but
+* still want arc-next's auth wiring.
+*
+* @example
+* const res = await fetch(url, {
+*   headers: { ...arcAuthHeaders(), 'X-Custom': '1' },
+*   credentials: getAuthMode() === 'cookie' ? 'include' : 'same-origin',
+* });
+*/
+function arcAuthHeaders() {
+	const { token, organizationId } = getAuthContext();
+	const authMode = getAuthMode();
+	const headers = {};
+	if (token) {
+		if (authMode === "header") headers[authConfig?.headerName ?? "x-api-key"] = token;
+		else if (authMode !== "cookie") headers.Authorization = `Bearer ${token}`;
+	}
+	if (organizationId) headers["x-organization-id"] = organizationId;
+	if (clientConfig?.internalApiKey) headers["x-internal-api-key"] = clientConfig.internalApiKey;
+	return headers;
+}
+/**
+* Headers that arc-next owns and a caller must not override via
+* {@link ArcFetchOptions.headers}. Passing one of these in `options.headers`
+* is silently dropped — see the `arcFetch` JSDoc for the rationale.
+*
+* Lower-cased on lookup so case-insensitive HTTP header semantics are
+* honored (`Authorization` vs `authorization` both protected).
+*/
+const ARC_FETCH_PROTECTED_HEADERS = new Set([
+	"authorization",
+	"x-organization-id",
+	"x-internal-api-key"
+]);
+let defaultArcFetchClient = null;
+function getDefaultArcFetchClient() {
+	if (!defaultArcFetchClient) defaultArcFetchClient = createAuthAwareClient();
+	return defaultArcFetchClient;
+}
+/** @internal — tests reset the default client between cases. */
+function _resetArcFetchClient() {
+	defaultArcFetchClient = null;
+}
+/**
+* Strip protected auth headers from a caller-supplied map. Case-insensitive
+* (HTTP header names are case-insensitive). The custom-auth `headerName`
+* (when `authMode: 'header'` is configured) is computed at call time so
+* apps that reconfigure auth modes don't lose protection on the renamed
+* header.
+*/
+function sanitizeUserHeaders(headers) {
+	if (!headers) return {};
+	const customHeader = authConfig?.headerName?.toLowerCase();
+	const out = {};
+	for (const [name, value] of Object.entries(headers)) {
+		const lower = name.toLowerCase();
+		if (ARC_FETCH_PROTECTED_HEADERS.has(lower)) continue;
+		if (customHeader && lower === customHeader) continue;
+		out[name] = value;
+	}
+	return out;
+}
+/**
+* Authenticated, tenant-scoped fetch to an arc endpoint — one line for the
+* non-hook contexts where `useQuery` / `useMutation` aren't available
+* (event handlers, service workers, server actions, custom MDX submits,
+* background polls).
+*
+* Auto-injects on every call:
+*  - `Authorization: Bearer <token>` (from `configureAuth().getToken`), or
+*    the custom header for `authMode: 'header'`
+*  - `x-organization-id` (from `configureAuth().getOrgId`)
+*  - `Content-Type: application/json` (only for plain object/array bodies)
+*  - `x-internal-api-key`, `Accept-Version`, `Idempotency-Key`,
+*    `x-arc-scope` when configured
+*
+* Composes with everything else `configureClient` + `configureAuth` do:
+*  - `retry` (5xx backoff)
+*  - `onAuthError` (401 → refresh → retry, with concurrent dedup)
+*  - `beforeRequest` / `afterResponse` interceptors
+*  - `cookie` / `bearer` / `header` auth modes
+*
+* Response handling:
+*  - 2xx → parsed body (JSON for `application/json`, Blob for binary,
+*    text for `text/*`).
+*  - non-2xx → throws `ArcApiError` with parsed body, status, endpoint,
+*    method. Use `isArcApiError(err)` + `err.code` to discriminate.
+*
+* For full `Response` control (rare), use plain `fetch` with
+* {@link arcAuthHeaders} instead.
+*
+* @example
+* import { arc } from '@classytic/arc-next/client';
+*
+* // Before — 15 lines of header dance + error parse + JSON
+* // After:
+* const result = await arc.post<{ ok: true }>('/api/statements', statements);
+*/
+function arcFetch(path, options = {}) {
+	const { method = "GET", body, headers, signal, elevated, idempotencyKey, revalidate, tags, cache, client } = options;
+	const transport = client ?? getDefaultArcFetchClient();
+	const apiOptions = {
+		body,
+		headerOptions: sanitizeUserHeaders(headers),
+		...signal ? { signal } : {},
+		...elevated !== void 0 ? { elevated } : {},
+		...idempotencyKey ? { idempotencyKey } : {},
+		...revalidate !== void 0 ? { revalidate } : {},
+		...tags ? { tags } : {},
+		...cache ? { cache } : {}
+	};
+	return transport.request(method, path, apiOptions);
+}
+/**
+* Method-specific shorthands for the 90% case. Each mirrors `arcFetch` with
+* the HTTP verb pre-filled; mutating verbs accept `body` as the second arg
+* so the call reads as a sentence:
+*
+*   `arc.post('/path', payload)` instead of
+*   `arcFetch('/path', { method: 'POST', body: payload })`.
+*
+* Identical composition with `onAuthError`, retry, and interceptors.
+*/
+const arc = {
+	get: (path, opts = {}) => arcFetch(path, {
+		...opts,
+		method: "GET"
+	}),
+	post: (path, body, opts = {}) => arcFetch(path, {
+		...opts,
+		method: "POST",
+		body
+	}),
+	put: (path, body, opts = {}) => arcFetch(path, {
+		...opts,
+		method: "PUT",
+		body
+	}),
+	patch: (path, body, opts = {}) => arcFetch(path, {
+		...opts,
+		method: "PATCH",
+		body
+	}),
+	delete: (path, opts = {}) => arcFetch(path, {
+		...opts,
+		method: "DELETE"
+	})
+};
 
 //#endregion
-export { ArcApiError, KNOWN_DETAILS_CODES, KNOWN_TOP_LEVEL_CODES, _resetAuthWarnings, buildStreamUrl, configureAuth, configureClient, createAuthAwareClient, createClient, createQueryString, getAuthContext, getAuthMode, getBaseUrl, getClientAuthContext, handleApiRequest, isAbortError, isArcApiError, isArcErrorCode, isAutoIdempotency, isDuplicateKeyError, isOrgContextRequiredError, isValidationError };
+export { ArcApiError, KNOWN_ARC_ERROR_CODES, _getAuthErrorHandler, _isAuthRecoverable, _resetArcFetchClient, _resetAuthRecovery, _resetAuthWarnings, _resolveRefreshedToken, _runAuthRecovery, arc, arcAuthHeaders, arcFetch, buildStreamUrl, configureAuth, configureClient, createAuthAwareClient, createAuthRefreshHandler, createClient, createQueryString, getAuthContext, getAuthMode, getBaseUrl, getClientAuthContext, handleApiRequest, hasGlobalStaticAuth, isAbortError, isArcApiError, isArcErrorCode, isAutoIdempotency, isDuplicateKeyError, isOrgContextRequiredError, isValidationError };