kugelaudio 0.7.0 → 0.8.0

package/src/client.test.ts

@@ -7,8 +7,12 @@
  */
 
 import { describe, it, expect, vi, beforeEach, afterEach } from 'vitest';
+import packageJson from '../package.json';
 import { KugelAudio } from './client';
 import { RateLimitError } from './errors';
+import { parseSessionUsage } from './types';
+
+const SDK_VERSION = packageJson.version;
 
 // ---------------------------------------------------------------------------
 // Minimal WebSocket mock
@@ -99,6 +103,43 @@ function collectStream(stream: NodeJS.ReadableStream): Promise<Buffer> {
 // Tests
 // ---------------------------------------------------------------------------
 
+describe('parseSessionUsage (/ws/tts final + session_closed)', () => {
+  it('parses the usage block from a /ws/tts final frame', () => {
+    const usage = parseSessionUsage({
+      final: true,
+      chunks: 3,
+      total_samples: 1000,
+      dur_ms: 5400,
+      gen_ms: 900,
+      rtf: 0.17,
+      usage: {
+        audio_seconds: 5.4,
+        characters: 142,
+        cost_cents: 0.49,
+        currency: 'eur',
+        model_id: 'kugel-3',
+      },
+    });
+    expect(usage).not.toBeNull();
+    expect(usage?.audioSeconds).toBe(5.4);
+    expect(usage?.costCents).toBe(0.49);
+    expect(usage?.costAvailable).toBe(true);
+  });
+
+  it('reports cost null (not zero) when unavailable', () => {
+    const usage = parseSessionUsage({
+      final: true,
+      usage: { audio_seconds: 2.0, cost_cents: null, cost_unavailable: true },
+    });
+    expect(usage?.costCents).toBeNull();
+    expect(usage?.costAvailable).toBe(false);
+  });
+
+  it('returns null when there is no usage info', () => {
+    expect(parseSessionUsage({ final: true, chunks: 1 })).toBeNull();
+  });
+});
+
 describe('TTSResource.toReadable()', () => {
   let client: KugelAudio;
 
@@ -271,7 +312,7 @@ describe('KugelAudio SDK metadata', () => {
     expect(init).toMatchObject({
       headers: {
         'X-KugelAudio-SDK': 'js',
-        'X-KugelAudio-SDK-Version': '0.6.1',
+        'X-KugelAudio-SDK-Version': SDK_VERSION,
       },
     });
   });
@@ -283,7 +324,7 @@ describe('KugelAudio SDK metadata', () => {
     await new Promise<void>((r) => setTimeout(r, 10));
 
     expect(mockWs.url).toContain('sdk=js');
-    expect(mockWs.url).toContain('sdk_version=0.6.1');
+    expect(mockWs.url).toContain(`sdk_version=${SDK_VERSION}`);
   });
 });
 
@@ -451,6 +492,111 @@ describe('StreamingSession', () => {
     expect(sessionClosedCalls[0].totalAudioChunks).toBe(4);
   });
 
+  it('fires onFinal (end-of-audio) before onSessionClosed on turn end (KUG-1238)', async () => {
+    const order: string[] = [];
+    let finalStats: { totalAudioSeconds: number; totalTextChunks: number; totalAudioChunks: number } | null = null;
+
+    const session = client.tts.streamingSession(
+      { voiceId: 1 },
+      {
+        onFinal: (totalAudioSeconds, totalTextChunks, totalAudioChunks) => {
+          order.push('final');
+          finalStats = { totalAudioSeconds, totalTextChunks, totalAudioChunks };
+        },
+        onSessionClosed: () => order.push('session_closed'),
+      },
+    );
+
+    session.connect();
+    await new Promise<void>((r) => setTimeout(r, 10));
+    session.send('Hello.', true);
+
+    mockWs.onmessage?.({ data: makeAudioMsg(0, 100) });
+    mockWs.onmessage?.({ data: makeChunkCompleteMsg(0, 1.0, 100) });
+    mockWs.onmessage?.({
+      data: JSON.stringify({
+        final: true,
+        total_audio_seconds: 1.0,
+        total_text_chunks: 1,
+        total_audio_chunks: 1,
+      }),
+    });
+    mockWs.onmessage?.({ data: makeSessionClosedMsg(1.0, 1, 1) });
+
+    expect(order).toEqual(['final', 'session_closed']);
+    expect(finalStats!.totalAudioSeconds).toBe(1.0);
+    expect(finalStats!.totalTextChunks).toBe(1);
+    expect(finalStats!.totalAudioChunks).toBe(1);
+  });
+
+  it('exposes typed per-session usage (cost charged) on lastUsage', async () => {
+    const session = client.tts.streamingSession({ voiceId: 1 }, {});
+    session.connect();
+    await new Promise<void>((r) => setTimeout(r, 10));
+    session.send('Hello.');
+
+    expect(session.lastUsage).toBeNull();
+
+    mockWs.onmessage?.({
+      data: JSON.stringify({
+        session_closed: true,
+        total_audio_seconds: 5.4,
+        usage: {
+          audio_seconds: 5.4,
+          characters: 142,
+          cost_cents: 0.49,
+          currency: 'eur',
+          model_id: 'kugel-3',
+        },
+      }),
+    });
+
+    expect(session.lastUsage).not.toBeNull();
+    expect(session.lastUsage?.audioSeconds).toBe(5.4);
+    expect(session.lastUsage?.characters).toBe(142);
+    expect(session.lastUsage?.costCents).toBe(0.49);
+    expect(session.lastUsage?.currency).toBe('eur');
+    expect(session.lastUsage?.modelId).toBe('kugel-3');
+    expect(session.lastUsage?.costAvailable).toBe(true);
+  });
+
+  it('reports cost as null (not zero) when the charge is unavailable', async () => {
+    const session = client.tts.streamingSession({ voiceId: 1 }, {});
+    session.connect();
+    await new Promise<void>((r) => setTimeout(r, 10));
+    session.send('Hi.');
+
+    mockWs.onmessage?.({
+      data: JSON.stringify({
+        session_closed: true,
+        total_audio_seconds: 2.0,
+        usage: {
+          audio_seconds: 2.0,
+          cost_cents: null,
+          cost_unavailable: true,
+          model_id: 'kugel-3',
+        },
+      }),
+    });
+
+    expect(session.lastUsage?.costCents).toBeNull();
+    expect(session.lastUsage?.costAvailable).toBe(false);
+    expect(session.lastUsage?.audioSeconds).toBe(2.0);
+  });
+
+  it('falls back to total_audio_seconds for a legacy server with no usage block', async () => {
+    const session = client.tts.streamingSession({ voiceId: 1 }, {});
+    session.connect();
+    await new Promise<void>((r) => setTimeout(r, 10));
+    session.send('Hi.');
+
+    mockWs.onmessage?.({ data: makeSessionClosedMsg(3.0, 1, 2) });
+
+    expect(session.lastUsage?.audioSeconds).toBe(3.0);
+    expect(session.lastUsage?.costCents).toBeNull();
+    expect(session.lastUsage?.costAvailable).toBe(false);
+  });
+
   it('resolves close() even if server never sends session_closed (quiet timeout)', async () => {
     const session = client.tts.streamingSession(
       { voiceId: 1 },
@@ -644,6 +790,55 @@ describe('StreamingSession', () => {
     expect(JSON.parse(mockWs.send.mock.calls[mockWs.send.mock.calls.length - 1][0] as string).voice_id).toBe(42);
   });
 
+  // -------------------------------------------------------------------------
+  // dictionaryIds — per-request dictionary selection (KUG-1094)
+  // -------------------------------------------------------------------------
+
+  it('first send carries dictionary_ids when configured', async () => {
+    const session = client.tts.streamingSession(
+      { voiceId: 1, dictionaryIds: [7, 9] },
+      {},
+    );
+
+    session.connect();
+    await new Promise<void>((r) => setTimeout(r, 10));
+
+    session.send('Hello.');
+    const sent = JSON.parse(
+      mockWs.send.mock.calls[mockWs.send.mock.calls.length - 1][0] as string
+    );
+    expect(sent.dictionary_ids).toEqual([7, 9]);
+  });
+
+  it('first send carries dictionary_ids: [] (explicit opt-out)', async () => {
+    const session = client.tts.streamingSession(
+      { voiceId: 1, dictionaryIds: [] },
+      {},
+    );
+
+    session.connect();
+    await new Promise<void>((r) => setTimeout(r, 10));
+
+    session.send('Hello.');
+    const sent = JSON.parse(
+      mockWs.send.mock.calls[mockWs.send.mock.calls.length - 1][0] as string
+    );
+    expect(sent.dictionary_ids).toEqual([]);
+  });
+
+  it('omits dictionary_ids when not configured', async () => {
+    const session = client.tts.streamingSession({ voiceId: 1 }, {});
+
+    session.connect();
+    await new Promise<void>((r) => setTimeout(r, 10));
+
+    session.send('Hello.');
+    const sent = JSON.parse(
+      mockWs.send.mock.calls[mockWs.send.mock.calls.length - 1][0] as string
+    );
+    expect(sent.dictionary_ids).toBeUndefined();
+  });
+
   it('cancelCurrent() resolves on quiet timeout if server never acks', async () => {
     const session = client.tts.streamingSession({ voiceId: 1 }, {});
 
@@ -724,4 +919,163 @@ describe('MultiContextSession closeContext', () => {
     expect((errors[0].error as RateLimitError).statusCode).toBe(429);
     expect((errors[0].error as RateLimitError).errorCode).toBe('TOO_MANY_CONTEXTS');
   });
+
+  it('fires onFinal per context on flush completion and graceful close (KUG-1238)', async () => {
+    const finals: string[] = [];
+    const closed: string[] = [];
+    const session = client.tts.createMultiContextSession({ defaultVoiceId: 1 });
+    await session.connect({
+      onFinal: (contextId) => finals.push(contextId),
+      onContextClosed: (contextId) => closed.push(contextId),
+    });
+
+    // Flush boundary: all audio admitted before the flush has been sent.
+    mockWs.onmessage?.({
+      data: JSON.stringify({ final: true, context_id: 'a' }),
+    });
+    expect(finals).toEqual(['a']);
+    expect(closed).toEqual([]);
+
+    // Graceful close: final precedes context_closed.
+    mockWs.onmessage?.({
+      data: JSON.stringify({ final: true, context_id: 'a' }),
+    });
+    mockWs.onmessage?.({
+      data: JSON.stringify({ context_closed: true, context_id: 'a' }),
+    });
+    expect(finals).toEqual(['a', 'a']);
+    expect(closed).toEqual(['a']);
+  });
+
+  it('exposes per-context usage on context_closed (per conversation)', async () => {
+    const closed: Array<{ id: string; usage: unknown }> = [];
+    const session = client.tts.createMultiContextSession({ defaultVoiceId: 1 });
+    await session.connect({
+      onContextClosed: (contextId, usage) => closed.push({ id: contextId, usage }),
+    });
+
+    mockWs.onmessage?.({
+      data: JSON.stringify({
+        context_closed: true,
+        context_id: 'narrator',
+        usage: { audio_seconds: 4.1, cost_cents: 0.37, currency: 'eur', model_id: 'kugel-3' },
+      }),
+    });
+
+    // Available both via the callback arg and the per-context accessor
+    expect(closed).toHaveLength(1);
+    expect(closed[0].id).toBe('narrator');
+    expect((closed[0].usage as { costCents: number }).costCents).toBe(0.37);
+
+    const u = session.usageFor('narrator');
+    expect(u?.audioSeconds).toBe(4.1);
+    expect(u?.costCents).toBe(0.37);
+    expect(u?.costAvailable).toBe(true);
+    expect(session.usageFor('missing')).toBeNull();
+  });
+});
+
+// ---------------------------------------------------------------------------
+// MultiContextSession createContext wire format (KUG-1233)
+//
+// The server binds a context's voice ONLY from voice_settings.voice_id at
+// context creation. A top-level voice_id updates session config and leaves
+// the context voiceless → MISSING_VOICE_ID on the first text. These tests
+// pin the wire format so it cannot silently regress.
+// ---------------------------------------------------------------------------
+
+describe('MultiContextSession createContext wire format (KUG-1233)', () => {
+  let client: KugelAudio;
+
+  beforeEach(() => {
+    client = new KugelAudio({ apiKey: 'test-key-xxx' });
+  });
+
+  it('puts voice_id inside voice_settings, never top-level', async () => {
+    const session = client.tts.createMultiContextSession({ defaultVoiceId: 42 });
+    await session.connect({});
+
+    session.createContext('narrator', { voiceId: 123 });
+
+    const sent = JSON.parse(
+      mockWs.send.mock.calls[mockWs.send.mock.calls.length - 1][0] as string
+    );
+    expect(sent.context_id).toBe('narrator');
+    expect(sent.voice_id).toBeUndefined();
+    expect(sent.voice_settings).toBeDefined();
+    expect(sent.voice_settings.voice_id).toBe(123);
+  });
+
+  it('falls back to defaultVoiceId inside voice_settings', async () => {
+    const session = client.tts.createMultiContextSession({ defaultVoiceId: 42 });
+    await session.connect({});
+
+    session.createContext('narrator');
+
+    const sent = JSON.parse(
+      mockWs.send.mock.calls[mockWs.send.mock.calls.length - 1][0] as string
+    );
+    expect(sent.voice_id).toBeUndefined();
+    expect(sent.voice_settings.voice_id).toBe(42);
+  });
+
+  it('send() to an unknown context auto-creates it with the default voice, even after session start', async () => {
+    const session = client.tts.createMultiContextSession({ defaultVoiceId: 42 });
+    await session.connect({});
+
+    // Simulate a started session (first context confirmed by the server).
+    session.createContext('first');
+    mockWs.onmessage?.({
+      data: JSON.stringify({ session_started: true, session_id: 's1' }),
+    });
+    mockWs.onmessage?.({
+      data: JSON.stringify({ context_created: true, context_id: 'first' }),
+    });
+
+    const callsBefore = mockWs.send.mock.calls.length;
+    session.send('second', 'hello there', true);
+    const frames = mockWs.send.mock.calls
+      .slice(callsBefore)
+      .map((c) => JSON.parse(c[0] as string));
+
+    // First frame: the auto-create with voice_settings.voice_id; then the text.
+    expect(frames).toHaveLength(2);
+    expect(frames[0].context_id).toBe('second');
+    expect(frames[0].voice_settings.voice_id).toBe(42);
+    expect(frames[1].text).toBe('hello there');
+    expect(frames[1].flush).toBe(true);
+  });
+
+  it('does not duplicate the create frame across repeated sends', async () => {
+    const session = client.tts.createMultiContextSession({ defaultVoiceId: 42 });
+    await session.connect({});
+
+    session.send('ctx', 'one');
+    session.send('ctx', 'two');
+
+    const frames = mockWs.send.mock.calls.map((c) => JSON.parse(c[0] as string));
+    const creates = frames.filter((f) => f.voice_settings?.voice_id === 42);
+    expect(creates).toHaveLength(1);
+  });
+
+  it('allows re-creating a context after the server closed it', async () => {
+    const session = client.tts.createMultiContextSession({ defaultVoiceId: 42 });
+    await session.connect({});
+
+    session.send('ctx', 'one');
+    mockWs.onmessage?.({
+      data: JSON.stringify({ context_created: true, context_id: 'ctx' }),
+    });
+    mockWs.onmessage?.({
+      data: JSON.stringify({ context_closed: true, context_id: 'ctx' }),
+    });
+
+    const callsBefore = mockWs.send.mock.calls.length;
+    session.send('ctx', 'again');
+    const frames = mockWs.send.mock.calls
+      .slice(callsBefore)
+      .map((c) => JSON.parse(c[0] as string));
+    expect(frames[0].voice_settings.voice_id).toBe(42);
+    expect(frames[1].text).toBe('again');
+  });
 });

package/src/client.ts

@@ -29,6 +29,7 @@ import type {
     VoiceReference,
     WordTimestamp
 } from './types';
+import { parseSessionUsage } from './types';
 import { base64ToArrayBuffer } from './utils';
 import { getWebSocket } from './websocket';
 
@@ -596,6 +597,7 @@ class TTSResource {
             generationMs: data.gen_ms,
             rtf: data.rtf,
             error: data.error,
+            usage: parseSessionUsage(data) ?? undefined,
           };
           pending.callbacks.onFinal?.(stats);
           this.pendingRequests.delete(requestId);
@@ -713,11 +715,15 @@ class TTSResource {
         ...(options.temperature !== undefined && { temperature: options.temperature }),
         max_new_tokens: options.maxNewTokens ?? 2048,
         sample_rate: options.sampleRate ?? 24000,
+        ...(options.outputFormat && { output_format: options.outputFormat }),
         normalize: options.normalize ?? true,
         ...(options.language && { language: options.language }),
         ...(options.wordTimestamps && { word_timestamps: true }),
         ...(options.speed !== undefined && { speed: options.speed }),
         ...(options.projectId !== undefined && { project_id: options.projectId }),
+        // [] is meaningful (explicit opt-out) and must be sent; only
+        // undefined (use the project default) is omitted.
+        ...(options.dictionaryIds !== undefined && { dictionary_ids: options.dictionaryIds }),
       }));
     });
   }
