@agentuity/react 0.0.100 → 0.0.101

package/src/client.ts

@@ -0,0 +1,148 @@
+import {
+	createClient as coreCreateClient,
+	type Client,
+	type ClientOptions,
+} from '@agentuity/frontend';
+
+/**
+ * RPC Route Registry interface that gets augmented by generated code.
+ * Applications should not define this directly - it's populated by the build system.
+ *
+ * @example
+ * ```typescript
+ * // Generated code augments this interface:
+ * declare module '@agentuity/react' {
+ *   export interface RPCRouteRegistry {
+ *     hello: { post: { input: HelloInput; output: HelloOutput; type: 'api' } };
+ *   }
+ * }
+ * ```
+ */
+// eslint-disable-next-line @typescript-eslint/no-empty-object-type
+export interface RPCRouteRegistry {}
+
+let globalBaseUrl: string | undefined;
+let globalAuthHeader: string | null | undefined;
+
+/**
+ * Set the global base URL for RPC clients.
+ * This is automatically called by AgentuityProvider.
+ * @internal
+ */
+export function setGlobalBaseUrl(url: string): void {
+	globalBaseUrl = url;
+}
+
+/**
+ * Get the global base URL for RPC clients.
+ * Returns the configured base URL or falls back to window.location.origin.
+ * @internal
+ */
+export function getGlobalBaseUrl(): string {
+	return globalBaseUrl || (typeof window !== 'undefined' ? window.location.origin : '');
+}
+
+/**
+ * Set the global auth header for RPC clients.
+ * This is automatically called by AgentuityProvider when auth state changes.
+ * @internal
+ */
+export function setGlobalAuthHeader(authHeader: string | null): void {
+	globalAuthHeader = authHeader;
+}
+
+/**
+ * Get the global auth header for RPC clients.
+ * Returns the current auth header or undefined if not set.
+ * @internal
+ */
+export function getGlobalAuthHeader(): string | null | undefined {
+	return globalAuthHeader;
+}
+
+/**
+ * Create a type-safe RPC client for React applications.
+ *
+ * This is a React-specific wrapper around @agentuity/core's createClient that
+ * automatically uses the baseUrl and auth headers from AgentuityProvider context.
+ *
+ * @example
+ * ```typescript
+ * import { createClient } from '@agentuity/react';
+ * import type { RPCRouteRegistry } from '@agentuity/react';
+ *
+ * const client = createClient<RPCRouteRegistry>();
+ *
+ * // Inside component
+ * const result = await client.hello.post({ name: 'World' });
+ * ```
+ */
+export function createClient<R>(
+	options?: Omit<ClientOptions, 'baseUrl' | 'headers'> & {
+		baseUrl?: string | (() => string);
+		headers?: Record<string, string> | (() => Record<string, string>);
+	},
+	metadata?: unknown
+): Client<R> {
+	// Merge user headers with auth headers
+	// User-provided headers take precedence over global auth header
+	const mergedHeaders = (): Record<string, string> => {
+		const authHeader = getGlobalAuthHeader();
+		const userHeaders =
+			typeof options?.headers === 'function' ? options.headers() : options?.headers || {};
+
+		const headers: Record<string, string> = {};
+
+		// Add global auth header first (lower priority)
+		if (authHeader) {
+			headers.Authorization = authHeader;
+		}
+
+		// User headers override global auth
+		return { ...headers, ...userHeaders };
+	};
+
+	return coreCreateClient<R>(
+		{
+			...options,
+			baseUrl: (options?.baseUrl || getGlobalBaseUrl) as string | (() => string),
+			headers: mergedHeaders,
+		} as ClientOptions,
+		metadata
+	);
+}
+
+/**
+ * Create a type-safe API client with optional configuration.
+ *
+ * This is the recommended way to create an API client in React applications.
+ * It automatically includes auth headers from AgentuityProvider and allows
+ * custom headers to be passed.
+ *
+ * The generic type parameter defaults to RPCRouteRegistry which is augmented
+ * by generated code, so you don't need to specify it manually.
+ *
+ * @example
+ * ```typescript
+ * import { createAPIClient } from '@agentuity/react';
+ *
+ * // Types are automatically inferred from generated routes
+ * const api = createAPIClient();
+ * await api.hello.post({ name: 'World' });
+ *
+ * // With custom headers
+ * const api = createAPIClient({ headers: { 'X-Custom': 'value' } });
+ * await api.hello.post({ name: 'World' });
+ * ```
+ */
+export function createAPIClient<R = RPCRouteRegistry>(
+	options?: Omit<ClientOptions, 'baseUrl' | 'headers'> & {
+		baseUrl?: string | (() => string);
+		headers?: Record<string, string> | (() => Record<string, string>);
+	}
+): Client<R> {
+	// This function is designed to be used with generated metadata
+	// The metadata will be provided by the code generator
+	// eslint-disable-next-line @typescript-eslint/no-explicit-any
+	return createClient<R>(options, (globalThis as any).__rpcRouteMetadata);
+}

