kugelaudio 0.7.0 → 0.9.0

package/dist/index.mjs

@@ -1,9 +1,25 @@
-var __require = /* @__PURE__ */ ((x) => typeof require !== "undefined" ? require : typeof Proxy !== "undefined" ? new Proxy(x, {
-  get: (a, b) => (typeof require !== "undefined" ? require : a)[b]
-}) : x)(function(x) {
-  if (typeof require !== "undefined") return require.apply(this, arguments);
-  throw Error('Dynamic require of "' + x + '" is not supported');
-});
+import {
+  AuthenticationError,
+  ConnectionError,
+  ErrorCodes,
+  InsufficientCreditsError,
+  KugelAudioError,
+  NotFoundError,
+  RateLimitError,
+  ValidationError,
+  WsCloseCodes,
+  __require,
+  base64ToArrayBuffer,
+  clampCfgScale,
+  classifyHttpError,
+  classifyWsClose,
+  classifyWsFrame,
+  classifyWsHandshakeError,
+  createWavBlob,
+  createWavFile,
+  decodePCM16,
+  package_default
+} from "./chunk-CB3B6T7F.mjs";
 
 // src/dictionaries.ts
 function mapDictionary(raw) {
@@ -186,265 +202,21 @@ var DictionariesResource = class {
   }
 };
 
