@classytic/arc-next 0.4.0 → 0.4.1

package/README.md

@@ -440,34 +440,55 @@ Subscribe to Arc SSE events with auto-reconnect and query invalidation:
 ```ts
 import { useEventStream } from "@classytic/arc-next/sse";
 
-const { isConnected, lastEvent } = useEventStream({
+// Global stream — all events (matches Arc's /events/stream)
+const { isConnected } = useEventStream({
+  invalidateQueries: [agentKeys.lists()],
+});
+
+// Filtered by resource — auto-generates patterns: ['agents.*']
+const { lastEvent } = useEventStream({
   resource: "agents",
-  patterns: ["agents.created", "agents.updated"],
   invalidateQueries: [agentKeys.lists()],
 });
+
+// Custom SSE path or explicit patterns
+const { isConnected } = useEventStream({
+  path: "/api/v2/events",
+  patterns: ["orders.created", "orders.updated"],
+});
 ```
 
 ### Query Keys (`KEYS`)
 
 ```ts
-KEYS.all                          // ["products"]
-KEYS.lists()                      // ["products", "list"]
-KEYS.list(params)                 // ["products", "list", params]
-KEYS.details()                    // ["products", "detail"]
-KEYS.detail(id)                   // ["products", "detail", id]
-KEYS.custom("stats", orgId)       // ["products", "stats", orgId]
-KEYS.scopedList("tenant", params) // ["products", "list", { _scope: "tenant", ...params }]
+KEYS.all                              // ["products"]
+KEYS.lists()                          // ["products", "list"]
+KEYS.list(params)                     // ["products", "list", params]
+KEYS.details()                        // ["products", "detail"]
+KEYS.detail(id)                       // ["products", "detail", id]
+KEYS.scopedDetail(id, orgId)          // ["products", "detail", id, { _org: orgId }] (or bare when null)
+KEYS.custom("stats", orgId)           // ["products", "stats", orgId]
+KEYS.scopedList("tenant", params)     // ["products", "list", { _scope: "tenant", ...params }]
 ```
 
 ### Cache Utilities (`cache`)
 
 ```ts
-await cache.invalidateAll(queryClient);
-await cache.invalidateLists(queryClient);
-await cache.invalidateDetail(queryClient, id);
+// Bare (single-tenant or public)
 cache.setDetail(queryClient, id, data);
-cache.getDetail(queryClient, id);       // T | undefined
+cache.getDetail(queryClient, id);
 cache.removeDetail(queryClient, id);
+await cache.invalidateDetail(queryClient, id);  // prefix-matches ALL scoped variants
+
+// Tenant-scoped (multi-tenant — isolated per org)
+cache.setScopedDetail(queryClient, id, orgId, data);
+cache.getScopedDetail(queryClient, id, orgId);
+cache.removeScopedDetail(queryClient, id, orgId);
+await cache.invalidateScopedDetail(queryClient, id, orgId);
+
+// Global
+await cache.invalidateAll(queryClient);
+await cache.invalidateLists(queryClient);
 ```
 
 ### `getQueryClient(overrides?)`
@@ -521,7 +542,17 @@ export default async function ProductsPage() {
 }
 ```
 
-**Methods:** `prefetchList(queryClient, params?, options?)`, `prefetchDetail(queryClient, id, options?)`
+**Methods:** `prefetchList`, `prefetchDetail`, `prefetchBySlug`, `prefetchDeleted`, `prefetchTree`
+
+All accept auth options for protected routes:
+
+```ts
+await prefetcher.prefetchList(queryClient, { limit: 20 }, {
+  token: serverToken,               // for bearer/header auth
+  organizationId: "org-1",          // for multi-tenant
+  headers: { "x-api-key": apiKey }, // for custom header auth
+});
+```
 
 ## Custom Mutations
 
@@ -620,16 +651,30 @@ By default, `configureClient()` sets a single global `baseUrl`. Use `createClien
 
 ### Create isolated clients
 
+Each client gets its own `baseUrl`, auth, and headers — fully independent from the global config:
+
 ```ts
 import { createClient } from "@classytic/arc-next/client";
-import { toast } from "sonner";
-import { useRouter } from "next/navigation";
 
+// Bearer auth for main API
+const mainClient = createClient({
+  baseUrl: "https://api.example.com",
+  getToken: () => session.jwt,
+  getOrgId: () => currentOrg.id,
+});
+
+// API key auth for analytics (no token needed — hooks auto-enable)
 const analyticsClient = createClient({
-  baseUrl: "https://analytics.example.com",
-  internalApiKey: "analytics-key",
-  toast: { success: toast.success, error: toast.error },
-  navigation: useRouter,
+  baseUrl: "https://analytics.internal",
+  authMode: "header",
+  getToken: () => env.ANALYTICS_KEY,
+  headerName: "x-analytics-key",
+});
+
+// Cookie auth for auth service
+const authClient = createClient({
+  baseUrl: "https://auth.example.com",
+  authMode: "cookie",
 });
 ```
 
