@socketr/client

Browser client SDK for Socketr — real-time WebSocket channels with public, private, and presence support.

Install

npm install @socketr/client

Quick start

import { SocketrClient } from '@socketr/client'

const client = new SocketrClient('wss://socketr-server.fly.dev/app/pk_...')

client.setAuthProvider(async (channelName, channelData) => {
  const res = await fetch('/api/auth', {
    method: 'POST',
    headers: { 'Content-Type': 'application/json' },
    body: JSON.stringify({ channel_name: channelName, channel_data: channelData }),
  })
  return res.json() // { auth, channel_data? }
})

await client.connect()

Channels

Public

const ch = client.channel('my-channel')
ch.on('my-event', (data) => console.log(data))

Private

const { auth } = await fetchAuth(client.socketId, 'private-room')
const ch = client.channelPrivate('private-room', auth)

Presence

const { auth, channel_data } = await fetchAuth(client.socketId, 'presence-room', userId, userInfo)
const ch = client.channelPresence('presence-room', auth, channel_data)

ch.on('member_added', ({ user_id, user_info }) => console.log('joined:', user_id))
ch.on('member_removed', ({ user_id }) => console.log('left:', user_id))

console.log(ch.members)      // PresenceMember[]
console.log(ch.memberCount)  // number

Broadcasting

client.broadcast('my-channel', 'my-event', { message: 'hello' })

Lifecycle events

client.addEventListener('connected',    (e) => console.log('socket id:', e.detail.socketId))
client.addEventListener('reconnecting', (e) => console.log('attempt', e.detail.attempt, 'in', e.detail.delayMs, 'ms'))
client.addEventListener('reconnected',  (e) => console.log('back online'))
client.addEventListener('disconnected', () => console.log('closed'))

Auto-reconnect

The client reconnects automatically with exponential backoff (1s → 30s max) on any unexpected close. When setAuthProvider is registered, private and presence channels are transparently re-authenticated and re-subscribed after every reconnect — no extra code needed.

API

new SocketrClient(wsUrl)

| Method | Description | |---|---| | connect() | Opens the WS connection. Returns Promise<this>. | | setAuthProvider(fn) | Registers the auth callback for private/presence channels. | | channel(name) | Subscribe to a public channel. | | channelPrivate(name, auth) | Subscribe to a private-* channel. | | channelPresence(name, auth, channelData) | Subscribe to a presence-* channel. | | broadcast(channel, event, data?) | Send an event via the open WS connection. | | unsubscribe(channel) | Unsubscribe from a channel. | | disconnect() | Gracefully close (no auto-reconnect). | | socketId | Current socket ID (available after connect). | | connected | true when the WS is open. |

Channel

| Member | Description | |---|---| | on(event, fn) | Listen for an event. Use "*" to catch all events. | | off(event, fn?) | Remove a listener (or all listeners for the event). | | members | PresenceMember[] — presence channels only. | | memberCount | Number of present members. |