@jchaffin/voicekit 0.2.0

package/README.md

@@ -0,0 +1,369 @@
+# @jchaffin/voicekit
+
+A React library for building voice-enabled AI agents using OpenAI's Realtime API.
+
+## Installation
+
+```bash
+npm install @jchaffin/voicekit @openai/agents
+```
+
+## Quick Start
+
+### 1. Create a session endpoint
+
+```ts
+// app/api/session/route.ts
+import { createSessionHandler } from '@jchaffin/voicekit/server';
+
+export const POST = createSessionHandler();
+
+// Or with options:
+export const POST = createSessionHandler({
+  model: 'gpt-realtime',
+  voice: 'alloy'
+});
+```
+
+### 2. Define your agent
+
+```tsx
+import { createAgent, defineTool } from '@jchaffin/voicekit';
+
+// Define tools
+const weatherTool = defineTool({
+  name: 'get_weather',
+  description: 'Get current weather for a location',
+  parameters: {
+    location: { type: 'string', description: 'City name' }
+  },
+  required: ['location'],
+  execute: async ({ location }) => {
+    const res = await fetch(`/api/weather?city=${location}`);
+    return res.json();
+  }
+});
+
+// Create agent
+const agent = createAgent({
+  name: 'Assistant',
+  instructions: `
+    You are a helpful voice assistant.
+    Help users check the weather and answer questions.
+  `,
+  tools: [weatherTool]
+});
+```
+
+### 3. Wrap your app with VoiceProvider
+
+```tsx
+import { VoiceProvider } from '@jchaffin/voicekit';
+
+function App() {
+  return (
+    <VoiceProvider agent={agent}>
+      <YourApp />
+    </VoiceProvider>
+  );
+}
+```
+
+### 4. Use the useVoice hook
+
+```tsx
+import { useVoice } from '@jchaffin/voicekit';
+
+function VoiceChat() {
+  const { 
+    status, 
+    connect, 
+    disconnect, 
+    transcript, 
+    sendMessage 
+  } = useVoice();
+
+  return (
+    <div>
+      <button onClick={status === 'CONNECTED' ? disconnect : connect}>
+        {status === 'CONNECTED' ? 'End Call' : 'Start Call'}
+      </button>
+      
+      <div>
+        {transcript.map(msg => (
+          <p key={msg.id}>
+            <strong>{msg.role}:</strong> {msg.text}
+          </p>
+        ))}
+      </div>
+      
+      <input 
+        type="text"
+        onKeyDown={(e) => {
+          if (e.key === 'Enter') {
+            sendMessage(e.currentTarget.value);
+            e.currentTarget.value = '';
+          }
+        }}
+        placeholder="Type a message..."
+      />
+    </div>
+  );
+}
+```
+
+## API Reference
+
+### UI Components
+
+#### `<VoiceChat>`
+
+Complete voice chat interface - drop in and go.
+
+```tsx
+import { VoiceProvider, VoiceChat, createAgent } from '@jchaffin/voicekit';
+
+const agent = createAgent({ name: 'Bot', instructions: 'Be helpful' });
+
+function App() {
+  return (
+    <VoiceProvider agent={agent}>
+      <VoiceChat height="400px" />
+    </VoiceProvider>
+  );
+}
+```
+
+Props:
+- `height` - Chat area height (default: `'400px'`)
+- `showHeader` - Show status header (default: `true`)
+- `showInput` - Show text input (default: `true`)
+- `emptyState` - Custom empty state content
+- `header` - Custom header content
+- `footer` - Custom footer content
+
+#### Individual Components
+
+```tsx
+import { 
+  Transcript,      // Message list
+  StatusIndicator, // Connection status dot
+  ConnectButton,   // Start/end button  
+  ChatInput        // Text input
+} from '@jchaffin/voicekit';
+
+// Use within VoiceProvider
+<StatusIndicator />
+<Transcript messages={transcript} />
+<ConnectButton connectText="Start Call" disconnectText="End Call" />
+<ChatInput placeholder="Say something..." />
+```
+
+### Core Components
+
+#### `<VoiceProvider>`
+
+Wraps your app to provide voice functionality.
+
+```tsx
+<VoiceProvider 
+  agent={agent}
+  sessionEndpoint="/api/session"  // Optional, defaults to /api/session
+  model="gpt-4o-realtime-preview" // Optional
+  language="en"                    // Optional
+  onStatusChange={(status) => {}}  // Optional
+  onTranscriptUpdate={(msgs) => {}} // Optional
+  onToolCall={(name, input, result) => {}} // Optional
+  onError={(error) => {}}          // Optional
+>
+  {children}
+</VoiceProvider>
+```
+
+### Hooks
+
+#### `useVoice()`
+
+Main hook for voice interaction.
+
+```ts
+const {
+  status,        // 'DISCONNECTED' | 'CONNECTING' | 'CONNECTED'
+  connect,       // () => Promise<void>
+  disconnect,    // () => Promise<void>
+  transcript,    // TranscriptMessage[]
+  clearTranscript, // () => void
+  sendMessage,   // (text: string) => void
+  interrupt,     // () => void
+  mute,          // (muted: boolean) => void
+  isMuted,       // boolean
+  agent,         // RealtimeAgent
+} = useVoice();
+```
+
+#### `useToolResult(toolName)`
+
+Listen for results from a specific tool.
+
+```tsx
+const { result, input, hasResult, clear } = useToolResult('get_weather');
+```
+
+#### `useToolListener(toolName, handler)`
+
+Register a callback for tool results.
+
+```tsx
+useToolListener('get_weather', (input, result) => {
+  console.log('Weather:', result);
+});
+```
+
+#### `useToolResults()`
+
+Get all tool results.
+
+```tsx
+const { results, lastResult, clear } = useToolResults();
+```
+
+### Tool Builders
+
+#### `defineTool(config)`
+
+Create a tool with type inference.
+
+```ts
+const tool = defineTool({
+  name: 'tool_name',
+  description: 'What the tool does',
+  parameters: {
+    param1: { type: 'string', description: 'Description' },
+    param2: { type: 'number', default: 10 }
+  },
+  required: ['param1'],
+  execute: async ({ param1, param2 }) => {
+    // Implementation
+    return { success: true };
+  }
+});
+```
+
+#### `createNavigationTool(sections)`
+
+Create a tool for single-page app navigation.
+
+```ts
+const navTool = createNavigationTool(['about', 'projects', 'contact']);
+```
+
+#### `createAPITool(config)`
+
+Create a tool that calls an API endpoint.
+
+```ts
+const searchTool = createAPITool({
+  name: 'search',
+  description: 'Search the database',
+  parameters: { query: { type: 'string' } },
+  required: ['query'],
+  endpoint: '/api/search',
+  method: 'POST'
+});
+```
+
+#### `createEventTool(config)`
+
+Create a tool that dispatches DOM events for UI updates.
+
+```ts
+const modalTool = createEventTool({
+  name: 'show_modal',
+  description: 'Show a modal',
+  parameters: { title: { type: 'string' } },
+  eventType: 'voice:show-modal'
+});
+```
+
+### Agent Builders
+
+#### `createAgent(config)`
+
+Create a voice agent.
+
+```ts
+const agent = createAgent({
+  name: 'Assistant',
+  instructions: 'You are helpful.',
+  tools: [tool1, tool2]
+});
+```
+
+#### `createAgentFromTemplate(config)`
+
+Create an agent using structured templates.
+
+```ts
+const agent = createAgentFromTemplate({
+  name: 'Support Bot',
+  role: 'customer support agent',
+  personality: 'Friendly and helpful',
+  capabilities: ['Answer questions', 'Track orders'],
+  constraints: ['Never share private data'],
+  tools: [orderTool]
+});
+```
+
+## Server API
+
+Import from `@jchaffin/voicekit/server` for server-side utilities.
+
+### `createSessionHandler(config?)`
+
+Creates a request handler for Next.js App Router or similar frameworks.
+
+```ts
+import { createSessionHandler } from '@jchaffin/voicekit/server';
+
+// Basic
+export const POST = createSessionHandler();
+
+// With config
+export const POST = createSessionHandler({
+  apiKey: process.env.CUSTOM_KEY,  // defaults to OPENAI_API_KEY
+  model: 'gpt-realtime',
+  voice: 'alloy'
+});
+```
+
+### `getEphemeralKey(config?)`
+
+Get an ephemeral key directly (for Express, Fastify, etc.)
+
+```ts
+import { getEphemeralKey } from '@jchaffin/voicekit/server';
+
+app.post('/api/session', async (req, res) => {
+  const result = await getEphemeralKey();
+  if (result.error) {
+    return res.status(500).json({ error: result.error });
+  }
+  res.json({ ephemeralKey: result.ephemeralKey });
+});
+```
+
+### `handleOptions()` / `corsHeaders()`
+
+CORS helpers for preflight requests.
+
+```ts
+import { handleOptions, corsHeaders } from '@jchaffin/voicekit/server';
+
+export function OPTIONS() {
+  return handleOptions();
+}
+```
+
+## License
+
+MIT

