@aiqa/sdk 0.0.0

package/src/README.md

@@ -0,0 +1,729 @@
+# AIQA SDK
+
+A TypeScript/JavaScript SDK for interacting with the AIQA WebSocket service. This SDK provides methods for managing applications, recording audio, and tracking facts during conversations.
+
+## Table of Contents
+
+- [Installation](#installation)
+- [Getting Started](#getting-started)
+- [Configuration](#configuration)
+- [API Reference](#api-reference)
+  - [Connection Management](#connection-management)
+  - [Application Management](#application-management)
+  - [Recording Management](#recording-management)
+  - [Fact Management](#fact-management)
+  - [Event Handling](#event-handling)
+- [Types](#types)
+- [Examples](#examples)
+- [Error Handling](#error-handling)
+
+## Installation
+
+The SDK can be used directly in your project. Make sure you have the SDK source files available and include Socket.IO client library in your HTML:
+
+```html
+<script src="https://cdn.socket.io/4.5.4/socket.io.min.js"></script>
+```
+
+## Getting Started
+
+### Basic Setup
+
+```typescript
+import AiQaSdk from './sdk-src';
+
+// Initialize the SDK
+const sdk = new AiQaSdk({
+  url: 'ws://api.solutionson.ai/',
+  enableLogging: true
+});
+
+// Set up event handlers
+sdk.on('connect', () => {
+  console.log('Connected to AIQA service');
+});
+
+sdk.on('error', (error) => {
+  console.error('Connection error:', error);
+});
+
+// Connect to the service
+sdk.connect();
+```
+
+## Configuration
+
+### SDKConfig Interface
+
+```typescript
+interface SDKConfig {
+  url?: string;              // WebSocket server URL (default: 'ws://localhost:3025')
+  jwtToken?: string;          // JWT token for authentication
+  path?: string;              // WebSocket path (default: '/ws')
+  enableLogging?: boolean;    // Enable/disable logging (default: true)
+}
+```
+
+### Configuration Methods
+
+#### Constructor Configuration
+
+```typescript
+const sdk = new AiQaSdk({
+  url: 'https://api.solutionson.ai/',
+  jwtToken: 'your-jwt-token',
+  path: '/ws',
+  enableLogging: false
+});
+```
+
+#### Runtime Configuration
+
+```typescript
+sdk.configure({
+  url: 'https://api.solutionson.ai/',
+  enableLogging: true
+});
+```
+
+## API Reference
+
+### Connection Management
+
+#### `connect()`
+
+Establishes a WebSocket connection to the AIQA service.
+
+```typescript
+sdk.connect();
+```
+
+#### `disconnect()`
+
+Closes the WebSocket connection.
+
+```typescript
+sdk.disconnect();
+```
+
+#### `isAlive(callback)`
+
+Checks if the WebSocket connection is alive (callback-based).
+
+```typescript
+sdk.isAlive(({ isAlive, error }) => {
+  if (error) {
+    console.error('Error checking connection:', error);
+  } else {
+    console.log('Connection is alive:', isAlive);
+  }
+});
+```
+
+#### `isAliveAsync()`
+
+Checks if the WebSocket connection is alive (Promise-based).
+
+```typescript
+try {
+  const isAlive = await sdk.isAliveAsync();
+  console.log('Connection is alive:', isAlive);
+} catch (error) {
+  console.error('Error checking connection:', error);
+}
+```
+
+### Application Management
+
+#### `createApplication(data, callback)`
+
+Creates a new application (callback-based).
+
+**Parameters:**
+- `data: TApplicationPayload`
+  ```typescript
+  {
+    policyNumber: string;
+    product: string;
+    insuredPhone: string;
+    clientName: string;
+  }
+  ```
+- `callback: (response: TResponse) => void`
+
+**Example:**
+```typescript
+sdk.createApplication({
+  policyNumber: 'POL-12345',
+  product: 'Insurance Product',
+  insuredPhone: '+1234567890',
+  clientName: 'John Doe'
+}, ({ application, error }) => {
+  if (error) {
+    console.error('Error creating application:', error);
+  } else {
+    console.log('Application created:', application);
+  }
+});
+```
+
+#### `createApplicationAsync(data)`
+
+Creates a new application (Promise-based).
+
+```typescript
+try {
+  const application = await sdk.createApplicationAsync({
+    policyNumber: 'POL-12345',
+    product: 'Insurance Product',
+    insuredPhone: '+1234567890',
+    clientName: 'John Doe'
+  });
+  console.log('Application created:', application);
+} catch (error) {
+  console.error('Error creating application:', error);
+}
+```
+
+#### `getApplication(id, callback)`
+
+Retrieves an application by ID (callback-based).
+
+```typescript
+sdk.getApplication('app-id-123', ({ application, error }) => {
+  if (error) {
+    console.error('Error getting application:', error);
+  } else {
+    console.log('Application:', application);
+  }
+});
+```
+
+#### `getApplicationAsync(id)`
+
+Retrieves an application by ID (Promise-based).
+
+```typescript
+try {
+  const application = await sdk.getApplicationAsync('app-id-123');
+  console.log('Application:', application);
+} catch (error) {
+  console.error('Error getting application:', error);
+}
+```
+
+#### `updateApplication(id, referenceId, callback)`
+
+Updates an application with a reference ID (callback-based).
+
+```typescript
+sdk.updateApplication('app-id-123', 'ref-456', ({ application, error }) => {
+  if (error) {
+    console.error('Error updating application:', error);
+  } else {
+    console.log('Application updated:', application);
+  }
+});
+```
+
+#### `updateApplicationAsync(id, referenceId)`
+
+Updates an application with a reference ID (Promise-based).
+
+```typescript
+try {
+  const application = await sdk.updateApplicationAsync('app-id-123', 'ref-456');
+  console.log('Application updated:', application);
+} catch (error) {
+  console.error('Error updating application:', error);
+}
+```
+
+#### `setActiveApplication(applicationId, callback)`
+
+Sets an application as active (callback-based).
+
+```typescript
+sdk.setActiveApplication('app-id-123', ({ applicationIsActive, error }) => {
+  if (error) {
+    console.error('Error setting active application:', error);
+  } else {
+    console.log('Application is active:', applicationIsActive);
+  }
+});
+```
+
+#### `setActiveApplicationAsync(applicationId)`
+
+Sets an application as active (Promise-based).
+
+```typescript
+try {
+  const isActive = await sdk.setActiveApplicationAsync('app-id-123');
+  console.log('Application is active:', isActive);
+} catch (error) {
+  console.error('Error setting active application:', error);
+}
+```
+
+#### `getActiveApplication(callback)`
+
+Gets the currently active application (callback-based).
+
+```typescript
+sdk.getActiveApplication(({ application, error }) => {
+  if (error) {
+    console.error('Error getting active application:', error);
+  } else {
+    console.log('Active application:', application);
+  }
+});
+```
+
+#### `getActiveApplicationAsync()`
+
+Gets the currently active application (Promise-based).
+
+```typescript
+try {
+  const application = await sdk.getActiveApplicationAsync();
+  console.log('Active application:', application);
+} catch (error) {
+  console.error('Error getting active application:', error);
+}
+```
+
+#### `resetActiveApplication(callback)`
+
+Resets (deactivates) the active application (callback-based).
+
+```typescript
+sdk.resetActiveApplication(({ applicationIsActive, error }) => {
+  if (error) {
+    console.error('Error resetting active application:', error);
+  } else {
+    console.log('Application is active:', applicationIsActive);
+  }
+});
+```
+
+#### `resetActiveApplicationAsync()`
+
+Resets (deactivates) the active application (Promise-based).
+
+```typescript
+try {
+  const isActive = await sdk.resetActiveApplicationAsync();
+  console.log('Application is active:', isActive);
+} catch (error) {
+  console.error('Error resetting active application:', error);
+}
+```
+
+### Recording Management
+
+#### `startRecording(callback)`
+
+Starts audio recording (callback-based).
+
+```typescript
+sdk.startRecording(({ recordingIsStarted, error }) => {
+  if (error) {
+    console.error('Error starting recording:', error);
+  } else {
+    console.log('Recording started:', recordingIsStarted);
+  }
+});
+```
+
+#### `startRecordingAsync()`
+
+Starts audio recording (Promise-based).
+
+```typescript
+try {
+  const started = await sdk.startRecordingAsync();
+  console.log('Recording started:', started);
+} catch (error) {
+  console.error('Error starting recording:', error);
+}
+```
+
+#### `stopRecording(callback)`
+
+Stops audio recording (callback-based).
+
+```typescript
+sdk.stopRecording(({ recordingIsStopped, error }) => {
+  if (error) {
+    console.error('Error stopping recording:', error);
+  } else {
+    console.log('Recording stopped:', recordingIsStopped);
+  }
+});
+```
+
+#### `stopRecordingAsync()`
+
+Stops audio recording (Promise-based).
+
+```typescript
+try {
+  const stopped = await sdk.stopRecordingAsync();
+  console.log('Recording stopped:', stopped);
+} catch (error) {
+  console.error('Error stopping recording:', error);
+}
+```
+
+#### `isRecordingNow(callback)`
+
+Checks if recording is currently active (callback-based).
+
+```typescript
+sdk.isRecordingNow(({ recordingIsActive, error }) => {
+  if (error) {
+    console.error('Error checking recording status:', error);
+  } else {
+    console.log('Recording is active:', recordingIsActive);
+  }
+});
+```
+
+#### `isRecordingNowAsync()`
+
+Checks if recording is currently active (Promise-based).
+
+```typescript
+try {
+  const isRecording = await sdk.isRecordingNowAsync();
+  console.log('Recording is active:', isRecording);
+} catch (error) {
+  console.error('Error checking recording status:', error);
+}
+```
+
+### Fact Management
+
+#### `addFact(fact, callback)`
+
+Adds a fact to the active application (callback-based).
+
+**Parameters:**
+- `fact: TApplicationFactPayload`
+  ```typescript
+  {
+    fact: {
+      id: string;
+      expected_answer: string;
+    };
+    applicationId: string;
+  }
+  ```
+- `callback: (response: TResponse) => void`
+
+**Example:**
+```typescript
+sdk.addFact({
+  fact: {
+    id: 'fact-123',
+    expected_answer: 'Yes'
+  },
+  applicationId: 'app-id-123'
+}, ({ factIsMatched, error }) => {
+  if (error) {
+    console.error('Error adding fact:', error);
+  } else {
+    console.log('Fact matched:', factIsMatched);
+  }
+});
+```
+
+#### `addFactAsync(fact)`
+
+Adds a fact to the active application (Promise-based).
+
+```typescript
+try {
+  const isMatched = await sdk.addFactAsync({
+    fact: {
+      id: 'fact-123',
+      expected_answer: 'Yes'
+    },
+    applicationId: 'app-id-123'
+  });
+  console.log('Fact matched:', isMatched);
+} catch (error) {
+  console.error('Error adding fact:', error);
+}
+```
+
+### Event Handling
+
+#### `on(eventName, callback)`
+
+Registers an event listener.
+
+**Available Events:**
+- `connect` - Fired when WebSocket connection is established
+- `disconnect` - Fired when WebSocket disconnects
+- `close` - Fired when WebSocket connection closes
+- `error` - Fired when an error occurs
+- `reconnect_attempt` - Fired during reconnection attempts
+- `reconnect_error` - Fired when reconnection fails
+- `reconnect_failed` - Fired when reconnection completely fails
+
+**Example:**
+```typescript
+sdk.on('connect', () => {
+  console.log('Connected to AIQA service');
+});
+
+sdk.on('disconnect', () => {
+  console.log('Disconnected from AIQA service');
+});
+
+sdk.on('error', (error) => {
+  console.error('Error occurred:', error);
+});
+```
+
+#### `off(eventName)`
+
+Removes an event listener.
+
+```typescript
+sdk.off('connect');
+```
+
+## Types
+
+### TApplicationPayload
+
+```typescript
+type TApplicationPayload = {
+  policyNumber: string;
+  product: string;
+  insuredPhone: string;
+  clientName: string;
+}
+```
+
+### TApplication
+
+```typescript
+type TApplication = {
+  application_id: string;
+  adviser_id: string;
+  start_date: Date;
+  language: string;
+  rtStatus: string;
+  policy_number?: string;
+  insured_phone?: string;
+  client_name?: string;
+  utterances: TApplicationUtterance[];
+  facts: TApplicationFact[];
+}
+```
+
+### TApplicationUtterance
+
+```typescript
+type TApplicationUtterance = {
+  id: string;
+  application_id?: string;
+  call_id?: number;
+  order?: number;
+  is_agent?: boolean;
+  speaker?: number;
+  text?: string;
+  text_en?: string;
+  start_time?: number;
+  end_time?: number;
+  extra?: any;
+}
+```
+
+### TApplicationFact
+
+```typescript
+type TApplicationFact = {
+  id: string;
+  expected_answer: string;
+  actual_answer: string;
+  is_matched: boolean;
+}
+```
+
+### TApplicationFactPayload
+
+```typescript
+type TApplicationFactPayload = {
+  fact: {
+    id: string;
+    expected_answer: string;
+  };
+  applicationId: string;
+}
+```
+
+### TResponse
+
+```typescript
+type TResponse = {
+  isAlive?: boolean;
+  application?: TApplication | null;
+  applicationIsActive?: boolean;
+  factIsMatched?: boolean;
+  recordingIsStarted?: boolean;
+  recordingIsStopped?: boolean;
+  recordingIsActive?: boolean;
+  error?: Error;
+}
+```
+
+## Examples
+
+### Complete Example: Recording Session
+
+```typescript
+import AiQaSdk from './sdk-src';
+
+// Initialize SDK
+const sdk = new AiQaSdk({
+  url: 'ws://api.solutionson.ai/',
+  enableLogging: true
+});
+
+// Set up event handlers
+sdk.on('connect', async () => {
+  console.log('Connected!');
+  
+  try {
+    // Create an application
+    const application = await sdk.createApplicationAsync({
+      policyNumber: 'POL-12345',
+      product: 'Life Insurance',
+      insuredPhone: '+1234567890',
+      clientName: 'John Doe'
+    });
+    
+    console.log('Application created:', application.application_id);
+    
+    // Set as active
+    await sdk.setActiveApplicationAsync(application.application_id);
+    
+    // Start recording
+    await sdk.startRecordingAsync();
+    console.log('Recording started');
+    
+    // Add a fact
+    const factMatched = await sdk.addFactAsync({
+      fact: {
+        id: 'fact-1',
+        expected_answer: 'Yes, I understand'
+      },
+      applicationId: application.application_id
+    });
+    
+    console.log('Fact matched:', factMatched);
+    
+    // Stop recording
+    await sdk.stopRecordingAsync();
+    console.log('Recording stopped');
+    
+  } catch (error) {
+    console.error('Error:', error);
+  }
+});
+
+sdk.on('error', (error) => {
+  console.error('SDK Error:', error);
+});
+
+// Connect
+sdk.connect();
+```
+
+### Example: Using Callbacks
+
+```typescript
+const sdk = new AiQaSdk({
+  url: 'ws://localhost:3025'
+});
+
+sdk.on('connect', () => {
+  // Create application with callback
+  sdk.createApplication({
+    policyNumber: 'POL-12345',
+    product: 'Insurance',
+    insuredPhone: '+1234567890',
+    clientName: 'Jane Doe'
+  }, ({ application, error }) => {
+    if (error) {
+      console.error('Error:', error);
+      return;
+    }
+    
+    // Set as active
+    sdk.setActiveApplication(application.application_id, ({ applicationIsActive, error }) => {
+      if (error) {
+        console.error('Error:', error);
+        return;
+      }
+      
+      console.log('Application is active:', applicationIsActive);
+    });
+  });
+});
+
+sdk.connect();
+```
+
+## Error Handling
+
+All methods support error handling through callbacks or Promise rejections.
+
+### Callback-based Error Handling
+
+```typescript
+sdk.createApplication(data, ({ application, error }) => {
+  if (error) {
+    // Handle error
+    console.error('Error:', error);
+    return;
+  }
+  
+  // Handle success
+  console.log('Success:', application);
+});
+```
+
+### Promise-based Error Handling
+
+```typescript
+try {
+  const application = await sdk.createApplicationAsync(data);
+  // Handle success
+  console.log('Success:', application);
+} catch (error) {
+  // Handle error
+  console.error('Error:', error);
+}
+```
+
+### Common Error Scenarios
+
+1. **Connection Errors**: Fired through the `error` event
+2. **Version Mismatch**: Thrown when the server version is incompatible
+3. **Invalid Data**: Returned in the error field of callbacks or rejected promises
+4. **Network Issues**: Handled through reconnection events
+
+## Version Requirements
+
+The SDK requires the AIQA service to be at least version `1.0.0`. If the server version is incompatible, the connection will be automatically closed and an error will be thrown.
+
+## License
+
+[Add your license information here]
+