@ctchealth/plato-sdk 0.0.8 → 0.0.9

package/README.md

@@ -0,0 +1,322 @@
+# Plato SDK
+
+A TypeScript SDK for interacting with the Plato API to create and manage AI-powered medical training simulations.
+
+## Overview
+
+The Plato SDK provides a simple and type-safe way to integrate with the Plato platform, allowing you to create medical training simulations with AI personas and manage voice-based interactions.
+
+## 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
+
+## Installation
+
+```bash
+npm install plato-sdk
+```
+
+## Quick Start
+
+```typescript
+import { PlatoApiClient } from 'plato-sdk';
+
+// Initialize the client
+const client = new PlatoApiClient({
+  baseUrl: 'https://your-plato-api.com',
+  token: 'your-api-token',
+  user: 'test@test.test',
+});
+
+// Create a simulation
+const simulation = await client.createSimulation({
+  persona: {
+    professionalProfile: {
+      location: 'City Hospital, New York',
+      practiceSettings: 'Outpatient Clinic',
+      yearOfExperience: 12,
+      specialityAndDepartment: 'Cardiology',
+    },
+    segment: SegmentType.CostConsciousPrescriber,
+    assistantGender: AssistantVoiceGender.Male,
+    name: 'Dr Vegapunk',
+    personalityAndBehaviour: {
+      riskTolerance: 40,
+      researchOrientation: 70,
+      recognitionNeed: 60,
+      brandLoyalty: 55,
+      patientEmpathy: 80,
+    },
+    context: {
+      subSpecialityOrTherapyFocus: 'Hypertension management',
+      typicalPatientMix: 'Elderly with comorbidities',
+      keyClinicalDrivers: 'Reducing cardiovascular risk',
+    },
+  },
+  product: {
+    name: 'Ibuprofen 1000mg',
+    description:
+      'A nonsteroidal anti-inflammatory drug used to reduce pain, inflammation, and fever',
+  },
+  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',
+  ],
+});
+
+// Check the simulation status - If simulation creation phase is equals to FINISHED, the simulation is ready to use
+// If the simulation creation phase is ERROR the simulation creation failed and you need to retry creating a new one
+// tip: you can also check the simulation status periodically using a polling mechanism
+const status = await client.getSimulationStatus(simulation.simulationId);
+
+// Start a voice call
+const call = await client.startCall(simulation.simulationId);
+
+// Listen to call events
+call.on('call-start', () => {
+  console.log('Call started');
+});
+
+call.on('message', message => {
+  console.log('Message received:', message.transcript);
+});
+
+call.on('call-end', () => {
+  console.log('Call ended');
+});
+
+// Stop the call when done
+call.stopCall();
+```
+
+## API Reference
+
+### PlatoApiClient
+
+The main class for interacting with the Plato API.
+
+#### Constructor
+
+```typescript
+new PlatoApiClient(config: ApiClientConfig)
+```
+
+**Parameters:**
+
+- `config.baseUrl` (string): The base URL of the Plato API
+- `config.token` (string): Your API authentication token
+- `config.user` (string): Your user identifier
+
+#### Methods
+
+##### createSimulation(params: CreateSimulationDto)
+
+Creates a new medical training simulation. It may take a few minutes for the simulation to be ready for use.
+
+**Returns:** `Promise<{ simulationId: string, phase: CreationPhase }>`
+
+##### startCall(simulationId: string)
+
+Starts a voice call with the AI persona for the specified simulation.
+
+**Returns:** Object with:
+
+- `stopCall()`: Function to end the call
+- `callId`: Unique identifier for the call
+- `on<K>(event: K, listener: CallEventListener<K>)`: Subscribe to call events
+- `off<K>(event: K, listener: CallEventListener<K>)`: Unsubscribe from call events
+
+##### getCallDetails(callId: string)
+
+Retrieves detailed information about a completed call, including transcript, summary, recording URL, ratings, and evaluation metrics.
+
+**Parameters:**
+
+- `callId` (string): The MongoDB `_id` of the call
+
+**Returns:** `Promise<CallDTO>` — An object containing:
+
+- `_id`: MongoDB ID of the call
+- `summary`: Summary of the conversation
+- `transcript`: Full transcript of the call
+- `recordingUrl`: URL to access the call recording
+- `rating`: User-provided rating (0-5)
+- `successEvaluation`: Boolean indicating if the call was successful
+- `score`: Overall score for the call
+- `strengths`: Array of identified strengths
+- `weaknesses`: Array of identified weaknesses
+- `metric1`, `metric2`, `metric3`: Evaluation metric names
+- `metric1Value`, `metric2Value`, `metric3Value`: Values for each metric
+- `createdAt`: Timestamp when the call was created
+- `endedAt`: Timestamp when the call ended
+- And other call-related fields
+
+**Example:**
+
+```typescript
+// After a call has ended, retrieve its details
+const callDetails = await client.getCallDetails(call._id);
+console.log('Call Summary:', callDetails.summary);
+```
+
+##### getCallRecordings(queryParams: SimulationRecordingsQueryDto)
+
+Retrieves a paginated list of call recordings for the authenticated user.
+
+**Parameters:**
+
+- `queryParams` (SimulationRecordingsQueryDto): Query parameters for filtering and pagination
+  - `limit` (optional): Number of recordings per page (`5`, `10`, or `25`)
+  - `page` (optional): Page number for pagination
+  - `sort` (optional): Sort order (`'asc'` or `'desc'`)
+
+**Returns:** `Promise<SimulationRecordingsDto[]>` — An array of recording objects, each containing:
+
+- `_id`: MongoDB ID of the call
+- `createdAt`: Timestamp when the call was created
+- `recordingStatus`: Status of the recording (`'STARTED'`, `'PROCESSING'`, `'FINISHED'`, or `'FAILED'`)
+
+**Example:**
+
+```typescript
+// Get the 10 most recent call recordings
+const recordings = await client.getCallRecordings({
+  limit: 10,
+  page: 1,
+  sort: 'desc',
+});
+
+recordings.forEach(recording => {
+  console.log(`Call ${recording._id} - Status: ${recording.recordingStatus}`);
+});
+```
+
+##### getCallRecording(callId: string)
+
+Retrieves the recording URL for a specific call.
+
+**Parameters:**
+
+- `callId` (string): The MongoDB `_id` of the call
+
+**Returns:** `Promise<string>` — The URL to access the call recording
+
+**Example:**
+
+```typescript
+// Get the recording URL for a specific call
+const recordingUrl = await client.getCallRecording(call._id);
+console.log('Recording URL:', recordingUrl);
+```
+
+## 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.
+
+```typescript
+const status = await client.checkSimulationStatus(simulation.simulationId);
+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.
+
+## Event System
+
+The SDK provides a comprehensive event system for managing voice calls:
+
+### Available Events
+
+- `call-start`: Triggered when a call begins
+- `call-end`: Triggered when a call ends
+- `speech-start`: Triggered when speech detection starts
+- `speech-end`: Triggered when speech detection ends
+- `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
+
+### Event Usage
+
+```typescript
+// Subscribe to events
+call.on('message', message => {
+  console.log('Transcript:', message.transcript);
+  console.log('Type:', message.transcriptType); // 'final' or 'partial'
+});
+
+call.on('volume-level', level => {
+  console.log('Volume level:', level);
+});
+
+call.on('error', error => {
+  console.error('Call error:', error);
+});
+```
+
+## Data Types
+
+### CreateSimulationDto
+
+Configuration for creating a simulation:
+
+```typescript
+interface CreateSimulationDto {
+  persona: CharacterCreateDto;
+  product: ProductConfig;
+  presentation?: string;
+  scenario: string;
+  objectives?: string[];
+  anticipatedObjections?: string[];
+  trainingConfiguration: TrainingConfigurationDto;
+}
+```
+
+### CharacterCreateDto
+
+AI persona configuration:
+
+```typescript
+interface CharacterCreateDto {
+  name: string;
+  professionalProfile: ProfessionalProfileDto;
+  segment: SegmentType;
+  personalityAndBehaviour: PersonalityAndBehaviourDto;
+  context: ContextDto;
+  assistantGender?: AssistantVoiceGender;
+}
+```
+
+## Error Handling
+
+The SDK throws errors for invalid configurations and API failures:
+
+```typescript
+try {
+  const client = new PlatoApiClient({
+    baseUrl: 'https://api.plato.com',
+    token: 'your-token',
+    user: 'your-user',
+  });
+
+  const simulation = await client.createSimulation(simulationConfig);
+  const call = await client.startCall(simulation.simulationId);
+} catch (error) {
+  console.error('Error:', error.message);
+}
+```
+
+## Support
+
+For support and questions, please contact the development team.

