@keyframelabs/elements 0.0.3 → 0.0.5

package/README.md

@@ -1,8 +1,14 @@
 # @keyframelabs/elements
 
-Headless vanilla TypeScript library for embedding Persona avatars. Handles video/audio elements, session wiring, microphone input, and voice agent connections.
+Framework-agnostic primitives for Keyframe Labs.
 
-No UI included — that's your job (or use `@keyframelabs/components-react`).
+**Which package should I use?**
+- **@keyframelabs/sdk** (high control)
+  - You implement the UI, state management, and agent/llm binding yourself
+- **@keyframelabs/elements** (custom UI)
+  - You implement the UI; we handle the state and agent/llm binding (framework-agnostic)
+- **@keyframelabs/react**: (drop-in)
+  - We handle the UI, state, and agent/llm binding
 
 ## Install
 
@@ -12,13 +18,21 @@ pnpm add @keyframelabs/elements
 
 ## Usage
 
+This package provides two primary classes depending on your integration strategy:
+1. **`PersonaEmbed`**: Fully managed. Uses a publishable key. Best for rapid frontend integration.
+2. **`PersonaView`**: Bring your own backend. Uses session tokens generated by your server.
+
+### Option A: PersonaEmbed (managed)
+
+Use this if you have configured an embed in the Keyframe platform dashboard.
+
 ```ts
 import { PersonaEmbed } from '@keyframelabs/elements';
 
 const embed = new PersonaEmbed({
-  container: document.getElementById('avatar')!,
+  container: document.getElementById('persona-container'),
   publishableKey: 'kfl_pk_live_...',
-  videoFit: 'contain', // 'cover' (default) or 'contain'
+  videoFit: 'cover',
   onStateChange: (status) => console.log('Status:', status),
   onAgentStateChange: (state) => console.log('Agent:', state),
   onDisconnect: () => console.log('Disconnected'),
@@ -28,49 +42,116 @@ const embed = new PersonaEmbed({
 await embed.connect();
 
 // Later...
-embed.toggleMute();
 embed.disconnect();
 ```
 
-## API
+### Option B: PersonaView (bring your own backend)
+
+Use this when you want to manage authentication through your own backend.
+
+```ts
+import { PersonaView } from '@keyframelabs/elements';
+
+const view = new PersonaView({
+  container: document.getElementById('persona-container')!,
+  sessionDetails,
+  voiceAgentDetails,
+  videoFit: 'contain',
+  onStateChange: (status) => console.log('Status:', status),
+  onAgentStateChange: (state) => console.log('Agent:', state),
+  onDisconnect: () => console.log('Disconnected'),
+  onError: (err) => console.error(err),
+});
+
+await view.connect();
 
-Create your embed config at platform.keyframelabs.com to get a publishable key.
+// Later...
+view.disconnect();
+```
+
+## Supported agents and real-time LLMs
+
+Supports ElevenLabs Agents, Cartesia Line, and Gemini Live.
+
+For `PersonaEmbed`, this is determined by the values you set in the Keyframe platform dashboard.
+
+For `PersonaView`, this is determined by `voiceAgentDetails`.
+
+## API
 
 ### `PersonaEmbed`
 
-#### Constructor Options
+#### Options
 
-| Option | Type | Default | Description |
-|--------|------|---------|-------------|
-| `container` | `HTMLElement` | required | Target container for video/audio elements |
-| `publishableKey` | `string` | required | Your embed config publishable key |
-| `apiBaseUrl` | `string` | production | API endpoint |
-| `videoFit` | `'cover' \| 'contain'` | `'cover'` | Video scaling mode |
-| `onStateChange` | `(status: EmbedStatus) => void` | - | Status callback |
-| `onAgentStateChange` | `(state: AgentState) => void` | - | Agent state callback |
-| `onDisconnect` | `() => void` | - | Disconnect callback |
-| `onError` | `(err: Error) => void` | - | Error callback |
+| Option               | Type                            | Default                          | Description                                    |
+| -------------------- | ------------------------------- | -------------------------------- | ---------------------------------------------- |
+| `container`          | `HTMLElement`                   | Required                         | Target container for video and audio elements. |
+| `publishableKey`     | `string`                        | Required                         | Your publishable embed key.                    |
+| `apiBaseUrl`         | `string`                        | `'https://api.keyframelabs.com'` | Base URL for the Keyframe API.                 |
+| `videoFit`           | `'cover' \| 'contain'`          | `'cover'`                        | Video scaling mode (`object-fit`).             |
+| `onStateChange`      | `(status: EmbedStatus) => void` | —                                | Fired when connection status changes.          |
+| `onAgentStateChange` | `(state: AgentState) => void`   | —                                | Fired when agent state changes.                |
+| `onDisconnect`       | `() => void`                    | —                                | Fired when the session disconnects.            |
+| `onError`            | `(err: Error) => void`          | —                                | Fired on fatal errors.                         |
+
+#### Methods
+
+| Method       | Signature             | Description                                        |
+| ------------ | --------------------- | -------------------------------------------------- |
+| `connect`    | `() => Promise<void>` | Starts the session and establishes the connection. |
+| `disconnect` | `() => void`          | Disconnects the session and cleans up resources.   |
+| `toggleMute` | `() => void`          | Toggles the user's microphone mute state.          |
 
 #### Properties
 
