VCC TypeScript SDK

A comprehensive TypeScript SDK for interacting with the VCC Backend Voice Assistant API. This SDK provides authentication via API keys, context management for calls, and support for multiple voice assistant providers.

Features

• 🔐 API Key Authentication - Secure authentication using API keys
• 🎯 Context Management - Automatic context building for calls with organization and customer data
• 🔌 Provider Agnostic - Support for VAPI and custom voice assistant providers
• 📊 Comprehensive Services - Full coverage of voice assistants, customers, organizations, and call logs
• 🛠️ TypeScript Support - Full type safety and IntelliSense support
• 📡 Auto Context Building - Intelligent context preparation before call initialization

Installation

npm install @hexalabs/vcc-sdk
# or
yarn add @hexalabs/vcc-sdk

📱 Using in Frontend? See FRONTEND_USAGE.md for React, Vue, and browser integration.

Quick Start

import VccSdk from '@hexalabs/vcc-sdk';

// Initialize the SDK
const sdk = new VccSdk({
  baseUrl: 'https://your-vcc-backend.com',
  apiKey: 'your-api-key',
  debug: true, // Optional: enable debug logging
});

// Test connection
const isConnected = await sdk.testConnection();
console.log('Connected:', isConnected);

Core Concepts

Call Context Management

The SDK automatically builds rich context for calls by gathering:

• Organization Data: Company info, industry, system prompts
• Assistant Configuration: Voice settings, prompts, capabilities
• Customer History: Previous interactions, preferences, call summaries
• Custom Context: Additional data you provide

Provider Support

The SDK supports multiple voice assistant providers:

• VAPI: Built-in support for VAPI integration
• Custom Providers: Extend with your own provider implementations

API Reference

Initialization

const sdk = new VccSdk({
  baseUrl: string;        // Your VCC backend URL
  apiKey: string;         // Your API key
  timeout?: number;       // Request timeout (default: 30000ms)
  debug?: boolean;        // Enable debug logging (default: false)
});

Call Management

Simple Call

// Direct call without context building
const response = await sdk.makeDirectCall({
  assistantId: 'assistant-uuid',
  customerPhone: '+1234567890',
  customerName: 'John Doe',
  message: 'Custom message', // Optional
});

Enhanced Call with Context

// Call with automatic context building
const result = await sdk.initializeCall({
  assistantId: 'assistant-uuid',
  customerPhone: '+1234567890',
  includeContext: true,
  customContext: {
    call_reason: 'appointment_reminder',
    urgency: 'high'
  },
});

console.log(result.callResponse); // Call details
console.log(result.context);     // Built context
console.log(result.provider);    // Provider used

Call Status and Control

// Get call status
const status = await sdk.getCallStatus('call-id', 'vapi');

// End call
await sdk.endCall('call-id', 'vapi');

Context Building

Build Call Context

const context = await sdk.buildCallContext({
  assistantId: 'assistant-uuid',
  customerPhone: '+1234567890',
  additionalContext: { key: 'value' }
});

Enhanced Context with History

const enhancedContext = await sdk.buildEnhancedContext({
  assistantId: 'assistant-uuid',
  customerPhone: '+1234567890',
  includeHistory: true,
  includeProducts: true,
  customContext: { campaign: 'summer_sale' }
});

Voice Assistant Management

// Create assistant
const assistant = await sdk.voiceAssistant.createAssistant({
  name: 'Sales Assistant',
  system_prompt: 'You are a sales rep for {{organization_name}}',
  first_message: 'Hello {{name}}, how can I help?',
  voice_id: 'voice-uuid'
});

// Get assistants
const assistants = await sdk.voiceAssistant.getOrganizationAssistants({
  is_active: true,
  page: 1,
  per_page: 20
});

// Update assistant
await sdk.voiceAssistant.updateAssistant('assistant-id', {
  system_prompt: 'Updated prompt'
});

Customer Management

// Create customer
const customer = await sdk.customer.create({
  name: 'John Doe',
  phone: '+1234567890',
  organization_id: 'org-uuid'
});

// Get customers
const customers = await sdk.customer.list({
  search: 'john',
  page: 1,
  per_page: 20
});

