@classytic/arc-next 0.4.0 → 0.5.0

package/dist/cache.js

@@ -0,0 +1,197 @@
+//#region src/cache.ts
+const DEFAULT_QUERY_CONFIG = {
+	staleTime: 300 * 1e3,
+	gcTime: 1800 * 1e3,
+	refetchOnWindowFocus: false,
+	retry: 0
+};
+/** Pre-built query config presets for common data freshness patterns. */
+const QUERY_CONFIGS = {
+	realtime: {
+		staleTime: 2e4,
+		refetchInterval: 3e4
+	},
+	frequent: { staleTime: 6e4 },
+	stable: { staleTime: 3e5 },
+	static: { staleTime: 6e5 }
+};
+/** Well-known keys checked in order for list responses. */
+const LIST_KEYS = [
+	"docs",
+	"data",
+	"items",
+	"results"
+];
+/** Well-known keys checked in order for detail responses. */
+const DETAIL_KEYS = [
+	"data",
+	"doc",
+	"item",
+	"result"
+];
+/**
+* Extract `_id` or `id` from any item. Returns `null` if neither exists.
+* Coerces numeric IDs to strings so cache keys stay consistent.
+*/
+function getItemId(item) {
+	if (!item || typeof item !== "object") return null;
+	const obj = item;
+	const id = obj._id ?? obj.id;
+	return typeof id === "string" ? id : id ? String(id) : null;
+}
+/**
+* Normalize any pagination response shape (offset / keyset / aggregate) to a
+* uniform `PaginationData` object. Returns `null` when no pagination signal
+* is present.
+*/
+function normalizePagination(data) {
+	if (!data || typeof data !== "object") return null;
+	const d = data;
+	const method = d.method ?? null;
+	const isKeyset = method === "keyset" || d.hasMore != null && d.total == null && d.pages == null;
+	const hasTotal = d.total != null || d.totalDocs != null;
+	const hasPages = d.pages != null || d.totalPages != null;
+	if (!hasTotal && !hasPages && !isKeyset) return null;
+	return {
+		method,
+		total: Number(d.total ?? d.totalDocs ?? 0),
+		pages: Number(d.pages ?? d.totalPages ?? (isKeyset ? 0 : 1)),
+		page: Number(d.page ?? d.currentPage ?? (isKeyset ? 0 : 1)),
+		limit: Number(d.limit ?? 10),
+		hasNext: Boolean(d.hasNext ?? d.hasNextPage ?? d.hasMore ?? false),
+		hasPrev: Boolean(d.hasPrev ?? d.hasPrevPage ?? false),
+		...isKeyset ? { next: d.next ?? null } : {}
+	};
+}
+/**
+* Permissive list extractor. Checks well-known keys (`docs`, `data`, `items`,
+* `results`) then falls back to *any* top-level array — so `{ products: [...] }`
+* and `{ users: [...] }` work without per-resource configuration.
+*/
+function extractItems(data) {
+	if (!data) return [];
+	if (Array.isArray(data)) return data;
+	if (typeof data !== "object") return [];
+	const d = data;
+	for (const key of LIST_KEYS) if (Array.isArray(d[key])) return d[key];
+	for (const value of Object.values(d)) if (Array.isArray(value)) return value;
+	return [];
+}
+/**
+* Strict detail extractor. Checks well-known keys (`data`, `doc`, `item`,
+* `result`); falls back to returning the response as-is. Primitive responses
+* (string/number/boolean) pass through.
+*/
+function extractItem(data) {
+	if (data == null) return null;
+	if (typeof data !== "object") return data;
+	const d = data;
+	for (const key of DETAIL_KEYS) if (d[key] != null) return d[key];
+	return d;
+}
+/**
+* Optimistic-update helper that mutates the items array of a list cache
+* regardless of which key holds it. Auto-adjusts `total`/`totalDocs` when
+* the array length changes.
+*/
+function updateListCache(listData, updater) {
+	if (!listData) return listData;
+	if (Array.isArray(listData)) return updater(listData);
+	if (typeof listData !== "object") return listData;
+	const d = listData;
+	let arrayField = null;
+	for (const key of LIST_KEYS) if (Array.isArray(d[key])) {
+		arrayField = key;
+		break;
+	}
+	if (!arrayField) {
+		for (const [key, value] of Object.entries(d)) if (Array.isArray(value)) {
+			arrayField = key;
+			break;
+		}
+	}
+	if (!arrayField) return listData;
+	const updated = updater(d[arrayField]);
+	const original = d[arrayField];
+	const delta = updated.length - original.length;
+	const result = {
+		...d,
+		[arrayField]: updated
+	};
+	if (delta !== 0) {
+		if (d.total != null) result.total = Math.max(0, Number(d.total) + delta);
+		if (d.totalDocs != null) result.totalDocs = Math.max(0, Number(d.totalDocs) + delta);
+	}
+	return result;
+}
+/**
+* Build a hierarchical query-key factory for a resource. The returned shape
+* is identical between server (prefetch) and client (hooks), so RSC SSR
+* hydration matches what client-side `useList`/`useDetail` produce.
+*/
+function createQueryKeys(entityKey) {
+	return {
+		all: [entityKey],
+		lists: () => [entityKey, "list"],
+		list: (params) => [
+			entityKey,
+			"list",
+			params
+		],
+		details: () => [entityKey, "detail"],
+		detail: (id) => [
+			entityKey,
+			"detail",
+			id
+		],
+		scopedDetail: (id, organizationId) => organizationId ? [
+			entityKey,
+			"detail",
+			id,
+			{ _org: organizationId }
+		] : [
+			entityKey,
+			"detail",
+			id
+		],
+		custom: (key, ...args) => [
+			entityKey,
+			key,
+			...args
+		],
+		scopedList: (scope, params) => [
+			entityKey,
+			"list",
+			{
+				_scope: scope,
+				...params
+			}
+		]
+	};
+}
+/**
+* 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.
+*/
+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;
+		},
+		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;
+		},
+		removeScopedDetail: (client, id, organizationId) => client.removeQueries({ queryKey: KEYS.scopedDetail(id, organizationId) })
+	};
+}
+
+//#endregion
+export { DEFAULT_QUERY_CONFIG, QUERY_CONFIGS, createCacheUtils, createQueryKeys, extractItem, extractItems, getItemId, normalizePagination, updateListCache };

