@classytic/arc-next 0.4.1 → 0.6.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;
@@ -11,6 +13,34 @@ type UseRouterHook = () => {
     scroll?: boolean;
   }) => void;
 };
+/**
+ * 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.
+ */
+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"];
+/**
+ * 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 ArcErrorCode = (typeof KNOWN_ARC_ERROR_CODES)[number] | (string & {});
 interface ArcApiErrorOptions {
   status: number;
   statusText: string;
@@ -39,13 +69,108 @@ 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" }`) */
+  /**
+   * Canonical error code from arc's wire envelope (`json.code`).
+   *
+   * 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 === 'ORG_CONTEXT_REQUIRED') promptOrgSelector();
+   * if (error.code === 'arc.not_found') router.replace('/404');
+   * if (error.code === 'duplicate_key') showRetryAsAdmin();
+   */
+  get code(): ArcErrorCode | null;
+  /**
+   * 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 details(): readonly ErrorDetail[] | null;
+  /**
+   * Extract field-level validation errors as `{ field: message }` map.
+   *
+   * 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;
 }
 /**
  * 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 `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, 'ORG_CONTEXT_REQUIRED')) promptOrgSelector();
+ */
+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 { code: 'ORG_CONTEXT_REQUIRED', message, status: 403 }`. 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 validation failures (Fastify AJV + Mongoose
+ * ValidationError). When true, `error.fieldErrors` is populated with the
+ * `{ field: message }` map. Matches arc's `arc.validation_error` and the
+ * canonical `validation_error` from repo-core.
+ */
+declare function isValidationError(error: unknown): error is ArcApiError;
+/**
+ * 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 {
   baseUrl: string;
   internalApiKey?: string;
@@ -79,7 +204,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.
  *
@@ -104,6 +323,16 @@ 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' */
@@ -115,11 +344,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,
@@ -133,6 +366,23 @@ 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 {
@@ -155,6 +405,11 @@ 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;
@@ -198,6 +453,41 @@ interface ArcClient {
  * });
  */
 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.
  */
@@ -210,8 +500,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>;
 /**
@@ -232,4 +522,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, BlobResponse, ClientConfig, HttpMethod, TextResponse, ToastHandler, UseRouterHook, configureAuth, configureClient, createClient, createQueryString, getAuthContext, getAuthMode, getBaseUrl, getClientAuthContext, handleApiRequest, isArcApiError, isAutoIdempotency };
+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 };