Metadata-Version: 2.4
Name: vconnct-devkit
Version: 1.0.0
Summary: Official Python SDK for VConnct v4 API - Rooms, Recordings, Analytics, and Branding
Project-URL: Homepage, https://vconnct.me/
Project-URL: Documentation, https://guide.vconnct.com/
Project-URL: Repository, https://github.com/vconnct/vconnct-sdk-python
Project-URL: Issues, https://github.com/vconnct/vconnct-sdk-python/issues
Author-email: vconnct developer team <developer@vconnct.com>
License-Expression: MIT
Keywords: api,conferencing,devkit,meeting,rooms,sdk,vconnct,video
Classifier: Development Status :: 5 - Production/Stable
Classifier: Intended Audience :: Developers
Classifier: License :: OSI Approved :: MIT License
Classifier: Operating System :: OS Independent
Classifier: Programming Language :: Python :: 3
Classifier: Programming Language :: Python :: 3.10
Classifier: Programming Language :: Python :: 3.11
Classifier: Programming Language :: Python :: 3.12
Classifier: Programming Language :: Python :: 3.13
Classifier: Topic :: Communications :: Conferencing
Classifier: Topic :: Internet :: WWW/HTTP
Classifier: Topic :: Software Development :: Libraries :: Python Modules
Classifier: Typing :: Typed
Requires-Python: >=3.10
Requires-Dist: httpx>=0.25.0
Provides-Extra: dev
Requires-Dist: mypy>=1.0.0; extra == 'dev'
Requires-Dist: pytest-asyncio>=0.21.0; extra == 'dev'
Requires-Dist: pytest-cov>=4.0.0; extra == 'dev'
Requires-Dist: pytest>=7.0.0; extra == 'dev'
Requires-Dist: respx>=0.20.0; extra == 'dev'
Requires-Dist: ruff>=0.1.0; extra == 'dev'
Description-Content-Type: text/markdown

# vcloud-devkit

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

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

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

## Features

- Full type hints support
- Automatic HMAC SHA256 signature generation
- Covers all VCloud 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 vcloud-devkit
```

## Quick Start

```python
from vcloud_devkit import VCloudClient

# Initialize the client
client = VCloudClient(
    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": f"room-{int(time.time())}",
    "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 vcloud_devkit import VCloudClient

client = VCloudClient(
    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 VCloudClient(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 vcloud_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": "2024-12-31T10:00:00Z",  # ISO8601 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": "2024-12-31T10:00:00Z",
    "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 vcloud_devkit import (
    VCloudClient,
    VCloudError,
    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 VCloudError 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 |
| `VCloudError` | * | 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 vcloud_devkit import (
    VCloudConfig,
    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://vcloud.vconnct.me/](https://vcloud.vconnct.me/)
- **Documentation**: [https://guide.vconnct.com/](https://guide.vconnct.com/)
- **Support**: [developer@vconnct.com](mailto:developer@vconnct.com)