-// src/errors.ts
-var ErrorCodes = {
-  UNAUTHORIZED: "UNAUTHORIZED",
-  RATE_LIMITED: "RATE_LIMITED",
-  INSUFFICIENT_CREDITS: "INSUFFICIENT_CREDITS",
-  MODEL_UNAVAILABLE: "MODEL_UNAVAILABLE",
-  EMPTY_AUDIO: "EMPTY_AUDIO",
-  VALIDATION: "VALIDATION_ERROR",
-  INTERNAL: "INTERNAL_ERROR",
-  NOT_FOUND: "NOT_FOUND",
-  MISSING_VOICE_ID: "MISSING_VOICE_ID",
-  TOO_MANY_CONTEXTS: "TOO_MANY_CONTEXTS"
-};
-var WsCloseCodes = {
-  UNAUTHORIZED: 4001,
-  INSUFFICIENT_CREDITS: 4003,
-  RATE_LIMITED: 4029,
-  MODEL_UNAVAILABLE: 4500
-};
-var API_KEYS_URL = "https://app.kugelaudio.com/settings/api-keys";
-var BILLING_URL = "https://app.kugelaudio.com/billing";
-var KugelAudioError = class _KugelAudioError extends Error {
-  constructor(message, options = {}) {
-    super(options.requestId ? `${message} (request_id: ${options.requestId})` : message);
-    this.name = "KugelAudioError";
-    this.statusCode = options.statusCode;
-    this.errorCode = options.errorCode;
-    this.requestId = options.requestId;
-    this.retryAfter = options.retryAfter;
-    Object.setPrototypeOf(this, _KugelAudioError.prototype);
-  }
-};
-var AuthenticationError = class _AuthenticationError extends KugelAudioError {
-  constructor(message, options = {}) {
-    super(
-      message ?? `KugelAudio rejected the API key. Check it is current at ${API_KEYS_URL}.`,
-      { statusCode: 401, errorCode: ErrorCodes.UNAUTHORIZED, ...options }
-    );
-    this.name = "AuthenticationError";
-    Object.setPrototypeOf(this, _AuthenticationError.prototype);
-  }
-};
-var RateLimitError = class _RateLimitError extends KugelAudioError {
-  constructor(message, options = {}) {
-    const msg = message ?? (options.retryAfter ? `KugelAudio rate limit hit; retry after ${options.retryAfter}s.` : "KugelAudio rate limit hit; retry shortly.");
-    super(msg, { statusCode: 429, errorCode: ErrorCodes.RATE_LIMITED, ...options });
-    this.name = "RateLimitError";
-    Object.setPrototypeOf(this, _RateLimitError.prototype);
-  }
-};
-var InsufficientCreditsError = class _InsufficientCreditsError extends KugelAudioError {
-  constructor(message, options = {}) {
-    super(
-      message ?? `Your KugelAudio account is out of credits. Top up at ${BILLING_URL}.`,
-      { statusCode: 402, errorCode: ErrorCodes.INSUFFICIENT_CREDITS, ...options }
-    );
-    this.name = "InsufficientCreditsError";
-    Object.setPrototypeOf(this, _InsufficientCreditsError.prototype);
-  }
-};
-var ValidationError = class _ValidationError extends KugelAudioError {
-  constructor(message, options = {}) {
-    super(message, { statusCode: 400, errorCode: ErrorCodes.VALIDATION, ...options });
-    this.name = "ValidationError";
-    Object.setPrototypeOf(this, _ValidationError.prototype);
-  }
-};
-var ConnectionError = class _ConnectionError extends KugelAudioError {
-  constructor(message, options = {}) {
-    super(message, { statusCode: 503, ...options });
-    this.name = "ConnectionError";
-    Object.setPrototypeOf(this, _ConnectionError.prototype);
-  }
-};
-var NotFoundError = class _NotFoundError extends KugelAudioError {
-  constructor(message, options = {}) {
-    super(message ?? "Not found.", {
-      statusCode: 404,
-      errorCode: ErrorCodes.NOT_FOUND,
-      ...options
-    });
-    this.name = "NotFoundError";
-    Object.setPrototypeOf(this, _NotFoundError.prototype);
-  }
-};
-function build(status, errorCode, message, opts = {}) {
-  const common = { ...opts };
-  if (status !== void 0) common.statusCode = status;
-  if (errorCode !== void 0) common.errorCode = errorCode;
-  if (errorCode === ErrorCodes.UNAUTHORIZED || status === 401) {
-    return new AuthenticationError(message || void 0, common);
-  }
-  if (errorCode === ErrorCodes.INSUFFICIENT_CREDITS || status === 402) {
-    return new InsufficientCreditsError(message || void 0, common);
-  }
-  if (errorCode === ErrorCodes.RATE_LIMITED || errorCode === ErrorCodes.TOO_MANY_CONTEXTS || status === 429) {
-    return new RateLimitError(message || void 0, common);
-  }
-  if (errorCode === ErrorCodes.VALIDATION || errorCode === ErrorCodes.MISSING_VOICE_ID || status === 400) {
-    return new ValidationError(message || "Request validation failed.", common);
-  }
-  if (errorCode === ErrorCodes.MODEL_UNAVAILABLE || status === 503) {
-    const detail = message || "service temporarily unavailable";
-    return new ConnectionError(
-      `KugelAudio is temporarily unavailable: ${detail}. Retry shortly.`,
-      common
-    );
-  }
-  if (errorCode === ErrorCodes.NOT_FOUND || status === 404) {
-    return new NotFoundError(message || void 0, common);
-  }
-  return new KugelAudioError(message || `HTTP ${status}`, common);
-}
-function readHeader(headers, name) {
-  if (headers && typeof headers.get === "function") {
-    return headers.get(name) ?? void 0;
-  }
-  const rec = headers;
-  return rec[name] ?? rec[name.toLowerCase()] ?? void 0;
-}
-function classifyHttpError(status, bodyText, headers) {
-  let errorCode;
-  let message = "";
-  let retryAfter;
-  if (bodyText) {
-    try {
-      const body = JSON.parse(bodyText);
-      if (body && typeof body === "object") {
-        errorCode = typeof body.error_code === "string" ? body.error_code : void 0;
-        const msg = body.error ?? body.detail;
-        if (Array.isArray(msg)) {
-          message = msg.map((m) => String(m)).join("; ");
-        } else if (typeof msg === "string") {
-          message = msg;
-        }
-        if (typeof body.retry_after === "number") {
-          retryAfter = body.retry_after;
-        }
-      }
-    } catch {
-    }
-  }
-  if (retryAfter === void 0) {
-    const header = readHeader(headers, "Retry-After") ?? readHeader(headers, "retry-after");
-    if (header) {
-      const n = Number(header);
-      if (Number.isFinite(n)) retryAfter = n;
-    }
-  }
-  const requestId = readHeader(headers, "x-request-id") ?? readHeader(headers, "X-Request-Id");
-  if (!message) {
-    message = (bodyText || "").trim();
-  }
-  return build(status, errorCode, message, { requestId, retryAfter });
-}
-function classifyWsFrame(data) {
-  const errorCode = data.error_code;
-  const message = data.error ?? "Server reported an error.";
-  const status = typeof data.code === "number" ? data.code : void 0;
-  const retryAfter = typeof data.retry_after === "number" ? data.retry_after : void 0;
-  return build(status, errorCode, message, { retryAfter });
-}
-function classifyWsClose(code, reason) {
-  const reasonTxt = (reason ?? "").trim();
-  if (code === WsCloseCodes.UNAUTHORIZED) {
-    let msg = `KugelAudio rejected the API key. Check it is current at ${API_KEYS_URL}.`;
-    if (reasonTxt) msg = `${msg} (${reasonTxt})`;
-    return new AuthenticationError(msg);
-  }
-  if (code === WsCloseCodes.INSUFFICIENT_CREDITS) {
-    return new InsufficientCreditsError();
-  }
-  if (code === WsCloseCodes.RATE_LIMITED) {
-    return new RateLimitError();
-  }
-  if (code === WsCloseCodes.MODEL_UNAVAILABLE) {
-    const suffix = reasonTxt ? ` (${reasonTxt})` : "";
-    return new ConnectionError(
-      `KugelAudio model is temporarily unavailable. Retry shortly.${suffix}`
-    );
-  }
-  const detail = reasonTxt || "no reason given";
-  const codeStr = code !== void 0 ? ` (code ${code})` : "";
-  return new ConnectionError(
-    `KugelAudio WebSocket closed by server: ${detail}${codeStr}.`
-  );
-}
-function classifyWsHandshakeError(err) {
-  if (!err || typeof err !== "object") return null;
-  const e = err;
-  let status;
-  if (typeof e.statusCode === "number") {
-    status = e.statusCode;
-  }
-  if (status === void 0 && typeof e.message === "string") {
-    const m = e.message.match(/Unexpected server response:\s*(\d{3})/i);
-    if (m) status = Number(m[1]);
-  }
-  if (status === void 0) return null;
-  if (status === 403) {
-    return new AuthenticationError();
-  }
-  return build(status, void 0, typeof e.message === "string" ? e.message : "");
-}
-
-// src/utils.ts
-function base64ToArrayBuffer(base64) {
-  if (typeof atob === "function") {
-    const binary = atob(base64);
-    const bytes = new Uint8Array(binary.length);
-    for (let i = 0; i < binary.length; i++) {
-      bytes[i] = binary.charCodeAt(i);
-    }
-    return bytes.buffer;
-  } else {
-    const buffer = Buffer.from(base64, "base64");
-    return buffer.buffer.slice(buffer.byteOffset, buffer.byteOffset + buffer.byteLength);
-  }
-}
-function decodePCM16(base64) {
-  const buffer = base64ToArrayBuffer(base64);
-  const int16 = new Int16Array(buffer);
-  const float32 = new Float32Array(int16.length);
-  for (let i = 0; i < int16.length; i++) {
-    float32[i] = int16[i] / 32768;
-  }
-  return float32;
-}
-function createWavFile(audio, sampleRate) {
-  const dataSize = audio.byteLength;
-  const fileSize = 44 + dataSize;
-  const buffer = new ArrayBuffer(fileSize);
-  const view = new DataView(buffer);
-  writeString(view, 0, "RIFF");
-  view.setUint32(4, fileSize - 8, true);
-  writeString(view, 8, "WAVE");
-  writeString(view, 12, "fmt ");
-  view.setUint32(16, 16, true);
-  view.setUint16(20, 1, true);
-  view.setUint16(22, 1, true);
-  view.setUint32(24, sampleRate, true);
-  view.setUint32(28, sampleRate * 2, true);
-  view.setUint16(32, 2, true);
-  view.setUint16(34, 16, true);
-  writeString(view, 36, "data");
-  view.setUint32(40, dataSize, true);
-  const audioBytes = new Uint8Array(audio);
-  const wavBytes = new Uint8Array(buffer);
-  wavBytes.set(audioBytes, 44);
-  return buffer;
-}
-function writeString(view, offset, str) {
-  for (let i = 0; i < str.length; i++) {
-    view.setUint8(offset + i, str.charCodeAt(i));
-  }
-}
-function createWavBlob(audio, sampleRate) {
-  const wavBuffer = createWavFile(audio, sampleRate);
-  return new Blob([wavBuffer], { type: "audio/wav" });
+// src/types.ts
+function parseSessionUsage(data) {
+  const raw = data.usage;
+  const source = raw && typeof raw === "object" ? raw : data;
+  const audioSeconds = typeof source.audio_seconds === "number" ? source.audio_seconds : typeof data.total_audio_seconds === "number" ? data.total_audio_seconds : void 0;
+  if (audioSeconds === void 0) return null;
+  const costCents = typeof source.cost_cents === "number" ? source.cost_cents : null;
+  return {
+    audioSeconds,
+    costCents,
+    currency: typeof source.currency === "string" ? source.currency : void 0,
+    characters: typeof source.characters === "number" ? source.characters : void 0,
+    modelId: typeof source.model_id === "string" ? source.model_id : void 0,
+    costAvailable: costCents !== null
+  };
 }
 
 // src/websocket.ts
@@ -474,69 +246,6 @@ function getWebSocket() {
   );
 }
 
