@ctchealth/plato-sdk 0.0.19 → 0.0.21

package/README.md

@@ -17,7 +17,7 @@ All API requests require authentication via a client token. Pass a pre-signed JW
 - Comprehensive event system for call management
 - Type-safe API with full TypeScript support
 - Medical training simulation configuration
-- Simulation persistence and recovery across page reloads
+- Simulation persistence across page reloads
 
 ## Installation
 
@@ -165,6 +165,8 @@ Creates a new medical training simulation. It may take a few minutes for the sim
 
 **Returns:** `Promise<{ simulationId: string, phase: CreationPhase }>`
 
+**Learning mode (`isLearning`):** Pass `isLearning: true` and their calls are excluded from `getRecommendations()` and have no post call. Defaults to `false`.
+
 ##### startCall(simulationId: string)
 
 Starts a voice call with the AI persona for the specified simulation.
@@ -475,7 +477,7 @@ await client.deleteSimulation('507f1f77bcf86cd799439011');
 
 ##### getRecommendations()
 
-Retrieves recommendations based on the user's recent call performance. Analyzes the 5 most recent calls using a sliding window of 3 calls to identify patterns and provide actionable insights. Calls shorter than 2 minutes are excluded from analysis. No new recommendations are generated if fewer than 3 eligible calls are available.
+Retrieves recommendations based on the user's recent call performance. Analyzes the 5 most recent calls using a sliding window of 3 calls to identify patterns and provide actionable insights. Calls shorter than 2 minutes are excluded from analysis, as are calls made against learning-mode simulations (`isLearning: true`). No new recommendations are generated if fewer than 3 eligible calls are available.
 
 **Returns:** `Promise<RecommendationsResponseDto>` — An object containing:
 
@@ -597,6 +599,7 @@ const inProgress = simulations.find(
 );
 ```
 
+<!--
 ## Call Recovery
 
 The SDK automatically handles call recovery in case of page refreshes or browser closures during active calls. This ensures that call data is never lost and all calls get properly processed by the backend, even if the page is refreshed while a call is in progress.
@@ -898,6 +901,7 @@ A: The `recoverAbandonedCall()` method returns `true` when a call is recovered.
 **Q: What if the backend is down during recovery?**
 
 A: The recovery attempt is logged and the stored state is cleared to prevent infinite retries. The SDK continues working normally. Recovery failures are graceful and don't break the app.
+-->
 
 ## Event System
 
@@ -912,6 +916,7 @@ The SDK provides a comprehensive event system for managing voice calls:
 - `message`: Triggered when a message is received (contains transcript and metadata)
 - `volume-level`: Triggered with volume level updates (number)
 - `error`: Triggered when an error occurs
+- `call-ended-reason`: Triggered just before `call-end` with the reason the call was terminated (e.g. silence timeout). Use this to show the user a contextual message immediately
 - `call-details-ready`: Triggered when post-call processing completes and call details are available (includes full `CallDTO` with transcript, summary, ratings, and evaluation)
 
 ### Event Usage
@@ -937,6 +942,29 @@ call.on('call-details-ready', callDetails => {
 });
 ```
 
+## Detecting Why a Call Ended
+
+The `call-ended-reason` event fires **just before** `call-end`, giving you the reason the call was terminated in time to update the UI before any post-call processing begins.
+
+### Usage
+
+```typescript
+call.on('call-ended-reason', ({ reason, isInactivity }) => {
+  // reason      — raw string from the platform, e.g. "silence-timed-out"
+  // isInactivity — true when reason contains "silence" or "inactivity"
+});
+```
+
+### Known Reason Values
+
+| `reason`              | `isInactivity` | When it occurs                                          |
+| --------------------- | -------------- | ------------------------------------------------------- |
+| `silence-timed-out`   | `true`         | No speech detected within the configured silence window |
+| `customer-ended-call` | `false`        | The user clicked "End Call"                             |
+| `pipeline-error`      | `false`        | An internal platform error terminated the call          |
+
+> **Note:** The `reason` field reflects the raw value from the underlying voice platform. New values may be introduced over time. Always handle unknown reasons gracefully by falling back to a generic message.
+
 ## Automatic Post-Call Feedback
 
 The SDK automatically fetches detailed call information after each call ends and completes post-call processing. This includes comprehensive feedback such as transcript, summary, evaluation metrics, strengths, weaknesses, and ratings.
