kugelaudio 0.7.0 → 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") {
@@ -515,7 +533,7 @@ function getWebSocket() {
 // package.json
 var package_default = {
   name: "kugelaudio",
-  version: "0.7.0",
+  version: "0.8.0",
   description: "Official JavaScript/TypeScript SDK for KugelAudio TTS API",
   main: "dist/index.js",
   module: "dist/index.mjs",
@@ -1031,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);
@@ -1122,11 +1141,15 @@ var TTSResource = class {
         ...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 }
       }));
     });
   }
@@ -1147,11 +1170,15 @@ var TTSResource = class {
           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) => {
@@ -1173,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();
@@ -1343,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 || {};
   }
@@ -1353,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.
    *
@@ -1406,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) {
@@ -1451,6 +1502,7 @@ var MultiContextSession = class {
         this.ws = null;
         this.isStarted = false;
         this.contexts.clear();
+        this.requestedContexts.clear();
       };
     });
   }
@@ -1461,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
@@ -1468,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));
   }
@@ -1495,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({
@@ -1553,6 +1610,7 @@ var MultiContextSession = class {
     this.ws = null;
     this.isStarted = false;
     this.contexts.clear();
+    this.requestedContexts.clear();
   }
   /**
    * Get active context IDs.
@@ -1571,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.
    *
@@ -1638,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,
@@ -1706,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;
@@ -1714,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));
@@ -2093,5 +2170,6 @@ var KugelAudio = class _KugelAudio {
   classifyWsHandshakeError,
   createWavBlob,
   createWavFile,
-  decodePCM16
+  decodePCM16,
+  parseSessionUsage
 });

package/dist/index.mjs

@@ -391,6 +391,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") {
@@ -477,7 +494,7 @@ function getWebSocket() {
 // package.json
 var package_default = {
   name: "kugelaudio",
-  version: "0.7.0",
+  version: "0.8.0",
   description: "Official JavaScript/TypeScript SDK for KugelAudio TTS API",
   main: "dist/index.js",
   module: "dist/index.mjs",
@@ -993,7 +1010,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);
@@ -1084,11 +1102,15 @@ var TTSResource = class {
         ...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 }
       }));
     });
   }
@@ -1109,11 +1131,15 @@ var TTSResource = class {
           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) => {
@@ -1135,7 +1161,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();
@@ -1305,7 +1332,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 || {};
   }
@@ -1315,6 +1346,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.
    *
@@ -1368,12 +1411,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) {
@@ -1413,6 +1463,7 @@ var MultiContextSession = class {
         this.ws = null;
         this.isStarted = false;
         this.contexts.clear();
+        this.requestedContexts.clear();
       };
     });
   }
@@ -1423,6 +1474,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
@@ -1430,23 +1482,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));
   }
@@ -1457,7 +1513,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({
@@ -1515,6 +1571,7 @@ var MultiContextSession = class {
     this.ws = null;
     this.isStarted = false;
     this.contexts.clear();
+    this.requestedContexts.clear();
   }
   /**
    * Get active context IDs.
@@ -1533,10 +1590,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.
    *
@@ -1600,7 +1666,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,
@@ -1668,6 +1742,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;
@@ -1676,6 +1751,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));
@@ -2054,5 +2130,6 @@ export {
   classifyWsHandshakeError,
   createWavBlob,
   createWavFile,
-  decodePCM16
+  decodePCM16,
+  parseSessionUsage
 };

package/package.json

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