-// package.json
-var package_default = {
-  name: "kugelaudio",
-  version: "0.7.0",
-  description: "Official JavaScript/TypeScript SDK for KugelAudio TTS API",
-  main: "dist/index.js",
-  module: "dist/index.mjs",
-  types: "dist/index.d.ts",
-  exports: {
-    ".": {
-      types: "./dist/index.d.ts",
-      import: "./dist/index.mjs",
-      require: "./dist/index.js"
-    }
-  },
-  files: [
-    "dist",
-    "src",
-    "LICENSE",
-    "CHANGELOG.md"
-  ],
-  scripts: {
-    build: "tsup src/index.ts --format cjs,esm --dts",
-    dev: "tsup src/index.ts --format cjs,esm --dts --watch",
-    lint: "eslint src/",
-    test: "vitest run",
-    "test:watch": "vitest",
-    prepublishOnly: "npm run build"
-  },
-  keywords: [
-    "tts",
-    "text-to-speech",
-    "audio",
-    "streaming",
-    "websocket",
-    "kugelaudio"
-  ],
-  author: "KugelAudio <hello@kugelaudio.com>",
-  license: "MIT",
-  repository: {
-    type: "git",
-    url: "https://github.com/Kugelaudio/KugelAudio",
-    directory: "sdks/js"
-  },
-  homepage: "https://kugelaudio.com",
-  bugs: {
-    url: "https://github.com/Kugelaudio/KugelAudio/issues"
-  },
-  devDependencies: {
-    "@types/node": "^25.3.2",
-    tsup: "^8.0.0",
-    typescript: "^6.0.2",
-    vitest: "^4.0.18"
-  },
-  engines: {
-    node: ">=18.0.0"
-  },
-  dependencies: {
-    tsx: "^4.21.0",
-    ws: "^8.18.0"
-  }
-};
-
 // src/client.ts
 var DEFAULT_API_URL = "https://api.kugelaudio.com";
 var EU_API_URL = "https://api.eu.kugelaudio.com";
