@vconnct/devkit

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

• Website: https://vcloud.vconnct.me/
• Documentation: https://guide.vconnct.com/

Supported Frameworks

Works with all major JavaScript/TypeScript frameworks:

| Framework | Support | |-----------|---------| | | Full Support | | | Full Support | | | Full Support | | | Full Support | | | Full Support | | | Full Support | | | Full Support | | | Full Support | | | Full Support |

Features

• 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

Installation

npm install @vconnct/devkit

yarn add @vconnct/devkit

pnpm add @vconnct/devkit

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)
});

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 from input)
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 Support

This SDK is written in TypeScript and includes full type definitions. All request parameters and response types are fully typed.

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' |

Browser Support

The SDK works in modern browsers that support:

• fetch API
• crypto.subtle (Web Crypto API) for HMAC signature generation
• ES2022 features

For older browsers, you may need appropriate polyfills.

Node.js Support

Requires Node.js 18.0.0 or higher.

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

License

MIT License

Links

• Website: https://vcloud.vconnct.me/
• Documentation: https://guide.vconnct.com/
• Support: [email protected]