kugelaudio 0.4.0 → 0.6.0

package/src/client.test.ts

@@ -333,6 +333,10 @@ function makeGenerationStartedMsg(chunkId: number, text: string): string {
   });
 }
 
+function makeInterruptedMsg(): string {
+  return JSON.stringify({ interrupted: true });
+}
+
 describe('StreamingSession', () => {
   let client: KugelAudio;
 
@@ -545,4 +549,115 @@ describe('StreamingSession', () => {
     expect(session.isConnected).toBe(true);
     expect(() => session.send('Hello.', true)).not.toThrow();
   });
+
+  // -------------------------------------------------------------------------
+  // cancelCurrent() — barge-in (KUG-1050)
+  // -------------------------------------------------------------------------
+
+  it('cancelCurrent() sends {cancel:true}, fires onInterrupted, keeps socket open', async () => {
+    const interruptedCalls: number[] = [];
+
+    const session = client.tts.streamingSession(
+      { voiceId: 1 },
+      { onInterrupted: () => interruptedCalls.push(1) },
+    );
+
+    session.connect();
+    await new Promise<void>((r) => setTimeout(r, 10));
+
+    session.send('A very long sentence the user is about to talk over.');
+    mockWs.onmessage?.({ data: makeAudioMsg(0, 100) });
+
+    const cancelPromise = session.cancelCurrent();
+
+    // The barge-in frame was sent to the server.
+    const lastSent = JSON.parse(mockWs.send.mock.calls[mockWs.send.mock.calls.length - 1][0] as string);
+    expect(lastSent.cancel).toBe(true);
+
+    // Server acks the barge-in.
+    mockWs.onmessage?.({ data: makeInterruptedMsg() });
+    await cancelPromise;
+
+    // onInterrupted fired and the socket stayed open for the next turn.
+    expect(interruptedCalls).toHaveLength(1);
+    expect(session.isConnected).toBe(true);
+    expect(mockWs.close).not.toHaveBeenCalled();
+  });
+
+  it('cancelCurrent() re-sends config on the next send (fresh server session)', async () => {
+    const session = client.tts.streamingSession({ voiceId: 42 }, {});
+
+    session.connect();
+    await new Promise<void>((r) => setTimeout(r, 10));
+
+    // First send carries config (voice_id).
+    session.send('Hello.');
+    expect(JSON.parse(mockWs.send.mock.calls[mockWs.send.mock.calls.length - 1][0] as string).voice_id).toBe(42);
+
+    const cancelPromise = session.cancelCurrent();
+    mockWs.onmessage?.({ data: makeInterruptedMsg() });
+    await cancelPromise;
+
+    // The server started a fresh session, so the next send must re-send config.
+    session.send('Next turn.');
+    expect(JSON.parse(mockWs.send.mock.calls[mockWs.send.mock.calls.length - 1][0] as string).voice_id).toBe(42);
+  });
+
+  it('cancelCurrent() resolves on quiet timeout if server never acks', async () => {
+    const session = client.tts.streamingSession({ voiceId: 1 }, {});
+
+    session.connect();
+    await new Promise<void>((r) => setTimeout(r, 10));
+    session.send('Hello.');
+
+    vi.useFakeTimers();
+    const cancelPromise = session.cancelCurrent();
+
+    // No interrupted ack — the 5 s quiet timeout resolves it.
+    await vi.advanceTimersByTimeAsync(6_000);
+    await cancelPromise;
+
+    vi.useRealTimers();
+    // Socket was never closed; still reusable.
+    expect(session.isConnected).toBe(true);
+  });
+});
+
+// ---------------------------------------------------------------------------
+// MultiContextSession barge-in — closeContext immediate (KUG-1050)
+// ---------------------------------------------------------------------------
+
+describe('MultiContextSession closeContext', () => {
+  let client: KugelAudio;
+
+  beforeEach(() => {
+    client = new KugelAudio({ apiKey: 'test-key-xxx' });
+  });
+
+  it('closeContext(id, true) sends the immediate barge-in flag', async () => {
+    const session = client.tts.createMultiContextSession({ defaultVoiceId: 1 });
+    await session.connect({});
+
+    session.closeContext('ctx1', true);
+
+    const sent = JSON.parse(
+      mockWs.send.mock.calls[mockWs.send.mock.calls.length - 1][0] as string
+    );
+    expect(sent.close_context).toBe(true);
+    expect(sent.context_id).toBe('ctx1');
+    expect(sent.immediate).toBe(true);
+  });
+
+  it('closeContext(id) omits immediate (graceful drain)', async () => {
+    const session = client.tts.createMultiContextSession({ defaultVoiceId: 1 });
+    await session.connect({});
+
+    session.closeContext('ctx1');
+
+    const sent = JSON.parse(
+      mockWs.send.mock.calls[mockWs.send.mock.calls.length - 1][0] as string
+    );
+    expect(sent.close_context).toBe(true);
+    expect(sent.immediate).toBeUndefined();
+  });
 });

package/src/client.ts

@@ -2,6 +2,7 @@
  * KugelAudio API Client.
  */
 
