sharpapi 0.2.1__py3-none-any.whl → 0.2.5__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,20 @@ from .exceptions import (
     ValidationError,
 )
 from .models import (
-    APIResponse,
     AccountInfo,
+    APIKey,
+    APIResponse,
     ArbitrageLeg,
     ArbitrageOpportunity,
-    EVOpportunity,
+    ClosingOddsLine,
+    ClosingSnapshot,
     Event,
+    EVOpportunity,
     GameState,
     League,
     LowHoldOpportunity,
     LowHoldSide,
+    Market,
     MiddleOpportunity,
     MiddleSide,
     OddsLine,
@@ -49,25 +56,28 @@ from .models import (
     Sportsbook,
 )
 from .streaming import EventStream
-from ._utils import american_to_decimal, american_to_probability, decimal_to_american
 
-__version__ = "0.2.1"
+__version__ = "0.2.5"
 
 __all__ = [
     # Clients
     "SharpAPI",
     "AsyncSharpAPI",
     # Models
+    "APIKey",
     "APIResponse",
     "AccountInfo",
     "ArbitrageLeg",
     "ArbitrageOpportunity",
+    "ClosingOddsLine",
+    "ClosingSnapshot",
     "EVOpportunity",
     "Event",
     "GameState",
     "League",
     "LowHoldOpportunity",
     "LowHoldSide",
+    "Market",
     "MiddleOpportunity",
     "MiddleSide",
     "OddsLine",
@@ -86,6 +96,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

@@ -2,20 +2,48 @@
 
 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.0"
+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
+RETRY_BASE_DELAY = 0.5
+RETRY_MAX_DELAY = 4.0
+
+
+def should_retry(response: httpx.Response | None, exc: Exception | None) -> bool:
+    """True for transient upstream failures worth retrying."""
+    if exc is not None:
+        return isinstance(exc, (httpx.ConnectError, httpx.ReadError, httpx.RemoteProtocolError))
+    return response is not None and response.status_code in RETRY_STATUSES
+
+
+def retry_delay(attempt: int) -> float:
+    """Exponential backoff with full jitter. attempt is 1-indexed."""
+    ceiling = min(RETRY_BASE_DELAY * (2 ** (attempt - 1)), RETRY_MAX_DELAY)
+    return random.uniform(0, ceiling)
 
 
 def parse_response(raw: dict, model_class: type) -> APIResponse:
@@ -70,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:
@@ -92,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

@@ -2,32 +2,41 @@
 
 from __future__ import annotations
 
-from typing import Any, Optional, Union
+import asyncio
+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,
     parse_response,
+    retry_delay,
+    should_retry,
 )
 from ._utils import _clean_params
 from .models import (
-    APIResponse,
     AccountInfo,
+    APIKey,
+    APIResponse,
     ArbitrageOpportunity,
-    EVOpportunity,
+    ClosingSnapshot,
     Event,
+    EVOpportunity,
     League,
     LowHoldOpportunity,
+    Market,
     MiddleOpportunity,
     OddsLine,
     RateLimitInfo,
-    Sportsbook,
     Sport,
+    Sportsbook,
 )
 
 
@@ -37,6 +46,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
@@ -48,6 +68,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())
     """
 
@@ -57,16 +81,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()
@@ -82,6 +108,7 @@ class AsyncSharpAPI:
         self.sportsbooks = _AsyncSportsbooksResource(self)
         self.events = _AsyncEventsResource(self)
         self.account = _AsyncAccountResource(self)
+        self.keys = _AsyncKeysResource(self)
 
     @property
     def rate_limit(self) -> RateLimitInfo:
@@ -89,11 +116,26 @@ 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."""
+        """Make an async request, return parsed JSON. Retries 502/503/504 with jittered backoff."""
         if params:
             params = _clean_params(params)
 
-        response = await self._http.request(method, path, params=params, **kwargs)
+        response: httpx.Response | None = None
+        for attempt in range(1, RETRY_MAX_ATTEMPTS + 1):
+            exc: Exception | None = None
+            try:
+                response = await self._http.request(method, path, params=params, **kwargs)
+            except (httpx.ConnectError, httpx.ReadError, httpx.RemoteProtocolError) as e:
+                exc = e
+
+            if attempt < RETRY_MAX_ATTEMPTS and should_retry(response, exc):
+                await asyncio.sleep(retry_delay(attempt))
+                continue
+            if exc is not None:
+                raise exc
+            break
+
+        assert response is not None
         self._last_rate_limit = parse_rate_limit(response)
         handle_errors(response)
         return response.json()
@@ -129,18 +171,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", {
@@ -162,15 +204,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", {
@@ -190,7 +232,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", {
@@ -204,6 +246,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."""
@@ -214,21 +275,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", {
@@ -260,18 +321,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", {
@@ -300,17 +361,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", {
@@ -338,16 +399,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", {
@@ -385,7 +446,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)
@@ -420,11 +481,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", {
@@ -442,6 +503,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):
@@ -457,3 +523,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)