@@ -567,6 +276,105 @@ function createWs(url) {
   return new WS(url);
 }
 var WS_OPEN = 1;
+var UPDATABLE_SETTINGS = {
+  cfgScale: "cfg_scale",
+  temperature: "temperature",
+  speed: "speed",
+  maxNewTokens: "max_new_tokens",
+  language: "language",
+  normalize: "normalize"
+};
+function buildSettingsUpdateBody(settings) {
+  const body = {};
+  for (const camel of Object.keys(UPDATABLE_SETTINGS)) {
+    const value = settings[camel];
+    if (value !== void 0) body[UPDATABLE_SETTINGS[camel]] = value;
+  }
+  if (Object.keys(body).length === 0) {
+    throw new KugelAudioError(
+      `updateSettings requires at least one parameter to change (one of ${Object.keys(UPDATABLE_SETTINGS).join(", ")})`
+    );
+  }
+  return body;
+}
+function parseEffectiveSettings(raw) {
+  const s = raw && typeof raw === "object" ? raw : {};
+  return {
+    cfgScale: s.cfg_scale,
+    temperature: s.temperature,
+    speed: s.speed,
+    maxNewTokens: s.max_new_tokens,
+    language: s.language,
+    normalize: s.normalize
+  };
+}
+function applyAcceptedSettingsUpdate(config, settings) {
+  for (const camel of Object.keys(UPDATABLE_SETTINGS)) {
+    if (settings[camel] !== void 0) {
+      config[camel] = settings[camel];
+    }
+  }
+}
+function sendUpdateSettings(ws, body) {
+  const QUIET_TIMEOUT_MS = 15e3;
+  return new Promise((resolve, reject) => {
+    let settled = false;
+    let timer;
+    const prevMessage = ws.onmessage;
+    const prevClose = ws.onclose;
+    const finish = (action) => {
+      if (settled) return;
+      settled = true;
+      clearTimeout(timer);
+      ws.onmessage = prevMessage;
+      ws.onclose = prevClose;
+      action();
+    };
+    const armQuietTimer = () => {
+      clearTimeout(timer);
+      timer = setTimeout(
+        () => finish(
+          () => reject(
+            new KugelAudioError(
+              "Timed out waiting for settings_updated acknowledgement"
+            )
+          )
+        ),
+        QUIET_TIMEOUT_MS
+      );
+    };
+    armQuietTimer();
+    ws.onmessage = (event) => {
+      armQuietTimer();
+      let data = null;
+      try {
+        const raw = typeof event.data === "string" ? event.data : event.data instanceof Buffer ? event.data.toString() : String(event.data);
+        data = JSON.parse(raw);
+      } catch {
+      }
+      if (data?.settings_updated) {
+        finish(() => resolve(parseEffectiveSettings(data.settings)));
+        return;
+      }
+      if (data?.error) {
+        finish(() => reject(new KugelAudioError(String(data.error))));
+        return;
+      }
+      if (prevMessage) prevMessage.call(ws, event);
+    };
+    ws.onclose = (event) => {
+      if (prevClose) prevClose.call(ws, event);
+      finish(
+        () => reject(
+          new ConnectionError(
+            "WebSocket closed before settings_updated acknowledgement"
+          )
+        )
+      );
+    };
+    ws.send(JSON.stringify({ update_settings: body }));
+  });
+}
 var _languageWarningLogged = false;
 function warnIfNoLanguage(language, normalize) {
   const normEnabled = normalize === void 0 || normalize;
@@ -622,6 +430,7 @@ var VoicesResource = class {
         category: v.category,
         sex: v.sex,
         age: v.age,
+        quality: v.quality,
         supportedLanguages: v.supported_languages || [],
         sampleText: v.sample_text,
         avatarUrl: v.avatar_url,
@@ -993,7 +802,8 @@ var TTSResource = class {
             durationMs: data.dur_ms,
             generationMs: data.gen_ms,
             rtf: data.rtf,
-            error: data.error
+            error: data.error,
+            usage: parseSessionUsage(data) ?? void 0
           };
           pending.callbacks.onFinal?.(stats);
           this.pendingRequests.delete(requestId);
@@ -1080,15 +890,19 @@ var TTSResource = class {
         text: options.text,
         model_id: options.modelId || "kugel-3",
         voice_id: options.voiceId,
-        cfg_scale: options.cfgScale ?? 2,
+        cfg_scale: clampCfgScale(options.cfgScale) ?? 2,
         ...options.temperature !== void 0 && { temperature: options.temperature },
         max_new_tokens: options.maxNewTokens ?? 2048,
         sample_rate: options.sampleRate ?? 24e3,
+        ...options.outputFormat && { output_format: options.outputFormat },
         normalize: options.normalize ?? true,
         ...options.language && { language: options.language },
         ...options.wordTimestamps && { word_timestamps: true },
         ...options.speed !== void 0 && { speed: options.speed },
-        ...options.projectId !== void 0 && { project_id: options.projectId }
+        ...options.projectId !== void 0 && { project_id: options.projectId },
+        // [] is meaningful (explicit opt-out) and must be sent; only
+        // undefined (use the project default) is omitted.
+        ...options.dictionaryIds !== void 0 && { dictionary_ids: options.dictionaryIds }
       }));
     });
   }
