fluvius-energy-api 0.1.0__py3-none-any.whl

fluvius_energy_api/__init__.py

@@ -0,0 +1,140 @@
+"""Fluvius Energy API Python wrapper."""
+
+from .auth import TokenProvider
+from .client import Environment, FluviusEnergyClient
+from .credentials import FluviusCredentials
+from .exceptions import (
+    AuthenticationError,
+    ConfigurationError,
+    FluviusAPIError,
+    ForbiddenError,
+    NotFoundError,
+    ServerError,
+    ServiceUnavailableError,
+    ValidationError,
+)
+from .models import (
+    AuxiliarySubHeadpoint,
+    ClientSessionDataService,
+    CreateClientSessionRequest,
+    CreateClientSessionResponse,
+    CreateClientSessionResponseApiDataResponse,
+    CreateClientSessionStatus,
+    CreateMandateRequest,
+    CreateMandateResponse,
+    CreateMandateResponseApiDataResponse,
+    DataServiceType,
+    EnergyType,
+    ErrorResponse,
+    ErrorValidationResponse,
+    EstimatedVolume,
+    EstimatedVolumeType,
+    Flow,
+    GasConversionFactor,
+    GetEnergyResponse,
+    GetEnergyResponseApiDataResponse,
+    GetInstallationResponse,
+    GetInstallationResponseApiDataResponse,
+    GetMandatesResponse,
+    GetMandatesResponseApiDataResponse,
+    Headpoint,
+    HeadpointUnion,
+    Installation,
+    LocalProductionInstallation,
+    LocalProductionInstallationType,
+    Mandate,
+    MandateRenewalStatus,
+    MandateStatus,
+    MeasurementDirection,
+    MeasurementTimeSlice,
+    MeasurementValue,
+    MeasurementValidationState,
+    MeasurementValueSet,
+    MeterType,
+    MeteringOnHeadpoint,
+    MeteringOnHeadpointAndMeter,
+    MeteringOnMeter,
+    OfftakeSubHeadpoint,
+    PeriodType,
+    PhysicalMeter,
+    ProductionSubHeadpoint,
+    Register,
+    ResponseMetadata,
+    SubHeadpoint,
+    SubHeadpointUnion,
+    Unit,
+)
+
+__version__ = "0.1.0"
+
+__all__ = [
+    # Client & Auth
+    "Environment",
+    "FluviusEnergyClient",
+    "FluviusCredentials",
+    "TokenProvider",
+    # Exceptions
+    "AuthenticationError",
+    "ConfigurationError",
+    "FluviusAPIError",
+    "ForbiddenError",
+    "NotFoundError",
+    "ServerError",
+    "ServiceUnavailableError",
+    "ValidationError",
+    # Enums
+    "CreateClientSessionStatus",
+    "DataServiceType",
+    "EnergyType",
+    "EstimatedVolumeType",
+    "Flow",
+    "GasConversionFactor",
+    "LocalProductionInstallationType",
+    "MandateRenewalStatus",
+    "MandateStatus",
+    "MeasurementValidationState",
+    "MeterType",
+    "PeriodType",
+    "Register",
+    "Unit",
+    # Base models
+    "ErrorResponse",
+    "ErrorValidationResponse",
+    "ResponseMetadata",
+    # Session models
+    "ClientSessionDataService",
+    "CreateClientSessionRequest",
+    "CreateClientSessionResponse",
+    "CreateClientSessionResponseApiDataResponse",
+    # Mandate models
+    "CreateMandateRequest",
+    "CreateMandateResponse",
+    "CreateMandateResponseApiDataResponse",
+    "GetMandatesResponse",
+    "GetMandatesResponseApiDataResponse",
+    "Mandate",
+    # Energy models
+    "AuxiliarySubHeadpoint",
+    "GetEnergyResponse",
+    "GetEnergyResponseApiDataResponse",
+    "Headpoint",
+    "HeadpointUnion",
+    "MeasurementDirection",
+    "MeasurementTimeSlice",
+    "MeasurementValue",
+    "MeasurementValueSet",
+    "MeteringOnHeadpoint",
+    "MeteringOnHeadpointAndMeter",
+    "MeteringOnMeter",
+    "OfftakeSubHeadpoint",
+    "PhysicalMeter",
+    "ProductionSubHeadpoint",
+    "SubHeadpoint",
+    "SubHeadpointUnion",
+    # Installation models
+    "EstimatedVolume",
+    "GetInstallationResponse",
+    "GetInstallationResponseApiDataResponse",
+    "Installation",
+    "LocalProductionInstallation",
+]

