feat: drop game_state from opportunity models + add gamestate resource (v0.2.6) (#5)

* feat!: drop game_state from opportunity models (v0.3.0)

The API server no longer emits a `game_state` object on the EV,
arbitrage, or low-hold response paths. Live game state (scores,
period, clock) is served exclusively by `/api/v1/gamestate` and the
`gamestate` stream channel — correlate by `event_id`.

- Remove `game_state` from ArbitrageOpportunity, MiddleOpportunity,
 and LowHoldOpportunity.
- Remove vestigial `home_score`, `away_score`, `game_period`,
 `game_clock` fields from OddsLine (the /api/v1/odds endpoint
 never populated them).
- Keep the `GameState` model exported for users consuming the
 gamestate endpoint.
- Bump 0.2.5 -> 0.3.0.

BREAKING CHANGE: code that read `arb.game_state`, `lh.game_state`,
or `mid.game_state` will need to fetch state via the gamestate
endpoint and join by `event_id`.

Co-Authored-By: Claude Opus 4.7 (1M context) <noreply@anthropic.com>

* feat(gamestate): add gamestate resource + stream method

The previous commit dropped `game_state` from EV / arb / low-hold rows.
This adds a first-class replacement: `client.gamestate.get(sport=...)`
fetches `/api/v1/gamestate{/<sport>}` and parses the response into a
`{sport: {event_id: GameState}}` map. Mirrored on the async client
and as `client.stream.gamestate()` for SSE.

The `GameState` model is rewritten to match what the gamestate endpoint
actually emits — `home_score`, `away_score`, `game_period`, `game_clock`,
`primary_book`, `book_count`, `stale`, `aggregator_stale` (plus team /
sport pass-through). `extra="allow"` keeps adapter-specific fields from
being silently dropped.

Bundled with the v0.3.0 breaking change so users have a clean migration:
where they used to read `arb.game_state.period`, they now do
``state[opp.sport][opp.event_id].game_period`` after a single
`client.gamestate.get()` per refresh.

Co-Authored-By: Claude Opus 4.7 (1M context) <noreply@anthropic.com>

* chore(version): bump 0.2.5 -> 0.2.6 (patch, not minor)

Earlier commit jumped to 0.3.0 to flag the breaking change. Project
preference is to use 0.0.1 patch bumps; switch the version on this
branch back to 0.2.6 so the release line stays continuous. The drop
of `game_state` from EV / arb / low-hold rows is still highlighted as
BREAKING in the commit message and PR — semver-strict downstreams
should pin accordingly.

Co-Authored-By: Claude Opus 4.7 (1M context) <noreply@anthropic.com>

---------

Co-authored-by: Claude Opus 4.7 (1M context) <noreply@anthropic.com>

Author: Mlaz-code

pyproject.toml

@@ -4,7 +4,7 @@ build-backend = "hatchling.build"
 
 [project]
 name = "sharpapi"
-version = "0.2.5"
+version = "0.2.6"
 description = "Official Python SDK for the SharpAPI real-time sports betting odds API"
 readme = "README.md"
 license = "MIT"

src/sharpapi/__init__.py

@@ -57,7 +57,7 @@
 )
 from .streaming import EventStream
 
