@cartesia/cartesia-js 3.0.0-b3 → 3.0.0-b5

package/src/backcompat/index.ts

@@ -0,0 +1,302 @@
+import WebSocket from "ws";
+import { Cartesia } from "../client";
+
+class AudioSource {
+	private buffers: Buffer[] = [];
+	private waiter: ((val?: any) => void) | null = null;
+	public isDone = false;
+
+	push(data: Buffer) {
+		this.buffers.push(data);
+		if (this.waiter) {
+			this.waiter();
+			this.waiter = null;
+		}
+	}
+
+	markDone() {
+		this.isDone = true;
+		if (this.waiter) {
+			this.waiter();
+			this.waiter = null;
+		}
+	}
+
+	async read(outBuffer: Float32Array): Promise<number> {
+		if (this.buffers.length === 0 && !this.isDone) {
+			await new Promise<void>((resolve) => { this.waiter = resolve; });
+		}
+
+		if (this.buffers.length === 0 && this.isDone) {
+			return 0;
+		}
+
+		let totalFloatsRead = 0;
+		let outOffset = 0;
+		const maxFloats = outBuffer.length;
+
+		while (this.buffers.length > 0 && totalFloatsRead < maxFloats) {
+			const buf = this.buffers[0] as Buffer; // ts not smart enough to check loop condition
+			const floatsInBuf = buf.length / 4;
+			const floatsNeeded = maxFloats - totalFloatsRead;
+
+			const floatsToCopy = Math.min(floatsInBuf, floatsNeeded);
+			const bytesToCopy = floatsToCopy * 4;
+
+			// Copy to outBuffer.
+			// Create a view on the buffer to read floats.
+
+			// We need to ensure byteOffset is a multiple of 4.
+			// If not, we must copy the buffer to a new one.
+			let srcFloats: Float32Array;
+			if (buf.byteOffset % 4 === 0) {
+				srcFloats = new Float32Array(buf.buffer, buf.byteOffset, floatsInBuf);
+			} else {
+				const alignedBuf = new Uint8Array(buf);
+				srcFloats = new Float32Array(alignedBuf.buffer, alignedBuf.byteOffset, floatsInBuf);
+			}
+
+			outBuffer.set(srcFloats.subarray(0, floatsToCopy), outOffset);
+
+			totalFloatsRead += floatsToCopy;
+			outOffset += floatsToCopy;
+
+			if (floatsToCopy < floatsInBuf) {
+				// We didn't use the whole buffer. Update it.
+				this.buffers[0] = buf.subarray(bytesToCopy);
+			} else {
+				// We used the whole buffer. Remove it.
+				this.buffers.shift();
+			}
+		}
+
+		return totalFloatsRead;
+	}
+}
+
+class WebSocketWrapper {
+	private client: Cartesia;
+	private config: any;
+	private socket: WebSocket | null = null;
+	private sources: Map<string, AudioSource> = new Map();
+	// Fallback source for messages without context_id or if we just want to capture everything (legacy behavior?)
+	// The original test didn't use context_id explicitly in send() but expected a response source.
+	// We'll map context_id to source.
+	private defaultSource: AudioSource | null = null;
+
+	constructor(client: Cartesia, config: any) {
+		this.client = client;
+		this.config = config;
+	}
+
+	async connect() {
+		const baseURL = this.client.baseURL;
+		// Construct WebSocket URL
+		// baseURL is like https://api.cartesia.ai
+		let urlStr = baseURL.replace(/^http/, "ws");
+		if (!urlStr.includes("/tts/websocket")) {
+			if (urlStr.endsWith("/")) {
+				urlStr += "tts/websocket";
+			} else {
+				urlStr += "/tts/websocket";
+			}
+		}
+
+		const url = new URL(urlStr);
+
+		const headers: any = {
+			"cartesia-version": "2025-04-16",
+		};
+		if (this.client.apiKey) {
+			headers["Authorization"] = `Bearer ${this.client.apiKey}`;
+		}
+
+		this.socket = new WebSocket(url.toString(), {
+			headers: headers,
+		});
+
+		return new Promise<void>((resolve, reject) => {
+			this.socket!.on("open", () => {
+				console.log("WebSocket connected.");
+				resolve();
+			});
+
+			this.socket!.on("error", (err) => {
+				console.error("WebSocket error:", err);
+				reject(err);
+			});
+
+			this.socket!.on("message", (data) => {
+				this.handleMessage(data);
+			});
+
+			this.socket!.on("close", () => {
+				console.log("WebSocket closed.");
+				this.sources.forEach((s) => { s.markDone(); });
+				if (this.defaultSource) this.defaultSource.markDone();
+			});
+		});
+	}
+
+	private handleMessage(data: WebSocket.Data) {
+		try {
+			const str = data.toString();
+			const msg = JSON.parse(str);
+
+			const contextId = msg.context_id;
+			let source = contextId ? this.sources.get(contextId) : this.defaultSource;
+
+			// If we received a message for a context we don't know about, and we have a default source, use it
+			if (!source && this.defaultSource) {
+				source = this.defaultSource;
+			}
+
+			if (msg.type === "chunk" && msg.data) {
+				const audioData = Buffer.from(msg.data, "base64");
+				if (source) source.push(audioData);
+			} else if (msg.type === "done") {
+				if (source) source.markDone();
+			} else if (msg.type === "error") {
+				console.error("Server error:", msg);
+				if (source) source.markDone(); // Fail the stream?
+			}
+		} catch (e) {
+			console.error("Error parsing message:", e);
+		}
+	}
+
+	async send(request: any) {
+		if (!this.socket) {
+			throw new Error("WebSocket not connected");
+		}
+
+		// Ensure request has a context_id so we can route the response
+		if (!request.context_id) {
+			request.context_id = uuidv4();
+		}
+
+		const source = new AudioSource();
+		this.sources.set(request.context_id, source);
+		// Also set as default source if none exists, for compatibility with simple tests
+		if (!this.defaultSource) {
+			this.defaultSource = source;
+		}
+
+		// Add output format from config if not present
+		if (!request.output_format && this.config) {
+			request.output_format = {
+				container: this.config.container,
+				encoding: this.config.encoding,
+				sample_rate: this.config.sampleRate,
+			};
+		}
+		// Fix camelCase to snake_case for output_format if needed
+		// The new API expects snake_case keys in JSON usually, but let's check.
+		// The GenerationRequest interface has `output_format`.
+		// The config passed to .websocket() uses `sampleRate`.
+		// We might need to map it.
+
+		if (request.output_format) {
+			// Ensure sample_rate is set (mapping from sampleRate)
+			if (request.output_format.sampleRate && !request.output_format.sample_rate) {
+				request.output_format.sample_rate = request.output_format.sampleRate;
+				delete request.output_format.sampleRate;
+			}
+		}
+
+		// Map camelCase request fields to snake_case if necessary?
+		// The old test uses `modelId`, `generationConfig`.
+		// The new API expects `model_id`, `generation_config`.
+		const payload = {
+			...request,
+			model_id: request.modelId || request.model_id,
+			generation_config: request.generationConfig || request.generation_config,
+			context_id: request.context_id,
+		};
+		// Remove camelCase keys if they persist?
+		// JSON.stringify handles it, but we should clean up if we want to be strict.
+
+		// Also `voice` object. Old test: `voice: { mode: 'id', id: ... }`. New API: same.
+
+		this.socket.send(JSON.stringify(payload));
+
+		return {
+			source: source
+		};
+	}
+
+	disconnect() {
+		if (this.socket) {
+			this.socket.close();
+		}
+	}
+}
+
+class TTSWrapper {
+	private client: Cartesia;
+
+	constructor(client: Cartesia) {
+		this.client = client;
+	}
+
+	websocket(config: any) {
+		return new WebSocketWrapper(this.client, config);
+	}
+
+	async bytes(request: any, requestOptions?: any) {
+		const params: any = {
+			model_id: request.modelId,
+			transcript: request.transcript,
+			voice: request.voice,
+			generation_config: request.generationConfig,
+			context_id: request.contextId,
+		};
+
+		if (request.outputFormat) {
+			params.output_format = {
+				...request.outputFormat,
+				sample_rate: request.outputFormat.sampleRate,
+				bit_rate: request.outputFormat.bitRate,
+			};
+			// Remove camelCase keys
+			delete params.output_format.sampleRate;
+			delete params.output_format.bitRate;
+		}
+
+		const options: any = {};
+		if (requestOptions) {
+			if (requestOptions.timeoutInSeconds) {
+				options.timeout = requestOptions.timeoutInSeconds * 1000;
+			}
+			options.maxRetries = requestOptions.maxRetries;
+			options.headers = requestOptions.headers;
+			options.signal = requestOptions.abortSignal;
+		}
+
+		// @ts-ignore
+		return this.client.tts.synthesizeBytes(params, options);
+	}
+}
+
+/*
+ * CartesiaClient - deprecated backcompat class.
+ * New code should use Cartesia class directly instead.
+ */
+export class CartesiaClient {
+	private client: Cartesia;
+	public tts: TTSWrapper;
+
+	constructor(options: any) {
+		this.client = new Cartesia(options);
+		this.tts = new TTSWrapper(this.client);
+	}
+}
+
+
+// Helper for generating UUIDs. Not cryptographically secure.
+function uuidv4() {
+	return 'xxxxxxxx-xxxx-4xxx-yxxx-xxxxxxxxxxxx'.replace(/[xy]/g, function(c) {
+		var r = Math.random() * 16 | 0, v = c == 'x' ? r : (r & 0x3 | 0x8);
+		return v.toString(16);
+	});
+}

