lumify-sdk 0.1.0__py3-none-any.whl

lumify/__init__.py

@@ -0,0 +1,65 @@
+"""
+lumify — official Python client for the Lumify agent-ready sports intelligence
+API (schedules, live scores, odds, line movement, betting splits, and AI bet
+intelligence). See https://lumify.ai/docs.
+
+This SDK *is* the typed REST path — the same data as the REST API and the
+``@lumifyai/mcp`` server, not a third implementation. Response models
+(``lumify.models``) are generated from Lumify's live OpenAPI schema, so they
+can't silently drift from what the API returns.
+"""
+
+from __future__ import annotations
+
+from ._transport import DEFAULT_BASE_URL, LumifyClient
+from .client import Lumify
+from .errors import (
+    APIError,
+    AuthenticationError,
+    ConnectionError,
+    FieldError,
+    LumifyError,
+    NotFoundError,
+    PaymentError,
+    PermissionError,
+    RateLimitError,
+    ValidationError,
+)
+from .meta import ResponseMeta, get_meta
+from .pagination import iterate_items, paginate
+from .sse import ScoreStreamEvent, SSEEvent, parse_sse_stream, stream_scores
+from .webhook_signature import WebhookSignatureError, verify_webhook
+
+__version__ = "0.1.0"
+
+__all__ = [
+    "Lumify",
+    "LumifyClient",
+    "DEFAULT_BASE_URL",
+    # errors
+    "LumifyError",
+    "AuthenticationError",
+    "PermissionError",
+    "NotFoundError",
+    "RateLimitError",
+    "ValidationError",
+    "PaymentError",
+    "APIError",
+    "ConnectionError",
+    "FieldError",
+    # meta
+    "ResponseMeta",
+    "get_meta",
+    # pagination
+    "paginate",
+    "iterate_items",
+    # sse
+    "stream_scores",
+    "parse_sse_stream",
+    "SSEEvent",
+    "ScoreStreamEvent",
+    # webhooks
+    "verify_webhook",
+    "WebhookSignatureError",
+    "__version__",
+]

lumify/_transport.py

