@vogent/vogent-web-client 0.0.3 → 0.0.5

package/VogentCall.ts

@@ -1,3 +1,45 @@
+/**
+ * @fileoverview VogentCall provides the main interface for managing voice calls with Vogent's AI system.
+ *
+ * This class handles:
+ * - Call lifecycle management (start, pause, hangup)
+ * - Audio connection setup
+ * - Real-time transcript monitoring
+ * - Status event handling
+ *
+ * Basic usage:
+ * ```typescript
+ * const call = new VogentCall({
+ *   sessionId: "session_id",
+ *   dialId: "dial_id",
+ *   token: "auth_token"
+ * });
+ *
+ * // Start the call
+ * await call.start();
+ *
+ * // Connect audio
+ * const audioConn = await call.connectAudio();
+ *
+ * // Monitor transcripts
+ * const unsubscribe = call.monitorTranscript((transcript) => {
+ *   console.log(transcript);
+ * });
+ *
+ * // Monitor status changes
+ * call.on('status', (status) => {
+ *   console.log('Call status:', status);
+ * });
+ *
+ * // Later: cleanup
+ * unsubscribe();
+ * await call.hangup();
+ * ```
+ *
+ * @see {@link https://docs.vogent.ai} for complete server documentation
+ * @module VogentCall
+ */
+
 import { ApolloClient, createHttpLink, InMemoryCache, NormalizedCacheObject, split } from '@apollo/client';
 import { setContext } from '@apollo/client/link/context';
 import { GraphQLWsLink } from '@apollo/client/link/subscriptions';
@@ -17,27 +59,54 @@ import {
   REFRESH_TRANSCRIPT,
 } from './queries';
 import { createClient } from 'graphql-ws';
-import { VogentDevice } from './devices/VogentDevice';
+import { VogentAudioConn, VogentDevice } from './devices/VogentDevice';
 import { VonageDevice } from './devices/VonageDevice';
 import { dialStatusIsComplete } from './utils';
 
 export type Transcript = {
+  /** The text of the transcript */
   text: string;
+  /** The speaker of the transcript currently either 'HUMAN' or 'AI', or 'IVR' if IVR detection is enabled */
   speaker: string;
 }[]
 
