@breeze.blue/sdk 0.7.0 → 0.8.0

package/CHANGELOG.md

@@ -2,6 +2,12 @@
 
 ## Unreleased
 
+## 0.8.0
+
+- Realtime TTS sessions prefer the optional query-free direct WebSocket URL
+  and authenticate with a non-echoed token-bearing subprotocol. Existing
+  public session URLs remain the fallback for older deployments and clients.
+
 ## 0.7.0
 
 - Realtime TTS connections can update synthesis instructions between turns

package/README.md

@@ -278,9 +278,15 @@ const session = await client.textToSpeech.realtime.createSession("voc_...", {
 // Later, when the first text is ready:
 const connection = await client.textToSpeech.realtime.connect("voc_...", {
   clientSecret: session.clientSecret,
+  websocketUrl: session.websocketUrl,
+  directWebsocketUrl: session.directWebsocketUrl,
 });
 ```
 
+When the session response includes `directWebsocketUrl`, the SDK prefers its
+query-free origin and authenticates with the WebSocket subprotocol. It falls
+back to `websocketUrl` for services that have not enabled the direct transport.
+
 The same `clientSecret` handoff lets a browser connect without ever seeing your
 API key: create the session on your server, hand `session.clientSecret` to the
 page, and build a key-less client there:
@@ -315,7 +321,7 @@ const connection = await browserClient.textToSpeech.realtime.connectManaged("voc
         reconnect,
       });
     }
-    return response.json(); // { clientSecret, websocketUrl? }
+    return response.json(); // { clientSecret, websocketUrl?, directWebsocketUrl? }
   },
 });
 ```

package/dist/client.d.ts

@@ -54,6 +54,7 @@ export declare class RealtimeTextToSpeechConnection implements AsyncIterable<Rea
     static open(socket: BreezeBlueWebSocket, options?: {
         timeout?: number;
         signal?: AbortSignal;
+        requiredSubprotocol?: string;
     }): Promise<RealtimeTextToSpeechConnection>;
     startTurn(turnId?: string): void;
     appendText(text: string): void;

package/dist/client.js

@@ -15,6 +15,9 @@ const MAX_REALTIME_RECONNECT_DELAY_MS = 4_000;
 const REALTIME_SETTLEMENT_DRAIN_TIMEOUT_MS = 5_000;
 const REALTIME_CLOSE_EVENT_GRACE_MS = 50;
 const REALTIME_MAX_INSTRUCTIONS_CHARACTERS = 1_000;
+const REALTIME_SAFE_SUBPROTOCOL = "breeze-realtime-v1";
+const REALTIME_TOKEN_SUBPROTOCOL_PREFIX = "breeze-realtime-token.";
+const REALTIME_MAX_TOKEN_SUBPROTOCOL_LENGTH = 7 * 1024;
 const WEBSOCKET_OPEN = 1;
 export class BreezeBlueClient {
     apiKey;
@@ -129,31 +132,55 @@ class RealtimeTextToSpeechResource {
         return this.client.requestJson("POST", `/v1/text-to-speech/${encodeURIComponent(voiceId)}/realtime-sessions`, undefined, request, options);
     }
     async connect(voiceId, options = {}) {
-        if ((options.clientSecret !== undefined || options.websocketUrl !== undefined) && hasRealtimeSessionParams(options)) {
+        if ((options.clientSecret !== undefined ||
+            options.websocketUrl !== undefined ||
+            options.directWebsocketUrl !== undefined) && hasRealtimeSessionParams(options)) {
             console.warn("@breeze.blue/sdk: realtime.connect ignores modelId, languageCode, instructions, voiceSettings, " +
-                "inactivityTimeoutSeconds, and enableLogging when clientSecret or websocketUrl is provided. " +
+                "inactivityTimeoutSeconds, and enableLogging when session credentials are provided. " +
                 "Configure these initial values when creating the realtime session instead. " +
                 "To change instructions between turns, call connection.updateInstructions() and wait for session.updated.");
         }
-        const websocketUrl = options.websocketUrl ??
-            (options.clientSecret
-                ? buildUrl(this.client.baseUrl.replace(/^http/i, "ws"), `/v1/text-to-speech/${encodeURIComponent(voiceId)}/stream-input`, { client_secret: options.clientSecret })
-                : (await this.createSession(voiceId, {
-                    modelId: options.modelId,
-                    languageCode: options.languageCode,
-                    instructions: options.instructions,
-                    voiceSettings: options.voiceSettings,
-                    inactivityTimeoutSeconds: options.inactivityTimeoutSeconds,
-                    enableLogging: options.enableLogging,
-                }, {
-                    signal: options.signal,
-                    timeout: options.timeout,
-                })).websocketUrl);
+        let clientSecret = options.clientSecret;
+        let websocketUrl = options.websocketUrl;
+        let directWebsocketUrl = options.directWebsocketUrl;
+        if (!clientSecret && !websocketUrl && !directWebsocketUrl) {
+            const session = await this.createSession(voiceId, {
+                modelId: options.modelId,
+                languageCode: options.languageCode,
+                instructions: options.instructions,
+                voiceSettings: options.voiceSettings,
+                inactivityTimeoutSeconds: options.inactivityTimeoutSeconds,
+                enableLogging: options.enableLogging,
+            }, {
+                signal: options.signal,
+                timeout: options.timeout,
+            });
+            clientSecret = session.clientSecret;
+            websocketUrl = session.websocketUrl;
+            directWebsocketUrl = session.directWebsocketUrl;
+        }
+        if (!websocketUrl && clientSecret) {
+            websocketUrl = buildUrl(this.client.baseUrl.replace(/^http/i, "ws"), `/v1/text-to-speech/${encodeURIComponent(voiceId)}/stream-input`, { client_secret: clientSecret });
+        }
+        let protocols;
+        let requiredSubprotocol;
+        if (directWebsocketUrl) {
+            if (!clientSecret) {
+                throw new BreezeBlueConfigurationError("realtime directWebsocketUrl requires a clientSecret.");
+            }
+            protocols = realtimeClientSecretSubprotocols(clientSecret);
+            requiredSubprotocol = REALTIME_SAFE_SUBPROTOCOL;
+            websocketUrl = directWebsocketUrl;
+        }
+        if (!websocketUrl) {
+            throw new BreezeBlueConfigurationError("realtime.connect requires session credentials or an API-created session.");
+        }
         const WebSocketImpl = requireWebSocket(options.webSocket ?? this.client.webSocket);
-        const socket = new WebSocketImpl(websocketUrl);
+        const socket = new WebSocketImpl(websocketUrl, protocols);
         return RealtimeTextToSpeechConnection.open(socket, {
             timeout: options.timeout ?? this.client.timeout ?? DEFAULT_REALTIME_HANDSHAKE_TIMEOUT_MS,
             signal: options.signal,
+            requiredSubprotocol,
         });
     }
     /**
@@ -191,6 +218,7 @@ class RealtimeTextToSpeechResource {
             return this.connect(voiceId, {
                 clientSecret: credentials.clientSecret,
                 websocketUrl: credentials.websocketUrl,
+                directWebsocketUrl: credentials.directWebsocketUrl,
                 webSocket: options.webSocket,
                 signal,
                 timeout: connectionTimeout,
@@ -212,6 +240,16 @@ function hasRealtimeSessionParams(options) {
         options.inactivityTimeoutSeconds !== undefined ||
         options.enableLogging !== undefined);
 }
+function realtimeClientSecretSubprotocols(clientSecret) {
+    if (!/^[A-Za-z0-9_-]+\.[A-Za-z0-9_-]{43}$/.test(clientSecret)) {
+        throw new BreezeBlueConfigurationError("Realtime clientSecret cannot be encoded as a WebSocket subprotocol token.");
+    }
+    const tokenProtocol = `${REALTIME_TOKEN_SUBPROTOCOL_PREFIX}${clientSecret}`;
+    if (tokenProtocol.length > REALTIME_MAX_TOKEN_SUBPROTOCOL_LENGTH) {
+        throw new BreezeBlueConfigurationError("Realtime clientSecret WebSocket subprotocol is too long.");
+    }
+    return [REALTIME_SAFE_SUBPROTOCOL, tokenProtocol];
+}
 export class RealtimeTextToSpeechConnection {
     socket;
     queue = [];
@@ -240,6 +278,11 @@ export class RealtimeTextToSpeechConnection {
             const succeed = () => {
                 if (settled)
                     return;
+                if (options.requiredSubprotocol !== undefined &&
+                    socket.protocol !== options.requiredSubprotocol) {
+                    fail(new BreezeBlueRealtimeError(`Realtime TTS WebSocket did not negotiate ${options.requiredSubprotocol}.`, { code: "GENERATION_INVALID_RESPONSE" }));
+                    return;
+                }
                 settled = true;
                 cleanup();
                 resolve();

package/dist/types.d.ts

@@ -28,6 +28,7 @@ export type BreezeBlueWebSocketConstructor = new (url: string, protocols?: strin
 export interface BreezeBlueWebSocket {
     binaryType: string;
     readyState: number;
+    readonly protocol?: string;
     onopen: ((event: Event) => void) | null;
     onmessage: ((event: MessageEvent) => void) | null;
     onerror: ((event: Event) => void) | null;
@@ -54,12 +55,14 @@ export interface RealtimeTextToSpeechAudioFormat {
 export interface RealtimeTextToSpeechSession {
     clientSecret: string;
     websocketUrl: string;
+    directWebsocketUrl?: string;
     expiresAt: string;
     audioFormat: RealtimeTextToSpeechAudioFormat;
 }
 export interface RealtimeTextToSpeechConnectOptions extends RealtimeTextToSpeechSessionRequest {
     clientSecret?: string;
     websocketUrl?: string;
+    directWebsocketUrl?: string;
     webSocket?: BreezeBlueWebSocketConstructor;
     signal?: AbortSignal;
     /** Handshake timeout in milliseconds. Defaults to the client `timeout`. */
@@ -68,9 +71,11 @@ export interface RealtimeTextToSpeechConnectOptions extends RealtimeTextToSpeech
 export type RealtimeTextToSpeechSessionCredentials = {
     clientSecret: string;
     websocketUrl?: string;
+    directWebsocketUrl?: string;
 } | {
     clientSecret?: string;
     websocketUrl: string;
+    directWebsocketUrl?: string;
 };
 export interface RealtimeTextToSpeechSessionFactoryContext {
     /**

package/dist/version.d.ts

@@ -1,2 +1,2 @@
-export declare const SDK_VERSION = "0.7.0";
+export declare const SDK_VERSION = "0.8.0";
 export declare const SDK_NAME = "@breeze.blue/sdk";

package/dist/version.js

@@ -1,2 +1,2 @@
-export const SDK_VERSION = "0.7.0";
+export const SDK_VERSION = "0.8.0";
 export const SDK_NAME = "@breeze.blue/sdk";

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@breeze.blue/sdk",
-  "version": "0.7.0",
+  "version": "0.8.0",
   "description": "ESM-first TypeScript SDK for the Breeze Blue Developer API.",
   "license": "MIT",
   "author": "Breeze Blue <support@breeze.blue>",