docs: add game-status-by-session guide and external downstream clients reference

Co-authored-by: Cursor <cursoragent@cursor.com>
2026-05-07 20:43:10 -04:00
parent 195448644a
commit 1c9f0ef280
3 changed files with 272 additions and 1 deletions
--- a/docs/api/guides/game-status-by-session.md
+++ b/docs/api/guides/game-status-by-session.md
@@ -0,0 +1,187 @@
+# Game Status by Session
+
+How to build a complete view of all enabled games—with popularity data and whether each game has been played in the current session. No single endpoint returns all three pieces today; this guide shows how to combine two public endpoints and join the results client-side.
+
+---
+
+## 1. Fetch Enabled Games
+
+`GET /api/games?enabled=true` returns every enabled game in the catalog. Each row includes `popularity_score`, `upvotes`, `downvotes`, `play_count`, and `favor_bias`.
+
+**Why:** This gives you the full list of games that are available for play, along with their cumulative popularity data across all sessions.
+
+See [Games endpoints](../endpoints/games.md) for all available filters (`playerCount`, `drawing`, `length`, `familyFriendly`, `pack`).
+
+```bash
+curl "http://localhost:5000/api/games?enabled=true"
+```
+
+**Sample response (200 OK):**
+
+```json
+[
+  {
+    "id": 1,
+    "pack_name": "Jackbox Party Pack 7",
+    "title": "Quiplash 3",
+    "min_players": 3,
+    "max_players": 8,
+    "length_minutes": 15,
+    "has_audience": 1,
+    "family_friendly": 0,
+    "game_type": "Writing",
+    "secondary_type": null,
+    "play_count": 4,
+    "popularity_score": 7,
+    "upvotes": 10,
+    "downvotes": 3,
+    "enabled": 1,
+    "favor_bias": 0,
+    "created_at": "2024-01-15T12:00:00.000Z"
+  },
+  {
+    "id": 5,
+    "pack_name": "Jackbox Party Pack 9",
+    "title": "Fibbage 4",
+    "min_players": 2,
+    "max_players": 8,
+    "length_minutes": 15,
+    "has_audience": 1,
+    "family_friendly": 1,
+    "game_type": "Trivia",
+    "secondary_type": null,
+    "play_count": 2,
+    "popularity_score": 3,
+    "upvotes": 5,
+    "downvotes": 2,
+    "enabled": 1,
+    "favor_bias": 1,
+    "created_at": "2024-01-15T12:00:00.000Z"
+  }
+]
+```
+
+---
+
+## 2. Fetch Session Games
+
+`GET /api/sessions/{id}/games` returns games that have been added to a specific session. Each row includes `status` (`playing`, `played`, or `skipped`), `played_at`, and joined popularity fields from the game catalog.
+
+**Why:** This tells you which games have already been played (or are currently playing) in the session, so you can mark them in the catalog.
+
+See [Sessions endpoints](../endpoints/sessions.md) for full details on session game fields.
+
+```bash
+curl "http://localhost:5000/api/sessions/5/games"
+```
+
+**Sample response (200 OK):**
+
+```json
+[
+  {
+    "id": 14,
+    "session_id": 5,
+    "game_id": 1,
+    "played_at": "2026-03-15T20:30:00.000Z",
+    "manually_added": 0,
+    "status": "played",
+    "room_code": "LSBN",
+    "player_count": 6,
+    "player_count_check_status": "completed",
+    "pack_name": "Jackbox Party Pack 7",
+    "title": "Quiplash 3",
+    "game_type": "Writing",
+    "min_players": 3,
+    "max_players": 8,
+    "popularity_score": 7,
+    "upvotes": 10,
+    "downvotes": 3
+  }
+]
+```
+
+Key fields for the join:
+
+| Field | Purpose |
+|-------|---------|
+| `game_id` | Matches `id` in the games catalog |
+| `status` | `playing`, `played`, or `skipped` |
+| `played_at` | When the game was added to the session |
+
+---
+
+## 3. Combine Client-Side
+
+Join the two responses by matching `game_id` (from session games) to `id` (from the catalog). This produces a single list of enabled games annotated with their session play status.
+
+```javascript
+const gamesRes = await fetch('/api/games?enabled=true');
+const games = await gamesRes.json();
+
+const sessionGamesRes = await fetch('/api/sessions/5/games');
+const sessionGames = await sessionGamesRes.json();
+
+const sessionGameMap = new Map(
+  sessionGames.map(sg => [sg.game_id, sg])
+);
+
+const combined = games.map(game => {
+  const sessionEntry = sessionGameMap.get(game.id);
+  return {
+    ...game,
+    playedInSession: !!sessionEntry,
+    sessionStatus: sessionEntry?.status ?? null,
+    sessionPlayedAt: sessionEntry?.played_at ?? null,
+  };
+});
+```
+
+**Sample merged output (one entry):**
+
+```json
+{
+  "id": 1,
+  "pack_name": "Jackbox Party Pack 7",
+  "title": "Quiplash 3",
+  "min_players": 3,
+  "max_players": 8,
+  "length_minutes": 15,
+  "has_audience": 1,
+  "family_friendly": 0,
+  "game_type": "Writing",
+  "play_count": 4,
+  "popularity_score": 7,
+  "upvotes": 10,
+  "downvotes": 3,
+  "enabled": 1,
+  "favor_bias": 0,
+  "playedInSession": true,
+  "sessionStatus": "played",
+  "sessionPlayedAt": "2026-03-15T20:30:00.000Z"
+}
+```
+
+Games that have not been played in the session will have `playedInSession: false`, `sessionStatus: null`, and `sessionPlayedAt: null`.
+
+---
+
+## Quick Reference
+
+| Data point | `GET /api/games` | `GET /api/sessions/{id}/games` |
+|------------|------------------|-------------------------------|
+| Enabled status | `enabled` field + `?enabled=true` filter | Not included |
+| Popularity score | `popularity_score`, `upvotes`, `downvotes` | `popularity_score`, `upvotes`, `downvotes` (joined) |
+| All-time play count | `play_count` | Not included |
+| Played in session | Not included | `status` field (`playing`/`played`/`skipped`) |
+| Auth required | No | No |
+
+---
+
+## Related Documentation
+
+- [Games endpoints](../endpoints/games.md) — full catalog CRUD, filters, favor bias
+- [Sessions endpoints](../endpoints/sessions.md) — session games, status updates, room codes
+- [Picker endpoint](../endpoints/picker.md) — weighted random selection with session exclusion
+- [Stats endpoint](../endpoints/stats.md) — `mostPlayedGames`, `topRatedGames`
+- [Voting & Popularity guide](voting-and-popularity.md) — how votes and popularity scores work