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

fluvius_energy_api/client.py

@@ -0,0 +1,334 @@
+"""Main API client for the Fluvius Energy API."""
+
+from __future__ import annotations
+
+from datetime import datetime
+from enum import Enum
+from types import TracebackType
+from typing import Self
+
+from ._http import HTTPClient
+from .auth import TokenProvider
+from .credentials import FluviusCredentials
+from .models.energy import GetEnergyResponseApiDataResponse
+from .models.enums import (
+    DataServiceType,
+    EnergyType,
+    MandateRenewalStatus,
+    MandateStatus,
+    PeriodType,
+)
+from .models.mandate import (
+    CreateMandateRequest,
+    CreateMandateResponseApiDataResponse,
+    GetMandatesResponseApiDataResponse,
+)
+from .models.session import (
+    ClientSessionDataService,
+    CreateClientSessionRequest,
+    CreateClientSessionResponseApiDataResponse,
+)
+
+
+class Environment(str, Enum):
+    """Environment configuration for the Fluvius API."""
+
+    PRODUCTION = "https://apihub.fluvius.be/esco-live/v3"
+    SANDBOX = "https://apihub.fluvius.be/esco-sbx/v3"
+
+
+class FluviusEnergyClient:
+    """Client for interacting with the Fluvius Energy API.
+
+    Authentication is handled automatically using OAuth2 with Azure AD.
+    Credentials can be loaded from environment variables or passed explicitly.
+
+    Args:
+        credentials: OAuth2 credentials for authentication. If not provided,
+            credentials are loaded from environment variables.
+        environment: The API environment to use. Defaults to SANDBOX.
+        timeout: Request timeout in seconds. Defaults to 30.0.
+
+    Environment Variables:
+        FLUVIUS_SUBSCRIPTION_KEY: Azure API Management subscription key.
+        FLUVIUS_CLIENT_ID: Azure AD application (client) ID.
+        FLUVIUS_TENANT_ID: Azure AD tenant ID.
+        FLUVIUS_SCOPE: OAuth2 scope for the Fluvius API.
+        FLUVIUS_CERTIFICATE_THUMBPRINT: Hexadecimal certificate thumbprint.
+        FLUVIUS_PRIVATE_KEY: RSA private key (PEM format or base64-encoded).
+        FLUVIUS_PRIVATE_KEY_PATH: Path to private key file (alternative).
+
+    Example:
+        ```python
+        from fluvius_energy_api import FluviusEnergyClient
+
+        # Using environment variables (recommended)
+        with FluviusEnergyClient() as client:
+            mandates = client.get_mandates()
+
+        # Explicit credentials
+        from fluvius_energy_api import FluviusCredentials, Environment
+
+        credentials = FluviusCredentials(
+            subscription_key="...",
+            client_id="...",
+            tenant_id="...",
+            scope="...",
+            certificate_thumbprint="...",
+            private_key="-----BEGIN RSA PRIVATE KEY-----...",
+        )
+        with FluviusEnergyClient(credentials=credentials, environment=Environment.PRODUCTION) as client:
+            mandates = client.get_mandates()
+        ```
+    """
+
+    def __init__(
+        self,
+        credentials: FluviusCredentials | None = None,
+        environment: Environment = Environment.SANDBOX,
+        timeout: float = 30.0,
+    ) -> None:
+        if credentials is None:
+            credentials = FluviusCredentials.from_env()
+
+        self._token_provider = TokenProvider(credentials)
+        self._http = HTTPClient(
+            base_url=environment.value,
+            token_provider=self._token_provider,
+            timeout=timeout,
+        )
+
+    def close(self) -> None:
+        """Close the client and release resources."""
+        self._http.close()
+
+    def __enter__(self) -> Self:
+        """Enter the context manager."""
+        return self
+
+    def __exit__(
+        self,
+        exc_type: type[BaseException] | None,
+        exc_val: BaseException | None,
+        exc_tb: TracebackType | None,
+    ) -> None:
+        """Exit the context manager."""
+        self.close()
+
+    def create_client_session(
+        self,
+        data_access_contract_number: str,
+        reference_number: str,
+        flow: str,
+        data_services: list[ClientSessionDataService] | None = None,
+        number_of_eans: int | None = None,
+        return_url_success: str | None = None,
+        return_url_failed: str | None = None,
+        sso: bool | None = None,
+        enterprise_number: str | None = None,
+    ) -> CreateClientSessionResponseApiDataResponse:
+        """Create a new client session.
+
+        Args:
+            data_access_contract_number: The data access contract number.
+            reference_number: The reference number.
+            flow: The flow type (B2C or B2B).
+            data_services: Optional list of data services.
+            number_of_eans: Optional number of EANs.
+            return_url_success: URL to redirect to on success.
+            return_url_failed: URL to redirect to on failure.
+            sso: Whether to use Single Sign On.
+            enterprise_number: The enterprise number.
+
+        Returns:
+            CreateClientSessionResponseApiDataResponse: The API response.
+        """
+        request = CreateClientSessionRequest(
+            data_access_contract_number=data_access_contract_number,
+            reference_number=reference_number,
+            flow=flow,
+            data_services=data_services,
+            number_of_eans=number_of_eans,
+            return_url_success=return_url_success,
+            return_url_failed=return_url_failed,
+            sso=sso,
+            enterprise_number=enterprise_number,
+        )
+
+        response_data = self._http.post(
+            "/api/shortUrlIdentifier",
+            json_data=request.model_dump(by_alias=True, exclude_none=True),
+        )
+
+        return CreateClientSessionResponseApiDataResponse.model_validate(response_data)
+
+    def get_mandates(
+        self,
+        reference_number: str | None = None,
+        ean: str | None = None,
+        data_service_types: list[DataServiceType] | None = None,
+        energy_type: EnergyType | None = None,
+        status: MandateStatus | None = None,
+        mandate_expiration_date: datetime | None = None,
+        renewal_status: MandateRenewalStatus | None = None,
+        last_updated_from: datetime | None = None,
+        last_updated_to: datetime | None = None,
+    ) -> GetMandatesResponseApiDataResponse:
+        """Get mandates that match the specified filters.
+
+        Args:
+            reference_number: Custom reference number.
+            ean: GSRN EAN-code that identifies the installation.
+            data_service_types: Types of the data service.
+            energy_type: The discipline (E for electricity, G for gas).
+            status: Status of the mandate.
+            mandate_expiration_date: Date and time of the mandate expiration.
+            renewal_status: Renewal status of the mandate.
+            last_updated_from: Start date and time of the last updated filter.
+            last_updated_to: End date and time of the last updated filter.
+
+        Returns:
+            GetMandatesResponseApiDataResponse: The API response containing mandates.
+        """
+        params: dict[str, str] = {}
+
+        if reference_number is not None:
+            params["referenceNumber"] = reference_number
+        if ean is not None:
+            params["ean"] = ean
+        if data_service_types is not None:
+            params["dataServiceTypes"] = ",".join(
+                dst.value if isinstance(dst, DataServiceType) else dst
+                for dst in data_service_types
+            )
+        if energy_type is not None:
+            params["energyType"] = (
+                energy_type.value
+                if isinstance(energy_type, EnergyType)
+                else energy_type
+            )
+        if status is not None:
+            params["status"] = (
+                status.value if isinstance(status, MandateStatus) else status
+            )
+        if mandate_expiration_date is not None:
+            params["mandateExpirationDate"] = mandate_expiration_date.strftime("%Y-%m-%dT%H:%M:%SZ")
+        if renewal_status is not None:
+            params["renewalStatus"] = (
+                renewal_status.value
+                if isinstance(renewal_status, MandateRenewalStatus)
+                else renewal_status
+            )
+        if last_updated_from is not None:
+            params["lastUpdatedFrom"] = last_updated_from.strftime("%Y-%m-%dT%H:%M:%SZ")
+        if last_updated_to is not None:
+            params["lastUpdatedTo"] = last_updated_to.strftime("%Y-%m-%dT%H:%M:%SZ")
+
+        response_data = self._http.get("/api/mandate", params=params or None)
+
+        return GetMandatesResponseApiDataResponse.model_validate(response_data)
+
+    def get_energy(
+        self,
+        ean: str,
+        period_type: PeriodType,
+        reference_number: str | None = None,
+        granularity: str | None = None,
+        complex_energy_types: str | None = None,
+        from_date: datetime | None = None,
+        to_date: datetime | None = None,
+    ) -> GetEnergyResponseApiDataResponse:
+        """Get energy measurements that match the specified filters.
+
+        Args:
+            ean: GSRN EAN-code that identifies the installation (required).
+            period_type: Type of period for the query (required).
+            reference_number: Custom reference number.
+            granularity: Granularity for energy measurements (e.g., "hourly_quarterhourly,daily").
+            complex_energy_types: Types of complex energy (e.g., "active,reactive").
+            from_date: Start date and time of the query.
+            to_date: End date and time of the query.
+
+        Returns:
+            GetEnergyResponseApiDataResponse: The API response containing energy data.
+        """
+        params: dict[str, str] = {
+            "ean": ean,
+            "periodType": (
+                period_type.value
+                if isinstance(period_type, PeriodType)
+                else period_type
+            ),
+        }
+
+        if reference_number is not None:
+            params["referenceNumber"] = reference_number
+        if granularity is not None:
+            params["granularity"] = granularity
+        if complex_energy_types is not None:
+            params["complexEnergyTypes"] = complex_energy_types
+        if from_date is not None:
+            params["from"] = from_date.strftime("%Y-%m-%dT%H:%M:%SZ")
+        if to_date is not None:
+            params["to"] = to_date.strftime("%Y-%m-%dT%H:%M:%SZ")
+
+        response_data = self._http.get("/api/mandate/energy", params=params)
+
+        return GetEnergyResponseApiDataResponse.model_validate(response_data)
+
+    def create_mock_mandate(
+        self,
+        reference_number: str,
+        ean: str,
+        data_service_type: DataServiceType,
+        data_period_from: str | None = None,
+        data_period_to: str | None = None,
+        status: MandateStatus | None = None,
+        mandate_expiration_date: str | None = None,
+        renewal_status: MandateRenewalStatus | None = None,
+    ) -> CreateMandateResponseApiDataResponse:
+        """Create a mock mandate in the sandbox environment.
+
+        This endpoint is only available in the sandbox environment.
+
+        Args:
+            reference_number: Custom reference number for the mandate.
+            ean: GSRN EAN-code that identifies the headpoint.
+            data_service_type: The data service type for the mandate.
+            data_period_from: Start date/time of the data period (ISO format).
+            data_period_to: End date/time of the data period (ISO format).
+            status: Status of the mandate to create.
+            mandate_expiration_date: Expiration date for the mandate (ISO format).
+            renewal_status: Renewal status of the mandate.
+
+        Returns:
+            CreateMandateResponseApiDataResponse: The API response.
+
+        Example:
+            ```python
+            response = client.create_mock_mandate(
+                reference_number="test-mandate-001",
+                ean="541448860000000016",
+                data_service_type=DataServiceType.VH_DAG,
+                data_period_from="2024-01-01T00:00:00Z",
+                status=MandateStatus.APPROVED,
+            )
+            ```
+        """
+        request = CreateMandateRequest(
+            reference_number=reference_number,
+            ean=ean,
+            data_service_type=data_service_type,
+            data_period_from=data_period_from,
+            data_period_to=data_period_to,
+            status=status,
+            mandate_expiration_date=mandate_expiration_date,
+            renewal_status=renewal_status,
+        )
+
+        response_data = self._http.post(
+            "/api/mandate/mock",
+            json_data=request.model_dump(by_alias=True, exclude_none=True),
+        )
+
+        return CreateMandateResponseApiDataResponse.model_validate(response_data)