@@ -0,0 +1,286 @@
+"""
+Low-level HTTP transport shared by every resource (mirrors the TS SDK's
+client.ts). Zero dependencies — the default engine is stdlib ``urllib``.
+
+The engine is injectable (``transport=``) so tests and non-standard runtimes
+can supply their own, exactly like passing a custom ``fetch`` to the TS client.
+This also keeps the door open to swapping in an async/``httpx`` engine later
+without touching any resource code.
+"""
+
+from __future__ import annotations
+
+import json as _json
+import random
+import socket
+import time
+import urllib.error
+import urllib.request
+from typing import Any, Callable, Dict, Mapping, Optional
+
+from .errors import ConnectionError, LumifyError, RateLimitError, error_from_response
+from .meta import _CaseInsensitiveHeaders, attach_meta, parse_meta
+
+DEFAULT_BASE_URL = "https://lumify.ai"
+DEFAULT_TIMEOUT = 30.0
+DEFAULT_MAX_RETRIES = 2
+SDK_VERSION = "0.1.0"
+
+
+class PreparedRequest:
+    """An immutable description of an outbound HTTP request."""
+
+    __slots__ = ("method", "url", "headers", "body")
+
+    def __init__(
+        self, method: str, url: str, headers: Dict[str, str], body: Optional[str]
+    ) -> None:
+        self.method = method
+        self.url = url
+        self.headers = headers
+        self.body = body
+
+
+class RawResponse:
+    """The minimal response shape a transport must return."""
+
+    __slots__ = ("status", "headers", "text")
+
+    def __init__(self, status: int, headers: Mapping[str, str], text: str) -> None:
+        self.status = status
+        self.headers = headers
+        self.text = text
+
+
+# A transport is any callable (request, timeout_seconds) -> RawResponse. It must
+# return a RawResponse for *any* HTTP status (including 4xx/5xx) and raise
+# lumify.errors.ConnectionError only for transport-level failures (DNS, refused
+# connection, timeout) where no response was received.
+Transport = Callable[[PreparedRequest, float], RawResponse]
+
+
+def _urllib_transport(req: PreparedRequest, timeout: float) -> RawResponse:
+    request = urllib.request.Request(
+        req.url,
+        data=req.body.encode("utf-8") if req.body is not None else None,
+        method=req.method,
+    )
+    for key, value in req.headers.items():
+        request.add_header(key, value)
+
+    try:
+        resp = urllib.request.urlopen(request, timeout=timeout)
+    except urllib.error.HTTPError as exc:
+        # A real HTTP response with a non-2xx status — read it and let the
+        # client map it to a typed error (uniform with the success path).
+        body = exc.read().decode("utf-8", "replace")
+        headers = dict(exc.headers.items()) if exc.headers else {}
+        return RawResponse(status=exc.code, headers=headers, text=body)
+    except (socket.timeout, TimeoutError) as exc:
+        raise ConnectionError(
+            "Request to %s %s timed out after %ss." % (req.method, req.url, timeout),
+            cause=exc,
+        )
+    except urllib.error.URLError as exc:
+        reason = getattr(exc, "reason", exc)
+        if isinstance(reason, (socket.timeout, TimeoutError)):
+            raise ConnectionError(
+                "Request to %s %s timed out after %ss." % (req.method, req.url, timeout),
+                cause=exc,
+            )
+        raise ConnectionError(
+            "Request to %s %s failed: %s" % (req.method, req.url, reason),
+            cause=exc,
+        )
+
+    with resp:
+        body = resp.read().decode("utf-8", "replace")
+        status = getattr(resp, "status", None) or resp.getcode()
+        headers = dict(resp.headers.items()) if resp.headers else {}
+    return RawResponse(status=int(status), headers=headers, text=body)
+
+
+def _build_query(params: Optional[Mapping[str, Any]]) -> str:
+    if not params:
+        return ""
+    from urllib.parse import urlencode
+
+    pairs = []
+    for key, value in params.items():
+        if value is None:
+            continue
+        if isinstance(value, bool):
+            # Match the REST/URLSearchParams contract: lowercase true/false,
+            # not Python's "True"/"False".
+            pairs.append((key, "true" if value else "false"))
+        else:
+            pairs.append((key, str(value)))
+    if not pairs:
+        return ""
+    return "?" + urlencode(pairs)
+
+
+def _safe_json(text: str) -> Any:
+    try:
+        return _json.loads(text)
+    except ValueError:
+        return _UNPARSEABLE
+
+
+_UNPARSEABLE = object()
+
+
+def _parse_retry_after(value: Optional[str]) -> Optional[float]:
+    """Parse ``Retry-After`` as integer seconds; ignore HTTP-date forms."""
+    if value is None or value == "":
+        return None
+    try:
+        seconds = float(value)
+    except (TypeError, ValueError):
+        return None
+    return seconds if seconds >= 0 else None
+
+
+class LumifyClient:
+    """The transport underlying every resource. Not usually constructed
+    directly — use :class:`lumify.Lumify`."""
+
+    def __init__(
+        self,
+        api_key: str,
+        *,
+        base_url: str = DEFAULT_BASE_URL,
+        timeout: float = DEFAULT_TIMEOUT,
+        max_retries: int = DEFAULT_MAX_RETRIES,
+        transport: Optional[Transport] = None,
+        user_agent: Optional[str] = None,
+    ) -> None:
+        if not api_key:
+            raise ValueError(
+                "Lumify SDK: `api_key` is required (create one at "
+                "https://lumify.ai/api-keys)."
+            )
+        self._api_key = api_key
+        self.base_url = (base_url or DEFAULT_BASE_URL).rstrip("/")
+        self.timeout = timeout
+        self.max_retries = max_retries
+        self._transport: Transport = transport or _urllib_transport
+        suffix = (" " + user_agent) if user_agent else ""
+        self.user_agent = "lumify-sdk-python/%s%s" % (SDK_VERSION, suffix)
+
+    def build_url(self, path: str, query: Optional[Mapping[str, Any]] = None) -> str:
+        return "%s%s%s" % (self.base_url, path, _build_query(query))
+
+    def auth_headers(self, accept: str = "application/json") -> Dict[str, str]:
+        return {
+            "Authorization": "Bearer %s" % self._api_key,
+            "Accept": accept,
+            "User-Agent": self.user_agent,
+        }
+
+    @property
+    def transport(self) -> Transport:
+        return self._transport
+
+    def get(self, path: str, *, query: Optional[Mapping[str, Any]] = None) -> Any:
+        return self.request("GET", path, query=query, idempotent=True)
+
+    def post(
+        self,
+        path: str,
+        *,
+        query: Optional[Mapping[str, Any]] = None,
+        body: Any = None,
+    ) -> Any:
+        return self.request("POST", path, query=query, body=body, idempotent=False)
+
+    def delete(self, path: str, *, query: Optional[Mapping[str, Any]] = None) -> Any:
+        return self.request("DELETE", path, query=query, idempotent=True)
+
+    def request(
+        self,
+        method: str,
+        path: str,
+        *,
+        query: Optional[Mapping[str, Any]] = None,
+        body: Any = None,
+        idempotent: Optional[bool] = None,
+    ) -> Any:
+        if idempotent is None:
+            idempotent = method == "GET"
+        attempts = max(1, self.max_retries + 1) if idempotent else 1
+
+        prepared = self._prepare(method, path, query, body)
+        last_exc: Optional[LumifyError] = None
+
+        for attempt in range(attempts):
+            if attempt > 0:
+                time.sleep(self._backoff(attempt, last_exc))
+            try:
+                raw = self._transport(prepared, self.timeout)
+                return self._process(method, path, raw)
+            except LumifyError as exc:
+                last_exc = exc
+                if not (idempotent and self._should_retry(exc) and attempt < attempts - 1):
+                    raise
+        # Unreachable — the loop always returns or raises.
+        assert last_exc is not None
+        raise last_exc
+
+    def _prepare(
+        self, method: str, path: str, query: Optional[Mapping[str, Any]], body: Any
+    ) -> PreparedRequest:
+        headers = self.auth_headers()
+        payload: Optional[str] = None
+        if body is not None:
+            headers["Content-Type"] = "application/json"
+            # Drop top-level None values, mirroring the TS SDK's
+            # `JSON.stringify` (which silently omits `undefined`-valued keys)
+            # — so optional params left unset never serialize as `null`.
+            if isinstance(body, dict):
+                body = {k: v for k, v in body.items() if v is not None}
+            payload = _json.dumps(body)
+        return PreparedRequest(method, self.build_url(path, query), headers, payload)
+
+    def _process(self, method: str, path: str, raw: RawResponse) -> Any:
+        headers = _CaseInsensitiveHeaders(raw.headers)
+        request_id = headers.get("x-request-id")
+        parsed = _safe_json(raw.text) if raw.text else None
+        parse_failed = bool(raw.text) and parsed is _UNPARSEABLE
+
+        if not (200 <= raw.status < 300):
+            payload = None
+            if isinstance(parsed, dict):
+                err = parsed.get("error")
+                if isinstance(err, dict):
+                    payload = err
+            raise error_from_response(
+                raw.status,
+                payload,
+                request_id,
+                retry_after_header=_parse_retry_after(headers.get("retry-after")),
+            )
+
+        if parse_failed:
+            from .errors import APIError
+
+            raise APIError(
+                "Response from %s %s was not valid JSON." % (method, path),
+                status=raw.status,
+                code="invalid_response",
+                request_id=request_id,
+            )
+
+        return attach_meta(parsed, parse_meta(raw.headers))
+
+    def _should_retry(self, exc: LumifyError) -> bool:
+        if isinstance(exc, ConnectionError):
+            return True
+        return exc.status == 429 or exc.status >= 500
+
+    def _backoff(self, attempt: int, last_exc: Optional[LumifyError]) -> float:
+        if isinstance(last_exc, RateLimitError) and last_exc.retry_after is not None:
+            if last_exc.retry_after >= 0:
+                return float(last_exc.retry_after)
+        base = 0.25 * (2 ** (attempt - 1))
+        return base + random.random() * 0.1

