covekit

The official JavaScript/TypeScript SDK for the CoveKit Media Suite. This package provides headless WebRTC meeting orchestration, media transport handshakes, and signaling channel loops.

Installation

npm install covekit

Integration Paths

Developers can integrate CoveKit in two ways:

1. Option A: Direct Embed (Low-Code / Complete UI): Embed our pre-built responsive UI widget inside an iframe.
2. Option B: Headless SDK (Pro-Code / Custom UI): Orchestrate WebRTC connections and media tracks programmatically to build a custom interface.

Option A: Direct Embed

Render an <iframe> referencing the CoveKit meeting URL with specific query parameters to hide standard menus/headers and automatically enter the room:

<iframe
  src="https://meet.covekit.com/m/lobby?embed=true&autoJoin=true&displayName=Satoshi&mic=on&cam=off"
  allow="camera; microphone; display-capture; fullscreen"
  style="width: 100%; height: 600px; border: none; border-radius: 8px;"
></iframe>

Supported Query Parameters:

• embed=true (Required): Strips out header spacing, navigation menus, and lobby wrappers.
• autoJoin=true (Optional): Skips the lobby settings stage and joins automatically.
• displayName (Optional): Prepopulates the user's name (required if autoJoin is active).
• passcode (Optional): Prepopulates the password.
• mic=on|off (Optional): Defaults the starting microphone state.
• cam=on|off (Optional): Defaults the starting camera state.

Option B: Headless SDK

Orchestrate the WebRTC media transports programmatically to build a custom UI.

import { CoveKitClient, CoveKitRoom } from 'covekit';

const client = new CoveKitClient();

// 1. Get meeting token
const session = await client.joinPublicMeeting('lobby-room', 'Alice');

// 2. Initialize connection
const room = new CoveKitRoom(client, {
  onConnected: (info) => {
    console.log('Connected! Session ID:', info.sessionId);
    // Request permission & publish mic/cam tracks
    room.publishLocalMedia(true, true);
  },
  onLocalStream: (stream) => {
    // Render local preview player
    const localVideo = document.getElementById('local-video') as HTMLVideoElement;
    localVideo.srcObject = stream;
  },
  onRemoteTrack: (track, peerId, kind) => {
    // Handle remote participant video/audio tracks
    const mediaStream = new MediaStream([track]);
    const remoteVideo = document.getElementById(`peer-${peerId}`) as HTMLVideoElement;
    if (remoteVideo) {
      remoteVideo.srcObject = mediaStream;
    }
  },
  onPeerJoin: (peer) => {
    console.log(`${peer.displayName} joined the call`);
  },
  onPeerLeave: (peerId) => {
    console.log(`Peer ${peerId} left`);
  },
  onPeerMuteStateChanged: (peerId, kind, muted) => {
    console.log(`Peer ${peerId} ${kind} is ${muted ? 'muted' : 'unmuted'}`);
  },
  onWhiteboardUpdate: (peerId, elements) => {
    console.log('Received whiteboard vector sync chunk:', elements);
  },
  onError: (error) => {
    console.error('Room signaling error:', error);
  }
});

// 3. Connect WebRTC media loops
await room.join(session.token, session.ice_servers);

API Reference

CoveKitClient

Main client class for talking to the CoveKit Control Plane.

Constructor

new CoveKitClient(config?: { apiBaseUrl?: string; mediaWsUrl?: string })
// or positional overrides (for backwards compatibility):
new CoveKitClient(apiBaseUrl?: string, mediaWsUrl?: string)

Methods

• joinPublicMeeting(publicId: string, displayName: string, passcode?: string, hostToken?: string): Establishes a session token and connects to waiting rooms.
• getPublicMeeting(publicId: string): Retrieves meeting metadata (e.g. title, status, meeting mode).
• pollSessionStatus(publicId: string, sessionId: string): Checks if the host has admitted the user from the waiting room.

CoveKitRoom

Handles room-wide media track lifecycle events and WebRTC connection pipelines.

Constructor

new CoveKitRoom(client: CoveKitClient, events: CoveKitRoomEvents)

Methods

• join(token: string, iceServers?: any[]): Connects the WebRTC signaling WebSocket.
• leave(): Stops all local streams, closes active producers, and tears down signaling.
• publishLocalMedia(audio: boolean, video: boolean, audioDeviceId?: string, existingStream?: MediaStream): Invokes the user's browser device permissions and publishes selected tracks.
• publishTrack(kind: 'audio' | 'video', track: MediaStreamTrack, appData?: any): Publishes a custom track.
• replaceTrack(kind: 'audio' | 'video', track: MediaStreamTrack | null, appData?: any): Swaps an active track in-place on the current WebRTC producer.
• toggleMute(kind: 'audio' | 'video', muted: boolean): Mutes/unmutes media tracks and broadcasts state to peers.
• sendWhiteboardUpdate(elements: any): Broadcasts real-time collaborative whiteboard updates to peers.
• kickParticipant(peerId: string): [Host Only] Evicts a participant from the room.
• endMeetingRoom(): [Host Only] Terminates the meeting session for everyone.

Authentication & Security

To prevent unauthorized access and protect your resources, CoveKit utilizes a two-tier authentication architecture:

1. Backend Server (Private - API Key): Your backend server manages meeting room creation and participant authorization. Secure these API requests from your server to the Control Plane by sending your secret API key in the X-API-Key header.

   [!WARNING] Never expose your X-API-Key in client-side code (browsers). Doing so allows anyone to create rooms, fetch session logs, or abuse your account.

2. Client-Side SDK / Iframe (Public - Room IDs): The client-side covekit SDK and the iframe embed only require the public room (publicId) and optionally a passcode. The client-side client handles WebRTC signaling and media stream loops using public, session-specific endpoints without exposing your secret API key.