@vconnct/devkit

TypeScript and JavaScript REST SDK for the Qriib v4 API. The published package name remains @vconnct/devkit; QriibClient is the primary client and the legacy VCloudClient export remains available for existing integrations.

The default API base URL is https://api.qriib.dev/api/v4.

Installation

npm install @vconnct/devkit

Quick start

Project-scoped endpoints (rooms, recordings, analytics, and branding) need only a project credential pair:

import { QriibClient } from '@vconnct/devkit';

const client = new QriibClient({
  project: {
    apiKey: 'YOUR_PROJECT_API_KEY',
    secretKey: 'YOUR_PROJECT_SECRET_KEY',
  },
});

const room = await client.rooms.createQuickVideoRoom({
  project_id: 'PROJECT_ID',
  client_room_id: 'support-42',
});

Do not put secret keys in browser-delivered source, a repository, or a log. Obtain credentials through your deployment's secure configuration instead.

Project and organization scopes

Project-management endpoints use a separate organization credential pair. Pass both scopes when the application calls both kinds of endpoint:

const client = new QriibClient({
  project: {
    apiKey: 'YOUR_PROJECT_API_KEY',
    secretKey: 'YOUR_PROJECT_SECRET_KEY',
  },
  organization: {
    apiKey: 'YOUR_ORGANIZATION_API_KEY',
    secretKey: 'YOUR_ORGANIZATION_SECRET_KEY',
  },
  // Optional; defaults to https://api.qriib.dev/api/v4
  baseUrl: 'https://api.qriib.dev/api/v4',
  timeout: 30_000,
});

const project = await client.projects.createProject({
  organization_id: 'ORGANIZATION_ID',
  project_name: 'Customer support',
});

Calling an organization endpoint without organization credentials rejects before a request is made. The legacy client is equivalent to project-only configuration:

import { VCloudClient } from '@vconnct/devkit';

const client = new VCloudClient({
  apiKey: 'YOUR_PROJECT_API_KEY',
  secretKey: 'YOUR_PROJECT_SECRET_KEY',
});

REST resource groups

All resource instances are available from QriibClient.

client.rooms — project scope

| Method | REST operation | | --- | --- | | createQuickAudioRoom(params) | Create an immediate audio room | | createQuickVideoRoom(params) | Create an immediate video room | | createScheduleAudioRoom(params) | Schedule an audio room | | createScheduleVideoRoom(params) | Schedule a video room | | startScheduledRoom(params) | Start a scheduled room | | getActiveRoomInfo(roomId) | Read one active room | | getAllActiveRooms() | List active rooms | | fetchPastRooms(params) | Retrieve past rooms for a project | | createInvitationLink(params) | Create a room invitation | | joinRoom(params) | Join a room using REST | | getRoomStatus(roomId) | Read room status | | endRoom(roomId) | End a room |

joinRoom accepts a room_id and user_info. Its optional user_info.role is sent as role metadata. Invitation roles are host, moderator, or attendee.

client.projects — organization scope

| Method | REST operation | | --- | --- | | createProject(params) | Create a project | | getProject(projectId) | Read a project | | getProjects(organizationId) | List an organization's projects | | updateProject(params) | Update project settings | | updateProjectStatus(projectId, status) | Set status to active or inactive |

client.recordings — project scope

| Method | REST operation | | --- | --- | | getRecord(roomId) | Retrieve the raw recording payload for a room | | getRecordingLink(recordingId) | Retrieve a signed recording link payload | | getRecords(projectId) | Retrieve raw recording payloads for a project | | getRecording(roomId) | Compatibility helper that unwraps a record payload when present | | getRecordingUrls(roomId) | Compatibility helper returning recording URLs |

client.analytics — project scope

getAnalytics(roomId) retrieves the analytics data object for a room.

client.branding — project scope

create(params) and update(params) manage project branding with multipart form data. Branding files can be browser Blob/File values or Node Buffer values.

Errors

HTTP errors are mapped to Qriib error classes. Each error includes a message; the base class also exposes statusCode and the response payload when present.

| Status | Error | | --- | --- | | 401, 403 | QriibAuthenticationError | | 400, 422 | QriibValidationError | | 404 | QriibNotFoundError | | 429 | QriibRateLimitError (retryAfter when supplied) | | Other non-success statuses | QriibError |

import {
  QriibAuthenticationError,
  QriibError,
  QriibNotFoundError,
  QriibRateLimitError,
  QriibValidationError,
} from '@vconnct/devkit';

try {
  await client.rooms.getActiveRoomInfo('ROOM_ID');
} catch (error) {
  if (error instanceof QriibAuthenticationError) {
    // Check the selected API key and request signature.
  } else if (error instanceof QriibValidationError) {
    // Correct the request parameters.
  } else if (error instanceof QriibNotFoundError) {
    // The requested resource is unavailable.
  } else if (error instanceof QriibRateLimitError) {
    // Retry after error.retryAfter seconds when supplied.
  } else if (error instanceof QriibError) {
    // Handle other API responses.
  }
}

For compatibility, VCloudError, AuthError, ValidationError, NotFoundError, and RateLimitError are aliases of their Qriib-named counterparts.

Request signatures

The SDK adds the selected credential pair's key header and an HMAC-SHA256, Base64-encoded hash-signature header automatically. GET requests sign the normalized API path (including /api/v4) and encoded query string. JSON POST, PUT, and PATCH requests sign the exact serialized JSON body. Multipart branding requests sign their project_id and let the runtime set the multipart content boundary.

Runtime support

The SDK supports Node.js 18 or later and modern browsers. Browser use requires fetch, FormData, Blob, and Web Crypto (crypto.subtle) for signing. Node uses its built-in crypto implementation. Supply credentials from an appropriate secure runtime boundary for the application architecture.

Scope limitation

This package is a REST SDK only. It does not include a browser meeting UI, WebRTC engine, live camera or microphone controls, or token-based meeting sessions.

License

MIT