kugelaudio 0.8.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,211 +202,6 @@ 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/types.ts
 function parseSessionUsage(data) {
   const raw = data.usage;
@@ -408,62 +219,6 @@ function parseSessionUsage(data) {
   };
 }
 
-// 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/websocket.ts
 var _cachedWs = null;
 function isNodeJs() {
@@ -491,69 +246,6 @@ function getWebSocket() {
   );
 }
 
-// package.json
-var package_default = {
-  name: "kugelaudio",
-  version: "0.8.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";
@@ -584,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;
@@ -639,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,
@@ -1098,7 +890,7 @@ 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,
@@ -1128,7 +920,7 @@ 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 },
@@ -1483,7 +1275,7 @@ var MultiContextSession = class {
       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.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;
@@ -1560,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.
    */
@@ -1738,7 +1557,7 @@ 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;
@@ -1887,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.
    *