npm package: @redonvn/vbee-sdk
Description: VBEE SDK for TypeScript/JavaScript - Text-to-Speech and Voice AI Services
Author: VBEE
Latest version: 1.8.4

# VBEE SDK for TypeScript/JavaScript

[![npm version](https://badge.fury.io/js/%40vbee%2Fsdk.svg)](https://badge.fury.io/js/%40vbee%2Fsdk)
[![License: MIT](https://img.shields.io/badge/License-MIT-yellow.svg)](https://opensource.org/licenses/MIT)

Official TypeScript/JavaScript SDK for VBEE Text-to-Speech and Voice AI Services.

## Features

- 🎯 **Text-to-Speech**: Convert text to natural-sounding speech
- 🎤 **Speech Recognition**: Transcribe audio to text
- 🗣️ **Voice Management**: Browse and manage available voices
- 📦 **TypeScript Support**: Full TypeScript type definitions
- 🔒 **Secure**: Built-in API key authentication
- ⚡ **Easy to Use**: Simple and intuitive API
- 🛠️ **Customizable**: Flexible configuration options

## Installation

```bash
npm install @vbee/sdk
```

or with yarn:

```bash
yarn add @vbee/sdk
```

## Quick Start

### Initialize the SDK

```typescript
import { VBeeClient } from '@vbee/sdk';

const client = new VBeeClient({
  apiKey: 'YOUR_API_KEY',
});
```

### Text-to-Speech

```typescript
// Simple text-to-speech
const audioUrl = await client.tts.synthesizeToUrl(
  'Xin chào, đây là VBEE Text-to-Speech',
  'voice-id-123'
);

console.log('Audio URL:', audioUrl);

// Advanced options
const result = await client.tts.synthesize({
  text: 'Hello, this is VBEE TTS',
  voiceId: 'voice-id-123',
  speed: 1.2,
  format: AudioFormat.MP3,
  language: 'vi-VN',
  sampleRate: 24000,
});

console.log('Audio URL:', result.audioUrl);
console.log('Duration:', result.duration);
```

### Voice Management

```typescript
// Get all available voices
const voices = await client.voice.list();
console.log('Available voices:', voices.voices);

// Filter voices by language
const vietnameseVoices = await client.voice.getByLanguage('vi-VN');
console.log('Vietnamese voices:', vietnameseVoices);

// Get specific voice
const voice = await client.voice.getById('voice-id-123');
console.log('Voice details:', voice);

// Search voices
const searchResults = await client.voice.search('female');
console.log('Search results:', searchResults);
```

### Speech Recognition

```typescript
// Transcribe audio from URL
const transcription = await client.speechRecognition.transcribeFromUrl(
  'https://example.com/audio.mp3',
  'vi-VN'
);

console.log('Transcription:', transcription.text);
console.log('Confidence:', transcription.confidence);

// Transcribe from buffer
const audioBuffer = fs.readFileSync('audio.mp3');
const result = await client.speechRecognition.transcribeFromBuffer(
  audioBuffer,
  'vi-VN'
);
```

## Configuration

### Basic Configuration

```typescript
const client = new VBeeClient({
  apiKey: 'YOUR_API_KEY',
});
```

### Advanced Configuration

```typescript
const client = new VBeeClient({
  apiKey: 'YOUR_API_KEY',
  baseURL: 'https://api.vbee.vn/v1', // Custom API endpoint
  timeout: 30000, // Request timeout in milliseconds
  retryAttempts: 3, // Number of retry attempts
  debug: true, // Enable debug mode
});
```

## API Reference

### VBeeClient

Main client class for interacting with VBEE API.

#### Methods

- `healthCheck()`: Test API connection
- `getVersion()`: Get SDK version

### TTSService

Text-to-Speech service.

#### Methods

- `synthesize(request: TTSRequest)`: Convert text to speech with detailed options
- `synthesizeToUrl(text: string, voiceId: string, options?)`: Get audio URL
- `synthesizeToBuffer(text: string, voiceId: string, options?)`: Get audio data

### VoiceService

Voice management service.

#### Methods

- `list(filters?)`: Get list of available voices
- `getById(voiceId: string)`: Get voice by ID
- `search(query: string)`: Search voices by name
- `getByLanguage(language: string)`: Get voices by language
- `getByGender(gender: string)`: Get voices by gender

### SpeechRecognitionService

Speech recognition service.

#### Methods

- `transcribe(request: SpeechRecognitionRequest)`: Transcribe audio to text
- `transcribeFromUrl(audioUrl: string, language?)`: Transcribe from URL
- `transcribeFromBuffer(audioBuffer: Buffer, language?)`: Transcribe from buffer

## Types

### VBeeConfig

```typescript
interface VBeeConfig {
  apiKey: string;
  baseURL?: string;
  timeout?: number;
  retryAttempts?: number;
  debug?: boolean;
}
```

### TTSRequest

```typescript
interface TTSRequest {
  text: string;
  voiceId: string;
  speed?: number;
  format?: AudioFormat;
  language?: string;
  sampleRate?: number;
}
```

### Voice

```typescript
interface Voice {
  id: string;
  name: string;
  language: string;
  gender: VoiceGender;
  description?: string;
  category?: string;
  sampleUrl?: string;
  isActive: boolean;
}
```

## Error Handling

The SDK provides comprehensive error handling with specific error types:

```typescript
import { 
  VBeeError, 
  AuthenticationError, 
  ValidationError, 
  RateLimitError 
} from '@vbee/sdk';

try {
  const result = await client.tts.synthesize({
    text: 'Hello',
    voiceId: 'invalid-voice',
  });
} catch (error) {
  if (error instanceof AuthenticationError) {
    console.error('Invalid API key');
  } else if (error instanceof ValidationError) {
    console.error('Invalid input:', error.message);
  } else if (error instanceof RateLimitError) {
    console.error('Rate limit exceeded');
  } else if (error instanceof VBeeError) {
    console.error('VBEE Error:', error.code, error.message);
  }
}
```

## Examples

Check out the [examples](./examples) directory for more usage examples:

- [Basic TTS](./examples/basic-tts.ts)
- [Voice Management](./examples/voice-management.ts)
- [Speech Recognition](./examples/speech-recognition.ts)
- [Error Handling](./examples/error-handling.ts)

## Development

### Build

```bash
npm run build
```

### Test

```bash
npm test
```

### Lint

```bash
npm run lint
npm run lint:fix
```

### Format

```bash
npm run format
```

## Contributing

Contributions are welcome! Please feel free to submit a Pull Request.

## License

This project is licensed under the MIT License - see the [LICENSE](LICENSE) file for details.

## Support

- Documentation: [https://docs.vbee.vn](https://docs.vbee.vn)
- Email: support@vbee.vn
- Issues: [GitHub Issues](https://github.com/Jin-mr05/sdk-vbee/issues)

## Changelog

See [CHANGELOG.md](CHANGELOG.md) for a list of changes.