@classytic/arc-next 0.5.0 → 0.7.0

package/dist/client.d.ts

@@ -1,3 +1,5 @@
+import { ErrorDetail } from "@classytic/repo-core/errors";
+
 //#region src/client.d.ts
 interface ToastHandler {
   success: (message: string) => void;
@@ -12,39 +14,33 @@ type UseRouterHook = () => {
   }) => 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.
+ * 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`.
  *
- * 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".
+ * 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.
  */
-declare const KNOWN_DETAILS_CODES: readonly ["ORG_CONTEXT_REQUIRED", "ORG_ROLE_REQUIRED", "OWNERSHIP_DENIED", "MIXED_UPDATE_SHAPE", "ALL_FIELDS_STRIPPED", "BEFORE_RESTORE_HOOK_ERROR"];
+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"];
 /**
- * Nested business-logic error code union derived from {@link KNOWN_DETAILS_CODES}.
- * Same `(string & {})` escape hatch as {@link ArcTopLevelErrorCode}.
+ * Canonical arc error code union. `(string & {})` keeps the type open so
+ * domain packages can extend hierarchically (`'order.cart.locked'`,
+ * `'payment.gateway.timeout'`) and still satisfy the type.
  */
-type ArcDetailsErrorCode = (typeof KNOWN_DETAILS_CODES)[number] | (string & {});
+type ArcErrorCode = (typeof KNOWN_ARC_ERROR_CODES)[number] | (string & {});
 interface ArcApiErrorOptions {
   status: number;
   statusText: string;
@@ -74,39 +70,36 @@ declare class ArcApiError extends Error {
   readonly method: HttpMethod;
   constructor(message: string, options: ArcApiErrorOptions);
   /**
-   * 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(): ArcTopLevelErrorCode | null;
+  get code(): ArcErrorCode | 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(): ArcDetailsErrorCode | null;
+  get details(): readonly ErrorDetail[] | 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(): Record<string, string> | null;
 }
@@ -137,23 +130,24 @@ declare function isArcApiError(error: unknown): error is ArcApiError;
  */
 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`.
+ * 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();
  */
-declare function isArcErrorCode(error: unknown, code: ArcTopLevelErrorCode | ArcDetailsErrorCode): error is ArcApiError;
+declare function isArcErrorCode(error: unknown, code: ArcErrorCode): 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.
+ * `403 { code: 'ORG_CONTEXT_REQUIRED', message, status: 403 }`. Hosts hitting
+ * this need to call `configureAuth({ getOrgId })` before retrying.
  *
  * @example
  * try { await api.bulkCreate({ data: [...] }); }
@@ -165,15 +159,16 @@ declare function isArcErrorCode(error: unknown, code: ArcTopLevelErrorCode | Arc
  */
 declare function isOrgContextRequiredError(error: unknown): error is ArcApiError;
 /**
- * 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.
  */
 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.
+ * 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'`).
  */
 declare function isDuplicateKeyError(error: unknown): error is ArcApiError;
 interface ClientConfig {
@@ -327,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.
@@ -334,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.
@@ -373,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';
 /**
@@ -505,8 +668,8 @@ declare function getClientAuthContext(client?: ArcClient): {
  * 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');
  */
 declare function handleApiRequest<T = unknown>(method: HttpMethod, endpoint: string, options?: ApiRequestOptions): Promise<T>;
 /**
@@ -526,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, 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 };
+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 };