@voxdiscover/voiceserver-react 0.1.0

package/dist/index.d.cts

@@ -0,0 +1,334 @@
+import * as react_jsx_runtime from 'react/jsx-runtime';
+import * as react from 'react';
+import { ReactNode, Dispatch, SetStateAction } from 'react';
+import { VoiceAgentConfig, VoiceAgent, ConnectionState, TranscriptData } from '@voxdiscover/voiceserver';
+export * from '@voxdiscover/voiceserver';
+export { ConnectionState, ReconnectionManager, TranscriptData, VoiceAgent, VoiceAgentConfig, VoiceAgentErrorCode, VoiceAgentEvents } from '@voxdiscover/voiceserver';
+
+/**
+ * Props for VoiceAgentProvider component.
+ * Per user decision: Config object pattern for flexibility.
+ */
+interface VoiceAgentProviderProps extends VoiceAgentConfig {
+    children: ReactNode;
+    /** Callback when connection is established */
+    onConnect?: () => void;
+    /** Callback when connection is closed */
+    onDisconnect?: () => void;
+    /** Callback for connection errors */
+    onError?: (error: Error) => void;
+}
+/**
+ * Context provider for VoiceAgent instance.
+ *
+ * Per user decisions:
+ * - Creates VoiceAgent instance but waits for explicit connect() call (manual connect pattern)
+ * - Auto-disconnects and cleans up WebRTC resources on unmount
+ * - Provides stable agent reference via useRef (prevents re-render cascades)
+ *
+ * @example
+ * ```tsx
+ * function App() {
+ *   return (
+ *     <VoiceAgentProvider
+ *       token={sessionToken}
+ *       onConnect={() => console.log('Connected!')}
+ *       onError={(err) => console.error('Error:', err)}
+ *     >
+ *       <VoiceChat />
+ *     </VoiceAgentProvider>
+ *   );
+ * }
+ * ```
+ */
+declare function VoiceAgentProvider({ children, token, baseUrl, reconnection, onConnect, onDisconnect, onError, }: VoiceAgentProviderProps): react_jsx_runtime.JSX.Element;
+
+/**
+ * Context value containing VoiceAgent instance and token.
+ * Per user decision: Context only holds agent instance, not UI state.
+ * Token included for session ID extraction (transcript persistence).
+ */
+interface VoiceAgentContextValue {
+    agent: VoiceAgent | null;
+    token: string;
+}
+/**
+ * React context for VoiceAgent instance.
+ * Provides stable reference to agent across component tree.
+ *
+ * @example
+ * ```tsx
+ * const context = useContext(VoiceAgentContext);
+ * if (!context?.agent) throw new Error('No agent available');
+ * ```
+ */
+declare const VoiceAgentContext: react.Context<VoiceAgentContextValue | null>;
+
+/**
+ * Retry state exposed for UI feedback.
+ * Per user decision: UI can display attempt count and countdown timer.
+ */
+interface RetryState {
+    /** Whether a retry is currently in progress */
+    isRetrying: boolean;
+    /** Current retry attempt number (0-based) */
+    attempt: number;
+    /** Maximum retry attempts configured */
+    maxAttempts: number;
+    /** Milliseconds until next retry attempt */
+    nextRetryIn: number;
+}
+/**
+ * Hook providing automatic retry logic with exponential backoff.
+ *
+ * Per RESEARCH.md Pattern 4 and user decision:
+ * - Exponential backoff: delay = min(1000 * 2^(attempt-1), 10000)
+ * - Countdown timer updates every 100ms for UI feedback
+ * - Reset retry state on success
+ * - Keep attempt count on failure for next retry
+ *
+ * @param connectFn - Async function to retry (typically agent.connect)
+ * @param maxAttempts - Maximum retry attempts (default: 5)
+ * @returns Retry state and retry function
+ *
+ * @example
+ * ```typescript
+ * const { retryState, retry } = useConnectionRetry(
+ *   async () => agent.connect(),
+ *   5
+ * );
+ *
+ * // Show retry UI
+ * if (retryState.isRetrying) {
+ *   return <div>Retrying... ({retryState.attempt}/{retryState.maxAttempts})
+ *           Next attempt in {Math.ceil(retryState.nextRetryIn / 1000)}s</div>
+ * }
+ *
+ * // Manual retry
+ * <button onClick={retry}>Retry Connection</button>
+ * ```
+ */
+declare function useConnectionRetry(connectFn: () => Promise<void>, maxAttempts?: number): {
+    retryState: RetryState;
+    retry: () => Promise<void>;
+};
+
+/**
+ * Return type for useVoiceAgent hook.
+ * Per user decision: Flat return structure with all properties at top level.
+ */
+interface UseVoiceAgentReturn {
+    /** Raw VoiceAgent instance for advanced use cases */
+    agent: VoiceAgent;
+    /** Current connection state */
+    callState: ConnectionState;
+    /** All transcripts accumulated during session */
+    transcripts: TranscriptData[];
+    /** Current error, if any (auto-cleared on success) */
+    error: Error | null;
+    /** Derived: true if callState === 'connected' */
+    isConnected: boolean;
+    /** Derived: true if callState === 'connecting' */
+    isConnecting: boolean;
+    /** Derived: true if callState === 'reconnecting' */
+    isReconnecting: boolean;
+    /** Retry state for UI feedback (attempt count, countdown) */
+    retryState: RetryState;
+    /** Connect to voice session */
+    connect: () => Promise<void>;
+    /** Disconnect from voice session */
+    disconnect: () => Promise<void>;
+    /** Mute microphone */
+    mute: () => void;
+    /** Unmute microphone */
+    unmute: () => void;
+    /** Manual retry connection (with exponential backoff) */
+    retryConnect: () => Promise<void>;
+}
+/**
+ * Comprehensive hook for VoiceAgent functionality.
+ *
+ * Per user decision:
+ * - Single comprehensive hook returning everything (not multiple focused hooks)
+ * - Flat return structure with all properties at top level
+ * - Includes raw agent instance for advanced use cases
+ * - Unlimited transcript accumulation in memory during session
+ * - Auto-clear errors when next action succeeds
+ *
+ * Per RESEARCH.md patterns:
+ * - Uses useSyncExternalStore for connection state (concurrent-safe)
+ * - Uses useState for transcripts and errors
+ * - Proper cleanup in useEffect to prevent memory leaks
+ * - useCallback for wrapped methods
+ *
+ * @throws {Error} When used outside VoiceAgentProvider
+ *
+ * @example
+ * ```tsx
+ * function VoiceChat() {
+ *   const {
+ *     connect,
+ *     disconnect,
+ *     mute,
+ *     unmute,
+ *     callState,
+ *     transcripts,
+ *     error,
+ *     isConnected,
+ *   } = useVoiceAgent();
+ *
+ *   return (
+ *     <div>
+ *       <button onClick={connect} disabled={isConnected}>
+ *         {isConnected ? 'Connected' : 'Connect'}
+ *       </button>
+ *       {error && <div>Error: {error.message}</div>}
+ *       <div>
+ *         {transcripts.map((t, i) => (
+ *           <p key={i}>{t.speaker}: {t.text}</p>
+ *         ))}
+ *       </div>
+ *     </div>
+ *   );
+ * }
+ * ```
+ */
+declare function useVoiceAgent(): UseVoiceAgentReturn;
+
+/**
+ * Hook to persist transcripts to sessionStorage.
+ *
+ * Per RESEARCH.md Pattern 3 and user decision:
+ * - Load persisted transcripts on mount
+ * - Save transcripts to sessionStorage on change
+ * - Clear on unmount (sessionStorage auto-clears on tab close)
+ * - Handle errors silently (log to console, don't crash)
+ * - No limits on transcript array size (browser quota is the limit)
+ *
+ * Per RESEARCH.md Pitfall 4:
+ * - Uses SSR-safe storage utilities
+ * - Won't crash in Next.js/Remix server-side rendering
+ *
+ * @param sessionId - Session ID to namespace storage key
+ * @param transcripts - Current transcripts array
+ * @param setTranscripts - State setter to restore transcripts
+ *
+ * @example
+ * ```typescript
+ * const [transcripts, setTranscripts] = useState<TranscriptData[]>([]);
+ * useTranscriptPersistence(sessionId, transcripts, setTranscripts);
+ * ```
+ */
+declare function useTranscriptPersistence(sessionId: string, transcripts: TranscriptData[], setTranscripts: Dispatch<SetStateAction<TranscriptData[]>>): void;
+
+/**
+ * SSR-safe sessionStorage utilities.
+ *
+ * Per RESEARCH.md Pitfall 4:
+ * - Guard with typeof window !== 'undefined' check
+ * - Wrap in try-catch (storage can be disabled or full)
+ * - Return null/false on error or SSR
+ *
+ * @packageDocumentation
+ */
+/**
+ * Get item from sessionStorage in SSR-safe manner.
+ * Returns null if running in SSR, storage disabled, or key doesn't exist.
+ *
+ * @param key - Storage key
+ * @returns Value or null
+ *
+ * @example
+ * ```typescript
+ * const transcripts = getSessionStorage('voice-agent-transcripts');
+ * if (transcripts) {
+ *   // Use transcripts
+ * }
+ * ```
+ */
+declare function getSessionStorage(key: string): string | null;
+/**
+ * Set item in sessionStorage in SSR-safe manner.
+ * Returns true on success, false on failure (SSR, quota exceeded, disabled).
+ *
+ * @param key - Storage key
+ * @param value - Value to store
+ * @returns Success flag
+ *
+ * @example
+ * ```typescript
+ * const success = setSessionStorage('voice-agent-transcripts', JSON.stringify(transcripts));
+ * if (!success) {
+ *   console.warn('Failed to persist transcripts');
+ * }
+ * ```
+ */
+declare function setSessionStorage(key: string, value: string): boolean;
+/**
+ * Remove item from sessionStorage in SSR-safe manner.
+ * Returns true on success, false on failure (SSR, disabled).
+ *
+ * @param key - Storage key
+ * @returns Success flag
+ *
+ * @example
+ * ```typescript
+ * removeSessionStorage('voice-agent-transcripts-session-123');
+ * ```
+ */
+declare function removeSessionStorage(key: string): boolean;
+/**
+ * Get and parse JSON from sessionStorage.
+ * Returns null if parsing fails, SSR, or key doesn't exist.
+ *
+ * @param key - Storage key
+ * @returns Parsed value or null
+ *
+ * @example
+ * ```typescript
+ * const transcripts = getSessionStorageJSON<TranscriptData[]>('voice-agent-transcripts');
+ * if (transcripts) {
+ *   // Use typed transcripts array
+ * }
+ * ```
+ */
+declare function getSessionStorageJSON<T>(key: string): T | null;
+/**
+ * Stringify and store JSON in sessionStorage.
+ * Returns true on success, false on failure (SSR, quota, parse error).
+ *
+ * @param key - Storage key
+ * @param value - Value to stringify and store
+ * @returns Success flag
+ *
+ * @example
+ * ```typescript
+ * const success = setSessionStorageJSON('voice-agent-transcripts', transcripts);
+ * if (!success) {
+ *   console.warn('Failed to persist transcripts');
+ * }
+ * ```
+ */
+declare function setSessionStorageJSON<T>(key: string, value: T): boolean;
+
+/**
+ * Simple JWT token decoder for extracting session ID.
+ * Per plan: Client-side JWT decoding (backend already validated).
+ */
+/**
+ * Extract session ID from JWT session token.
+ * Uses atob() for browser compatibility.
+ *
+ * @param token - JWT session token
+ * @returns Session ID string
+ * @throws {Error} If token is malformed
+ *
+ * @example
+ * ```typescript
+ * const sessionId = extractSessionId(sessionToken);
+ * // Use sessionId for storage key
+ * ```
+ */
+declare function extractSessionId(token: string): string;
+
+export { type RetryState, type UseVoiceAgentReturn, VoiceAgentContext, type VoiceAgentContextValue, VoiceAgentProvider, type VoiceAgentProviderProps, extractSessionId, getSessionStorage, getSessionStorageJSON, removeSessionStorage, setSessionStorage, setSessionStorageJSON, useConnectionRetry, useTranscriptPersistence, useVoiceAgent };