-| Property | Type | Description |
-|----------|------|-------------|
-| `status` | `EmbedStatus` | `'connecting' \| 'connected' \| 'error' \| 'disconnected'` |
-| `agentState` | `AgentState` | `'idle' \| 'listening' \| 'thinking' \| 'speaking'` |
-| `isMuted` | `boolean` | Microphone mute state |
-| `videoElement` | `HTMLVideoElement` | The video element |
-| `audioElement` | `HTMLAudioElement` | The audio element |
+| Property       | Type               | Description                                                                            |
+| -------------- | ------------------ | -------------------------------------------------------------------------------------- |
+| `status`       | `EmbedStatus`      | Current connection status: `'connecting' \| 'connected' \| 'disconnected' \| 'error'`. |
+| `agentState`   | `AgentState`       | Current agent state: `'idle' \| 'listening' \| 'thinking' \| 'speaking'`.              |
+| `isMuted`      | `boolean`          | Whether the microphone is currently muted.                                             |
+| `videoElement` | `HTMLVideoElement` | The underlying video element used for rendering.                                       |
+| `audioElement` | `HTMLAudioElement` | The underlying audio element used for playback.                                        |
+
+### `PersonaView`
+
+#### Options
+
+| Option               | Type                            | Default   | Description                                    |
+| -------------------- | ------------------------------- | --------- | ---------------------------------------------- |
+| `container`          | `HTMLElement`                   | Required  | Target container for video and audio elements. |
+| `sessionDetails`     | `SessionDetails`                | Required  | Session configuration from your backend.       |
+| `voiceAgentDetails`  | `VoiceAgentDetails`             | Required  | Voice agent configuration from your backend.   |
+| `videoFit`           | `'cover' \| 'contain'`          | `'cover'` | Video scaling mode (`object-fit`).             |
+| `onStateChange`      | `(status: EmbedStatus) => void` | —         | Fired when connection status changes.          |
+| `onAgentStateChange` | `(state: AgentState) => void`   | —         | Fired when agent state changes.                |
+| `onDisconnect`       | `() => void`                    | —         | Fired when the session disconnects.            |
+| `onError`            | `(err: Error) => void`          | —         | Fired on fatal errors.                         |
 
 #### Methods
 
-| Method | Description |
-|--------|-------------|
-| `connect()` | Connect to session (async) |
-| `disconnect()` | Disconnect and cleanup |
-| `toggleMute()` | Toggle microphone mute |
+Same as `PersonaEmbed`.
+
+#### Properties
+
+Same as `PersonaEmbed`.
 
-## Voice Agents
+#### Types
+
+```ts
+type SessionDetails = {
+  server_url: string;
+  participant_token: string;
+  agent_identity: string;
+};
+
+type VoiceAgentDetails = {
+  type: 'gemini' | 'elevenlabs' | 'cartesia';
+  token?: string;       // For gemini, cartesia
+  agent_id?: string;    // For elevenlabs, cartesia
+  signed_url?: string;  // For elevenlabs
+};
+```
 
-Supports Gemini Live, ElevenLabs, and Cartesia agents. The agent type is determined by your embed config.
+## License
 
-If you need support for new voice agent platforms built in, drop us a line at support@keyframelabs.com
+MIT

package/dist/ApiError.d.ts

@@ -0,0 +1,20 @@
+export type ApiErrorPayload = {
+    code?: string;
+    message?: string;
+    details?: unknown;
+};
+export declare class ApiError extends Error {
+    status: number;
+    payload?: ApiErrorPayload;
+    url?: string;
+    constructor(opts: {
+        message: string;
+        status: number;
+        payload?: ApiErrorPayload;
+        url?: string;
+    });
+}
+export type ApiErrorResponse = {
+    detail?: ApiErrorPayload | string;
+};
+export declare function normalizeFastApiPayload(x: ApiErrorResponse | null): ApiErrorPayload | undefined;

package/dist/PersonaEmbed.d.ts

@@ -1,7 +1,7 @@
 import { AgentState } from './agents';
