agent-widget-sdk/README.md

JavaScript SDK for Sarvam Agent Widget APIs and WebSocket connections

# Sarvam Agent Widget SDK

A JavaScript SDK for integrating with Sarvam Agent Widget APIs and WebSocket connections. This SDK provides a simple and powerful way to build voice-enabled applications with real-time audio processing.

## Features

- 🎤 **Audio Processing**: Real-time audio capture and processing
- 🔗 **WebSocket Integration**: Seamless real-time communication
- 📡 **API Client**: Easy-to-use API client for widget configuration
- 🎵 **Audio Playback**: Built-in audio response playback
- 🔄 **Auto-reconnection**: Automatic WebSocket reconnection
- 📝 **TypeScript Support**: Full TypeScript support with type definitions
- 🛡️ **Error Handling**: Comprehensive error handling and logging

## Installation

```bash
npm install @sarvam/agent-widget-sdk
```

## Quick Start

```javascript
import SarvamWidgetSDK from '@sarvam/agent-widget-sdk';

// Initialize the SDK
const sdk = new SarvamWidgetSDK({
	apiUrl: 'https://agent-widget-sarvam.vercel.app',
	enableLogging: true
});

// Initialize audio and setup
await sdk.initialize();

// Start a voice session
await sdk.startVoiceSession(
	{
		orgId: 'your-org-id',
		appId: 'your-app-id',
		token: 'your-token'
	},
	{
		onOpen: () => console.log('Connected'),
		onMessage: (event) => console.log('Message received:', event.data),
		onClose: () => console.log('Disconnected'),
		onError: (error) => console.error('Error:', error),
		onAudioResponse: (audioData) => {
			// Handle audio response
			sdk.playAudioResponse(audioData.data);
		}
	}
);

// Start interaction
sdk.startInteraction('Current page content...');
```

## API Reference

### SarvamWidgetSDK

Main SDK class that provides access to all functionality.

#### Constructor

```javascript
new SarvamWidgetSDK(config?: SDKConfig)
```

**Parameters:**

- `config` (optional): Configuration object
  - `apiUrl`: API base URL (default: 'https://agent-widget-sarvam.vercel.app')
  - `enableLogging`: Enable console logging (default: true)
  - `autoReconnect`: Auto-reconnect WebSocket (default: true)
  - `reconnectInterval`: Reconnection interval in ms (default: 3000)
  - `maxReconnectAttempts`: Maximum reconnection attempts (default: 5)

#### Methods

##### `initialize(): Promise<void>`

Initializes the SDK with audio processor and sets up audio context.

```javascript
await sdk.initialize();
```

##### `startVoiceSession(config, handlers): Promise<void>`

Starts a voice session with WebSocket connection.

```javascript
await sdk.startVoiceSession(
	{
		orgId: 'org-123',
		appId: 'app-456',
		token: 'your-token',
		appVersion: 1 // optional
	},
	{
		onOpen: () => console.log('Connected'),
		onMessage: (event) => console.log('Message:', event.data),
		onClose: () => console.log('Disconnected'),
		onError: (error) => console.error('Error:', error),
		onAudioResponse: (audioData) => {
			// Handle audio response
		},
		onTextResponse: (text) => {
			// Handle text response
		}
	}
);
```

##### `startInteraction(webContent?: string): void`

Starts audio recording and interaction.

```javascript
sdk.startInteraction('Current page content or context');
```

##### `stopInteraction(): void`

Stops audio recording and interaction.

```javascript
sdk.stopInteraction();
```

##### `sendContentUpdate(content: string): void`

Sends content update to the agent.

```javascript
sdk.sendContentUpdate('Updated page content');
```

##### `playAudioResponse(audioData: string, onStart?: () => void, onEnd?: () => void): Promise<void>`

Plays audio response.

```javascript
await sdk.playAudioResponse(
	base64AudioData,
	() => console.log('Playback started'),
	() => console.log('Playback ended')
);
```

##### `endVoiceSession(): Promise<void>`

Ends the voice session and cleans up resources.

```javascript
await sdk.endVoiceSession();
```

##### `cleanup(): Promise<void>`

Cleans up all SDK resources.

```javascript
await sdk.cleanup();
```

### Widget Configuration API

##### `getWidgetConfig(appId: string): Promise<WidgetConfig>`

Retrieves widget configuration.

```javascript
const config = await sdk.getWidgetConfig('app-123');
console.log(config);
```

##### `createWidgetConfig(config): Promise<WidgetConfig>`

Creates a new widget configuration.

```javascript
const config = await sdk.createWidgetConfig({
	appId: 'app-123',
	orgId: 'org-456',
	orgName: 'My Organization',
	buttonConfig: {
		text: 'Talk to us',
		bgColor: '#0066cc',
		textColor: '#ffffff',
		endText: 'End Call'
	},
	widgetConfig: {
		title: 'Support Chat',
		logoUrl: 'https://example.com/logo.png'
	}
});
```

##### `updateWidgetConfig(appId: string, updates): Promise<WidgetConfig>`

Updates widget configuration.

