@cartesia/cartesia-js 3.0.0-b13 → 3.0.0-b16

package/src/backcompat/index.ts

@@ -2,6 +2,7 @@ import { Cartesia, type ClientOptions } from '../client';
 import { TTSWrapper } from './tts-wrapper';
 import { VoicesWrapper } from './voices-wrapper';
 import { VoiceChangerWrapper } from './voice-changer-wrapper';
+import { buildHeaders, type NullableHeaders } from '../internal/headers';
 import type { CartesiaClientOptions, Supplier } from './types';
 
 async function resolveSupplier<T>(supplier: Supplier<T>): Promise<T> {
@@ -19,27 +20,25 @@ class DynamicCartesia extends Cartesia {
     this.apiKeySupplier = options.apiKeySupplier;
   }
 
-  protected override async prepareRequest(
-    request: RequestInit,
-    _context: { url: string; options: any },
-  ): Promise<void> {
-    await super.prepareRequest(request, _context);
+  protected override validateHeaders(_headers: NullableHeaders): void {
+    // Skip validation if we have a dynamic API key supplier
+    // The key will be resolved and added in authHeaders
+    if (this.apiKeySupplier) {
+      return;
+    }
+    super.validateHeaders(_headers);
+  }
 
+  protected override async authHeaders(opts: any): Promise<NullableHeaders | undefined> {
+    // If we have a dynamic supplier, resolve it and return the auth header
     if (this.apiKeySupplier) {
       const key = await resolveSupplier(this.apiKeySupplier);
       if (key) {
-        const authHeader = `Bearer ${key}`;
-        if (!request.headers) {
-          request.headers = { Authorization: authHeader };
-        } else if (request.headers instanceof Headers) {
-          request.headers.set('Authorization', authHeader);
-        } else if (Array.isArray(request.headers)) {
-          request.headers.push(['Authorization', authHeader]);
-        } else {
-          (request.headers as Record<string, string>)['Authorization'] = authHeader;
-        }
+        return buildHeaders([{ Authorization: `Bearer ${key}` }]);
       }
     }
+    // Otherwise, fall back to default behavior
+    return super.authHeaders(opts);
   }
 }
 

package/src/resources/tts/index.ts

@@ -12,3 +12,5 @@ export {
   type TTSGenerateParams,
   type TTSGenerateSseParams,
 } from './tts';
+
+export { TTSWS, TTSWSContext, type ContextOptions, type ContextGenerateRequest } from './ws';

package/src/resources/tts/tts.ts

@@ -1,5 +1,6 @@
 // File generated from our OpenAPI spec by Stainless. See CONTRIBUTING.md for details.
 
+import type * as WS from 'ws';
 import { APIResource } from '../../core/resource';
 import * as TTSAPI from './tts';
 import * as InfillAPI from '../infill';
@@ -7,6 +8,7 @@ import * as VoicesAPI from '../voices';
 import { APIPromise } from '../../core/api-promise';
 import { buildHeaders } from '../../internal/headers';
 import { RequestOptions } from '../../internal/request-options';
+import { TTSWS } from './ws';
 
 export class TTS extends APIResource {
   /**
@@ -31,6 +33,15 @@ export class TTS extends APIResource {
       headers: buildHeaders([{ Accept: '*/*' }, options?.headers]),
     });
   }
