TypeScript SDK
Official TypeScript/JavaScript SDK for the VCloud v4 API
TypeScript SDK
Official TypeScript/JavaScript SDK for the VCloud v4 API. Build video and audio conferencing applications with ease.
npm install @vconnct/devkitFeatures
- Full TypeScript support with type definitions
- Works in both Node.js and browser environments
- 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
Supported Frameworks
Frontend Frameworks
| Framework | Support |
|---|---|
| React | Full Support |
| Vue.js | Full Support |
| Angular | Full Support |
| Svelte | Full Support |
| Next.js | Full Support |
| Nuxt.js | Full Support |
| Gatsby | Full Support |
Backend Frameworks
| Framework | Support |
|---|---|
| Node.js | Full Support |
| Express.js | Full Support |
| NestJS | Full Support |
| Fastify | Full Support |
| Koa.js | Full Support |
Mobile Development
| Framework | Support |
|---|---|
| React Native | Full Support |
| Ionic | Full Support |
| Capacitor | Full Support |
Desktop Development
| Framework | Support |
|---|---|
| Electron | Full Support |
| Tauri | Full Support |
Quick Start
import { VCloudClient } from '@vconnct/devkit';
// Initialize the client
const client = new VCloudClient({
apiKey: 'your-api-key',
secretKey: 'your-secret-key',
});
// Create a video room
const room = await client.rooms.createQuickVideoRoom({
project_id: 'your-project-id',
client_room_id: `room-${Date.now()}`,
name: 'My Meeting Room',
max_participants: 10,
empty_timeout: 300,
metadata: {
room_title: 'Team Meeting',
welcome_message: 'Welcome to the meeting!',
},
});
console.log('Room created:', room.room_id);
console.log('Join URL:', room.final_link);Configuration
const client = new VCloudClient({
apiKey: 'your-api-key', // Required: Your API key
secretKey: 'your-secret-key', // Required: Your secret key for HMAC signing
baseUrl: 'https://v.cloudapi.vconnct.me/api/v4', // Optional: API base URL
timeout: 30000, // Optional: Request timeout in ms (default: 30000)
});| Option | Type | Required | Description |
|---|---|---|---|
apiKey | string | Yes | Your API key |
secretKey | string | Yes | Your secret key for HMAC signing |
baseUrl | string | No | API base URL (default: v4 endpoint) |
timeout | number | No | Request timeout in milliseconds (default: 30000) |
API Reference
Rooms
Create Quick Video Room
Create an instant video room for immediate use.
const room = await client.rooms.createQuickVideoRoom({
project_id: 'project-uuid',
client_room_id: 'unique-room-id',
name: 'Room Name', // optional
moderator_id: 'moderator-user-id', // optional
max_participants: 10, // optional
empty_timeout: 300, // optional (seconds)
metadata: { // optional
room_title: 'Display Title',
welcome_message: 'Welcome!',
},
});Create Quick Audio Room
Create an instant audio-only room.
const room = await client.rooms.createQuickAudioRoom({
project_id: 'project-uuid',
client_room_id: 'unique-room-id',
// ... same options as video room
});Create Scheduled Video Room
Schedule a video room for a future time.
const room = await client.rooms.createScheduleVideoRoom({
project_id: 'project-uuid',
client_room_id: 'unique-room-id',
start_at: '2024-12-31T10:00:00Z', // ISO8601 format (required)
empty_timeout: 300, // required for scheduled rooms
// ... other options
});Create Scheduled Audio Room
Schedule an audio room for a future time.
const room = await client.rooms.createScheduleAudioRoom({
project_id: 'project-uuid',
client_room_id: 'unique-room-id',
start_at: '2024-12-31T10:00:00Z',
empty_timeout: 300,
// ... other options
});Start Scheduled Room
Start a previously scheduled room.
const room = await client.rooms.startScheduledRoom({
room_id: 'room-uuid',
name: 'Updated Room Name', // optional
});Get Active Room Info
Get information about a specific active room.
const roomInfo = await client.rooms.getActiveRoomInfo('room-uuid');
console.log(roomInfo.room);Get All Active Rooms
List all currently active rooms.
const activeRooms = await client.rooms.getAllActiveRooms();
console.log(activeRooms.rooms);Fetch Past Rooms
Retrieve historical room data by room IDs.
const pastRooms = await client.rooms.fetchPastRooms({
project_id: 'project-uuid',
room_ids: ['room-id-1', 'room-id-2'], // required
limit: 10, // optional
from: 0, // optional (offset)
order_by: 'DESC', // optional: 'ASC' | 'DESC'
});Create Invitation Link
Generate an invitation link for a room.
const invite = await client.rooms.createInvitationLink({
room_id: 'room-uuid',
user_id: 'user-id',
role: 'viewer', // 'admin' | 'viewer'
});
console.log('Invite URL:', invite.invitation_link || invite.invitation_url);End Room
Terminate an active room session.
const result = await client.rooms.endRoom('room-uuid');Recordings
Get Recording
Retrieve recording information for a room.
const recording = await client.recordings.getRecording('room-uuid');Analytics
Get Analytics
Retrieve analytics data for a room.
const analytics = await client.analytics.getAnalytics('room-uuid');Branding
Create Branding
Create branding for a project with logos and favicon.
In browser (with File objects):
const logoFile = document.getElementById('logo-input').files[0];
const branding = await client.branding.create({
project_id: 'project-uuid',
logo: logoFile,
dark_logo: darkLogoFile, // optional
mobile_logo: mobileLogoFile, // optional
mobile_dark_logo: mobileDarkLogoFile, // optional
fav_icon: faviconFile, // optional
});In Node.js (with Buffer):
import { readFileSync } from 'fs';
const branding = await client.branding.create({
project_id: 'project-uuid',
logo: readFileSync('./logo.png'),
});Update Branding
Update existing branding for a project.
const branding = await client.branding.update({
project_id: 'project-uuid',
logo: newLogoFile,
});Error Handling
The SDK provides specific error classes for different error types:
import {
VCloudClient,
VCloudError,
AuthError,
ValidationError,
NotFoundError,
RateLimitError,
} from '@vconnct/devkit';
try {
const room = await client.rooms.getActiveRoomInfo('invalid-room-id');
} catch (error) {
if (error instanceof AuthError) {
// Handle authentication errors (401)
console.error('Authentication failed:', error.message);
} else if (error instanceof ValidationError) {
// Handle validation errors (400)
console.error('Validation error:', error.message);
} else if (error instanceof NotFoundError) {
// Handle not found errors (404)
console.error('Not found:', error.message);
console.error('Details:', error.details);
} else if (error instanceof RateLimitError) {
// Handle rate limit errors (429)
console.error('Rate limited. Retry after:', error.retryAfter, 'seconds');
} else if (error instanceof VCloudError) {
// Handle other API errors
console.error('API error:', error.message);
console.error('Status code:', error.statusCode);
}
}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 |
TypeScript Types
This SDK is written in TypeScript and includes full type definitions:
import type {
VCloudConfig,
CreateQuickRoomParams,
CreateScheduleRoomParams,
CreateRoomResponse,
FetchPastRoomsParams,
FetchPastRoomsResponse,
InvitationLinkParams,
InvitationLinkResponse,
GetActiveRoomResponse,
GetActiveRoomsResponse,
BrandingParams,
BrandingResponse,
} from '@vconnct/devkit';Parameter Reference
CreateQuickRoomParams
| Parameter | Type | Required | Description |
|---|---|---|---|
project_id | string | Yes | Project UUID |
client_room_id | string | Yes | Your unique room identifier |
name | string | No | Room display name |
moderator_id | string | No | Moderator user ID |
max_participants | number | No | Max allowed participants |
empty_timeout | number | No | Seconds before empty room closes |
metadata | object | No | Contains room_title and welcome_message |
CreateScheduleRoomParams
Extends CreateQuickRoomParams with:
| Parameter | Type | Required | Description |
|---|---|---|---|
start_at | string | Yes | ISO8601 datetime for scheduled start |
empty_timeout | number | Yes | Required for scheduled rooms |
InvitationLinkParams
| Parameter | Type | Required | Description |
|---|---|---|---|
room_id | string | Yes | Room UUID |
user_id | string | Yes | User identifier |
role | string | Yes | 'admin' or 'viewer' |
FetchPastRoomsParams
| Parameter | Type | Required | Description |
|---|---|---|---|
project_id | string | Yes | Project UUID |
room_ids | string[] | Yes | Array of room IDs to fetch |
limit | number | No | Max results to return |
from | number | No | Pagination offset |
order_by | string | No | 'ASC' or 'DESC' |
Runtime Requirements
Browser Support:
fetchAPIcrypto.subtle(Web Crypto API) for HMAC signature generation- ES2022 features
For older browsers, you may need appropriate polyfills.
Node.js: Requires Node.js 18.0.0 or higher.
Authentication
All API requests are authenticated using:
keyheader: Your API keyhash-signatureheader: 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