@ctchealth/plato-sdk 0.0.9 → 0.0.11

package/README.md

@@ -8,11 +8,12 @@ The Plato SDK provides a simple and type-safe way to integrate with the Plato pl
 
 ## Features
 
-- 🎭 Create AI personas with customizable professional profiles and personalities
-- 🗣️ Real-time voice interactions with AI assistants
-- 📊 Comprehensive event system for call management
-- 🔒 Type-safe API with full TypeScript support
-- 🎯 Medical training simulation configuration
+- Create AI personas with customizable professional profiles and personalities
+- Real-time voice interactions with AI assistants
+- Comprehensive event system for call management
+- Type-safe API with full TypeScript support
+- Medical training simulation configuration
+- Simulation persistence and recovery across page reloads
 
 ## Installation
 
@@ -64,16 +65,10 @@ const simulation = await client.createSimulation({
   },
   presentation: 'Oral tablets, 10 tablets per pack',
   scenario: 'Discussing treatment options for an elderly patient with chronic arthritis',
-  objectives: [
-    'Demonstrate efficacy of Ibuprofen in pain management',
-    'Highlight safety profile and contraindications',
-    'Encourage patient adherence',
-  ],
-  anticipatedObjections: [
-    'Concerns about gastrointestinal side effects',
-    'Preference for lower-cost generic alternatives',
-    'Potential interactions with other medications',
-  ],
+  objectives:
+    'Demonstrate efficacy of Ibuprofen in pain management Highlight safety profile and contraindications Encourage patient adherence',
+  anticipatedObjections:
+    'Concerns about gastrointestinal side effects Preference for lower-cost generic alternatives Potential interactions with other medications',
 });
 
 // Check the simulation status - If simulation creation phase is equals to FINISHED, the simulation is ready to use
@@ -161,6 +156,7 @@ Retrieves detailed information about a completed call, including transcript, sum
 - `metric1Value`, `metric2Value`, `metric3Value`: Values for each metric
 - `createdAt`: Timestamp when the call was created
 - `endedAt`: Timestamp when the call ended
+- `callDurationMs`: Duration of the call in milliseconds
 - And other call-related fields
 
 **Example:**
