@glydeunity/voice-sdk 1.0.0 → 1.2.0

package/dist/index.d.ts

@@ -1,32 +1,251 @@
+/**
+ * GLYDE Voice SDK
+ *
+ * Voice agent client for GLYDE Unity with support for multiple authentication methods
+ * and voice context types.
+ *
+ * @packageDocumentation
+ */
+
+/**
+ * Deepgram agent configuration for LLM and voice settings
+ */
+export declare interface DeepgramAgentConfig {
+    think?: {
+        provider?: {
+            type: string;
+            model?: string;
+        };
+        functions?: Array<{
+            name: string;
+            description: string;
+            parameters: unknown;
+        }>;
+    };
+    speak?: {
+        provider?: {
+            type: string;
+            model?: string;
+        };
+    };
+    listen?: {
+        provider?: {
+            type: string;
+            model?: string;
+            version?: string;
+        };
+    };
+}
+
+/**
+ * GlydeVoice - Voice Agent Client
+ *
+ * Connects to Deepgram Voice Agent API for bidirectional voice conversation.
+ * Uses wss://agent.deepgram.com/agent WebSocket endpoint which:
+ * - Receives user audio (microphone)
+ * - Transcribes speech to text (STT)
+ * - Sends to LLM for response
+ * - Converts response to speech (TTS)
+ * - Streams audio back to user
+ *
+ * Audio Architecture:
+ * - Microphone capture: AudioWorklet (audio-capture-processor.js) at 48kHz
+ * - Playback: AudioWorklet (audio-playback-processor.js) with ring buffer
+ * - Ring buffer enables instant interruption (clear buffer when user speaks)
+ */
 export declare class GlydeVoice {
     private config;
-    private _deepgram;
     private unityUrl;
     private active;
+    private serverConfig;
+    private ws;
+    private audioContext;
+    private mediaStream;
+    private captureWorkletNode;
+    private playbackWorkletNode;
+    private isMuted;
+    private readonly outputSampleRate;
+    private readonly inputSampleRate;
+    private isAgentSpeaking;
+    private agentAudioDoneReceived;
+    /**
+     * Create a new GlydeVoice instance
+     * @param config - Configuration options
+     */
     constructor(config: GlydeVoiceConfig);
+    /**
+     * Get authentication headers based on configured auth method
+     * Supports publishableKey, apiKey, and JWT token (authToken)
+     * @returns Headers object with appropriate authentication
+     */
+    private getAuthHeaders;
+    /**
+     * Fetch voice configuration from Unity API
+     * @returns Voice configuration including system prompt, tools, and Deepgram settings
+     */
+    private fetchConfig;
     /**
      * Initialize and start the voice session
      */
     start(): Promise<void>;
+    /**
+     * Create a blob URL from inline JavaScript code for AudioWorklet modules.
+     * This avoids CORS issues when the SDK is loaded from a different origin than the page.
+     * @param code - The JavaScript code to convert to a blob URL
+     * @returns A blob URL that can be used with audioWorklet.addModule()
+     */
+    private createWorkletBlobUrl;
+    /**
+     * Initialize the audio system with both capture and playback worklets.
+     * Uses inline blob URLs to avoid CORS issues when SDK is embedded in external apps.
+     */
+    private initializeAudio;
+    /**
+     * Handle text messages from the Voice Agent
+     */
+    private handleTextMessage;
+    /**
+     * Handle binary audio data (Blob) from agent TTS
+     */
+    private handleAudioData;
+    /**
+     * Handle binary audio buffer from agent TTS
+     * Deepgram sends linear16 PCM at 24kHz, we need to resample to 48kHz for playback
+     */
+    private handleAudioBuffer;
+    /**
+     * Resample audio from 24kHz to 48kHz using linear interpolation
+     */
+    private resample24kTo48k;
+    /**
+     * Clear the playback buffer (for interruption handling)
+     */
+    private clearPlaybackBuffer;
+    /**
+     * Start capturing microphone audio using AudioWorklet
+     */
+    private startMicrophone;
+    /**
+     * Save transcript to Unity backend
+     */
+    private saveTranscript;
+    /**
+     * Toggle mute state
+     * @param muted - Whether to mute the microphone
+     */
+    setMuted(muted: boolean): void;
+    /**
+     * Get current mute state
+     */
+    getMuted(): boolean;
+    /**
+     * Check if the voice agent is currently active
+     */
+    isActive(): boolean;
+    /**
+     * Get the current server configuration
+     */
+    getServerConfig(): VoiceConfig | null;
     /**
      * Stop the voice session
      */
     stop(): void;
+    /**
+     * Cleanup resources
+     */
+    private cleanup;
+    /**
+     * Emit event to callback
+     */
     private emit;
+    /**
+     * Render a simple UI widget (optional)
+     */
     private renderUI;
 }
 
