@classytic/arc-next 0.6.0 → 0.7.1

package/dist/client.js

@@ -275,6 +275,23 @@ function getBaseUrl() {
 function isAutoIdempotency() {
 	return clientConfig?.autoIdempotency ?? false;
 }
+/**
+* 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.
+*/
+function hasGlobalStaticAuth() {
+	if (!clientConfig) return false;
+	if (clientConfig.authMode === "cookie") return true;
+	if (clientConfig.internalApiKey) return true;
+	if (clientConfig.defaultHeaders && Object.keys(clientConfig.defaultHeaders).length > 0) return true;
+	return false;
+}
 let authConfig = null;
 let hasWarnedAsyncToken = false;
 /**
@@ -308,7 +325,7 @@ function readToken(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.");
+			console.error(/* @__PURE__ */ new Error("[arc-next] configureAuth({ getToken }) returned a Promise. Tokens MUST resolve synchronously — async returns are dropped and every authenticated query will be silently disabled (no GET fires, isLoading:false, item:null). Fix: cache the token outside getToken (localStorage, memory, signal, useState) and have getToken() return the cached value. See README → 'Authentication'."));
 		}
 		return null;
 	}
@@ -328,6 +345,138 @@ function _resetAuthWarnings() {
 	hasWarnedAsyncToken = false;
 }
 /**
+* Shared in-flight refresh. Multiple concurrent 401s collapse onto one
+* `onAuthError` invocation — the dedup happens here. Cleared in `.finally`
+* so the NEXT 401 (after settlement) triggers a fresh recovery cycle.
+*/
+let pendingAuthRecovery = null;
+/** @internal — exposed for tests; clears the dedup so they don't bleed. */
+function _resetAuthRecovery() {
+	pendingAuthRecovery = null;
+}
+/**
+* @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).
+*/
+function _getAuthErrorHandler() {
+	return {
+		handler: authConfig?.onAuthError,
+		retryOn403: authConfig?.retryOn403 ?? false,
+		maxAuthRetries: Math.max(0, authConfig?.maxAuthRetries ?? 1)
+	};
+}
+/**
+* @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.
+*/
+function _runAuthRecovery(handler, ctx) {
+	return runAuthRecovery(handler, ctx);
+}
+/**
+* @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.
+*/
+function _resolveRefreshedToken(overrideToken) {
+	if (overrideToken !== void 0) return overrideToken;
+	return readToken(authConfig?.getToken);
+}
+/**
+* @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`).
+*/
+function _isAuthRecoverable(error, retryOn403) {
+	return isAuthRecoverable(error, retryOn403);
+}
+/** True for status codes that should trigger {@link AuthConfig.onAuthError}. */
+function isAuthRecoverable(error, retryOn403) {
+	if (!isArcApiError(error)) return false;
+	if (error.status === 401) return true;
+	if (retryOn403 && error.status === 403) return true;
+	return false;
+}
+/**
+* Run the recovery handler with concurrent-request dedup. Every concurrent
+* 401 awaits the same promise and gets the same decision + override token.
+* Cleared on settlement so a later (post-settlement) 401 starts a new cycle.
+*/
+function runAuthRecovery(handler, ctx) {
+	if (pendingAuthRecovery) return pendingAuthRecovery;
+	pendingAuthRecovery = (async () => {
+		let overrideToken = void 0;
+		const setToken = (token) => {
+			overrideToken = token;
+		};
+		return {
+			decision: await handler({
+				...ctx,
+				setToken
+			}),
+			overrideToken
+		};
+	})().finally(() => {
+		pendingAuthRecovery = null;
+	});
+	return pendingAuthRecovery;
+}
+/**
+* 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()),
+*   }),
+* });
+* ```
+*/
+function createAuthRefreshHandler(opts) {
+	return async ({ setToken }) => {
+		try {
+			const token = await opts.refresh();
+			if (token == null) return "skip";
+			setToken(token);
+			return "retry";
+		} catch (err) {
+			if (opts.onRefreshError === "throw") throw err;
+			return "skip";
+		}
+	};
+}
+/**
 * Build an auth-aware URL using the global client + auth singletons.
 *
 * Single source of truth for {@link import('./sse.js').buildSseUrl} (HTTP) and
@@ -436,16 +585,48 @@ function createClient(config) {
 * });
 */
 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
