kugelaudio 0.4.0 → 0.5.0

package/src/dictionaries.test.ts

@@ -0,0 +1,212 @@
+/**
+ * Tests for the dictionaries resource.
+ *
+ * Stubs the global `fetch` to verify the SDK sends the right method,
+ * URL, params, and JSON body for each CRUD path, and that snake_case
+ * server responses get mapped to camelCase SDK types.
+ */
+
+import { afterEach, beforeEach, describe, expect, it, vi } from 'vitest';
+import { KugelAudio } from './client';
+
+function jsonResponse(body: unknown, status = 200): Response {
+  return new Response(JSON.stringify(body), {
+    status,
+    headers: { 'Content-Type': 'application/json' },
+  });
+}
+
+function dictRow(overrides: Record<string, unknown> = {}) {
+  return {
+    id: 1,
+    project_id: 42,
+    name: 'Brand names',
+    description: null,
+    language: null,
+    is_active: true,
+    created_at: '2026-01-01T00:00:00+00:00',
+    updated_at: '2026-01-01T00:00:00+00:00',
+    ...overrides,
+  };
+}
+
+function entryRow(overrides: Record<string, unknown> = {}) {
+  return {
+    id: 11,
+    dictionary_id: 1,
+    word: 'Kubernetes',
+    replacement: 'koo-ber-net-eez',
+    ipa: null,
+    case_sensitive: false,
+    created_at: '2026-01-01T00:00:00+00:00',
+    updated_at: '2026-01-01T00:00:00+00:00',
+    ...overrides,
+  };
+}
+
+let fetchMock: ReturnType<typeof vi.fn>;
+
+beforeEach(() => {
+  fetchMock = vi.fn();
+  vi.stubGlobal('fetch', fetchMock);
+});
+
+afterEach(() => {
+  vi.unstubAllGlobals();
+});
+
+function makeClient() {
+  return new KugelAudio({ apiKey: 'test-key', apiUrl: 'https://api.example.com' });
+}
+
+describe('Dictionaries CRUD', () => {
+  it('lists dictionaries', async () => {
+    fetchMock.mockResolvedValueOnce(
+      jsonResponse({ dictionaries: [dictRow(), dictRow({ id: 2, name: 'Other' })] }),
+    );
+    const client = makeClient();
+    const result = await client.dictionaries.list();
+    expect(result).toHaveLength(2);
+    expect(result[0]).toMatchObject({
+      id: 1,
+      projectId: 42,
+      name: 'Brand names',
+      isActive: true,
+    });
+    const [url, init] = fetchMock.mock.calls[0];
+    expect(url).toBe('https://api.example.com/v1/dictionaries');
+    expect(init.method).toBe('GET');
+  });
+
+  it('passes project_id as a query param when supplied', async () => {
+    fetchMock.mockResolvedValueOnce(jsonResponse({ dictionaries: [] }));
+    const client = makeClient();
+    await client.dictionaries.list({ projectId: 99 });
+    expect(fetchMock.mock.calls[0][0]).toBe(
+      'https://api.example.com/v1/dictionaries?project_id=99',
+    );
+  });
+
+  it('creates a dictionary', async () => {
+    fetchMock.mockResolvedValueOnce(jsonResponse(dictRow({ id: 7, name: 'Glossary' })));
+    const client = makeClient();
+    const d = await client.dictionaries.create({
+      name: 'Glossary',
+      description: 'hi',
+      language: 'en',
+    });
+    expect(d.id).toBe(7);
+    const [url, init] = fetchMock.mock.calls[0];
+    expect(url).toBe('https://api.example.com/v1/dictionaries');
+    expect(init.method).toBe('POST');
+    expect(JSON.parse(init.body as string)).toEqual({
+      name: 'Glossary',
+      description: 'hi',
+      language: 'en',
+    });
+  });
+
+  it('updates only provided fields', async () => {
+    fetchMock.mockResolvedValueOnce(jsonResponse(dictRow({ is_active: false })));
+    const client = makeClient();
+    await client.dictionaries.update(1, { isActive: false });
+    const [url, init] = fetchMock.mock.calls[0];
+    expect(url).toBe('https://api.example.com/v1/dictionaries/1');
+    expect(init.method).toBe('PATCH');
+    expect(JSON.parse(init.body as string)).toEqual({ is_active: false });
+  });
+
+  it('deletes a dictionary', async () => {
+    fetchMock.mockResolvedValueOnce(jsonResponse({ deleted: true }));
+    const client = makeClient();
+    await client.dictionaries.delete(1);
+    const [url, init] = fetchMock.mock.calls[0];
+    expect(url).toBe('https://api.example.com/v1/dictionaries/1');
+    expect(init.method).toBe('DELETE');
+  });
+});
+
+describe('Dictionary entries CRUD', () => {
+  it('lists entries with search + pagination', async () => {
+    fetchMock.mockResolvedValueOnce(
+      jsonResponse({
+        entries: [entryRow()],
+        total: 1,
+        limit: 25,
+        offset: 0,
+      }),
+    );
+    const client = makeClient();
+    const res = await client.dictionaries.entries.list(1, {
+      search: 'kub',
+      limit: 25,
+    });
+    expect(res.total).toBe(1);
+    expect(res.entries[0]).toMatchObject({
+      id: 11,
+      dictionaryId: 1,
+      word: 'Kubernetes',
+      caseSensitive: false,
+    });
+    expect(fetchMock.mock.calls[0][0]).toBe(
+      'https://api.example.com/v1/dictionaries/1/entries?search=kub&limit=25',
+    );
+  });
+
+  it('adds a single entry and maps camelCase fields', async () => {
+    fetchMock.mockResolvedValueOnce(
+      jsonResponse(entryRow({ word: 'Postgres', replacement: 'post-gres' })),
+    );
+    const client = makeClient();
+    const e = await client.dictionaries.entries.add(1, {
+      word: 'Postgres',
+      replacement: 'post-gres',
+      caseSensitive: true,
+    });
+    expect(e.word).toBe('Postgres');
+    const [, init] = fetchMock.mock.calls[0];
+    expect(JSON.parse(init.body as string)).toEqual({
+      word: 'Postgres',
+      replacement: 'post-gres',
+      case_sensitive: true,
+    });
+  });
+
+  it('updates a single entry', async () => {
+    fetchMock.mockResolvedValueOnce(jsonResponse(entryRow({ replacement: 'new' })));
+    const client = makeClient();
+    await client.dictionaries.entries.update(1, 11, { replacement: 'new' });
+    const [url, init] = fetchMock.mock.calls[0];
+    expect(url).toBe('https://api.example.com/v1/dictionaries/1/entries/11');
+    expect(init.method).toBe('PATCH');
+    expect(JSON.parse(init.body as string)).toEqual({ replacement: 'new' });
+  });
+
+  it('deletes a single entry', async () => {
+    fetchMock.mockResolvedValueOnce(jsonResponse({ deleted: true }));
+    const client = makeClient();
+    await client.dictionaries.entries.delete(1, 11);
+    expect(fetchMock.mock.calls[0][1].method).toBe('DELETE');
+  });
+
+  it('bulk replaces entries', async () => {
+    fetchMock.mockResolvedValueOnce(
+      jsonResponse({ upserted: 2, deleted: 3, total: 2 }),
+    );
+    const client = makeClient();
+    const result = await client.dictionaries.entries.replaceAll(1, [
+      { word: 'Postgres', replacement: 'post-gres' },
+      { word: 'K8s', replacement: 'kubernetes', caseSensitive: true },
+    ]);
+    expect(result).toEqual({ upserted: 2, deleted: 3, total: 2 });
+    const [url, init] = fetchMock.mock.calls[0];
+    expect(url).toBe('https://api.example.com/v1/dictionaries/1/entries');
+    expect(init.method).toBe('PUT');
+    expect(JSON.parse(init.body as string)).toEqual({
+      entries: [
+        { word: 'Postgres', replacement: 'post-gres' },
+        { word: 'K8s', replacement: 'kubernetes', case_sensitive: true },
+      ],
+    });
+  });
+});