-__version__ = "0.2.5"
+__version__ = "0.2.6"
 
 __all__ = [
     # Clients

src/sharpapi/async_client.py

@@ -29,6 +29,7 @@
     ClosingSnapshot,
     Event,
     EVOpportunity,
+    GameState,
     League,
     LowHoldOpportunity,
     Market,
@@ -103,6 +104,7 @@ def __init__(
         self.arbitrage = _AsyncArbitrageResource(self)
         self.middles = _AsyncMiddlesResource(self)
         self.low_hold = _AsyncLowHoldResource(self)
+        self.gamestate = _AsyncGameStateResource(self)
         self.sports = _AsyncSportsResource(self)
         self.leagues = _AsyncLeaguesResource(self)
         self.sportsbooks = _AsyncSportsbooksResource(self)
@@ -426,6 +428,41 @@ async def get(
         return parse_response(data, LowHoldOpportunity)
 
 
+class _AsyncGameStateResource:
+    """Async access to live game state — scores, period, clock —
+    merged across sportsbooks.
+
+    Requires the Game State add-on ($79/mo) or Enterprise tier.
+    """
+
+    def __init__(self, client: AsyncSharpAPI):
+        self._client = client
+
+    async def get(self, sport: str | None = None) -> dict[str, dict[str, GameState]]:
+        """Fetch the current game state.
+
+        Args:
+            sport: Limit to a single sport (e.g. ``"basketball"``).
+                Omit to fetch every sport at once.
+
+        Returns:
+            Nested mapping ``{sport: {event_id: GameState}}``.
+        """
+        path = f"/gamestate/{sport}" if sport else "/gamestate"
+        data = await self._client._get(path)
+        raw = data.get("data", {}) or {}
+        result: dict[str, dict[str, GameState]] = {}
+        for sport_key, events in raw.items():
+            if not isinstance(events, dict):
+                continue
+            result[sport_key] = {
+                eid: GameState.model_validate(state)
+                for eid, state in events.items()
+                if isinstance(state, dict)
+            }
+        return result
+
+
 class _AsyncSportsResource:
     def __init__(self, client: AsyncSharpAPI):
         self._client = client

src/sharpapi/client.py

@@ -29,6 +29,7 @@
     ClosingSnapshot,
     Event,
     EVOpportunity,
+    GameState,
     League,
     LowHoldOpportunity,
     Market,
@@ -111,6 +112,7 @@ def __init__(
         self.arbitrage = _ArbitrageResource(self)
         self.middles = _MiddlesResource(self)
         self.low_hold = _LowHoldResource(self)
+        self.gamestate = _GameStateResource(self)
         self.sports = _SportsResource(self)
         self.leagues = _LeaguesResource(self)
         self.sportsbooks = _SportsbooksResource(self)
@@ -542,6 +544,44 @@ def get(
         return _parse_response(data, LowHoldOpportunity)
 
 
+class _GameStateResource:
+    """Live game state — scores, period, clock — merged across sportsbooks.
+
+    Requires the Game State add-on ($79/mo) or Enterprise tier.
+    Pair with EV / arb / low-hold rows: those endpoints no longer carry
+    ``game_state`` themselves — look up the row's ``event_id`` here.
+    """
+
+    def __init__(self, client: SharpAPI):
+        self._client = client
+
+    def get(self, sport: str | None = None) -> dict[str, dict[str, GameState]]:
+        """Fetch the current game state.
+
+        Args:
+            sport: Limit to a single sport (e.g. ``"basketball"``,
+                ``"football"``). Omit to fetch every sport at once.
+
+        Returns:
+            Nested mapping ``{sport: {event_id: GameState}}``. Look up an
+            opportunity's state with
+            ``result.get(opp.sport, {}).get(opp.event_id)``.
+        """
+        path = f"/gamestate/{sport}" if sport else "/gamestate"
+        data = self._client._get(path)
+        raw = data.get("data", {}) or {}
+        result: dict[str, dict[str, GameState]] = {}
+        for sport_key, events in raw.items():
+            if not isinstance(events, dict):
+                continue
+            result[sport_key] = {
+                eid: GameState.model_validate(state)
+                for eid, state in events.items()
+                if isinstance(state, dict)
+            }
+        return result
+
+
 class _SportsResource:
     def __init__(self, client: SharpAPI):
         self._client = client
@@ -781,6 +821,15 @@ def event(
             "market": market,
         })
 
+    def gamestate(self) -> EventStream:
+        """Stream live game state updates (scores, period, clock).
+
+        Emits ``gamestate:snapshot`` (initial dump on connect) and
+        ``gamestate:update`` / ``gamestate:removed`` events. Requires the
+        Game State add-on or Enterprise tier.
+        """
+        return self._build_stream("/stream/gamestate")
+
 
 # =============================================================================
 # Helpers

src/sharpapi/models.py

@@ -60,9 +60,9 @@ def to_dataframe(self, flatten: bool = True):
         Requires ``pip install sharpapi[pandas]``.
 
         Args:
-            flatten: If True (default), flatten nested objects like
-                ``game_state.period`` into ``game_state_period`` columns.
-                Nested lists (like ``legs``) remain as-is.
+            flatten: If True (default), flatten nested objects into
+                underscore-joined columns. Nested lists (like ``legs``)
+                remain as-is.
 
         Returns:
             pandas.DataFrame with one row per item in ``data``.
@@ -109,12 +109,29 @@ def _flatten_dict(d: dict, parent_key: str = "", sep: str = "_") -> dict:
 
 
 class GameState(BaseModel):
-    """Live game state."""
+    """Live game state for a single event, merged across sportsbooks.
 
-    period: str | None = None
-    clock: str | None = None
-    score_home: int | None = None
-    score_away: int | None = None
+    Returned by ``/api/v1/gamestate`` and the ``gamestate`` stream channel.
+    Scores are consensus-merged with period-guarded outlier rejection;
+    period/clock are picked from the most-advanced book. Not present on
+    EV / arb / low-hold opportunity rows — correlate by ``event_id``.
+
+    ``extra="allow"`` lets adapter-specific fields pass through unchanged.
+    """
+
+    home_score: int | None = None
+    away_score: int | None = None
+    game_period: str | None = None
+    game_clock: str | None = None
+    home_team: str | None = None
+    away_team: str | None = None
+    sport: str | None = None
+    primary_book: str | None = None
+    book_count: int | None = None
+    stale: bool = False
+    aggregator_stale: bool = False
+
+    model_config = {"extra": "allow"}
 
 
 # =============================================================================
@@ -146,10 +163,6 @@ class OddsLine(BaseModel):
     deep_link: str | None = None
     player_name: str | None = None
     stat_category: str | None = None
-    home_score: int | None = None
-    away_score: int | None = None
-    game_period: str | None = None
-    game_clock: str | None = None
 
 
 # =============================================================================
@@ -248,7 +261,6 @@ class ArbitrageOpportunity(BaseModel):
     possibly_stale: bool = False
     oldest_odds_age_seconds: float | None = None
     warnings: list[str] = Field(default_factory=list)
-    game_state: GameState | None = None
     ev_available: bool | None = None
     ev_percentage: float | None = None
     is_player_prop: bool = False
@@ -304,7 +316,6 @@ class MiddleOpportunity(BaseModel):
     quality_score: float | None = None
     market_overround: float | None = None
     is_live: bool = False
-    game_state: GameState | None = None
     is_player_prop: bool = False
     player_name: str | None = None
     stat_category: str | None = None
@@ -352,7 +363,6 @@ class LowHoldOpportunity(BaseModel):
     side2: LowHoldSide | None = None
     side3: LowHoldSide | None = None
     is_live: bool = False
-    game_state: GameState | None = None
     is_alternate_line: bool = False
     all_books: list[str] | None = None
     confidence: float | None = None

tests/conftest.py

@@ -28,12 +28,6 @@
             "possibly_stale": False,
             "oldest_odds_age_seconds": 12.5,
             "warnings": ["LIVE_GAME"],
-            "game_state": {
-                "period": "Q2",
-                "clock": "5:23",
-                "score_home": 48,
-                "score_away": 52,
-            },
             "ev_available": True,
             "ev_percentage": 3.2,
             "is_player_prop": False,
@@ -249,6 +243,54 @@
     },
 }
 
+GAMESTATE_RESPONSE = {
+    "data": {
+        "basketball": {
+            "evt_lal_bos": {
+                "home_score": 48,
+                "away_score": 52,
+                "game_period": "Q2",
+                "game_clock": "5:23",
+                "home_team": "Boston Celtics",
+                "away_team": "Los Angeles Lakers",
+                "sport": "basketball",
+                "primary_book": "draftkings",
+                "book_count": 4,
+                "stale": False,
+            },
+            "evt_gsw_phx": {
+                "home_score": 30,
+                "away_score": 28,
+                "game_period": "Q1",
+                "game_clock": "1:42",
+                "sport": "basketball",
+                "primary_book": "fanduel",
+                "book_count": 3,
+                "aggregator_stale": True,
+            },
+        },
+        "football": {
+            "evt_kc_buf": {
+                "home_score": 14,
+                "away_score": 7,
+                "game_period": "Q2",
+                "game_clock": "8:15",
+                "sport": "football",
+                "primary_book": "draftkings",
+                "book_count": 5,
+            },
+        },
+    },
+    "updated_at": "2026-04-25T20:30:00Z",
+}
+
+GAMESTATE_BASKETBALL_RESPONSE = {
+    "data": {
+        "basketball": GAMESTATE_RESPONSE["data"]["basketball"],
+    },
+    "updated_at": "2026-04-25T20:30:00Z",
+}
+
 ERROR_401 = {
     "error": {"code": "invalid_api_key", "message": "Invalid API key"},
 }

tests/test_async_client.py

@@ -11,6 +11,7 @@
     AsyncSharpAPI,
     AuthenticationError,
     EVOpportunity,
+    GameState,
     OddsLine,
     RateLimitedError,
     Sport,
@@ -24,6 +25,7 @@
     ERROR_401,
     ERROR_429,
     EV_RESPONSE,
+    GAMESTATE_RESPONSE,
     ODDS_RESPONSE,
     RATE_LIMIT_HEADERS,
     SPORTS_RESPONSE,
@@ -51,6 +53,7 @@ def test_resource_namespaces_exist(self):
         assert hasattr(client, "arbitrage")
         assert hasattr(client, "middles")
         assert hasattr(client, "low_hold")
+        assert hasattr(client, "gamestate")
         assert hasattr(client, "sports")
         assert hasattr(client, "leagues")
         assert hasattr(client, "sportsbooks")
@@ -177,6 +180,35 @@ async def test_get_ev(self):
             assert result.data[0].ev_percentage == 4.2
 
 
+class TestAsyncGameState:
+    @pytest.mark.asyncio
+    @respx.mock
+    async def test_get_all_sports(self):
+        respx.get(f"{BASE_URL}/api/v1/gamestate").mock(
+            return_value=Response(200, json=GAMESTATE_RESPONSE)
+        )
+        async with AsyncSharpAPI(API_KEY) as client:
+            result = await client.gamestate.get()
+            state = result["basketball"]["evt_lal_bos"]
+            assert isinstance(state, GameState)
+            assert state.home_score == 48
+            assert state.game_period == "Q2"
+
+    @pytest.mark.asyncio
+    @respx.mock
+    async def test_get_single_sport(self):
+        route = respx.get(f"{BASE_URL}/api/v1/gamestate/basketball").mock(
+            return_value=Response(200, json={
+                "data": {"basketball": GAMESTATE_RESPONSE["data"]["basketball"]},
+                "updated_at": "2026-04-25T20:30:00Z",
+            })
+        )
+        async with AsyncSharpAPI(API_KEY) as client:
+            result = await client.gamestate.get("basketball")
+            assert route.called
+            assert "football" not in result
+
+
 # =============================================================================
 # Async Reference Data
 # =============================================================================