@lokutor/sdk 1.4.1 → 1.5.1

package/dist/index.d.mts

@@ -289,7 +289,7 @@ interface ToolCall {
 /**
  * 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';
+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' | 'session.ended' | 'audio.microphone_unavailable' | 'internal.error' | 'internal.timeout' | 'internal.cancelled' | 'ws.close';
 /**
  * Typed error class for all Lokutor SDK errors.
  * Includes the backend error code, human-readable message,
@@ -325,6 +325,13 @@ interface AudioManager {
     setMuted(muted: boolean): void;
     getAmplitude(): number;
 }
+/** What the server announced about how long this session may run (landing-page demo sessions). */
+interface SessionLimit {
+    /** Seconds the session may still run, from when the message arrived. */
+    seconds: number;
+    /** Why there is a limit, e.g. "demo". */
+    reason?: string;
+}
 /**
  * Main client for Lokutor Voice Agent SDK
  *
@@ -358,6 +365,7 @@ declare class VoiceAgentClient {
     private reconnectAttempts;
     private maxReconnectAttempts;
     private reconnectTimer;
+    private micStarted;
     private serverPlaybackRate;
     private serverInputRate;
     private serverUrl;
@@ -685,8 +693,32 @@ interface BrowserAudioConfig {
     autoGainControl?: boolean;
     echoCancellation?: boolean;
     noiseSuppression?: boolean;
+    /**
+     * Keep the screen awake while the microphone is live (Screen Wake Lock API), as a video player does.
+     * Default true: a phone that dims and locks mid-call suspends the page's microphone and audio, and
+     * the call goes silent in both directions. Set false if your app manages this itself.
+     */
+    keepAwake?: boolean;
+    /**
+     * A microphone stream the page already asked for, ideally with requestMicrophone() inside the tap that
+     * started the call. startMicrophone uses it instead of calling getUserMedia again later, after the
+     * connection opens -- which iOS Safari can refuse without showing its prompt.
+     */
+    microphone?: MediaStream | Promise<MediaStream>;
     onInputError?: (error: Error) => void;
 }
+/**
+ * Ask for the microphone now, from inside the tap or click that starts a call, and return the pending stream.
+ *
+ * Call it synchronously in the gesture handler, before any await, and pass the result to BrowserAudioManager
+ * as `microphone` (ConversationalPanel does this itself). Two iOS Safari behaviours made a later request fail
+ * with no prompt at all -- the call connected, the agent spoke, and nothing the caller said was heard:
+ *  - a request outside a user gesture may be refused instead of prompting;
+ *  - while the page's audio session is in 'playback' mode (set by pages so audio plays through the mute
+ *    switch), capture is refused outright. It is put back to 'auto', under which Safari switches to
+ *    play-and-record itself when capture starts and keeps the loudspeaker.
+ */
+declare function requestMicrophone(constraints?: Pick<BrowserAudioConfig, 'autoGainControl' | 'echoCancellation' | 'noiseSuppression'>): Promise<MediaStream>;
 /**
  * Analyser configuration for audio visualization
  */
