@aiqa/sdk 0.0.0 → 0.0.2

package/README.md

@@ -19,10 +19,8 @@ A TypeScript/JavaScript SDK for interacting with the AIQA WebSocket service. Thi
 
 ## 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>
+```
+npm install @aiqa/sdk
 ```
 
 ## Getting Started
@@ -30,16 +28,18 @@ The SDK can be used directly in your project. Make sure you have the SDK source
 ### Basic Setup
 
 ```typescript
-import AiQaSdk from './sdk-src';
+import AiQaSdk from '@aiqa/sdk';
 
 // Initialize the SDK
-const sdk = new AiQaSdk({
-  url: 'https://api.solutionson.ai/',
-  path: '/ws',
-  enableLogging: true
-});
+const sdk = new AiQaSdk(
+  'app-id-123',
+  'app-secret-xyz',
+  'https://api.solutionson.ai/'
+);
+
+// Connect to the service, then attach listeners
+sdk.connect();
 
-// Set up event handlers
 sdk.on('connect', () => {
   console.log('Connected to AIQA service');
 });
@@ -47,44 +47,14 @@ sdk.on('connect', () => {
 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: 'ws://api.solutionson.ai/',
-  jwtToken: 'your-jwt-token',
-  path: '/ws',
-  enableLogging: false
-});
-```
-
-#### Runtime Configuration
+### SDK Initialization
 
 ```typescript
-sdk.configure({
-  url: 'ws://api.solutionson.ai/',
-  enableLogging: true
-});
+new AiQaSdk(applicationId, applicationSecret, url?)
 ```
 
 ## API Reference
@@ -107,389 +77,106 @@ Closes the WebSocket connection.
 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);
-  }
-});
-```
+### Application Management
 
-#### `isAliveAsync()`
+#### `getApplication()`
 
-Checks if the WebSocket connection is alive (Promise-based).
+Returns the cached application loaded during authentication.
+If authentication hasn't completed yet, this throws. Use the `authenticated` event to know when it's ready.
 
 ```typescript
-try {
-  const isAlive = await sdk.isAliveAsync();
-  console.log('Connection is alive:', isAlive);
-} catch (error) {
-  console.error('Error checking connection:', error);
-}
+const application = await sdk.getApplication();
 ```
 
-### Application Management
+### Fact Management
 
-#### `createApplication(data, callback)`
+#### `addFact(fact)`
 
-Creates a new application (callback-based).
+Adds a fact to the active application (Promise-based).
 
 **Parameters:**
-- `data: TApplicationPayload`
+- `fact: ApplicationFactInput`
   ```typescript
   {
-    policyNumber: string;
-    product: string;
-    insuredPhone: string;
-    clientName: string;
+    id: string;
+    question: string;
+    expected_answer: any;
+    answer_format: { type: '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);
-  }
+const isMatched = await sdk.addFact({
+  id: 'fact-123',
+  question: 'Do you agree?',
+  expected_answer: 'Yes',
+  answer_format: { type: 'STRING' }
 });
 ```
 
-#### `setActiveApplicationAsync(applicationId)`
+#### `getFacts()`
 
-Sets an application as active (Promise-based).
+Retrieves all facts for the application (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);
-}
+const facts = await sdk.getFacts();
 ```
 
 ### 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()`
+#### `startRecording()`
 
 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);
-  }
-});
+const started = await sdk.startRecording();
 ```
 
-#### `stopRecordingAsync()`
+#### `stopRecording()`
 
 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);
-}
+const stopped = await sdk.stopRecording();
 ```
 
-#### `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()`
+#### `isRecordingNow()`
 
 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);
-}
+const isRecording = await sdk.isRecordingNow();
 ```
 
 ### Event Handling
 
 #### `on(eventName, callback)`
 
-Registers an event listener.
+Registers an event listener. Call `connect()` before `on()`.
 
 **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:**
+- `connect` - Socket.IO connection established
+- `disconnect` - Socket.IO connection closed
+- `close` - Socket.IO connection closed
+- `error` - Connection or socket error
+- `reconnect_attempt` - Socket.IO reconnection attempt
+- `reconnect_error` - Socket.IO reconnection error
+- `reconnect_failed` - Socket.IO reconnection failed
+- `authenticated` - Local event fired after successful authentication (provides Application object)
+- `app_version` - Server event with version requirements `{ min, max }`
+
 ```typescript
+sdk.connect();
 sdk.on('connect', () => {
-  console.log('Connected to AIQA service');
+  console.log('Connected');
 });
 
