@voxdiscover/voiceserver-react 0.1.0

package/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 Voxdiscover
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

package/README.md

@@ -0,0 +1,418 @@
+# @voxdiscover/voiceserver-react
+
+React adapter for Voice_server voice agents. Provides hooks, context provider, and automatic state management for building real-time voice AI applications.
+
+## Installation
+
+```bash
+pnpm add @voxdiscover/voiceserver-react @voxdiscover/voiceserver @daily-co/daily-js
+```
+
+Or with npm/yarn:
+
+```bash
+npm install @voxdiscover/voiceserver-react @voxdiscover/voiceserver @daily-co/daily-js
+yarn add @voxdiscover/voiceserver-react @voxdiscover/voiceserver @daily-co/daily-js
+```
+
+## Quick Start
+
+```tsx
+import { VoiceAgentProvider, useVoiceAgent } from '@voxdiscover/voiceserver-react';
+
+function App() {
+  return (
+    <VoiceAgentProvider token="your-session-token">
+      <VoiceChat />
+    </VoiceAgentProvider>
+  );
+}
+
+function VoiceChat() {
+  const { connect, disconnect, isConnected, transcripts } = useVoiceAgent();
+
+  return (
+    <div>
+      <button onClick={connect} disabled={isConnected}>
+        Start Call
+      </button>
+      <button onClick={disconnect} disabled={!isConnected}>
+        End Call
+      </button>
+      <div>
+        {transcripts.map((t, i) => (
+          <p key={i}>{t.speaker}: {t.text}</p>
+        ))}
+      </div>
+    </div>
+  );
+}
+```
+
+## Features
+
+- **React Hooks**: Single comprehensive `useVoiceAgent` hook with all functionality
+- **Automatic State Management**: Connection state, transcripts, and errors synced with React
+- **TypeScript Support**: Full type definitions included
+- **SSR-Safe**: Works with Next.js, Remix, and other SSR frameworks
+- **Transcript Persistence**: Automatically saves transcripts to sessionStorage
+- **Retry Logic**: Built-in exponential backoff with countdown UI feedback
+- **Concurrent-Safe**: Uses `useSyncExternalStore` for React 18+ concurrent features
+- **Memory Leak Protection**: Automatic cleanup on unmount
+
+## Usage
+
+### Provider Setup
+
+Wrap your app (or part of it) with `VoiceAgentProvider`:
+
+```tsx
+import { VoiceAgentProvider } from '@voxdiscover/voiceserver-react';
+
+function App() {
+  return (
+    <VoiceAgentProvider
+      token="your-session-token"
+      baseUrl="https://voiceserver.voxdiscover.com" // Optional, defaults to https://voiceserver.voxdiscover.com
+      reconnection={{
+        enabled: true,
+        maxAttempts: 5,
+        initialDelay: 1000,
+      }}
+      onConnect={() => console.log('Connected!')}
+      onDisconnect={() => console.log('Disconnected')}
+      onError={(error) => console.error('Error:', error)}
+    >
+      <YourApp />
+    </VoiceAgentProvider>
+  );
+}
+```
+
+### useVoiceAgent Hook
+
+Access all voice agent functionality from the hook:
+
+```tsx
+import { useVoiceAgent } from '@voxdiscover/voiceserver-react';
+
+function VoiceChat() {
+  const {
+    // Raw agent instance for advanced use cases
+    agent,
+
+    // Connection state
+    callState, // 'disconnected' | 'connecting' | 'connected' | 'reconnecting' | 'failed'
+    isConnected,
+    isConnecting,
+    isReconnecting,
+
+    // Transcripts and errors
+    transcripts, // Array of TranscriptData
+    error, // Current error, auto-cleared on success
+
+    // Retry state
+    retryState, // { isRetrying, attempt, maxAttempts, nextRetryIn }
+
+    // Actions
+    connect,
+    disconnect,
+    mute,
+    unmute,
+    retryConnect,
+  } = useVoiceAgent();
+
+  return (
+    <div>
+      {/* Your UI */}
+    </div>
+  );
+}
+```
+
+### Connection Management
+
+```tsx
+function ConnectionControls() {
+  const { connect, disconnect, isConnected, isConnecting } = useVoiceAgent();
+
+  return (
+    <div>
+      <button
+        onClick={connect}
+        disabled={isConnected || isConnecting}
+      >
+        {isConnecting ? 'Connecting...' : 'Start Call'}
+      </button>
+      <button
+        onClick={disconnect}
+        disabled={!isConnected}
+      >
+        End Call
+      </button>
+    </div>
+  );
+}
+```
+
+### Audio Controls
+
+```tsx
+function AudioControls() {
+  const { mute, unmute, isConnected } = useVoiceAgent();
+  const [isMuted, setIsMuted] = useState(false);
+
+  const toggleMute = () => {
+    if (isMuted) {
+      unmute();
+      setIsMuted(false);
+    } else {
+      mute();
+      setIsMuted(true);
+    }
+  };
+
+  return (
+    <button onClick={toggleMute} disabled={!isConnected}>
+      {isMuted ? 'Unmute' : 'Mute'}
+    </button>
+  );
+}
+```
+
+### Displaying Transcripts
+
+```tsx
+function TranscriptDisplay() {
+  const { transcripts } = useVoiceAgent();
+  const transcriptEndRef = useRef<HTMLDivElement>(null);
+
+  // Auto-scroll to bottom
+  useEffect(() => {
+    transcriptEndRef.current?.scrollIntoView({ behavior: 'smooth' });
+  }, [transcripts]);
+
+  return (
+    <div className="transcript-list">
+      {transcripts.map((transcript, index) => (
+        <div key={index} className={transcript.speaker}>
+          <strong>{transcript.speaker}:</strong> {transcript.text}
+        </div>
+      ))}
+      <div ref={transcriptEndRef} />
+    </div>
+  );
+}
+```
+
+### Error Handling
+
+```tsx
+function ErrorDisplay() {
+  const { error, retryState, retryConnect } = useVoiceAgent();
+
+  if (!error && !retryState.isRetrying) return null;
+
+  return (
+    <div className="error-banner">
+      {error && (
+        <div className="error-message">
+          <strong>Error:</strong> {error.message}
+        </div>
+      )}
+      {retryState.isRetrying && (
+        <div className="retry-info">
+          Retrying... attempt {retryState.attempt}/{retryState.maxAttempts}
+          <br />
+          Next retry in {Math.ceil(retryState.nextRetryIn / 1000)}s
+          <button onClick={retryConnect}>Retry Now</button>
+        </div>
+      )}
+    </div>
+  );
+}
+```
+
+### Advanced: Direct Agent Access
+
+For advanced use cases, access the raw `VoiceAgent` instance:
+
+```tsx
+function AdvancedControls() {
+  const { agent } = useVoiceAgent();
+
+  const handleCustomEvent = () => {
+    agent.on('custom:event', (data) => {
+      console.log('Custom event:', data);
+    });
+  };
+
+  return <button onClick={handleCustomEvent}>Setup Custom Listener</button>;
+}
+```
+
+## API Reference
+
+### VoiceAgentProvider Props
+
+```tsx
+interface VoiceAgentProviderProps {
+  children: ReactNode;
+  token: string; // Session token from backend
+  baseUrl?: string; // Backend URL, defaults to https://voiceserver.voxdiscover.com
+  reconnection?: {
+    enabled?: boolean;
+    maxAttempts?: number;
+    initialDelay?: number;
+  };
+  onConnect?: () => void;
+  onDisconnect?: () => void;
+  onError?: (error: Error) => void;
+}
+```
+
+### useVoiceAgent Return Type
+
+```tsx
+interface UseVoiceAgentReturn {
+  agent: VoiceAgent; // Raw agent instance
+  callState: ConnectionState; // Current connection state
+  transcripts: TranscriptData[]; // All transcripts
+  error: Error | null; // Current error (auto-cleared)
+  isConnected: boolean; // Derived from callState
+  isConnecting: boolean; // Derived from callState
+  isReconnecting: boolean; // Derived from callState
+  retryState: RetryState; // Retry attempt info
+  connect: () => Promise<void>; // Connect to session
+  disconnect: () => Promise<void>; // Disconnect from session
+  mute: () => void; // Mute microphone
+  unmute: () => void; // Unmute microphone
+  retryConnect: () => Promise<void>; // Manual retry
+}
+```
+
+### Types
+
+```tsx
+// Connection states
+type ConnectionState =
+  | 'disconnected'
+  | 'connecting'
+  | 'connected'
+  | 'reconnecting'
+  | 'failed';
+
+// Transcript data
+interface TranscriptData {
+  speaker: 'user' | 'agent';
+  text: string;
+  timestamp: number;
+  isFinal: boolean;
+}
+
+// Retry state
+interface RetryState {
+  isRetrying: boolean;
+  attempt: number;
+  maxAttempts: number;
+  nextRetryIn: number; // milliseconds
+}
+```
+
+## Examples
+
+See the [examples/basic-app](./examples/basic-app) directory for a complete working example demonstrating:
+
+- Connection lifecycle management
+- Audio controls (mute/unmute)
+- Real-time transcript display with auto-scroll
+- Error handling with visual feedback
+- Retry state display with countdown
+- Connection status indicators
+
+To run the example:
+
+```bash
+cd examples/basic-app
+cp .env.example .env
+# Edit .env and add your session token
+pnpm dev
+```
+
+Visit http://localhost:3001 to see the example app.
+
+## Troubleshooting
+
+### "useVoiceAgent must be used within VoiceAgentProvider"
+
+Make sure your component using `useVoiceAgent` is wrapped with `<VoiceAgentProvider>`:
+
+```tsx
+// ❌ Wrong
+function App() {
+  const { connect } = useVoiceAgent(); // Error!
+  return <div>...</div>;
+}
+
+// ✅ Correct
+function App() {
+  return (
+    <VoiceAgentProvider token={token}>
+      <VoiceChat />
+    </VoiceAgentProvider>
+  );
+}
+
+function VoiceChat() {
+  const { connect } = useVoiceAgent(); // Works!
+  return <div>...</div>;
+}
+```
+
+### SSR Hydration Errors
+
+The React adapter is SSR-safe by default. Storage operations use `typeof window` guards to prevent server-side errors.
+
+If you still experience issues with Next.js, you can force client-side rendering:
+
+```tsx
+import dynamic from 'next/dynamic';
+
+const VoiceChat = dynamic(() => import('./VoiceChat'), { ssr: false });
+```
+
+### Storage Quota Exceeded
+
+Transcript persistence silently handles storage quota errors. If you hit quota limits:
+
+1. Transcripts will stop persisting but the app continues working
+2. Check browser console for "Failed to persist transcripts" warnings
+3. Clear sessionStorage to free up space: `sessionStorage.clear()`
+
+### Connection Errors
+
+If you experience connection errors:
+
+1. Verify your session token is valid (not expired)
+2. Check that your backend URL is correct
+3. Ensure your backend is running and accessible
+4. Check browser console for detailed error messages
+
+## TypeScript
+
+This package is written in TypeScript and includes full type definitions. All types are exported:
+
+```tsx
+import type {
+  VoiceAgentProviderProps,
+  UseVoiceAgentReturn,
+  RetryState,
+  ConnectionState,
+  TranscriptData,
+  VoiceAgentConfig,
+} from '@voxdiscover/voiceserver-react';
+```
+
+## License
+
+MIT