+/**
+ * VogentCall manages the lifecycle and state of a voice call session
+ */
 export class VogentCall {
-  client: ApolloClient<NormalizedCacheObject>;
-  sessionId: string;
-  dialId: string;
-  subscription?: ObservableSubscription;
-  baseUrl: string;
-  dial?: Dial;
-  _handlers: {
+  /** Apollo GraphQL client instance for API communication */
+  private client: ApolloClient<NormalizedCacheObject>;
+
+  /** Unique identifier for the current session */
+  private sessionId: string;
+
+  /** Unique identifier for the current dial/call */
+  private dialId: string;
+
+  /** GraphQL subscription handle */
+  private subscription?: ObservableSubscription;
+
+  /** Base URL for the API endpoints */
+  private baseUrl: string;
+
+  /** Current dial/call state */
+  private dial?: Dial;
+
+  /** Array of event handlers for status changes */
+  private _handlers: {
     ev: 'status';
     fn: (...args: any[]) => void;
   }[];
 
+  /**
+   * Creates a new VogentCall instance
+   * @param dialDetails - Object containing session details and authentication, retrieved from the Vogent server API
+   * @param dialDetails.sessionId - Unique session identifier
+   * @param dialDetails.dialId - Unique dial/call identifier
+   * @param dialDetails.token - Authentication token
+   * @param config - Configuration options
+   * @param config.baseUrl - API base URL (defaults to 'https://api.getelto.com')
+   */
   constructor(dialDetails: {
     sessionId: string;
     dialId: string;
@@ -97,6 +166,12 @@ export class VogentCall {
     });
   }
 
+  /**
+   * Registers an event handler for status changes
+   * @param ev - Event type ('status')
+   * - status: called when the dial status changes, see docs.vogent.ai for more details
+   * @param fn - Callback function to handle the event
+   */
   on(ev: 'status', fn: (...args: any[]) => void) {
     this._handlers.push({
       ev,
@@ -104,6 +179,11 @@ export class VogentCall {
     });
   }
 
+  /**
+   * Subscribes to transcript updates for the current call
+   * @param fn - Callback function that receives transcript updates
+   * @returns Function to unsubscribe from transcript updates
+   */
   monitorTranscript(fn: (transcript: Transcript) => void): () => void {
     const subscription = this.client
       .subscribe({
@@ -130,7 +210,11 @@ export class VogentCall {
     }
   }
 
-  updateDial(dial: Dial) {
+  /**
+   * Internal method to update dial state and trigger status handlers
+   * @param dial - Updated dial information
+   */
+  private updateDial(dial: Dial) {
     if (!this.dial || dial.status !== this.dial.status) {
       this._handlers.forEach((h) => {
         h.fn(dial.status);
@@ -149,7 +233,13 @@ export class VogentCall {
     };
   }
 
-  async connectAudio(liveListen: boolean = false) {
+  /**
+   * Establishes audio connection for the call
+   * @param liveListen - Whether to enable live listening mode. This should be set to true for monitoring legs (e.g. humans that are listening
+   * to the call who the AI should not interact with.)
+   * @returns Promise resolving to audio connection handle
+   */
+  async connectAudio(liveListen: boolean = false): Promise<VogentAudioConn> {
     const token = await this.client.mutate({
       mutation: AI_GET_TOKEN,
       variables: {
@@ -163,11 +253,16 @@ export class VogentCall {
     const d: VogentDevice = await VonageDevice.getDevice(token.data!.browserDialToken.token, true);
 
     const c = await d.connect({
-      params: { EltoDialSessionID: this.sessionId, LiveListen: liveListen },
+      params: { EltoDialSessionID: this.sessionId, LiveListen: liveListen, DialID: this.dialId },
     });
+
+    return c;
   }
 
-  async start(disableAudio: boolean = false) {
+  /**
+   * Starts the call session. Does not connect audio, you must call connectAudio() to do so.
+   */
+  async start() {
     this.subscription = this.client
       .subscribe({
         query: AI_CONNECT_SESSION,
@@ -196,12 +291,12 @@ export class VogentCall {
           }
         }
       });
-
-    if (!disableAudio) {
-      await this.connectAudio();
-    }
   }
 
+  /**
+   * Sets the pause state of the AI
+   * @param paused - Whether to pause the AI or not.
+   */
   async setPaused(paused: boolean) {
     if (!this.dial) {
       return;
@@ -216,6 +311,9 @@ export class VogentCall {
     });
   }
 
+  /**
+   * Ends the current call
+   */
   async hangup() {
     if (!this.dial) {
       return;

package/devices/VogentDevice.ts

@@ -1,12 +1,49 @@
 // eslint-disable-next-line @typescript-eslint/no-empty-interface
 
-export interface VogentCall {
-    on: (ev: 'mute' | 'disconnect', fn: (...args: any[]) => void) => void;
-    mute: (status: boolean) => void;
-    disconnect: () => void;
-    sendDigits: (k: string) => void;
-  }
-
-  export interface VogentDevice {
-    connect: (p: any) => Promise<VogentCall>;
-  }
+/**
+ * Interface representing an active audio connection to a Vogent call.
+ * Returned by VogentCall.connectAudio()
+ */
+export interface VogentAudioConn {
+  /**
+   * Register event handlers for connection events
+   * @param ev - Event type to listen for
+   * - 'mute': Fired when the connection's mute state changes
+   * - 'disconnect': Fired when the connection is terminated
+   * @param fn - Callback function to handle the event
+   */
+  on: (ev: 'mute' | 'disconnect', fn: (...args: any[]) => void) => void;
+
+  /**
+   * Mute or unmute the audio connection
+   * @param status - True to mute, false to unmute
+   */
+  mute: (status: boolean) => void;
+
+  /**
+   * Terminate the audio connection
+   */
+  disconnect: () => void;
+
+  /**
+   * Send DTMF digits through the connection
+   * @param k - String of DTMF digits to send (0-9, *, #)
+   */
+  sendDigits: (k: string) => void;
+}
+
+/**
+ * Interface representing a device that can establish audio connections
+ * Currently implemented by VonageDevice
+ */
+export interface VogentDevice {
+  /**
+   * Establish an audio connection with the specified parameters
+   * @param p - Connection parameters object containing:
+   * - params.EltoDialSessionID: The session ID for the call
+   * - params.LiveListen: Whether this is a monitoring connection
+   * - params.DialID: The ID of the dial to connect to
+   * @returns Promise resolving to an active audio connection
+   */
+  connect: (p: any) => Promise<VogentAudioConn>;
+}

package/devices/VonageDevice.ts

@@ -1,4 +1,4 @@
-import { VogentCall } from './VogentDevice';
+import { VogentAudioConn } from './VogentDevice';
 import { VonageClient, LoggingLevel } from '@vonage/client-sdk';
 
 export class VonageCall {
@@ -95,7 +95,7 @@ export class VonageDevice {
     return new VonageDevice(sessId, client, disableEffects);
   }
 
-  async connect(p: any): Promise<VogentCall> {
+  async connect(p: any): Promise<VogentAudioConn> {
     const call = await this._client.serverCall(p.params);
     const v = new VonageCall(call, this._client, p.params);
     return v;

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@vogent/vogent-web-client",
-  "version": "0.0.3",
+  "version": "0.0.5",
   "license": "MIT",
   "dependencies": {
     "@apollo/client": "^3.12.4",