kugelaudio 0.6.1 → 0.7.0

package/CHANGELOG.md

@@ -1,3 +1,14 @@
+## [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

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;

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;

package/dist/index.js

@@ -512,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) {
@@ -525,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);
@@ -893,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.
@@ -1041,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 },
@@ -1067,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,
@@ -1297,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) => {
@@ -1518,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) => {
@@ -1922,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);
@@ -1962,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

@@ -474,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) {
@@ -487,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);
@@ -855,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.
@@ -1003,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 },
@@ -1029,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,
@@ -1259,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) => {
@@ -1480,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) => {
@@ -1884,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);
@@ -1924,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.1",
+  "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

@@ -18,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;
@@ -33,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;
@@ -42,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(() => {
@@ -247,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
 // ---------------------------------------------------------------------------

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,
@@ -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;
 
@@ -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/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;