sharpapi 0.2.2__py3-none-any.whl → 0.3.1__py3-none-any.whl

sharpapi/__init__.py

@@ -17,9 +17,12 @@ Example::
         print(f"+{opp.ev_percentage}% on {opp.selection} @ {opp.sportsbook}")
 """
 
+from ._utils import american_to_decimal, american_to_probability, decimal_to_american
 from .async_client import AsyncSharpAPI
 from .client import SharpAPI
 from .exceptions import (
+    ERROR_CODE_DESCRIPTIONS,
+    ERROR_CODE_TO_EXCEPTION,
     AuthenticationError,
     RateLimitedError,
     SharpAPIError,
@@ -28,16 +31,21 @@ from .exceptions import (
     ValidationError,
 )
 from .models import (
-    APIResponse,
     AccountInfo,
+    APIKey,
+    APIResponse,
     ArbitrageLeg,
     ArbitrageOpportunity,
-    EVOpportunity,
+    ClosingOddsLine,
+    ClosingSnapshot,
+    EntityRef,
     Event,
+    EVOpportunity,
     GameState,
     League,
     LowHoldOpportunity,
     LowHoldSide,
+    Market,
     MiddleOpportunity,
     MiddleSide,
     OddsLine,
@@ -46,28 +54,35 @@ from .models import (
     RateLimitInfo,
     ResponseMeta,
     Sport,
+    SportRef,
     Sportsbook,
+    Team,
+    TeamRef,
 )
 from .streaming import EventStream
-from ._utils import american_to_decimal, american_to_probability, decimal_to_american
 
-__version__ = "0.2.1"
+__version__ = "0.3.1"
 
 __all__ = [
     # Clients
     "SharpAPI",
     "AsyncSharpAPI",
     # Models
+    "APIKey",
     "APIResponse",
     "AccountInfo",
     "ArbitrageLeg",
     "ArbitrageOpportunity",
+    "ClosingOddsLine",
+    "ClosingSnapshot",
+    "EntityRef",
     "EVOpportunity",
     "Event",
     "GameState",
     "League",
     "LowHoldOpportunity",
     "LowHoldSide",
+    "Market",
     "MiddleOpportunity",
     "MiddleSide",
     "OddsLine",
@@ -76,7 +91,10 @@ __all__ = [
     "RateLimitInfo",
     "ResponseMeta",
     "Sport",
+    "SportRef",
     "Sportsbook",
+    "Team",
+    "TeamRef",
     # Streaming
     "EventStream",
     # Exceptions
@@ -86,6 +104,9 @@ __all__ = [
     "StreamError",
     "TierRestrictedError",
     "ValidationError",
+    # Error-code registry
+    "ERROR_CODE_DESCRIPTIONS",
+    "ERROR_CODE_TO_EXCEPTION",
     # Utilities
     "american_to_decimal",
     "american_to_probability",

sharpapi/_base.py

@@ -3,21 +3,29 @@
 from __future__ import annotations
 
 import random
+from typing import Literal
 
 import httpx
 
 from .exceptions import (
+    ERROR_CODE_TO_EXCEPTION,
     AuthenticationError,
     RateLimitedError,
     SharpAPIError,
     TierRestrictedError,
     ValidationError,
+    canonical_code,
 )
 from .models import APIResponse, RateLimitInfo, ResponseMeta
 
 DEFAULT_BASE_URL = "https://api.sharpapi.io"
 DEFAULT_TIMEOUT = 30.0
-USER_AGENT = "sharpapi-python/0.2.2"
+USER_AGENT = "sharpapi-python/0.2.5"
+
+# Supported REST authentication methods. SSE always uses ``?api_key=`` query
+# regardless of this setting because EventSource cannot set custom headers.
+AuthMethod = Literal["x-api-key", "bearer"]
+DEFAULT_AUTH_METHOD: AuthMethod = "x-api-key"
 
 RETRY_STATUSES = frozenset({502, 503, 504})
 RETRY_MAX_ATTEMPTS = 3
@@ -90,6 +98,30 @@ def handle_errors(response: httpx.Response) -> None:
         code = body.get("code", "unknown_error")
     status = response.status_code
 
+    # Resolve deprecated code aliases (bad_request, invalid_request → validation_error).
+    code = canonical_code(code)
+
+    # Prefer the canonical code→exception mapping for well-known codes; fall back
+    # to HTTP-status-based routing for responses that omit an error code.
+    exc_class = ERROR_CODE_TO_EXCEPTION.get(code or "")
+    if exc_class is TierRestrictedError:
+        raise TierRestrictedError(
+            error_msg,
+            code=code,
+            status=status,
+            required_tier=body.get("required_tier"),
+        )
+    if exc_class is RateLimitedError:
+        raise RateLimitedError(
+            error_msg,
+            code=code,
+            status=status,
+            retry_after=body.get("retry_after"),
+        )
+    if exc_class is not None and exc_class is not SharpAPIError:
+        raise exc_class(error_msg, code=code, status=status)
+
+    # No canonical code match — route by HTTP status.
     if status == 401:
         raise AuthenticationError(error_msg, code=code, status=status)
     elif status == 403:
@@ -112,13 +144,28 @@ def handle_errors(response: httpx.Response) -> None:
         raise SharpAPIError(error_msg, code=code, status=status)
 
 
-def make_headers(api_key: str) -> dict[str, str]:
-    """Build default request headers."""
-    return {
-        "X-API-Key": api_key,
+def make_headers(
+    api_key: str,
+    auth_method: AuthMethod = DEFAULT_AUTH_METHOD,
+) -> dict[str, str]:
+    """Build default request headers.
+
+    Args:
+        api_key: The SharpAPI key (e.g. ``sk_live_...``).
+        auth_method: Either ``"x-api-key"`` (default — sends an
+            ``X-API-Key`` header) or ``"bearer"`` (sends
+            ``Authorization: Bearer <key>``). Useful when proxies, IAM
+            layers, or SSO gateways strip non-standard custom headers.
+    """
+    headers: dict[str, str] = {
         "Content-Type": "application/json",
         "User-Agent": USER_AGENT,
     }
+    if auth_method == "bearer":
+        headers["Authorization"] = f"Bearer {api_key}"
+    else:
+        headers["X-API-Key"] = api_key
+    return headers
 
 
 def _int_or_none(value: str | None) -> int | None:

sharpapi/async_client.py

@@ -3,14 +3,16 @@
 from __future__ import annotations
 
 import asyncio
-from typing import Any, Optional, Union
+from typing import Any
 
 import httpx
 
 from ._base import (
+    DEFAULT_AUTH_METHOD,
     DEFAULT_BASE_URL,
     DEFAULT_TIMEOUT,
     RETRY_MAX_ATTEMPTS,
+    AuthMethod,
     handle_errors,
     make_headers,
     parse_rate_limit,
@@ -20,18 +22,22 @@ from ._base import (
 )
 from ._utils import _clean_params
 from .models import (
-    APIResponse,
     AccountInfo,
+    APIKey,
+    APIResponse,
     ArbitrageOpportunity,
-    EVOpportunity,
+    ClosingSnapshot,
     Event,
+    EVOpportunity,
+    GameState,
     League,
     LowHoldOpportunity,
+    Market,
     MiddleOpportunity,
     OddsLine,
     RateLimitInfo,
-    Sportsbook,
     Sport,
+    Sportsbook,
 )
 
 
@@ -41,6 +47,17 @@ class AsyncSharpAPI:
     Provides typed access to odds, +EV, arbitrage, middles, and streaming
     endpoints using ``async``/``await``.
 
+    Args:
+        api_key: Your SharpAPI key (e.g. ``sk_live_...``).
+        base_url: Override the API base URL (defaults to production).
+        timeout: HTTP timeout in seconds.
+        auth_method: How to send the API key on REST requests. ``"x-api-key"``
+            (default) sends the ``X-API-Key`` header. ``"bearer"`` sends
+            ``Authorization: Bearer <key>`` instead — useful when running
+            behind IAM layers, SSO, or API gateways that strip custom
+            headers. SSE streams (sync client only) always authenticate via
+            ``?api_key=`` query and are unaffected.
+
     Example::
 
         import asyncio
@@ -52,6 +69,10 @@ class AsyncSharpAPI:
                 for arb in arbs.data:
                     print(f"{arb.profit_percent}% — {arb.event_name}")
 
+            # Or, behind a proxy that requires standard Bearer auth:
+            async with AsyncSharpAPI("sk_live_xxx", auth_method="bearer") as c:
+                ...
+
         asyncio.run(main())
     """
 