+import { DictionariesResource } from './dictionaries';
 import {
     ConnectionError,
     KugelAudioError,
@@ -1194,14 +1195,22 @@ class MultiContextSession {
 
   /**
    * Close a specific context.
+   *
+   * @param contextId - The context to close.
+   * @param immediate - When `true`, **barge-in**: the server cancels the
+   *   context's in-flight generation immediately and discards any buffered or
+   *   queued text instead of draining it. Use this when the end user speaks
+   *   over the agent. When `false` (default), queued sentences finish first.
    */
-  closeContext(contextId: string): void {
+  closeContext(contextId: string, immediate = false): void {
     if (!this.ws || this.ws.readyState !== WS_OPEN) return;
 
-    this.ws.send(JSON.stringify({
+    const msg: Record<string, unknown> = {
       close_context: true,
       context_id: contextId,
-    }));
+    };
+    if (immediate) msg.immediate = true;
+    this.ws.send(JSON.stringify(msg));
   }
 
   /**
@@ -1361,6 +1370,10 @@ class StreamingSession {
           this.callbacks.onGenerationStarted?.(data.chunk_id ?? 0, data.text ?? '');
         }
 
+        if (data.interrupted) {
+          this.callbacks.onInterrupted?.();
+        }
+
         if (data.session_closed) {
           this.callbacks.onSessionClosed?.(
             data.total_audio_seconds ?? 0,
@@ -1460,6 +1473,97 @@ class StreamingSession {
     this.ws.send(JSON.stringify(msg));
   }
 
+  /**
+   * Interrupt (barge-in) the current generation without closing the socket.
+   *
+   * Use this when the end user starts speaking over the agent: it tells the
+   * server to **stop generating audio for the current turn immediately** and
+   * drop any text that was buffered or queued but not yet spoken. Unlike
+   * {@link endSession}, no remaining text is flushed — the turn is abandoned.
+   *
+   * The WebSocket stays open and a fresh session is ready, so you can call
+   * {@link send} for the next user turn right away (config is re-sent
+   * automatically on that first `send`).
+   *
+   * The returned promise resolves once the server acknowledges with an
+   * `interrupted` frame (which also fires
+   * {@link StreamingSessionCallbacks.onInterrupted}), or after a 5 s **quiet**
+   * timeout — i.e. 5 s elapse without any server message arriving. The timer
+   * resets on every incoming frame, so a few in-flight audio chunks still
+   * draining at the moment of cancellation do not trip it prematurely.
+   *
+   * @example
+   * ```typescript
+   * // VAD detected the user speaking over the agent:
+   * await session.cancelCurrent();
+   * // Socket is still open — start the next turn immediately:
+   * session.send(nextLlmToken);
+   * ```
+   */
+  cancelCurrent(): Promise<void> {
+    if (!this.ws || this.ws.readyState !== WS_OPEN) return Promise.resolve();
+
+    const ws = this.ws;
+    // Quiet timeout: resets on every incoming server message. Trips only
+    // when the server has been silent for this long. A short window is fine
+    // here because the server cancels in-flight generation promptly; we only
+    // need to outlast a handful of already-emitted audio frames in transit.
+    const QUIET_TIMEOUT_MS = 5_000;
+
+    return new Promise<void>((resolve) => {
+      let settled = false;
+      let timer: ReturnType<typeof setTimeout>;
+
+      const prevMessage = ws.onmessage;
+      const prevClose = ws.onclose;
+
+      const done = () => {
+        if (settled) return;
+        settled = true;
+        clearTimeout(timer);
+        // Restore the original handlers so subsequent calls don't stack
+        // wrappers and the typed-error onclose installed by connect() stays
+        // in effect for the next turn.
+        ws.onmessage = prevMessage;
+        ws.onclose = prevClose;
+        // The server starts a fresh session after a cancel, so the next
+        // send() must re-send config.
+        this.configSent = false;
+        resolve();
+      };
+
+      const armQuietTimer = () => {
+        clearTimeout(timer);
+        timer = setTimeout(done, QUIET_TIMEOUT_MS);
+      };
+
+      armQuietTimer();
+
+      ws.onmessage = (event: MessageEvent) => {
+        // Reset the quiet timer on EVERY incoming frame — late audio chunks
+        // from the cancelled turn count as liveness, not just the ack.
+        armQuietTimer();
+        if (prevMessage) prevMessage.call(ws, event);
+        try {
+          const raw = typeof event.data === 'string'
+            ? event.data
+            : event.data instanceof Buffer
+              ? event.data.toString()
+              : String(event.data);
+          if (JSON.parse(raw).interrupted) done();
+        } catch { /* ignore parse errors */ }
+      };
+
+      ws.onclose = (event: CloseEvent) => {
+        this.ws = null;
+        if (prevClose) prevClose.call(ws, event);
+        done();
+      };
+
+      ws.send(JSON.stringify({ cancel: true }));
+    });
+  }
+
   /**
    * End the current session but keep the WebSocket connection open.
    *
@@ -1614,6 +1718,8 @@ export class KugelAudio {
   public readonly models: ModelsResource;
   /** Voices resource */
   public readonly voices: VoicesResource;
+  /** Custom dictionaries resource */
+  public readonly dictionaries: DictionariesResource;
   /** TTS resource */
   public readonly tts: TTSResource;
 
@@ -1656,6 +1762,7 @@ export class KugelAudio {
 
     this.models = new ModelsResource(this);
     this.voices = new VoicesResource(this);
+    this.dictionaries = new DictionariesResource(this);
     this.tts = new TTSResource(this);
   }
 

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 },
+      ],
+    });
+  });
+});