@@ -221,6 +217,84 @@ const recordingUrl = await client.getCallRecording(call._id);
 console.log('Recording URL:', recordingUrl);
 ```
 
+##### uploadPdfSlides(file: File | Blob)
+
+Uploads a PDF file for slide analysis. The file will be uploaded to S3 and analyzed asynchronously.
+
+**Parameters:**
+
+- `file` (File | Blob): The PDF file to upload
+
+**Returns:** `Promise<UploadPdfSlidesResponseDto>` — An object containing:
+
+- `objectKey`: The S3 object key where the PDF was saved
+- `filename`: The original filename
+- `size`: The file size in bytes
+- `contentType`: The content type of the file
+
+**Example:**
+
+```typescript
+// Upload a PDF file from an input element
+const fileInput = document.querySelector('input[type="file"]') as HTMLInputElement;
+const file = fileInput.files?.[0];
+
+if (file) {
+  const result = await client.uploadPdfSlides(file);
+  console.log('PDF uploaded:', result.objectKey);
+  console.log('Original filename:', result.filename);
+}
+```
+
+##### getRecommendations()
+
+Retrieves recommendations based on the user's recent call performance. Analyzes up to 10 of the most recent calls to identify patterns and provide actionable insights.
+
+**Returns:** `Promise<RecommendationsResponseDto>` — An object containing:
+
+- `recommendations`: Array of recommendation objects, each with:
+  - `title`: Brief title of the recommendation
+  - `description`: Detailed, actionable description
+  - `priority`: Priority level (`'high'`, `'medium'`, or `'low'`)
+- `strengths`: Array of identified strengths, each with:
+  - `strength`: Description of the strength
+  - `frequency`: Number of calls where this strength appeared
+- `improvementAreas`: Array of areas needing improvement, each with:
+  - `area`: Description of the improvement area
+  - `frequency`: Number of calls where this weakness appeared
+- `summary`: A 2-3 sentence overall summary of performance trends
+- `callsAnalyzed`: Number of calls that were analyzed
+- `generatedAt`: Timestamp when the recommendations were generated
+
+**Example:**
+
+```typescript
+// Get personalized recommendations based on call history
+const recommendations = await client.getRecommendations();
+
+console.log(`Analyzed ${recommendations.callsAnalyzed} calls`);
+console.log('Summary:', recommendations.summary);
+
+// Display high-priority recommendations
+recommendations.recommendations
+  .filter(rec => rec.priority === 'high')
+  .forEach(rec => {
+    console.log(`[HIGH] ${rec.title}: ${rec.description}`);
+  });
+
+// Show recurring strengths
+recommendations.strengths.forEach(s => {
+  console.log(`Strength (${s.frequency} calls): ${s.strength}`);
+});
+
+// Show areas for improvement
+recommendations.improvementAreas.forEach(area => {
+  console.log(`Needs work (${area.frequency} calls): ${area.area}`);
+});
+```
+
+**Note:** This method requires the user to have at least one completed call. If no calls are found, a `BadRequestException` will be thrown.
+
 ## Checking Simulation Status
 
 You can check the current phase/status of a simulation using the `checkSimulationStatus` method. This is useful for polling the simulation creation process until it is ready or has failed.
@@ -233,6 +307,60 @@ console.log('Current phase:', status.phase); // e.g., 'FINISHED', 'ERROR', etc.
 - **Returns:** `{ phase: CreationPhase }` — The current phase of the simulation creation process.
 - **Typical usage:** Poll this method until the phase is `FINISHED` or `ERROR` before starting a call.
 
+## Simulation Persistence
+
+Simulations are persisted server-side and can be recovered after page reloads. Store the simulation ID client-side (e.g., localStorage) for quick recovery.
+
+### getSimulationDetails(simulationId: string)
+
+Retrieves detailed information about a simulation, including its original configuration.
+
+**Returns:** `Promise<SimulationDetailsDto>` containing:
+
+- `simulationId`: MongoDB ID
+- `phase`: Current creation phase
+- `assistantId`: The assistant ID (available after creation)
+- `configuration`: Original `CreateSimulationDto`
+- `createdAt`, `updatedAt`: Timestamps
+
+**Example:**
+
+```typescript
+// Store simulation ID after creation
+const simulation = await client.createSimulation(config);
+localStorage.setItem('plato_simulation_id', simulation.simulationId);
+
+// Recover simulation on page reload
+const simulationId = localStorage.getItem('plato_simulation_id');
+if (simulationId) {
+  const details = await client.getSimulationDetails(simulationId);
+
+  if (details.phase !== CreationPhase.ERROR) {
+    // Resume polling if still in progress
+    if (details.phase !== CreationPhase.FINISHED) {
+      startPolling(details.simulationId);
+    }
+  } else {
+    localStorage.removeItem('plato_simulation_id');
+  }
+}
+```
+
+### getUserSimulations()
+
+Retrieves all simulations for the authenticated user. Useful when the simulation ID is not stored locally.
+
+**Returns:** `Promise<Array<{ simulationId: string; phase: CreationPhase }>>`
+
+**Example:**
+
+```typescript
+const simulations = await client.getUserSimulations();
+const inProgress = simulations.find(
+  sim => sim.phase !== CreationPhase.FINISHED && sim.phase !== CreationPhase.ERROR
+);
+```
+
 ## Event System
 
 The SDK provides a comprehensive event system for managing voice calls:
@@ -277,8 +405,8 @@ interface CreateSimulationDto {
   product: ProductConfig;
   presentation?: string;
   scenario: string;
-  objectives?: string[];
-  anticipatedObjections?: string[];
+  objectives?: string;
+  anticipatedObjections?: string;
   trainingConfiguration: TrainingConfigurationDto;
 }
 ```