package/dist/client.d.ts

@@ -11,6 +11,40 @@ type UseRouterHook = () => {
     scroll?: boolean;
   }) => void;
 };
+/**
+ * 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).
+ */
+declare const KNOWN_TOP_LEVEL_CODES: readonly ["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"];
+/**
+ * Top-level HTTP-status error code union derived from {@link KNOWN_TOP_LEVEL_CODES}.
+ * `(string & {})` keeps the type open so non-arc backends or custom error mappers
+ * still satisfy it.
+ */
+type ArcTopLevelErrorCode = (typeof KNOWN_TOP_LEVEL_CODES)[number] | (string & {});
+/**
+ * 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".
+ */
+declare const KNOWN_DETAILS_CODES: readonly ["ORG_CONTEXT_REQUIRED", "ORG_ROLE_REQUIRED", "OWNERSHIP_DENIED", "MIXED_UPDATE_SHAPE", "ALL_FIELDS_STRIPPED", "BEFORE_RESTORE_HOOK_ERROR"];
+/**
+ * Nested business-logic error code union derived from {@link KNOWN_DETAILS_CODES}.
+ * Same `(string & {})` escape hatch as {@link ArcTopLevelErrorCode}.
+ */
+type ArcDetailsErrorCode = (typeof KNOWN_DETAILS_CODES)[number] | (string & {});
 interface ArcApiErrorOptions {
   status: number;
   statusText: string;
@@ -39,13 +73,109 @@ declare class ArcApiError extends Error {
   readonly endpoint: string;
   readonly method: HttpMethod;
   constructor(message: string, options: ArcApiErrorOptions);
-  /** Extract field-level validation errors if present (e.g. `{ field: "message" }`) */
+  /**
+   * Top-level error code from arc's response 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.
+   *
+   * @example
+   * if (error.code === 'DUPLICATE_KEY') showRetryAsAdmin();
+   */
+  get code(): ArcTopLevelErrorCode | 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 })');
+   * }
+   */
+  get detailsCode(): ArcDetailsErrorCode | 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.
+   */
   get fieldErrors(): Record<string, string> | null;
 }
 /**
  * Type guard for ArcApiError.
  */
 declare function isArcApiError(error: unknown): error is ArcApiError;
