kugelaudio 0.8.0 → 0.9.0

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "kugelaudio",
-  "version": "0.8.0",
+  "version": "0.9.0",
   "description": "Official JavaScript/TypeScript SDK for KugelAudio TTS API",
   "main": "dist/index.js",
   "module": "dist/index.mjs",
@@ -10,6 +10,11 @@
       "types": "./dist/index.d.ts",
       "import": "./dist/index.mjs",
       "require": "./dist/index.js"
+    },
+    "./livekit": {
+      "types": "./dist/livekit/index.d.ts",
+      "import": "./dist/livekit/index.mjs",
+      "require": "./dist/livekit/index.js"
     }
   },
   "files": [
@@ -19,8 +24,8 @@
     "CHANGELOG.md"
   ],
   "scripts": {
-    "build": "tsup src/index.ts --format cjs,esm --dts",
-    "dev": "tsup src/index.ts --format cjs,esm --dts --watch",
+    "build": "tsup src/index.ts src/livekit/index.ts --format cjs,esm --dts",
+    "dev": "tsup src/index.ts src/livekit/index.ts --format cjs,esm --dts --watch",
     "lint": "eslint src/",
     "test": "vitest run",
     "test:watch": "vitest",
@@ -46,11 +51,26 @@
     "url": "https://github.com/Kugelaudio/KugelAudio/issues"
   },
   "devDependencies": {
+    "@livekit/agents": "^1.4.11",
+    "@livekit/rtc-node": "^0.13.30",
     "@types/node": "^25.3.2",
+    "@types/ws": "^8.18.1",
     "tsup": "^8.0.0",
     "typescript": "^6.0.2",
     "vitest": "^4.0.18"
   },
+  "peerDependencies": {
+    "@livekit/agents": ">=1.0.0",
+    "@livekit/rtc-node": ">=0.13.0"
+  },
+  "peerDependenciesMeta": {
+    "@livekit/agents": {
+      "optional": true
+    },
+    "@livekit/rtc-node": {
+      "optional": true
+    }
+  },
   "engines": {
     "node": ">=18.0.0"
   },

package/src/cfg-scale.test.ts

@@ -0,0 +1,33 @@
+/**
+ * Unit tests for cfg_scale range clamping (KUG-1342).
+ *
+ * The accepted classifier-free guidance band is [1.2, 2.5]; values outside
+ * it are clamped into the band client-side (matching the server).
+ */
+
+import { describe, it, expect } from 'vitest';
+import { clampCfgScale, MIN_CFG_SCALE, MAX_CFG_SCALE } from './utils';
+
+describe('clampCfgScale', () => {
+  it('preserves values inside [1.2, 2.5]', () => {
+    for (const cfg of [MIN_CFG_SCALE, 2.0, MAX_CFG_SCALE]) {
+      expect(clampCfgScale(cfg)).toBe(cfg);
+    }
+  });
+
+  it('passes undefined through (server default applies)', () => {
+    expect(clampCfgScale(undefined)).toBeUndefined();
+  });
+
+  it('clamps values below the floor up to 1.2', () => {
+    for (const cfg of [0, 1.0, 1.19]) {
+      expect(clampCfgScale(cfg)).toBe(MIN_CFG_SCALE);
+    }
+  });
+
+  it('clamps values above the ceiling down to 2.5', () => {
+    for (const cfg of [2.51, 3.0, 5, 10]) {
+      expect(clampCfgScale(cfg)).toBe(MAX_CFG_SCALE);
+    }
+  });
+});

package/src/client.test.ts

@@ -1079,3 +1079,113 @@ describe('MultiContextSession createContext wire format (KUG-1233)', () => {
     expect(frames[1].text).toBe('again');
   });
 });