@@ -61,16 +82,18 @@ class AsyncSharpAPI:
         *,
         base_url: str = DEFAULT_BASE_URL,
         timeout: float = DEFAULT_TIMEOUT,
+        auth_method: AuthMethod = DEFAULT_AUTH_METHOD,
     ):
         if not api_key:
             raise ValueError("api_key is required")
 
         self._api_key = api_key
+        self._auth_method: AuthMethod = auth_method
         self._base_url = base_url.rstrip("/")
         self._timeout = timeout
         self._http = httpx.AsyncClient(
             base_url=f"{self._base_url}/api/v1",
-            headers=make_headers(api_key),
+            headers=make_headers(api_key, auth_method),
             timeout=timeout,
         )
         self._last_rate_limit = RateLimitInfo()
@@ -81,11 +104,13 @@ class AsyncSharpAPI:
         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)
         self.events = _AsyncEventsResource(self)
         self.account = _AsyncAccountResource(self)
+        self.keys = _AsyncKeysResource(self)
 
     @property
     def rate_limit(self) -> RateLimitInfo:
@@ -93,7 +118,7 @@ class AsyncSharpAPI:
         return self._last_rate_limit
 
     async def _request(self, method: str, path: str, params: dict | None = None, **kwargs) -> Any:
-        """Make an async API request and return parsed JSON. Retries 502/503/504 with jittered backoff."""
+        """Make an async request, return parsed JSON. Retries 502/503/504 with jittered backoff."""
         if params:
             params = _clean_params(params)
 
