kugelaudio 0.6.0 → 0.7.0

package/CHANGELOG.md

@@ -1,3 +1,20 @@
+## [kugelaudio-v0.7.0](https://github.com/Kugelaudio/KugelAudio/compare/js-sdk-v0.6.1...js-sdk-v0.7.0) (2026-06-06)
+
+### Features
+
+* **ingress:** add request observability metadata ([#1321](https://github.com/Kugelaudio/KugelAudio/issues/1321)) ([a9c5178](https://github.com/Kugelaudio/KugelAudio/commit/a9c5178193cb8b746a8bbd9b566b11f7b1d00f6d))
+* **sdks:** default all SDKs to kugel-3 model ([#1323](https://github.com/Kugelaudio/KugelAudio/issues/1323)) ([c4de212](https://github.com/Kugelaudio/KugelAudio/commit/c4de212c91e16326a15dbee5622acacc83ed85bb))
+
+### Bug Fixes
+
+* **js-sdk:** type SDK metadata fetch mock ([#1334](https://github.com/Kugelaudio/KugelAudio/issues/1334)) ([e8f6f59](https://github.com/Kugelaudio/KugelAudio/commit/e8f6f59595e123eaae8b44670c94fb4e7bc8d06c))
+
+## [kugelaudio-v0.6.1](https://github.com/Kugelaudio/KugelAudio/compare/js-sdk-v0.6.0...js-sdk-v0.6.1) (2026-06-04)
+
+### Bug Fixes
+
+* **python-sdk:** propagate ingress errors through SDK integrations ([#1313](https://github.com/Kugelaudio/KugelAudio/issues/1313)) ([3ae2e03](https://github.com/Kugelaudio/KugelAudio/commit/3ae2e03745b49cca0712c20d9a658c160f4b6f38))
+
 ## [kugelaudio-v0.6.0](https://github.com/Kugelaudio/KugelAudio/compare/js-sdk-v0.5.0...js-sdk-v0.6.0) (2026-06-01)
 
 ### Features

package/dist/index.d.mts

@@ -217,7 +217,7 @@ interface WordTimestamp {
 interface GenerateOptions {
     /** Text to synthesize */
     text: string;
-    /** Model to use: 'kugel-1-turbo' (fast) or 'kugel-1' (premium). Default: 'kugel-1-turbo' */
+    /** Model to use. Default: 'kugel-3'. Legacy ids (kugel-2.5, kugel-1-turbo, …) still accepted; they alias to kugel-3 server-side. */
     modelId?: string;
     /** Voice ID to use */
     voiceId?: number;
@@ -296,7 +296,7 @@ interface GenerateOptions {
 interface StreamConfig {
     /** Voice ID to use */
     voiceId?: number;
-    /** Model ID ('kugel-1-turbo' or 'kugel-1'). Default: 'kugel-1-turbo' */
+    /** Model ID. Default: 'kugel-3'. Legacy ids still accepted; they alias to kugel-3 server-side. */
     modelId?: string;
     /** CFG scale for generation */
     cfgScale?: number;
@@ -1224,6 +1224,8 @@ declare const ErrorCodes: {
     readonly VALIDATION: "VALIDATION_ERROR";
     readonly INTERNAL: "INTERNAL_ERROR";
     readonly NOT_FOUND: "NOT_FOUND";
+    readonly MISSING_VOICE_ID: "MISSING_VOICE_ID";
+    readonly TOO_MANY_CONTEXTS: "TOO_MANY_CONTEXTS";
 };
 type ErrorCode = typeof ErrorCodes[keyof typeof ErrorCodes];
 declare const WsCloseCodes: {
@@ -1305,11 +1307,12 @@ interface HttpResponseLike {
 declare function classifyHttpError(status: number, bodyText: string, headers: HttpResponseLike['headers']): KugelAudioError;
 /**
  * Build a `KugelAudioError` from a server-sent WebSocket error frame
- * (`{error, error_code, retry_after}`).
+ * (`{error, error_code, code}`).
  */
 declare function classifyWsFrame(data: {
     error?: string;
     error_code?: string;
+    code?: number;
     retry_after?: number;
 }): KugelAudioError;
 /**

package/dist/index.d.ts

@@ -217,7 +217,7 @@ interface WordTimestamp {
 interface GenerateOptions {
     /** Text to synthesize */
     text: string;
-    /** Model to use: 'kugel-1-turbo' (fast) or 'kugel-1' (premium). Default: 'kugel-1-turbo' */
+    /** Model to use. Default: 'kugel-3'. Legacy ids (kugel-2.5, kugel-1-turbo, …) still accepted; they alias to kugel-3 server-side. */
     modelId?: string;
     /** Voice ID to use */
     voiceId?: number;
@@ -296,7 +296,7 @@ interface GenerateOptions {
 interface StreamConfig {
     /** Voice ID to use */
     voiceId?: number;
-    /** Model ID ('kugel-1-turbo' or 'kugel-1'). Default: 'kugel-1-turbo' */
+    /** Model ID. Default: 'kugel-3'. Legacy ids still accepted; they alias to kugel-3 server-side. */
     modelId?: string;
     /** CFG scale for generation */
     cfgScale?: number;
@@ -1224,6 +1224,8 @@ declare const ErrorCodes: {
     readonly VALIDATION: "VALIDATION_ERROR";
     readonly INTERNAL: "INTERNAL_ERROR";
     readonly NOT_FOUND: "NOT_FOUND";
+    readonly MISSING_VOICE_ID: "MISSING_VOICE_ID";
+    readonly TOO_MANY_CONTEXTS: "TOO_MANY_CONTEXTS";
 };
 type ErrorCode = typeof ErrorCodes[keyof typeof ErrorCodes];
 declare const WsCloseCodes: {
@@ -1305,11 +1307,12 @@ interface HttpResponseLike {
 declare function classifyHttpError(status: number, bodyText: string, headers: HttpResponseLike['headers']): KugelAudioError;
 /**
  * Build a `KugelAudioError` from a server-sent WebSocket error frame
- * (`{error, error_code, retry_after}`).
+ * (`{error, error_code, code}`).
  */
 declare function classifyWsFrame(data: {
     error?: string;
     error_code?: string;
+    code?: number;
     retry_after?: number;
 }): KugelAudioError;
 /**

package/dist/index.js

@@ -233,7 +233,9 @@ var ErrorCodes = {
   EMPTY_AUDIO: "EMPTY_AUDIO",
   VALIDATION: "VALIDATION_ERROR",
   INTERNAL: "INTERNAL_ERROR",
-  NOT_FOUND: "NOT_FOUND"
+  NOT_FOUND: "NOT_FOUND",
+  MISSING_VOICE_ID: "MISSING_VOICE_ID",
+  TOO_MANY_CONTEXTS: "TOO_MANY_CONTEXTS"
 };
 var WsCloseCodes = {
   UNAUTHORIZED: 4001,
@@ -317,10 +319,10 @@ function build(status, errorCode, message, opts = {}) {
   if (errorCode === ErrorCodes.INSUFFICIENT_CREDITS || status === 402) {
     return new InsufficientCreditsError(message || void 0, common);
   }
-  if (errorCode === ErrorCodes.RATE_LIMITED || status === 429) {
+  if (errorCode === ErrorCodes.RATE_LIMITED || errorCode === ErrorCodes.TOO_MANY_CONTEXTS || status === 429) {
     return new RateLimitError(message || void 0, common);
   }
-  if (errorCode === ErrorCodes.VALIDATION || status === 400) {
+  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) {
@@ -380,8 +382,9 @@ function classifyHttpError(status, bodyText, headers) {
 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(void 0, errorCode, message, { retryAfter });
+  return build(status, errorCode, message, { retryAfter });
 }
 function classifyWsClose(code, reason) {
   const reasonTxt = (reason ?? "").trim();
@@ -509,10 +512,75 @@ 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";
 var SUPPORTED_REGIONS = ["eu", "us", "global"];
+var SDK_NAME = "js";
+var SDK_VERSION = package_default.version;
 var REGION_PREFIXES = ["eu-", "us-", "global-"];
 function parseApiKey(apiKey) {
   for (const prefix of REGION_PREFIXES) {
@@ -522,6 +590,16 @@ function parseApiKey(apiKey) {
   }
   return { cleanKey: apiKey };
 }
+function sdkHeaders() {
+  return {
+    "X-KugelAudio-SDK": SDK_NAME,
+    "X-KugelAudio-SDK-Version": SDK_VERSION
+  };
+}
+function appendSdkQuery(url) {
+  const separator = url.includes("?") ? "&" : "?";
+  return `${url}${separator}sdk=${encodeURIComponent(SDK_NAME)}&sdk_version=${encodeURIComponent(SDK_VERSION)}`;
+}
 function createWs(url) {
   const WS = getWebSocket();
   return new WS(url);
@@ -890,7 +968,7 @@ var TTSResource = class {
     if (this.client.orgId !== void 0) {
       url += `&org_id=${this.client.orgId}`;
     }
-    return url;
+    return appendSdkQuery(url);
   }
   /**
    * Get or create a WebSocket connection for connection pooling.
@@ -1038,7 +1116,7 @@ var TTSResource = class {
       callbacks.onOpen?.();
       ws.send(JSON.stringify({
         text: options.text,
-        model_id: options.modelId || "kugel-1-turbo",
+        model_id: options.modelId || "kugel-3",
         voice_id: options.voiceId,
         cfg_scale: options.cfgScale ?? 2,
         ...options.temperature !== void 0 && { temperature: options.temperature },
@@ -1064,7 +1142,7 @@ var TTSResource = class {
         callbacks.onOpen?.();
         ws.send(JSON.stringify({
           text: options.text,
-          model_id: options.modelId || "kugel-1-turbo",
+          model_id: options.modelId || "kugel-3",
           voice_id: options.voiceId,
           cfg_scale: options.cfgScale ?? 2,
           max_new_tokens: options.maxNewTokens ?? 2048,
@@ -1294,7 +1372,7 @@ var MultiContextSession = class {
     } else {
       authParam = "api_key";
     }
-    const url = `${wsUrl}/ws/tts/multi?${authParam}=${this.client.apiKey}`;
+    const url = appendSdkQuery(`${wsUrl}/ws/tts/multi?${authParam}=${this.client.apiKey}`);
     this.ws = createWs(url);
     const ws = this.ws;
     ws.onmessage = (event) => {
@@ -1303,7 +1381,7 @@ var MultiContextSession = class {
         const data = JSON.parse(messageData);
         if (data.error) {
           this.callbacks.onError?.(
-            new KugelAudioError(data.error),
+            classifyWsFrame(data),
             data.context_id
           );
           return;
@@ -1515,7 +1593,7 @@ var StreamingSession = class {
     } else {
       authParam = "api_key";
     }
-    const url = `${wsUrl}/ws/tts/stream?${authParam}=${this.client.apiKey}`;
+    const url = appendSdkQuery(`${wsUrl}/ws/tts/stream?${authParam}=${this.client.apiKey}`);
     this.ws = createWs(url);
     const ws = this.ws;
     ws.onmessage = (event) => {
@@ -1919,7 +1997,8 @@ var KugelAudio = class _KugelAudio {
     const headers = {
       "Content-Type": "application/json",
       "X-API-Key": this._apiKey,
-      "Authorization": `Bearer ${this._apiKey}`
+      "Authorization": `Bearer ${this._apiKey}`,
+      ...sdkHeaders()
     };
     const controller = new AbortController();
     const timeoutId = setTimeout(() => controller.abort(), this._timeout);
@@ -1959,7 +2038,8 @@ var KugelAudio = class _KugelAudio {
     const url = `${this._apiUrl}${path}`;
     const headers = {
       "X-API-Key": this._apiKey,
-      "Authorization": `Bearer ${this._apiKey}`
+      "Authorization": `Bearer ${this._apiKey}`,
+      ...sdkHeaders()
     };
     const controller = new AbortController();
     const timeoutId = setTimeout(() => controller.abort(), this._timeout);

package/dist/index.mjs

@@ -195,7 +195,9 @@ var ErrorCodes = {
   EMPTY_AUDIO: "EMPTY_AUDIO",
   VALIDATION: "VALIDATION_ERROR",
   INTERNAL: "INTERNAL_ERROR",
-  NOT_FOUND: "NOT_FOUND"
+  NOT_FOUND: "NOT_FOUND",
+  MISSING_VOICE_ID: "MISSING_VOICE_ID",
+  TOO_MANY_CONTEXTS: "TOO_MANY_CONTEXTS"
 };
 var WsCloseCodes = {
   UNAUTHORIZED: 4001,
@@ -279,10 +281,10 @@ function build(status, errorCode, message, opts = {}) {
   if (errorCode === ErrorCodes.INSUFFICIENT_CREDITS || status === 402) {
     return new InsufficientCreditsError(message || void 0, common);
   }
-  if (errorCode === ErrorCodes.RATE_LIMITED || status === 429) {
+  if (errorCode === ErrorCodes.RATE_LIMITED || errorCode === ErrorCodes.TOO_MANY_CONTEXTS || status === 429) {
     return new RateLimitError(message || void 0, common);
   }
-  if (errorCode === ErrorCodes.VALIDATION || status === 400) {
+  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) {
@@ -342,8 +344,9 @@ function classifyHttpError(status, bodyText, headers) {
 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(void 0, errorCode, message, { retryAfter });
+  return build(status, errorCode, message, { retryAfter });
 }
 function classifyWsClose(code, reason) {
   const reasonTxt = (reason ?? "").trim();
@@ -471,10 +474,75 @@ 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";
 var SUPPORTED_REGIONS = ["eu", "us", "global"];
+var SDK_NAME = "js";
+var SDK_VERSION = package_default.version;
 var REGION_PREFIXES = ["eu-", "us-", "global-"];
 function parseApiKey(apiKey) {
   for (const prefix of REGION_PREFIXES) {
@@ -484,6 +552,16 @@ function parseApiKey(apiKey) {
   }
   return { cleanKey: apiKey };
 }
+function sdkHeaders() {
+  return {
+    "X-KugelAudio-SDK": SDK_NAME,
+    "X-KugelAudio-SDK-Version": SDK_VERSION
+  };
+}
+function appendSdkQuery(url) {
+  const separator = url.includes("?") ? "&" : "?";
+  return `${url}${separator}sdk=${encodeURIComponent(SDK_NAME)}&sdk_version=${encodeURIComponent(SDK_VERSION)}`;
+}
 function createWs(url) {
   const WS = getWebSocket();
   return new WS(url);
@@ -852,7 +930,7 @@ var TTSResource = class {
     if (this.client.orgId !== void 0) {
       url += `&org_id=${this.client.orgId}`;
     }
-    return url;
+    return appendSdkQuery(url);
   }
   /**
    * Get or create a WebSocket connection for connection pooling.
@@ -1000,7 +1078,7 @@ var TTSResource = class {
       callbacks.onOpen?.();
       ws.send(JSON.stringify({
         text: options.text,
-        model_id: options.modelId || "kugel-1-turbo",
+        model_id: options.modelId || "kugel-3",
         voice_id: options.voiceId,
         cfg_scale: options.cfgScale ?? 2,
         ...options.temperature !== void 0 && { temperature: options.temperature },
@@ -1026,7 +1104,7 @@ var TTSResource = class {
         callbacks.onOpen?.();
         ws.send(JSON.stringify({
           text: options.text,
-          model_id: options.modelId || "kugel-1-turbo",
+          model_id: options.modelId || "kugel-3",
           voice_id: options.voiceId,
           cfg_scale: options.cfgScale ?? 2,
           max_new_tokens: options.maxNewTokens ?? 2048,
@@ -1256,7 +1334,7 @@ var MultiContextSession = class {
     } else {
       authParam = "api_key";
     }
-    const url = `${wsUrl}/ws/tts/multi?${authParam}=${this.client.apiKey}`;
+    const url = appendSdkQuery(`${wsUrl}/ws/tts/multi?${authParam}=${this.client.apiKey}`);
     this.ws = createWs(url);
     const ws = this.ws;
     ws.onmessage = (event) => {
@@ -1265,7 +1343,7 @@ var MultiContextSession = class {
         const data = JSON.parse(messageData);
         if (data.error) {
           this.callbacks.onError?.(
-            new KugelAudioError(data.error),
+            classifyWsFrame(data),
             data.context_id
           );
           return;
@@ -1477,7 +1555,7 @@ var StreamingSession = class {
     } else {
       authParam = "api_key";
     }
-    const url = `${wsUrl}/ws/tts/stream?${authParam}=${this.client.apiKey}`;
+    const url = appendSdkQuery(`${wsUrl}/ws/tts/stream?${authParam}=${this.client.apiKey}`);
     this.ws = createWs(url);
     const ws = this.ws;
     ws.onmessage = (event) => {
@@ -1881,7 +1959,8 @@ var KugelAudio = class _KugelAudio {
     const headers = {
       "Content-Type": "application/json",
       "X-API-Key": this._apiKey,
-      "Authorization": `Bearer ${this._apiKey}`
+      "Authorization": `Bearer ${this._apiKey}`,
+      ...sdkHeaders()
     };
     const controller = new AbortController();
     const timeoutId = setTimeout(() => controller.abort(), this._timeout);
@@ -1921,7 +2000,8 @@ var KugelAudio = class _KugelAudio {
     const url = `${this._apiUrl}${path}`;
     const headers = {
       "X-API-Key": this._apiKey,
-      "Authorization": `Bearer ${this._apiKey}`
+      "Authorization": `Bearer ${this._apiKey}`,
+      ...sdkHeaders()
     };
     const controller = new AbortController();
     const timeoutId = setTimeout(() => controller.abort(), this._timeout);

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "kugelaudio",
-  "version": "0.6.0",
+  "version": "0.7.0",
   "description": "Official JavaScript/TypeScript SDK for KugelAudio TTS API",
   "main": "dist/index.js",
   "module": "dist/index.mjs",

package/src/client.test.ts

@@ -8,6 +8,7 @@
 
 import { describe, it, expect, vi, beforeEach, afterEach } from 'vitest';
 import { KugelAudio } from './client';
+import { RateLimitError } from './errors';
 
 // ---------------------------------------------------------------------------
 // Minimal WebSocket mock
@@ -17,6 +18,7 @@ type WsListener = (event: { data: string }) => void;
 type WsCloseListener = (event: { code: number }) => void;
 
 interface MockWs {
+  url: string;
   readyState: number;
   onopen: (() => void) | null;
   onmessage: WsListener | null;
@@ -32,6 +34,7 @@ let mockWs: MockWs;
 vi.mock('./websocket', () => ({
   getWebSocket: () => {
     return class MockWebSocket {
+      url: string;
       readyState = 0; // CONNECTING
       onopen: (() => void) | null = null;
       onmessage: WsListener | null = null;
@@ -41,7 +44,8 @@ vi.mock('./websocket', () => ({
       close = vi.fn();
       ping = vi.fn();
 
-      constructor() {
+      constructor(url: string) {
+        this.url = url;
         mockWs = this as unknown as MockWs;
         // Simulate async open
         setTimeout(() => {
@@ -246,6 +250,43 @@ describe('KugelAudio multi-region', () => {
   });
 });
 
+describe('KugelAudio SDK metadata', () => {
+  it('adds SDK metadata headers to HTTP requests', async () => {
+    const originalFetch = globalThis.fetch;
+    const fetchMock = vi.fn<typeof fetch>(async () => ({
+      ok: true,
+      json: async () => ({ models: [] }),
+    } as Response));
+    globalThis.fetch = fetchMock;
+
+    try {
+      const client = new KugelAudio({ apiKey: 'ka_test123' });
+      await client.models.list();
+    } finally {
+      globalThis.fetch = originalFetch;
+    }
+
+    expect(fetchMock).toHaveBeenCalledTimes(1);
+    const [, init] = fetchMock.mock.calls[0];
+    expect(init).toMatchObject({
+      headers: {
+        'X-KugelAudio-SDK': 'js',
+        'X-KugelAudio-SDK-Version': '0.6.1',
+      },
+    });
+  });
+
+  it('adds SDK metadata query params to WebSocket URLs', async () => {
+    const client = new KugelAudio({ apiKey: 'ka_test123' });
+
+    client.tts.toReadable({ text: 'metadata test' });
+    await new Promise<void>((r) => setTimeout(r, 10));
+
+    expect(mockWs.url).toContain('sdk=js');
+    expect(mockWs.url).toContain('sdk_version=0.6.1');
+  });
+});
+
 // ---------------------------------------------------------------------------
 // Keepalive ping tests
 // ---------------------------------------------------------------------------
@@ -660,4 +701,27 @@ describe('MultiContextSession closeContext', () => {
     expect(sent.close_context).toBe(true);
     expect(sent.immediate).toBeUndefined();
   });
+
+  it('maps ingress context-cap errors to typed callback errors', async () => {
+    const errors: Array<{ contextId?: string; error: Error }> = [];
+    const session = client.tts.createMultiContextSession({ defaultVoiceId: 1 });
+    await session.connect({
+      onError: (error, contextId) => errors.push({ contextId, error }),
+    });
+
+    mockWs.onmessage?.({
+      data: JSON.stringify({
+        error: 'Too many concurrent contexts',
+        error_code: 'TOO_MANY_CONTEXTS',
+        code: 429,
+        context_id: 'ctx1',
+      }),
+    });
+
+    expect(errors).toHaveLength(1);
+    expect(errors[0].contextId).toBe('ctx1');
+    expect(errors[0].error).toBeInstanceOf(RateLimitError);
+    expect((errors[0].error as RateLimitError).statusCode).toBe(429);
+    expect((errors[0].error as RateLimitError).errorCode).toBe('TOO_MANY_CONTEXTS');
+  });
 });

package/src/client.ts

@@ -33,10 +33,13 @@ import { base64ToArrayBuffer } from './utils';
 import { getWebSocket } from './websocket';
 
 import type { Region } from './types';
+import packageJson from '../package.json';
 
 const DEFAULT_API_URL = 'https://api.kugelaudio.com';
 const EU_API_URL = 'https://api.eu.kugelaudio.com';
 const SUPPORTED_REGIONS = ['eu', 'us', 'global'] as const;
+const SDK_NAME = 'js';
+const SDK_VERSION = packageJson.version;
 
 const REGION_PREFIXES = ['eu-', 'us-', 'global-'] as const;
 
@@ -49,6 +52,18 @@ function parseApiKey(apiKey: string): { cleanKey: string; detectedRegion?: Regio
   return { cleanKey: apiKey };
 }
 
+function sdkHeaders(): Record<string, string> {
+  return {
+    'X-KugelAudio-SDK': SDK_NAME,
+    'X-KugelAudio-SDK-Version': SDK_VERSION,
+  };
+}
+
+function appendSdkQuery(url: string): string {
+  const separator = url.includes('?') ? '&' : '?';
+  return `${url}${separator}sdk=${encodeURIComponent(SDK_NAME)}&sdk_version=${encodeURIComponent(SDK_VERSION)}`;
+}
+
 /**
  * Create a new WebSocket instance.
  * Lazily resolves the constructor to avoid top-level side-effects
@@ -491,7 +506,7 @@ class TTSResource {
     if (this.client.orgId !== undefined) {
       url += `&org_id=${this.client.orgId}`;
     }
-    return url;
+    return appendSdkQuery(url);
   }
 
   /**
@@ -692,7 +707,7 @@ class TTSResource {
 
       ws.send(JSON.stringify({
         text: options.text,
-        model_id: options.modelId || 'kugel-1-turbo',
+        model_id: options.modelId || 'kugel-3',
         voice_id: options.voiceId,
         cfg_scale: options.cfgScale ?? 2.0,
         ...(options.temperature !== undefined && { temperature: options.temperature }),
@@ -724,7 +739,7 @@ class TTSResource {
         // Send TTS request
         ws.send(JSON.stringify({
           text: options.text,
-          model_id: options.modelId || 'kugel-1-turbo',
+          model_id: options.modelId || 'kugel-3',
           voice_id: options.voiceId,
           cfg_scale: options.cfgScale ?? 2.0,
           max_new_tokens: options.maxNewTokens ?? 2048,
@@ -873,7 +888,7 @@ class TTSResource {
     }
   }
 
-  private parseError(data: { error?: string; error_code?: string; retry_after?: number }): Error {
+  private parseError(data: { error?: string; error_code?: string; code?: number; retry_after?: number }): Error {
     return classifyWsFrame(data);
   }
 
@@ -1003,7 +1018,7 @@ class MultiContextSession {
       authParam = 'api_key';
     }
 
-    const url = `${wsUrl}/ws/tts/multi?${authParam}=${this.client.apiKey}`;
+    const url = appendSdkQuery(`${wsUrl}/ws/tts/multi?${authParam}=${this.client.apiKey}`);
     this.ws = createWs(url);
     const ws = this.ws;
 
@@ -1019,7 +1034,7 @@ class MultiContextSession {
 
         if (data.error) {
           this.callbacks.onError?.(
-            new KugelAudioError(data.error),
+            classifyWsFrame(data),
             data.context_id
           );
           return;
@@ -1317,7 +1332,7 @@ class StreamingSession {
       authParam = 'api_key';
     }
 
-    const url = `${wsUrl}/ws/tts/stream?${authParam}=${this.client.apiKey}`;
+    const url = appendSdkQuery(`${wsUrl}/ws/tts/stream?${authParam}=${this.client.apiKey}`);
     this.ws = createWs(url);
     const ws = this.ws;
 
@@ -1865,6 +1880,7 @@ export class KugelAudio {
       'Content-Type': 'application/json',
       'X-API-Key': this._apiKey,
       'Authorization': `Bearer ${this._apiKey}`,
+      ...sdkHeaders(),
     };
 
     const controller = new AbortController();
@@ -1913,6 +1929,7 @@ export class KugelAudio {
     const headers: Record<string, string> = {
       'X-API-Key': this._apiKey,
       'Authorization': `Bearer ${this._apiKey}`,
+      ...sdkHeaders(),
     };
 
     const controller = new AbortController();

package/src/errors.ts

@@ -17,6 +17,8 @@ export const ErrorCodes = {
   VALIDATION: 'VALIDATION_ERROR',
   INTERNAL: 'INTERNAL_ERROR',
   NOT_FOUND: 'NOT_FOUND',
+  MISSING_VOICE_ID: 'MISSING_VOICE_ID',
+  TOO_MANY_CONTEXTS: 'TOO_MANY_CONTEXTS',
 } as const;
 export type ErrorCode = typeof ErrorCodes[keyof typeof ErrorCodes];
 
@@ -175,10 +177,18 @@ function build(
   if (errorCode === ErrorCodes.INSUFFICIENT_CREDITS || status === 402) {
     return new InsufficientCreditsError(message || undefined, common);
   }
-  if (errorCode === ErrorCodes.RATE_LIMITED || status === 429) {
+  if (
+    errorCode === ErrorCodes.RATE_LIMITED ||
+    errorCode === ErrorCodes.TOO_MANY_CONTEXTS ||
+    status === 429
+  ) {
     return new RateLimitError(message || undefined, common);
   }
-  if (errorCode === ErrorCodes.VALIDATION || status === 400) {
+  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) {
@@ -263,17 +273,19 @@ export function classifyHttpError(
 
 /**
  * Build a `KugelAudioError` from a server-sent WebSocket error frame
- * (`{error, error_code, retry_after}`).
+ * (`{error, error_code, code}`).
  */
 export function classifyWsFrame(data: {
   error?: string;
   error_code?: string;
+  code?: number;
   retry_after?: number;
 }): KugelAudioError {
   const errorCode = data.error_code;
   const message = data.error ?? 'Server reported an error.';
+  const status = typeof data.code === 'number' ? data.code : undefined;
   const retryAfter = typeof data.retry_after === 'number' ? data.retry_after : undefined;
-  return build(undefined, errorCode, message, { retryAfter });
+  return build(status, errorCode, message, { retryAfter });
 }
 
 /**

package/src/types.ts

@@ -240,7 +240,7 @@ export interface WordTimestamp {
 export interface GenerateOptions {
   /** Text to synthesize */
   text: string;
-  /** Model to use: 'kugel-1-turbo' (fast) or 'kugel-1' (premium). Default: 'kugel-1-turbo' */
+  /** Model to use. Default: 'kugel-3'. Legacy ids (kugel-2.5, kugel-1-turbo, …) still accepted; they alias to kugel-3 server-side. */
   modelId?: string;
   /** Voice ID to use */
   voiceId?: number;
@@ -320,7 +320,7 @@ export interface GenerateOptions {
 export interface StreamConfig {
   /** Voice ID to use */
   voiceId?: number;
-  /** Model ID ('kugel-1-turbo' or 'kugel-1'). Default: 'kugel-1-turbo' */
+  /** Model ID. Default: 'kugel-3'. Legacy ids still accepted; they alias to kugel-3 server-side. */
   modelId?: string;
   /** CFG scale for generation */
   cfgScale?: number;