```javascript
const config = await sdk.updateWidgetConfig('app-123', {
	buttonConfig: {
		text: 'New button text',
		bgColor: '#ff0000'
	}
});
```

### Audio Device Management

##### `getAudioDevices(): Promise<MediaDeviceInfo[]>`

Gets available audio input devices.

```javascript
const devices = await sdk.getAudioDevices();
console.log(devices);
```

##### `setAudioInputDevice(deviceId: string): Promise<void>`

Sets the audio input device.

```javascript
await sdk.setAudioInputDevice('device-id');
```

### Status Methods

##### `isInitialized(): boolean`

Checks if SDK is initialized.

```javascript
if (sdk.isInitialized()) {
	console.log('SDK is ready');
}
```

##### `isConnected(): boolean`

Checks if WebSocket is connected.

```javascript
if (sdk.isConnected()) {
	console.log('WebSocket is connected');
}
```

##### `isRecording(): boolean`

Checks if audio is being recorded.

```javascript
if (sdk.isRecording()) {
	console.log('Recording audio');
}
```

### Proxy API

##### `proxyRequest(url: string, options): Promise<Response>`

Makes requests through the proxy to bypass CORS.

```javascript
const response = await sdk.proxyRequest('https://api.example.com/data', {
	method: 'POST',
	headers: {
		Authorization: 'Bearer token'
	},
	body: { data: 'example' }
});
```

## Error Handling

The SDK provides comprehensive error handling with specific error codes:

```javascript
import { SDKError } from '@sarvam/agent-widget-sdk';

try {
	await sdk.initialize();
} catch (error) {
	if (error instanceof SDKError) {
		console.error('SDK Error:', error.code, error.message);
		console.error('Details:', error.details);
	}
}
```

### Error Codes

- `SDK_INITIALIZATION_FAILED`: Failed to initialize SDK
- `SDK_NOT_INITIALIZED`: SDK not initialized
- `WEBSOCKET_CONNECTION_FAILED`: WebSocket connection failed
- `WEBSOCKET_NOT_CONNECTED`: WebSocket not connected
- `AUDIO_SETUP_FAILED`: Audio setup failed
- `AUDIO_PLAYBACK_FAILED`: Audio playback failed
- `WIDGET_CONFIG_FETCH_FAILED`: Widget config fetch failed
- `PROXY_REQUEST_FAILED`: Proxy request failed

## Examples

### Basic Voice Chat

```javascript
import SarvamWidgetSDK from '@sarvam/agent-widget-sdk';

const sdk = new SarvamWidgetSDK();

async function startVoiceChat() {
	try {
		// Initialize SDK
		await sdk.initialize();

		// Start voice session
		await sdk.startVoiceSession(
			{
				orgId: 'your-org-id',
				appId: 'your-app-id',
				token: 'your-token'
			},
			{
				onOpen: () => console.log('Voice chat connected'),
				onAudioResponse: async (audioData) => {
					await sdk.playAudioResponse(audioData.data);
				},
				onClose: () => console.log('Voice chat disconnected')
			}
		);

		// Start interaction
		sdk.startInteraction('Hello, I need help with...');
	} catch (error) {
		console.error('Failed to start voice chat:', error);
	}
}

startVoiceChat();
```

### Widget Configuration Management

```javascript
import SarvamWidgetSDK from '@sarvam/agent-widget-sdk';

const sdk = new SarvamWidgetSDK();

async function manageWidgetConfig() {
	try {
		// Get existing config
		const config = await sdk.getWidgetConfig('app-123');
		console.log('Current config:', config);

		// Update config
		const updatedConfig = await sdk.updateWidgetConfig('app-123', {
			buttonConfig: {
				text: 'Chat with AI',
				bgColor: '#4CAF50'
			}
		});

		console.log('Updated config:', updatedConfig);
	} catch (error) {
		console.error('Failed to manage config:', error);
	}
}

manageWidgetConfig();
```

## TypeScript Support

The SDK is written in TypeScript and provides complete type definitions:

```typescript
import SarvamWidgetSDK, {
	SDKConfig,
	VoiceSessionConfig,
	WebSocketHandlers,
	WidgetConfig
} from '@sarvam/agent-widget-sdk';

const config: SDKConfig = {
	apiUrl: 'https://agent-widget-sarvam.vercel.app',
	enableLogging: true
};

const sdk = new SarvamWidgetSDK(config);

const sessionConfig: VoiceSessionConfig = {
	orgId: 'org-123',
	appId: 'app-456',
	token: 'your-token'
};

const handlers: WebSocketHandlers = {
	onOpen: () => console.log('Connected'),
	onMessage: (event) => console.log('Message:', event.data),
	onClose: () => console.log('Disconnected'),
	onError: (error) => console.error('Error:', error)
};
```

## Browser Support

The SDK supports all modern browsers with WebRTC and Web Audio API support:

- Chrome 66+
- Firefox 60+
- Safari 13+
- Edge 79+

## License

MIT License - see LICENSE file for details.

## Support

For questions and support, please contact the Sarvam AI team or create an issue in the repository.