-export type EmbedStatus = 'connecting' | 'connected' | 'error' | 'disconnected';
-export type VideoFit = 'cover' | 'contain';
-export interface PersonaEmbedOptions {
+import { EmbedStatus, VideoFit, BaseCallbacks } from './types';
+export type { EmbedStatus, VideoFit } from './types';
+export interface PersonaEmbedOptions extends BaseCallbacks {
     /** Target container element */
     container: HTMLElement;
     /** Publishable key from your embed config */
@@ -10,14 +10,6 @@ export interface PersonaEmbedOptions {
     apiBaseUrl?: string;
     /** Video fit mode. 'cover' fills container (may crop), 'contain' shows full video (may have black bars). Default: 'cover' */
     videoFit?: VideoFit;
-    /** Called when session disconnects */
-    onDisconnect?: () => void;
-    /** Called on error */
-    onError?: (err: Error) => void;
-    /** Called when status changes */
-    onStateChange?: (status: EmbedStatus) => void;
-    /** Called when agent state changes */
-    onAgentStateChange?: (state: AgentState) => void;
 }
 /**
  * Headless Persona avatar with voice agent integration.

package/dist/PersonaView.d.ts

@@ -0,0 +1,67 @@
+import { AgentState } from './agents';
+import { EmbedStatus, VideoFit, VoiceAgentDetails, SessionDetails, BaseCallbacks } from './types';
+export interface PersonaViewOptions extends BaseCallbacks {
+    /** Target container element */
+    container: HTMLElement;
+    /** Voice agent configuration from your backend */
+    voiceAgentDetails: VoiceAgentDetails;
+    /** Session configuration from your backend */
+    sessionDetails: SessionDetails;
+    /** Video fit mode. 'cover' fills container (may crop), 'contain' shows full video (may have black bars). Default: 'cover' */
+    videoFit?: VideoFit;
+}
+/**
+ * Headless Persona avatar with voice agent integration (BYOB mode).
+ *
+ * Creates video/audio elements and handles all wiring.
+ * UI (overlays, controls, status) is the consumer's responsibility.
+ *
+ * @example
+ * ```ts
+ * // Fetch session details from your own backend
+ * const { sessionDetails, voiceAgentDetails } = await myBackend.createSession();
+ *
+ * const view = new PersonaView({
+ *   container: document.getElementById('avatar'),
+ *   sessionDetails,
+ *   voiceAgentDetails,
+ *   onStateChange: (status) => updateUI(status),
+ * });
+ * await view.connect();
+ * ```
+ */
+export declare class PersonaView {
+    private readonly voiceAgentDetails;
+    private readonly sessionDetails;
+    private readonly callbacks;
+    private readonly connectionId;
+    private readonly _video;
+    private readonly _audio;
+    private session;
+    private agent;
+    private audioContext;
+    private processor;
+    private stream;
+    private _status;
+    private _agentState;
+    private _isMuted;
+    private mounted;
+    constructor(options: PersonaViewOptions);
+    get status(): EmbedStatus;
+    get agentState(): AgentState;
+    get isMuted(): boolean;
+    get videoElement(): HTMLVideoElement;
+    get audioElement(): HTMLAudioElement;
+    /** Connect to the session */
+    connect(): Promise<void>;
+    /** Disconnect and cleanup */
+    disconnect(): void;
+    /** Toggle microphone mute */
+    toggleMute(): void;
+    private setStatus;
+    private setAgentState;
+    private initSession;
+    private initMicrophone;
+    private connectAgent;
+    private cleanup;
+}

package/dist/index.d.ts

@@ -1,5 +1,10 @@
 export { PersonaEmbed } from './PersonaEmbed';
-export type { PersonaEmbedOptions, EmbedStatus, VideoFit } from './PersonaEmbed';
+export type { PersonaEmbedOptions } from './PersonaEmbed';
+export { PersonaView } from './PersonaView';
+export type { PersonaViewOptions } from './PersonaView';
+export type { EmbedStatus, VideoFit, VoiceAgentDetails, SessionDetails, BaseCallbacks, } from './types';
 export { createAgent, GeminiLiveAgent, ElevenLabsAgent, CartesiaAgent, BaseAgent, AGENT_REGISTRY, getAgentInfo, } from './agents';
 export type { AgentType, AgentState, AgentConfig, AgentEventMap, Agent, AnyAgent, AgentTypeInfo, GeminiLiveConfig, ElevenLabsConfig, CartesiaConfig, } from './agents';
 export { floatTo16BitPCM, resamplePcm, base64ToBytes, bytesToBase64, SAMPLE_RATE, createEventEmitter, } from './agents';
+export { ApiError as KeyframeApiError } from './ApiError';
+export type { ApiErrorPayload as KeyframeApiErrorPayload } from './ApiError';