@lokutor/sdk 1.0.0

package/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2024 Lokutor AI
+
+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

@@ -0,0 +1,80 @@
+# Lokutor JavaScript SDK
+
+[![npm version](https://img.shields.io/npm/v/@lokutor/sdk.svg)](https://www.npmjs.com/package/@lokutor/sdk)
+[![License: MIT](https://img.shields.io/badge/License-MIT-yellow.svg)](https://opensource.org/licenses/MIT)
+
+Official JavaScript/TypeScript SDK for [Lokutor AI](https://lokutor.com), providing high-performance, real-time Voice-to-Voice AI.
+
+## Features
+
+- ⚡ **Ultra-low latency**: Optimized WebSocket streaming for real-time interactions.
+- 🗣️ **Conversational Intelligence**: Integrated STT, LLM, and TTS with VAD and barge-in support.
+- 🌍 **Multi-lingual**: Support for English, Spanish, French, Portuguese, and Korean.
+- 🎨 **Natural Voices**: Multiple high-quality male and female voice styles.
+- 💻 **TypeScript First**: Full type definitions included.
+
+## Installation
+
+```bash
+npm install @lokutor/sdk
+# or
+yarn add @lokutor/sdk
+```
+
+## Quick Start
+
+### 1. Voice Agent (Conversational AI)
+
+The `VoiceAgentClient` handles everything from audio streaming to conversational logic.
+
+```typescript
+import { VoiceAgentClient, VoiceStyle, Language } from '@lokutor/sdk';
+
+const client = new VoiceAgentClient({
+  apiKey: 'your-api-key',
+  prompt: 'You are a helpful and friendly AI assistant.',
+  onTranscription: (text) => console.log('User:', text),
+  onResponse: (text) => console.log('AI:', text)
+});
+
+await client.connect();
+// Feed PCM audio data to the client:
+// client.sendAudio(pcmData);
+```
+
+### 2. Standalone Streaming TTS
+
+Use `TTSClient` to convert text into high-quality audio streams without the conversational overhead.
+
+```typescript
+import { TTSClient, VoiceStyle } from '@lokutor/sdk';
+
+const client = new TTSClient({ apiKey: 'your-api-key' });
+
+await client.synthesize({
+  text: 'Hello world, this is a test of Lokutor streaming TTS.',
+  voice: VoiceStyle.F1,
+  onAudio: (buffer) => {
+    // Play the audio buffer (Node.js or Browser)
+    console.log(`Received ${buffer.length} bytes of audio`);
+  }
+});
+```
+
+## Hardware Compatibility
+
+This SDK is platform-agnostic and works in both **Node.js** and **Browser** environments. 
+
+### For Node.js
+We recommend using `node-record-lpcm16` for recording and `speaker` for playback. See the [examples](./examples) folder for a complete Node.js CLI implementation.
+
+### For Browser
+Use the [Web Audio API](https://developer.mozilla.org/en-US/docs/Web/API/Web_Audio_API) to capture microphone input and play back the received buffers.
+
+## Documentation
+
+Full documentation is available at [docs.lokutor.com](https://docs.lokutor.com).
+
+## License
+
+MIT © [Lokutor AI](https://lokutor.com)

package/dist/index.d.mts

@@ -0,0 +1,163 @@
+/**
+ * Available voice styles for the Lokutor AI Agent
+ */
+declare enum VoiceStyle {
+    F1 = "F1",
+    F2 = "F2",
+    F3 = "F3",
+    F4 = "F4",
+    F5 = "F5",
+    M1 = "M1",
+    M2 = "M2",
+    M3 = "M3",
+    M4 = "M4",
+    M5 = "M5"
+}
+/**
+ * Supported languages for speech and text
+ */
+declare enum Language {
+    ENGLISH = "en",
+    SPANISH = "es",
+    FRENCH = "fr",
+    PORTUGUESE = "pt",
+    KOREAN = "ko"
+}
+/**
+ * Audio configuration constants
+ */
+declare const AUDIO_CONFIG: {
+    SAMPLE_RATE: number;
+    CHANNELS: number;
+    CHUNK_DURATION_MS: number;
+    readonly CHUNK_SIZE: number;
+};
+/**
+ * Default WebSocket URLs
+ */
+declare const DEFAULT_URLS: {
+    VOICE_AGENT: string;
+    TTS: string;
+};
+/**
+ * SDK Configuration interface
+ */
+interface LokutorConfig {
+    apiKey: string;
+    serverUrl?: string;
+    onTranscription?: (text: string) => void;
+    onResponse?: (text: string) => void;
+    onAudio?: (data: Buffer) => void;
+    onStatus?: (status: string) => void;
+    onError?: (error: any) => void;
+}
+/**
+ * Text-to-Speech synthesis request options
+ */
+interface SynthesizeOptions {
+    text: string;
+    voice?: VoiceStyle;
+    language?: Language;
+    speed?: number;
+    steps?: number;
+    visemes?: boolean;
+}
+
+/**
+ * Main client for Lokutor Voice Agent SDK
+ *
+ * Provides a high-level interface for real-time voice conversations.
+ */
+declare class VoiceAgentClient {
+    private ws;
+    private apiKey;
+    private serverUrl;
+    prompt: string;
+    voice: VoiceStyle;
+    language: Language;
+    private onTranscription?;
+    private onResponse?;
+    private onAudioCallback?;
+    private onStatus?;
+    private onError?;
+    private isConnected;
+    constructor(config: LokutorConfig & {
+        prompt: string;
+        voice?: VoiceStyle;
+        language?: Language;
+    });
+    /**
+     * Connect to the Lokutor Voice Agent server
+     */
+    connect(): Promise<boolean>;
+    /**
+     * Send initial configuration to the server
+     */
+    private sendConfig;
+    /**
+     * Send raw PCM audio data to the server
+     * @param audioData Int16 PCM audio buffer
+     */
+    sendAudio(audioData: Buffer | Uint8Array): void;
+    /**
+     * Handle incoming binary data (audio response)
+     */
+    private handleBinaryMessage;
+    /**
+     * Handle incoming text messages (metadata/transcriptions)
+     */
+    private handleTextMessage;
+    private audioListeners;
+    private emit;
+    onAudio(callback: (data: Buffer) => void): void;
+    /**
+     * Disconnect from the server
+     */
+    disconnect(): void;
+}
+/**
+ * Client for standalone Text-to-Speech synthesis
+ */
+declare class TTSClient {
+    private apiKey;
+    private serverUrl;
+    private onAudioCallback?;
+    private onVisemesCallback?;
+    private onErrorCallback?;
+    constructor(config: {
+        apiKey: string;
+        serverUrl?: string;
+    });
+    /**
+     * Synthesize text to speech
+     *
+     * This opens a temporary WebSocket connection, sends the request,
+     * and streams back the audio.
+     */
+    synthesize(options: {
+        text: string;
+        voice?: VoiceStyle;
+        language?: Language;
+        speed?: number;
+        steps?: number;
+        visemes?: boolean;
+        onAudio?: (data: Buffer) => void;
+        onVisemes?: (visemes: any[]) => void;
+        onError?: (error: any) => void;
+    }): Promise<void>;
+}
+/**
+ * Quick function to start a conversation (requires manual audio piping in JS)
+ */
+declare function simpleConversation(config: LokutorConfig & {
+    prompt: string;
+}): Promise<VoiceAgentClient>;
+/**
+ * Quick function for standalone TTS synthesis
+ */
+declare function simpleTTS(options: SynthesizeOptions & {
+    apiKey: string;
+    onAudio: (buf: Buffer) => void;
+}): Promise<void>;
+
+export { AUDIO_CONFIG, DEFAULT_URLS, Language, type LokutorConfig, type SynthesizeOptions, TTSClient, VoiceAgentClient, VoiceStyle, simpleConversation, simpleTTS };

package/dist/index.d.ts

@@ -0,0 +1,163 @@
+/**
+ * Available voice styles for the Lokutor AI Agent
+ */
+declare enum VoiceStyle {
+    F1 = "F1",
+    F2 = "F2",
+    F3 = "F3",
+    F4 = "F4",
+    F5 = "F5",
+    M1 = "M1",
+    M2 = "M2",
+    M3 = "M3",
+    M4 = "M4",
+    M5 = "M5"
+}
+/**
+ * Supported languages for speech and text
+ */
+declare enum Language {
+    ENGLISH = "en",
+    SPANISH = "es",
+    FRENCH = "fr",
+    PORTUGUESE = "pt",
+    KOREAN = "ko"
+}
+/**
+ * Audio configuration constants
+ */
+declare const AUDIO_CONFIG: {
+    SAMPLE_RATE: number;
+    CHANNELS: number;
+    CHUNK_DURATION_MS: number;
+    readonly CHUNK_SIZE: number;
+};
+/**
+ * Default WebSocket URLs
+ */
+declare const DEFAULT_URLS: {
+    VOICE_AGENT: string;
+    TTS: string;
+};
+/**
+ * SDK Configuration interface
+ */
+interface LokutorConfig {
+    apiKey: string;
+    serverUrl?: string;
+    onTranscription?: (text: string) => void;
+    onResponse?: (text: string) => void;
+    onAudio?: (data: Buffer) => void;
+    onStatus?: (status: string) => void;
+    onError?: (error: any) => void;
+}
+/**
+ * Text-to-Speech synthesis request options
+ */
+interface SynthesizeOptions {
+    text: string;
+    voice?: VoiceStyle;
+    language?: Language;
+    speed?: number;
+    steps?: number;
+    visemes?: boolean;
+}
+
+/**
+ * Main client for Lokutor Voice Agent SDK
+ *
+ * Provides a high-level interface for real-time voice conversations.
+ */
+declare class VoiceAgentClient {
+    private ws;
+    private apiKey;
+    private serverUrl;
+    prompt: string;
+    voice: VoiceStyle;
+    language: Language;
+    private onTranscription?;
+    private onResponse?;
+    private onAudioCallback?;
+    private onStatus?;
+    private onError?;
+    private isConnected;
+    constructor(config: LokutorConfig & {
+        prompt: string;
+        voice?: VoiceStyle;
+        language?: Language;
+    });
+    /**
+     * Connect to the Lokutor Voice Agent server
+     */
+    connect(): Promise<boolean>;
+    /**
+     * Send initial configuration to the server
+     */
+    private sendConfig;
+    /**
+     * Send raw PCM audio data to the server
+     * @param audioData Int16 PCM audio buffer
+     */
+    sendAudio(audioData: Buffer | Uint8Array): void;
+    /**
+     * Handle incoming binary data (audio response)
+     */
+    private handleBinaryMessage;
+    /**
+     * Handle incoming text messages (metadata/transcriptions)
+     */
+    private handleTextMessage;
+    private audioListeners;
+    private emit;
+    onAudio(callback: (data: Buffer) => void): void;
+    /**
+     * Disconnect from the server
+     */
+    disconnect(): void;
+}
+/**
+ * Client for standalone Text-to-Speech synthesis
+ */
+declare class TTSClient {
+    private apiKey;
+    private serverUrl;
+    private onAudioCallback?;
+    private onVisemesCallback?;
+    private onErrorCallback?;
+    constructor(config: {
+        apiKey: string;
+        serverUrl?: string;
+    });
+    /**
+     * Synthesize text to speech
+     *
+     * This opens a temporary WebSocket connection, sends the request,
+     * and streams back the audio.
+     */
+    synthesize(options: {
+        text: string;
+        voice?: VoiceStyle;
+        language?: Language;
+        speed?: number;
+        steps?: number;
+        visemes?: boolean;
+        onAudio?: (data: Buffer) => void;
+        onVisemes?: (visemes: any[]) => void;
+        onError?: (error: any) => void;
+    }): Promise<void>;
+}
+/**
+ * Quick function to start a conversation (requires manual audio piping in JS)
+ */
+declare function simpleConversation(config: LokutorConfig & {
+    prompt: string;
+}): Promise<VoiceAgentClient>;
+/**
+ * Quick function for standalone TTS synthesis
+ */
+declare function simpleTTS(options: SynthesizeOptions & {
+    apiKey: string;
+    onAudio: (buf: Buffer) => void;
+}): Promise<void>;
+
+export { AUDIO_CONFIG, DEFAULT_URLS, Language, type LokutorConfig, type SynthesizeOptions, TTSClient, VoiceAgentClient, VoiceStyle, simpleConversation, simpleTTS };

package/dist/index.js

@@ -0,0 +1,305 @@
+"use strict";
+var __defProp = Object.defineProperty;
+var __getOwnPropDesc = Object.getOwnPropertyDescriptor;
+var __getOwnPropNames = Object.getOwnPropertyNames;
+var __hasOwnProp = Object.prototype.hasOwnProperty;
+var __export = (target, all) => {
+  for (var name in all)
+    __defProp(target, name, { get: all[name], enumerable: true });
+};
+var __copyProps = (to, from, except, desc) => {
+  if (from && typeof from === "object" || typeof from === "function") {
+    for (let key of __getOwnPropNames(from))
+      if (!__hasOwnProp.call(to, key) && key !== except)
+        __defProp(to, key, { get: () => from[key], enumerable: !(desc = __getOwnPropDesc(from, key)) || desc.enumerable });
+  }
+  return to;
+};
+var __toCommonJS = (mod) => __copyProps(__defProp({}, "__esModule", { value: true }), mod);
+
+// src/index.ts
+var index_exports = {};
+__export(index_exports, {
+  AUDIO_CONFIG: () => AUDIO_CONFIG,
+  DEFAULT_URLS: () => DEFAULT_URLS,
+  Language: () => Language,
+  TTSClient: () => TTSClient,
+  VoiceAgentClient: () => VoiceAgentClient,
+  VoiceStyle: () => VoiceStyle,
+  simpleConversation: () => simpleConversation,
+  simpleTTS: () => simpleTTS
+});
+module.exports = __toCommonJS(index_exports);
+
+// src/types.ts
+var VoiceStyle = /* @__PURE__ */ ((VoiceStyle2) => {
+  VoiceStyle2["F1"] = "F1";
+  VoiceStyle2["F2"] = "F2";
+  VoiceStyle2["F3"] = "F3";
+  VoiceStyle2["F4"] = "F4";
+  VoiceStyle2["F5"] = "F5";
+  VoiceStyle2["M1"] = "M1";
+  VoiceStyle2["M2"] = "M2";
+  VoiceStyle2["M3"] = "M3";
+  VoiceStyle2["M4"] = "M4";
+  VoiceStyle2["M5"] = "M5";
+  return VoiceStyle2;
+})(VoiceStyle || {});
+var Language = /* @__PURE__ */ ((Language2) => {
+  Language2["ENGLISH"] = "en";
+  Language2["SPANISH"] = "es";
+  Language2["FRENCH"] = "fr";
+  Language2["PORTUGUESE"] = "pt";
+  Language2["KOREAN"] = "ko";
+  return Language2;
+})(Language || {});
+var AUDIO_CONFIG = {
+  SAMPLE_RATE: 44100,
+  CHANNELS: 1,
+  CHUNK_DURATION_MS: 20,
+  get CHUNK_SIZE() {
+    return Math.floor(this.SAMPLE_RATE * this.CHUNK_DURATION_MS / 1e3);
+  }
+};
+var DEFAULT_URLS = {
+  VOICE_AGENT: "wss://api.lokutor.com/ws/agent",
+  TTS: "wss://api.lokutor.com/ws/tts"
+};
+
+// src/client.ts
+var import_ws = require("ws");
+var VoiceAgentClient = class {
+  ws = null;
+  apiKey;
+  serverUrl;
+  prompt;
+  voice;
+  language;
+  // Callbacks
+  onTranscription;
+  onResponse;
+  onAudioCallback;
+  onStatus;
+  onError;
+  isConnected = false;
+  constructor(config) {
+    this.apiKey = config.apiKey;
+    this.serverUrl = config.serverUrl || DEFAULT_URLS.VOICE_AGENT;
+    this.prompt = config.prompt;
+    this.voice = config.voice || "F1" /* F1 */;
+    this.language = config.language || "en" /* ENGLISH */;
+    this.onTranscription = config.onTranscription;
+    this.onResponse = config.onResponse;
+    this.onAudioCallback = config.onAudio;
+    this.onStatus = config.onStatus;
+    this.onError = config.onError;
+  }
+  /**
+   * Connect to the Lokutor Voice Agent server
+   */
+  async connect() {
+    return new Promise((resolve, reject) => {
+      try {
+        console.log(`\u{1F517} Connecting to ${this.serverUrl}...`);
+        const headers = {};
+        if (this.apiKey) {
+          headers["X-API-Key"] = this.apiKey;
+        }
+        this.ws = new import_ws.WebSocket(this.serverUrl, {
+          headers
+        });
+        this.ws.on("open", () => {
+          this.isConnected = true;
+          console.log("\u2705 Connected to voice agent!");
+          this.sendConfig();
+          resolve(true);
+        });
+        this.ws.on("message", (data, isBinary) => {
+          if (isBinary) {
+            this.handleBinaryMessage(data);
+          } else {
+            this.handleTextMessage(data.toString());
+          }
+        });
+        this.ws.on("error", (err) => {
+          console.error("\u274C WebSocket error:", err);
+          if (this.onError) this.onError(err);
+          if (!this.isConnected) reject(err);
+        });
+        this.ws.on("close", () => {
+          this.isConnected = false;
+          console.log("Disconnected");
+        });
+      } catch (err) {
+        if (this.onError) this.onError(err);
+        reject(err);
+      }
+    });
+  }
+  /**
+   * Send initial configuration to the server
+   */
+  sendConfig() {
+    if (!this.ws || !this.isConnected) return;
+    this.ws.send(JSON.stringify({ type: "prompt", data: this.prompt }));
+    this.ws.send(JSON.stringify({ type: "voice", data: this.voice }));
+    this.ws.send(JSON.stringify({ type: "language", data: this.language }));
+    console.log(`\u2699\uFE0F Configured: voice=${this.voice}, language=${this.language}`);
+  }
+  /**
+   * Send raw PCM audio data to the server
+   * @param audioData Int16 PCM audio buffer
+   */
+  sendAudio(audioData) {
+    if (this.ws && this.isConnected) {
+      this.ws.send(audioData, { binary: true });
+    }
+  }
+  /**
+   * Handle incoming binary data (audio response)
+   */
+  handleBinaryMessage(data) {
+    this.emit("audio", data);
+  }
+  /**
+   * Handle incoming text messages (metadata/transcriptions)
+   */
+  handleTextMessage(text) {
+    try {
+      const msg = JSON.parse(text);
+      switch (msg.type) {
+        case "audio":
+          if (msg.data) {
+            const buffer = Buffer.from(msg.data, "base64");
+            this.handleBinaryMessage(buffer);
+          }
+          break;
+        case "transcript":
+          if (msg.role === "user") {
+            if (this.onTranscription) this.onTranscription(msg.data);
+            console.log(`\u{1F4AC} You: ${msg.data}`);
+          } else {
+            if (this.onResponse) this.onResponse(msg.data);
+            console.log(`\u{1F916} Agent: ${msg.data}`);
+          }
+          break;
+        case "status":
+          if (this.onStatus) this.onStatus(msg.data);
+          const icons = {
+            "interrupted": "\u26A1",
+            "thinking": "\u{1F9E0}",
+            "speaking": "\u{1F50A}",
+            "listening": "\u{1F442}"
+          };
+          console.log(`${icons[msg.data] || ""} Status: ${msg.data}`);
+          break;
+        case "error":
+          if (this.onError) this.onError(msg.data);
+          console.error(`\u274C Server error: ${msg.data}`);
+          break;
+      }
+    } catch (e) {
+    }
+  }
+  audioListeners = [];
+  emit(event, data) {
+    if (event === "audio") {
+      if (this.onAudioCallback) this.onAudioCallback(data);
+      this.audioListeners.forEach((l) => l(data));
+    }
+  }
+  onAudio(callback) {
+    this.audioListeners.push(callback);
+  }
+  /**
+   * Disconnect from the server
+   */
+  disconnect() {
+    if (this.ws) {
+      this.ws.close();
+      this.ws = null;
+    }
+  }
+};
+var TTSClient = class {
+  apiKey;
+  serverUrl;
+  onAudioCallback;
+  onVisemesCallback;
+  onErrorCallback;
+  constructor(config) {
+    this.apiKey = config.apiKey;
+    this.serverUrl = config.serverUrl || DEFAULT_URLS.TTS;
+  }
+  /**
+   * Synthesize text to speech
+   * 
+   * This opens a temporary WebSocket connection, sends the request, 
+   * and streams back the audio.
+   */
+  synthesize(options) {
+    return new Promise((resolve, reject) => {
+      try {
+        const headers = {};
+        if (this.apiKey) {
+          headers["X-API-Key"] = this.apiKey;
+        }
+        const ws = new import_ws.WebSocket(this.serverUrl, { headers });
+        ws.on("open", () => {
+          const req = {
+            text: options.text,
+            voice: options.voice || "F1" /* F1 */,
+            lang: options.language || "en" /* ENGLISH */,
+            speed: options.speed || 1.05,
+            steps: options.steps || 24,
+            visemes: options.visemes || false
+          };
+          ws.send(JSON.stringify(req));
+        });
+        ws.on("message", (data, isBinary) => {
+          if (isBinary) {
+            if (options.onAudio) options.onAudio(data);
+          } else {
+            try {
+              const msg = JSON.parse(data.toString());
+              if (Array.isArray(msg) && options.onVisemes) {
+                options.onVisemes(msg);
+              }
+            } catch (e) {
+            }
+          }
+        });
+        ws.on("error", (err) => {
+          if (options.onError) options.onError(err);
+          reject(err);
+        });
+        ws.on("close", () => {
+          resolve();
+        });
+      } catch (err) {
+        if (options.onError) options.onError(err);
+        reject(err);
+      }
+    });
+  }
+};
+async function simpleConversation(config) {
+  const client = new VoiceAgentClient(config);
+  await client.connect();
+  return client;
+}
+async function simpleTTS(options) {
+  const client = new TTSClient({ apiKey: options.apiKey });
+  return client.synthesize(options);
+}
+// Annotate the CommonJS export names for ESM import in node:
+0 && (module.exports = {
+  AUDIO_CONFIG,
+  DEFAULT_URLS,
+  Language,
+  TTSClient,
+  VoiceAgentClient,
+  VoiceStyle,
+  simpleConversation,
+  simpleTTS
+});

package/dist/index.mjs

@@ -0,0 +1,271 @@
+// src/types.ts
+var VoiceStyle = /* @__PURE__ */ ((VoiceStyle2) => {
+  VoiceStyle2["F1"] = "F1";
+  VoiceStyle2["F2"] = "F2";
+  VoiceStyle2["F3"] = "F3";
+  VoiceStyle2["F4"] = "F4";
+  VoiceStyle2["F5"] = "F5";
+  VoiceStyle2["M1"] = "M1";
+  VoiceStyle2["M2"] = "M2";
+  VoiceStyle2["M3"] = "M3";
+  VoiceStyle2["M4"] = "M4";
+  VoiceStyle2["M5"] = "M5";
+  return VoiceStyle2;
+})(VoiceStyle || {});
+var Language = /* @__PURE__ */ ((Language2) => {
+  Language2["ENGLISH"] = "en";
+  Language2["SPANISH"] = "es";
+  Language2["FRENCH"] = "fr";
+  Language2["PORTUGUESE"] = "pt";
+  Language2["KOREAN"] = "ko";
+  return Language2;
+})(Language || {});
+var AUDIO_CONFIG = {
+  SAMPLE_RATE: 44100,
+  CHANNELS: 1,
+  CHUNK_DURATION_MS: 20,
+  get CHUNK_SIZE() {
+    return Math.floor(this.SAMPLE_RATE * this.CHUNK_DURATION_MS / 1e3);
+  }
+};
+var DEFAULT_URLS = {
+  VOICE_AGENT: "wss://api.lokutor.com/ws/agent",
+  TTS: "wss://api.lokutor.com/ws/tts"
+};
+
+// src/client.ts
+import { WebSocket } from "ws";
+var VoiceAgentClient = class {
+  ws = null;
+  apiKey;
+  serverUrl;
+  prompt;
+  voice;
+  language;
+  // Callbacks
+  onTranscription;
+  onResponse;
+  onAudioCallback;
+  onStatus;
+  onError;
+  isConnected = false;
+  constructor(config) {
+    this.apiKey = config.apiKey;
+    this.serverUrl = config.serverUrl || DEFAULT_URLS.VOICE_AGENT;
+    this.prompt = config.prompt;
+    this.voice = config.voice || "F1" /* F1 */;
+    this.language = config.language || "en" /* ENGLISH */;
+    this.onTranscription = config.onTranscription;
+    this.onResponse = config.onResponse;
+    this.onAudioCallback = config.onAudio;
+    this.onStatus = config.onStatus;
+    this.onError = config.onError;
+  }
+  /**
+   * Connect to the Lokutor Voice Agent server
+   */
+  async connect() {
+    return new Promise((resolve, reject) => {
+      try {
+        console.log(`\u{1F517} Connecting to ${this.serverUrl}...`);
+        const headers = {};
+        if (this.apiKey) {
+          headers["X-API-Key"] = this.apiKey;
+        }
+        this.ws = new WebSocket(this.serverUrl, {
+          headers
+        });
+        this.ws.on("open", () => {
+          this.isConnected = true;
+          console.log("\u2705 Connected to voice agent!");
+          this.sendConfig();
+          resolve(true);
+        });
+        this.ws.on("message", (data, isBinary) => {
+          if (isBinary) {
+            this.handleBinaryMessage(data);
+          } else {
+            this.handleTextMessage(data.toString());
+          }
+        });
+        this.ws.on("error", (err) => {
+          console.error("\u274C WebSocket error:", err);
+          if (this.onError) this.onError(err);
+          if (!this.isConnected) reject(err);
+        });
+        this.ws.on("close", () => {
+          this.isConnected = false;
+          console.log("Disconnected");
+        });
+      } catch (err) {
+        if (this.onError) this.onError(err);
+        reject(err);
+      }
+    });
+  }
+  /**
+   * Send initial configuration to the server
+   */
+  sendConfig() {
+    if (!this.ws || !this.isConnected) return;
+    this.ws.send(JSON.stringify({ type: "prompt", data: this.prompt }));
+    this.ws.send(JSON.stringify({ type: "voice", data: this.voice }));
+    this.ws.send(JSON.stringify({ type: "language", data: this.language }));
+    console.log(`\u2699\uFE0F Configured: voice=${this.voice}, language=${this.language}`);
+  }
+  /**
+   * Send raw PCM audio data to the server
+   * @param audioData Int16 PCM audio buffer
+   */
+  sendAudio(audioData) {
+    if (this.ws && this.isConnected) {
+      this.ws.send(audioData, { binary: true });
+    }
+  }
+  /**
+   * Handle incoming binary data (audio response)
+   */
+  handleBinaryMessage(data) {
+    this.emit("audio", data);
+  }
+  /**
+   * Handle incoming text messages (metadata/transcriptions)
+   */
+  handleTextMessage(text) {
+    try {
+      const msg = JSON.parse(text);
+      switch (msg.type) {
+        case "audio":
+          if (msg.data) {
+            const buffer = Buffer.from(msg.data, "base64");
+            this.handleBinaryMessage(buffer);
+          }
+          break;
+        case "transcript":
+          if (msg.role === "user") {
+            if (this.onTranscription) this.onTranscription(msg.data);
+            console.log(`\u{1F4AC} You: ${msg.data}`);
+          } else {
+            if (this.onResponse) this.onResponse(msg.data);
+            console.log(`\u{1F916} Agent: ${msg.data}`);
+          }
+          break;
+        case "status":
+          if (this.onStatus) this.onStatus(msg.data);
+          const icons = {
+            "interrupted": "\u26A1",
+            "thinking": "\u{1F9E0}",
+            "speaking": "\u{1F50A}",
+            "listening": "\u{1F442}"
+          };
+          console.log(`${icons[msg.data] || ""} Status: ${msg.data}`);
+          break;
+        case "error":
+          if (this.onError) this.onError(msg.data);
+          console.error(`\u274C Server error: ${msg.data}`);
+          break;
+      }
+    } catch (e) {
+    }
+  }
+  audioListeners = [];
+  emit(event, data) {
+    if (event === "audio") {
+      if (this.onAudioCallback) this.onAudioCallback(data);
+      this.audioListeners.forEach((l) => l(data));
+    }
+  }
+  onAudio(callback) {
+    this.audioListeners.push(callback);
+  }
+  /**
+   * Disconnect from the server
+   */
+  disconnect() {
+    if (this.ws) {
+      this.ws.close();
+      this.ws = null;
+    }
+  }
+};
+var TTSClient = class {
+  apiKey;
+  serverUrl;
+  onAudioCallback;
+  onVisemesCallback;
+  onErrorCallback;
+  constructor(config) {
+    this.apiKey = config.apiKey;
+    this.serverUrl = config.serverUrl || DEFAULT_URLS.TTS;
+  }
+  /**
+   * Synthesize text to speech
+   * 
+   * This opens a temporary WebSocket connection, sends the request, 
+   * and streams back the audio.
+   */
+  synthesize(options) {
+    return new Promise((resolve, reject) => {
+      try {
+        const headers = {};
+        if (this.apiKey) {
+          headers["X-API-Key"] = this.apiKey;
+        }
+        const ws = new WebSocket(this.serverUrl, { headers });
+        ws.on("open", () => {
+          const req = {
+            text: options.text,
+            voice: options.voice || "F1" /* F1 */,
+            lang: options.language || "en" /* ENGLISH */,
+            speed: options.speed || 1.05,
+            steps: options.steps || 24,
+            visemes: options.visemes || false
+          };
+          ws.send(JSON.stringify(req));
+        });
+        ws.on("message", (data, isBinary) => {
+          if (isBinary) {
+            if (options.onAudio) options.onAudio(data);
+          } else {
+            try {
+              const msg = JSON.parse(data.toString());
+              if (Array.isArray(msg) && options.onVisemes) {
+                options.onVisemes(msg);
+              }
+            } catch (e) {
+            }
+          }
+        });
+        ws.on("error", (err) => {
+          if (options.onError) options.onError(err);
+          reject(err);
+        });
+        ws.on("close", () => {
+          resolve();
+        });
+      } catch (err) {
+        if (options.onError) options.onError(err);
+        reject(err);
+      }
+    });
+  }
+};
+async function simpleConversation(config) {
+  const client = new VoiceAgentClient(config);
+  await client.connect();
+  return client;
+}
+async function simpleTTS(options) {
+  const client = new TTSClient({ apiKey: options.apiKey });
+  return client.synthesize(options);
+}
+export {
+  AUDIO_CONFIG,
+  DEFAULT_URLS,
+  Language,
+  TTSClient,
+  VoiceAgentClient,
+  VoiceStyle,
+  simpleConversation,
+  simpleTTS
+};

package/package.json

@@ -0,0 +1,40 @@
+{
+  "name": "@lokutor/sdk",
+  "version": "1.0.0",
+  "description": "JavaScript/TypeScript SDK for Lokutor Real-time Voice AI",
+  "main": "./dist/index.js",
+  "module": "./dist/index.mjs",
+  "types": "./dist/index.d.ts",
+  "files": [
+    "dist"
+  ],
+  "scripts": {
+    "build": "tsup src/index.ts --format cjs,esm --dts",
+    "dev": "tsup src/index.ts --format cjs,esm --watch --dts",
+    "test": "vitest run",
+    "test:watch": "vitest",
+    "lint": "eslint src --ext .ts",
+    "docs": "typedoc src/index.ts"
+  },
+  "keywords": [
+    "voice",
+    "ai",
+    "tts",
+    "stt",
+    "streaming",
+    "websocket",
+    "real-time"
+  ],
+  "author": "Lokutor AI",
+  "license": "MIT",
+  "dependencies": {
+    "ws": "^8.16.0"
+  },
+  "devDependencies": {
+    "@types/node": "^20.10.0",
+    "@types/ws": "^8.5.10",
+    "tsup": "^8.0.1",
+    "typescript": "^5.3.2",
+    "vitest": "^1.0.1"
+  }
+}