@classytic/arc-next 0.3.1 → 0.4.1

package/dist/mutation.js

@@ -1,8 +1,8 @@
 "use client";
 
-import { isArcApiError } from "./client.js";
+import { isArcApiError, isAutoIdempotency } from "./client.js";
 import { useMutation, useQueryClient } from "@tanstack/react-query";
-import { useTransition } from "react";
+import { useCallback, useRef, useTransition } from "react";
 
 //#region src/mutation.ts
 let toastHandler = {
@@ -43,8 +43,18 @@ function useMutationWithTransition(config) {
 	const { mutationFn, invalidateQueries = [], onSuccess, onError, onSettled, messages, useTransition: withTransition = true, showToast: toast = true, toastHandler: instanceToast } = config;
 	const queryClient = useQueryClient();
 	const [isTransitioning, startTransition] = useTransition();
+	const idempotencyKeyRef = useRef(null);
 	const mutation = useMutation({
-		mutationFn,
+		mutationFn: (variables) => {
+			if (idempotencyKeyRef.current && typeof variables === "object" && variables !== null) {
+				const vars = variables;
+				if (vars.options && typeof vars.options === "object") vars.options.idempotencyKey ??= idempotencyKeyRef.current;
+			}
+			return mutationFn(variables);
+		},
+		onMutate: () => {
+			idempotencyKeyRef.current = isAutoIdempotency() ? globalThis.crypto.randomUUID() : null;
+		},
 		onSuccess: (data, variables) => {
 			const invalidate = () => {
 				invalidateQueries.forEach((key) => queryClient.invalidateQueries({ queryKey: key }));
@@ -151,17 +161,6 @@ function useOptimisticMutation(config) {
 		}
 	});
 }
-const QUERY_CONFIGS = {
-	realtime: {
-		staleTime: 2e4,
-		refetchInterval: 3e4
-	},
-	frequent: { staleTime: 6e4 },
-	stable: { staleTime: 3e5 },
-	static: { staleTime: 6e5 }
-};
-/** @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 {
@@ -28,6 +36,21 @@ interface CrudPrefetcher {
    * await productsPrefetcher.prefetchDetail(queryClient, productId);
    */
   prefetchDetail: (queryClient: QueryClient, id: string, options?: PrefetchDetailOptions) => Promise<void>;
+  /**
+   * Prefetch a detail-by-slug query. Uses the same query keys as useDetailBySlug.
+   * Only available when the API has a `getBySlug` method (slugLookup preset).
+   */
+  prefetchBySlug: (queryClient: QueryClient, slug: string, options?: PrefetchDetailOptions) => Promise<void>;
+  /**
+   * Prefetch soft-deleted items. Uses the same query keys as useDeleted.
+   * Only available when the API has a `getDeleted` method (softDelete preset).
+   */
+  prefetchDeleted: (queryClient: QueryClient, params?: Record<string, unknown>, options?: PrefetchOptions) => Promise<void>;
+  /**
+   * Prefetch a tree query. Uses the same query keys as useTree.
+   * Only available when the API has a `getTree` method (tree preset).
+   */
+  prefetchTree: (queryClient: QueryClient, params?: Record<string, unknown>, options?: PrefetchOptions) => Promise<void>;
 }
 /**
  * Create server-safe prefetch helpers for CRUD queries.
@@ -59,12 +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

@@ -1,23 +1,7 @@
+import { createQueryKeys } from "./query.js";
 import { dehydrate } from "@tanstack/react-query";
 
 //#region src/prefetch.ts
-function scopedListKey(entityKey, scope, params) {
-	return [
-		entityKey,
-		"list",
-		{
-			_scope: scope,
-			...params || {}
-		}
-	];
-}
-function detailKey(entityKey, id) {
-	return [
-		entityKey,
-		"detail",
-		id
-	];
-}
 /**
 * Create server-safe prefetch helpers for CRUD queries.
 * Use in Next.js server components to pre-populate the query cache before rendering.
@@ -44,34 +28,96 @@ function detailKey(entityKey, id) {
 * }
 */
 function createCrudPrefetcher(api, entityKey) {
+	const KEYS = createQueryKeys(entityKey);
 	return {
 		async prefetchList(queryClient, params = {}, options = {}) {
-			const { organizationId, ...restParams } = params;
-			const queryKey = scopedListKey(entityKey, organizationId ? "tenant" : "super-admin", {
-				organizationId,
+			const { organizationId: paramOrgId, ...restParams } = params;
+			const orgId = paramOrgId ?? options.organizationId ?? null;
+			const scope = orgId ? "tenant" : "super-admin";
+			const queryKey = KEYS.scopedList(scope, {
+				...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 baseKey = detailKey(entityKey, id);
+			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, token, organizationId } = options;
+			const queryKey = params ? KEYS.custom("slug", slug, params) : KEYS.custom("slug", slug);
+			await queryClient.prefetchQuery({
+				queryKey,
+				queryFn: () => api.getBySlug({
+					slug,
+					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: paramOrgId, ...restParams } = params;
+			const orgId = paramOrgId ?? options.organizationId ?? null;
+			const queryKey = KEYS.custom("deleted", {
+				...orgId ? { organizationId: orgId } : {},
+				...restParams
+			});
+			await queryClient.prefetchQuery({
+				queryKey,
+				queryFn: () => api.getDeleted({
+					params: restParams,
+					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: paramOrgId, ...restParams } = params;
+			const orgId = paramOrgId ?? options.organizationId ?? null;
+			const queryKey = KEYS.custom("tree", {
+				...orgId ? { organizationId: orgId } : {},
+				...restParams
+			});
+			await queryClient.prefetchQuery({
+				queryKey,
+				queryFn: () => api.getTree({
+					params: restParams,
+					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;
@@ -103,6 +114,22 @@ declare const DEFAULT_QUERY_CONFIG: {
   readonly refetchOnWindowFocus: false;
   readonly retry: 0;
 };
+/** Pre-built query config presets for common data freshness patterns. */
+declare const QUERY_CONFIGS: {
+  /** Live data: 20s stale, 30s polling */readonly realtime: {
+    readonly staleTime: 20000;
+    readonly refetchInterval: 30000;
+  }; /** Frequently updated: 60s stale */
+  readonly frequent: {
+    readonly staleTime: 60000;
+  }; /** Stable data: 5min stale (same as default) */
+  readonly stable: {
+    readonly staleTime: 300000;
+  }; /** Rarely changes: 10min stale */
+  readonly static: {
+    readonly staleTime: 600000;
+  };
+};
 declare function getItemId(item: unknown): string | null;
 declare function extractItem<T>(data: unknown): T | null;
 declare function updateListCache<T>(listData: unknown, updater: (items: T[]) => T[]): unknown;
@@ -117,6 +144,8 @@ interface CreateListQueryConfig {
   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;
 }
 declare function useListQuery<T>({
@@ -126,6 +155,7 @@ declare function useListQuery<T>({
   options,
   prefillDetailCache,
   detailKeyBuilder,
+  itemIdResolver,
   select
 }: CreateListQueryConfig): ListQueryResult<T>;
 interface CreateDetailQueryConfig {
@@ -155,6 +185,12 @@ interface InfiniteListQueryOptions {
   refetchIntervalInBackground?: boolean;
   _scope?: string;
   request?: RequestPassthrough;
+  /**
+   * Max pages to keep in memory. Old pages are evicted and re-fetched on scroll-back.
+   * Requires `getPreviousPageParam` for backward re-fetching.
+   * When unset, all fetched pages are retained (default TanStack Query behavior).
+   */
+  maxPages?: number;
 }
 interface InfiniteListQueryResult<T> {
   items: T[];
@@ -183,6 +219,8 @@ interface CreateInfiniteListQueryConfig {
   initialPageParam?: unknown;
   getNextPageParam: (lastPage: unknown) => unknown;
   getPreviousPageParam?: (firstPage: unknown) => unknown;
+  /** Max pages to keep in memory. Old pages are evicted when exceeded. */
+  maxPages?: number;
 }
 declare function useInfiniteListQuery<T>({
   queryKey,
@@ -191,13 +229,8 @@ declare function useInfiniteListQuery<T>({
   options,
   initialPageParam,
   getNextPageParam,
-  getPreviousPageParam
+  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, 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

@@ -10,6 +10,16 @@ const DEFAULT_QUERY_CONFIG = {
 	refetchOnWindowFocus: false,
 	retry: 0
 };
+/** Pre-built query config presets for common data freshness patterns. */
+const QUERY_CONFIGS = {
+	realtime: {
+		staleTime: 2e4,
+		refetchInterval: 3e4
+	},
+	frequent: { staleTime: 6e4 },
+	stable: { staleTime: 3e5 },
+	static: { staleTime: 6e5 }
+};
 function getItemId(item) {
 	if (!item || typeof item !== "object") return null;
 	const obj = item;
@@ -110,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,
@@ -134,10 +154,16 @@ 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, select }) {
+function useListQuery({ queryKey, queryFn, enabled = true, options = {}, prefillDetailCache = true, detailKeyBuilder, itemIdResolver, select }) {
 	const queryClient = useQueryClient();
 	const query = useQuery({
 		queryKey,
@@ -152,8 +178,9 @@ function useListQuery({ queryKey, queryFn, enabled = true, options = {}, prefill
 	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 = getItemId(item);
+			const id = resolveId(item);
 			if (id) queryClient.setQueryData(detailKeyBuilder(id), { data: item });
 		});
 	}, [
@@ -196,7 +223,7 @@ function useDetailQuery({ queryKey, queryFn, enabled = true, options = {}, selec
 		data: query.data
 	};
 }
-function useInfiniteListQuery({ queryKey, queryFn, enabled = true, options = {}, initialPageParam = 1, getNextPageParam, getPreviousPageParam }) {
+function useInfiniteListQuery({ queryKey, queryFn, enabled = true, options = {}, initialPageParam = 1, getNextPageParam, getPreviousPageParam, maxPages }) {
 	const query = useInfiniteQuery({
 		queryKey,
 		queryFn: ({ pageParam, signal }) => queryFn({
@@ -207,6 +234,7 @@ function useInfiniteListQuery({ queryKey, queryFn, enabled = true, options = {},
 		initialPageParam,
 		getNextPageParam,
 		getPreviousPageParam,
+		...maxPages != null ? { maxPages } : {},
 		...DEFAULT_QUERY_CONFIG,
 		...options
 	});
@@ -227,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, 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

@@ -0,0 +1,69 @@
+import { QueryKey } from "@tanstack/react-query";
+
+//#region src/sse.d.ts
+interface ArcServerEvent {
+  type: string;
+  resource: string;
+  data: unknown;
+  timestamp: string;
+  id?: string;
+}
+interface EventStreamOptions {
+  /** Full SSE endpoint URL. When set, overrides `path` and `baseUrl`. Use for non-Arc backends or custom URLs. */
+  url?: string;
+  /**
+   * 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;
+  /**
+   * 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. */
+  invalidateQueries?: QueryKey[];
+  /** Callback for each event. */
+  onEvent?: (event: ArcServerEvent) => void;
+  /** Callback for connection state changes. */
+  onConnectionChange?: (connected: boolean) => void;
+  /** Whether the stream is enabled. Default: true */
+  enabled?: boolean;
+  /** Reconnect delay in ms. Default: 3000 */
+  reconnectDelay?: number;
+  /** Maximum reconnect attempts before giving up. Default: Infinity */
+  maxReconnectAttempts?: number;
+  /** Whether to include credentials (cookies). Derived from authMode when not set. */
+  withCredentials?: boolean;
+}
+interface EventStreamResult {
+  /** Whether the EventSource is currently connected. */
+  isConnected: boolean;
+  /** The most recently received event. */
+  lastEvent: ArcServerEvent | null;
+  /** Number of events received since connection. */
+  eventCount: number;
+  /** Close the connection manually. */
+  close: () => void;
+  /** Reconnect after a manual close. */
+  reconnect: () => void;
+}
+/**
+ * Subscribe to Arc server-sent events for real-time cache invalidation.
+ *
+ * Uses the browser's native `EventSource` API for automatic reconnection
+ * and efficient server-push. Events trigger query invalidation so TanStack Query
+ * refetches affected data automatically.
+ *
+ * @example
+ * const { isConnected } = useEventStream({
+ *   resource: 'agents',
+ *   invalidateQueries: [agentKeys.lists()],
+ * });
+ */
+declare function useEventStream(options: EventStreamOptions): EventStreamResult;
+//#endregion
+export { ArcServerEvent, EventStreamOptions, EventStreamResult, useEventStream };

package/dist/sse.js

@@ -0,0 +1,145 @@
+"use client";
+
+import { getAuthContext, getAuthMode, getBaseUrl } from "./client.js";
+import { useQueryClient } from "@tanstack/react-query";
+import { useCallback, useEffect, useRef, useState } from "react";
+
+//#region src/sse.ts
+/**
+* Subscribe to Arc server-sent events for real-time cache invalidation.
+*
+* Uses the browser's native `EventSource` API for automatic reconnection
+* and efficient server-push. Events trigger query invalidation so TanStack Query
+* refetches affected data automatically.
+*
+* @example
+* const { isConnected } = useEventStream({
+*   resource: 'agents',
+*   invalidateQueries: [agentKeys.lists()],
+* });
+*/
+function useEventStream(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);
+	const [eventCount, setEventCount] = useState(0);
+	const esRef = useRef(null);
+	const reconnectAttemptsRef = useRef(0);
+	const reconnectTimerRef = useRef(null);
+	const manualCloseRef = useRef(false);
+	const onEventRef = useRef(options.onEvent);
+	onEventRef.current = options.onEvent;
+	const onConnectionChangeRef = useRef(options.onConnectionChange);
+	onConnectionChangeRef.current = options.onConnectionChange;
+	const patternsRef = useRef(options.patterns ?? []);
+	patternsRef.current = options.patterns ?? [];
+	const invalidateKeysRef = useRef(options.invalidateQueries ?? []);
+	invalidateKeysRef.current = options.invalidateQueries ?? [];
+	const buildUrl = useCallback(() => {
+		if (url) return url;
+		const auth = getAuthContext();
+		const params = new URLSearchParams();
+		const patterns = patternsRef.current;
+		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 = `${getBaseUrl()}${ssePath}`;
+		return qs ? `${base}?${qs}` : base;
+	}, [
+		url,
+		resource,
+		ssePath
+	]);
+	const connect = useCallback(() => {
+		if (esRef.current) esRef.current.close();
+		manualCloseRef.current = false;
+		const eventUrl = buildUrl();
+		const authMode = getAuthMode();
+		const es = new EventSource(eventUrl, { withCredentials: withCredentials ?? authMode === "cookie" });
+		esRef.current = es;
+		es.onopen = () => {
+			reconnectAttemptsRef.current = 0;
+			setIsConnected(true);
+			onConnectionChangeRef.current?.(true);
+		};
+		es.onmessage = (event) => {
+			try {
+				const parsed = JSON.parse(event.data);
+				const patterns = patternsRef.current;
+				if (patterns.length > 0 && !patterns.includes(parsed.type)) return;
+				setLastEvent(parsed);
+				setEventCount((c) => c + 1);
+				onEventRef.current?.(parsed);
+				const keys = invalidateKeysRef.current;
+				for (const key of keys) queryClient.invalidateQueries({ queryKey: key });
+			} catch {}
+		};
+		es.onerror = () => {
+			es.close();
+			setIsConnected(false);
+			onConnectionChangeRef.current?.(false);
+			if (manualCloseRef.current) return;
+			if (reconnectAttemptsRef.current < maxReconnectAttempts) {
+				reconnectAttemptsRef.current += 1;
+				const delay = Math.min(reconnectDelay * Math.pow(1.5, reconnectAttemptsRef.current - 1), 3e4);
+				reconnectTimerRef.current = setTimeout(connect, delay);
+			}
+		};
+	}, [
+		buildUrl,
+		queryClient,
+		withCredentials,
+		reconnectDelay,
+		maxReconnectAttempts
+	]);
+	const close = useCallback(() => {
+		manualCloseRef.current = true;
+		if (reconnectTimerRef.current) {
+			clearTimeout(reconnectTimerRef.current);
+			reconnectTimerRef.current = null;
+		}
+		if (esRef.current) {
+			esRef.current.close();
+			esRef.current = null;
+		}
+		setIsConnected(false);
+		onConnectionChangeRef.current?.(false);
+	}, []);
+	const reconnect = useCallback(() => {
+		reconnectAttemptsRef.current = 0;
+		manualCloseRef.current = false;
+		connect();
+	}, [connect]);
+	useEffect(() => {
+		if (!enabled) {
+			close();
+			return;
+		}
+		connect();
+		return () => {
+			manualCloseRef.current = true;
+			if (reconnectTimerRef.current) clearTimeout(reconnectTimerRef.current);
+			if (esRef.current) {
+				esRef.current.close();
+				esRef.current = null;
+			}
+		};
+	}, [
+		enabled,
+		connect,
+		close
+	]);
+	return {
+		isConnected,
+		lastEvent,
+		eventCount,
+		close,
+		reconnect
+	};
+}
+
+//#endregion
+export { useEventStream };