@breeze.blue/sdk 0.3.0

package/CHANGELOG.md

@@ -0,0 +1,53 @@
+# Changelog
+
+## 0.3.0
+
+- Added async text-to-speech helpers: `client.textToSpeech.createJob(...)`,
+  `client.generationJobs.get(...)`, and
+  `client.generationJobs.downloadAudio(...)` for long text, reference-heavy
+  voices, and batch production workflows.
+- Added `BreezeBlueGenerationNotReadyError` for active async job audio
+  downloads, with `retryAfter` parsed from the `Retry-After` response header.
+
+## 0.2.1
+
+- Fixed README text-to-speech examples to omit the optional model selector unless using a value returned by `models.list()`.
+- Fixed the README clone preview example to load `sample.wav` directly instead of referencing an undefined `audioBytes` variable.
+
+## 0.2.0
+
+- Updated voice preview helpers to use the clearer `/v1/voice-previews/...` API paths by default while keeping the same `client.voices.*` method names.
+- Updated voice edit and settings helpers to use REST-style `PATCH /v1/voices/{voiceId}` and `PATCH /v1/voices/{voiceId}/settings` paths by default.
+
+## 0.1.3
+
+- Breaking: collapsed `client.voices.ivc.*` and `client.textToVoice.*` into `client.voices.*` and renamed methods around Breeze's actual two-step preview → save flow. Replacements:
+  - `voices.ivc.createPreview` → `voices.createClonePreview`
+  - `voices.ivc.edit` → `voices.edit`
+  - `voices.ivc.settings` → `voices.getSettings`
+  - `voices.ivc.delete` → `voices.delete`
+  - `textToVoice.design` → `voices.createDesignPreview`
+  - `textToVoice.create` → `voices.savePreview`
+  - `textToVoice.streamPreview` → `voices.streamPreview`
+- Removed the `client.textToVoice` namespace and the internal `voices.ivc` proxy. `voices.editSettings` is unchanged.
+
+## 0.1.2
+
+- Breaking: all request and response field names are now camelCase (e.g. `modelId`, `voiceId`, `voiceSettings`, `historyItemId`). The SDK transparently translates to the snake_case HTTP wire format on send and from snake_case on receive. `labels: Record<string, string>` is preserved verbatim.
+- Removed remaining ElevenLabs-positioning copy from the README and package keywords. Quickstart and reference examples use the published packages only.
+
+## 0.1.1
+
+- Rewrote the npm package README for external developers.
+- Removed internal monorepo release workflow notes from the packaged README.
+- Clarified setup, TTS, voice, history, account, Node audio helper, and error handling examples.
+- Removed JavaScript and declaration source maps from the published npm package.
+
+## 0.1.0
+
+Initial release.
+
+- ElevenLabs-compatible client surface for text-to-speech, voices, text-to-voice, history, models, and account APIs.
+- Typed errors for authentication, rate limiting, validation, billing, upstream, and service-unavailable failures.
+- Node audio playback helpers through the `@breeze.blue/sdk/node` subpath.
+- `xi-api-key` auth header and `x-breeze-sdk` telemetry header.

package/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 Breeze Blue
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

package/README.md