fluvius_energy_api/_http.py

@@ -0,0 +1,128 @@
+"""Internal HTTP client wrapper for the Fluvius Energy API."""
+
+from __future__ import annotations
+
+from typing import TYPE_CHECKING, Any
+
+import httpx
+
+from .exceptions import (
+    AuthenticationError,
+    FluviusAPIError,
+    ForbiddenError,
+    NotFoundError,
+    ServerError,
+    ServiceUnavailableError,
+    ValidationError,
+)
+from .models.base import ErrorResponse, ErrorValidationResponse
+
+if TYPE_CHECKING:
+    from .auth import TokenProvider
+
+
+class HTTPClient:
+    """Internal HTTP client with authentication and error handling."""
+
+    def __init__(
+        self,
+        base_url: str,
+        token_provider: TokenProvider,
+        timeout: float = 30.0,
+    ) -> None:
+        self._base_url = base_url.rstrip("/")
+        self._token_provider = token_provider
+        self._timeout = timeout
+        self._client: httpx.Client | None = None
+
+    def _get_client(self) -> httpx.Client:
+        """Get or create the HTTP client."""
+        if self._client is None:
+            self._client = httpx.Client(
+                base_url=self._base_url,
+                timeout=self._timeout,
+            )
+        return self._client
+
+    def _get_headers(self) -> dict[str, str]:
+        """Get headers for API requests, including fresh auth token."""
+        headers = self._token_provider.get_authorization_headers()
+        headers["Content-Type"] = "application/json"
+        headers["Accept"] = "application/json"
+        return headers
+
+    def close(self) -> None:
+        """Close the HTTP client."""
+        if self._client is not None:
+            self._client.close()
+            self._client = None
+        self._token_provider.close()
+
+    def _handle_error_response(self, response: httpx.Response) -> None:
+        """Handle error responses from the API."""
+        error_response: ErrorResponse | ErrorValidationResponse | None = None
+
+        try:
+            error_data = response.json()
+            # Check for validation errors (API returns PascalCase)
+            if "validationErrorMessages" in error_data or "ValidationErrorMessages" in error_data:
+                error_response = ErrorValidationResponse.model_validate(error_data)
+            else:
+                error_response = ErrorResponse.model_validate(error_data)
+        except Exception:
+            pass
+
+        message = (
+            error_response.message
+            if error_response and error_response.message
+            else response.text or f"HTTP {response.status_code}"
+        )
+
+        match response.status_code:
+            case 400:
+                raise ValidationError(
+                    message=message,
+                    error_response=error_response
+                    if isinstance(error_response, ErrorValidationResponse)
+                    else None,
+                )
+            case 401:
+                raise AuthenticationError(message=message, error_response=error_response)
+            case 403:
+                raise ForbiddenError(message=message, error_response=error_response)
+            case 404:
+                raise NotFoundError(message=message, error_response=error_response)
+            case 500:
+                raise ServerError(message=message, error_response=error_response)
+            case 503:
+                raise ServiceUnavailableError(
+                    message=message, error_response=error_response
+                )
+            case _:
+                raise FluviusAPIError(
+                    message=message,
+                    status_code=response.status_code,
+                    error_response=error_response,
+                )
+
+    def get(self, path: str, params: dict[str, Any] | None = None) -> dict[str, Any]:
+        """Make a GET request."""
+        client = self._get_client()
+        response = client.get(path, params=params, headers=self._get_headers())
+
+        if not response.is_success:
+            self._handle_error_response(response)
+
+        return response.json()
+
+    def post(
+        self, path: str, json_data: dict[str, Any] | None = None
+    ) -> dict[str, Any]:
+        """Make a POST request."""
+        client = self._get_client()
+        response = client.post(path, json=json_data, headers=self._get_headers())
+
+        if not response.is_success:
+            self._handle_error_response(response)
+
+        return response.json()