package/src/dictionaries.ts

@@ -0,0 +1,278 @@
+/**
+ * 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' },
+ * ]);
+ * ```
+ */
+
+import type { KugelAudio } from './client';
+import type {
+  BulkReplaceResult,
+  CreateDictionaryOptions,
+  Dictionary,
+  DictionaryEntry,
+  DictionaryEntryInput,
+  DictionaryEntryListResponse,
+  UpdateDictionaryOptions,
+  UpdateDictionaryEntryOptions,
+} from './types';
+
+function mapDictionary(raw: Record<string, unknown>): Dictionary {
+  return {
+    id: raw.id as number,
+    projectId: raw.project_id as number,
+    name: raw.name as string,
+    description: (raw.description as string | null) ?? undefined,
+    language: (raw.language as string | null) ?? undefined,
+    isActive: (raw.is_active as boolean) ?? true,
+    createdAt: raw.created_at as string,
+    updatedAt: raw.updated_at as string,
+  };
+}
+
+function mapEntry(raw: Record<string, unknown>): DictionaryEntry {
+  return {
+    id: raw.id as number,
+    dictionaryId: raw.dictionary_id as number,
+    word: raw.word as string,
+    replacement: raw.replacement as string,
+    ipa: (raw.ipa as string | null) ?? undefined,
+    caseSensitive: (raw.case_sensitive as boolean) ?? false,
+    createdAt: raw.created_at as string,
+    updatedAt: raw.updated_at as string,
+  };
+}
+
+function entryPayload(input: DictionaryEntryInput): Record<string, unknown> {
+  const payload: Record<string, unknown> = {
+    word: input.word,
+    replacement: input.replacement,
+  };
+  if (input.ipa !== undefined) payload.ipa = input.ipa;
+  if (input.caseSensitive !== undefined) {
+    payload.case_sensitive = input.caseSensitive;
+  }
+  return payload;
+}
+
+function buildPath(base: string, params: Record<string, unknown>): string {
+  const search = new URLSearchParams();
+  for (const [key, val] of Object.entries(params)) {
+    if (val === undefined || val === null) continue;
+    search.set(key, String(val));
+  }
+  const query = search.toString();
+  return query ? `${base}?${query}` : base;
+}
+
+/**
+ * Resource for entries within a single dictionary.
+ * Access via ``client.dictionaries.entries`` and pass ``dictionaryId``
+ * to each call.
+ */
+export class DictionaryEntriesResource {
+  constructor(private client: KugelAudio) {}
+
+  /** List entries with optional search + pagination. */
+  async list(
+    dictionaryId: number,
+    options?: {
+      search?: string;
+      limit?: number;
+      offset?: number;
+      projectId?: number;
+    },
+  ): Promise<DictionaryEntryListResponse> {
+    const path = buildPath(`/v1/dictionaries/${dictionaryId}/entries`, {
+      search: options?.search,
+      limit: options?.limit,
+      offset: options?.offset,
+      project_id: options?.projectId,
+    });
+    const raw = await this.client.request<{
+      entries: Record<string, unknown>[];
+      total: number;
+      limit: number;
+      offset: number;
+    }>('GET', path);
+    return {
+      entries: raw.entries.map(mapEntry),
+      total: raw.total,
+      limit: raw.limit,
+      offset: raw.offset,
+    };
+  }
+
+  /** Add a single entry to a dictionary. */
+  async add(
+    dictionaryId: number,
+    entry: DictionaryEntryInput,
+    options?: { projectId?: number },
+  ): Promise<DictionaryEntry> {
+    const path = buildPath(`/v1/dictionaries/${dictionaryId}/entries`, {
+      project_id: options?.projectId,
+    });
+    const raw = await this.client.request<Record<string, unknown>>(
+      'POST',
+      path,
+      entryPayload(entry),
+    );
+    return mapEntry(raw);
+  }
+
+  /** Update an existing entry. */
+  async update(
+    dictionaryId: number,
+    entryId: number,
+    updates: UpdateDictionaryEntryOptions,
+    options?: { projectId?: number },
+  ): Promise<DictionaryEntry> {
+    const payload: Record<string, unknown> = {};
+    if (updates.word !== undefined) payload.word = updates.word;
+    if (updates.replacement !== undefined) payload.replacement = updates.replacement;
+    if (updates.ipa !== undefined) payload.ipa = updates.ipa;
+    if (updates.caseSensitive !== undefined) {
+      payload.case_sensitive = updates.caseSensitive;
+    }
+    const path = buildPath(`/v1/dictionaries/${dictionaryId}/entries/${entryId}`, {
+      project_id: options?.projectId,
+    });
+    const raw = await this.client.request<Record<string, unknown>>(
+      'PATCH',
+      path,
+      payload,
+    );
+    return mapEntry(raw);
+  }
+
+  /** Delete a single entry. */
+  async delete(
+    dictionaryId: number,
+    entryId: number,
+    options?: { projectId?: number },
+  ): Promise<void> {
+    const path = buildPath(`/v1/dictionaries/${dictionaryId}/entries/${entryId}`, {
+      project_id: options?.projectId,
+    });
+    await this.client.request<{ deleted: boolean }>('DELETE', path);
+  }
+
+  /**
+   * 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.
+   */
+  async replaceAll(
+    dictionaryId: number,
+    entries: DictionaryEntryInput[],
+    options?: { projectId?: number },
+  ): Promise<BulkReplaceResult> {
+    const path = buildPath(`/v1/dictionaries/${dictionaryId}/entries`, {
+      project_id: options?.projectId,
+    });
+    const raw = await this.client.request<BulkReplaceResult>('PUT', path, {
+      entries: entries.map(entryPayload),
+    });
+    return raw;
+  }
+}
+
+/**
+ * Resource for managing per-project custom dictionaries.
+ */
+export class DictionariesResource {
+  /** Per-entry operations within a dictionary. */
+  public readonly entries: DictionaryEntriesResource;
+
+  constructor(private client: KugelAudio) {
+    this.entries = new DictionaryEntriesResource(client);
+  }
+
+  /** List every dictionary in the caller's project. */
+  async list(options?: { projectId?: number }): Promise<Dictionary[]> {
+    const path = buildPath('/v1/dictionaries', {
+      project_id: options?.projectId,
+    });
+    const raw = await this.client.request<{
+      dictionaries: Record<string, unknown>[];
+    }>('GET', path);
+    return raw.dictionaries.map(mapDictionary);
+  }
+
+  /** Create a new dictionary scoped to the caller's project. */
+  async create(
+    body: CreateDictionaryOptions,
+    options?: { projectId?: number },
+  ): Promise<Dictionary> {
+    const path = buildPath('/v1/dictionaries', {
+      project_id: options?.projectId,
+    });
+    const payload: Record<string, unknown> = { name: body.name };
+    if (body.description !== undefined) payload.description = body.description;
+    if (body.language !== undefined) payload.language = body.language;
+    const raw = await this.client.request<Record<string, unknown>>(
+      'POST',
+      path,
+      payload,
+    );
+    return mapDictionary(raw);
+  }
+
+  /** Fetch a single dictionary. */
+  async get(
+    dictionaryId: number,
+    options?: { projectId?: number },
+  ): Promise<Dictionary> {
+    const path = buildPath(`/v1/dictionaries/${dictionaryId}`, {
+      project_id: options?.projectId,
+    });
+    const raw = await this.client.request<Record<string, unknown>>('GET', path);
+    return mapDictionary(raw);
+  }
+
+  /** Update name / description / language / isActive. */
+  async update(
+    dictionaryId: number,
+    updates: UpdateDictionaryOptions,
+    options?: { projectId?: number },
+  ): Promise<Dictionary> {
+    const payload: Record<string, unknown> = {};
+    if (updates.name !== undefined) payload.name = updates.name;
+    if (updates.description !== undefined) payload.description = updates.description;
+    if (updates.language !== undefined) payload.language = updates.language;
+    if (updates.isActive !== undefined) payload.is_active = updates.isActive;
+    const path = buildPath(`/v1/dictionaries/${dictionaryId}`, {
+      project_id: options?.projectId,
+    });
+    const raw = await this.client.request<Record<string, unknown>>(
+      'PATCH',
+      path,
+      payload,
+    );
+    return mapDictionary(raw);
+  }
+
+  /** Delete a dictionary (cascades to its entries). */
+  async delete(
+    dictionaryId: number,
+    options?: { projectId?: number },
+  ): Promise<void> {
+    const path = buildPath(`/v1/dictionaries/${dictionaryId}`, {
+      project_id: options?.projectId,
+    });
+    await this.client.request<{ deleted: boolean }>('DELETE', path);
+  }
+}

