kugelaudio 0.1.1

package/dist/index.mjs

@@ -0,0 +1,384 @@
+// src/errors.ts
+var KugelAudioError = class _KugelAudioError extends Error {
+  constructor(message, statusCode) {
+    super(message);
+    this.name = "KugelAudioError";
+    this.statusCode = statusCode;
+    Object.setPrototypeOf(this, _KugelAudioError.prototype);
+  }
+};
+var AuthenticationError = class _AuthenticationError extends KugelAudioError {
+  constructor(message = "Authentication failed") {
+    super(message, 401);
+    this.name = "AuthenticationError";
+    Object.setPrototypeOf(this, _AuthenticationError.prototype);
+  }
+};
+var RateLimitError = class _RateLimitError extends KugelAudioError {
+  constructor(message = "Rate limit exceeded") {
+    super(message, 429);
+    this.name = "RateLimitError";
+    Object.setPrototypeOf(this, _RateLimitError.prototype);
+  }
+};
+var InsufficientCreditsError = class _InsufficientCreditsError extends KugelAudioError {
+  constructor(message = "Insufficient credits") {
+    super(message, 403);
+    this.name = "InsufficientCreditsError";
+    Object.setPrototypeOf(this, _InsufficientCreditsError.prototype);
+  }
+};
+var ValidationError = class _ValidationError extends KugelAudioError {
+  constructor(message) {
+    super(message, 400);
+    this.name = "ValidationError";
+    Object.setPrototypeOf(this, _ValidationError.prototype);
+  }
+};
+var ConnectionError = class _ConnectionError extends KugelAudioError {
+  constructor(message = "Failed to connect to server") {
+    super(message, 503);
+    this.name = "ConnectionError";
+    Object.setPrototypeOf(this, _ConnectionError.prototype);
+  }
+};
+
+// src/utils.ts
+function base64ToArrayBuffer(base64) {
+  if (typeof atob === "function") {
+    const binary = atob(base64);
+    const bytes = new Uint8Array(binary.length);
+    for (let i = 0; i < binary.length; i++) {
+      bytes[i] = binary.charCodeAt(i);
+    }
+    return bytes.buffer;
+  } else {
+    const buffer = Buffer.from(base64, "base64");
+    return buffer.buffer.slice(buffer.byteOffset, buffer.byteOffset + buffer.byteLength);
+  }
+}
+function decodePCM16(base64) {
+  const buffer = base64ToArrayBuffer(base64);
+  const int16 = new Int16Array(buffer);
+  const float32 = new Float32Array(int16.length);
+  for (let i = 0; i < int16.length; i++) {
+    float32[i] = int16[i] / 32768;
+  }
+  return float32;
+}
+function createWavFile(audio, sampleRate) {
+  const dataSize = audio.byteLength;
+  const fileSize = 44 + dataSize;
+  const buffer = new ArrayBuffer(fileSize);
+  const view = new DataView(buffer);
+  writeString(view, 0, "RIFF");
+  view.setUint32(4, fileSize - 8, true);
+  writeString(view, 8, "WAVE");
+  writeString(view, 12, "fmt ");
+  view.setUint32(16, 16, true);
+  view.setUint16(20, 1, true);
+  view.setUint16(22, 1, true);
+  view.setUint32(24, sampleRate, true);
+  view.setUint32(28, sampleRate * 2, true);
+  view.setUint16(32, 2, true);
+  view.setUint16(34, 16, true);
+  writeString(view, 36, "data");
+  view.setUint32(40, dataSize, true);
+  const audioBytes = new Uint8Array(audio);
+  const wavBytes = new Uint8Array(buffer);
+  wavBytes.set(audioBytes, 44);
+  return buffer;
+}
+function writeString(view, offset, str) {
+  for (let i = 0; i < str.length; i++) {
+    view.setUint8(offset + i, str.charCodeAt(i));
+  }
+}
+function createWavBlob(audio, sampleRate) {
+  const wavBuffer = createWavFile(audio, sampleRate);
+  return new Blob([wavBuffer], { type: "audio/wav" });
+}
+
+// src/client.ts
+var DEFAULT_API_URL = "https://api.kugelaudio.com";
+var ModelsResource = class {
+  constructor(client) {
+    this.client = client;
+  }
+  /**
+   * List available TTS models.
+   */
+  async list() {
+    const response = await this.client.request("GET", "/v1/models");
+    return response.models.map((m) => ({
+      id: m.id,
+      name: m.name,
+      description: m.description || "",
+      parameters: m.parameters || "",
+      maxInputLength: m.max_input_length || 5e3,
+      sampleRate: m.sample_rate || 24e3
+    }));
+  }
+};
+var VoicesResource = class {
+  constructor(client) {
+    this.client = client;
+  }
+  /**
+   * List available voices.
+   */
+  async list(options) {
+    const params = new URLSearchParams();
+    if (options?.language) params.set("language", options.language);
+    if (options?.includePublic !== void 0) {
+      params.set("include_public", String(options.includePublic));
+    }
+    if (options?.limit) params.set("limit", String(options.limit));
+    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
+    }));
+  }
+  /**
+   * Get a specific voice by ID.
+   */
+  async get(voiceId) {
+    const v = await this.client.request("GET", `/v1/voices/${voiceId}`);
+    return {
+      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
+    };
+  }
+};
+var TTSResource = class {
+  constructor(client) {
+    this.client = client;
+  }
+  /**
+   * Generate audio from text with streaming via WebSocket.
+   * Returns complete audio after all chunks are received.
+   */
+  async generate(options) {
+    const chunks = [];
+    let finalStats;
+    await this.stream(options, {
+      onChunk: (chunk) => {
+        chunks.push(base64ToArrayBuffer(chunk.audio));
+      },
+      onFinal: (stats) => {
+        finalStats = stats;
+      }
+    });
+    const totalLength = chunks.reduce((acc, c) => acc + c.byteLength, 0);
+    const combined = new Uint8Array(totalLength);
+    let offset = 0;
+    for (const chunk of chunks) {
+      combined.set(new Uint8Array(chunk), offset);
+      offset += chunk.byteLength;
+    }
+    return {
+      audio: combined.buffer,
+      sampleRate: options.sampleRate || 24e3,
+      samples: finalStats ? finalStats.totalSamples : totalLength / 2,
+      durationMs: finalStats ? finalStats.durationMs : 0,
+      generationMs: finalStats ? finalStats.generationMs : 0,
+      rtf: finalStats ? finalStats.rtf : 0
+    };
+  }
+  /**
+   * Stream audio from text via WebSocket.
+   */
+  stream(options, callbacks) {
+    return new Promise((resolve, reject) => {
+      const wsUrl = this.client.ttsUrl.replace("https://", "wss://").replace("http://", "ws://");
+      const url = `${wsUrl}/ws/tts?api_key=${this.client.apiKey}`;
+      const ws = new WebSocket(url);
+      ws.onopen = () => {
+        callbacks.onOpen?.();
+        ws.send(JSON.stringify({
+          text: options.text,
+          model: options.model || "kugel-one-turbo",
+          voice_id: options.voiceId,
+          cfg_scale: options.cfgScale ?? 2,
+          max_new_tokens: options.maxNewTokens ?? 2048,
+          sample_rate: options.sampleRate ?? 24e3,
+          speaker_prefix: options.speakerPrefix ?? true
+        }));
+      };
+      ws.onmessage = (event) => {
+        try {
+          const data = JSON.parse(event.data);
+          if (data.error) {
+            const error = this.parseError(data.error);
+            callbacks.onError?.(error);
+            ws.close();
+            reject(error);
+            return;
+          }
+          if (data.final) {
+            const stats = {
+              final: true,
+              chunks: data.chunks,
+              totalSamples: data.total_samples,
+              durationMs: data.dur_ms,
+              generationMs: data.gen_ms,
+              ttfaMs: data.ttfa_ms,
+              rtf: data.rtf,
+              error: data.error
+            };
+            callbacks.onFinal?.(stats);
+            ws.close();
+            resolve();
+            return;
+          }
+          if (data.audio) {
+            const chunk = {
+              audio: data.audio,
+              encoding: data.enc || "pcm_s16le",
+              index: data.idx,
+              sampleRate: data.sr,
+              samples: data.samples
+            };
+            callbacks.onChunk?.(chunk);
+          }
+        } catch (e) {
+          console.error("Failed to parse WebSocket message:", e);
+        }
+      };
+      ws.onerror = () => {
+        const error = new KugelAudioError("WebSocket connection error");
+        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"));
+        }
+      };
+    });
+  }
+  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);
+  }
+};
+var KugelAudio = class {
+  constructor(options) {
+    if (!options.apiKey) {
+      throw new Error("API key is required");
+    }
+    this._apiKey = options.apiKey;
+    this._apiUrl = (options.apiUrl || DEFAULT_API_URL).replace(/\/$/, "");
+    this._ttsUrl = (options.ttsUrl || this._apiUrl).replace(/\/$/, "");
+    this._timeout = options.timeout || 6e4;
+    this.models = new ModelsResource(this);
+    this.voices = new VoicesResource(this);
+    this.tts = new TTSResource(this);
+  }
+  /** Get API key */
+  get apiKey() {
+    return this._apiKey;
+  }
+  /** Get TTS URL */
+  get ttsUrl() {
+    return this._ttsUrl;
+  }
+  /**
+   * Make an HTTP request to the API.
+   * @internal
+   */
+  async request(method, path, body) {
+    const url = `${this._apiUrl}${path}`;
+    const headers = {
+      "Content-Type": "application/json",
+      "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: body ? JSON.stringify(body) : void 0,
+        signal: controller.signal
+      });
+      clearTimeout(timeoutId);
+      if (response.status === 401) {
+        throw new AuthenticationError("Invalid API key");
+      }
+      if (response.status === 403) {
+        throw new InsufficientCreditsError("Access denied");
+      }
+      if (response.status === 429) {
+        throw new RateLimitError("Rate limit exceeded");
+      }
+      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);
+      }
+      return await response.json();
+    } catch (error) {
+      clearTimeout(timeoutId);
+      if (error instanceof KugelAudioError) {
+        throw error;
+      }
+      if (error.name === "AbortError") {
+        throw new KugelAudioError("Request timed out");
+      }
+      throw new KugelAudioError(`Request failed: ${error.message}`);
+    }
+  }
+};
+export {
+  AuthenticationError,
+  ConnectionError,
+  InsufficientCreditsError,
+  KugelAudio,
+  KugelAudioError,
+  RateLimitError,
+  ValidationError,
+  base64ToArrayBuffer,
+  createWavBlob,
+  createWavFile,
+  decodePCM16
+};

package/package.json

@@ -0,0 +1,56 @@
+{
+  "name": "kugelaudio",
+  "version": "0.1.1",
+  "description": "Official JavaScript/TypeScript SDK for KugelAudio TTS API",
+  "main": "dist/index.js",
+  "module": "dist/index.mjs",
+  "types": "dist/index.d.ts",
+  "exports": {
+    ".": {
+      "import": "./dist/index.mjs",
+      "require": "./dist/index.js",
+      "types": "./dist/index.d.ts"
+    }
+  },
+  "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 <support@kugelaudio.com>",
+  "license": "MIT",
+  "repository": {
+    "type": "git",
+    "url": "https://github.com/kugelaudio/kugelaudio-js"
+  },
+  "homepage": "https://kugelaudio.com",
+  "bugs": {
+    "url": "https://github.com/kugelaudio/kugelaudio-js/issues"
+  },
+  "devDependencies": {
+    "@types/node": "^20.0.0",
+    "tsup": "^8.0.0",
+    "typescript": "^5.0.0",
+    "vitest": "^1.0.0"
+  },
+  "engines": {
+    "node": ">=18.0.0"
+  }
+}