+
+// ---------------------------------------------------------------------------
+// updateSettings() — mid-connection generation-param changes (KUG-1166)
+// ---------------------------------------------------------------------------
+
+describe('updateSettings (KUG-1166)', () => {
+  let client: KugelAudio;
+
+  beforeEach(() => {
+    client = new KugelAudio({ apiKey: 'test-key-xxx' });
+  });
+
+  const lastSent = () =>
+    JSON.parse(mockWs.send.mock.calls[mockWs.send.mock.calls.length - 1][0] as string);
+
+  it('stream: sends update_settings (snake_case) and resolves with effective settings', async () => {
+    const session = client.tts.streamingSession({ voiceId: 1, cfgScale: 2.0 }, {});
+    session.connect();
+    await new Promise<void>((r) => setTimeout(r, 10));
+
+    const p = session.updateSettings({ cfgScale: 1.5, speed: 1.1 });
+    expect(lastSent().update_settings).toEqual({ cfg_scale: 1.5, speed: 1.1 });
+
+    mockWs.onmessage?.({
+      data: JSON.stringify({ settings_updated: true, settings: { cfg_scale: 1.5, speed: 1.1 } }),
+    });
+    const eff = await p;
+    expect(eff.cfgScale).toBe(1.5);
+    expect(eff.speed).toBe(1.1);
+  });
+
+  it('stream: syncs local config so the next first send carries the new value', async () => {
+    const session = client.tts.streamingSession({ voiceId: 1, cfgScale: 2.0 }, {});
+    session.connect();
+    await new Promise<void>((r) => setTimeout(r, 10));
+
+    const p = session.updateSettings({ cfgScale: 1.5 });
+    mockWs.onmessage?.({
+      data: JSON.stringify({ settings_updated: true, settings: { cfg_scale: 1.5 } }),
+    });
+    await p;
+
+    session.send('Hello.');
+    // First send serializes config — it must carry the updated cfg_scale, not 2.0.
+    expect(lastSent().cfg_scale).toBe(1.5);
+  });
+
+  it('stream: server rejection rejects the promise without changing local defaults', async () => {
+    const session = client.tts.streamingSession({ voiceId: 1, cfgScale: 2.0 }, {});
+    session.connect();
+    await new Promise<void>((r) => setTimeout(r, 10));
+
+    const p = session.updateSettings({ cfgScale: 99 });
+    mockWs.onmessage?.({
+      data: JSON.stringify({
+        error: 'Invalid settings update: cfg_scale: out of range',
+        error_code: 'VALIDATION_ERROR',
+        code: 400,
+      }),
+    });
+    await expect(p).rejects.toThrow(/Invalid settings update/);
+
+    session.send('Hello.');
+    expect(lastSent().cfg_scale).toBe(2.0);
+  });
+
+  it('stream: empty update throws synchronously', async () => {
+    const session = client.tts.streamingSession({ voiceId: 1 }, {});
+    session.connect();
+    await new Promise<void>((r) => setTimeout(r, 10));
+    expect(() => session.updateSettings({})).toThrow(/at least one parameter/);
+  });
+
+  it('multi: session-scoped update acked, no context_id', async () => {
+    const session = client.tts.createMultiContextSession({ defaultVoiceId: 1, cfgScale: 1.0 });
+    await session.connect({});
+
+    const p = session.updateSettings({ cfgScale: 2.5, normalize: false });
+    expect(lastSent().update_settings).toEqual({ cfg_scale: 2.5, normalize: false });
+    expect(lastSent().context_id).toBeUndefined();
+
+    mockWs.onmessage?.({
+      data: JSON.stringify({ settings_updated: true, settings: { cfg_scale: 2.5, normalize: false } }),
+    });
+    const eff = await p;
+    expect(eff.cfgScale).toBe(2.5);
+    expect(eff.normalize).toBe(false);
+  });
+
+  it('multi: server rejection does not change local defaults', async () => {
+    // cfgScale 2.0 is inside the client-side clamp band [1.2, 2.5] so the
+    // re-send below reflects the local default verbatim — a value below 1.2
+    // would be clamped up and mask whether the rejected update poisoned it.
+    const session = client.tts.createMultiContextSession({ defaultVoiceId: 1, cfgScale: 2.0 });
+    await session.connect({});
+
+    const p = session.updateSettings({ cfgScale: 99 });
+    mockWs.onmessage?.({
+      data: JSON.stringify({
+        error: 'Invalid settings update: cfg_scale: out of range',
+        error_code: 'VALIDATION_ERROR',
+        code: 400,
+      }),
+    });
+    await expect(p).rejects.toThrow(/Invalid settings update/);
+
+    session.createContext('narrator');
+    expect(lastSent().cfg_scale).toBe(2.0);
+  });
+});

package/src/client.ts