package/eslint.config.cjs

@@ -0,0 +1,121 @@
+const { defineConfig, globalIgnores } = require('eslint/config');
+const path = require('path');
+
+const typescriptEslintEslintPlugin = require('@typescript-eslint/eslint-plugin');
+const globals = require('globals');
+const tsParser = require('@typescript-eslint/parser');
+const jest = require('eslint-plugin-jest');
+const js = require('@eslint/js');
+const headers = require('eslint-plugin-headers');
+const { FlatCompat } = require('@eslint/eslintrc');
+const baseRules = require('../../eslint-config-base.cjs');
+
+const compat = new FlatCompat({
+  baseDirectory: __dirname,
+  recommendedConfig: js.configs.recommended,
+  allConfig: js.configs.all,
+});
+
+module.exports = defineConfig([
+  globalIgnores([
+    '**/.eslintrc.js',
+    'src/index.d.ts',
+    'scripts/db-migrations/archived/**/*',
+    '**/*.spec.ts',
+    '**/*.config.js',
+    '**/*.config.cjs',
+    '**/jest.config.ts',
+  ]),
+  {
+    files: ['**/*.ts'],
+    plugins: {
+      headers,
+    },
+    rules: {
+      'headers/header-format': [
+        'error',
+        {
+          source: 'string',
+          content: `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.`,
+          style: 'jsdoc',
+          trailingNewlines: 1,
+          preservePragmas: false,
+        },
+      ],
+    },
+  },
+  {
+    extends: compat.extends(
+      'plugin:@typescript-eslint/recommended',
+      'plugin:@typescript-eslint/recommended-requiring-type-checking',
+      'plugin:@typescript-eslint/strict'
+    ),
+
+    files: ['**/*.ts'],
+    ignores: ['**/*.json', '**/*.spec.ts'],
+
+    plugins: {
+      '@typescript-eslint': typescriptEslintEslintPlugin,
+    },
+
+    languageOptions: {
+      globals: {
+        ...globals.node,
+        ...globals.jest,
+      },
+
+      parser: tsParser,
+      ecmaVersion: 10,
+      sourceType: 'module',
+
+      parserOptions: {
+        project: path.join(__dirname, 'tsconfig.lib.json'),
+      },
+    },
+
+    rules: {
+      ...baseRules.rules, // shared rules
+      // project-specific rules
+      '@typescript-eslint/ban-ts-comment': 'warn',
+      '@typescript-eslint/interface-name-prefix': 'off',
+      '@typescript-eslint/explicit-function-return-type': 'warn',
+      '@typescript-eslint/promise-function-async': ['error'],
+      '@typescript-eslint/no-floating-promises': 'error',
+      '@typescript-eslint/await-thenable': 'error',
+      semi: ['error', 'always'],
+      '@typescript-eslint/unbound-method': 'error',
+      'keyword-spacing': ['error'],
+      '@typescript-eslint/restrict-template-expressions': 'error',
+      '@typescript-eslint/prefer-regexp-exec': 'warn',
+      '@typescript-eslint/require-await': 'warn',
+      '@typescript-eslint/no-non-null-assertion': 'error',
+      '@typescript-eslint/no-unnecessary-condition': 'warn',
+      '@typescript-eslint/prefer-ts-expect-error': 'warn',
+      '@typescript-eslint/prefer-nullish-coalescing': 'off',
+      'space-infix-ops': 'off',
+    },
+  },
+  {
+    files: ['**/*.spec.ts'],
+    extends: compat.extends('plugin:jest/recommended'),
+
+    plugins: {
+      jest,
+    },
+
+    rules: {
+      '@typescript-eslint/unbound-method': 'off',
+      'jest/unbound-method': 'error',
+    },
+  },
+]);

