@classytic/arc-next 0.4.1 → 0.6.0

package/dist/query.d.ts

@@ -1,18 +1,7 @@
-import { InfiniteData, QueryClient, QueryKey } from "@tanstack/react-query";
+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";
 
 //#region src/query.d.ts
-interface PaginationData {
-  /** Pagination method detected from response (offset | keyset | aggregate) */
-  method: 'offset' | 'keyset' | 'aggregate' | null;
-  total: number;
-  pages: number;
-  page: number;
-  limit: number;
-  hasNext: boolean;
-  hasPrev: boolean;
-  /** Keyset cursor for next page (keyset pagination only) */
-  next?: string | null;
-}
 /** Request-level options passed through to the fetch call */
 interface RequestPassthrough {
   cache?: RequestCache;
@@ -80,61 +69,6 @@ interface DetailQueryResult<T> {
   refetch: () => Promise<unknown>;
   data: unknown;
 }
-interface QueryKeys {
-  all: string[];
-  lists: () => QueryKey;
-  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;
-  readonly gcTime: number;
-  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;
-declare function createQueryKeys(entityKey: string): QueryKeys;
-declare function createCacheUtils<T>(KEYS: QueryKeys): CacheUtils<T>;
 interface CreateListQueryConfig {
   queryKey: QueryKey;
   queryFn: (context: {
@@ -232,5 +166,88 @@ declare function useInfiniteListQuery<T>({
   getPreviousPageParam,
   maxPages
 }: CreateInfiniteListQueryConfig): InfiniteListQueryResult<T>;
+/** Recognized data-freshness presets. Maps to QUERY_CONFIGS. */
+type QueryFreshness = keyof typeof QUERY_CONFIGS;
+/**
+ * Identity passthrough — arc emits raw data on success (no envelope; HTTP
+ * status discriminates errors via thrown `ArcApiError`). Kept as a named
+ * type for the `useApiQuery` default param so the public signature stays
+ * `useApiQuery<TResponse, TData = ExtractData<TResponse>>` for callers
+ * that want a custom select projection.
+ */
+type ExtractData<T> = T;
+/** Per-call request pass-through and TanStack Query overrides. */
+interface UseApiQueryOptions {
+  staleTime?: number;
+  gcTime?: number;
+  refetchOnWindowFocus?: boolean;
+  refetchInterval?: number | false;
+  refetchIntervalInBackground?: boolean;
+  retry?: boolean | number;
+  /** Limit re-renders to changes in these specific fields (perf optimization). */
+  notifyOnChangeProps?: ('data' | 'error' | 'isLoading' | 'isFetching' | 'isError' | 'isSuccess' | 'isStale')[];
+}
+interface UseApiQueryConfig<TResponse, TData> {
+  queryKey: QueryKey;
+  queryFn: (context: {
+    signal: AbortSignal;
+  }) => Promise<TResponse>;
+  enabled?: boolean;
+  /** Freshness preset name (`realtime` | `frequent` | `stable` | `static`). */
+  freshness?: QueryFreshness;
+  /**
+   * Custom projection from the raw response. When omitted, the response is
+   * returned unchanged — arc 2.13+ has no wire envelope, so the response
+   * already IS the data.
+   */
+  select?: (response: TResponse) => TData;
+  /** TanStack Query overrides (staleTime, refetchInterval, retry, etc.). */
+  options?: UseApiQueryOptions;
+}
+interface UseApiQueryResult<TData> {
+  data: TData | null;
+  isLoading: boolean;
+  isFetching: boolean;
+  isError: boolean;
+  isSuccess: boolean;
+  isStale: boolean;
+  error: Error | null;
+  refetch: () => Promise<unknown>;
+}
+/**
+ * Generic query hook for non-CRUD reads (reports, aggregates, lookups, RPC-style
+ * endpoints). Wraps TanStack Query with two ergonomics on top:
+ *
+ * 1. **Freshness presets.** Pass `freshness: 'realtime' | 'frequent' | 'stable' |
+ *    'static'` to map onto `QUERY_CONFIGS`. Per-option overrides still win.
+ * 2. **Standardized result shape.** `{ data, isLoading, isFetching, isError,
+ *    isSuccess, isStale, error, refetch }` — same contract as the CRUD hooks.
+ *
+ * Arc emits raw data on success (no envelope), so the response IS the data.
+ * Use `select` for shape transformations / multi-field projections.
+ *
+ * @example
+ * // Direct typing — response IS the data
+ * const { data } = useApiQuery<DashboardStats>({
+ *   queryKey: ['dashboard', 'stats'],
+ *   queryFn: ({ signal }) => api.request('GET', '/dashboard/stats', { options: { signal } }),
+ *   freshness: 'realtime',
+ * });
+ *
+ * // Custom projection (e.g. extract a sub-field)
+ * const { data } = useApiQuery({
+ *   queryKey: ['ledger', accountId],
+ *   queryFn: ({ signal }) => api.request<{ entries: Entry[] }>('GET', `/ledger/${accountId}`, { options: { signal } }),
+ *   select: (res) => res.entries,
+ * });
+ */
+declare function useApiQuery<TResponse = unknown, TData = ExtractData<TResponse>>({
+  queryKey,
+  queryFn,
+  enabled,
+  freshness,
+  select,
+  options
+}: UseApiQueryConfig<TResponse, TData>): UseApiQueryResult<TData>;
 //#endregion
-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 };
+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 };

package/dist/query.js

@@ -1,168 +1,10 @@
 "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 { useEffect, useMemo } from "react";
+import { useCallback, useEffect, useMemo, useRef } from "react";
 
 //#region src/query.ts
-const DEFAULT_QUERY_CONFIG = {
-	staleTime: 300 * 1e3,
-	gcTime: 1800 * 1e3,
-	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;
-	const id = obj._id ?? obj.id;
-	return typeof id === "string" ? id : id ? String(id) : null;
-}
-function normalizePagination(data) {
-	if (!data || typeof data !== "object") return null;
-	const d = data;
-	const method = d.method ?? null;
-	const isKeyset = method === "keyset" || d.hasMore != null && d.total == null && d.pages == null;
-	const hasTotal = d.total != null || d.totalDocs != null;
-	const hasPages = d.pages != null || d.totalPages != null;
-	if (!hasTotal && !hasPages && !isKeyset) return null;
-	return {
-		method,
-		total: Number(d.total ?? d.totalDocs ?? 0),
-		pages: Number(d.pages ?? d.totalPages ?? (isKeyset ? 0 : 1)),
-		page: Number(d.page ?? d.currentPage ?? (isKeyset ? 0 : 1)),
-		limit: Number(d.limit ?? 10),
-		hasNext: Boolean(d.hasNext ?? d.hasNextPage ?? d.hasMore ?? false),
-		hasPrev: Boolean(d.hasPrev ?? d.hasPrevPage ?? false),
-		...isKeyset ? { next: d.next ?? null } : {}
-	};
-}
-/** Well-known keys checked in order for list responses. */
-const LIST_KEYS = [
-	"docs",
-	"data",
-	"items",
-	"results"
-];
-/** Well-known keys checked in order for detail responses. */
-const DETAIL_KEYS = [
-	"data",
-	"doc",
-	"item",
-	"result"
-];
-function extractItems(data) {
-	if (!data) return [];
-	if (Array.isArray(data)) return data;
-	if (typeof data !== "object") return [];
-	const d = data;
-	for (const key of LIST_KEYS) if (Array.isArray(d[key])) return d[key];
-	for (const value of Object.values(d)) if (Array.isArray(value)) return value;
-	return [];
-}
-function extractItem(data) {
-	if (data == null) return null;
-	if (typeof data !== "object") return data;
-	const d = data;
-	for (const key of DETAIL_KEYS) if (d[key] != null) return d[key];
-	return d;
-}
-function updateListCache(listData, updater) {
-	if (!listData) return listData;
-	if (Array.isArray(listData)) return updater(listData);
-	if (typeof listData !== "object") return listData;
-	const d = listData;
-	let arrayField = null;
-	for (const key of LIST_KEYS) if (Array.isArray(d[key])) {
-		arrayField = key;
-		break;
-	}
-	if (!arrayField) {
-		for (const [key, value] of Object.entries(d)) if (Array.isArray(value)) {
-			arrayField = key;
-			break;
-		}
-	}
-	if (!arrayField) return listData;
-	const updated = updater(d[arrayField]);
-	const original = d[arrayField];
-	const delta = updated.length - original.length;
-	const result = {
-		...d,
-		[arrayField]: updated
-	};
-	if (delta !== 0) {
-		if (d.total != null) result.total = Math.max(0, Number(d.total) + delta);
-		if (d.totalDocs != null) result.totalDocs = Math.max(0, Number(d.totalDocs) + delta);
-	}
-	return result;
-}
-function createQueryKeys(entityKey) {
-	return {
-		all: [entityKey],
-		lists: () => [entityKey, "list"],
-		list: (params) => [
-			entityKey,
-			"list",
-			params
-		],
-		details: () => [entityKey, "detail"],
-		detail: (id) => [
-			entityKey,
-			"detail",
-			id
-		],
-		scopedDetail: (id, organizationId) => organizationId ? [
-			entityKey,
-			"detail",
-			id,
-			{ _org: organizationId }
-		] : [
-			entityKey,
-			"detail",
-			id
-		],
-		custom: (key, ...args) => [
-			entityKey,
-			key,
-			...args
-		],
-		scopedList: (scope, params) => [
-			entityKey,
-			"list",
-			{
-				_scope: scope,
-				...params
-			}
-		]
-	};
-}
-function createCacheUtils(KEYS) {
-	return {
-		invalidateAll: (client) => client.invalidateQueries({ queryKey: KEYS.all }),
-		invalidateLists: (client) => client.invalidateQueries({ queryKey: KEYS.lists() }),
-		invalidateDetail: (client, id) => client.invalidateQueries({ queryKey: KEYS.detail(id) }),
-		setDetail: (client, id, data) => client.setQueryData(KEYS.detail(id), { data }),
-		getDetail: (client, id) => {
-			return client.getQueryData(KEYS.detail(id))?.data;
-		},
-		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 }) {
 	const queryClient = useQueryClient();
 	const query = useQuery({
@@ -255,6 +97,62 @@ function useInfiniteListQuery({ queryKey, queryFn, enabled = true, options = {},
 		data: query.data
 	};
 }
+/**
+* Generic query hook for non-CRUD reads (reports, aggregates, lookups, RPC-style
+* endpoints). Wraps TanStack Query with two ergonomics on top:
+*
+* 1. **Freshness presets.** Pass `freshness: 'realtime' | 'frequent' | 'stable' |
+*    'static'` to map onto `QUERY_CONFIGS`. Per-option overrides still win.
+* 2. **Standardized result shape.** `{ data, isLoading, isFetching, isError,
+*    isSuccess, isStale, error, refetch }` — same contract as the CRUD hooks.
+*
+* Arc emits raw data on success (no envelope), so the response IS the data.
+* Use `select` for shape transformations / multi-field projections.
+*
+* @example
+* // Direct typing — response IS the data
+* const { data } = useApiQuery<DashboardStats>({
+*   queryKey: ['dashboard', 'stats'],
+*   queryFn: ({ signal }) => api.request('GET', '/dashboard/stats', { options: { signal } }),
+*   freshness: 'realtime',
+* });
+*
+* // Custom projection (e.g. extract a sub-field)
+* const { data } = useApiQuery({
+*   queryKey: ['ledger', accountId],
+*   queryFn: ({ signal }) => api.request<{ entries: Entry[] }>('GET', `/ledger/${accountId}`, { options: { signal } }),
+*   select: (res) => res.entries,
+* });
+*/
+function useApiQuery({ queryKey, queryFn, enabled = true, freshness, select, options = {} }) {
+	const selectRef = useRef(select);
+	selectRef.current = select;
+	const projection = useCallback((response) => {
+		const fn = selectRef.current;
+		if (fn) return fn(response);
+		return response;
+	}, []);
+	const preset = freshness ? QUERY_CONFIGS[freshness] : void 0;
+	const query = useQuery({
+		queryKey,
+		queryFn: ({ signal }) => queryFn({ signal }),
+		enabled,
+		...DEFAULT_QUERY_CONFIG,
+		...preset,
+		...options,
+		select: projection
+	});
+	return {
+		data: query.data ?? null,
+		isLoading: query.isLoading,
+		isFetching: query.isFetching,
+		isError: query.isError,
+		isSuccess: query.isSuccess,
+		isStale: query.isStale,
+		error: query.error,
+		refetch: query.refetch
+	};
+}
 
 //#endregion
-export { DEFAULT_QUERY_CONFIG, QUERY_CONFIGS, createCacheUtils, createQueryKeys, extractItem, getItemId, updateListCache, useDetailQuery, useInfiniteListQuery, useListQuery };
+export { DEFAULT_QUERY_CONFIG, QUERY_CONFIGS, createCacheUtils, createQueryKeys, extractItem, extractItems, getItemId, normalizePagination, updateListCache, useApiQuery, useDetailQuery, useInfiniteListQuery, useListQuery };

package/dist/sse.d.ts

@@ -1,69 +1,148 @@
 import { QueryKey } from "@tanstack/react-query";
 
 //#region src/sse.d.ts
-interface ArcServerEvent {
+/**
+ * Build an authenticated SSE URL using the global client + auth singletons.
+ *
+ * Thin alias for {@link import('./client.js').buildStreamUrl} with the HTTP
+ * protocol — kept as a named export so SSE consumers don't have to think about
+ * the `protocol` arg.
+ *
+ * @example
+ * const es = new EventSource(buildSseUrl('/jobs/stream', { jobId }), {
+ *   withCredentials: getAuthMode() === 'cookie',
+ * });
+ */
+declare function buildSseUrl(path: string, params?: Record<string, string | number | boolean | null | undefined>): string;
+/**
+ * Generic Arc server event envelope.
+ *
+ * Defaults to `unknown` payload — narrow with the generic when you control
+ * the broadcast shape (`ArcServerEvent<Todo>`). For the canonical CRUD shape,
+ * use {@link CrudEvent} which constrains `type` to `<resource>.<operation>`
+ * and `operation` to the three lifecycle verbs.
+ */
+interface ArcServerEvent<TData = unknown> {
   type: string;
   resource: string;
-  data: unknown;
+  data: TData;
   timestamp: string;
   id?: string;
 }
-interface EventStreamOptions {
-  /** Full SSE endpoint URL. When set, overrides `path` and `baseUrl`. Use for non-Arc backends or custom URLs. */
+/** Lifecycle operations Arc emits on every CRUD broadcast. */
+type CrudOperation = "created" | "updated" | "deleted";
+/**
+ * Typed CRUD event narrowed to Arc's `<resource>.<operation>` envelope.
+ *
+ * Arc auto-emits this shape from `BaseController` for every list/get/create/
+ * update/delete. Pass `<TDoc>` so SSE/WS callbacks get inference for free:
+ *
+ * ```ts
+ * subscribeToEvents<CrudEvent<Todo>>({
+ *   resource: 'todo',
+ *   onEvent: (e) => console.log(e.operation, e.data.title),
+ * });
+ * ```
+ */
+interface CrudEvent<TDoc = unknown> extends ArcServerEvent<TDoc> {
+  /** Always `<resource>.<operation>` (e.g. `'todo.created'`). */
+  type: string;
+  operation: CrudOperation;
+}
+interface SubscribeToEventsOptions<TData = unknown> {
+  /** Full SSE endpoint URL. When set, overrides `path` and `baseUrl`. */
   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 name for auto pattern filtering + named-event derivation. */
   resource?: string;
-  /**
-   * SSE endpoint path (appended to baseUrl). Default: '/events/stream'.
-   * Matches Arc's ssePlugin default. Override if your backend uses a custom path.
-   */
+  /** Endpoint path (default: `/events/stream`). */
   path?: string;
-  /** Event patterns to listen for (e.g., ['agents.created', 'agents.updated']). When empty, all events are received. */
+  /** Event patterns to listen for (e.g. `['todo.*']`). Empty → all events. */
   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. */
+  /**
+   * Named SSE event types to subscribe to via `addEventListener`.
+   * Falls back to `patterns` (literal entries) or `[<resource>.created|updated|deleted]`.
+   * Pass `[]` to opt out of named-event subscription entirely.
+   */
+  eventTypes?: string[];
+  /** Per-event callback. */
+  onEvent?: (event: ArcServerEvent<TData>) => void;
+  /** Connection-state callback. */
   onConnectionChange?: (connected: boolean) => void;
-  /** Whether the stream is enabled. Default: true */
-  enabled?: boolean;
-  /** Reconnect delay in ms. Default: 3000 */
+  /** Reconnect delay in ms. Default: 3000. */
   reconnectDelay?: number;
-  /** Maximum reconnect attempts before giving up. Default: Infinity */
+  /** Maximum reconnect attempts. 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. */
+/** Handle returned by {@link subscribeToEvents}. Stable across reconnects. */
+interface SubscribeToEventsHandle {
+  close: () => void;
+  reconnect: () => void;
+  isConnected: () => boolean;
+}
+interface EventStreamOptions<TData = unknown> extends SubscribeToEventsOptions<TData> {
+  /** Query keys to invalidate when any matching event arrives. */
+  invalidateQueries?: QueryKey[];
+  /** Whether the stream is active. Default: true. */
+  enabled?: boolean;
+  /**
+   * Whether to track `lastEvent` in React state. Default: true.
+   *
+   * Set to `false` for high-volume streams (telemetry, live tickers) where
+   * the consumer uses `onEvent` for fire-and-forget handling and never reads
+   * `result.lastEvent`. Each inbound frame skips a `setState` call,
+   * eliminating per-event re-renders.
+   */
+  trackLastEvent?: boolean;
+  /**
+   * Whether to track `eventCount` in React state. Default: true.
+   *
+   * Same trade-off as `trackLastEvent`: skip the counter `setState` for
+   * high-volume streams that don't read it.
+   */
+  trackEventCount?: boolean;
+}
+interface EventStreamResult<TData = unknown> {
   isConnected: boolean;
-  /** The most recently received event. */
-  lastEvent: ArcServerEvent | null;
-  /** Number of events received since connection. */
+  lastEvent: ArcServerEvent<TData> | null;
   eventCount: number;
-  /** Close the connection manually. */
   close: () => void;
-  /** Reconnect after a manual close. */
   reconnect: () => void;
 }
+/**
+ * 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()`.
+ *
+ * Reconnect uses exponential backoff (×1.5 per attempt, capped at 30s).
+ * Subscriptions persist across reconnect.
+ *
+ * @example
+ * const sub = subscribeToEvents<CrudEvent<Todo>>({
+ *   resource: 'todo',
+ *   onEvent: (e) => console.log(e.operation, e.data.title),
+ * });
+ * // ...later
+ * sub.close();
+ */
+declare function subscribeToEvents<TData = unknown>(options: SubscribeToEventsOptions<TData>): SubscribeToEventsHandle;
 /**
  * Subscribe to Arc server-sent events for real-time cache invalidation.
  *
- * Uses the browser's native `EventSource` API for automatic reconnection
+ * Uses the browser's native `EventSource` for automatic reconnection
  * and efficient server-push. Events trigger query invalidation so TanStack Query
  * refetches affected data automatically.
  *
+ * Internally delegates to {@link subscribeToEvents} — for non-React contexts
+ * (Node, tests, plain JS) call that directly.
+ *
  * @example
- * const { isConnected } = useEventStream({
- *   resource: 'agents',
- *   invalidateQueries: [agentKeys.lists()],
+ * const { isConnected } = useEventStream<CrudEvent<Todo>>({
+ *   resource: 'todo',
+ *   invalidateQueries: [todoKeys.lists()],
  * });
  */
-declare function useEventStream(options: EventStreamOptions): EventStreamResult;
+declare function useEventStream<TData = unknown>(options: EventStreamOptions<TData>): EventStreamResult<TData>;
 //#endregion
-export { ArcServerEvent, EventStreamOptions, EventStreamResult, useEventStream };
+export { ArcServerEvent, CrudEvent, CrudOperation, EventStreamOptions, EventStreamResult, SubscribeToEventsHandle, SubscribeToEventsOptions, buildSseUrl, subscribeToEvents, useEventStream };