@@ -16,10 +16,12 @@ import type {
     AudioChunk,
     AudioResponse,
     CreateVoiceOptions,
+    EffectiveSettings,
     GenerateOptions,
     GenerationStats,
     KugelAudioOptions,
     Model,
+    SettingsUpdate,
     StreamCallbacks,
     StreamConfig,
     StreamingSessionCallbacks,
@@ -30,7 +32,7 @@ import type {
     WordTimestamp
 } from './types';
 import { parseSessionUsage } from './types';
-import { base64ToArrayBuffer } from './utils';
+import { base64ToArrayBuffer, clampCfgScale } from './utils';
 import { getWebSocket } from './websocket';
 
 import type { Region } from './types';
@@ -78,6 +80,145 @@ function createWs(url: string): WebSocket {
 /** WebSocket OPEN readyState constant. */
 const WS_OPEN = 1;
 
+/**
+ * camelCase SDK field → snake_case wire field for the generation parameters
+ * changeable mid-connection via `update_settings` (KUG-1166). The key set is
+ * authoritative: anything not here is fixed for the connection's lifetime.
+ */
+const UPDATABLE_SETTINGS: Record<keyof SettingsUpdate, string> = {
+  cfgScale: 'cfg_scale',
+  temperature: 'temperature',
+  speed: 'speed',
+  maxNewTokens: 'max_new_tokens',
+  language: 'language',
+  normalize: 'normalize',
+};
+
+/** Build the snake_case `update_settings` body; throws when empty (KUG-1166). */
+function buildSettingsUpdateBody(settings: SettingsUpdate): Record<string, unknown> {
+  const body: Record<string, unknown> = {};
+  for (const camel of Object.keys(UPDATABLE_SETTINGS) as (keyof SettingsUpdate)[]) {
+    const value = settings[camel];
+    if (value !== undefined) body[UPDATABLE_SETTINGS[camel]] = value;
+  }
+  if (Object.keys(body).length === 0) {
+    throw new KugelAudioError(
+      'updateSettings requires at least one parameter to change ' +
+        `(one of ${Object.keys(UPDATABLE_SETTINGS).join(', ')})`,
+    );
+  }
+  return body;
+}
+
+/** Map the server's snake_case `settings` echo back to camelCase. */
+function parseEffectiveSettings(raw: unknown): EffectiveSettings {
+  const s = (raw && typeof raw === 'object' ? raw : {}) as Record<string, unknown>;
+  return {
+    cfgScale: s.cfg_scale as number | undefined,
+    temperature: s.temperature as number | null | undefined,
+    speed: s.speed as number | undefined,
+    maxNewTokens: s.max_new_tokens as number | undefined,
+    language: s.language as string | null | undefined,
+    normalize: s.normalize as boolean | undefined,
+  };
+}
+
+/** Mirror an accepted settings update onto an SDK config object. */
+function applyAcceptedSettingsUpdate(
+  config: Record<string, unknown>,
+  settings: SettingsUpdate,
+): void {
+  for (const camel of Object.keys(UPDATABLE_SETTINGS) as (keyof SettingsUpdate)[]) {
+    if (settings[camel] !== undefined) {
+      config[camel] = settings[camel];
+    }
+  }
+}
+
+/**
+ * Send an `update_settings` message on an open socket and resolve with the
+ * server's `settings_updated` echo (KUG-1166). Audio frames that arrive while
+ * waiting are passed through to the session's normal handler (not dropped); an
+ * `error` frame rejects, as does a quiet timeout or a socket close.
+ */
+function sendUpdateSettings(
+  ws: WebSocket,
+  body: Record<string, unknown>,
+): Promise<EffectiveSettings> {
+  const QUIET_TIMEOUT_MS = 15_000;
+  return new Promise<EffectiveSettings>((resolve, reject) => {
+    let settled = false;
+    let timer: ReturnType<typeof setTimeout>;
+    const prevMessage = ws.onmessage;
+    const prevClose = ws.onclose;
+
+    const finish = (action: () => void): void => {
+      if (settled) return;
+      settled = true;
+      clearTimeout(timer);
+      ws.onmessage = prevMessage;
+      ws.onclose = prevClose;
+      action();
+    };
+
+    const armQuietTimer = (): void => {
+      clearTimeout(timer);
+      timer = setTimeout(
+        () =>
+          finish(() =>
+            reject(
+              new KugelAudioError(
+                'Timed out waiting for settings_updated acknowledgement',
+              ),
+            ),
+          ),
+        QUIET_TIMEOUT_MS,
+      );
+    };
+
+    armQuietTimer();
+
+    ws.onmessage = (event: MessageEvent) => {
+      armQuietTimer();
+      let data: Record<string, unknown> | null = null;
+      try {
+        const raw = typeof event.data === 'string'
+          ? event.data
+          : event.data instanceof Buffer
+            ? event.data.toString()
+            : String(event.data);
+        data = JSON.parse(raw) as Record<string, unknown>;
+      } catch {
+        /* ignore parse errors */
+      }
+      if (data?.settings_updated) {
+        finish(() => resolve(parseEffectiveSettings(data!.settings)));
+        return;
+      }
+      if (data?.error) {
+        finish(() => reject(new KugelAudioError(String(data!.error))));
+        return;
+      }
+      // Unrelated frame (e.g. stray audio from a draining turn): deliver it
+      // through the session's normal handler rather than dropping it.
+      if (prevMessage) prevMessage.call(ws, event);
+    };
+
+    ws.onclose = (event: CloseEvent) => {
+      if (prevClose) prevClose.call(ws, event);
+      finish(() =>
+        reject(
+          new ConnectionError(
+            'WebSocket closed before settings_updated acknowledgement',
+          ),
+        ),
+      );
+    };
+
+    ws.send(JSON.stringify({ update_settings: body }));
+  });
+}
+
 let _languageWarningLogged = false;
 
 function warnIfNoLanguage(
@@ -152,6 +293,7 @@ class VoicesResource {
         category: v.category,
         sex: v.sex,
         age: v.age,
+        quality: v.quality,
         supportedLanguages: v.supported_languages || [],
         sampleText: v.sample_text,
         avatarUrl: v.avatar_url,
@@ -711,7 +853,7 @@ class TTSResource {
         text: options.text,
         model_id: options.modelId || 'kugel-3',
         voice_id: options.voiceId,
-        cfg_scale: options.cfgScale ?? 2.0,
+        cfg_scale: clampCfgScale(options.cfgScale) ?? 2.0,
         ...(options.temperature !== undefined && { temperature: options.temperature }),
         max_new_tokens: options.maxNewTokens ?? 2048,
         sample_rate: options.sampleRate ?? 24000,
@@ -747,7 +889,7 @@ class TTSResource {
           text: options.text,
           model_id: options.modelId || 'kugel-3',
           voice_id: options.voiceId,
-          cfg_scale: options.cfgScale ?? 2.0,
+          cfg_scale: clampCfgScale(options.cfgScale) ?? 2.0,
           max_new_tokens: options.maxNewTokens ?? 2048,
           sample_rate: options.sampleRate ?? 24000,
           ...(options.outputFormat && { output_format: options.outputFormat }),
@@ -1195,7 +1337,7 @@ class MultiContextSession {
       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.cfgScale !== undefined) msg.cfg_scale = clampCfgScale(this.config.cfgScale);
       if (this.config.temperature !== undefined) msg.temperature = this.config.temperature;
       if (this.config.maxNewTokens) msg.max_new_tokens = this.config.maxNewTokens;
       if (this.config.normalize !== undefined) msg.normalize = this.config.normalize;
@@ -1297,6 +1439,36 @@ class MultiContextSession {
     }));
   }
 
+  /**
+   * Change the session's generation parameters mid-connection (KUG-1166).
+   *
+   * Session-scoped (there is no `contextId`): the update applies to contexts
+   * started **after** it — a context already streaming keeps the settings it
+   * began with, since generation parameters are bound when a context's engine
+   * session opens. With the common one-context-per-turn pattern that means it
+   * takes effect on the next turn. Per-context `cfgScale` / `maxNewTokens`
+   * passed to {@link createContext} still win for that context.
+   *
+   * Resolves with the generation parameters now in effect (the server's echo).
+   *
+   * @throws {KugelAudioError} if no field is provided, the socket is not open,
+   *   or the server rejects the update.
+   */
+  updateSettings(settings: SettingsUpdate): Promise<EffectiveSettings> {
+    if (!this.ws || this.ws.readyState !== WS_OPEN) {
+      throw new KugelAudioError(
+        'MultiContextSession not connected. Call connect() first.',
+      );
+    }
+    const body = buildSettingsUpdateBody(settings);
+    return sendUpdateSettings(this.ws, body).then((effective) => {
+      // Mirror onto local config only after the server accepts the update, so
+      // rejected values do not leak into future context creation.
+      applyAcceptedSettingsUpdate(this.config as Record<string, unknown>, settings);
+      return effective;
+    });
+  }
+
   /**
    * Close the session and all contexts.
    */
@@ -1549,7 +1721,7 @@ class StreamingSession {
     if (!this.configSent) {
       if (this.config.voiceId !== undefined) msg.voice_id = this.config.voiceId;
       if (this.config.modelId !== undefined) msg.model_id = this.config.modelId;
-      if (this.config.cfgScale !== undefined) msg.cfg_scale = this.config.cfgScale;
+      if (this.config.cfgScale !== undefined) msg.cfg_scale = clampCfgScale(this.config.cfgScale);
       if (this.config.temperature !== undefined) msg.temperature = this.config.temperature;
       if (this.config.maxNewTokens !== undefined) msg.max_new_tokens = this.config.maxNewTokens;
       if (this.config.sampleRate !== undefined) msg.sample_rate = this.config.sampleRate;
@@ -1749,6 +1921,42 @@ class StreamingSession {
     this.configSent = false;
   }
 
+  /**
+   * Change generation parameters mid-connection without reconnecting (KUG-1166).
+   *
+   * Sends an `update_settings` message and resolves with the generation
+   * parameters now in effect (the server's echo). Only the six fields of
+   * {@link SettingsUpdate} are updatable; identity / audio-format fields
+   * (`voiceId`, `modelId`, `sampleRate`, `outputFormat`, `dictionaryIds`) are
+   * fixed for the connection — change those with {@link updateConfig} after
+   * {@link endSession} instead.
+   *
+   * The change applies to the **next turn**: a turn already streaming keeps the
+   * settings it started with, so call this between turns.
+   *
+   * @example
+   * ```typescript
+   * const effective = await session.updateSettings({ cfgScale: 1.5, speed: 1.1 });
+   * ```
+   *
+   * @throws {KugelAudioError} if no field is provided, the socket is not open,
+   *   or the server rejects the update (e.g. a value out of range).
+   */
+  updateSettings(settings: SettingsUpdate): Promise<EffectiveSettings> {
+    if (!this.ws || this.ws.readyState !== WS_OPEN) {
+      throw new KugelAudioError(
+        'StreamingSession not connected. Call connect() first.',
+      );
+    }
+    const body = buildSettingsUpdateBody(settings);
+    return sendUpdateSettings(this.ws, body).then((effective) => {
+      // Keep the local config in sync only after the server accepts the
+      // change; rejected updates must not poison later config re-sends.
+      applyAcceptedSettingsUpdate(this.config as Record<string, unknown>, settings);
+      return effective;
+    });
+  }
+
   /**
    * Close the session and the WebSocket connection.
    *

package/src/index.ts

@@ -54,6 +54,7 @@ export type {
     DictionaryEntry,
     DictionaryEntryInput,
     DictionaryEntryListResponse,
+    EffectiveSettings,
     GenerateOptions,
     GenerationStats,
     KugelAudioOptions,
@@ -63,6 +64,7 @@ export type {
     MultiContextCallbacks,
     MultiContextConfig,
     SessionUsage,
+    SettingsUpdate,
     StreamCallbacks,
     StreamConfig,
     StreamingSessionCallbacks,

package/src/livekit/index.ts

@@ -0,0 +1,32 @@
+/**
+ * KugelAudio TTS plugin for the LiveKit Agents (Node.js) framework.
+ *
+ * Import from `kugelaudio/livekit`. Requires `@livekit/agents` and its peer
+ * `@livekit/rtc-node` to be installed (they are optional peer dependencies of
+ * this SDK). This is the TypeScript counterpart to `kugelaudio.livekit` in the
+ * Python SDK.
+ *
+ * @example
+ * ```ts
+ * import { TTS } from 'kugelaudio/livekit';
+ *
+ * const tts = new TTS({ voiceId: 1071, model: 'kugel-3', language: 'en' });
+ * ```
+ *
+ * @packageDocumentation
+ */
+
+export { TTS, ChunkedStream, SynthesizeStream } from './tts';
+export type { TTSOptions } from './tts';
+
+export {
+  DEFAULT_CFG_SCALE,
+  DEFAULT_MAX_NEW_TOKENS,
+  DEFAULT_MODEL,
+  DEFAULT_SAMPLE_RATE,
+  DEFAULT_VOICE_ID,
+  SUPPORTED_LANGUAGES,
+  SUPPORTED_SAMPLE_RATES,
+  validateLanguage,
+} from './models';
+export type { TTSModels } from './models';

package/src/livekit/models.test.ts

@@ -0,0 +1,30 @@
+import { describe, it, expect } from 'vitest';
+import { SUPPORTED_LANGUAGES, validateLanguage } from './models';
+
+describe('validateLanguage', () => {
+  it('returns undefined for null/undefined', () => {
+    expect(validateLanguage(undefined)).toBeUndefined();
+    expect(validateLanguage(null)).toBeUndefined();
+  });
+
+  it('accepts supported ISO 639-1 codes', () => {
+    expect(validateLanguage('de')).toBe('de');
+    expect(validateLanguage('en')).toBe('en');
+    expect(validateLanguage('yue')).toBe('yue');
+  });
+
+  it('rejects BCP 47 locale tags with a helpful message', () => {
+    expect(() => validateLanguage('de-DE')).toThrow(/de-DE/);
+    expect(() => validateLanguage('de-DE')).toThrow(/use 'de' instead/);
+  });
+
+  it('rejects unknown codes', () => {
+    expect(() => validateLanguage('xx')).toThrow();
+  });
+
+  it('has a non-empty language set covering common languages', () => {
+    for (const code of ['de', 'en', 'fr', 'es', 'it', 'zh', 'ja', 'ko', 'ar', 'hi']) {
+      expect(SUPPORTED_LANGUAGES.has(code)).toBe(true);
+    }
+  });
+});

package/src/livekit/models.ts

@@ -0,0 +1,84 @@
+/**
+ * Models, constants, and language validation for the KugelAudio LiveKit
+ * Agents TTS plugin.
+ *
+ * This module has NO dependency on `@livekit/agents`, so it can be imported
+ * and unit-tested without the (heavy, native) LiveKit runtime.
+ */
+
+/**
+ * Available TTS models. Legacy ids (`kugel-2.5`, `kugel-2-turbo`,
+ * `kugel-1-turbo`, `kugel-1`) remain accepted for back-compat — server-side
+ * they all alias to `kugel-3` — but new code should use `'kugel-3'`.
+ */
+export type TTSModels =
+  | 'kugel-3'
+  | 'kugel-2.5'
+  | 'kugel-2-turbo'
+  | 'kugel-1-turbo'
+  | 'kugel-1';
+
+/** Default model (matches the public API default; server-side `is_default=kugel-3`). */
+export const DEFAULT_MODEL: TTSModels = 'kugel-3';
+
+/**
+ * Supported output sample rates. The model generates at 24 kHz natively;
+ * other rates use server-side resampling.
+ */
+export const SUPPORTED_SAMPLE_RATES = [24000, 22050, 16000, 8000] as const;
+
+/** Default output sample rate. */
+export const DEFAULT_SAMPLE_RATE = 24000;
+
+/** Default voice id (`null` means use the server default voice). */
+export const DEFAULT_VOICE_ID: number | null = null;
+
+/** Default classifier-free guidance scale. */
+export const DEFAULT_CFG_SCALE = 2.0;
+
+/** Default maximum number of tokens to generate. */
+export const DEFAULT_MAX_NEW_TOKENS = 2048;
+
+/**
+ * ISO 639-1 language codes accepted by the API for text normalization.
+ * Mirrors `kugelaudio.livekit.tts.SUPPORTED_LANGUAGES` in the Python SDK.
+ */
+export const SUPPORTED_LANGUAGES: ReadonlySet<string> = new Set([
+  // Germanic
+  'de', 'en', 'nl', 'sv', 'da', 'no',
+  // Romance
+  'fr', 'es', 'it', 'pt', 'ro',
+  // Slavic
+  'pl', 'cs', 'uk', 'bg', 'sk', 'sl', 'hr', 'sr',
+  // Uralic
+  'fi', 'hu',
+  // Other European
+  'el', 'tr', 'ru',
+  // CJK + SEA
+  'zh', 'ja', 'ko', 'vi', 'yue', 'th', 'id', 'ms',
+  // Semitic + Indic + Other
+  'ar', 'hi', 'he', 'fa', 'ur', 'bn', 'ta',
+]);
+
+/**
+ * Validate that `language` is an ISO 639-1 code supported by the API.
+ *
+ * @param language - The language code, or `undefined`/`null` to leave unset.
+ * @returns The validated code, or `undefined` when none was supplied.
+ * @throws {Error} If `language` is not a supported ISO 639-1 code. A common
+ *   mistake is passing a BCP 47 locale tag such as `'de-DE'` instead of `'de'`.
+ */
+export function validateLanguage(
+  language: string | null | undefined,
+): string | undefined {
+  if (language === null || language === undefined) return undefined;
+  if (!SUPPORTED_LANGUAGES.has(language)) {
+    const supported = [...SUPPORTED_LANGUAGES].sort().join(', ');
+    throw new Error(
+      `language must be a supported ISO 639-1 code (${supported}), got ` +
+        `'${language}'. Note: BCP 47 tags like 'de-DE' are not accepted — ` +
+        `use 'de' instead.`,
+    );
+  }
+  return language;
+}