@vapi-ai/web 3.0.0 → 3.1.0

package/vapi.ts

@@ -23,6 +23,7 @@ import {
   CreateSquadDTO,
   CreateAssistantDTO,
   AssistantOverrides,
+  CreateWebCallDTO,
   CreateWorkflowDTO,
   WorkflowOverrides,
 } from './api';
@@ -205,7 +206,24 @@ type VapiEventListeners = {
   'recording-upload-completed': (event: DailyEventObjectNoPayload) => void;
 };
 
+type VideoRecordingStartMode = NonNullable<
+  CreateWebCallDTO['videoRecordingStartMode']
+>;
+
+// The app message Vapi sends when it couldn't start a server-mode recording.
+const VIDEO_RECORDING_START_FAILED_MESSAGE_TYPE = 'video-recording.start-failed';
+
+type VideoRecordingStartFailedMessage = {
+  type: typeof VIDEO_RECORDING_START_FAILED_MESSAGE_TYPE;
+  /** `not-hosting` when Daily saw nobody in the room; `failed` for any other failure. */
+  outcome: 'not-hosting' | 'failed';
+  /** A short description of the failure. */
+  error: string;
+};
+
 type StartCallOptions = {
+  /** Acquire the microphone before creating a backend call. Defaults to true. */
+  microphonePreflightEnabled?: boolean;
   /**
    * This determines whether the daily room will be deleted and all participants will be kicked once the user leaves the room.
    * If set to `false`, the room will be kept alive even after the user leaves, allowing clients to reconnect to the same room.
@@ -215,6 +233,25 @@ type StartCallOptions = {
    * @example true
    */
   roomDeleteOnUserLeaveEnabled?: boolean;
+  /**
+   * This determines who starts the video recording. Only applies when video
+   * recording is enabled (`artifactPlan.videoRecordingEnabled`).
+   *
+   * - `client`: the web client starts the recording when it joins.
+   * - `server`: Vapi starts the recording once the user has joined, so a weak
+   *   client connection can't stop it from starting. If Vapi can't set up the
+   *   server-side start, or the start itself fails, the SDK emits
+   *   `recording-error`.
+   *
+   * In `server` mode the SDK never calls `startRecording()` itself. If the
+   * server-side start couldn't be set up, calling it yourself may still start
+   * the recording.
+   *
+   * Requires a Vapi API that supports this field; older servers reject the
+   * request. The server defaults to `client` when it is not set.
+   * @example "server"
+   */
+  videoRecordingStartMode?: VideoRecordingStartMode;
 }
 
 type WebCall = {
@@ -242,12 +279,22 @@ type WebCall = {
   assistant?: { voice?: { provider?: string } };
   /**
    * The Vapi WebCall transport. When video recording is enabled, the server
-   * sets `callToken` to a Daily meeting token that auto-starts the cloud
-   * recording on join.
+   * sets `callToken` to the Daily meeting token to join with. In `client` mode
+   * the token auto-starts the cloud recording on join; in `server` mode it
+   * starts nothing and Vapi starts the recording. If there is no token, the
+   * SDK emits `recording-error` and starts nothing, though `startRecording()`
+   * may still start the recording from the client.
+   *
+   * `videoRecordingStartMode` is `server` when Vapi starts the recording, and
+   * is absent when video recording is off or the server-side start couldn't
+   * be set up.
    *
    * call.transport
    */
-  transport?: { callToken?: string };
+  transport?: {
+    callToken?: string;
+    videoRecordingStartMode?: VideoRecordingStartMode;
+  };
 }
 
 async function startAudioPlayer(
@@ -295,14 +342,13 @@ function subscribeToTracks(
   e: DailyEventObjectParticipant,
   call: DailyCall,
   isVideoRecordingEnabled?: boolean,
-  isVideoEnabled?: boolean,
 ) {
   if (e.participant.local) return;
 
   call.updateParticipant(e.participant.session_id, {
     setSubscribedTracks: {
       audio: true,
-      video: isVideoRecordingEnabled || isVideoEnabled,
+      video: isVideoRecordingEnabled,
     },
   });
 }
@@ -356,6 +402,40 @@ export default class Vapi extends VapiEventEmitter {
   private speakingTimeout: NodeJS.Timeout | null = null;
   private dailyCallConfig: DailyAdvancedConfig = {};
   private dailyCallObject: DailyFactoryOptions = {};
+  private microphoneTrack: MediaStreamTrack | null = null;
+  private cancelMicrophonePreflight: (() => void) | null = null;
+
+  private async microphoneAcquire(): Promise<MediaStreamTrack> {
+    const source = this.dailyCallObject.audioSource;
+    if (source && typeof source === 'object') {
+      if (source.readyState === 'ended') {
+        throw new DOMException('The supplied microphone track has ended.', 'NotReadableError');
+      }
+      return source;
+    }
+    return new Promise<MediaStreamTrack>((resolve, reject) => {
+      let cancelled = false;
+      this.cancelMicrophonePreflight = () => {
+        cancelled = true;
+        reject(new DOMException('Microphone preflight cancelled.', 'AbortError'));
+      };
+      navigator.mediaDevices.getUserMedia({
+        audio: typeof source === 'string' ? { deviceId: { exact: source } } : true,
+      }).then((stream) => {
+        const track = stream.getAudioTracks()[0];
+        if (cancelled || !track || track.readyState === 'ended') {
+          stream.getTracks().forEach((item) => item.stop());
+          reject(new DOMException('No live microphone track available.', 'NotFoundError'));
+          return;
+        }
+        stream.getTracks().filter((item) => item !== track).forEach((item) => item.stop());
+        this.microphoneTrack = track;
+        resolve(track);
+      }, reject);
+    }).finally(() => {
+      this.cancelMicrophonePreflight = null;
+    });
+  }
 
   private hasEmittedCallEndedStatus: boolean = false;
 
@@ -376,6 +456,8 @@ export default class Vapi extends VapiEventEmitter {
   }
 
   private async cleanup() {
+    this.microphoneTrack?.stop();
+    this.microphoneTrack = null;
     this.started = false;
     this.hasEmittedCallEndedStatus = false;
     if (this.call) {
@@ -498,7 +580,16 @@ export default class Vapi extends VapiEventEmitter {
     
     this.started = true;
 
+    let failureStage = 'microphone-preflight';
     try {
+      if (this.call) {
+        await this.cleanup();
+        this.started = true;
+      }
+      const audioSource = options?.microphonePreflightEnabled === false
+        ? this.dailyCallObject.audioSource ?? true
+        : await this.microphoneAcquire();
+      failureStage = 'unknown';
             // Stage 1: Create web call
       this.emit('call-start-progress', {
         stage: 'web-call-creation',
@@ -508,18 +599,23 @@ export default class Vapi extends VapiEventEmitter {
       
       const webCallStartTime = Date.now();
       
+      // An unset option stays undefined, so JSON.stringify drops the key and
+      // older servers never see it.
+      const createWebCallBody: CreateWebCallDTO = {
+        assistant: typeof assistant === 'string' ? undefined : assistant,
+        assistantId: typeof assistant === 'string' ? assistant : undefined,
+        assistantOverrides,
+        squad: typeof squad === 'string' ? undefined : squad,
+        squadId: typeof squad === 'string' ? squad : undefined,
+        workflow: typeof workflow === 'string' ? undefined : workflow,
+        workflowId: typeof workflow === 'string' ? workflow : undefined,
+        workflowOverrides,
+        roomDeleteOnUserLeaveEnabled: options?.roomDeleteOnUserLeaveEnabled,
+        videoRecordingStartMode: options?.videoRecordingStartMode,
+      };
+
       const webCall = (
-        await client.call.callControllerCreateWebCall({
-          assistant: typeof assistant === 'string' ? undefined : assistant,
-          assistantId: typeof assistant === 'string' ? assistant : undefined,
-          assistantOverrides,
-          squad: typeof squad === 'string' ? undefined : squad,
-          squadId: typeof squad === 'string' ? squad : undefined,
-          workflow: typeof workflow === 'string' ? undefined : workflow,
-          workflowId: typeof workflow === 'string' ? workflow : undefined,
-          workflowOverrides,
-          roomDeleteOnUserLeaveEnabled: options?.roomDeleteOnUserLeaveEnabled,
-        })
+        await client.call.callControllerCreateWebCall(createWebCallBody)
       ).data;
       
       const webCallDuration = Date.now() - webCallStartTime;
@@ -535,28 +631,20 @@ export default class Vapi extends VapiEventEmitter {
         }
       });
 
-      if (this.call) {
-        this.emit('call-start-progress', {
-          stage: 'daily-call-object-creation',
-          status: 'started',
-          timestamp: new Date().toISOString(),
-          metadata: { action: 'cleanup-existing' }
-        });
-        await this.cleanup();
-      }
-
       const isVideoRecordingEnabled =
         webCall?.artifactPlan?.videoRecordingEnabled ?? false;
 
-      const isVideoEnabled = webCall?.assistant?.voice?.provider === 'tavus';
-
       // When video recording is enabled, the server sends a Daily meeting
-      // token that auto-starts the cloud recording on join — more reliable
-      // than calling startRecording() from a weak client network. Older
-      // servers don't send one; then the client starts the recording itself.
-      const callToken = (
-        webCall?.transport as { callToken?: string } | undefined
-      )?.callToken;
+      // token. In client mode it auto-starts the cloud recording on join. In
+      // server mode it starts nothing: Vapi starts the recording from its
+      // servers once the user has joined, which a weak client network can't
+      // stop. Without a token the SDK emits recording-error and starts
+      // nothing.
+      const transport = webCall?.transport as WebCall['transport'];
+      const callToken = transport?.callToken;
+      const isRecordingStartedByServer =
+        transport?.videoRecordingStartMode === 'server';
+      const recordingTokenMissing = isVideoRecordingEnabled && !callToken;
 
       // Stage 2: Create Daily call object
       this.emit('call-start-progress', {
@@ -567,7 +655,6 @@ export default class Vapi extends VapiEventEmitter {
           audioSource: this.dailyCallObject.audioSource ?? true,
           videoSource: this.dailyCallObject.videoSource ?? isVideoRecordingEnabled,
           isVideoRecordingEnabled,
-          isVideoEnabled
         }
       });
       
@@ -575,7 +662,7 @@ export default class Vapi extends VapiEventEmitter {
       
       try {
         this.call = DailyIframe.createCallObject({
-          audioSource: this.dailyCallObject.audioSource ?? true,
+          audioSource,
           videoSource: this.dailyCallObject.videoSource ?? isVideoRecordingEnabled,
           dailyConfig: this.dailyCallConfig,
         });
@@ -677,12 +764,7 @@ export default class Vapi extends VapiEventEmitter {
 
       this.call.on('participant-joined', (e) => {
         if (!e || !this.call) return;
-        subscribeToTracks(
-          e,
-          this.call,
-          isVideoRecordingEnabled,
-          isVideoEnabled,
-        );
+        subscribeToTracks(e, this.call, isVideoRecordingEnabled);
       });
 
       this.call.on('participant-updated', (e) => {
@@ -699,6 +781,11 @@ export default class Vapi extends VapiEventEmitter {
         this.detachAudioPlayer(e.participant.session_id);
       });
 
+      // Registered before join(), as in reconnect(): Vapi starts a server-mode
+      // recording when it sees the user join, so its start-failed message can
+      // arrive while join() is still in flight.
+      this.call.on('app-message', (e) => this.onAppMessage(e));
+
       // Registered before join(): a token-auto-started recording can begin
       // while join() is still in flight, so a listener added after join
       // could miss the event.
@@ -799,52 +886,28 @@ export default class Vapi extends VapiEventEmitter {
 
       // Stage 5: Video recording setup (if enabled)
       if (isVideoRecordingEnabled && callToken) {
-        // The meeting token auto-started the recording at join, so there is
-        // nothing to request from the client.
+        // The meeting token auto-started the recording at join, or Vapi
+        // starts it from its servers, so there is nothing to request from the
+        // client.
         this.emit('call-start-progress', {
           stage: 'video-recording-setup',
           status: 'completed',
           timestamp: new Date().toISOString(),
-          metadata: { action: 'auto-started-via-meeting-token' }
+          metadata: {
+            action: isRecordingStartedByServer
+              ? 'started-by-server'
+              : 'auto-started-via-meeting-token'
+          }
         });
       } else if (isVideoRecordingEnabled) {
+        // No token: nothing starts the recording. The recording-error is
+        // reported once start() has finished.
         this.emit('call-start-progress', {
           stage: 'video-recording-setup',
-          status: 'started',
-          timestamp: new Date().toISOString()
+          status: 'failed',
+          timestamp: new Date().toISOString(),
+          metadata: { action: 'no-meeting-token' }
         });
-
-        const recordingStartTime = Date.now();
-
-        try {
-          recordingRequestedTime = new Date().getTime();
-          this.startRecording();
-
-          const recordingSetupDuration = Date.now() - recordingStartTime;
-          this.emit('call-start-progress', {
-            stage: 'video-recording-setup',
-            status: 'completed',
-            duration: recordingSetupDuration,
-            timestamp: new Date().toISOString()
-          });
-        } catch (error) {
-          const recordingSetupDuration = Date.now() - recordingStartTime;
-          const serializedError = serializeError(error);
-          this.emit('call-start-progress', {
-            stage: 'video-recording-setup',
-            status: 'failed',
-            duration: recordingSetupDuration,
-            timestamp: new Date().toISOString(),
-            metadata: { error: serializedError.message }
-          });
-          this.emit('error', {
-            type: 'video-recording-setup-error',
-            stage: 'video-recording-setup',
-            error: serializedError,
-            timestamp: new Date().toISOString()
-          });
-          // Don't throw here, video recording is optional
-        }
       } else {
         this.emit('call-start-progress', {
           stage: 'video-recording-setup',
@@ -899,8 +962,6 @@ export default class Vapi extends VapiEventEmitter {
         if (e) this.handleLocalAudioLevel(e);
       });
 
-      this.call.on('app-message', (e) => this.onAppMessage(e));
-
       this.call.on('nonfatal-error', (e) => {
         // https://docs.daily.co/reference/daily-js/events/meeting-events#type-audio-processor-error
         if (e?.type === 'local-audio-level-observer-error') {
@@ -990,13 +1051,18 @@ export default class Vapi extends VapiEventEmitter {
         timestamp: new Date().toISOString()
       });
 
+      if (recordingTokenMissing) {
+        this.recordingTokenMissingReportSchedule();
+      }
+
       return webCall;
     } catch (e) {
       const totalDuration = Date.now() - startTime;
       const serializedError = serializeError(e);
+      await this.cleanup();
       
       this.emit('call-start-failed', {
-        stage: 'unknown',
+        stage: failureStage,
         totalDuration,
         error: serializedError.message,
         errorStack: serializedError.stack || 'No stack trace available',
@@ -1011,8 +1077,10 @@ export default class Vapi extends VapiEventEmitter {
       
       // Also emit the generic error event for backward compatibility
       this.emit('error', {
-        type: 'start-method-error',
-        stage: 'unknown',
+        type: failureStage === 'microphone-preflight'
+          ? `microphone-preflight-${e && typeof e === 'object' && 'name' in e ? e.name : 'error'}`
+          : 'start-method-error',
+        stage: failureStage,
         error: serializedError,
         totalDuration,
         timestamp: new Date().toISOString(),
@@ -1024,7 +1092,6 @@ export default class Vapi extends VapiEventEmitter {
         }
       });
       
-      await this.cleanup();
       return null;
     }
   }
@@ -1039,6 +1106,12 @@ export default class Vapi extends VapiEventEmitter {
       } else {
         try {
           const parsedMessage = JSON.parse(e.data);
+          // Not a Vapi client message: re-emitted as recording-error, and kept
+          // out of 'message' because its consumers switch on `type`.
+          if (parsedMessage?.type === VIDEO_RECORDING_START_FAILED_MESSAGE_TYPE) {
+            this.videoRecordingStartFailedReport(parsedMessage);
+            return;
+          }
           this.emit('message', parsedMessage);
           if (parsedMessage && 'type' in parsedMessage && 'status' in parsedMessage && parsedMessage.type === 'status-update' && parsedMessage.status === 'ended') {
             this.hasEmittedCallEndedStatus = true;
@@ -1092,6 +1165,12 @@ export default class Vapi extends VapiEventEmitter {
    * If `roomDeleteOnUserLeaveEnabled` is set to `true`, the Vapi call will also be destroyed, preventing any reconnections.
    */
   async stop(): Promise<void> {
+    if (this.cancelMicrophonePreflight) {
+      this.cancelMicrophonePreflight();
+      return;
+    }
+    this.microphoneTrack?.stop();
+    this.microphoneTrack = null;
     this.started = false;
     if (this.call) {
       await this.call.destroy();
@@ -1231,6 +1310,41 @@ export default class Vapi extends VapiEventEmitter {
     }
   }
 
+  /**
+   * Reported in a later task, like Daily's own recording-error: start() or
+   * reconnect() has resolved and the caller's await continuation has run, so a
+   * listener registered right after it still hears this, and one that calls
+   * stop() can't interrupt call setup. Skipped if that call was stopped or
+   * replaced.
+   */
+  private recordingTokenMissingReportSchedule() {
+    const call = this.call;
+    if (!call) return;
+    setTimeout(() => {
+      if (!this.started || this.call !== call) return;
+      this.emitToConsumer('recording-error', {
+        action: 'recording-error',
+        callClientId: call.callClientId,
+        errorMsg:
+          'Vapi returned no recording token, so the recording was not started. Call startRecording() to try starting it from the client.',
+      });
+    }, 0);
+  }
+
+  /** The fields are read defensively: the app message is untrusted JSON. */
+  private videoRecordingStartFailedReport(
+    message: Partial<VideoRecordingStartFailedMessage>,
+  ) {
+    const outcome =
+      typeof message.outcome === 'string' ? message.outcome : 'unknown';
+    const error = typeof message.error === 'string' ? message.error : 'unknown';
+    this.emitToConsumer('recording-error', {
+      action: 'recording-error',
+      callClientId: this.call?.callClientId ?? '',
+      errorMsg: `Vapi couldn't start the recording (${outcome}): ${error}`,
+    });
+  }
+
   /** Drops the reference before removing, so nothing hands out a detached element. */
   private detachAudioPlayer(participantId: string) {
     if (this.audioPlayer?.dataset.participantId === participantId) {
@@ -1498,12 +1612,16 @@ export default class Vapi extends VapiEventEmitter {
       }
 
       const isVideoRecordingEnabled = webCall?.artifactPlan?.videoRecordingEnabled ?? false;
-      const isVideoEnabled = webCall?.assistant?.voice?.provider === 'tavus';
 
-      // Same auto-start token as in start(). Rejoining with it while the
+      // Same token as in start(). In client mode, rejoining with it while the
       // recording is still running is safe; if the recording stopped when the
-      // user left, the token starts a new one.
+      // user left, the token starts a new one. In server mode it starts
+      // nothing. Without a token the SDK emits recording-error and starts
+      // nothing.
       const callToken = webCall?.transport?.callToken;
+      const isRecordingStartedByServer =
+        webCall?.transport?.videoRecordingStartMode === 'server';
+      const recordingTokenMissing = isVideoRecordingEnabled && !callToken;
 
       // Stage 1: Create Daily call object
       this.emit('call-start-progress', {
@@ -1514,7 +1632,6 @@ export default class Vapi extends VapiEventEmitter {
           audioSource: this.dailyCallObject.audioSource ?? true,
           videoSource: this.dailyCallObject.videoSource ?? isVideoRecordingEnabled,
           isVideoRecordingEnabled,
-          isVideoEnabled
         }
       });
 
@@ -1605,12 +1722,7 @@ export default class Vapi extends VapiEventEmitter {
 
       this.call.on('participant-joined', (e) => {
         if (!e || !this.call) return;
-        subscribeToTracks(
-          e,
-          this.call,
-          isVideoRecordingEnabled,
-          isVideoEnabled,
-        );
+        subscribeToTracks(e, this.call, isVideoRecordingEnabled);
       });
 
       this.call.on('participant-updated', (e) => {
@@ -1738,46 +1850,28 @@ export default class Vapi extends VapiEventEmitter {
 
       // Stage 4: Video recording setup (if enabled)
       if (isVideoRecordingEnabled && callToken) {
-        // The meeting token auto-started the recording at join, so there is
-        // nothing to request from the client.
+        // The meeting token auto-started the recording at join, or Vapi
+        // starts it from its servers, so there is nothing to request from the
+        // client.
         this.emit('call-start-progress', {
           stage: 'video-recording-setup',
           status: 'completed',
           timestamp: new Date().toISOString(),
-          metadata: { action: 'auto-started-via-meeting-token' }
+          metadata: {
+            action: isRecordingStartedByServer
+              ? 'started-by-server'
+              : 'auto-started-via-meeting-token'
+          }
         });
       } else if (isVideoRecordingEnabled) {
+        // No token: nothing starts the recording. The recording-error is
+        // reported once reconnect() has finished.
         this.emit('call-start-progress', {
           stage: 'video-recording-setup',
-          status: 'started',
-          timestamp: new Date().toISOString()
+          status: 'failed',
+          timestamp: new Date().toISOString(),
+          metadata: { action: 'no-meeting-token' }
         });
-
-        const recordingStartTime = Date.now();
-
-        try {
-          recordingRequestedTime = new Date().getTime();
-          this.startRecording();
-
-          const recordingSetupDuration = Date.now() - recordingStartTime;
-          this.emit('call-start-progress', {
-            stage: 'video-recording-setup',
-            status: 'completed',
-            duration: recordingSetupDuration,
-            timestamp: new Date().toISOString()
-          });
-        } catch (error) {
-          const recordingSetupDuration = Date.now() - recordingStartTime;
-          const serializedError = serializeError(error);
-          this.emit('call-start-progress', {
-            stage: 'video-recording-setup',
-            status: 'failed',
-            duration: recordingSetupDuration,
-            timestamp: new Date().toISOString(),
-            metadata: { error: serializedError.message }
-          });
-          // Don't throw here, video recording is optional
-        }
       } else {
         this.emit('call-start-progress', {
           stage: 'video-recording-setup',
@@ -1880,6 +1974,10 @@ export default class Vapi extends VapiEventEmitter {
 
       this.emit('call-start');
 
+      if (recordingTokenMissing) {
+        this.recordingTokenMissingReportSchedule();
+      }
+
     } catch (e) {
       const totalDuration = Date.now() - startTime;
       const serializedError = serializeError(e);