avin-ai 0.1.10 → 0.2.0

package/dist/index.d.ts

@@ -2,6 +2,117 @@ export declare interface Agent {
     tts_voice?: TTSVoice;
 }
 
+export declare class AvinAI {
+    private config;
+    private _status;
+    private client;
+    private listeners;
+    constructor(config: AvinAIConfig);
+    /** Current connection status */
+    get status(): AvinAIStatus;
+    /** Shorthand: true when status is 'connected' */
+    get isConnected(): boolean;
+    /**
+     * 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;
+    /**
+     * 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;
+    private emit;
+    /**
+     * Connect to the Voice AI agent and start the call.
+     * Requests microphone permission, establishes WebRTC, and opens the data channel.
+     */
+    start(): Promise<void>;
+    /**
+     * Disconnect the call and release all resources (microphone, WebRTC connection).
+     */
+    stop(): void;
+    /**
+     * 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;
+    /**
+     * 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;
+    /**
+     * 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;
+    /**
+     * 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).
+     *
+     * @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;
+    private _setStatus;
+    private _inferServerUrl;
+    private _assertConnected;
+}
+
+export declare interface AvinAIConfig {
+    /** Your Ovin agent ID from the dashboard */
+    agentId: string;
+    /** 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;
+}
+
+/**
+ * AvinAI SDK
+ * ============
+ * A simple, developer-friendly Voice AI client.
+ * Hides all WebRTC complexity behind a clean event-emitter API.
+ *
+ * @example
+ * ```ts
+ * const client = new AvinAI({ 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();
+ * ```
+ */
+export declare type AvinAIStatus = 'idle' | 'connecting' | 'connected' | 'disconnected' | 'error';
+
 export declare class AvinWidget extends HTMLElement {
     private shadow;
     private provider;
@@ -29,12 +140,27 @@ declare interface ChatMessage {
 }
 
 export declare class ChatService {
+    static setChatUrl(url: string): void;
     static createChatProspect(prospectGroupId: string): Promise<string>;
-    static fetchWelcomeMessage(agentId: string, prospectId: string): Promise<ChatMessage | null>;
+    static fetchWelcomeMessage(agentId: string, prospectId: string): Promise<ChatMessage & {
+        chatId?: string;
+    }>;
     static sendChatMessage(agentId: string, prospectId: string, message: string, chatId: string | null, onChunk: (text: string) => void, onWidget: (widget: any) => void, onDone: (newChatId: string | null) => void): Promise<void>;
+    static listenForAdminReplies(inboxId: string, sender: string, onMessage: (content: string) => void): EventSource;
     static createCall(agentId: string, prospectId: string | null, widgetMode: string): Promise<string>;
 }
 
+export declare 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';
+}
+
 export declare class ConfigService {
     static fetchWidgetConfig(widgetId: string): Promise<WidgetConfig>;
 }
@@ -44,6 +170,28 @@ export declare interface ControlEvent {
     text?: string;
     isFinal?: boolean;
     name?: string;
+    tool_call?: any;
+    data?: any;
+}
+
+declare type EventCallback<T> = T extends void ? () => void : (payload: T) => void;
+
+declare 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 the AI triggers a client-side tool (action) */
+    tool_call: ClientToolCall;
+};
+
+export declare interface TranscriptionEvent {
+    text: string;
+    isFinal: boolean;
 }
 
 export declare interface TTSProvider {
@@ -64,6 +212,7 @@ export declare class WebRTCClient {
     private onError;
     private onTranscription;
     private onRemoteTrack;
+    private onClientToolCall;
     private pc;
     private dataChannel;
     private audioElement;
@@ -95,6 +244,20 @@ export declare class WebRTCClient {
      * Generate unique call ID
      */
     generateCallId(): string;
+    /**
+     * Send client-side tool execution result back to the AI server.
+     * Use this to unblock a 'blocking' execution mode tool.
+     */
+    sendToolResult(callId: string, result: any): void;
+    /**
+     * Silently update the AI's context with what the user is currently viewing.
+     * Does NOT interrupt the AI's current speech.
+     */
+    sendSilentContext(context: string): void;
+    /**
+     * Trigger a client-side interrupt — cuts AI audio and forces it to react to a UI event.
+     */
+    triggerActionInterrupt(): void;
     /**
      * Static helper to fetch ICE servers from Hasura
      */
@@ -110,6 +273,7 @@ export declare interface WebRTCClientConfig {
     onError?: (error: any) => void;
     onTranscription?: (text: string, isFinal: boolean) => void;
     onRemoteTrack?: (track: MediaStreamTrack, stream: MediaStream) => void;
+    onClientToolCall?: (toolCall: any) => void;
     iceServers?: RTCIceServer[];
     token?: string;
 }

package/package.json

@@ -1,7 +1,23 @@
 {
     "name": "avin-ai",
-    "version": "0.1.10",
-    "description": "AvinAI Voice Widget SDK",
+    "version": "0.2.0",
+    "description": "AvinAI Voice & Chat Widget SDK — embed conversational AI into any website with one script tag",
+    "author": "AvinAI <dev@avin.ai>",
+    "license": "MIT",
+    "homepage": "https://avin.ai",
+    "keywords": [
+        "voice-ai",
+        "chatbot",
+        "widget",
+        "sdk",
+        "webrtc",
+        "ai-assistant",
+        "avin"
+    ],
+    "repository": {
+        "type": "git",
+        "url": "https://github.com/avin-ai/sdk"
+    },
     "type": "module",
     "main": "./dist/avin-ai.umd.js",
     "module": "./dist/avin-ai.es.js",