@jchaffin/voicekit 0.2.0

package/dist/server.d.mts

@@ -0,0 +1,80 @@
+export { S as ServerAdapter, g as ServerSessionConfig } from './types-DY31oVB1.mjs';
+
+/**
+ * Server-side utilities for VoiceKit
+ * Use these in your API routes (Next.js, Express, etc.)
+ *
+ * This module provides the legacy OpenAI-specific helpers.
+ * For provider-agnostic server adapters, import from the adapter entrypoints:
+ *   import { openaiServer } from '@jchaffin/voicekit/openai'
+ *   import { livekitServer } from '@jchaffin/voicekit/livekit'
+ */
+
+interface SessionConfig {
+    /** OpenAI API key (defaults to OPENAI_API_KEY env var) */
+    apiKey?: string;
+    /** Model to use */
+    model?: string;
+    /** Voice ID */
+    voice?: string;
+    /** Instructions for the agent */
+    instructions?: string;
+    /** Expiration time in seconds (default: 600 = 10 minutes) */
+    expiresIn?: number;
+}
+/**
+ * Create an ephemeral session key for OpenAI Realtime API
+ *
+ * @example Next.js App Router
+ * ```ts
+ * // app/api/session/route.ts
+ * import { createSessionHandler } from '@jchaffin/voicekit/server';
+ * export const POST = createSessionHandler();
+ * ```
+ *
+ * @example Next.js with config
+ * ```ts
+ * export const POST = createSessionHandler({
+ *   model: 'gpt-realtime',
+ *   voice: 'alloy'
+ * });
+ * ```
+ */
+declare function createSessionHandler(config?: SessionConfig): (request?: Request) => Promise<Response>;
+/**
+ * Get an ephemeral key directly (for custom server implementations)
+ *
+ * @example Express
+ * ```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 });
+ * });
+ * ```
+ */
+declare function getEphemeralKey(config?: SessionConfig): Promise<{
+    ephemeralKey: string;
+    error?: never;
+} | {
+    ephemeralKey?: never;
+    error: string;
+}>;
+/**
+ * Create CORS headers for API routes
+ */
+declare function corsHeaders(origin?: string): {
+    'Access-Control-Allow-Origin': string;
+    'Access-Control-Allow-Methods': string;
+    'Access-Control-Allow-Headers': string;
+};
+/**
+ * Handle OPTIONS preflight request
+ */
+declare function handleOptions(origin?: string): Response;
+
+export { type SessionConfig, corsHeaders, createSessionHandler, getEphemeralKey, handleOptions };

package/dist/server.d.ts

@@ -0,0 +1,80 @@
+export { S as ServerAdapter, g as ServerSessionConfig } from './types-DY31oVB1.js';
+
+/**
+ * Server-side utilities for VoiceKit
+ * Use these in your API routes (Next.js, Express, etc.)
+ *
+ * This module provides the legacy OpenAI-specific helpers.
+ * For provider-agnostic server adapters, import from the adapter entrypoints:
+ *   import { openaiServer } from '@jchaffin/voicekit/openai'
+ *   import { livekitServer } from '@jchaffin/voicekit/livekit'
+ */
+
+interface SessionConfig {
+    /** OpenAI API key (defaults to OPENAI_API_KEY env var) */
+    apiKey?: string;
+    /** Model to use */
+    model?: string;
+    /** Voice ID */
+    voice?: string;
+    /** Instructions for the agent */
+    instructions?: string;
+    /** Expiration time in seconds (default: 600 = 10 minutes) */
+    expiresIn?: number;
+}
+/**
+ * Create an ephemeral session key for OpenAI Realtime API
+ *
+ * @example Next.js App Router
+ * ```ts
+ * // app/api/session/route.ts
+ * import { createSessionHandler } from '@jchaffin/voicekit/server';
+ * export const POST = createSessionHandler();
+ * ```
+ *
+ * @example Next.js with config
+ * ```ts
+ * export const POST = createSessionHandler({
+ *   model: 'gpt-realtime',
+ *   voice: 'alloy'
+ * });
+ * ```
+ */
+declare function createSessionHandler(config?: SessionConfig): (request?: Request) => Promise<Response>;
+/**
+ * Get an ephemeral key directly (for custom server implementations)
+ *
+ * @example Express
+ * ```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 });
+ * });
+ * ```
+ */
+declare function getEphemeralKey(config?: SessionConfig): Promise<{
+    ephemeralKey: string;
+    error?: never;
+} | {
+    ephemeralKey?: never;
+    error: string;
+}>;
+/**
+ * Create CORS headers for API routes
+ */
+declare function corsHeaders(origin?: string): {
+    'Access-Control-Allow-Origin': string;
+    'Access-Control-Allow-Methods': string;
+    'Access-Control-Allow-Headers': string;
+};
+/**
+ * Handle OPTIONS preflight request
+ */
+declare function handleOptions(origin?: string): Response;
+
+export { type SessionConfig, corsHeaders, createSessionHandler, getEphemeralKey, handleOptions };