+	const { toast, navigation, getToken, getOrgId, headerName, ...overrideCfg } = overrides;
+	const authGetToken = getToken ?? (() => readToken(authConfig?.getToken));
+	const authGetOrgId = getOrgId ?? (() => authConfig?.getOrgId?.() ?? null);
+	const authHeaderName = headerName ?? authConfig?.headerName;
+	const clientAuth = {
+		getToken: authGetToken,
+		getOrgId: authGetOrgId,
+		headerName: authHeaderName
+	};
+	const resolveClientCfg = () => ({
+		baseUrl: overrideCfg.baseUrl ?? getBaseUrl(),
+		authMode: overrideCfg.authMode ?? getAuthMode(),
+		autoIdempotency: overrideCfg.autoIdempotency ?? isAutoIdempotency(),
+		elevated: overrideCfg.elevated ?? clientConfig?.elevated,
+		internalApiKey: overrideCfg.internalApiKey ?? clientConfig?.internalApiKey,
+		defaultHeaders: overrideCfg.defaultHeaders ?? clientConfig?.defaultHeaders,
+		credentials: overrideCfg.credentials ?? clientConfig?.credentials,
+		apiVersion: overrideCfg.apiVersion ?? clientConfig?.apiVersion,
+		retry: overrideCfg.retry ?? clientConfig?.retry,
+		beforeRequest: overrideCfg.beforeRequest ?? clientConfig?.beforeRequest,
+		afterResponse: overrideCfg.afterResponse ?? clientConfig?.afterResponse
 	});