package/dist/adapters/deepgram.d.mts

@@ -0,0 +1,43 @@
+import { i as SessionOptions, g as ServerSessionConfig, e as VoiceAdapter, S as ServerAdapter } from '../types-DY31oVB1.mjs';
+
+/**
+ * Deepgram adapter for VoiceKit.
+ *
+ * Peer dependency: @deepgram/sdk (>= 3.0.0)
+ *
+ * Deepgram provides STT (listen) and TTS (speak) but does not offer a
+ * single "conversational AI" socket like OpenAI or ElevenLabs. This adapter
+ * wires Deepgram live transcription for the user's mic audio and expects
+ * a server-side agent (e.g. your own LLM pipeline) to handle the assistant
+ * logic and push assistant transcripts/audio back via a companion WebSocket.
+ *
+ * Usage:
+ * ```ts
+ * import { deepgram } from '@jchaffin/voicekit/deepgram';
+ *
+ * <VoiceProvider
+ *   adapter={deepgram({ agentUrl: 'wss://my-backend/agent' })}
+ *   agent={agent}
+ * />
+ * ```
+ */
+
+interface DeepgramAdapterOptions extends SessionOptions {
+    /** WebSocket URL of your agent backend that orchestrates Deepgram STT + LLM + TTS */
+    agentUrl: string;
+}
+/**
+ * Create a Deepgram adapter.
+ *
+ * ```ts
+ * import { deepgram } from '@jchaffin/voicekit/deepgram';
+ * <VoiceProvider adapter={deepgram({ agentUrl: 'wss://...' })} agent={agent} />
+ * ```
+ */
+declare function deepgram(options: DeepgramAdapterOptions): VoiceAdapter;
+interface DeepgramServerConfig extends ServerSessionConfig {
+    apiKey?: string;
+}
+declare function deepgramServer(config?: DeepgramServerConfig): ServerAdapter;
+
+export { type DeepgramAdapterOptions, type DeepgramServerConfig, deepgram, deepgramServer, deepgram as default };

