# 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
  }'
```