@keyframelabs/elements 0.0.2 → 0.0.4

package/README.md

@@ -2,7 +2,7 @@
 
 Headless vanilla TypeScript library for embedding Persona avatars. Handles video/audio elements, session wiring, microphone input, and voice agent connections.
 
-No UI included — that's your job (or use `@keyframelabs/components-react`).
+No UI included — see `@keyframelabs/components-react` for a React example.
 
 ## Install
 
@@ -12,6 +12,13 @@ pnpm add @keyframelabs/elements
 
 ## Usage
 
+Two classes are available depending on your integration:
+
+- **`PersonaEmbed`** — Fully managed KFL embed workflow. Uses a publishable key to handle authentication and session creation automatically.
+- **`PersonaView`** — Bring Your Own Backend (BYOB). Accepts pre-fetched session/agent details from your own backend.
+
+### PersonaEmbed (Publishable Key)
+
 ```ts
 import { PersonaEmbed } from '@keyframelabs/elements';
 
@@ -32,11 +39,45 @@ embed.toggleMute();
 embed.disconnect();
 ```
 
+### PersonaView (Bring Your Own Backend)
+
+Use this when you want to manage authentication through your own backend.
+
+First, fetch session details from your backend:
+
+```ts
+const response = await fetch('/api/persona/session', { method: 'POST' });
+const { sessionDetails, voiceAgentDetails } = await response.json();
+```
+
+Then pass them to PersonaView:
+
+```ts
+import { PersonaView } from '@keyframelabs/elements';
+
+const view = new PersonaView({
+  container: document.getElementById('avatar')!,
+  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();
+
+// Later...
+view.toggleMute();
+view.disconnect();
+```
+
 ## API
 
-Create your embed config at platform.keyframelabs.com to get a publishable key.
+### `PersonaEmbed` (Fully Managed)
 
-### `PersonaEmbed`
+Create your embed config at platform.keyframelabs.com to get a publishable key. KFL handles session creation, authentication, and agent configuration.
 
 #### Constructor Options
 
@@ -69,8 +110,46 @@ Create your embed config at platform.keyframelabs.com to get a publishable key.
 | `disconnect()` | Disconnect and cleanup |
 | `toggleMute()` | Toggle microphone mute |
 
+### `PersonaView` (BYOB)
+
+For self-hosted backends that manage their own session creation and authentication.
+
+#### Constructor Options
+
+| Option | Type | Default | Description |
+|--------|------|---------|-------------|
+| `container` | `HTMLElement` | required | Target container for video/audio elements |
+| `sessionDetails` | `SessionDetails` | required | Session config from your backend |
+| `voiceAgentDetails` | `VoiceAgentDetails` | required | Voice agent config from your backend |
+| `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 |
+
+#### 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
+};
+```
+
+#### Properties & Methods
+
+Same as `PersonaEmbed` (see above).
+
 ## Voice Agents
 
-Supports Gemini Live, ElevenLabs, and Cartesia agents. The agent type is determined by your embed config.
+Supports Gemini Live, ElevenLabs, and Cartesia agents. The agent type is determined by your embed config or `voiceAgentDetails.type`.
 
 If you need support for new voice agent platforms built in, drop us a line at support@keyframelabs.com

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';