vconnct-devkit 1.0.1
Official Python SDK for VConnct v4 API - Rooms, Recordings, Analytics, and Branding
Requires Python: >=3.10
Keywords: api, conferencing, devkit, meeting, rooms, sdk, vconnct, video

# vconnct-devkit

[![PyPI version](https://img.shields.io/pypi/v/vconnct-devkit.svg)](https://pypi.org/project/vconnct-devkit/)
[![Python versions](https://img.shields.io/pypi/pyversions/vconnct-devkit.svg)](https://pypi.org/project/vconnct-devkit/)
[![License: MIT](https://img.shields.io/badge/License-MIT-yellow.svg)](https://opensource.org/licenses/MIT)

Official Python SDK for the VConnct v4 API. Build video and audio conferencing applications with ease.

- **Website**: [https://vconnct.me/](https://vconnct.me/)
- **Documentation**: [https://guide.vconnct.com/](https://guide.vconnct.com/)

## Features

- Full type hints support
- Automatic HMAC SHA256 signature generation
- Covers all VConnct v4 API endpoints:
  - **Rooms** - Create, manage, and control video/audio rooms
  - **Recordings** - Access room recordings
  - **Analytics** - Retrieve room analytics data
  - **Branding** - Customize project branding with logos

## Installation

```bash
pip install vconnct-devkit
```

## Quick Start

```python
from vconnct_devkit import VConnctClient

# Initialize the client
client = VConnctClient(
    api_key="your-api-key",
    secret_key="your-secret-key",
)

# Create a video room
room = client.rooms.create_quick_video_room({
    "project_id": "your-project-id",
    "client_room_id": "unique-room-id",
    "name": "My Meeting Room",
    "max_participants": 10,
    "empty_timeout": 300,
    "metadata": {
        "room_title": "Team Meeting",
        "welcome_message": "Welcome to the meeting!",
    },
})

print(f"Room created: {room.room_id}")
print(f"Join URL: {room.final_link}")
```

## Configuration

```python
from vconnct_devkit import VConnctClient

client = VConnctClient(
    api_key="your-api-key",       # Required: Your API key
    secret_key="your-secret-key", # Required: Your secret key for HMAC signing
    base_url="https://v.cloudapi.vconnct.me/api/v4",  # Optional: API base URL
    timeout=30.0,                 # Optional: Request timeout in seconds (default: 30.0)
)

# Or use as a context manager
with VConnctClient(api_key="...", secret_key="...") as client:
    room = client.rooms.create_quick_video_room({...})
```

## API Reference

### Rooms

#### Create Quick Video Room

Create an instant video room for immediate use.

```python
from vconnct_devkit import CreateQuickRoomParams, RoomMetadata

# Using dataclass
room = client.rooms.create_quick_video_room(
    CreateQuickRoomParams(
        project_id="project-uuid",
        client_room_id="unique-room-id",
        name="Room Name",
        moderator_id="moderator-user-id",
        max_participants=10,
        empty_timeout=300,
        metadata=RoomMetadata(
            room_title="Display Title",
            welcome_message="Welcome!",
        ),
    )
)

# Or using dict
room = client.rooms.create_quick_video_room({
    "project_id": "project-uuid",
    "client_room_id": "unique-room-id",
    "name": "Room Name",
})
```

#### Create Quick Audio Room

```python
room = client.rooms.create_quick_audio_room({
    "project_id": "project-uuid",
    "client_room_id": "unique-room-id",
})
```

#### Create Scheduled Video Room

```python
room = client.rooms.create_schedule_video_room({
    "project_id": "project-uuid",
    "client_room_id": "unique-room-id",
    "start_at": "2025-12-31T10:00",  # YYYY-MM-DDTHH:MM format
    "empty_timeout": 300,
})
```

#### Create Scheduled Audio Room

```python
room = client.rooms.create_schedule_audio_room({
    "project_id": "project-uuid",
    "client_room_id": "unique-room-id",
    "start_at": "2025-12-31T10:00",
    "empty_timeout": 300,
})
```

#### Start Scheduled Room

```python
room = client.rooms.start_scheduled_room({
    "room_id": "room-uuid",
    "name": "Updated Room Name",  # optional
})
```

#### Get Active Room Info

```python
room_info = client.rooms.get_active_room_info("room-uuid")
print(room_info.room)
```

#### Get All Active Rooms

```python
active_rooms = client.rooms.get_all_active_rooms()
for room in active_rooms.rooms:
    print(room.room_id)
```

#### Fetch Past Rooms

```python
past_rooms = client.rooms.fetch_past_rooms({
    "project_id": "project-uuid",
    "room_ids": ["room-id-1", "room-id-2"],
    "limit": 10,
    "from_": 0,  # Note: use from_ to avoid Python keyword
    "order_by": "DESC",
})
```

#### Create Invitation Link

```python
invite = client.rooms.create_invitation_link({
    "room_id": "room-uuid",
    "user_id": "user-id",
    "role": "viewer",  # "admin" or "viewer"
})

print(f"Invite URL: {invite.invitation_link or invite.invitation_url}")
```

#### End Room

```python
result = client.rooms.end_room("room-uuid")
```

---

### Recordings

#### Get Recording

```python
recording = client.recordings.get_recording("room-uuid")
print(recording.url)
```

#### Get Recording URLs

```python
urls = client.recordings.get_recording_urls("room-uuid")
for url in urls:
    print(url)
```

---

### Analytics

#### Get Analytics

```python
analytics = client.analytics.get_analytics("room-uuid")
print(analytics)
```

---

### Branding

#### Create Branding

```python
# With file path
with open("logo.png", "rb") as f:
    logo_bytes = f.read()

branding = client.branding.create({
    "project_id": "project-uuid",
    "logo": logo_bytes,
    "dark_logo": dark_logo_bytes,      # optional
    "mobile_logo": mobile_logo_bytes,  # optional
    "fav_icon": favicon_bytes,         # optional
})
```

#### Update Branding

```python
branding = client.branding.update({
    "project_id": "project-uuid",
    "logo": new_logo_bytes,
})
```

---

## Error Handling

The SDK provides specific error classes for different error types:

```python
from vconnct_devkit import (
    VConnctClient,
    VConnctError,
    AuthError,
    ValidationError,
    NotFoundError,
    RateLimitError,
)

try:
    room = client.rooms.get_active_room_info("invalid-room-id")
except AuthError as e:
    # Handle authentication errors (401)
    print(f"Authentication failed: {e.message}")
except ValidationError as e:
    # Handle validation errors (400)
    print(f"Validation error: {e.message}")
    if e.fields:
        print(f"Invalid fields: {e.fields}")
except NotFoundError as e:
    # Handle not found errors (404)
    print(f"Not found: {e.message}")
    print(f"Details: {e.details}")
except RateLimitError as e:
    # Handle rate limit errors (429)
    print(f"Rate limited. Retry after: {e.retry_after} seconds")
except VConnctError as e:
    # Handle other API errors
    print(f"API error: {e.message}")
    print(f"Status code: {e.status_code}")
```

### Error Classes

| Error Class | Status Code | Description |
|-------------|-------------|-------------|
| `AuthError` | 401 | Invalid API key or signature |
| `ValidationError` | 400 | Request validation failed |
| `NotFoundError` | 404 | Resource not found |
| `RateLimitError` | 429 | Rate limit exceeded |
| `VConnctError` | * | Base error class for all API errors |

---

## Type Hints

This SDK includes full type hints. All request parameters and response types are fully typed:

```python
from vconnct_devkit import (
    VConnctConfig,
    CreateQuickRoomParams,
    CreateScheduleRoomParams,
    CreateRoomResponse,
    FetchPastRoomsParams,
    FetchPastRoomsResponse,
    InvitationLinkParams,
    InvitationLinkResponse,
    GetActiveRoomResponse,
    GetActiveRoomsResponse,
    BrandingParams,
    BrandingResponse,
)
```

---

## Authentication

All API requests are authenticated using:
- `key` header: Your API key
- `hash-signature` header: HMAC SHA256 signature (Base64 encoded)

The SDK handles signature generation automatically:
- **GET requests**: Signs the full URL path with query string
- **POST/PATCH requests**: Signs the JSON request body
- **FormData requests**: Signs the project_id

---

## Requirements

- Python 3.10+
- httpx >= 0.25.0

---

## License

MIT License

## Links

- **Website**: [https://vconnct.me/](https://vconnct.me/)
- **Documentation**: [https://guide.vconnct.com/](https://guide.vconnct.com/)
- **Support**: [developer@vconnct.com](mailto:developer@vconnct.com)