@classytic/arc-next 0.6.0 → 0.7.0

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
@@ -470,7 +619,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 +645,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 +714,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,
@@ -692,6 +891,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 };

package/dist/hooks.js

@@ -1,9 +1,9 @@
 "use client";
 
-import { getAuthMode, getClientAuthContext } from "./client.js";
+import { getAuthMode, getClientAuthContext, hasGlobalStaticAuth } from "./client.js";
 import { isKeysetPagination, isOffsetPagination } from "./api.js";
-import { DEFAULT_QUERY_CONFIG, createCacheUtils, createQueryKeys, extractItem, getItemId, updateListCache } from "./cache.js";
-import { useDetailQuery, useInfiniteListQuery, useListQuery } from "./query.js";
+import { DEFAULT_QUERY_CONFIG, createCacheUtils, createQueryKeys, extractItem, getItemId, syncDetailToLists, updateListCache } from "./cache.js";
+import { findItemInListCache, useDetailQuery, useInfiniteListQuery, useListQuery } from "./query.js";
 import { useMutationWithTransition, useOptimisticMutation } from "./mutation.js";
 import { subscribeToEvents } from "./sse.js";
 import { connectWs } from "./ws.js";
@@ -33,8 +33,19 @@ function createCrudHooks({ api, entityKey, singular, plural, idField, defaults =
 	const pluralName = plural ?? `${singular}s`;
 	/** Resolve auth context — per-client auth takes priority over global */
 	const resolveAuth = () => getClientAuthContext(client);
-	/** Whether auth is provided via static config (headers, internalApiKey, per-client auth) — no token needed for enablement */
-	const hasStaticAuth = !!(client?.config?.defaultHeaders || client?.config?.internalApiKey || client?.auth);
+	/**
+	* Whether auth is provided via static config — no per-request token needed.
+	* Sources (in priority order):
+	*   1. Per-client `defaultHeaders` / `internalApiKey` (when `client` is passed in).
+	*   2. Per-client custom auth (e.g. `createClient({ getToken })`).
+	*   3. Global `configureClient({ internalApiKey | defaultHeaders | authMode: 'cookie' })`.
+	*
+	* Resolved lazily on every render so that an app calling `configureClient`
+	* inside a "use client" provider after factory creation still picks up the
+	* global static-auth signal — previously a global `internalApiKey` was
+	* ignored, leaving every protected query stuck in a permanently-disabled state.
+	*/
+	const resolveHasStaticAuth = () => !!(client?.config?.defaultHeaders || client?.config?.internalApiKey || client?.auth) || hasGlobalStaticAuth();
 	/** Extract ID from an item using configured idField, falling back to _id → id */
 	function resolveItemId(item) {
 		if (!item || typeof item !== "object") return null;
@@ -99,7 +110,7 @@ function createCrudHooks({ api, entityKey, singular, plural, idField, defaults =
 					...requestOpts
 				}
 			}),
-			enabled: createEnabledRule(token, queryOpts, resolveAuthMode(), hasStaticAuth),
+			enabled: createEnabledRule(token, queryOpts, resolveAuthMode(), resolveHasStaticAuth()),
 			options: {
 				staleTime: queryOpts.staleTime ?? config.staleTime,
 				gcTime: queryOpts.gcTime ?? config.gcTime,
@@ -108,9 +119,6 @@ function createCrudHooks({ api, entityKey, singular, plural, idField, defaults =
 				refetchInterval: queryOpts.refetchInterval,
 				refetchIntervalInBackground: queryOpts.refetchIntervalInBackground
 			},
-			prefillDetailCache: queryOpts.prefillDetailCache ?? true,
-			detailKeyBuilder: (id) => KEYS.scopedDetail(id, organizationId ?? null),
-			itemIdResolver: resolveItemId,
 			select: queryOpts.select
 		});
 	}
@@ -131,8 +139,11 @@ function createCrudHooks({ api, entityKey, singular, plural, idField, defaults =
 		}
 		const { organizationId, params: queryParams, request: requestOpts, ...restOptions } = options;
 		const detailKey = KEYS.scopedDetail(id || "", organizationId ?? null);
-		return useDetailQuery({
-			queryKey: queryParams ? [...detailKey, queryParams] : detailKey,
+		const fullDetailKey = queryParams ? [...detailKey, queryParams] : detailKey;
+		const queryClient = useQueryClient();
+		const listPlaceholder = useCallback(() => id ? findItemInListCache(queryClient, KEYS.lists(), id, idField) : void 0, [queryClient, id]);
+		const detailResult = useDetailQuery({
+			queryKey: fullDetailKey,
 			queryFn: ({ signal }) => api.getById({
 				id,
 				token,
@@ -143,7 +154,7 @@ function createCrudHooks({ api, entityKey, singular, plural, idField, defaults =
 					...requestOpts
 				}
 			}),
-			enabled: !!id && createEnabledRule(token, restOptions, resolveAuthMode(), hasStaticAuth),
+			enabled: !!id && createEnabledRule(token, restOptions, resolveAuthMode(), resolveHasStaticAuth()),
 			options: {
 				staleTime: restOptions.staleTime ?? config.staleTime,
 				gcTime: restOptions.gcTime ?? config.gcTime,
@@ -152,8 +163,18 @@ function createCrudHooks({ api, entityKey, singular, plural, idField, defaults =
 				refetchInterval: restOptions.refetchInterval,
 				refetchIntervalInBackground: restOptions.refetchIntervalInBackground
 			},
-			select: restOptions.select
+			select: restOptions.select,
+			placeholderData: listPlaceholder
 		});
+		useEffect(() => {
+			if (!detailResult.item || detailResult.isPlaceholderData) return;
+			syncDetailToLists(queryClient, KEYS.lists(), detailResult.item, idField ? { idField } : {});
+		}, [
+			detailResult.item,
+			detailResult.isPlaceholderData,
+			queryClient
+		]);
+		return detailResult;
 	}
 	function useActions() {
 		const queryClient = useQueryClient();
@@ -413,7 +434,7 @@ function createCrudHooks({ api, entityKey, singular, plural, idField, defaults =
 					}
 				});
 			},
-			enabled: createEnabledRule(token, queryOpts, resolveAuthMode(), hasStaticAuth),
+			enabled: createEnabledRule(token, queryOpts, resolveAuthMode(), resolveHasStaticAuth()),
 			initialPageParam: restParams.after ? restParams.after : 1,
 			getNextPageParam: (lastPage) => {
 				const page = lastPage;
@@ -498,7 +519,7 @@ function createCrudHooks({ api, entityKey, singular, plural, idField, defaults =
 					}
 				});
 			},
-			enabled: !!api.getDeleted && createEnabledRule(token, queryOpts, resolveAuthMode(), hasStaticAuth),
+			enabled: !!api.getDeleted && createEnabledRule(token, queryOpts, resolveAuthMode(), resolveHasStaticAuth()),
 			options: {
 				staleTime: queryOpts.staleTime ?? config.staleTime,
 				gcTime: queryOpts.gcTime ?? config.gcTime
@@ -512,7 +533,9 @@ function createCrudHooks({ api, entityKey, singular, plural, idField, defaults =
 		const resolvedOptions = options ?? {};
 		const organizationId = resolvedOptions.organizationId ?? auth.organizationId;
 		const { params: queryParams, request: requestOpts, ...restOptions } = resolvedOptions;
-		return useDetailQuery({
+		const queryClient = useQueryClient();
+		const listPlaceholder = useCallback(() => slug ? findItemInListCache(queryClient, KEYS.lists(), slug, "slug") : void 0, [queryClient, slug]);
+		const slugResult = useDetailQuery({
 			queryKey: queryParams ? KEYS.custom("slug", slug, queryParams) : KEYS.custom("slug", slug),
 			queryFn: ({ signal }) => {
 				if (!api.getBySlug) return Promise.reject(/* @__PURE__ */ new Error(`[arc-next] "${entityKey}" api does not define a getBySlug method`));
@@ -527,15 +550,25 @@ function createCrudHooks({ api, entityKey, singular, plural, idField, defaults =
 					}
 				});
 			},
-			enabled: !!api.getBySlug && !!slug && createEnabledRule(token, restOptions, resolveAuthMode(), hasStaticAuth),
+			enabled: !!api.getBySlug && !!slug && createEnabledRule(token, restOptions, resolveAuthMode(), resolveHasStaticAuth()),
 			options: {
 				staleTime: restOptions.staleTime ?? config.staleTime,
 				gcTime: restOptions.gcTime ?? config.gcTime,
 				refetchOnWindowFocus: restOptions.refetchOnWindowFocus ?? config.refetchOnWindowFocus,
 				structuralSharing: restOptions.structuralSharing ?? config.structuralSharing
 			},
-			select: restOptions.select
+			select: restOptions.select,
+			placeholderData: listPlaceholder
 		});
+		useEffect(() => {
+			if (!slugResult.item || slugResult.isPlaceholderData) return;
+			syncDetailToLists(queryClient, KEYS.lists(), slugResult.item, idField ? { idField } : {});
+		}, [
+			slugResult.item,
+			slugResult.isPlaceholderData,
+			queryClient
+		]);
+		return slugResult;
 	}
 	function useTree(params, options) {
 		const auth = resolveAuth();
@@ -561,7 +594,7 @@ function createCrudHooks({ api, entityKey, singular, plural, idField, defaults =
 					}
 				});
 			},
-			enabled: !!api.getTree && createEnabledRule(token, queryOpts, resolveAuthMode(), hasStaticAuth),
+			enabled: !!api.getTree && createEnabledRule(token, queryOpts, resolveAuthMode(), resolveHasStaticAuth()),
 			options: {
 				staleTime: queryOpts.staleTime ?? config.staleTime,
 				gcTime: queryOpts.gcTime ?? config.gcTime
@@ -594,14 +627,11 @@ function createCrudHooks({ api, entityKey, singular, plural, idField, defaults =
 					}
 				});
 			},
-			enabled: !!api.getChildren && !!parentId && createEnabledRule(token, queryOpts, resolveAuthMode(), hasStaticAuth),
+			enabled: !!api.getChildren && !!parentId && createEnabledRule(token, queryOpts, resolveAuthMode(), resolveHasStaticAuth()),
 			options: {
 				staleTime: queryOpts.staleTime ?? config.staleTime,
 				gcTime: queryOpts.gcTime ?? config.gcTime
 			},
-			prefillDetailCache: queryOpts.prefillDetailCache ?? true,
-			detailKeyBuilder: (id) => KEYS.scopedDetail(id, organizationId ?? null),
-			itemIdResolver: resolveItemId,
 			select: queryOpts.select
 		});
 	}
@@ -806,7 +836,7 @@ function createCrudHooks({ api, entityKey, singular, plural, idField, defaults =
 			enabled: !!name && !!api.aggregate && createEnabledRule(auth.token, {
 				public: isPublic,
 				enabled
-			}, resolveAuthMode(), hasStaticAuth),
+			}, resolveAuthMode(), resolveHasStaticAuth()),
 			staleTime,
 			gcTime,
 			refetchOnWindowFocus,
@@ -912,8 +942,8 @@ function createCrudHooks({ api, entityKey, singular, plural, idField, defaults =
 			const id = resolveItemId(item);
 			if (id) {
 				const orgId = resolveAuth().organizationId;
-				queryClient.setQueryData(KEYS.scopedDetail(id, orgId), { data: item });
-				if (orgId) queryClient.setQueryData(KEYS.detail(id), { data: item });
+				queryClient.setQueryData(KEYS.scopedDetail(id, orgId), item);
+				if (orgId) queryClient.setQueryData(KEYS.detail(id), item);
 			}
 			if (!router) return;
 			const { scroll = true, replace = false } = options;