package/dist/adapters/deepgram.d.ts

@@ -0,0 +1,43 @@
+import { i as SessionOptions, g as ServerSessionConfig, e as VoiceAdapter, S as ServerAdapter } from '../types-DY31oVB1.js';
+
+/**
+ * Deepgram adapter for VoiceKit.
+ *
+ * Peer dependency: @deepgram/sdk (>= 3.0.0)
+ *
+ * Deepgram provides STT (listen) and TTS (speak) but does not offer a
+ * single "conversational AI" socket like OpenAI or ElevenLabs. This adapter
+ * wires Deepgram live transcription for the user's mic audio and expects
+ * a server-side agent (e.g. your own LLM pipeline) to handle the assistant
+ * logic and push assistant transcripts/audio back via a companion WebSocket.
+ *
+ * Usage:
+ * ```ts
+ * import { deepgram } from '@jchaffin/voicekit/deepgram';
+ *
+ * <VoiceProvider
+ *   adapter={deepgram({ agentUrl: 'wss://my-backend/agent' })}
+ *   agent={agent}
+ * />
+ * ```
+ */
+
+interface DeepgramAdapterOptions extends SessionOptions {
+    /** WebSocket URL of your agent backend that orchestrates Deepgram STT + LLM + TTS */
+    agentUrl: string;
+}
+/**
+ * Create a Deepgram adapter.
+ *
+ * ```ts
+ * import { deepgram } from '@jchaffin/voicekit/deepgram';
+ * <VoiceProvider adapter={deepgram({ agentUrl: 'wss://...' })} agent={agent} />
+ * ```
+ */
+declare function deepgram(options: DeepgramAdapterOptions): VoiceAdapter;
+interface DeepgramServerConfig extends ServerSessionConfig {
+    apiKey?: string;
+}
+declare function deepgramServer(config?: DeepgramServerConfig): ServerAdapter;
+
+export { type DeepgramAdapterOptions, type DeepgramServerConfig, deepgram, deepgramServer, deepgram as default };

