@breeze.blue/sdk 0.5.1 → 0.6.1

package/dist/client.js

@@ -1,11 +1,19 @@
 import { AudioResponse } from "./audio.js";
-import { BreezeBlueConfigurationError, BreezeBlueRealtimeError, errorFromResponse } from "./errors.js";
+import { BreezeBlueAPIError, BreezeBlueConfigurationError, BreezeBlueRealtimeError, errorFromResponse, } from "./errors.js";
 import { camelizeKeys, snakeizeKeys } from "./_transform.js";
 import { SDK_NAME, SDK_VERSION } from "./version.js";
 const DEFAULT_BASE_URL = "https://api.breeze.blue";
 const DEFAULT_TIMEOUT_MS = 60_000;
 const DEFAULT_REALTIME_HANDSHAKE_TIMEOUT_MS = 30_000;
 const REALTIME_MAX_BUFFERED_BYTES = 16 * 1024 * 1024;
+const DEFAULT_REALTIME_ROTATION_MARGIN_MS = 120_000;
+const DEFAULT_REALTIME_HEARTBEAT_TIMEOUT_MS = 5_000;
+const DEFAULT_REALTIME_MAX_PHYSICAL_SESSION_MS = 10 * 60_000;
+const DEFAULT_REALTIME_MAX_RECONNECT_ATTEMPTS = 3;
+const DEFAULT_REALTIME_RECONNECT_BASE_DELAY_MS = 250;
+const MAX_REALTIME_RECONNECT_DELAY_MS = 4_000;
+const REALTIME_SETTLEMENT_DRAIN_TIMEOUT_MS = 5_000;
+const REALTIME_CLOSE_EVENT_GRACE_MS = 50;
 const WEBSOCKET_OPEN = 1;
 export class BreezeBlueClient {
     apiKey;
@@ -135,11 +143,59 @@ class RealtimeTextToSpeechResource {
                     voiceSettings: options.voiceSettings,
                     inactivityTimeoutSeconds: options.inactivityTimeoutSeconds,
                     enableLogging: options.enableLogging,
+                }, {
+                    signal: options.signal,
+                    timeout: options.timeout,
                 })).websocketUrl);
         const WebSocketImpl = requireWebSocket(options.webSocket ?? this.client.webSocket);
         const socket = new WebSocketImpl(websocketUrl);
         return RealtimeTextToSpeechConnection.open(socket, {
             timeout: options.timeout ?? this.client.timeout ?? DEFAULT_REALTIME_HANDSHAKE_TIMEOUT_MS,
+            signal: options.signal,
+        });
+    }
+    /**
+     * Open an SDK-managed logical connection backed by bounded physical
+     * WebSocket sessions. The manager keeps idle sessions alive, rotates at
+     * turn boundaries, and performs bounded idle reconnects with fresh
+     * credentials. It never replays an interrupted active turn.
+     */
+    async connectManaged(voiceId, options = {}) {
+        if (options.sessionFactory !== undefined && hasRealtimeSessionParams(options)) {
+            console.warn("@breeze.blue/sdk: realtime.connectManaged cannot apply modelId, languageCode, instructions, " +
+                "voiceSettings, inactivityTimeoutSeconds, or enableLogging when sessionFactory is provided. " +
+                "Configure these when the factory creates each realtime session.");
+        }
+        const sessionRequest = {
+            modelId: options.modelId,
+            languageCode: options.languageCode,
+            instructions: options.instructions,
+            voiceSettings: options.voiceSettings,
+            inactivityTimeoutSeconds: options.inactivityTimeoutSeconds,
+            enableLogging: options.enableLogging,
+        };
+        const connectionTimeout = options.timeout ?? this.client.timeout ?? DEFAULT_REALTIME_HANDSHAKE_TIMEOUT_MS;
+        const createConnection = async (signal) => {
+            const credentials = options.sessionFactory
+                ? await options.sessionFactory({ signal })
+                : await this.createSession(voiceId, sessionRequest, {
+                    signal,
+                    timeout: connectionTimeout,
+                });
+            if (!credentials.clientSecret && !credentials.websocketUrl) {
+                throw new BreezeBlueConfigurationError("realtime.connectManaged sessionFactory must return a clientSecret or websocketUrl.");
+            }
+            return this.connect(voiceId, {
+                clientSecret: credentials.clientSecret,
+                websocketUrl: credentials.websocketUrl,
+                webSocket: options.webSocket,
+                signal,
+                timeout: connectionTimeout,
+            });
+        };
+        return ManagedRealtimeTextToSpeechConnection.open(createConnection, {
+            ...options,
+            timeout: connectionTimeout,
         });
     }
 }
