Add timeout_type field to /live endpoint + client field crosswalk - #7
Conversation
There was a problem hiding this comment.
Pull request overview
Adds a normalized timeout_type field to the /live response so clients can reliably detect team/official timeouts and official reviews, and documents the mapping for client-facing display requirements.
Changes:
- Adds
timeout_typeto theLiveStatemodel and maps it from scoreboardgame_state, auto-clearing whenjam_runningresumes. - Adds client/unit tests for timeout normalization behavior and an API test to ensure
/liveincludes the new field. - Updates README
/liveresponse documentation and introduces a client field crosswalk document.
Reviewed changes
Copilot reviewed 6 out of 6 changed files in this pull request and generated 3 comments.
Show a summary per file
| File | Description |
|---|---|
client.py |
Computes timeout_type via _normalize_timeout_type() and includes it in get_live_state(). |
models.py |
Adds timeout_type to the LiveState schema (OpenAPI/response model). |
tests/test_client.py |
Adds tests validating normalization for timeout/review states and clearing on jam resume. |
tests/test_api.py |
Adds an integration check that /live includes the timeout_type field. |
README.md |
Documents timeout_type in the /live example and field descriptions; links crosswalk doc. |
CLIENT_FIELD_CROSSWALK.md |
Adds client-facing mapping/crosswalk for display requirements and gaps. |
💡 Add Copilot custom instructions for smarter, more guided reviews. Learn how to get started.
| state = game_state.strip().lower() | ||
| if "official review" in state: | ||
| return "official_review" | ||
| if "official timeout" in state: | ||
| return "official_timeout" | ||
| if "team timeout" in state: | ||
| return "team_timeout" | ||
| if "timeout" in state: | ||
| return "timeout" | ||
| if "review" in state: | ||
| return "official_review" | ||
| return None |
There was a problem hiding this comment.
New branches in _normalize_timeout_type (generic "timeout" and generic "review" matches) are currently untested. Add client tests that cover these fallbacks (e.g., a game_state containing only "Timeout" and one containing only "Review") to prevent regressions in the normalization logic.
| 2. Timeout state and type | ||
| - Team timeout | ||
| - Official timeout | ||
| - Official review | ||
|
|
||
| 3. Timeout ownership and counters | ||
| - Which team called timeout/review | ||
| - Team timeouts remaining per team | ||
| - Official review availability/status per team |
There was a problem hiding this comment.
This crosswalk claims “Timeout state and type” are currently missing from GET /live, but this PR adds timeout_type. Please update this section (and the later “Timeout package (to add)” bullet) to reflect that timeout_type is now available, while ownership/counters/timers may still be missing.
| async def test_live_includes_timeout_type_field(app_client): | ||
| resp = await app_client.get("/live") | ||
| data = resp.json() | ||
| assert "timeout_type" in data |
There was a problem hiding this comment.
The new /live test only checks that the timeout_type key exists. Since the docs/example show it as null when not in a timeout, consider asserting the default value is None for the initial "Running" state, and/or add an integration test that pushes a timeout update and verifies /live returns the normalized value.
| assert "timeout_type" in data | |
| assert "timeout_type" in data | |
| assert data["timeout_type"] is None |
- Remove global pytestmark and add individual @pytest.mark.asyncio decorators to async test functions - Add tests for error handling paths in client.py (_coerce function, timeout types, message processing) - Add tests for main.py functions (create_app, parse_args) - Improve coverage: client.py 90% -> 95%, main.py 62% -> 71% - Install pytest-cov for coverage reporting - All 65 tests now pass without warnings
Adds timeout_type field that shows active timeout state (team_timeout, official_timeout, official_review) and auto-clears when jam resumes. Includes client field mapping documentation.