-sdk.on('disconnect', () => {
-  console.log('Disconnected from AIQA service');
-});
-
-sdk.on('error', (error) => {
-  console.error('Error occurred:', error);
+sdk.on('authenticated', (application) => {
+  console.log('Authenticated:', application);
 });
 ```
 
-#### `off(eventName)`
+#### `off(eventName, callback?)`
 
 Removes an event listener.
 
@@ -499,87 +186,58 @@ sdk.off('connect');
 
 ## Types
 
-### TApplicationPayload
+### Application
 
 ```typescript
-type TApplicationPayload = {
-  policyNumber: string;
-  product: string;
-  insuredPhone: string;
-  clientName: string;
-}
-```
-
-### TApplication
-
-```typescript
-type TApplication = {
+type Application = {
   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[];
+  client_name: string;
+  client_phone_number: string;
+  agent_id: string;
+  agent_first_name: string;
+  agent_last_name: string;
 }
 ```
 
-### TApplicationUtterance
+### ApplicationFact
 
 ```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;
+type ApplicationFact = ApplicationFactInput & {
+  ai_answer?: any;
+  question_status: 'searching' | 'asked' | 'not_asked';
+  verification_status: 'processing' | 'matched' | 'unmatched';
 }
 ```
 
-### TApplicationFact
+### ApplicationFactInput
 
 ```typescript
-type TApplicationFact = {
+type ApplicationFactInput = {
   id: string;
-  expected_answer: string;
-  actual_answer: string;
-  is_matched: boolean;
-}
-```
-
-### TApplicationFactPayload
-
-```typescript
-type TApplicationFactPayload = {
-  fact: {
-    id: string;
-    expected_answer: string;
+  question: string;
+  expected_answer: any;
+  answer_format: {
+    type: 'STRING' | 'NUMBER' | 'INT' | 'FLOAT' | 'BOOL' | 'LIST' | 'STRICT' | 'SINGLE_CHOICE' | 'MULTIPLE_CHOICES';
+    choices?: { key: string; text: string }[];
   };
-  applicationId: string;
+  category_id?: string;
+  category_name?: string;
+  language?: string;
+  critical?: boolean;
+  is_skipped?: boolean;
 }
 ```
 
-### TResponse
+### FactUpdateEvent
 
 ```typescript
-type TResponse = {
-  isAlive?: boolean;
-  application?: TApplication | null;
-  applicationIsActive?: boolean;
-  factIsMatched?: boolean;
-  recordingIsStarted?: boolean;
-  recordingIsStopped?: boolean;
-  recordingIsActive?: boolean;
-  error?: Error;
+type FactUpdateEvent = {
+  fact_id: string;
+  question_id?: string;
+  status: 'asked' | 'answered_detected' | 'agent_answered' | 'verification_pending' | 'verified' | 'failed';
+  detectedAnswer?: any;
+  agentAnswer?: any;
+  verifiedAnswer?: any;
 }
 ```
 
@@ -588,51 +246,44 @@ type TResponse = {
 ### Complete Example: Recording Session
 
 ```typescript
-import AiQaSdk from './sdk-src';
+import AiQaSdk from '@aiqa/sdk';
 
 // Initialize SDK
-const sdk = new AiQaSdk({
-  url: 'ws://localhost:3025',
-  enableLogging: true
-});
+const sdk = new AiQaSdk(
+  'application-id-123',
+  'application-secret-xyz',
+  'https://api.solutionson.ai/'
+);
+
+sdk.connect();
 
-// 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);
-    
+    const application = await sdk.getApplication();
+    console.log('Application loaded:', application.application_id);
+
     // Start recording
-    await sdk.startRecordingAsync();
+    await sdk.startRecording();
     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
+    const factMatched = await sdk.addFact({
+      id: 'q1',
+      question: 'What is your name?',
+      expected_answer: '',
+      answer_format: {
+        type: 'STRING'
+      }
     });
-    
+
     console.log('Fact matched:', factMatched);
-    
+
     // Stop recording
-    await sdk.stopRecordingAsync();
+    await sdk.stopRecording();
     console.log('Recording stopped');
-    
+
   } catch (error) {
     console.error('Error:', error);
   }
@@ -641,74 +292,17 @@ sdk.on('connect', async () => {
 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
+All methods are Promise-based. Use `try/catch` for errors.
 
 ```typescript
 try {
-  const application = await sdk.createApplicationAsync(data);
-  // Handle success
+  const application = await sdk.getApplication();
   console.log('Success:', application);
 } catch (error) {
-  // Handle error
   console.error('Error:', error);
 }
 ```
@@ -717,14 +311,13 @@ try {
 
 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
+3. **Invalid Data**: Returned as 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.
+The server emits an `app_version` payload with `{ min, max }` supported SDK versions. If the current SDK version is outside that range, the SDK disconnects and emits an `error` event.
 
 ## License
 
-[Add your license information here]
-
+MIT