@@ -744,11 +750,15 @@ class TTSResource {
           cfg_scale: options.cfgScale ?? 2.0,
           max_new_tokens: options.maxNewTokens ?? 2048,
           sample_rate: options.sampleRate ?? 24000,
+          ...(options.outputFormat && { output_format: options.outputFormat }),
           normalize: options.normalize ?? true,
           ...(options.language && { language: options.language }),
           ...(options.wordTimestamps && { word_timestamps: true }),
           ...(options.speed !== undefined && { speed: options.speed }),
           ...(options.projectId !== undefined && { project_id: options.projectId }),
+          // [] is meaningful (explicit opt-out) and must be sent; only
+          // undefined (use the project default) is omitted.
+          ...(options.dictionaryIds !== undefined && { dictionary_ids: options.dictionaryIds }),
         }));
       };
 
@@ -779,6 +789,7 @@ class TTSResource {
               generationMs: data.gen_ms,
               rtf: data.rtf,
               error: data.error,
+              usage: parseSessionUsage(data) ?? undefined,
             };
             callbacks.onFinal?.(stats);
             ws.close();
@@ -977,7 +988,11 @@ class MultiContextSession {
   private config: import('./types').MultiContextConfig;
   private callbacks: import('./types').MultiContextCallbacks = {};
   private contexts: Set<string> = new Set();
+  /** Contexts a create message has been sent for (not yet necessarily
+   *  confirmed by the server via context_created). */
+  private requestedContexts: Set<string> = new Set();
   private _sessionId: string | null = null;
+  private _contextUsage: Map<string, import('./types').SessionUsage> = new Map();
   private isStarted = false;
 
   constructor(
@@ -994,6 +1009,20 @@ class MultiContextSession {
     return this._sessionId;
   }
 
+  /**
+   * Per-context usage (audio time + amount charged) for a closed context, or
+   * null if that context hasn't closed yet. Each context is its own
+   * conversation — use this to bill per conversation. See {@link SessionUsage}.
+   */
+  usageFor(contextId: string): import('./types').SessionUsage | null {
+    return this._contextUsage.get(contextId) ?? null;
+  }
+
+  /** Map of context_id → per-context usage for all closed contexts. */
+  get contextUsage(): Map<string, import('./types').SessionUsage> {
+    return new Map(this._contextUsage);
+  }
+
   /**
    * Connect to the multi-context WebSocket endpoint.
    *
@@ -1063,13 +1092,25 @@ class MultiContextSession {
           this.callbacks.onChunk?.(chunk);
         }
 
+        if (data.final && data.context_id) {
+          // Per-context end-of-audio marker (KUG-1238): all audio admitted
+          // before the client's flush has been delivered; also precedes
+          // context_closed on a graceful close.
+          this.callbacks.onFinal?.(data.context_id);
+        }
+
         if (data.context_closed) {
           this.contexts.delete(data.context_id);
-          this.callbacks.onContextClosed?.(data.context_id);
+          this.requestedContexts.delete(data.context_id);
+          // Per-context (per-conversation) usage rides on context_closed.
+          const ctxUsage = parseSessionUsage(data) ?? undefined;
+          if (ctxUsage) this._contextUsage.set(data.context_id, ctxUsage);
+          this.callbacks.onContextClosed?.(data.context_id, ctxUsage);
         }
 
         if (data.context_timeout) {
           this.contexts.delete(data.context_id);
+          this.requestedContexts.delete(data.context_id);
           this.callbacks.onContextTimeout?.(data.context_id);
         }
 
@@ -1124,6 +1165,7 @@ class MultiContextSession {
         this.ws = null;
         this.isStarted = false;
         this.contexts.clear();
+        this.requestedContexts.clear();
       };
     });
   }
@@ -1141,6 +1183,7 @@ class MultiContextSession {
     if (!this.ws || this.ws.readyState !== WS_OPEN) {
       throw new KugelAudioError('WebSocket not connected');
     }
+    this.requestedContexts.add(contextId);
 
     const msg: Record<string, unknown> = {
       text: ' ',
@@ -1151,26 +1194,36 @@ class MultiContextSession {
     if (!this.isStarted) {
       warnIfNoLanguage(this.config.language, this.config.normalize);
       if (this.config.sampleRate) msg.sample_rate = this.config.sampleRate;
+      if (this.config.outputFormat) msg.output_format = this.config.outputFormat;
       if (this.config.cfgScale) msg.cfg_scale = this.config.cfgScale;
       if (this.config.temperature !== undefined) msg.temperature = this.config.temperature;
       if (this.config.maxNewTokens) msg.max_new_tokens = this.config.maxNewTokens;
       if (this.config.normalize !== undefined) msg.normalize = this.config.normalize;
       if (this.config.language) msg.language = this.config.language;
+      // [] is meaningful (explicit opt-out) and must be sent; only
+      // undefined (use the project default) is omitted.
+      if (this.config.dictionaryIds !== undefined) msg.dictionary_ids = this.config.dictionaryIds;
       if (this.config.inactivityTimeout) msg.inactivity_timeout = this.config.inactivityTimeout;
     }
 
-    // Per-context voice
+    // Per-context voice. The server binds a context's voice ONLY from
+    // voice_settings.voice_id at context creation — a top-level voice_id
+    // merely updates the session config and leaves the context voiceless,
+    // which the server rejects with MISSING_VOICE_ID on the first text
+    // (KUG-1233). This matches the Python SDK's wire format.
+    const voiceSettings: Record<string, unknown> = {};
     const voiceId = options?.voiceId || this.config.defaultVoiceId;
-    if (voiceId) msg.voice_id = voiceId;
+    if (voiceId) voiceSettings.voice_id = voiceId;
 
     if (options?.voiceSettings) {
-      msg.voice_settings = {
-        stability: options.voiceSettings.stability,
-        similarity_boost: options.voiceSettings.similarityBoost,
-        style: options.voiceSettings.style,
-        use_speaker_boost: options.voiceSettings.useSpeakerBoost,
-        speed: options.voiceSettings.speed,
-      };
+      voiceSettings.stability = options.voiceSettings.stability;
+      voiceSettings.similarity_boost = options.voiceSettings.similarityBoost;
+      voiceSettings.style = options.voiceSettings.style;
+      voiceSettings.use_speaker_boost = options.voiceSettings.useSpeakerBoost;
+      voiceSettings.speed = options.voiceSettings.speed;
+    }
+    if (Object.keys(voiceSettings).length > 0) {
+      msg.voice_settings = voiceSettings;
     }
 
     this.ws.send(JSON.stringify(msg));
@@ -1184,8 +1237,12 @@ class MultiContextSession {
       throw new KugelAudioError('WebSocket not connected');
     }
 
-    // Auto-create context if needed
-    if (!this.contexts.has(contextId) && !this.isStarted) {
+    // Auto-create context if needed. Tracked via requestedContexts (sent
+    // creates, not yet necessarily confirmed) rather than this.contexts
+    // (server-confirmed) — otherwise a send() to a new context after the
+    // session started goes out bare, and the server auto-creates the
+    // context without voice_settings → MISSING_VOICE_ID (KUG-1233).
+    if (!this.requestedContexts.has(contextId) && !this.contexts.has(contextId)) {
       this.createContext(contextId);
     }
 
@@ -1251,6 +1308,7 @@ class MultiContextSession {
     this.ws = null;
     this.isStarted = false;
     this.contexts.clear();
+    this.requestedContexts.clear();
   }
 
   /**
@@ -1303,6 +1361,7 @@ class StreamingSession {
   private callbacks: StreamingSessionCallbacks;
   private client: KugelAudio;
   private configSent = false;
+  private _lastUsage: import('./types').SessionUsage | null = null;
 
   constructor(client: KugelAudio, config: StreamConfig, callbacks: StreamingSessionCallbacks) {
     this.client = client;
@@ -1310,6 +1369,15 @@ class StreamingSession {
     this.callbacks = callbacks;
   }
 
+  /**
+   * Per-session usage from the most recently closed session, or null before
+   * the first session closes. Use this to bill your own customers per
+   * conversation. See {@link SessionUsage}.
+   */
+  get lastUsage(): import('./types').SessionUsage | null {
+    return this._lastUsage;
+  }
+
   /**
    * Open the WebSocket connection and authenticate.
    *
@@ -1389,7 +1457,18 @@ class StreamingSession {
           this.callbacks.onInterrupted?.();
         }
 
+        if (data.final) {
+          // End-of-audio marker for the turn (KUG-1238) — arrives after
+          // the last audio frame and before session_closed.
+          this.callbacks.onFinal?.(
+            data.total_audio_seconds ?? 0,
+            data.total_text_chunks ?? 0,
+            data.total_audio_chunks ?? 0,
+          );
+        }
+
         if (data.session_closed) {
+          this._lastUsage = parseSessionUsage(data);
           this.callbacks.onSessionClosed?.(
             data.total_audio_seconds ?? 0,
             data.total_text_chunks ?? 0,
@@ -1474,6 +1553,7 @@ class StreamingSession {
       if (this.config.temperature !== undefined) msg.temperature = this.config.temperature;
       if (this.config.maxNewTokens !== undefined) msg.max_new_tokens = this.config.maxNewTokens;
       if (this.config.sampleRate !== undefined) msg.sample_rate = this.config.sampleRate;
+      if (this.config.outputFormat !== undefined) msg.output_format = this.config.outputFormat;
       if (this.config.flushTimeoutMs !== undefined) msg.flush_timeout_ms = this.config.flushTimeoutMs;
       if (this.config.maxBufferLength !== undefined) msg.max_buffer_length = this.config.maxBufferLength;
       if (this.config.normalize !== undefined) msg.normalize = this.config.normalize;
@@ -1482,6 +1562,9 @@ class StreamingSession {
       if (this.config.autoMode !== undefined) msg.auto_mode = this.config.autoMode;
       if (this.config.chunkLengthSchedule?.length) msg.chunk_length_schedule = this.config.chunkLengthSchedule;
       if (this.config.speed !== undefined) msg.speed = this.config.speed;
+      // [] is meaningful (explicit opt-out) and must be sent; only
+      // undefined (use the project default) is omitted.
+      if (this.config.dictionaryIds !== undefined) msg.dictionary_ids = this.config.dictionaryIds;
       this.configSent = true;
     }
 

package/src/index.ts

@@ -62,6 +62,7 @@ export type {
     MultiContextAudioChunk,
     MultiContextCallbacks,
     MultiContextConfig,
+    SessionUsage,
     StreamCallbacks,
     StreamConfig,
     StreamingSessionCallbacks,
@@ -78,6 +79,7 @@ export type {
     VoiceSex,
     WordTimestamp
 } from './types';
+export { parseSessionUsage } from './types';
 
 export { DictionariesResource, DictionaryEntriesResource } from './dictionaries';