package/src/errors.ts

@@ -3,7 +3,7 @@
  *
  * 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.
  */
 
@@ -126,6 +126,26 @@ export class ConnectionError extends KugelAudioError {
   }
 }
 
+/**
+ * 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.
+ */
+export class NotFoundError extends KugelAudioError {
+  constructor(message?: string, options: KugelAudioErrorOptions = {}) {
+    super(message ?? 'Not found.', {
+      statusCode: 404,
+      errorCode: ErrorCodes.NOT_FOUND,
+      ...options,
+    });
+    this.name = 'NotFoundError';
+    Object.setPrototypeOf(this, NotFoundError.prototype);
+  }
+}
+
 // ---------------------------------------------------------------------------
 // Classifiers
 // ---------------------------------------------------------------------------
@@ -168,6 +188,9 @@ function build(
       common,
     );
   }
+  if (errorCode === ErrorCodes.NOT_FOUND || status === 404) {
+    return new NotFoundError(message || undefined, common);
+  }
   return new KugelAudioError(message || `HTTP ${status}`, common);
 }
 

package/src/index.ts

@@ -46,8 +46,14 @@ export { KugelAudio } from './client';
 export type {
     AudioChunk,
     AudioResponse,
+    BulkReplaceResult,
     ContextVoiceSettings,
+    CreateDictionaryOptions,
     CreateVoiceOptions,
+    Dictionary,
+    DictionaryEntry,
+    DictionaryEntryInput,
+    DictionaryEntryListResponse,
     GenerateOptions,
     GenerationStats,
     KugelAudioOptions,
@@ -59,6 +65,8 @@ export type {
     StreamCallbacks,
     StreamConfig,
     StreamingSessionCallbacks,
+    UpdateDictionaryEntryOptions,
+    UpdateDictionaryOptions,
     UpdateVoiceOptions,
     Voice,
     VoiceAge,
@@ -71,6 +79,8 @@ export type {
     WordTimestamp
 } from './types';
 
+export { DictionariesResource, DictionaryEntriesResource } from './dictionaries';
+
 // Errors
 export {
     AuthenticationError,
@@ -78,6 +88,7 @@ export {
     ErrorCodes,
     InsufficientCreditsError,
     KugelAudioError,
+    NotFoundError,
     RateLimitError,
     ValidationError,
     WsCloseCodes,

package/src/types.ts

@@ -62,6 +62,94 @@ export interface VoiceListResponse {
  */
 export type VoiceQuality = 'low' | 'mid' | 'high';
 
+// ─── Dictionaries ────────────────────────────────────────────────────────────
+
+/**
+ * A per-project pronunciation dictionary.
+ */
+export 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.
+ */
+export interface DictionaryEntry {
+  id: number;
+  dictionaryId: number;
+  word: string;
+  replacement: string;
+  ipa?: string;
+  caseSensitive: boolean;
+  createdAt: string;
+  updatedAt: string;
+}
+
+/**
+ * Paginated response from listing entries.
+ */
+export interface DictionaryEntryListResponse {
+  entries: DictionaryEntry[];
+  total: number;
+  limit: number;
+  offset: number;
+}
+
+/**
+ * Counts returned by `entries.replaceAll`.
+ */
+export interface BulkReplaceResult {
+  upserted: number;
+  deleted: number;
+  total: number;
+}
+
+/**
+ * Options for creating a dictionary.
+ */
+export interface CreateDictionaryOptions {
+  name: string;
+  description?: string;
+  language?: string;
+}
+
+/**
+ * Options for updating a dictionary. Only provided fields are changed.
+ */
+export interface UpdateDictionaryOptions {
+  name?: string;
+  description?: string;
+  language?: string;
+  isActive?: boolean;
+}
+
+/**
+ * Payload for creating or replacing a single entry.
+ */
+export interface DictionaryEntryInput {
+  word: string;
+  replacement: string;
+  ipa?: string;
+  caseSensitive?: boolean;
+}
+
+/**
+ * Options for updating an entry.
+ */
+export interface UpdateDictionaryEntryOptions {
+  word?: string;
+  replacement?: string;
+  ipa?: string;
+  caseSensitive?: boolean;
+}
+
 /**
  * Extended voice information returned by voice management endpoints.
  */