+
+  /**
+   * Create a WebSocket connection for streaming TTS.
+   * Returns a promise that resolves when the connection is open.
+   */
+  async websocket(options?: WS.ClientOptions): Promise<TTSWS> {
+    const ws = new TTSWS(this._client, options);
+    return ws.connect();
+  }
 }
 
 /**

package/src/resources/tts/ws.ts

@@ -1,14 +1,159 @@
 // File generated from our OpenAPI spec by Stainless. See CONTRIBUTING.md for details.
 
 import * as WS from 'ws';
+import { humanId } from 'human-id';
 import { TTSEmitter, buildURL } from './internal-base';
 import * as TTSAPI from './tts';
-import { Cartesia } from '../../client';
+import type { Cartesia } from '../../client';
+
+/**
+ * Request parameters for context.generate(), same as GenerationRequest but without context_id.
+ */
+export type ContextGenerateRequest = Omit<TTSAPI.GenerationRequest, 'context_id'>;
+
+/**
+ * Options for creating a context, including the model, voice, and output format.
+ */
+export interface ContextOptions {
+  model_id: string;
+  voice: TTSAPI.VoiceSpecifier;
+  output_format: TTSAPI.GenerationRequest['output_format'];
+  contextId?: string;
+}
+
+/**
+ * A context helper for managing WebSocket conversations with automatic context_id handling.
+ */
+export class TTSWSContext {
+  private _ws: TTSWS;
+  private _options: Omit<ContextOptions, 'contextId'>;
+  readonly contextId: string;
+
+  constructor(ws: TTSWS, options: ContextOptions) {
+    this._ws = ws;
+    this._options = {
+      model_id: options.model_id,
+      voice: options.voice,
+      output_format: options.output_format,
+    };
+    this.contextId = options.contextId ?? humanId({ separator: '-', capitalize: false });
+  }
+
+  /**
+   * Send a transcript chunk with continue: true.
+   * Call this multiple times to stream transcript chunks, then call done() to finish.
+   */
+  async push(options: { transcript: string }) {
+    this._ws.send({
+      model_id: this._options.model_id,
+      voice: this._options.voice,
+      output_format: this._options.output_format,
+      transcript: options.transcript,
+      context_id: this.contextId,
+      continue: true,
+    });
+  }
+
+  /**
+   * Signal that no more transcript chunks will be sent.
+   * Sends an empty transcript with continue: false.
+   */
+  async done() {
+    this._ws.send({
+      model_id: this._options.model_id,
+      voice: this._options.voice,
+      output_format: this._options.output_format,
+      transcript: '',
+      context_id: this.contextId,
+      continue: false,
+    });
+  }
+
+  /**
+   * Send a generation request without waiting for responses.
+   * Use this for streaming multiple transcript chunks.
+   * The context_id is automatically set.
+   */
+  send(request: ContextGenerateRequest) {
+    this._ws.send({
+      ...request,
+      context_id: this.contextId,
+    });
+  }
+
+  /**
+   * Iterate over responses for this context.
+   * Completes when a "done" event is received.
+   */
+  async *receive(): AsyncGenerator<TTSAPI.WebsocketResponse> {
+    const queue: TTSAPI.WebsocketResponse[] = [];
+    let done = false;
+    let error: Error | null = null;
+    let resolve: (() => void) | null = null;
+
+    const onEvent = (event: TTSAPI.WebsocketResponse) => {
+      // Filter by context_id
+      if ('context_id' in event && event.context_id !== this.contextId) {
+        return;
+      }
+      queue.push(event);
+      if (event.type === 'done' || event.type === 'error') {
+        done = true;
+        if (event.type === 'error') {
+          error = new Error(JSON.stringify(event));
+        }
+      }
+      resolve?.();
+    };
+
+    this._ws.on('event', onEvent);
+
+    try {
+      while (!done || queue.length > 0) {
+        if (queue.length > 0) {
+          const event = queue.shift()!;
+          yield event;
+          if (event.type === 'done') {
+            return;
+          }
+          if (event.type === 'error') {
+            throw error;
+          }
+        } else {
+          await new Promise<void>((r) => {
+            resolve = r;
+          });
+        }
+      }
+    } finally {
+      this._ws.off('event', onEvent);
+    }
+  }
+
+  /**
+   * Send a generation request and iterate over the responses.
+   * The context_id is automatically set.
+   */
+  async *generate(request: ContextGenerateRequest): AsyncGenerator<TTSAPI.WebsocketResponse> {
+    yield* this._ws.generate({
+      ...request,
+      context_id: this.contextId,
+    });
+  }
+
+  /**
+   * Cancel this context to stop generating speech.
+   */
+  cancel() {
+    this._ws.cancelContext(this.contextId);
+  }
+}
 
 export class TTSWS extends TTSEmitter {
   url: URL;
   socket: WS.WebSocket;
   private client: Cartesia;
+  private _ready: Promise<void>;
 
   constructor(client: Cartesia, options?: WS.ClientOptions | undefined) {
     super();
@@ -23,6 +168,11 @@ export class TTSWS extends TTSEmitter {
       },
     });
 