@@ -298,6 +426,69 @@ interface CharacterCreateDto {
 }
 ```
 
+### SimulationDetailsDto
+
+Detailed simulation information returned by `getSimulationDetails()`:
+
+```typescript
+interface SimulationDetailsDto {
+  simulationId: string;
+  phase: CreationPhase;
+  assistantId: string;
+  configuration?: CreateSimulationDto;
+  createdAt: Date;
+  updatedAt: Date;
+}
+```
+
+### CreationPhase
+
+Enum representing the simulation creation phases:
+
+```typescript
+enum CreationPhase {
+  STARTING = 'STARTING',
+  CORE = 'CORE',
+  BOUNDARIES = 'BOUNDARIES',
+  SPEECH_AND_THOUGHT = 'SPEECH_AND_THOUGHT',
+  CONVERSATION_EVOLUTION = 'CONVERSATION_EVOLUTION',
+  MEMORY = 'MEMORY',
+  FINISHED = 'FINISHED',
+  ERROR = 'ERROR',
+}
+```
+
+### RecommendationsResponseDto
+
+Response object from `getRecommendations()`:
+
+```typescript
+interface RecommendationsResponseDto {
+  recommendations: RecommendationItemDto[];
+  strengths: PerformancePatternDto[];
+  improvementAreas: ImprovementAreaDto[];
+  summary: string;
+  callsAnalyzed: number;
+  generatedAt: Date;
+}
+
+interface RecommendationItemDto {
+  title: string;
+  description: string;
+  priority: 'high' | 'medium' | 'low';
+}
+
+interface PerformancePatternDto {
+  strength: string;
+  frequency: number;
+}
+
+interface ImprovementAreaDto {
+  area: string;
+  frequency: number;
+}
+```
+
 ## Error Handling
 
 The SDK throws errors for invalid configurations and API failures:

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@ctchealth/plato-sdk",
-  "version": "0.0.9",
+  "version": "0.0.11",
   "dependencies": {
     "tslib": "^2.3.0",
     "@vapi-ai/web": "2.1.8",
@@ -11,5 +11,6 @@
   "typings": "./src/index.d.ts",
   "publishConfig": {
     "access": "public"
-  }
-}
+  },
+  "types": "./src/index.d.ts"
+}

package/src/index.d.ts

@@ -0,0 +1,14 @@
+/**
+ * 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.
+ */
+export * from './lib/plato-sdk';

package/src/index.js

@@ -0,0 +1,18 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+const tslib_1 = require("tslib");
+/**
+ * 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.
+ */
+tslib_1.__exportStar(require("./lib/plato-sdk"), exports);
+//# sourceMappingURL=index.js.map

package/src/index.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"index.js","sourceRoot":"","sources":["../../../../libs/plato-sdk/src/index.ts"],"names":[],"mappings":";;;AAAA;;;;;;;;;;;;GAYG;AACH,0DAAgC"}

package/src/lib/plato-intefaces.d.ts

@@ -0,0 +1,269 @@
+/**
+ * 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.
+ */
+export declare enum YearOfExperience {
+    '1-5' = "1-5 years",
+    '6-10' = "6-10 years",
+    '11-20' = "16-20 years",
+    '20+' = "20+ years"
+}
+export declare enum PracticeType {
+    Private = "Private Practice",
+    Hospital = "Hospital",
+    AcademicMedicalCenter = "Academic Medical Center",
+    Clinic = "Clinic"
+}
+export declare enum SegmentType {
+    Traditionalist = "The Traditionalist",
+    Innovator = "The Innovator",
+    PatientOrientedPhysician = "The Patient-Oriented Physician",
+    FinanciallyDrivenPrescriber = "The Financially-Driven Prescriber",
+    EvidencePurist = "The Evidence-Purist",
+    CostConsciousPrescriber = "The Cost-Conscious Prescriber"
+}
+export declare enum AssistantVoiceGender {
+    Male = "Male",
+    Female = "Female"
+}
+export declare class PersonalityAndBehaviourDto {
+    riskTolerance: number;
+    researchOrientation: number;
+    recognitionNeed: number;
+    brandLoyalty: number;
+    patientEmpathy: number;
+}
+export declare class ProfessionalProfileDto {
+    practiceSettings: string;
+    yearOfExperience: number;
+    specialityAndDepartment: string;
+    location: string;
+}
+export declare class ContextDto {
+    subSpecialityOrTherapyFocus: string;
+    typicalPatientMix: string;
+    keyClinicalDrivers: string;
+}
+export declare class CharacterCreateDto {
+    name: string;
+    professionalProfile: ProfessionalProfileDto;
+    segment: SegmentType;
+    personalityAndBehaviour: PersonalityAndBehaviourDto;
+    context: ContextDto;
+    assistantGender?: AssistantVoiceGender;
+}
+export declare class ProductConfig {
+    name: string;
+    description: string;
+}
+export declare class CreateSimulationDto {
+    persona: CharacterCreateDto;
+    product: ProductConfig;
+    presentation?: string;
+    scenario: string;
+    objectives?: string;
+    anticipatedObjections?: string;
+}
+export type RecordingsLimit = 5 | 10 | 25;
+export declare class SimulationRecordingsQueryDto {
+    limit?: RecordingsLimit;
+    page?: number;
+    sort?: SortOrder;
+}
+export declare enum SortOrder {
+    ASC = "asc",
+    DESC = "desc"
+}
+export declare enum RecordingStatus {
+    STARTED = "STARTED",
+    PROCESSING = "PROCESSING",
+    FINISHED = "FINISHED",
+    FAILED = "FAILED"
+}
+export declare class SimulationRecordingsDto {
+    _id: string;
+    createdAt: Date;
+    recordingStatus?: RecordingStatus;
+}
+export interface CallCreateDto {
+    /**
+     * Call ID obtained
+     */
+    callId: string;
+    /**
+     * Call Assistant ID
+     */
+    assistantId: string;
+}
+export interface CallDTO {
+    /**
+     * call ID
+     */
+    _id: string;
+    /**
+     *  call ID obtained
+     */
+    callId: string;
+    /**
+     *  call User ID
+     */
+    platoUserId: string;
+    /**
+     *  call Assistant ID
+     */
+    assistantId: string;
+    /**
+     *  call summary of the conversation
+     */
+    summary: string;
+    /**
+     *  call transcript of the conversation
+     */
+    transcript: string;
+    /**
+     *  call feedback provided by the user
+     */
+    feedback: string;
+    /**
+     * Success Evaluation returned by model
+     */
+    successEvaluation: boolean;
+    /**
+     *  call Recording URL
+     */
+    recordingUrl: string;
+    /**
+     * Status of recording processing (e.g., 'STARTED', 'PROCESSING', 'FINISHED', 'FAILED')
+     */
+    recordingStatus?: RecordingStatus;
+    /**
+     * Date and Time of the creation of the message
+     */
+    createdAt: Date;
+    /**
+     * Date and Time of the creation of the message
+     */
+    endedAt: Date;
+    /**
+     * Rating of the call given by the user
+     */
+    rating: number;
+    /**
+     * Main strenghts of the user conversation based on the analysis of the AI
+     */
+    strengths: Array<string>;
+    /**
+     * Main weak points of the user conversation based on the analysis of the AI
+     */
+    weaknesses: Array<string>;
+    /**
+     * Name of Metric for the AI feedback report
+     */
+    metric1: string;
+    /**
+     * Name of Metric for the AI feedback report
+     */
+    metric2: string;
+    /**
+     * Name of Metric for the AI feedback report
+     */
+    metric3: string;
+    /**
+     * AI feedback value for Metric 1
+     */
+    metric1Value: number;
+    /**
+     * AI feedback value for Metric 2
+     */
+    metric2Value: number;
+    /**
+     * AI feedback value for Metric 3
+     */
+    metric3Value: number;
+    /**
+     * AI feedback value for the call score
+     */
+    score?: number;
+    /**
+     * Defines if the calls will be consider for the memory feature
+     */
+    inMemory: boolean;
+    /**
+     * Duration of the call in milliseconds
+     */
+    callDurationMs?: number;
+}
+export declare enum CreationPhase {
+    STARTING = "STARTING",
+    CORE = "CORE",
+    BOUNDARIES = "BOUNDARIES",
+    SPEECH_AND_THOUGHT = "SPEECH_AND_THOUGHT",
+    CONVERSATION_EVOLUTION = "CONVERSATION_EVOLUTION",
+    MEMORY = "MEMORY",
+    FINISHED = "FINISHED",
+    ERROR = "ERROR"
+}
+/**
+ * Response DTO for PDF file upload.
+ */
+export interface UploadPdfSlidesResponseDto {
+    /**
+     * The S3 object key where the PDF was saved
+     */
+    objectKey: string;
+    /**
+     * The original filename
+     */
+    filename: string;
+    /**
+     * The file size in bytes
+     */
+    size: number;
+    /**
+     * The content type of the file
+     */
+    contentType: string;
+}
+export interface SimulationDetailsDto {
+    simulationId: string;
+    phase: CreationPhase;
+    assistantId: string;
+    configuration?: CreateSimulationDto;
+    createdAt: Date;
+    updatedAt: Date;
+}
+export declare enum RecommendationPriority {
+    HIGH = "high",
+    MEDIUM = "medium",
+    LOW = "low"
+}
+export interface RecommendationItemDto {
+    title: string;
+    description: string;
+    priority: RecommendationPriority;
+}
+export interface PerformancePatternDto {
+    strength: string;
+    frequency: number;
+}
+export interface ImprovementAreaDto {
+    area: string;
+    frequency: number;
+}
+export interface RecommendationsResponseDto {
+    recommendations: RecommendationItemDto[];
+    strengths: PerformancePatternDto[];
+    improvementAreas: ImprovementAreaDto[];
+    summary: string;
+    callsAnalyzed: number;
+    generatedAt: Date;
+}