@@ -148,18 +173,18 @@ class _AsyncOddsResource:
     async def get(
         self,
         *,
-        sportsbook: Optional[Union[str, list[str]]] = None,
-        add_sportsbook: Optional[Union[str, list[str]]] = None,
-        sport: Optional[Union[str, list[str]]] = None,
-        league: Optional[Union[str, list[str]]] = None,
-        market: Optional[Union[str, list[str]]] = None,
-        event: Optional[Union[str, list[str]]] = None,
-        live: Optional[bool] = None,
-        sort: Optional[str] = None,
-        group_by: Optional[str] = None,
-        fields: Optional[Union[str, list[str]]] = None,
-        limit: Optional[int] = None,
-        offset: Optional[int] = None,
+        sportsbook: str | list[str] | None = None,
+        add_sportsbook: str | list[str] | None = None,
+        sport: str | list[str] | None = None,
+        league: str | list[str] | None = None,
+        market: str | list[str] | None = None,
+        event: str | list[str] | None = None,
+        live: bool | None = None,
+        sort: str | None = None,
+        group_by: str | None = None,
+        fields: str | list[str] | None = None,
+        limit: int | None = None,
+        offset: int | None = None,
     ) -> APIResponse[list[OddsLine]]:
         """Get current odds snapshot."""
         data = await self._client._get("/odds", {
@@ -181,15 +206,15 @@ class _AsyncOddsResource:
     async def best(
         self,
         *,
-        sport: Optional[Union[str, list[str]]] = None,
-        league: Optional[Union[str, list[str]]] = None,
-        market: Optional[Union[str, list[str]]] = None,
-        event: Optional[Union[str, list[str]]] = None,
-        live: Optional[bool] = None,
-        sportsbook: Optional[Union[str, list[str]]] = None,
-        add_sportsbook: Optional[Union[str, list[str]]] = None,
-        limit: Optional[int] = None,
-        offset: Optional[int] = None,
+        sport: str | list[str] | None = None,
+        league: str | list[str] | None = None,
+        market: str | list[str] | None = None,
+        event: str | list[str] | None = None,
+        live: bool | None = None,
+        sportsbook: str | list[str] | None = None,
+        add_sportsbook: str | list[str] | None = None,
+        limit: int | None = None,
+        offset: int | None = None,
     ) -> APIResponse[list[OddsLine]]:
         """Get best odds per selection across all sportsbooks."""
         data = await self._client._get("/odds/best", {
@@ -209,7 +234,7 @@ class _AsyncOddsResource:
         self,
         event_id: str,
         *,
-        market: Optional[str] = None,
+        market: str | None = None,
     ) -> APIResponse[list[OddsLine]]:
         """Get side-by-side odds comparison for an event."""
         data = await self._client._get("/odds/comparison", {
@@ -223,6 +248,25 @@ class _AsyncOddsResource:
         data = await self._client._post("/odds/batch", {"event_ids": event_ids})
         return parse_response(data, OddsLine)
 
+    async def closing(
+        self,
+        event_id: str,
+        *,
+        sportsbook: str | None = None,
+    ) -> ClosingSnapshot:
+        """Get closing-line snapshot for an event.
+
+        Returns the captured closing odds grouped by sportsbook. If no
+        closing data has been captured for the event, the returned
+        ``ClosingSnapshot.books`` mapping will be empty.
+        """
+        data = await self._client._get("/odds/closing", {
+            "event_id": event_id,
+            "sportsbook": sportsbook or None,
+        })
+        raw = data.get("data", data)
+        return ClosingSnapshot.model_validate(raw)
+
 
 class _AsyncEVResource:
     """Async access to +EV opportunities."""
@@ -233,21 +277,21 @@ class _AsyncEVResource:
     async def get(
         self,
         *,
-        sport: Optional[Union[str, list[str]]] = None,
-        league: Optional[Union[str, list[str]]] = None,
-        sportsbook: Optional[Union[str, list[str]]] = None,
-        add_sportsbook: Optional[Union[str, list[str]]] = None,
-        market: Optional[Union[str, list[str]]] = None,
-        min_ev: Optional[float] = None,
-        max_ev: Optional[float] = None,
-        min_market_width: Optional[float] = None,
-        max_market_width: Optional[float] = None,
-        max_odds_age: Optional[int] = None,
-        date_range: Optional[str] = None,
-        live: Optional[bool] = None,
-        sort: Optional[str] = None,
-        limit: Optional[int] = None,
-        offset: Optional[int] = None,
+        sport: str | list[str] | None = None,
+        league: str | list[str] | None = None,
+        sportsbook: str | list[str] | None = None,
+        add_sportsbook: str | list[str] | None = None,
+        market: str | list[str] | None = None,
+        min_ev: float | None = None,
+        max_ev: float | None = None,
+        min_market_width: float | None = None,
+        max_market_width: float | None = None,
+        max_odds_age: int | None = None,
+        date_range: str | None = None,
+        live: bool | None = None,
+        sort: str | None = None,
+        limit: int | None = None,
+        offset: int | None = None,
     ) -> APIResponse[list[EVOpportunity]]:
         """Get +EV opportunities. Requires Pro tier or higher."""
         data = await self._client._get("/opportunities/ev", {
@@ -279,18 +323,18 @@ class _AsyncArbitrageResource:
     async def get(
         self,
         *,
-        sport: Optional[Union[str, list[str]]] = None,
-        league: Optional[Union[str, list[str]]] = None,
-        sportsbook: Optional[Union[str, list[str]]] = None,
-        add_sportsbook: Optional[Union[str, list[str]]] = None,
-        market: Optional[Union[str, list[str]]] = None,
-        min_profit: Optional[float] = None,
-        max_odds_age: Optional[int] = None,
-        live: Optional[bool] = None,
-        sort: Optional[str] = None,
-        group: Optional[str] = None,
-        limit: Optional[int] = None,
-        offset: Optional[int] = None,
+        sport: str | list[str] | None = None,
+        league: str | list[str] | None = None,
+        sportsbook: str | list[str] | None = None,
+        add_sportsbook: str | list[str] | None = None,
+        market: str | list[str] | None = None,
+        min_profit: float | None = None,
+        max_odds_age: int | None = None,
+        live: bool | None = None,
+        sort: str | None = None,
+        group: str | None = None,
+        limit: int | None = None,
+        offset: int | None = None,
     ) -> APIResponse[list[ArbitrageOpportunity]]:
         """Get arbitrage opportunities. Requires Hobby tier or higher."""
         data = await self._client._get("/opportunities/arbitrage", {
@@ -319,17 +363,17 @@ class _AsyncMiddlesResource:
     async def get(
         self,
         *,
-        sport: Optional[Union[str, list[str]]] = None,
-        league: Optional[Union[str, list[str]]] = None,
-        sportsbook: Optional[Union[str, list[str]]] = None,
-        market: Optional[Union[str, list[str]]] = None,
-        min_size: Optional[float] = None,
-        max_odds_age: Optional[int] = None,
-        live: Optional[bool] = None,
-        state: Optional[str] = None,
-        sort: Optional[str] = None,
-        limit: Optional[int] = None,
-        offset: Optional[int] = None,
+        sport: str | list[str] | None = None,
+        league: str | list[str] | None = None,
+        sportsbook: str | list[str] | None = None,
+        market: str | list[str] | None = None,
+        min_size: float | None = None,
+        max_odds_age: int | None = None,
+        live: bool | None = None,
+        state: str | None = None,
+        sort: str | None = None,
+        limit: int | None = None,
+        offset: int | None = None,
     ) -> APIResponse[list[MiddleOpportunity]]:
         """Get middle opportunities. Requires Pro tier or higher."""
         data = await self._client._get("/opportunities/middles", {
@@ -357,16 +401,16 @@ class _AsyncLowHoldResource:
     async def get(
         self,
         *,
-        sport: Optional[Union[str, list[str]]] = None,
-        league: Optional[Union[str, list[str]]] = None,
-        sportsbook: Optional[Union[str, list[str]]] = None,
-        market: Optional[Union[str, list[str]]] = None,
-        max_hold: Optional[float] = None,
-        live: Optional[bool] = None,
-        state: Optional[str] = None,
-        sort: Optional[str] = None,
-        limit: Optional[int] = None,
-        offset: Optional[int] = None,
+        sport: str | list[str] | None = None,
+        league: str | list[str] | None = None,
+        sportsbook: str | list[str] | None = None,
+        market: str | list[str] | None = None,
+        max_hold: float | None = None,
+        live: bool | None = None,
+        state: str | None = None,
+        sort: str | None = None,
+        limit: int | None = None,
+        offset: int | None = None,
     ) -> APIResponse[list[LowHoldOpportunity]]:
         """Get low-hold opportunities."""
         data = await self._client._get("/opportunities/low_hold", {
@@ -384,6 +428,41 @@ class _AsyncLowHoldResource:
         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
@@ -404,7 +483,7 @@ class _AsyncLeaguesResource:
     def __init__(self, client: AsyncSharpAPI):
         self._client = client
 
-    async def list(self, *, sport: Optional[str] = None) -> APIResponse[list[League]]:
+    async def list(self, *, sport: str | None = None) -> APIResponse[list[League]]:
         """List all leagues, optionally filtered by sport."""
         data = await self._client._get("/leagues", {"sport": sport})
         return parse_response(data, League)
@@ -439,11 +518,11 @@ class _AsyncEventsResource:
     async def list(
         self,
         *,
-        sport: Optional[str] = None,
-        league: Optional[Union[str, list[str]]] = None,
-        live: Optional[bool] = None,
-        limit: Optional[int] = None,
-        offset: Optional[int] = None,
+        sport: str | None = None,
+        league: str | list[str] | None = None,
+        live: bool | None = None,
+        limit: int | None = None,
+        offset: int | None = None,
     ) -> APIResponse[list[Event]]:
         """List events."""
         data = await self._client._get("/events", {
@@ -461,6 +540,11 @@ class _AsyncEventsResource:
         raw = data.get("data", data)
         return Event.model_validate(raw)
 
+    async def markets(self, event_id: str) -> APIResponse[list[Market]]:
+        """List the markets available on a specific event."""
+        data = await self._client._get(f"/events/{event_id}/markets")
+        return parse_response(data, Market)
+
 
 class _AsyncAccountResource:
     def __init__(self, client: AsyncSharpAPI):
@@ -476,3 +560,33 @@ class _AsyncAccountResource:
         """Get current usage stats."""
         data = await self._client._get("/account/usage")
         return data.get("data", data)
+
+
+class _AsyncKeysResource:
+    """Async access to API key CRUD on the current account."""
+
+    def __init__(self, client: AsyncSharpAPI):
+        self._client = client
+
+    async def list(self) -> APIResponse[list[APIKey]]:
+        """List all API keys on the account."""
+        data = await self._client._get("/account/keys")
+        return parse_response(data, APIKey)
+
+    async def create(self, name: str) -> APIKey:
+        """Create a new API key. Returned ``APIKey.key`` is shown only once."""
+        data = await self._client._post("/account/keys", {"name": name})
+        raw = data.get("data", data)
+        return APIKey.model_validate(raw)
+
+    async def revoke(self, key_id: str) -> None:
+        """Revoke (delete) an API key by ID."""
+        await self._client._request("DELETE", f"/account/keys/{key_id}")
+
+    async def rotate(self, key_id: str) -> APIKey:
+        """Rotate an API key — issues a new key and revokes the old one."""
+        data = await self._client._post(f"/account/keys/{key_id}/rotate")
+        raw = data.get("data", data)
+        if isinstance(raw, dict) and "new_key" in raw:
+            return APIKey.model_validate(raw["new_key"])
+        return APIKey.model_validate(raw)