@estuary-ai/sdk 0.4.1 → 0.5.0

package/dist/index.mjs

@@ -31464,6 +31464,231 @@ function parseActions(text) {
   return parser2.parse(text);
 }
 
+// src/scripting/script-player.ts
+var DEFAULT_LINE_TIMEOUT_MS = 3e4;
+var ScriptPlayer = class {
+  host;
+  lines;
+  lineGapMs;
+  loop;
+  lineTimeoutMs;
+  _index = -1;
+  _state = "idle";
+  currentMessageId = null;
+  lineAcked = false;
+  retiredIds = /* @__PURE__ */ new Set();
+  selfInterruptPending = false;
+  pauseRequested = false;
+  // Number of stray bot_responses still expected from text-only lines that were superseded
+  // (via next()/stop()) BEFORE they were acked. Their server messageId isn't known yet, so we
+  // can't retire them by id — instead we swallow that many fresh responses by arrival order.
+  pendingStaleResponses = 0;
+  lineTimer = null;
+  gapTimer = null;
+  resolveDone;
+  done;
+  onBotResponse = (r2) => this.handleBotResponse(r2);
+  onAudioComplete = (messageId) => this.handleAudioComplete(messageId);
+  onInterrupt = (data) => this.handleExternalInterrupt(data);
+  onDisconnected = () => this.finish("disconnected");
+  constructor(host, lines, opts = {}) {
+    this.host = host;
+    const defaultTextOnly = opts.textOnly ?? false;
+    this.lines = lines.map(
+      (line) => typeof line === "string" ? { text: line, textOnly: defaultTextOnly } : { text: line.text, textOnly: line.textOnly ?? defaultTextOnly }
+    );
+    this.lineGapMs = Math.max(0, opts.lineGapMs ?? 0);
+    this.loop = opts.loop ?? false;
+    this.lineTimeoutMs = opts.lineTimeoutMs ?? DEFAULT_LINE_TIMEOUT_MS;
+    this.done = new Promise((resolve) => {
+      this.resolveDone = resolve;
+    });
+    this.host.on("botResponse", this.onBotResponse);
+    this.host.on("audioPlaybackComplete", this.onAudioComplete);
+    this.host.on("interrupt", this.onInterrupt);
+    this.host.on("disconnected", this.onDisconnected);
+    if (opts.autoStart ?? true) {
+      queueMicrotask(() => this.play());
+    }
+  }
+  get length() {
+    return this.lines.length;
+  }
+  get index() {
+    return this._index;
+  }
+  get state() {
+    return this._state;
+  }
+  play() {
+    if (this._state === "done" || this._state === "playing") return;
+    this.pauseRequested = false;
+    this._state = "playing";
+    this.startNextLine();
+  }
+  resume() {
+    this.play();
+  }
+  pause() {
+    if (this._state === "done") return;
+    this.pauseRequested = true;
+  }
+  next() {
+    if (this._state === "done") return;
+    if (this._state === "idle") {
+      this.play();
+      return;
+    }
+    const expectInterrupt = this._state === "playing";
+    this.pauseRequested = false;
+    this._state = "playing";
+    this.clearTimers();
+    this.supersedeCurrentLine(expectInterrupt);
+    this.startNextLine();
+  }
+  stop() {
+    this.finish("stopped", true);
+  }
+  // ─── internals ────────────────────────────────────────────────
+  hasSpeakableLine() {
+    return this.lines.some((l) => l.text.trim().length > 0);
+  }
+  startNextLine() {
+    if (this._state !== "playing") return;
+    if (!this.hasSpeakableLine()) {
+      this.finish("finished");
+      return;
+    }
+    let next = this._index + 1;
+    for (; ; ) {
+      if (next >= this.lines.length) {
+        if (this.loop) {
+          next = 0;
+        } else {
+          this.finish("finished");
+          return;
+        }
+      }
+      if (this.lines[next].text.trim()) break;
+      next++;
+    }
+    this._index = next;
+    this.currentMessageId = null;
+    this.lineAcked = false;
+    if (!this.host.isConnected) {
+      this.finish("disconnected");
+      return;
+    }
+    const line = this.lines[next];
+    this.host.sayLine(line.text, line.textOnly);
+    this.lineTimer = setTimeout(() => this.handleLineTimeout(), this.lineTimeoutMs);
+  }
+  handleBotResponse(r2) {
+    if (this._state === "done" || this._index < 0) return;
+    if (r2.messageId && this.retiredIds.has(r2.messageId)) return;
+    if (r2.isInterjection) return;
+    if (!this.lineAcked) {
+      if (this.pendingStaleResponses > 0) {
+        this.pendingStaleResponses--;
+        if (r2.messageId) this.retiredIds.add(r2.messageId);
+        return;
+      }
+      this.lineAcked = true;
+      this.currentMessageId = r2.messageId ?? null;
+      this.selfInterruptPending = false;
+      this.host.emitScriptLineStarted({
+        index: this._index,
+        text: this.lines[this._index].text,
+        messageId: r2.messageId
+      });
+    }
+    if (this.currentMessageId && r2.messageId && r2.messageId !== this.currentMessageId) return;
+    const line = this.lines[this._index];
+    const completesOnResponse = line.textOnly || !this.host.willPlayScriptedAudio;
+    if (completesOnResponse && r2.isFinal) {
+      this.onLineComplete();
+    }
+  }
+  handleAudioComplete(messageId) {
+    if (this._state === "done" || this._index < 0) return;
+    if (messageId && this.retiredIds.has(messageId)) return;
+    const line = this.lines[this._index];
+    if (line.textOnly || !this.host.willPlayScriptedAudio) return;
+    if (this.currentMessageId && messageId && messageId !== this.currentMessageId) return;
+    this.onLineComplete();
+  }
+  handleLineTimeout() {
+    if (this._state === "done") return;
+    this.host.log(`script line ${this._index} timed out after ${this.lineTimeoutMs}ms; advancing`);
+    this.onLineComplete();
+  }
+  onLineComplete() {
+    this.clearTimers();
+    if (this.lineGapMs > 0) {
+      this.gapTimer = setTimeout(() => this.afterGap(), this.lineGapMs);
+    } else {
+      this.afterGap();
+    }
+  }
+  afterGap() {
+    this.gapTimer = null;
+    if (this._state === "done") return;
+    if (this.pauseRequested) {
+      this._state = "paused";
+      return;
+    }
+    this.startNextLine();
+  }
+  handleExternalInterrupt(data) {
+    if (this._state === "done") return;
+    if (data?.messageId && this.retiredIds.has(data.messageId)) return;
+    if (this.selfInterruptPending) {
+      this.selfInterruptPending = false;
+      return;
+    }
+    this.finish("interrupted");
+  }
+  /**
+   * Retire the current line because we're moving off it.
+   * @param expectInterrupt true when the line is still in-flight (next()/stop() mid-line), so the
+   *   server will emit a self-induced `interrupt` we must not treat as external. false when the
+   *   line already completed (e.g. next() while paused), where no interrupt is coming.
+   */
+  supersedeCurrentLine(expectInterrupt) {
+    if (this.lineAcked && this.currentMessageId) {
+      this.retiredIds.add(this.currentMessageId);
+    } else if (expectInterrupt && this.lines[this._index]?.textOnly) {
+      this.pendingStaleResponses++;
+    }
+    if (expectInterrupt) this.selfInterruptPending = true;
+  }
+  clearTimers() {
+    if (this.lineTimer) {
+      clearTimeout(this.lineTimer);
+      this.lineTimer = null;
+    }
+    if (this.gapTimer) {
+      clearTimeout(this.gapTimer);
+      this.gapTimer = null;
+    }
+  }
+  finish(reason, interrupt = false) {
+    if (this._state === "done") return;
+    this.clearTimers();
+    if (interrupt) {
+      this.selfInterruptPending = true;
+      if (this.host.isConnected) this.host.interrupt();
+    }
+    this._state = "done";
+    this.host.off("botResponse", this.onBotResponse);
+    this.host.off("audioPlaybackComplete", this.onAudioComplete);
+    this.host.off("interrupt", this.onInterrupt);
+    this.host.off("disconnected", this.onDisconnected);
+    this.host.emitScriptComplete({ reason });
+    this.resolveDone({ reason });
+  }
+};
+
 // 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.";
