kugelaudio 0.6.1 → 0.8.0

package/dist/index.js

@@ -39,7 +39,8 @@ __export(index_exports, {
   classifyWsHandshakeError: () => classifyWsHandshakeError,
   createWavBlob: () => createWavBlob,
   createWavFile: () => createWavFile,
-  decodePCM16: () => decodePCM16
+  decodePCM16: () => decodePCM16,
+  parseSessionUsage: () => parseSessionUsage
 });
 module.exports = __toCommonJS(index_exports);
 
@@ -429,6 +430,23 @@ function classifyWsHandshakeError(err) {
   return build(status, void 0, typeof e.message === "string" ? e.message : "");
 }
 
+// src/types.ts
+function parseSessionUsage(data) {
+  const raw = data.usage;
+  const source = raw && typeof raw === "object" ? raw : data;
+  const audioSeconds = typeof source.audio_seconds === "number" ? source.audio_seconds : typeof data.total_audio_seconds === "number" ? data.total_audio_seconds : void 0;
+  if (audioSeconds === void 0) return null;
+  const costCents = typeof source.cost_cents === "number" ? source.cost_cents : null;
+  return {
+    audioSeconds,
+    costCents,
+    currency: typeof source.currency === "string" ? source.currency : void 0,
+    characters: typeof source.characters === "number" ? source.characters : void 0,
+    modelId: typeof source.model_id === "string" ? source.model_id : void 0,
+    costAvailable: costCents !== null
+  };
+}
+
 // src/utils.ts
 function base64ToArrayBuffer(base64) {
   if (typeof atob === "function") {
@@ -512,10 +530,75 @@ function getWebSocket() {
   );
 }
 
+// package.json
+var package_default = {
+  name: "kugelaudio",
+  version: "0.8.0",
+  description: "Official JavaScript/TypeScript SDK for KugelAudio TTS API",
+  main: "dist/index.js",
+  module: "dist/index.mjs",
+  types: "dist/index.d.ts",
+  exports: {
+    ".": {
+      types: "./dist/index.d.ts",
+      import: "./dist/index.mjs",
+      require: "./dist/index.js"
+    }
+  },
+  files: [
+    "dist",
+    "src",
+    "LICENSE",
+    "CHANGELOG.md"
+  ],
+  scripts: {
+    build: "tsup src/index.ts --format cjs,esm --dts",
+    dev: "tsup src/index.ts --format cjs,esm --dts --watch",
+    lint: "eslint src/",
+    test: "vitest run",
+    "test:watch": "vitest",
+    prepublishOnly: "npm run build"
+  },
+  keywords: [
+    "tts",
+    "text-to-speech",
+    "audio",
+    "streaming",
+    "websocket",
+    "kugelaudio"
+  ],
+  author: "KugelAudio <hello@kugelaudio.com>",
+  license: "MIT",
+  repository: {
+    type: "git",
+    url: "https://github.com/Kugelaudio/KugelAudio",
+    directory: "sdks/js"
+  },
+  homepage: "https://kugelaudio.com",
+  bugs: {
+    url: "https://github.com/Kugelaudio/KugelAudio/issues"
+  },
+  devDependencies: {
+    "@types/node": "^25.3.2",
+    tsup: "^8.0.0",
+    typescript: "^6.0.2",
+    vitest: "^4.0.18"
+  },
+  engines: {
+    node: ">=18.0.0"
+  },
+  dependencies: {
+    tsx: "^4.21.0",
+    ws: "^8.18.0"
+  }
+};
+
 // src/client.ts
 var DEFAULT_API_URL = "https://api.kugelaudio.com";
 var EU_API_URL = "https://api.eu.kugelaudio.com";
 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 +608,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 +986,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.
@@ -956,7 +1049,8 @@ var TTSResource = class {
             durationMs: data.dur_ms,
             generationMs: data.gen_ms,
             rtf: data.rtf,
-            error: data.error
+            error: data.error,
+            usage: parseSessionUsage(data) ?? void 0
           };
           pending.callbacks.onFinal?.(stats);
           this.pendingRequests.delete(requestId);
@@ -1041,17 +1135,21 @@ 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 },
         max_new_tokens: options.maxNewTokens ?? 2048,
         sample_rate: options.sampleRate ?? 24e3,
+        ...options.outputFormat && { output_format: options.outputFormat },
         normalize: options.normalize ?? true,
         ...options.language && { language: options.language },
         ...options.wordTimestamps && { word_timestamps: true },
         ...options.speed !== void 0 && { speed: options.speed },
