@estuary-ai/sdk 0.4.1 → 0.6.0

package/LICENSE

@@ -1,21 +1,21 @@
-MIT License
-
-Copyright (c) 2026 estuary.ai
-
-Permission is hereby granted, free of charge, to any person obtaining a copy
-of this software and associated documentation files (the "Software"), to deal
-in the Software without restriction, including without limitation the rights
-to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
-copies of the Software, and to permit persons to whom the Software is
-furnished to do so, subject to the following conditions:
-
-The above copyright notice and this permission notice shall be included in all
-copies or substantial portions of the Software.
-
-THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
-IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
-FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
-AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
-LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
-OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
-SOFTWARE.
+MIT License
+
+Copyright (c) 2026 estuary.ai
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

package/README.md

@@ -46,6 +46,37 @@ client.sendText('What do you remember about me?');
 client.sendText('Just respond in text', true); // textOnly mode
 ```
 
+### Scripted Lines
+
+Make the character speak exact, prewritten lines (straight to TTS, skipping the LLM):
+
+```typescript
+client.sayLine('Welcome back, traveler.');          // TTS audio
+client.sayLine('System: connection restored.', true); // text only, no audio
+```
+
+For a sequence, use `playScript()` — it paces the lines so each finishes before the next is
+sent. (`say_line` interrupts any in-progress speech, so firing several at once would make each
+line cut off the previous one.)
+
+```typescript
+const script = client.playScript(
+  ['Welcome to my shop, traveler!', 'I have wares, if you have coin.', 'Come back anytime.'],
+  { textOnly: false, lineGapMs: 250 },
+);
+
+client.on('scriptLineStarted', ({ index, text }) => console.log(`line ${index}: ${text}`));
+await script.done; // resolves when all lines have been spoken
+
+script.pause();
+script.resume();
+script.next(); // skip ahead
+script.stop(); // halt + interrupt
+```
+
+`sayLines(lines, opts)` is a convenience alias of `playScript(lines, opts)`. Lines may be plain
+strings or per-line overrides: `{ text: '(a silent stage direction)', textOnly: true }`.
+
 ### Voice (WebSocket)
 
 ```typescript
@@ -182,6 +213,10 @@ client.on('interrupt', (data) => { /* response interrupted */ });
 client.on('characterAction', (action) => { /* parsed action from bot response */ });
 client.on('cameraCaptureRequest', (request) => { /* server requests a camera image */ });
 
+// Scripted lines (playScript / sayLines)
+client.on('scriptLineStarted', ({ index, text, messageId }) => { /* a scripted line began */ });
+client.on('scriptComplete', ({ reason }) => { /* 'finished' | 'stopped' | 'disconnected' | 'interrupted' */ });
+
 // Voice
 client.on('voiceStarted', () => { /* voice session began */ });
 client.on('voiceStopped', () => { /* voice session ended */ });

package/dist/index.d.mts

@@ -91,6 +91,17 @@ interface QuotaExceededData {
     remaining: number;
     tier: string;
 }
