kugelaudio 0.2.3 → 0.3.0

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "kugelaudio",
-  "version": "0.2.3",
+  "version": "0.3.0",
   "description": "Official JavaScript/TypeScript SDK for KugelAudio TTS API",
   "main": "dist/index.js",
   "module": "dist/index.mjs",
@@ -34,21 +34,22 @@
     "websocket",
     "kugelaudio"
   ],
-  "author": "KugelAudio <support@kugelaudio.com>",
+  "author": "KugelAudio <hello@kugelaudio.com>",
   "license": "MIT",
   "repository": {
     "type": "git",
-    "url": "https://github.com/kugelaudio/kugelaudio-js"
+    "url": "https://github.com/Kugelaudio/KugelAudio",
+    "directory": "sdks/js"
   },
   "homepage": "https://kugelaudio.com",
   "bugs": {
-    "url": "https://github.com/kugelaudio/kugelaudio-js/issues"
+    "url": "https://github.com/Kugelaudio/KugelAudio/issues"
   },
   "devDependencies": {
-    "@types/node": "^20.0.0",
+    "@types/node": "^25.3.2",
     "tsup": "^8.0.0",
-    "typescript": "^5.0.0",
-    "vitest": "^1.0.0"
+    "typescript": "^6.0.2",
+    "vitest": "^4.0.18"
   },
   "engines": {
     "node": ">=18.0.0"
@@ -57,4 +58,4 @@
     "tsx": "^4.21.0",
     "ws": "^8.18.0"
   }
-}
+}

package/src/client.test.ts

