kugelaudio 0.3.0 → 0.5.0

package/CHANGELOG.md

@@ -1,3 +1,24 @@
+## [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
+
+* **web:** bump kugelaudio SDK to ^0.3.0 to enable per-project dictionary ([#640](https://github.com/Kugelaudio/KugelAudio/issues/640)) ([f503372](https://github.com/Kugelaudio/KugelAudio/commit/f5033728b2febb00cea6b021da5b5309c2c9097f))
+
+### Bug Fixes
+
+* **python-sdk,js-sdk,java-sdk:** update regional endpoints ([#660](https://github.com/Kugelaudio/KugelAudio/issues/660)) ([b9a32c0](https://github.com/Kugelaudio/KugelAudio/commit/b9a32c09813c3e9de34a9d0a84ed0e024e1fe158))
+
 # Changelog
 
 All notable changes to the KugelAudio JavaScript/TypeScript SDK will be documented in this file.
@@ -5,6 +26,21 @@ All notable changes to the KugelAudio JavaScript/TypeScript SDK will be document
 The format is based on [Keep a Changelog](https://keepachangelog.com/en/1.0.0/),
 and this project adheres to [Semantic Versioning](https://semver.org/spec/v2.0.0.html).
 
+## [0.3.0](https://github.com/Kugelaudio/KugelAudio/compare/js-sdk-v0.2.3...js-sdk-v0.3.0) (2026-05-10)
+
+### Features
+
+* **temperature, projectId, speed** on `tts.stream` / `tts.generate` / multi-context. Required for per-project custom dictionary replacement on the website. ([#273](https://github.com/Kugelaudio/KugelAudio/pull/273))
+* **error classification:** unify across SDKs with actionable messages ([#315](https://github.com/Kugelaudio/KugelAudio/pull/315))
+* **multi-region routing** for all SDKs ([#227](https://github.com/Kugelaudio/KugelAudio/pull/227))
+
+### Bug Fixes
+
+* **streaming session close:** per-message-quiet timeout in `StreamingSession.close()` ([#528](https://github.com/Kugelaudio/KugelAudio/pull/528))
+* **multi-context:** remove redundant `is_final` signal from protocol ([#279](https://github.com/Kugelaudio/KugelAudio/pull/279))
+* **websocket:** keep alive across streaming sessions ([#253](https://github.com/Kugelaudio/KugelAudio/pull/253))
+* **release pipeline:** fix stale repo URLs blocking semantic-release ([#637](https://github.com/Kugelaudio/KugelAudio/pull/637))
+
 ## [0.1.3] - 2024-12-25
 
 ### Fixed

package/README.md

@@ -59,30 +59,28 @@ const client = new KugelAudio({
 
 ### Region Selection
 
-KugelAudio is available in multiple regions. The default is EU.
+By default, KugelAudio uses the canonical geo-routed API endpoint. You can
+select the direct EU endpoint when you need to pin traffic to Europe.
 
-| Region | Endpoint |
-|--------|----------|
-| `eu` | `api.kugelaudio.com` (default) |
-| `us` | `us-api.kugelaudio.com` |
-| `global` | `global-api.kugelaudio.com` (geo-routed) |
+| Region hint | Endpoint |
+|-------------|----------|
+| default | `api.kugelaudio.com` (geo-routed) |
+| `eu` | `api.eu.kugelaudio.com` |
 
 **Option 1 — API key prefix** (simplest, works with env vars):
 
 ```typescript
-const client = new KugelAudio({ apiKey: 'us-ka_your_api_key' });       // → US
-const client = new KugelAudio({ apiKey: 'global-ka_your_api_key' });   // → Global
-const client = new KugelAudio({ apiKey: 'eu-ka_your_api_key' });       // → EU (explicit)
-const client = new KugelAudio({ apiKey: 'ka_your_api_key' });           // → EU (default)
+const client = new KugelAudio({ apiKey: 'eu-ka_your_api_key' });       // → EU
+const client = new KugelAudio({ apiKey: 'ka_your_api_key' });          // → canonical geo-routed API
 ```
 
 **Option 2 — `region` parameter**:
 
 ```typescript
-const client = new KugelAudio({ apiKey: 'ka_your_api_key', region: 'us' });
+const client = new KugelAudio({ apiKey: 'ka_your_api_key', region: 'eu' });
 ```
 
-The prefix is always stripped before authentication. Priority: `apiUrl` > `region` > key prefix > default (EU).
+The prefix is always stripped before authentication. Priority: `apiUrl` > `region` > key prefix > default.
 
 ### Single URL Architecture
 
@@ -276,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:
@@ -333,6 +364,7 @@ import {
   RateLimitError,
   InsufficientCreditsError,
   ValidationError,
+  NotFoundError,
   ConnectionError,
 } from 'kugelaudio';
 
@@ -347,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) {
@@ -361,9 +395,9 @@ try {
 
 ```typescript
 interface KugelAudioOptions {
-  apiKey: string;           // Required (can be prefixed with 'eu-', 'us-', or 'global-')
-  region?: Region;          // 'eu' | 'us' | 'global' (default: 'eu')
-  apiUrl?: string;          // Default: determined by region
+  apiKey: string;           // Required (can be prefixed with 'eu-' for EU)
+  region?: Region;          // 'eu' selects the direct EU endpoint
+  apiUrl?: string;          // Default: https://api.kugelaudio.com
   ttsUrl?: string;          // Default: same as apiUrl
   timeout?: number;         // Default: 60000 (ms)
 }
@@ -571,4 +605,3 @@ The SDK works in modern browsers with WebSocket support. For Node.js, ensure you
 ## License
 
 MIT
-

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.
  */
@@ -379,17 +457,17 @@ interface StreamCallbacks {
     onClose?: () => void;
 }
 /**
- * Deployment region. Controls which API endpoint the SDK connects to.
- * - `'eu'` — `api.kugelaudio.com` (default)
- * - `'us'` — `us-api.kugelaudio.com`
- * - `'global'` — `global-api.kugelaudio.com` (geo-routed)
+ * Deployment region. Set `'eu'` to use the direct EU endpoint:
+ * `api.eu.kugelaudio.com`.
+ *
+ * If omitted, the SDK uses `api.kugelaudio.com`.
  */
 type Region = 'eu' | 'us' | 'global';
 /**
  * KugelAudio client options.
  */
 interface KugelAudioOptions {
-    /** Your KugelAudio API key or JWT token. Can be prefixed with `eu-`, `us-`, or `global-` to select a region (prefix is stripped before auth). */
+    /** Your KugelAudio API key or JWT token. Prefix with `eu-` to select the direct EU endpoint (prefix is stripped before auth). */
     apiKey: string;
     /** Whether apiKey is a master key (for internal/server-side use). Master keys bypass billing. */
     isMasterKey?: boolean;
@@ -397,7 +475,7 @@ interface KugelAudioOptions {
     isToken?: boolean;
     /** Organisation ID to bill usage against (required for token auth to enable usage recording). */
     orgId?: number;
-    /** Deployment region. Takes precedence over API-key prefix but not over `apiUrl`. */
+    /** Deployment region. Set `eu` to select the direct EU endpoint. Takes precedence over API-key prefix but not over `apiUrl`. */
     region?: Region;
     /** API base URL (default: https://api.kugelaudio.com) */
     apiUrl?: string;
@@ -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.
  */
@@ -379,17 +457,17 @@ interface StreamCallbacks {
     onClose?: () => void;
 }
 /**
- * Deployment region. Controls which API endpoint the SDK connects to.
- * - `'eu'` — `api.kugelaudio.com` (default)
- * - `'us'` — `us-api.kugelaudio.com`
- * - `'global'` — `global-api.kugelaudio.com` (geo-routed)
+ * Deployment region. Set `'eu'` to use the direct EU endpoint:
+ * `api.eu.kugelaudio.com`.
+ *
+ * If omitted, the SDK uses `api.kugelaudio.com`.
  */
 type Region = 'eu' | 'us' | 'global';
 /**
  * KugelAudio client options.
  */
 interface KugelAudioOptions {
-    /** Your KugelAudio API key or JWT token. Can be prefixed with `eu-`, `us-`, or `global-` to select a region (prefix is stripped before auth). */
+    /** Your KugelAudio API key or JWT token. Prefix with `eu-` to select the direct EU endpoint (prefix is stripped before auth). */
     apiKey: string;
     /** Whether apiKey is a master key (for internal/server-side use). Master keys bypass billing. */
     isMasterKey?: boolean;
@@ -397,7 +475,7 @@ interface KugelAudioOptions {
     isToken?: boolean;
     /** Organisation ID to bill usage against (required for token auth to enable usage recording). */
     orgId?: number;
-    /** Deployment region. Takes precedence over API-key prefix but not over `apiUrl`. */
+    /** Deployment region. Set `eu` to select the direct EU endpoint. Takes precedence over API-key prefix but not over `apiUrl`. */
     region?: Region;
     /** API base URL (default: https://api.kugelaudio.com) */
     apiUrl?: string;
@@ -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 };