@lokutor/sdk 1.5.1 → 1.6.0

package/dist/index.mjs

@@ -87,7 +87,12 @@ function isRetryableCode(code) {
     "validation.speed_out_of_range",
     "validation.steps_out_of_range",
     "validation.invalid_request_format",
-    "internal.cancelled"
+    "internal.cancelled",
+    "agent.not_found",
+    "billing.insufficient_balance",
+    "billing.topup_required",
+    "billing.limit_reached",
+    "billing.account_disputed"
   ];
   return !fatal.includes(code);
 }
@@ -662,6 +667,9 @@ function nowMs() {
 function wsToHttp(url) {
   return url.replace(/^wss:/, "https:").replace(/^ws:/, "http:");
 }
+function apiOrigin(base) {
+  return new URL(wsToHttp(base || DEFAULT_URLS.VOICE_AGENT)).origin;
+}
 async function fetchJson(url, timeoutMs = 1e4) {
   const controller = new AbortController();
   const timer = setTimeout(() => controller.abort(), timeoutMs);
@@ -774,10 +782,16 @@ var VoiceAgentClient = class {
   serverPlaybackRate = 44100;
   serverInputRate = 16e3;
   serverUrl;
+  authProvider;
+  voiceExplicit = false;
+  languageExplicit = false;
   constructor(config) {
-    this.apiKey = config.apiKey;
+    this.apiKey = config.apiKey || "";
+    this.authProvider = config.auth;
     this.agentId = config.agentId || "";
-    this.prompt = config.prompt;
+    this.prompt = config.prompt ?? "";
+    this.voiceExplicit = config.voice !== void 0;
+    this.languageExplicit = config.language !== void 0;
     this.voice = config.voice || "F1" /* F1 */;
     this.language = config.language || "en" /* ENGLISH */;
     this.serverUrl = config.serverUrl || DEFAULT_URLS.VOICE_AGENT;
@@ -797,6 +811,15 @@ var VoiceAgentClient = class {
    */
   async connect(customAudioManager) {
     this.isUserDisconnect = false;
+    if (this.authProvider) {
+      try {
+        this.apiKey = await this.authProvider();
+      } catch (err) {
+        const error = new LokutorError("auth.missing_key", "The auth callback failed to return a credential", { original: err, retryable: true });
+        this.emit("error", error);
+        throw error;
+      }
+    }
     if (this.enableAudio || customAudioManager) {
       if (customAudioManager) {
         this.audioManager = customAudioManager;
@@ -819,11 +842,11 @@ var VoiceAgentClient = class {
         let url = this.serverUrl;
         if (this.apiKey) {
           const separator = url.includes("?") ? "&" : "?";
-          url += `${separator}api_key=${this.apiKey}`;
+          url += `${separator}api_key=${encodeURIComponent(this.apiKey)}`;
         }
         if (this.agentId) {
           const separator = url.includes("?") ? "&" : "?";
-          url += `${separator}agent_id=${this.agentId}`;
+          url += `${separator}agent_id=${encodeURIComponent(this.agentId)}`;
         }
         const redactedUrl = url.replace(/api_key=[^&]+/, "api_key=***");
         sdkTrace("ws.connect", {
@@ -889,7 +912,7 @@ var VoiceAgentClient = class {
           });
           console.error("\u274C WebSocket error:", error.message);
           sdkTrace("ws.error", { code: error.code, message: error.message });
-          if (this.onError) this.onError(error);
+          this.emit("error", error);
           if (!this.isConnected) {
             settle(() => reject(error));
           }
@@ -926,8 +949,8 @@ var VoiceAgentClient = class {
             });
             console.log(`Session ended by the server (code ${event.code})`);
             this.emit("ended", { code: event.code, reason: event.reason || "" });
-            if (this.onError) this.onError(ended);
-            if (this.onStatus) this.onStatus("disconnected");
+            this.emit("error", ended);
+            this.emit("status", "disconnected");
             return;
           }
           if (!this.isUserDisconnect && this.reconnectAttempts < this.maxReconnectAttempts) {
@@ -935,7 +958,7 @@ var VoiceAgentClient = class {
             this.reconnectAttempts++;
             const backoffDelay = Math.min(1e3 * Math.pow(2, this.reconnectAttempts), 1e4);
             console.warn(`Connection lost. Reconnecting in ${backoffDelay}ms (attempt ${this.reconnectAttempts}/${this.maxReconnectAttempts})`);
-            if (this.onStatus) this.onStatus("reconnecting");
+            this.emit("status", "reconnecting");
             if (this.reconnectTimer) clearTimeout(this.reconnectTimer);
             this.reconnectTimer = setTimeout(() => {
               this.reconnectTimer = null;
@@ -945,15 +968,15 @@ var VoiceAgentClient = class {
             }, backoffDelay);
           } else if (this.isUserDisconnect) {
             console.log("Disconnected");
-            if (this.onStatus) this.onStatus("disconnected");
+            this.emit("status", "disconnected");
           } else {
             console.log("Max reconnection attempts reached");
-            if (this.onStatus) this.onStatus("disconnected");
+            this.emit("status", "disconnected");
           }
         };
       } catch (err) {
         const error = err instanceof LokutorError ? err : new LokutorError("internal.error", "Failed to create WebSocket connection", { original: err });
-        if (this.onError) this.onError(error);
+        this.emit("error", error);
         settle(() => reject(error));
       }
     });
@@ -981,13 +1004,14 @@ var VoiceAgentClient = class {
   sendConfig() {
     if (!this.ws || !this.isConnected) return;
     this.configConfirmed = false;
-    this.ws.send(JSON.stringify({ type: "voice", data: this.voice }));
-    this.ws.send(JSON.stringify({ type: "language", data: this.language }));
+    const agentSession = Boolean(this.agentId);
+    if (!agentSession || this.voiceExplicit) this.ws.send(JSON.stringify({ type: "voice", data: this.voice }));
+    if (!agentSession || this.languageExplicit) this.ws.send(JSON.stringify({ type: "language", data: this.language }));
     if (this.tools && this.tools.length > 0) {
       this.ws.send(JSON.stringify({ type: "tools", data: this.tools }));
     }
     this.ws.send(JSON.stringify({ type: "visemes", data: this.wantVisemes }));
-    this.ws.send(JSON.stringify({ type: "prompt", data: this.prompt }));
+    if (!agentSession || this.prompt) this.ws.send(JSON.stringify({ type: "prompt", data: this.prompt }));
     this.ws.send(JSON.stringify({ type: "rates", playback: 44100, input: 16e3 }));
     sdkTrace("ws.send.config", {
       promptLen: this.prompt?.length || 0,
@@ -1048,6 +1072,10 @@ var VoiceAgentClient = class {
           sdkTrace("server_rates", { playback: this.serverPlaybackRate, input: this.serverInputRate });
           break;
         case "transcript":
+          if (msg.partial) {
+            this.emit("transcription_partial", msg.data);
+            break;
+          }
           const role = msg.role === "user" ? "user" : "agent";
           this.messages.push({
             role,
@@ -1055,11 +1083,9 @@ var VoiceAgentClient = class {
             timestamp: nowMs()
           });
           if (msg.role === "user") {
-            if (this.onTranscription) this.onTranscription(msg.data);
             this.emit("transcription", msg.data);
             console.log(`\u{1F4AC} You: ${msg.data}`);
           } else {
-            if (this.onResponse) this.onResponse(msg.data);
             this.emit("response", msg.data);
             console.log(`\u{1F916} Agent: ${msg.data}`);
           }
@@ -1081,7 +1107,6 @@ var VoiceAgentClient = class {
           if (msg.data === "interrupted" && this.audioManager) {
             this.audioManager.stopPlayback();
           }
-          if (this.onStatus) this.onStatus(msg.data);
           this.emit("status", msg.data);
           const icons = {
             "interrupted": "\u26A1",
@@ -1131,11 +1156,12 @@ var VoiceAgentClient = class {
           }
           break;
         }
-        case "tool_call":
-          this.emit("tool_call", { name: msg.name, arguments: msg.arguments });
+        case "tool_call": {
+          const call = { name: msg.name, arguments: msg.arguments, call_id: msg.call_id };
           console.log(`\u{1F6E0}\uFE0F Tool Call: ${msg.name}(${msg.arguments})`);
-          this.emit("tool_call", msg);
+          this.emit("tool_call", call);
           break;
+        }
       }
     } catch (e) {
       sdkTrace("ws.recv.parse_error", { preview: text?.slice(0, 120) });
@@ -1249,7 +1275,7 @@ var VoiceAgentClient = class {
    * No authentication required.
    */
   static async fetchVoices(baseUrl) {
-    const url = wsToHttp(baseUrl || DEFAULT_URLS.VOICE_AGENT);
+    const url = apiOrigin(baseUrl);
     const data = await fetchJson(`${url}/voices`);
     return data.voices || [];
   }
@@ -1258,7 +1284,7 @@ var VoiceAgentClient = class {
    * No authentication required.
    */
   static async fetchLanguages(baseUrl) {
-    const url = wsToHttp(baseUrl || DEFAULT_URLS.VOICE_AGENT);
+    const url = apiOrigin(baseUrl);
     const data = await fetchJson(`${url}/languages`);
     return data.languages || [];
   }
@@ -1267,7 +1293,7 @@ var VoiceAgentClient = class {
    * No authentication required.
    */
   static async fetchModels(baseUrl) {
-    const url = wsToHttp(baseUrl || DEFAULT_URLS.VOICE_AGENT);
+    const url = apiOrigin(baseUrl);
     const data = await fetchJson(`${url}/models`);
     return data.models || [];
   }
@@ -1276,7 +1302,7 @@ var VoiceAgentClient = class {
    * No authentication required.
    */
   static async fetchConfig(baseUrl) {
-    const url = wsToHttp(baseUrl || DEFAULT_URLS.VOICE_AGENT);
+    const url = apiOrigin(baseUrl);
     return fetchJson(`${url}/config`);
   }
   /**
@@ -1284,16 +1310,16 @@ var VoiceAgentClient = class {
    * No authentication required.
    */
   static async fetchStatus(baseUrl) {
-    const url = wsToHttp(baseUrl || DEFAULT_URLS.VOICE_AGENT);
+    const url = apiOrigin(baseUrl);
     return fetchJson(`${url}/status`);
   }
   /**
-   * Fetch health/liveness status from the server.
-   * No authentication required.
+   * Fetch readiness from the server (GET /ready: 200 once it can serve).
+   * No authentication required. (/health is the operator dashboard's and needs its password.)
    */
   static async fetchHealth(baseUrl) {
-    const url = wsToHttp(baseUrl || DEFAULT_URLS.VOICE_AGENT);
-    return fetchJson(`${url}/health`);
+    const url = apiOrigin(baseUrl);
+    return fetchJson(`${url}/ready`);
   }
   /**
    * Update the system prompt mid-conversation
@@ -1318,6 +1344,7 @@ var VoiceAgentClient = class {
    */
   updateVoice(voice) {
     this.voice = voice;
+    this.voiceExplicit = true;
     if (this.ws && this.ws.readyState === WebSocket.OPEN && this.isConnected) {
       this.ws.send(JSON.stringify({ type: "voice", data: voice }));
       console.log(`\u2699\uFE0F Updated voice: ${voice}`);
@@ -1328,6 +1355,7 @@ var VoiceAgentClient = class {
    */
   updateLanguage(language) {
     this.language = language;
+    this.languageExplicit = true;
     if (this.ws && this.ws.readyState === WebSocket.OPEN && this.isConnected) {
       this.ws.send(JSON.stringify({ type: "language", data: language }));
       console.log(`\u2699\uFE0F Updated language: ${language}`);
@@ -1387,98 +1415,120 @@ var TTSClient = class {
    */
   synthesize(options) {
     return new Promise((resolve, reject) => {
-      let activityTimeout;
+      let timer;
       let ws;
       let startTime;
       let firstByteReceived = false;
-      const refreshTimeout = () => {
-        if (activityTimeout) clearTimeout(activityTimeout);
-        activityTimeout = setTimeout(() => {
-          console.log("\u23F1\uFE0F TTS synthesis reached inactivity timeout (2s) - resolving");
-          if (ws) ws.close();
+      let finished = false;
+      const finish = (err) => {
+        if (finished) return;
+        finished = true;
+        if (timer) clearTimeout(timer);
+        try {
+          ws?.close();
+        } catch {
+        }
+        if (err) {
+          if (options.onError) options.onError(err);
+          reject(err);
+        } else {
           resolve();
-        }, 2e3);
+        }
+      };
+      const arm = () => {
+        if (timer) clearTimeout(timer);
+        timer = setTimeout(
+          () => finish(new LokutorError(
+            "internal.timeout",
+            firstByteReceived ? "TTS stream stalled" : "No audio within 30 s",
+            { retryable: true }
+          )),
+          firstByteReceived ? 15e3 : 3e4
+        );
       };
       try {
         let url = DEFAULT_URLS.TTS;
         if (this.apiKey) {
           const separator = url.includes("?") ? "&" : "?";
-          url += `${separator}api_key=${this.apiKey}`;
+          url += `${separator}api_key=${encodeURIComponent(this.apiKey)}`;
         }
         ws = new WebSocket(url);
         ws.binaryType = "arraybuffer";
         ws.onopen = () => {
-          refreshTimeout();
+          arm();
           const req = {
             text: options.text,
             voice: options.voice || "F1" /* F1 */,
             language: options.language || "en" /* ENGLISH */,
-            speed: options.speed || 1.05,
-            steps: options.steps || 24,
             visemes: options.visemes || false
           };
+          if (options.speed !== void 0) req.speed = options.speed;
+          if (options.steps !== void 0) req.steps = options.steps;
           ws.send(JSON.stringify(req));
           startTime = nowMs();
         };
         ws.onmessage = async (event) => {
-          refreshTimeout();
           if (event.data instanceof ArrayBuffer) {
             if (!firstByteReceived) {
               const ttfb = nowMs() - startTime;
               if (options.onTTFB) options.onTTFB(ttfb);
               firstByteReceived = true;
             }
+            arm();
             if (options.onAudio) options.onAudio(new Uint8Array(event.data));
             return;
           }
           const text = event.data.toString();
           if (text === "EOS") {
-            if (activityTimeout) clearTimeout(activityTimeout);
-            ws.close();
-            resolve();
+            finish();
             return;
           }
+          let msg;
           try {
-            const msg = JSON.parse(text);
-            if (msg.type === "audio" && msg.data) {
-              const audioBuffer = base64ToUint8Array(msg.data);
-              if (!firstByteReceived) {
-                const ttfb = nowMs() - startTime;
-                if (options.onTTFB) options.onTTFB(ttfb);
-                firstByteReceived = true;
-              }
-              if (options.onAudio) options.onAudio(audioBuffer);
-              return;
-            }
-            if (msg.type === "visemes" && Array.isArray(msg.data) && options.onVisemes) {
-              options.onVisemes(normalizeVisemes(msg.data));
-              return;
-            }
-            if (Array.isArray(msg) && options.onVisemes) {
-              options.onVisemes(normalizeVisemes(msg));
-              return;
-            }
-            if (msg.type === "eos") {
-              if (activityTimeout) clearTimeout(activityTimeout);
-              ws.close();
-              resolve();
+            msg = JSON.parse(text);
+          } catch {
+            return;
+          }
+          if (msg.type === "error") {
+            const data = typeof msg.data === "object" && msg.data ? msg.data : { message: msg.data };
+            finish(new LokutorError(data.code ?? "internal.error", data.message ?? "TTS failed", {
+              detail: data.detail,
+              retryable: data.retryable ?? false
+            }));
+            return;
+          }
+          if (msg.type === "audio" && msg.data) {
+            const audioBuffer = base64ToUint8Array(msg.data);
+            if (!firstByteReceived) {
+              const ttfb = nowMs() - startTime;
+              if (options.onTTFB) options.onTTFB(ttfb);
+              firstByteReceived = true;
             }
-          } catch (e) {
+            arm();
+            if (options.onAudio) options.onAudio(audioBuffer);
+            return;
+          }
+          if (msg.type === "visemes" && Array.isArray(msg.data) && options.onVisemes) {
+            options.onVisemes(normalizeVisemes(msg.data));
+            return;
+          }
+          if (Array.isArray(msg) && options.onVisemes) {
+            options.onVisemes(normalizeVisemes(msg));
+            return;
+          }
+          if (msg.type === "eos") {
+            finish();
           }
         };
-        ws.onerror = (err) => {
-          if (activityTimeout) clearTimeout(activityTimeout);
-          if (options.onError) options.onError(err);
-          reject(err);
-        };
-        ws.onclose = () => {
-          if (activityTimeout) clearTimeout(activityTimeout);
-          resolve();
+        ws.onerror = (err) => finish(err);
+        ws.onclose = (ev) => {
+          if (!finished) {
+            if (firstByteReceived && ev.code === 1e3) finish();
+            else finish(new LokutorError("internal.error", `TTS socket closed (${ev.code}${ev.reason ? `: ${ev.reason}` : ""})`, { retryable: true }));
+          }
         };
       } catch (err) {
-        if (activityTimeout) clearTimeout(activityTimeout);
-        if (options.onError) options.onError(err);
-        reject(err);
+        finish(err);
       }
     });
   }
@@ -1584,17 +1634,28 @@ var SpeechToTextClient = class {
       try {
         let url = this.serverUrl;
         const separator = url.includes("?") ? "&" : "?";
-        url += `${separator}api_key=${this.apiKey}`;
+        url += `${separator}api_key=${encodeURIComponent(this.apiKey)}`;
         this.ws = new WebSocket(url);
         this.ws.onopen = async () => {
           this.isConnected = true;
           this.onStatusChange?.("connected");
           this.ws.send(JSON.stringify({ language: this.language || "en" /* ENGLISH */, vad: this.vad }));
-          await this.audioManager.startMicrophone((data) => {
-            if (this.isConnected && this.ws?.readyState === WebSocket.OPEN) {
-              this.ws.send(data);
+          try {
+            await this.audioManager.startMicrophone((data) => {
+              if (this.isConnected && this.ws?.readyState === WebSocket.OPEN) {
+                this.ws.send(data);
+              }
+            });
+          } catch (err) {
+            const error = err instanceof LokutorError ? err : new LokutorError("audio.microphone_unavailable", "Could not start the microphone", { original: err });
+            this.onError?.(error);
+            try {
+              this.ws?.close();
+            } catch {
             }
-          });
+            settle(() => reject(error));
+            return;
+          }
           settle(() => resolve(true));
         };
         this.ws.onmessage = (event) => {
@@ -1608,7 +1669,11 @@ var SpeechToTextClient = class {
                 this.onPartialTranscript?.(msg.data ?? "");
               }
             } else if (msg.type === "error") {
-              this.onError?.(new LokutorError("internal.error", msg.data ?? "STT error"));
+              const data = typeof msg.data === "object" && msg.data ? msg.data : { message: msg.data };
+              this.onError?.(new LokutorError(data.code ?? "internal.error", data.message ?? "STT error", {
+                detail: data.detail,
+                retryable: data.retryable ?? false
+              }));
             }
           } catch {
           }

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@lokutor/sdk",
-  "version": "1.5.1",
+  "version": "1.6.0",
   "description": "JavaScript/TypeScript SDK for Lokutor Real-time Voice AI",
   "main": "./dist/index.js",
   "module": "./dist/index.mjs",