Types & Errors

import { KugelAudio } from 'kugelaudio';
import {
  KugelAudioError,
  AuthenticationError,
  RateLimitError,
  InsufficientCreditsError,
  ValidationError,
  NotFoundError,
  ConnectionError,
  ServerRestartingError,
} from 'kugelaudio';

try {
  const audio = await client.tts.generate({ text: 'Hello!', voiceId: 1071 });
} catch (error) {
  if (error instanceof AuthenticationError) {
    console.error('Invalid API key');
  } else if (error instanceof RateLimitError) {
    console.error('Rate limit exceeded, please wait');
  } else if (error instanceof InsufficientCreditsError) {
    console.error('Not enough credits, please top up');
  } else if (error instanceof NotFoundError) {
    console.error('Voice, model, or dictionary not found');
  } else if (error instanceof ValidationError) {
    console.error(`Invalid request: ${error.message}`);
  } else if (error instanceof ServerRestartingError) {
    console.error(`Server restarting, retry in ${error.retryAfter}s`);
  } else if (error instanceof ConnectionError) {
    console.error('Failed to connect to server');
  } else if (error instanceof KugelAudioError) {
    console.error(`API error: ${error.message}`);
  }
}

type Region = 'eu' | 'us' | 'global';

interface KugelAudioOptions {
  apiKey: string;                   // Required; an 'eu-' prefix selects the EU endpoint
  isToken?: boolean;                // Treat apiKey as a JWT token
  orgId?: number;                   // Org to bill against (token auth)
  region?: Region;                  // 'eu' selects the direct EU endpoint
  apiUrl?: string;                  // Default: https://api.kugelaudio.com
  ttsUrl?: string;                  // Default: same as apiUrl
  timeout?: number;                 // Default: 60000 (ms)
  keepalivePingInterval?: number | null;  // Default: 20000 (ms); 0/null disables; Node only
}

interface GenerateOptions {
  text: string;              // Required: Text to synthesize
  modelId?: string;          // Default: 'kugel-3'
  voiceId?: number;          // SDK-optional; required for successful synthesis
  cfgScale?: number;         // Guidance scale 1.2-2.5; default: 2.0
  temperature?: number;      // Sampling variance 0.0-1.0; omit for server default
  maxNewTokens?: number;     // Default: 2048
  sampleRate?: number;       // Default: 24000
  outputFormat?: string;     // 'pcm_24000' | 'ulaw_8000' | 'alaw_8000' | ...
  normalize?: boolean;       // Default: true - Enable text normalization
  language?: string;         // ISO 639-1 code for normalization (e.g., 'en', 'de')
  wordTimestamps?: boolean;  // Default: false - Request word-level timestamps
  speed?: number;            // Playback speed 0.8-1.2 (default 1.0); pitch-preserving
  projectId?: number;        // Project ID for dictionary lookup (all auth modes)
  dictionaryIds?: number[];  // With projectId: omit = all active, [] = none,
                             // list = exact IDs (including inactive ones)
}

interface AudioChunk {
  audio: string;       // Base64-encoded bytes in `encoding`
  encoding: 'pcm_s16le' | 'mulaw' | 'alaw'; // G.711 when outputFormat is set
  index: number;       // Chunk index (0-based)
  sampleRate: number;  // Requested sample rate (24000 by default)
  samples: number;     // Number of samples in chunk
}

interface WordTimestamp {
  word: string;      // The word
  startMs: number;   // Start time in milliseconds
  endMs: number;     // End time in milliseconds
  charStart: number; // Character start index in original text
  charEnd: number;   // Character end index in original text
  score: number;     // Compatibility field; currently always 1.0
}

interface AudioResponse {
  audio: ArrayBuffer;              // Complete bytes in the requested output format
  sampleRate: number;              // The sampleRate you passed (24000 by default); set it to match outputFormat
  samples: number;                 // Total samples
  durationMs: number;              // Duration in milliseconds
  generationMs: number;            // Generation time in milliseconds
  rtf: number;                     // Real-time factor
  wordTimestamps: WordTimestamp[];  // Per-word timing (when wordTimestamps: true)
}

interface GenerationStats {
  final: true;
  chunks: number;         // Number of chunks generated
  totalSamples: number;   // Total samples generated
  durationMs: number;     // Audio duration in ms
  generationMs: number;   // Generation time in ms
  rtf: number;           // Real-time factor
  error?: string;         // Error message when supplied by the final frame
  usage?: SessionUsage;  // Per-request usage (audio time + charge); undefined if not reported
}

interface SessionUsage {
  audioSeconds: number;    // Audio generated (the unit we bill on)
  costCents: number | null; // Actual charge in EUR cents; null if undetermined
  currency?: string;       // Currency of costCents ('eur'); set only when costCents is
  characters?: number;     // Input characters; omitted on multi-context per-context usage
  modelId?: string;        // Model that produced the audio
  costAvailable: boolean;  // true when an authoritative charge was returned
}

interface StreamCallbacks {
  onOpen?: () => void;
  onChunk?: (chunk: AudioChunk) => void;
  onWordTimestamps?: (timestamps: WordTimestamp[]) => void;
  onFinal?: (stats: GenerationStats) => void;
  onError?: (error: Error) => void;
  onClose?: () => void;
  // A rolling deploy closed the socket before any audio arrived; the SDK
  // re-issues the request once after error.retryAfter seconds
  onServerRestart?: (error: ServerRestartingError) => void;
}

