koios-client 1.0.0__py3-none-any.whl

koios_client/__init__.py

@@ -0,0 +1,85 @@
+"""Koios Client — typed Python SDK for the Koios IoT platform.
+
+Quick start:
+    from koios_client import KoiosClient
+
+    client = KoiosClient(
+        hostname="koios.example.com",
+        client_id="your-client-uuid",
+        client_secret="your-client-secret",
+    )
+
+    # High-level resource API (lookup by ID or UUID slug)
+    device = client.device(1)  # by ID (default)
+    device.enable()
+    for tag in device.tags():
+        print(tag.name, tag.value)
+
+    # Low-level GraphQL (fully typed — IDE autocomplete works)
+    result = client.gql.get_devices()
+    for device in result.devices.results:
+        print(device.name, device.status)
+
+Enums, input types, and response types are available from koios_client.types:
+    from koios_client.types import (
+        StatusChoices, UsageChoices, DeviceInput, OffsetPaginationInput,
+    )
+
+Resource classes are available from koios_client.resources:
+    from koios_client.resources import Device, Tag, Model, PaginatedList
+"""
+
+from koios_client.client import KoiosClient
+from koios_client.exceptions import (
+    AuthenticationError,
+    GraphQLError,
+    KoiosConnectionError,
+    KoiosError,
+    KoiosPermissionError,
+    NotFoundError,
+    OperationError,
+    OperationMessage,
+    ValidationError,
+)
+from koios_client.resources import (
+    Binding,
+    Device,
+    DeviceSet,
+    Model,
+    PaginatedList,
+    Protocol,
+    Resource,
+    ScanGroup,
+    Tag,
+)
+
+__all__ = [
+    # Client
+    "KoiosClient",
+    # Resources
+    "Binding",
+    "Device",
+    "DeviceSet",
+    "Model",
+    "PaginatedList",
+    "Protocol",
+    "Resource",
+    "ScanGroup",
+    "Tag",
+    # Exceptions
+    "KoiosError",
+    "AuthenticationError",
+    "KoiosConnectionError",
+    "GraphQLError",
+    "NotFoundError",
+    "OperationError",
+    "OperationMessage",
+    "KoiosPermissionError",
+    "ValidationError",
+]
+try:
+    from importlib.metadata import version as _get_version
+
+    __version__ = _get_version("koios-client")
+except Exception:
+    __version__ = "0.0.0"

koios_client/_auth.py

