@classytic/arc-next 0.6.0 → 0.7.1

package/README.md

@@ -85,15 +85,33 @@ function Products() {
 ## Core Hooks (from `createCrudHooks`)
 
 ```ts
-const { items, pagination, isLoading, refetch } = useList(token, params, options);
-const { item, isLoading } = useDetail(id, token, options);
+const { items, pagination, isLoading, refetch } = useList(params, options);
+const { item, isLoading, isPlaceholderData } = useDetail(id, options);
 const { create, update, remove, isMutating } = useActions();
-const { items, hasNextPage, fetchNextPage } = useInfiniteList(token, params);
+const { items, hasNextPage, fetchNextPage } = useInfiniteList(params);
 
 await create({ data, organizationId }, { onSuccess: (item) => navigate(...) });
 ```
 
-All mutations are optimistic with automatic rollback on error. Lists prefill the detail cache. Cache keys auto-scope by `organizationId` when present.
+- All mutations are optimistic with automatic rollback on error.
+- Cache keys auto-scope by `organizationId` when present.
+- **List → detail handoff:** when a parent `useList` has the entity in cache,
+  `useDetail` reads it via TanStack's `placeholderData` factory — instant
+  preview, but the real detail GET still fires (rich payload swap, no
+  cache pollution). Use `isPlaceholderData` to dim the preview while it
+  resolves. See [CHANGELOG 0.7](./CHANGELOG.md#070) for why this replaced
+  the old setQueryData-based prefill.
+- **Detail → list pseudo-normalization:** after a `useDetail` GET resolves,
+  arc-next shallow-merges the fresh fields into every list cache holding
+  this id. The list view stays in sync without a refetch. Direction is
+  one-way (detail → list, never the reverse) — see
+  [CHANGELOG → "pseudo-normalization"](./CHANGELOG.md#070) for the
+  rationale. For true entity-level normalization (one copy per id, field-
+  level invalidation), use Apollo Client or Relay; arc-next stays in the
+  REST + React Query niche.
+
+`useList(token, params, options)` (legacy 3-arg form) still compiles —
+both signatures are kept stable across the 0.x line.
 
 ### `useApiQuery` — non-CRUD reads
 
@@ -413,13 +431,132 @@ configureClient({
 
 Interceptors are async-supported and compose with retry — `beforeRequest` re-runs each attempt (so a refreshed token mid-flight is picked up). Aborting via `AbortSignal` cancels both the pending fetch AND any in-flight backoff sleep.
 
+## `arcFetch` — one-line authenticated fetch for non-hook contexts (0.7+)
+
+When you need to hit an arc endpoint from outside a hook — event handler, service worker, server action, custom MDX submit, background poll — `arcFetch` collapses the auth/org/content-type/error/parse boilerplate into one call:
+
+```ts
+import { arc } from "@classytic/arc-next/client";
+
+// Before — 15 lines of header dance + error parse + JSON parse:
+//   const { token } = getAuthContext();
+//   if (!token) throw ...
+//   const res = await fetch(`${apiBaseUrl()}/api/statements`, {
+//     method: "POST",
+//     headers: { "content-type": "application/json", authorization: `Bearer ${token}`, ... },
+//     body: JSON.stringify(statements),
+//   });
+//   if (!res.ok) throw ...
+//   return await res.json();
+//
+// After:
+const result = await arc.post<{ ok: boolean }>("/api/statements", statements);
+```
+
+Auto-injects `Authorization` (or your `headerName` for `authMode: "header"`), `x-organization-id`, `x-internal-api-key`, `Idempotency-Key`, `x-arc-scope`, and `Content-Type: application/json` (only for plain object/array bodies). Composes with everything else — `retry`, `onAuthError`, `beforeRequest`, `afterResponse`.
+
+**Method shorthands:**
+
+```ts
+arc.get<T>(path, opts?)
+arc.post<T>(path, body?, opts?)
+arc.put<T>(path, body?, opts?)
+arc.patch<T>(path, body?, opts?)
+arc.delete<T>(path, opts?)
+
+// Or call arcFetch directly for full RequestInit control:
+arcFetch<T>(path, { method, body, headers, signal, elevated, idempotencyKey, revalidate, tags, cache, client })
+```
+
+**Body sniffing.** `FormData`, `Blob`, `URLSearchParams`, `ArrayBuffer`, `ReadableStream`, and `string` pass through unchanged — caller controls `Content-Type` for those. Plain objects and arrays get `JSON.stringify`d and the JSON content-type header.
+
+**Protected headers.** `Authorization`, `x-organization-id`, `x-internal-api-key`, and the custom header for `authMode: "header"` cannot be overridden by `options.headers`. A caller can't accidentally strip the bearer token by spreading their own header map. Non-auth headers (`X-Trace-Id`, `Accept-Version`, etc.) pass through normally.
+
+**Error handling.** Non-2xx throws `ArcApiError` with parsed body, status, endpoint, method — same contract as the CRUD hooks. Use `isArcApiError(err)` + `err.code` to discriminate.
+
+**Escape hatch.** When you need full `Response` control (rare — streaming downloads, custom redirect logic), use plain `fetch` with `arcAuthHeaders()`:
+
+```ts
+import { arcAuthHeaders, getAuthMode } from "@classytic/arc-next/client";
+
+const res = await fetch(url, {
+  headers: { ...arcAuthHeaders(), "X-Custom": "1" },
+  credentials: getAuthMode() === "cookie" ? "include" : "same-origin",
+});
+```
+
+## Auth Recovery (0.7+) — 401 → refresh → retry
+
+When a session token expires mid-page, the SDK transparently refreshes and retries — no flash of unauthenticated UI, no manual reload. Wire it once at app boot:
+
+```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 () => {
+      // Whatever your auth lib calls to mint a fresh access token.
+      const { data } = await authClient.getSession({ disableCookieCache: true });
+      return data?.session.token ?? null; // null → session truly expired; original 401 surfaces
+    },
+  }),
+});
+```
+
+Every `useList`, `useDetail`, `useActions`, and any code path going through `createAuthAwareClient()` or `createClient(...)` now survives token expiry transparently. Apps that don't wire `onAuthError` see the original behavior (401 surfaces immediately).
+
+**Concurrent-refresh dedup.** When N requests hit 401 at the same time, the handler fires **once**. All N concurrent callers await the same refresh promise and retry with the token it produces — no stampeding the refresh endpoint under burst auth-expiry.
+
+**Tuning knobs.**
+
+```ts
+configureAuth({
+  // ...
+  onAuthError,
+  retryOn403: true,    // also recover from 403 (default: 401 only)
+  maxAuthRetries: 1,   // cap per individual request (default: 1; prevents loops)
+});
+```
+
+**Custom handler.** Bypass `createAuthRefreshHandler` if you need full control over the recovery cycle:
+
+```ts
+configureAuth({
+  onAuthError: async ({ error, request, attempt, setToken }) => {
+    if (error.code === "session.revoked") return "skip"; // route to /login
+    const fresh = await myRefreshFn();
+    if (!fresh) return "skip";
+    setToken(fresh);
+    return "retry";
+  },
+});
+```
+
+The handler receives the full `ArcApiError`, the failing request descriptor, the 1-indexed attempt counter, and a `setToken(value)` callback that supplies the refreshed token for the retry. Throwing from the handler short-circuits — the thrown error propagates instead of the 401.
+
+**Transport coverage.** Auth recovery fires across every transport arc-next exposes:
+
+| Transport | Trigger | Mechanism |
+|---|---|---|
+| Fetch (CRUD hooks, `arcFetch`, `handleApiRequest`) | 401 / 403 response | Inline retry in `executeRequest` |
+| XHR upload (`uploadWithProgress`, `useUploadWithProgress`) | 401 / 403 response | Outer retry loop in `upload.ts` |
+| WebSocket | close code `1008` / `3401` / `4001` / `4401` | `ws.onclose` handler routes through recovery, reconnect with refreshed token |
+| SSE (`subscribeToEvents`, `useEventStream`) | `EventSource` error | Pre-flight `fetch` probe classifies as auth-failure → recovery → reopen |
+
+All four transports share **one** dedup'd refresh promise — concurrent failures across mixed transports (5 in-flight uploads + 3 WebSocket reconnects + 10 fetch calls, all 401 at once) collapse to a single `onAuthError` call.
+
 ## Cache & Keys
 
 ```ts
 KEYS.detail(id);                        // ["products", "detail", id]
 KEYS.scopedDetail(id, orgId);           // tenant-scoped variant
 
+// Writes/reads the raw doc — no `{ data: TDoc }` envelope (0.7+). Matches
+// what useDetail, prefetchDetail, and useNavigation all produce.
 cache.setDetail(qc, id, data);
+cache.getDetail(qc, id);                // TDoc | undefined
 cache.invalidateDetail(qc, id);         // matches all scoped variants
 cache.invalidateLists(qc);
 ```

package/dist/cache.d.ts

@@ -65,6 +65,27 @@ declare function extractItem<T>(data: unknown): T | null;
  * the array length changes.
  */
 declare function updateListCache<T>(listData: unknown, updater: (items: T[]) => T[]): 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
+ * `idField`, falling back to `_id` / `id`. Handles both flat list payloads
+ * and infinite-query page arrays.
+ *
+ * Only updates EXISTING list entries — never creates new caches or new items
+ * in lists. If the item moved between filter buckets (e.g. status changed),
+ * the relevant lists will refetch on their own; we don't try to predict
+ * filter membership.
+ *
+ * Returns the number of cache entries updated (useful for tests + telemetry).
+ *
+ * @param qc TanStack QueryClient
+ * @param listsKey Prefix key for this entity's lists (typically `KEYS.lists()`)
+ * @param item Fresh entity to merge into matching list items
+ * @param opts.idField Custom ID field name (defaults to `_id` / `id` lookup)
+ */
+declare function syncDetailToLists<TItem extends Record<string, unknown>>(qc: QueryClient, listsKey: QueryKey, item: TItem, opts?: {
+  idField?: string;
+}): number;
 interface QueryKeys {
   all: string[];
   lists: () => QueryKey;
@@ -119,7 +140,13 @@ interface CacheUtils<T> {
  * Build cache read/write/invalidate helpers bound to the given key factory.
  * Server-safe — operates on a `QueryClient` instance which can be a per-request
  * server client (during prefetch) or the browser singleton.
+ *
+ * **Wire shape:** Arc 2.13+ emits raw documents on `GET /:resource/:id` — no
+ * `{ data: ... }` envelope. `setDetail` / `getDetail` write and read the raw
+ * doc directly so the cache shape matches `useDetail`'s `queryFn` output,
+ * `useNavigation`'s pre-populated entries, and `prefetchDetail`'s server seed.
+ * All four paths converge on the same shape: TDoc, not `{ data: TDoc }`.
  */
 declare function createCacheUtils<T>(KEYS: QueryKeys): CacheUtils<T>;
 //#endregion
-export { CacheUtils, DEFAULT_QUERY_CONFIG, PaginationData, QUERY_CONFIGS, QueryKeys, createCacheUtils, createQueryKeys, extractItem, extractItems, getItemId, normalizePagination, updateListCache };
+export { CacheUtils, DEFAULT_QUERY_CONFIG, PaginationData, QUERY_CONFIGS, QueryKeys, createCacheUtils, createQueryKeys, extractItem, extractItems, getItemId, normalizePagination, syncDetailToLists, updateListCache };

package/dist/cache.js

@@ -115,6 +115,7 @@ function updateListCache(listData, updater) {
 	if (!arrayField) return listData;
 	const updated = updater(d[arrayField]);
 	const original = d[arrayField];
+	if (updated === original) return listData;
 	const delta = updated.length - original.length;
 	const result = {
 		...d,
@@ -126,6 +127,95 @@ function updateListCache(listData, updater) {
 	}
 	return result;
 }
+/** Item-identity helper that respects a custom idField, falling back to `_id` / `id`. */
+function resolveId(item, idField) {
+	if (!item || typeof item !== "object") return null;
+	if (idField) {
+		const v = item[idField];
+		if (v != null) return String(v);
+	}
+	return getItemId(item);
+}
+/**
+* Shallow-merge updater that preserves the receiver's key set. Detail payloads
+* are often richer than list payloads (populated relations, full body fields).
+* If we replaced wholesale we'd bloat list caches with detail-only fields and
+* force a full re-render on every value change. Merge keeps lists lean while
+* still picking up updates to fields the list already cares about.
+*/
+function shallowMergeKept(receiver, source) {
+	let changed = false;
+	const next = { ...receiver };
+	for (const key of Object.keys(receiver)) if (key in source && !Object.is(receiver[key], source[key])) {
+		next[key] = source[key];
+		changed = true;
+	}
+	return changed ? next : receiver;
+}
+/**
+* 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
+* `idField`, falling back to `_id` / `id`. Handles both flat list payloads
+* and infinite-query page arrays.
+*
+* Only updates EXISTING list entries — never creates new caches or new items
+* in lists. If the item moved between filter buckets (e.g. status changed),
+* the relevant lists will refetch on their own; we don't try to predict
+* filter membership.
+*
+* Returns the number of cache entries updated (useful for tests + telemetry).
+*
+* @param qc TanStack QueryClient
+* @param listsKey Prefix key for this entity's lists (typically `KEYS.lists()`)
+* @param item Fresh entity to merge into matching list items
+* @param opts.idField Custom ID field name (defaults to `_id` / `id` lookup)
+*/
+function syncDetailToLists(qc, listsKey, item, opts = {}) {
+	const targetId = resolveId(item, opts.idField);
+	if (!targetId) return 0;
+	let updates = 0;
+	const entries = qc.getQueriesData({ queryKey: listsKey });
+	for (const [qKey, raw] of entries) {
+		if (!raw) continue;
+		if (typeof raw === "object" && raw !== null && Array.isArray(raw.pages)) {
+			const inf = raw;
+			let pagesChanged = false;
+			const nextPages = inf.pages.map((page) => {
+				const merged = mergeItemIntoListPage(page, targetId, item, opts.idField);
+				if (merged !== page) pagesChanged = true;
+				return merged;
+			});
+			if (pagesChanged) {
+				qc.setQueryData(qKey, {
+					...inf,
+					pages: nextPages
+				});
+				updates += 1;
+			}
+			continue;
+		}
+		const merged = mergeItemIntoListPage(raw, targetId, item, opts.idField);
+		if (merged !== raw) {
+			qc.setQueryData(qKey, merged);
+			updates += 1;
+		}
+	}
+	return updates;
+}
+/** Internal — merge an item into a single list payload (one filter result or one infinite page). */
+function mergeItemIntoListPage(page, targetId, item, idField) {
+	return updateListCache(page, (items) => {
+		let changed = false;
+		const next = items.map((listItem) => {
+			if (!listItem || typeof listItem !== "object") return listItem;
+			if (resolveId(listItem, idField) !== targetId) return listItem;
+			const merged = shallowMergeKept(listItem, item);
+			if (merged !== listItem) changed = true;
+			return merged;
+		});
+		return changed ? next : items;
+	});
+}
 /**
 * Build a hierarchical query-key factory for a resource. The returned shape
 * is identical between server (prefetch) and client (hooks), so RSC SSR
@@ -186,26 +276,28 @@ function createQueryKeys(entityKey) {
 * Build cache read/write/invalidate helpers bound to the given key factory.
 * Server-safe — operates on a `QueryClient` instance which can be a per-request
 * server client (during prefetch) or the browser singleton.
+*
+* **Wire shape:** Arc 2.13+ emits raw documents on `GET /:resource/:id` — no
+* `{ data: ... }` envelope. `setDetail` / `getDetail` write and read the raw
+* doc directly so the cache shape matches `useDetail`'s `queryFn` output,
+* `useNavigation`'s pre-populated entries, and `prefetchDetail`'s server seed.
+* All four paths converge on the same shape: TDoc, not `{ data: TDoc }`.
 */
 function createCacheUtils(KEYS) {
 	return {
 		invalidateAll: (client) => client.invalidateQueries({ queryKey: KEYS.all }),
 		invalidateLists: (client) => client.invalidateQueries({ queryKey: KEYS.lists() }),
 		invalidateDetail: (client, id) => client.invalidateQueries({ queryKey: KEYS.detail(id) }),
-		setDetail: (client, id, data) => client.setQueryData(KEYS.detail(id), { data }),
-		getDetail: (client, id) => {
-			return client.getQueryData(KEYS.detail(id))?.data;
-		},
+		setDetail: (client, id, data) => client.setQueryData(KEYS.detail(id), data),
+		getDetail: (client, id) => client.getQueryData(KEYS.detail(id)) ?? void 0,
 		removeDetail: (client, id) => client.removeQueries({ queryKey: KEYS.detail(id) }),
 		invalidateScopedDetail: (client, id, organizationId) => client.invalidateQueries({ queryKey: KEYS.scopedDetail(id, organizationId) }),
-		setScopedDetail: (client, id, organizationId, data) => client.setQueryData(KEYS.scopedDetail(id, organizationId), { data }),
-		getScopedDetail: (client, id, organizationId) => {
-			return client.getQueryData(KEYS.scopedDetail(id, organizationId))?.data;
-		},
+		setScopedDetail: (client, id, organizationId, data) => client.setQueryData(KEYS.scopedDetail(id, organizationId), data),
+		getScopedDetail: (client, id, organizationId) => client.getQueryData(KEYS.scopedDetail(id, organizationId)) ?? void 0,
 		removeScopedDetail: (client, id, organizationId) => client.removeQueries({ queryKey: KEYS.scopedDetail(id, organizationId) }),
 		invalidateAggregations: (client, name) => client.invalidateQueries({ queryKey: name ? KEYS.aggregation(name) : KEYS.aggregations() })
 	};
 }
 
 //#endregion
-export { DEFAULT_QUERY_CONFIG, QUERY_CONFIGS, createCacheUtils, createQueryKeys, extractItem, extractItems, getItemId, normalizePagination, updateListCache };
+export { DEFAULT_QUERY_CONFIG, QUERY_CONFIGS, createCacheUtils, createQueryKeys, extractItem, extractItems, getItemId, normalizePagination, syncDetailToLists, updateListCache };

package/dist/client.d.ts

@@ -322,6 +322,17 @@ declare function getAuthMode(): 'bearer' | 'cookie' | 'header';
 declare function getBaseUrl(): string;
 /** Whether auto-idempotency is enabled on the global client. */
 declare function isAutoIdempotency(): boolean;
+/**
+ * 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.
+ */
+declare function hasGlobalStaticAuth(): boolean;
 interface AuthConfig {
   /**
    * Returns the current bearer/API token, or `null` if not authenticated.
@@ -329,15 +340,83 @@ interface AuthConfig {
    * **MUST resolve synchronously.** The signature is `() => string | null`, never
    * `Promise<string | null>`. If your auth library exposes an async session getter
    * (Better Auth, NextAuth, Clerk, OAuth flows), refresh the token out-of-band
-   * (timer, event listener, lazy 401 retry) and have `getToken` return the *cached*
-   * value. Returning a Promise will be detected and warned about in dev — but the
-   * underlying token will be silently treated as `null`, causing 401s.
+   * (timer, event listener, lazy 401 retry via {@link onAuthError}) and have
+   * `getToken` return the *cached* value. Returning a Promise will be detected and
+   * logged as an Error in dev — and the underlying token will be silently treated
+   * as `null`, causing 401s.
    */
   getToken?: () => string | null;
   getOrgId?: () => string | null;
   /** Custom auth header name. Used when authMode is 'header'. Default: 'x-api-key' */
   headerName?: string;
+  /**
+   * Lazy 401-recovery hook. Invoked once per request when the backend returns
+   * 401 (or 403, if {@link retryOn403} is true) AND a handler is configured.
+   *
+   * - Return `'retry'` to re-issue the request once with a fresh token.
+   * - Return `'skip'` to surface the original error to the caller (e.g. after
+   *   a refresh attempt that found no valid session — let the consumer route
+   *   to sign-in).
+   * - Throw to short-circuit; the thrown error propagates to the caller.
+   *
+   * **Concurrent dedup.** When N requests hit 401 at the same time, the handler
+   * fires ONCE — every concurrent caller awaits the same refresh promise and
+   * retries with the token it produced. Avoids stampeding the refresh endpoint.
+   *
+   * **Token propagation.** Inside the handler, call `ctx.setToken(newToken)` to
+   * inject the refreshed token for the retry. If you've already updated your
+   * global auth state out-of-band (e.g. updated a signal or the auth library's
+   * cache), you can omit `setToken` — arc-next re-reads via `getToken()` on
+   * the retry attempt.
+   *
+   * @see {@link createAuthRefreshHandler} for the canonical wiring with any
+   * `refresh()` function (Better Auth, NextAuth, custom OAuth flows).
+   */
+  onAuthError?: AuthErrorHandler;
+  /**
+   * Treat 403 as auth-recoverable too. Default: `false` (only 401 triggers
+   * the handler). Enable for backends that emit 403 on expired sessions
+   * instead of 401.
+   */
+  retryOn403?: boolean;
+  /**
+   * Cap on auth-recovery retries per individual request. Default: `1`.
+   * Bumping above 1 risks pathological loops if the refresh itself
+   * triggers 401s — only do it if you have hard guarantees on `getToken()`.
+   */
+  maxAuthRetries?: number;
+}
+/**
+ * Context passed to {@link AuthConfig.onAuthError} when a request 401s.
+ *
+ * Inspect `error` to decide whether to refresh. Call `setToken(t)` to inject
+ * the refreshed token for the retry — arc-next prefers this value over
+ * re-reading `getToken()`, so it works even when your auth library hasn't
+ * yet propagated the new session.
+ */
+interface AuthErrorContext {
+  /** The 401/403 thrown by the failing request. Carries `status`, `code`, `json`. */
+  error: ArcApiError;
+  /** The request that failed — useful for path-based heuristics. */
+  request: {
+    method: HttpMethod;
+    endpoint: string;
+  };
+  /**
+   * 1-indexed auth-recovery attempt. First 401 in a request lifecycle is 1.
+   * Reaches {@link AuthConfig.maxAuthRetries} → handler is NOT called again
+   * and the 401 surfaces.
+   */
+  attempt: number;
+  /**
+   * Inject the refreshed token for the retry. Pass `null` to retry
+   * unauthenticated. Optional — omit if `getToken()` already returns the
+   * fresh value.
+   */
+  setToken: (token: string | null) => void;
 }
+/** {@link AuthConfig.onAuthError} signature. */
+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.
@@ -368,6 +447,95 @@ declare function getAuthContext(): {
 };
 /** @internal — exposed for tests; resets the dev-warn dedup flag. */
 declare function _resetAuthWarnings(): void;
+/**
+ * Outcome of a single auth-recovery cycle. `overrideToken` is the value the
+ * handler injected via `setToken`; `undefined` means the handler didn't call
+ * `setToken` and we should re-read via `getToken()`. `null` is meaningful —
+ * "retry without a token" (rare but valid for public endpoints).
+ */
+interface AuthRecoveryResult {
+  decision: 'retry' | 'skip';
+  overrideToken: string | null | undefined;
+}
+/** @internal — exposed for tests; clears the dedup so they don't bleed. */
+declare function _resetAuthRecovery(): void;
+/**
+ * @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).
+ */
+declare function _getAuthErrorHandler(): {
+  handler: AuthErrorHandler | undefined;
+  retryOn403: boolean;
+  maxAuthRetries: number;
+};
+/**
+ * @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.
+ */
+declare function _runAuthRecovery(handler: AuthErrorHandler, ctx: Omit<AuthErrorContext, 'setToken'>): Promise<AuthRecoveryResult>;
+/**
+ * @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.
+ */
+declare function _resolveRefreshedToken(overrideToken: string | null | undefined): string | null;
+/**
+ * @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`).
+ */
+declare function _isAuthRecoverable(error: unknown, retryOn403: boolean): boolean;
+/**
+ * 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()),
+ *   }),
+ * });
+ * ```
+ */
+declare function createAuthRefreshHandler(opts: {
+  refresh: () => Promise<string | null>;
+  /**
+   * Behavior when the `refresh()` call itself throws. Default: `'skip'`
+   * (the original 401 surfaces; consumers handle "session expired" once).
+   */
+  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';
 /**
@@ -521,5 +689,110 @@ declare function handleApiRequest<T = unknown>(method: HttpMethod, endpoint: str
  * // => 'populate[employeeId][select]=name,email'
  */
 declare function createQueryString<T extends Record<string, unknown>>(params?: T): string;
+/**
+ * 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',
+ * });
+ */
+declare function arcAuthHeaders(): Record<string, string>;
+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`,
+   * `Blob`, `ArrayBuffer`, `URLSearchParams`, `ReadableStream`) and strings
+   * pass through unchanged — the caller owns `Content-Type` for those.
+   */
+  body?: Record<string, unknown> | unknown[] | BodyInit | null;
+  /**
+   * Extra headers merged on top of arc-next's auto-injected ones. Auth-
+   * related headers (`Authorization`, `x-organization-id`,
+   * `x-internal-api-key`, and the configured custom-auth header name) are
+   * **protected** — passing them here is silently dropped, so a caller can't
+   * accidentally strip the bearer token by spreading their own header map.
+   */
+  headers?: Record<string, string>;
+  /** AbortSignal — same semantics as `fetch`. */
+  signal?: AbortSignal;
+  /** Per-call elevated-scope override (`x-arc-scope: platform`). */
+  elevated?: boolean;
+  /** Per-call `Idempotency-Key` header. */
+  idempotencyKey?: string;
+  /** Next.js fetch `revalidate` pass-through. */
+  revalidate?: number;
+  /** Next.js fetch `tags` pass-through. */
+  tags?: string[];
+  /** `cache` pass-through (browser fetch + Next.js). */
+  cache?: RequestCache;
+  /**
+   * Per-call client. Defaults to a lazily-created `createAuthAwareClient()`
+   * that bridges global `configureClient` + `configureAuth`. Pass a
+   * dedicated `createClient(...)` for multi-backend apps.
+   */
+  client?: ArcClient;
+}
+/** @internal — tests reset the default client between cases. */
+declare function _resetArcFetchClient(): void;
+/**
+ * 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);
+ */
+declare function arcFetch<T = unknown>(path: string, options?: ArcFetchOptions): Promise<T>;
+/**
+ * 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.
+ */
+declare const arc: {
+  get: <T = unknown>(path: string, opts?: ArcFetchOptions) => Promise<T>;
+  post: <T = unknown>(path: string, body?: ArcFetchOptions["body"], opts?: ArcFetchOptions) => Promise<T>;
+  put: <T = unknown>(path: string, body?: ArcFetchOptions["body"], opts?: ArcFetchOptions) => Promise<T>;
+  patch: <T = unknown>(path: string, body?: ArcFetchOptions["body"], opts?: ArcFetchOptions) => Promise<T>;
+  delete: <T = unknown>(path: string, opts?: ArcFetchOptions) => Promise<T>;
+};
 //#endregion
-export { AfterResponseContext, AfterResponseInterceptor, ApiRequestOptions, ArcApiError, ArcApiErrorOptions, ArcClient, ArcClientConfig, ArcErrorCode, AuthConfig, BeforeRequestContext, BeforeRequestInterceptor, BlobResponse, ClientConfig, HttpMethod, KNOWN_ARC_ERROR_CODES, RetryConfig, StreamUrlProtocol, TextResponse, ToastHandler, UseRouterHook, _resetAuthWarnings, buildStreamUrl, configureAuth, configureClient, createAuthAwareClient, createClient, createQueryString, getAuthContext, getAuthMode, getBaseUrl, getClientAuthContext, handleApiRequest, isAbortError, isArcApiError, isArcErrorCode, isAutoIdempotency, isDuplicateKeyError, isOrgContextRequiredError, isValidationError };
+export { AfterResponseContext, AfterResponseInterceptor, ApiRequestOptions, ArcApiError, ArcApiErrorOptions, ArcClient, ArcClientConfig, ArcErrorCode, ArcFetchOptions, AuthConfig, AuthErrorContext, AuthErrorHandler, BeforeRequestContext, BeforeRequestInterceptor, BlobResponse, ClientConfig, HttpMethod, KNOWN_ARC_ERROR_CODES, 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, handleApiRequest, hasGlobalStaticAuth, isAbortError, isArcApiError, isArcErrorCode, isAutoIdempotency, isDuplicateKeyError, isOrgContextRequiredError, isValidationError };