@@ -0,0 +1,228 @@
+# @breeze.blue/sdk
+
+ESM-first TypeScript SDK for the Breeze Blue Developer API. Covers
+text-to-speech, voice management, voice preview generation, history audio,
+models, and account usage.
+
+The root entrypoint is safe to import in Node, browser, and edge runtimes. Local
+audio playback helpers live in the Node-only `@breeze.blue/sdk/node` subpath.
+
+## Install
+
+```sh
+pnpm add @breeze.blue/sdk
+```
+
+or:
+
+```sh
+npm install @breeze.blue/sdk
+```
+
+## API Key
+
+Create an API key in the Breeze Blue Developer Console, then export it:
+
+```sh
+export BREEZE_API_KEY=brz_...
+```
+
+The SDK sends the key with the `xi-api-key` header. It also sends
+`x-breeze-sdk` for server-side observability.
+
+## Quickstart
+
+```ts
+import { BreezeBlueClient } from "@breeze.blue/sdk";
+import { save } from "@breeze.blue/sdk/node";
+
+const client = new BreezeBlueClient();
+
+const audio = await client.textToSpeech.convert(
+  "voc_...",
+  { text: "Hello from Breeze Blue." },
+  { outputFormat: "mp3" },
+);
+
+await save(audio, "hello.mp3");
+console.log(audio.contentType);
+console.log(audio.historyItemId);
+```
+
+`new BreezeBlueClient()` reads `BREEZE_API_KEY` by default and sends requests to
+`https://api.breeze.blue`. To point at another environment, pass `baseUrl` or
+set `BREEZE_BASE_URL`.
+
+```ts
+const client = new BreezeBlueClient({
+  apiKey: "brz_...",
+  baseUrl: "https://api.breeze.blue",
+  timeout: 120_000,
+});
+```
+
+Per-request options accept `timeout`, `signal`, and extra `headers`.
+
+## Text to Speech
+
+```ts
+const audio = await client.textToSpeech.convert("voc_...", {
+  text: "Render this line.",
+});
+
+const audioStream = await client.textToSpeech.stream("voc_...", {
+  text: "Stream this line.",
+});
+```
+
+Use async text-to-speech for long text, reference-heavy voices, or batch
+production where the caller should not hold an HTTP connection open:
+
+```ts
+const job = await client.textToSpeech.createJob(
+  "voc_...",
+  { text: "Render this longer script." },
+  { outputFormat: "mp3" },
+);
+
+const status = await client.generationJobs.get(job.generationJobId);
+if (status.status === "ready") {
+  const audio = await client.generationJobs.downloadAudio(job.generationJobId);
+  await save(audio, "async.mp3");
+}
+```
+
+If the job is still active, `downloadAudio(...)` rejects with
+`BreezeBlueGenerationNotReadyError`; read `error.retryAfter` before retrying.
+
+The API uses the default text-to-speech model when `modelId` is omitted. If
+you need to select a model explicitly, call `client.models.list()` and pass one
+of the returned `modelId` values.
+
+All field names follow TypeScript conventions (`modelId`, `voiceSettings`,
+`outputFormat`, `historyItemId`, ...). The SDK translates them to the
+snake_case HTTP wire format on send and translates JSON responses back to
+camelCase on receive.
+
+Audio responses expose convenient helpers:
+
+```ts
+await audio.arrayBuffer();
+await audio.bytes();
+await audio.blob();
+
+audio.contentType;
+audio.historyItemId;
+```
+
+Node playback helpers:
+
+```ts
+import { play, save, stream } from "@breeze.blue/sdk/node";
+
+await play(audio);        // ffplay, with macOS afplay fallback
+await save(audio, "x.mp3");
+await stream(audioStream); // mpv
+```
+
+## Voices
+
+Browse existing voices and inspect a single voice:
+
+```ts
+const voices = await client.voices.search({ search: "narrator" });
+const firstVoiceId = voices.voices[0].voiceId;
+
+const voice = await client.voices.get(firstVoiceId);
+const settings = await client.voices.getSettings(firstVoiceId);
+```
+
+Breeze voice creation is always two steps: produce a **preview**, let the
+user accept it, then **save the preview** as a real voice. Two ways to
+produce a preview:
+
+```ts
+import { readFile } from "node:fs/promises";
+
+// Option A — clone preview from an audio sample
+const clonePreview = await client.voices.createClonePreview({
+  name: "Demo voice",
+  file: {
+    data: await readFile("sample.wav"),
+    filename: "sample.wav",
+    contentType: "audio/wav",
+  },
+  text: "This is a short preview script.",
+});
+let generatedVoiceId = clonePreview.generatedVoiceId;
+
+// Option B — design preview from a text description (no audio)
+const design = await client.voices.createDesignPreview({
+  voiceDescription: "Warm documentary narrator with clear articulation.",
+});
+generatedVoiceId = design.previews[0].generatedVoiceId;
+```
+
+Stream the preview so the user can audition it, then save the one they
+pick:
+
+```ts
+const audio = await client.voices.streamPreview(generatedVoiceId);
+await save(audio, "preview.mp3");
+
+const saved = await client.voices.savePreview({
+  generatedVoiceId,
+  voiceName: "Documentary narrator",
+});
+```
+
+Edit, tune settings, or delete a saved voice:
+
+```ts
+await client.voices.edit(saved.voiceId, { name: "Renamed narrator" });
+await client.voices.editSettings(saved.voiceId, { guidanceScale: 1.2 });
+await client.voices.delete(saved.voiceId);
+```
+
+## History, Models, and Account
+
+```ts
+const models = await client.models.list();
+const balance = await client.account.balance();
+const usage = await client.account.usage({ days: 7 });
+
+const history = await client.history.list({ pageSize: 10 });
+const item = await client.history.get(history.history[0].historyItemId);
+const audio = await client.history.downloadAudio(item.historyItemId);
+```
+
+## Errors
+
+API failures throw `BreezeBlueAPIError` subclasses:
+
+- `BreezeBlueAuthenticationError`
+- `BreezeBlueBadRequestError`
+- `BreezeBlueConflictError`
+- `BreezeBlueForbiddenError`
+- `BreezeBlueNotFoundError`
+- `BreezeBlueValidationError`
+- `BreezeBlueRateLimitError`
+- `BreezeBlueInsufficientCreditsError`
+- `BreezeBlueUpstreamError` for upstream generation/storage/model failures,
+  commonly 502/504
+- `BreezeBlueServiceUnavailableError` for capacity or service-configuration
+  failures, commonly 503
+
+```ts
+import { BreezeBlueClient, BreezeBlueRateLimitError } from "@breeze.blue/sdk";
+
+try {
+  await new BreezeBlueClient().models.list();
+} catch (error) {
+  if (error instanceof BreezeBlueRateLimitError) {
+    console.log(error.headers.get("retry-after"));
+  }
+}
+```
+
+Each API error exposes `status`, `code`, `detail`, `meta`, and `headers`.