fluvius_energy_api/auth.py

@@ -0,0 +1,239 @@
+"""OAuth2 token management for Fluvius API authentication."""
+
+from __future__ import annotations
+
+import base64
+import logging
+import time
+import uuid
+from dataclasses import dataclass
+
+import httpx
+import jwt
+
+from .credentials import FluviusCredentials
+from .exceptions import AuthenticationError
+
+logger = logging.getLogger(__name__)
+
+AZURE_AD_TOKEN_URL = "https://login.microsoftonline.com/{tenant_id}/oauth2/v2.0/token"
+TOKEN_LIFETIME_SECONDS = 3600
+REFRESH_MARGIN_SECONDS = 60
+
+
+@dataclass
+class AccessToken:
+    """Represents an OAuth2 access token."""
+
+    access_token: str
+    token_type: str
+    expires_in: int
+    obtained_at: float
+
+    @property
+    def expires_at(self) -> float:
+        """Unix timestamp when the token expires."""
+        return self.obtained_at + self.expires_in
+
+    def is_expired(self, margin_seconds: int = REFRESH_MARGIN_SECONDS) -> bool:
+        """Check if the token is expired or about to expire.
+
+        Args:
+            margin_seconds: Safety margin in seconds before actual expiration.
+
+        Returns:
+            True if the token should be refreshed.
+        """
+        return time.time() >= (self.expires_at - margin_seconds)
+
+
+class TokenProvider:
+    """Manages OAuth2 token lifecycle with automatic refresh.
+
+    Supports two authentication methods:
+    - Certificate-based: Uses JWT bearer assertion with RS256 (production)
+    - Client secret: Uses simple client_secret parameter (sandbox)
+
+    Tokens are cached and automatically refreshed before expiration.
+
+    Attributes:
+        credentials: The Fluvius API credentials.
+
+    Example:
+        ```python
+        credentials = FluviusCredentials.from_env()
+        token_provider = TokenProvider(credentials)
+
+        # Get a valid access token (auto-refreshes if needed)
+        token = token_provider.get_access_token()
+
+        # Get authorization headers for API requests
+        headers = token_provider.get_authorization_headers()
+        ```
+    """
+
+    def __init__(self, credentials: FluviusCredentials) -> None:
+        """Initialize the token provider.
+
+        Args:
+            credentials: The Fluvius API credentials.
+        """
+        self.credentials = credentials
+        self._token: AccessToken | None = None
+        self._http_client: httpx.Client | None = None
+
+    def _get_http_client(self) -> httpx.Client:
+        """Get or create the HTTP client for token requests."""
+        if self._http_client is None:
+            self._http_client = httpx.Client(timeout=30.0)
+        return self._http_client
+
+    def close(self) -> None:
+        """Close the HTTP client."""
+        if self._http_client is not None:
+            self._http_client.close()
+            self._http_client = None
+
+    def get_access_token(self) -> str:
+        """Get a valid access token, refreshing if necessary.
+
+        Returns:
+            The access token string.
+
+        Raises:
+            AuthenticationError: If token acquisition fails.
+        """
+        if self._token is None or self._token.is_expired():
+            logger.debug("Token is missing or expired, acquiring new token")
+            self._token = self._acquire_token()
+        else:
+            logger.debug("Reusing cached token")
+
+        return self._token.access_token
+
+    def get_authorization_headers(self) -> dict[str, str]:
+        """Get HTTP headers for authenticated API requests.
+
+        Returns:
+            Dictionary containing Authorization and subscription key headers.
+        """
+        return {
+            "Authorization": f"Bearer {self.get_access_token()}",
+            "Ocp-Apim-Subscription-Key": self.credentials.subscription_key,
+        }
+
+    def _acquire_token(self) -> AccessToken:
+        """Acquire a new access token from Azure AD.
+
+        Uses certificate-based auth if credentials include certificate,
+        otherwise uses client secret.
+
+        Returns:
+            The acquired access token.
+
+        Raises:
+            AuthenticationError: If token acquisition fails.
+        """
+        token_url = AZURE_AD_TOKEN_URL.format(tenant_id=self.credentials.tenant_id)
+
+        # Build request data based on authentication method
+        if self.credentials.uses_certificate:
+            logger.debug("Using certificate-based authentication")
+            client_assertion = self._create_client_assertion()
+            data = {
+                "grant_type": "client_credentials",
+                "client_id": self.credentials.client_id,
+                "client_assertion_type": "urn:ietf:params:oauth:client-assertion-type:jwt-bearer",
+                "client_assertion": client_assertion,
+                "scope": self.credentials.scope,
+            }
+        else:
+            logger.debug("Using client secret authentication")
+            data = {
+                "grant_type": "client_credentials",
+                "client_id": self.credentials.client_id,
+                "client_secret": self.credentials.client_secret,
+                "scope": self.credentials.scope,
+            }
+
+        client = self._get_http_client()
+        obtained_at = time.time()
+
+        try:
+            response = client.post(
+                token_url,
+                data=data,
+                headers={"Content-Type": "application/x-www-form-urlencoded"},
+            )
+            response.raise_for_status()
+        except httpx.HTTPStatusError as e:
+            error_detail = ""
+            try:
+                error_body = e.response.json()
+                error_detail = f": {error_body.get('error_description', error_body.get('error', ''))}"
+            except Exception:
+                pass
+            raise AuthenticationError(
+                f"Failed to acquire access token{error_detail}"
+            ) from e
+        except httpx.RequestError as e:
+            raise AuthenticationError(
+                f"Failed to connect to Azure AD: {e}"
+            ) from e
+
+        token_data = response.json()
+
+        return AccessToken(
+            access_token=token_data["access_token"],
+            token_type=token_data.get("token_type", "Bearer"),
+            expires_in=token_data.get("expires_in", TOKEN_LIFETIME_SECONDS),
+            obtained_at=obtained_at,
+        )
+
+    def _create_client_assertion(self) -> str:
+        """Create a signed JWT client assertion for Azure AD.
+
+        Returns:
+            The signed JWT token.
+        """
+        now = int(time.time())
+        expiry = now + TOKEN_LIFETIME_SECONDS
+
+        headers = {
+            "alg": "RS256",
+            "typ": "JWT",
+            "x5t": self._encode_thumbprint(self.credentials.certificate_thumbprint),
+        }
+
+        payload = {
+            "aud": f"https://login.microsoftonline.com/{self.credentials.tenant_id}/v2.0",
+            "iss": self.credentials.client_id,
+            "sub": self.credentials.client_id,
+            "jti": str(uuid.uuid4()),
+            "nbf": now,
+            "exp": expiry,
+        }
+
+        return jwt.encode(
+            payload,
+            self.credentials.private_key,
+            algorithm="RS256",
+            headers=headers,
+        )
+
+    @staticmethod
+    def _encode_thumbprint(thumbprint: str) -> str:
+        """Encode a certificate thumbprint for the x5t JWT header.
+
+        The thumbprint is a hexadecimal string that needs to be converted
+        to bytes and then base64url-encoded.
+
+        Args:
+            thumbprint: Hexadecimal certificate thumbprint.
+
+        Returns:
+            Base64url-encoded thumbprint.
+        """
+        thumbprint_bytes = bytes.fromhex(thumbprint)
+        encoded = base64.urlsafe_b64encode(thumbprint_bytes).rstrip(b"=")
+        return encoded.decode("ascii")