package/dist/index.d.ts

@@ -0,0 +1,334 @@
+import * as react_jsx_runtime from 'react/jsx-runtime';
+import * as react from 'react';
+import { ReactNode, Dispatch, SetStateAction } from 'react';
+import { VoiceAgentConfig, VoiceAgent, ConnectionState, TranscriptData } from '@voxdiscover/voiceserver';
+export * from '@voxdiscover/voiceserver';
+export { ConnectionState, ReconnectionManager, TranscriptData, VoiceAgent, VoiceAgentConfig, VoiceAgentErrorCode, VoiceAgentEvents } from '@voxdiscover/voiceserver';
+
+/**
+ * Props for VoiceAgentProvider component.
+ * Per user decision: Config object pattern for flexibility.
+ */
+interface VoiceAgentProviderProps extends VoiceAgentConfig {
+    children: ReactNode;
+    /** Callback when connection is established */
+    onConnect?: () => void;
+    /** Callback when connection is closed */
+    onDisconnect?: () => void;
+    /** Callback for connection errors */
+    onError?: (error: Error) => void;
+}
+/**
+ * Context provider for VoiceAgent instance.
+ *
+ * Per user decisions:
+ * - Creates VoiceAgent instance but waits for explicit connect() call (manual connect pattern)
+ * - Auto-disconnects and cleans up WebRTC resources on unmount
+ * - Provides stable agent reference via useRef (prevents re-render cascades)
+ *
+ * @example
+ * ```tsx
+ * function App() {
+ *   return (
+ *     <VoiceAgentProvider
+ *       token={sessionToken}
+ *       onConnect={() => console.log('Connected!')}
+ *       onError={(err) => console.error('Error:', err)}
+ *     >
+ *       <VoiceChat />
+ *     </VoiceAgentProvider>
+ *   );
+ * }
+ * ```
+ */
+declare function VoiceAgentProvider({ children, token, baseUrl, reconnection, onConnect, onDisconnect, onError, }: VoiceAgentProviderProps): react_jsx_runtime.JSX.Element;
+
+/**
+ * Context value containing VoiceAgent instance and token.
+ * Per user decision: Context only holds agent instance, not UI state.
+ * Token included for session ID extraction (transcript persistence).
+ */
+interface VoiceAgentContextValue {
+    agent: VoiceAgent | null;
+    token: string;
+}
+/**
+ * React context for VoiceAgent instance.
+ * Provides stable reference to agent across component tree.
+ *
+ * @example
+ * ```tsx
+ * const context = useContext(VoiceAgentContext);
+ * if (!context?.agent) throw new Error('No agent available');
+ * ```
+ */
+declare const VoiceAgentContext: react.Context<VoiceAgentContextValue | null>;
+
+/**
+ * Retry state exposed for UI feedback.
+ * Per user decision: UI can display attempt count and countdown timer.
+ */
+interface RetryState {
+    /** Whether a retry is currently in progress */
+    isRetrying: boolean;
+    /** Current retry attempt number (0-based) */
+    attempt: number;
+    /** Maximum retry attempts configured */
+    maxAttempts: number;
+    /** Milliseconds until next retry attempt */
+    nextRetryIn: number;
+}
+/**
+ * Hook providing automatic retry logic with exponential backoff.
+ *
+ * Per RESEARCH.md Pattern 4 and user decision:
+ * - Exponential backoff: delay = min(1000 * 2^(attempt-1), 10000)
+ * - Countdown timer updates every 100ms for UI feedback
+ * - Reset retry state on success
+ * - Keep attempt count on failure for next retry
+ *
+ * @param connectFn - Async function to retry (typically agent.connect)
+ * @param maxAttempts - Maximum retry attempts (default: 5)
+ * @returns Retry state and retry function
+ *
+ * @example
+ * ```typescript
+ * const { retryState, retry } = useConnectionRetry(
+ *   async () => agent.connect(),
+ *   5
+ * );
+ *
+ * // Show retry UI
+ * if (retryState.isRetrying) {
+ *   return <div>Retrying... ({retryState.attempt}/{retryState.maxAttempts})
+ *           Next attempt in {Math.ceil(retryState.nextRetryIn / 1000)}s</div>
+ * }
+ *
+ * // Manual retry
+ * <button onClick={retry}>Retry Connection</button>
+ * ```
+ */
+declare function useConnectionRetry(connectFn: () => Promise<void>, maxAttempts?: number): {
+    retryState: RetryState;
+    retry: () => Promise<void>;
+};
+
+/**
+ * Return type for useVoiceAgent hook.
+ * Per user decision: Flat return structure with all properties at top level.
+ */
+interface UseVoiceAgentReturn {
+    /** Raw VoiceAgent instance for advanced use cases */
+    agent: VoiceAgent;
+    /** Current connection state */
+    callState: ConnectionState;
+    /** All transcripts accumulated during session */
+    transcripts: TranscriptData[];
+    /** Current error, if any (auto-cleared on success) */
+    error: Error | null;
+    /** Derived: true if callState === 'connected' */
+    isConnected: boolean;
+    /** Derived: true if callState === 'connecting' */
+    isConnecting: boolean;
+    /** Derived: true if callState === 'reconnecting' */
+    isReconnecting: boolean;
+    /** Retry state for UI feedback (attempt count, countdown) */
+    retryState: RetryState;
+    /** Connect to voice session */
+    connect: () => Promise<void>;
+    /** Disconnect from voice session */
+    disconnect: () => Promise<void>;
+    /** Mute microphone */
+    mute: () => void;
+    /** Unmute microphone */
+    unmute: () => void;
+    /** Manual retry connection (with exponential backoff) */
+    retryConnect: () => Promise<void>;
+}
+/**
+ * Comprehensive hook for VoiceAgent functionality.
+ *
+ * Per user decision:
+ * - Single comprehensive hook returning everything (not multiple focused hooks)
+ * - Flat return structure with all properties at top level
+ * - Includes raw agent instance for advanced use cases
+ * - Unlimited transcript accumulation in memory during session
+ * - Auto-clear errors when next action succeeds
+ *
+ * Per RESEARCH.md patterns:
+ * - Uses useSyncExternalStore for connection state (concurrent-safe)
+ * - Uses useState for transcripts and errors
+ * - Proper cleanup in useEffect to prevent memory leaks
+ * - useCallback for wrapped methods
+ *
+ * @throws {Error} When used outside VoiceAgentProvider
+ *
+ * @example
+ * ```tsx
+ * function VoiceChat() {
+ *   const {
+ *     connect,
+ *     disconnect,
+ *     mute,
+ *     unmute,
+ *     callState,
+ *     transcripts,
+ *     error,
+ *     isConnected,
+ *   } = useVoiceAgent();
+ *
+ *   return (
+ *     <div>
+ *       <button onClick={connect} disabled={isConnected}>
+ *         {isConnected ? 'Connected' : 'Connect'}
+ *       </button>
+ *       {error && <div>Error: {error.message}</div>}
+ *       <div>
+ *         {transcripts.map((t, i) => (
+ *           <p key={i}>{t.speaker}: {t.text}</p>
+ *         ))}
+ *       </div>
+ *     </div>
+ *   );
+ * }
+ * ```
+ */
+declare function useVoiceAgent(): UseVoiceAgentReturn;
+
+/**
+ * Hook to persist transcripts to sessionStorage.
+ *
+ * Per RESEARCH.md Pattern 3 and user decision:
+ * - Load persisted transcripts on mount
+ * - Save transcripts to sessionStorage on change
+ * - Clear on unmount (sessionStorage auto-clears on tab close)
+ * - Handle errors silently (log to console, don't crash)
+ * - No limits on transcript array size (browser quota is the limit)
+ *
+ * Per RESEARCH.md Pitfall 4:
+ * - Uses SSR-safe storage utilities
+ * - Won't crash in Next.js/Remix server-side rendering
+ *
+ * @param sessionId - Session ID to namespace storage key
+ * @param transcripts - Current transcripts array
+ * @param setTranscripts - State setter to restore transcripts
+ *
+ * @example
+ * ```typescript
+ * const [transcripts, setTranscripts] = useState<TranscriptData[]>([]);
+ * useTranscriptPersistence(sessionId, transcripts, setTranscripts);
+ * ```
+ */
+declare function useTranscriptPersistence(sessionId: string, transcripts: TranscriptData[], setTranscripts: Dispatch<SetStateAction<TranscriptData[]>>): void;
+
+/**
+ * SSR-safe sessionStorage utilities.
+ *
+ * Per RESEARCH.md Pitfall 4:
+ * - Guard with typeof window !== 'undefined' check
+ * - Wrap in try-catch (storage can be disabled or full)
+ * - Return null/false on error or SSR
+ *
+ * @packageDocumentation
+ */
+/**
+ * Get item from sessionStorage in SSR-safe manner.
+ * Returns null if running in SSR, storage disabled, or key doesn't exist.
+ *
+ * @param key - Storage key
+ * @returns Value or null
+ *
+ * @example
+ * ```typescript
+ * const transcripts = getSessionStorage('voice-agent-transcripts');
+ * if (transcripts) {
+ *   // Use transcripts
+ * }
+ * ```
+ */
+declare function getSessionStorage(key: string): string | null;
+/**
+ * Set item in sessionStorage in SSR-safe manner.
+ * Returns true on success, false on failure (SSR, quota exceeded, disabled).
+ *
+ * @param key - Storage key
+ * @param value - Value to store
+ * @returns Success flag
+ *
+ * @example
+ * ```typescript
+ * const success = setSessionStorage('voice-agent-transcripts', JSON.stringify(transcripts));
+ * if (!success) {
+ *   console.warn('Failed to persist transcripts');
+ * }
+ * ```
+ */
+declare function setSessionStorage(key: string, value: string): boolean;
+/**
+ * Remove item from sessionStorage in SSR-safe manner.
+ * Returns true on success, false on failure (SSR, disabled).
+ *
+ * @param key - Storage key
+ * @returns Success flag
+ *
+ * @example
+ * ```typescript
+ * removeSessionStorage('voice-agent-transcripts-session-123');
+ * ```
+ */
+declare function removeSessionStorage(key: string): boolean;
+/**
+ * Get and parse JSON from sessionStorage.
+ * Returns null if parsing fails, SSR, or key doesn't exist.
+ *
+ * @param key - Storage key
+ * @returns Parsed value or null
+ *
+ * @example
+ * ```typescript
+ * const transcripts = getSessionStorageJSON<TranscriptData[]>('voice-agent-transcripts');
+ * if (transcripts) {
+ *   // Use typed transcripts array
+ * }
+ * ```
+ */
+declare function getSessionStorageJSON<T>(key: string): T | null;
+/**
+ * Stringify and store JSON in sessionStorage.
+ * Returns true on success, false on failure (SSR, quota, parse error).
+ *
+ * @param key - Storage key
+ * @param value - Value to stringify and store
+ * @returns Success flag
+ *
+ * @example
+ * ```typescript
+ * const success = setSessionStorageJSON('voice-agent-transcripts', transcripts);
+ * if (!success) {
+ *   console.warn('Failed to persist transcripts');
+ * }
+ * ```
+ */
+declare function setSessionStorageJSON<T>(key: string, value: T): boolean;
+
+/**
+ * Simple JWT token decoder for extracting session ID.
+ * Per plan: Client-side JWT decoding (backend already validated).
+ */
+/**
+ * Extract session ID from JWT session token.
+ * Uses atob() for browser compatibility.
+ *
+ * @param token - JWT session token
+ * @returns Session ID string
+ * @throws {Error} If token is malformed
+ *
+ * @example
+ * ```typescript
+ * const sessionId = extractSessionId(sessionToken);
+ * // Use sessionId for storage key
+ * ```
+ */
+declare function extractSessionId(token: string): string;
+
+export { type RetryState, type UseVoiceAgentReturn, VoiceAgentContext, type VoiceAgentContextValue, VoiceAgentProvider, type VoiceAgentProviderProps, extractSessionId, getSessionStorage, getSessionStorageJSON, removeSessionStorage, setSessionStorage, setSessionStorageJSON, useConnectionRetry, useTranscriptPersistence, useVoiceAgent };