+    this._ready = new Promise((resolve, reject) => {
+      this.socket.once('open', () => resolve());
+      this.socket.once('error', (err) => reject(err));
+    });
+
     this.socket.on('message', (wsEvent) => {
       const event = (() => {
         try {
@@ -58,6 +208,71 @@ export class TTSWS extends TTSEmitter {
     }
   }
 
+  /**
+   * Send a generation request and iterate over the responses.
+   */
+  async *generate(request: TTSAPI.GenerationRequest): AsyncGenerator<TTSAPI.WebsocketResponse> {
+    const contextId = request.context_id;
+    const queue: TTSAPI.WebsocketResponse[] = [];
+    let done = false;
+    let error: Error | null = null;
+    let resolve: (() => void) | null = null;
+
+    const onEvent = (event: TTSAPI.WebsocketResponse) => {
+      // Filter by context_id if specified
+      if (contextId && 'context_id' in event && event.context_id !== contextId) {
+        return;
+      }
+      queue.push(event);
+      if (event.type === 'done' || event.type === 'error') {
+        done = true;
+        if (event.type === 'error') {
+          error = new Error(JSON.stringify(event));
+        }
+      }
+      resolve?.();
+    };
+
+    this.on('event', onEvent);
+
+    try {
+      this.send(request);
+
+      while (!done || queue.length > 0) {
+        if (queue.length > 0) {
+          const event = queue.shift()!;
+          yield event;
+          if (event.type === 'done') {
+            return;
+          }
+          if (event.type === 'error') {
+            throw error;
+          }
+        } else {
+          await new Promise<void>((r) => {
+            resolve = r;
+          });
+        }
+      }
+    } finally {
+      this.off('event', onEvent);
+    }
+  }
+
+  /**
+   * Cancel a context to stop generating speech for it.
+   */
+  cancelContext(contextId: string) {
+    this.send({ cancel: true, context_id: contextId });
+  }
+
+  /**
+   * Create a new context with the given options.
+   */
+  context(options: ContextOptions): TTSWSContext {
+    return new TTSWSContext(this, options);
+  }
+
   close(props?: { code: number; reason: string }) {
     try {
       this.socket.close(props?.code ?? 1000, props?.reason ?? 'OK');
@@ -66,6 +281,14 @@ export class TTSWS extends TTSEmitter {
     }
   }
 
+  /**
+   * Wait for the WebSocket connection to be ready.
+   */
+  async connect(): Promise<this> {
+    await this._ready;
+    return this;
+  }
+
   private authHeaders(): Record<string, string> {
     if (this.client.token) {
       return { Authorization: `Bearer ${this.client.token}` };

package/src/resources/voices.ts

@@ -163,7 +163,8 @@ export type SupportedLanguage =
   | 'kn'
   | 'ml'
   | 'mr'
-  | 'pa';
+  | 'pa'
+  | (string & {});
 
 export interface Voice {
   /**

package/src/version.ts

@@ -1 +1 @@
-export const VERSION = '3.0.0-b13'; // x-release-please-version
+export const VERSION = '3.0.0-b16'; // x-release-please-version

package/version.d.mts

@@ -1,2 +1,2 @@
-export declare const VERSION = "3.0.0-b13";
+export declare const VERSION = "3.0.0-b16";
 //# sourceMappingURL=version.d.mts.map

package/version.d.ts

@@ -1,2 +1,2 @@
-export declare const VERSION = "3.0.0-b13";
+export declare const VERSION = "3.0.0-b16";
 //# sourceMappingURL=version.d.ts.map

package/version.js

@@ -1,5 +1,5 @@
 "use strict";
 Object.defineProperty(exports, "__esModule", { value: true });
 exports.VERSION = void 0;
-exports.VERSION = '3.0.0-b13'; // x-release-please-version
+exports.VERSION = '3.0.0-b16'; // x-release-please-version
 //# sourceMappingURL=version.js.map

package/version.mjs

@@ -1,2 +1,2 @@
-export const VERSION = '3.0.0-b13'; // x-release-please-version
+export const VERSION = '3.0.0-b16'; // x-release-please-version
 //# sourceMappingURL=version.mjs.map