package/dist/server.js

@@ -0,0 +1,147 @@
+"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/server.ts
+var server_exports = {};
+__export(server_exports, {
+  corsHeaders: () => corsHeaders,
+  createSessionHandler: () => createSessionHandler,
+  getEphemeralKey: () => getEphemeralKey,
+  handleOptions: () => handleOptions
+});
+module.exports = __toCommonJS(server_exports);
+function createSessionHandler(config = {}) {
+  return async function handler(request) {
+    try {
+      const apiKey = config.apiKey || process.env.OPENAI_API_KEY;
+      if (!apiKey) {
+        return Response.json(
+          { error: "OpenAI API key not configured" },
+          { status: 500 }
+        );
+      }
+      const response = await fetch("https://api.openai.com/v1/realtime/client_secrets", {
+        method: "POST",
+        headers: {
+          "Authorization": `Bearer ${apiKey}`,
+          "Content-Type": "application/json"
+        },
+        body: JSON.stringify({
+          expires_after: {
+            anchor: "created_at",
+            seconds: config.expiresIn || 600
+          },
+          session: {
+            type: "realtime",
+            model: config.model || "gpt-realtime",
+            ...config.voice && {
+              audio: {
+                output: { voice: config.voice }
+              }
+            },
+            ...config.instructions && { instructions: config.instructions }
+          }
+        })
+      });
+      if (!response.ok) {
+        const error = await response.text();
+        console.error("OpenAI client_secrets error:", error);
+        return Response.json(
+          { error: `OpenAI API error: ${response.status}` },
+          { status: 500 }
+        );
+      }
+      const data = await response.json();
+      if (!data.value) {
+        return Response.json(
+          { error: "Invalid response from OpenAI" },
+          { status: 500 }
+        );
+      }
+      return Response.json({ ephemeralKey: data.value });
+    } catch (error) {
+      console.error("Session handler error:", error);
+      return Response.json(
+        { error: "Internal server error" },
+        { status: 500 }
+      );
+    }
+  };
+}
+async function getEphemeralKey(config = {}) {
+  try {
+    const apiKey = config.apiKey || process.env.OPENAI_API_KEY;
+    if (!apiKey) {
+      return { error: "OpenAI API key not configured" };
+    }
+    const response = await fetch("https://api.openai.com/v1/realtime/client_secrets", {
+      method: "POST",
+      headers: {
+        "Authorization": `Bearer ${apiKey}`,
+        "Content-Type": "application/json"
+      },
+      body: JSON.stringify({
+        expires_after: {
+          anchor: "created_at",
+          seconds: config.expiresIn || 600
+        },
+        session: {
+          type: "realtime",
+          model: config.model || "gpt-realtime",
+          ...config.voice && {
+            audio: {
+              output: { voice: config.voice }
+            }
+          },
+          ...config.instructions && { instructions: config.instructions }
+        }
+      })
+    });
+    if (!response.ok) {
+      return { error: `OpenAI API error: ${response.status}` };
+    }
+    const data = await response.json();
+    if (!data.value) {
+      return { error: "Invalid response from OpenAI" };
+    }
+    return { ephemeralKey: data.value };
+  } catch (error) {
+    return { error: String(error) };
+  }
+}
+function corsHeaders(origin = "*") {
+  return {
+    "Access-Control-Allow-Origin": origin,
+    "Access-Control-Allow-Methods": "POST, OPTIONS",
+    "Access-Control-Allow-Headers": "Content-Type"
+  };
+}
+function handleOptions(origin = "*") {
+  return new Response(null, {
+    status: 200,
+    headers: corsHeaders(origin)
+  });
+}
+// Annotate the CommonJS export names for ESM import in node:
+0 && (module.exports = {
+  corsHeaders,
+  createSessionHandler,
+  getEphemeralKey,
+  handleOptions
+});

package/dist/server.mjs