@@ -0,0 +1,548 @@
+/**
+ * Unit tests for TTSResource.toReadable() and keepalive ping mechanism.
+ *
+ * These tests mock the WebSocket and verify that toReadable() correctly
+ * pipes audio chunks into a Node.js Readable stream without gaps or
+ * ordering issues — the root cause of KUG-157.
+ */
+
+import { describe, it, expect, vi, beforeEach, afterEach } from 'vitest';
+import { KugelAudio } from './client';
+
+// ---------------------------------------------------------------------------
+// Minimal WebSocket mock
+// ---------------------------------------------------------------------------
+
+type WsListener = (event: { data: string }) => void;
+type WsCloseListener = (event: { code: number }) => void;
+
+interface MockWs {
+  readyState: number;
+  onopen: (() => void) | null;
+  onmessage: WsListener | null;
+  onerror: (() => void) | null;
+  onclose: WsCloseListener | null;
+  send: ReturnType<typeof vi.fn>;
+  close: ReturnType<typeof vi.fn>;
+  ping?: ReturnType<typeof vi.fn>;
+}
+
+let mockWs: MockWs;
+
+vi.mock('./websocket', () => ({
+  getWebSocket: () => {
+    return class MockWebSocket {
+      readyState = 0; // CONNECTING
+      onopen: (() => void) | null = null;
+      onmessage: WsListener | null = null;
+      onerror: (() => void) | null = null;
+      onclose: WsCloseListener | null = null;
+      send = vi.fn();
+      close = vi.fn();
+      ping = vi.fn();
+
+      constructor() {
+        mockWs = this as unknown as MockWs;
+        // Simulate async open
+        setTimeout(() => {
+          this.readyState = 1; // OPEN
+          this.onopen?.();
+        }, 0);
+      }
+    };
+  },
+}));
+
+// ---------------------------------------------------------------------------
+// Helpers
+// ---------------------------------------------------------------------------
+
+function makeAudioMsg(index: number, samples = 100): string {
+  // Create a Buffer of `samples * 2` bytes (PCM16 = 2 bytes/sample) and base64-encode it.
+  const pcm = Buffer.alloc(samples * 2, index); // fill with byte value = index
+  return JSON.stringify({
+    audio: pcm.toString('base64'),
+    enc: 'pcm_s16le',
+    idx: index,
+    sr: 24000,
+    samples,
+  });
+}
+
+function makeFinalMsg(chunks: number, totalSamples: number): string {
+  return JSON.stringify({
+    final: true,
+    chunks,
+    total_samples: totalSamples,
+    dur_ms: 100,
+    gen_ms: 50,
+    ttfa_ms: 30,
+    rtf: 0.5,
+  });
+}
+
+/** Collect all data events from a Readable into a single Buffer. */
+function collectStream(stream: NodeJS.ReadableStream): Promise<Buffer> {
+  return new Promise((resolve, reject) => {
+    const parts: Buffer[] = [];
+    stream.on('data', (chunk: Buffer) => parts.push(chunk));
+    stream.on('end', () => resolve(Buffer.concat(parts)));
+    stream.on('error', reject);
+  });
+}
+
+// ---------------------------------------------------------------------------
+// Tests
+// ---------------------------------------------------------------------------
+
+describe('TTSResource.toReadable()', () => {
+  let client: KugelAudio;
+
+  beforeEach(() => {
+    client = new KugelAudio({ apiKey: 'test-key-xxx' });
+  });
+
+  it('returns a Readable that emits raw PCM16 bytes for each audio chunk', async () => {
+    const readable = client.tts.toReadable({ text: 'Hello' });
+
+    // Wait for the mock WebSocket to open and send() to be called
+    await new Promise<void>((r) => setTimeout(r, 10));
+
+    // Simulate three audio chunks followed by final
+    mockWs.onmessage?.({ data: makeAudioMsg(0, 100) });
+    mockWs.onmessage?.({ data: makeAudioMsg(1, 200) });
+    mockWs.onmessage?.({ data: makeAudioMsg(2, 150) });
+    mockWs.onmessage?.({ data: makeFinalMsg(3, 450) });
+
+    const result = await collectStream(readable);
+
+    // Each PCM16 chunk is samples*2 bytes
+    expect(result.byteLength).toBe((100 + 200 + 150) * 2);
+  });
+
+  it('emits chunks in the correct order', async () => {
+    const readable = client.tts.toReadable({ text: 'Order test' });
+
+    await new Promise<void>((r) => setTimeout(r, 10));
+
+    // Use distinct fill patterns per chunk so ordering is detectable
+    const chunk0 = Buffer.alloc(10, 0x01);
+    const chunk1 = Buffer.alloc(10, 0x02);
+    const chunk2 = Buffer.alloc(10, 0x03);
+
+    mockWs.onmessage?.({ data: JSON.stringify({ audio: chunk0.toString('base64'), enc: 'pcm_s16le', idx: 0, sr: 24000, samples: 5 }) });
+    mockWs.onmessage?.({ data: JSON.stringify({ audio: chunk1.toString('base64'), enc: 'pcm_s16le', idx: 1, sr: 24000, samples: 5 }) });
+    mockWs.onmessage?.({ data: JSON.stringify({ audio: chunk2.toString('base64'), enc: 'pcm_s16le', idx: 2, sr: 24000, samples: 5 }) });
+    mockWs.onmessage?.({ data: makeFinalMsg(3, 15) });
+
+    const result = await collectStream(readable);
+
+    expect(result.byteLength).toBe(30);
+    // First 10 bytes should be 0x01, next 10 should be 0x02, last 10 should be 0x03
+    expect(result.subarray(0, 10).every((b) => b === 0x01)).toBe(true);
+    expect(result.subarray(10, 20).every((b) => b === 0x02)).toBe(true);
+    expect(result.subarray(20, 30).every((b) => b === 0x03)).toBe(true);
+  });
+
+  it('destroys the stream with an error on WebSocket error', async () => {
+    const readable = client.tts.toReadable({ text: 'Error test' });
+
+    await new Promise<void>((r) => setTimeout(r, 10));
+
+    mockWs.onmessage?.({ data: JSON.stringify({ error: 'internal server error' }) });
+
+    await expect(collectStream(readable)).rejects.toThrow();
+  });
+
+  it('ends the stream cleanly when final message is received', async () => {
+    const readable = client.tts.toReadable({ text: 'End test' });
+
+    await new Promise<void>((r) => setTimeout(r, 10));
+
+    mockWs.onmessage?.({ data: makeAudioMsg(0, 50) });
+    mockWs.onmessage?.({ data: makeFinalMsg(1, 50) });
+
+    const result = await collectStream(readable);
+    expect(result.byteLength).toBe(100); // 50 samples * 2 bytes
+  });
+
+  it('creates the stream synchronously before audio arrives', () => {
+    // The Readable must be returned immediately, not after the first chunk.
+    const readable = client.tts.toReadable({ text: 'Sync test' });
+    expect(readable).toBeDefined();
+    expect(typeof readable.pipe).toBe('function');
+    expect(typeof readable.on).toBe('function');
+  });
+});
+
+// ---------------------------------------------------------------------------
+// Multi-region tests
+// ---------------------------------------------------------------------------
+
+describe('KugelAudio multi-region', () => {
+  it('defaults to EU when no region or prefix is given', () => {
+    const client = new KugelAudio({ apiKey: 'ka_test123' });
+    expect((client as any)._apiUrl).toBe('https://api.kugelaudio.com');
+  });
+
+  it('selects US endpoint with explicit region', () => {
+    const client = new KugelAudio({ apiKey: 'ka_test123', region: 'us' });
+    expect((client as any)._apiUrl).toBe('https://us-api.kugelaudio.com');
+  });
+
+  it('selects global endpoint with explicit region', () => {
+    const client = new KugelAudio({ apiKey: 'ka_test123', region: 'global' });
+    expect((client as any)._apiUrl).toBe('https://global-api.kugelaudio.com');
+  });
+
+  it('detects US region from key prefix and strips it', () => {
+    const client = new KugelAudio({ apiKey: 'us-ka_test123' });
+    expect((client as any)._apiUrl).toBe('https://us-api.kugelaudio.com');
+    expect((client as any)._apiKey).toBe('ka_test123');
+  });
+
+  it('detects global region from key prefix and strips it', () => {
+    const client = new KugelAudio({ apiKey: 'global-ka_test123' });
+    expect((client as any)._apiUrl).toBe('https://global-api.kugelaudio.com');
+    expect((client as any)._apiKey).toBe('ka_test123');
+  });
+
+  it('detects EU region from key prefix and strips it', () => {
+    const client = new KugelAudio({ apiKey: 'eu-ka_test123' });
+    expect((client as any)._apiUrl).toBe('https://api.kugelaudio.com');
+    expect((client as any)._apiKey).toBe('ka_test123');
+  });
+
+  it('explicit region overrides key prefix', () => {
+    const client = new KugelAudio({ apiKey: 'us-ka_test123', region: 'global' });
+    expect((client as any)._apiUrl).toBe('https://global-api.kugelaudio.com');
+    expect((client as any)._apiKey).toBe('ka_test123');
+  });
+
+  it('explicit apiUrl overrides region entirely', () => {
+    const client = new KugelAudio({
+      apiKey: 'us-ka_test123',
+      region: 'global',
+      apiUrl: 'https://custom.example.com',
+    });
+    expect((client as any)._apiUrl).toBe('https://custom.example.com');
+    expect((client as any)._apiKey).toBe('ka_test123');
+  });
+
+  it('throws on invalid region', () => {
+    expect(() => new KugelAudio({ apiKey: 'ka_test123', region: 'mars' as any })).toThrow(
+      /Invalid region/
+    );
+  });
+
+  it('ttsUrl defaults to the resolved region URL', () => {
+    const client = new KugelAudio({ apiKey: 'us-ka_test123' });
+    expect((client as any)._ttsUrl).toBe('https://us-api.kugelaudio.com');
+  });
+
+  it('unprefixed key is not modified', () => {
+    const client = new KugelAudio({ apiKey: 'ka_no_prefix' });
+    expect((client as any)._apiKey).toBe('ka_no_prefix');
+  });
+});
+
+// ---------------------------------------------------------------------------
+// Keepalive ping tests
+// ---------------------------------------------------------------------------
+
+describe('KugelAudio keepalive ping', () => {
+  beforeEach(() => {
+    vi.useFakeTimers();
+  });
+
+  afterEach(() => {
+    vi.useRealTimers();
+  });
+
+  it('stores default keepalive interval of 20 000 ms', () => {
+    const client = new KugelAudio({ apiKey: 'test-key-xxx' });
+    expect(client.keepalivePingInterval).toBe(20_000);
+  });
+
+  it('accepts a custom keepalive interval', () => {
+    const client = new KugelAudio({ apiKey: 'test-key-xxx', keepalivePingInterval: 5_000 });
+    expect(client.keepalivePingInterval).toBe(5_000);
+  });
+
+  it('stores null when keepalive is disabled', () => {
+    const client = new KugelAudio({ apiKey: 'test-key-xxx', keepalivePingInterval: null });
+    expect(client.keepalivePingInterval).toBeNull();
+  });
+
+  it('calls ws.ping() after each interval fires', async () => {
+    const client = new KugelAudio({ apiKey: 'test-key-xxx', keepalivePingInterval: 1_000 });
+    // Trigger the connection by opening a stream
+    client.tts.toReadable({ text: 'ping test' });
+
+    // Advance just enough for the mock WebSocket setTimeout(0) to fire (open event)
+    await vi.advanceTimersByTimeAsync(10);
+
+    // Now the WS is open and the keepalive setInterval is registered.
+    // Advance 3 more seconds to fire the ping 3 times.
+    await vi.advanceTimersByTimeAsync(3_000);
+
+    expect(mockWs.ping).toBeDefined();
+    expect((mockWs.ping as ReturnType<typeof vi.fn>).mock.calls.length).toBeGreaterThanOrEqual(2);
+  });
+
+  it('does not call ws.ping() when keepalive is disabled', async () => {
+    const client = new KugelAudio({ apiKey: 'test-key-xxx', keepalivePingInterval: null });
+    client.tts.toReadable({ text: 'no ping test' });
+
+    // Let the WS open
+    await vi.advanceTimersByTimeAsync(10);
+    // Advance a long time — no pings should fire
+    await vi.advanceTimersByTimeAsync(60_000);
+
+    expect((mockWs.ping as ReturnType<typeof vi.fn>).mock.calls.length).toBe(0);
+  });
+});
+
+// ---------------------------------------------------------------------------
+// StreamingSession tests (KUG-264)
+// ---------------------------------------------------------------------------
+
+function makeChunkCompleteMsg(chunkId: number, audioSeconds: number, genMs: number): string {
+  return JSON.stringify({
+    chunk_complete: true,
+    chunk_id: chunkId,
+    audio_seconds: audioSeconds,
+    gen_ms: genMs,
+  });
+}
+
+function makeSessionClosedMsg(totalAudioSeconds: number, totalTextChunks: number, totalAudioChunks: number): string {
+  return JSON.stringify({
+    session_closed: true,
+    total_audio_seconds: totalAudioSeconds,
+    total_text_chunks: totalTextChunks,
+    total_audio_chunks: totalAudioChunks,
+  });
+}
+
+function makeGenerationStartedMsg(chunkId: number, text: string): string {
+  return JSON.stringify({
+    generation_started: true,
+    chunk_id: chunkId,
+    text,
+  });
+}
+
+describe('StreamingSession', () => {
+  let client: KugelAudio;
+
+  beforeEach(() => {
+    client = new KugelAudio({ apiKey: 'test-key-xxx' });
+  });
+
+  /**
+   * Helper: make the mock's close() simulate real WebSocket behaviour —
+   * once close() is called, onmessage is nulled (no more message delivery).
+   * This reproduces the real-world timing issue where the server's
+   * session_closed message arrives after the socket is torn down.
+   */
+  function makeCloseTearDown(): void {
+    mockWs.close = vi.fn(() => {
+      mockWs.readyState = 3; // CLOSED
+      mockWs.onmessage = null;
+    });
+  }
+
+  it('fires onSessionClosed when server sends session_closed after close()', async () => {
+    const sessionClosedCalls: Array<{ totalAudioSeconds: number; totalTextChunks: number; totalAudioChunks: number }> = [];
+    const chunkCompleteCalls: Array<{ chunkId: number; audioSeconds: number; genMs: number }> = [];
+
+    const session = client.tts.streamingSession(
+      { voiceId: 1 },
+      {
+        onChunkComplete: (chunkId, audioSeconds, genMs) => {
+          chunkCompleteCalls.push({ chunkId, audioSeconds, genMs });
+        },
+        onSessionClosed: (totalAudioSeconds, totalTextChunks, totalAudioChunks) => {
+          sessionClosedCalls.push({ totalAudioSeconds, totalTextChunks, totalAudioChunks });
+        },
+      },
+    );
+
+    session.connect();
+    await new Promise<void>((r) => setTimeout(r, 10));
+
+    // Multi-send: simulate streaming LLM tokens
+    session.send('Hello ');
+    session.send('world. ');
+    session.send('How are you?');
+
+    // Server generates first chunk
+    mockWs.onmessage?.({ data: makeGenerationStartedMsg(0, 'Hello world.') });
+    mockWs.onmessage?.({ data: makeAudioMsg(0, 100) });
+    mockWs.onmessage?.({ data: makeChunkCompleteMsg(0, 1.0, 100) });
+
+    expect(chunkCompleteCalls).toHaveLength(1);
+
+    // Make close() realistic: socket tears down immediately, killing onmessage
+    makeCloseTearDown();
+
+    // Client calls close() — must wait for session_closed before tearing down
+    const closePromise = session.close();
+
+    // Simulate server processing the final flush and sending responses
+    // (this happens asynchronously on the server after receiving {close: true})
+    mockWs.onmessage?.({ data: makeGenerationStartedMsg(1, 'How are you?') });
+    mockWs.onmessage?.({ data: makeAudioMsg(1, 80) });
+    mockWs.onmessage?.({ data: makeChunkCompleteMsg(1, 0.8, 90) });
+    mockWs.onmessage?.({ data: makeSessionClosedMsg(1.8, 2, 4) });
+
+    await closePromise;
+
+    // onSessionClosed MUST have been called
+    expect(sessionClosedCalls).toHaveLength(1);
+    expect(sessionClosedCalls[0].totalAudioSeconds).toBe(1.8);
+    expect(sessionClosedCalls[0].totalTextChunks).toBe(2);
+    expect(sessionClosedCalls[0].totalAudioChunks).toBe(4);
+  });
+
+  it('resolves close() even if server never sends session_closed (quiet timeout)', async () => {
+    const session = client.tts.streamingSession(
+      { voiceId: 1 },
+      {},
+    );
+
+    session.connect();
+    await new Promise<void>((r) => setTimeout(r, 10));
+    session.send('Hello.');
+
+    // Simulate some audio
+    mockWs.onmessage?.({ data: makeAudioMsg(0, 50) });
+    mockWs.onmessage?.({ data: makeChunkCompleteMsg(0, 0.5, 50) });
+
+    makeCloseTearDown();
+    vi.useFakeTimers();
+
+    const closePromise = session.close();
+
+    // No further server messages — quiet timeout (15 s) should resolve.
+    await vi.advanceTimersByTimeAsync(16_000);
+
+    await closePromise;
+
+    vi.useRealTimers();
+
+    // Should have cleaned up
+    expect(session.isConnected).toBe(false);
+  });
+
+  /**
+   * Regression: a slow final-flush that streams audio for longer than the
+   * old 10 s wall-clock fuse must NOT be truncated. The quiet-timeout fix
+   * resets on every incoming frame, so as long as the server keeps sending
+   * audio, close() keeps waiting.
+   */
+  it('does not truncate a slow final flush that streams past the old 10 s fuse', async () => {
+    const audioChunks: unknown[] = [];
+    const sessionClosedCalls: unknown[] = [];
+
+    const session = client.tts.streamingSession(
+      { voiceId: 1 },
+      {
+        onChunk: (chunk) => audioChunks.push(chunk),
+        onSessionClosed: (totalSecs, chunks, audioCnt) => {
+          sessionClosedCalls.push({ totalSecs, chunks, audioCnt });
+        },
+      },
+    );
+
+    session.connect();
+    await new Promise<void>((r) => setTimeout(r, 10));
+
+    // Buffer text without an explicit flush — server will flush on close.
+    session.send('A long final paragraph that takes many seconds to render.');
+
+    makeCloseTearDown();
+    vi.useFakeTimers();
+
+    const closePromise = session.close();
+
+    // Server streams audio every 2 s for 18 s — well past the old 10 s fuse.
+    // Each frame must reset the quiet timer so close() keeps waiting.
+    for (let i = 0; i < 9; i++) {
+      await vi.advanceTimersByTimeAsync(2_000);
+      mockWs.onmessage?.({ data: makeAudioMsg(i, 200) });
+    }
+
+    // Server finally finishes generation and confirms close.
+    mockWs.onmessage?.({ data: makeChunkCompleteMsg(0, 18.0, 17_500) });
+    mockWs.onmessage?.({ data: makeSessionClosedMsg(18.0, 1, 9) });
+
+    await closePromise;
+
+    vi.useRealTimers();
+
+    // All 9 audio frames from the slow final flush were delivered.
+    expect(audioChunks).toHaveLength(9);
+    // session_closed was observed (not truncated by a wall-clock fuse).
+    expect(sessionClosedCalls).toHaveLength(1);
+  });
+
+  it('receives audio chunks from final flush before session_closed', async () => {
+    const audioChunks: unknown[] = [];
+    const sessionClosedCalls: unknown[] = [];
+
+    const session = client.tts.streamingSession(
+      { voiceId: 1 },
+      {
+        onChunk: (chunk) => audioChunks.push(chunk),
+        onSessionClosed: (totalSecs, chunks, audioCnt) => {
+          sessionClosedCalls.push({ totalSecs, chunks, audioCnt });
+        },
+      },
+    );
+
+    session.connect();
+    await new Promise<void>((r) => setTimeout(r, 10));
+
+    // Send partial text that hasn't been flushed
+    session.send('Partial text that');
+
+    makeCloseTearDown();
+
+    // Client closes — server flushes remaining text and sends audio
+    const closePromise = session.close();
+
+    // Server flushes and generates
+    mockWs.onmessage?.({ data: makeGenerationStartedMsg(0, 'Partial text that') });
+    mockWs.onmessage?.({ data: makeAudioMsg(0, 200) });
+    mockWs.onmessage?.({ data: makeAudioMsg(1, 150) });
+    mockWs.onmessage?.({ data: makeChunkCompleteMsg(0, 1.5, 120) });
+    mockWs.onmessage?.({ data: makeSessionClosedMsg(1.5, 1, 2) });
+
+    await closePromise;
+
+    // Audio from final flush must have been received
+    expect(audioChunks).toHaveLength(2);
+    expect(sessionClosedCalls).toHaveLength(1);
+  });
+
+  // -------------------------------------------------------------------------
+  // connect() awaitability — regression for the "StreamingSession not
+  // connected" race fixed alongside KUG-421.
+  // -------------------------------------------------------------------------
+
+  it('connect() returns a promise that resolves when the WS is OPEN', async () => {
+    const session = client.tts.streamingSession({ voiceId: 1 }, {});
+
+    // Before await, the mock is still CONNECTING (readyState 0).
+    const ready = session.connect();
+    expect(session.isConnected).toBe(false);
+
+    await ready;
+
+    // After await, the WS is OPEN and send() works without throwing.
+    expect(session.isConnected).toBe(true);
+    expect(() => session.send('Hello.', true)).not.toThrow();
+  });
+});