@@ -31480,6 +31705,7 @@ var EstuaryClient = class extends TypedEventEmitter {
   _hasAutoInterrupted = false;
   _autoInterruptGraceTimer = null;
   _isLiveKitSpeaking = false;
+  _activeScript = null;
   constructor(config) {
     super();
     if (!config.apiKey && !config.sessionToken) {
@@ -31554,6 +31780,10 @@ var EstuaryClient = class extends TypedEventEmitter {
   /** Disconnect from the server */
   async disconnect() {
     this.logger.info("Disconnecting...");
+    if (this._activeScript && this._activeScript.state !== "done") {
+      this._activeScript.stop();
+    }
+    this._activeScript = null;
     if (this._autoInterruptGraceTimer) {
       clearTimeout(this._autoInterruptGraceTimer);
       this._autoInterruptGraceTimer = null;
@@ -31575,6 +31805,59 @@ var EstuaryClient = class extends TypedEventEmitter {
     this.ensureConnected();
     this.socketManager.emitEvent("say_line", { text, text_only: textOnly });
   }
+  /**
+   * Script a sequence of prewritten lines. Lines are paced so each finishes before the next
+   * is sent — required because say_line interrupts any in-progress response server-side, so
+   * unpaced lines would stomp each other. Returns a controller (play/pause/resume/next/stop +
+   * an awaitable `done`). Starting a new script stops any currently-active one.
+   */
+  playScript(lines, opts) {
+    this.ensureConnected();
+    if (this._activeScript && this._activeScript.state !== "done") {
+      this._activeScript.stop();
+    }
+    const player = new ScriptPlayer(this.createScriptHost(), lines, opts);
+    this._activeScript = player;
+    return player;
+  }
+  /** Convenience alias of playScript() for fire-and-forget scripted sequences. */
+  sayLines(lines, opts) {
+    return this.playScript(lines, opts);
+  }
+  createScriptHost() {
+    const self2 = this;
+    return {
+      sayLine(text, textOnly) {
+        self2.sayLine(text, textOnly);
+      },
+      interrupt() {
+        self2.interrupt();
+      },
+      on(event, listener) {
+        self2.on(event, listener);
+        return self2;
+      },
+      off(event, listener) {
+        self2.off(event, listener);
+        return self2;
+      },
+      get isConnected() {
+        return self2.isConnected;
+      },
+      get willPlayScriptedAudio() {
+        return self2.audioPlayer != null;
+      },
+      emitScriptLineStarted(info) {
+        self2.emit("scriptLineStarted", info);
+      },
+      emitScriptComplete(info) {
+        self2.emit("scriptComplete", info);
+      },
+      log(msg) {
+        self2.logger.debug(msg);
+      }
+    };
+  }
   /** Interrupt the current bot response */
   interrupt(messageId) {
     this.ensureConnected();