@whogoes/client

A lightweight TypeScript client for the Whogoes presence service.

Installation

npm install @whogoes/client

Basic Usage

Initialization

Create a new PresenceClient instance with your server endpoint.

import { PresenceClient } from '@whogoes/client';

const client = new PresenceClient({
  endpoint: 'ws://localhost:3000/ws',
  token: () => 'your-auth-token', // Function returning a Promise or string
});

Joining a Room

Join a room to start receiving presence updates.

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

The join method returns a Room instance which handles connection management and event subscriptions. It also automatically handles multiple tabs for the same room, ensuring only one WebSocket connection is open per browser instance (Leader Election).

Listening to Events

The Room instance emits events for presence changes.

// Initial state of the room
room.on('snapshot', (sessions) => {
  console.log('Current users:', sessions);
});

// A user updated their state (e.g. moved cursor)
room.on('update', (session) => {
  console.log('User updated:', session);
});

// A new user joined
room.on('join', (session) => {
  console.log('User joined:', session);
});

// A user left
room.on('leave', (sessionId) => {
  console.log('User left:', sessionId);
});

API Reference

PresenceClient

• constructor(config: PresenceClientConfig)
• join(roomId: string): Room

Room

• update(payload: Partial<SessionPayload>): Broadcasts an update about the current user to the room.
• leave(): Disconnects from the room.
• on(event: string, callback: Function): Subscribe to events.

Events

• snapshot: Fired immediately after connection with the full list of active sessions.
• update: Fired when a peer updates their presence data.
• join: Fired when a new peer joins the room.
• leave: Fired when a peer leaves the room.