@lokutor/sdk 1.1.17 → 1.1.20

package/dist/index.d.mts

@@ -85,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;
 }
 /**
@@ -121,6 +171,30 @@ 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)
@@ -166,6 +240,7 @@ declare class VoiceAgentClient {
     private reconnecting;
     private reconnectAttempts;
     private maxReconnectAttempts;
+    private serverUrl;
     constructor(config: LokutorConfig & {
         prompt: string;
         voice?: VoiceStyle;
@@ -174,6 +249,7 @@ declare class VoiceAgentClient {
         onVisemes?: (visemes: Viseme[]) => void;
         enableAudio?: boolean;
         tools?: ToolDefinition[];
+        serverUrl?: string;
     });
     /**
      * Connect to the Lokutor Voice Agent server
@@ -182,7 +258,7 @@ declare class VoiceAgentClient {
     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 both Browser and Node.js.
+     * This is the recommended way to start a conversation in browser environments.
      */
     startManaged(config?: {
         audioManager?: AudioManager;
@@ -218,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
@@ -227,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
      */
@@ -475,4 +590,78 @@ declare class BrowserAudioManager {
     isRecording(): boolean;
 }
 
-export { AUDIO_CONFIG, type AnalyserConfig, type AudioManager, 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 };
+interface ConversationalPanelConfig {
+    container: HTMLElement;
+    title: string;
+    description: string;
+    prompt: string;
+    voice?: string;
+    language?: string;
+    /** Accent color for the sphere glow and highlights, e.g. '#e74c3c' */
+    accentColor?: string;
+    /** Background color, e.g. '#0a0a0a' */
+    backgroundColor?: string;
+    /** API key for connecting to the voice agent */
+    apiKey: string;
+    /** Reference to the ConvoAgent class */
+    ConvoAgent: any;
+    /** Reference to the SphereVisualizer class */
+    SphereVisualizer: any;
+    /** URL for the connecting sound asset */
+    connectingSoundSrc?: string;
+    /** Background image for the curtain, e.g. '/background_gradient.jpeg' */
+    curtainBgSrc?: string;
+}
+declare class ConversationalPanel {
+    private cfg;
+    private container;
+    private agent;
+    private visualizer;
+    private timerTicker;
+    private connectingSound;
+    private connectingFadeTimer;
+    private isRunning;
+    private el;
+    private curtain;
+    private curtainTitle;
+    private curtainDesc;
+    private startBtn;
+    private errorEl;
+    private errorText;
+    private timerEl;
+    private canvas;
+    private muteBtn;
+    private stopBtn;
+    private visualizerWrap;
+    onTranscription?: (text: string) => void;
+    onResponse?: (text: string) => void;
+    onStart?: () => void;
+    onStop?: () => void;
+    onError?: (err: any) => void;
+    constructor(cfg: ConversationalPanelConfig);
+    private buildDOM;
+    private esc;
+    /** Start the conversation (called when user clicks "Start Conversation" or externally) */
+    start(): Promise<void>;
+    /** Stop / disconnect the conversation */
+    stop(): void;
+    /** Update accent color dynamically */
+    setColor(color: string): void;
+    /** Update title text */
+    setTitle(title: string): void;
+    /** Update description text */
+    setDescription(desc: string): void;
+    /** Update prompt (only takes effect on next start()) */
+    setPrompt(prompt: string): void;
+    /** Show an error message */
+    showError(text: string): void;
+    /** Destroy the component, removing all DOM and stopping any active session */
+    destroy(): void;
+    private startTimer;
+    private toggleMute;
+    private playConnectingSound;
+    private fadeOutConnectingSound;
+    private playErrorTone;
+}
+
+export { AUDIO_CONFIG, type AnalyserConfig, type AudioManager, type BrowserAudioConfig, BrowserAudioManager, type BrowserAudioOptions, ConversationalPanel, type ConversationalPanelConfig, 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

@@ -85,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;
 }
 /**
@@ -121,6 +171,30 @@ 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)
@@ -166,6 +240,7 @@ declare class VoiceAgentClient {
     private reconnecting;
     private reconnectAttempts;
     private maxReconnectAttempts;
+    private serverUrl;
     constructor(config: LokutorConfig & {
         prompt: string;
         voice?: VoiceStyle;
@@ -174,6 +249,7 @@ declare class VoiceAgentClient {
         onVisemes?: (visemes: Viseme[]) => void;
         enableAudio?: boolean;
         tools?: ToolDefinition[];
+        serverUrl?: string;
     });
     /**
      * Connect to the Lokutor Voice Agent server
@@ -182,7 +258,7 @@ declare class VoiceAgentClient {
     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 both Browser and Node.js.
+     * This is the recommended way to start a conversation in browser environments.
      */
     startManaged(config?: {
         audioManager?: AudioManager;
@@ -218,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
@@ -227,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
      */
@@ -475,4 +590,78 @@ declare class BrowserAudioManager {
     isRecording(): boolean;
 }
 
-export { AUDIO_CONFIG, type AnalyserConfig, type AudioManager, 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 };
+interface ConversationalPanelConfig {
+    container: HTMLElement;
+    title: string;
+    description: string;
+    prompt: string;
+    voice?: string;
+    language?: string;
+    /** Accent color for the sphere glow and highlights, e.g. '#e74c3c' */
+    accentColor?: string;
+    /** Background color, e.g. '#0a0a0a' */
+    backgroundColor?: string;
+    /** API key for connecting to the voice agent */
+    apiKey: string;
+    /** Reference to the ConvoAgent class */
+    ConvoAgent: any;
+    /** Reference to the SphereVisualizer class */
+    SphereVisualizer: any;
+    /** URL for the connecting sound asset */
+    connectingSoundSrc?: string;
+    /** Background image for the curtain, e.g. '/background_gradient.jpeg' */
+    curtainBgSrc?: string;
+}
+declare class ConversationalPanel {
+    private cfg;
+    private container;
+    private agent;
+    private visualizer;
+    private timerTicker;
+    private connectingSound;
+    private connectingFadeTimer;
+    private isRunning;
+    private el;
+    private curtain;
+    private curtainTitle;
+    private curtainDesc;
+    private startBtn;
+    private errorEl;
+    private errorText;
+    private timerEl;
+    private canvas;
+    private muteBtn;
+    private stopBtn;
+    private visualizerWrap;
+    onTranscription?: (text: string) => void;
+    onResponse?: (text: string) => void;
+    onStart?: () => void;
+    onStop?: () => void;
+    onError?: (err: any) => void;
+    constructor(cfg: ConversationalPanelConfig);
+    private buildDOM;
+    private esc;
+    /** Start the conversation (called when user clicks "Start Conversation" or externally) */
+    start(): Promise<void>;
+    /** Stop / disconnect the conversation */
+    stop(): void;
+    /** Update accent color dynamically */
+    setColor(color: string): void;
+    /** Update title text */
+    setTitle(title: string): void;
+    /** Update description text */
+    setDescription(desc: string): void;
+    /** Update prompt (only takes effect on next start()) */
+    setPrompt(prompt: string): void;
+    /** Show an error message */
+    showError(text: string): void;
+    /** Destroy the component, removing all DOM and stopping any active session */
+    destroy(): void;
+    private startTimer;
+    private toggleMute;
+    private playConnectingSound;
+    private fadeOutConnectingSound;
+    private playErrorTone;
+}
+
+export { AUDIO_CONFIG, type AnalyserConfig, type AudioManager, type BrowserAudioConfig, BrowserAudioManager, type BrowserAudioOptions, ConversationalPanel, type ConversationalPanelConfig, 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 };