vocafuse 0.1.1
A Python module for communicating with the VocaFuse API and building voice-enabled applications.
License: MIT
Requires Python: >=3.7
Keywords: vocafuse, voice, api, sdk, transcription, audio, speech

# VocaFuse Python SDK ✨

A comprehensive Python SDK for integrating with the VocaFuse voice API.

## Installation

```bash
pip install -r requirements.txt
```

## Quick Start

```python
import os
from vocafuse import Client, AccessToken  # Everything from main package

# Initialize client (auto-detects environment from API key prefix)
client = Client(
    api_key=os.environ["VOCAFUSE_API_KEY"],
    api_secret=os.environ["VOCAFUSE_API_SECRET"]
)

# List recordings
recordings = client.recordings.list(limit=10)
print(f"Found {len(recordings['data'])} recordings")

# Get specific recording
recording = client.recordings.get('recording_id')
print(f"Status: {recording['data']['status']}")

# Get transcription (nested access pattern)
transcription = client.recordings('recording_id').transcription.get()
print(f"Text: {transcription['data']['text']}")

# Generate JWT token for frontend authentication (standalone approach)
token = AccessToken(
    api_key=os.environ["VOCAFUSE_API_KEY"],
    api_secret=os.environ["VOCAFUSE_API_SECRET"],
    identity='user_123'
)
jwt_response = token()
jwt_token = jwt_response['data']['jwt_token']

# Manage webhooks
webhook = client.webhooks.create(
    url='https://myapp.com/webhooks',
    events=['recording.completed', 'recording.failed']
)

# Verify webhook signatures (standalone validator from main package)
from vocafuse import RequestValidator

validator = RequestValidator('your-webhook-secret')
is_valid = validator.validate(webhook_payload, webhook_signature)
```

## Features

### 🎯 **Complete API Client**
- **Auto-environment Detection**: Automatically detects dev/test/live from API key prefix
- **Comprehensive Error Handling**: Specific exceptions for different error types
- **Type Hints**: Full type hint support for better development experience

### 📡 **Resource Management**
- **Recordings**: List, get, delete recordings with transcription access
- **Webhooks**: Create, update, delete, list webhook configurations
- **API Keys**: Create, list, delete API keys for authentication
- **Account**: Get and update account information and settings
- **JWT Generation**: Standalone AccessToken class for frontend authentication
- **Webhook Verification**: Standalone RequestValidator for signature verification

### 🔐 **JWT Token Generation**
- **Callable Interface**: Simple `token()` method for generation
- **Custom Scopes & Expiration**: Flexible token configuration

## API Reference

### Main Client

#### Client(api_key, api_secret, base_url=None)

Initialize the VocaFuse client with API credentials.

```python
from vocafuse import Client

client = Client(
    api_key="your-api-key",
    api_secret="your-api-secret"
)
```

**Environment Auto-Detection:**
- `sk_live_*` → Production: `https://api.vocafuse.com/v1`
- `sk_test_*` → Testing: `https://test-api.vocafuse.com/v1`
- Other → Development: Current dev URL

### JWT Token Generation

#### AccessToken(api_key, api_secret, identity, base_url=None)

Generate JWT tokens for frontend authentication.

```python
from vocafuse.jwt.access_token import AccessToken

# Create token generator
token = AccessToken(
    api_key='your-api-key',
    api_secret='your-api-secret',
    identity='user_123'
)

# Generate token with default settings
response = token()
jwt_token = response['data']['jwt_token']

# Generate token with custom options
response = token(
    expires_in=3600,  # 1 hour
    scopes=['recordings:read', 'recordings:write']
)
```

**Default Scopes:** `['voice-api.upload_recording']`

### Recordings Resource

```python
# List recordings with filters
recordings = client.recordings.list(
    page=0,
    limit=50,
    status='completed',
    date_from='2024-01-01',
    date_to='2024-12-31'
)

# Get specific recording
recording = client.recordings.get('recording_id')

# Delete recording
client.recordings.delete('recording_id')

# Nested access pattern
recording_instance = client.recordings('recording_id')
recording_data = recording_instance.get()
transcription = recording_instance.transcription.get()
recording_instance.delete()
```

### Webhooks Resource

```python
# List webhooks
webhooks = client.webhooks.list()

# Create webhook
webhook = client.webhooks.create(
    url='https://myapp.com/webhooks',
    events=['recording.completed', 'recording.failed'],
    secret='optional-webhook-secret'
)

# Update webhook
client.webhooks.update(
    webhook_id='webhook_id',
    url='https://myapp.com/new-webhook',
    events=['recording.completed']
)

# Delete webhook
client.webhooks.delete('webhook_id')

# Verify webhook signature (standalone)
from vocafuse import RequestValidator
validator = RequestValidator('your-webhook-secret')
is_valid = validator.validate(payload, signature)
```

### API Keys Resource

```python
# List API keys
keys = client.api_keys.list()

# Create new API key
new_key = client.api_keys.create(name='Production Key')
print(f"Key: {new_key['data']['key']}")
print(f"Secret: {new_key['data']['secret']}")

# Delete API key
client.api_keys.delete('key_id')
```

### Account Resource

```python
# Get account info
account = client.account.get()
print(f"Account: {account['data']['name']}")
print(f"Tenant ID: {account['data']['tenant_id']}")

# Update account
client.account.update(name='New Company Name')
```

### Webhook Verification

```python
from flask import Flask, request, jsonify
from vocafuse import Client, RequestValidator

app = Flask(__name__)
client = Client(
    api_key='your-api-key',
    api_secret='your-api-secret'
)
webhook_validator = RequestValidator('your-webhook-secret')

@app.route('/webhooks/vocafuse', methods=['POST'])
def handle_webhook():
    payload = request.get_data(as_text=True)
    signature = request.headers.get('X-VocaFuse-Signature')

    if webhook_validator.validate(payload, signature):
        # Process webhook
        data = request.get_json()
        print(f"Webhook event: {data['event']}")
        return jsonify({"status": "received"})
    else:
        return jsonify({"error": "Invalid signature"}), 401
```

## Error Handling

The SDK provides specific exceptions for different error scenarios:

```python
from vocafuse import (
    Client,
    VocaFuseError,
    AuthenticationError,
    ValidationError,
    RecordingNotFoundError,
    WebhookNotFoundError
)

try:
    recording = client.recordings.get('invalid-id')
except RecordingNotFoundError as e:
    print(f"Recording not found: {e}")
    print(f"Status code: {e.status_code}")
    print(f"Error code: {e.error_code}")
except AuthenticationError as e:
    print(f"Authentication failed: {e}")
except VocaFuseError as e:
    print(f"General API error: {e}")
```

## Examples

See `examples/complete_usage.py` for a comprehensive example demonstrating all SDK features.

```bash
# Set environment variables
export VOCAFUSE_API_KEY="your-api-key"
export VOCAFUSE_API_SECRET="your-api-secret"

# Run the complete example
python examples/complete_usage.py
```

## Environment Variables

```bash
VOCAFUSE_API_KEY=your_api_key_here
VOCAFUSE_API_SECRET=your_api_secret_here
VOCAFUSE_WEBHOOK_SECRET=your_webhook_secret_here  # For webhook verification
```

## Requirements

- Python 3.7+
- requests >= 2.25.0

## Support

- 📧 Email: support@vocafuse.com
- 📖 Documentation: https://docs.vocafuse.com