package/jest.config.ts

@@ -0,0 +1,10 @@
+export default {
+  displayName: 'plato-sdk',
+  preset: '../../jest.preset.js',
+  testEnvironment: 'node',
+  transform: {
+    '^.+\\.[tj]s$': ['ts-jest', { tsconfig: '<rootDir>/tsconfig.spec.json' }],
+  },
+  moduleFileExtensions: ['ts', 'js', 'html'],
+  coverageDirectory: '../../coverage/libs/plato-sdk',
+};

package/package.json

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

package/project.json

@@ -0,0 +1,24 @@
+{
+  "name": "plato-sdk",
+  "$schema": "../../node_modules/nx/schemas/project-schema.json",
+  "sourceRoot": "libs/plato-sdk/src",
+  "projectType": "library",
+  "tags": [],
+  "targets": {
+    "build": {
+      "executor": "@nx/js:tsc",
+      "outputs": ["{options.outputPath}"],
+      "options": {
+        "outputPath": "dist/libs/plato-sdk",
+        "main": "libs/plato-sdk/src/index.ts",
+        "tsConfig": "libs/plato-sdk/tsconfig.lib.json",
+        "assets": ["libs/plato-sdk/*.md"]
+      }
+    },
+    "nx-release-publish": {
+      "options": {
+        "packageRoot": "dist/{projectRoot}"
+      }
+    }
+  }
+}