@@ -0,0 +1,119 @@
+// src/server.ts
+function createSessionHandler(config = {}) {
+  return async function handler(request) {
+    try {
+      const apiKey = config.apiKey || process.env.OPENAI_API_KEY;
+      if (!apiKey) {
+        return Response.json(
+          { error: "OpenAI API key not configured" },
+          { status: 500 }
+        );
+      }
+      const response = await fetch("https://api.openai.com/v1/realtime/client_secrets", {
+        method: "POST",
+        headers: {
+          "Authorization": `Bearer ${apiKey}`,
+          "Content-Type": "application/json"
+        },
+        body: JSON.stringify({
+          expires_after: {
+            anchor: "created_at",
+            seconds: config.expiresIn || 600
+          },
+          session: {
+            type: "realtime",
+            model: config.model || "gpt-realtime",
+            ...config.voice && {
+              audio: {
+                output: { voice: config.voice }
+              }
+            },
+            ...config.instructions && { instructions: config.instructions }
+          }
+        })
+      });
+      if (!response.ok) {
+        const error = await response.text();
+        console.error("OpenAI client_secrets error:", error);
+        return Response.json(
+          { error: `OpenAI API error: ${response.status}` },
+          { status: 500 }
+        );
+      }
+      const data = await response.json();
+      if (!data.value) {
+        return Response.json(
+          { error: "Invalid response from OpenAI" },
+          { status: 500 }
+        );
+      }
+      return Response.json({ ephemeralKey: data.value });
+    } catch (error) {
+      console.error("Session handler error:", error);
+      return Response.json(
+        { error: "Internal server error" },
+        { status: 500 }
+      );
+    }
+  };
+}
+async function getEphemeralKey(config = {}) {
+  try {
+    const apiKey = config.apiKey || process.env.OPENAI_API_KEY;
+    if (!apiKey) {
+      return { error: "OpenAI API key not configured" };
+    }
+    const response = await fetch("https://api.openai.com/v1/realtime/client_secrets", {
+      method: "POST",
+      headers: {
+        "Authorization": `Bearer ${apiKey}`,
+        "Content-Type": "application/json"
+      },
+      body: JSON.stringify({
+        expires_after: {
+          anchor: "created_at",
+          seconds: config.expiresIn || 600
+        },
+        session: {
+          type: "realtime",
+          model: config.model || "gpt-realtime",
+          ...config.voice && {
+            audio: {
+              output: { voice: config.voice }
+            }
+          },
+          ...config.instructions && { instructions: config.instructions }
+        }
+      })
+    });
+    if (!response.ok) {
+      return { error: `OpenAI API error: ${response.status}` };
+    }
+    const data = await response.json();
+    if (!data.value) {
+      return { error: "Invalid response from OpenAI" };
+    }
+    return { ephemeralKey: data.value };
+  } catch (error) {
+    return { error: String(error) };
+  }
+}
+function corsHeaders(origin = "*") {
+  return {
+    "Access-Control-Allow-Origin": origin,
+    "Access-Control-Allow-Methods": "POST, OPTIONS",
+    "Access-Control-Allow-Headers": "Content-Type"
+  };
+}
+function handleOptions(origin = "*") {
+  return new Response(null, {
+    status: 200,
+    headers: corsHeaders(origin)
+  });
+}
+export {
+  corsHeaders,
+  createSessionHandler,
+  getEphemeralKey,
+  handleOptions
+};

package/dist/types-DY31oVB1.d.mts