@@ -0,0 +1,229 @@
+"""JWT token management for Koios API authentication.
+
+Handles obtaining and refreshing tokens via the GraphQL endpoint.
+Uses a dedicated httpx.Client (not the generated client) to avoid circular auth dependency.
+"""
+
+from __future__ import annotations
+
+import logging
+import time
+from collections.abc import Generator
+from dataclasses import dataclass
+from typing import Any
+
+import httpx
+
+from koios_client.exceptions import AuthenticationError
+
+logger = logging.getLogger(__name__)
+
+# Shared inline fragment for token union responses.
+_TOKEN_FRAGMENTS = """
+    ... on TokenResultType {
+      __typename
+      access
+      refresh
+      expiresIn
+    }
+    ... on OperationInfo {
+      __typename
+      messages {
+        message
+      }
+    }
+"""
+
+_OBTAIN_TOKEN_QUERY = f"""
+mutation ObtainClientToken($credentials: ClientCredentialsInput!) {{
+  obtainClientToken(credentials: $credentials) {{
+{_TOKEN_FRAGMENTS}
+  }}
+}}
+"""
+
+_REFRESH_TOKEN_QUERY = f"""
+mutation RefreshToken($refreshInput: RefreshTokenInput!) {{
+  refreshToken(refreshInput: $refreshInput) {{
+{_TOKEN_FRAGMENTS}
+  }}
+}}
+"""
+
+# Buffer in seconds — refresh tokens before they actually expire.
+_EXPIRY_BUFFER_SECONDS = 60
+
+
+@dataclass
+class TokenPair:
+    """JWT access and refresh token pair with expiry tracking."""
+
+    access: str
+    refresh: str
+    expires_at: float  # Unix timestamp
+
+
+class KoiosAuth(httpx.Auth):
+    """httpx Auth handler that manages Koios JWT tokens.
+
+    Obtains an initial token on first use and automatically refreshes
+    before expiry or on HTTP 401.
+
+    Args:
+        url: GraphQL endpoint URL (e.g. "https://koios.example.com:443/graphql/").
+        client_id: Endpoint client UUID.
+        client_secret: Endpoint client secret.
+        verify_ssl: Whether to verify TLS certificates.
+    """
+
+    requires_response_body = True
+
+    def __init__(
+        self,
+        url: str,
+        client_id: str,
+        client_secret: str,
+        *,
+        verify_ssl: bool = True,
+    ) -> None:
+        self._url = url
+        self._client_id = client_id
+        self._client_secret = client_secret
+        self._verify_ssl = verify_ssl
+        self._token: TokenPair | None = None
+        # Dedicated client for auth requests — reuses TCP/TLS connections.
+        self._auth_http = httpx.Client(verify=verify_ssl, timeout=30.0)
+
+    def auth_flow(  # type: ignore[override]
+        self, request: httpx.Request
+    ) -> Generator[httpx.Request, httpx.Response, None]:
+        """Inject Bearer token, refreshing if needed."""
+        if self._token is None:
+            self._obtain_token()
+        elif self._is_expired():
+            self._refresh_or_obtain()
+
+        assert self._token is not None  # ensured by _obtain_token / _refresh_or_obtain
+        request.headers["Authorization"] = f"Bearer {self._token.access}"
+        response = yield request
+
+        # Retry once on 401 (token may have been invalidated server-side)
+        if response.status_code == 401:
+            logger.debug("Got 401, attempting token refresh")
+            self._refresh_or_obtain()
+            assert self._token is not None
+            request.headers["Authorization"] = f"Bearer {self._token.access}"
+            yield request
+
+    @property
+    def is_authenticated(self) -> bool:
+        """Whether we currently hold a valid (non-expired) token."""
+        return self._token is not None and not self._is_expired()
+
+    def force_refresh(self) -> None:
+        """Force a token refresh. Useful if permissions changed server-side."""
+        if self._token is not None:
+            self._refresh_token()
+        else:
+            self._obtain_token()
+
+    def close(self) -> None:
+        """Close the dedicated auth HTTP client."""
+        self._auth_http.close()
+
+    def _is_expired(self) -> bool:
+        if self._token is None:
+            return True
+        return time.time() >= (self._token.expires_at - _EXPIRY_BUFFER_SECONDS)
+
+    def _refresh_or_obtain(self) -> None:
+        """Try refresh first; fall back to full re-authentication."""
+        try:
+            self._refresh_token()
+        except Exception:
+            logger.debug("Token refresh failed, re-authenticating")
+            self._obtain_token()
+
+    def _obtain_token(self) -> None:
+        """Obtain a new token pair using client credentials."""
+        result = self._execute_auth_mutation(
+            query=_OBTAIN_TOKEN_QUERY,
+            variables={
+                "credentials": {
+                    "clientId": self._client_id,
+                    "clientSecret": self._client_secret,
+                }
+            },
+            operation="obtainClientToken",
+        )
+        self._parse_token_result(result, "obtainClientToken")
+
+    def _refresh_token(self) -> None:
+        """Refresh the access token using the refresh token."""
+        if self._token is None:
+            raise AuthenticationError("No token to refresh")
+
+        result = self._execute_auth_mutation(
+            query=_REFRESH_TOKEN_QUERY,
+            variables={
+                "refreshInput": {
+                    "refreshToken": self._token.refresh,
+                }
+            },
+            operation="refreshToken",
+        )
+        self._parse_token_result(result, "refreshToken")
+
+    def _execute_auth_mutation(
+        self, *, query: str, variables: dict[str, Any], operation: str
+    ) -> dict[str, Any]:
+        """Execute a raw GraphQL mutation for auth and return the result dict."""
+        response = self._auth_http.post(
+            self._url,
+            json={"query": query, "variables": variables},
+        )
+
+        if response.status_code != 200:
+            raise AuthenticationError(f"{operation} failed with HTTP {response.status_code}")
+
+        data = response.json()
+
+        if "errors" in data:
+            msg = data["errors"][0].get("message", "Unknown error")
+            raise AuthenticationError(f"{operation} failed: {msg}")
+
+        return data.get("data", {}).get(operation, {})
+
+    def _parse_token_result(self, result: dict[str, Any], operation: str) -> None:
+        """Parse a token result, handling both success and OperationInfo."""
+        if not result:
+            raise AuthenticationError(f"{operation} returned empty result")
+
+        # Check for OperationInfo (error response)
+        typename = result.get("__typename", "")
+        if typename == "OperationInfo":
+            messages = result.get("messages", [])
+            msg = messages[0]["message"] if messages else "Unknown error"
+            raise AuthenticationError(f"{operation} failed: {msg}")
+
+        # Parse successful token response
+        access = result.get("access")
+        refresh = result.get("refresh")
+        expires_in = result.get("expiresIn")
+
+        if not access:
+            raise AuthenticationError(f"{operation} returned incomplete token data")
+
+        # On refresh, the server may omit the refresh token to signal "keep the
+        # existing one" — this keeps refresh tokens long-lived across access refreshes.
+        if not refresh:
+            if self._token is None:
+                raise AuthenticationError(f"{operation} returned no refresh token")
+            refresh = self._token.refresh
+
+        self._token = TokenPair(
+            access=access,
+            refresh=refresh,
+            expires_at=time.time() + (expires_in or 3600),
+        )
+        logger.debug("Token obtained, expires in %ds", expires_in or 3600)