IRC-kosmi-relay/docs/WEBSOCKET_EVENT_FLOW.md

# WebSocket Event Flow - Jackbox Integration

## Event Broadcasting Behavior

| Event | Broadcast To | Requires Subscription? |
|-------|--------------|------------------------|
| `session.started` | **All authenticated clients** | ❌ NO |
| `game.added` | Session subscribers only | ✅ YES |
| `session.ended` | Session subscribers only | ✅ YES |

## Bot Connection Flow

```
1. Connect to WebSocket
   ↓
2. Send auth message with JWT token
   ↓
3. Receive auth_success
   ↓
4. Wait for session.started (automatic broadcast)
   ↓
5. When session.started received:
   - Subscribe to that specific session ID
   - Announce "Game Night is starting!"
   ↓
6. Receive game.added events (for subscribed session)
   - Announce new games
   ↓
7. Receive session.ended event (for subscribed session)
   - Announce final votes + goodnight
```

## Message Formats

### 1. Authentication
**Bot → Server:**
```json
{
  "type": "auth",
  "token": "eyJhbGciOiJIUzI1NiIsInR5cCI6IkpXVCJ9..."
}
```

**Server → Bot:**
```json
{
  "type": "auth_success",
  "message": "Authenticated successfully"
}
```

### 2. Session Started (Automatic Broadcast)
**Server → Bot:**
```json
{
  "type": "session.started",
  "timestamp": "2025-11-01T03:24:30Z",
  "data": {
    "session": {
      "id": 21,
      "is_active": 1,
      "created_at": "2025-11-01 07:24:30",
      "notes": null
    }
  }
}
```

**Bot Action:**
- Automatically subscribe to this session
- Announce "🎮 Game Night is starting! Session #21"

### 3. Subscribe to Session
**Bot → Server:**
```json
{
  "type": "subscribe",
  "sessionId": 21
}
```

**Server → Bot:**
```json
{
  "type": "subscribed",
  "message": "Subscribed to session 21"
}
```

### 4. Game Added (Requires Subscription)
**Server → Bot:**
```json
{
  "type": "game.added",
  "timestamp": "2025-11-01T03:25:00Z",
  "data": {
    "session": {
      "id": 21,
      "is_active": true,
      "games_played": 1
    },
    "game": {
      "id": 42,
      "title": "Drawful 2",
      "pack_name": "Drawful 2",
      "min_players": 3,
      "max_players": 8,
      "manually_added": false
    }
  }
}
```

**Bot Action:**
- Announce previous game's votes (if any)
- Announce "🎮 Coming up next: Drawful 2!"

### 5. Session Ended (Requires Subscription)
**Server → Bot:**
```json
{
  "type": "session.ended",
  "timestamp": "2025-11-01T04:30:00Z",
  "data": {
    "session": {
      "id": 21,
      "is_active": 0,
      "games_played": 5
    }
  }
}
```

**Bot Action:**
- Announce final game's votes (if any)
- Announce "🌙 Game Night has ended! Thanks for playing!"
- Clear active session (reset to time-based vote debouncing)

## Fallback Polling

If WebSocket events are missed, the bot has a fallback polling mechanism (every 30 seconds):

- **Detects new sessions** via HTTP GET `/api/sessions/active`
- **Detects ended sessions** when active session becomes null/inactive
- **Logs warnings** when polling detects changes (indicates missed WebSocket events)

Example warning logs:
```
WARN Found active session 21 via polling (session.started event may have been missed)
WARN Active session ended (detected via polling, session.ended event may have been missed)
```

## Testing

### Expected Logs (Happy Path)
```
INFO Authentication successful
INFO Session started: ID=21
INFO Subscribed to session 21
INFO Active session set to 21
INFO Broadcasting Jackbox message: 🎮 Game Night is starting! Session #21
INFO Subscription confirmed: Subscribed to session 21
INFO Game added: Drawful 2 from Drawful 2
INFO Broadcasting Jackbox message: 🎮 Coming up next: Drawful 2!
INFO Session ended event received
INFO Broadcasting Jackbox message: 🌙 Game Night has ended! Thanks for playing!
```

### Expected Logs (Fallback Polling)
```
INFO Authentication successful
WARN Found active session 21 via polling (session.started event may have been missed), subscribing...
INFO Subscribed to session 21
```

## Troubleshooting

### Bot doesn't receive `session.started`
- Check backend logs: Should say "Broadcasted session.started to X client(s)"
- Check bot is authenticated: Look for "Authentication successful" in logs
- Check WebSocket connection: Should say "WebSocket connected"

### Bot doesn't receive `game.added` or `session.ended`
- Check bot subscribed to session: Look for "Subscribed to session X" in logs
- Check backend logs: Should say "Broadcasted game.added to X client(s) for session Y"
- If X = 0, bot didn't subscribe properly

### Polling warnings appear
- This means WebSocket events aren't being received
- Check your backend is calling `broadcastToAll()` for `session.started`
- Check your backend is calling `broadcastEvent(sessionId)` for `game.added` and `session.ended`