package/src/client.ts

@@ -51,6 +51,7 @@ import {
   SupportedLanguage,
   Voice,
   VoiceCloneParams,
+  VoiceGetParams,
   VoiceListParams,
   VoiceLocalizeParams,
   VoiceMetadata,
@@ -942,6 +943,7 @@ export declare namespace Cartesia {
     type VoiceUpdateParams as VoiceUpdateParams,
     type VoiceListParams as VoiceListParams,
     type VoiceCloneParams as VoiceCloneParams,
+    type VoiceGetParams as VoiceGetParams,
     type VoiceLocalizeParams as VoiceLocalizeParams,
   };
 }

package/src/index.ts

@@ -5,6 +5,7 @@ export { Cartesia as default } from './client';
 export { type Uploadable, toFile } from './core/uploads';
 export { APIPromise } from './core/api-promise';
 export { Cartesia, type ClientOptions } from './client';
+export { CartesiaClient } from './backcompat';
 export { PagePromise } from './core/pagination';
 export {
   CartesiaError,

package/src/resources/access-token.ts

@@ -41,6 +41,12 @@ export namespace AccessTokenCreateParams {
    * optional - specify only the capabilities you need.
    */
   export interface Grants {
+    /**
+     * The `agent` grant allows the token to be used to access the Agent websocket
+     * calling [endpoint](/line/integrations/web-calls#connection).
+     */
+    agent?: boolean | null;
+
     /**
      * The `stt` grant allows the token to be used to access any STT endpoint.
      */

package/src/resources/agents/agents.ts

@@ -44,7 +44,7 @@ export class Agents extends APIResource {
    * Lists all agents associated with your account.
    */
   list(options?: RequestOptions): APIPromise<AgentListResponse> {
-    return this._client.get('/agents/', options);
+    return this._client.get('/agents', options);
   }
 
   /**

package/src/resources/agents/metrics/index.ts

@@ -12,6 +12,7 @@ export {
 export {
   Results,
   type ResultListResponse,
+  type ResultExportResponse,
   type ResultListParams,
   type ResultExportParams,
   type ResultListResponsesCursorIDPage,

package/src/resources/agents/metrics/metrics.ts

@@ -4,6 +4,7 @@ import { APIResource } from '../../../core/resource';
 import * as ResultsAPI from './results';
 import {
   ResultExportParams,
+  ResultExportResponse,
   ResultListParams,
   ResultListResponse,
   ResultListResponsesCursorIDPage,
@@ -179,6 +180,7 @@ export declare namespace Metrics {
   export {
     Results as Results,
     type ResultListResponse as ResultListResponse,
+    type ResultExportResponse as ResultExportResponse,
     type ResultListResponsesCursorIDPage as ResultListResponsesCursorIDPage,
     type ResultListParams as ResultListParams,
     type ResultExportParams as ResultExportParams,

package/src/resources/agents/metrics/results.ts

@@ -4,6 +4,7 @@ import { APIResource } from '../../../core/resource';
 import * as CallsAPI from '../calls';
 import { APIPromise } from '../../../core/api-promise';
 import { CursorIDPage, type CursorIDPageParams, PagePromise } from '../../../core/pagination';
+import { type Uploadable } from '../../../core/uploads';
 import { buildHeaders } from '../../../internal/headers';
 import { RequestOptions } from '../../../internal/request-options';
 
@@ -22,16 +23,15 @@ export class Results extends APIResource {
   }
 
   /**
-   * Export metric results to a CSV file. This endpoint is paginated with a default
-   * of 10 results per page and maximum of 100 results per page. Information on
-   * pagination can be found in the headers `x-has-more`, `x-limit`, and
-   * `x-next-page`.
+   * Export metric results to a CSV file. This endpoint streams at most 100k results
+   * as the CSV file directly to the client. Use the optional filters to narrow down
+   * the results to export.
    */
-  export(query: ResultExportParams | null | undefined = {}, options?: RequestOptions): APIPromise<void> {
+  export(query: ResultExportParams | null | undefined = {}, options?: RequestOptions): APIPromise<string> {
     return this._client.get('/agents/metrics/results/export', {
       query,
       ...options,
-      headers: buildHeaders([{ Accept: '*/*' }, options?.headers]),
+      headers: buildHeaders([{ Accept: 'text/csv' }, options?.headers]),
     });
   }
 }
@@ -110,6 +110,8 @@ export interface ResultListResponse {
   value?: unknown;
 }
 
+export type ResultExportResponse = Uploadable;
+
 export interface ResultListParams extends CursorIDPageParams {
   /**
    * The ID of the agent.
@@ -126,6 +128,12 @@ export interface ResultListParams extends CursorIDPageParams {
    */
   deployment_id?: string | null;
 
+  /**
+   * Filter metric results created before or at this ISO 8601 date/time (e.g.
+   * 2024-04-30T23:59:59Z).
+   */
+  end_date?: string | null;
+
   /**
    * The number of metric results to return per page, ranging between 1 and 100.
    */
@@ -135,6 +143,12 @@ export interface ResultListParams extends CursorIDPageParams {
    * The ID of the metric.
    */
   metric_id?: string | null;
+
+  /**
+   * Filter metric results created at or after this ISO 8601 date/time (e.g.
+   * 2024-04-01T00:00:00Z).
+   */
+  start_date?: string | null;
 }
 
 export interface ResultExportParams {
@@ -154,18 +168,10 @@ export interface ResultExportParams {
   deployment_id?: string | null;
 
   /**
-   * A cursor to use in pagination. `ending_before` is a metric result ID that
-   * defines your place in the list. For example, if you make a /metrics/results
-   * request and receive 100 objects, starting with `metric_result_abc123`, your
-   * subsequent call can include `ending_before=metric_result_abc123` to fetch the
-   * previous page of the list.
-   */
-  ending_before?: string | null;
-
-  /**
-   * The number of metric results to return per page, ranging between 1 and 100.
+   * Filter metric results created before or at this ISO 8601 date/time (e.g.
+   * 2024-04-30T23:59:59Z).
    */
-  limit?: number | null;
+  end_date?: string | null;
 
   /**
    * The ID of the metric.
@@ -173,18 +179,16 @@ export interface ResultExportParams {
   metric_id?: string | null;
 
   /**
-   * A cursor to use in pagination. `starting_after` is a metric result ID that
-   * defines your place in the list. For example, if you make a /metrics/results
-   * request and receive 100 objects, ending with `metric_result_abc123`, your
-   * subsequent call can include `starting_after=metric_result_abc123` to fetch the
-   * next page of the list.
+   * Filter metric results created at or after this ISO 8601 date/time (e.g.
+   * 2024-04-01T00:00:00Z).
    */
-  starting_after?: string | null;
+  start_date?: string | null;
 }
 
 export declare namespace Results {
   export {
     type ResultListResponse as ResultListResponse,
+    type ResultExportResponse as ResultExportResponse,
     type ResultListResponsesCursorIDPage as ResultListResponsesCursorIDPage,
     type ResultListParams as ResultListParams,
     type ResultExportParams as ResultExportParams,

package/src/resources/index.ts

@@ -62,6 +62,7 @@ export {
   type VoiceUpdateParams,
   type VoiceListParams,
   type VoiceCloneParams,
+  type VoiceGetParams,
   type VoiceLocalizeParams,
   type VoicesCursorIDPage,
 } from './voices';

package/src/resources/infill.ts

@@ -16,8 +16,6 @@ export class Infill extends APIResource {
    * **The cost is 1 credit per character of the infill text plus a fixed cost of 300
    * credits.**
    *
-   * Infilling is only available on `sonic-2` at this time.
-   *
    * At least one of `left_audio` or `right_audio` must be provided.
    *
    * As with all generative models, there's some inherent variability, but here's
@@ -55,7 +53,8 @@ export interface InfillCreateParams {
   left_audio?: Uploadable;
 
   /**
-   * The ID of the model to use for generating audio
+   * The ID of the model to use for generating audio. Any model other than the first
+   * `"sonic"` model is supported.
    */
   model_id?: string;
 
@@ -77,7 +76,7 @@ export interface InfillCreateParams {
   /**
    * The sample rate of the output audio
    */
-  'output_format[sample_rate]'?: number;
+  'output_format[sample_rate]'?: 8000 | 16000 | 22050 | 24000 | 44100 | 48000;
 
   right_audio?: Uploadable;
 

package/src/resources/pronunciation-dicts.ts

@@ -55,26 +55,6 @@ export class PronunciationDicts extends APIResource {
       headers: buildHeaders([{ Accept: '*/*' }, options?.headers]),
     });
   }
-
-  /**
-   * Pin a pronunciation dictionary for the authenticated user
-   */
-  pin(id: string, options?: RequestOptions): APIPromise<void> {
-    return this._client.post(path`/pronunciation-dicts/${id}/pin`, {
-      ...options,
-      headers: buildHeaders([{ Accept: '*/*' }, options?.headers]),
-    });
-  }
-
-  /**
-   * Unpin a pronunciation dictionary for the authenticated user
-   */
-  unpin(id: string, options?: RequestOptions): APIPromise<void> {
-    return this._client.post(path`/pronunciation-dicts/${id}/unpin`, {
-      ...options,
-      headers: buildHeaders([{ Accept: '*/*' }, options?.headers]),
-    });
-  }
 }
 
 export type PronunciationDictsCursorIDPage = CursorIDPage<PronunciationDict>;