fluvius_energy_api/credentials.py

@@ -0,0 +1,215 @@
+"""Credentials configuration for Fluvius API authentication."""
+
+from __future__ import annotations
+
+import base64
+import os
+from dataclasses import dataclass
+from pathlib import Path
+
+from .exceptions import ConfigurationError
+
+
+@dataclass(frozen=True)
+class FluviusCredentials:
+    """OAuth2 credentials for Fluvius API authentication.
+
+    Supports two authentication methods:
+    1. Certificate-based (production): Uses certificate_thumbprint + private_key
+    2. Client secret-based (sandbox): Uses client_secret
+
+    Attributes:
+        subscription_key: Azure API Management subscription key.
+        client_id: Azure AD application (client) ID.
+        tenant_id: Azure AD tenant ID.
+        scope: OAuth2 scope for the Fluvius API.
+        certificate_thumbprint: Hexadecimal thumbprint of the certificate (for certificate auth).
+        private_key: RSA private key in PEM format (for certificate auth).
+        client_secret: Client secret (for secret-based auth, typically sandbox).
+
+    Example:
+        ```python
+        # Production with certificate
+        prod_creds = FluviusCredentials(
+            subscription_key="...",
+            client_id="...",
+            tenant_id="...",
+            scope="...",
+            certificate_thumbprint="...",
+            private_key="-----BEGIN RSA PRIVATE KEY-----...",
+        )
+
+        # Sandbox with client secret
+        sandbox_creds = FluviusCredentials(
+            subscription_key="...",
+            client_id="...",
+            tenant_id="...",
+            scope="...",
+            client_secret="...",
+        )
+        ```
+    """
+
+    subscription_key: str
+    client_id: str
+    tenant_id: str
+    scope: str
+    data_access_contract_number: str
+    # Certificate-based auth (production)
+    certificate_thumbprint: str | None = None
+    private_key: str | None = None
+    # Client secret auth (sandbox)
+    client_secret: str | None = None
+
+    def __post_init__(self) -> None:
+        """Validate that all required fields are non-empty."""
+        # Always required
+        for field_name in ["subscription_key", "client_id", "tenant_id", "scope", "data_access_contract_number"]:
+            value = getattr(self, field_name)
+            if not value or not value.strip():
+                raise ConfigurationError(
+                    f"Missing required credential: {field_name}"
+                )
+
+        # Must have either certificate-based or secret-based auth
+        has_certificate = (
+            self.certificate_thumbprint
+            and self.certificate_thumbprint.strip()
+            and self.private_key
+            and self.private_key.strip()
+        )
+        has_secret = self.client_secret and self.client_secret.strip()
+
+        if not has_certificate and not has_secret:
+            raise ConfigurationError(
+                "Missing authentication credentials: provide either "
+                "(certificate_thumbprint + private_key) or client_secret"
+            )
+
+    @property
+    def uses_certificate(self) -> bool:
+        """Return True if using certificate-based authentication."""
+        return bool(
+            self.certificate_thumbprint
+            and self.certificate_thumbprint.strip()
+            and self.private_key
+            and self.private_key.strip()
+        )
+
+    @classmethod
+    def from_env(cls, prefix: str = "FLUVIUS") -> FluviusCredentials:
+        """Load credentials from environment variables.
+
+        Args:
+            prefix: Environment variable prefix. Defaults to "FLUVIUS".
+                Use "FLUVIUS_SANDBOX" for sandbox-specific credentials.
+                Common values (subscription_key, client_id, tenant_id, scope)
+                will fall back to FLUVIUS_* if not found with the prefix.
+
+        Environment Variables:
+            {PREFIX}_SUBSCRIPTION_KEY: Azure API Management subscription key.
+            {PREFIX}_CLIENT_ID: Azure AD application (client) ID.
+            {PREFIX}_TENANT_ID: Azure AD tenant ID.
+            {PREFIX}_SCOPE: OAuth2 scope for the Fluvius API.
+
+            For certificate auth (production):
+            {PREFIX}_CERTIFICATE_THUMBPRINT: Hexadecimal certificate thumbprint.
+            {PREFIX}_PRIVATE_KEY: RSA private key (PEM format or base64-encoded).
+            {PREFIX}_PRIVATE_KEY_PATH: Path to private key file (alternative).
+
+            For client secret auth (sandbox):
+            {PREFIX}_CLIENT_SECRET: Client secret.
+
+            Always required:
+            {PREFIX}_DATA_ACCESS_CONTRACT_NUMBER: Data access contract number.
+
+        Example:
+            ```python
+            # Production (certificate auth)
+            prod_creds = FluviusCredentials.from_env()
+
+            # Sandbox (client secret auth, falls back to FLUVIUS_* for common values)
+            sandbox_creds = FluviusCredentials.from_env(prefix="FLUVIUS_SANDBOX")
+            ```
+
+        Returns:
+            FluviusCredentials: The loaded credentials.
+
+        Raises:
+            ConfigurationError: If required environment variables are missing.
+        """
+        private_key = cls._load_private_key(prefix)
+
+        # Helper to get env var with fallback to default prefix
+        def get_env(name: str, fallback_prefix: str = "FLUVIUS") -> str:
+            value = os.environ.get(f"{prefix}_{name}", "")
+            if not value and prefix != fallback_prefix:
+                value = os.environ.get(f"{fallback_prefix}_{name}", "")
+            return value
+
+        return cls(
+            subscription_key=get_env("SUBSCRIPTION_KEY"),
+            client_id=get_env("CLIENT_ID"),
+            tenant_id=get_env("TENANT_ID"),
+            scope=get_env("SCOPE"),
+            certificate_thumbprint=get_env("CERTIFICATE_THUMBPRINT") or None,
+            private_key=private_key or None,
+            client_secret=get_env("CLIENT_SECRET") or None,
+            data_access_contract_number=get_env("DATA_ACCESS_CONTRACT_NUMBER"),
+        )
+
+    @staticmethod
+    def _load_private_key(prefix: str = "FLUVIUS") -> str:
+        """Load the private key from environment variable or file.
+
+        Args:
+            prefix: Environment variable prefix.
+
+        Returns:
+            The private key in PEM format, or empty string if not found.
+        """
+        private_key = os.environ.get(f"{prefix}_PRIVATE_KEY")
+        private_key_path = os.environ.get(f"{prefix}_PRIVATE_KEY_PATH")
+
+        # Fall back to default prefix if using custom prefix
+        if not private_key and not private_key_path and prefix != "FLUVIUS":
+            private_key = os.environ.get("FLUVIUS_PRIVATE_KEY")
+            private_key_path = os.environ.get("FLUVIUS_PRIVATE_KEY_PATH")
+
+        if private_key:
+            return _decode_private_key(private_key)
+
+        if private_key_path:
+            path = Path(private_key_path)
+            if not path.exists():
+                raise ConfigurationError(
+                    f"Private key file not found: {private_key_path}"
+                )
+            try:
+                return path.read_text()
+            except OSError as e:
+                raise ConfigurationError(
+                    f"Failed to read private key file: {e}"
+                ) from e
+
+        return ""
+
+
+def _decode_private_key(key: str) -> str:
+    """Decode a private key that may be base64-encoded.
+
+    Args:
+        key: The private key, either in PEM format or base64-encoded.
+
+    Returns:
+        The private key in PEM format.
+    """
+    if key.startswith("-----BEGIN"):
+        return key
+
+    try:
+        cleaned = key.replace(" ", "").replace("\n", "").replace("\r", "").replace("\t", "")
+        decoded = base64.b64decode(cleaned, validate=True).decode("utf-8")
+        return decoded
+    except (ValueError, UnicodeDecodeError):
+        return key

