@breeze.blue/sdk 0.7.0 → 0.9.0

package/CHANGELOG.md

@@ -2,6 +2,17 @@
 
 ## Unreleased
 
+## 0.9.0
+
+- Added language-aware voice search and language metadata for voice results,
+  preview saves, and saved-voice edits.
+
+## 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? }
   },
 });
 ```
@@ -443,13 +449,14 @@ await save(audio, "preview.mp3");
 const saved = await client.voices.savePreview({
   generatedVoiceId,
   voiceName: "Documentary narrator",
+  languageCode: "en",
 });
 ```
 
 Edit, tune settings, or delete a saved voice:
 
 ```ts
-await client.voices.edit(saved.voiceId, { name: "Renamed narrator" });
+await client.voices.edit(saved.voiceId, { name: "Renamed narrator", languageCode: "en" });
 await client.voices.editSettings(saved.voiceId, { guidanceScale: 1.2 });
 await client.voices.delete(saved.voiceId);
 ```

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();
@@ -1503,6 +1546,7 @@ class VoicesResource {
             primaryCategoryCode: request.primaryCategoryCode,
             visibility: request.visibility,
             playedNotSelectedVoiceIds: request.playedNotSelectedVoiceIds,
+            languageCode: request.languageCode,
         }, options);
     }
 }
@@ -1651,6 +1695,7 @@ function voiceEditForm(request) {
     appendOptional(form, "labels", request.labels ? JSON.stringify(request.labels) : undefined);
     appendOptional(form, "primary_category_code", request.primaryCategoryCode);
     appendOptional(form, "visibility", request.visibility);
+    appendOptional(form, "language_code", request.languageCode);
     for (const file of normalizeFiles(request.file, request.files, { required: false })) {
         appendFile(form, "files", file);
     }

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 {
     /**
@@ -304,6 +309,7 @@ export interface Voice {
     createdAtUnix?: number | null;
     primaryCategoryCode?: string | null;
     visibility?: string | null;
+    languageCode: string;
     [key: string]: unknown;
 }
 export interface SavedVoice {
@@ -315,6 +321,7 @@ export interface SavedVoice {
     createdAtUnix?: number | null;
     primaryCategoryCode?: string | null;
     visibility?: string | null;
+    languageCode: string;
 }
 export interface VoiceList {
     voices: Voice[];
@@ -326,6 +333,7 @@ export interface VoiceList {
 }
 export interface VoiceSearchParams {
     search?: string;
+    languageCode?: string;
     origin?: "designed" | "cloned" | string;
     voiceType?: "all" | "default" | "personal" | string;
     sort?: "created_at_unix" | "name" | string;
@@ -363,6 +371,7 @@ export interface VoiceEditRequest {
     labels?: Record<string, string>;
     primaryCategoryCode?: string;
     visibility?: "private" | "public" | string;
+    languageCode?: string;
     file?: UploadData | UploadFile;
     files?: Array<UploadData | UploadFile>;
 }
@@ -396,6 +405,7 @@ export interface SaveVoiceRequest {
     primaryCategoryCode?: string;
     visibility?: "private" | "public" | string;
     playedNotSelectedVoiceIds?: string[];
+    languageCode?: string;
 }
 export interface HistoryItem {
     historyItemId: string;

package/dist/version.d.ts

@@ -1,2 +1,2 @@
-export declare const SDK_VERSION = "0.7.0";
+export declare const SDK_VERSION = "0.9.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.9.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.9.0",
   "description": "ESM-first TypeScript SDK for the Breeze Blue Developer API.",
   "license": "MIT",
   "author": "Breeze Blue <support@breeze.blue>",