Client SDK

Client SDK

Vanilla JavaScript client for framework-agnostic usage.

Installation

npm install @realtime-sdk/client

RealtimeClient

The main client class for connecting to the server.

import { RealtimeClient } from '@realtime-sdk/client';
 
const client = new RealtimeClient({
  endpoint: 'wss://api.realtimesdk.dev',
  authToken: 'your-jwt-token',
});
 
await client.connect();

Constructor Options

interface RealtimeConfig {
  endpoint: string;
  authToken: string | (() => string) | (() => Promise<string>);
  heartbeatInterval?: number;  // default: 30000
  heartbeatTimeout?: number;   // default: 10000
  maxReconnectAttempts?: number; // default: 10
  reconnectBaseDelay?: number;  // default: 1000
  reconnectMaxDelay?: number;   // default: 30000
  debug?: boolean;             // default: false
}

Methods

connect()

Connect to the server.

await client.connect();

disconnect()

Disconnect from the server.

client.disconnect();

room(roomId)

Get or create a room instance.

const room = client.room('my-room');

Properties

Property	Type	Description
status	ConnectionStatus	Current connection status
connection	ConnectionInfo	Connection details

Events

client.on('connection:status', (status) => {
  console.log('Connection:', status);
});
 
client.on('connection:error', (error) => {
  console.error('Error:', error);
});

Room

Represents a collaboration room.

join(options?)

Join the room.

await room.join({
  metadata: { name: 'Alice' }
});

leave()

Leave the room.

room.leave();

updatePresence(data)

Update your presence data.

room.updatePresence({ status: 'away' });

updateCursor(position)

Update your cursor position.

room.updateCursor({ x: 100, y: 200 });
// or hide cursor
room.updateCursor(null);

broadcast(event, data)

Send a custom event to the room.

room.broadcast('emoji', { type: '👋' });

Properties

Property	Type	Description
id	string	Room ID
status	RoomStatus	Current room status
users	PresenceUser[]	All users
self	PresenceUser | null	Current user
others	PresenceUser[]	Other users

Events

room.on('status', (status) => { ... });
room.on('presence:sync', (users) => { ... });
room.on('presence:join', (user) => { ... });
room.on('presence:leave', (userId) => { ... });
room.on('presence:update', ({ userId, data }) => { ... });
room.on('cursor:update', ({ userId, position }) => { ... });
room.on('broadcast', ({ event, data, senderId }) => { ... });

Types

ConnectionStatus

type ConnectionStatus = 
  | 'connecting'
  | 'connected' 
  | 'disconnected'
  | 'reconnecting';

RoomStatus

type RoomStatus =
  | 'joining'
  | 'joined'
  | 'leaving'
  | 'left'
  | 'error';

PresenceUser

interface PresenceUser {
  id: string;
  connectionId: string;
  color: string;
  data: Record<string, unknown>;
  cursor: CursorPosition | null;
  joinedAt: number;
}

CursorPosition

interface CursorPosition {
  x: number;
  y: number;
  selectionStart?: number;
  selectionEnd?: number;
}