@vanira/sdk-react-native 0.0.2

package/src/core/VaniraAI.ts

@@ -0,0 +1,464 @@
+/**
+ * VaniraAI SDK
+ * ============
+ * A simple, developer-friendly Voice AI client.
+ * Hides all WebRTC complexity behind a clean event-emitter API.
+ *
+ * @example
+ * ```ts
+ * const client = new VaniraAI({ agentId: 'your-agent-id', token: 'Bearer your-token' });
+ * client.on('tool_call', ({ name, arguments: args, tool_call_id, execution_mode }) => {
+ *   // render your UI component here
+ *   if (execution_mode === 'blocking') {
+ *     client.sendToolResult(tool_call_id, { success: true });
+ *   }
+ * });
+ * await client.start();
+ * ```
+ */
+
+import { WebRTCClient } from './WebRTCClient';
+import { normalizeToolCallFields } from './toolCallNormalize';
+import {
+    uploadFileByteSize,
+    normalizeUploadMimeForUpload,
+    type UploadMediaInput,
+} from '../adapters/react-native/rnUploadFile';
+
+// ─── Types ───────────────────────────────────────────────────────────────────
+
+export type VaniraAIStatus = 'idle' | 'connecting' | 'connected' | 'disconnected' | 'error';
+
+export interface VaniraAIConfig {
+    /** Your Vanira agent ID from the dashboard */
+    agentId: string;
+    /** Optional prospect ID. If supplied, the SDK resumes the prospect context. */
+    prospectId?: string;
+    /**
+     * Determines the lifecycle behavior when starting a connection:
+     * - 'continue': Reconnects/resumes the call using the provided `callId` or the stored sessionStorage call session.
+     * - 'new' (default): Ignores any previous call state and provisions a brand-new call.
+     */
+    sessionBehavior?: 'continue' | 'new';
+    /** Bearer token for authentication. Required for ICE server fetching. */
+    token?: string;
+    /** Override the WebRTC server URL. Auto-detected if omitted. */
+    serverUrl?: string;
+    /** Override the GraphQL endpoint for config fetching. */
+    graphqlEndpoint?: string;
+    /** Optional: pre-supply your own ICE servers (skips auto-fetch). */
+    iceServers?: RTCIceServer[];
+    /** Optional call ID override. Auto-generated if omitted. */
+    callId?: string;
+    /** Your sk_live_* or pk_live_* API key. Required for client-side call creation. */
+    apiKey?: string;
+    /** Override the default backend URL (e.g. http://localhost:8000). */
+    backendUrl?: string;
+    /** Platform runtime configuration */
+    runtime?: any;
+}
+
+export interface ClientToolCall {
+    /** The ref_code of the triggered action */
+    name: string;
+    /** The mapped payload from client_action_fields */
+    arguments: Record<string, any>;
+    /** Unique ID for this execution. Required when sending a result back for blocking tools. */
+    tool_call_id: string;
+    /** Whether the AI is paused waiting for result ('blocking') or keeps talking ('fire_and_forget') */
+    execution_mode: 'blocking' | 'fire_and_forget';
+    /** Dynamic UI configuration parameters for zero-code presets */
+    client_fields?: Record<string, any>;
+}
+
+export interface TranscriptionEvent {
+    text: string;
+    isFinal: boolean;
+}
+
+type EventMap = {
+    /** Fired when WebRTC connection is fully established */
+    connected: void;
+    /** Fired when the connection is lost or explicitly disconnected */
+    disconnected: void;
+    /** Fired on connection or protocol error. Payload is an error message string. */
+    error: string;
+    /** Fired whenever the AI transcribes speech (both interim and final) */
+    transcription: TranscriptionEvent;
+    /**
+     * Fired when a preset tool call is received (before tool_call).
+     * Raw toolCall shape matches WebRTCClient onPreset callback.
+     */
+    preset: { toolCall: unknown; client: WebRTCClient };
+    /** Fired when the AI triggers a client-side tool (action) */
+    tool_call: ClientToolCall;
+    /** Fired when a remote media track (like video) is received */
+    track: { track: MediaStreamTrack; stream: MediaStream };
+    /** Fired when the prospect and call session are successfully generated/retrieved */
+    session_started: { prospectId: string; callId: string; serverUrl: string };
+};
+
+type EventCallback<T> = T extends void ? () => void : (payload: T) => void;
+
+// ─── VaniraAI Class ────────────────────────────────────────────────────────────
+
+export class VaniraAI {
+    private config: VaniraAIConfig;
+    private _status: VaniraAIStatus = 'idle';
+    private client: WebRTCClient | null = null;
+    private listeners: Map<string, Set<Function>> = new Map();
+
+    constructor(config: VaniraAIConfig) {
+        if (!config.agentId) throw new Error('[VaniraAI] agentId is required');
+        this.config = config;
+    }
+
+    // ─── Getters ─────────────────────────────────────────────────────────────
+
+    /** Returns the active WebRTC worker/server URL */
+    get serverUrl(): string | undefined {
+        return this.client?.serverUrl;
+    }
+
+    /** Returns the active call ID */
+    get callId(): string | undefined {
+        return this.client?.callId;
+    }
+
+    /** Returns the active prospect ID associated with this session */
+    get prospectId(): string | undefined {
+        return this.client?.prospectId;
+    }
+
+    // ─── Status ──────────────────────────────────────────────────────────────
+
+    /** Current connection status */
+    get status(): VaniraAIStatus {
+        return this._status;
+    }
+
+    /** Shorthand: true when status is 'connected' */
+    get isConnected(): boolean {
+        return this._status === 'connected';
+    }
+
+    // ─── Event Emitter ───────────────────────────────────────────────────────
+
+    /**
+     * Register an event listener.
+     * @param event - Event name
+     * @param callback - Handler function
+     * @returns `this` for chaining
+     */
+    on<K extends keyof EventMap>(event: K, callback: EventCallback<EventMap[K]>): this {
+        if (!this.listeners.has(event)) {
+            this.listeners.set(event, new Set());
+        }
+        this.listeners.get(event)!.add(callback);
+        return this;
+    }
+
+    /**
+     * Remove a previously registered event listener.
+     * @param event - Event name
+     * @param callback - The exact same function reference that was registered
+     */
+    off<K extends keyof EventMap>(event: K, callback: EventCallback<EventMap[K]>): this {
+        this.listeners.get(event)?.delete(callback);
+        return this;
+    }
+
+    private emit<K extends keyof EventMap>(event: K, payload?: EventMap[K]): void {
+        this.listeners.get(event)?.forEach(cb => cb(payload));
+    }
+
+    // ─── Lifecycle ───────────────────────────────────────────────────────────
+
+    /**
+     * Connect to the Voice AI agent and start the call.
+     * Requests microphone permission, establishes WebRTC, and opens the data channel.
+     */
+    async start(): Promise<{ callId: string; prospectId: string; serverUrl: string }> {
+        if (this._status === 'connecting' || this._status === 'connected') {
+            console.warn('[VaniraAI] Already connecting or connected. Call stop() first.');
+            return {
+                callId: this.callId || '',
+                prospectId: this.prospectId || '',
+                serverUrl: this.serverUrl || '',
+            };
+        }
+
+        this._setStatus('connecting');
+
+        const serverUrl = this.config.serverUrl || (this.config.apiKey ? '' : this._inferServerUrl());
+
+        try {
+            this.client = new WebRTCClient({
+                serverUrl,
+                agentId: this.config.agentId,
+                callId: this.config.callId,
+                prospectId: this.config.prospectId,
+                sessionBehavior: this.config.sessionBehavior,
+                token: this.config.token,
+                apiKey: this.config.apiKey,
+                backendUrl: this.config.backendUrl,
+                iceServers: this.config.iceServers,
+                runtime: this.config.runtime,
+                onSessionStarted: (payload) => {
+                    this.emit('session_started', payload);
+                },
+                onConnected: () => {
+                    this._setStatus('connected');
+                    this.emit('connected');
+                },
+                onDisconnected: () => {
+                    this._setStatus('disconnected');
+                    this.emit('disconnected');
+                },
+                onError: (err: any) => {
+                    this._setStatus('error');
+                    this.emit('error', typeof err === 'string' ? err : (err?.message || 'Connection failed'));
+                },
+                onTranscription: (text: string, isFinal: boolean) => {
+                    this.emit('transcription', { text, isFinal });
+                },
+                onPreset: (payload) => {
+                    this.emit('preset', payload);
+                },
+                // @ts-ignore - onClientToolCall is on the dashboard's WebRTCClient; proxy it here
+                onClientToolCall: (rawCall: any) => {
+                    const normalized = normalizeToolCallFields(rawCall);
+                    const toolCall: ClientToolCall = {
+                        name: normalized.name,
+                        arguments: normalized.arguments,
+                        tool_call_id: normalized.tool_call_id,
+                        execution_mode: normalized.execution_mode as ClientToolCall['execution_mode'],
+                        client_fields: normalized.client_fields,
+                    };
+                    this.emit('tool_call', toolCall);
+                },
+                // @ts-ignore - onRemoteTrack is on the dashboard's WebRTCClient; proxy it here
+                onRemoteTrack: (track: MediaStreamTrack, stream: MediaStream) => {
+                    this.emit('track', { track, stream });
+                }
+            });
+
+            await this.client.connect();
+
+            return {
+                callId: this.callId || '',
+                prospectId: this.prospectId || '',
+                serverUrl: this.serverUrl || '',
+            };
+        } catch (err: any) {
+            this._setStatus('error');
+            this.emit('error', err?.message || 'Failed to start call');
+            throw err;
+        }
+    }
+
+    /**
+     * Disconnect the call and release all resources (microphone, WebRTC connection).
+     */
+    stop(): void {
+        if (this.client) {
+            this.client.disconnect();
+            this.client = null;
+        }
+        this._setStatus('disconnected');
+    }
+
+    /** Mute or unmute your microphone while the call stays connected. */
+    setMicrophoneMuted(muted: boolean): void {
+        this.client?.setMicrophoneMuted(muted);
+    }
+
+    isMicrophoneMuted(): boolean {
+        return this.client?.isMicrophoneMuted() ?? false;
+    }
+
+    // ─── Client → Server Actions ─────────────────────────────────────────────
+
+    /**
+     * Send the result of a **blocking** client-side tool back to the AI.
+     * The AI is paused and will resume once it receives this.
+     *
+     * @param toolCallId - The `tool_call_id` from the `tool_call` event
+     * @param result - Arbitrary JSON payload the AI needs to continue
+     *
+     * @example
+     * client.sendToolResult(tool_call_id, { selected_store: 'Store #5' });
+     */
+    sendToolResult(toolCallId: string, result: Record<string, any>): void {
+        this._assertConnected('sendToolResult');
+        this.client!.sendToolResult(toolCallId, result);
+    }
+
+    /**
+     * Send an error result for a **blocking** client-side tool.
+     * Use when the user cancelled or the UI crashed.
+     *
+     * @param toolCallId - The `tool_call_id` from the `tool_call` event
+     * @param errorMessage - Human-readable error description
+     */
+    sendToolError(toolCallId: string, errorMessage: string): void {
+        this._assertConnected('sendToolError');
+        // Fallback: use the generic sendEvent until SDK's WebRTCClient is fully updated
+        this.client!.sendEvent('client_tool_result', {
+            call_id: toolCallId,
+            result: { status: 'error', error: errorMessage }
+        });
+    }
+
+    /**
+     * Silently update the AI's context with what the user is currently doing on screen.
+     * Does NOT interrupt the AI's current speech.
+     *
+     * @example
+     * client.updateContext({ active_page: 'Checkout', item: 'Nike Shoes', price: 149.99 });
+     */
+    updateContext(context: Record<string, any>): void {
+        this._assertConnected('updateContext');
+        this.client!.sendContextUpdate(context);
+    }
+
+    /**
+     * Force the AI to stop speaking and immediately react to a UI event.
+     * Use when the user performs a significant action (e.g., clicks a button, opens a page).
+     *
+     * Do NOT call this after `uploadMedia()` — `uploadMedia()` already sends
+     * `client_media_update` which is the only notification the backend needs.
+     * Calling `triggerInterrupt` after an upload causes double-TTS.
+     *
+     * @param actionName - A descriptive name for the action (e.g., 'user_clicked_cart')
+     * @param data - Optional context about the action
+     *
+     * @example
+     * client.triggerInterrupt('user_opened_checkout', { cart_value: 299 });
+     */
+    triggerInterrupt(actionName: string, data: Record<string, any> = {}): void {
+        this._assertConnected('triggerInterrupt');
+        this.client!.triggerActionInterrupt();
+        this.client!.sendActionTrigger(actionName, data);
+    }
+
+    /**
+     * Cut the AI's current audio mid-sentence WITHOUT sending a client_action_trigger.
+     * Use this when you want to interrupt the agent but the next notification will be
+     * sent by the SDK itself (e.g. right before `uploadMedia()`).
+     */
+    interruptAudioOnly(): void {
+        this._assertConnected('interruptAudioOnly');
+        this.client!.triggerActionInterrupt();
+    }
+
+    /**
+     * Send a raw DataChannel event to the server.
+     * Used for protocol-level signals that don't have a higher-level API method
+     * (e.g. `client_live_camera_started`, `client_media_frame`, `client_live_camera_stopped`).
+     *
+     * @param event - Event name string
+     * @param data  - Optional payload merged into the DataChannel message
+     */
+    sendEvent(event: string, data: Record<string, any> = {}): void {
+        this._assertConnected('sendEvent');
+        this.client!.sendEvent(event, data);
+    }
+
+    /**
+     * Observe inbound DataChannel control events (preset harness / debugging).
+     * Install after `start()` resolves. Returns false if the WebRTC client is missing.
+     */
+    tapControlEvents(handler: (event: string, msg: Record<string, unknown>) => void): boolean {
+        if (!this.client) {
+            return false;
+        }
+        return this.client.tapControlEvents((msg) => {
+            handler(String(msg.event ?? 'unknown'), msg as Record<string, unknown>);
+        });
+    }
+
+    /** Harness-only: inject a synthetic inbound DataChannel event (e.g. client_tool_call). */
+    injectControlEvent(msg: Record<string, unknown>): void {
+        this._assertConnected('injectControlEvent');
+        this.client!.injectControlEvent(msg as import('../types').ControlEvent);
+    }
+
+    /**
+     * Upload a file (photo, document, screenshot) to the AI agent during a live call.
+     * Handles the HTTP upload and DataChannel notification automatically.
+     *
+     * ⚠️  This method is SELF-CONTAINED:
+     *   1. POSTs the file to /media/upload
+     *   2. Sends `client_media_update` via the DataChannel
+     *
+     * The backend LLM receives `client_media_update` and calls `process_media` — NO
+     * additional `triggerInterrupt()` or `sendActionTrigger()` is needed.
+     * Calling those after `uploadMedia()` will cause a SECOND LLM response (double TTS).
+     *
+     * @param file            - File or Blob to upload (JPEG, PNG, GIF, WebP, PDF — max 50 MB)
+     * @param reason          - Routing key: 'general' | 'kyc_photo' | 'damage_photo' | 'selfie' | 'document' | 'screenshot'
+     * @param message         - Optional text the user wants to say about the file
+     * @param interruptFirst  - Pass `true` to cut the AI's current audio before uploading
+     *                          (sends `action_interrupt` only — NOT `client_action_trigger`)
+     * @returns               `{ media_id, url }` on success
+     *
+     * @example
+     * // Correct — one event, full context, LLM gets everything:
+     * const result = await client.uploadMedia(file, 'person_verification', 'Here is my ID', true);
+     *
+     * // ❌ Wrong — causes double TTS:
+     * const result = await client.uploadMedia(file, 'person_verification');
+     * client.triggerInterrupt('media_uploaded', { url: result.url }); // don't do this
+     */
+    async uploadMedia(
+        file: UploadMediaInput,
+        reason: string = 'general',
+        message: string = '',
+        interruptFirst: boolean = false
+    ): Promise<{ media_id: string; url: string; content_type?: string }> {
+        this._assertConnected('uploadMedia');
+
+        // Optionally cut the AI's current audio — audio-only, no action_trigger
+        if (interruptFirst) {
+            this.client!.triggerActionInterrupt();
+        }
+
+        // Client-side validation — 50 MB limit
+        const MAX_SIZE = 50 * 1024 * 1024;
+        const byteSize = uploadFileByteSize(file);
+        if (byteSize !== undefined && byteSize > MAX_SIZE) {
+            throw new Error(`Upload failed: file is too large (${(byteSize / 1024 / 1024).toFixed(1)} MB). Maximum is 50 MB.`);
+        }
+
+        // Supported MIME types — parity with web upload preset accept string
+        const SUPPORTED_TYPES = [
+            'image/jpeg', 'image/png', 'image/gif', 'image/webp', 'image/bmp',
+            'application/pdf', 'text/plain', 'text/csv',
+        ];
+        const mimeType = normalizeUploadMimeForUpload(file);
+        if (mimeType && !SUPPORTED_TYPES.includes(mimeType)) {
+            throw new Error(`Upload failed: unsupported file type '${mimeType}'. Supported: JPEG, JPG, PNG, GIF, WebP, BMP, PDF, TXT, CSV.`);
+        }
+
+        // uploadMedia() in WebRTCClient uploads the file and sends client_media_update
+        // via the DataChannel. That single event is everything the backend needs.
+        return this.client!.uploadMedia(file, reason, message);
+    }
+
+    // ─── Private helpers ─────────────────────────────────────────────────────
+
+    private _setStatus(status: VaniraAIStatus): void {
+        this._status = status;
+    }
+
+    private _inferServerUrl(): string {
+        return 'https://in-godspeed.travelr.club';
+      }
+
+    private _assertConnected(method: string): void {
+        if (!this.client || !this.isConnected) {
+            throw new Error(`[VaniraAI] Cannot call ${method}() when not connected. Call start() first.`);
+        }
+    }
+}