Rooms

​

Room Lifecycle

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.join(); // defaults to { role: 'editor' }
   // currentUser.status is now 'online'
   // Other users receive a 'userJoined' event only when this session is an editor
   
4. The room tracks participants, presence, and all collaboration state Users can join as an editor or viewer:
   await client.join({ role: 'viewer' });
   console.log(client.role); // 'viewer'
   
   await client.updateRole('editor');
   
   Roles are session-scoped. Editors are active collaborators and appear in client.users.active; viewers receive realtime updates and can follow users, but cannot write 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 returns room details. Use client.users.list(...) for paginated users and client.users.active for active editors.
   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

client.socket.on('connected', () => {
  console.log('Initial WebSocket connection established');
});

​

Lifecycle Events

​

Auto-Reconnection

• 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)

client.socket.onReconnect(async () => {
  // Refresh the JWT token before reconnecting
  const newToken = await fetchNewToken();
  client.authToken = newToken;
});

​

Connection States

disconnected -> connecting -> connected -> disconnected
                                  |
                                  v
                            reconnecting -> reconnected
                                  |
                                  v
                               failed

​

Examples

​

Offline Queue

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);
  }
}