@breeze.blue/sdk 0.3.0 → 0.4.0

package/CHANGELOG.md

@@ -1,5 +1,24 @@
 # Changelog
 
+## 0.4.0
+
+- Added `client.textToSpeech.aiRewrite(...)` for instruction-only
+  text-to-speech AI Rewrite.
+- Added `client.voices.random()` for fetching one visible voice to use as a
+  text-to-speech reference voice.
+- Added account usage filters for API key, status class, client type, and date
+  range, plus usage log fields for API key attribution, request duration, first
+  audio chunk latency, and client telemetry.
+- Improved typed error mapping for generation timeouts and fallback 429 rate
+  limit responses.
+
+## 0.3.1
+
+- Added SDK-side validation for `voices.createClonePreview(...)` and
+  `voices.edit(...)` reference audio inputs so `file` and single-item `files`
+  forms are accepted, while missing or multiple clone samples are rejected
+  before sending a request.
+
 ## 0.3.0
 
 - Added async text-to-speech helpers: `client.textToSpeech.createJob(...)`,

package/README.md

@@ -73,6 +73,11 @@ const audio = await client.textToSpeech.convert("voc_...", {
 const audioStream = await client.textToSpeech.stream("voc_...", {
   text: "Stream this line.",
 });
+
+const rewritten = await client.textToSpeech.aiRewrite({
+  instruction: "Calm, warm, bedtime narration.",
+  languageCode: "en",
+});
 ```
 
 Use async text-to-speech for long text, reference-heavy voices, or batch
@@ -135,6 +140,9 @@ const firstVoiceId = voices.voices[0].voiceId;
 
 const voice = await client.voices.get(firstVoiceId);
 const settings = await client.voices.getSettings(firstVoiceId);
+
+const randomVoice = await client.voices.random();
+console.log(randomVoice.voiceId, randomVoice.name);
 ```
 
 Breeze voice creation is always two steps: produce a **preview**, let the
@@ -163,6 +171,8 @@ const design = await client.voices.createDesignPreview({
 generatedVoiceId = design.previews[0].generatedVoiceId;
 ```
 
+`files` is also accepted with exactly one item.
+
 Stream the preview so the user can audition it, then save the one they
 pick:
 
@@ -190,6 +200,10 @@ await client.voices.delete(saved.voiceId);
 const models = await client.models.list();
 const balance = await client.account.balance();
 const usage = await client.account.usage({ days: 7 });
+const keyUsage = await client.account.usage({
+  apiKeyId: "key_01hprod",
+  clientType: "sdk",
+});
 
 const history = await client.history.list({ pageSize: 10 });
 const item = await client.history.get(history.history[0].historyItemId);

package/dist/client.d.ts

@@ -1,5 +1,5 @@
 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";
+import type { AudioRequestOptions, AsyncTextToSpeechJob, Balance, BreezeBlueClientOptions, GenericStatus, GenerationJob, HistoryItem, HistoryList, HistoryListParams, Model, RequestOptions, SaveVoiceRequest, StreamTextToSpeechOptions, TextToSpeechRequest, TtsAiRewriteRequest, TtsAiRewriteResponse, Usage, UsageParams, Voice, VoiceClonePreview, VoiceClonePreviewRequest, VoiceDesignRequest, VoiceDesignResponse, VoiceEditRequest, VoiceList, VoiceSearchParams, VoiceSettings } from "./types.js";
 export declare class BreezeBlueClient {
     readonly apiKey: string;
     readonly baseUrl: string;
@@ -24,6 +24,7 @@ declare class TextToSpeechResource {
     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>;
+    aiRewrite(request: TtsAiRewriteRequest, options?: RequestOptions): Promise<TtsAiRewriteResponse>;
 }
 declare class GenerationJobsResource {
     private readonly client;
@@ -44,6 +45,7 @@ declare class VoicesResource {
     constructor(client: BreezeBlueClient);
     search(params?: VoiceSearchParams, options?: RequestOptions): Promise<VoiceList>;
     get(voiceId: string, options?: RequestOptions): Promise<Voice>;
+    random(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>>;

package/dist/client.js

@@ -96,6 +96,9 @@ class TextToSpeechResource {
             enableLogging: options.enableLogging,
         }, request, options);
     }
+    aiRewrite(request, options) {
+        return this.client.requestJson("POST", "/v1/text-to-speech/ai-rewrite", undefined, request, options);
+    }
 }
 class GenerationJobsResource {
     client;
@@ -129,6 +132,9 @@ class VoicesResource {
     get(voiceId, options) {
         return this.client.requestJson("GET", `/v1/voices/${encodeURIComponent(voiceId)}`, undefined, undefined, options);
     }
+    random(options) {
+        return this.client.requestJson("GET", "/v1/voices/random", undefined, undefined, options);
+    }
     edit(voiceId, request, options) {
         return this.client.requestJson("PATCH", `/v1/voices/${encodeURIComponent(voiceId)}`, undefined, voiceEditForm(request), options);
     }
@@ -279,7 +285,7 @@ function clonePreviewForm(request) {
     appendOptional(form, "labels", request.labels ? JSON.stringify(request.labels) : undefined);
     appendOptional(form, "text", request.text);
     appendOptional(form, "instructions", request.instructions);
-    for (const file of normalizeFiles(request.file, request.files)) {
+    for (const file of normalizeFiles(request.file, request.files, { required: true })) {
         appendFile(form, "files", file);
     }
     return form;
@@ -289,7 +295,7 @@ function voiceEditForm(request) {
     form.set("name", request.name);
     appendOptional(form, "description", request.description);
     appendOptional(form, "labels", request.labels ? JSON.stringify(request.labels) : undefined);
-    for (const file of normalizeFiles(request.file, request.files)) {
+    for (const file of normalizeFiles(request.file, request.files, { required: false })) {
         appendFile(form, "files", file);
     }
     return form;
@@ -299,10 +305,18 @@ function appendOptional(form, key, value) {
         return;
     form.set(key, String(value));
 }
-function normalizeFiles(file, files) {
-    if (files && files.length > 0)
-        return files;
-    return file === undefined ? [] : [file];
+function normalizeFiles(file, files, options) {
+    if (file !== undefined && files !== undefined) {
+        throw new BreezeBlueConfigurationError("Pass either file or files, not both.");
+    }
+    const selected = files !== undefined ? files : file === undefined ? [] : [file];
+    if (options.required && selected.length === 0) {
+        throw new BreezeBlueConfigurationError("Exactly one sample file is required.");
+    }
+    if (selected.length > 1) {
+        throw new BreezeBlueConfigurationError("Exactly one sample file is currently supported.");
+    }
+    return selected;
 }
 function appendFile(form, key, input) {
     const upload = isUploadFile(input) ? input : { data: input };

package/dist/errors.js

@@ -68,6 +68,7 @@ const codeErrorMap = new Map([
     ["UPSTREAM_BILLING_ERROR", BreezeBlueUpstreamError],
     ["UPSTREAM_GENERATION_ERROR", BreezeBlueUpstreamError],
     ["UPSTREAM_TIMEOUT", BreezeBlueUpstreamError],
+    ["GENERATION_TIMEOUT", BreezeBlueUpstreamError],
     ["UPSTREAM_GENERATION_SERVICE_ERROR", BreezeBlueUpstreamError],
     ["UPSTREAM_ASSET_STORAGE_ERROR", BreezeBlueUpstreamError],
     ["GENERATION_INVALID_RESPONSE", BreezeBlueUpstreamError],
@@ -141,6 +142,8 @@ function fallbackCode(status) {
         return "VALIDATION_ERROR";
     if (status === 425)
         return "GENERATION_NOT_READY";
+    if (status === 429)
+        return "RATE_LIMITED";
     if (status === 502)
         return "UPSTREAM_GENERATION_ERROR";
     if (status === 503)

package/dist/types.d.ts

@@ -46,6 +46,14 @@ export interface TextToSpeechRequest {
     applyTextNormalization?: string;
     applyLanguageTextNormalization?: boolean;
 }
+export interface TtsAiRewriteRequest {
+    instruction: string;
+    languageCode?: string | null;
+}
+export interface TtsAiRewriteResponse {
+    instruction: string;
+    languageCode: string;
+}
 export interface AsyncTextToSpeechJob {
     generationJobId: string;
     historyItemId: string;
@@ -192,6 +200,9 @@ export interface HistoryItem {
     requestId?: string | null;
     latencyMs?: number | null;
     httpStatus?: number | null;
+    billableUnits?: number | null;
+    cost?: number | null;
+    costMillicredits?: number | null;
     [key: string]: unknown;
 }
 export interface HistoryList {
@@ -244,15 +255,24 @@ export interface UsageItem {
     endpoint: string;
     method: string;
     status: number;
+    apiKeyId?: string | null;
+    apiKeyName?: string | null;
+    apiKeyPrefix?: string | null;
     model?: string | null;
     billableUnits?: number | null;
     cost?: number | null;
     costMillicredits?: number | null;
     latencyMs?: number | null;
+    durationMs?: number | null;
+    firstAudioChunkMs?: number | null;
+    requestDurationMs?: number | null;
     traceId?: string | null;
     requestId?: string | null;
     textCharacters?: number | null;
     actionCode?: string | null;
+    clientType?: string | null;
+    clientName?: string | null;
+    clientVersion?: string | null;
     createdAt?: string | null;
     [key: string]: unknown;
 }
@@ -270,6 +290,11 @@ export interface UsageParams {
     days?: number;
     search?: string;
     method?: string;
+    apiKeyId?: string;
+    statusClass?: "2xx" | "4xx" | "5xx" | "other" | string;
+    clientType?: "api" | "sdk" | "cli" | string;
+    from?: string;
+    to?: string;
     page?: number;
     pageSize?: number;
 }

package/dist/version.d.ts

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

package/dist/version.js

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

package/package.json

@@ -1,10 +1,10 @@
 {
   "name": "@breeze.blue/sdk",
-  "version": "0.3.0",
+  "version": "0.4.0",
   "description": "ESM-first TypeScript SDK for the Breeze Blue Developer API.",
   "license": "MIT",
   "author": "Breeze Blue <support@breeze.blue>",
-  "homepage": "https://breeze.blue",
+  "homepage": "https://breezeblue.ai",
   "keywords": [
     "audio",
     "breeze",
@@ -45,8 +45,8 @@
     "typescript": "^5.9.3"
   },
   "scripts": {
-    "build": "pnpm exec tsc -p tsconfig.json",
-    "typecheck": "pnpm exec tsc -p tsconfig.json --noEmit",
+    "build": "node node_modules/typescript/bin/tsc -p tsconfig.json",
+    "typecheck": "node node_modules/typescript/bin/tsc -p tsconfig.json --noEmit",
     "test": "pnpm run build && node --test ./test/*.test.js"
   }
 }