@@ -0,0 +1,150 @@
+type VoiceStatus$1 = 'DISCONNECTED' | 'CONNECTING' | 'CONNECTED';
+interface TranscriptMessage {
+    id: string;
+    role: 'user' | 'assistant';
+    text: string;
+    timestamp: Date;
+    status: 'pending' | 'complete';
+}
+type ToolParamType = 'string' | 'number' | 'boolean' | 'array' | 'object';
+interface ToolParamDefinition {
+    type: ToolParamType;
+    description?: string;
+    enum?: string[];
+    default?: unknown;
+}
+interface ToolDefinition<TParams = Record<string, unknown>, TResult = unknown> {
+    name: string;
+    description: string;
+    parameters: {
+        type: 'object';
+        properties: Record<string, ToolParamDefinition>;
+        required?: string[];
+    };
+    execute: (params: TParams) => Promise<TResult> | TResult;
+}
+interface AgentConfig {
+    name: string;
+    instructions: string;
+    tools?: ToolDefinition[];
+    voice?: string;
+}
+interface VoiceConfig {
+    /** API endpoint that returns session token */
+    sessionEndpoint?: string;
+    /** Model identifier (provider-specific) */
+    model?: string;
+    /** Audio codec preference */
+    codec?: 'opus' | 'pcmu' | 'pcma';
+    /** Language for transcription */
+    language?: string;
+    onStatusChange?: (status: VoiceStatus$1) => void;
+    onTranscriptUpdate?: (messages: TranscriptMessage[]) => void;
+    onToolCall?: (toolName: string, params: unknown, result: unknown) => void;
+    onError?: (error: Error) => void;
+}
+interface VoiceProviderProps extends VoiceConfig {
+    /** Provider adapter (e.g. openai(), livekit(), deepgram()) */
+    adapter: VoiceAdapter;
+    /** Agent configuration */
+    agent: VoiceAgentConfig;
+    children: React.ReactNode;
+}
+interface VoiceContextValue {
+    status: VoiceStatus$1;
+    connect: () => Promise<void>;
+    disconnect: () => Promise<void>;
+    transcript: TranscriptMessage[];
+    clearTranscript: () => void;
+    sendMessage: (text: string) => void;
+    interrupt: () => void;
+    mute: (muted: boolean) => void;
+    isMuted: boolean;
+    agent: VoiceAgentConfig;
+}
+
+type VoiceStatus = 'DISCONNECTED' | 'CONNECTING' | 'CONNECTED';
+interface VoiceAgentConfig {
+    name: string;
+    instructions: string;
+    tools?: ToolDefinition[];
+    voice?: string;
+    handoffs?: VoiceAgentConfig[];
+}
+interface SessionEvents {
+    [event: string]: (...args: any[]) => void;
+    status_change: (status: VoiceStatus) => void;
+    user_speech_started: () => void;
+    user_transcript: (data: TranscriptData) => void;
+    assistant_transcript: (data: TranscriptData) => void;
+    tool_call_start: (name: string, input: unknown) => void;
+    tool_call_end: (name: string, input: unknown, output: unknown) => void;
+    agent_handoff: (from: string, to: string) => void;
+    guardrail_tripped: (info: unknown) => void;
+    audio_delta: (itemId: string, delta: string) => void;
+    error: (error: Error) => void;
+    /** Escape hatch for provider-specific events not covered by normalized types */
+    raw_event: (event: unknown) => void;
+}
+interface TranscriptData {
+    itemId: string;
+    delta?: string;
+    text?: string;
+    isFinal: boolean;
+}
+interface VoiceSession {
+    connect(config: ConnectConfig): Promise<void>;
+    disconnect(): Promise<void>;
+    sendMessage(text: string): void | Promise<void>;
+    interrupt(): void;
+    mute(muted: boolean): void;
+    sendRawEvent?(event: Record<string, unknown>): void;
+    on<E extends string & keyof SessionEvents>(event: E, handler: SessionEvents[E]): void;
+    off<E extends string & keyof SessionEvents>(event: E, handler: SessionEvents[E]): void;
+}
+interface ConnectConfig {
+    /** Authentication token/key obtained from server handler */
+    authToken: string;
+    /** HTML audio element for playback */
+    audioElement?: HTMLAudioElement;
+    /** Extra context passed to the session */
+    context?: Record<string, unknown>;
+    /** Output guardrails */
+    outputGuardrails?: unknown[];
+}
+interface SessionOptions {
+    model?: string;
+    language?: string;
+    codec?: string;
+    voice?: string;
+    /** Provider-specific options */
+    [key: string]: unknown;
+}
+interface VoiceAdapter {
+    /** Unique name for this adapter (e.g. 'openai', 'livekit') */
+    readonly name: string;
+    /** Create a session for the given agent */
+    createSession(agent: VoiceAgentConfig, options?: SessionOptions): VoiceSession;
+}
+interface ServerSessionConfig {
+    /** Provider-specific API key */
+    apiKey?: string;
+    model?: string;
+    voice?: string;
+    instructions?: string;
+    expiresIn?: number;
+    /** Provider-specific options */
+    [key: string]: unknown;
+}
+interface ServerAdapter {
+    createSessionHandler(config?: ServerSessionConfig): (request?: Request) => Promise<Response>;
+    getSessionToken(config?: ServerSessionConfig): Promise<{
+        token: string;
+        error?: string;
+    } | {
+        token?: string;
+        error: string;
+    }>;
+}
+
+export type { AgentConfig as A, ConnectConfig as C, ServerAdapter as S, TranscriptMessage as T, VoiceProviderProps as V, VoiceContextValue as a, VoiceAgentConfig as b, ToolDefinition as c, ToolParamDefinition as d, VoiceAdapter as e, VoiceStatus$1 as f, ServerSessionConfig as g, SessionEvents as h, SessionOptions as i, TranscriptData as j, VoiceConfig as k, VoiceSession as l };