+/**
+ * Detects request cancellation (AbortSignal triggered) regardless of runtime.
+ *
+ * Filtering out abort errors from real failures is a common need — without it,
+ * unmounting a React component mid-fetch produces noisy logs and bogus error
+ * toasts that look like API failures. Use this predicate to skip the catch
+ * branch when the request was deliberately cancelled.
+ *
+ * Handles the three AbortError shapes you'll see in the wild:
+ * 1. Browser `DOMException { name: 'AbortError' }`
+ * 2. Node 18+ / undici `Error { name: 'AbortError' }` (no DOMException)
+ * 3. Some polyfills / older runtimes where the error has `code: 'ERR_ABORTED'`
+ *
+ * @example
+ * try {
+ *   await api.getAll({ options: { signal } });
+ * } catch (err) {
+ *   if (isAbortError(err)) return; // user navigated away — silence
+ *   showToast('Failed to load: ' + err.message);
+ * }
+ */
+declare function isAbortError(error: unknown): boolean;
+/**
+ * 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`.
+ *
+ * @example
+ * if (isArcErrorCode(error, 'DUPLICATE_KEY')) showRetryUI();
+ * if (isArcErrorCode(error, 'ORG_CONTEXT_REQUIRED')) promptOrgSelector();
+ */
+declare function isArcErrorCode(error: unknown, code: ArcTopLevelErrorCode | ArcDetailsErrorCode): error is ArcApiError;
+/**
+ * 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.
+ *
+ * @example
+ * try { await api.bulkCreate({ data: [...] }); }
+ * catch (e) {
+ *   if (isOrgContextRequiredError(e)) {
+ *     console.warn('Bulk requires org context. Configure: configureAuth({ getOrgId })');
+ *   } else throw e;
+ * }
+ */
+declare function isOrgContextRequiredError(error: unknown): error is ArcApiError;
+/**
+ * Specific predicate for arc's `VALIDATION_ERROR` (Fastify AJV + Mongoose
+ * ValidationError). When true, `error.fieldErrors` is populated with the
+ * `{ field: message }` map.
+ */
+declare function isValidationError(error: unknown): error is ArcApiError;
+/**
+ * Specific predicate for arc's `DUPLICATE_KEY` (unique-constraint violation).
+ * Arc's errorHandler classifies these uniformly across MongoDB E11000,
+ * Postgres 23505, and Prisma P2002.
+ */
+declare function isDuplicateKeyError(error: unknown): error is ArcApiError;
 interface ClientConfig {
   baseUrl: string;
   internalApiKey?: string;
@@ -79,7 +209,101 @@ interface ClientConfig {
    * Default: false — opt-in per-request via `idempotencyKey` option.
    */
   autoIdempotency?: boolean;
+  /**
+   * Send `x-arc-scope: platform` on every request. Triggers arc's elevated-scope
+   * upgrade (member → elevated) when the caller has the appropriate permission.
+   * Use sparingly — typically only for internal admin tooling.
+   * Per-request override: set `elevated: true | false` on `RequestOptions`.
+   */
+  elevated?: boolean;
+  /**
+   * 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
+   * direct `handleApiRequest` call get nothing without this.
+   *
+   * @example
+   * configureClient({
+   *   baseUrl,
+   *   retry: { attempts: 3, backoff: 'exponential' },
+   * });
+   */
+  retry?: RetryConfig;
+  /**
+   * Mutate the outgoing request before fetch. Runs once per attempt (so a retry
+   * re-runs the interceptor — useful for refreshed tokens or rotated trace IDs).
+   * Return the (possibly modified) context. Async is supported.
+   *
+   * @example
+   * configureClient({
+   *   baseUrl,
+   *   beforeRequest: (req) => ({
+   *     ...req,
+   *     headers: { ...req.headers, 'x-correlation-id': crypto.randomUUID() },
+   *   }),
+   * });
+   */
+  beforeRequest?: BeforeRequestInterceptor;
+  /**
+   * Inspect or transform the parsed response body. Receives the same shape the
+   * SDK is about to return; returning a new `body` replaces it. Errors are not
+   * forwarded here — they throw `ArcApiError` before this runs. Async is supported.
+   *
+   * @example
+   * configureClient({
+   *   baseUrl,
+   *   afterResponse: (res) => {
+   *     console.log(`[arc] ${res.method} ${res.endpoint} ${res.status} ${res.durationMs}ms`);
+   *     return res; // unchanged
+   *   },
+   * });
+   */
+  afterResponse?: AfterResponseInterceptor;
+}
+interface RetryConfig {
+  /** Total attempts including the first. `attempts: 3` means 1 try + 2 retries. Default: 0 (off). */
+  attempts?: number;
+  /**
+   * Backoff strategy.
+   * - `'exponential'` (default): `min(300 * 2^n, 10_000)` ms
+   * - `'linear'`: `300 * (n + 1)` ms
+   * - `(attempt) => number`: custom delay in ms; receives the 0-indexed retry attempt
+   */
+  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
+   * TypeError) AND `ArcApiError.status >= 500 && < 600`. Never retries on
+   * AbortError or 4xx.
+   */
+  retryOn?: number[] | ((error: unknown) => boolean);
 }