fluvius_energy_api/exceptions.py

@@ -0,0 +1,104 @@
+"""Custom exceptions for the Fluvius Energy API."""
+
+from __future__ import annotations
+
+from typing import TYPE_CHECKING
+
+if TYPE_CHECKING:
+    from .models.base import ErrorResponse, ErrorValidationResponse
+
+
+class FluviusAPIError(Exception):
+    """Base exception for Fluvius API errors."""
+
+    def __init__(
+        self,
+        message: str,
+        status_code: int | None = None,
+        error_response: ErrorResponse | ErrorValidationResponse | None = None,
+    ) -> None:
+        super().__init__(message)
+        self.message = message
+        self.status_code = status_code
+        self.error_response = error_response
+
+    def __str__(self) -> str:
+        if self.status_code:
+            return f"[{self.status_code}] {self.message}"
+        return self.message
+
+
+class ConfigurationError(FluviusAPIError):
+    """Raised when credentials or configuration is missing or invalid."""
+
+    def __init__(self, message: str) -> None:
+        super().__init__(message)
+
+
+class AuthenticationError(FluviusAPIError):
+    """Raised when authentication fails (401 Unauthorized)."""
+
+    def __init__(
+        self,
+        message: str = "Authentication failed. Check your bearer token.",
+        error_response: ErrorResponse | ErrorValidationResponse | None = None,
+    ) -> None:
+        super().__init__(message, status_code=401, error_response=error_response)
+
+
+class ForbiddenError(FluviusAPIError):
+    """Raised when access is forbidden (403 Forbidden)."""
+
+    def __init__(
+        self,
+        message: str = "Access forbidden. You don't have permission to access this resource.",
+        error_response: ErrorResponse | ErrorValidationResponse | None = None,
+    ) -> None:
+        super().__init__(message, status_code=403, error_response=error_response)
+
+
+class NotFoundError(FluviusAPIError):
+    """Raised when a resource is not found (404 Not Found)."""
+
+    def __init__(
+        self,
+        message: str = "Resource not found.",
+        error_response: ErrorResponse | ErrorValidationResponse | None = None,
+    ) -> None:
+        super().__init__(message, status_code=404, error_response=error_response)
+
+
+class ValidationError(FluviusAPIError):
+    """Raised when request validation fails (400 Bad Request)."""
+
+    def __init__(
+        self,
+        message: str = "Request validation failed.",
+        error_response: ErrorValidationResponse | None = None,
+    ) -> None:
+        super().__init__(message, status_code=400, error_response=error_response)
+        self.validation_errors = (
+            error_response.validation_error_messages if error_response else None
+        )
+
+
+class ServerError(FluviusAPIError):
+    """Raised when a server error occurs (500 Internal Server Error)."""
+
+    def __init__(
+        self,
+        message: str = "Internal server error.",
+        error_response: ErrorResponse | ErrorValidationResponse | None = None,
+    ) -> None:
+        super().__init__(message, status_code=500, error_response=error_response)
+
+
+class ServiceUnavailableError(FluviusAPIError):
+    """Raised when the service is unavailable (503 Service Unavailable)."""
+
+    def __init__(
+        self,
+        message: str = "Service unavailable. Please try again later.",
+        error_response: ErrorResponse | ErrorValidationResponse | None = None,
+    ) -> None:
+        super().__init__(message, status_code=503, error_response=error_response)