@@ -1106,14 +920,18 @@ var TTSResource = class {
           text: options.text,
           model_id: options.modelId || "kugel-3",
           voice_id: options.voiceId,
-          cfg_scale: options.cfgScale ?? 2,
+          cfg_scale: clampCfgScale(options.cfgScale) ?? 2,
           max_new_tokens: options.maxNewTokens ?? 2048,
           sample_rate: options.sampleRate ?? 24e3,
+          ...options.outputFormat && { output_format: options.outputFormat },
           normalize: options.normalize ?? true,
           ...options.language && { language: options.language },
           ...options.wordTimestamps && { word_timestamps: true },
           ...options.speed !== void 0 && { speed: options.speed },
-          ...options.projectId !== void 0 && { project_id: options.projectId }
+          ...options.projectId !== void 0 && { project_id: options.projectId },
+          // [] is meaningful (explicit opt-out) and must be sent; only
+          // undefined (use the project default) is omitted.
+          ...options.dictionaryIds !== void 0 && { dictionary_ids: options.dictionaryIds }
         }));
       };
       ws.onmessage = (event) => {
@@ -1135,7 +953,8 @@ var TTSResource = class {
               durationMs: data.dur_ms,
               generationMs: data.gen_ms,
               rtf: data.rtf,
-              error: data.error
+              error: data.error,
+              usage: parseSessionUsage(data) ?? void 0
             };
             callbacks.onFinal?.(stats);
             ws.close();
@@ -1305,7 +1124,11 @@ var MultiContextSession = class {
     this.ws = null;
     this.callbacks = {};
     this.contexts = /* @__PURE__ */ new Set();
+    /** Contexts a create message has been sent for (not yet necessarily
+     *  confirmed by the server via context_created). */
+    this.requestedContexts = /* @__PURE__ */ new Set();
     this._sessionId = null;
+    this._contextUsage = /* @__PURE__ */ new Map();
     this.isStarted = false;
     this.config = config || {};
   }
@@ -1315,6 +1138,18 @@ var MultiContextSession = class {
   get sessionId() {
     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) {
+    return this._contextUsage.get(contextId) ?? null;
+  }
+  /** Map of context_id → per-context usage for all closed contexts. */
+  get contextUsage() {
+    return new Map(this._contextUsage);
+  }
   /**
    * Connect to the multi-context WebSocket endpoint.
    *
@@ -1368,12 +1203,19 @@ var MultiContextSession = class {
           };
           this.callbacks.onChunk?.(chunk);
         }
+        if (data.final && data.context_id) {
+          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);
+          const ctxUsage = parseSessionUsage(data) ?? void 0;
+          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);
         }
         if (data.session_closed) {
@@ -1413,6 +1255,7 @@ var MultiContextSession = class {
         this.ws = null;
         this.isStarted = false;
         this.contexts.clear();
+        this.requestedContexts.clear();
       };
     });
   }
@@ -1423,6 +1266,7 @@ var MultiContextSession = class {
     if (!this.ws || this.ws.readyState !== WS_OPEN) {
       throw new KugelAudioError("WebSocket not connected");
     }
+    this.requestedContexts.add(contextId);
     const msg = {
       text: " ",
       context_id: contextId
@@ -1430,23 +1274,27 @@ var MultiContextSession = class {
     if (!this.isStarted) {
       warnIfNoLanguage(this.config.language, this.config.normalize);
       if (this.config.sampleRate) msg.sample_rate = this.config.sampleRate;
-      if (this.config.cfgScale) msg.cfg_scale = this.config.cfgScale;
+      if (this.config.outputFormat) msg.output_format = this.config.outputFormat;
+      if (this.config.cfgScale !== void 0) msg.cfg_scale = clampCfgScale(this.config.cfgScale);
       if (this.config.temperature !== void 0) msg.temperature = this.config.temperature;
       if (this.config.maxNewTokens) msg.max_new_tokens = this.config.maxNewTokens;
       if (this.config.normalize !== void 0) msg.normalize = this.config.normalize;
       if (this.config.language) msg.language = this.config.language;
+      if (this.config.dictionaryIds !== void 0) msg.dictionary_ids = this.config.dictionaryIds;
       if (this.config.inactivityTimeout) msg.inactivity_timeout = this.config.inactivityTimeout;
     }
+    const voiceSettings = {};
     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));
   }
@@ -1457,7 +1305,7 @@ var MultiContextSession = class {
     if (!this.ws || this.ws.readyState !== WS_OPEN) {
       throw new KugelAudioError("WebSocket not connected");
     }
-    if (!this.contexts.has(contextId) && !this.isStarted) {
+    if (!this.requestedContexts.has(contextId) && !this.contexts.has(contextId)) {
       this.createContext(contextId);
     }
     this.ws.send(JSON.stringify({
@@ -1504,6 +1352,33 @@ var MultiContextSession = class {
       context_id: contextId
     }));
   }
+  /**
+   * Change the session's generation parameters mid-connection (KUG-1166).
+   *
+   * Session-scoped (there is no `contextId`): the update applies to contexts
+   * started **after** it — a context already streaming keeps the settings it
+   * began with, since generation parameters are bound when a context's engine
+   * session opens. With the common one-context-per-turn pattern that means it
+   * takes effect on the next turn. Per-context `cfgScale` / `maxNewTokens`
+   * passed to {@link createContext} still win for that context.
+   *
+   * Resolves with the generation parameters now in effect (the server's echo).
+   *
+   * @throws {KugelAudioError} if no field is provided, the socket is not open,
+   *   or the server rejects the update.
+   */
+  updateSettings(settings) {
+    if (!this.ws || this.ws.readyState !== WS_OPEN) {
+      throw new KugelAudioError(
+        "MultiContextSession not connected. Call connect() first."
+      );
+    }
+    const body = buildSettingsUpdateBody(settings);
+    return sendUpdateSettings(this.ws, body).then((effective) => {
+      applyAcceptedSettingsUpdate(this.config, settings);
+      return effective;
+    });
+  }
   /**
    * Close the session and all contexts.
    */
@@ -1515,6 +1390,7 @@ var MultiContextSession = class {
     this.ws = null;
     this.isStarted = false;
     this.contexts.clear();
+    this.requestedContexts.clear();
   }
   /**
    * Get active context IDs.
@@ -1533,10 +1409,19 @@ var StreamingSession = class {
   constructor(client, config, callbacks) {
     this.ws = null;
     this.configSent = false;
+    this._lastUsage = null;
     this.client = client;
     this.config = config;
     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() {
+    return this._lastUsage;
+  }
   /**
    * Open the WebSocket connection and authenticate.
    *
@@ -1600,7 +1485,15 @@ var StreamingSession = class {
         if (data.interrupted) {
           this.callbacks.onInterrupted?.();
         }
+        if (data.final) {
+          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,
@@ -1664,10 +1557,11 @@ var StreamingSession = class {
     if (!this.configSent) {
       if (this.config.voiceId !== void 0) msg.voice_id = this.config.voiceId;
       if (this.config.modelId !== void 0) msg.model_id = this.config.modelId;
-      if (this.config.cfgScale !== void 0) msg.cfg_scale = this.config.cfgScale;
+      if (this.config.cfgScale !== void 0) msg.cfg_scale = clampCfgScale(this.config.cfgScale);
       if (this.config.temperature !== void 0) msg.temperature = this.config.temperature;
       if (this.config.maxNewTokens !== void 0) msg.max_new_tokens = this.config.maxNewTokens;
       if (this.config.sampleRate !== void 0) msg.sample_rate = this.config.sampleRate;
+      if (this.config.outputFormat !== void 0) msg.output_format = this.config.outputFormat;
       if (this.config.flushTimeoutMs !== void 0) msg.flush_timeout_ms = this.config.flushTimeoutMs;
       if (this.config.maxBufferLength !== void 0) msg.max_buffer_length = this.config.maxBufferLength;
       if (this.config.normalize !== void 0) msg.normalize = this.config.normalize;
@@ -1676,6 +1570,7 @@ var StreamingSession = class {
       if (this.config.autoMode !== void 0) msg.auto_mode = this.config.autoMode;
       if (this.config.chunkLengthSchedule?.length) msg.chunk_length_schedule = this.config.chunkLengthSchedule;
       if (this.config.speed !== void 0) msg.speed = this.config.speed;
+      if (this.config.dictionaryIds !== void 0) msg.dictionary_ids = this.config.dictionaryIds;
       this.configSent = true;
     }
     this.ws.send(JSON.stringify(msg));
@@ -1811,6 +1706,39 @@ var StreamingSession = class {
     Object.assign(this.config, config);
     this.configSent = false;
   }
+  /**
+   * Change generation parameters mid-connection without reconnecting (KUG-1166).
+   *
+   * Sends an `update_settings` message and resolves with the generation
+   * parameters now in effect (the server's echo). Only the six fields of
+   * {@link SettingsUpdate} are updatable; identity / audio-format fields
+   * (`voiceId`, `modelId`, `sampleRate`, `outputFormat`, `dictionaryIds`) are
+   * fixed for the connection — change those with {@link updateConfig} after
+   * {@link endSession} instead.
+   *
+   * The change applies to the **next turn**: a turn already streaming keeps the
+   * settings it started with, so call this between turns.
+   *
+   * @example
+   * ```typescript
+   * const effective = await session.updateSettings({ cfgScale: 1.5, speed: 1.1 });
+   * ```
+   *
+   * @throws {KugelAudioError} if no field is provided, the socket is not open,
+   *   or the server rejects the update (e.g. a value out of range).
+   */
+  updateSettings(settings) {
+    if (!this.ws || this.ws.readyState !== WS_OPEN) {
+      throw new KugelAudioError(
+        "StreamingSession not connected. Call connect() first."
+      );
+    }
+    const body = buildSettingsUpdateBody(settings);
+    return sendUpdateSettings(this.ws, body).then((effective) => {
+      applyAcceptedSettingsUpdate(this.config, settings);
+      return effective;
+    });
+  }
   /**
    * Close the session and the WebSocket connection.
    *
@@ -2054,5 +1982,6 @@ export {
   classifyWsHandshakeError,
   createWavBlob,
   createWavFile,
-  decodePCM16
+  decodePCM16,
+  parseSessionUsage
 };