+/**
+ * Emitted when the server ends the session due to inactivity (no conversation
+ * activity for the server's idle timeout). The server disconnects the socket
+ * right after; the SDK does not auto-reconnect from this — call connect()
+ * again on explicit user intent to resume.
+ */
+interface SessionTimeoutData {
+    reason: string;
+    idleSeconds: number;
+    timeoutSeconds: number;
+}
 interface LiveKitTokenResponse {
     token: string;
     url: string;
@@ -156,6 +167,46 @@ interface CharacterAction {
     /** Message ID of the bot response that contained this action */
     messageId: string;
 }
+/** A scripted line: plain text (uses the script's default textOnly) or an explicit override. */
+type ScriptLine = string | {
+    text: string;
+    textOnly?: boolean;
+};
+interface ScriptOptions {
+    /** Default for plain-string lines: false = TTS audio (default), true = text-only. */
+    textOnly?: boolean;
+    /** Pause inserted after each line completes, in ms (default 0). */
+    lineGapMs?: number;
+    /** Begin speaking immediately on creation (default true). If false, call play(). */
+    autoStart?: boolean;
+    /** Repeat from the first line after the last (default false). */
+    loop?: boolean;
+    /** Force-advance a line if no completion signal arrives within this many ms (default 30000). */
+    lineTimeoutMs?: number;
+}
+type ScriptEndReason = 'finished' | 'stopped' | 'disconnected' | 'interrupted';
+type ScriptState = 'idle' | 'playing' | 'paused' | 'done';
+interface ScriptLineStartedInfo {
+    index: number;
+    text: string;
+    messageId: string;
+}
+/** Handle returned by EstuaryClient.playScript() / sayLines(). */
+interface ScriptController {
+    readonly length: number;
+    /** Index of the current / most-recently-started line (-1 before the first line starts). */
+    readonly index: number;
+    readonly state: ScriptState;
+    /** Resolves (never rejects) when the script ends, with the reason. Awaitable. */
+    readonly done: Promise<{
+        reason: ScriptEndReason;
+    }>;
+    play(): void;
+    pause(): void;
+    resume(): void;
+    next(): void;
+    stop(): void;
+}
 type EstuaryEventMap = {
     connected: (session: SessionInfo) => void;
     disconnected: (reason: string) => void;
@@ -168,6 +219,7 @@ type EstuaryEventMap = {
     error: (error: Error) => void;
     authError: (error: string) => void;
     quotaExceeded: (data: QuotaExceededData) => void;
+    sessionTimeout: (data: SessionTimeoutData) => void;
     cameraCaptureRequest: (request: CameraCaptureRequest) => void;
     characterAction: (action: CharacterAction) => void;
     voiceStarted: () => void;
@@ -179,6 +231,10 @@ type EstuaryEventMap = {
     /** Bot audio level 0.0–1.0, emitted during playback for both transports. */
     botAudioLevel: (level: number) => void;
     memoryUpdated: (event: MemoryUpdatedEvent) => void;
+    scriptLineStarted: (info: ScriptLineStartedInfo) => void;
+    scriptComplete: (info: {
+        reason: ScriptEndReason;
+    }) => void;
 };
 interface VoiceManager {
     start(): Promise<void>;
@@ -360,6 +416,7 @@ declare class EstuaryClient extends TypedEventEmitter<EstuaryEventMap> {
     private _hasAutoInterrupted;
     private _autoInterruptGraceTimer;
     private _isLiveKitSpeaking;
+    private _activeScript;
     constructor(config: EstuaryConfig);
     /** Memory API client for querying memories, graphs, and facts */
     get memory(): MemoryClient;
@@ -385,6 +442,16 @@ declare class EstuaryClient extends TypedEventEmitter<EstuaryEventMap> {
     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;
+    /**
+     * 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: ScriptLine[], opts?: ScriptOptions): ScriptController;
+    /** Convenience alias of playScript() for fire-and-forget scripted sequences. */
+    sayLines(lines: ScriptLine[], opts?: ScriptOptions): ScriptController;
+    private createScriptHost;
     /** Interrupt the current bot response */
     interrupt(messageId?: string): void;
     /** Send a camera image for vision processing */
@@ -399,6 +466,13 @@ declare class EstuaryClient extends TypedEventEmitter<EstuaryEventMap> {
     startVoice(): Promise<void>;
     /** Stop voice input */
     stopVoice(): Promise<void>;
+    /**
+     * Tear down voice state without requiring an active manager — used when the
+     * server ends the session out from under us. Unlike stopVoice(), this also
+     * disposes a manager whose transport already died (LiveKit room deleted →
+     * isActive is false but the local mic track was never released).
+     */
+    private releaseVoice;
     /** Toggle microphone mute */
     toggleMute(): void;
     /** Whether the microphone is muted */
@@ -470,4 +544,4 @@ declare class CharacterClient {
     dispose(): void;
 }
 
-export { type BotResponse, type BotVoice, type CameraCaptureRequest, type CharacterAction, CharacterClient, type CharacterInfo, ConnectionState, type CoreFact, type CoreFactsResponse, ErrorCode, EstuaryClient, type EstuaryConfig, EstuaryError, type EstuaryEventMap, type InterruptData, type LiveKitTokenResponse, MemoryClient, type MemoryData, type MemoryGraphEdge, type MemoryGraphNode, type MemoryGraphOptions, type MemoryGraphResponse, type MemoryListOptions, type MemoryListResponse, type MemorySearchOptions, type MemorySearchResponse, type MemoryStatsResponse, type MemoryTimelineOptions, type MemoryTimelineResponse, type MemoryUpdatedEvent, type ParsedAction, type QuotaExceededData, type SessionCapabilities, type SessionInfo, type ShareOpenResponse, type SttResponse, type VoiceManager, type VoiceTransport, parseActions };
+export { type BotResponse, type BotVoice, type CameraCaptureRequest, type CharacterAction, CharacterClient, type CharacterInfo, ConnectionState, type CoreFact, type CoreFactsResponse, ErrorCode, EstuaryClient, type EstuaryConfig, EstuaryError, type EstuaryEventMap, type InterruptData, type LiveKitTokenResponse, MemoryClient, type MemoryData, type MemoryGraphEdge, type MemoryGraphNode, type MemoryGraphOptions, type MemoryGraphResponse, type MemoryListOptions, type MemoryListResponse, type MemorySearchOptions, type MemorySearchResponse, type MemoryStatsResponse, type MemoryTimelineOptions, type MemoryTimelineResponse, type MemoryUpdatedEvent, type ParsedAction, type QuotaExceededData, type ScriptController, type ScriptEndReason, type ScriptLine, type ScriptLineStartedInfo, type ScriptOptions, type ScriptState, type SessionCapabilities, type SessionInfo, type ShareOpenResponse, type SttResponse, type VoiceManager, type VoiceTransport, parseActions };

package/dist/index.d.ts

@@ -91,6 +91,17 @@ interface QuotaExceededData {
     remaining: number;
     tier: string;
 }
+/**
+ * Emitted when the server ends the session due to inactivity (no conversation
+ * activity for the server's idle timeout). The server disconnects the socket
+ * right after; the SDK does not auto-reconnect from this — call connect()
+ * again on explicit user intent to resume.
+ */
+interface SessionTimeoutData {
+    reason: string;
+    idleSeconds: number;
+    timeoutSeconds: number;
+}
 interface LiveKitTokenResponse {
     token: string;
     url: string;
@@ -156,6 +167,46 @@ interface CharacterAction {
     /** Message ID of the bot response that contained this action */
     messageId: string;
 }
+/** A scripted line: plain text (uses the script's default textOnly) or an explicit override. */
+type ScriptLine = string | {
+    text: string;
+    textOnly?: boolean;
+};
+interface ScriptOptions {
+    /** Default for plain-string lines: false = TTS audio (default), true = text-only. */
+    textOnly?: boolean;
+    /** Pause inserted after each line completes, in ms (default 0). */
+    lineGapMs?: number;
+    /** Begin speaking immediately on creation (default true). If false, call play(). */
+    autoStart?: boolean;
+    /** Repeat from the first line after the last (default false). */
+    loop?: boolean;
+    /** Force-advance a line if no completion signal arrives within this many ms (default 30000). */
+    lineTimeoutMs?: number;
+}
+type ScriptEndReason = 'finished' | 'stopped' | 'disconnected' | 'interrupted';
+type ScriptState = 'idle' | 'playing' | 'paused' | 'done';
+interface ScriptLineStartedInfo {
+    index: number;
+    text: string;
+    messageId: string;
+}
+/** Handle returned by EstuaryClient.playScript() / sayLines(). */
+interface ScriptController {
+    readonly length: number;
+    /** Index of the current / most-recently-started line (-1 before the first line starts). */
+    readonly index: number;
+    readonly state: ScriptState;
+    /** Resolves (never rejects) when the script ends, with the reason. Awaitable. */
+    readonly done: Promise<{
+        reason: ScriptEndReason;
+    }>;
+    play(): void;
+    pause(): void;
+    resume(): void;
+    next(): void;
+    stop(): void;
+}
 type EstuaryEventMap = {
     connected: (session: SessionInfo) => void;
     disconnected: (reason: string) => void;
@@ -168,6 +219,7 @@ type EstuaryEventMap = {
     error: (error: Error) => void;
     authError: (error: string) => void;
     quotaExceeded: (data: QuotaExceededData) => void;
+    sessionTimeout: (data: SessionTimeoutData) => void;
     cameraCaptureRequest: (request: CameraCaptureRequest) => void;
     characterAction: (action: CharacterAction) => void;
     voiceStarted: () => void;
@@ -179,6 +231,10 @@ type EstuaryEventMap = {
     /** Bot audio level 0.0–1.0, emitted during playback for both transports. */
     botAudioLevel: (level: number) => void;
     memoryUpdated: (event: MemoryUpdatedEvent) => void;
+    scriptLineStarted: (info: ScriptLineStartedInfo) => void;
+    scriptComplete: (info: {
+        reason: ScriptEndReason;
+    }) => void;
 };
 interface VoiceManager {
     start(): Promise<void>;
@@ -360,6 +416,7 @@ declare class EstuaryClient extends TypedEventEmitter<EstuaryEventMap> {
     private _hasAutoInterrupted;
     private _autoInterruptGraceTimer;
     private _isLiveKitSpeaking;
+    private _activeScript;
     constructor(config: EstuaryConfig);
     /** Memory API client for querying memories, graphs, and facts */
     get memory(): MemoryClient;
@@ -385,6 +442,16 @@ declare class EstuaryClient extends TypedEventEmitter<EstuaryEventMap> {
     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;
+    /**
+     * 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: ScriptLine[], opts?: ScriptOptions): ScriptController;
+    /** Convenience alias of playScript() for fire-and-forget scripted sequences. */
+    sayLines(lines: ScriptLine[], opts?: ScriptOptions): ScriptController;
+    private createScriptHost;
     /** Interrupt the current bot response */
     interrupt(messageId?: string): void;
     /** Send a camera image for vision processing */
@@ -399,6 +466,13 @@ declare class EstuaryClient extends TypedEventEmitter<EstuaryEventMap> {
     startVoice(): Promise<void>;
     /** Stop voice input */
     stopVoice(): Promise<void>;
+    /**
+     * Tear down voice state without requiring an active manager — used when the
+     * server ends the session out from under us. Unlike stopVoice(), this also
+     * disposes a manager whose transport already died (LiveKit room deleted →
+     * isActive is false but the local mic track was never released).
+     */
+    private releaseVoice;
     /** Toggle microphone mute */
     toggleMute(): void;
     /** Whether the microphone is muted */
@@ -470,4 +544,4 @@ declare class CharacterClient {
     dispose(): void;
 }
 
-export { type BotResponse, type BotVoice, type CameraCaptureRequest, type CharacterAction, CharacterClient, type CharacterInfo, ConnectionState, type CoreFact, type CoreFactsResponse, ErrorCode, EstuaryClient, type EstuaryConfig, EstuaryError, type EstuaryEventMap, type InterruptData, type LiveKitTokenResponse, MemoryClient, type MemoryData, type MemoryGraphEdge, type MemoryGraphNode, type MemoryGraphOptions, type MemoryGraphResponse, type MemoryListOptions, type MemoryListResponse, type MemorySearchOptions, type MemorySearchResponse, type MemoryStatsResponse, type MemoryTimelineOptions, type MemoryTimelineResponse, type MemoryUpdatedEvent, type ParsedAction, type QuotaExceededData, type SessionCapabilities, type SessionInfo, type ShareOpenResponse, type SttResponse, type VoiceManager, type VoiceTransport, parseActions };
+export { type BotResponse, type BotVoice, type CameraCaptureRequest, type CharacterAction, CharacterClient, type CharacterInfo, ConnectionState, type CoreFact, type CoreFactsResponse, ErrorCode, EstuaryClient, type EstuaryConfig, EstuaryError, type EstuaryEventMap, type InterruptData, type LiveKitTokenResponse, MemoryClient, type MemoryData, type MemoryGraphEdge, type MemoryGraphNode, type MemoryGraphOptions, type MemoryGraphResponse, type MemoryListOptions, type MemoryListResponse, type MemorySearchOptions, type MemorySearchResponse, type MemoryStatsResponse, type MemoryTimelineOptions, type MemoryTimelineResponse, type MemoryUpdatedEvent, type ParsedAction, type QuotaExceededData, type ScriptController, type ScriptEndReason, type ScriptLine, type ScriptLineStartedInfo, type ScriptOptions, type ScriptState, type SessionCapabilities, type SessionInfo, type ShareOpenResponse, type SttResponse, type VoiceManager, type VoiceTransport, parseActions };