package/src/context.tsx

@@ -1,10 +1,12 @@
-import React, { useState } from 'react';
-import { createContext, useContext, type Context, type ReactElement } from 'react';
-import { defaultBaseUrl } from './url';
+import React, { useState, useEffect } from 'react';
+import { createContext, useContext, type Context } from 'react';
+import { defaultBaseUrl } from '@agentuity/frontend';
+import { setGlobalBaseUrl, setGlobalAuthHeader } from './client';
 
 export interface ContextProviderArgs {
 	children?: React.ReactNode;
 	baseUrl?: string;
+	authHeader?: string | null;
 }
 
 export interface AgentuityContextValue {
@@ -18,14 +20,36 @@ export interface AgentuityContextValue {
 export const AgentuityContext: Context<AgentuityContextValue | null> =
 	createContext<AgentuityContextValue | null>(null);
 
-export const AgentuityProvider = ({ baseUrl, children }: ContextProviderArgs): ReactElement => {
-	const [authHeader, setAuthHeader] = useState<string | null>(null);
+export const AgentuityProvider = ({
+	baseUrl,
+	authHeader: authHeaderProp,
+	children,
+}: ContextProviderArgs): React.JSX.Element => {
+	const [authHeader, setAuthHeader] = useState<string | null>(authHeaderProp ?? null);
 	const [authLoading, setAuthLoading] = useState<boolean>(false);
+	const resolvedBaseUrl = baseUrl || defaultBaseUrl;
+
+	// Set global baseUrl for RPC clients
+	useEffect(() => {
+		setGlobalBaseUrl(resolvedBaseUrl);
+	}, [resolvedBaseUrl]);
+
+	// Sync authHeader to global state for RPC clients
+	useEffect(() => {
+		setGlobalAuthHeader(authHeader);
+	}, [authHeader]);
+
+	// Sync authHeader prop changes to state
+	useEffect(() => {
+		if (authHeaderProp !== undefined) {
+			setAuthHeader(authHeaderProp);
+		}
+	}, [authHeaderProp]);
 
 	return (
 		<AgentuityContext.Provider
 			value={{
-				baseUrl: baseUrl || defaultBaseUrl,
+				baseUrl: resolvedBaseUrl,
 				authHeader,
 				setAuthHeader,
 				authLoading,

package/src/eventstream.ts

@@ -1,13 +1,12 @@
 import { useCallback, useContext, useEffect, useMemo, useRef, useState } from 'react';
 import type { InferOutput } from '@agentuity/core';
+import {
+	buildUrl,
+	EventStreamManager,
+	jsonEqual,
+	type SSERouteRegistry,
+} from '@agentuity/frontend';
 import { AgentuityContext } from './context';
-import { buildUrl } from './url';
-import { deserializeData } from './serialization';
-import { createReconnectManager } from './reconnect';
-import { jsonEqual } from './memo';
-import type { SSERouteRegistry } from './types';
-
-type onMessageHandler<T = unknown> = (data: T) => void;
 
 /**
  * Extract SSE route keys (e.g., '/events', '/notifications')
@@ -43,216 +42,117 @@ export interface EventStreamOptions {
 	signal?: AbortSignal;
 }
 
-interface EventStreamResponseInternal<TOutput> {
-	/** Whether EventStream is currently connected */
+/**
+ * Type-safe EventStream (SSE) hook for connecting to SSE routes.
+ *
+ * Provides automatic type inference for route outputs based on
+ * the SSERouteRegistry generated from your routes.
+ *
+ * @template TRoute - SSE route key from SSERouteRegistry (e.g., '/events', '/notifications')
+ *
+ * @example Simple SSE connection
+ * ```typescript
+ * const { isConnected, data } = useEventStream('/events');
+ *
+ * // data is fully typed based on route output schema!
+ * ```
+ *
+ * @example SSE with query parameters
+ * ```typescript
+ * const { isConnected, data } = useEventStream('/notifications', {
+ *   query: new URLSearchParams({ userId: '123' })
+ * });
+ * ```
+ */
+export function useEventStream<TRoute extends SSERouteKey>(
+	route: TRoute,
+	options?: EventStreamOptions
+): {
 	isConnected: boolean;
-	/** Most recent data received from EventStream */
-	data?: TOutput;
-	/** Error if connection or message failed */
+	close: () => void;
+	data?: SSERouteOutput<TRoute>;
 	error: Error | null;
-	/** Whether an error has occurred */
 	isError: boolean;
-	/** Set handler for incoming messages (use data property instead) */
-	setHandler: (handler: onMessageHandler<TOutput>) => void;
-	/** EventStream connection state (CONNECTING=0, OPEN=1, CLOSED=2) */
-	readyState: number;
-	/** Close the EventStream connection */
-	close: () => void;
-	/** Reset state to initial values */
 	reset: () => void;
-}
-
-const useEventStreamInternal = <TOutput>(
-	path: string,
-	options?: EventStreamOptions
-): EventStreamResponseInternal<TOutput> => {
+	readyState: number;
+} {
 	const context = useContext(AgentuityContext);
 
 	if (!context) {
 		throw new Error('useEventStream must be used within a AgentuityProvider');
 	}
 
-	const manualClose = useRef(false);
-	const esRef = useRef<EventSource | undefined>(undefined);
-	const pending = useRef<TOutput[]>([]);
-	const handler = useRef<onMessageHandler<TOutput> | undefined>(undefined);
-	const reconnectManagerRef = useRef<ReturnType<typeof createReconnectManager> | undefined>(
-		undefined
-	);
+	const managerRef = useRef<EventStreamManager<SSERouteOutput<TRoute>> | null>(null);
 
-	const [data, setData] = useState<TOutput>();
+	const [data, setData] = useState<SSERouteOutput<TRoute>>();
 	const [error, setError] = useState<Error | null>(null);
 	const [isError, setIsError] = useState(false);
 	const [isConnected, setIsConnected] = useState(false);
+	const [readyState, setReadyState] = useState<number>(2); // EventSource.CLOSED = 2
 
+	// Build EventStream URL
 	const esUrl = useMemo(
-		() => buildUrl(context.baseUrl!, path, options?.subpath, options?.query),
-		[context.baseUrl, path, options?.subpath, options?.query?.toString()]
+		() => buildUrl(context.baseUrl!, route as string, options?.subpath, options?.query),
+		[context.baseUrl, route, options?.subpath, options?.query?.toString()]
 	);
 
-	const connect = useCallback(() => {
-		if (manualClose.current) return;
-
-		esRef.current = new EventSource(esUrl);
-		let firstMessageReceived = false;
-
-		esRef.current.onopen = () => {
-			reconnectManagerRef.current?.recordSuccess();
-			setIsConnected(true);
-			setError(null);
-			setIsError(false);
-		};
-
-		esRef.current.onerror = () => {
-			setError(new Error('EventStream error'));
-			setIsError(true);
-			setIsConnected(false);
-
-			if (manualClose.current) {
-				return;
-			}
-
-			const result = reconnectManagerRef.current?.recordFailure();
-			if (result?.scheduled) {
-				const es = esRef.current;
-				if (es) {
-					es.onopen = null;
-					es.onerror = null;
-					es.onmessage = null;
-					es.close();
-				}
-				esRef.current = undefined;
-			}
-		};
-
-		esRef.current.onmessage = (event: MessageEvent) => {
-			if (!firstMessageReceived) {
-				reconnectManagerRef.current?.recordSuccess();
-				firstMessageReceived = true;
-			}
-			const payload = deserializeData<TOutput>(event.data);
-			// Use JSON memoization to prevent re-renders when data hasn't changed
-			setData((prev) => (prev !== undefined && jsonEqual(prev, payload) ? prev : payload));
-			if (handler.current) {
-				handler.current(payload);
-			} else {
-				pending.current.push(payload);
-			}
-		};
-	}, [esUrl]);
-
+	// Initialize manager and connect
 	useEffect(() => {
-		reconnectManagerRef.current = createReconnectManager({
-			onReconnect: connect,
-			threshold: 3,
-			baseDelay: 500,
-			factor: 2,
-			maxDelay: 30000,
-			jitter: 250,
-			enabled: () => !manualClose.current,
+		const manager = new EventStreamManager<SSERouteOutput<TRoute>>({
+			url: esUrl,
+			callbacks: {
+				onConnect: () => {
+					setIsConnected(true);
+					setError(null);
+					setIsError(false);
+					setReadyState(1); // EventSource.OPEN = 1
+				},
+				onDisconnect: () => {
+					setIsConnected(false);
+					setReadyState(2); // EventSource.CLOSED = 2
+				},
+				onError: (err) => {
+					setError(err);
+					setIsError(true);
+				},
+			},
 		});
-		return () => reconnectManagerRef.current?.dispose();
-	}, [connect]);
 
-	const cleanup = useCallback(() => {
-		manualClose.current = true;
-		reconnectManagerRef.current?.dispose();
-		const es = esRef.current;
-		if (es) {
-			es.onopen = null;
-			es.onerror = null;
-			es.onmessage = null;
-			es.close();
-		}
-		esRef.current = undefined;
-		handler.current = undefined;
-		pending.current = [];
-		setIsConnected(false);
-	}, []);
+		// Set message handler with JSON memoization
+		manager.setMessageHandler((message) => {
+			setData((prev) => (prev !== undefined && jsonEqual(prev, message) ? prev : message));
+		});
 
-	useEffect(() => {
-		manualClose.current = false;
-		connect();
+		manager.connect();
+		managerRef.current = manager;
 
 		return () => {
-			cleanup();
+			manager.dispose();
+			managerRef.current = null;
 		};
-	}, [connect, cleanup]);
+	}, [esUrl]);
 
+	// Handle abort signal
 	useEffect(() => {
 		if (options?.signal) {
 			const listener = () => {
-				cleanup();
+				managerRef.current?.close();
 			};
 			options.signal.addEventListener('abort', listener);
 			return () => {
 				options.signal?.removeEventListener('abort', listener);
 			};
 		}
-	}, [options?.signal, cleanup]);
+	}, [options?.signal]);
 
-	const reset = () => {
+	const reset = useCallback(() => {
 		setError(null);
 		setIsError(false);
-	};
-
-	const setHandler = useCallback((h: onMessageHandler<TOutput>) => {
-		handler.current = h;
-		pending.current.forEach(h);
-		pending.current = [];
 	}, []);
 
-	const close = () => {
-		cleanup();
-	};
-
-	return {
-		isConnected,
-		close,
-		data,
-		error,
-		isError,
-		setHandler,
-		reset,
-		readyState: esRef.current?.readyState ?? EventSource.CLOSED,
-	};
-};
-
-/**
- * Type-safe EventStream (SSE) hook for connecting to SSE routes.
- *
- * Provides automatic type inference for route outputs based on
- * the SSERouteRegistry generated from your routes.
- *
- * @template TRoute - SSE route key from SSERouteRegistry (e.g., '/events', '/notifications')
- *
- * @example Simple SSE connection
- * ```typescript
- * const { isConnected, data } = useEventStream('/events');
- *
- * // data is fully typed based on route output schema!
- * ```
- *
- * @example SSE with query parameters
- * ```typescript
- * const { isConnected, data } = useEventStream('/notifications', {
- *   query: new URLSearchParams({ userId: '123' })
- * });
- * ```
- */
-export function useEventStream<TRoute extends SSERouteKey>(
-	route: TRoute,
-	options?: EventStreamOptions
-): Omit<EventStreamResponseInternal<SSERouteOutput<TRoute>>, 'setHandler'> & {
-	data?: SSERouteOutput<TRoute>;
-} {
-	const [data, setData] = useState<SSERouteOutput<TRoute>>();
-	const { isConnected, close, setHandler, readyState, error, isError, reset } =
-		useEventStreamInternal<SSERouteOutput<TRoute>>(route as string, options);
-
-	useEffect(() => {
-		setHandler(setData);
-	}, [route, setHandler]);
+	const close = useCallback(() => {
+		managerRef.current?.close();
+	}, []);
 
 	return {
 		isConnected,

package/src/index.ts

@@ -8,6 +8,15 @@ export {
 	type AgentuityHookValue,
 	type AuthContextValue,
 } from './context';
+export {
+	createClient,
+	createAPIClient,
+	setGlobalBaseUrl,
+	getGlobalBaseUrl,
+	setGlobalAuthHeader,
+	getGlobalAuthHeader,
+	type RPCRouteRegistry,
+} from './client';
 export {
 	useWebsocket,
 	type WebSocketRouteKey,
@@ -21,7 +30,6 @@ export {
 	type SSERouteOutput,
 	type EventStreamOptions,
 } from './eventstream';
-export { type RouteRegistry, type WebSocketRouteRegistry, type SSERouteRegistry } from './types';
 export {
 	useAPI,
 	type RouteKey,
@@ -32,5 +40,37 @@ export {
 	type UseAPIOptions,
 	type UseAPIResult,
 } from './api';
-export { jsonEqual, useJsonMemo } from './memo';
-export { buildUrl, defaultBaseUrl } from './url';
+export { useJsonMemo } from './memo';
+
+// Re-export web utilities for convenience
+export {
+	buildUrl,
+	defaultBaseUrl,
+	deserializeData,
+	createReconnectManager,
+	jsonEqual,
+	getProcessEnv,
+	WebSocketManager,
+	EventStreamManager,
+	type RouteRegistry,
+	type WebSocketRouteRegistry,
+	type SSERouteRegistry,
+	type ReconnectOptions,
+	type ReconnectManager,
+	type WebSocketMessageHandler,
+	type WebSocketCallbacks,
+	type WebSocketManagerOptions,
+	type WebSocketManagerState,
+	type EventStreamMessageHandler,
+	type EventStreamCallbacks,
+	type EventStreamManagerOptions,
+	type EventStreamManagerState,
+	// Client type exports (createClient is exported from ./client.ts)
+	type Client,
+	type ClientOptions,
+	type RouteEndpoint,
+	type WebSocketClient,
+	type EventStreamClient,
+	type StreamClient,
+	type EventHandler,
+} from '@agentuity/frontend';

package/src/memo.ts

@@ -1,26 +1,10 @@
-/**
- * Simple JSON-based equality check for memoization.
- * Compares stringified JSON to avoid deep equality overhead.
- */
-export function jsonEqual<T>(a: T, b: T): boolean {
-	if (a === b) return true;
-	if (a === undefined || b === undefined) return false;
-	if (a === null || b === null) return a === b;
-
-	try {
-		return JSON.stringify(a) === JSON.stringify(b);
-	} catch {
-		// Fallback for non-serializable values
-		return false;
-	}
-}
+import { useRef } from 'react';
+import { jsonEqual } from '@agentuity/frontend';
 
 /**
  * Hook to memoize a value based on JSON equality instead of reference equality.
  * Prevents unnecessary re-renders when data hasn't actually changed.
  */
-import { useRef } from 'react';
-
 export function useJsonMemo<T>(value: T): T {
 	const ref = useRef<T>(value);