@lokutor/sdk 1.1.15 → 1.1.19

package/dist/index.d.mts

@@ -28,7 +28,9 @@ declare enum Language {
  */
 declare const AUDIO_CONFIG: {
     SAMPLE_RATE: number;
+    SAMPLE_RATE_INPUT: number;
     SPEAKER_SAMPLE_RATE: number;
+    SAMPLE_RATE_OUTPUT: number;
     CHANNELS: number;
     CHUNK_DURATION_MS: number;
     readonly CHUNK_SIZE: number;
@@ -83,18 +85,68 @@ interface VoiceAgentOptions {
     language?: Language;
     serverUrl?: string;
     visemes?: boolean;
-    onTranscription?: (text: string, isUser: boolean) => void;
+    onTranscription?: (text: string) => void;
     onVisemes?: (visemes: Viseme[]) => void;
     onStatusChange?: (status: string) => void;
-    onError?: (err: any) => void;
+    onError?: (err: LokutorError) => void;
+}
+/**
+ * REST API response types for discovery endpoints.
+ */
+interface VoiceInfo {
+    id: string;
+    gender?: string;
+    languages?: string[];
+}
+interface LanguageInfo {
+    code: string;
+    name: string;
+}
+interface ModelInfo {
+    name: string;
+    description?: string;
+    default?: boolean;
+}
+interface ServerConfig {
+    max_text_length: number;
+    min_speed: number;
+    max_speed: number;
+    min_steps: number;
+    max_steps: number;
+    sample_rate: number;
+    channels: number;
+}
+interface ServerStatus {
+    status: string;
+    timestamp: string;
+    version: string;
+    runtime: string;
+    inference: string;
+    uptime_seconds: number;
+    goroutines: number;
+    mem_alloc_bytes: number;
+    active_connections: number;
+    failed_requests: number;
+    ready: boolean;
+}
+interface HealthStatus {
+    status: string;
+    timestamp: string;
+    version: string;
+    runtime: string;
+    inference: string;
+    load: number;
 }
 /**
  * Viseme data for lip-sync animation
  * Format: {"v": index, "c": character, "t": timestamp}
  */
 interface Viseme {
+    /** Text-position index (which input character the model is attending to), not a stable viseme ID */
     v: number;
+    /** Character/phoneme being spoken (reduced set: a,e,i,o,u,m,p,b,f,v,t,d,s,z,l,n,r,k,g,sil) */
     c: string;
+    /** Offset in seconds from the start of the audio stream */
     t: number;
 }
 /**
@@ -119,7 +171,45 @@ interface ToolCall {
     name: string;
     arguments: string;
 }
+/**
+ * Error code enum matching the backend API error catalog
+ */
+type ErrorCode = 'auth.missing_key' | 'auth.invalid_key' | 'auth.rate_limited' | 'auth.time_limited' | 'validation.invalid_voice' | 'validation.invalid_language' | 'validation.text_too_long' | 'validation.speed_out_of_range' | 'validation.steps_out_of_range' | 'validation.invalid_request_format' | 'tts.synthesis_failed' | 'tts.voice_unavailable' | 'tts.model_not_found' | 'tts.session_limit_reached' | 'stt.not_configured' | 'stt.stream_create_failed' | 'stt.language_not_supported' | 'agent.session_failed' | 'agent.provider_error' | 'internal.error' | 'internal.timeout' | 'internal.cancelled' | 'ws.close';
+/**
+ * Typed error class for all Lokutor SDK errors.
+ * Includes the backend error code, human-readable message,
+ * optional detail, and whether the operation is retryable.
+ */
+declare class LokutorError extends Error {
+    readonly code: ErrorCode;
+    readonly detail?: string;
+    readonly retryable: boolean;
+    readonly original?: unknown;
+    constructor(code: ErrorCode, message: string, opts?: {
+        detail?: string;
+        retryable?: boolean;
+        original?: unknown;
+    });
+}
+/**
+ * Returns true if the given error is a retryable LokutorError.
+ */
+declare function isRetryable(error: unknown): boolean;
 
+/**
+ * Interface for audio hardware management (Browser/Node parity)
+ */
+interface AudioManager {
+    init(): Promise<void>;
+    startMicrophone(onAudioInput: (pcm16Data: Uint8Array) => void): Promise<void>;
+    stopMicrophone(): void;
+    playAudio(pcm16Data: Uint8Array): void;
+    stopPlayback(): void;
+    cleanup(): void;
+    isMicMuted(): boolean;
+    setMuted(muted: boolean): void;
+    getAmplitude(): number;
+}
 /**
  * Main client for Lokutor Voice Agent SDK
  *
@@ -145,10 +235,12 @@ declare class VoiceAgentClient {
     private audioManager;
     private enableAudio;
     private currentGeneration;
+    private listeners;
     private isUserDisconnect;
     private reconnecting;
     private reconnectAttempts;
     private maxReconnectAttempts;
+    private serverUrl;
     constructor(config: LokutorConfig & {
         prompt: string;
         voice?: VoiceStyle;
@@ -157,11 +249,20 @@ declare class VoiceAgentClient {
         onVisemes?: (visemes: Viseme[]) => void;
         enableAudio?: boolean;
         tools?: ToolDefinition[];
+        serverUrl?: string;
     });
     /**
      * Connect to the Lokutor Voice Agent server
+     * @param customAudioManager Optional replacement for the default audio hardware handler
      */
-    connect(): Promise<boolean>;
+    connect(customAudioManager?: AudioManager): Promise<boolean>;
+    /**
+     * The "Golden Path" - Starts a managed session with hardware handled automatically.
+     * This is the recommended way to start a conversation in browser environments.
+     */
+    startManaged(config?: {
+        audioManager?: AudioManager;
+    }): Promise<this>;
     /**
      * Send initial configuration to the server
      */
@@ -179,7 +280,13 @@ declare class VoiceAgentClient {
      * Handle incoming text messages (metadata/transcriptions)
      */
     private handleTextMessage;
-    private audioListeners;
+    /**
+     * Register an event listener (for Python parity)
+     */
+    on(event: string, callback: Function): this;
+    /**
+     * Internal emitter for all events
+     */
     private emit;
     onAudio(callback: (data: Uint8Array) => void): void;
     onVisemes(callback: (visemes: Viseme[]) => void): void;
@@ -187,6 +294,15 @@ declare class VoiceAgentClient {
      * Disconnect from the server
      */
     disconnect(): void;
+    /**
+     * Returns true if the client is currently connected.
+     */
+    get connected(): boolean;
+    /**
+     * Returns the current generation counter.
+     * Useful for correlating audio/viseme chunks with utterances.
+     */
+    get generation(): number;
     /**
      * Toggles the microphone mute state (if managed by client)
      * returns the new mute state
@@ -196,6 +312,36 @@ declare class VoiceAgentClient {
      * Gets the microphone volume amplitude 0-1 (if managed by client)
      */
     getAmplitude(): number;
+    /**
+     * Fetch available voice styles from the server.
+     * No authentication required.
+     */
+    static fetchVoices(baseUrl?: string): Promise<VoiceInfo[]>;
+    /**
+     * Fetch supported languages from the server.
+     * No authentication required.
+     */
+    static fetchLanguages(baseUrl?: string): Promise<LanguageInfo[]>;
+    /**
+     * Fetch loaded TTS model versions from the server.
+     * No authentication required.
+     */
+    static fetchModels(baseUrl?: string): Promise<ModelInfo[]>;
+    /**
+     * Fetch server configuration (limits and defaults).
+     * No authentication required.
+     */
+    static fetchConfig(baseUrl?: string): Promise<ServerConfig>;
+    /**
+     * Fetch rich runtime status from the server.
+     * No authentication required.
+     */
+    static fetchStatus(baseUrl?: string): Promise<ServerStatus>;
+    /**
+     * Fetch health/liveness status from the server.
+     * No authentication required.
+     */
+    static fetchHealth(baseUrl?: string): Promise<HealthStatus>;
     /**
      * Update the system prompt mid-conversation
      */
@@ -236,6 +382,7 @@ declare class TTSClient {
         visemes?: boolean;
         onAudio?: (data: Uint8Array) => void;
         onVisemes?: (visemes: any[]) => void;
+        onTTFB?: (ms: number) => void;
         onError?: (error: any) => void;
     }): Promise<void>;
 }
@@ -443,4 +590,4 @@ declare class BrowserAudioManager {
     isRecording(): boolean;
 }
 
-export { AUDIO_CONFIG, type AnalyserConfig, type BrowserAudioConfig, BrowserAudioManager, type BrowserAudioOptions, DEFAULT_URLS, Language, type LokutorConfig, StreamResampler, type SynthesizeOptions, TTSClient, type ToolCall, type ToolDefinition, type Viseme, VoiceAgentClient, type VoiceAgentOptions, VoiceStyle, applyLowPassFilter, bytesToPcm16, calculateRMS, float32ToPcm16, normalizeAudio, pcm16ToBytes, pcm16ToFloat32, resample, resampleWithAntiAliasing, simpleConversation, simpleTTS };
+export { AUDIO_CONFIG, type AnalyserConfig, type AudioManager, type BrowserAudioConfig, BrowserAudioManager, type BrowserAudioOptions, DEFAULT_URLS, type ErrorCode, type HealthStatus, Language, type LanguageInfo, type LokutorConfig, LokutorError, type ModelInfo, type ServerConfig, type ServerStatus, StreamResampler, type SynthesizeOptions, TTSClient, type ToolCall, type ToolDefinition, type Viseme, VoiceAgentClient, type VoiceAgentOptions, type VoiceInfo, VoiceStyle, applyLowPassFilter, bytesToPcm16, calculateRMS, float32ToPcm16, isRetryable, normalizeAudio, pcm16ToBytes, pcm16ToFloat32, resample, resampleWithAntiAliasing, simpleConversation, simpleTTS };

package/dist/index.d.ts

@@ -28,7 +28,9 @@ declare enum Language {
  */
 declare const AUDIO_CONFIG: {
     SAMPLE_RATE: number;
+    SAMPLE_RATE_INPUT: number;
     SPEAKER_SAMPLE_RATE: number;
+    SAMPLE_RATE_OUTPUT: number;
     CHANNELS: number;
     CHUNK_DURATION_MS: number;
     readonly CHUNK_SIZE: number;
@@ -83,18 +85,68 @@ interface VoiceAgentOptions {
     language?: Language;
     serverUrl?: string;
     visemes?: boolean;
-    onTranscription?: (text: string, isUser: boolean) => void;
+    onTranscription?: (text: string) => void;
     onVisemes?: (visemes: Viseme[]) => void;
     onStatusChange?: (status: string) => void;
-    onError?: (err: any) => void;
+    onError?: (err: LokutorError) => void;
+}
+/**
+ * REST API response types for discovery endpoints.
+ */
+interface VoiceInfo {
+    id: string;
+    gender?: string;
+    languages?: string[];
+}
+interface LanguageInfo {
+    code: string;
+    name: string;
+}
+interface ModelInfo {
+    name: string;
+    description?: string;
+    default?: boolean;
+}
+interface ServerConfig {
+    max_text_length: number;
+    min_speed: number;
+    max_speed: number;
+    min_steps: number;
+    max_steps: number;
+    sample_rate: number;
+    channels: number;
+}
+interface ServerStatus {
+    status: string;
+    timestamp: string;
+    version: string;
+    runtime: string;
+    inference: string;
+    uptime_seconds: number;
+    goroutines: number;
+    mem_alloc_bytes: number;
+    active_connections: number;
+    failed_requests: number;
+    ready: boolean;
+}
+interface HealthStatus {
+    status: string;
+    timestamp: string;
+    version: string;
+    runtime: string;
+    inference: string;
+    load: number;
 }
 /**
  * Viseme data for lip-sync animation
  * Format: {"v": index, "c": character, "t": timestamp}
  */
 interface Viseme {
+    /** Text-position index (which input character the model is attending to), not a stable viseme ID */
     v: number;
+    /** Character/phoneme being spoken (reduced set: a,e,i,o,u,m,p,b,f,v,t,d,s,z,l,n,r,k,g,sil) */
     c: string;
+    /** Offset in seconds from the start of the audio stream */
     t: number;
 }
 /**
@@ -119,7 +171,45 @@ interface ToolCall {
     name: string;
     arguments: string;
 }
+/**
+ * Error code enum matching the backend API error catalog
+ */
+type ErrorCode = 'auth.missing_key' | 'auth.invalid_key' | 'auth.rate_limited' | 'auth.time_limited' | 'validation.invalid_voice' | 'validation.invalid_language' | 'validation.text_too_long' | 'validation.speed_out_of_range' | 'validation.steps_out_of_range' | 'validation.invalid_request_format' | 'tts.synthesis_failed' | 'tts.voice_unavailable' | 'tts.model_not_found' | 'tts.session_limit_reached' | 'stt.not_configured' | 'stt.stream_create_failed' | 'stt.language_not_supported' | 'agent.session_failed' | 'agent.provider_error' | 'internal.error' | 'internal.timeout' | 'internal.cancelled' | 'ws.close';
+/**
+ * Typed error class for all Lokutor SDK errors.
+ * Includes the backend error code, human-readable message,
+ * optional detail, and whether the operation is retryable.
+ */
+declare class LokutorError extends Error {
+    readonly code: ErrorCode;
+    readonly detail?: string;
+    readonly retryable: boolean;
+    readonly original?: unknown;
+    constructor(code: ErrorCode, message: string, opts?: {
+        detail?: string;
+        retryable?: boolean;
+        original?: unknown;
+    });
+}
+/**
+ * Returns true if the given error is a retryable LokutorError.
+ */
+declare function isRetryable(error: unknown): boolean;
 
+/**
+ * Interface for audio hardware management (Browser/Node parity)
+ */
+interface AudioManager {
+    init(): Promise<void>;
+    startMicrophone(onAudioInput: (pcm16Data: Uint8Array) => void): Promise<void>;
+    stopMicrophone(): void;
+    playAudio(pcm16Data: Uint8Array): void;
+    stopPlayback(): void;
+    cleanup(): void;
+    isMicMuted(): boolean;
+    setMuted(muted: boolean): void;
+    getAmplitude(): number;
+}
 /**
  * Main client for Lokutor Voice Agent SDK
  *
@@ -145,10 +235,12 @@ declare class VoiceAgentClient {
     private audioManager;
     private enableAudio;
     private currentGeneration;
+    private listeners;
     private isUserDisconnect;
     private reconnecting;
     private reconnectAttempts;
     private maxReconnectAttempts;
+    private serverUrl;
     constructor(config: LokutorConfig & {
         prompt: string;
         voice?: VoiceStyle;
@@ -157,11 +249,20 @@ declare class VoiceAgentClient {
         onVisemes?: (visemes: Viseme[]) => void;
         enableAudio?: boolean;
         tools?: ToolDefinition[];
+        serverUrl?: string;
     });
     /**
      * Connect to the Lokutor Voice Agent server
+     * @param customAudioManager Optional replacement for the default audio hardware handler
      */
-    connect(): Promise<boolean>;
+    connect(customAudioManager?: AudioManager): Promise<boolean>;
+    /**
+     * The "Golden Path" - Starts a managed session with hardware handled automatically.
+     * This is the recommended way to start a conversation in browser environments.
+     */
+    startManaged(config?: {
+        audioManager?: AudioManager;
+    }): Promise<this>;
     /**
      * Send initial configuration to the server
      */
@@ -179,7 +280,13 @@ declare class VoiceAgentClient {
      * Handle incoming text messages (metadata/transcriptions)
      */
     private handleTextMessage;
-    private audioListeners;
+    /**
+     * Register an event listener (for Python parity)
+     */
+    on(event: string, callback: Function): this;
+    /**
+     * Internal emitter for all events
+     */
     private emit;
     onAudio(callback: (data: Uint8Array) => void): void;
     onVisemes(callback: (visemes: Viseme[]) => void): void;
@@ -187,6 +294,15 @@ declare class VoiceAgentClient {
      * Disconnect from the server
      */
     disconnect(): void;
+    /**
+     * Returns true if the client is currently connected.
+     */
+    get connected(): boolean;
+    /**
+     * Returns the current generation counter.
+     * Useful for correlating audio/viseme chunks with utterances.
+     */
+    get generation(): number;
     /**
      * Toggles the microphone mute state (if managed by client)
      * returns the new mute state
@@ -196,6 +312,36 @@ declare class VoiceAgentClient {
      * Gets the microphone volume amplitude 0-1 (if managed by client)
      */
     getAmplitude(): number;
+    /**
+     * Fetch available voice styles from the server.
+     * No authentication required.
+     */
+    static fetchVoices(baseUrl?: string): Promise<VoiceInfo[]>;
+    /**
+     * Fetch supported languages from the server.
+     * No authentication required.
+     */
+    static fetchLanguages(baseUrl?: string): Promise<LanguageInfo[]>;
+    /**
+     * Fetch loaded TTS model versions from the server.
+     * No authentication required.
+     */
+    static fetchModels(baseUrl?: string): Promise<ModelInfo[]>;
+    /**
+     * Fetch server configuration (limits and defaults).
+     * No authentication required.
+     */
+    static fetchConfig(baseUrl?: string): Promise<ServerConfig>;
+    /**
+     * Fetch rich runtime status from the server.
+     * No authentication required.
+     */
+    static fetchStatus(baseUrl?: string): Promise<ServerStatus>;
+    /**
+     * Fetch health/liveness status from the server.
+     * No authentication required.
+     */
+    static fetchHealth(baseUrl?: string): Promise<HealthStatus>;
     /**
      * Update the system prompt mid-conversation
      */
@@ -236,6 +382,7 @@ declare class TTSClient {
         visemes?: boolean;
         onAudio?: (data: Uint8Array) => void;
         onVisemes?: (visemes: any[]) => void;
+        onTTFB?: (ms: number) => void;
         onError?: (error: any) => void;
     }): Promise<void>;
 }
@@ -443,4 +590,4 @@ declare class BrowserAudioManager {
     isRecording(): boolean;
 }
 
-export { AUDIO_CONFIG, type AnalyserConfig, type BrowserAudioConfig, BrowserAudioManager, type BrowserAudioOptions, DEFAULT_URLS, Language, type LokutorConfig, StreamResampler, type SynthesizeOptions, TTSClient, type ToolCall, type ToolDefinition, type Viseme, VoiceAgentClient, type VoiceAgentOptions, VoiceStyle, applyLowPassFilter, bytesToPcm16, calculateRMS, float32ToPcm16, normalizeAudio, pcm16ToBytes, pcm16ToFloat32, resample, resampleWithAntiAliasing, simpleConversation, simpleTTS };
+export { AUDIO_CONFIG, type AnalyserConfig, type AudioManager, type BrowserAudioConfig, BrowserAudioManager, type BrowserAudioOptions, DEFAULT_URLS, type ErrorCode, type HealthStatus, Language, type LanguageInfo, type LokutorConfig, LokutorError, type ModelInfo, type ServerConfig, type ServerStatus, StreamResampler, type SynthesizeOptions, TTSClient, type ToolCall, type ToolDefinition, type Viseme, VoiceAgentClient, type VoiceAgentOptions, type VoiceInfo, VoiceStyle, applyLowPassFilter, bytesToPcm16, calculateRMS, float32ToPcm16, isRetryable, normalizeAudio, pcm16ToBytes, pcm16ToFloat32, resample, resampleWithAntiAliasing, simpleConversation, simpleTTS };