@voxdiscover/voiceserver 0.1.0

package/dist/index.d.cts

@@ -0,0 +1,580 @@
+import EventEmitter from 'eventemitter3';
+
+/**
+ * Connection states for voice session.
+ * Per user decision: Detailed states (connecting, connected, reconnecting, disconnected, failed).
+ */
+type ConnectionState = 'connecting' | 'connected' | 'reconnecting' | 'disconnected' | 'failed';
+/**
+ * Configuration for VoiceAgent initialization.
+ * Per user decision: Minimal required config (only token required).
+ */
+interface VoiceAgentConfig {
+    /** Session token from backend (POST /v1/sessions) */
+    token: string;
+    /** Optional base URL for session validation (defaults to production) */
+    baseUrl?: string;
+    /** Optional reconnection configuration */
+    reconnection?: {
+        enabled?: boolean;
+        maxAttempts?: number;
+    };
+    /**
+     * Optional mem0 API key for client-side memory integration.
+     * Requires `npm install mem0ai` in the consuming app.
+     *
+     * When set, conversation is synced to mem0 on disconnect() for the specified userId.
+     *
+     * SECURITY WARNING: API keys in client code can be extracted from DevTools.
+     * For production, prefer the server-side pattern: backend handles mem0 with
+     * user_id from session context.
+     *
+     * @see https://docs.mem0.ai/platform/quickstart
+     */
+    mem0ApiKey?: string;
+    /**
+     * Optional user identifier for mem0 memory scoping.
+     * Required when mem0ApiKey is set.
+     * Maps to mem0 user_id parameter for per-user memory isolation.
+     */
+    userId?: string;
+}
+/**
+ * Transcript data from conversation.
+ * Per user decision: Streaming with interim/final separation.
+ */
+interface TranscriptData {
+    text: string;
+    speaker: 'user' | 'agent';
+    timestamp?: Date;
+}
+/**
+ * Analytics event types for lifecycle and error tracking.
+ * Per RESEARCH.md Pattern 5 (Analytics Hooks with Lifecycle Events).
+ * Per user decision: lifecycle + error events only (not full event stream).
+ */
+type AnalyticsEventType = 'session_started' | 'session_ended' | 'connection_failed' | 'agent_swap_completed' | 'agent_swap_failed' | 'error';
+/**
+ * Analytics event payload with standard fields.
+ * Per user decision: timestamp, event_type, session_id, agent_id, user_id, custom_context.
+ *
+ * Analytics callbacks MUST be read-only (no SDK method calls) to prevent infinite
+ * loops. Calling SDK methods from inside a callback will trigger circuit breaker
+ * and disable analytics. See RESEARCH.md Pitfall #5.
+ */
+interface AnalyticsEvent {
+    /** Unix timestamp in milliseconds when the event occurred */
+    timestamp: number;
+    /** Type of lifecycle or error event */
+    eventType: AnalyticsEventType;
+    /** Session identifier from session token */
+    sessionId: string;
+    /** Agent identifier from session token */
+    agentId?: string;
+    /** User identifier from session context */
+    userId?: string;
+    /** Custom context data from session creation */
+    customContext?: Record<string, any>;
+    /** Error details for connection_failed and error events */
+    error?: {
+        /** Error code for programmatic handling */
+        code: string;
+        /** Human-readable error message */
+        message: string;
+        /** Whether the operation that caused the error can be retried */
+        retryable: boolean;
+    };
+}
+/**
+ * Callback type for analytics event handlers.
+ * IMPORTANT: Callbacks MUST be read-only - do NOT call SDK methods (connect,
+ * disconnect, mute, etc.) inside a callback. This causes infinite loops.
+ */
+type AnalyticsCallback = (event: AnalyticsEvent) => void;
+/**
+ * Custom context for session-specific data injection.
+ * Per Phase 15 ADV-02: custom context with predefined fields and arbitrary JSON.
+ *
+ * Predefined fields map to backend CustomContext model.
+ * The custom field holds arbitrary JSON for agent context (max 10KB, 50 fields).
+ */
+interface CustomContext {
+    /** User identifier (used for mem0 memory integration) */
+    user_id?: string;
+    /** Customer/tenant identifier */
+    customer_id?: string;
+    /** Structured session metadata */
+    session_metadata?: Record<string, unknown>;
+    /** Arbitrary JSON for agent context (10KB max, 50 fields max) */
+    custom?: Record<string, unknown>;
+}
+/**
+ * Payload emitted with context:updated event.
+ */
+interface ContextUpdateData {
+    /** The context updates that were applied */
+    updates: Partial<CustomContext>;
+    /** Timestamp of the update (milliseconds since epoch) */
+    timestamp: number;
+}
+/**
+ * Individual cost breakdown for a single provider call.
+ * Per RESEARCH.md Pattern 4 (Web SDK - Cost Aggregation).
+ */
+interface CostBreakdown {
+    /** Provider name (openai, elevenlabs, deepgram, cartesia, etc.) */
+    provider: string;
+    /** Service type for the provider call */
+    serviceType: 'stt' | 'llm' | 'tts';
+    /** Model name used for this call */
+    model: string;
+    /** Cost in USD for this single call */
+    costUsd: number;
+    /** Unix timestamp when this cost was incurred */
+    timestamp: number;
+}
+/**
+ * Cumulative cost summary for the session.
+ * Aggregated from all CostBreakdown entries during the session.
+ */
+interface CostSummary {
+    /** Total session cost in USD (sum of all breakdown entries) */
+    totalUsd: number;
+    /** All individual cost breakdown entries */
+    breakdown: CostBreakdown[];
+    /** Total cost grouped by provider name */
+    byProvider: Record<string, number>;
+    /** Total cost grouped by service type (stt, llm, tts) */
+    byServiceType: Record<string, number>;
+}
+/**
+ * Options for agent hot-swap.
+ * Per Phase 15 ADV-01: controls context/transcript preservation and timeout.
+ */
+interface AgentSwapOptions {
+    /** Transfer LLM context to new agent (default: true) */
+    preserveContext?: boolean;
+    /** Transfer transcript history to new agent (default: true) */
+    preserveTranscripts?: boolean;
+    /** Milliseconds to wait for new agent to connect before failing (default: 5000) */
+    timeout?: number;
+}
+/**
+ * Payload for agent swap events.
+ */
+interface AgentSwapEventData {
+    /** New agent ID being swapped to */
+    newAgentId: string;
+    /** Unix timestamp in milliseconds */
+    timestamp: number;
+    /** Error message (only on agent:swap-failed) */
+    error?: string;
+}
+/**
+ * Event map for typed EventEmitter.
+ * Per RESEARCH.md Pattern 2 and user decision.
+ */
+interface VoiceAgentEvents {
+    'connection:state': (state: ConnectionState) => void;
+    'connection:error': (error: Error) => void;
+    'transcript:interim': (data: TranscriptData) => void;
+    'transcript:final': (data: TranscriptData) => void;
+    'audio:muted': () => void;
+    'audio:unmuted': () => void;
+    'session:expiring': (expiresIn: number) => void;
+    'context:updated': (data: ContextUpdateData) => void;
+    'cost:update': (summary: CostSummary) => void;
+    'agent:swapping': (data: AgentSwapEventData) => void;
+    'agent:swapped': (data: AgentSwapEventData) => void;
+    'agent:swap-failed': (data: AgentSwapEventData) => void;
+}
+
+/**
+ * Error codes for VoiceAgent SDK.
+ * Per user decision: both instanceof checks AND code property checks.
+ */
+type VoiceAgentErrorCode = 'TOKEN_EXPIRED' | 'TOKEN_INVALID' | 'CONNECTION_FAILED' | 'PERMISSION_DENIED' | 'NETWORK_ERROR' | 'UNKNOWN_ERROR';
+/**
+ * Base error class for VoiceAgent SDK.
+ *
+ * Per user decision: includes human-readable message, suggested fix/action,
+ * original cause, context data, and retryability indicator.
+ *
+ * Supports both error handling patterns:
+ * - Pattern 1: instanceof checks
+ * - Pattern 2: code property checks
+ *
+ * @example
+ * ```typescript
+ * try {
+ *   await agent.connect();
+ * } catch (err) {
+ *   // Pattern 1: instanceof
+ *   if (err instanceof TokenExpiredError) {
+ *     console.log(err.context?.suggestion);
+ *   }
+ *
+ *   // Pattern 2: code property
+ *   if (err.code === 'TOKEN_EXPIRED') {
+ *     refreshToken();
+ *   }
+ *
+ *   // Retryability check
+ *   if (err.retryable) {
+ *     retry();
+ *   }
+ * }
+ * ```
+ */
+declare class VoiceAgentError extends Error {
+    readonly code: VoiceAgentErrorCode;
+    readonly cause?: Error;
+    readonly context?: Record<string, any>;
+    readonly retryable: boolean;
+    constructor(message: string, code: VoiceAgentErrorCode, options?: {
+        cause?: Error;
+        context?: Record<string, any>;
+        retryable?: boolean;
+    });
+}
+/**
+ * Session token has expired.
+ * Per user decision: non-retryable, includes suggested action.
+ */
+declare class TokenExpiredError extends VoiceAgentError {
+    constructor(message?: string, cause?: Error);
+}
+/**
+ * Session token is invalid or malformed.
+ * Per user decision: non-retryable, includes suggested action.
+ */
+declare class TokenInvalidError extends VoiceAgentError {
+    constructor(message?: string, cause?: Error);
+}
+/**
+ * WebRTC connection failed.
+ * Per user decision: retryable, includes suggested action.
+ */
+declare class ConnectionFailedError extends VoiceAgentError {
+    constructor(message: string, cause?: Error);
+}
+/**
+ * Microphone or camera permission denied by user.
+ * Per user decision: non-retryable, includes suggested action.
+ */
+declare class PermissionDeniedError extends VoiceAgentError {
+    constructor(permission: 'microphone' | 'camera');
+}
+/**
+ * Network error occurred during API call or WebRTC connection.
+ * Per user decision: retryable.
+ */
+declare class NetworkError extends VoiceAgentError {
+    constructor(message: string, cause?: Error);
+}
+
+/**
+ * VoiceAgent SDK for Voice_server voice conversations.
+ *
+ * Per user decisions:
+ * - Constructor pattern with minimal required config (only token)
+ * - Explicit connect() - no auto-connect on init
+ * - disconnect() performs full cleanup (leave + destroy)
+ * - Read-only state property
+ * - Async validation before connect
+ *
+ * @example
+ * ```typescript
+ * const agent = new VoiceAgent({ token: sessionToken });
+ *
+ * agent.on('connection:state', (state) => {
+ *   console.log('State:', state);
+ * });
+ *
+ * await agent.connect();
+ * agent.mute();
+ * await agent.disconnect();
+ * ```
+ */
+declare class VoiceAgent extends EventEmitter<VoiceAgentEvents> {
+    private config;
+    private sessionData;
+    private dailyCall;
+    private _state;
+    private reconnectionManager;
+    /**
+     * Audio elements for remote participants.
+     * Daily.js createCallObject() does not auto-play remote audio — we must
+     * create <audio> elements ourselves in the track-started handler.
+     */
+    private remoteAudioElements;
+    /**
+     * Cumulative cost breakdown for the current session.
+     * Per RESEARCH.md Pattern 4: appended on each cost-update app-message.
+     * Reset to [] on disconnect() for clean state on reconnection.
+     */
+    private costBreakdown;
+    /**
+     * Current agent ID tracked for duplicate-swap guard.
+     * Initialized from session token on connect().
+     */
+    private currentAgentId;
+    /**
+     * Registered analytics callbacks.
+     * Per RESEARCH.md Pattern 5: observer pattern for lifecycle and error events.
+     */
+    private analyticsCallbacks;
+    /**
+     * Circuit breaker counter for analytics to prevent infinite loops.
+     * Per RESEARCH.md Pitfall #5: if same event emitted >10 times/second, disable analytics.
+     */
+    private analyticsCallCount;
+    private analyticsCallResetTimer;
+    private analyticsDisabled;
+    /**
+     * Optional mem0 memory client for client-side conversation memory.
+     * Initialized from config.mem0ApiKey via dynamic import (optional peer dependency).
+     * Per RESEARCH.md Pattern 3: client-side pattern syncs on session end.
+     */
+    private memoryClient;
+    /**
+     * Transcript history for mem0 sync on session end.
+     * Accumulates final transcripts as {role, content} pairs.
+     * Reset on disconnect() for clean state on reconnection.
+     */
+    private transcriptHistory;
+    /**
+     * Create VoiceAgent instance.
+     * Per user decision: constructor pattern, minimal config (only token required).
+     */
+    constructor(config: VoiceAgentConfig);
+    /**
+     * Get current connection state.
+     * Per user decision: read-only state property.
+     */
+    get state(): ConnectionState;
+    /**
+     * Register an analytics callback for lifecycle and error events.
+     *
+     * Emits: session_started, session_ended, connection_failed, and error events.
+     *
+     * IMPORTANT: Analytics callbacks MUST be read-only. Do NOT call SDK methods
+     * (connect, disconnect, mute, etc.) inside a callback. Doing so will trigger
+     * the circuit breaker and disable analytics for the remainder of the session.
+     * See RESEARCH.md Pitfall #5.
+     *
+     * @param callback Function called with each analytics event
+     *
+     * @example
+     * ```typescript
+     * agent.onAnalyticsEvent((event) => {
+     *   // Integrate with Segment, DataDog, PostHog, etc.
+     *   analytics.track(event.eventType, {
+     *     session_id: event.sessionId,
+     *     user_id: event.userId,
+     *   });
+     * });
+     * ```
+     */
+    onAnalyticsEvent(callback: AnalyticsCallback): void;
+    /**
+     * Search user memories from mem0 for context-aware responses.
+     *
+     * Requires mem0ApiKey and userId in config. Returns empty array if mem0
+     * is not configured or an error occurs.
+     *
+     * @param query Search query (e.g., "user preferences", "previous orders")
+     * @param limit Maximum number of results (default: 5)
+     * @returns Array of memory objects with 'memory' and 'score' fields
+     *
+     * @example
+     * ```typescript
+     * const memories = await agent.searchMemories('user preferences', 3);
+     * memories.forEach(m => console.log(m.memory));
+     * ```
+     */
+    searchMemories(query: string, limit?: number): Promise<any[]>;
+    /**
+     * Initialize optional mem0 memory client via dynamic import.
+     * Uses dynamic import so missing mem0ai package is a soft warning, not an error.
+     * Per RESEARCH.md Pattern 3 (Client-side - Web SDK).
+     */
+    private initMemoryClient;
+    /**
+     * Emit analytics event to all registered callbacks.
+     * Per RESEARCH.md Pattern 5: try/catch per callback prevents analytics errors from breaking SDK.
+     * Per RESEARCH.md Pitfall #5: circuit breaker disables analytics on excessive calls.
+     */
+    private emitAnalyticsEvent;
+    /**
+     * Connect to voice session.
+     * Per user decision: explicit connect(), async validation before connect.
+     */
+    connect(): Promise<void>;
+    /**
+     * Disconnect from voice session.
+     * Per user decision: full cleanup (leave + destroy + remove listeners).
+     * Per RESEARCH.md Pitfall 2: Both leave() and destroy() required.
+     */
+    disconnect(): Promise<void>;
+    /**
+     * Mute microphone.
+     */
+    mute(): void;
+    /**
+     * Unmute microphone.
+     */
+    unmute(): void;
+    /**
+     * Update session context mid-session.
+     *
+     * Per Phase 15 ADV-02: allows developer to update user_id, customer_id,
+     * session_metadata, and custom JSON during an active session.
+     *
+     * Validates context client-side (10KB size, 50 fields) with warnings.
+     * POSTs to /v1/sessions/{session_id}/context endpoint.
+     * Emits 'context:updated' event on success.
+     *
+     * @param contextUpdates Partial context to merge into existing session context
+     * @throws Error if no active session
+     * @throws Error if the context update API call fails
+     *
+     * @example
+     * ```typescript
+     * await agent.updateContext({
+     *   user_id: 'user_123',
+     *   custom: { preferred_language: 'Spanish', loyalty_tier: 'gold' }
+     * });
+     * ```
+     */
+    updateContext(contextUpdates: Partial<CustomContext>): Promise<void>;
+    /**
+     * Validate context client-side for size (10KB) and field count (50 max).
+     * Validation is permissive: warns but does not throw on limits exceeded.
+     * Per user decision: don't break session on validation warning.
+     *
+     * @param context Context object to validate
+     */
+    private validateContext;
+    /**
+     * Switch agent mid-session without disconnecting WebRTC.
+     *
+     * Per Phase 15 ADV-01: hot-swap the backend bot while keeping the Daily room
+     * connection alive. The new agent receives full conversation context and
+     * transcript history.
+     *
+     * Protocol:
+     * 1. Validate connected and not already using newAgentId
+     * 2. Emit agent:swapping event (for analytics / UI loading indicator)
+     * 3. Send Daily app-message to backend bot requesting swap
+     * 4. Wait for agent-swap-complete confirmation (with timeout)
+     * 5. Update currentAgentId and emit agent:swapped on success
+     * 6. Emit agent:swap-failed and throw on timeout or backend error
+     *
+     * @param newAgentId UUID of the agent to swap to
+     * @param options Swap options (preserveContext, preserveTranscripts, timeout)
+     * @throws Error if not connected, already using newAgentId, or swap fails/times out
+     *
+     * @example
+     * ```typescript
+     * try {
+     *   await agent.switchAgent('specialist-agent-uuid');
+     *   console.log('Agent switched successfully');
+     * } catch (err) {
+     *   console.error('Swap failed:', err);
+     *   // Old agent is still active (resilient fallback)
+     * }
+     * ```
+     */
+    switchAgent(newAgentId: string, options?: AgentSwapOptions): Promise<void>;
+    /**
+     * Wait for backend agent-swap-complete confirmation via Daily app-message.
+     *
+     * Resolves when agent-swap-complete is received with matching agent_id.
+     * Rejects on agent-swap-failed message or timeout.
+     *
+     * @param agentId Expected new agent ID in confirmation
+     * @param timeoutMs Milliseconds before timing out
+     */
+    private waitForSwapConfirmation;
+    /**
+     * Subscribe to real-time cost updates for the session.
+     *
+     * Registers a callback that is called after each provider API call (STT, LLM, TTS)
+     * with the cumulative cost summary including a breakdown by provider and service type.
+     *
+     * Per RESEARCH.md Pattern 4: Backend streams cost events; SDK aggregates and exposes
+     * via this callback for developer integration (budget alerts, user-facing displays).
+     *
+     * @param callback Function called with CostSummary on each cost update
+     *
+     * @example
+     * ```typescript
+     * agent.onCostUpdate((summary) => {
+     *   console.log(`Session cost: $${summary.totalUsd.toFixed(4)}`);
+     *   console.log('By provider:', summary.byProvider);
+     *   console.log('By service:', summary.byServiceType);
+     * });
+     * ```
+     */
+    onCostUpdate(callback: (summary: CostSummary) => void): void;
+    /**
+     * Get the current cumulative cost summary for the session.
+     *
+     * Returns a snapshot of all costs incurred so far, aggregated by provider
+     * and service type. Returns empty summary if no costs have been tracked.
+     *
+     * @returns CostSummary with totalUsd, breakdown array, byProvider, and byServiceType
+     */
+    getCostSummary(): CostSummary;
+    /**
+     * Set up cost tracking subscription on the Daily call object.
+     * Per RESEARCH.md Pattern 4: subscribe to cost-update app-messages from backend.
+     * Called from setupDailyEventListeners() after Daily call object is created.
+     */
+    private setupCostTracking;
+    /**
+     * Handle cost-update app-message from backend bot.
+     * Parses cost event, appends to costBreakdown, and emits cost:update event.
+     * Per RESEARCH.md Pattern 4: cost events contain provider, service_type, model, cost_usd.
+     */
+    private handleCostUpdate;
+    private setState;
+    private setupDailyEventListeners;
+    private handleJoined;
+    private handleLeft;
+    private handleParticipantJoined;
+    private handleParticipantLeft;
+    /**
+     * Create and play an <audio> element when a remote participant's audio track starts.
+     * Daily.js createCallObject() does NOT auto-play remote audio in headless mode —
+     * the app must handle track-started and wire the track to an audio element.
+     */
+    private handleTrackStarted;
+    private handleTrackStopped;
+    private handleDailyError;
+    private handleTranscript;
+    private attemptReconnect;
+}
+
+/**
+ * Manages automatic reconnection with exponential backoff and jitter.
+ * Per RESEARCH.md Pattern 4 and research recommendations.
+ */
+declare class ReconnectionManager {
+    private maxRetries;
+    private initialDelayMs;
+    private maxDelayMs;
+    constructor(config?: {
+        maxRetries?: number;
+        initialDelayMs?: number;
+        maxDelayMs?: number;
+    });
+    /**
+     * Execute connection function with exponential backoff retry logic.
+     * Adds jitter to prevent thundering herd problem.
+     */
+    reconnectWithBackoff(connectFn: () => Promise<void>, onRetry?: (attempt: number, delayMs: number) => void): Promise<void>;
+}
+
+export { type AnalyticsCallback, type AnalyticsEvent, type AnalyticsEventType, ConnectionFailedError, type ConnectionState, type ContextUpdateData, type CostBreakdown, type CostSummary, type CustomContext, NetworkError, PermissionDeniedError, ReconnectionManager, TokenExpiredError, TokenInvalidError, type TranscriptData, VoiceAgent, type VoiceAgentConfig, VoiceAgentError, type VoiceAgentErrorCode, type VoiceAgentEvents };