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
• Getting Started
• Configuration
• API Reference
  • Connection Management
  • Application Management
  • Recording Management
  • Fact Management
  • Event Handling
• Types
• Examples
• Error Handling

Installation

The SDK can be used directly in your project. The Socket.IO client is bundled with the SDK.

Getting Started

Basic Setup

import AiQaSdk from '@aiqa/sdk';

// Initialize the SDK
const sdk = new AiQaSdk(
  'app-id-123',
  'app-secret-xyz',
  'https://api.solutionson.ai/'
);

// Connect to the service, then attach listeners
sdk.connect();

sdk.on('connect', () => {
  console.log('Connected to AIQA service');
});

sdk.on('error', (error) => {
  console.error('Connection error:', error);
});

Configuration

SDK Initialization

new AiQaSdk(applicationId, applicationSecret, url?)

API Reference

Connection Management

connect()

Establishes a WebSocket connection to the AIQA service.

sdk.connect();

disconnect()

Closes the WebSocket connection.

sdk.disconnect();

Application Management

getApplication()

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.

const application = await sdk.getApplication();

Fact Management

addFact(fact)

Adds a fact to the active application (Promise-based).

Parameters:

• fact: ApplicationFactInput

  {
    id: string;
    question: string;
    expected_answer: any;
    answer_format: { type: 'STRING' };
  }

const isMatched = await sdk.addFact({
  id: 'fact-123',
  question: 'Do you agree?',
  expected_answer: 'Yes',
  answer_format: { type: 'STRING' }
});

getFacts()

Retrieves all facts for the application (Promise-based).

const facts = await sdk.getFacts();

Recording Management

startRecording()

Starts audio recording (Promise-based).

const started = await sdk.startRecording();

stopRecording()

Stops audio recording (Promise-based).

const stopped = await sdk.stopRecording();

isRecordingNow()

Checks if recording is currently active (Promise-based).

const isRecording = await sdk.isRecordingNow();

Event Handling

on(eventName, callback)

Registers an event listener. Call connect() before on().

Available Events:

• 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 }

sdk.connect();
sdk.on('connect', () => {
  console.log('Connected');
});

sdk.on('authenticated', (application) => {
  console.log('Authenticated:', application);
});

off(eventName, callback?)

Removes an event listener.

sdk.off('connect');

Types

Application

type Application = {
  application_id: string;
  client_name: string;
  client_phone_number: string;
  agent_id: string;
  agent_first_name: string;
  agent_last_name: string;
}

ApplicationFact

type ApplicationFact = ApplicationFactInput & {
  ai_answer?: any;
  question_status: 'searching' | 'asked' | 'not_asked';
  verification_status: 'processing' | 'matched' | 'unmatched';
}

ApplicationFactInput

type ApplicationFactInput = {
  id: 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 }[];
  };
  category_id?: string;
  category_name?: string;
  language?: string;
  critical?: boolean;
  is_skipped?: boolean;
}

FactUpdateEvent

type FactUpdateEvent = {
  fact_id: string;
  question_id?: string;
  status: 'asked' | 'answered_detected' | 'agent_answered' | 'verification_pending' | 'verified' | 'failed';
  detectedAnswer?: any;
  agentAnswer?: any;
  verifiedAnswer?: any;
}

Examples

Complete Example: Recording Session

import AiQaSdk from '@aiqa/sdk';

// Initialize SDK
const sdk = new AiQaSdk(
  'application-id-123',
  'application-secret-xyz',
  'https://api.solutionson.ai/'
);

sdk.connect();

sdk.on('connect', async () => {
  console.log('Connected!');

  try {
    const application = await sdk.getApplication();
    console.log('Application loaded:', application.application_id);

    // Start recording
    await sdk.startRecording();
    console.log('Recording started');

    // Add a fact
    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.stopRecording();
    console.log('Recording stopped');

  } catch (error) {
    console.error('Error:', error);
  }
});

sdk.on('error', (error) => {
  console.error('SDK Error:', error);
});

Error Handling

All methods are Promise-based. Use try/catch for errors.

try {
  const application = await sdk.getApplication();
  console.log('Success:', application);
} catch (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 as rejected promises
4. Network Issues: Handled through reconnection events

Version Requirements

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]