PulseClient API

When Do You Need This?

Most users only need <pulse-widget>. The PulseClient API is for building your own custom UI instead of using the built-in widget.

PulseClient is the low-level client that connects to the Pulse server. The widget uses it internally.

Setup

import { PulseClient } from '@gamention/pulse-core';

const client = new PulseClient({
  apiKey: 'pk_your_key',
  token: userToken,
  room: 'dashboard',
  endpoint: 'wss://pulse.hire.rest'
});

client.connect();

Option	Type	Required	Description
apiKey	string	Yes	Publishable key (pk_...)
token	string	Yes	User JWT from /auth/token
room	string	Yes	Room identifier
endpoint	string	Yes	Pulse server WebSocket URL

Connection

client.connect();                           // Connect
client.disconnect();                        // Disconnect and clean up
console.log(client.connectionState);        // "connected" | "connecting" | "disconnected"

client.on('connection', (state) => { ... });  // Listen for changes

Threads & Comments

// Create a thread (returns the thread ID)
const threadId = client.createThread('This button looks off', {
  mentions: ['user-2'],                  // optional @mentions
  position: { x: 0.45, y: 0.72 }        // optional pin position (0-1 range)
});

// Reply to a thread (returns the comment ID)
const commentId = client.reply('thread-id', 'Agreed, fixing now', ['user-1']);

// Edit your own comment
client.editComment('comment-id', 'Updated text', []);

// Delete your own comment
client.deleteComment('comment-id');

// Resolve / reopen a thread
client.resolveThread('thread-id', true);   // resolve
client.resolveThread('thread-id', false);  // reopen

Reactions

client.addReaction('comment-id', 'comment', '👍');
client.removeReaction('reaction-id');

Presence & Cursors

client.moveCursor({ x: 0.5, y: 0.3, pageX: 500, pageY: 300 });
client.updatePresence('idle');           // 'online' | 'idle'
client.setAppearOffline(true);           // hide from presence

Other Interactions

client.sendTyping('thread-id');          // typing indicator
client.performClick({ x: 0.5, y: 0.3, pageX: 500, pageY: 300 });

client.drawStroke(
  [{ x: 100, y: 200 }, { x: 150, y: 250 }],
  '#ff0000', 3
);
client.clearDrawing();

Notifications

client.markRead('notification-id');
client.markAllRead();

Accessing State

client.state.user;           // Current user (PulseUser)
client.state.threads;        // All threads (Thread[])
client.state.presence;       // Online users (PresenceUser[])
client.state.notifications;  // User notifications (Notification[])
client.state.reactions;       // All reactions (Reaction[])
client.state.getUser('id');  // Look up any user by ID

See State & Events for subscribing to changes.