HyperSpaceOut/jackboxpartypack-gamepicker

Files

Add design doc for Jackbox ecast API reverse engineering

Defines scope, methodology (REST probing + WebSocket interception),
and documentation structure for comprehensive API documentation effort.

Made-with: Cursor

2026-03-20 09:18:55 -04:00

3.1 KiB

Raw Blame History

Jackbox Ecast API Reverse Engineering — Design

Date: 2026-03-20 Goal: Produce comprehensive documentation of the Jackbox ecast API (REST + WebSocket) through live traffic analysis. Deliverable: docs/jackbox-ecast-api.md

Scope

In Scope

Ecast REST API — All discoverable endpoints at ecast.jackboxgames.com, including undocumented paths, multiple API versions, and different HTTP methods.
Ecast WebSocket Protocol — Full bidirectional message protocol between jackbox.tv and ecast servers: connection handshake, all opcodes/message types, entity model, and state transitions through the complete game lifecycle.
Player & Room Management — Join/leave detection, real-time player count, max players, lobby lock/game start signals, game completion signals, player and game stats/results.

Out of Scope

Kosmi integration (chrome extension)
This application's own API
Game-specific mechanics (drawing, voting within Drawful 2) unless they reveal useful metadata

Approach

Primary: REST probing + browser console WebSocket interception (Approach A) Fallback: Puppeteer + CDP automated capture script (Approach B)

Phase 1 — REST API Probing

Probe known endpoint GET /api/v2/rooms/{code} and document full response
Discover new paths: /players, /audience, /state, etc.
Try API versions v1, v3
Check for discovery endpoints (/api, /swagger, /openapi, /health)
Try different HTTP methods (POST, PUT, OPTIONS)
Document all response schemas, headers, status codes

Phase 2 — WebSocket Interception

Navigate to jackbox.tv in browser
Inject WebSocket interceptor (monkey-patch WebSocket) before joining room
Join as player — capture full connection lifecycle
Join as audience — capture audience-specific messages
If injection races with connection, reload page after patching

Phase 3 — Game Lifecycle Capture

Walk through entire Drawful 2 lifecycle with interceptor running:

Lobby: join/leave messages, player list updates
Game start: lock signal, round info
Gameplay: state transitions, metadata
Game end: results, stats, disconnection sequence
Multiple players to observe multi-player messages

Fallback (Approach B)

If browser console interception is unreliable, write a Node.js script using Puppeteer + CDP Network.webSocketFrame* events for automated structured capture.

Documentation Structure

The deliverable (docs/jackbox-ecast-api.md) will contain:

Overview — What ecast is, base URLs, architecture
REST API Reference — Each endpoint with method, URL, params, response schema, notes
WebSocket Protocol Reference — Connection details, message format, message catalog (all opcodes), entity model
Game Lifecycle — Sequence diagram of message flow from room creation through completion
Player & Room Management — Answers to specific questions (join/leave detection, player count, max players, lock/start, completion, stats) with supporting evidence
Appendix: Raw Captures — Sanitized example payloads

3.1 KiB Raw Blame History