lumify/client.py

@@ -0,0 +1,58 @@
+from __future__ import annotations
+
+from typing import Optional
+
+from ._transport import DEFAULT_BASE_URL, DEFAULT_MAX_RETRIES, DEFAULT_TIMEOUT, LumifyClient, Transport
+from .resources import (
+    AgentResource,
+    EventsResource,
+    PlayersResource,
+    SeasonsResource,
+    SportsResource,
+    TeamsResource,
+    WebhooksResource,
+)
+
+
+class Lumify:
+    """The Lumify SDK entry point.
+
+    Example::
+
+        from lumify import Lumify
+
+        client = Lumify(api_key=os.environ["LUMIFY_API_KEY"])
+        sports = client.sports.list()
+        event = client.events.get(12345, include_odds=True)
+    """
+
+    def __init__(
+        self,
+        api_key: str,
+        *,
+        base_url: str = DEFAULT_BASE_URL,
+        timeout: float = DEFAULT_TIMEOUT,
+        max_retries: int = DEFAULT_MAX_RETRIES,
+        transport: Optional[Transport] = None,
+        user_agent: Optional[str] = None,
+    ) -> None:
+        self._client = LumifyClient(
+            api_key,
+            base_url=base_url,
+            timeout=timeout,
+            max_retries=max_retries,
+            transport=transport,
+            user_agent=user_agent,
+        )
+        self.sports = SportsResource(self._client)
+        self.seasons = SeasonsResource(self._client)
+        self.events = EventsResource(self._client)
+        self.teams = TeamsResource(self._client)
+        self.players = PlayersResource(self._client)
+        self.webhooks = WebhooksResource(self._client)
+        self.agent = AgentResource(self._client)
+
+    @property
+    def base_url(self) -> str:
+        """The configured API origin (default ``https://lumify.ai``)."""
+        return self._client.base_url

