websocket-realtime

# websocket-realtime

Receive live vote updates from poll-builder via WebSocket.

## Connection

```
ws://localhost:3000/ws
```

## Protocol

### Subscribe to a poll

After connecting, send a subscribe message with the poll slug:

```json
{ "type": "subscribe", "slug": "k9xm2q4r" }
```

### Receive updates

The server sends an update message after each successful vote:

```json
{
  "type": "update",
  "slug": "k9xm2q4r",
  "results": [
    { "optionId": 1, "text": "Mobile app",        "votes": 396, "pct": 48.1 },
    { "optionId": 2, "text": "API improvements",  "votes": 255, "pct": 31.0 },
    { "optionId": 3, "text": "Better docs",       "votes": 123, "pct": 14.9 },
    { "optionId": 4, "text": "Admin dashboard",   "votes": 50,  "pct": 6.1  }
  ],
  "totalVotes": 824
}
```

### Unsubscribe

Close the connection or send:

```json
{ "type": "unsubscribe", "slug": "k9xm2q4r" }
```

## Example (Node.js)

```javascript
import WebSocket from 'ws';

const ws = new WebSocket('ws://localhost:3000/ws');

ws.on('open', () => {
  ws.send(JSON.stringify({ type: 'subscribe', slug: 'k9xm2q4r' }));
});

ws.on('message', (data) => {
  const msg = JSON.parse(data.toString());
  if (msg.type === 'update') {
    console.log(`Total votes: ${msg.totalVotes}`);
    msg.results.forEach(r => {
      console.log(`  ${r.text}: ${r.votes} (${r.pct}%)`);
    });
  }
});
```

## Multiple subscriptions

A single WebSocket connection can subscribe to multiple polls:

```json
{ "type": "subscribe", "slug": "k9xm2q4r" }
{ "type": "subscribe", "slug": "7bwq1pz3" }
```

Each update message includes the `slug` field to identify which poll triggered it.

## Error handling

If the slug does not exist:
```json
{ "type": "error", "message": "poll_not_found", "slug": "k9xm2q4r" }
```

The connection remains open - you can subscribe to other slugs.

## Notes

- Updates are broadcast only to clients subscribed to the relevant slug
- Closed polls do not generate updates (no new votes accepted)
- The WebSocket server is part of the same Node.js process as the HTTP server
- No authentication required for public WebSocket connections