@estuary-ai/sdk 0.1.31 → 0.2.0

package/dist/index.mjs

@@ -26976,11 +26976,8 @@ var init_websocket_voice = __esm({
         this.logger.debug("WebSocket voice stopped");
       }
       toggleMute() {
-        if (!this._isActive || !this.mediaStream) return;
+        if (!this._isActive) return;
         this._isMuted = !this._isMuted;
-        for (const track of this.mediaStream.getAudioTracks()) {
-          track.enabled = !this._isMuted;
-        }
         this.logger.debug("Mute toggled:", this._isMuted);
       }
       setSuppressed(suppressed) {
@@ -27038,6 +27035,7 @@ var init_livekit_voice = __esm({
       room = null;
       // livekit-client Room (dynamically imported)
       _isMuted = false;
+      _isSuppressed = false;
       _isActive = false;
       speakingStateCallback = null;
       audioLevelCallback = null;
@@ -27204,14 +27202,20 @@ var init_livekit_voice = __esm({
         }
         this._isActive = false;
         this._isMuted = false;
+        this._isSuppressed = false;
         this.logger.debug("LiveKit voice stopped");
       }
       toggleMute() {
         if (!this._isActive || !this.room) return;
         this._isMuted = !this._isMuted;
-        this.room.localParticipant.setMicrophoneEnabled(!this._isMuted);
+        this.updateTrackEnabled();
         this.logger.debug("Mute toggled:", this._isMuted);
       }
+      setSuppressed(suppressed) {
+        this._isSuppressed = suppressed;
+        this.updateTrackEnabled();
+        this.logger.debug("Audio suppression:", suppressed ? "on" : "off");
+      }
       dispose() {
         this.speakingStateCallback = null;
         this.audioLevelCallback = null;
@@ -27225,6 +27229,19 @@ var init_livekit_voice = __esm({
         }
         this._isActive = false;
         this._isMuted = false;
+        this._isSuppressed = false;
+      }
+      /** Mute/unmute the local audio track directly via MediaStreamTrack.enabled.
+       *  This avoids setMicrophoneEnabled() which publishes/unpublishes the track
+       *  through the LiveKit server and can fail with engine timeout errors. */
+      updateTrackEnabled() {
+        if (!this.room) return;
+        const enabled = !this._isMuted && !this._isSuppressed;
+        for (const [, publication] of this.room.localParticipant.audioTrackPublications) {
+          if (publication.track?.mediaStreamTrack) {
+            publication.track.mediaStreamTrack.enabled = enabled;
+          }
+        }
       }
       // ─── Audio Level Polling (participant.audioLevel) ───────────────
       startAudioLevelPolling() {
@@ -30751,7 +30768,8 @@ function toBotVoice(wire) {
     audio: wire.audio,
     messageId: wire.message_id,
     chunkIndex: wire.chunk_index,
-    isFinal: wire.is_final
+    isFinal: wire.is_final ?? false,
+    isLivekit: wire.is_livekit
   };
 }
 function toSttResponse(wire) {
@@ -30849,13 +30867,18 @@ var SocketManager = class extends TypedEventEmitter {
       let settled = false;
       const onConnect = () => {
         this.logger.debug("Socket connected, authenticating...");
-        this.socket.emit("authenticate", {
-          api_key: this.config.apiKey,
+        const authPayload = {
           character_id: this.config.characterId,
           player_id: this.config.playerId,
           audio_sample_rate: this.config.audioSampleRate ?? 16e3,
           realtime_memory: this.config.realtimeMemory ?? false
-        });
+        };
+        if (this.config.sessionToken) {
+          authPayload.api_key = this.config.sessionToken;
+        } else if (this.config.apiKey) {
+          authPayload.api_key = this.config.apiKey;
+        }
+        this.socket.emit("authenticate", authPayload);
       };
       const onSessionInfo = (data) => {
         this.sessionInfo = toSessionInfo(data);
@@ -31184,6 +31207,7 @@ var AudioPlayer = class _AudioPlayer {
   _isCleared = false;
   _interruptedMessageId = null;
   _drainTimer = null;
+  /** How long to wait for more chunks before declaring playback complete (ms) */
   static DRAIN_DELAY_MS = 300;
   constructor(sampleRate, onEvent) {
     this.sampleRate = sampleRate;
@@ -31202,6 +31226,7 @@ var AudioPlayer = class _AudioPlayer {
     this._interruptedMessageId = id;
   }
   enqueue(voice) {
+    if (!voice.audio) return;
     if (voice.messageId === this._interruptedMessageId) return;
     if (this._interruptedMessageId && voice.messageId !== this._interruptedMessageId) {
       this._interruptedMessageId = null;
@@ -31215,7 +31240,9 @@ var AudioPlayer = class _AudioPlayer {
     const buffer = ctx.createBuffer(1, float32.length, this.sampleRate);
     buffer.getChannelData(0).set(float32);
     this.queue.push({ buffer, messageId: voice.messageId });
-    if (!this.isPlaying) {
+    const wasDraining = this._drainTimer !== null;
+    this.cancelDrain();
+    if (!this.isPlaying || wasDraining) {
       this.playNext();
     }
   }
@@ -31314,6 +31341,7 @@ var AudioPlayer = class _AudioPlayer {
       }
       return;
     }
+    this.cancelDrain();
     const { buffer, messageId } = this.queue.shift();
     if (messageId !== this.currentMessageId) {
       if (this.currentMessageId) {
@@ -31434,35 +31462,51 @@ function parseActions(text) {
 }
 
 // src/client.ts
-var DEFAULT_SAMPLE_RATE = 16e3;
+var DEFAULT_SAMPLE_RATE = 24e3;
+var REST_UNAVAILABLE_MESSAGE = "REST API not available with session token auth. Use a server-side proxy for REST calls.";
 var EstuaryClient = class extends TypedEventEmitter {
   config;
   logger;
   socketManager;
   voiceManager = null;
   audioPlayer = null;
-  _memory;
-  _character;
+  _memory = null;
+  _character = null;
   _sessionInfo = null;
   actionParsers = /* @__PURE__ */ new Map();
   _hasAutoInterrupted = false;
   _autoInterruptGraceTimer = null;
+  _isLiveKitSpeaking = false;
   constructor(config) {
     super();
+    if (!config.apiKey && !config.sessionToken) {
+      throw new EstuaryError(
+        "AUTH_FAILED" /* AUTH_FAILED */,
+        "Either apiKey or sessionToken must be provided"
+      );
+    }
     this.config = config;
     this.logger = new Logger(config.debug ?? false);
     this.socketManager = new SocketManager(config, this.logger);
     this.forwardSocketEvents();
-    const restClient = new RestClient(config.serverUrl, config.apiKey);
-    this._memory = new MemoryClient(restClient, config.characterId, config.playerId);
-    this._character = new CharacterClient(restClient);
+    if (config.apiKey) {
+      const restClient = new RestClient(config.serverUrl, config.apiKey);
+      this._memory = new MemoryClient(restClient, config.characterId, config.playerId);
+      this._character = new CharacterClient(restClient);
+    }
   }
   /** Memory API client for querying memories, graphs, and facts */
   get memory() {
+    if (!this._memory) {
+      throw new EstuaryError("NOT_CONNECTED" /* NOT_CONNECTED */, REST_UNAVAILABLE_MESSAGE);
+    }
     return this._memory;
   }
   /** Fetch character details including 3D model and avatar URLs. */
   async getCharacter(characterId) {
+    if (!this._character) {
+      throw new EstuaryError("NOT_CONNECTED" /* NOT_CONNECTED */, REST_UNAVAILABLE_MESSAGE);
+    }
     return this._character.getCharacter(characterId ?? this.config.characterId);
   }
   /** Current session info (null if not connected) */
@@ -31502,6 +31546,12 @@ var EstuaryClient = class extends TypedEventEmitter {
     this.ensureConnected();
     this.socketManager.emitEvent("text", { text, textOnly });
   }
+  /** Script the character to say a specific prewritten line. Defaults to TTS enabled (textOnly=false). */
+  sayLine(text, textOnly = false) {
+    if (!text?.trim()) return;
+    this.ensureConnected();
+    this.socketManager.emitEvent("say_line", { text, text_only: textOnly });
+  }
   /** Interrupt the current bot response */
   interrupt(messageId) {
     this.ensureConnected();
@@ -31554,12 +31604,7 @@ var EstuaryClient = class extends TypedEventEmitter {
     if (!this.audioPlayer && result.resolvedTransport === "websocket" && typeof AudioContext !== "undefined") {
       this.audioPlayer = new AudioPlayer(sampleRate, (event) => {
         if (event.type === "started") {
-          this._hasAutoInterrupted = true;
-          if (this._autoInterruptGraceTimer) clearTimeout(this._autoInterruptGraceTimer);
-          this._autoInterruptGraceTimer = setTimeout(() => {
-            this._hasAutoInterrupted = false;
-            this._autoInterruptGraceTimer = null;
-          }, 1500);
+          this.startPlaybackGrace();
           this.emit("audioPlaybackStarted", event.messageId);
           if (this.config.suppressMicDuringPlayback) {
             this.voiceManager?.setSuppressed?.(true);
@@ -31576,7 +31621,9 @@ var EstuaryClient = class extends TypedEventEmitter {
     }
     await this.voiceManager.start();
     this.voiceManager.setSpeakingStateCallback?.((speaking) => {
+      this._isLiveKitSpeaking = speaking;
       if (speaking) {
+        this.startPlaybackGrace();
         this.emit("audioPlaybackStarted", "livekit-audio");
         if (this.config.suppressMicDuringPlayback) {
           this.voiceManager?.setSuppressed?.(true);
@@ -31601,6 +31648,7 @@ var EstuaryClient = class extends TypedEventEmitter {
       await this.voiceManager.stop();
       this.voiceManager.dispose();
       this.voiceManager = null;
+      this._isLiveKitSpeaking = false;
       this.emit("voiceStopped");
     }
   }
@@ -31615,12 +31663,19 @@ var EstuaryClient = class extends TypedEventEmitter {
   get isMuted() {
     return this.voiceManager?.isMuted ?? false;
   }
-  /** Get/set suppressMicDuringPlayback at runtime (no reconnect needed) */
+  /** Whether mic suppression during playback is enabled */
   get suppressMicDuringPlayback() {
     return this.config.suppressMicDuringPlayback ?? false;
   }
+  /** Update mic suppression during playback at runtime (no reconnect needed) */
   set suppressMicDuringPlayback(enabled) {
     this.config.suppressMicDuringPlayback = enabled;
+    if (!this.voiceManager?.isActive) return;
+    if (enabled && this._isBotPlaying) {
+      this.voiceManager.setSuppressed?.(true);
+    } else if (!enabled) {
+      this.voiceManager.setSuppressed?.(false);
+    }
   }
   /** Whether voice is currently active */
   get isVoiceActive() {
@@ -31632,6 +31687,20 @@ var EstuaryClient = class extends TypedEventEmitter {
       throw new EstuaryError("NOT_CONNECTED" /* NOT_CONNECTED */, "Not connected to server. Call connect() first.");
     }
   }
+  /** Whether bot audio is currently playing (via AudioPlayer or LiveKit) */
+  get _isBotPlaying() {
+    return (this.audioPlayer?.playing ?? false) || this._isLiveKitSpeaking;
+  }
+  /** Suppress auto-interrupt for 1500ms so trailing STT partials from the
+   *  user's previous speech don't kill the new bot audio. */
+  startPlaybackGrace() {
+    this._hasAutoInterrupted = true;
+    if (this._autoInterruptGraceTimer) clearTimeout(this._autoInterruptGraceTimer);
+    this._autoInterruptGraceTimer = setTimeout(() => {
+      this._hasAutoInterrupted = false;
+      this._autoInterruptGraceTimer = null;
+    }, 1500);
+  }
   forwardSocketEvents() {
     this.socketManager.on("connected", (session) => {
       this._sessionInfo = session;
@@ -31721,7 +31790,7 @@ var EstuaryClient = class extends TypedEventEmitter {
     if ((this.config.autoInterruptOnSpeech ?? true) === false) return;
     if (this.config.suppressMicDuringPlayback) return;
     if (stt.isFinal) return;
-    if (!this.audioPlayer?.playing) return;
+    if (!this._isBotPlaying) return;
     if (this._hasAutoInterrupted) return;
     this._hasAutoInterrupted = true;
     this.interrupt();