lumify/errors.py

@@ -0,0 +1,169 @@
+"""
+Error taxonomy mirroring api/errors.py's unified envelope (and the TS SDK's
+errors.ts):
+
+    { "error": { "code", "message", "status", "doc_url", ...extra }, "detail" }
+
+Agents should switch on ``err.code``, not parse ``err.message``.
+"""
+
+from __future__ import annotations
+
+from typing import Any, Dict, List, Optional
+
+
+class LumifyError(Exception):
+    """Base class for every error the SDK raises for a non-2xx API response."""
+
+    def __init__(
+        self,
+        message: str,
+        *,
+        status: int,
+        code: str,
+        doc_url: Optional[str] = None,
+        request_id: Optional[str] = None,
+        payload: Optional[Dict[str, Any]] = None,
+    ) -> None:
+        super().__init__(message)
+        self.message = message
+        #: Stable machine-readable slug, e.g. ``"not_found"`` — switch on this.
+        self.code = code
+        #: HTTP status code (0 for connection errors).
+        self.status = status
+        #: Link to the error-code reference docs, when the envelope carries one.
+        self.doc_url = doc_url
+        #: Value of the ``X-Request-Id`` response header, if present.
+        self.request_id = request_id
+        #: The full parsed ``error`` object from the response envelope.
+        self.payload = payload or {}
+
+    def __repr__(self) -> str:  # pragma: no cover - cosmetic
+        return "%s(code=%r, status=%r, message=%r)" % (
+            type(self).__name__,
+            self.code,
+            self.status,
+            self.message,
+        )
+
+
+class AuthenticationError(LumifyError):
+    """401 — missing/invalid API key."""
+
+
+class PaymentError(LumifyError):
+    """402 — credit top-up or payment method required."""
+
+
+class PermissionError(LumifyError):
+    """403 — key lacks scope/plan for this resource."""
+
+    def __init__(self, message: str, **kwargs: Any) -> None:
+        super().__init__(message, **kwargs)
+        #: Present on sport-scope denials — where to upgrade the key's plan/scope.
+        self.upgrade_url: Optional[str] = self.payload.get("upgrade_url")
+
+
+class NotFoundError(LumifyError):
+    """404 — resource does not exist."""
+
+
+class FieldError:
+    """One entry in a 422 validation error's ``errors`` list."""
+
+    __slots__ = ("field", "message", "type")
+
+    def __init__(self, field: str, message: str, type: str) -> None:  # noqa: A002
+        self.field = field
+        self.message = message
+        self.type = type
+
+    def __repr__(self) -> str:  # pragma: no cover - cosmetic
+        return "FieldError(field=%r, message=%r, type=%r)" % (
+            self.field,
+            self.message,
+            self.type,
+        )
+
+
+class ValidationError(LumifyError):
+    """422 — request failed server-side validation."""
+
+    def __init__(self, message: str, **kwargs: Any) -> None:
+        super().__init__(message, **kwargs)
+        raw = self.payload.get("errors") or []
+        self.field_errors: List[FieldError] = [
+            FieldError(
+                field=str(e.get("field", "")),
+                message=str(e.get("message", "")),
+                type=str(e.get("type", "")),
+            )
+            for e in raw
+            if isinstance(e, dict)
+        ]
+
+
+class RateLimitError(LumifyError):
+    """429 — rate limit exceeded."""
+
+    def __init__(
+        self, message: str, *, retry_after: Optional[float] = None, **kwargs: Any
+    ) -> None:
+        super().__init__(message, **kwargs)
+        # Prefer the envelope field (canonical for Lumify), fall back to the header.
+        from_payload = self.payload.get("retry_after")
+        if isinstance(from_payload, (int, float)):
+            self.retry_after: Optional[float] = float(from_payload)
+        elif retry_after is not None:
+            self.retry_after = float(retry_after)
+        else:
+            self.retry_after = None
+
+
+class APIError(LumifyError):
+    """5xx, or any status this SDK has no dedicated class for."""
+
+
+class ConnectionError(LumifyError):
+    """Network failure, timeout, or abort — the request never got a response."""
+
+    def __init__(self, message: str, *, cause: Optional[BaseException] = None) -> None:
+        super().__init__(message, status=0, code="connection_error")
+        self.__cause__ = cause
+
+
+def error_from_response(
+    status: int,
+    payload: Optional[Dict[str, Any]],
+    request_id: Optional[str],
+    *,
+    retry_after_header: Optional[float] = None,
+) -> LumifyError:
+    """Build the right LumifyError subclass from a parsed error envelope.
+
+    Falls back to :class:`APIError` for unrecognized status codes.
+    """
+    payload = payload or None
+    code = (payload or {}).get("code") or ("http_%d" % status)
+    message = (payload or {}).get("message") or ("Request failed with status %d." % status)
+    common = dict(
+        status=status,
+        code=code,
+        doc_url=(payload or {}).get("doc_url"),
+        request_id=request_id,
+        payload=payload,
+    )
+
+    if status == 401:
+        return AuthenticationError(message, **common)
+    if status == 402:
+        return PaymentError(message, **common)
+    if status == 403:
+        return PermissionError(message, **common)
+    if status == 404:
+        return NotFoundError(message, **common)
+    if status == 422:
+        return ValidationError(message, **common)
+    if status == 429:
+        return RateLimitError(message, retry_after=retry_after_header, **common)
+    return APIError(message, **common)