kugelaudio 0.4.0 → 0.5.0

package/CHANGELOG.md

@@ -1,3 +1,14 @@
+## [kugelaudio-v0.5.0](https://github.com/Kugelaudio/KugelAudio/compare/js-sdk-v0.4.0...js-sdk-v0.5.0) (2026-05-21)
+
+### Features
+
+* **ingress,sdks:** public API for custom word dictionaries (KUG-765) ([#875](https://github.com/Kugelaudio/KugelAudio/issues/875)) ([9988924](https://github.com/Kugelaudio/KugelAudio/commit/99889244997d1cb4dba9714e2633d84ace9852a3))
+* **sdk:** add NotFoundError for unknown resources (KUG-423) ([#872](https://github.com/Kugelaudio/KugelAudio/issues/872)) ([d613b0f](https://github.com/Kugelaudio/KugelAudio/commit/d613b0fa1314c9e9e1f2af924652d94014626ddc))
+
+### Reverts
+
+* undo accidental merge of PR [#723](https://github.com/Kugelaudio/KugelAudio/issues/723) ([e8eff2e](https://github.com/Kugelaudio/KugelAudio/commit/e8eff2e86c76b893262782ff6ae763ed405396ce))
+
 ## [kugelaudio-v0.4.0](https://github.com/Kugelaudio/KugelAudio/compare/js-sdk-v0.3.0...js-sdk-v0.4.0) (2026-05-14)
 
 ### Features

package/README.md

@@ -274,6 +274,39 @@ onChunk: (chunk) => {
 }
 ```
 
+## LLM Integration: Streaming Text Input
+
+For real-time TTS when streaming text from an LLM (GPT-4, Claude, etc.),
+use a `StreamingSession`. Forward LLM tokens directly to `session.send()`
+**without** `flush=true` — the server accumulates them and starts
+generation at natural sentence boundaries. `session.close()` triggers a
+single final flush at the end of the assistant turn.
+
+```typescript
+const session = client.tts.streamingSession(
+  { voiceId: 123, modelId: 'kugel-1-turbo', language: 'en' },
+  { onChunk: (chunk) => playAudio(chunk.audio) },
+);
+await session.connect();
+
+// Forward every LLM token directly. No flush per token —
+// the server's text buffer chunks at sentence boundaries.
+for await (const token of llmTokenStream) {
+  session.send(token);
+}
+
+// Triggers the server-side final flush of any trailing text,
+// streams the resulting audio through onChunk, then closes the WS.
+await session.close();
+```
+
+> ⚠️ **Do not call `session.send(text, true)` (`flush=true`) between
+> sentences or words.** Each explicit flush is a separate TTS request
+> that pays the full model time-to-first-audio (TTFA) again and produces
+> an audible gap. See [Streaming best practices](https://docs.kugelaudio.com/streaming-best-practices)
+> for the full rationale, chunk-size ordering, and ElevenLabs migration
+> notes.
+
 ## Text Normalization
 
 Text normalization converts numbers, dates, times, and other non-verbal text into spoken words. For example:
@@ -331,6 +364,7 @@ import {
   RateLimitError,
   InsufficientCreditsError,
   ValidationError,
+  NotFoundError,
   ConnectionError,
 } from 'kugelaudio';
 
@@ -345,6 +379,8 @@ try {
     console.error('Not enough credits, please top up');
   } else if (error instanceof ValidationError) {
     console.error(`Invalid request: ${error.message}`);
+  } else if (error instanceof NotFoundError) {
+    console.error(`Resource not found (e.g. unknown voiceId): ${error.message}`);
   } else if (error instanceof ConnectionError) {
     console.error('Failed to connect to server');
   } else if (error instanceof KugelAudioError) {

package/dist/index.d.mts

@@ -54,6 +54,84 @@ interface VoiceListResponse {
  * Voice quality levels.
  */
 type VoiceQuality = 'low' | 'mid' | 'high';
+/**
+ * A per-project pronunciation dictionary.
+ */
+interface Dictionary {
+    id: number;
+    projectId: number;
+    name: string;
+    description?: string;
+    language?: string;
+    isActive: boolean;
+    createdAt: string;
+    updatedAt: string;
+}
+/**
+ * A single word → replacement / IPA mapping within a dictionary.
+ */
+interface DictionaryEntry {
+    id: number;
+    dictionaryId: number;
+    word: string;
+    replacement: string;
+    ipa?: string;
+    caseSensitive: boolean;
+    createdAt: string;
+    updatedAt: string;
+}
+/**
+ * Paginated response from listing entries.
+ */
+interface DictionaryEntryListResponse {
+    entries: DictionaryEntry[];
+    total: number;
+    limit: number;
+    offset: number;
+}
+/**
+ * Counts returned by `entries.replaceAll`.
+ */
+interface BulkReplaceResult {
+    upserted: number;
+    deleted: number;
+    total: number;
+}
+/**
+ * Options for creating a dictionary.
+ */
+interface CreateDictionaryOptions {
+    name: string;
+    description?: string;
+    language?: string;
+}
+/**
+ * Options for updating a dictionary. Only provided fields are changed.
+ */
+interface UpdateDictionaryOptions {
+    name?: string;
+    description?: string;
+    language?: string;
+    isActive?: boolean;
+}
+/**
+ * Payload for creating or replacing a single entry.
+ */
+interface DictionaryEntryInput {
+    word: string;
+    replacement: string;
+    ipa?: string;
+    caseSensitive?: boolean;
+}
+/**
+ * Options for updating an entry.
+ */
+interface UpdateDictionaryEntryOptions {
+    word?: string;
+    replacement?: string;
+    ipa?: string;
+    caseSensitive?: boolean;
+}
 /**
  * Extended voice information returned by voice management endpoints.
  */
@@ -482,6 +560,92 @@ interface MultiContextCallbacks {
     onError?: (error: Error, contextId?: string) => void;
 }
 
+/**
+ * Resources for managing per-project custom word dictionaries.
+ *
+ * @example
+ * ```typescript
+ * const dict = await client.dictionaries.create({ name: 'Brand names' });
+ * await client.dictionaries.entries.add(dict.id, {
+ *   word: 'Postgres',
+ *   replacement: 'post-gres',
+ * });
+ *
+ * // Sync from an external source — atomic, idempotent
+ * await client.dictionaries.entries.replaceAll(dict.id, [
+ *   { word: 'Postgres', replacement: 'post-gres' },
+ *   { word: 'Kubernetes', replacement: 'koo-ber-net-eez' },
+ * ]);
+ * ```
+ */
+
+/**
+ * Resource for entries within a single dictionary.
+ * Access via ``client.dictionaries.entries`` and pass ``dictionaryId``
+ * to each call.
+ */
+declare class DictionaryEntriesResource {
+    private client;
+    constructor(client: KugelAudio);
+    /** List entries with optional search + pagination. */
+    list(dictionaryId: number, options?: {
+        search?: string;
+        limit?: number;
+        offset?: number;
+        projectId?: number;
+    }): Promise<DictionaryEntryListResponse>;
+    /** Add a single entry to a dictionary. */
+    add(dictionaryId: number, entry: DictionaryEntryInput, options?: {
+        projectId?: number;
+    }): Promise<DictionaryEntry>;
+    /** Update an existing entry. */
+    update(dictionaryId: number, entryId: number, updates: UpdateDictionaryEntryOptions, options?: {
+        projectId?: number;
+    }): Promise<DictionaryEntry>;
+    /** Delete a single entry. */
+    delete(dictionaryId: number, entryId: number, options?: {
+        projectId?: number;
+    }): Promise<void>;
+    /**
+     * Replace every entry in the dictionary atomically.
+     *
+     * Each item must have ``word`` and ``replacement``; existing entries
+     * whose ``word`` is not in the supplied list are deleted. Idempotent.
+     */
+    replaceAll(dictionaryId: number, entries: DictionaryEntryInput[], options?: {
+        projectId?: number;
+    }): Promise<BulkReplaceResult>;
+}
+/**
+ * Resource for managing per-project custom dictionaries.
+ */
+declare class DictionariesResource {
+    private client;
+    /** Per-entry operations within a dictionary. */
+    readonly entries: DictionaryEntriesResource;
+    constructor(client: KugelAudio);
+    /** List every dictionary in the caller's project. */
+    list(options?: {
+        projectId?: number;
+    }): Promise<Dictionary[]>;
+    /** Create a new dictionary scoped to the caller's project. */
+    create(body: CreateDictionaryOptions, options?: {
+        projectId?: number;
+    }): Promise<Dictionary>;
+    /** Fetch a single dictionary. */
+    get(dictionaryId: number, options?: {
+        projectId?: number;
+    }): Promise<Dictionary>;
+    /** Update name / description / language / isActive. */
+    update(dictionaryId: number, updates: UpdateDictionaryOptions, options?: {
+        projectId?: number;
+    }): Promise<Dictionary>;
+    /** Delete a dictionary (cascades to its entries). */
+    delete(dictionaryId: number, options?: {
+        projectId?: number;
+    }): Promise<void>;
+}
+
 /**
  * Models resource for listing TTS models.
  */
@@ -929,6 +1093,8 @@ declare class KugelAudio {
     readonly models: ModelsResource;
     /** Voices resource */
     readonly voices: VoicesResource;
+    /** Custom dictionaries resource */
+    readonly dictionaries: DictionariesResource;
     /** TTS resource */
     readonly tts: TTSResource;
     constructor(options: KugelAudioOptions);
@@ -1005,7 +1171,7 @@ declare class KugelAudio {
  *
  * All SDK errors inherit from {@link KugelAudioError}. Specific subclasses
  * map to the server's `error_code` field (see the server-side `ErrorCode`
- * enum at `tts/src/serving/deployments/errors.py`) so callers can
+ * enum at `engine/src/serving/deployments/errors.py`) so callers can
  * `instanceof AuthenticationError` without matching on message text.
  */
 declare const ErrorCodes: {
@@ -1073,6 +1239,17 @@ declare class ValidationError extends KugelAudioError {
 declare class ConnectionError extends KugelAudioError {
     constructor(message: string, options?: KugelAudioErrorOptions);
 }
+/**
+ * A referenced resource doesn't exist or isn't visible to the caller.
+ *
+ * Surfaced when the server returns HTTP 404 with `error_code = NOT_FOUND` —
+ * e.g. an unknown `voiceId`, a voice that belongs to another org, or a
+ * deleted resource. Distinct from {@link ValidationError} (malformed
+ * request) so callers can show "not found" UX without parsing messages.
+ */
+declare class NotFoundError extends KugelAudioError {
+    constructor(message?: string, options?: KugelAudioErrorOptions);
+}
 interface HttpResponseLike {
     status: number;
     headers: {
@@ -1133,4 +1310,4 @@ declare function createWavFile(audio: ArrayBuffer, sampleRate: number): ArrayBuf
  */
 declare function createWavBlob(audio: ArrayBuffer, sampleRate: number): Blob;
 
-export { type AudioChunk, type AudioResponse, AuthenticationError, ConnectionError, type ContextVoiceSettings, type CreateVoiceOptions, type ErrorCode, ErrorCodes, type GenerateOptions, type GenerationStats, InsufficientCreditsError, KugelAudio, KugelAudioError, type KugelAudioErrorOptions, type KugelAudioOptions, type Model, type MultiContextAudioChunk, type MultiContextCallbacks, type MultiContextConfig, RateLimitError, type Region, type StreamCallbacks, type StreamConfig, type StreamingSessionCallbacks, type UpdateVoiceOptions, ValidationError, type Voice, type VoiceAge, type VoiceCategory, type VoiceDetail, type VoiceListResponse, type VoiceQuality, type VoiceReference, type VoiceSex, type WordTimestamp, WsCloseCodes, base64ToArrayBuffer, classifyHttpError, classifyWsClose, classifyWsFrame, classifyWsHandshakeError, createWavBlob, createWavFile, decodePCM16 };
+export { type AudioChunk, type AudioResponse, AuthenticationError, type BulkReplaceResult, ConnectionError, type ContextVoiceSettings, type CreateDictionaryOptions, type CreateVoiceOptions, DictionariesResource, type Dictionary, DictionaryEntriesResource, type DictionaryEntry, type DictionaryEntryInput, type DictionaryEntryListResponse, type ErrorCode, ErrorCodes, type GenerateOptions, type GenerationStats, InsufficientCreditsError, KugelAudio, KugelAudioError, type KugelAudioErrorOptions, type KugelAudioOptions, type Model, type MultiContextAudioChunk, type MultiContextCallbacks, type MultiContextConfig, NotFoundError, RateLimitError, type Region, type StreamCallbacks, type StreamConfig, type StreamingSessionCallbacks, type UpdateDictionaryEntryOptions, type UpdateDictionaryOptions, type UpdateVoiceOptions, ValidationError, type Voice, type VoiceAge, type VoiceCategory, type VoiceDetail, type VoiceListResponse, type VoiceQuality, type VoiceReference, type VoiceSex, type WordTimestamp, WsCloseCodes, base64ToArrayBuffer, classifyHttpError, classifyWsClose, classifyWsFrame, classifyWsHandshakeError, createWavBlob, createWavFile, decodePCM16 };

package/dist/index.d.ts

@@ -54,6 +54,84 @@ interface VoiceListResponse {
  * Voice quality levels.
  */
 type VoiceQuality = 'low' | 'mid' | 'high';
+/**
+ * A per-project pronunciation dictionary.
+ */
+interface Dictionary {
+    id: number;
+    projectId: number;
+    name: string;
+    description?: string;
+    language?: string;
+    isActive: boolean;
+    createdAt: string;
+    updatedAt: string;
+}
+/**
+ * A single word → replacement / IPA mapping within a dictionary.
+ */
+interface DictionaryEntry {
+    id: number;
+    dictionaryId: number;
+    word: string;
+    replacement: string;
+    ipa?: string;
+    caseSensitive: boolean;
+    createdAt: string;
+    updatedAt: string;
+}
+/**
+ * Paginated response from listing entries.
+ */
+interface DictionaryEntryListResponse {
+    entries: DictionaryEntry[];
+    total: number;
+    limit: number;
+    offset: number;
+}
+/**
+ * Counts returned by `entries.replaceAll`.
+ */
+interface BulkReplaceResult {
+    upserted: number;
+    deleted: number;
+    total: number;
+}
+/**
+ * Options for creating a dictionary.
+ */
+interface CreateDictionaryOptions {
+    name: string;
+    description?: string;
+    language?: string;
+}
+/**
+ * Options for updating a dictionary. Only provided fields are changed.
+ */
+interface UpdateDictionaryOptions {
+    name?: string;
+    description?: string;
+    language?: string;
+    isActive?: boolean;
+}
+/**
+ * Payload for creating or replacing a single entry.
+ */
+interface DictionaryEntryInput {
+    word: string;
+    replacement: string;
+    ipa?: string;
+    caseSensitive?: boolean;
+}
+/**
+ * Options for updating an entry.
+ */
+interface UpdateDictionaryEntryOptions {
+    word?: string;
+    replacement?: string;
+    ipa?: string;
+    caseSensitive?: boolean;
+}
 /**
  * Extended voice information returned by voice management endpoints.
  */
@@ -482,6 +560,92 @@ interface MultiContextCallbacks {
     onError?: (error: Error, contextId?: string) => void;
 }
 
+/**
+ * Resources for managing per-project custom word dictionaries.
+ *
+ * @example
+ * ```typescript
+ * const dict = await client.dictionaries.create({ name: 'Brand names' });
+ * await client.dictionaries.entries.add(dict.id, {
+ *   word: 'Postgres',
+ *   replacement: 'post-gres',
+ * });
+ *
+ * // Sync from an external source — atomic, idempotent
+ * await client.dictionaries.entries.replaceAll(dict.id, [
+ *   { word: 'Postgres', replacement: 'post-gres' },
+ *   { word: 'Kubernetes', replacement: 'koo-ber-net-eez' },
+ * ]);
+ * ```
+ */
+
+/**
+ * Resource for entries within a single dictionary.
+ * Access via ``client.dictionaries.entries`` and pass ``dictionaryId``
+ * to each call.
+ */
+declare class DictionaryEntriesResource {
+    private client;
+    constructor(client: KugelAudio);
+    /** List entries with optional search + pagination. */
+    list(dictionaryId: number, options?: {
+        search?: string;
+        limit?: number;
+        offset?: number;
+        projectId?: number;
+    }): Promise<DictionaryEntryListResponse>;
+    /** Add a single entry to a dictionary. */
+    add(dictionaryId: number, entry: DictionaryEntryInput, options?: {
+        projectId?: number;
+    }): Promise<DictionaryEntry>;
+    /** Update an existing entry. */
+    update(dictionaryId: number, entryId: number, updates: UpdateDictionaryEntryOptions, options?: {
+        projectId?: number;
+    }): Promise<DictionaryEntry>;
+    /** Delete a single entry. */
+    delete(dictionaryId: number, entryId: number, options?: {
+        projectId?: number;
+    }): Promise<void>;
+    /**
+     * Replace every entry in the dictionary atomically.
+     *
+     * Each item must have ``word`` and ``replacement``; existing entries
+     * whose ``word`` is not in the supplied list are deleted. Idempotent.
+     */
+    replaceAll(dictionaryId: number, entries: DictionaryEntryInput[], options?: {
+        projectId?: number;
+    }): Promise<BulkReplaceResult>;
+}
+/**
+ * Resource for managing per-project custom dictionaries.
+ */
+declare class DictionariesResource {
+    private client;
+    /** Per-entry operations within a dictionary. */
+    readonly entries: DictionaryEntriesResource;
+    constructor(client: KugelAudio);
+    /** List every dictionary in the caller's project. */
+    list(options?: {
+        projectId?: number;
+    }): Promise<Dictionary[]>;
+    /** Create a new dictionary scoped to the caller's project. */
+    create(body: CreateDictionaryOptions, options?: {
+        projectId?: number;
+    }): Promise<Dictionary>;
+    /** Fetch a single dictionary. */
+    get(dictionaryId: number, options?: {
+        projectId?: number;
+    }): Promise<Dictionary>;
+    /** Update name / description / language / isActive. */
+    update(dictionaryId: number, updates: UpdateDictionaryOptions, options?: {
+        projectId?: number;
+    }): Promise<Dictionary>;
+    /** Delete a dictionary (cascades to its entries). */
+    delete(dictionaryId: number, options?: {
+        projectId?: number;
+    }): Promise<void>;
+}
+
 /**
  * Models resource for listing TTS models.
  */
@@ -929,6 +1093,8 @@ declare class KugelAudio {
     readonly models: ModelsResource;
     /** Voices resource */
     readonly voices: VoicesResource;
+    /** Custom dictionaries resource */
+    readonly dictionaries: DictionariesResource;
     /** TTS resource */
     readonly tts: TTSResource;
     constructor(options: KugelAudioOptions);
@@ -1005,7 +1171,7 @@ declare class KugelAudio {
  *
  * All SDK errors inherit from {@link KugelAudioError}. Specific subclasses
  * map to the server's `error_code` field (see the server-side `ErrorCode`
- * enum at `tts/src/serving/deployments/errors.py`) so callers can
+ * enum at `engine/src/serving/deployments/errors.py`) so callers can
  * `instanceof AuthenticationError` without matching on message text.
  */
 declare const ErrorCodes: {
@@ -1073,6 +1239,17 @@ declare class ValidationError extends KugelAudioError {
 declare class ConnectionError extends KugelAudioError {
     constructor(message: string, options?: KugelAudioErrorOptions);
 }
+/**
+ * A referenced resource doesn't exist or isn't visible to the caller.
+ *
+ * Surfaced when the server returns HTTP 404 with `error_code = NOT_FOUND` —
+ * e.g. an unknown `voiceId`, a voice that belongs to another org, or a
+ * deleted resource. Distinct from {@link ValidationError} (malformed
+ * request) so callers can show "not found" UX without parsing messages.
+ */
+declare class NotFoundError extends KugelAudioError {
+    constructor(message?: string, options?: KugelAudioErrorOptions);
+}
 interface HttpResponseLike {
     status: number;
     headers: {
@@ -1133,4 +1310,4 @@ declare function createWavFile(audio: ArrayBuffer, sampleRate: number): ArrayBuf
  */
 declare function createWavBlob(audio: ArrayBuffer, sampleRate: number): Blob;
 
-export { type AudioChunk, type AudioResponse, AuthenticationError, ConnectionError, type ContextVoiceSettings, type CreateVoiceOptions, type ErrorCode, ErrorCodes, type GenerateOptions, type GenerationStats, InsufficientCreditsError, KugelAudio, KugelAudioError, type KugelAudioErrorOptions, type KugelAudioOptions, type Model, type MultiContextAudioChunk, type MultiContextCallbacks, type MultiContextConfig, RateLimitError, type Region, type StreamCallbacks, type StreamConfig, type StreamingSessionCallbacks, type UpdateVoiceOptions, ValidationError, type Voice, type VoiceAge, type VoiceCategory, type VoiceDetail, type VoiceListResponse, type VoiceQuality, type VoiceReference, type VoiceSex, type WordTimestamp, WsCloseCodes, base64ToArrayBuffer, classifyHttpError, classifyWsClose, classifyWsFrame, classifyWsHandshakeError, createWavBlob, createWavFile, decodePCM16 };
+export { type AudioChunk, type AudioResponse, AuthenticationError, type BulkReplaceResult, ConnectionError, type ContextVoiceSettings, type CreateDictionaryOptions, type CreateVoiceOptions, DictionariesResource, type Dictionary, DictionaryEntriesResource, type DictionaryEntry, type DictionaryEntryInput, type DictionaryEntryListResponse, type ErrorCode, ErrorCodes, type GenerateOptions, type GenerationStats, InsufficientCreditsError, KugelAudio, KugelAudioError, type KugelAudioErrorOptions, type KugelAudioOptions, type Model, type MultiContextAudioChunk, type MultiContextCallbacks, type MultiContextConfig, NotFoundError, RateLimitError, type Region, type StreamCallbacks, type StreamConfig, type StreamingSessionCallbacks, type UpdateDictionaryEntryOptions, type UpdateDictionaryOptions, type UpdateVoiceOptions, ValidationError, type Voice, type VoiceAge, type VoiceCategory, type VoiceDetail, type VoiceListResponse, type VoiceQuality, type VoiceReference, type VoiceSex, type WordTimestamp, WsCloseCodes, base64ToArrayBuffer, classifyHttpError, classifyWsClose, classifyWsFrame, classifyWsHandshakeError, createWavBlob, createWavFile, decodePCM16 };