@@ -763,19 +808,20 @@ const adminApi = createCrudApi("users", {
 
 - **CRUD Factory** — `createCrudApi` + `createCrudHooks` generates typed API clients and React Query hooks
 - **Optimistic Updates** — Create, update, delete with instant UI feedback and automatic rollback
-- **Multi-Tenant Scoping** — Tenant ID sent via `x-organization-id` header + scoped list query keys. Backend controls the tenant field name and access enforcement.
+- **Multi-Tenant Scoping** — `scopedDetail(id, orgId)` + `scopedList` isolate cache per tenant. Scoped cache utils for reads/writes. Navigation prefill is tenant-aware.
 - **Pagination Normalization** — Handles `docs`/`data`/`items`/`results` + any custom key, offset/keyset/aggregate pagination
 - **Detail Cache Prefilling** — List results auto-populate detail query cache
 - **React 19 Transitions** — `useMutationWithTransition` wraps invalidation in `startTransition`
 - **Cookie, Bearer & Header Auth** — `authMode: 'cookie'` / `'bearer'` / `'header'` (custom header like `x-api-key`)
 - **Custom ID Fields** — `idField` on `createCrudHooks` for resources keyed by `sku`, `slug`, `code`, etc.
 - **Preset Hooks** — `useDeleted`, `useBulkActions`, `useDetailBySlug`, `useTree`, `useChildren`, `useFindBy`
-- **SSE Real-Time** — `useEventStream` with auto-reconnect, pattern filtering, query invalidation
+- **SSE Real-Time** — `useEventStream` with auto-reconnect, auto-pattern derivation from `resource`, query invalidation. Works with zero config or custom `path`.
 - **Infinite Scroll** — `maxPages` for memory management with automatic scroll-back support
 - **Idempotency** — `autoIdempotency` generates retry-safe keys at mutation level
 - **API Versioning** — `apiVersion` sends `Accept-Version` header
 - **SSR Prefetch** — `createCrudPrefetcher` + `prefetchBySlug` / `prefetchDeleted` / `prefetchTree`
 - **SSR Safety** — warns when `configureClient`/`configureAuth` called on the server
+- **Per-Client Auth** — `createClient({ getToken, getOrgId, headerName })` — each backend gets its own auth, queries auto-enable
 - **Multi-Client** — `createClient()` for multiple API backends side by side
 - **Pluggable Toast** — `configureToast()` — use sonner, react-hot-toast, or anything
 - **Pluggable Navigation** — `configureNavigation()` — use Next.js, React Router, or any router

package/dist/api.d.ts

@@ -232,7 +232,7 @@ declare class BaseApi<TDoc = Record<string, unknown>, TCreate = Partial<TDoc>, T
     params,
     options
   }?: {
-    token?: string;
+    token?: string | null;
     organizationId?: string | null;
     data?: unknown;
     params?: QueryParams;

package/dist/api.js

@@ -96,7 +96,7 @@ var BaseApi = class {
 		if (organizationId) requestOptions.organizationId = organizationId;
 		return this.requestFn("GET", url, this.withHeaders(requestOptions));
 	}
-	async create({ token, organizationId = null, data, options = {} }) {
+	async create({ token = null, organizationId = null, data, options = {} }) {
 		const requestOptions = {
 			body: data,
 			...options
@@ -105,7 +105,7 @@ var BaseApi = class {
 		if (organizationId) requestOptions.organizationId = organizationId;
 		return this.requestFn("POST", this.baseUrl, this.withHeaders(requestOptions));
 	}
-	async update({ token, organizationId = null, id, data, options = {} }) {
+	async update({ token = null, organizationId = null, id, data, options = {} }) {
 		if (!id) throw new Error("ID is required");
 		const requestOptions = {
 			body: data,
@@ -115,14 +115,14 @@ var BaseApi = class {
 		if (organizationId) requestOptions.organizationId = organizationId;
 		return this.requestFn("PATCH", `${this.baseUrl}/${id}`, this.withHeaders(requestOptions));
 	}
-	async delete({ token, organizationId = null, id, options = {} }) {
+	async delete({ token = null, organizationId = null, id, options = {} }) {
 		if (!id) throw new Error("ID is required");
 		const requestOptions = { ...options };
 		if (token) requestOptions.token = token;
 		if (organizationId) requestOptions.organizationId = organizationId;
 		return this.requestFn("DELETE", `${this.baseUrl}/${id}`, this.withHeaders(requestOptions));
 	}
-	async upload({ token, organizationId = null, data, id, path, options = {} }) {
+	async upload({ token = null, organizationId = null, data, id, path, options = {} }) {
 		const suffix = path ?? (id ? `${id}/upload` : void 0);
 		const url = suffix ? `${this.baseUrl}/${suffix}` : this.baseUrl;
 		const requestOptions = {
@@ -167,7 +167,7 @@ var BaseApi = class {
 		if (organizationId) requestOptions.organizationId = organizationId;
 		return this.requestFn("GET", `${this.baseUrl}?${queryString}`, this.withHeaders(requestOptions));
 	}
-	async request(method, endpoint, { token, organizationId = null, data, params, options = {} } = {}) {
+	async request(method, endpoint, { token = null, organizationId = null, data, params, options = {} } = {}) {
 		let url = endpoint;
 		if (params) {
 			const processedParams = this.prepareParams(params);
@@ -197,14 +197,14 @@ var BaseApi = class {
 		if (organizationId) requestOptions.organizationId = organizationId;
 		return this.requestFn("GET", `${this.baseUrl}/deleted?${queryString}`, this.withHeaders(requestOptions));
 	}
-	async restore({ token, organizationId = null, id, options = {} }) {
+	async restore({ token = null, organizationId = null, id, options = {} }) {
 		if (!id) throw new Error("ID is required");
 		const requestOptions = { ...options };
 		if (token) requestOptions.token = token;
 		if (organizationId) requestOptions.organizationId = organizationId;
 		return this.requestFn("POST", `${this.baseUrl}/${id}/restore`, this.withHeaders(requestOptions));
 	}
-	async bulkCreate({ token, organizationId = null, data, options = {} }) {
+	async bulkCreate({ token = null, organizationId = null, data, options = {} }) {
 		const requestOptions = {
 			body: data,
 			...options
@@ -213,7 +213,7 @@ var BaseApi = class {
 		if (organizationId) requestOptions.organizationId = organizationId;
 		return this.requestFn("POST", `${this.baseUrl}/bulk`, this.withHeaders(requestOptions));
 	}
-	async bulkUpdate({ token, organizationId = null, filter, data, options = {} }) {
+	async bulkUpdate({ token = null, organizationId = null, filter, data, options = {} }) {
 		const requestOptions = {
 			body: {
 				filter,
@@ -225,7 +225,7 @@ var BaseApi = class {
 		if (organizationId) requestOptions.organizationId = organizationId;
 		return this.requestFn("PATCH", `${this.baseUrl}/bulk`, this.withHeaders(requestOptions));
 	}
-	async bulkDelete({ token, organizationId = null, filter, options = {} }) {
+	async bulkDelete({ token = null, organizationId = null, filter, options = {} }) {
 		const requestOptions = {
 			body: { filter },
 			...options

package/dist/client.d.ts

@@ -99,6 +99,8 @@ declare function configureClient(config: ClientConfig): void;
  * Get the configured auth mode. Returns 'bearer' if not configured.
  */
 declare function getAuthMode(): 'bearer' | 'cookie' | 'header';
+/** Get the configured base URL. Returns empty string if not configured. */
+declare function getBaseUrl(): string;
 /** Whether auto-idempotency is enabled on the global client. */
 declare function isAutoIdempotency(): boolean;
 interface AuthConfig {
@@ -132,6 +134,16 @@ declare function getAuthContext(): {
   organizationId: string | null;
 };
 type HttpMethod = 'GET' | 'POST' | 'PATCH' | 'PUT' | 'DELETE';
+/** Returned by `handleApiRequest` for PDF, image, and CSV responses. */
+interface BlobResponse {
+  data: Blob;
+  response: Response;
+}
+/** Returned by `handleApiRequest` for text/plain and text/html responses. */
+interface TextResponse {
+  data: string;
+  response: Response;
+}
 interface ApiRequestOptions {
   body?: unknown;
   token?: string | null;
@@ -147,27 +159,52 @@ interface ApiRequestOptions {
 interface ArcClientConfig extends ClientConfig {
   toast?: ToastHandler;
   navigation?: UseRouterHook;
+  /** Per-client token provider. Overrides global configureAuth().getToken. */
+  getToken?: () => string | null;
+  /** Per-client org ID provider. Overrides global configureAuth().getOrgId. */
+  getOrgId?: () => string | null;
+  /** Per-client custom auth header name. Used when authMode is 'header'. */
+  headerName?: string;
 }
 interface ArcClient {
   request: <T = unknown>(method: HttpMethod, endpoint: string, options?: ApiRequestOptions) => Promise<T>;
   config: ClientConfig;
   toast?: ToastHandler;
   navigation?: UseRouterHook;
+  /** Per-client auth context. Falls back to global configureAuth() when not set. */
+  auth?: {
+    getToken?: () => string | null;
+    getOrgId?: () => string | null;
+    headerName?: string;
+  };
 }
 /**
  * Create an isolated API client for a specific backend.
- * Use this when your app needs to talk to multiple APIs.
+ * Use this when your app needs to talk to multiple APIs with different auth.
  *
  * @example
+ * // Bearer auth for main API
+ * const mainClient = createClient({
+ *   baseUrl: 'https://api.example.com',
+ *   getToken: () => session.accessToken,
+ * });
+ *
+ * // API key auth for analytics
  * const analyticsClient = createClient({
  *   baseUrl: 'https://analytics.example.com',
- *   toast: { success: toast.success, error: toast.error },
- *   navigation: useRouter,
+ *   authMode: 'header',
+ *   getToken: () => env.ANALYTICS_KEY,
+ *   headerName: 'x-api-key',
  * });
- *
- * const eventsApi = createCrudApi('events', { client: analyticsClient });
  */
 declare function createClient(config: ArcClientConfig): ArcClient;
+/**
+ * Get auth context for a specific client instance, falling back to global.
+ */
+declare function getClientAuthContext(client?: ArcClient): {
+  token: string | null;
+  organizationId: string | null;
+};
 /**
  * Universal API request handler.
  * Handles JSON, binary (PDF, images), CSV, and text responses.
@@ -195,4 +232,4 @@ declare function handleApiRequest<T = unknown>(method: HttpMethod, endpoint: str
  */
 declare function createQueryString<T extends Record<string, unknown>>(params?: T): string;
 //#endregion
-export { ApiRequestOptions, ArcApiError, ArcApiErrorOptions, ArcClient, ArcClientConfig, AuthConfig, ClientConfig, HttpMethod, ToastHandler, UseRouterHook, configureAuth, configureClient, createClient, createQueryString, getAuthContext, getAuthMode, handleApiRequest, isArcApiError, isAutoIdempotency };
+export { ApiRequestOptions, ArcApiError, ArcApiErrorOptions, ArcClient, ArcClientConfig, AuthConfig, BlobResponse, ClientConfig, HttpMethod, TextResponse, ToastHandler, UseRouterHook, configureAuth, configureClient, createClient, createQueryString, getAuthContext, getAuthMode, getBaseUrl, getClientAuthContext, handleApiRequest, isArcApiError, isAutoIdempotency };

package/dist/client.js

@@ -64,6 +64,10 @@ function configureClient(config) {
 function getAuthMode() {
 	return clientConfig?.authMode ?? "bearer";
 }
+/** Get the configured base URL. Returns empty string if not configured. */
+function getBaseUrl() {
+	return clientConfig?.baseUrl ?? "";
+}
 /** Whether auto-idempotency is enabled on the global client. */
 function isAutoIdempotency() {
 	return clientConfig?.autoIdempotency ?? false;
@@ -100,25 +104,62 @@ function getAuthContext() {
 }
 /**
 * Create an isolated API client for a specific backend.
-* Use this when your app needs to talk to multiple APIs.
+* Use this when your app needs to talk to multiple APIs with different auth.
 *
 * @example
+* // Bearer auth for main API
+* const mainClient = createClient({
+*   baseUrl: 'https://api.example.com',
+*   getToken: () => session.accessToken,
+* });
+*
+* // API key auth for analytics
 * const analyticsClient = createClient({
 *   baseUrl: 'https://analytics.example.com',
-*   toast: { success: toast.success, error: toast.error },
-*   navigation: useRouter,
+*   authMode: 'header',
+*   getToken: () => env.ANALYTICS_KEY,
+*   headerName: 'x-api-key',
 * });
-*
-* const eventsApi = createCrudApi('events', { client: analyticsClient });
 */
 function createClient(config) {
-	const { toast, navigation, ...clientCfg } = config;
+	const { toast, navigation, getToken, getOrgId, headerName, ...clientCfg } = config;
+	const clientAuth = getToken || getOrgId || headerName ? {
+		getToken,
+		getOrgId,
+		headerName
+	} : void 0;
 	return {
-		request: (method, endpoint, options) => executeRequest(clientCfg, method, endpoint, options),
+		request: (method, endpoint, options) => {
+			if (clientAuth) {
+				const resolved = { ...options };
+				if (resolved.token === void 0 && clientAuth.getToken) resolved.token = clientAuth.getToken();
+				if (resolved.organizationId === void 0 && clientAuth.getOrgId) resolved.organizationId = clientAuth.getOrgId();
+				if (clientCfg.authMode === "header" && resolved.token) {
+					resolved.headerOptions = {
+						[clientAuth.headerName ?? "x-api-key"]: resolved.token,
+						...resolved.headerOptions ?? {}
+					};
+					resolved.token = void 0;
+				}
+				return executeRequest(clientCfg, method, endpoint, resolved);
+			}
+			return executeRequest(clientCfg, method, endpoint, options);
+		},
 		config: clientCfg,
 		toast,
-		navigation
+		navigation,
+		auth: clientAuth
+	};
+}
+/**
+* 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,
+		organizationId: client.auth.getOrgId?.() ?? authConfig?.getOrgId?.() ?? null
 	};
+	return getAuthContext();
 }
 async function executeRequest(config, method, endpoint, options = {}) {
 	const { body, token, organizationId, revalidate, headerOptions, tags, cache, signal, idempotencyKey } = options;
@@ -158,8 +199,21 @@ async function executeRequest(config, method, endpoint, options = {}) {
 		};
 		const response = await fetch(`${config.baseUrl}${endpoint}`, fetchOptions);
 		if (!response.ok) {
-			const json = await response.json().catch(() => null);
-			throw new ArcApiError(json?.message || response.statusText, {
+			let json = null;
+			let errorMessage = response.statusText;
+			try {
+				json = await response.clone().json();
+				errorMessage = json?.message || response.statusText;
+			} catch {
+				try {
+					const text = await response.text();
+					if (text) {
+						json = { rawBody: text };
+						errorMessage = text.slice(0, 200) || response.statusText;
+					}
+				} catch {}
+			}
+			throw new ArcApiError(errorMessage, {
 				status: response.status,
 				statusText: response.statusText,
 				json,
@@ -187,11 +241,15 @@ async function executeRequest(config, method, endpoint, options = {}) {
 				data: await response.clone().blob(),
 				response
 			};
-		} catch {
-			data = {
-				data: await response.text(),
-				response
-			};
+		} catch (blobError) {
+			try {
+				data = {
+					data: await response.text(),
+					response
+				};
+			} catch {
+				throw new Error(`Failed to parse response body from ${method} ${endpoint}: blob error: ${blobError instanceof Error ? blobError.message : String(blobError)}`);
+			}
 		}
 		return data;
 	} catch (error) {
@@ -256,4 +314,4 @@ function createQueryString(params = {}) {
 }
 
 //#endregion
-export { ArcApiError, configureAuth, configureClient, createClient, createQueryString, getAuthContext, getAuthMode, handleApiRequest, isArcApiError, isAutoIdempotency };
+export { ArcApiError, configureAuth, configureClient, createClient, createQueryString, getAuthContext, getAuthMode, getBaseUrl, getClientAuthContext, handleApiRequest, isArcApiError, isAutoIdempotency };

package/dist/hooks.d.ts

@@ -1,7 +1,7 @@
 import { ArcClient, UseRouterHook } from "./client.js";
 import { BaseApi, FilterOperator } from "./api.js";
-import { CacheUtils, DetailQueryOptions, DetailQueryResult, InfiniteListQueryOptions, InfiniteListQueryResult, ListQueryOptions, ListQueryResult, QueryKeys } from "./query.js";
 import { MutationCallbacks, MutationMessages, TransitionMutationReturn } from "./mutation.js";
+import { CacheUtils, DetailQueryOptions, DetailQueryResult, InfiniteListQueryOptions, InfiniteListQueryResult, ListQueryOptions, ListQueryResult, QueryKeys } from "./query.js";
 import { QueryKey } from "@tanstack/react-query";
 
 //#region src/hooks.d.ts

package/dist/hooks.js

@@ -1,6 +1,6 @@
 "use client";
 
-import { getAuthContext, getAuthMode } from "./client.js";
+import { getAuthMode, getClientAuthContext } from "./client.js";
 import { isKeysetPagination, isOffsetPagination } from "./api.js";
 import { DEFAULT_QUERY_CONFIG, createCacheUtils, createQueryKeys, extractItem, getItemId, updateListCache, useDetailQuery, useInfiniteListQuery, useListQuery } from "./query.js";
 import { useMutationWithTransition, useOptimisticMutation } from "./mutation.js";
@@ -21,12 +21,17 @@ let useRouterHook = null;
 function configureNavigation(hook) {
 	useRouterHook = hook;
 }
-function createEnabledRule(token, options, authMode = getAuthMode()) {
+function createEnabledRule(token, options, authMode = getAuthMode(), hasStaticAuth = false) {
 	if (authMode === "cookie" || options.public) return options.enabled ?? true;
+	if (hasStaticAuth) return options.enabled ?? true;
 	return options.enabled !== void 0 ? options.enabled && !!token : !!token;
 }
 function createCrudHooks({ api, entityKey, singular, plural, idField, defaults = {}, callbacks = {}, client }) {
 	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);
 	/** Extract ID from an item using configured idField, falling back to _id → id */
 	function resolveItemId(item) {
 		if (!item || typeof item !== "object") return null;
@@ -60,12 +65,12 @@ function createCrudHooks({ api, entityKey, singular, plural, idField, defaults =
 		let token;
 		let params;
 		let options;
-		if (tokenOrParams === null || typeof tokenOrParams === "string") {
+		if (typeof tokenOrParams === "string" || tokenOrParams === null && maybeOptions !== void 0) {
 			token = tokenOrParams;
 			params = paramsOrOptions ?? {};
 			options = maybeOptions ?? {};
 		} else {
-			const auth = getAuthContext();
+			const auth = resolveAuth();
 			token = auth.token;
 			params = tokenOrParams ?? {};
 			options = paramsOrOptions ?? {};
@@ -91,7 +96,7 @@ function createCrudHooks({ api, entityKey, singular, plural, idField, defaults =
 					...requestOpts
 				}
 			}),
-			enabled: createEnabledRule(token, queryOpts, resolveAuthMode()),
+			enabled: createEnabledRule(token, queryOpts, resolveAuthMode(), hasStaticAuth),
 			options: {
 				staleTime: queryOpts.staleTime ?? config.staleTime,
 				gcTime: queryOpts.gcTime ?? config.gcTime,
@@ -101,7 +106,7 @@ function createCrudHooks({ api, entityKey, singular, plural, idField, defaults =
 				refetchIntervalInBackground: queryOpts.refetchIntervalInBackground
 			},
 			prefillDetailCache: queryOpts.prefillDetailCache ?? true,
-			detailKeyBuilder: (id) => KEYS.detail(id),
+			detailKeyBuilder: (id) => KEYS.scopedDetail(id, organizationId ?? null),
 			itemIdResolver: resolveItemId,
 			select: queryOpts.select
 		});
@@ -109,11 +114,11 @@ function createCrudHooks({ api, entityKey, singular, plural, idField, defaults =
 	function useDetail(id, tokenOrOptions, maybeOptions) {
 		let token;
 		let options;
-		if (tokenOrOptions === null || typeof tokenOrOptions === "string") {
+		if (typeof tokenOrOptions === "string" || tokenOrOptions === null && maybeOptions !== void 0) {
 			token = tokenOrOptions;
 			options = maybeOptions ?? {};
 		} else {
-			const auth = getAuthContext();
+			const auth = resolveAuth();
 			token = auth.token;
 			options = tokenOrOptions ?? {};
 			if (auth.organizationId && !options.organizationId) options = {
@@ -122,8 +127,9 @@ 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 ? [...KEYS.detail(id || ""), queryParams] : KEYS.detail(id || ""),
+			queryKey: queryParams ? [...detailKey, queryParams] : detailKey,
 			queryFn: ({ signal }) => api.getById({
 				id,
 				token,
@@ -134,7 +140,7 @@ function createCrudHooks({ api, entityKey, singular, plural, idField, defaults =
 					...requestOpts
 				}
 			}),
-			enabled: !!id && createEnabledRule(token, restOptions, resolveAuthMode()),
+			enabled: !!id && createEnabledRule(token, restOptions, resolveAuthMode(), hasStaticAuth),
 			options: {
 				staleTime: restOptions.staleTime ?? config.staleTime,
 				gcTime: restOptions.gcTime ?? config.gcTime,
@@ -197,13 +203,16 @@ function createCrudHooks({ api, entityKey, singular, plural, idField, defaults =
 					...item,
 					...data
 				} : item));
-				queryClient.setQueryData(KEYS.detail(id), (current) => current ? {
+				const detailUpdater = (current) => current ? {
 					...current,
 					data: {
 						...current.data || {},
 						...data
 					}
-				} : current);
+				} : current;
+				queryClient.getQueriesData({ queryKey: KEYS.detail(id) }).forEach(([qKey, qData]) => {
+					if (qData) queryClient.setQueryData(qKey, detailUpdater);
+				});
 				return updated;
 			},
 			onSuccess: (raw, { id, data: updateData }) => {
@@ -276,8 +285,8 @@ function createCrudHooks({ api, entityKey, singular, plural, idField, defaults =
 			},
 			toastHandler: instanceToast
 		});
-		const resolveAuth = useCallback((params) => {
-			const auth = getAuthContext();
+		const resolveActionAuth = useCallback((params) => {
+			const auth = resolveAuth();
 			return {
 				...params,
 				token: params.token ?? auth.token,
@@ -288,7 +297,7 @@ function createCrudHooks({ api, entityKey, singular, plural, idField, defaults =
 			create: useCallback(async (params, options) => {
 				silentRef.current = options?.silent ?? false;
 				try {
-					const entity = extractItem(await createMutation.mutateAsync(resolveAuth(params)));
+					const entity = extractItem(await createMutation.mutateAsync(resolveActionAuth(params)));
 					options?.onSuccess?.(entity);
 					options?.onSettled?.(entity, null);
 					return entity;
@@ -299,11 +308,11 @@ function createCrudHooks({ api, entityKey, singular, plural, idField, defaults =
 				} finally {
 					silentRef.current = false;
 				}
-			}, [createMutation, resolveAuth]),
+			}, [createMutation, resolveActionAuth]),
 			update: useCallback(async (params, options) => {
 				silentRef.current = options?.silent ?? false;
 				try {
-					const entity = extractItem(await updateMutation.mutateAsync(resolveAuth(params)));
+					const entity = extractItem(await updateMutation.mutateAsync(resolveActionAuth(params)));
 					options?.onSuccess?.(entity);
 					options?.onSettled?.(entity, null);
 					return entity;
@@ -314,11 +323,11 @@ function createCrudHooks({ api, entityKey, singular, plural, idField, defaults =
 				} finally {
 					silentRef.current = false;
 				}
-			}, [updateMutation, resolveAuth]),
+			}, [updateMutation, resolveActionAuth]),
 			remove: useCallback(async (params, options) => {
 				silentRef.current = options?.silent ?? false;
 				try {
-					const result = await deleteMutation.mutateAsync(resolveAuth(params));
+					const result = await deleteMutation.mutateAsync(resolveActionAuth(params));
 					options?.onSuccess?.(result);
 					options?.onSettled?.(result, null);
 					return result;
@@ -329,11 +338,11 @@ function createCrudHooks({ api, entityKey, singular, plural, idField, defaults =
 				} finally {
 					silentRef.current = false;
 				}
-			}, [deleteMutation, resolveAuth]),
+			}, [deleteMutation, resolveActionAuth]),
 			restore: useCallback(async (params, options) => {
 				silentRef.current = options?.silent ?? false;
 				try {
-					const entity = extractItem(await restoreMutation.mutateAsync(resolveAuth(params)));
+					const entity = extractItem(await restoreMutation.mutateAsync(resolveActionAuth(params)));
 					options?.onSuccess?.(entity);
 					options?.onSettled?.(entity, null);
 					return entity;
@@ -344,7 +353,7 @@ function createCrudHooks({ api, entityKey, singular, plural, idField, defaults =
 				} finally {
 					silentRef.current = false;
 				}
-			}, [restoreMutation, resolveAuth]),
+			}, [restoreMutation, resolveActionAuth]),
 			isCreating: createMutation.isPending,
 			isUpdating: updateMutation.isPending,
 			isDeleting: deleteMutation.isPending,
@@ -356,12 +365,12 @@ function createCrudHooks({ api, entityKey, singular, plural, idField, defaults =
 		let token;
 		let params;
 		let options;
-		if (tokenOrParams === null || typeof tokenOrParams === "string") {
+		if (typeof tokenOrParams === "string" || tokenOrParams === null && maybeOptions !== void 0) {
 			token = tokenOrParams;
 			params = paramsOrOptions ?? {};
 			options = maybeOptions ?? {};
 		} else {
-			const auth = getAuthContext();
+			const auth = resolveAuth();
 			token = auth.token;
 			params = tokenOrParams ?? {};
 			options = paramsOrOptions ?? {};
@@ -393,7 +402,7 @@ function createCrudHooks({ api, entityKey, singular, plural, idField, defaults =
 					}
 				});
 			},
-			enabled: createEnabledRule(token, queryOpts, resolveAuthMode()),
+			enabled: createEnabledRule(token, queryOpts, resolveAuthMode(), hasStaticAuth),
 			initialPageParam: restParams.after ? restParams.after : 1,
 			getNextPageParam: (lastPage) => {
 				const page = lastPage;
@@ -423,7 +432,7 @@ function createCrudHooks({ api, entityKey, singular, plural, idField, defaults =
 		return useMutationWithTransition({
 			mutationFn: ({ data, id, path }) => {
 				if (!api.upload) return Promise.reject(/* @__PURE__ */ new Error(`[arc-next] "${entityKey}" api does not define an upload method`));
-				const auth = getAuthContext();
+				const auth = resolveAuth();
 				return api.upload({
 					token: auth.token,
 					organizationId: auth.organizationId,
@@ -444,7 +453,7 @@ function createCrudHooks({ api, entityKey, singular, plural, idField, defaults =
 		});
 	}
 	function useSearch(query, params, options) {
-		const auth = getAuthContext();
+		const auth = resolveAuth();
 		const token = params?.token ?? auth.token;
 		const organizationId = params?.organizationId ?? auth.organizationId;
 		const { organizationId: _, token: _t, ...restParams } = params ?? {};
@@ -475,7 +484,7 @@ function createCrudHooks({ api, entityKey, singular, plural, idField, defaults =
 					}
 				});
 			},
-			enabled: !!api.search && query.length > 0 && createEnabledRule(token, queryOpts, resolveAuthMode()),
+			enabled: !!api.search && query.length > 0 && createEnabledRule(token, queryOpts, resolveAuthMode(), hasStaticAuth),
 			options: {
 				staleTime: queryOpts.staleTime ?? config.staleTime,
 				gcTime: queryOpts.gcTime ?? config.gcTime
@@ -495,7 +504,7 @@ function createCrudHooks({ api, entityKey, singular, plural, idField, defaults =
 		});
 	}
 	function useDeleted(params, options) {
-		const auth = getAuthContext();
+		const auth = resolveAuth();
 		const token = auth.token;
 		const mergedParams = params ?? {};
 		const organizationId = mergedParams.organizationId ?? auth.organizationId;
@@ -518,7 +527,7 @@ function createCrudHooks({ api, entityKey, singular, plural, idField, defaults =
 					}
 				});
 			},
-			enabled: !!api.getDeleted && createEnabledRule(token, queryOpts, resolveAuthMode()),
+			enabled: !!api.getDeleted && createEnabledRule(token, queryOpts, resolveAuthMode(), hasStaticAuth),
 			options: {
 				staleTime: queryOpts.staleTime ?? config.staleTime,
 				gcTime: queryOpts.gcTime ?? config.gcTime
@@ -527,7 +536,7 @@ function createCrudHooks({ api, entityKey, singular, plural, idField, defaults =
 		});
 	}
 	function useDetailBySlug(slug, options) {
-		const auth = getAuthContext();
+		const auth = resolveAuth();
 		const token = auth.token;
 		const resolvedOptions = options ?? {};
 		const organizationId = resolvedOptions.organizationId ?? auth.organizationId;
@@ -547,7 +556,7 @@ function createCrudHooks({ api, entityKey, singular, plural, idField, defaults =
 					}
 				});
 			},
-			enabled: !!api.getBySlug && !!slug && createEnabledRule(token, restOptions, resolveAuthMode()),
+			enabled: !!api.getBySlug && !!slug && createEnabledRule(token, restOptions, resolveAuthMode(), hasStaticAuth),
 			options: {
 				staleTime: restOptions.staleTime ?? config.staleTime,
 				gcTime: restOptions.gcTime ?? config.gcTime,
@@ -558,7 +567,7 @@ function createCrudHooks({ api, entityKey, singular, plural, idField, defaults =
 		});
 	}
 	function useTree(params, options) {
-		const auth = getAuthContext();
+		const auth = resolveAuth();
 		const token = auth.token;
 		const mergedParams = params ?? {};
 		const organizationId = mergedParams.organizationId ?? auth.organizationId;
@@ -581,7 +590,7 @@ function createCrudHooks({ api, entityKey, singular, plural, idField, defaults =
 					}
 				});
 			},
-			enabled: !!api.getTree && createEnabledRule(token, queryOpts, resolveAuthMode()),
+			enabled: !!api.getTree && createEnabledRule(token, queryOpts, resolveAuthMode(), hasStaticAuth),
 			options: {
 				staleTime: queryOpts.staleTime ?? config.staleTime,
 				gcTime: queryOpts.gcTime ?? config.gcTime
@@ -590,7 +599,7 @@ function createCrudHooks({ api, entityKey, singular, plural, idField, defaults =
 		});
 	}
 	function useChildren(parentId, params, options) {
-		const auth = getAuthContext();
+		const auth = resolveAuth();
 		const token = auth.token;
 		const mergedParams = params ?? {};
 		const organizationId = mergedParams.organizationId ?? auth.organizationId;
@@ -614,24 +623,29 @@ function createCrudHooks({ api, entityKey, singular, plural, idField, defaults =
 					}
 				});
 			},
-			enabled: !!api.getChildren && !!parentId && createEnabledRule(token, queryOpts, resolveAuthMode()),
+			enabled: !!api.getChildren && !!parentId && createEnabledRule(token, queryOpts, resolveAuthMode(), hasStaticAuth),
 			options: {
 				staleTime: queryOpts.staleTime ?? config.staleTime,
 				gcTime: queryOpts.gcTime ?? config.gcTime
 			},
 			prefillDetailCache: queryOpts.prefillDetailCache ?? true,
-			detailKeyBuilder: (id) => KEYS.detail(id),
+			detailKeyBuilder: (id) => KEYS.scopedDetail(id, organizationId ?? null),
 			itemIdResolver: resolveItemId,
 			select: queryOpts.select
 		});
 	}
 	function useFindBy(field, value, options) {
-		const auth = getAuthContext();
+		const auth = resolveAuth();
 		const token = auth.token;
 		const organizationId = auth.organizationId;
 		const { operator, request: requestOpts, ...queryOpts } = options ?? {};
 		return useListQuery({
-			queryKey: KEYS.custom("findBy", field, value, operator),
+			queryKey: KEYS.custom("findBy", {
+				field,
+				value,
+				operator,
+				organizationId
+			}),
 			queryFn: ({ signal }) => {
 				if (!api.findBy) return Promise.reject(/* @__PURE__ */ new Error(`[arc-next] "${entityKey}" api does not define a findBy method`));
 				return api.findBy({
@@ -646,13 +660,13 @@ function createCrudHooks({ api, entityKey, singular, plural, idField, defaults =
 					}
 				});
 			},
-			enabled: !!api.findBy && value !== void 0 && value !== null && createEnabledRule(token, queryOpts, resolveAuthMode()),
+			enabled: !!api.findBy && value !== void 0 && value !== null && createEnabledRule(token, queryOpts, resolveAuthMode(), hasStaticAuth),
 			options: {
 				staleTime: queryOpts.staleTime ?? config.staleTime,
 				gcTime: queryOpts.gcTime ?? config.gcTime
 			},
 			prefillDetailCache: queryOpts.prefillDetailCache ?? true,
-			detailKeyBuilder: (id) => KEYS.detail(id),
+			detailKeyBuilder: (id) => KEYS.scopedDetail(id, organizationId ?? null),
 			itemIdResolver: resolveItemId,
 			select: queryOpts.select
 		});
@@ -661,7 +675,7 @@ function createCrudHooks({ api, entityKey, singular, plural, idField, defaults =
 		const bulkCreateMutation = useMutationWithTransition({
 			mutationFn: (vars) => {
 				if (!api.bulkCreate) return Promise.reject(/* @__PURE__ */ new Error(`[arc-next] "${entityKey}" api does not define a bulkCreate method`));
-				const auth = getAuthContext();
+				const auth = resolveAuth();
 				return api.bulkCreate({
 					token: vars.token ?? auth.token,
 					organizationId: vars.organizationId ?? auth.organizationId,
@@ -678,7 +692,7 @@ function createCrudHooks({ api, entityKey, singular, plural, idField, defaults =
 		const bulkUpdateMutation = useMutationWithTransition({
 			mutationFn: (vars) => {
 				if (!api.bulkUpdate) return Promise.reject(/* @__PURE__ */ new Error(`[arc-next] "${entityKey}" api does not define a bulkUpdate method`));
-				const auth = getAuthContext();
+				const auth = resolveAuth();
 				return api.bulkUpdate({
 					token: vars.token ?? auth.token,
 					organizationId: vars.organizationId ?? auth.organizationId,
@@ -696,7 +710,7 @@ function createCrudHooks({ api, entityKey, singular, plural, idField, defaults =
 		const bulkDeleteMutation = useMutationWithTransition({
 			mutationFn: (vars) => {
 				if (!api.bulkDelete) return Promise.reject(/* @__PURE__ */ new Error(`[arc-next] "${entityKey}" api does not define a bulkDelete method`));
-				const auth = getAuthContext();
+				const auth = resolveAuth();
 				return api.bulkDelete({
 					token: vars.token ?? auth.token,
 					organizationId: vars.organizationId ?? auth.organizationId,
@@ -740,7 +754,11 @@ function createCrudHooks({ api, entityKey, singular, plural, idField, defaults =
 		const router = resolvedRouterHook();
 		return useCallback((href, item, options = {}) => {
 			const id = resolveItemId(item);
-			if (id) queryClient.setQueryData(KEYS.detail(id), { data: item });
+			if (id) {
+				const orgId = resolveAuth().organizationId;
+				queryClient.setQueryData(KEYS.scopedDetail(id, orgId), { data: item });
+				if (orgId) queryClient.setQueryData(KEYS.detail(id), { data: item });
+			}
 			if (!router) return;
 			const { scroll = true, replace = false } = options;
 			if (replace) router.replace(href, { scroll });

package/dist/mutation.d.ts

@@ -1,5 +1,4 @@
 import { ToastHandler } from "./client.js";
-import { QUERY_CONFIGS } from "./query.js";
 import * as _$_tanstack_react_query0 from "@tanstack/react-query";
 import { QueryClient, QueryKey, UseMutateAsyncFunction, UseMutateFunction } from "@tanstack/react-query";
 
@@ -107,7 +106,5 @@ declare function useOptimisticMutation<TData, TVariables>(config: CreateOptimist
     data: [readonly unknown[], unknown][];
   }[];
 }>;
-/** @deprecated Use `useOptimisticMutation` */
-declare const createOptimisticMutation: typeof useOptimisticMutation;
 //#endregion
-export { CreateOptimisticMutationConfig, MutationCallbacks, MutationMessages, OptimisticMutationConfig, QUERY_CONFIGS, TransitionMutationConfig, TransitionMutationReturn, configureToast, createOptimisticMutation, useMutationWithOptimistic, useMutationWithTransition, useOptimisticMutation };
+export { CreateOptimisticMutationConfig, MutationCallbacks, MutationMessages, OptimisticMutationConfig, TransitionMutationConfig, TransitionMutationReturn, configureToast, useMutationWithOptimistic, useMutationWithTransition, useOptimisticMutation };

package/dist/mutation.js

@@ -1,7 +1,6 @@
 "use client";
 
 import { isArcApiError, isAutoIdempotency } from "./client.js";
-import { QUERY_CONFIGS } from "./query.js";
 import { useMutation, useQueryClient } from "@tanstack/react-query";
 import { useCallback, useRef, useTransition } from "react";
 
@@ -162,8 +161,6 @@ function useOptimisticMutation(config) {
 		}
 	});
 }
-/** @deprecated Use `useOptimisticMutation` */
-const createOptimisticMutation = useOptimisticMutation;
 
 //#endregion
-export { QUERY_CONFIGS, configureToast, createOptimisticMutation, useMutationWithOptimistic, useMutationWithTransition, useOptimisticMutation };
+export { configureToast, useMutationWithOptimistic, useMutationWithTransition, useOptimisticMutation };

package/dist/prefetch.d.ts

@@ -1,7 +1,15 @@
 import { QueryClient, dehydrate } from "@tanstack/react-query";
 
 //#region src/prefetch.d.ts
-interface PrefetchOptions {
+interface PrefetchAuthContext {
+  /** Auth token for protected endpoints. Required for bearer/header auth on server. */
+  token?: string | null;
+  /** Organization ID for multi-tenant prefetch. Sent as x-organization-id header. */
+  organizationId?: string | null;
+  /** Additional headers (e.g., x-api-key for header auth). */
+  headers?: Record<string, string>;
+}
+interface PrefetchOptions extends PrefetchAuthContext {
   staleTime?: number;
 }
 interface PrefetchDetailOptions extends PrefetchOptions {
@@ -74,28 +82,43 @@ declare function createCrudPrefetcher(api: {
     params?: Record<string, unknown>;
     token?: string | null;
     organizationId?: string | null;
+    options?: {
+      headerOptions?: Record<string, string>;
+    };
   }) => Promise<unknown>;
   getById: (opts: {
     id: string;
     token?: string | null;
     organizationId?: string | null;
+    options?: {
+      headerOptions?: Record<string, string>;
+    };
   }) => Promise<unknown>;
   getBySlug?: (opts: {
     slug: string;
     token?: string | null;
     organizationId?: string | null;
     params?: Record<string, unknown>;
+    options?: {
+      headerOptions?: Record<string, string>;
+    };
   }) => Promise<unknown>;
   getDeleted?: (opts: {
     params?: Record<string, unknown>;
     token?: string | null;
     organizationId?: string | null;
+    options?: {
+      headerOptions?: Record<string, string>;
+    };
   }) => Promise<unknown>;
   getTree?: (opts: {
     params?: Record<string, unknown>;
     token?: string | null;
     organizationId?: string | null;
+    options?: {
+      headerOptions?: Record<string, string>;
+    };
   }) => Promise<unknown>;
 }, entityKey: string): CrudPrefetcher;
 //#endregion
-export { CrudPrefetcher, PrefetchDetailOptions, PrefetchOptions, createCrudPrefetcher, dehydrate };
+export { CrudPrefetcher, PrefetchAuthContext, PrefetchDetailOptions, PrefetchOptions, createCrudPrefetcher, dehydrate };

package/dist/prefetch.js

@@ -31,75 +31,90 @@ function createCrudPrefetcher(api, entityKey) {
 	const KEYS = createQueryKeys(entityKey);
 	return {
 		async prefetchList(queryClient, params = {}, options = {}) {
-			const { organizationId, ...restParams } = params;
-			const scope = organizationId ? "tenant" : "super-admin";
+			const { organizationId: paramOrgId, ...restParams } = params;
+			const orgId = paramOrgId ?? options.organizationId ?? null;
+			const scope = orgId ? "tenant" : "super-admin";
 			const queryKey = KEYS.scopedList(scope, {
-				organizationId,
+				...orgId ? { organizationId: orgId } : {},
 				...restParams
 			});
 			await queryClient.prefetchQuery({
 				queryKey,
 				queryFn: () => api.getAll({
 					params: restParams,
-					organizationId: organizationId ?? null
+					token: options.token ?? null,
+					organizationId: orgId,
+					...options.headers ? { options: { headerOptions: options.headers } } : {}
 				}),
 				staleTime: options.staleTime
 			});
 		},
 		async prefetchDetail(queryClient, id, options = {}) {
-			const { params, staleTime } = options;
+			const { params, staleTime, token, organizationId } = options;
 			const baseKey = KEYS.detail(id);
 			const queryKey = params ? [...baseKey, params] : baseKey;
 			await queryClient.prefetchQuery({
 				queryKey,
 				queryFn: () => api.getById({
 					id,
-					...params ? { params } : {}
+					token: token ?? null,
+					organizationId: organizationId ?? null,
+					...params ? { params } : {},
+					...options.headers ? { options: { headerOptions: options.headers } } : {}
 				}),
 				staleTime
 			});
 		},
 		async prefetchBySlug(queryClient, slug, options = {}) {
 			if (!api.getBySlug) throw new Error(`[arc-next] prefetchBySlug requires an api with getBySlug (slugLookup preset)`);
-			const { params, staleTime } = options;
+			const { params, staleTime, token, organizationId } = options;
 			const queryKey = params ? KEYS.custom("slug", slug, params) : KEYS.custom("slug", slug);
 			await queryClient.prefetchQuery({
 				queryKey,
 				queryFn: () => api.getBySlug({
 					slug,
-					...params ? { params } : {}
+					token: token ?? null,
+					organizationId: organizationId ?? null,
+					...params ? { params } : {},
+					...options.headers ? { options: { headerOptions: options.headers } } : {}
 				}),
 				staleTime
 			});
 		},
 		async prefetchDeleted(queryClient, params = {}, options = {}) {
 			if (!api.getDeleted) throw new Error(`[arc-next] prefetchDeleted requires an api with getDeleted (softDelete preset)`);
-			const { organizationId, ...restParams } = params;
+			const { organizationId: paramOrgId, ...restParams } = params;
+			const orgId = paramOrgId ?? options.organizationId ?? null;
 			const queryKey = KEYS.custom("deleted", {
-				organizationId,
+				...orgId ? { organizationId: orgId } : {},
 				...restParams
 			});
 			await queryClient.prefetchQuery({
 				queryKey,
 				queryFn: () => api.getDeleted({
 					params: restParams,
-					organizationId: organizationId ?? null
+					token: options.token ?? null,
+					organizationId: orgId,
+					...options.headers ? { options: { headerOptions: options.headers } } : {}
 				}),
 				staleTime: options.staleTime
 			});
 		},
 		async prefetchTree(queryClient, params = {}, options = {}) {
 			if (!api.getTree) throw new Error(`[arc-next] prefetchTree requires an api with getTree (tree preset)`);
-			const { organizationId, ...restParams } = params;
+			const { organizationId: paramOrgId, ...restParams } = params;
+			const orgId = paramOrgId ?? options.organizationId ?? null;
 			const queryKey = KEYS.custom("tree", {
-				organizationId,
+				...orgId ? { organizationId: orgId } : {},
 				...restParams
 			});
 			await queryClient.prefetchQuery({
 				queryKey,
 				queryFn: () => api.getTree({
 					params: restParams,
-					organizationId: organizationId ?? null
+					token: options.token ?? null,
+					organizationId: orgId,
+					...options.headers ? { options: { headerOptions: options.headers } } : {}
 				}),
 				staleTime: options.staleTime
 			});

package/dist/query.d.ts

@@ -86,16 +86,27 @@ interface QueryKeys {
   list: (params?: unknown) => QueryKey;
   details: () => QueryKey;
   detail: (id: string) => QueryKey;
+  /** Tenant-scoped detail key. Use when IDs are only unique within an org. */
+  scopedDetail: (id: string, organizationId: string | null) => QueryKey;
   custom: (key: string, ...args: unknown[]) => QueryKey;
   scopedList: (scope: string, params?: unknown) => QueryKey;
 }
 interface CacheUtils<T> {
   invalidateAll: (client: QueryClient) => Promise<void>;
   invalidateLists: (client: QueryClient) => Promise<void>;
+  /** Invalidate detail by ID (prefix-matches all scoped/parameterized variants). */
   invalidateDetail: (client: QueryClient, id: string) => Promise<void>;
   setDetail: (client: QueryClient, id: string, data: T) => void;
   getDetail: (client: QueryClient, id: string) => T | undefined;
   removeDetail: (client: QueryClient, id: string) => void;
+  /** Invalidate tenant-scoped detail (prefix-matches parameterized variants within org). */
+  invalidateScopedDetail: (client: QueryClient, id: string, organizationId: string | null) => Promise<void>;
+  /** Set tenant-scoped detail cache. */
+  setScopedDetail: (client: QueryClient, id: string, organizationId: string | null, data: T) => void;
+  /** Get tenant-scoped detail from cache. */
+  getScopedDetail: (client: QueryClient, id: string, organizationId: string | null) => T | undefined;
+  /** Remove tenant-scoped detail from cache. */
+  removeScopedDetail: (client: QueryClient, id: string, organizationId: string | null) => void;
 }
 declare const DEFAULT_QUERY_CONFIG: {
   readonly staleTime: number;
@@ -221,11 +232,5 @@ declare function useInfiniteListQuery<T>({
   getPreviousPageParam,
   maxPages
 }: CreateInfiniteListQueryConfig): InfiniteListQueryResult<T>;
-/** @deprecated Use `useListQuery` */
-declare const createListQuery: typeof useListQuery;
-/** @deprecated Use `useDetailQuery` */
-declare const createDetailQuery: typeof useDetailQuery;
-/** @deprecated Use `useInfiniteListQuery` */
-declare const createInfiniteListQuery: typeof useInfiniteListQuery;
 //#endregion
-export { CacheUtils, CreateDetailQueryConfig, CreateInfiniteListQueryConfig, CreateListQueryConfig, DEFAULT_QUERY_CONFIG, DetailQueryOptions, DetailQueryResult, InfiniteListQueryOptions, InfiniteListQueryResult, ListQueryOptions, ListQueryResult, PaginationData, QUERY_CONFIGS, QueryKeys, RequestPassthrough, createCacheUtils, createDetailQuery, createInfiniteListQuery, createListQuery, createQueryKeys, extractItem, getItemId, updateListCache, useDetailQuery, useInfiniteListQuery, useListQuery };
+export { CacheUtils, CreateDetailQueryConfig, CreateInfiniteListQueryConfig, CreateListQueryConfig, DEFAULT_QUERY_CONFIG, DetailQueryOptions, DetailQueryResult, InfiniteListQueryOptions, InfiniteListQueryResult, ListQueryOptions, ListQueryResult, PaginationData, QUERY_CONFIGS, QueryKeys, RequestPassthrough, createCacheUtils, createQueryKeys, extractItem, getItemId, updateListCache, useDetailQuery, useInfiniteListQuery, useListQuery };

package/dist/query.js

@@ -120,6 +120,16 @@ function createQueryKeys(entityKey) {
 			"detail",
 			id
 		],
+		scopedDetail: (id, organizationId) => organizationId ? [
+			entityKey,
+			"detail",
+			id,
+			{ _org: organizationId }
+		] : [
+			entityKey,
+			"detail",
+			id
+		],
 		custom: (key, ...args) => [
 			entityKey,
 			key,
@@ -144,7 +154,13 @@ function createCacheUtils(KEYS) {
 		getDetail: (client, id) => {
 			return client.getQueryData(KEYS.detail(id))?.data;
 		},
-		removeDetail: (client, id) => client.removeQueries({ queryKey: KEYS.detail(id) })
+		removeDetail: (client, id) => client.removeQueries({ queryKey: KEYS.detail(id) }),
+		invalidateScopedDetail: (client, id, organizationId) => client.invalidateQueries({ queryKey: KEYS.scopedDetail(id, organizationId) }),
+		setScopedDetail: (client, id, organizationId, data) => client.setQueryData(KEYS.scopedDetail(id, organizationId), { data }),
+		getScopedDetail: (client, id, organizationId) => {
+			return client.getQueryData(KEYS.scopedDetail(id, organizationId))?.data;
+		},
+		removeScopedDetail: (client, id, organizationId) => client.removeQueries({ queryKey: KEYS.scopedDetail(id, organizationId) })
 	};
 }
 function useListQuery({ queryKey, queryFn, enabled = true, options = {}, prefillDetailCache = true, detailKeyBuilder, itemIdResolver, select }) {
@@ -239,12 +255,6 @@ function useInfiniteListQuery({ queryKey, queryFn, enabled = true, options = {},
 		data: query.data
 	};
 }
-/** @deprecated Use `useListQuery` */
-const createListQuery = useListQuery;
-/** @deprecated Use `useDetailQuery` */
-const createDetailQuery = useDetailQuery;
-/** @deprecated Use `useInfiniteListQuery` */
-const createInfiniteListQuery = useInfiniteListQuery;
 
 //#endregion
-export { DEFAULT_QUERY_CONFIG, QUERY_CONFIGS, createCacheUtils, createDetailQuery, createInfiniteListQuery, createListQuery, createQueryKeys, extractItem, getItemId, updateListCache, useDetailQuery, useInfiniteListQuery, useListQuery };
+export { DEFAULT_QUERY_CONFIG, QUERY_CONFIGS, createCacheUtils, createQueryKeys, extractItem, getItemId, updateListCache, useDetailQuery, useInfiniteListQuery, useListQuery };

package/dist/sse.d.ts

@@ -9,12 +9,19 @@ interface ArcServerEvent {
   id?: string;
 }
 interface EventStreamOptions {
-  /** SSE endpoint URL (absolute or relative to baseUrl). Default: `/{basePath}/{resource}/events/stream` */
+  /** Full SSE endpoint URL. When set, overrides `path` and `baseUrl`. Use for non-Arc backends or custom URLs. */
   url?: string;
-  /** Resource name used for the default endpoint path and event filtering. */
+  /**
+   * Resource name for automatic pattern filtering.
+   * When set and `patterns` is empty, auto-generates `['resource.*']` filter.
+   * Does NOT affect the endpoint URL — use `path` for that.
+   */
   resource?: string;
-  /** Base path for the events endpoint. Default: '/api/v1' */
-  basePath?: string;
+  /**
+   * SSE endpoint path (appended to baseUrl). Default: '/events/stream'.
+   * Matches Arc's ssePlugin default. Override if your backend uses a custom path.
+   */
+  path?: string;
   /** Event patterns to listen for (e.g., ['agents.created', 'agents.updated']). When empty, all events are received. */
   patterns?: string[];
   /** Query keys to invalidate when any event is received. */

package/dist/sse.js

@@ -1,6 +1,6 @@
 "use client";
 
-import { getAuthContext, getAuthMode } from "./client.js";
+import { getAuthContext, getAuthMode, getBaseUrl } from "./client.js";
 import { useQueryClient } from "@tanstack/react-query";
 import { useCallback, useEffect, useRef, useState } from "react";
 
@@ -19,7 +19,7 @@ import { useCallback, useEffect, useRef, useState } from "react";
 * });
 */
 function useEventStream(options) {
-	const { url, resource, basePath = "/api/v1", enabled = true, reconnectDelay = 3e3, maxReconnectAttempts = Infinity, withCredentials } = options;
+	const { url, resource, path: ssePath = "/events/stream", enabled = true, reconnectDelay = 3e3, maxReconnectAttempts = Infinity, withCredentials } = options;
 	const queryClient = useQueryClient();
 	const [isConnected, setIsConnected] = useState(false);
 	const [lastEvent, setLastEvent] = useState(null);
@@ -38,20 +38,20 @@ function useEventStream(options) {
 	invalidateKeysRef.current = options.invalidateQueries ?? [];
 	const buildUrl = useCallback(() => {
 		if (url) return url;
-		if (!resource) throw new Error("[arc-next] useEventStream requires either `url` or `resource`");
 		const auth = getAuthContext();
 		const params = new URLSearchParams();
 		const patterns = patternsRef.current;
-		if (patterns.length > 0) params.set("patterns", patterns.join(","));
+		const effectivePatterns = patterns.length > 0 ? patterns : resource ? [`${resource}.*`] : [];
+		if (effectivePatterns.length > 0) params.set("patterns", effectivePatterns.join(","));
 		if (auth.organizationId) params.set("organizationId", auth.organizationId);
 		if (auth.token) params.set("token", auth.token);
 		const qs = params.toString();
-		const base = `${basePath}/${resource}/events/stream`;
+		const base = `${getBaseUrl()}${ssePath}`;
 		return qs ? `${base}?${qs}` : base;
 	}, [
 		url,
 		resource,
-		basePath
+		ssePath
 	]);
 	const connect = useCallback(() => {
 		if (esRef.current) esRef.current.close();
@@ -110,6 +110,7 @@ function useEventStream(options) {
 	}, []);
 	const reconnect = useCallback(() => {
 		reconnectAttemptsRef.current = 0;
+		manualCloseRef.current = false;
 		connect();
 	}, [connect]);
 	useEffect(() => {

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@classytic/arc-next",
-  "version": "0.4.0",
+  "version": "0.4.1",
   "description": "React + TanStack Query SDK for Arc resources",
   "type": "module",
   "sideEffects": false,