Skip to main content
A room is the virtual container. All users, presence, stores, comments, and files are scoped to a room. The Room module provides access to the current room’s details.

​
Room Lifecycle

Rooms are created via the REST API and cannot be created from the client SDK. The typical flow is:
  1. Your backend creates a room via POST /rooms
  2. Your backend adds a user via POST /users, gets a JWT token
  3. The client SDK connects and joins the room using the JWT token 
    // After your backend creates a room and user:
const client = new CollabKitClient({
  serverUrl: 'https://api.collab-kit.com',
  authToken: jwtFromBackend,
});
await client.connect();
await client.join();
// currentUser.status is now 'online'
// Other users receive a 'userJoined' event
  4. The room tracks participants, presence, and all collaboration state After connecting and joining, room information is available using: 
    console.log(client.currentRoom);
// { id, name, state, active_participants, duration_seconds, ... }
    You can also fetch the current room’s details from the server:
    This method also returns a list of users in the room
    const room = await client.room.get();
console.log(room);

// Optionally pass a room ID to fetch a different room:
const otherRoom = await client.room.get({ roomId: 'other-room-id' });

​
Connection Lifecycle

The client exposes low-level connection events via client.socket. Use these to monitor connection state, handle disconnections, and implement custom reconnection logic like so: 
client.socket.on('connected', () => {
  console.log('Initial WebSocket connection established');
});

​
Lifecycle Events

EventPayloadDescription
connectednoneInitial WebSocket connection established and authenticated
disconnectednoneWebSocket connection closed
reconnecting{ attempt: number }A reconnection attempt is starting
reconnectednoneSuccessfully reconnected and state has been rehydrated
failednoneAll reconnection attempts have been exhausted
authFailednoneThe JWT token was rejected by the server

​
Auto-Reconnection

The SDK automatically reconnects when the WebSocket connection drops unexpectedly. It uses exponential backoff with configurable parameters:
  • Reconnection starts immediately after disconnection
  • Each subsequent attempt waits longer (exponential backoff)
  • After all attempts are exhausted, the failed event fires

​
Pre-Reconnect Hooks (Optional)

Register a handler that runs before each reconnection attempt. Use this to refresh tokens or perform setup before reconnecting: 
client.socket.onReconnect(async () => {
  // Refresh the JWT token before reconnecting
  const newToken = await fetchNewToken();
  client.authToken = newToken;
});

​
Connection States

The connection transitions through these states: 
disconnected -> connecting -> connected -> disconnected
                                  |
                                  v
                            reconnecting -> reconnected
                                  |
                                  v
                               failed

​
Examples

​
Offline Queue

Buffer actions while offline and replay them on reconnect: 
const offlineQueue: (() => Promise<void>)[] = [];
let isOnline = true;

client.socket.on('disconnected', () => {
  isOnline = false;
});

client.socket.on('reconnected', async () => {
  isOnline = true;
  // Replay queued actions
  while (offlineQueue.length > 0) {
    const action = offlineQueue.shift();
    await action?.();
  }
});

// Wrapper for store operations
async function safeStoreSet(key: string, value: any) {
  const action = () => client.stores.tasks.set({ key, value });

  if (isOnline) {
    await action();
  } else {
    offlineQueue.push(action);
  }
}