package/dist/_transform.d.ts

@@ -0,0 +1,2 @@
+export declare function camelizeKeys<T = unknown>(value: unknown): T;
+export declare function snakeizeKeys<T = unknown>(value: unknown): T;

package/dist/_transform.js

@@ -0,0 +1,38 @@
+// Keys whose values are user-defined dictionaries; we transform the key itself
+// but never recurse into the value.
+const OPAQUE_VALUE_KEYS = new Set(["labels"]);
+function snakeToCamel(key) {
+    return key.replace(/_([a-z0-9])/g, (_, c) => c.toUpperCase());
+}
+function camelToSnake(key) {
+    return key.replace(/([a-z0-9])([A-Z])/g, "$1_$2").toLowerCase();
+}
+function isPlainObject(value) {
+    if (value === null || typeof value !== "object")
+        return false;
+    if (Array.isArray(value))
+        return false;
+    const proto = Object.getPrototypeOf(value);
+    return proto === Object.prototype || proto === null;
+}
+function transform(value, keyFn, opaqueKey) {
+    if (Array.isArray(value)) {
+        return value.map((item) => transform(item, keyFn, false));
+    }
+    if (isPlainObject(value)) {
+        if (opaqueKey)
+            return value;
+        const out = {};
+        for (const [k, v] of Object.entries(value)) {
+            out[keyFn(k)] = transform(v, keyFn, OPAQUE_VALUE_KEYS.has(k));
+        }
+        return out;
+    }
+    return value;
+}
+export function camelizeKeys(value) {
+    return transform(value, snakeToCamel, false);
+}
+export function snakeizeKeys(value) {
+    return transform(value, camelToSnake, false);
+}

package/dist/audio.d.ts

@@ -0,0 +1,49 @@
+export interface CommandAvailability {
+    has(command: string): boolean;
+}
+export interface PlaybackCommand {
+    command: string;
+    args: string[];
+    mode: "stdin" | "file";
+}
+export interface StreamPlaybackCommand {
+    command: string;
+    args: string[];
+}
+export interface AudioResponseOptions {
+    filename?: string | null;
+}
+export interface PlayOptions {
+    command?: string;
+    args?: string[];
+    availability?: CommandAvailability;
+    platform?: string;
+}
+export interface StreamOptions {
+    command?: string;
+    args?: string[];
+}
+export declare class AudioResponse {
+    #private;
+    readonly response: Response;
+    readonly contentType: string;
+    readonly historyItemId: string | null;
+    readonly filename: string | null;
+    constructor(response: Response, options?: AudioResponseOptions);
+    get headers(): Headers;
+    arrayBuffer(): Promise<ArrayBuffer>;
+    bytes(): Promise<Uint8Array>;
+    blob(): Promise<Blob>;
+    saveToFile(path: string): Promise<void>;
+    play(options?: PlayOptions): Promise<void>;
+    stream(options?: StreamOptions): Promise<void>;
+}
+export declare function save(audio: AudioResponse, path: string): Promise<void>;
+export declare function play(audio: AudioResponse, options?: PlayOptions): Promise<void>;
+export declare function stream(audio: AudioResponse, options?: StreamOptions): Promise<void>;
+export declare function selectAudioPlaybackCommand(params: {
+    availability: CommandAvailability;
+    platform: string;
+}): PlaybackCommand;
+export declare function selectStreamPlaybackCommand(): StreamPlaybackCommand;
+export declare function extensionForContentType(contentType: string): string;