@@ -158,6 +214,7 @@ export class RealtimeTextToSpeechConnection {
     closed = false;
     queuedBytes = 0;
     failure;
+    closeEventGraceTimer;
     constructor(socket) {
         this.socket = socket;
     }
@@ -167,20 +224,25 @@ export class RealtimeTextToSpeechConnection {
         await new Promise((resolve, reject) => {
             let settled = false;
             let timer;
+            const cleanup = () => {
+                if (timer !== undefined) {
+                    clearTimeout(timer);
+                    timer = undefined;
+                }
+                options.signal?.removeEventListener("abort", abort);
+            };
             const succeed = () => {
                 if (settled)
                     return;
                 settled = true;
-                if (timer !== undefined)
-                    clearTimeout(timer);
+                cleanup();
                 resolve();
             };
             const fail = (error) => {
                 if (settled)
                     return;
                 settled = true;
-                if (timer !== undefined)
-                    clearTimeout(timer);
+                cleanup();
                 try {
                     socket.close(1000);
                 }
@@ -189,9 +251,15 @@ export class RealtimeTextToSpeechConnection {
                 }
                 reject(error);
             };
+            const abort = () => fail(new BreezeBlueRealtimeError("Realtime TTS WebSocket opening was aborted."));
             if (timeoutMs > 0) {
                 timer = setTimeout(() => fail(new Error(`Realtime TTS WebSocket did not open within ${timeoutMs}ms.`)), timeoutMs);
             }
+            if (options.signal?.aborted) {
+                abort();
+                return;
+            }
+            options.signal?.addEventListener("abort", abort, { once: true });
             socket.binaryType = "arraybuffer";
             socket.onopen = () => succeed();
             socket.onerror = (event) => fail(new Error(`Realtime TTS WebSocket failed to open: ${String(event.type)}`));
@@ -199,7 +267,7 @@ export class RealtimeTextToSpeechConnection {
         });
         socket.onmessage = (event) => connection.handleMessage(event.data);
         socket.onclose = (event) => connection.handleClose(event);
-        socket.onerror = () => connection.finish();
+        socket.onerror = () => connection.handleSocketError();
         return connection;
     }
     startTurn(turnId) {
@@ -243,6 +311,13 @@ export class RealtimeTextToSpeechConnection {
             if (message.type === "audio") {
                 yield message.audio;
             }
+            else if (message.type === "error") {
+                throw realtimeErrorFromEvent(message);
+            }
+            else if (message.type === "session.closed" &&
+                (message.reconnect === true || (message.code !== undefined && message.code !== 1000))) {
+                throw realtimeErrorFromClose(message);
+            }
         }
     }
     [Symbol.asyncIterator]() {
@@ -288,6 +363,7 @@ export class RealtimeTextToSpeechConnection {
         }
     }
     handleClose(event) {
+        this.clearCloseEventGraceTimer();
         if (!this.closed && event.code !== 1000) {
             this.push({
                 type: "session.closed",
@@ -298,6 +374,17 @@ export class RealtimeTextToSpeechConnection {
         }
         this.finish();
     }
+    handleSocketError() {
+        if (this.closed || this.closeEventGraceTimer !== undefined) {
+            return;
+        }
+        // Browsers normally dispatch `close` immediately after `error`. Give that
+        // event a short window so its code/reason/reconnect semantics are not lost.
+        this.closeEventGraceTimer = setTimeout(() => {
+            this.closeEventGraceTimer = undefined;
+            this.fail(new BreezeBlueRealtimeError("Realtime TTS WebSocket failed without a close event.", { reconnect: true }));
+        }, REALTIME_CLOSE_EVENT_GRACE_MS);
+    }
     push(message, size) {
         if (this.closed) {
             return;
@@ -319,6 +406,7 @@ export class RealtimeTextToSpeechConnection {
         if (this.closed) {
             return;
         }
+        this.clearCloseEventGraceTimer();
         this.closed = true;
         this.failure = error;
         this.queue.length = 0;
@@ -332,11 +420,859 @@ export class RealtimeTextToSpeechConnection {
         if (this.closed) {
             return;
         }
+        this.clearCloseEventGraceTimer();
         this.closed = true;
         for (const waiter of this.waiters.splice(0)) {
             waiter.resolve({ value: undefined, done: true });
         }
     }
+    clearCloseEventGraceTimer() {
+        if (this.closeEventGraceTimer !== undefined) {
+            clearTimeout(this.closeEventGraceTimer);
+            this.closeEventGraceTimer = undefined;
+        }
+    }
+}
+/**
+ * A logical realtime TTS connection backed by bounded physical WebSocket
+ * epochs. Use `textToSpeech.realtime.connectManaged(...)` to create one.
+ *
+ * The manager automatically keeps an idle session alive, rotates before the
+ * server session limit at turn boundaries, and makes bounded reconnect
+ * attempts while idle. It does not buffer turn content or replay commands;
+ * startTurnWhenReady() may wait before its first turn.start write. If the
+ * transport is interrupted during a turn, iteration rejects with
+ * `BreezeBlueRealtimeError`.
+ */
+export class ManagedRealtimeTextToSpeechConnection {
+    createConnection;
+    queue = [];
+    drainingEpochs = new Set();
+    openAttempts = new Set();
+    waiters = [];
+    heartbeatIntervalMs;
+    heartbeatTimeoutMs;
+    readyTimeoutMs;
+    rotationMarginMs;
+    maxPhysicalSessionMs;
+    maxReconnectAttempts;
+    reconnectBaseDelayMs;
+    current;
+    heartbeatTimer;
+    heartbeatAckTimer;
+    rotationTimer;
+    retryDelay;
+    transitionPromise;
+    transitionKind;
+    epochSequence = 0;
+    queuedBytes = 0;
+    activeTurn = false;
+    rotationPending = false;
+    closed = false;
+    failure;
+    constructor(createConnection, options) {
+        this.createConnection = createConnection;
+        this.readyTimeoutMs = positiveNumber(options.timeout ?? DEFAULT_REALTIME_HANDSHAKE_TIMEOUT_MS, "timeout");
+        this.heartbeatIntervalMs = optionalNonNegativeNumber(options.heartbeatIntervalMs, "heartbeatIntervalMs");
+        this.heartbeatTimeoutMs = positiveNumber(options.heartbeatTimeoutMs ?? DEFAULT_REALTIME_HEARTBEAT_TIMEOUT_MS, "heartbeatTimeoutMs");
+        this.rotationMarginMs = nonNegativeNumber(options.rotationMarginMs ?? DEFAULT_REALTIME_ROTATION_MARGIN_MS, "rotationMarginMs");
+        this.maxPhysicalSessionMs = nonNegativeNumber(options.maxPhysicalSessionMs ?? DEFAULT_REALTIME_MAX_PHYSICAL_SESSION_MS, "maxPhysicalSessionMs");
+        this.maxReconnectAttempts = nonNegativeInteger(options.maxReconnectAttempts ?? DEFAULT_REALTIME_MAX_RECONNECT_ATTEMPTS, "maxReconnectAttempts");
+        this.reconnectBaseDelayMs = nonNegativeNumber(options.reconnectBaseDelayMs ?? DEFAULT_REALTIME_RECONNECT_BASE_DELAY_MS, "reconnectBaseDelayMs");
+    }
+    static async open(createConnection, options = {}) {
+        const managed = new ManagedRealtimeTextToSpeechConnection(createConnection, options);
+        const epoch = await managed.openEpoch();
+        managed.installEpoch(epoch);
+        return managed;
+    }
+    startTurn(turnId) {
+        const connection = this.requireCurrentConnection();
+        try {
+            connection.startTurn(turnId);
+            this.activeTurn = true;
+        }
+        catch (error) {
+            this.activeTurn = false;
+            throw error;
+        }
+    }
+    /**
+     * Start a turn on the current physical epoch, waiting only when an idle
+     * unexpected reconnect is already replacing a missing epoch.
+     *
+     * No other turn command is buffered. Await this method before calling
+     * appendText(), flush(), endTurn(), or cancelTurn().
+     */
+    async startTurnWhenReady(turnId, options = {}) {
+        let waitedForUnexpectedTransition = false;
+        while (true) {
+            this.throwIfStartTurnAborted(options.signal);
+            if (this.current) {
+                if (waitedForUnexpectedTransition && this.activeTurn) {
+                    throw new BreezeBlueRealtimeError("Realtime TTS managed connection started another turn while waiting for its replacement epoch.");
+                }
+                this.startTurn(turnId);
+                return;
+            }
+            const transition = this.transitionPromise;
+            if (this.transitionKind !== "unexpected" || transition === undefined) {
+                this.requireCurrentConnection();
+                return;
+            }
+            waitedForUnexpectedTransition = true;
+            await this.waitForStartTurnTransition(transition, options.signal);
+        }
+    }
+    appendText(text) {
+        this.requireCurrentConnection().appendText(text);
+    }
+    flush() {
+        this.requireCurrentConnection().flush();
+    }
+    endTurn() {
+        this.requireCurrentConnection().endTurn();
+    }
+    cancelTurn() {
+        this.requireCurrentConnection().cancelTurn();
+    }
+    /** Send an immediate ping in addition to the managed keepalive schedule. */
+    ping() {
+        this.requireCurrentConnection().ping();
+    }
+    close() {
+        if (this.closed) {
+            return;
+        }
+        this.closed = true;
+        this.clearTimers();
+        this.cancelRetryDelay();
+        this.cancelOpenAttempts();
+        const current = this.current;
+        this.current = undefined;
+        current?.connection.close();
+        this.closeSettlementDrains();
+        this.queue.length = 0;
+        this.queuedBytes = 0;
+        for (const waiter of this.waiters.splice(0)) {
+            waiter.resolve({ value: undefined, done: true });
+        }
+    }
+    async *events() {
+        for await (const message of this) {
+            if (message.type !== "audio") {
+                yield message;
+            }
+        }
+    }
+    async *audio() {
+        for await (const message of this) {
+            if (message.type === "audio") {
+                yield message.audio;
+            }
+            else if (message.type === "error") {
+                throw realtimeErrorFromEvent(message);
+            }
+            else if (message.type === "session.closed" &&
+                (message.reconnect === true || (message.code !== undefined && message.code !== 1000))) {
+                throw realtimeErrorFromClose(message);
+            }
+        }
+    }
+    [Symbol.asyncIterator]() {
+        return {
+            next: () => {
+                const entry = this.queue.shift();
+                if (entry) {
+                    this.queuedBytes -= entry.size;
+                    return Promise.resolve({ value: entry.message, done: false });
+                }
+                if (this.failure) {
+                    return Promise.reject(this.failure);
+                }
+                if (this.closed) {
+                    return Promise.resolve({ value: undefined, done: true });
+                }
+                return new Promise((resolve, reject) => this.waiters.push({ resolve, reject }));
+            },
+        };
+    }
+    async openEpoch() {
+        const attempt = {
+            controller: new AbortController(),
+            abortListener: () => { },
+            connection: undefined,
+            timer: undefined,
+            active: true,
+        };
+        this.openAttempts.add(attempt);
+        const boundary = new Promise((_resolve, reject) => {
+            attempt.abortListener = () => reject(new BreezeBlueRealtimeError("Realtime TTS managed epoch opening was aborted."));
+            attempt.controller.signal.addEventListener("abort", attempt.abortListener, {
+                once: true,
+            });
+            attempt.timer = setTimeout(() => {
+                attempt.active = false;
+                reject(new BreezeBlueRealtimeError(`Realtime TTS managed epoch did not reach session.ready within ${this.readyTimeoutMs}ms.`, { reconnect: true }));
+                attempt.controller.abort();
+            }, this.readyTimeoutMs);
+        });
+        const connectionPromise = this.createConnection(attempt.controller.signal).then((connection) => {
+            attempt.connection = connection;
+            if (!attempt.active) {
+                connection.close();
+                throw new BreezeBlueRealtimeError("Realtime TTS managed epoch opening was aborted.");
+            }
+            return connection;
+        });
+        try {
+            const connection = await Promise.race([connectionPromise, boundary]);
+            const iterator = connection[Symbol.asyncIterator]();
+            const pending = [];
+            while (true) {
+                const result = await Promise.race([iterator.next(), boundary]);
+                if (result.done) {
+                    throw new BreezeBlueRealtimeError("Realtime TTS connection closed before session.ready.", { reconnect: true });
+                }
+                const message = result.value;
+                if (message.type === "session.ready") {
+                    this.completeOpenAttempt(attempt);
+                    return {
+                        id: ++this.epochSequence,
+                        connection,
+                        iterator,
+                        ready: message,
+                        pending,
+                        pendingUsageHistoryIds: new Set(),
+                        reconnectRequested: false,
+                        retryAfterMs: 0,
+                        heartbeatIntervalMs: 0,
+                        heartbeatTimeoutMs: this.heartbeatTimeoutMs,
+                        draining: false,
+                        drainTimer: undefined,
+                    };
+                }
+                if (message.type === "error") {
+                    throw realtimeErrorFromEvent(message);
+                }
+                if (message.type === "session.closed") {
+                    throw realtimeErrorFromClose(message);
+                }
+                pending.push(message);
+            }
+        }
+        catch (error) {
+            this.cancelOpenAttempt(attempt);
+            throw error;
+        }
+        finally {
+            this.openAttempts.delete(attempt);
+        }
+    }
+    installEpoch(epoch, transitionKind) {
+        if (this.closed) {
+            epoch.connection.close();
+            return;
+        }
+        const previous = this.current;
+        this.clearTimers();
+        this.current = epoch;
+        this.rotationPending = false;
+        this.push(epoch.ready);
+        for (const message of epoch.pending) {
+            this.handleEpochMessage(epoch, message);
+        }
+        this.scheduleTimers(epoch, transitionKind !== undefined);
+        void this.pumpEpoch(epoch);
+        if (previous && previous !== epoch) {
+            if (transitionKind === "planned" && previous.pendingUsageHistoryIds.size > 0) {
+                this.beginSettlementDrain(previous);
+            }
+            else {
+                previous.connection.close();
+            }
+        }
+    }
+    async pumpEpoch(epoch) {
+        try {
+            while (!this.closed && (this.current === epoch || epoch.draining)) {
+                const result = await epoch.iterator.next();
+                const isCurrent = this.current === epoch;
+                if ((!isCurrent && !epoch.draining) || this.closed) {
+                    return;
+                }
+                if (result.done) {
+                    if (epoch.draining && !isCurrent) {
+                        this.finishSettlementDrain(epoch, false);
+                    }
+                    else {
+                        this.handleEpochEnd(epoch);
+                    }
+                    return;
+                }
+                if (epoch.draining && !isCurrent) {
+                    if (!this.handleSettlementDrainMessage(epoch, result.value)) {
+                        return;
+                    }
+                    continue;
+                }
+                if (!this.handleEpochMessage(epoch, result.value)) {
+                    return;
+                }
+            }
+        }
+        catch (error) {
+            if (epoch.draining && this.current !== epoch) {
+                this.finishSettlementDrain(epoch, false);
+                return;
+            }
+            if (this.current !== epoch || this.closed) {
+                return;
+            }
+            if (this.activeTurn) {
+                this.fail(activeTurnInterruptedError(error));
+            }
+            else if (error instanceof BreezeBlueRealtimeError && error.reconnect) {
+                this.requestUnexpectedReconnect(epoch, error);
+            }
+            else {
+                this.fail(asError(error));
+            }
+        }
+    }
+    handleEpochMessage(epoch, message) {
+        // Any inbound frame proves the full server-to-client path is alive. Pong
+        // is the expected idle acknowledgement; audio and events also prevent a
+        // false timeout while a turn is producing data.
+        this.acknowledgeHeartbeat(epoch);
+        if (message.type === "turn.started") {
+            this.activeTurn = true;
+        }
+        else if (message.type === "turn.done") {
+            this.activeTurn = false;
+            epoch.pendingUsageHistoryIds.add(message.historyItemId);
+        }
+        else if (message.type === "turn.cancelled") {
+            this.activeTurn = false;
+        }
+        else if (message.type === "usage.committed") {
+            epoch.pendingUsageHistoryIds.delete(message.historyItemId);
+        }
+        else if (message.type === "session.expiring") {
+            this.rotationPending = true;
+        }
+        else if (message.type === "error") {
+            const error = realtimeErrorFromEvent(message);
+            if (typeof message.meta?.retryAfterMs === "number") {
+                epoch.retryAfterMs = Math.max(epoch.retryAfterMs, message.meta.retryAfterMs);
+            }
+            if (error.recoverable) {
+                if (message.code === "GENERATION_CONCURRENCY_EXCEEDED") {
+                    // The server rejected turn.start before establishing an active turn,
+                    // so no turn.cancelled event will follow to clear local state.
+                    this.activeTurn = false;
+                }
+                this.push(message);
+                if (!this.activeTurn && this.rotationPending) {
+                    this.beginTransition("planned", epoch);
+                }
+                return true;
+            }
+            if (error.reconnect && this.activeTurn) {
+                this.fail(activeTurnInterruptedError(error));
+                return false;
+            }
+            if (error.reconnect) {
+                epoch.reconnectRequested = true;
+                this.requestUnexpectedReconnect(epoch, error);
+                return false;
+            }
+            this.fail(this.activeTurn ? activeTurnInterruptedError(error) : error);
+            return false;
+        }
+        else if (message.type === "session.closed") {
+            const reconnect = isReconnectableClose(message);
+            if (reconnect && this.activeTurn) {
+                this.fail(activeTurnInterruptedError(realtimeErrorFromClose(message)));
+                return false;
+            }
+            if (reconnect) {
+                epoch.reconnectRequested = true;
+                this.requestUnexpectedReconnect(epoch, realtimeErrorFromClose(message));
+                return false;
+            }
+            this.push(message);
+            return true;
+        }
+        this.push(message);
+        if (!this.activeTurn && this.rotationPending) {
+            this.beginTransition("planned", epoch);
+        }
+        return true;
+    }
+    handleEpochEnd(epoch) {
+        if (this.current !== epoch || this.closed) {
+            return;
+        }
+        if (this.activeTurn) {
+            this.fail(activeTurnInterruptedError());
+            return;
+        }
+        if (epoch.reconnectRequested) {
+            this.requestUnexpectedReconnect(epoch);
+            return;
+        }
+        this.clearTimers();
+        this.current = undefined;
+        this.finish();
+    }
+    requestUnexpectedReconnect(epoch, cause) {
+        if (this.current !== epoch || this.closed) {
+            return;
+        }
+        if (this.activeTurn) {
+            this.fail(activeTurnInterruptedError(cause));
+            return;
+        }
+        this.clearTimers();
+        this.current = undefined;
+        epoch.connection.close();
+        this.beginTransition("unexpected", epoch, cause);
+    }
+    beginTransition(kind, source, cause) {
+        if (this.closed || this.transitionPromise !== undefined) {
+            return;
+        }
+        this.transitionKind = kind;
+        this.transitionPromise = (async () => {
+            try {
+                await this.replaceEpoch(kind, source, cause);
+            }
+            catch (error) {
+                this.fail(asError(error));
+            }
+            finally {
+                this.transitionPromise = undefined;
+                this.transitionKind = undefined;
+                const current = this.current;
+                if (!this.closed && this.rotationPending && !this.activeTurn && current) {
+                    this.beginTransition("planned", current);
+                }
+            }
+        })();
+    }
+    async replaceEpoch(kind, source, initialCause) {
+        let needsReconnectBudget = kind === "unexpected";
+        let lastError = initialCause;
+        let reconnectAttempts = 0;
+        while (!this.closed) {
+            if (this.deferPlannedTransitionForActiveTurn(kind, source)) {
+                return;
+            }
+            if (needsReconnectBudget) {
+                if (reconnectAttempts >= this.maxReconnectAttempts) {
+                    if (this.deferPlannedTransitionForActiveTurn(kind, source)) {
+                        return;
+                    }
+                    throw reconnectExhaustedError(lastError, this.maxReconnectAttempts);
+                }
+                reconnectAttempts += 1;
+                const backoffCeilingMs = Math.min(this.reconnectBaseDelayMs * 2 ** (reconnectAttempts - 1), MAX_REALTIME_RECONNECT_DELAY_MS);
+                const jitteredBackoffMs = Math.floor(backoffCeilingMs * (0.5 + Math.random() * 0.5));
+                const retryAfterMs = reconnectAttempts === 1 ? source.retryAfterMs : 0;
+                await this.waitForRetryDelay(Math.max(jitteredBackoffMs, retryAfterMs));
+                if (this.closed) {
+                    return;
+                }
+                if (this.deferPlannedTransitionForActiveTurn(kind, source)) {
+                    return;
+                }
+            }
+            let candidate;
+            try {
+                candidate = await this.openEpoch();
+            }
+            catch (error) {
+                if (this.deferPlannedTransitionForActiveTurn(kind, source)) {
+                    return;
+                }
+                if ((error instanceof BreezeBlueAPIError && !isRetryableRealtimeSetupError(error)) ||
+                    error instanceof BreezeBlueConfigurationError ||
+                    (error instanceof BreezeBlueRealtimeError && !error.reconnect)) {
+                    throw error;
+                }
+                lastError = error;
+                needsReconnectBudget = true;
+                continue;
+            }
+            if (this.closed) {
+                candidate.connection.close();
+                return;
+            }
+            if (this.deferPlannedTransitionForActiveTurn(kind, source)) {
+                // A new turn won the boundary race while the replacement socket was
+                // opening. Keep that turn on the old epoch and try again after it
+                // reaches a terminal event.
+                candidate.connection.close();
+                return;
+            }
+            this.installEpoch(candidate, kind);
+            return;
+        }
+    }
+    deferPlannedTransitionForActiveTurn(kind, source) {
+        if (kind !== "planned" ||
+            !this.activeTurn ||
+            this.current !== source ||
+            this.closed) {
+            return false;
+        }
+        this.rotationPending = true;
+        return true;
+    }
+    scheduleTimers(epoch, probeImmediately = false) {
+        const heartbeatInterval = this.heartbeatIntervalMs ??
+            Math.max(100, Math.min(15_000, Math.floor(epoch.ready.inactivityTimeoutSeconds * 400)));
+        epoch.heartbeatIntervalMs = heartbeatInterval;
+        epoch.heartbeatTimeoutMs = this.heartbeatTimeoutMs;
+        if (heartbeatInterval > 0) {
+            this.scheduleNextHeartbeat(epoch, probeImmediately ? 0 : heartbeatInterval);
+        }
+        const maxSessionMs = epoch.ready.maxSessionSeconds * 1_000;
+        const safeRotationMargin = Math.min(this.rotationMarginMs, maxSessionMs / 2);
+        const serverRotationDelay = Math.max(0, maxSessionMs - safeRotationMargin);
+        const rotationDelay = this.maxPhysicalSessionMs > 0
+            ? Math.min(serverRotationDelay, this.maxPhysicalSessionMs)
+            : serverRotationDelay;
+        this.rotationTimer = setTimeout(() => {
+            if (this.closed || this.current !== epoch) {
+                return;
+            }
+            this.rotationPending = true;
+            if (!this.activeTurn) {
+                this.beginTransition("planned", epoch);
+            }
+        }, rotationDelay);
+    }
+    scheduleNextHeartbeat(epoch, delayMs = epoch.heartbeatIntervalMs) {
+        if (epoch.heartbeatIntervalMs <= 0 ||
+            this.closed ||
+            this.current !== epoch) {
+            return;
+        }
+        this.heartbeatTimer = setTimeout(() => {
+            this.heartbeatTimer = undefined;
+            if (this.closed || this.current !== epoch) {
+                return;
+            }
+            try {
+                epoch.connection.ping();
+            }
+            catch (error) {
+                this.requestUnexpectedReconnect(epoch, error);
+                return;
+            }
+            this.heartbeatAckTimer = setTimeout(() => {
+                this.heartbeatAckTimer = undefined;
+                if (this.closed || this.current !== epoch) {
+                    return;
+                }
+                this.requestUnexpectedReconnect(epoch, new BreezeBlueRealtimeError(`Realtime TTS managed heartbeat received no server response within ${epoch.heartbeatTimeoutMs}ms.`, { code: "HEARTBEAT_TIMEOUT", reconnect: true }));
+            }, epoch.heartbeatTimeoutMs);
+        }, delayMs);
+    }
+    acknowledgeHeartbeat(epoch) {
+        if (this.current !== epoch || this.heartbeatAckTimer === undefined) {
+            return;
+        }
+        clearTimeout(this.heartbeatAckTimer);
+        this.heartbeatAckTimer = undefined;
+        this.scheduleNextHeartbeat(epoch);
+    }
+    requireCurrentConnection() {
+        if (this.failure) {
+            throw this.failure;
+        }
+        if (this.closed) {
+            throw new BreezeBlueRealtimeError("Realtime TTS managed connection is closed.");
+        }
+        if (!this.current) {
+            throw new BreezeBlueRealtimeError("Realtime TTS managed connection is reconnecting; wait for the next session.ready event.", { reconnect: true });
+        }
+        return this.current.connection;
+    }
+    async waitForStartTurnTransition(transition, signal) {
+        if (!signal) {
+            await transition;
+            return;
+        }
+        this.throwIfStartTurnAborted(signal);
+        let abortListener;
+        try {
+            await Promise.race([
+                transition,
+                new Promise((_resolve, reject) => {
+                    abortListener = () => reject(startTurnAbortReason(signal));
+                    signal.addEventListener("abort", abortListener, { once: true });
+                }),
+            ]);
+        }
+        finally {
+            if (abortListener) {
+                signal.removeEventListener("abort", abortListener);
+            }
+        }
+    }
+    throwIfStartTurnAborted(signal) {
+        if (signal?.aborted) {
+            throw startTurnAbortReason(signal);
+        }
+    }
+    push(message) {
+        if (this.closed) {
+            return;
+        }
+        const waiter = this.waiters.shift();
+        if (waiter) {
+            waiter.resolve({ value: message, done: false });
+            return;
+        }
+        const size = realtimeMessageSize(message);
+        this.queue.push({ message, size });
+        this.queuedBytes += size;
+        if (this.queuedBytes > REALTIME_MAX_BUFFERED_BYTES) {
+            this.fail(new BreezeBlueRealtimeError(`Realtime TTS managed connection buffered more than ${REALTIME_MAX_BUFFERED_BYTES} bytes without ` +
+                "being consumed, so the logical connection was closed."));
+        }
+    }
+    fail(error) {
+        if (this.closed) {
+            return;
+        }
+        this.failure = error;
+        this.closed = true;
+        this.clearTimers();
+        this.cancelRetryDelay();
+        this.cancelOpenAttempts();
+        const current = this.current;
+        this.current = undefined;
+        current?.connection.close();
+        this.closeSettlementDrains();
+        this.queue.length = 0;
+        this.queuedBytes = 0;
+        for (const waiter of this.waiters.splice(0)) {
+            waiter.reject(error);
+        }
+    }
+    finish() {
+        if (this.closed) {
+            return;
+        }
+        this.closed = true;
+        this.clearTimers();
+        this.cancelRetryDelay();
+        this.cancelOpenAttempts();
+        this.closeSettlementDrains();
+        for (const waiter of this.waiters.splice(0)) {
+            waiter.resolve({ value: undefined, done: true });
+        }
+    }
+    clearTimers() {
+        if (this.heartbeatTimer !== undefined) {
+            clearTimeout(this.heartbeatTimer);
+            this.heartbeatTimer = undefined;
+        }
+        if (this.heartbeatAckTimer !== undefined) {
+            clearTimeout(this.heartbeatAckTimer);
+            this.heartbeatAckTimer = undefined;
+        }
+        if (this.rotationTimer !== undefined) {
+            clearTimeout(this.rotationTimer);
+            this.rotationTimer = undefined;
+        }
+    }
+    waitForRetryDelay(milliseconds) {
+        if (this.closed) {
+            return Promise.reject(new BreezeBlueRealtimeError("Realtime TTS managed reconnect delay was cancelled."));
+        }
+        if (milliseconds <= 0) {
+            return Promise.resolve();
+        }
+        return new Promise((resolve, reject) => {
+            const timer = setTimeout(() => {
+                if (this.retryDelay?.timer === timer) {
+                    this.retryDelay = undefined;
+                }
+                resolve();
+            }, milliseconds);
+            this.retryDelay = { timer, reject };
+        });
+    }
+    cancelRetryDelay() {
+        const pending = this.retryDelay;
+        if (!pending) {
+            return;
+        }
+        this.retryDelay = undefined;
+        clearTimeout(pending.timer);
+        pending.reject(new BreezeBlueRealtimeError("Realtime TTS managed reconnect delay was cancelled."));
+    }
+    completeOpenAttempt(attempt) {
+        attempt.active = false;
+        if (attempt.timer !== undefined) {
+            clearTimeout(attempt.timer);
+            attempt.timer = undefined;
+        }
+        attempt.controller.signal.removeEventListener("abort", attempt.abortListener);
+    }
+    cancelOpenAttempt(attempt) {
+        attempt.active = false;
+        if (attempt.timer !== undefined) {
+            clearTimeout(attempt.timer);
+            attempt.timer = undefined;
+        }
+        if (!attempt.controller.signal.aborted) {
+            attempt.controller.abort();
+        }
+        attempt.controller.signal.removeEventListener("abort", attempt.abortListener);
+        attempt.connection?.close();
+    }
+    cancelOpenAttempts() {
+        for (const attempt of Array.from(this.openAttempts)) {
+            this.cancelOpenAttempt(attempt);
+        }
+        this.openAttempts.clear();
+    }
+    beginSettlementDrain(epoch) {
+        epoch.draining = true;
+        this.drainingEpochs.add(epoch);
+        epoch.drainTimer = setTimeout(() => this.finishSettlementDrain(epoch, true), REALTIME_SETTLEMENT_DRAIN_TIMEOUT_MS);
+    }
+    handleSettlementDrainMessage(epoch, message) {
+        if (message.type === "usage.committed") {
+            epoch.pendingUsageHistoryIds.delete(message.historyItemId);
+            this.push(message);
+            if (epoch.pendingUsageHistoryIds.size === 0) {
+                this.finishSettlementDrain(epoch, true);
+                return false;
+            }
+            return true;
+        }
+        if (message.type === "error") {
+            this.finishSettlementDrain(epoch, true);
+            return false;
+        }
+        if (message.type === "session.closed") {
+            this.finishSettlementDrain(epoch, false);
+            return false;
+        }
+        return true;
+    }
+    finishSettlementDrain(epoch, closeConnection) {
+        if (!epoch.draining) {
+            return;
+        }
+        epoch.draining = false;
+        if (epoch.drainTimer !== undefined) {
+            clearTimeout(epoch.drainTimer);
+            epoch.drainTimer = undefined;
+        }
+        this.drainingEpochs.delete(epoch);
+        if (closeConnection) {
+            epoch.connection.close();
+        }
+    }
+    closeSettlementDrains() {
+        for (const epoch of Array.from(this.drainingEpochs)) {
+            this.finishSettlementDrain(epoch, true);
+        }
+    }
+}
+const REALTIME_RECOVERABLE_ERROR_CODES = new Set([
+    "BAD_REQUEST",
+    "GENERATION_CAPACITY_EXCEEDED",
+    "GENERATION_CONCURRENCY_EXCEEDED",
+    "VALIDATION_ERROR",
+]);
+function realtimeErrorFromEvent(event) {
+    const reconnect = event.meta?.reconnect === true ||
+        event.code === "SESSION_EXPIRED" ||
+        event.code === "IDLE_TIMEOUT" ||
+        event.code === "AUTH_CONFIG_MISSING" ||
+        event.code === "GENERATION_INVALID_RESPONSE" ||
+        (event.code.startsWith("UPSTREAM_") && event.code !== "UPSTREAM_BILLING_ERROR");
+    return new BreezeBlueRealtimeError(`Realtime TTS failed: ${event.code}: ${event.message}`, {
+        code: event.code,
+        meta: event.meta,
+        reconnect,
+        recoverable: !reconnect && REALTIME_RECOVERABLE_ERROR_CODES.has(event.code),
+    });
+}
+function realtimeErrorFromClose(event) {
+    const detail = [event.code, event.reason].filter((value) => value !== undefined && value !== "").join(" ");
+    return new BreezeBlueRealtimeError(`Realtime TTS connection closed${detail ? `: ${detail}` : "."}`, {
+        closeCode: event.code,
+        reconnect: isReconnectableClose(event),
+    });
+}
+function isReconnectableClose(event) {
+    return (event.reconnect === true ||
+        event.code === 1001 ||
+        event.code === 1006 ||
+        event.code === 1011 ||
+        event.code === 1012);
+}
+function activeTurnInterruptedError(cause) {
+    const realtimeCause = cause instanceof BreezeBlueRealtimeError ? cause : undefined;
+    return new BreezeBlueRealtimeError("Realtime TTS active turn was interrupted. The SDK did not replay any turn commands; start a new turn from application state.", {
+        code: "TURN_INTERRUPTED",
+        meta: realtimeCause?.meta,
+        closeCode: realtimeCause?.closeCode,
+        reconnect: realtimeCause?.reconnect ?? true,
+        recoverable: false,
+        cause,
+    });
+}
+function reconnectExhaustedError(cause, maxReconnectAttempts) {
+    return new BreezeBlueRealtimeError(`Realtime TTS managed connection exhausted ${maxReconnectAttempts} reconnect attempts.`, {
+        code: "RECONNECT_EXHAUSTED",
+        reconnect: false,
+        recoverable: false,
+        cause,
+    });
+}
+function isRetryableRealtimeSetupError(error) {
+    return error.status >= 500 || error.status === 408 || error.status === 425 || error.status === 429;
+}
+function realtimeMessageSize(message) {
+    if (message.type === "audio") {
+        return message.audio.byteLength;
+    }
+    return JSON.stringify(message).length * 2;
+}
+function optionalNonNegativeNumber(value, name) {
+    return value === undefined ? undefined : nonNegativeNumber(value, name);
+}
+function nonNegativeNumber(value, name) {
+    if (!Number.isFinite(value) || value < 0) {
+        throw new BreezeBlueConfigurationError(`${name} must be a finite non-negative number.`);
+    }
+    return value;
+}
+function positiveNumber(value, name) {
+    if (!Number.isFinite(value) || value <= 0) {
+        throw new BreezeBlueConfigurationError(`${name} must be a finite positive number.`);
+    }
+    return value;
+}
+function nonNegativeInteger(value, name) {
+    if (!Number.isInteger(value) || value < 0) {
+        throw new BreezeBlueConfigurationError(`${name} must be a non-negative integer.`);
+    }
+    return value;
+}
+function asError(error) {
+    return error instanceof Error ? error : new Error(String(error));
 }
 class GenerationJobsResource {
     client;
@@ -498,6 +1434,10 @@ function buildAbortSignal(inputSignal, timeoutMs) {
         },
     };
 }
+function startTurnAbortReason(signal) {
+    return signal.reason ??
+        new BreezeBlueRealtimeError("Realtime TTS managed startTurnWhenReady was aborted before turn.start was sent.");
+}
 function buildUrl(baseUrl, path, params) {
     const url = new URL(`${baseUrl}${path}`);
     for (const [key, value] of Object.entries(params ?? {})) {