npm package: @socketrsdk/client
Description: Browser client SDK for Socketr — real-time WebSocket channels with auto-reconnect
Author: Socketr
Latest version: 0.1.0

# @socketr/client

Browser client SDK for [Socketr](https://socketr.io) — real-time WebSocket channels with public, private, and presence support.

## Install

```bash
npm install @socketr/client
```

## Quick start

```ts
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

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

### Private

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

### Presence

```ts
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

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

## Lifecycle events

```ts
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. |