vconnct-devkit 1.0.0

Official Python SDK for VConnct v4 API - Rooms, Recordings, Analytics, and Branding

vcloud-devkit

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

• Website: https://vcloud.vconnct.me/
• Documentation: 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

pip install vcloud-devkit

Quick Start

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

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.

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

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

Create Scheduled Video Room

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

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

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

Get Active Room Info

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

Get All Active Rooms

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

Fetch Past Rooms

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

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

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

---

Recordings

Get Recording

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

Get Recording URLs

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

---

Analytics

Get Analytics

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

---

Branding

Create Branding

# 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

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

---

Error Handling

The SDK provides specific error classes for different error types:

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:

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/
• Documentation: https://guide.vconnct.com/
• Support: [e-mail]