@classytic/arc-next 0.6.0 → 0.7.0

package/dist/query.d.ts

@@ -1,5 +1,5 @@
 import { CacheUtils, DEFAULT_QUERY_CONFIG, PaginationData, QUERY_CONFIGS, QueryKeys, createCacheUtils, createQueryKeys, extractItem, extractItems, getItemId, normalizePagination, updateListCache } from "./cache.js";
-import { InfiniteData, QueryKey } from "@tanstack/react-query";
+import { InfiniteData, QueryClient, QueryKey } from "@tanstack/react-query";
 
 //#region src/query.d.ts
 /** Request-level options passed through to the fetch call */
@@ -17,6 +17,17 @@ interface ListQueryOptions<TData = unknown> {
   gcTime?: number;
   refetchOnWindowFocus?: boolean;
   structuralSharing?: boolean;
+  /**
+   * @deprecated No-op since 0.7. The old setQueryData-based prefill was
+   * removed because it (1) stored a `{ data: ... }` envelope that didn't
+   * match arc 2.13+'s raw doc wire, (2) blocked subsequent detail GETs from
+   * firing (fresh staleTime), and (3) clobbered detail responses every
+   * render due to an unstable effect dep. `useDetail` / `useDetailBySlug`
+   * now read list cache via `placeholderData` — the canonical TanStack
+   * pattern — so the GET always fires while consumers see an instant
+   * preview. Safe to remove from caller code. Retained for compile-time
+   * compatibility; will be deleted in a future major.
+   */
   prefillDetailCache?: boolean;
   refetchInterval?: number | false;
   refetchIntervalInBackground?: boolean;
@@ -65,6 +76,13 @@ interface DetailQueryResult<T> {
   isError: boolean;
   isSuccess: boolean;
   isStale: boolean;
+  /**
+   * `true` while the detail GET is in flight and the consumer is seeing a
+   * preview derived from a list cache entry (or any other `placeholderData`).
+   * Use to dim or label the preview, e.g. `<article aria-busy={isPlaceholderData}>`.
+   * Flips to `false` once the real detail payload resolves.
+   */
+  isPlaceholderData: boolean;
   error: Error | null;
   refetch: () => Promise<unknown>;
   data: unknown;
@@ -76,23 +94,52 @@ interface CreateListQueryConfig {
   }) => Promise<unknown>;
   enabled?: boolean;
   options?: Record<string, unknown>;
-  prefillDetailCache?: boolean;
-  detailKeyBuilder?: (id: string) => QueryKey;
-  /** Custom ID extractor for cache prefill. Falls back to getItemId (_id → id). */
-  itemIdResolver?: (item: unknown) => string | null;
   select?: (data: unknown) => unknown;
 }
+/**
+ * List query hook. Returns the canonical `{ items, pagination, ... }` shape
+ * derived from arc's `PaginatedResult` wire envelope.
+ *
+ * **No detail-cache prefill.** Older revisions of this hook wrote each list
+ * item into the detail cache via `setQueryData`. That pattern was wrong on
+ * three counts: (1) it stored a `{ data: ... }` envelope that didn't match
+ * arc 2.13+'s raw doc wire shape, (2) the fresh-default `staleTime` made
+ * subsequent `useDetail` calls reuse the partial list payload and never fetch
+ * the rich detail response, and (3) the unstable `detailKeyBuilder` ref made
+ * the prefill effect re-run on every render, clobbering successful detail
+ * fetches. The clean fix is on the read side: `useDetail` now reads list cache
+ * directly via `placeholderData`, so the detail GET still fires while the
+ * consumer sees an instant list-shaped preview. See `findItemInListCache`.
+ */
 declare function useListQuery<T>({
   queryKey,
   queryFn,
   enabled,
   options,
-  prefillDetailCache,
-  detailKeyBuilder,
-  itemIdResolver,
   select
 }: CreateListQueryConfig): ListQueryResult<T>;