+	return {
+		request: (method, endpoint, options) => {
+			const cfg = resolveClientCfg();
+			const resolved = { ...options };
+			if (resolved.token === void 0) resolved.token = readToken(authGetToken);
+			if (resolved.organizationId === void 0) resolved.organizationId = authGetOrgId();
+			if (cfg.authMode === "header" && resolved.token) {
+				resolved.headerOptions = {
+					[authHeaderName ?? "x-api-key"]: resolved.token,
+					...resolved.headerOptions ?? {}
+				};
+				resolved.token = void 0;
+			}
+			return executeRequest(cfg, method, endpoint, resolved);
+		},
+		config: resolveClientCfg(),
+		toast,
+		navigation,
+		auth: clientAuth
+	};
 }
 /**
 * Get auth context for a specific client instance, falling back to global.
@@ -470,7 +651,14 @@ function computeBackoff(retry, attempt) {
 	if (strategy === "linear") return 300 * (attempt + 1);
 	return Math.min(300 * Math.pow(2, attempt), 1e4);
 }
-async function executeRequest(config, method, endpoint, options = {}) {
+/**
+* Inner request loop — handles 5xx + network-failure backoff per
+* {@link ClientConfig.retry}. Knows nothing about 401 recovery; that's the
+* outer {@link executeRequest} wrapper. Split so the two retry families don't
+* tangle: the backoff loop has its own attempt counter and predicate, the
+* auth loop has its own cap and dedup.
+*/
+async function executeWithBackoff(config, method, endpoint, options = {}) {
 	const totalAttempts = Math.max(1, config.retry?.attempts ?? 1);
 	const shouldRetry = (() => {
 		const r = config.retry?.retryOn;
@@ -489,6 +677,47 @@ async function executeRequest(config, method, endpoint, options = {}) {
 	}
 	throw lastError;
 }
+/**
+* Top-level request entry. Wraps the 5xx-backoff loop with the 401-recovery
+* loop so the two retry families compose cleanly:
+*
+*   401 (auth) ─→ onAuthError ─→ retry with fresh token ─→ may 5xx ─→ backoff
+*
+* `maxAuthRetries` (default 1) caps the auth loop independently of the
+* backoff loop's `attempts`. AbortSignal propagates through both loops.
+*
+* The auth loop only fires when {@link AuthConfig.onAuthError} is configured —
+* apps that haven't wired a refresh handler see the original behavior (401
+* surfaces immediately, no extra round-trip).
+*/
+async function executeRequest(config, method, endpoint, options = {}) {
+	const handler = authConfig?.onAuthError;
+	if (!handler) return executeWithBackoff(config, method, endpoint, options);
+	const retryOn403 = authConfig?.retryOn403 ?? false;
+	const maxAuthRetries = Math.max(0, authConfig?.maxAuthRetries ?? 1);
+	let currentOptions = options;
+	for (let authAttempt = 0; authAttempt <= maxAuthRetries; authAttempt++) try {
+		return await executeWithBackoff(config, method, endpoint, currentOptions);
+	} catch (error) {
+		if (authAttempt >= maxAuthRetries || !isAuthRecoverable(error, retryOn403)) throw error;
+		if (currentOptions.signal?.aborted) throw error;
+		const { decision, overrideToken } = await runAuthRecovery(handler, {
+			error,
+			request: {
+				method,
+				endpoint
+			},
+			attempt: authAttempt + 1
+		});
+		if (decision !== "retry") throw error;
+		const nextToken = overrideToken !== void 0 ? overrideToken : readToken(authConfig?.getToken);
+		currentOptions = {
+			...currentOptions,
+			token: nextToken
+		};
+	}
+	throw new Error("arc-next: auth retry loop terminated without resolution");
+}
 /** Sleep that resolves early if the signal aborts. */
 function sleepAbortable(ms, signal) {
 	return new Promise((resolve, reject) => {
@@ -517,21 +746,23 @@ async function executeAttempt(config, method, endpoint, options, attempt) {
 			...config.defaultHeaders ?? {}
 		};
 		if (config.internalApiKey) headers["x-internal-api-key"] = config.internalApiKey;
-		if (token) if (config.authMode === "header") {
-			const headerName = authConfig?.headerName ?? "x-api-key";
-			headers[headerName] = token;
-		} else headers["Authorization"] = `Bearer ${token}`;
+		if (token) {
+			if (config.authMode === "header") {
+				const headerName = authConfig?.headerName ?? "x-api-key";
+				headers[headerName] = token;
+			} else if (config.authMode !== "cookie") 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 (body !== void 0 && body !== null && !isNonJsonBody(body)) 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 (body !== void 0 && body !== null) serializedBody = isNonJsonBody(body) ? body : JSON.stringify(body);
 		if (config.beforeRequest) {
 			const ctx = await config.beforeRequest({
 				method,
@@ -560,6 +791,7 @@ async function executeAttempt(config, method, endpoint, options, attempt) {
 			...fetchOptions.next,
 			tags
 		};
+		if (!/^https?:\/\//i.test(endpoint) && !config.baseUrl) throw new Error(`[arc-next] handleApiRequest(${method} ${endpoint}): baseUrl is empty. Call configureClient({ baseUrl: '...' }) BEFORE the first request. If you use createAuthAwareClient() at module top-level, make sure the Providers component runs configureClient() first (e.g. in a useState() initializer, before the children render).`);
 		const response = await fetch(`${config.baseUrl}${endpoint}`, fetchOptions);
 		if (!response.ok) {
 			let json = null;
@@ -692,6 +924,183 @@ function createQueryString(params = {}) {
 	});
 	return searchParams.toString();
 }
+/**
+* Body shapes that carry their own Content-Type and must NOT be re-serialized
+* by arc-next:
+*
+*  - `FormData` — multipart with a runtime-computed boundary.
+*  - `Blob` / `File` — carries `.type`.
+*  - `URLSearchParams` — `application/x-www-form-urlencoded`.
+*  - `ArrayBuffer` / typed arrays — raw bytes; caller controls Content-Type.
+*  - `ReadableStream` — caller controls Content-Type.
+*  - `string` — caller controls Content-Type (could be plain text, XML, etc.).
+*
+* Plain objects and arrays fall through and get `JSON.stringify`d with
+* `Content-Type: application/json`.
+*/
+function isNonJsonBody(body) {
+	if (body == null) return false;
+	if (typeof body === "string") return true;
+	if (typeof FormData !== "undefined" && body instanceof FormData) return true;
+	if (typeof Blob !== "undefined" && body instanceof Blob) return true;
+	if (typeof URLSearchParams !== "undefined" && body instanceof URLSearchParams) return true;
+	if (typeof ArrayBuffer !== "undefined" && body instanceof ArrayBuffer) return true;
+	if (typeof ArrayBuffer !== "undefined" && ArrayBuffer.isView(body)) return true;
+	if (typeof ReadableStream !== "undefined" && body instanceof ReadableStream) return true;
+	return false;
+}
+/**
+* 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',
+* });
+*/
+function arcAuthHeaders() {
+	const { token, organizationId } = getAuthContext();
+	const authMode = getAuthMode();
+	const headers = {};
+	if (token) {
+		if (authMode === "header") headers[authConfig?.headerName ?? "x-api-key"] = token;
+		else if (authMode !== "cookie") headers.Authorization = `Bearer ${token}`;
+	}
+	if (organizationId) headers["x-organization-id"] = organizationId;
+	if (clientConfig?.internalApiKey) headers["x-internal-api-key"] = clientConfig.internalApiKey;
+	return headers;
+}
+/**
+* Headers that arc-next owns and a caller must not override via
+* {@link ArcFetchOptions.headers}. Passing one of these in `options.headers`
+* is silently dropped — see the `arcFetch` JSDoc for the rationale.
+*
+* Lower-cased on lookup so case-insensitive HTTP header semantics are
+* honored (`Authorization` vs `authorization` both protected).
+*/
+const ARC_FETCH_PROTECTED_HEADERS = new Set([
+	"authorization",
+	"x-organization-id",
+	"x-internal-api-key"
+]);
+let defaultArcFetchClient = null;
+function getDefaultArcFetchClient() {
+	if (!defaultArcFetchClient) defaultArcFetchClient = createAuthAwareClient();
+	return defaultArcFetchClient;
+}
+/** @internal — tests reset the default client between cases. */
+function _resetArcFetchClient() {
+	defaultArcFetchClient = null;
+}
+/**
+* Strip protected auth headers from a caller-supplied map. Case-insensitive
+* (HTTP header names are case-insensitive). The custom-auth `headerName`
+* (when `authMode: 'header'` is configured) is computed at call time so
+* apps that reconfigure auth modes don't lose protection on the renamed
+* header.
+*/
+function sanitizeUserHeaders(headers) {
+	if (!headers) return {};
+	const customHeader = authConfig?.headerName?.toLowerCase();
+	const out = {};
+	for (const [name, value] of Object.entries(headers)) {
+		const lower = name.toLowerCase();
+		if (ARC_FETCH_PROTECTED_HEADERS.has(lower)) continue;
+		if (customHeader && lower === customHeader) continue;
+		out[name] = value;
+	}
+	return out;
+}
+/**
+* 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);
+*/
+function arcFetch(path, options = {}) {
+	const { method = "GET", body, headers, signal, elevated, idempotencyKey, revalidate, tags, cache, client } = options;
+	const transport = client ?? getDefaultArcFetchClient();
+	const apiOptions = {
+		body,
+		headerOptions: sanitizeUserHeaders(headers),
+		...signal ? { signal } : {},
+		...elevated !== void 0 ? { elevated } : {},
+		...idempotencyKey ? { idempotencyKey } : {},
+		...revalidate !== void 0 ? { revalidate } : {},
+		...tags ? { tags } : {},
+		...cache ? { cache } : {}
+	};
+	return transport.request(method, path, apiOptions);
+}
+/**
+* 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.
+*/
+const arc = {
+	get: (path, opts = {}) => arcFetch(path, {
+		...opts,
+		method: "GET"
+	}),
+	post: (path, body, opts = {}) => arcFetch(path, {
+		...opts,
+		method: "POST",
+		body
+	}),
+	put: (path, body, opts = {}) => arcFetch(path, {
+		...opts,
+		method: "PUT",
+		body
+	}),
+	patch: (path, body, opts = {}) => arcFetch(path, {
+		...opts,
+		method: "PATCH",
+		body
+	}),
+	delete: (path, opts = {}) => arcFetch(path, {
+		...opts,
+		method: "DELETE"
+	})
+};
 
 //#endregion
-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 };
+export { ArcApiError, KNOWN_ARC_ERROR_CODES, _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 };