@lokutor/sdk 1.5.0 → 1.6.0

package/src/conversational-panel.ts

@@ -1,3 +1,5 @@
+import { requestMicrophone } from './browser-audio';
+
 const PANEL_CSS = /*css*/ `
   .cv-panel {
     position: relative;
@@ -349,7 +351,11 @@ export 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;
@@ -365,6 +371,20 @@ export interface ConversationalPanelConfig {
   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. */
+export function microphoneMessage(err: any): string {
+  const name = String(err?.original?.name ?? err?.name ?? '');
+  const detail = String(err?.detail ?? err?.message ?? '');
+  if (/NotAllowedError|SecurityError/.test(name + ' ' + detail)) {
+    return 'Microphone access is blocked. Allow it for this site in your browser settings, then try again.';
+  }
+  if (/NotFoundError|OverconstrainedError/.test(name + ' ' + detail)) {
+    return 'No microphone was found on this device.';
+  }
+  return 'The microphone could not start. Please try again.';
+}
+
 export class ConversationalPanel {
   private cfg: ConversationalPanelConfig;
   private container: HTMLElement;
@@ -394,6 +414,8 @@ export class ConversationalPanel {
   private countdownEl!: HTMLElement;
   private noteEl!: HTMLElement;
   private countdownTicker: number | null = null;
+  private microphone: Promise<MediaStream> | null = null;
+  private micError: unknown = null;
 
   // Callbacks
   onTranscription?: (text: string) => void;
@@ -507,14 +529,25 @@ export class ConversationalPanel {
     return d.innerHTML;
   }
 
-  /** Start the conversation (called when user clicks "Start Conversation" or externally) */
-  async start() {
-    if (this.isRunning) return;
+  /**
+   * 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).
+   */
+  async start(): Promise<boolean> {
+    if (this.isRunning) return false;
     if (this._locked) {
       this.showError('This session has ended. Refresh the page to start a new one.');
-      return;
+      return false;
     }
     this.isRunning = true;
+    // First, while this is still the tap: iOS Safari only reliably shows its microphone prompt for a request
+    // made inside a user gesture, and refuses capture with no prompt at all while the page's audio session
+    // is in playback mode. Asked for later, after the connection opened, the call went live with the agent
+    // talking and the caller's microphone never captured (2026-09-28).
+    this.microphone = requestMicrophone();
+    this.micError = null;
+    this.microphone.catch((e) => { this.micError = e; });
     this.startBtn.disabled = true;
     this.errorEl.classList.remove('is-visible');
     this.playConnectingSound();
@@ -577,10 +610,13 @@ export class ConversationalPanel {
           this.onError?.(err);
           // The server's own words when it ended the session on purpose (e.g. "Demo time limit
           // reached..."); a generic line for anything else.
-          this.end(err?.code === 'session.ended' && err?.message
-            ? err.message
-            : 'Connection issue. Try again in a moment.');
-        }
+          this.end(err?.code === 'audio.microphone_unavailable'
+            ? microphoneMessage(err)
+            : err?.code === 'session.ended' && err?.message
+              ? err.message
+              : 'Connection issue. Try again in a moment.');
+        },
+        microphone: this.microphone,
       });
 
       this.agent = agentHandle;
@@ -591,6 +627,8 @@ export class ConversationalPanel {
       try { agentHandle.unlockAudioForMobile?.(); } catch (_) { /* ignore */ }
 
       const ok = await agentHandle.connect();
+      // Ended while connecting (the microphone was refused, the server closed): the reason is already shown.
+      if (!this.isRunning) return false;
       if (ok) {
         this.fadeOutConnectingSound();
         // Resize canvas to container
@@ -605,19 +643,22 @@ export class ConversationalPanel {
         this.startTimer();
         this.onStart?.();
         if ((window as any).lucide) (window as any).lucide.createIcons();
-      } else {
-        this.fadeOutConnectingSound();
-        this.playErrorTone();
-        this.curtain.classList.remove('is-up');
-        this.showError('Could not connect. Please try again.');
-        this.isRunning = false;
+        return true;
       }
+      this.fadeOutConnectingSound();
+      this.playErrorTone();
+      // The microphone's own failure when that is what stopped the call, not a generic connection line.
+      const micError = this.micError;
+      this.stop();
+      this.showError(micError ? microphoneMessage(micError) : 'Could not connect. Please try again.');
+      return false;
     } catch (err: any) {
       this.fadeOutConnectingSound();
       this.playErrorTone();
       console.error('ConversationalPanel start error:', err);
       this.stop();
       this.showError('Something went wrong. Please try again.');
+      return false;
     } finally {
       this.startBtn.disabled = false;
     }
@@ -633,6 +674,11 @@ export class ConversationalPanel {
       try { this.agent.disconnect(); } catch (_) {}
       this.agent = null;
     }
+    // Release the stream asked for at Start even if the agent never took it over (a ConvoAgent that
+    // ignores `microphone` asks again itself); stopping tracks the agent already stopped is harmless.
+    const mic = this.microphone;
+    this.microphone = null;
+    mic?.then((s) => s.getTracks().forEach((t) => t.stop()), () => {});
     if (this.timerTicker) { clearInterval(this.timerTicker); this.timerTicker = null; }
     this.stopCountdown();
     this.setNote('');

package/src/index.ts

@@ -14,7 +14,7 @@ export {
 } from './client';
 export { BrowserAudioManager } from './browser-audio';
 export { NodeAudioManager } from './node-audio';
-export { ConversationalPanel } from './conversational-panel';
+export { ConversationalPanel, microphoneMessage } from './conversational-panel';
 export type { ConversationalPanelConfig } from './conversational-panel';
 export {
   pcm16ToFloat32,

package/src/types.ts

@@ -4,13 +4,13 @@
 /**
  * Built-in voices.
  *
- * Versa 2.0 names each voice for the language its reference speaker was recorded in: `EN_*` are
- * English speakers, `ESCA_*` Spanish/Catalan. That is a guide to how a voice sounds, not a
- * restriction — the model is zero-shot, so any voice can speak any supported language.
+ * Use `F1`–`F5` / `M1`–`M5` (what GET /voices lists). Each is a slot: the server resolves it to the
+ * native speaker of the call's language in that slot, so `F1` in Spanish is a Spanish speaker and `F1`
+ * in English an English one.
  *
- * The bare `F1`–`M5` values are the Versa 1.x names. They still work: the server maps them onto
- * the matching Versa 2.0 voice, keeping the language family of the call. Prefer the explicit names
- * in new code.
+ * `EN_*` pin the English speakers regardless of language. `ESCA_*` is the retired Spanish/Catalan pack
+ * (its recordings measure as noisy in the top octave); do not use it in new code — `F1`–`M5` with
+ * `language: 'es'` gives the vetted Spanish voices.
  *
  * This enum is a convenience, not the full set — a cloned voice's id (`clone_…`) is also a valid
  * `voice`, which is why the config fields accept any string.
@@ -29,36 +29,36 @@ export enum VoiceStyle {
   EN_M5 = "en_m5",
 
   // Spanish / Catalan reference speakers
+  /** @deprecated Retired pack; use F1 with language "es". */
   ESCA_F1 = "esca_f1",
+  /** @deprecated Retired pack; use F2 with language "es". */
   ESCA_F2 = "esca_f2",
+  /** @deprecated Retired pack; use F3 with language "es". */
   ESCA_F3 = "esca_f3",
+  /** @deprecated Retired pack; use F4 with language "es". */
   ESCA_F4 = "esca_f4",
+  /** @deprecated Retired pack; use F5 with language "es". */
   ESCA_F5 = "esca_f5",
+  /** @deprecated Retired pack; use M1 with language "es". */
   ESCA_M1 = "esca_m1",
+  /** @deprecated Retired pack; use M2 with language "es". */
   ESCA_M2 = "esca_m2",
+  /** @deprecated Retired pack; use M3 with language "es". */
   ESCA_M3 = "esca_m3",
+  /** @deprecated Retired pack; use M4 with language "es". */
   ESCA_M4 = "esca_m4",
+  /** @deprecated Retired pack; use M5 with language "es". */
   ESCA_M5 = "esca_m5",
 
-  /** @deprecated Versa 1.x name, mapped server-side. Use EN_F1 / ESCA_F1. */
   F1 = "F1",
-  /** @deprecated Versa 1.x name, mapped server-side. */
   F2 = "F2",
-  /** @deprecated Versa 1.x name, mapped server-side. */
   F3 = "F3",
-  /** @deprecated Versa 1.x name, mapped server-side. */
   F4 = "F4",
-  /** @deprecated Versa 1.x name, mapped server-side. */
   F5 = "F5",
-  /** @deprecated Versa 1.x name, mapped server-side. */
   M1 = "M1",
-  /** @deprecated Versa 1.x name, mapped server-side. */
   M2 = "M2",
-  /** @deprecated Versa 1.x name, mapped server-side. */
   M3 = "M3",
-  /** @deprecated Versa 1.x name, mapped server-side. */
   M4 = "M4",
-  /** @deprecated Versa 1.x name, mapped server-side. */
   M5 = "M5",
 }
 
@@ -118,7 +118,14 @@ export const DEFAULT_URLS = {
  * SDK Configuration interface
  */
 export interface LokutorConfig {
-  apiKey: string;
+  /** An API key, or a short-lived wst_ ticket from POST /ws-ticket. Optional when `auth` is given. */
+  apiKey?: string;
+  /**
+   * Called before every connect (and reconnect) for the credential to use. In a browser, have it ask
+   * your backend for a fresh ticket (POST https://api.lokutor.com/ws-ticket with your API key) so the
+   * key itself never reaches the page; a ticket lasts 10 minutes, so reconnects need a new one.
+   */
+  auth?: () => string | Promise<string>;
   agentId?: string;
   onTranscription?: (text: string) => void;
   onResponse?: (text: string) => void;
@@ -313,6 +320,8 @@ export interface ToolDefinition {
 export interface ToolCall {
   name: string;
   arguments: string;
+  /** Pass to submitToolResult(call_id, result). */
+  call_id: string;
 }
 
 /**
@@ -338,7 +347,13 @@ export type ErrorCode =
   | 'stt.language_not_supported'
   | 'agent.session_failed'
   | 'agent.provider_error'
+  | 'agent.not_found'
+  | 'billing.insufficient_balance'
+  | 'billing.topup_required'
+  | 'billing.limit_reached'
+  | 'billing.account_disputed'
   | 'session.ended'
+  | 'audio.microphone_unavailable'
   | 'internal.error'
   | 'internal.timeout'
   | 'internal.cancelled'
@@ -371,6 +386,7 @@ function isRetryableCode(code: ErrorCode): boolean {
     'auth.invalid_key',
     'auth.time_limited',
     'session.ended',
+    'audio.microphone_unavailable',
     'validation.invalid_voice',
     'validation.invalid_language',
     'validation.text_too_long',
@@ -378,6 +394,11 @@ function isRetryableCode(code: ErrorCode): boolean {
     'validation.steps_out_of_range',
     'validation.invalid_request_format',
     'internal.cancelled',
+    'agent.not_found',
+    'billing.insufficient_balance',
+    'billing.topup_required',
+    'billing.limit_reached',
+    'billing.account_disputed',
   ];
   return !fatal.includes(code);
 }