package/dist/adapters/deepgram.js

@@ -0,0 +1,216 @@
+"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/adapters/deepgram.ts
+var deepgram_exports = {};
+__export(deepgram_exports, {
+  deepgram: () => deepgram,
+  deepgramServer: () => deepgramServer,
+  default: () => deepgram_default
+});
+module.exports = __toCommonJS(deepgram_exports);
+
+// src/core/EventEmitter.ts
+var EventEmitter = class {
+  constructor() {
+    this.handlers = /* @__PURE__ */ new Map();
+  }
+  on(event, handler) {
+    let set = this.handlers.get(event);
+    if (!set) {
+      set = /* @__PURE__ */ new Set();
+      this.handlers.set(event, set);
+    }
+    set.add(handler);
+  }
+  off(event, handler) {
+    this.handlers.get(event)?.delete(handler);
+  }
+  emit(event, ...args) {
+    this.handlers.get(event)?.forEach((fn) => {
+      try {
+        fn(...args);
+      } catch (e) {
+        console.error(`EventEmitter error in "${event}":`, e);
+      }
+    });
+  }
+  removeAllListeners() {
+    this.handlers.clear();
+  }
+};
+
+// src/adapters/deepgram.ts
+var DeepgramSession = class extends EventEmitter {
+  constructor(agent, agentUrl, options) {
+    super();
+    this.ws = null;
+    this.mediaStream = null;
+    this.mediaRecorder = null;
+    this.agent = agent;
+    this.agentUrl = agentUrl;
+    this.options = options;
+  }
+  async connect(config) {
+    const url = new URL(this.agentUrl);
+    url.searchParams.set("token", config.authToken);
+    if (this.options.model) url.searchParams.set("model", this.options.model);
+    if (this.options.language) url.searchParams.set("language", this.options.language);
+    this.ws = new WebSocket(url.toString());
+    await new Promise((resolve, reject) => {
+      const ws = this.ws;
+      ws.onopen = () => resolve();
+      ws.onerror = (e) => reject(new Error("WebSocket connection failed"));
+      ws.onclose = () => this.emit("status_change", "DISCONNECTED");
+    });
+    this.ws.onmessage = (event) => {
+      try {
+        const msg = JSON.parse(event.data);
+        this.handleMessage(msg, config.audioElement);
+      } catch {
+        this.emit("raw_event", event.data);
+      }
+    };
+    this.ws.onerror = () => {
+      this.emit("error", new Error("Deepgram WebSocket error"));
+    };
+    this.ws.send(JSON.stringify({
+      type: "agent_config",
+      agent: {
+        name: this.agent.name,
+        instructions: this.agent.instructions,
+        tools: (this.agent.tools || []).map((t) => ({
+          name: t.name,
+          description: t.description,
+          parameters: t.parameters
+        }))
+      }
+    }));
+    this.mediaStream = await navigator.mediaDevices.getUserMedia({ audio: true });
+    this.mediaRecorder = new MediaRecorder(this.mediaStream, {
+      mimeType: MediaRecorder.isTypeSupported("audio/webm;codecs=opus") ? "audio/webm;codecs=opus" : "audio/webm"
+    });
+    this.mediaRecorder.ondataavailable = (e) => {
+      if (e.data.size > 0 && this.ws?.readyState === WebSocket.OPEN) {
+        this.ws.send(e.data);
+      }
+    };
+    this.mediaRecorder.start(250);
+    this.emit("status_change", "CONNECTED");
+  }
+  async disconnect() {
+    this.mediaRecorder?.stop();
+    this.mediaStream?.getTracks().forEach((t) => t.stop());
+    this.mediaRecorder = null;
+    this.mediaStream = null;
+    if (this.ws) {
+      this.ws.close();
+      this.ws = null;
+    }
+    this.removeAllListeners();
+  }
+  sendMessage(text) {
+    this.ws?.send(JSON.stringify({ type: "user_message", text }));
+  }
+  interrupt() {
+    this.ws?.send(JSON.stringify({ type: "interrupt" }));
+  }
+  mute(muted) {
+    this.mediaStream?.getAudioTracks().forEach((t) => {
+      t.enabled = !muted;
+    });
+  }
+  sendRawEvent(event) {
+    this.ws?.send(JSON.stringify(event));
+  }
+  handleMessage(msg, audioElement) {
+    switch (msg.type) {
+      case "user_transcript":
+        this.emit("user_transcript", {
+          itemId: msg.itemId || msg.id || "",
+          delta: msg.delta,
+          text: msg.text,
+          isFinal: msg.is_final ?? msg.isFinal ?? !!msg.text
+        });
+        break;
+      case "assistant_transcript":
+        this.emit("assistant_transcript", {
+          itemId: msg.itemId || msg.id || "",
+          delta: msg.delta,
+          text: msg.text,
+          isFinal: msg.is_final ?? msg.isFinal ?? !!msg.text
+        });
+        break;
+      case "audio":
+        if (msg.data && audioElement) {
+          this.emit("audio_delta", msg.itemId || "", msg.data);
+        }
+        break;
+      case "tool_call_start":
+        this.emit("tool_call_start", msg.name, msg.input);
+        break;
+      case "tool_call_end":
+        this.emit("tool_call_end", msg.name, msg.input, msg.output);
+        break;
+      case "speech_started":
+        this.emit("user_speech_started");
+        break;
+      case "error":
+        this.emit("error", new Error(msg.message || "Deepgram error"));
+        break;
+      default:
+        this.emit("raw_event", msg);
+        break;
+    }
+  }
+};
+function deepgram(options) {
+  return {
+    name: "deepgram",
+    createSession(agent, sessionOpts) {
+      return new DeepgramSession(agent, options.agentUrl, { ...options, ...sessionOpts });
+    }
+  };
+}
+function deepgramServer(config = {}) {
+  const getSessionToken = async (overrides = {}) => {
+    const merged = { ...config, ...overrides };
+    const apiKey = merged.apiKey || process.env.DEEPGRAM_API_KEY;
+    if (!apiKey) return { error: "Deepgram API key not configured" };
+    return { token: apiKey };
+  };
+  return {
+    getSessionToken,
+    createSessionHandler(overrides) {
+      return async (_request) => {
+        const result = await getSessionToken(overrides);
+        if (result.error) {
+          return Response.json({ error: result.error }, { status: 500 });
+        }
+        return Response.json({ ephemeralKey: result.token });
+      };
+    }
+  };
+}
+var deepgram_default = deepgram;
+// Annotate the CommonJS export names for ESM import in node:
+0 && (module.exports = {
+  deepgram,
+  deepgramServer
+});