package/dist/audio.js

@@ -0,0 +1,82 @@
+export class AudioResponse {
+    response;
+    contentType;
+    historyItemId;
+    filename;
+    #buffer = null;
+    constructor(response, options = {}) {
+        this.response = response;
+        this.contentType = response.headers.get("content-type")?.split(";", 1)[0].trim() || "application/octet-stream";
+        this.historyItemId = response.headers.get("history-item-id");
+        this.filename = options.filename ?? filenameFromContentDisposition(response.headers.get("content-disposition"));
+    }
+    get headers() {
+        return this.response.headers;
+    }
+    async arrayBuffer() {
+        if (this.#buffer === null) {
+            this.#buffer = await this.response.arrayBuffer();
+        }
+        return this.#buffer.slice(0);
+    }
+    async bytes() {
+        return new Uint8Array(await this.arrayBuffer());
+    }
+    async blob() {
+        return new Blob([await this.arrayBuffer()], { type: this.contentType });
+    }
+    async saveToFile(path) {
+        throw nodeHelperError(`save audio to ${path}`);
+    }
+    async play(options = {}) {
+        void options;
+        throw nodeHelperError("play audio");
+    }
+    async stream(options = {}) {
+        void options;
+        throw nodeHelperError("stream audio");
+    }
+}
+export function save(audio, path) {
+    return audio.saveToFile(path);
+}
+export function play(audio, options = {}) {
+    return audio.play(options);
+}
+export function stream(audio, options = {}) {
+    return audio.stream(options);
+}
+export function selectAudioPlaybackCommand(params) {
+    if (params.availability.has("ffplay")) {
+        return { command: "ffplay", args: ["-autoexit", "-nodisp", "-"], mode: "stdin" };
+    }
+    if (params.platform === "darwin" && params.availability.has("afplay")) {
+        return { command: "afplay", args: [], mode: "file" };
+    }
+    throw new Error("No supported audio player found. Install ffplay, or use afplay on macOS.");
+}
+export function selectStreamPlaybackCommand() {
+    return { command: "mpv", args: ["--no-terminal", "--really-quiet", "-"] };
+}
+function nodeHelperError(action) {
+    return new Error(`Use @breeze.blue/sdk/node to ${action} in Node.js runtimes.`);
+}
+function filenameFromContentDisposition(value) {
+    if (!value)
+        return null;
+    const match = /filename="?([^";]+)"?/i.exec(value);
+    return match?.[1] ?? null;
+}
+export function extensionForContentType(contentType) {
+    if (contentType.includes("mpeg"))
+        return ".mp3";
+    if (contentType.includes("wav"))
+        return ".wav";
+    if (contentType.includes("flac"))
+        return ".flac";
+    if (contentType.includes("aac"))
+        return ".aac";
+    if (contentType.includes("opus"))
+        return ".opus";
+    return ".bin";
+}

package/dist/client.d.ts