-interface CreateDetailQueryConfig {
+/**
+ * Find an item in any list cache for this entity by ID.
+ *
+ * Walks every `[entity, 'list', ...]` query (including scoped variants and
+ * infinite-list page arrays) and extracts items via the permissive list
+ * detector. Returns the first match — list payloads are subsets of detail
+ * payloads, so the consumer sees an instant preview while the real detail
+ * GET runs in the background.
+ *
+ * This is the canonical TanStack pattern for "show list data while fetching
+ * detail": pass the returned value as `placeholderData` to `useDetail`. The
+ * value isn't persisted to the detail cache (no pollution), `staleTime`
+ * doesn't apply to it (always refetches), and `isPlaceholderData` is `true`
+ * until the GET resolves.
+ *
+ * @param qc TanStack QueryClient (typically from `useQueryClient()`)
+ * @param listsKey Prefix key for this entity's lists (e.g. `KEYS.lists()`)
+ * @param id Item ID being requested
+ * @param idField Optional custom ID field (matches `createCrudHooks({ idField })`)
+ */
+declare function findItemInListCache<T>(qc: QueryClient, listsKey: QueryKey, id: string, idField?: string): T | undefined;
+interface CreateDetailQueryConfig<T = unknown> {
   queryKey: QueryKey;
   queryFn: (context: {
     signal?: AbortSignal;
@@ -100,14 +147,22 @@ interface CreateDetailQueryConfig {
   enabled?: boolean;
   options?: Record<string, unknown>;
   select?: (data: unknown) => unknown;
+  /**
+   * Lazy placeholder. Returns a value (or `undefined`) on each render to show
+   * before the detail GET resolves. Use with `findItemInListCache` to derive
+   * an instant preview from list cache without polluting the detail cache —
+   * the canonical TanStack pattern for "show list data while fetching detail."
+   */
+  placeholderData?: () => T | undefined;
 }
 declare function useDetailQuery<T>({
   queryKey,
   queryFn,
   enabled,
   options,
-  select
-}: CreateDetailQueryConfig): DetailQueryResult<T>;
+  select,
+  placeholderData
+}: CreateDetailQueryConfig<T>): DetailQueryResult<T>;
 interface InfiniteListQueryOptions {
   public?: boolean;
   enabled?: boolean;
@@ -250,4 +305,4 @@ declare function useApiQuery<TResponse = unknown, TData = ExtractData<TResponse>
   options
 }: UseApiQueryConfig<TResponse, TData>): UseApiQueryResult<TData>;
 //#endregion
-export { type CacheUtils, CreateDetailQueryConfig, CreateInfiniteListQueryConfig, CreateListQueryConfig, DEFAULT_QUERY_CONFIG, DetailQueryOptions, DetailQueryResult, ExtractData, InfiniteListQueryOptions, InfiniteListQueryResult, ListQueryOptions, ListQueryResult, type PaginationData, QUERY_CONFIGS, QueryFreshness, type QueryKeys, RequestPassthrough, UseApiQueryConfig, UseApiQueryOptions, UseApiQueryResult, createCacheUtils, createQueryKeys, extractItem, extractItems, getItemId, normalizePagination, updateListCache, useApiQuery, useDetailQuery, useInfiniteListQuery, useListQuery };
+export { type CacheUtils, CreateDetailQueryConfig, CreateInfiniteListQueryConfig, CreateListQueryConfig, DEFAULT_QUERY_CONFIG, DetailQueryOptions, DetailQueryResult, ExtractData, InfiniteListQueryOptions, InfiniteListQueryResult, ListQueryOptions, ListQueryResult, type PaginationData, QUERY_CONFIGS, QueryFreshness, type QueryKeys, RequestPassthrough, UseApiQueryConfig, UseApiQueryOptions, UseApiQueryResult, createCacheUtils, createQueryKeys, extractItem, extractItems, findItemInListCache, getItemId, normalizePagination, updateListCache, useApiQuery, useDetailQuery, useInfiniteListQuery, useListQuery };

package/dist/query.js

@@ -1,12 +1,26 @@
 "use client";
 
 import { DEFAULT_QUERY_CONFIG, QUERY_CONFIGS, createCacheUtils, createQueryKeys, extractItem, extractItems, getItemId, normalizePagination, updateListCache } from "./cache.js";
-import { keepPreviousData, useInfiniteQuery, useQuery, useQueryClient } from "@tanstack/react-query";
-import { useCallback, useEffect, useMemo, useRef } from "react";
+import { keepPreviousData, useInfiniteQuery, useQuery } from "@tanstack/react-query";
+import { useCallback, useMemo, useRef } from "react";
 
 //#region src/query.ts
-function useListQuery({ queryKey, queryFn, enabled = true, options = {}, prefillDetailCache = true, detailKeyBuilder, itemIdResolver, select }) {
-	const queryClient = useQueryClient();
+/**
+* List query hook. Returns the canonical `{ items, pagination, ... }` shape
+* derived from arc's `PaginatedResult` wire envelope.
+*
+* **No detail-cache prefill.** Older revisions of this hook wrote each list
+* item into the detail cache via `setQueryData`. That pattern was wrong on
+* three counts: (1) it stored a `{ data: ... }` envelope that didn't match
+* arc 2.13+'s raw doc wire shape, (2) the fresh-default `staleTime` made
+* subsequent `useDetail` calls reuse the partial list payload and never fetch
+* the rich detail response, and (3) the unstable `detailKeyBuilder` ref made
+* the prefill effect re-run on every render, clobbering successful detail
+* fetches. The clean fix is on the read side: `useDetail` now reads list cache
+* directly via `placeholderData`, so the detail GET still fires while the
+* consumer sees an instant list-shaped preview. See `findItemInListCache`.
+*/
+function useListQuery({ queryKey, queryFn, enabled = true, options = {}, select }) {
 	const query = useQuery({
 		queryKey,
 		queryFn: ({ signal }) => queryFn({ signal }),
@@ -16,24 +30,9 @@ function useListQuery({ queryKey, queryFn, enabled = true, options = {}, prefill
 		...select ? { select } : {},
 		placeholderData: keepPreviousData
 	});
-	const items = useMemo(() => extractItems(query.data), [query.data]);
-	const pagination = useMemo(() => normalizePagination(query.data), [query.data]);
-	useEffect(() => {
-		if (!prefillDetailCache || !detailKeyBuilder || items.length === 0) return;
-		const resolveId = itemIdResolver ?? getItemId;
-		items.forEach((item) => {
-			const id = resolveId(item);
-			if (id) queryClient.setQueryData(detailKeyBuilder(id), { data: item });
-		});
-	}, [
-		items,
-		prefillDetailCache,
-		detailKeyBuilder,
-		queryClient
-	]);
 	return {
-		items,
-		pagination,
+		items: useMemo(() => extractItems(query.data), [query.data]),
+		pagination: useMemo(() => normalizePagination(query.data), [query.data]),
 		isLoading: query.isLoading,
 		isFetching: query.isFetching,
 		isError: query.isError,
@@ -44,14 +43,50 @@ function useListQuery({ queryKey, queryFn, enabled = true, options = {}, prefill
 		data: query.data
 	};
 }
-function useDetailQuery({ queryKey, queryFn, enabled = true, options = {}, select }) {
+/**
+* Find an item in any list cache for this entity by ID.
+*
+* Walks every `[entity, 'list', ...]` query (including scoped variants and
+* infinite-list page arrays) and extracts items via the permissive list
+* detector. Returns the first match — list payloads are subsets of detail
+* payloads, so the consumer sees an instant preview while the real detail
+* GET runs in the background.
+*
+* This is the canonical TanStack pattern for "show list data while fetching
+* detail": pass the returned value as `placeholderData` to `useDetail`. The
+* value isn't persisted to the detail cache (no pollution), `staleTime`
+* doesn't apply to it (always refetches), and `isPlaceholderData` is `true`
+* until the GET resolves.
+*
+* @param qc TanStack QueryClient (typically from `useQueryClient()`)
+* @param listsKey Prefix key for this entity's lists (e.g. `KEYS.lists()`)
+* @param id Item ID being requested
+* @param idField Optional custom ID field (matches `createCrudHooks({ idField })`)
+*/
+function findItemInListCache(qc, listsKey, id, idField) {
+	if (!id) return void 0;
+	const entries = qc.getQueriesData({ queryKey: listsKey });
+	for (const [, raw] of entries) {
+		if (!raw) continue;
+		const pages = typeof raw === "object" && raw !== null && Array.isArray(raw.pages) ? raw.pages : [raw];
+		for (const page of pages) {
+			const items = extractItems(page);
+			for (const item of items) {
+				const got = idField ? item?.[idField] : getItemId(item);
+				if (got != null && String(got) === id) return item;
+			}
+		}
+	}
+}
+function useDetailQuery({ queryKey, queryFn, enabled = true, options = {}, select, placeholderData }) {
 	const query = useQuery({
 		queryKey,
 		queryFn: ({ signal }) => queryFn({ signal }),
 		enabled,
 		...DEFAULT_QUERY_CONFIG,
 		...options,
-		...select ? { select } : {}
+		...select ? { select } : {},
+		...placeholderData ? { placeholderData } : {}
 	});
 	return {
 		item: extractItem(query.data),
@@ -60,6 +95,7 @@ function useDetailQuery({ queryKey, queryFn, enabled = true, options = {}, selec
 		isError: query.isError,
 		isSuccess: query.isSuccess,
 		isStale: query.isStale,
+		isPlaceholderData: query.isPlaceholderData,
 		error: query.error,
 		refetch: query.refetch,
 		data: query.data
@@ -155,4 +191,4 @@ function useApiQuery({ queryKey, queryFn, enabled = true, freshness, select, opt
 }
 
 //#endregion
-export { DEFAULT_QUERY_CONFIG, QUERY_CONFIGS, createCacheUtils, createQueryKeys, extractItem, extractItems, getItemId, normalizePagination, updateListCache, useApiQuery, useDetailQuery, useInfiniteListQuery, useListQuery };
+export { DEFAULT_QUERY_CONFIG, QUERY_CONFIGS, createCacheUtils, createQueryKeys, extractItem, extractItems, findItemInListCache, getItemId, normalizePagination, updateListCache, useApiQuery, useDetailQuery, useInfiniteListQuery, useListQuery };

package/dist/sse.js

@@ -1,6 +1,6 @@
 "use client";
 
-import { buildStreamUrl, getAuthMode } from "./client.js";
+import { ArcApiError, _getAuthErrorHandler, _runAuthRecovery, buildStreamUrl, getAuthMode } from "./client.js";
 import { useQueryClient } from "@tanstack/react-query";
 import { useEffect, useMemo, useRef, useState } from "react";
 
@@ -21,6 +21,35 @@ function buildSseUrl(path, params = {}) {
 	return buildStreamUrl(path, params, "http");
 }
 /**
+* Send a minimal HEAD/GET probe to the SSE URL to classify an EventSource
+* failure as either an auth failure (401, or 403 when `retryOn403`) or
+* something transient (network, 5xx, CORS). EventSource itself doesn't
+* expose status codes — this is the only cross-browser way to route SSE
+* close events through `onAuthError`.
+*
+* The probe uses HEAD when supported (cheaper); falls back to GET with
+* `Range: bytes=0-0` for servers that 405 on HEAD. Either way, the body
+* is never read — only the status code matters.
+*/
+async function probeForAuthFailure(url, retryOn403) {
+	try {
+		let res = await fetch(url, {
+			method: "HEAD",
+			credentials: "include"
+		});
+		if (res.status === 405) res = await fetch(url, {
+			method: "GET",
+			credentials: "include",
+			headers: { Range: "bytes=0-0" }
+		});
+		if (res.status === 401) return "auth-failure";
+		if (retryOn403 && res.status === 403) return "auth-failure";
+		return "not-auth";
+	} catch {
+		return "not-auth";
+	}
+}
+/**
 * Subscribe to an Arc SSE stream from any JS context (React, Node, Bun, tests).
 * Pure function — no React hook required. Returns a handle with `close()` /
 * `reconnect()` / `isConnected()`.
@@ -68,6 +97,7 @@ function subscribeToEvents(options) {
 		es = new EventSource(buildUrl(), { withCredentials: credentials });
 		es.onopen = () => {
 			reconnectAttempts = 0;
+			sseAuthRetries = 0;
 			connected = true;
 			options.onConnectionChange?.(true);
 		};
@@ -98,13 +128,49 @@ function subscribeToEvents(options) {
 			connected = false;
 			options.onConnectionChange?.(false);
 			if (manualClose) return;
-			if (reconnectAttempts < maxReconnectAttempts) {
-				reconnectAttempts += 1;
-				const delay = Math.min(reconnectDelay * Math.pow(1.5, reconnectAttempts - 1), 3e4);
-				reconnectTimer = setTimeout(connect, delay);
+			const { handler, retryOn403, maxAuthRetries } = _getAuthErrorHandler();
+			if (handler && sseAuthRetries < maxAuthRetries) {
+				sseAuthRetries += 1;
+				probeForAuthFailure(buildUrl(), retryOn403).then(async (status) => {
+					if (status === "auth-failure") {
+						const { decision } = await _runAuthRecovery(handler, {
+							error: new ArcApiError("SSE pre-flight auth failure", {
+								status: 401,
+								statusText: "SSE auth failure",
+								json: { code: "arc.sse.unauthorized" },
+								endpoint: ssePath,
+								method: "GET"
+							}),
+							request: {
+								method: "GET",
+								endpoint: ssePath
+							},
+							attempt: sseAuthRetries
+						});
+						if (decision === "retry") {
+							reconnectAttempts = 0;
+							connect();
+							return;
+						}
+					}
+					scheduleReconnect();
+				}).catch(() => {
+					scheduleReconnect();
+				});
+				return;
 			}
+			scheduleReconnect();
 		};
 	};
+	/** Standard backoff-reconnect — shared between non-auth errors and skipped recoveries. */
+	const scheduleReconnect = () => {
+		if (reconnectAttempts < maxReconnectAttempts) {
+			reconnectAttempts += 1;
+			const delay = Math.min(reconnectDelay * Math.pow(1.5, reconnectAttempts - 1), 3e4);
+			reconnectTimer = setTimeout(connect, delay);
+		}
+	};
+	let sseAuthRetries = 0;
 	connect();
 	return {
 		close: () => {

package/dist/upload.js

@@ -1,4 +1,4 @@
-import { ArcApiError, getAuthMode, getBaseUrl, getClientAuthContext } from "./client.js";
+import { ArcApiError, _getAuthErrorHandler, _isAuthRecoverable, _resolveRefreshedToken, _runAuthRecovery, getAuthMode, getBaseUrl, getClientAuthContext } from "./client.js";
 import { getToastHandler } from "./mutation.js";
 import { useQueryClient } from "@tanstack/react-query";
 import { useCallback, useRef, useState } from "react";
@@ -78,7 +78,38 @@ import { useCallback, useRef, useState } from "react";
 *   onProgress: ({ percent }) => setUiProgress(percent),
 * });
 */
-function uploadWithProgress(options) {
+async function uploadWithProgress(options) {
+	const { handler, retryOn403, maxAuthRetries } = _getAuthErrorHandler();
+	if (!handler) return uploadAttempt(options);
+	let currentOptions = options;
+	for (let attempt = 0; attempt <= maxAuthRetries; attempt++) try {
+		return await uploadAttempt(currentOptions);
+	} catch (error) {
+		if (attempt >= maxAuthRetries || !_isAuthRecoverable(error, retryOn403)) throw error;
+		if (currentOptions.signal?.aborted) throw error;
+		const { decision, overrideToken } = await _runAuthRecovery(handler, {
+			error,
+			request: {
+				method: currentOptions.method ?? "POST",
+				endpoint: currentOptions.url
+			},
+			attempt: attempt + 1
+		});
+		if (decision !== "retry") throw error;
+		currentOptions = {
+			...currentOptions,
+			token: _resolveRefreshedToken(overrideToken)
+		};
+	}
+	throw new Error("arc-next: upload auth retry loop terminated without resolution");
+}
+/**
+* Single XHR attempt. Identical to the pre-0.7 body of `uploadWithProgress`
+* — extracted so the auth-retry loop above can re-run it with a refreshed
+* token without duplicating the XHR setup. All auth-recovery semantics live
+* in the outer loop; this function just performs one upload.
+*/
+function uploadAttempt(options) {
 	const { url, formData, method = "POST", onProgress, signal, client, headers: extraHeaders, elevated, idempotencyKey, responseType = "json" } = options;
 	return new Promise((resolve, reject) => {
 		if (signal?.aborted) {

package/dist/ws.js

@@ -1,6 +1,6 @@
 "use client";
 
-import { buildStreamUrl } from "./client.js";
+import { ArcApiError, _getAuthErrorHandler, _runAuthRecovery, buildStreamUrl } from "./client.js";
 import { useQueryClient } from "@tanstack/react-query";
 import { useCallback, useEffect, useMemo, useRef, useState } from "react";
 
@@ -69,9 +69,15 @@ function connectWs(options = {}) {
 		if (wildcard) for (const fn of wildcard) fn(message);
 	};
 	const connect = () => {
-		if (ws) try {
-			ws.close();
-		} catch {}
+		if (ws) {
+			ws.onclose = null;
+			ws.onerror = null;
+			ws.onmessage = null;
+			ws.onopen = null;
+			try {
+				ws.close();
+			} catch {}
+		}
 		if (heartbeatTimer) {
 			clearInterval(heartbeatTimer);
 			heartbeatTimer = null;
@@ -81,6 +87,7 @@ function connectWs(options = {}) {
 		ws = protocols !== void 0 ? new WebSocket(wsUrl, protocols) : new WebSocket(wsUrl);
 		ws.onopen = () => {
 			reconnectAttempts = 0;
+			wsAuthRetries = 0;
 			connected = true;
 			options.onConnectionChange?.(true);
 			for (const resource of subscriptions) sendRaw({
@@ -104,7 +111,7 @@ function connectWs(options = {}) {
 			dispatch(parsed);
 		};
 		ws.onerror = () => {};
-		ws.onclose = () => {
+		ws.onclose = (event) => {
 			connected = false;
 			options.onConnectionChange?.(false);
 			if (heartbeatTimer) {
@@ -112,6 +119,35 @@ function connectWs(options = {}) {
 				heartbeatTimer = null;
 			}
 			if (manualClose) return;
+			const { handler, maxAuthRetries } = _getAuthErrorHandler();
+			const isAuthClose = event.code === 1008 || event.code === 3401 || event.code === 4001 || event.code === 4401;
+			if (handler && isAuthClose && wsAuthRetries < maxAuthRetries) {
+				wsAuthRetries += 1;
+				_runAuthRecovery(handler, {
+					error: new ArcApiError(event.reason || `WebSocket closed with auth code ${event.code}`, {
+						status: 401,
+						statusText: "WebSocket auth failure",
+						json: {
+							code: "arc.websocket.unauthorized",
+							wsCloseCode: event.code,
+							reason: event.reason
+						},
+						endpoint: url ?? path,
+						method: "GET"
+					}),
+					request: {
+						method: "GET",
+						endpoint: url ?? path
+					},
+					attempt: wsAuthRetries
+				}).then(({ decision }) => {
+					if (decision === "retry") {
+						reconnectAttempts = 0;
+						connect();
+					}
+				}).catch(() => {});
+				return;
+			}
 			if (reconnectAttempts < maxReconnectAttempts) {
 				reconnectAttempts += 1;
 				const delay = Math.min(reconnectDelay * Math.pow(1.5, reconnectAttempts - 1), 3e4);
@@ -119,6 +155,7 @@ function connectWs(options = {}) {
 			}
 		};
 	};
+	let wsAuthRetries = 0;
 	connect();
 	return {
 		isConnected: () => connected,

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@classytic/arc-next",
-  "version": "0.6.0",
+  "version": "0.7.0",
   "description": "React + TanStack Query SDK for Arc resources",
   "type": "module",
   "sideEffects": false,
@@ -123,12 +123,17 @@
   },
   "peerDependencies": {
     "@classytic/repo-core": ">=0.4.0",
-    "@tanstack/react-query": ">=5.0.0",
+    "@tanstack/react-query": ">=5.62.0",
     "react": ">=19.0.0"
   },
+  "peerDependenciesMeta": {
+    "react": { "optional": false },
+    "@tanstack/react-query": { "optional": false },
+    "@classytic/repo-core": { "optional": false }
+  },
   "devDependencies": {
     "@classytic/dev-tools": "^0.2.0",
-    "@classytic/repo-core": "^0.4.0",
+    "@classytic/repo-core": "^0.5.0",
     "@tanstack/react-query": "^5.97.0",
     "@testing-library/jest-dom": "^6.9.1",
     "@testing-library/react": "^16.3.2",