@classytic/arc-next 0.4.0 → 0.5.0

package/dist/presets/tree.js

@@ -0,0 +1,47 @@
+//#region src/presets/tree.ts
+/**
+* Adds tree preset methods to a BaseApi.
+*
+* Mirrors arc's `tree` preset — for resources with a `parentId` field, exposes
+* `getTree` (full hierarchy) and `getChildren` (one level deep). Backend caps
+* tree depth via the preset config.
+*
+* @example
+* import { withTree } from '@classytic/arc-next/presets/tree';
+* const categories = withTree(createCrudApi<Category>('categories'));
+*
+* const root = await categories.getTree();
+* const kids = await categories.getChildren({ parentId: 'engineering' });
+*/
+function withTree(api) {
+	return Object.assign(api, {
+		async getTree({ token = null, organizationId = null, params = {}, options = {} } = {}) {
+			const merged = {
+				...api.config.defaultParams,
+				...params
+			};
+			return api.request("GET", `${api.baseUrl}/tree`, {
+				token,
+				organizationId,
+				params: merged,
+				options
+			});
+		},
+		async getChildren({ token = null, organizationId = null, parentId, params = {}, options = {} }) {
+			if (!parentId) throw new Error("Parent ID is required");
+			const merged = {
+				...api.config.defaultParams,
+				...params
+			};
+			return api.request("GET", `${api.baseUrl}/${parentId}/children`, {
+				token,
+				organizationId,
+				params: merged,
+				options
+			});
+		}
+	});
+}
+
+//#endregion
+export { withTree };

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,50 +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;
-  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>;
-  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;
-}
-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: {
@@ -221,11 +166,88 @@ 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;
+/** Recognized data-freshness presets. Maps to QUERY_CONFIGS. */
+type QueryFreshness = keyof typeof QUERY_CONFIGS;
+/**
+ * Extracts the inner type of an Arc envelope `{ success, data: T }`.
+ * Falls through to `T` itself when the response isn't an envelope.
+ */
+type ExtractData<T> = T extends {
+  success: unknown;
+  data: infer D;
+} ? D : 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 hook auto-unwraps
+   * Arc envelopes (`{ success, data }`) and returns `data`. Non-envelope responses
+   * pass through unchanged.
+   */
+  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 three ergonomics on top:
+ *
+ * 1. **Envelope auto-unwrap.** `{ success, data: T }` responses are projected to
+ *    `T` automatically. Override with a custom `select` for shape changes or
+ *    multi-field projections.
+ * 2. **Freshness presets.** Pass `freshness: 'realtime' | 'frequent' | 'stable' |
+ *    'static'` to map onto `QUERY_CONFIGS`. Per-option overrides still win.
+ * 3. **Standardized result shape.** `{ data, isLoading, isFetching, isError,
+ *    isSuccess, isStale, error, refetch }` — same contract as the CRUD hooks.
+ *
+ * @example
+ * // Auto-unwrap envelope
+ * const { data } = useApiQuery<ApiResponse<DashboardStats>>({
+ *   queryKey: ['dashboard', 'stats'],
+ *   queryFn: ({ signal }) => api.request('GET', '/dashboard/stats', { options: { signal } }),
+ *   freshness: 'realtime',
+ * });
+ *
+ * // Custom projection
+ * const { data } = useApiQuery({
+ *   queryKey: ['ledger', accountId],
+ *   queryFn: ({ signal }) => api.request('GET', `/ledger/${accountId}`, { options: { signal } }),
+ *   select: (res) => res.data?.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, createDetailQuery, createInfiniteListQuery, createListQuery, 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,152 +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
-		],
-		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) })
-	};
-}
 function useListQuery({ queryKey, queryFn, enabled = true, options = {}, prefillDetailCache = true, detailKeyBuilder, itemIdResolver, select }) {
 	const queryClient = useQueryClient();
 	const query = useQuery({
@@ -239,12 +97,72 @@ 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;
+/**
+* Strict Arc envelope detector — requires BOTH `success` and `data` keys.
+*
+* Stricter than checking only `data` so we don't mis-unwrap responses that happen
+* to use a `data` field for unrelated semantics (e.g. a chart that returns
+* `{ data: number[], labels: [] }`).
+*/
+function isArcEnvelope(value) {
+	return typeof value === "object" && value !== null && "success" in value && "data" in value;
+}
+/**
+* Generic query hook for non-CRUD reads (reports, aggregates, lookups, RPC-style
+* endpoints). Wraps TanStack Query with three ergonomics on top:
+*
+* 1. **Envelope auto-unwrap.** `{ success, data: T }` responses are projected to
+*    `T` automatically. Override with a custom `select` for shape changes or
+*    multi-field projections.
+* 2. **Freshness presets.** Pass `freshness: 'realtime' | 'frequent' | 'stable' |
+*    'static'` to map onto `QUERY_CONFIGS`. Per-option overrides still win.
+* 3. **Standardized result shape.** `{ data, isLoading, isFetching, isError,
+*    isSuccess, isStale, error, refetch }` — same contract as the CRUD hooks.
+*
+* @example
+* // Auto-unwrap envelope
+* const { data } = useApiQuery<ApiResponse<DashboardStats>>({
+*   queryKey: ['dashboard', 'stats'],
+*   queryFn: ({ signal }) => api.request('GET', '/dashboard/stats', { options: { signal } }),
+*   freshness: 'realtime',
+* });
+*
+* // Custom projection
+* const { data } = useApiQuery({
+*   queryKey: ['ledger', accountId],
+*   queryFn: ({ signal }) => api.request('GET', `/ledger/${accountId}`, { options: { signal } }),
+*   select: (res) => res.data?.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 isArcEnvelope(response) ? response.data : 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, createDetailQuery, createInfiniteListQuery, createListQuery, 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,62 +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 {
-  /** SSE endpoint URL (absolute or relative to baseUrl). Default: `/{basePath}/{resource}/events/stream` */
+/** 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 used for the default endpoint path and event filtering. */
+  /** Resource name for auto pattern filtering + named-event derivation. */
   resource?: string;
-  /** Base path for the events endpoint. Default: '/api/v1' */
-  basePath?: string;
-  /** Event patterns to listen for (e.g., ['agents.created', 'agents.updated']). When empty, all events are received. */
+  /** Endpoint path (default: `/events/stream`). */
+  path?: string;
+  /** 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 };