@@ -1116,10 +1144,22 @@ call.on('call-details-ready', callDetails => {
 
 ### Timing Considerations
 
+- `call-ended-reason`: Fires immediately before `call-end`, with the reason the call stopped
 - `call-end`: Fires immediately when the call stops
 - `call-details-ready`: Fires after backend processing completes (typically 2-5 seconds after call ends)
 
-Plan your UX accordingly—show a loading/processing state between these two events.
+Plan your UX accordingly—show a contextual end message on `call-ended-reason`, then a loading/processing state until `call-details-ready` arrives.
+
+### Call Duration and Data Availability
+
+The quality of data returned in `call-details-ready` depends on the duration of the call:
+
+| Call duration     | Behaviour                                                                                                                                                                                                                                                                   |
+| ----------------- | --------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
+| **< ~15 seconds** | `call-details-ready` fires immediately after `call-end` with whatever the database currently holds. Fields like `transcript`, `summary`, `score`, `strengths`, and `weaknesses` will typically be empty or zero — the call was too short to generate a meaningful analysis. |
+| **≥ ~15 seconds** | The SDK polls the backend until Vapi's post-call analysis is ready (transcript present), then emits `call-details-ready` with the fully populated `CallDTO`.                                                                                                                |
+
+> **Note:** The ~15 second threshold accounts for the Vapi connection handshake (typically 1–5 seconds) plus a minimum amount of conversation time required for analysis to be generated. Always handle empty fields gracefully regardless of call length.
 
 ## Data Types
 
@@ -1167,6 +1207,7 @@ interface CreateSimulationDto {
   imageId: string;
   avatarLanguage: AvatarLanguage;
   pdfSlideId?: string;
+  isLearning?: boolean;
 }
 ```
 
@@ -1426,6 +1467,31 @@ try {
 }
 ```
 
+### Concurrency Limit Error
+
+When the platform has reached its maximum number of simultaneous active calls, `startCall()` throws a `CallConcurrencyLimitError`. This is a platform-wide limit, not user-specific. You should catch this specifically and show the user a clear message rather than a generic error.
+
+```typescript
+import { CallConcurrencyLimitError } from 'plato-sdk';
+
+const handleStartCall = async (simulationId: string) => {
+  try {
+    const call = await platoClient.startCall(simulationId);
+
+    call.on('call-start', () => setCallActive(true));
+    call.on('call-end', () => setCallActive(false));
+  } catch (error) {
+    if (error instanceof CallConcurrencyLimitError) {
+      setErrorMessage(
+        'The platform has reached its maximum number of simultaneous calls. Please try again in a moment.'
+      );
+    } else {
+      setErrorMessage('Failed to start call. Please try again.');
+    }
+  }
+};
+```
+
 ## Support
 
 For support and questions, please contact the development team.

package/package.json

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

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/{constants.ts → constants.d.ts}

@@ -11,6 +11,6 @@
  *
  * For internal use only.
  */
-export const MAX_PDF_FILE_SIZE = 20 * 1024 * 1024; // 20MB
-export const ALLOWED_PDF_MIME_TYPES = ['application/pdf'];
-export const MAX_PDF_PAGES = 100;
+export declare const MAX_PDF_FILE_SIZE: number;
+export declare const ALLOWED_PDF_MIME_TYPES: string[];
+export declare const MAX_PDF_PAGES = 100;

package/src/lib/constants.js

@@ -0,0 +1,20 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.MAX_PDF_PAGES = exports.ALLOWED_PDF_MIME_TYPES = exports.MAX_PDF_FILE_SIZE = void 0;
+/**
+ * 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.
+ */
+exports.MAX_PDF_FILE_SIZE = 20 * 1024 * 1024; // 20MB
+exports.ALLOWED_PDF_MIME_TYPES = ['application/pdf'];
+exports.MAX_PDF_PAGES = 100;
+//# sourceMappingURL=constants.js.map

package/src/lib/constants.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"constants.js","sourceRoot":"","sources":["../../../../../libs/plato-sdk/src/lib/constants.ts"],"names":[],"mappings":";;;AAAA;;;;;;;;;;;;GAYG;AACU,QAAA,iBAAiB,GAAG,EAAE,GAAG,IAAI,GAAG,IAAI,CAAC,CAAC,OAAO;AAC7C,QAAA,sBAAsB,GAAG,CAAC,iBAAiB,CAAC,CAAC;AAC7C,QAAA,aAAa,GAAG,GAAG,CAAC"}

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

@@ -0,0 +1,391 @@
+/**
+ * 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 enum AvatarLanguage {
+    English = "en",
+    German = "de",
+    Spanish = "es",
+    Italian = "it",
+    French = "fr",
+    Arabic = "ar",
+    Russian = "ru"
+}
+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;
+    scenario: string;
+    objectives?: string;
+    anticipatedObjections?: string;
+    imageId: string;
+    avatarLanguage: AvatarLanguage;
+    pdfSlideId?: string;
+    isLearning?: boolean;
+}
+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 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 {
+    QUEUED = "QUEUED",
+    STARTING = "STARTING",
+    BUILD_HEADER = "BUILD_HEADER",
+    SEGMENT_SELECTED = "SEGMENT_SELECTED",
+    BUILD_CONTEXT = "BUILD_CONTEXT",
+    BUILD_PSYCHOGRAPHICS = "BUILD_PSYCHOGRAPHICS",
+    BUILD_OBJECTIVES = "BUILD_OBJECTIVES",
+    PERSONA_ASSEMBLED = "PERSONA_ASSEMBLED",
+    CORE = "CORE",
+    BOUNDARIES = "BOUNDARIES",
+    SPEECH_AND_THOUGHT = "SPEECH_AND_THOUGHT",
+    CONVERSATION_EVOLUTION = "CONVERSATION_EVOLUTION",
+    MEMORY = "MEMORY",
+    OBJECTION_HANDLING = "OBJECTION_HANDLING",
+    PERFORMANCE_EVALUATION = "PERFORMANCE_EVALUATION",
+    BEHAVIORAL_FRAMEWORKS = "BEHAVIORAL_FRAMEWORKS",
+    FINISHED = "FINISHED",
+    ERROR = "ERROR"
+}
+/**
+ * Presigned POST data for S3 upload.
+ */
+export interface PresignedPost {
+    url: string;
+    fields: Record<string, string>;
+}
+/**
+ * Response for requesting a PDF upload.
+ */
+export interface RequestPdfUploadResponse {
+    presignedPost: PresignedPost;
+    objectKey: string;
+    pdfId: string;
+}
+/**
+ * Persona description within simulation briefing
+ */
+export interface PersonaDescriptionDto {
+    summary: string;
+    details: string[];
+}
+/**
+ * Scenario context within simulation briefing
+ */
+export interface ScenarioContextDto {
+    summary: string;
+    steps: string[];
+}
+/**
+ * Training objectives within simulation briefing
+ */
+export interface TrainingObjectiveDto {
+    summary: string;
+    keyObjectives: string[];
+}
+/**
+ * Complete simulation briefing structure generated by multi-agent system
+ */
+export interface SimulationBriefingDto {
+    objectiveTag: string;
+    personaDescription: PersonaDescriptionDto;
+    scenarioContext: ScenarioContextDto;
+    trainingObjective: TrainingObjectiveDto;
+}
+export interface SimulationDetailsDto {
+    simulationId: string;
+    phase: CreationPhase;
+    assistantId: string;
+    configuration?: CreateSimulationDto;
+    simulationBriefing?: SimulationBriefingDto;
+    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;
+}
+export declare enum PdfSlidesStatus {
+    PENDING = "pending",
+    STARTED = "started",
+    PROCESSING = "processing",
+    OVERVIEW = "overview",
+    COMPLETED = "completed",
+    FAILED = "failed"
+}
+export interface CheckPdfStatusResponse {
+    status: PdfSlidesStatus;
+    processedBatches: number[];
+    totalBatches?: number;
+}
+export declare enum PdfSlidesSortField {
+    CREATED_AT = "createdAt",
+    FILENAME = "originalFilename",
+    TOTAL_SLIDES = "totalSlides"
+}
+export declare class PdfSlidesAnalysisQueryDto {
+    limit?: RecordingsLimit;
+    page?: number;
+    sort?: SortOrder;
+    sortBy?: PdfSlidesSortField;
+}
+export interface SlideAnalysis {
+    slideNumber: number;
+    title?: string;
+    textExtraction?: string;
+    visualDescription?: string;
+}
+export interface PdfSlidesDto {
+    _id: string;
+    status: PdfSlidesStatus;
+    originalFilename: string;
+    totalSlides?: number;
+    lessonOverview?: string;
+    createdAt: Date;
+    updatedAt: Date;
+}
+export interface PdfSlideDto {
+    _id: string;
+    status: PdfSlidesStatus;
+    originalFilename: string;
+    totalSlides?: number;
+    lessonOverview?: string;
+    slideAnalysis?: SlideAnalysis[];
+    createdAt: Date;
+    updatedAt: Date;
+}
+export interface AssistantImageDto {
+    _id: string;
+    imageUrl: string;
+}
+/**
+ * Represents the state of an active call stored in localStorage for recovery purposes.
+ * Used to detect and recover abandoned calls after page refresh.
+ */
+export interface ActiveCallState {
+    /**
+     * MongoDB ID of the call record
+     */
+    callId: string;
+    /**
+     * External call provider ID
+     */
+    externalCallId: string;
+    /**
+     * ID of the simulation this call belongs to
+     */
+    simulationId: string;
+    /**
+     * ISO 8601 timestamp when the call was started
+     */
+    startedAt: string;
+    /**
+     * Schema version for future compatibility
+     */
+    version: number;
+}