@@ -0,0 +1,87 @@
+import { AudioResponse } from "./audio.js";
+import type { AudioRequestOptions, AsyncTextToSpeechJob, Balance, BreezeBlueClientOptions, GenericStatus, GenerationJob, HistoryItem, HistoryList, HistoryListParams, Model, RequestOptions, SaveVoiceRequest, StreamTextToSpeechOptions, TextToSpeechRequest, Usage, UsageParams, Voice, VoiceClonePreview, VoiceClonePreviewRequest, VoiceDesignRequest, VoiceDesignResponse, VoiceEditRequest, VoiceList, VoiceSearchParams, VoiceSettings } from "./types.js";
+export declare class BreezeBlueClient {
+    readonly apiKey: string;
+    readonly baseUrl: string;
+    readonly fetch: typeof fetch;
+    readonly headers: HeadersInit | undefined;
+    readonly timeout: number | undefined;
+    readonly textToSpeech: TextToSpeechResource;
+    readonly generationJobs: GenerationJobsResource;
+    readonly voices: VoicesResource;
+    readonly history: HistoryResource;
+    readonly models: ModelsResource;
+    readonly account: AccountResource;
+    constructor(options?: BreezeBlueClientOptions);
+    requestJson<T>(method: string, path: string, params?: object, body?: unknown, options?: RequestOptions): Promise<T>;
+    requestAudio(method: string, path: string, params?: object, body?: unknown, options?: RequestOptions): Promise<AudioResponse>;
+    request(method: string, path: string, params?: object, body?: unknown, options?: RequestOptions): Promise<Response>;
+    private buildHeaders;
+}
+declare class TextToSpeechResource {
+    private readonly client;
+    constructor(client: BreezeBlueClient);
+    convert(voiceId: string, request: TextToSpeechRequest, options?: AudioRequestOptions): Promise<AudioResponse>;
+    createJob(voiceId: string, request: TextToSpeechRequest, options?: AudioRequestOptions): Promise<AsyncTextToSpeechJob>;
+    stream(voiceId: string, request: TextToSpeechRequest, options?: StreamTextToSpeechOptions): Promise<AudioResponse>;
+}
+declare class GenerationJobsResource {
+    private readonly client;
+    constructor(client: BreezeBlueClient);
+    get(generationJobId: string, options?: RequestOptions): Promise<GenerationJob>;
+    downloadAudio(generationJobId: string, options?: RequestOptions): Promise<AudioResponse>;
+}
+/**
+ * Voice CRUD plus the two-step preview → save flow for Breeze voices.
+ *
+ * Breeze's voice creation is always two steps: produce a preview
+ * (`createClonePreview` from an audio sample, or `createDesignPreview` from
+ * a text description), then persist it with `savePreview`. Preview generation
+ * never creates a saved voice until `savePreview` is called.
+ */
+declare class VoicesResource {
+    private readonly client;
+    constructor(client: BreezeBlueClient);
+    search(params?: VoiceSearchParams, options?: RequestOptions): Promise<VoiceList>;
+    get(voiceId: string, options?: RequestOptions): Promise<Voice>;
+    edit(voiceId: string, request: VoiceEditRequest, options?: RequestOptions): Promise<GenericStatus>;
+    delete(voiceId: string, options?: RequestOptions): Promise<GenericStatus>;
+    getSettings(voiceId: string, options?: RequestOptions): Promise<Required<VoiceSettings>>;
+    editSettings(voiceId: string, settings: VoiceSettings, options?: RequestOptions): Promise<Required<VoiceSettings>>;
+    /**
+     * Generate a clone preview from a single audio sample. Returns a
+     * `generatedVoiceId`; call {@link savePreview} after the user accepts
+     * the preview to persist it as a real voice.
+     */
+    createClonePreview(request: VoiceClonePreviewRequest, options?: RequestOptions): Promise<VoiceClonePreview>;
+    /**
+     * Design preview voices from a text prompt (no audio sample). Returns one
+     * or more previews; pass the chosen `generatedVoiceId` to
+     * {@link savePreview}.
+     */
+    createDesignPreview(request: VoiceDesignRequest, options?: AudioRequestOptions): Promise<VoiceDesignResponse>;
+    /** Stream the audio of a clone or design preview before saving. */
+    streamPreview(generatedVoiceId: string, options?: AudioRequestOptions): Promise<AudioResponse>;
+    /** Persist a clone or design preview as a real voice asset. */
+    savePreview(request: SaveVoiceRequest, options?: RequestOptions): Promise<Voice>;
+}
+declare class HistoryResource {
+    private readonly client;
+    constructor(client: BreezeBlueClient);
+    list(params?: HistoryListParams, options?: RequestOptions): Promise<HistoryList>;
+    get(historyItemId: string, options?: RequestOptions): Promise<HistoryItem>;
+    downloadAudio(historyItemId: string, options?: RequestOptions): Promise<AudioResponse>;
+    delete(historyItemId: string, options?: RequestOptions): Promise<GenericStatus>;
+}
+declare class ModelsResource {
+    private readonly client;
+    constructor(client: BreezeBlueClient);
+    list(options?: RequestOptions): Promise<Model[]>;
+}
+declare class AccountResource {
+    private readonly client;
+    constructor(client: BreezeBlueClient);
+    balance(options?: RequestOptions): Promise<Balance>;
+    usage(params?: UsageParams, options?: RequestOptions): Promise<Usage>;
+}
+export {};