121 lines
4.0 KiB
Markdown
121 lines
4.0 KiB
Markdown
|
# Picker Endpoints
|
|||
|
|
|
|||
|
|
Weighted random game selection. Picks from enabled games matching your filters, with favor bias affecting probability. Avoids recently played games within a session.
|
|||
|
|
|
|||
|
|
## Endpoint Summary
|
|||
|
|
|
|||
|
|
| Method | Path | Auth | Description |
|
|||
|
|
|--------|------|------|-------------|
|
|||
|
|
| POST | `/api/pick` | No | Pick a random game with filters and repeat avoidance |
|
|||
|
|
|
|||
|
|
---
|
|||
|
|
|
|||
|
|
## POST /api/pick
|
|||
|
|
|
|||
|
|
Select a game using weighted random selection. Filters to only enabled games, applies favor/disfavor bias to influence probability, and optionally excludes recently played games when a session is provided.
|
|||
|
|
|
|||
|
|
### Authentication
|
|||
|
|
|
|||
|
|
None.
|
|||
|
|
|
|||
|
|
### Request Body
|
|||
|
|
|
|||
|
|
All fields optional. Provide only the filters you want to apply.
|
|||
|
|
|
|||
|
|
| Field | Type | Required | Description |
|
|||
|
|
|-------|------|----------|-------------|
|
|||
|
|
| playerCount | integer | No | Filter games where `min_players ≤ count ≤ max_players` |
|
|||
|
|
| drawing | string | No | `"only"` = Drawing type only, `"exclude"` = exclude Drawing type |
|
|||
|
|
| length | string | No | `"short"` (≤15 min or NULL), `"medium"` (16–25 min), `"long"` (>25 min) |
|
|||
|
|
| familyFriendly | boolean | No | Filter by family-friendly rating |
|
|||
|
|
| sessionId | integer | No | Session ID for repeat avoidance |
|
|||
|
|
| excludePlayed | boolean | No | When `true`, exclude ALL games played in session. Default: exclude last 2 only |
|
|||
|
|
|
|||
|
|
```json
|
|||
|
|
{
|
|||
|
|
"playerCount": 6,
|
|||
|
|
"drawing": "exclude",
|
|||
|
|
"length": "short",
|
|||
|
|
"familyFriendly": true,
|
|||
|
|
"sessionId": 3,
|
|||
|
|
"excludePlayed": false
|
|||
|
|
}
|
|||
|
|
```
|
|||
|
|
|
|||
|
|
### Filters
|
|||
|
|
|
|||
|
|
- **Enabled games only:** Only games with `enabled = 1` are considered.
|
|||
|
|
- **playerCount:** Filters games where `min_players ≤ playerCount ≤ max_players`.
|
|||
|
|
- **drawing:** `"only"` = games with `game_type = 'Drawing'`; `"exclude"` = games that are not Drawing type.
|
|||
|
|
- **length:** `"short"` = ≤15 min (includes NULL); `"medium"` = 16–25 min; `"long"` = >25 min.
|
|||
|
|
- **familyFriendly:** `true` or `false` filters by `family_friendly`.
|
|||
|
|
|
|||
|
|
### Weighted Selection
|
|||
|
|
|
|||
|
|
- **Game favor_bias:** `1` = 3× weight, `0` = 1× weight, `-1` = 0.2× weight.
|
|||
|
|
- **Pack favor_bias:** `1` = 2× weight, `0` = 1× weight, `-1` = 0.3× weight.
|
|||
|
|
- Game and pack biases multiply together.
|
|||
|
|
|
|||
|
|
### Repeat Avoidance (with sessionId)
|
|||
|
|
|
|||
|
|
- **Default (`excludePlayed: false`):** Excludes the last 2 played games in the session.
|
|||
|
|
- **With `excludePlayed: true`:** Excludes ALL games played in the session.
|
|||
|
|
|
|||
|
|
### Response
|
|||
|
|
|
|||
|
|
**200 OK**
|
|||
|
|
|
|||
|
|
```json
|
|||
|
|
{
|
|||
|
|
"game": {
|
|||
|
|
"id": 42,
|
|||
|
|
"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": 0,
|
|||
|
|
"popularity_score": 0,
|
|||
|
|
"enabled": 1,
|
|||
|
|
"favor_bias": 0,
|
|||
|
|
"created_at": "2024-01-15T12:00:00.000Z"
|
|||
|
|
},
|
|||
|
|
"poolSize": 15,
|
|||
|
|
"totalEnabled": 17
|
|||
|
|
}
|
|||
|
|
```
|
|||
|
|
|
|||
|
|
| Field | Description |
|
|||
|
|
|-------|-------------|
|
|||
|
|
| game | Full game object for the selected game |
|
|||
|
|
| poolSize | Number of games in the eligible pool after filters |
|
|||
|
|
| totalEnabled | Approximate total enabled games (includes excluded when sessionId provided) |
|
|||
|
|
|
|||
|
|
### Error Responses
|
|||
|
|
|
|||
|
|
| Status | Body | When |
|
|||
|
|
|--------|------|------|
|
|||
|
|
| 404 | `{ "error": "No games match the current filters", "suggestion": "Try adjusting your filters or enabling more games" }` | No games match the filters |
|
|||
|
|
| 404 | `{ "error": "All eligible games have been played in this session", "suggestion": "Enable more games or adjust your filters", "recentlyPlayed": [1, 5, 12] }` | All eligible games already played in session (when `excludePlayed: true`) |
|
|||
|
|
| 404 | `{ "error": "All eligible games have been played recently", "suggestion": "Enable more games or adjust your filters", "recentlyPlayed": [1, 5] }` | Last 2 games are the only matches (when `excludePlayed: false`) |
|
|||
|
|
| 500 | `{ "error": "..." }` | Server error |
|
|||
|
|
|
|||
|
|
### Example
|
|||
|
|
|
|||
|
|
```bash
|
|||
|
|
curl -X POST "http://localhost:5000/api/pick" \
|
|||
|
|
-H "Content-Type: application/json" \
|
|||
|
|
-d '{
|
|||
|
|
"playerCount": 6,
|
|||
|
|
"drawing": "exclude",
|
|||
|
|
"length": "short",
|
|||
|
|
"familyFriendly": true,
|
|||
|
|
"sessionId": 3,
|
|||
|
|
"excludePlayed": false
|
|||
|
|
}'
|
|||
|
|
```
|