interface StreamConfig {
  voiceId?: number;           // SDK-optional; required before synthesis
  modelId?: string;           // Default: 'kugel-3'
  cfgScale?: number;          // Guidance scale 1.2-2.5; default: 2.0
  temperature?: number;       // Sampling variance 0.0-1.0; omit for server default
  maxNewTokens?: number;
  sampleRate?: number;
  outputFormat?: string;      // Combined codec + rate token
  flushTimeoutMs?: number;
  maxBufferLength?: number;
  normalize?: boolean;
  language?: string;          // ISO 639-1 code; default: the voice's primary language
  wordTimestamps?: boolean;
  /**
   * Minimum buffer sizes (chars) before each successive chunk is auto-emitted.
   * Smaller = lower TTFA; larger = better prosody context.
   * Default: [5, 80, 150, 250]
   */
  chunkLengthSchedule?: number[];
  /**
   * When true, start generating at the very first clean sentence boundary.
   * Equivalent to ElevenLabs auto_mode=true. Lowest possible TTFA.
   */
  autoMode?: boolean;
  speed?: number;             // Playback speed 0.8-1.2 (default 1.0); pitch-preserving
  projectId?: number;         // Project whose dictionaries apply (see Dictionaries)
  dictionaryIds?: number[];   // Exact selection; [] disables; non-empty requires projectId
}

interface StreamingSessionCallbacks {
  onChunk?: (chunk: AudioChunk) => void;
  onChunkComplete?: (chunkId: number, audioSeconds: number, genMs: number) => void;
  // End of audio for the turn (ElevenLabs isFinal equivalent); fires after
  // the last audio frame, right before onSessionClosed. Not on barge-in.
  onFinal?: (totalAudioSeconds: number, totalTextChunks: number, totalAudioChunks: number) => void;
  onSessionClosed?: (totalAudioSeconds: number, totalTextChunks: number, totalAudioChunks: number) => void;
  onGenerationStarted?: (chunkId: number, text: string) => void;
  onWordTimestamps?: (timestamps: WordTimestamp[]) => void;
  onInterrupted?: () => void;
  onError?: (error: Error) => void;
  // A rolling deploy closed the socket; the SDK reconnects after
  // error.retryAfter seconds and replays the current turn
  onServerRestart?: (error: ServerRestartingError) => void;
}

interface Model {
  id: string;             // e.g. 'kugel-3'
  name: string;           // Human-readable name
  description: string;    // Model description
  parameters: string;     // Parameter-count label (e.g. '7B')
  maxInputLength: number; // Maximum input characters
  sampleRate: number;     // Output sample rate
}

interface VoiceListResponse {
  voices: Voice[];   // Voices on this page
  total: number;     // Total number of matching voices
  limit: number;     // Page size used
  offset: number;    // Offset used
}

type VoiceCategory = 'premade' | 'cloned' | 'designed' | 'conversational' | 'narrative' | 'narrative_story' | 'characters';
type VoiceSex = 'male' | 'female' | 'neutral';
type VoiceAge = 'young' | 'middle_aged' | 'old';
type VoiceQuality = 'low' | 'mid' | 'high';

interface Voice {
  id: number;                    // Voice ID
  name: string;                  // Voice name
  description?: string;          // Description
  category?: VoiceCategory;
  sex?: VoiceSex;
  age?: VoiceAge;
  quality?: string;
  supportedLanguages: string[];  // ['en', 'de', ...]
  sampleText?: string;           // Text used for sample generation
  avatarUrl?: string;            // Avatar image URL
  sampleUrl?: string;            // Sample audio URL
  isPublic: boolean;
  verified: boolean;
}

interface VoiceDetail {
  id: number;
  name: string;
  description: string;
  generativeVoiceDescription: string;
  supportedLanguages: string[];
  category: string;
  age?: string;
  sex?: string;
  quality: string;                 // 'low' | 'mid' | 'high'
  isPublic: boolean;
  verified: boolean;
  pendingVerification: boolean;
  sampleUrl?: string;
  avatarUrl?: string;
  sampleText: string;
}

interface VoiceReference {
  id: number;
  voiceId: number;
  name: string;
  referenceText: string;
  s3Path: string;
  audioUrl?: string;
  isGenerated: boolean;
}

interface CreateVoiceOptions {
  name: string;
  sex: string;
  description?: string;
  category?: string;
  age?: string;
  quality?: string;
  supportedLanguages?: string[];
  isPublic?: boolean;
  sampleText?: string;
  referenceFiles?: Array<File | Blob>;
}

interface UpdateVoiceOptions {
  name?: string;
  description?: string;
  category?: string;
  age?: string;
  sex?: string;
  quality?: string;
  supportedLanguages?: string[];
  isPublic?: boolean;
  sampleText?: string;
}

interface TranscriptionResponse {
  text: string;                            // OpenAI-compatible transcript field
  transcript: string;                      // KugelAudio's transcript field (same text)
  language: string;                        // Language reported by the server
  duration_s: number;                      // Audio duration in seconds
  model: string;                           // Always 'luchs-1'
  model_revision?: string;                 // Immutable checkpoint revision
  word_alternatives: WordAlternatives[];   // Alternative spellings for uncertain words
}

interface WordAlternatives {
  raw_word_index: number;
  word: string;
  alternatives: SpellingAlternative[];
}

interface SpellingAlternative {
  spelling: string;
  probability: number;
}