kugelaudio 0.2.3 → 0.3.0

package/src/errors.ts

@@ -1,73 +1,321 @@
 /**
  * Custom errors for KugelAudio SDK.
+ *
+ * All SDK errors inherit from {@link KugelAudioError}. Specific subclasses
+ * map to the server's `error_code` field (see the server-side `ErrorCode`
+ * enum at `tts/src/serving/deployments/errors.py`) so callers can
+ * `instanceof AuthenticationError` without matching on message text.
  */
 
+// Keep in lockstep with the server `ErrorCode` enum.
+export const ErrorCodes = {
+  UNAUTHORIZED: 'UNAUTHORIZED',
+  RATE_LIMITED: 'RATE_LIMITED',
+  INSUFFICIENT_CREDITS: 'INSUFFICIENT_CREDITS',
+  MODEL_UNAVAILABLE: 'MODEL_UNAVAILABLE',
+  EMPTY_AUDIO: 'EMPTY_AUDIO',
+  VALIDATION: 'VALIDATION_ERROR',
+  INTERNAL: 'INTERNAL_ERROR',
+  NOT_FOUND: 'NOT_FOUND',
+} as const;
+export type ErrorCode = typeof ErrorCodes[keyof typeof ErrorCodes];
+
+// Server-defined WebSocket close codes.
+export const WsCloseCodes = {
+  UNAUTHORIZED: 4001,
+  INSUFFICIENT_CREDITS: 4003,
+  RATE_LIMITED: 4029,
+  MODEL_UNAVAILABLE: 4500,
+} as const;
+
+const API_KEYS_URL = 'https://app.kugelaudio.com/settings/api-keys';
+const BILLING_URL = 'https://app.kugelaudio.com/billing';
+
+export interface KugelAudioErrorOptions {
+  statusCode?: number;
+  errorCode?: string;
+  requestId?: string;
+  retryAfter?: number;
+  cause?: unknown;
+}
+
 /**
  * Base error class for KugelAudio SDK.
  */
 export class KugelAudioError extends Error {
   public readonly statusCode?: number;
+  public readonly errorCode?: string;
+  public readonly requestId?: string;
+  public readonly retryAfter?: number;
 
-  constructor(message: string, statusCode?: number) {
-    super(message);
+  constructor(message: string, options: KugelAudioErrorOptions = {}) {
+    super(options.requestId ? `${message} (request_id: ${options.requestId})` : message);
     this.name = 'KugelAudioError';
-    this.statusCode = statusCode;
+    this.statusCode = options.statusCode;
+    this.errorCode = options.errorCode;
+    this.requestId = options.requestId;
+    this.retryAfter = options.retryAfter;
     Object.setPrototypeOf(this, KugelAudioError.prototype);
   }
 }
 
 /**
- * Thrown when authentication fails.
+ * API key was missing, malformed, or rejected by the server.
  */
 export class AuthenticationError extends KugelAudioError {
-  constructor(message: string = 'Authentication failed') {
-    super(message, 401);
+  constructor(message?: string, options: KugelAudioErrorOptions = {}) {
+    super(
+      message ?? `KugelAudio rejected the API key. Check it is current at ${API_KEYS_URL}.`,
+      { statusCode: 401, errorCode: ErrorCodes.UNAUTHORIZED, ...options },
+    );
     this.name = 'AuthenticationError';
     Object.setPrototypeOf(this, AuthenticationError.prototype);
   }
 }
 
 /**
- * Thrown when rate limit is exceeded.
+ * Request was rejected by the per-org rate limiter.
  */
 export class RateLimitError extends KugelAudioError {
-  constructor(message: string = 'Rate limit exceeded') {
-    super(message, 429);
+  constructor(message?: string, options: KugelAudioErrorOptions = {}) {
+    const msg =
+      message ??
+      (options.retryAfter
+        ? `KugelAudio rate limit hit; retry after ${options.retryAfter}s.`
+        : 'KugelAudio rate limit hit; retry shortly.');
+    super(msg, { statusCode: 429, errorCode: ErrorCodes.RATE_LIMITED, ...options });
     this.name = 'RateLimitError';
     Object.setPrototypeOf(this, RateLimitError.prototype);
   }
 }
 
 /**
- * Thrown when user has insufficient credits.
+ * Account is out of TTS credits.
  */
 export class InsufficientCreditsError extends KugelAudioError {
-  constructor(message: string = 'Insufficient credits') {
-    super(message, 403);
+  constructor(message?: string, options: KugelAudioErrorOptions = {}) {
+    super(
+      message ?? `Your KugelAudio account is out of credits. Top up at ${BILLING_URL}.`,
+      { statusCode: 402, errorCode: ErrorCodes.INSUFFICIENT_CREDITS, ...options },
+    );
     this.name = 'InsufficientCreditsError';
     Object.setPrototypeOf(this, InsufficientCreditsError.prototype);
   }
 }
 
 /**
- * Thrown when request validation fails.
+ * Request was rejected as invalid (bad params, missing fields, etc.).
  */
 export class ValidationError extends KugelAudioError {
-  constructor(message: string) {
-    super(message, 400);
+  constructor(message: string, options: KugelAudioErrorOptions = {}) {
+    super(message, { statusCode: 400, errorCode: ErrorCodes.VALIDATION, ...options });
     this.name = 'ValidationError';
     Object.setPrototypeOf(this, ValidationError.prototype);
   }
 }
 
 /**
- * Thrown when connection to server fails.
+ * The SDK could not reach KugelAudio (network error, server down,
+ * or model deployment temporarily unavailable).
  */
 export class ConnectionError extends KugelAudioError {
-  constructor(message: string = 'Failed to connect to server') {
-    super(message, 503);
+  constructor(message: string, options: KugelAudioErrorOptions = {}) {
+    super(message, { statusCode: 503, ...options });
     this.name = 'ConnectionError';
     Object.setPrototypeOf(this, ConnectionError.prototype);
   }
 }
 
+// ---------------------------------------------------------------------------
+// Classifiers
+// ---------------------------------------------------------------------------
+
+function build(
+  status: number | undefined,
+  errorCode: string | undefined,
+  message: string,
+  opts: { requestId?: string; retryAfter?: number; cause?: unknown } = {},
+): KugelAudioError {
+  // Only include keys whose value we actually know. Subclass constructors
+  // spread `...options` over their canonical defaults (e.g. statusCode: 401),
+  // so a key with `undefined` would clobber the default.
+  const common: {
+    statusCode?: number;
+    errorCode?: string;
+    requestId?: string;
+    retryAfter?: number;
+    cause?: unknown;
+  } = { ...opts };
+  if (status !== undefined) common.statusCode = status;
+  if (errorCode !== undefined) common.errorCode = errorCode;
+
+  if (errorCode === ErrorCodes.UNAUTHORIZED || status === 401) {
+    return new AuthenticationError(message || undefined, common);
+  }
+  if (errorCode === ErrorCodes.INSUFFICIENT_CREDITS || status === 402) {
+    return new InsufficientCreditsError(message || undefined, common);
+  }
+  if (errorCode === ErrorCodes.RATE_LIMITED || status === 429) {
+    return new RateLimitError(message || undefined, common);
+  }
+  if (errorCode === ErrorCodes.VALIDATION || status === 400) {
+    return new ValidationError(message || 'Request validation failed.', common);
+  }
+  if (errorCode === ErrorCodes.MODEL_UNAVAILABLE || status === 503) {
+    const detail = message || 'service temporarily unavailable';
+    return new ConnectionError(
+      `KugelAudio is temporarily unavailable: ${detail}. Retry shortly.`,
+      common,
+    );
+  }
+  return new KugelAudioError(message || `HTTP ${status}`, common);
+}
+
+interface HttpResponseLike {
+  status: number;
+  headers: { get(name: string): string | null } | Record<string, string | undefined>;
+  text?: () => Promise<string>;
+}
+
+function readHeader(
+  headers: HttpResponseLike['headers'],
+  name: string,
+): string | undefined {
+  if (headers && typeof (headers as Headers).get === 'function') {
+    return (headers as Headers).get(name) ?? undefined;
+  }
+  const rec = headers as Record<string, string | undefined>;
+  return rec[name] ?? rec[name.toLowerCase()] ?? undefined;
+}
+
+/**
+ * Build the appropriate `KugelAudioError` from an HTTP response body that
+ * was already parsed. `bodyText` is the raw text fallback.
+ */
+export function classifyHttpError(
+  status: number,
+  bodyText: string,
+  headers: HttpResponseLike['headers'],
+): KugelAudioError {
+  let errorCode: string | undefined;
+  let message = '';
+  let retryAfter: number | undefined;
+
+  if (bodyText) {
+    try {
+      const body = JSON.parse(bodyText);
+      if (body && typeof body === 'object') {
+        errorCode = typeof body.error_code === 'string' ? body.error_code : undefined;
+        const msg = body.error ?? body.detail;
+        if (Array.isArray(msg)) {
+          message = msg.map((m) => String(m)).join('; ');
+        } else if (typeof msg === 'string') {
+          message = msg;
+        }
+        if (typeof body.retry_after === 'number') {
+          retryAfter = body.retry_after;
+        }
+      }
+    } catch {
+      // Not JSON; fall back to raw body text below.
+    }
+  }
+
+  if (retryAfter === undefined) {
+    const header = readHeader(headers, 'Retry-After') ?? readHeader(headers, 'retry-after');
+    if (header) {
+      const n = Number(header);
+      if (Number.isFinite(n)) retryAfter = n;
+    }
+  }
+
+  const requestId = readHeader(headers, 'x-request-id') ?? readHeader(headers, 'X-Request-Id');
+
+  if (!message) {
+    message = (bodyText || '').trim();
+  }
+
+  return build(status, errorCode, message, { requestId, retryAfter });
+}
+
+/**
+ * Build a `KugelAudioError` from a server-sent WebSocket error frame
+ * (`{error, error_code, retry_after}`).
+ */
+export function classifyWsFrame(data: {
+  error?: string;
+  error_code?: string;
+  retry_after?: number;
+}): KugelAudioError {
+  const errorCode = data.error_code;
+  const message = data.error ?? 'Server reported an error.';
+  const retryAfter = typeof data.retry_after === 'number' ? data.retry_after : undefined;
+  return build(undefined, errorCode, message, { retryAfter });
+}
+
+/**
+ * Build a `KugelAudioError` from a WebSocket close code + reason.
+ */
+export function classifyWsClose(
+  code: number | undefined,
+  reason?: string,
+): KugelAudioError {
+  const reasonTxt = (reason ?? '').trim();
+
+  if (code === WsCloseCodes.UNAUTHORIZED) {
+    let msg = `KugelAudio rejected the API key. Check it is current at ${API_KEYS_URL}.`;
+    if (reasonTxt) msg = `${msg} (${reasonTxt})`;
+    return new AuthenticationError(msg);
+  }
+  if (code === WsCloseCodes.INSUFFICIENT_CREDITS) {
+    return new InsufficientCreditsError();
+  }
+  if (code === WsCloseCodes.RATE_LIMITED) {
+    return new RateLimitError();
+  }
+  if (code === WsCloseCodes.MODEL_UNAVAILABLE) {
+    const suffix = reasonTxt ? ` (${reasonTxt})` : '';
+    return new ConnectionError(
+      `KugelAudio model is temporarily unavailable. Retry shortly.${suffix}`,
+    );
+  }
+
+  const detail = reasonTxt || 'no reason given';
+  const codeStr = code !== undefined ? ` (code ${code})` : '';
+  return new ConnectionError(
+    `KugelAudio WebSocket closed by server: ${detail}${codeStr}.`,
+  );
+}
+
+/**
+ * Extract the HTTP status from a `ws` package handshake-rejection error and
+ * return a typed `KugelAudioError`. Returns `null` if the error doesn't look
+ * like a handshake rejection (e.g. pure network failure).
+ *
+ * The `ws` library surfaces rejected upgrades via:
+ *  - an Error whose `.message` is `"Unexpected server response: <status>"`
+ *  - `error.code === 'EUNEXPECTEDRESPONSE'`, with `error.statusCode` on some versions
+ *
+ * The TTS server rejects WS upgrades with a bare API key using HTTP 403
+ * (not 401), so we treat 403 here as an auth failure — HTTP API callers
+ * keep the generic 403 semantics via {@link classifyHttpError}.
+ */
+export function classifyWsHandshakeError(err: unknown): KugelAudioError | null {
+  if (!err || typeof err !== 'object') return null;
+  const e = err as { message?: unknown; statusCode?: unknown; code?: unknown };
+
+  let status: number | undefined;
+  if (typeof e.statusCode === 'number') {
+    status = e.statusCode;
+  }
+  if (status === undefined && typeof e.message === 'string') {
+    const m = e.message.match(/Unexpected server response:\s*(\d{3})/i);
+    if (m) status = Number(m[1]);
+  }
+  if (status === undefined) return null;
+
+  if (status === 403) {
+    return new AuthenticationError();
+  }
+  return build(status, undefined, typeof e.message === 'string' ? e.message : '');
+}

package/src/index.ts

@@ -39,7 +39,7 @@
  * @packageDocumentation
  */
 
-// Main client
+// Main client and session classes
 export { KugelAudio } from './client';
 
 // Types
@@ -47,18 +47,26 @@ export type {
     AudioChunk,
     AudioResponse,
     ContextVoiceSettings,
+    CreateVoiceOptions,
     GenerateOptions,
     GenerationStats,
     KugelAudioOptions,
     Model,
+    Region,
     MultiContextAudioChunk,
     MultiContextCallbacks,
     MultiContextConfig,
     StreamCallbacks,
     StreamConfig,
+    StreamingSessionCallbacks,
+    UpdateVoiceOptions,
     Voice,
     VoiceAge,
     VoiceCategory,
+    VoiceDetail,
+    VoiceListResponse,
+    VoiceQuality,
+    VoiceReference,
     VoiceSex,
     WordTimestamp
 } from './types';
@@ -67,11 +75,18 @@ export type {
 export {
     AuthenticationError,
     ConnectionError,
+    ErrorCodes,
     InsufficientCreditsError,
     KugelAudioError,
     RateLimitError,
-    ValidationError
+    ValidationError,
+    WsCloseCodes,
+    classifyHttpError,
+    classifyWsClose,
+    classifyWsFrame,
+    classifyWsHandshakeError,
 } from './errors';
+export type { ErrorCode, KugelAudioErrorOptions } from './errors';
 
 // Utilities
 export {