@classytic/arc-next 0.4.1 → 0.6.0

package/dist/client.js

@@ -1,5 +1,61 @@
 //#region src/client.ts
 /**
+* 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.
+*/
+const KNOWN_ARC_ERROR_CODES = [
+	"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"
+];
+/**
 * 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 +84,71 @@ var ArcApiError = class extends Error {
 		this.endpoint = options.endpoint;
 		this.method = options.method;
 	}
-	/** 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() {
+		const j = this.json;
+		return j && typeof j.code === "string" ? j.code : 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() {
+		const j = this.json;
+		return Array.isArray(j?.details) ? j.details : 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() {
-		return this.json?.errors ?? null;
+		const j = this.json;
+		if (!j) return null;
+		if (Array.isArray(j.details) && j.details.length > 0) {
+			const map = {};
+			for (const d of j.details) {
+				if (!d || typeof d !== "object") continue;
+				const key = typeof d.path === "string" ? d.path : "";
+				const msg = typeof d.message === "string" ? d.message : "Invalid value";
+				if (key && !(key in map)) map[key] = msg;
+			}
+			if (Object.keys(map).length > 0) return map;
+		}
+		if (j.errors && !Array.isArray(j.errors) && typeof j.errors === "object") return j.errors;
+		const detailsObj = j.details;
+		const errorList = Array.isArray(j.errors) ? j.errors : Array.isArray(detailsObj?.errors) ? detailsObj.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 +157,91 @@ 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 `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();
+*/
+function isArcErrorCode(error, code) {
+	return isArcApiError(error) && error.code === 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 { 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;
+* }
+*/
+function isOrgContextRequiredError(error) {
+	return isArcErrorCode(error, "ORG_CONTEXT_REQUIRED");
+}
+/**
+* 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.
+*/
+function isValidationError(error) {
+	if (!isArcApiError(error)) return false;
+	return error.code === "arc.validation_error" || error.code === "validation_error";
+}
+/**
+* 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'`).
+*/
+function isDuplicateKeyError(error) {
+	if (!isArcApiError(error)) return false;
+	if (error.code === "arc.conflict" || error.code === "duplicate_key" || error.code === "conflict") {
+		if (error.code === "arc.conflict") return error.details?.some((d) => d.code === "duplicate_key") ?? false;
+		return true;
+	}
+	return false;
+}
 let clientConfig = null;
 /**
 * Configure the API client. Call once at app init before any API requests.
@@ -73,17 +276,22 @@ 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,
@@ -92,16 +300,58 @@ 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 with different auth.
@@ -132,7 +382,7 @@ function createClient(config) {
 		request: (method, endpoint, options) => {
 			if (clientAuth) {
 				const resolved = { ...options };
-				if (resolved.token === void 0 && clientAuth.getToken) resolved.token = clientAuth.getToken();
+				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 = {
@@ -152,17 +402,115 @@ function createClient(config) {
 	};
 }
 /**
+* 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: client.auth.getToken?.() ?? authConfig?.getToken?.() ?? null,
+		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 } : {},
@@ -175,19 +523,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,
@@ -203,7 +566,8 @@ async function executeRequest(config, method, endpoint, options = {}) {
 			let errorMessage = response.statusText;
 			try {
 				json = await response.clone().json();
-				errorMessage = json?.message || response.statusText;
+				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();
@@ -251,6 +615,14 @@ async function executeRequest(config, method, endpoint, options = {}) {
 				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;
@@ -262,8 +634,8 @@ async function executeRequest(config, method, endpoint, options = {}) {
 * 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');
 */
 async function handleApiRequest(method, endpoint, options = {}) {
 	if (!clientConfig) throw new Error("arc-next: Client not configured. Call configureClient({ baseUrl }) before making API requests.");
@@ -308,10 +680,18 @@ function createQueryString(params = {}) {
 			if (value.length > 1) searchParams.append(`${key}[in]`, value.join(","));
 			else if (value.length === 1) searchParams.append(key, String(value[0]));
 		} else if (value === null) searchParams.append(key, "null");
+		else if (typeof value === "object") for (const [op, opValue] of Object.entries(value)) {
+			if (opValue === void 0 || opValue === "") continue;
+			const bracketKey = `${key}[${op}]`;
+			if (Array.isArray(opValue)) {
+				if (opValue.length > 0) searchParams.append(bracketKey, opValue.join(","));
+			} else if (opValue === null) searchParams.append(bracketKey, "null");
+			else searchParams.append(bracketKey, String(opValue));
+		}
 		else searchParams.append(key, String(value));
 	});
 	return searchParams.toString();
 }
 
 //#endregion
-export { ArcApiError, configureAuth, configureClient, createClient, createQueryString, getAuthContext, getAuthMode, getBaseUrl, getClientAuthContext, handleApiRequest, isArcApiError, isAutoIdempotency };
+export { ArcApiError, KNOWN_ARC_ERROR_CODES, _resetAuthWarnings, buildStreamUrl, configureAuth, configureClient, createAuthAwareClient, createClient, createQueryString, getAuthContext, getAuthMode, getBaseUrl, getClientAuthContext, handleApiRequest, isAbortError, isArcApiError, isArcErrorCode, isAutoIdempotency, isDuplicateKeyError, isOrgContextRequiredError, isValidationError };