+/**
+ * Configuration options for GlydeVoice
+ */
 export declare interface GlydeVoiceConfig {
-    publishableKey: string;
+    /** Publishable key for external apps (Screen) */
+    publishableKey?: string;
+    /** API key for programmatic access */
+    apiKey?: string;
+    /** JWT token for GLYDEBuddy passthrough (Teams app) */
+    authToken?: string;
+    /** Voice context type - determines which prompt and tools to use */
+    contextType: VoiceContextType;
+    /** Context identifier (e.g., application_uuid) - required for screening */
     contextId?: string;
+    /** Unity API base URL - defaults to https://api.glydeunity.com */
     unityBaseUrl?: string;
+    /** DOM element to render the widget UI (optional) */
     container?: HTMLElement | string;
+    /** Event callback for voice agent events */
     onEvent?: (event: VoiceEvent) => void;
+    /** Transcript callback for conversation text */
+    onTranscript?: (text: string, role: 'user' | 'agent') => void;
+    /** Override system prompt (skips config fetch) */
+    systemPrompt?: string;
+    /** Override Deepgram configuration */
+    deepgramConfig?: DeepgramAgentConfig;
 }
 
+/**
+ * MCP Tool definition for voice agent
+ */
+export declare interface MCPTool {
+    name: string;
+    description: string;
+    inputSchema?: unknown;
+}
+
+/**
+ * Voice configuration response from Unity API
+ */
+export declare interface VoiceConfig {
+    system_prompt: string;
+    available_tools: MCPTool[];
+    deepgram_config: DeepgramAgentConfig;
+    context: {
+        type: VoiceContextType;
+        id: string | null;
+    };
+}
+
+/**
+ * GlydeVoice SDK - Voice Agent Client for GLYDE Unity
+ *
+ * Provides voice interaction capabilities with GLYDE AI agents through Deepgram Voice API.
+ * Supports multiple authentication methods: publishableKey, apiKey, and JWT token.
+ *
+ * @example
+ * // Using publishable key (external apps)
+ * const voice = new GlydeVoice({
+ *   publishableKey: 'pk_...',
+ *   contextType: 'screening',
+ *   contextId: 'application-uuid'
+ * });
+ *
+ * @example
+ * // Using JWT token (GLYDEBuddy Teams app)
+ * const voice = new GlydeVoice({
+ *   authToken: userSession.accessToken,
+ *   contextType: 'recruiter'
+ * });
+ */
+/**
+ * Voice context types supported by the voice agent
+ */
+export declare type VoiceContextType = 'screening' | 'recruiter' | 'custom' | 'phone';
+
+/**
+ * Voice events emitted by the agent
+ */
 export declare interface VoiceEvent {
-    type: 'open' | 'close' | 'error' | 'transcript' | 'agent_audio';
-    payload?: any;
+    type: 'open' | 'close' | 'error' | 'ready' | 'user_speaking' | 'agent_speaking' | 'microphone_ready' | 'transcript' | 'agent_audio';
+    payload?: unknown;
 }
 
 export { }