anva-sdk 0.2.0 → 0.3.0

package/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 Penguin Robotics
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

package/README.md

@@ -1,26 +1,36 @@
-# anva — JavaScript / TypeScript SDK
+# anva-sdk — JavaScript / TypeScript
 
-Official JS/TS SDK for [Anva](https://anva.ai) — live AI avatars.
-ESM, zero dependencies, typed. Node 18+ and modern browsers (keep your API
-key server-side; hand only the `embed_url` to clients).
-
-```bash
-npm install anva-sdk
-```
+Install with `npm install anva-sdk@0.3.0`. REST uses Node 18+'s fetch. Realtime needs
+Node 22+'s WebSocket or an injected compatible constructor.
 
 ```js
-import { Anva } from "anva-sdk";
-
+import { Anva, AnvaError } from "anva-sdk";
 const client = new Anva(process.env.ANVA_KEY);
-
-const session = await client.createSession({ characterId: "char_..." });
-console.log(session.embed_url);
-
-await client.sendMessage(session.session_id, "Welcome!");
-
-for await (const event of client.events(session.session_id)) {
-  console.log(event);
+const capabilities = await client.capabilities();
+const session = await client.createSession({
+  presetId:"YOUR_PRESET_ID", serviceMode:"byo_llm"
+});
+// Attach session.embed_url in your browser.
+const stream = await client.connect(session.session_id);
+try {
+  for await (const event of stream) {
+    if (event.type === "turn.request") {
+      // Replace this immediate sample reply with your cancellable LLM worker.
+      await stream.turnDelta(event.payload.turn_id, "Hello from your application.");
+      await stream.turnDone(event.payload.turn_id);
+    }
+  }
+} finally {
+  stream.close();
+  await client.endSession(session.session_id);
 }
 ```
 
-Errors throw `AnvaError` with `.status` and `.code`. MIT © Penguin Robotics
+Inject WebSocket on older Node: `client.connect(id, {WebSocketImpl})`. Keep keys
+and sockets server-side. `AnvaError` exposes `status`, `code`, and `details`;
+command errors arrive as structured events. Never log authenticated event URLs.
+
+All five canonical modes, capability/billing discovery, REST interrupt,
+presentation and PCM methods are typed in `index.d.ts`. Read the repository
+README for mode availability and flow-control requirements. Preset updates use
+the REST API's snake_case patch fields.

package/index.d.ts

@@ -1,81 +1,118 @@
-/** Official JavaScript/TypeScript SDK for Anva (https://anva.ai). */
-
-export interface AnvaOptions {
-  /** Override for self-hosted / testing setups. Default: https://anva.ai */
-  baseUrl?: string;
+/** Official Anva SDK. All API keys and authenticated realtime sockets belong on your server. */
+export type ServiceMode = 'avatar_only' | 'byo_llm' | 'anva_light' | 'anva_expressive' | 'elevenagents_max';
+export interface AnvaOptions { baseUrl?: string; }
+export interface PerformanceOptions {
+  conversation_provider?: string;
+  performance_mode?: string;
+  elevenlabs_agent_id?: string;
+  dynamic_expressions?: boolean;
+  [key: string]: unknown;
 }
-
 export interface CreateSessionParams {
-  characterId: string;
-  /** Omit for the built-in conversation engine, or "external" to drive the LLM yourself. */
-  llmMode?: "external";
+  presetId?: string;
+  avatarId?: string;
+  systemPrompt?: string;
+  voiceId?: string;
+  languageCode?: string;
+  serviceMode?: ServiceMode;
+  /** Deprecated compatibility alias. Conflicts with serviceMode are rejected by the server. */
+  llmMode?: string;
+  performanceOptions?: PerformanceOptions;
+  conversationProvider?: string;
+  performanceMode?: string;
+  elevenlabsAgentId?: string;
+  dynamicExpressions?: boolean;
   webhookUrl?: string;
   webhookSecret?: string;
 }
-
+export interface ModeCapability { id: ServiceMode; name: string; available: boolean; reason?: string; input?: string[]; [key: string]: unknown; }
+export interface Capabilities { api_version: string; modes: ModeCapability[]; audio_input?: Record<string, unknown>; [key: string]: unknown; }
+export interface SessionBilling { unit: string; tokens_per_minute?: number; credits_per_minute?: number; rate_version: string; basis: string; [key: string]: unknown; }
 export interface Session {
   session_id: string;
   session_token: string;
-  character_id: string;
+  instance_id: string;
+  preset_id?: string;
+  avatar_id?: string;
+  service_mode?: ServiceMode;
   llm_mode?: string;
+  billing?: SessionBilling;
   expires_at: string;
-  /** Ready to drop into an <iframe allow="camera; microphone; autoplay">. */
   embed_url: string;
   events_ws_url: string;
   [key: string]: unknown;
 }
-
-export interface Character {
-  id: string;
-  name: string;
-  visual_character_id: string;
-  system_prompt: string;
-  voice_id: string;
-  language_code?: string;
-  disabled: boolean;
-  active: boolean;
-  [key: string]: unknown;
-}
-
-export interface SessionEvent {
-  type: string;
+export interface Preset {
+  id: string; name: string; avatar_id: string;
+  /** Deprecated alias. */ visual_character_id?: string;
+  system_prompt: string; voice_id: string; language_code?: string;
+  disabled: boolean; active: boolean;
   [key: string]: unknown;
 }
-
-export interface EventsOptions {
-  /** A WebSocket-compatible constructor (e.g. `ws` in older Node versions). */
-  WebSocketImpl?: new (url: string) => WebSocket;
+export interface Instance { id: string; [key: string]: unknown; }
+export interface SessionEvent { type: string; payload?: Record<string, unknown>; [key: string]: unknown; }
+export interface PresentationContext {
+  version: 1; demo: string; revision: number; page: string; highlight: string;
+  brief?: string; opening?: string;
+  pages: Array<{ id: string; title: string; items: Array<{id: string; text: string}> }>;
 }
-
+export interface PresentationStart { version: 1; demo: string; revision: number; }
+export interface EventsOptions { WebSocketImpl?: new (url: string) => WebSocket; }
+export type PCMBytes = Uint8Array | ArrayBuffer;
 export declare class AnvaError extends Error {
-  status: number;
-  code: string;
+  constructor(status: number, code: string, message: string, details?: Record<string, unknown>);
+  status: number; code: string; details: Record<string, unknown>;
+}
+/** One active event reader per connection. Breaking iteration closes the socket. */
+export declare class RealtimeSession implements AsyncIterable<SessionEvent> {
+  constructor(socket: WebSocket);
+  ready: Promise<RealtimeSession>;
+  closed: boolean;
+  send(type: string, payload?: Record<string, unknown>): Promise<void>;
+  message(text: string): Promise<void>;
+  interrupt(): Promise<void>;
+  updateContext(context: PresentationContext): Promise<void>;
+  startPresentation(start: PresentationStart): Promise<void>;
+  turnDelta(turnId: string, text: string): Promise<void>;
+  turnDone(turnId: string): Promise<void>;
+  turnCancel(turnId: string, reason?: string): Promise<void>;
+  startSpeech(turnId: string, options?: {text?: string}): Promise<void>;
+  appendSpeech(turnId: string, seq: number, startSample: number, pcm: PCMBytes): Promise<void>;
+  finishSpeech(turnId: string, totalSamples: number): Promise<void>;
+  cancelSpeech(turnId: string): Promise<void>;
+  close(): void;
+  [Symbol.asyncIterator](): AsyncGenerator<SessionEvent, void, void>;
 }
-
 export declare class Anva {
   constructor(apiKey: string, opts?: AnvaOptions);
-  apiKey: string;
-  baseUrl: string;
-
+  apiKey: string; baseUrl: string;
   createSession(params: CreateSessionParams): Promise<Session>;
   getSession(sessionId: string): Promise<Record<string, unknown>>;
   endSession(sessionId: string): Promise<Record<string, unknown>>;
-  sendMessage(sessionId: string, text: string): Promise<{ status: string }>;
-  interrupt(sessionId: string): Promise<{ status: string }>;
-  triggerAction(sessionId: string, name: string): Promise<{ status: string }>;
+  sendMessage(sessionId: string, text: string): Promise<{status: string}>;
+  interrupt(sessionId: string): Promise<{status: string}>;
+  triggerAction(sessionId: string, name: string): Promise<{status: string}>;
   eventsUrl(sessionId: string): string;
-  events(sessionId: string, opts?: EventsOptions): AsyncGenerator<SessionEvent, void, void>;
-
-  listCharacters(): Promise<{ characters: Character[] }>;
-  createCharacter(params: {
-    name: string;
-    visualCharacterId?: string;
-    systemPrompt?: string;
-    voiceId?: string;
-    languageCode?: string;
-  }): Promise<Character>;
-  getCharacter(characterId: string): Promise<Character>;
-  deleteCharacter(characterId: string): Promise<{ id: string; status: string }>;
+  connect(sessionId: string, options?: EventsOptions): Promise<RealtimeSession>;
+  events(sessionId: string, options?: EventsOptions): AsyncGenerator<SessionEvent, void, void>;
+  capabilities(): Promise<Capabilities>;
+  billing(): Promise<Record<string, unknown>>;
+  listAvatars(): Promise<Record<string, unknown>>;
+  listVoices(): Promise<Record<string, unknown>>;
+  listLanguages(): Promise<Record<string, unknown>>;
+  updateContext(sessionId: string, context: PresentationContext): Promise<Record<string, unknown>>;
+  startPresentation(sessionId: string, start: PresentationStart): Promise<Record<string, unknown>>;
+  speech(sessionId: string, type: string, payload: Record<string, unknown>): Promise<Record<string, unknown>>;
+  startSpeech(sessionId: string, turnId: string, options?: {text?: string}): Promise<Record<string, unknown>>;
+  appendSpeech(sessionId: string, turnId: string, seq: number, startSample: number, pcm: PCMBytes): Promise<Record<string, unknown>>;
+  finishSpeech(sessionId: string, turnId: string, totalSamples: number): Promise<Record<string, unknown>>;
+  cancelSpeech(sessionId: string, turnId: string): Promise<Record<string, unknown>>;
+  listPresets(): Promise<{presets: Preset[]}>;
+  createPreset(params: {name: string; avatarId?: string; visualCharacterId?: string; systemPrompt?: string; voiceId?: string; languageCode?: string}): Promise<Preset>;
+  /** Patch uses the REST API's snake_case field names. */
+  updatePreset(presetId: string, patch: Record<string, unknown>): Promise<Preset>;
+  getPreset(presetId: string): Promise<Preset>;
+  deletePreset(presetId: string): Promise<{id: string; status: string}>;
+  listInstances(): Promise<{instances: Instance[]}>;
 }
-
 export default Anva;

package/index.js

@@ -1,24 +1,28 @@
 /**
  * Official JavaScript/TypeScript SDK for Anva (https://anva.ai).
  *
- *   import { Anva } from "anva";
+ *   import { Anva } from "anva-sdk";
  *   const client = new Anva(process.env.ANVA_KEY);
  *   const session = await client.createSession({ presetId: "..." });
  *   // put session.embed_url in an <iframe allow="camera; microphone; autoplay">
  *
- * Works in Node 18+ (global fetch/WebSocket) and modern browsers — but keep
+ * Works in Node 18+ (supply a WebSocket implementation before Node 22) and modern browsers — but keep
  * your API key server-side; mint sessions on your backend and hand the
  * embed_url to the client.
  */
 
+import { RealtimeSession, speechStart, speechAppend } from "./realtime.js";
+export { RealtimeSession } from "./realtime.js";
+
 const DEFAULT_BASE_URL = "https://anva.ai";
 
 export class AnvaError extends Error {
-  constructor(status, code, message) {
+  constructor(status, code, message, details = {}) {
     super(`${code}: ${message} (HTTP ${status})`);
     this.name = "AnvaError";
     this.status = status;
     this.code = code;
+    this.details = details;
   }
 }
 
@@ -48,9 +52,9 @@ export class Anva {
    *   webhookUrl?: string, webhookSecret?: string}} params
    */
   createSession(params = {}) {
-    const { presetId, avatarId, systemPrompt, voiceId, languageCode, llmMode, webhookUrl, webhookSecret } = params;
-    if (!presetId && !avatarId) {
-      throw new Error("createSession requires either presetId (embed) or avatarId (advanced persona)");
+    const { presetId, avatarId, systemPrompt, voiceId, languageCode, llmMode, serviceMode, performanceOptions, conversationProvider, performanceMode, elevenlabsAgentId, dynamicExpressions, webhookUrl, webhookSecret } = params;
+    if ((!presetId && !avatarId) || (presetId && avatarId)) {
+      throw new Error("createSession requires exactly one of presetId or avatarId");
     }
     const body = {};
     if (presetId) body.preset_id = presetId;
@@ -58,7 +62,13 @@ export class Anva {
     if (systemPrompt) body.system_prompt = systemPrompt;
     if (voiceId) body.voice_id = voiceId;
     if (languageCode) body.language_code = languageCode;
-    if (llmMode) body.llm_mode = llmMode;
+    if (llmMode !== undefined) body.llm_mode = llmMode;
+    if (serviceMode !== undefined) body.service_mode = serviceMode;
+    if (performanceOptions !== undefined) body.performance_options = performanceOptions;
+    if (conversationProvider !== undefined) body.conversation_provider = conversationProvider;
+    if (performanceMode !== undefined) body.performance_mode = performanceMode;
+    if (elevenlabsAgentId !== undefined) body.elevenlabs_agent_id = elevenlabsAgentId;
+    if (dynamicExpressions !== undefined) body.dynamic_expressions = dynamicExpressions;
     if (webhookUrl) body.webhook_url = webhookUrl;
     if (webhookSecret) body.webhook_secret = webhookSecret;
     return this._request("POST", "/api/v2/sessions", body);
@@ -72,7 +82,8 @@ export class Anva {
     return this._request("DELETE", `/api/v2/sessions/${enc(sessionId)}`);
   }
 
-  /** Have the avatar speak `text` to the user. */
+  /** Send `text` as a user message; the avatar hears it and replies (it does
+   * NOT speak `text` verbatim). For external replies, use serviceMode:"byo_llm" and turnDelta/turnDone on a realtime connection. */
   sendMessage(sessionId, text) {
     return this._request("POST", `/api/v2/sessions/${enc(sessionId)}/messages`, { text });
   }
@@ -92,54 +103,29 @@ export class Anva {
     return `${ws}/api/v2/sessions/${enc(sessionId)}/events?api_key=${encodeURIComponent(this.apiKey)}`;
   }
 
-  /**
-   * Async-iterate live events (transcripts, state changes):
-   *
-   *   for await (const event of client.events(sessionId)) { ... }
-   */
-  async *events(sessionId, { WebSocketImpl } = {}) {
+  /** Open a single socket for both events and turn/presentation/speech commands. */
+  async connect(sessionId, { WebSocketImpl } = {}) {
     const WS = WebSocketImpl || globalThis.WebSocket;
-    if (!WS) throw new Error("no WebSocket implementation available — pass { WebSocketImpl }");
-    const ws = new WS(this.eventsUrl(sessionId));
-    const queue = [];
-    let notify = null;
-    let done = false;
-    let failure = null;
-    ws.onmessage = (m) => {
-      try {
-        queue.push(JSON.parse(m.data));
-      } catch {
-        /* non-JSON frame */
-      }
-      if (notify) notify();
-    };
-    ws.onclose = () => {
-      done = true;
-      if (notify) notify();
-    };
-    ws.onerror = () => {
-      failure = new Error("events socket error");
-      done = true;
-      if (notify) notify();
-    };
-    try {
-      while (!done || queue.length) {
-        if (!queue.length) {
-          await new Promise((resolve) => (notify = resolve));
-          notify = null;
-          continue;
-        }
-        yield queue.shift();
-      }
-      if (failure) throw failure;
-    } finally {
-      try {
-        ws.close();
-      } catch {
-        /* already closed */
-      }
-    }
-  }
+    if (!WS) throw new Error('No WebSocket implementation; pass { WebSocketImpl }');
+    const stream = new RealtimeSession(new WS(this.eventsUrl(sessionId)));
+    try { await stream.ready; return stream; } catch (error) { stream.close(); throw error; }
+  }
+  async *events(sessionId, options = {}) {
+    const stream = await this.connect(sessionId, options);
+    try { yield* stream; } finally { stream.close(); }
+  }
+  capabilities() { return this._request('GET', '/api/v2/capabilities'); }
+  billing() { return this._request('GET', '/api/v2/billing'); }
+  listAvatars() { return this._request('GET', '/api/v2/avatars'); }
+  listVoices() { return this._request('GET', '/api/v2/voices'); }
+  listLanguages() { return this._request('GET', '/api/v2/languages'); }
+  updateContext(sessionId, context) { return this._request('POST', `/api/v2/sessions/${enc(sessionId)}/context`, context); }
+  startPresentation(sessionId, start) { return this._request('POST', `/api/v2/sessions/${enc(sessionId)}/presentation`, start); }
+  speech(sessionId, type, payload) { return this._request('POST', `/api/v2/sessions/${enc(sessionId)}/speech`, { type, payload }); }
+  startSpeech(sessionId, turnId, { text } = {}) { return this.speech(sessionId, 'speech.start', speechStart(turnId, text)); }
+  appendSpeech(sessionId, turnId, seq, startSample, pcm) { return this.speech(sessionId, 'speech.append', speechAppend(turnId, seq, startSample, pcm)); }
+  finishSpeech(sessionId, turnId, totalSamples) { return this.speech(sessionId, 'speech.done', { turn_id: turnId, total_samples: totalSamples }); }
+  cancelSpeech(sessionId, turnId) { return this.speech(sessionId, 'speech.cancel', { turn_id: turnId }); }
 
   // -- presets --------------------------------------------------------------
 
@@ -147,9 +133,9 @@ export class Anva {
     return this._request("GET", "/api/v2/presets");
   }
 
-  createPreset({ name, visualCharacterId, systemPrompt, voiceId, languageCode }) {
+  createPreset({ name, avatarId, visualCharacterId, systemPrompt, voiceId, languageCode }) {
     const body = { name };
-    if (visualCharacterId) body.visual_character_id = visualCharacterId;
+    if (avatarId || visualCharacterId) body.avatar_id = avatarId || visualCharacterId;
     if (systemPrompt) body.system_prompt = systemPrompt;
     if (voiceId) body.voice_id = voiceId;
     if (languageCode) body.language_code = languageCode;
@@ -160,6 +146,10 @@ export class Anva {
     return this._request("GET", `/api/v2/presets/${enc(presetId)}`);
   }
 
+  updatePreset(presetId, patch) {
+    return this._request("PATCH", `/api/v2/presets/${enc(presetId)}`, patch);
+  }
+
   deletePreset(presetId) {
     return this._request("DELETE", `/api/v2/presets/${enc(presetId)}`);
   }
@@ -178,7 +168,7 @@ export class Anva {
       headers: {
         Authorization: `Bearer ${this.apiKey}`,
         "Content-Type": "application/json",
-        "User-Agent": "anva-js/0.2.0",
+        "User-Agent": "anva-js/0.3.0",
       },
       body: body === undefined ? undefined : JSON.stringify(body),
     });
@@ -190,8 +180,8 @@ export class Anva {
       payload = { message: raw.slice(0, 300) };
     }
     if (!res.ok) {
-      const err = payload.error || payload;
-      throw new AnvaError(res.status, err.code || "request_failed", err.message || "request failed");
+      const err = payload?.error || payload || {};
+      throw new AnvaError(res.status, err.code || "request_failed", err.message || "request failed", err);
     }
     return payload;
   }

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "anva-sdk",
-  "version": "0.2.0",
+  "version": "0.3.0",
   "description": "Official JavaScript/TypeScript SDK for Anva \u2014 live AI avatars for your product.",
   "keywords": [
     "avatar",
@@ -30,9 +30,13 @@
   "files": [
     "index.js",
     "index.d.ts",
-    "README.md"
+    "README.md",
+    "realtime.js"
   ],
   "engines": {
     "node": ">=18"
+  },
+  "scripts": {
+    "test": "node --test test/*.test.js"
   }
-}
+}

package/realtime.js

@@ -0,0 +1,78 @@
+/** A single bidirectional events connection. Keep the API key on your server. */
+export class RealtimeSession {
+  constructor(socket) {
+    this.socket = socket;
+    this.queue = [];
+    this.waiters = [];
+    this.closed = false;
+    this.closeRequested = false;
+    this.failure = null;
+    this.ready = new Promise((resolve, reject) => {
+      this.resolveReady = resolve;
+      this.rejectReady = reject;
+    });
+    socket.onopen = () => this.resolveReady(this);
+    socket.onmessage = event => {
+      try { this.queue.push(JSON.parse(event.data)); } catch { return; }
+      this.wake();
+    };
+    socket.onclose = event => {
+      this.closed = true;
+      if (event.code !== 1000 && event.code !== undefined) this.failure ||= new Error(`Events socket closed (${event.code})`);
+      this.rejectReady(this.failure || new Error('Events socket closed before opening'));
+      this.wake();
+    };
+    socket.onerror = () => {
+      this.failure = new Error('Events socket error');
+      this.closed = true;
+      this.rejectReady(this.failure);
+      this.close();
+      this.wake();
+    };
+    if (socket.readyState === 1) this.resolveReady(this);
+  }
+  wake() { for (const resolve of this.waiters.splice(0)) resolve(); }
+  async send(type, payload = {}) {
+    await this.ready;
+    if (this.closed || this.socket.readyState !== 1) throw new Error('Events socket is not open');
+    this.socket.send(JSON.stringify({ type, payload }));
+  }
+  message(text) { return this.send('message', { text }); }
+  interrupt() { return this.send('interrupt'); }
+  updateContext(context) { return this.send('context.update', context); }
+  startPresentation(start) { return this.send('presentation.start', start); }
+  turnDelta(turnId, text) { return this.send('turn.delta', { turn_id: turnId, text }); }
+  turnDone(turnId) { return this.send('turn.done', { turn_id: turnId }); }
+  turnCancel(turnId, reason = '') { return this.send('turn.cancel', { turn_id: turnId, reason }); }
+  startSpeech(turnId, { text } = {}) { return this.send('speech.start', speechStart(turnId, text)); }
+  appendSpeech(turnId, seq, startSample, pcm) { return this.send('speech.append', speechAppend(turnId, seq, startSample, pcm)); }
+  finishSpeech(turnId, totalSamples) { return this.send('speech.done', { turn_id: turnId, total_samples: totalSamples }); }
+  cancelSpeech(turnId) { return this.send('speech.cancel', { turn_id: turnId }); }
+  close() {
+    if (this.closeRequested) return;
+    this.closeRequested = true;
+    this.closed = true;
+    this.rejectReady(new Error('Events socket closed before opening'));
+    try { this.socket.close(1000); } finally { this.wake(); }
+  }
+  async *[Symbol.asyncIterator]() {
+    await this.ready;
+    try {
+      while (!this.closed || this.queue.length) {
+        if (!this.queue.length) { await new Promise(resolve => this.waiters.push(resolve)); continue; }
+        yield this.queue.shift();
+      }
+      if (this.failure) throw this.failure;
+    } finally { this.close(); }
+  }
+}
+export const speechStart = (turnId, text) => ({ turn_id: turnId, codec: 'pcm_s16le', sample_rate: 24000, channels: 1, ...(text === undefined ? {} : { text }) });
+export function speechAppend(turnId, seq, startSample, pcm) {
+  const bytes = pcm instanceof Uint8Array ? pcm : pcm instanceof ArrayBuffer ? new Uint8Array(pcm) : null;
+  if (!bytes || bytes.length === 0 || bytes.length % 2 || bytes.length > 24000) throw new Error('PCM chunk must contain 1–12000 signed 16-bit samples');
+  if (!Number.isSafeInteger(seq) || seq < 0 || !Number.isSafeInteger(startSample) || startSample < 0) throw new Error('seq and startSample must be nonnegative integers');
+  let binary = '';
+  for (const byte of bytes) binary += String.fromCharCode(byte);
+  const data = typeof globalThis.btoa === 'function' ? globalThis.btoa(binary) : globalThis.Buffer.from(bytes).toString('base64');
+  return { turn_id: turnId, seq, start_sample: startSample, data };
+}