Documentation

Quick start guide for ClotPulse realtime messaging.

1. Install the Client SDK

npm install clotpulse-js

2. Connect from the Browser

import { ClotPulseClient } from 'clotpulse-js';

const client = new ClotPulseClient({
  host: 'wss://your-domain.com',
  appId: 'app_xxxxxxxxxxxx',
  key: 'pk_xxxxxxxxxxxx',
});

await client.connect();

3. Subscribe to a Channel

// Public channel
const channel = client.subscribe('chat');

channel.on('message', (data) => {
  console.log('New message:', data);
});

// Private channel (requires auth token)
const privateChannel = client.subscribe('private-user.123');

// Presence channel
const presenceChannel = client.subscribe('presence-room.42', {
  userInfo: { id: 'user_1', name: 'Alice' },
});

presenceChannel.on('cp:member_added', (member) => {
  console.log('Member joined:', member);
});

4. Publish Events (Server-Side)

import { ClotPulseServer } from 'clotpulse-node';

const pulse = new ClotPulseServer({
  host: 'https://your-domain.com',
  appId: 'app_xxxxxxxxxxxx',
  secretKey: 'sk_xxxxxxxxxxxx',
});

// Publish to a channel
await pulse.publish('chat', 'message', {
  userId: 'user_1',
  text: 'Hello world!',
});

// Publish to multiple channels
await pulse.publishBatch([
  { channel: 'chat', event: 'message', data: { text: 'Hi!' } },
  { channel: 'notifications', event: 'alert', data: { level: 'info' } },
]);

5. REST API — Publish via HTTP

POST /apps/:appId/events/publish

Authenticate with your secret key in the X-API-Key header.

curl -X POST https://your-domain.com/apps/app_xxx/events/publish \
  -H "X-API-Key: sk_xxxxxxxxxxxx" \
  -H "Content-Type: application/json" \
  -d '{
    "channel": "chat",
    "event": "message",
    "data": { "text": "Hello!" }
  }'

6. Webhook Verification

import crypto from 'crypto';

function verifyWebhook(payload: string, signature: string, secret: string) {
  const expected = crypto
    .createHmac('sha256', secret)
    .update(payload)
    .digest('hex');
  return `sha256=${expected}` === signature;
}

// Express handler
app.post('/webhooks/clotpulse', (req, res) => {
  const sig = req.headers['x-clotpulse-signature'];
  const raw = JSON.stringify(req.body);
  
  if (!verifyWebhook(raw, sig, process.env.WEBHOOK_SECRET)) {
    return res.status(401).send('Invalid signature');
  }
  
  console.log('Event:', req.body.event, req.body.channel);
  res.sendStatus(200);
});

Channel Types

publicchat

Anyone can subscribe — no authentication needed.

privateprivate-user.123

Requires a signed auth token from your server.

presencepresence-room.42

Private + member tracking. Members see who else is online.