@ctchealth/plato-sdk 0.0.18 → 0.0.19

package/src/lib/plato-sdk.ts

@@ -0,0 +1,776 @@
+/**
+ * Copyright (c) 2025 ctcHealth. All rights reserved.
+ *
+ * This file is part of the ctcHealth Plato Platform, a proprietary software system developed by ctcHealth.
+ *
+ * This source code and all related materials are confidential and proprietary to ctcHealth.
+ * Unauthorized access, use, copying, modification, distribution, or disclosure is strictly prohibited
+ * and may result in disciplinary action and civil and/or criminal penalties.
+ *
+ * This software is intended solely for authorized use within ctcHealth and its designated partners.
+ *
+ * For internal use only.
+ */
+import axios, { AxiosInstance } from 'axios';
+import {
+  CallCreateDto,
+  CallDTO,
+  CreateSimulationDto,
+  CreationPhase,
+  SimulationRecordingsDto,
+  SimulationRecordingsQueryDto,
+  SimulationDetailsDto,
+  RecommendationsResponseDto,
+  RequestPdfUploadResponse,
+  PdfSlidesDto,
+  PdfSlideDto,
+  PdfSlidesAnalysisQueryDto,
+  CheckPdfStatusResponse,
+  AssistantImageDto,
+  ActiveCallState,
+} from './plato-intefaces';
+import Vapi from '@vapi-ai/web';
+import { Call } from '@vapi-ai/web/dist/api';
+import { checkFile, calculateHash, getPdfPageCount } from './utils';
+import { MAX_PDF_FILE_SIZE, ALLOWED_PDF_MIME_TYPES, MAX_PDF_PAGES } from './constants';
+
+export interface ApiClientConfig {
+  baseUrl: string;
+  jwtToken: string;
+  publicKey: string;
+}
+
+export interface ToolCall {
+  function: {
+    name: string;
+    arguments: {
+      slideNumber?: number;
+      progressObjectiveNumber?: number;
+      [key: string]: unknown;
+    };
+  };
+  id: string;
+}
+
+/**
+ * Event map for call events, providing strict typing for each event's payload.
+ * There are no inputs for the events and all of them return void.
+ */
+export interface CallEventMap {
+  'call-start': undefined;
+  'call-end': undefined;
+  'speech-start': undefined;
+  'speech-end': undefined;
+  error: Error;
+  message: {
+    type: string;
+    role: string;
+    transcript?: string;
+    transcriptType: 'final' | 'partial';
+    toolCallList?: ToolCall[]; // used in real-time messages to the client
+    toolCalls?: ToolCall[]; // used in conversation history
+    [key: string]: unknown;
+  };
+  'volume-level': number;
+  'call-details-ready': CallDTO;
+}
+
+export type CallEventNames = keyof CallEventMap;
+
+export type CallEventListener<K extends CallEventNames> = (payload: CallEventMap[K]) => void;
+
+export class PlatoApiClient {
+  private static readonly ACTIVE_CALL_STORAGE_KEY = 'plato_active_call';
+
+  private http: AxiosInstance;
+  // eslint-disable-next-line @typescript-eslint/no-unsafe-function-type
+  private eventListeners: Partial<Record<CallEventNames, Function[]>> = {};
+  private callControllerInstance?: Vapi;
+  private eventsAttached = false;
+  private currentCallId?: string;
+  // Vapi-native events (events that Vapi SDK supports)
+  // Exclude our custom SDK events from this list
+  private vapiEventNames: Exclude<CallEventNames, 'call-details-ready'>[] = [
+    'call-start',
+    'call-end',
+    'speech-start',
+    'speech-end',
+    'error',
+    'message',
+    'volume-level',
+  ];
+  // All event names including SDK-specific events
+  eventNames: CallEventNames[] = [
+    'call-start',
+    'call-end',
+    'speech-start',
+    'speech-end',
+    'error',
+    'message',
+    'volume-level',
+    'call-details-ready',
+  ];
+
+  constructor(private config: ApiClientConfig) {
+    if (!config.baseUrl) {
+      throw new Error('baseUrl is required');
+    }
+
+    if (config.baseUrl.endsWith('/')) {
+      config.baseUrl = config.baseUrl.slice(0, -1);
+    }
+
+    this.http = axios.create({
+      baseURL: config.baseUrl,
+      headers: {
+        'x-client-token': config.jwtToken,
+      },
+    });
+  }
+
+  /**
+   * Update the JWT token for all subsequent requests.
+   * Useful when the token is refreshed or when switching user context.
+   */
+  setJwtToken(jwtToken: string): void {
+    this.http.defaults.headers.common['x-client-token'] = jwtToken;
+  }
+
+  /**
+   * Remove the JWT token from subsequent requests.
+   */
+  clearJwtToken(): void {
+    delete this.http.defaults.headers.common['x-client-token'];
+  }
+
+  /**
+   * Register a listener for a call event with strict typing.
+   * @param event Event name
+   * @param listener Listener function
+   */
+  private on<K extends CallEventNames>(event: K, listener: CallEventListener<K>): void {
+    if (!this.eventListeners[event]) {
+      this.eventListeners[event] = [];
+    }
+    const listeners = this.eventListeners[event];
+
+    if (listeners) {
+      listeners.push(listener);
+    }
+    if (this.callControllerInstance && !this.eventsAttached) {
+      this.attachEvents();
+    }
+  }
+
+  /**
+   * Remove a listener for a call event with strict typing.
+   * @param event Event name
+   * @param listener Listener function
+   */
+  private off<K extends CallEventNames>(event: K, listener: CallEventListener<K>): void {
+    const listeners = this.eventListeners[event];
+
+    if (!listeners) return;
+    this.eventListeners[event] = listeners.filter(l => l !== listener);
+  }
+
+  /**
+   * Internal: Attach event listeners and propagate to registered listeners.
+   */
+  private attachEvents(): void {
+    if (this.eventsAttached || !this.callControllerInstance) return;
+    this.eventsAttached = true;
+    const vapi = this.callControllerInstance;
+
+    // Only attach Vapi-native events to the Vapi instance
+    this.vapiEventNames.forEach(event => {
+      vapi.on(event, (payload: CallEventMap[CallEventNames]) => {
+        (this.eventListeners[event] || []).forEach(listener => listener(payload));
+      });
+    });
+  }
+
+  /**
+   * Internal: Emit SDK-specific events that are not part of Vapi.
+   */
+  private emit<K extends CallEventNames>(event: K, payload: CallEventMap[K]): void {
+    const listeners = this.eventListeners[event];
+    if (listeners) {
+      listeners.forEach(listener => listener(payload));
+    }
+  }
+
+  /**
+   * Store active call state in localStorage for recovery purposes.
+   * @private
+   */
+  private storeCallState(state: ActiveCallState): void {
+    try {
+      localStorage.setItem(PlatoApiClient.ACTIVE_CALL_STORAGE_KEY, JSON.stringify(state));
+    } catch (error) {
+      console.warn('Failed to store call state:', error);
+    }
+  }
+
+  /**
+   * Retrieve active call state from localStorage.
+   * Validates the stored data and clears it if invalid.
+   * @private
+   * @returns The stored call state or null if not found or invalid
+   */
+  private getStoredCallState(): ActiveCallState | null {
+    try {
+      const stored = localStorage.getItem(PlatoApiClient.ACTIVE_CALL_STORAGE_KEY);
+      if (!stored) {
+        return null;
+      }
+
+      const parsed = JSON.parse(stored) as ActiveCallState;
+
+      // Validate required fields
+      if (!parsed.callId || !parsed.externalCallId || !parsed.simulationId || !parsed.startedAt) {
+        console.warn('Invalid stored call state, clearing');
+        this.clearCallState();
+        return null;
+      }
+
+      return parsed;
+    } catch (error) {
+      console.warn('Failed to retrieve call state:', error);
+      return null;
+    }
+  }
+
+  /**
+   * Clear active call state from localStorage.
+   * @private
+   */
+  private clearCallState(): void {
+    try {
+      localStorage.removeItem(PlatoApiClient.ACTIVE_CALL_STORAGE_KEY);
+    } catch (error) {
+      console.warn('Failed to clear call state:', error);
+    }
+  }
+
+  /**
+   * Check if a stored call is considered abandoned based on age.
+   * Calls older than 5 minutes are considered abandoned.
+   * @private
+   * @param state The call state to check
+   * @returns true if the call is abandoned, false otherwise
+   */
+  private isCallAbandoned(state: ActiveCallState): boolean {
+    const ABANDONMENT_THRESHOLD_MS = 5 * 60 * 1000; // 5 minutes
+    const startedAt = new Date(state.startedAt).getTime();
+    const now = Date.now();
+    const age = now - startedAt;
+
+    return age > ABANDONMENT_THRESHOLD_MS;
+  }
+
+  /**
+   * Recover and clean up any abandoned calls from previous sessions.
+   *
+   * This method should be called during application initialization,
+   * typically in ngOnInit() or useEffect(). It detects calls that were
+   * active when the page was last refreshed and notifies the backend
+   * to process them if they're older than 5 minutes.
+   *
+   * The backend endpoint is idempotent, so calling this method multiple
+   * times for the same call is safe.
+   *
+   * @returns Promise<boolean> - true if an abandoned call was recovered and processed
+   *
+   * @example
+   * // In Angular component
+   * async ngOnInit(): Promise<void> {
+   *   const recovered = await this.platoClient.recoverAbandonedCall();
+   *   if (recovered) {
+   *     console.log('Recovered abandoned call from previous session');
+   *   }
+   * }
+   *
+   * @example
+   * // In React component
+   * useEffect(() => {
+   *   platoClient.recoverAbandonedCall()
+   *     .then(recovered => {
+   *       if (recovered) {
+   *         console.log('Recovered abandoned call');
+   *       }
+   *     })
+   *     .catch(console.error);
+   * }, []);
+   */
+  async recoverAbandonedCall(): Promise<boolean> {
+    try {
+      const storedState = this.getStoredCallState();
+
+      if (!storedState) {
+        return false;
+      }
+
+      if (!this.isCallAbandoned(storedState)) {
+        return false;
+      }
+
+      console.log('Detected abandoned call, notifying backend:', storedState.callId);
+
+      try {
+        const response = await this.http.post('/api/v1/postcall/call-ended', {
+          callId: storedState.callId,
+        });
+
+        console.log('Backend notified of abandoned call:', response.data);
+      } catch (error) {
+        console.error('Failed to notify backend of abandoned call:', error);
+      }
+
+      this.clearCallState();
+
+      return true;
+    } catch (error) {
+      console.error('Error during call recovery:', error);
+      this.clearCallState();
+      return false;
+    }
+  }
+
+  async createSimulation(createSimulationParams: CreateSimulationDto): Promise<{
+    simulationId: string;
+    phase: CreationPhase;
+  }> {
+    try {
+      const res = await this.http.post('/api/v1/simulation', {
+        ...createSimulationParams,
+      });
+      return {
+        simulationId: res.data.simulationId,
+        phase: res.data.phase,
+      };
+    } catch (e) {
+      if (axios.isAxiosError(e)) {
+        console.error('Error creating simulation:', e.response?.data.message);
+      }
+      throw e;
+    }
+  }
+
+  async checkSimulationStatus(simulationId: string): Promise<{
+    phase: CreationPhase;
+  }> {
+    const res = await this.http.get(`/api/v1/simulation/status/${simulationId}`);
+
+    return res.data;
+  }
+
+  async getUserSimulations(): Promise<Array<{ simulationId: string; phase: CreationPhase }>> {
+    try {
+      const res = await this.http.get('/api/v1/simulation/user/simulations');
+      return res.data;
+    } catch (e) {
+      if (axios.isAxiosError(e)) {
+        console.error('Error getting user simulations:', e.response?.data.message);
+      }
+      throw e;
+    }
+  }
+
+  async getSimulationDetails(simulationId: string): Promise<SimulationDetailsDto> {
+    try {
+      const res = await this.http.get(`/api/v1/simulation/details/${simulationId}`);
+      return res.data as SimulationDetailsDto;
+    } catch (e) {
+      if (axios.isAxiosError(e)) {
+        console.error('Error getting simulation details:', e.response?.data.message);
+      }
+      throw e;
+    }
+  }
+
+  /**
+   * Deletes a simulation (assistant) from the server and Vapi.
+   * @param simulationId - MongoDB ObjectId of the simulation
+   * @throws 404 if simulation not found
+   */
+  async deleteSimulation(simulationId: string): Promise<void> {
+    try {
+      await this.http.delete(`/api/v1/simulation/${simulationId}`);
+    } catch (e) {
+      if (axios.isAxiosError(e)) {
+        console.error('Error deleting simulation:', e.response?.data.message);
+      }
+      throw e;
+    }
+  }
+
+  async getCallDetails(callId: string): Promise<CallDTO> {
+    try {
+      const res = await this.http.get(`/api/v1/simulation/call/${callId}`);
+      return res.data as CallDTO;
+    } catch (e) {
+      if (axios.isAxiosError(e)) {
+        console.error('Error getting call details:', e.response?.data.message);
+      }
+      throw e;
+    }
+  }
+
+  async getCallRecordings(
+    queryParams: SimulationRecordingsQueryDto
+  ): Promise<SimulationRecordingsDto[]> {
+    try {
+      const res = await this.http.get(`/api/v1/simulation/call/recordings`, {
+        params: queryParams,
+      });
+      return res.data as SimulationRecordingsDto[];
+    } catch (e) {
+      if (axios.isAxiosError(e)) {
+        console.error('Error getting call recordings:', e.response?.data.message);
+      }
+      throw e;
+    }
+  }
+
+  async getCallRecording(callId: string): Promise<string> {
+    try {
+      const res = await this.http.get(`/api/v1/simulation/call/recordings/${callId}`);
+      return res.data as string;
+    } catch (e) {
+      if (axios.isAxiosError(e)) {
+        console.error('Error getting call recording:', e.response?.data.message);
+      }
+      throw e;
+    }
+  }
+
+  /**
+   * Remove all listeners for all call events.
+   */
+  private removeAllEventListeners(): void {
+    if (!this.callControllerInstance) return;
+    this.eventNames.forEach(event => {
+      (this.eventListeners[event] || []).forEach(listener => {
+        // eslint-disable-next-line @typescript-eslint/ban-ts-comment
+        // @ts-expect-error
+        this.callControllerInstance?.off(event, listener);
+      });
+      this.eventListeners[event] = [];
+    });
+    this.eventsAttached = false;
+  }
+
+  async startCall(simulationId: string) {
+    // Check for any previous call state before starting new call
+    // If found, notify backend to ensure it gets processed
+    const storedState = this.getStoredCallState();
+    if (storedState) {
+      console.log(
+        'Found previous call state, notifying backend before starting new call:',
+        storedState.callId
+      );
+      try {
+        await this.http.post('/api/v1/postcall/call-ended', {
+          callId: storedState.callId,
+        });
+        console.log('Backend notified of previous call');
+      } catch (error) {
+        console.error('Failed to notify backend of previous call:', error);
+      }
+    }
+
+    // Now clear the state before starting new call
+    this.clearCallState();
+
+    this.callControllerInstance = new Vapi(
+      this.config.publicKey,
+      'https://db41aykk1gw9e.cloudfront.net' // base url
+    );
+    if (!this.eventsAttached) {
+      this.attachEvents();
+    }
+
+    // Internal call-end listener
+    this.callControllerInstance.on('call-end', () => {
+      this.onCallEnded().catch(error => {
+        console.error('Error in onCallEnded: ', error);
+      });
+    });
+
+    const { data } = await this.http.get(`/api/v1/simulation/${simulationId}`);
+    const assistantId = data as string;
+    const call: Call | null = await this.callControllerInstance.start(assistantId);
+
+    if (!call || !call.assistantId) {
+      throw new Error('Cannot start a call, please try again later');
+    }
+    try {
+      const apiCall = await this.createCall({
+        callId: call.id,
+        assistantId: call.assistantId,
+      });
+
+      // Store the callId for use in onCallEnded
+      this.currentCallId = apiCall._id;
+
+      // Store call state in localStorage for recovery
+      this.storeCallState({
+        callId: apiCall._id,
+        externalCallId: call.id,
+        simulationId: simulationId,
+        startedAt: new Date().toISOString(),
+        version: 1,
+      });
+
+      // Return stopCall, callId, and event subscription methods with strict typing
+      return {
+        stopCall: () => {
+          this.callControllerInstance?.stop();
+          this.removeAllEventListeners();
+          this.clearCallState();
+        },
+        callId: apiCall._id,
+        /**
+         * Subscribe to call events for this call with strict typing.
+         * @param event Event name
+         * @param listener Listener function
+         */
+        on: <K extends CallEventNames>(event: K, listener: CallEventListener<K>) =>
+          this.on(event, listener),
+        /**
+         * Unsubscribe from call events for this call with strict typing.
+         * @param event Event name
+         * @param listener Listener function
+         */
+        off: <K extends CallEventNames>(event: K, listener: CallEventListener<K>) =>
+          this.off(event, listener),
+      };
+    } catch (e) {
+      this.callControllerInstance?.stop();
+      this.removeAllEventListeners();
+      this.clearCallState();
+      throw e;
+    }
+  }
+
+  private async onCallEnded(): Promise<void> {
+    let callIdForRetry: string | undefined;
+    try {
+      if (!this.currentCallId) {
+        return;
+      }
+
+      callIdForRetry = this.currentCallId;
+
+      // First attempt
+      let response = await this.http.post('/api/v1/postcall/call-ended', {
+        callId: callIdForRetry,
+      });
+
+      // If status is "processing", retry once immediately
+      if (response.data?.status === 'processing') {
+        response = await this.http.post('/api/v1/postcall/call-ended', {
+          callId: callIdForRetry,
+        });
+      }
+
+      // After onCallEnded completes successfully, fetch and emit call details
+      try {
+        const callDetails = await this.getCallDetails(callIdForRetry);
+        this.emit('call-details-ready', callDetails);
+      } catch (error) {
+        console.error('Error fetching call details after call ended:', error);
+        // Don't throw - we don't want to break the onCallEnded flow
+      }
+    } catch {
+      // Silently handle errors in post-call processing
+    } finally {
+      // Clean up the callId after processing (success or failure)
+      this.currentCallId = undefined;
+      // Clear stored call state after normal call end
+      this.clearCallState();
+    }
+  }
+
+  private async createCall(payload: CallCreateDto) {
+    const response = await this.http.post('/api/v1/simulation/call', {
+      ...payload,
+    });
+
+    return response.data as CallDTO;
+  }
+
+  async uploadPdfSlides(file: File | Blob): Promise<string> {
+    try {
+      const checkResult = checkFile(file, MAX_PDF_FILE_SIZE, ALLOWED_PDF_MIME_TYPES);
+
+      if (checkResult !== true) {
+        throw new Error(checkResult);
+      }
+
+      // Check PDF page count before proceeding
+      const pageCount = await getPdfPageCount(file);
+      if (pageCount > MAX_PDF_PAGES) {
+        throw new Error(
+          `PDF has ${pageCount} pages, which exceeds the maximum allowed page count of ${MAX_PDF_PAGES} pages.`
+        );
+      }
+
+      const contentHash = await calculateHash(file);
+      const filename = file instanceof File ? file.name : (file as { filename?: string }).filename;
+
+      if (!filename) {
+        throw new Error(
+          'Invalid input: could not extract filename from the provided file or blob.'
+        );
+      }
+
+      if (/[^a-zA-Z0-9._ -]/.test(filename)) {
+        throw new Error(
+          'Filename contains invalid characters. Only English letters, numbers, dots, hyphens, and underscores are allowed.'
+        );
+      }
+
+      const { presignedPost, pdfId } = (
+        await this.http.post<RequestPdfUploadResponse>('/api/v1/pdfSlides/request-upload', {
+          contentHash,
+          filename,
+        })
+      ).data;
+
+      const formData = new FormData();
+      Object.entries(presignedPost.fields).forEach(([key, value]) => {
+        formData.append(key, value);
+      });
+      formData.append('file', file);
+
+      try {
+        await axios.post(presignedPost.url, formData, {
+          headers: {
+            'Content-Type': 'multipart/form-data',
+          },
+        });
+      } catch (uploadError) {
+        // S3 upload failed - clean up the MongoDB record created during request-upload
+        try {
+          await this.deleteSlideAnalysis(pdfId);
+        } catch (deleteError) {
+          console.error('Failed to clean up PDF record after upload failure:', deleteError);
+        }
+        throw uploadError;
+      }
+
+      /*
+      // replace const { presignedPost, pdfId } with const { presignedPost, objectKey, pdfId }
+      // Uncomment this block if you are testing locally without AWS EventBridge
+      await this.http.post('/api/v1/pdfSlides/test-event-bridge', {
+        s3Name: objectKey,
+      });
+      */
+
+      return pdfId;
+    } catch (e) {
+      if (axios.isAxiosError(e)) {
+        console.error('Error uploading PDF slides:', e.response?.data?.message || e.message);
+      } else {
+        console.error(
+          'Error uploading PDF slides:',
+          e instanceof Error ? e.message : 'Unknown error'
+        );
+      }
+      throw e;
+    }
+  }
+
+  async getRecommendations(): Promise<RecommendationsResponseDto> {
+    try {
+      const res = await this.http.get<RecommendationsResponseDto>('/api/v1/recommendations');
+      return res.data;
+    } catch (e) {
+      if (axios.isAxiosError(e)) {
+        console.error('Error getting recommendations:', e.response?.data.message);
+      }
+      throw e;
+    }
+  }
+
+  async getSlidesAnalysis(queryParams: PdfSlidesAnalysisQueryDto): Promise<PdfSlidesDto[]> {
+    try {
+      const res = await this.http.get<PdfSlidesDto[]>('/api/v1/pdfSlides', {
+        params: queryParams,
+      });
+      return res.data;
+    } catch (e) {
+      if (axios.isAxiosError(e)) {
+        console.error('Error getting PDF slides analysis:', e.response?.data.message);
+      }
+      throw e;
+    }
+  }
+
+  async getSlideAnalysis(id: string): Promise<PdfSlideDto> {
+    try {
+      const res = await this.http.get<PdfSlideDto>(`/api/v1/pdfSlides/${id}`);
+      return res.data;
+    } catch (e) {
+      if (axios.isAxiosError(e)) {
+        console.error('Error getting PDF slide analysis by ID:', e.response?.data.message);
+      }
+      throw e;
+    }
+  }
+
+  async deleteSlideAnalysis(id: string): Promise<void> {
+    try {
+      await this.http.delete(`/api/v1/pdfSlides/${id}`);
+    } catch (e) {
+      if (axios.isAxiosError(e)) {
+        console.error('Error deleting PDF slide analysis:', e.response?.data.message);
+      }
+      throw e;
+    }
+  }
+
+  async checkPdfStatus(id: string): Promise<CheckPdfStatusResponse> {
+    try {
+      const res = await this.http.get<CheckPdfStatusResponse>(`/api/v1/pdfSlides/status/${id}`);
+      return res.data;
+    } catch (e) {
+      if (axios.isAxiosError(e)) {
+        console.error('Error checking PDF status:', e.response?.data.message);
+      }
+      throw e;
+    }
+  }
+
+  async getAssistantImages(): Promise<AssistantImageDto[]> {
+    try {
+      const res = await this.http.get<AssistantImageDto[]>('/api/v1/assistant-images');
+      return res.data;
+    } catch (e) {
+      if (axios.isAxiosError(e)) {
+        console.error('Error getting assistant images:', e.response?.data.message);
+      }
+      throw e;
+    }
+  }
+
+  /**
+   * Deletes a call and all associated data (messages, recommendations, recording).
+   * Only the owner of the call can delete it.
+   * @param callId - MongoDB ObjectId of the call
+   * @throws 404 if call not found
+   * @throws 403 if the caller is not the call owner
+   */
+  async deleteCall(callId: string): Promise<void> {
+    try {
+      await this.http.delete(`/api/v1/simulation/call/${callId}`);
+    } catch (e) {
+      if (axios.isAxiosError(e)) {
+        console.error('Error deleting call:', e.response?.data.message);
+      }
+      throw e;
+    }
+  }
+}