Vconnct Developers

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/devkit

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

Supported Frameworks

Frontend Frameworks

FrameworkSupport
ReactFull Support
Vue.jsFull Support
AngularFull Support
SvelteFull Support
Next.jsFull Support
Nuxt.jsFull Support
GatsbyFull Support

Backend Frameworks

FrameworkSupport
Node.jsFull Support
Express.jsFull Support
NestJSFull Support
FastifyFull Support
Koa.jsFull Support

Mobile Development

FrameworkSupport
React NativeFull Support
IonicFull Support
CapacitorFull Support

Desktop Development

FrameworkSupport
ElectronFull Support
TauriFull 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)
});
OptionTypeRequiredDescription
apiKeystringYesYour API key
secretKeystringYesYour secret key for HMAC signing
baseUrlstringNoAPI base URL (default: v4 endpoint)
timeoutnumberNoRequest 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'
});

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 ClassStatus CodeDescription
AuthError401Invalid API key or signature
ValidationError400Request validation failed
NotFoundError404Resource not found
RateLimitError429Rate 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

ParameterTypeRequiredDescription
project_idstringYesProject UUID
client_room_idstringYesYour unique room identifier
namestringNoRoom display name
moderator_idstringNoModerator user ID
max_participantsnumberNoMax allowed participants
empty_timeoutnumberNoSeconds before empty room closes
metadataobjectNoContains room_title and welcome_message

CreateScheduleRoomParams

Extends CreateQuickRoomParams with:

ParameterTypeRequiredDescription
start_atstringYesISO8601 datetime for scheduled start
empty_timeoutnumberYesRequired for scheduled rooms

InvitationLinkParams

ParameterTypeRequiredDescription
room_idstringYesRoom UUID
user_idstringYesUser identifier
rolestringYes'admin' or 'viewer'

FetchPastRoomsParams

ParameterTypeRequiredDescription
project_idstringYesProject UUID
room_idsstring[]YesArray of room IDs to fetch
limitnumberNoMax results to return
fromnumberNoPagination offset
order_bystringNo'ASC' or 'DESC'

Runtime Requirements

Browser Support:

  • fetch API
  • crypto.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:

  • 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