// Update customer
await sdk.customer.update('customer-id', {
  name: 'John Smith'
});

Organization Management

// Get organization
const org = await sdk.organization.getById('org-uuid');

// Get team members
const members = await sdk.organization.getTeamMembers();

// Get products
const products = await sdk.organization.getProducts({
  category: 'insurance'
});

Call Logs

// Get call logs
const logs = await sdk.callLog.list({
  assistant_id: 'assistant-uuid',
  started_after: '2024-01-01T00:00:00Z',
  page: 1,
  per_page: 50
});

// Get specific call log
const log = await sdk.callLog.getById('log-uuid');

// Get analytics
const analytics = await sdk.callLog.getAnalytics({
  date_from: '2024-01-01',
  date_to: '2024-01-31'
});

Phone Number Management

// Get phone numbers
const phoneNumbers = await sdk.voiceAssistant.getPhoneNumbers({
  is_assigned: false
});

// Assign phone number
await sdk.voiceAssistant.assignPhoneNumber('phone-id', 'assistant-id');

// Update server URL
await sdk.voiceAssistant.updateServerUrl('phone-id', 'https://your-server.com');

Voice Management

// Get available voices
const voices = await sdk.voiceAssistant.getVoices({
  provider: 'elevenlabs',
  gender: 'female'
});

// Add custom voice
await sdk.voiceAssistant.addVoice({
  id: 'custom-voice-id',
  name: 'Custom Voice',
  description: 'Custom voice description',
  gender: 'female',
  provider: 'elevenlabs'
});

Advanced Usage

Custom Providers

import { CallProviderInterface } from '@hexalabs/vcc-sdk';

class MyCustomProvider implements CallProviderInterface {
  name = 'my-provider';

  async initializeCall(context, config) {
    // Your provider implementation
    return callResponse;
  }

  async getCallStatus(callId) {
    // Implementation
  }

  async endCall(callId) {
    // Implementation
  }
}

// Add to SDK
sdk.addCallProvider('my-provider', new MyCustomProvider(config));

Context Enrichment

// Prepare customer with auto-creation
const { customer, isNewCustomer } = await sdk.prepareCustomerContext(
  '+1234567890',
  'org-uuid'
);

if (isNewCustomer) {
  console.log('Created new customer');
}

// Quick setup for common scenarios
const setup = await sdk.quickCallSetup({
  organizationId: 'org-uuid',
  assistantName: 'Sales Assistant',
  customerPhone: '+1234567890',
  customerName: 'John Doe'
});

Post-Call Processing

// Handle post-call updates
await sdk.handlePostCall({
  customerId: 'customer-uuid',
  callSummary: 'Customer interested in premium plan',
  additionalData: {
    lead_score: 85,
    next_action: 'send_proposal'
  }
});

Error Handling

The SDK provides structured error responses:

try {
  const result = await sdk.makeDirectCall({...});
} catch (error) {
  console.error('Error details:', error.details);
  console.error('Status code:', error.status_code);
  
  // Handle specific errors
  if (error.status_code === 401) {
    // Handle authentication error
  } else if (error.status_code === 404) {
    // Handle not found
  }
}

TypeScript Support

Full TypeScript definitions are included:

import { 
  CallContext, 
  Assistant, 
  Customer, 
  Organization,
  MakeCallResponse 
} from '@hexalabs/vcc-sdk';

const context: CallContext = await sdk.buildCallContext({...});
const assistant: Assistant = await sdk.voiceAssistant.getAssistant('id');

Examples

See the /examples directory for complete usage examples:

• Basic call scenarios
• Advanced context management
• Custom provider implementation
• Error handling patterns
• Real-world integration examples

Documentation

• 📚 GETTING_STARTED.md - Quick setup and first call
• 📱 FRONTEND_USAGE.md - React, Vue, and browser integration
• 🏗️ examples/ARCHITECTURE.md - Configuration flow and patterns
• 🔑 examples/CREDENTIALS.md - Credential reference
• 📖 examples/README.md - Example usage guide
• ⚡ Project README - Main project documentation

License

MIT License - see LICENSE file for details.

Support

For issues and questions:

• GitHub Issues: Repository Issues
• Documentation: API Docs
• Email: [email protected]