@burki.dev/sdk 0.1.0

package/README.md

@@ -0,0 +1,476 @@
+# Burki JavaScript/TypeScript SDK
+
+Official JavaScript/TypeScript SDK for the [Burki Voice AI Platform](https://burki.dev).
+
+## Installation
+
+```bash
+npm install @burki.dev/sdk
+```
+
+## Quick Start
+
+```typescript
+import { BurkiClient } from '@burki/sdk';
+
+// Initialize the client
+const client = new BurkiClient({ apiKey: 'your-api-key' });
+
+// List all assistants
+const assistants = await client.assistants.list();
+for (const assistant of assistants) {
+  console.log(`${assistant.id}: ${assistant.name}`);
+}
+
+// Create a new assistant
+const assistant = await client.assistants.create({
+  name: 'Support Bot',
+  description: 'Customer support assistant',
+  llmSettings: {
+    model: 'gpt-4o-mini',
+    temperature: 0.7,
+    systemPrompt: 'You are a helpful customer support agent.'
+  },
+  ttsSettings: {
+    provider: 'elevenlabs',
+    voiceId: 'rachel'
+  }
+});
+```
+
+## Features
+
+### Assistants
+
+```typescript
+// List assistants
+const assistants = await client.assistants.list();
+
+// List with options
+const activeAssistants = await client.assistants.list({
+  activeOnly: true,
+  includeStats: true,
+  limit: 50
+});
+
+// Get a specific assistant
+const assistant = await client.assistants.get(123);
+
+// Get an assistant by phone number
+const assistant = await client.assistants.getByPhone('+14155551234');
+
+// Create an assistant
+const assistant = await client.assistants.create({
+  name: 'My Bot',
+  llmSettings: { model: 'gpt-4o-mini' }
+});
+
+// Update an assistant
+const updated = await client.assistants.update(123, { name: 'Updated Bot' });
+
+// Quick status update
+await client.assistants.updateStatus(123, false); // Deactivate
+
+// Delete an assistant
+await client.assistants.delete(123);
+
+// Get assistant count
+const count = await client.assistants.getCount(true); // Active only
+
+// Export assistants
+const csvBlob = await client.assistants.export({ format: 'csv' });
+
+// Get cloned voices
+const voices = await client.assistants.getClonedVoices({ provider: 'elevenlabs' });
+
+// Get available LLM providers
+const providers = await client.assistants.getProviders();
+
+// Get organization info
+const orgInfo = await client.assistants.getOrganizationInfo();
+```
+
+### Calls
+
+```typescript
+// Initiate an outbound call
+const response = await client.calls.initiate({
+  fromPhoneNumber: '+14155559999',
+  toPhoneNumber: '+14155551234',
+  welcomeMessage: 'Hello! This is a follow-up call.',
+  agenda: 'Discuss the recent proposal'
+});
+
+// List calls with filters
+const calls = await client.calls.list({
+  status: 'completed',
+  dateFrom: '2026-01-01',
+  limit: 50
+});
+
+// Get call details
+const call = await client.calls.get(123);
+
+// Get call by SID
+const call = await client.calls.getBySid('CA123...');
+
+// Update call metadata
+await client.calls.updateMetadata(123, { customField: 'value' });
+
+// Get call transcripts
+const transcripts = await client.calls.getTranscripts(123);
+
+// Get transcripts by SID
+const transcripts = await client.calls.getTranscriptsBySid('CA123...');
+
+// Export transcripts
+const txtBlob = await client.calls.exportTranscripts(123, { format: 'txt' });
+
+// Get call recordings
+const recordings = await client.calls.getRecordings(123);
+
+// Get recording URL
+const url = client.calls.getRecordingUrl(123, 456);
+
+// Get call metrics
+const metrics = await client.calls.getMetrics(123);
+
+// Get chat messages (LLM conversation)
+const messages = await client.calls.getMessages(123);
+
+// Get webhook logs
+const logs = await client.calls.getWebhookLogs(123);
+
+// Terminate an ongoing call
+await client.calls.terminate('CA123...');
+
+// Get analytics
+const analytics = await client.calls.getAnalytics('7d');
+
+// Get stats
+const stats = await client.calls.getStats();
+
+// Search calls
+const results = await client.calls.search('customer name');
+
+// Export calls
+const csvBlob = await client.calls.export({ format: 'csv', status: 'completed' });
+```
+
+### Phone Numbers
+
+```typescript
+// List phone numbers
+const numbers = await client.phoneNumbers.list();
+
+// Search available numbers
+const available = await client.phoneNumbers.search({
+  provider: 'twilio',
+  countryCode: 'US',
+  areaCode: '415'
+});
+
+// Purchase a number
+const result = await client.phoneNumbers.purchase({
+  phoneNumber: '+14155551234',
+  provider: 'twilio',
+  friendlyName: 'Support Line'
+});
+
+// Release a number
+await client.phoneNumbers.release('+14155551234');
+
+// Assign to an assistant
+await client.phoneNumbers.assign(123, { assistantId: 456 });
+
+// Unassign from assistant
+await client.phoneNumbers.unassign(123);
+
+// Get available countries
+const countries = await client.phoneNumbers.getCountries('telnyx');
+
+// Diagnose connection (Telnyx)
+const diagnosis = await client.phoneNumbers.diagnose('+14155551234');
+
+// Get webhook configuration
+const webhooks = await client.phoneNumbers.getWebhooks('+14155551234');
+
+// Update webhooks
+await client.phoneNumbers.updateWebhooks({
+  phoneNumber: '+14155551234',
+  voiceWebhookUrl: 'https://example.com/voice'
+});
+
+// Sync verified caller IDs
+await client.phoneNumbers.syncVerifiedCallerIds();
+
+// Add a verified caller ID
+await client.phoneNumbers.addVerifiedCallerId({
+  phoneNumber: '+14155551234',
+  friendlyName: 'My Phone'
+});
+```
+
+### Documents (RAG)
+
+```typescript
+// Upload a document (browser)
+const file = new File(['content'], 'knowledge.pdf', { type: 'application/pdf' });
+const document = await client.documents.upload(123, file, 'knowledge.pdf');
+
+// Upload from URL
+const document = await client.documents.uploadFromUrl({
+  assistantId: 123,
+  url: 'https://example.com/document.pdf'
+});
+
+// List documents
+const documents = await client.documents.list(123);
+
+// Check processing status
+const status = await client.documents.getStatus(456);
+
+// Reprocess a document
+await client.documents.reprocess(456);
+
+// Delete a document
+await client.documents.delete(456);
+```
+
+### Tools
+
+```typescript
+// List tools
+const tools = await client.tools.list();
+
+// Get a tool
+const tool = await client.tools.get(123);
+
+// Create an HTTP tool
+const tool = await client.tools.create({
+  name: 'check_inventory',
+  toolType: 'http',
+  description: 'Check product inventory',
+  httpConfig: {
+    method: 'GET',
+    url: 'https://api.example.com/inventory'
+  }
+});
+
+// Update a tool
+await client.tools.update(123, { description: 'Updated description' });
+
+// Delete a tool
+await client.tools.delete(123);
+
+// Assign tool to assistant
+await client.tools.assign(123, 456);
+
+// Unassign tool from assistant
+await client.tools.unassign(123, 456);
+
+// Discover AWS Lambda functions
+const lambdas = await client.tools.discoverLambda('us-east-1');
+```
+
+### SMS
+
+```typescript
+// Send an SMS
+const response = await client.sms.send({
+  fromPhoneNumber: '+14155559999',
+  toPhoneNumber: '+14155551234',
+  message: 'Hello from Burki!',
+  queue: true // Use rate-limited queue
+});
+
+// Get message status
+const status = await client.sms.getStatus('msg_123');
+
+// Cancel a queued message
+await client.sms.cancel('msg_123');
+
+// Get queue statistics
+const stats = await client.sms.getQueueStats();
+
+// List conversations
+const conversations = await client.sms.listConversations({
+  assistantId: 123,
+  status: 'active'
+});
+
+// Get a conversation
+const conversation = await client.sms.getConversation('conv_123');
+
+// Get messages in a conversation
+const messages = await client.sms.getMessages('conv_123');
+
+// Get related conversations (voice + SMS unified session)
+const related = await client.sms.getRelatedConversations('conv_123');
+
+// Delete/archive a conversation
+await client.sms.deleteConversation('conv_123');
+
+// Export a conversation
+const txtBlob = await client.sms.exportConversation('conv_123', { format: 'txt' });
+```
+
+### Campaigns
+
+```typescript
+// List campaigns
+const campaigns = await client.campaigns.list({ status: 'running' });
+
+// Get a campaign
+const campaign = await client.campaigns.get(123);
+
+// Create a campaign
+const campaign = await client.campaigns.create({
+  name: 'Outreach Campaign',
+  assistantId: 123,
+  contacts: [
+    { phoneNumber: '+14155551234', name: 'John', variables: { company: 'Acme' } },
+    { phoneNumber: '+14155555678', name: 'Jane' }
+  ],
+  settings: {
+    maxConcurrentCalls: 5,
+    callsPerMinute: 10
+  }
+});
+
+// Update a campaign
+await client.campaigns.update(123, { name: 'Updated Campaign' });
+
+// Delete a campaign
+await client.campaigns.delete(123);
+
+// Start the campaign
+await client.campaigns.start(123);
+
+// Pause the campaign
+await client.campaigns.pause(123);
+
+// Resume the campaign
+await client.campaigns.resume(123);
+
+// Cancel the campaign
+await client.campaigns.cancel(123);
+
+// Get campaign progress
+const progress = await client.campaigns.getProgress(123);
+
+// Get contacts
+const contacts = await client.campaigns.getContacts(123, { status: 'pending' });
+
+// Add contacts
+await client.campaigns.addContacts(123, [
+  { phoneNumber: '+14155559999', name: 'New Contact' }
+]);
+```
+
+### Real-time Streaming (WebSocket)
+
+```typescript
+// Stream live transcripts during a call
+const stream = client.realtime.liveTranscript('CA123...');
+await stream.connect();
+
+for await (const event of stream) {
+  if (event.type === 'transcript') {
+    console.log(`[${event.speaker}]: ${event.content}`);
+  } else if (event.type === 'call_status') {
+    console.log(`Call status: ${event.status}`);
+  }
+}
+
+stream.disconnect();
+```
+
+```typescript
+// Stream campaign progress updates
+const stream = client.realtime.campaignProgress(123);
+await stream.connect();
+
+for await (const event of stream) {
+  if (event.type === 'progress') {
+    console.log(`Progress: ${event.completedContacts}/${event.totalContacts}`);
+  } else if (event.type === 'campaign_completed') {
+    console.log(`Campaign completed! Success rate: ${event.successRate}%`);
+  }
+}
+```
+
+## Configuration
+
+### Custom Base URL
+
+```typescript
+const client = new BurkiClient({
+  apiKey: 'your-api-key',
+  baseUrl: 'https://custom.burki.dev'
+});
+```
+
+### Timeout Settings
+
+```typescript
+const client = new BurkiClient({
+  apiKey: 'your-api-key',
+  timeout: 60000 // 60 seconds
+});
+```
+
+## Error Handling
+
+```typescript
+import {
+  BurkiClient,
+  AuthenticationError,
+  NotFoundError,
+  ValidationError,
+  RateLimitError,
+  ServerError,
+  WebSocketError
+} from '@burki/sdk';
+
+const client = new BurkiClient({ apiKey: 'your-api-key' });
+
+try {
+  const assistant = await client.assistants.get(999);
+} catch (error) {
+  if (error instanceof AuthenticationError) {
+    console.error('Invalid API key');
+  } else if (error instanceof NotFoundError) {
+    console.error('Assistant not found');
+  } else if (error instanceof ValidationError) {
+    console.error(`Validation error: ${error.message}`);
+  } else if (error instanceof RateLimitError) {
+    console.error(`Rate limited. Retry after ${error.retryAfter} seconds`);
+  } else if (error instanceof ServerError) {
+    console.error('Server error occurred');
+  } else if (error instanceof WebSocketError) {
+    console.error('WebSocket connection error');
+  }
+}
+```
+
+## TypeScript Support
+
+This SDK is written in TypeScript and provides full type definitions for all models and methods.
+
+```typescript
+import type {
+  Assistant,
+  AssistantCreateParams,
+  Call,
+  CallListParams,
+  Campaign,
+  PhoneNumber,
+  Tool,
+  // ... and more
+} from '@burki/sdk';
+```
+
+## License
+
+MIT License