@@ -714,6 +746,10 @@ declare class BrowserAudioManager {
     private autoGainControl;
     private echoCancellation;
     private noiseSuppression;
+    private keepAwake;
+    private providedMicrophone;
+    private wakeLock;
+    private visibilityHandler;
     private onAudioInput?;
     private onInputError?;
     private isMuted;
@@ -735,6 +771,13 @@ declare class BrowserAudioManager {
      * Stop capturing microphone input
      */
     stopMicrophone(): void;
+    /**
+     * Keep the screen on while the microphone is live, and bring audio back when the page returns
+     * to the foreground (iOS leaves the context "interrupted" after the screen locks).
+     */
+    private holdScreenAwake;
+    private requestWakeLock;
+    private releaseScreenAwake;
     /**
      * Play back audio received from the server
      * @param pcm16Data Int16 PCM audio data at SPEAKER_SAMPLE_RATE
@@ -824,7 +867,11 @@ interface ConversationalPanelConfig {
     backgroundColor?: string;
     /** API key for connecting to the voice agent */
     apiKey: string;
-    /** Reference to the ConvoAgent class */
+    /**
+     * Reference to the ConvoAgent class. Its constructor options include `microphone`, a
+     * Promise<MediaStream> requested inside the Start tap (see requestMicrophone); pass it on to
+     * BrowserAudioManager as `microphone` so the call uses it instead of asking again later.
+     */
     ConvoAgent: any;
     /** Reference to the SphereVisualizer class */
     SphereVisualizer: any;
@@ -839,6 +886,9 @@ interface ConversationalPanelConfig {
     /** Seconds of silence before auto-close (default 60) */
     silenceTimeout?: number;
 }
+/** What to tell the caller when the microphone did not start: a DOMException from getUserMedia, or the
+ *  SDK's 'audio.microphone_unavailable' error wrapping one. */
+declare function microphoneMessage(err: any): string;
 declare class ConversationalPanel {
     private cfg;
     private container;
@@ -865,17 +915,32 @@ declare class ConversationalPanel {
     private muteSvg;
     private stopBtn;
     private visualizerWrap;
+    private countdownEl;
+    private noteEl;
+    private countdownTicker;
+    private microphone;
+    private micError;
     onTranscription?: (text: string) => void;
     onResponse?: (text: string) => void;
     onStart?: () => void;
     onStop?: () => void;
     onError?: (err: any) => void;
     onToolCall?: (tool: any) => void;
+    /**
+     * The call ended without the visitor pressing End: a time limit, the silence timeout, the server
+     * closing the session, or the connection being lost. Receives the message the panel shows, so a
+     * page that renders its own chrome (and hides this panel's curtain) can show it too.
+     */
+    onEnded?: (message: string) => void;
     constructor(cfg: ConversationalPanelConfig);
     private buildDOM;
     private esc;
-    /** Start the conversation (called when user clicks "Start Conversation" or externally) */
-    start(): Promise<void>;
+    /**
+     * Start the conversation (called when user clicks "Start Conversation" or externally). Call it from
+     * inside the click or tap, before any await: it asks for the microphone there. Resolves true once the
+     * call is live, false when it could not start (the reason is shown, and passed to onError).
+     */
+    start(): Promise<boolean>;
     /** Stop / disconnect the conversation */
     stop(): void;
     /** Update accent color dynamically */
@@ -893,6 +958,12 @@ declare class ConversationalPanel {
     setTools(tools: any[]): void;
     /** Show an error message */
     showError(text: string): void;
+    /** End the call for a reason other than the End button, and say why. */
+    private end;
+    /** Show how long the session may still run, as announced by the server. */
+    private startCountdown;
+    private stopCountdown;
+    private setNote;
     /** Destroy the component, removing all DOM and stopping any active session */
     destroy(): void;
     private startTimer;
@@ -902,4 +973,4 @@ declare class ConversationalPanel {
     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, NodeAudioManager, STTClient, type ServerConfig, type ServerStatus, SpeechToTextClient, type SpeechToTextOptions, StreamResampler, type SynthesizeOptions, TTSClient, type ToolCall, type ToolDefinition, type TranscribeOptions, type TranscribeResult, type TranscribeSegment, type Viseme, VoiceAgentClient, type VoiceAgentOptions, type VoiceId, type VoiceInfo, VoiceStyle, applyLowPassFilter, bytesToPcm16, calculateRMS, float32ToPcm16, isRetryable, normalizeAudio, pcm16ToBytes, pcm16ToFloat32, resample, resampleWithAntiAliasing, simpleConversation, simpleTTS, simpleTranscribe };
+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, NodeAudioManager, STTClient, type ServerConfig, type ServerStatus, type SessionLimit, SpeechToTextClient, type SpeechToTextOptions, StreamResampler, type SynthesizeOptions, TTSClient, type ToolCall, type ToolDefinition, type TranscribeOptions, type TranscribeResult, type TranscribeSegment, type Viseme, VoiceAgentClient, type VoiceAgentOptions, type VoiceId, type VoiceInfo, VoiceStyle, applyLowPassFilter, bytesToPcm16, calculateRMS, float32ToPcm16, isRetryable, microphoneMessage, normalizeAudio, pcm16ToBytes, pcm16ToFloat32, requestMicrophone, resample, resampleWithAntiAliasing, simpleConversation, simpleTTS, simpleTranscribe };

package/dist/index.d.ts

@@ -289,7 +289,7 @@ interface ToolCall {
 /**
  * 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';
+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' | 'session.ended' | 'audio.microphone_unavailable' | 'internal.error' | 'internal.timeout' | 'internal.cancelled' | 'ws.close';
 /**
  * Typed error class for all Lokutor SDK errors.
  * Includes the backend error code, human-readable message,
@@ -325,6 +325,13 @@ interface AudioManager {
     setMuted(muted: boolean): void;
     getAmplitude(): number;
 }
+/** What the server announced about how long this session may run (landing-page demo sessions). */
+interface SessionLimit {
+    /** Seconds the session may still run, from when the message arrived. */
+    seconds: number;
+    /** Why there is a limit, e.g. "demo". */
+    reason?: string;
+}
 /**
  * Main client for Lokutor Voice Agent SDK
  *
@@ -358,6 +365,7 @@ declare class VoiceAgentClient {
     private reconnectAttempts;
     private maxReconnectAttempts;
     private reconnectTimer;
+    private micStarted;
     private serverPlaybackRate;
     private serverInputRate;
     private serverUrl;
@@ -685,8 +693,32 @@ interface BrowserAudioConfig {
     autoGainControl?: boolean;
     echoCancellation?: boolean;
     noiseSuppression?: boolean;
+    /**
+     * Keep the screen awake while the microphone is live (Screen Wake Lock API), as a video player does.
+     * Default true: a phone that dims and locks mid-call suspends the page's microphone and audio, and
+     * the call goes silent in both directions. Set false if your app manages this itself.
+     */
+    keepAwake?: boolean;
+    /**
+     * A microphone stream the page already asked for, ideally with requestMicrophone() inside the tap that
+     * started the call. startMicrophone uses it instead of calling getUserMedia again later, after the
+     * connection opens -- which iOS Safari can refuse without showing its prompt.
+     */
+    microphone?: MediaStream | Promise<MediaStream>;
     onInputError?: (error: Error) => void;
 }
+/**
+ * Ask for the microphone now, from inside the tap or click that starts a call, and return the pending stream.
+ *
+ * Call it synchronously in the gesture handler, before any await, and pass the result to BrowserAudioManager
+ * as `microphone` (ConversationalPanel does this itself). Two iOS Safari behaviours made a later request fail
+ * with no prompt at all -- the call connected, the agent spoke, and nothing the caller said was heard:
+ *  - a request outside a user gesture may be refused instead of prompting;
+ *  - while the page's audio session is in 'playback' mode (set by pages so audio plays through the mute
+ *    switch), capture is refused outright. It is put back to 'auto', under which Safari switches to
+ *    play-and-record itself when capture starts and keeps the loudspeaker.
+ */
+declare function requestMicrophone(constraints?: Pick<BrowserAudioConfig, 'autoGainControl' | 'echoCancellation' | 'noiseSuppression'>): Promise<MediaStream>;
 /**
  * Analyser configuration for audio visualization
  */
@@ -714,6 +746,10 @@ declare class BrowserAudioManager {
     private autoGainControl;
     private echoCancellation;
     private noiseSuppression;
+    private keepAwake;
+    private providedMicrophone;
+    private wakeLock;
+    private visibilityHandler;
     private onAudioInput?;
     private onInputError?;
     private isMuted;
@@ -735,6 +771,13 @@ declare class BrowserAudioManager {
      * Stop capturing microphone input
      */
     stopMicrophone(): void;
+    /**
+     * Keep the screen on while the microphone is live, and bring audio back when the page returns
+     * to the foreground (iOS leaves the context "interrupted" after the screen locks).
+     */
+    private holdScreenAwake;
+    private requestWakeLock;
+    private releaseScreenAwake;
     /**
      * Play back audio received from the server
      * @param pcm16Data Int16 PCM audio data at SPEAKER_SAMPLE_RATE
@@ -824,7 +867,11 @@ interface ConversationalPanelConfig {
     backgroundColor?: string;
     /** API key for connecting to the voice agent */
     apiKey: string;
-    /** Reference to the ConvoAgent class */
+    /**
+     * Reference to the ConvoAgent class. Its constructor options include `microphone`, a
+     * Promise<MediaStream> requested inside the Start tap (see requestMicrophone); pass it on to
+     * BrowserAudioManager as `microphone` so the call uses it instead of asking again later.
+     */
     ConvoAgent: any;
     /** Reference to the SphereVisualizer class */
     SphereVisualizer: any;
@@ -839,6 +886,9 @@ interface ConversationalPanelConfig {
     /** Seconds of silence before auto-close (default 60) */
     silenceTimeout?: number;
 }
+/** What to tell the caller when the microphone did not start: a DOMException from getUserMedia, or the
+ *  SDK's 'audio.microphone_unavailable' error wrapping one. */
+declare function microphoneMessage(err: any): string;
 declare class ConversationalPanel {
     private cfg;
     private container;
@@ -865,17 +915,32 @@ declare class ConversationalPanel {
     private muteSvg;
     private stopBtn;
     private visualizerWrap;
+    private countdownEl;
+    private noteEl;
+    private countdownTicker;
+    private microphone;
+    private micError;
     onTranscription?: (text: string) => void;
     onResponse?: (text: string) => void;
     onStart?: () => void;
     onStop?: () => void;
     onError?: (err: any) => void;
     onToolCall?: (tool: any) => void;
+    /**
+     * The call ended without the visitor pressing End: a time limit, the silence timeout, the server
+     * closing the session, or the connection being lost. Receives the message the panel shows, so a
+     * page that renders its own chrome (and hides this panel's curtain) can show it too.
+     */
+    onEnded?: (message: string) => void;
     constructor(cfg: ConversationalPanelConfig);
     private buildDOM;
     private esc;
-    /** Start the conversation (called when user clicks "Start Conversation" or externally) */
-    start(): Promise<void>;
+    /**
+     * Start the conversation (called when user clicks "Start Conversation" or externally). Call it from
+     * inside the click or tap, before any await: it asks for the microphone there. Resolves true once the
+     * call is live, false when it could not start (the reason is shown, and passed to onError).
+     */
+    start(): Promise<boolean>;
     /** Stop / disconnect the conversation */
     stop(): void;
     /** Update accent color dynamically */
@@ -893,6 +958,12 @@ declare class ConversationalPanel {
     setTools(tools: any[]): void;
     /** Show an error message */
     showError(text: string): void;
+    /** End the call for a reason other than the End button, and say why. */
+    private end;
+    /** Show how long the session may still run, as announced by the server. */
+    private startCountdown;
+    private stopCountdown;
+    private setNote;
     /** Destroy the component, removing all DOM and stopping any active session */
     destroy(): void;
     private startTimer;
@@ -902,4 +973,4 @@ declare class ConversationalPanel {
     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, NodeAudioManager, STTClient, type ServerConfig, type ServerStatus, SpeechToTextClient, type SpeechToTextOptions, StreamResampler, type SynthesizeOptions, TTSClient, type ToolCall, type ToolDefinition, type TranscribeOptions, type TranscribeResult, type TranscribeSegment, type Viseme, VoiceAgentClient, type VoiceAgentOptions, type VoiceId, type VoiceInfo, VoiceStyle, applyLowPassFilter, bytesToPcm16, calculateRMS, float32ToPcm16, isRetryable, normalizeAudio, pcm16ToBytes, pcm16ToFloat32, resample, resampleWithAntiAliasing, simpleConversation, simpleTTS, simpleTranscribe };
+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, NodeAudioManager, STTClient, type ServerConfig, type ServerStatus, type SessionLimit, SpeechToTextClient, type SpeechToTextOptions, StreamResampler, type SynthesizeOptions, TTSClient, type ToolCall, type ToolDefinition, type TranscribeOptions, type TranscribeResult, type TranscribeSegment, type Viseme, VoiceAgentClient, type VoiceAgentOptions, type VoiceId, type VoiceInfo, VoiceStyle, applyLowPassFilter, bytesToPcm16, calculateRMS, float32ToPcm16, isRetryable, microphoneMessage, normalizeAudio, pcm16ToBytes, pcm16ToFloat32, requestMicrophone, resample, resampleWithAntiAliasing, simpleConversation, simpleTTS, simpleTranscribe };