+/** Context handed to {@link ClientConfig.beforeRequest}. Mutate + return to override. */
+interface BeforeRequestContext {
+  method: HttpMethod;
+  endpoint: string;
+  /** Headers about to be sent. Mutating this is the recommended way to inject auth/trace headers. */
+  headers: Record<string, string>;
+  /** Body as the SDK is about to send it (already JSON-stringified, FormData, or undefined). */
+  body: BodyInit | undefined;
+  /** AbortSignal forwarded to fetch, if any. */
+  signal?: AbortSignal;
+  /** 0 on first attempt, 1+ on retries — useful for trace stamping. */
+  attempt: number;
+}
+type BeforeRequestInterceptor = (ctx: BeforeRequestContext) => BeforeRequestContext | Promise<BeforeRequestContext>;
+/** Context handed to {@link ClientConfig.afterResponse}. */
+interface AfterResponseContext<T = unknown> {
+  method: HttpMethod;
+  endpoint: string;
+  status: number;
+  /** Parsed response body — JSON object, blob wrapper, or text wrapper depending on Content-Type. */
+  body: T;
+  /** Total elapsed milliseconds from `beforeRequest` invocation to response parse complete. */
+  durationMs: number;
+  /** Original Response — clone before reading body if you need raw access. */
+  response: Response;
+}
+type AfterResponseInterceptor = <T = unknown>(ctx: AfterResponseContext<T>) => AfterResponseContext<T> | Promise<AfterResponseContext<T>>;
 /**
  * Configure the API client. Call once at app init before any API requests.
  *
@@ -99,9 +323,21 @@ declare function configureClient(config: ClientConfig): void;
  * Get the configured auth mode. Returns 'bearer' if not configured.
  */
 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. */
 declare function isAutoIdempotency(): boolean;
 interface AuthConfig {
+  /**
+   * Returns the current bearer/API token, or `null` if not authenticated.
+   *
+   * **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.
+   */
   getToken?: () => string | null;
   getOrgId?: () => string | null;
   /** Custom auth header name. Used when authMode is 'header'. Default: 'x-api-key' */
@@ -113,11 +349,15 @@ interface AuthConfig {
  *
  * **SSR safety:** This sets module-level state. Call only in client-side code.
  *
+ * **Token resolution is synchronous.** `getToken` must return `string | null`
+ * synchronously — never a Promise. See {@link AuthConfig.getToken} for guidance
+ * on bridging async auth libraries via cached values.
+ *
  * @example
  * // Cookie auth (no token needed)
  * configureAuth({ getOrgId: () => currentOrg.id });
  *
- * // Bearer auth
+ * // Bearer auth — token is cached synchronously by the auth library
  * configureAuth({
  *   getToken: () => session?.accessToken ?? null,
  *   getOrgId: () => currentOrg?.id ?? null,
@@ -131,7 +371,34 @@ declare function getAuthContext(): {
   token: string | null;
   organizationId: string | null;
 };
+/** @internal — exposed for tests; resets the dev-warn dedup flag. */
+declare function _resetAuthWarnings(): void;
+/** Protocol family the URL should target. `http` keeps `getBaseUrl()` as-is; `ws` rewrites `http(s)://` → `ws(s)://`. */
+type StreamUrlProtocol = 'http' | 'ws';
+/**
+ * Build an auth-aware URL using the global client + auth singletons.
+ *
+ * Single source of truth for {@link import('./sse.js').buildSseUrl} (HTTP) and
+ * {@link import('./ws.js').buildWsUrl} (WebSocket). Both delegate here so the
+ * auth-injection rule (org always, token only when `authMode !== 'cookie'`)
+ * stays in one place and can't drift.
+ *
+ * @param path Path appended to the base URL (leading slash recommended).
+ * @param params Caller-supplied params; merged with auth params. Caller wins on key collision.
+ * @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';
+/** Returned by `handleApiRequest` for PDF, image, and CSV responses. */
+interface BlobResponse {
+  data: Blob;
+  response: Response;
+}
+/** Returned by `handleApiRequest` for text/plain and text/html responses. */
+interface TextResponse {
+  data: string;
+  response: Response;
+}
 interface ApiRequestOptions {
   body?: unknown;
   token?: string | null;
@@ -143,31 +410,96 @@ interface ApiRequestOptions {
   signal?: AbortSignal;
   /** Explicit idempotency key for this request. Sent as `Idempotency-Key` header. */
   idempotencyKey?: string;
+  /**
+   * Send `x-arc-scope: platform` for this request only — overrides `ClientConfig.elevated`.
+   * Pass `false` to suppress when client-level elevation is on.
+   */
+  elevated?: boolean;
 }
 interface ArcClientConfig extends ClientConfig {
   toast?: ToastHandler;
   navigation?: UseRouterHook;
+  /** Per-client token provider. Overrides global configureAuth().getToken. */
+  getToken?: () => string | null;
+  /** Per-client org ID provider. Overrides global configureAuth().getOrgId. */
+  getOrgId?: () => string | null;
+  /** Per-client custom auth header name. Used when authMode is 'header'. */
+  headerName?: string;
 }
 interface ArcClient {
   request: <T = unknown>(method: HttpMethod, endpoint: string, options?: ApiRequestOptions) => Promise<T>;
   config: ClientConfig;
   toast?: ToastHandler;
   navigation?: UseRouterHook;
+  /** Per-client auth context. Falls back to global configureAuth() when not set. */
+  auth?: {
+    getToken?: () => string | null;
+    getOrgId?: () => string | null;
+    headerName?: string;
+  };
 }
 /**
  * Create an isolated API client for a specific backend.
- * Use this when your app needs to talk to multiple APIs.
+ * Use this when your app needs to talk to multiple APIs with different auth.
  *
  * @example
+ * // Bearer auth for main API
+ * const mainClient = createClient({
+ *   baseUrl: 'https://api.example.com',
+ *   getToken: () => session.accessToken,
+ * });
+ *
+ * // API key auth for analytics
  * const analyticsClient = createClient({
  *   baseUrl: 'https://analytics.example.com',
- *   toast: { success: toast.success, error: toast.error },
- *   navigation: useRouter,
+ *   authMode: 'header',
+ *   getToken: () => env.ANALYTICS_KEY,
+ *   headerName: 'x-api-key',
  * });
- *
- * const eventsApi = createCrudApi('events', { client: analyticsClient });
  */
 declare function createClient(config: ArcClientConfig): ArcClient;
+/**
+ * Create an `ArcClient` wired to the global `configureClient` + `configureAuth` setup.
+ *
+ * Removes the boilerplate every consumer SDK writes by hand (auth-injection adapter
+ * + `BaseApi` constructor with `client: { request: handleApiRequest, config: ... }`).
+ * The returned client reads `getToken` / `getOrgId` lazily on each request, so token
+ * rotation in the global auth layer takes effect immediately.
+ *
+ * Equivalent to `createClient(...)` with `getToken`/`getOrgId` pulled from
+ * `getAuthContext()`. Pass `overrides` to customize specific fields without
+ * rebuilding the whole transport.
+ *
+ * @example
+ * // App init (somewhere in a "use client" provider)
+ * configureClient({ baseUrl: process.env.NEXT_PUBLIC_API_URL! });
+ * configureAuth({
+ *   getToken: () => session?.accessToken ?? null,
+ *   getOrgId: () => currentOrg?.id ?? null,
+ * });
+ *
+ * // SDK module
+ * import { createAuthAwareClient } from '@classytic/arc-next/client';
+ * import { createCrudApi } from '@classytic/arc-next/api';
+ *
+ * const client = createAuthAwareClient();
+ * export const productsApi = createCrudApi('products', { client });
+ *
+ * // With per-call overrides
+ * const analyticsClient = createAuthAwareClient({
+ *   baseUrl: 'https://analytics.example.com',
+ *   authMode: 'header',
+ *   headerName: 'x-api-key',
+ * });
+ */
+declare function createAuthAwareClient(overrides?: Partial<ArcClientConfig>): ArcClient;
+/**
+ * Get auth context for a specific client instance, falling back to global.
+ */
+declare function getClientAuthContext(client?: ArcClient): {
+  token: string | null;
+  organizationId: string | null;
+};
 /**
  * Universal API request handler.
  * Handles JSON, binary (PDF, images), CSV, and text responses.
@@ -195,4 +527,4 @@ declare function handleApiRequest<T = unknown>(method: HttpMethod, endpoint: str
  */
 declare function createQueryString<T extends Record<string, unknown>>(params?: T): string;
 //#endregion
-export { ApiRequestOptions, ArcApiError, ArcApiErrorOptions, ArcClient, ArcClientConfig, AuthConfig, ClientConfig, HttpMethod, ToastHandler, UseRouterHook, configureAuth, configureClient, createClient, createQueryString, getAuthContext, getAuthMode, handleApiRequest, isArcApiError, isAutoIdempotency };
+export { AfterResponseContext, AfterResponseInterceptor, ApiRequestOptions, ArcApiError, ArcApiErrorOptions, ArcClient, ArcClientConfig, ArcDetailsErrorCode, ArcTopLevelErrorCode, AuthConfig, BeforeRequestContext, BeforeRequestInterceptor, BlobResponse, ClientConfig, HttpMethod, KNOWN_DETAILS_CODES, KNOWN_TOP_LEVEL_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 };