kugelaudio 0.2.2 → 0.3.0

package/dist/index.mjs

@@ -6,49 +6,192 @@ var __require = /* @__PURE__ */ ((x) => typeof require !== "undefined" ? require
 });
 
 // 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"
+};
+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, statusCode) {
-    super(message);
+  constructor(message, options = {}) {
+    super(options.requestId ? `${message} (request_id: ${options.requestId})` : message);
     this.name = "KugelAudioError";
-    this.statusCode = statusCode;
+    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 = "Authentication failed") {
-    super(message, 401);
+  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 = "Rate limit exceeded") {
-    super(message, 429);
+  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 = "Insufficient credits") {
-    super(message, 403);
+  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) {
-    super(message, 400);
+  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 = "Failed to connect to server") {
-    super(message, 503);
+  constructor(message, options = {}) {
+    super(message, { statusCode: 503, ...options });
     this.name = "ConnectionError";
     Object.setPrototypeOf(this, _ConnectionError.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 || status === 429) {
+    return new RateLimitError(message || void 0, common);
+  }
+  if (errorCode === ErrorCodes.VALIDATION || 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
+    );
+  }
+  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 retryAfter = typeof data.retry_after === "number" ? data.retry_after : void 0;
+  return build(void 0, 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) {
@@ -108,33 +251,61 @@ function createWavBlob(audio, sampleRate) {
 
 // src/websocket.ts
 var _cachedWs = null;
+function isNodeJs() {
+  return typeof process !== "undefined" && !!process.versions && typeof process.versions.node === "string";
+}
 function getWebSocket() {
   if (_cachedWs) return _cachedWs;
+  if (isNodeJs()) {
+    try {
+      const _require = typeof __require !== "undefined" ? __require : Function('return typeof require !== "undefined" ? require : undefined')();
+      if (_require) {
+        const ws = _require("ws");
+        _cachedWs = ws.default || ws;
+        return _cachedWs;
+      }
+    } catch {
+    }
+  }
   if (typeof globalThis !== "undefined" && typeof globalThis.WebSocket !== "undefined") {
     _cachedWs = globalThis.WebSocket;
     return _cachedWs;
   }
-  try {
-    const _require = typeof __require !== "undefined" ? __require : Function('return typeof require !== "undefined" ? require : undefined')();
-    if (_require) {
-      const ws = _require("ws");
-      _cachedWs = ws.default || ws;
-      return _cachedWs;
-    }
-  } catch {
-  }
   throw new Error(
     'WebSocket not available. In Node.js, install the "ws" package: npm install ws'
   );
 }
 
 // src/client.ts
-var DEFAULT_API_URL = "https://api.kugelaudio.com";
+var REGION_URLS = {
+  eu: "https://api.kugelaudio.com",
+  us: "https://us-api.kugelaudio.com",
+  global: "https://global-api.kugelaudio.com"
+};
+var REGION_PREFIXES = ["eu-", "us-", "global-"];
+function parseApiKey(apiKey) {
+  for (const prefix of REGION_PREFIXES) {
+    if (apiKey.startsWith(prefix)) {
+      return { cleanKey: apiKey.slice(prefix.length), detectedRegion: prefix.slice(0, -1) };
+    }
+  }
+  return { cleanKey: apiKey };
+}
 function createWs(url) {
   const WS = getWebSocket();
   return new WS(url);
 }
 var WS_OPEN = 1;
+var _languageWarningLogged = false;
+function warnIfNoLanguage(language, normalize) {
+  const normEnabled = normalize === void 0 || normalize;
+  if (!language && normEnabled && !_languageWarningLogged) {
+    _languageWarningLogged = true;
+    console.warn(
+      "[KugelAudio] No 'language' set with normalization enabled \u2014 the server will auto-detect the language, adding ~60-150ms to TTFA. Set language (e.g., language: 'en') for optimal latency."
+    );
+  }
+}
 var ModelsResource = class {
   constructor(client) {
     this.client = client;
@@ -168,42 +339,177 @@ var VoicesResource = class {
       params.set("include_public", String(options.includePublic));
     }
     if (options?.limit) params.set("limit", String(options.limit));
+    if (options?.offset) params.set("offset", String(options.offset));
     const query = params.toString();
     const path = query ? `/v1/voices?${query}` : "/v1/voices";
     const response = await this.client.request("GET", path);
-    return response.voices.map((v) => ({
-      id: v.id,
-      name: v.name,
-      description: v.description,
-      category: v.category,
-      sex: v.sex,
-      age: v.age,
-      supportedLanguages: v.supported_languages || [],
-      sampleText: v.sample_text,
-      avatarUrl: v.avatar_url,
-      sampleUrl: v.sample_url,
-      isPublic: v.is_public || false,
-      verified: v.verified || false
-    }));
+    return {
+      voices: response.voices.map((v) => ({
+        id: v.id,
+        name: v.name,
+        description: v.description,
+        category: v.category,
+        sex: v.sex,
+        age: v.age,
+        supportedLanguages: v.supported_languages || [],
+        sampleText: v.sample_text,
+        avatarUrl: v.avatar_url,
+        sampleUrl: v.sample_url,
+        isPublic: v.is_public || false,
+        verified: v.verified || false
+      })),
+      total: response.total,
+      limit: response.limit,
+      offset: response.offset
+    };
   }
   /**
    * Get a specific voice by ID.
    */
   async get(voiceId) {
     const v = await this.client.request("GET", `/v1/voices/${voiceId}`);
+    return this.mapVoiceDetail(v);
+  }
+  /**
+   * Create a new voice.
+   */
+  async create(options) {
+    const metadata = {
+      name: options.name,
+      sex: options.sex,
+      description: options.description ?? "",
+      category: options.category ?? "conversational",
+      age: options.age ?? "middle_age",
+      quality: options.quality ?? "mid",
+      supported_languages: options.supportedLanguages ?? ["en"],
+      is_public: options.isPublic ?? false,
+      sample_text: options.sampleText ?? ""
+    };
+    const formData = new FormData();
+    formData.append(
+      "metadata",
+      new Blob([JSON.stringify(metadata)], { type: "application/json" })
+    );
+    if (options.referenceFiles) {
+      for (const file of options.referenceFiles) {
+        formData.append("files", file);
+      }
+    }
+    const v = await this.client.requestMultipart("POST", "/v1/voices", formData);
+    return this.mapVoiceDetail(v);
+  }
+  /**
+   * Update an existing voice. Only provided fields are updated.
+   */
+  async update(voiceId, options) {
+    const payload = {};
+    if (options.name !== void 0) payload.name = options.name;
+    if (options.description !== void 0) payload.description = options.description;
+    if (options.category !== void 0) payload.category = options.category;
+    if (options.age !== void 0) payload.age = options.age;
+    if (options.sex !== void 0) payload.sex = options.sex;
+    if (options.quality !== void 0) payload.quality = options.quality;
+    if (options.supportedLanguages !== void 0) payload.supported_languages = options.supportedLanguages;
+    if (options.isPublic !== void 0) payload.is_public = options.isPublic;
+    if (options.sampleText !== void 0) payload.sample_text = options.sampleText;
+    const v = await this.client.request("PATCH", `/v1/voices/${voiceId}`, payload);
+    return this.mapVoiceDetail(v);
+  }
+  /**
+   * Delete a voice.
+   */
+  async delete(voiceId) {
+    await this.client.request("DELETE", `/v1/voices/${voiceId}`);
+  }
+  // -- Reference management --
+  /**
+   * List reference audio files for a voice.
+   */
+  async listReferences(voiceId) {
+    const response = await this.client.request(
+      "GET",
+      `/v1/voices/${voiceId}/references`
+    );
+    return response.references.map((r) => this.mapVoiceReference(r));
+  }
+  /**
+   * Upload a reference audio file to a voice.
+   *
+   * @param voiceId - Voice ID
+   * @param file - Audio file (File in browser, Blob in Node.js)
+   * @param referenceText - Optional transcript of the reference audio
+   */
+  async addReference(voiceId, file, referenceText) {
+    const formData = new FormData();
+    formData.append("file", file);
+    if (referenceText) {
+      formData.append("reference_text", referenceText);
+    }
+    const r = await this.client.requestMultipart(
+      "POST",
+      `/v1/voices/${voiceId}/references`,
+      formData
+    );
+    return this.mapVoiceReference(r);
+  }
+  /**
+   * Delete a reference audio file from a voice.
+   */
+  async deleteReference(voiceId, referenceId) {
+    await this.client.request(
+      "DELETE",
+      `/v1/voices/${voiceId}/references/${referenceId}`
+    );
+  }
+  // -- Publishing --
+  /**
+   * Request publication of a voice. Sets it as public and marks it
+   * as pending verification by an admin.
+   */
+  async publish(voiceId) {
+    const v = await this.client.request("POST", `/v1/voices/${voiceId}/publish`);
+    return this.mapVoiceDetail(v);
+  }
+  // -- Sample generation --
+  /**
+   * Trigger sample audio generation for a voice.
+   */
+  async generateSample(voiceId) {
+    const v = await this.client.request(
+      "POST",
+      `/v1/voices/${voiceId}/generate-sample`
+    );
+    return this.mapVoiceDetail(v);
+  }
+  // -- Helpers --
+  mapVoiceDetail(v) {
     return {
       id: v.id,
       name: v.name,
-      description: v.description,
-      category: v.category,
-      sex: v.sex,
+      description: v.description ?? "",
+      generativeVoiceDescription: v.generative_voice_description ?? "",
+      supportedLanguages: v.supported_languages ?? [],
+      category: v.category ?? "cloned",
       age: v.age,
-      supportedLanguages: v.supported_languages || [],
-      sampleText: v.sample_text,
-      avatarUrl: v.avatar_url,
+      sex: v.sex,
+      quality: v.quality ?? "mid",
+      isPublic: v.is_public ?? false,
+      verified: v.verified ?? false,
+      pendingVerification: v.pending_verification ?? false,
       sampleUrl: v.sample_url,
-      isPublic: v.is_public || false,
-      verified: v.verified || false
+      avatarUrl: v.avatar_url,
+      sampleText: v.sample_text ?? ""
+    };
+  }
+  mapVoiceReference(r) {
+    return {
+      id: r.id,
+      voiceId: r.voice_id,
+      name: r.name ?? "",
+      referenceText: r.reference_text ?? "",
+      s3Path: r.s3_path ?? "",
+      audioUrl: r.audio_url,
+      isGenerated: r.is_generated ?? false
     };
   }
 };
@@ -215,6 +521,7 @@ var TTSResource = class {
     this.wsUrl = null;
     this.pendingRequests = /* @__PURE__ */ new Map();
     this.requestCounter = 0;
+    this.keepaliveTimer = null;
   }
   /**
    * Pre-establish WebSocket connection for faster first request.
@@ -249,10 +556,14 @@ var TTSResource = class {
   async generate(options) {
     const chunks = [];
     let finalStats;
+    const allTimestamps = [];
     await this.stream(options, {
       onChunk: (chunk) => {
         chunks.push(base64ToArrayBuffer(chunk.audio));
       },
+      onWordTimestamps: (timestamps) => {
+        allTimestamps.push(...timestamps);
+      },
       onFinal: (stats) => {
         finalStats = stats;
       }
@@ -270,9 +581,67 @@ var TTSResource = class {
       samples: finalStats ? finalStats.totalSamples : totalLength / 2,
       durationMs: finalStats ? finalStats.durationMs : 0,
       generationMs: finalStats ? finalStats.generationMs : 0,
-      rtf: finalStats ? finalStats.rtf : 0
+      rtf: finalStats ? finalStats.rtf : 0,
+      wordTimestamps: allTimestamps
     };
   }
+  /**
+   * Stream audio and return a Node.js Readable stream of raw PCM16 binary data.
+   *
+   * **Node.js only** — this method requires the `stream` built-in module and is
+   * intended for server-side integrations such as Vapi custom TTS endpoints,
+   * Express/Fastify handlers, or any pipeline that expects a Node.js `Readable`.
+   *
+   * Compared to manually wiring `onChunk` to a `Readable`, this method avoids
+   * a common race-condition: the stream object is created and returned **before**
+   * any chunks arrive, so the caller can safely pipe or attach listeners before
+   * the first audio byte is pushed.
+   *
+   * @example Vapi custom TTS endpoint
+   * ```typescript
+   * app.post('/synthesize', (req, res) => {
+   *   res.setHeader('Content-Type', 'audio/pcm');
+   *   res.setHeader('Transfer-Encoding', 'chunked');
+   *
+   *   const readable = client.tts.toReadable({
+   *     text: req.body.message.text,
+   *     modelId: 'kugel-1-turbo',
+   *     sampleRate: req.body.message.sampleRate,
+   *     language: 'en',
+   *   });
+   *
+   *   readable.pipe(res);
+   * });
+   * ```
+   *
+   * @param options - TTS generation options (same as `stream()`)
+   * @param reuseConnection - Reuse the pooled WebSocket connection (default: true)
+   * @returns Node.js Readable stream emitting raw PCM16 binary Buffer chunks
+   */
+  // eslint-disable-next-line @typescript-eslint/no-explicit-any
+  toReadable(options, reuseConnection = true) {
+    const { Readable } = __require("stream");
+    const readable = new Readable({ read() {
+    } });
+    this.stream(
+      options,
+      {
+        onChunk: (chunk) => {
+          readable.push(Buffer.from(chunk.audio, "base64"));
+        },
+        onFinal: () => {
+          readable.push(null);
+        },
+        onError: (error) => {
+          readable.destroy(error);
+        }
+      },
+      reuseConnection
+    ).catch((error) => {
+      readable.destroy(error);
+    });
+    return readable;
+  }
   /**
    * Build the WebSocket URL with appropriate auth param.
    */
@@ -314,10 +683,17 @@ var TTSResource = class {
         this.wsConnection = ws;
         this.wsUrl = url;
         this.setupMessageHandler(ws);
+        this.startKeepalive(ws);
         resolve(ws);
       };
-      ws.onerror = () => {
-        reject(new KugelAudioError("WebSocket connection error"));
+      ws.onerror = (event) => {
+        const underlying = event?.error ?? event;
+        const typed = classifyWsHandshakeError(underlying);
+        reject(
+          typed ?? new ConnectionError(
+            `Could not establish KugelAudio WebSocket connection to ${url}. Check network connectivity.`
+          )
+        );
       };
     });
   }
@@ -332,7 +708,7 @@ var TTSResource = class {
         const [requestId, pending] = [...this.pendingRequests.entries()][0] || [];
         if (!pending) return;
         if (data.error) {
-          const error = this.parseError(data.error);
+          const error = this.parseError(data);
           pending.callbacks.onError?.(error);
           this.pendingRequests.delete(requestId);
           pending.reject(error);
@@ -345,7 +721,6 @@ var TTSResource = class {
             totalSamples: data.total_samples,
             durationMs: data.dur_ms,
             generationMs: data.gen_ms,
-            ttfaMs: data.ttfa_ms,
             rtf: data.rtf,
             error: data.error
           };
@@ -364,25 +739,41 @@ var TTSResource = class {
           };
           pending.callbacks.onChunk?.(chunk);
         }
+        if (data.word_timestamps) {
+          const timestamps = data.word_timestamps.map(
+            (w) => ({
+              word: w.word,
+              startMs: w.start_ms,
+              endMs: w.end_ms,
+              charStart: w.char_start,
+              charEnd: w.char_end,
+              score: w.score ?? 1
+            })
+          );
+          pending.callbacks.onWordTimestamps?.(timestamps);
+        }
       } catch (e) {
         console.error("Failed to parse WebSocket message:", e);
       }
     };
     ws.onclose = (event) => {
+      this.stopKeepalive();
       this.wsConnection = null;
       this.wsUrl = null;
       for (const [id, pending] of this.pendingRequests) {
         pending.callbacks.onClose?.();
-        if (event.code === 4001) {
-          pending.reject(new AuthenticationError("Authentication failed"));
-        } else if (event.code === 4003) {
-          pending.reject(new InsufficientCreditsError("Insufficient credits"));
+        if (event.code === 4001 || event.code === 4003 || event.code === 4029 || event.code === 4500) {
+          const error = classifyWsClose(event.code, event.reason);
+          pending.callbacks.onError?.(error);
+          pending.reject(error);
         }
         this.pendingRequests.delete(id);
       }
     };
     ws.onerror = () => {
-      const error = new KugelAudioError("WebSocket connection error");
+      const error = new ConnectionError(
+        "KugelAudio WebSocket connection error. Check network connectivity."
+      );
       for (const [id, pending] of this.pendingRequests) {
         pending.callbacks.onError?.(error);
         pending.reject(error);
@@ -408,6 +799,7 @@ var TTSResource = class {
    * Stream with connection pooling (fast path).
    */
   async streamWithPooling(options, callbacks) {
+    warnIfNoLanguage(options.language, options.normalize);
     const ws = await this.getConnection();
     const requestId = ++this.requestCounter;
     return new Promise((resolve, reject) => {
@@ -418,10 +810,14 @@ var TTSResource = class {
         model_id: options.modelId || "kugel-1-turbo",
         voice_id: options.voiceId,
         cfg_scale: options.cfgScale ?? 2,
+        ...options.temperature !== void 0 && { temperature: options.temperature },
         max_new_tokens: options.maxNewTokens ?? 2048,
         sample_rate: options.sampleRate ?? 24e3,
         normalize: options.normalize ?? true,
-        ...options.language && { language: options.language }
+        ...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 }
       }));
     });
   }
@@ -429,6 +825,7 @@ var TTSResource = class {
    * Stream without connection pooling (original behavior).
    */
   streamWithoutPooling(options, callbacks) {
+    warnIfNoLanguage(options.language, options.normalize);
     return new Promise((resolve, reject) => {
       const url = this.buildWsUrl();
       const ws = createWs(url);
@@ -442,7 +839,10 @@ var TTSResource = class {
           max_new_tokens: options.maxNewTokens ?? 2048,
           sample_rate: options.sampleRate ?? 24e3,
           normalize: options.normalize ?? true,
-          ...options.language && { language: options.language }
+          ...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 }
         }));
       };
       ws.onmessage = (event) => {
@@ -450,7 +850,7 @@ var TTSResource = class {
           const messageData = typeof event.data === "string" ? event.data : event.data instanceof Buffer ? event.data.toString() : String(event.data);
           const data = JSON.parse(messageData);
           if (data.error) {
-            const error = this.parseError(data.error);
+            const error = this.parseError(data);
             callbacks.onError?.(error);
             ws.close();
             reject(error);
@@ -463,7 +863,6 @@ var TTSResource = class {
               totalSamples: data.total_samples,
               durationMs: data.dur_ms,
               generationMs: data.gen_ms,
-              ttfaMs: data.ttfa_ms,
               rtf: data.rtf,
               error: data.error
             };
@@ -482,29 +881,71 @@ var TTSResource = class {
             };
             callbacks.onChunk?.(chunk);
           }
+          if (data.word_timestamps) {
+            const timestamps = data.word_timestamps.map(
+              (w) => ({
+                word: w.word,
+                startMs: w.start_ms,
+                endMs: w.end_ms,
+                charStart: w.char_start,
+                charEnd: w.char_end,
+                score: w.score ?? 1
+              })
+            );
+            callbacks.onWordTimestamps?.(timestamps);
+          }
         } catch (e) {
           console.error("Failed to parse WebSocket message:", e);
         }
       };
-      ws.onerror = () => {
-        const error = new KugelAudioError("WebSocket connection error");
+      ws.onerror = (event) => {
+        const underlying = event?.error ?? event;
+        const error = classifyWsHandshakeError(underlying) ?? new ConnectionError(
+          "KugelAudio WebSocket connection error. Check network connectivity."
+        );
         callbacks.onError?.(error);
         reject(error);
       };
       ws.onclose = (event) => {
         callbacks.onClose?.();
-        if (event.code === 4001) {
-          reject(new AuthenticationError("Authentication failed"));
-        } else if (event.code === 4003) {
-          reject(new InsufficientCreditsError("Insufficient credits"));
+        if (event.code === 4001 || event.code === 4003 || event.code === 4029 || event.code === 4500) {
+          const error = classifyWsClose(event.code, event.reason);
+          callbacks.onError?.(error);
+          reject(error);
         }
       };
     });
   }
+  /**
+   * Start periodic keepalive pings on the pooled connection.
+   * Uses the ws package's ping() in Node.js; silently skips in browsers
+   * where WebSocket doesn't expose a ping method.
+   */
+  startKeepalive(ws) {
+    this.stopKeepalive();
+    const intervalMs = this.client.keepalivePingInterval;
+    if (intervalMs == null || intervalMs <= 0) return;
+    this.keepaliveTimer = setInterval(() => {
+      if (this.wsConnection !== ws || ws.readyState !== WS_OPEN) {
+        this.stopKeepalive();
+        return;
+      }
+      if (typeof ws.ping === "function") {
+        ws.ping();
+      }
+    }, intervalMs);
+  }
+  stopKeepalive() {
+    if (this.keepaliveTimer !== null) {
+      clearInterval(this.keepaliveTimer);
+      this.keepaliveTimer = null;
+    }
+  }
   /**
    * Close the pooled WebSocket connection.
    */
   close() {
+    this.stopKeepalive();
     if (this.wsConnection) {
       try {
         this.wsConnection.close();
@@ -514,15 +955,39 @@ var TTSResource = class {
       this.wsUrl = null;
     }
   }
-  parseError(message) {
-    const lower = message.toLowerCase();
-    if (lower.includes("auth") || lower.includes("unauthorized")) {
-      return new AuthenticationError(message);
-    }
-    if (lower.includes("credit")) {
-      return new InsufficientCreditsError(message);
-    }
-    return new KugelAudioError(message);
+  parseError(data) {
+    return classifyWsFrame(data);
+  }
+  /**
+   * Create a streaming session for LLM integration.
+   *
+   * The session connects to `/ws/tts/stream` and keeps a persistent
+   * connection across multiple {@link StreamingSession.send} calls.
+   * The server auto-chunks text at sentence boundaries — no client-side
+   * flushing required.
+   *
+   * @param config - Session configuration (voice, model, chunking strategy).
+   * @param callbacks - Callbacks for audio chunks and session lifecycle events.
+   * @returns A {@link StreamingSession} instance. Call `.connect()` before sending.
+   *
+   * @example
+   * ```typescript
+   * const session = client.tts.streamingSession(
+   *   { voiceId: 123, autoMode: true, chunkLengthSchedule: [50, 100, 150, 250] },
+   *   { onChunk: (chunk) => playAudio(chunk.audio) },
+   * );
+   *
+   * session.connect();
+   *
+   * for await (const token of llmStream) {
+   *   session.send(token);
+   * }
+   *
+   * await session.close();
+   * ```
+   */
+  streamingSession(config, callbacks) {
+    return new StreamingSession(this.client, config, callbacks);
   }
   /**
    * Create a multi-context session for concurrent TTS streams.
@@ -542,7 +1007,7 @@ var TTSResource = class {
    *     console.log(`Audio from ${chunk.contextId}`);
    *     playAudio(chunk.audio);
    *   },
-   *   onContextFinal: (contextId) => {
+   *   onContextClosed: (contextId) => {
    *     console.log(`${contextId} finished`);
    *   },
    * });
@@ -581,6 +1046,11 @@ var MultiContextSession = class {
   }
   /**
    * Connect to the multi-context WebSocket endpoint.
+   *
+   * The returned promise resolves once the WebSocket is OPEN so callers can
+   * ``await session.connect(callbacks)`` before invoking
+   * {@link createContext} / {@link send}. Pre-open errors reject with the
+   * typed error.
    */
   connect(callbacks) {
     this.callbacks = callbacks;
@@ -595,9 +1065,8 @@ var MultiContextSession = class {
     }
     const url = `${wsUrl}/ws/tts/multi?${authParam}=${this.client.apiKey}`;
     this.ws = createWs(url);
-    this.ws.onopen = () => {
-    };
-    this.ws.onmessage = (event) => {
+    const ws = this.ws;
+    ws.onmessage = (event) => {
       try {
         const messageData = typeof event.data === "string" ? event.data : event.data instanceof Buffer ? event.data.toString() : String(event.data);
         const data = JSON.parse(messageData);
@@ -628,9 +1097,6 @@ var MultiContextSession = class {
           };
           this.callbacks.onChunk?.(chunk);
         }
-        if (data.is_final) {
-          this.callbacks.onContextFinal?.(data.context_id);
-        }
         if (data.context_closed) {
           this.contexts.delete(data.context_id);
           this.callbacks.onContextClosed?.(data.context_id);
@@ -646,19 +1112,38 @@ var MultiContextSession = class {
         console.error("Failed to parse WebSocket message:", e);
       }
     };
-    this.ws.onerror = () => {
-      this.callbacks.onError?.(new KugelAudioError("WebSocket connection error"));
-    };
-    this.ws.onclose = (event) => {
-      if (event.code === 4001) {
-        this.callbacks.onError?.(new AuthenticationError("Authentication failed"));
-      } else if (event.code === 4003) {
-        this.callbacks.onError?.(new InsufficientCreditsError("Insufficient credits"));
-      }
-      this.ws = null;
-      this.isStarted = false;
-      this.contexts.clear();
-    };
+    return new Promise((resolve, reject) => {
+      let opened = false;
+      ws.onopen = () => {
+        opened = true;
+        resolve();
+      };
+      ws.onerror = (event) => {
+        const underlying = event?.error ?? event;
+        const err = classifyWsHandshakeError(underlying) ?? new ConnectionError(
+          "KugelAudio multi-context WebSocket connection error. Check network connectivity."
+        );
+        if (!opened) reject(err);
+        this.callbacks.onError?.(err);
+      };
+      ws.onclose = (event) => {
+        let typedErr = null;
+        if (event.code === 4001 || event.code === 4003 || event.code === 4029 || event.code === 4500) {
+          typedErr = classifyWsClose(event.code, event.reason);
+          this.callbacks.onError?.(typedErr);
+        }
+        if (!opened) {
+          reject(
+            typedErr ?? new ConnectionError(
+              `KugelAudio multi-context WebSocket closed before ready (code ${event.code}).`
+            )
+          );
+        }
+        this.ws = null;
+        this.isStarted = false;
+        this.contexts.clear();
+      };
+    });
   }
   /**
    * Create a new context with optional voice settings.
@@ -672,10 +1157,13 @@ var MultiContextSession = class {
       context_id: contextId
     };
     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.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.inactivityTimeout) msg.inactivity_timeout = this.config.inactivityTimeout;
     }
     const voiceId = options?.voiceId || this.config.defaultVoiceId;
@@ -762,18 +1250,271 @@ var MultiContextSession = class {
     return this.ws !== null && this.ws.readyState === WS_OPEN;
   }
 };
+var StreamingSession = class {
+  constructor(client, config, callbacks) {
+    this.ws = null;
+    this.configSent = false;
+    this.client = client;
+    this.config = config;
+    this.callbacks = callbacks;
+  }
+  /**
+   * Open the WebSocket connection and authenticate.
+   *
+   * The returned promise resolves once the WebSocket is OPEN, so callers can
+   * ``await session.connect()`` and then ``send()`` without racing the
+   * handshake. Pre-open errors (network failure, 4001 unauthorized, …) reject
+   * the promise with the typed error.
+   */
+  connect() {
+    const wsUrl = this.client.ttsUrl.replace("https://", "wss://").replace("http://", "ws://");
+    let authParam;
+    if (this.client.isToken) {
+      authParam = "token";
+    } else if (this.client.isMasterKey) {
+      authParam = "master_key";
+    } else {
+      authParam = "api_key";
+    }
+    const url = `${wsUrl}/ws/tts/stream?${authParam}=${this.client.apiKey}`;
+    this.ws = createWs(url);
+    const ws = this.ws;
+    ws.onmessage = (event) => {
+      try {
+        const messageData = typeof event.data === "string" ? event.data : event.data instanceof Buffer ? event.data.toString() : String(event.data);
+        const data = JSON.parse(messageData);
+        if (data.error) {
+          this.callbacks.onError?.(new KugelAudioError(data.error));
+          return;
+        }
+        if (data.audio) {
+          const chunk = {
+            audio: data.audio,
+            encoding: data.enc || "pcm_s16le",
+            index: data.idx,
+            sampleRate: data.sr,
+            samples: data.samples
+          };
+          this.callbacks.onChunk?.(chunk);
+        }
+        if (data.word_timestamps) {
+          const timestamps = data.word_timestamps.map((w) => ({
+            word: w.word,
+            startMs: w.start_ms,
+            endMs: w.end_ms,
+            charStart: w.char_start,
+            charEnd: w.char_end,
+            score: w.score ?? 1
+          }));
+          this.callbacks.onWordTimestamps?.(timestamps);
+        }
+        if (data.chunk_complete) {
+          this.callbacks.onChunkComplete?.(
+            data.chunk_id ?? 0,
+            data.audio_seconds ?? 0,
+            data.gen_ms ?? 0
+          );
+        }
+        if (data.generation_started) {
+          this.callbacks.onGenerationStarted?.(data.chunk_id ?? 0, data.text ?? "");
+        }
+        if (data.session_closed) {
+          this.callbacks.onSessionClosed?.(
+            data.total_audio_seconds ?? 0,
+            data.total_text_chunks ?? 0,
+            data.total_audio_chunks ?? 0
+          );
+        }
+      } catch (e) {
+        console.error("[KugelAudio] Failed to parse streaming session message:", e);
+      }
+    };
+    return new Promise((resolve, reject) => {
+      let opened = false;
+      ws.onopen = () => {
+        opened = true;
+        resolve();
+      };
+      ws.onerror = (event) => {
+        const underlying = event?.error ?? event;
+        const err = classifyWsHandshakeError(underlying) ?? new ConnectionError(
+          "KugelAudio streaming WebSocket connection error. Check network connectivity."
+        );
+        if (!opened) reject(err);
+        this.callbacks.onError?.(err);
+      };
+      ws.onclose = (event) => {
+        let typedErr = null;
+        if (event.code === 4001 || event.code === 4003 || event.code === 4029 || event.code === 4500) {
+          typedErr = classifyWsClose(event.code, event.reason);
+          this.callbacks.onError?.(typedErr);
+        }
+        if (!opened) {
+          reject(
+            typedErr ?? new ConnectionError(
+              `KugelAudio streaming WebSocket closed before ready (code ${event.code}).`
+            )
+          );
+        }
+        this.ws = null;
+        this.configSent = false;
+      };
+    });
+  }
+  /**
+   * Send a text chunk to the server (e.g. one LLM output token).
+   *
+   * The server buffers text across multiple calls and starts generating at
+   * natural sentence boundaries automatically — no need to call `flush`.
+   *
+   * @param text - Raw text or LLM token to append to the server buffer.
+   * @param flush - Force immediate generation of whatever is buffered.
+   *   **Avoid calling this per-sentence from the client.** Doing so bypasses
+   *   the server's semantic chunking, incurs a fresh model prefill cost on
+   *   every flush, and makes latency *worse*, not better.  Let the server
+   *   handle chunking via `chunkLengthSchedule` / `autoMode` instead.
+   */
+  send(text, flush = false) {
+    if (!this.ws || this.ws.readyState !== WS_OPEN) {
+      throw new KugelAudioError("StreamingSession not connected. Call connect() first.");
+    }
+    const msg = { text, flush };
+    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.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.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;
+      if (this.config.language !== void 0) msg.language = this.config.language;
+      if (this.config.wordTimestamps) msg.word_timestamps = true;
+      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;
+      this.configSent = true;
+    }
+    this.ws.send(JSON.stringify(msg));
+  }
+  /**
+   * End the current session but keep the WebSocket connection open.
+   *
+   * This allows starting a new session on the same connection, avoiding
+   * the overhead of a new WebSocket handshake (~200-300ms). After calling
+   * this, optionally call {@link updateConfig} to change voice/model settings,
+   * then call {@link send} to start the next session.
+   *
+   * The returned promise resolves once the server confirms with a
+   * `session_closed` message, or after a 15 s **quiet** timeout — i.e. 15 s
+   * elapse without *any* server message arriving. The timer resets on every
+   * incoming frame so a long final flush that streams audio for tens of
+   * seconds is not truncated; only a genuinely silent server trips the fuse.
+   */
+  endSession() {
+    if (!this.ws || this.ws.readyState !== WS_OPEN) return Promise.resolve();
+    const ws = this.ws;
+    const QUIET_TIMEOUT_MS = 15e3;
+    return new Promise((resolve) => {
+      let settled = false;
+      let timer;
+      const prevMessage = ws.onmessage;
+      const prevClose = ws.onclose;
+      const done = () => {
+        if (settled) return;
+        settled = true;
+        clearTimeout(timer);
+        ws.onmessage = prevMessage;
+        ws.onclose = prevClose;
+        this.configSent = false;
+        resolve();
+      };
+      const armQuietTimer = () => {
+        clearTimeout(timer);
+        timer = setTimeout(done, QUIET_TIMEOUT_MS);
+      };
+      armQuietTimer();
+      ws.onmessage = (event) => {
+        armQuietTimer();
+        if (prevMessage) prevMessage.call(ws, event);
+        try {
+          const raw = typeof event.data === "string" ? event.data : event.data instanceof Buffer ? event.data.toString() : String(event.data);
+          if (JSON.parse(raw).session_closed) done();
+        } catch {
+        }
+      };
+      ws.onclose = (event) => {
+        this.ws = null;
+        if (prevClose) prevClose.call(ws, event);
+        done();
+      };
+      ws.send(JSON.stringify({ close: true }));
+    });
+  }
+  /**
+   * Update session configuration for the next session.
+   *
+   * Call this after {@link endSession} and before the next {@link send}
+   * to change voice, model, language, or other settings.
+   */
+  updateConfig(config) {
+    Object.assign(this.config, config);
+    this.configSent = false;
+  }
+  /**
+   * Close the session and the WebSocket connection.
+   *
+   * For session reuse without closing the connection, use
+   * {@link endSession} instead.
+   *
+   * The returned promise resolves once the server confirms the close with a
+   * `session_closed` message, or after a 15 s **quiet** timeout (no traffic
+   * from the server in that window). Audio frames from the server-side
+   * final-flush of the still-buffered text are delivered to your callbacks
+   * before this promise resolves, and each frame resets the quiet timer.
+   */
+  async close() {
+    await this.endSession();
+    if (this.ws) {
+      try {
+        this.ws.close();
+      } catch {
+      }
+      this.ws = null;
+    }
+  }
+  /** Whether the underlying WebSocket is open. */
+  get isConnected() {
+    return this.ws !== null && this.ws.readyState === WS_OPEN;
+  }
+};
 var KugelAudio = class _KugelAudio {
   constructor(options) {
     if (!options.apiKey) {
-      throw new Error("API key is required");
+      throw new ValidationError(
+        "KugelAudio API key is missing. Set the KUGELAUDIO_API_KEY environment variable or pass { apiKey: ... } to the client. Get a key at https://app.kugelaudio.com/settings/api-keys."
+      );
     }
-    this._apiKey = options.apiKey;
+    const { cleanKey, detectedRegion } = parseApiKey(options.apiKey);
+    this._apiKey = cleanKey;
     this._isMasterKey = options.isMasterKey || false;
     this._isToken = options.isToken || false;
     this._orgId = options.orgId;
-    this._apiUrl = (options.apiUrl || DEFAULT_API_URL).replace(/\/$/, "");
+    if (options.apiUrl) {
+      this._apiUrl = options.apiUrl.replace(/\/$/, "");
+    } else {
+      const effectiveRegion = options.region || detectedRegion || "eu";
+      if (!(effectiveRegion in REGION_URLS)) {
+        throw new ValidationError(
+          `Invalid region '${effectiveRegion}'. Must be one of: ${Object.keys(REGION_URLS).join(", ")}.`
+        );
+      }
+      this._apiUrl = REGION_URLS[effectiveRegion];
+    }
     this._ttsUrl = (options.ttsUrl || this._apiUrl).replace(/\/$/, "");
     this._timeout = options.timeout || 6e4;
+    this._keepalivePingInterval = options.keepalivePingInterval !== void 0 ? options.keepalivePingInterval : 2e4;
     this.models = new ModelsResource(this);
     this.voices = new VoicesResource(this);
     this.tts = new TTSResource(this);
@@ -819,6 +1560,10 @@ var KugelAudio = class _KugelAudio {
   get ttsUrl() {
     return this._ttsUrl;
   }
+  /** Get keepalive ping interval in milliseconds, or null if disabled. */
+  get keepalivePingInterval() {
+    return this._keepalivePingInterval;
+  }
   /**
    * Close the client and release resources.
    * This closes any pooled WebSocket connections.
@@ -873,25 +1618,49 @@ var KugelAudio = class _KugelAudio {
         signal: controller.signal
       });
       clearTimeout(timeoutId);
-      if (response.status === 401) {
-        throw new AuthenticationError("Invalid API key");
+      if (!response.ok) {
+        const text = await response.text();
+        throw classifyHttpError(response.status, text, response.headers);
       }
-      if (response.status === 403) {
-        throw new InsufficientCreditsError("Access denied");
+      return await response.json();
+    } catch (error) {
+      clearTimeout(timeoutId);
+      if (error instanceof KugelAudioError) {
+        throw error;
       }
-      if (response.status === 429) {
-        throw new RateLimitError("Rate limit exceeded");
+      if (error.name === "AbortError") {
+        throw new ConnectionError(
+          `Request to ${method} ${path} timed out after ${this._timeout}ms.`
+        );
       }
+      throw new ConnectionError(
+        `Could not reach KugelAudio at ${url}: ${error.message}. Check network connectivity.`
+      );
+    }
+  }
+  /**
+   * Make a multipart/form-data request (for file uploads).
+   * @internal Used by VoicesResource for reference file uploads.
+   */
+  async requestMultipart(method, path, formData) {
+    const url = `${this._apiUrl}${path}`;
+    const headers = {
+      "X-API-Key": this._apiKey,
+      "Authorization": `Bearer ${this._apiKey}`
+    };
+    const controller = new AbortController();
+    const timeoutId = setTimeout(() => controller.abort(), this._timeout);
+    try {
+      const response = await fetch(url, {
+        method,
+        headers,
+        body: formData,
+        signal: controller.signal
+      });
+      clearTimeout(timeoutId);
       if (!response.ok) {
         const text = await response.text();
-        let message = `HTTP ${response.status}`;
-        try {
-          const json = JSON.parse(text);
-          message = json.detail || json.error || message;
-        } catch {
-          message = text || message;
-        }
-        throw new KugelAudioError(message, response.status);
+        throw classifyHttpError(response.status, text, response.headers);
       }
       return await response.json();
     } catch (error) {
@@ -900,21 +1669,31 @@ var KugelAudio = class _KugelAudio {
         throw error;
       }
       if (error.name === "AbortError") {
-        throw new KugelAudioError("Request timed out");
+        throw new ConnectionError(
+          `Request to ${method} ${path} timed out after ${this._timeout}ms.`
+        );
       }
-      throw new KugelAudioError(`Request failed: ${error.message}`);
+      throw new ConnectionError(
+        `Could not reach KugelAudio at ${url}: ${error.message}. Check network connectivity.`
+      );
     }
   }
 };
 export {
   AuthenticationError,
   ConnectionError,
+  ErrorCodes,
   InsufficientCreditsError,
   KugelAudio,
   KugelAudioError,
   RateLimitError,
   ValidationError,
+  WsCloseCodes,
   base64ToArrayBuffer,
+  classifyHttpError,
+  classifyWsClose,
+  classifyWsFrame,
+  classifyWsHandshakeError,
   createWavBlob,
   createWavFile,
   decodePCM16