kugelaudio 0.3.0 → 0.4.0

package/CHANGELOG.md

@@ -1,3 +1,13 @@
+## [kugelaudio-v0.4.0](https://github.com/Kugelaudio/KugelAudio/compare/js-sdk-v0.3.0...js-sdk-v0.4.0) (2026-05-14)
+
+### Features
+
+* **web:** bump kugelaudio SDK to ^0.3.0 to enable per-project dictionary ([#640](https://github.com/Kugelaudio/KugelAudio/issues/640)) ([f503372](https://github.com/Kugelaudio/KugelAudio/commit/f5033728b2febb00cea6b021da5b5309c2c9097f))
+
+### Bug Fixes
+
+* **python-sdk,js-sdk,java-sdk:** update regional endpoints ([#660](https://github.com/Kugelaudio/KugelAudio/issues/660)) ([b9a32c0](https://github.com/Kugelaudio/KugelAudio/commit/b9a32c09813c3e9de34a9d0a84ed0e024e1fe158))
+
 # Changelog
 
 All notable changes to the KugelAudio JavaScript/TypeScript SDK will be documented in this file.
@@ -5,6 +15,21 @@ All notable changes to the KugelAudio JavaScript/TypeScript SDK will be document
 The format is based on [Keep a Changelog](https://keepachangelog.com/en/1.0.0/),
 and this project adheres to [Semantic Versioning](https://semver.org/spec/v2.0.0.html).
 
+## [0.3.0](https://github.com/Kugelaudio/KugelAudio/compare/js-sdk-v0.2.3...js-sdk-v0.3.0) (2026-05-10)
+
+### Features
+
+* **temperature, projectId, speed** on `tts.stream` / `tts.generate` / multi-context. Required for per-project custom dictionary replacement on the website. ([#273](https://github.com/Kugelaudio/KugelAudio/pull/273))
+* **error classification:** unify across SDKs with actionable messages ([#315](https://github.com/Kugelaudio/KugelAudio/pull/315))
+* **multi-region routing** for all SDKs ([#227](https://github.com/Kugelaudio/KugelAudio/pull/227))
+
+### Bug Fixes
+
+* **streaming session close:** per-message-quiet timeout in `StreamingSession.close()` ([#528](https://github.com/Kugelaudio/KugelAudio/pull/528))
+* **multi-context:** remove redundant `is_final` signal from protocol ([#279](https://github.com/Kugelaudio/KugelAudio/pull/279))
+* **websocket:** keep alive across streaming sessions ([#253](https://github.com/Kugelaudio/KugelAudio/pull/253))
+* **release pipeline:** fix stale repo URLs blocking semantic-release ([#637](https://github.com/Kugelaudio/KugelAudio/pull/637))
+
 ## [0.1.3] - 2024-12-25
 
 ### Fixed

package/README.md

@@ -59,30 +59,28 @@ const client = new KugelAudio({
 
 ### Region Selection
 
-KugelAudio is available in multiple regions. The default is EU.
+By default, KugelAudio uses the canonical geo-routed API endpoint. You can
+select the direct EU endpoint when you need to pin traffic to Europe.
 
-| Region | Endpoint |
-|--------|----------|
-| `eu` | `api.kugelaudio.com` (default) |
-| `us` | `us-api.kugelaudio.com` |
-| `global` | `global-api.kugelaudio.com` (geo-routed) |
+| Region hint | Endpoint |
+|-------------|----------|
+| default | `api.kugelaudio.com` (geo-routed) |
+| `eu` | `api.eu.kugelaudio.com` |
 
 **Option 1 — API key prefix** (simplest, works with env vars):
 
 ```typescript
-const client = new KugelAudio({ apiKey: 'us-ka_your_api_key' });       // → US
-const client = new KugelAudio({ apiKey: 'global-ka_your_api_key' });   // → Global
-const client = new KugelAudio({ apiKey: 'eu-ka_your_api_key' });       // → EU (explicit)
-const client = new KugelAudio({ apiKey: 'ka_your_api_key' });           // → EU (default)
+const client = new KugelAudio({ apiKey: 'eu-ka_your_api_key' });       // → EU
+const client = new KugelAudio({ apiKey: 'ka_your_api_key' });          // → canonical geo-routed API
 ```
 
 **Option 2 — `region` parameter**:
 
 ```typescript
-const client = new KugelAudio({ apiKey: 'ka_your_api_key', region: 'us' });
+const client = new KugelAudio({ apiKey: 'ka_your_api_key', region: 'eu' });
 ```
 
-The prefix is always stripped before authentication. Priority: `apiUrl` > `region` > key prefix > default (EU).
+The prefix is always stripped before authentication. Priority: `apiUrl` > `region` > key prefix > default.
 
 ### Single URL Architecture
 
@@ -361,9 +359,9 @@ try {
 
 ```typescript
 interface KugelAudioOptions {
-  apiKey: string;           // Required (can be prefixed with 'eu-', 'us-', or 'global-')
-  region?: Region;          // 'eu' | 'us' | 'global' (default: 'eu')
-  apiUrl?: string;          // Default: determined by region
+  apiKey: string;           // Required (can be prefixed with 'eu-' for EU)
+  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)
 }
@@ -571,4 +569,3 @@ The SDK works in modern browsers with WebSocket support. For Node.js, ensure you
 ## License
 
 MIT
-

package/dist/index.d.mts

@@ -379,17 +379,17 @@ interface StreamCallbacks {
     onClose?: () => void;
 }
 /**
- * Deployment region. Controls which API endpoint the SDK connects to.
- * - `'eu'` — `api.kugelaudio.com` (default)
- * - `'us'` — `us-api.kugelaudio.com`
- * - `'global'` — `global-api.kugelaudio.com` (geo-routed)
+ * Deployment region. Set `'eu'` to use the direct EU endpoint:
+ * `api.eu.kugelaudio.com`.
+ *
+ * If omitted, the SDK uses `api.kugelaudio.com`.
  */
 type Region = 'eu' | 'us' | 'global';
 /**
  * KugelAudio client options.
  */
 interface KugelAudioOptions {
-    /** Your KugelAudio API key or JWT token. Can be prefixed with `eu-`, `us-`, or `global-` to select a region (prefix is stripped before auth). */
+    /** Your KugelAudio API key or JWT token. Prefix with `eu-` to select the direct EU endpoint (prefix is stripped before auth). */
     apiKey: string;
     /** Whether apiKey is a master key (for internal/server-side use). Master keys bypass billing. */
     isMasterKey?: boolean;
@@ -397,7 +397,7 @@ interface KugelAudioOptions {
     isToken?: boolean;
     /** Organisation ID to bill usage against (required for token auth to enable usage recording). */
     orgId?: number;
-    /** Deployment region. Takes precedence over API-key prefix but not over `apiUrl`. */
+    /** Deployment region. Set `eu` to select the direct EU endpoint. Takes precedence over API-key prefix but not over `apiUrl`. */
     region?: Region;
     /** API base URL (default: https://api.kugelaudio.com) */
     apiUrl?: string;

package/dist/index.d.ts

@@ -379,17 +379,17 @@ interface StreamCallbacks {
     onClose?: () => void;
 }
 /**
- * Deployment region. Controls which API endpoint the SDK connects to.
- * - `'eu'` — `api.kugelaudio.com` (default)
- * - `'us'` — `us-api.kugelaudio.com`
- * - `'global'` — `global-api.kugelaudio.com` (geo-routed)
+ * Deployment region. Set `'eu'` to use the direct EU endpoint:
+ * `api.eu.kugelaudio.com`.
+ *
+ * If omitted, the SDK uses `api.kugelaudio.com`.
  */
 type Region = 'eu' | 'us' | 'global';
 /**
  * KugelAudio client options.
  */
 interface KugelAudioOptions {
-    /** Your KugelAudio API key or JWT token. Can be prefixed with `eu-`, `us-`, or `global-` to select a region (prefix is stripped before auth). */
+    /** Your KugelAudio API key or JWT token. Prefix with `eu-` to select the direct EU endpoint (prefix is stripped before auth). */
     apiKey: string;
     /** Whether apiKey is a master key (for internal/server-side use). Master keys bypass billing. */
     isMasterKey?: boolean;
@@ -397,7 +397,7 @@ interface KugelAudioOptions {
     isToken?: boolean;
     /** Organisation ID to bill usage against (required for token auth to enable usage recording). */
     orgId?: number;
-    /** Deployment region. Takes precedence over API-key prefix but not over `apiUrl`. */
+    /** Deployment region. Set `eu` to select the direct EU endpoint. Takes precedence over API-key prefix but not over `apiUrl`. */
     region?: Region;
     /** API base URL (default: https://api.kugelaudio.com) */
     apiUrl?: string;

package/dist/index.js

@@ -312,11 +312,9 @@ function getWebSocket() {
 }
 
 // src/client.ts
-var REGION_URLS = {
-  eu: "https://api.kugelaudio.com",
-  us: "https://us-api.kugelaudio.com",
-  global: "https://global-api.kugelaudio.com"
-};
+var DEFAULT_API_URL = "https://api.kugelaudio.com";
+var EU_API_URL = "https://api.eu.kugelaudio.com";
+var SUPPORTED_REGIONS = ["eu", "us", "global"];
 var REGION_PREFIXES = ["eu-", "us-", "global-"];
 function parseApiKey(apiKey) {
   for (const prefix of REGION_PREFIXES) {
@@ -1539,13 +1537,16 @@ var KugelAudio = class _KugelAudio {
     if (options.apiUrl) {
       this._apiUrl = options.apiUrl.replace(/\/$/, "");
     } else {
-      const effectiveRegion = options.region || detectedRegion || "eu";
-      if (!(effectiveRegion in REGION_URLS)) {
+      const effectiveRegion = options.region || detectedRegion;
+      if (!effectiveRegion) {
+        this._apiUrl = DEFAULT_API_URL;
+      } else if (!SUPPORTED_REGIONS.includes(effectiveRegion)) {
         throw new ValidationError(
-          `Invalid region '${effectiveRegion}'. Must be one of: ${Object.keys(REGION_URLS).join(", ")}.`
+          `Invalid region '${effectiveRegion}'. Must be one of: ${SUPPORTED_REGIONS.join(", ")}.`
         );
+      } else {
+        this._apiUrl = effectiveRegion === "eu" ? EU_API_URL : DEFAULT_API_URL;
       }
-      this._apiUrl = REGION_URLS[effectiveRegion];
     }
     this._ttsUrl = (options.ttsUrl || this._apiUrl).replace(/\/$/, "");
     this._timeout = options.timeout || 6e4;

package/dist/index.mjs

@@ -277,11 +277,9 @@ function getWebSocket() {
 }
 
 // src/client.ts
-var REGION_URLS = {
-  eu: "https://api.kugelaudio.com",
-  us: "https://us-api.kugelaudio.com",
-  global: "https://global-api.kugelaudio.com"
-};
+var DEFAULT_API_URL = "https://api.kugelaudio.com";
+var EU_API_URL = "https://api.eu.kugelaudio.com";
+var SUPPORTED_REGIONS = ["eu", "us", "global"];
 var REGION_PREFIXES = ["eu-", "us-", "global-"];
 function parseApiKey(apiKey) {
   for (const prefix of REGION_PREFIXES) {
@@ -1504,13 +1502,16 @@ var KugelAudio = class _KugelAudio {
     if (options.apiUrl) {
       this._apiUrl = options.apiUrl.replace(/\/$/, "");
     } else {
-      const effectiveRegion = options.region || detectedRegion || "eu";
-      if (!(effectiveRegion in REGION_URLS)) {
+      const effectiveRegion = options.region || detectedRegion;
+      if (!effectiveRegion) {
+        this._apiUrl = DEFAULT_API_URL;
+      } else if (!SUPPORTED_REGIONS.includes(effectiveRegion)) {
         throw new ValidationError(
-          `Invalid region '${effectiveRegion}'. Must be one of: ${Object.keys(REGION_URLS).join(", ")}.`
+          `Invalid region '${effectiveRegion}'. Must be one of: ${SUPPORTED_REGIONS.join(", ")}.`
         );
+      } else {
+        this._apiUrl = effectiveRegion === "eu" ? EU_API_URL : DEFAULT_API_URL;
       }
-      this._apiUrl = REGION_URLS[effectiveRegion];
     }
     this._ttsUrl = (options.ttsUrl || this._apiUrl).replace(/\/$/, "");
     this._timeout = options.timeout || 6e4;

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "kugelaudio",
-  "version": "0.3.0",
+  "version": "0.4.0",
   "description": "Official JavaScript/TypeScript SDK for KugelAudio TTS API",
   "main": "dist/index.js",
   "module": "dist/index.mjs",
@@ -58,4 +58,4 @@
     "tsx": "^4.21.0",
     "ws": "^8.18.0"
   }
-}
+}

package/src/client.test.ts

@@ -180,42 +180,42 @@ describe('TTSResource.toReadable()', () => {
 // ---------------------------------------------------------------------------
 
 describe('KugelAudio multi-region', () => {
-  it('defaults to EU when no region or prefix is given', () => {
+  it('uses canonical API when no region or prefix is given', () => {
     const client = new KugelAudio({ apiKey: 'ka_test123' });
     expect((client as any)._apiUrl).toBe('https://api.kugelaudio.com');
   });
 
-  it('selects US endpoint with explicit region', () => {
+  it('selects canonical endpoint with explicit region', () => {
     const client = new KugelAudio({ apiKey: 'ka_test123', region: 'us' });
-    expect((client as any)._apiUrl).toBe('https://us-api.kugelaudio.com');
+    expect((client as any)._apiUrl).toBe('https://api.kugelaudio.com');
   });
 
   it('selects global endpoint with explicit region', () => {
     const client = new KugelAudio({ apiKey: 'ka_test123', region: 'global' });
-    expect((client as any)._apiUrl).toBe('https://global-api.kugelaudio.com');
+    expect((client as any)._apiUrl).toBe('https://api.kugelaudio.com');
   });
 
-  it('detects US region from key prefix and strips it', () => {
+  it('detects canonical route from key prefix and strips it', () => {
     const client = new KugelAudio({ apiKey: 'us-ka_test123' });
-    expect((client as any)._apiUrl).toBe('https://us-api.kugelaudio.com');
+    expect((client as any)._apiUrl).toBe('https://api.kugelaudio.com');
     expect((client as any)._apiKey).toBe('ka_test123');
   });
 
   it('detects global region from key prefix and strips it', () => {
     const client = new KugelAudio({ apiKey: 'global-ka_test123' });
-    expect((client as any)._apiUrl).toBe('https://global-api.kugelaudio.com');
+    expect((client as any)._apiUrl).toBe('https://api.kugelaudio.com');
     expect((client as any)._apiKey).toBe('ka_test123');
   });
 
   it('detects EU region from key prefix and strips it', () => {
     const client = new KugelAudio({ apiKey: 'eu-ka_test123' });
-    expect((client as any)._apiUrl).toBe('https://api.kugelaudio.com');
+    expect((client as any)._apiUrl).toBe('https://api.eu.kugelaudio.com');
     expect((client as any)._apiKey).toBe('ka_test123');
   });
 
   it('explicit region overrides key prefix', () => {
     const client = new KugelAudio({ apiKey: 'us-ka_test123', region: 'global' });
-    expect((client as any)._apiUrl).toBe('https://global-api.kugelaudio.com');
+    expect((client as any)._apiUrl).toBe('https://api.kugelaudio.com');
     expect((client as any)._apiKey).toBe('ka_test123');
   });
 
@@ -237,7 +237,7 @@ describe('KugelAudio multi-region', () => {
 
   it('ttsUrl defaults to the resolved region URL', () => {
     const client = new KugelAudio({ apiKey: 'us-ka_test123' });
-    expect((client as any)._ttsUrl).toBe('https://us-api.kugelaudio.com');
+    expect((client as any)._ttsUrl).toBe('https://api.kugelaudio.com');
   });
 
   it('unprefixed key is not modified', () => {

package/src/client.ts

@@ -33,11 +33,9 @@ import { getWebSocket } from './websocket';
 
 import type { Region } from './types';
 
-const REGION_URLS: Record<Region, string> = {
-  eu: 'https://api.kugelaudio.com',
-  us: 'https://us-api.kugelaudio.com',
-  global: 'https://global-api.kugelaudio.com',
-};
+const DEFAULT_API_URL = 'https://api.kugelaudio.com';
+const EU_API_URL = 'https://api.eu.kugelaudio.com';
+const SUPPORTED_REGIONS = ['eu', 'us', 'global'] as const;
 
 const REGION_PREFIXES = ['eu-', 'us-', 'global-'] as const;
 
@@ -1637,13 +1635,16 @@ export class KugelAudio {
     if (options.apiUrl) {
       this._apiUrl = options.apiUrl.replace(/\/$/, '');
     } else {
-      const effectiveRegion = options.region || detectedRegion || 'eu';
-      if (!(effectiveRegion in REGION_URLS)) {
+      const effectiveRegion = options.region || detectedRegion;
+      if (!effectiveRegion) {
+        this._apiUrl = DEFAULT_API_URL;
+      } else if (!SUPPORTED_REGIONS.includes(effectiveRegion as Region)) {
         throw new ValidationError(
-          `Invalid region '${effectiveRegion}'. Must be one of: ${Object.keys(REGION_URLS).join(', ')}.`,
+          `Invalid region '${effectiveRegion}'. Must be one of: ${SUPPORTED_REGIONS.join(', ')}.`,
         );
+      } else {
+        this._apiUrl = effectiveRegion === 'eu' ? EU_API_URL : DEFAULT_API_URL;
       }
-      this._apiUrl = REGION_URLS[effectiveRegion as Region];
     }
 
     // If ttsUrl not specified, use apiUrl (backend proxies to TTS server)
@@ -1843,4 +1844,3 @@ export class KugelAudio {
     }
   }
 }
-

package/src/types.ts

@@ -399,10 +399,10 @@ export interface StreamCallbacks {
 }
 
 /**
- * Deployment region. Controls which API endpoint the SDK connects to.
- * - `'eu'` — `api.kugelaudio.com` (default)
- * - `'us'` — `us-api.kugelaudio.com`
- * - `'global'` — `global-api.kugelaudio.com` (geo-routed)
+ * Deployment region. Set `'eu'` to use the direct EU endpoint:
+ * `api.eu.kugelaudio.com`.
+ *
+ * If omitted, the SDK uses `api.kugelaudio.com`.
  */
 export type Region = 'eu' | 'us' | 'global';
 
@@ -410,7 +410,7 @@ export type Region = 'eu' | 'us' | 'global';
  * KugelAudio client options.
  */
 export interface KugelAudioOptions {
-  /** Your KugelAudio API key or JWT token. Can be prefixed with `eu-`, `us-`, or `global-` to select a region (prefix is stripped before auth). */
+  /** Your KugelAudio API key or JWT token. Prefix with `eu-` to select the direct EU endpoint (prefix is stripped before auth). */
   apiKey: string;
   /** Whether apiKey is a master key (for internal/server-side use). Master keys bypass billing. */
   isMasterKey?: boolean;
@@ -418,7 +418,7 @@ export interface KugelAudioOptions {
   isToken?: boolean;
   /** Organisation ID to bill usage against (required for token auth to enable usage recording). */
   orgId?: number;
-  /** Deployment region. Takes precedence over API-key prefix but not over `apiUrl`. */
+  /** Deployment region. Set `eu` to select the direct EU endpoint. Takes precedence over API-key prefix but not over `apiUrl`. */
   region?: Region;
   /** API base URL (default: https://api.kugelaudio.com) */
   apiUrl?: string;
@@ -515,4 +515,3 @@ export interface MultiContextCallbacks {
   /** Called on error */
   onError?: (error: Error, contextId?: string) => void;
 }
-