-        ...options.projectId !== void 0 && { project_id: options.projectId }
+        ...options.projectId !== void 0 && { project_id: options.projectId },
+        // [] is meaningful (explicit opt-out) and must be sent; only
+        // undefined (use the project default) is omitted.
+        ...options.dictionaryIds !== void 0 && { dictionary_ids: options.dictionaryIds }
       }));
     });
   }
@@ -1067,16 +1165,20 @@ 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,
           sample_rate: options.sampleRate ?? 24e3,
+          ...options.outputFormat && { output_format: options.outputFormat },
           normalize: options.normalize ?? true,
           ...options.language && { language: options.language },
           ...options.wordTimestamps && { word_timestamps: true },
           ...options.speed !== void 0 && { speed: options.speed },
-          ...options.projectId !== void 0 && { project_id: options.projectId }
+          ...options.projectId !== void 0 && { project_id: options.projectId },
+          // [] is meaningful (explicit opt-out) and must be sent; only
+          // undefined (use the project default) is omitted.
+          ...options.dictionaryIds !== void 0 && { dictionary_ids: options.dictionaryIds }
         }));
       };
       ws.onmessage = (event) => {
@@ -1098,7 +1200,8 @@ var TTSResource = class {
               durationMs: data.dur_ms,
               generationMs: data.gen_ms,
               rtf: data.rtf,
-              error: data.error
+              error: data.error,
+              usage: parseSessionUsage(data) ?? void 0
             };
             callbacks.onFinal?.(stats);
             ws.close();
@@ -1268,7 +1371,11 @@ var MultiContextSession = class {
     this.ws = null;
     this.callbacks = {};
     this.contexts = /* @__PURE__ */ new Set();
+    /** Contexts a create message has been sent for (not yet necessarily
+     *  confirmed by the server via context_created). */
+    this.requestedContexts = /* @__PURE__ */ new Set();
     this._sessionId = null;
+    this._contextUsage = /* @__PURE__ */ new Map();
     this.isStarted = false;
     this.config = config || {};
   }
@@ -1278,6 +1385,18 @@ var MultiContextSession = class {
   get sessionId() {
     return this._sessionId;
   }
+  /**
+   * Per-context usage (audio time + amount charged) for a closed context, or
+   * null if that context hasn't closed yet. Each context is its own
+   * conversation — use this to bill per conversation. See {@link SessionUsage}.
+   */
+  usageFor(contextId) {
+    return this._contextUsage.get(contextId) ?? null;
+  }
+  /** Map of context_id → per-context usage for all closed contexts. */
+  get contextUsage() {
+    return new Map(this._contextUsage);
+  }
   /**
    * Connect to the multi-context WebSocket endpoint.
    *
@@ -1297,7 +1416,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) => {
@@ -1331,12 +1450,19 @@ var MultiContextSession = class {
           };
           this.callbacks.onChunk?.(chunk);
         }
+        if (data.final && data.context_id) {
+          this.callbacks.onFinal?.(data.context_id);
+        }
         if (data.context_closed) {
           this.contexts.delete(data.context_id);
-          this.callbacks.onContextClosed?.(data.context_id);
+          this.requestedContexts.delete(data.context_id);
+          const ctxUsage = parseSessionUsage(data) ?? void 0;
+          if (ctxUsage) this._contextUsage.set(data.context_id, ctxUsage);
+          this.callbacks.onContextClosed?.(data.context_id, ctxUsage);
         }
         if (data.context_timeout) {
           this.contexts.delete(data.context_id);
+          this.requestedContexts.delete(data.context_id);
           this.callbacks.onContextTimeout?.(data.context_id);
         }
         if (data.session_closed) {
@@ -1376,6 +1502,7 @@ var MultiContextSession = class {
         this.ws = null;
         this.isStarted = false;
         this.contexts.clear();
+        this.requestedContexts.clear();
       };
     });
   }
@@ -1386,6 +1513,7 @@ var MultiContextSession = class {
     if (!this.ws || this.ws.readyState !== WS_OPEN) {
       throw new KugelAudioError("WebSocket not connected");
     }
+    this.requestedContexts.add(contextId);
     const msg = {
       text: " ",
       context_id: contextId
@@ -1393,23 +1521,27 @@ var MultiContextSession = class {
     if (!this.isStarted) {
       warnIfNoLanguage(this.config.language, this.config.normalize);
       if (this.config.sampleRate) msg.sample_rate = this.config.sampleRate;
+      if (this.config.outputFormat) msg.output_format = this.config.outputFormat;
       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.dictionaryIds !== void 0) msg.dictionary_ids = this.config.dictionaryIds;
       if (this.config.inactivityTimeout) msg.inactivity_timeout = this.config.inactivityTimeout;
     }
+    const voiceSettings = {};
     const voiceId = options?.voiceId || this.config.defaultVoiceId;
-    if (voiceId) msg.voice_id = voiceId;
+    if (voiceId) voiceSettings.voice_id = voiceId;
     if (options?.voiceSettings) {
-      msg.voice_settings = {
-        stability: options.voiceSettings.stability,
-        similarity_boost: options.voiceSettings.similarityBoost,
-        style: options.voiceSettings.style,
-        use_speaker_boost: options.voiceSettings.useSpeakerBoost,
-        speed: options.voiceSettings.speed
-      };
+      voiceSettings.stability = options.voiceSettings.stability;
+      voiceSettings.similarity_boost = options.voiceSettings.similarityBoost;
+      voiceSettings.style = options.voiceSettings.style;
+      voiceSettings.use_speaker_boost = options.voiceSettings.useSpeakerBoost;
+      voiceSettings.speed = options.voiceSettings.speed;
+    }
+    if (Object.keys(voiceSettings).length > 0) {
+      msg.voice_settings = voiceSettings;
     }
     this.ws.send(JSON.stringify(msg));
   }
@@ -1420,7 +1552,7 @@ var MultiContextSession = class {
     if (!this.ws || this.ws.readyState !== WS_OPEN) {
       throw new KugelAudioError("WebSocket not connected");
     }
-    if (!this.contexts.has(contextId) && !this.isStarted) {
+    if (!this.requestedContexts.has(contextId) && !this.contexts.has(contextId)) {
       this.createContext(contextId);
     }
     this.ws.send(JSON.stringify({
@@ -1478,6 +1610,7 @@ var MultiContextSession = class {
     this.ws = null;
     this.isStarted = false;
     this.contexts.clear();
+    this.requestedContexts.clear();
   }
   /**
    * Get active context IDs.
@@ -1496,10 +1629,19 @@ var StreamingSession = class {
   constructor(client, config, callbacks) {
     this.ws = null;
     this.configSent = false;
+    this._lastUsage = null;
     this.client = client;
     this.config = config;
     this.callbacks = callbacks;
   }
+  /**
+   * Per-session usage from the most recently closed session, or null before
+   * the first session closes. Use this to bill your own customers per
+   * conversation. See {@link SessionUsage}.
+   */
+  get lastUsage() {
+    return this._lastUsage;
+  }
   /**
    * Open the WebSocket connection and authenticate.
    *
@@ -1518,7 +1660,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) => {
@@ -1563,7 +1705,15 @@ var StreamingSession = class {
         if (data.interrupted) {
           this.callbacks.onInterrupted?.();
         }
+        if (data.final) {
+          this.callbacks.onFinal?.(
+            data.total_audio_seconds ?? 0,
+            data.total_text_chunks ?? 0,
+            data.total_audio_chunks ?? 0
+          );
+        }
         if (data.session_closed) {
+          this._lastUsage = parseSessionUsage(data);
           this.callbacks.onSessionClosed?.(
             data.total_audio_seconds ?? 0,
             data.total_text_chunks ?? 0,
@@ -1631,6 +1781,7 @@ var StreamingSession = class {
       if (this.config.temperature !== void 0) msg.temperature = this.config.temperature;
       if (this.config.maxNewTokens !== void 0) msg.max_new_tokens = this.config.maxNewTokens;
       if (this.config.sampleRate !== void 0) msg.sample_rate = this.config.sampleRate;
+      if (this.config.outputFormat !== void 0) msg.output_format = this.config.outputFormat;
       if (this.config.flushTimeoutMs !== void 0) msg.flush_timeout_ms = this.config.flushTimeoutMs;
       if (this.config.maxBufferLength !== void 0) msg.max_buffer_length = this.config.maxBufferLength;
       if (this.config.normalize !== void 0) msg.normalize = this.config.normalize;
@@ -1639,6 +1790,7 @@ var StreamingSession = class {
       if (this.config.autoMode !== void 0) msg.auto_mode = this.config.autoMode;
       if (this.config.chunkLengthSchedule?.length) msg.chunk_length_schedule = this.config.chunkLengthSchedule;
       if (this.config.speed !== void 0) msg.speed = this.config.speed;
+      if (this.config.dictionaryIds !== void 0) msg.dictionary_ids = this.config.dictionaryIds;
       this.configSent = true;
     }
     this.ws.send(JSON.stringify(msg));
@@ -1922,7 +2074,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 +2115,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);
@@ -2016,5 +2170,6 @@ var KugelAudio = class _KugelAudio {
   classifyWsHandshakeError,
   createWavBlob,
   createWavFile,
-  decodePCM16
+  decodePCM16,
+  parseSessionUsage
 });