@classytic/arc-next 0.4.0 → 0.5.0

package/dist/client.js

@@ -1,5 +1,51 @@
 //#region src/client.ts
 /**
+* Top-level error codes arc's `errorHandlerPlugin` emits on the response root
+* (`json.code`). Mirrors `statusCodeToCode()` + the special `VALIDATION_ERROR`
+* / `DUPLICATE_KEY` / `INTERNAL_ERROR` branches.
+*
+* Open via intersection with `(string & {})` so unknown codes from custom
+* `errorMappers` / `errorMap` still satisfy the type.
+*/
+/**
+* Top-level HTTP-status error codes arc's `errorHandlerPlugin` emits on
+* `json.code`. Exported as a `const` array first so callers get both
+* compile-time exhaustiveness AND runtime iteration (e.g. building a
+* client-side i18n lookup, or whitelisting which codes get retried).
+*/
+const KNOWN_TOP_LEVEL_CODES = [
+	"BAD_REQUEST",
+	"UNAUTHORIZED",
+	"FORBIDDEN",
+	"NOT_FOUND",
+	"METHOD_NOT_ALLOWED",
+	"CONFLICT",
+	"UNPROCESSABLE_ENTITY",
+	"RATE_LIMITED",
+	"INTERNAL_ERROR",
+	"BAD_GATEWAY",
+	"SERVICE_UNAVAILABLE",
+	"GATEWAY_TIMEOUT",
+	"VALIDATION_ERROR",
+	"DUPLICATE_KEY",
+	"DOMAIN_ERROR"
+];
+/**
+* Nested business-logic codes arc's mixins / preset routes / org guards emit
+* on `json.details.code`. These are distinct from the HTTP-status code above —
+* `error.code` (top-level) vs `error.detailsCode` (nested). When a route
+* returns 403 with `details.code: 'ORG_CONTEXT_REQUIRED'`, hosts read
+* `detailsCode` to disambiguate "missing org context" from "permission denied".
+*/
+const KNOWN_DETAILS_CODES = [
+	"ORG_CONTEXT_REQUIRED",
+	"ORG_ROLE_REQUIRED",
+	"OWNERSHIP_DENIED",
+	"MIXED_UPDATE_SHAPE",
+	"ALL_FIELDS_STRIPPED",
+	"BEFORE_RESTORE_HOOK_ERROR"
+];
+/**
 * Rich API error with status code, response payload, and request metadata.
 * Extends Error so existing `catch (e) { if (e instanceof Error) }` still works.
 *
@@ -28,9 +74,63 @@ var ArcApiError = class extends Error {
 		this.endpoint = options.endpoint;
 		this.method = options.method;
 	}
-	/** 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() {
+		const j = this.json;
+		return j && typeof j.code === "string" ? j.code : null;
+	}
+	/**
+	* Nested business-logic code from arc's `json.details.code` slot.
+	*
+	* Arc's preset mixins (bulk, softDelete) and org guards emit specific reason
+	* codes here — distinct from the HTTP-status `code` above. The most common
+	* is `ORG_CONTEXT_REQUIRED` (bulk operations + orgGuard reject when the
+	* caller's `request.scope.organizationId` is missing).
+	*
+	* @example
+	* if (error.detailsCode === 'ORG_CONTEXT_REQUIRED') {
+	*   alert('Configure auth before bulk operations: configureAuth({ getOrgId })');
+	* }
+	*/
+	get detailsCode() {
+		const c = this.json?.details?.code;
+		return typeof c === "string" ? c : 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() {
-		return this.json?.errors ?? null;
+		const j = this.json;
+		if (!j) return null;
+		if (j.errors && !Array.isArray(j.errors) && typeof j.errors === "object") return j.errors;
+		const errorList = Array.isArray(j.errors) ? j.errors : Array.isArray(j.details?.errors) ? j.details.errors : null;
+		if (!errorList) return null;
+		const map = {};
+		for (const item of errorList) {
+			if (!item || typeof item !== "object") continue;
+			const e = item;
+			const key = typeof e.field === "string" && e.field || typeof e.instancePath === "string" && e.instancePath.replace(/^\//, "") || typeof e.path === "string" && e.path || typeof e.params?.missingProperty === "string" && e.params.missingProperty || "";
+			if (!key) continue;
+			const msg = typeof e.message === "string" ? e.message : "Invalid value";
+			if (!(key in map)) map[key] = msg;
+		}
+		return Object.keys(map).length > 0 ? map : null;
 	}
 };
 /**
@@ -39,6 +139,84 @@ var ArcApiError = class extends Error {
 function isArcApiError(error) {
 	return error instanceof 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);
+* }
+*/
+function isAbortError(error) {
+	if (!error) return false;
+	if (typeof error !== "object") return false;
+	const e = error;
+	if (e.name === "AbortError") return true;
+	if (e.code === "ERR_ABORTED") return true;
+	return false;
+}
+/**
+* Generic check: is this an `ArcApiError` carrying a specific top-level OR
+* nested `details.code`? Matches whichever slot the code lives in — saves
+* call sites from having to know whether arc emitted it at the root or under
+* `details`.
+*
+* @example
+* if (isArcErrorCode(error, 'DUPLICATE_KEY')) showRetryUI();
+* if (isArcErrorCode(error, 'ORG_CONTEXT_REQUIRED')) promptOrgSelector();
+*/
+function isArcErrorCode(error, code) {
+	if (!isArcApiError(error)) return false;
+	return error.code === code || error.detailsCode === code;
+}
+/**
+* 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;
+* }
+*/
+function isOrgContextRequiredError(error) {
+	return isArcErrorCode(error, "ORG_CONTEXT_REQUIRED");
+}
+/**
+* Specific predicate for arc's `VALIDATION_ERROR` (Fastify AJV + Mongoose
+* ValidationError). When true, `error.fieldErrors` is populated with the
+* `{ field: message }` map.
+*/
+function isValidationError(error) {
+	return isArcErrorCode(error, "VALIDATION_ERROR");
+}
+/**
+* Specific predicate for arc's `DUPLICATE_KEY` (unique-constraint violation).
+* Arc's errorHandler classifies these uniformly across MongoDB E11000,
+* Postgres 23505, and Prisma P2002.
+*/
+function isDuplicateKeyError(error) {
+	return isArcErrorCode(error, "DUPLICATE_KEY");
+}
 let clientConfig = null;
 /**
 * Configure the API client. Call once at app init before any API requests.
@@ -64,22 +242,31 @@ function configureClient(config) {
 function getAuthMode() {
 	return clientConfig?.authMode ?? "bearer";
 }
+/** Get the configured base URL. Returns empty string if not configured. */
+function getBaseUrl() {
+	return clientConfig?.baseUrl ?? "";
+}
 /** Whether auto-idempotency is enabled on the global client. */
 function isAutoIdempotency() {
 	return clientConfig?.autoIdempotency ?? false;
 }
 let authConfig = null;
+let hasWarnedAsyncToken = false;
 /**
 * Configure auth context for automatic token/orgId injection.
 * When configured, hooks auto-inject these values so you don't need to pass them manually.
 *
 * **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,
@@ -88,40 +275,217 @@ let authConfig = null;
 function configureAuth(config) {
 	if (typeof window === "undefined") console.warn("[arc-next] configureAuth() called on the server. This sets module-level state that persists across requests. Call only in client-side code (e.g., a 'use client' provider).");
 	authConfig = config;
+	hasWarnedAsyncToken = false;
+}
+function readToken(getToken) {
+	if (!getToken) return null;
+	const result = getToken();
+	if (result && typeof result.then === "function") {
+		if (!hasWarnedAsyncToken) {
+			hasWarnedAsyncToken = true;
+			console.warn("[arc-next] configureAuth({ getToken }) returned a Promise. Tokens MUST resolve synchronously — async returns are dropped and requests will be unauthenticated. Cache your token (localStorage, memory, signal) and have getToken() return the cached value.");
+		}
+		return null;
+	}
+	return result ?? null;
 }
 /**
 * Get the current auth context. Returns nulls when not configured.
 */
 function getAuthContext() {
 	return {
-		token: authConfig?.getToken?.() ?? null,
+		token: readToken(authConfig?.getToken),
 		organizationId: authConfig?.getOrgId?.() ?? null
 	};
 }
+/** @internal — exposed for tests; resets the dev-warn dedup flag. */
+function _resetAuthWarnings() {
+	hasWarnedAsyncToken = false;
+}
+/**
+* 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.
+*/
+function buildStreamUrl(path, params = {}, protocol = "http") {
+	const auth = getAuthContext();
+	const qs = new URLSearchParams();
+	for (const [key, value] of Object.entries(params)) {
+		if (value === void 0 || value === null || value === "") continue;
+		qs.set(key, String(value));
+	}
+	if (auth.organizationId && !qs.has("organizationId")) qs.set("organizationId", auth.organizationId);
+	if (auth.token && getAuthMode() !== "cookie" && !qs.has("token")) qs.set("token", auth.token);
+	const origin = protocol === "ws" ? getBaseUrl().replace(/^http(s?):\/\//, "ws$1://") : getBaseUrl();
+	const suffix = qs.toString();
+	return `${origin}${path}${suffix ? `?${suffix}` : ""}`;
+}
 /**
 * 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 });
 */
 function createClient(config) {
-	const { toast, navigation, ...clientCfg } = config;
+	const { toast, navigation, getToken, getOrgId, headerName, ...clientCfg } = config;
+	const clientAuth = getToken || getOrgId || headerName ? {
+		getToken,
+		getOrgId,
+		headerName
+	} : void 0;
 	return {
-		request: (method, endpoint, options) => executeRequest(clientCfg, method, endpoint, options),
+		request: (method, endpoint, options) => {
+			if (clientAuth) {
+				const resolved = { ...options };
+				if (resolved.token === void 0 && clientAuth.getToken) resolved.token = readToken(clientAuth.getToken);
+				if (resolved.organizationId === void 0 && clientAuth.getOrgId) resolved.organizationId = clientAuth.getOrgId();
+				if (clientCfg.authMode === "header" && resolved.token) {
+					resolved.headerOptions = {
+						[clientAuth.headerName ?? "x-api-key"]: resolved.token,
+						...resolved.headerOptions ?? {}
+					};
+					resolved.token = void 0;
+				}
+				return executeRequest(clientCfg, method, endpoint, resolved);
+			}
+			return executeRequest(clientCfg, method, endpoint, options);
+		},
 		config: clientCfg,
 		toast,
-		navigation
+		navigation,
+		auth: clientAuth
+	};
+}
+/**
+* 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',
+* });
+*/
+function createAuthAwareClient(overrides = {}) {
+	return createClient({
+		baseUrl: overrides.baseUrl ?? getBaseUrl(),
+		authMode: overrides.authMode ?? getAuthMode(),
+		autoIdempotency: overrides.autoIdempotency ?? isAutoIdempotency(),
+		elevated: overrides.elevated ?? clientConfig?.elevated,
+		...overrides,
+		getToken: overrides.getToken ?? (() => readToken(authConfig?.getToken)),
+		getOrgId: overrides.getOrgId ?? (() => authConfig?.getOrgId?.() ?? null),
+		headerName: overrides.headerName ?? authConfig?.headerName
+	});
+}
+/**
+* Get auth context for a specific client instance, falling back to global.
+*/
+function getClientAuthContext(client) {
+	if (client?.auth) return {
+		token: readToken(client.auth.getToken) ?? readToken(authConfig?.getToken),
+		organizationId: client.auth.getOrgId?.() ?? authConfig?.getOrgId?.() ?? null
 	};
+	return getAuthContext();
+}
+/** Default retry predicate: retry on network failures and 5xx, never on Abort or 4xx. */
+function defaultShouldRetry(error) {
+	if (isAbortError(error)) return false;
+	if (isArcApiError(error)) return error.status >= 500 && error.status < 600;
+	return error instanceof Error;
+}
+/** Compute the delay in ms before the Nth retry. */
+function computeBackoff(retry, attempt) {
+	const strategy = retry.backoff ?? "exponential";
+	if (typeof strategy === "function") return Math.max(0, strategy(attempt));
+	if (strategy === "linear") return 300 * (attempt + 1);
+	return Math.min(300 * Math.pow(2, attempt), 1e4);
 }
 async function executeRequest(config, method, endpoint, options = {}) {
-	const { body, token, organizationId, revalidate, headerOptions, tags, cache, signal, idempotencyKey } = options;
+	const totalAttempts = Math.max(1, config.retry?.attempts ?? 1);
+	const shouldRetry = (() => {
+		const r = config.retry?.retryOn;
+		if (typeof r === "function") return r;
+		if (Array.isArray(r)) return (e) => isArcApiError(e) && r.includes(e.status);
+		return defaultShouldRetry;
+	})();
+	let lastError;
+	for (let attempt = 0; attempt < totalAttempts; attempt++) try {
+		return await executeAttempt(config, method, endpoint, options, attempt);
+	} catch (error) {
+		lastError = error;
+		if (attempt === totalAttempts - 1 || !shouldRetry(error)) throw error;
+		const delay = computeBackoff(config.retry ?? {}, attempt);
+		if (delay > 0) await sleepAbortable(delay, options.signal);
+	}
+	throw lastError;
+}
+/** Sleep that resolves early if the signal aborts. */
+function sleepAbortable(ms, signal) {
+	return new Promise((resolve, reject) => {
+		if (signal?.aborted) {
+			reject(Object.assign(/* @__PURE__ */ new Error("Aborted"), { name: "AbortError" }));
+			return;
+		}
+		const timer = setTimeout(() => {
+			signal?.removeEventListener("abort", onAbort);
+			resolve();
+		}, ms);
+		const onAbort = () => {
+			clearTimeout(timer);
+			reject(Object.assign(/* @__PURE__ */ new Error("Aborted"), { name: "AbortError" }));
+		};
+		signal?.addEventListener("abort", onAbort, { once: true });
+	});
+}
+/** A single fetch attempt — used by executeRequest's retry loop. */
+async function executeAttempt(config, method, endpoint, options, attempt) {
+	const { body, token, organizationId, revalidate, headerOptions, tags, cache, signal, idempotencyKey, elevated } = options;
+	const startTime = Date.now();
 	try {
 		let headers = {
 			...organizationId ? { "x-organization-id": organizationId } : {},
@@ -134,19 +498,34 @@ async function executeRequest(config, method, endpoint, options = {}) {
 		} else headers["Authorization"] = `Bearer ${token}`;
 		if (config.apiVersion) headers["Accept-Version"] = config.apiVersion;
 		if (idempotencyKey) headers["Idempotency-Key"] = idempotencyKey;
+		if (elevated ?? config.elevated ?? false) headers["x-arc-scope"] = "platform";
 		if (body !== void 0 && body !== null && !(body instanceof FormData)) headers["Content-Type"] = "application/json";
 		if (headerOptions) headers = {
 			...headers,
 			...headerOptions
 		};
 		const credentials = config.credentials ?? (config.authMode === "cookie" ? "include" : "same-origin");
+		let serializedBody = void 0;
+		if (body !== void 0 && body !== null) serializedBody = body instanceof FormData ? body : JSON.stringify(body);
+		if (config.beforeRequest) {
+			const ctx = await config.beforeRequest({
+				method,
+				endpoint,
+				headers,
+				body: serializedBody,
+				signal,
+				attempt
+			});
+			headers = ctx.headers;
+			serializedBody = ctx.body;
+		}
 		const fetchOptions = {
 			method,
 			headers,
 			credentials,
 			...signal ? { signal } : {}
 		};
-		if (body !== void 0 && body !== null) fetchOptions.body = body instanceof FormData ? body : JSON.stringify(body);
+		if (serializedBody !== void 0) fetchOptions.body = serializedBody;
 		if (cache) fetchOptions.cache = cache;
 		if (revalidate !== void 0) fetchOptions.next = {
 			...fetchOptions.next,
@@ -158,8 +537,22 @@ async function executeRequest(config, method, endpoint, options = {}) {
 		};
 		const response = await fetch(`${config.baseUrl}${endpoint}`, fetchOptions);
 		if (!response.ok) {
-			const json = await response.json().catch(() => null);
-			throw new ArcApiError(json?.message || response.statusText, {
+			let json = null;
+			let errorMessage = response.statusText;
+			try {
+				json = await response.clone().json();
+				const j = json;
+				errorMessage = typeof j?.error === "string" && j.error || typeof j?.message === "string" && j.message || response.statusText;
+			} catch {
+				try {
+					const text = await response.text();
+					if (text) {
+						json = { rawBody: text };
+						errorMessage = text.slice(0, 200) || response.statusText;
+					}
+				} catch {}
+			}
+			throw new ArcApiError(errorMessage, {
 				status: response.status,
 				statusText: response.statusText,
 				json,
@@ -187,12 +580,24 @@ async function executeRequest(config, method, endpoint, options = {}) {
 				data: await response.clone().blob(),
 				response
 			};
-		} catch {
-			data = {
-				data: await response.text(),
-				response
-			};
+		} catch (blobError) {
+			try {
+				data = {
+					data: await response.text(),
+					response
+				};
+			} catch {
+				throw new Error(`Failed to parse response body from ${method} ${endpoint}: blob error: ${blobError instanceof Error ? blobError.message : String(blobError)}`);
+			}
 		}
+		if (config.afterResponse) data = (await config.afterResponse({
+			method,
+			endpoint,
+			status: response.status,
+			body: data,
+			durationMs: Date.now() - startTime,
+			response
+		})).body;
 		return data;
 	} catch (error) {
 		if (error instanceof Error) throw error;
@@ -256,4 +661,4 @@ function createQueryString(params = {}) {
 }
 
 //#endregion
-export { ArcApiError, configureAuth, configureClient, createClient, createQueryString, getAuthContext, getAuthMode, handleApiRequest, isArcApiError, isAutoIdempotency };
+export { ArcApiError, KNOWN_DETAILS_CODES, KNOWN_TOP_LEVEL_CODES, _resetAuthWarnings, buildStreamUrl, configureAuth, configureClient, createAuthAwareClient, createClient, createQueryString, getAuthContext, getAuthMode, getBaseUrl, getClientAuthContext, handleApiRequest, isAbortError, isArcApiError, isArcErrorCode, isAutoIdempotency, isDuplicateKeyError, isOrgContextRequiredError, isValidationError };