@trillet-ai/web-sdk/README.md

Trillet Web SDK for real-time audio communication with AI agents

# Trillet AI Web Calls SDK

The Trillet AI Web Calls SDK enables seamless integration of AI-powered voice and text interactions into web applications. This SDK provides a simple interface to connect with Trillet AI agents for real-time communication.

## Features

- 🎙️ Real-time voice interactions with AI agents
- 💬 Text-based conversations
- 🔒 Secure authentication options
- 📊 Audio visualization capabilities
- 🎯 Event-driven architecture
- 🔄 Real-time transcription
- 🌐 Browser compatibility checks

## Installation

```bash
npm install @trillet-ai/web-sdk
# or
yarn add @trillet-ai/web-sdk
```

## Quick Start

```typescript
import { TrilletAgent } from '@trillet-ai/web-sdk';

// Initialize the agent with API Key (Standard Method)
const agent = new TrilletAgent({
  apiKey: 'your-api-key',
  workspaceId: 'your-workspace-id',
  agentId: 'your-agent-id',
  mode: 'voice', // 'voice' or 'text'

  // Optional parameters
  variables: {
    customVar1: 'value1',
    customVar2: 'value2'
  },
  callbackUrl: 'https://your-callback-url.com'
});

// Start a regular call
await agent.startCall();

// Or start a public call
await agent.startPublicCall();

// Listen for events
agent.on('connected', (details) => {
  console.log('Connected to call:', details);
});

agent.on('transcriptionReceived', (transcript) => {
  console.log('New voice transcript:', transcript);
});

agent.on('message', (message) => {
    console.log('New text message from agent:', message);
});

agent.on('transcriptUpdate', (transcripts) => {
    console.log('Transcript updated:', transcripts);
});

// Control the call
agent.toggleMicrophone(true); // Enable/disable microphone in voice mode
agent.sendTextMessage("Hello, agent!"); // Send a text message in text mode
agent.endCall(); // End the call
```

## Authentication

The SDK supports two authentication methods:

1. **API Key Authentication (Standard Method)**
   ```typescript
   const agent = new TrilletAgent({
     apiKey: 'your-api-key',
     workspaceId: 'your-workspace-id',
     agentId: 'your-agent-id'
   });
   ```

2. **Public Access**
   - For public-facing applications
   - Uses `startPublicCall()` method
   ```typescript
   const agent = new TrilletAgent({
     workspaceId: 'your-workspace-id',
     agentId: 'your-agent-id',
     mode: 'text' // Or 'voice'
   });
   await agent.startPublicCall();
   ```

## Call Types

The SDK supports two types of calls:

1. **Regular Call** - Using `startCall()`
   - Requires full authentication with API Key
   - Suitable for authenticated users

2. **Public Call** - Using `startPublicCall()`
   - Requires workspace ID and agent ID
   - Suitable for public-facing applications
   - No API key needed in client-side code
   - Example:
     ```typescript
     const agent = new TrilletAgent({
       workspaceId: 'your-workspace-id',
       agentId: 'your-agent-id',  // Required for both public and regular calls
       mode: 'text' // Or 'voice'
     });
     await agent.startPublicCall();
     ```

## Events

The SDK emits various events that you can listen to:

```typescript
agent.on('connected', (details) => {
  // Called when successfully connected to a call
});

agent.on('disconnected', () => {
  // Called when the call ends
});

agent.on('error', (error) => {
  // Called when an error occurs
});

agent.on('transcriptionReceived', (segments, participant) => {
  // Called when new transcription is available (voice mode)
});

agent.on('assistantStartedSpeaking', () => {
  // Called when the AI agent starts speaking (voice mode)
});

agent.on('assistantStoppedSpeaking', () => {
  // Called when the AI agent stops speaking (voice mode)
});

agent.on('audioData', (data) => {
  // Raw audio data for visualization (voice mode)
});

agent.on('message', (message) => {
    // Called when a text message is received from the agent (text mode)
});

agent.on('transcriptUpdate', (transcripts) => {
    // Called whenever the transcript is updated (voice or text)
});
```

## Voice Mode Features

When using voice mode, the SDK provides additional audio-related features:

```typescript
// Check if the assistant is currently speaking
const isSpeaking = agent.isAssistantSpeaking;

// Access transcripts
const allTranscripts = agent.getTranscripts();
const currentTranscript = agent.getCurrentTranscript();
```

## Text Mode Features

When using text mode, you can send and receive text messages.

```typescript
// Send a message to the agent
agent.sendTextMessage("Hello, how are you?");

// Listen for messages from the agent
agent.on('message', (message) => {
  console.log('Agent says:', message.text);
});

// The full conversation transcript is available for both modes
const fullConversation = agent.getTranscripts();
console.log(fullConversation);
```

## Requirements

- Modern web browser with secure context (HTTPS or localhost)
- WebRTC support
- Microphone access (for voice mode)

## Browser Support

The SDK is compatible with modern browsers that support WebRTC:
- Chrome (recommended)
- Firefox
- Safari
- Edge

## Error Handling

The SDK includes comprehensive error handling:

```typescript
agent.on('error', (error) => {
  console.error('Trillet SDK Error:', error);
});
```

## License

[License details here]

## Support

For support, please contact [support contact information].