@estuary-ai/sdk 0.1.32 → 0.2.0

package/dist/index.d.mts

@@ -1,8 +1,10 @@
 interface EstuaryConfig {
     /** Base URL of the Estuary server (e.g., "https://api.estuary-ai.com") */
     serverUrl: string;
-    /** API key (starts with "est_") */
-    apiKey: string;
+    /** API key (starts with "est_"). Required unless sessionToken is provided. */
+    apiKey?: string;
+    /** Session token from share exchange (starts with "sst_"). Alternative to apiKey for share flows. */
+    sessionToken?: string;
     /** Character (agent) ID */
     characterId: string;
     /** Unique identifier for the end user */
@@ -50,10 +52,11 @@ interface BotResponse {
     tokenStream?: boolean;
 }
 interface BotVoice {
-    audio: string;
+    audio?: string;
     messageId: string;
     chunkIndex: number;
-    isFinal: boolean;
+    isFinal?: boolean;
+    isLivekit?: boolean;
 }
 interface SttResponse {
     text: string;
@@ -330,6 +333,7 @@ declare class EstuaryClient extends TypedEventEmitter<EstuaryEventMap> {
     private actionParsers;
     private _hasAutoInterrupted;
     private _autoInterruptGraceTimer;
+    private _isLiveKitSpeaking;
     constructor(config: EstuaryConfig);
     /** Memory API client for querying memories, graphs, and facts */
     get memory(): MemoryClient;
@@ -347,6 +351,8 @@ declare class EstuaryClient extends TypedEventEmitter<EstuaryEventMap> {
     disconnect(): Promise<void>;
     /** Send a text message to the character. Defaults to textOnly=true (no TTS audio response). Pass textOnly=false to receive voice audio. */
     sendText(text: string, textOnly?: boolean): void;
+    /** Script the character to say a specific prewritten line. Defaults to TTS enabled (textOnly=false). */
+    sayLine(text: string, textOnly?: boolean): void;
     /** Interrupt the current bot response */
     interrupt(messageId?: string): void;
     /** Send a camera image for vision processing */
@@ -365,12 +371,18 @@ declare class EstuaryClient extends TypedEventEmitter<EstuaryEventMap> {
     toggleMute(): void;
     /** Whether the microphone is muted */
     get isMuted(): boolean;
-    /** Get/set suppressMicDuringPlayback at runtime (no reconnect needed) */
+    /** Whether mic suppression during playback is enabled */
     get suppressMicDuringPlayback(): boolean;
+    /** Update mic suppression during playback at runtime (no reconnect needed) */
     set suppressMicDuringPlayback(enabled: boolean);
     /** Whether voice is currently active */
     get isVoiceActive(): boolean;
     private ensureConnected;
+    /** Whether bot audio is currently playing (via AudioPlayer or LiveKit) */
+    private get _isBotPlaying();
+    /** Suppress auto-interrupt for 1500ms so trailing STT partials from the
+     *  user's previous speech don't kill the new bot audio. */
+    private startPlaybackGrace;
     private forwardSocketEvents;
     private handleBotResponse;
     private handleBotVoice;

package/dist/index.d.ts

@@ -1,8 +1,10 @@
 interface EstuaryConfig {
     /** Base URL of the Estuary server (e.g., "https://api.estuary-ai.com") */
     serverUrl: string;
-    /** API key (starts with "est_") */
-    apiKey: string;
+    /** API key (starts with "est_"). Required unless sessionToken is provided. */
+    apiKey?: string;
+    /** Session token from share exchange (starts with "sst_"). Alternative to apiKey for share flows. */
+    sessionToken?: string;
     /** Character (agent) ID */
     characterId: string;
     /** Unique identifier for the end user */
@@ -50,10 +52,11 @@ interface BotResponse {
     tokenStream?: boolean;
 }
 interface BotVoice {
-    audio: string;
+    audio?: string;
     messageId: string;
     chunkIndex: number;
-    isFinal: boolean;
+    isFinal?: boolean;
+    isLivekit?: boolean;
 }
 interface SttResponse {
     text: string;
@@ -330,6 +333,7 @@ declare class EstuaryClient extends TypedEventEmitter<EstuaryEventMap> {
     private actionParsers;
     private _hasAutoInterrupted;
     private _autoInterruptGraceTimer;
+    private _isLiveKitSpeaking;
     constructor(config: EstuaryConfig);
     /** Memory API client for querying memories, graphs, and facts */
     get memory(): MemoryClient;
@@ -347,6 +351,8 @@ declare class EstuaryClient extends TypedEventEmitter<EstuaryEventMap> {
     disconnect(): Promise<void>;
     /** Send a text message to the character. Defaults to textOnly=true (no TTS audio response). Pass textOnly=false to receive voice audio. */
     sendText(text: string, textOnly?: boolean): void;
+    /** Script the character to say a specific prewritten line. Defaults to TTS enabled (textOnly=false). */
+    sayLine(text: string, textOnly?: boolean): void;
     /** Interrupt the current bot response */
     interrupt(messageId?: string): void;
     /** Send a camera image for vision processing */
@@ -365,12 +371,18 @@ declare class EstuaryClient extends TypedEventEmitter<EstuaryEventMap> {
     toggleMute(): void;
     /** Whether the microphone is muted */
     get isMuted(): boolean;
-    /** Get/set suppressMicDuringPlayback at runtime (no reconnect needed) */
+    /** Whether mic suppression during playback is enabled */
     get suppressMicDuringPlayback(): boolean;
+    /** Update mic suppression during playback at runtime (no reconnect needed) */
     set suppressMicDuringPlayback(enabled: boolean);
     /** Whether voice is currently active */
     get isVoiceActive(): boolean;
     private ensureConnected;
+    /** Whether bot audio is currently playing (via AudioPlayer or LiveKit) */
+    private get _isBotPlaying();
+    /** Suppress auto-interrupt for 1500ms so trailing STT partials from the
+     *  user's previous speech don't kill the new bot audio. */
+    private startPlaybackGrace;
     private forwardSocketEvents;
     private handleBotResponse;
     private handleBotVoice;

package/dist/index.js

@@ -4980,11 +4980,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) {
@@ -5042,6 +5039,7 @@ var init_livekit_voice = __esm({
       room = null;
       // livekit-client Room (dynamically imported)
       _isMuted = false;
+      _isSuppressed = false;
       _isActive = false;
       speakingStateCallback = null;
       audioLevelCallback = null;
@@ -5208,14 +5206,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;
@@ -5229,6 +5233,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() {
@@ -8911,7 +8928,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) {
@@ -9009,13 +9027,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);
@@ -9344,6 +9367,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;
@@ -9362,6 +9386,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;
@@ -9375,7 +9400,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();
     }
   }
@@ -9474,6 +9501,7 @@ var AudioPlayer = class _AudioPlayer {
       }
       return;
     }
+    this.cancelDrain();
     const { buffer, messageId } = this.queue.shift();
     if (messageId !== this.currentMessageId) {
       if (this.currentMessageId) {
@@ -9595,34 +9623,50 @@ function parseActions(text) {
 
 // src/client.ts
 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 exports.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 exports.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 exports.EstuaryError("NOT_CONNECTED" /* NOT_CONNECTED */, REST_UNAVAILABLE_MESSAGE);
+    }
     return this._character.getCharacter(characterId ?? this.config.characterId);
   }
   /** Current session info (null if not connected) */
@@ -9662,6 +9706,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();
@@ -9714,12 +9764,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);
@@ -9736,7 +9781,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);
@@ -9761,6 +9808,7 @@ var EstuaryClient = class extends TypedEventEmitter {
       await this.voiceManager.stop();
       this.voiceManager.dispose();
       this.voiceManager = null;
+      this._isLiveKitSpeaking = false;
       this.emit("voiceStopped");
     }
   }
@@ -9775,12 +9823,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() {
@@ -9792,6 +9847,20 @@ var EstuaryClient = class extends TypedEventEmitter {
       throw new exports.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;
@@ -9881,7 +9950,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();