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

fluvius_energy_api-0.1.0.dist-info/METADATA

@@ -0,0 +1,311 @@
+Metadata-Version: 2.4
+Name: fluvius-energy-api
+Version: 0.1.0
+Summary: Python wrapper for the Fluvius Energy API
+Project-URL: Homepage, https://github.com/warreee/fluvius-energy-api
+Project-URL: Repository, https://github.com/warreee/fluvius-energy-api.git
+Project-URL: Issues, https://github.com/warreee/fluvius-energy-api/issues
+Author: Ward Schodts
+License-Expression: AGPL-3.0-or-later
+License-File: LICENSE
+Keywords: api,belgium,electricity,energy,esco,fluvius,gas,smart-meter
+Classifier: Development Status :: 4 - Beta
+Classifier: Intended Audience :: Developers
+Classifier: License :: OSI Approved :: GNU Affero General Public License v3 or later (AGPLv3+)
+Classifier: Operating System :: OS Independent
+Classifier: Programming Language :: Python :: 3
+Classifier: Programming Language :: Python :: 3.13
+Classifier: Topic :: Home Automation
+Classifier: Topic :: Software Development :: Libraries :: Python Modules
+Classifier: Typing :: Typed
+Requires-Python: >=3.13
+Requires-Dist: cryptography>=43.0.0
+Requires-Dist: httpx>=0.27.0
+Requires-Dist: pydantic>=2.0.0
+Requires-Dist: pyjwt>=2.8.0
+Description-Content-Type: text/markdown
+
+# Fluvius Energy API
+
+Python wrapper for the Fluvius Energy API v3 (ESCO - Energy Service Company API).
+
+## Installation
+
+```bash
+pip install fluvius-energy-api
+```
+
+Or with uv:
+
+```bash
+uv add fluvius-energy-api
+```
+
+## Configuration
+
+The client requires OAuth2 credentials for Azure AD authentication. Two authentication methods are supported:
+
+- **Certificate-based** (production): Uses certificate thumbprint + private key
+- **Client secret** (sandbox): Uses a simple client secret
+
+### Common Environment Variables
+
+These are shared between production and sandbox:
+
+| Variable | Description |
+|----------|-------------|
+| `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 (e.g., `api://dcfd07b1-f05e-4005-a6fb-7929be1bece4/.default`) |
+
+### Production (Certificate-based auth)
+
+| Variable | Description |
+|----------|-------------|
+| `FLUVIUS_CERTIFICATE_THUMBPRINT` | Certificate thumbprint (hex format) |
+| `FLUVIUS_PRIVATE_KEY` | RSA private key in PEM format |
+| `FLUVIUS_PRIVATE_KEY_PATH` | Alternative: path to private key file |
+
+### Sandbox (Client secret auth)
+
+| Variable | Description |
+|----------|-------------|
+| `FLUVIUS_SANDBOX_CLIENT_SECRET` | Client secret for sandbox |
+
+Note: For sandbox, common values (subscription_key, client_id, tenant_id, scope, data_access_contract_number) automatically fall back to `FLUVIUS_*` if not set with `FLUVIUS_SANDBOX_*` prefix.
+
+### Data Access Contract
+
+| Variable | Description |
+|----------|-------------|
+| `FLUVIUS_DATA_ACCESS_CONTRACT_NUMBER` | Data access contract number (required, typically constant per service provider) |
+
+### Private Key Formats
+
+The private key can be provided in three ways:
+1. **Inline PEM**: Set `FLUVIUS_PRIVATE_KEY` with the full PEM content
+2. **Base64-encoded**: Set `FLUVIUS_PRIVATE_KEY` with the PEM content encoded as base64
+3. **File path**: Set `FLUVIUS_PRIVATE_KEY_PATH` to point to a `.pem` file
+
+## Usage
+
+### Production (Certificate auth)
+
+```python
+from fluvius_energy_api import FluviusEnergyClient, Environment
+
+# Credentials loaded from FLUVIUS_* environment variables
+with FluviusEnergyClient(environment=Environment.PRODUCTION) as client:
+    response = client.get_mandates()
+    for mandate in response.data.mandates:
+        print(f"EAN: {mandate.ean}, Status: {mandate.status}")
+```
+
+### Sandbox (Client secret auth)
+
+```python
+from fluvius_energy_api import FluviusEnergyClient, FluviusCredentials, Environment
+
+# Load credentials - falls back to FLUVIUS_* for common values,
+# uses FLUVIUS_SANDBOX_CLIENT_SECRET for auth
+sandbox_credentials = FluviusCredentials.from_env(prefix="FLUVIUS_SANDBOX")
+
+with FluviusEnergyClient(credentials=sandbox_credentials, environment=Environment.SANDBOX) as client:
+    response = client.get_mandates()
+    print(f"Found {len(response.data.mandates)} mandates in sandbox")
+```
+
+### Explicit Credentials
+
+```python
+from fluvius_energy_api import FluviusEnergyClient, FluviusCredentials, Environment
+
+# Production with certificate
+prod_credentials = FluviusCredentials(
+    subscription_key="your-subscription-key",
+    client_id="your-client-id",
+    tenant_id="your-tenant-id",
+    scope="api://your-scope/.default",
+    certificate_thumbprint="YOUR_CERTIFICATE_THUMBPRINT",
+    private_key="-----BEGIN RSA PRIVATE KEY-----\n...\n-----END RSA PRIVATE KEY-----",
+)
+
+# Sandbox with client secret
+sandbox_credentials = FluviusCredentials(
+    subscription_key="your-subscription-key",
+    client_id="your-client-id",
+    tenant_id="your-tenant-id",
+    scope="api://your-scope/.default",
+    client_secret="your-client-secret",
+)
+
+with FluviusEnergyClient(credentials=prod_credentials, environment=Environment.PRODUCTION) as client:
+    mandates = client.get_mandates()
+```
+
+### Create Client Session
+
+Create a session for end-users to grant data access:
+
+```python
+from fluvius_energy_api import (
+    FluviusEnergyClient,
+    ClientSessionDataService,
+    DataServiceType,
+    Environment,
+)
+
+with FluviusEnergyClient(environment=Environment.PRODUCTION) as client:
+    response = client.create_client_session(
+        data_access_contract_number="3599900040",
+        reference_number="my-unique-reference",
+        flow="B2B",
+        data_services=[
+            ClientSessionDataService(
+                data_service_type=DataServiceType.VH_DAG,
+                data_period_from="2024-01-01T00:00:00Z",
+            ),
+            ClientSessionDataService(
+                data_service_type=DataServiceType.VH_KWARTIER_UUR,
+                data_period_from="2024-01-01T00:00:00Z",
+            ),
+        ],
+        number_of_eans=5,
+    )
+
+    if response.data.status == "success":
+        # Build the consent URL for end-users
+        consent_url = f"https://mijn.fluvius.be/verbruik/dienstverlener?id={response.data.short_url_identifier}"
+        print(f"Consent URL: {consent_url}")
+        print(f"Valid until: {response.data.valid_to}")
+```
+
+### Get Mandates
+
+Retrieve mandates with optional filters:
+
+```python
+from fluvius_energy_api import (
+    FluviusEnergyClient,
+    EnergyType,
+    MandateStatus,
+    DataServiceType,
+    Environment,
+)
+
+with FluviusEnergyClient(environment=Environment.PRODUCTION) as client:
+    # Get all mandates
+    response = client.get_mandates()
+
+    # Get mandates with filters
+    response = client.get_mandates(
+        ean="541448800000004312",
+        energy_type=EnergyType.ELECTRICITY,
+        status=MandateStatus.APPROVED,
+        data_service_types=[DataServiceType.VH_DAG, DataServiceType.VH_KWARTIER_UUR],
+    )
+
+    for mandate in response.data.mandates:
+        print(f"EAN: {mandate.ean}")
+        print(f"Status: {mandate.status}")
+        print(f"Energy type: {mandate.energy_type}")
+        print(f"Data service: {mandate.data_service_type}")
+```
+
+### Get Energy Data
+
+Retrieve energy consumption/production data:
+
+```python
+from datetime import datetime
+from fluvius_energy_api import FluviusEnergyClient, PeriodType, Environment
+
+with FluviusEnergyClient(environment=Environment.PRODUCTION) as client:
+    response = client.get_energy(
+        ean="541448800000004312",
+        period_type=PeriodType.READ_TIME,
+        granularity="daily",
+        from_date=datetime(2024, 1, 1),
+        to_date=datetime(2024, 6, 1),
+    )
+
+    headpoint = response.data.headpoint
+    print(f"EAN: {headpoint.ean}")
+    print(f"Energy type: {headpoint.energy_type}")
+```
+
+## Environments
+
+The client supports two environments:
+
+| Environment | Base URL | Auth Method |
+|-------------|----------|-------------|
+| `Environment.PRODUCTION` | `https://apihub.fluvius.be/esco-live/v3` | Certificate |
+| `Environment.SANDBOX` | `https://apihub.fluvius.be/esco-sbx/v3` | Client secret |
+
+```python
+from fluvius_energy_api import FluviusEnergyClient, Environment
+
+# Production
+client = FluviusEnergyClient(environment=Environment.PRODUCTION)
+
+# Sandbox
+client = FluviusEnergyClient(environment=Environment.SANDBOX)
+```
+
+## Error Handling
+
+The client raises specific exceptions for different error scenarios:
+
+```python
+from fluvius_energy_api import (
+    FluviusEnergyClient,
+    FluviusAPIError,
+    AuthenticationError,
+    ForbiddenError,
+    NotFoundError,
+    ValidationError,
+    ServerError,
+    ServiceUnavailableError,
+    ConfigurationError,
+    Environment,
+)
+
+try:
+    with FluviusEnergyClient(environment=Environment.PRODUCTION) as client:
+        response = client.get_mandates()
+except ConfigurationError as e:
+    print(f"Configuration error: {e}")
+except AuthenticationError as e:
+    print(f"Authentication failed: {e}")
+except ForbiddenError as e:
+    print(f"Access forbidden: {e}")
+except NotFoundError as e:
+    print(f"Resource not found: {e}")
+except ValidationError as e:
+    print(f"Validation error: {e}")
+    if e.validation_errors:
+        for error in e.validation_errors:
+            print(f"  - {error}")
+except ServerError as e:
+    print(f"Server error: {e}")
+except ServiceUnavailableError as e:
+    print(f"Service unavailable: {e}")
+except FluviusAPIError as e:
+    print(f"API error: {e}")
+```
+
+## Data Service Types
+
+Available data service types:
+
+| Type | Description |
+|------|-------------|
+| `VH_DAG` | Daily consumption history |
+| `VH_KWARTIER_UUR` | Quarter-hourly/hourly consumption history |
+| `VH_ONBEPAALD` | Indefinite consumption history |
+| `IG` | Installation data |
+## License
+
+GNU AFFERO GENERAL PUBLIC LICENSE

fluvius_energy_api-0.1.0.dist-info/RECORD

@@ -0,0 +1,18 @@
+fluvius_energy_api/__init__.py,sha256=r9YmMlNy1FhWyd0HGR-iDanalwLTmGyXWHCFe-KcSgI,3459
+fluvius_energy_api/_http.py,sha256=yt82D8aBKwpQBchScvFaPQvOPv8BVJN0Mgnvz6ROMDE,4331
+fluvius_energy_api/auth.py,sha256=w9MKugj-xkSuBD37fCObx7FTT0CycM7ITHBaB4xsLgE,7667
+fluvius_energy_api/client.py,sha256=E_yku_t3oQn-YgsQt0afKt5Lj3dCqgg5p9k4yi9FTGQ,12610
+fluvius_energy_api/credentials.py,sha256=Z6Cy7WQxQJYRmpRlIsCS-cRfzEEvXk4F-RBmlup76PY,7746
+fluvius_energy_api/exceptions.py,sha256=Z6Sb95eouiFl6Sc7YGcBuEH-apB4urVhfh26BgcAVQk,3387
+fluvius_energy_api/py.typed,sha256=47DEQpj8HBSa-_TImW-5JCeuQeRkm5NMpJWZG3hSuFU,0
+fluvius_energy_api/models/__init__.py,sha256=20d6_vhmeNl_A4YC1afUYbpiwBB2oKbo7UFG8fHal3g,2917
+fluvius_energy_api/models/base.py,sha256=n-bgJmbc7DhP7KLlUYDHjmvRg7GyLtFYGvz3_Cb3ZI4,1009
+fluvius_energy_api/models/energy.py,sha256=Cl4D0mazS3DRqsb6wKTGIAN7f5ye_cAYaFnFf8pA7BA,6612
+fluvius_energy_api/models/enums.py,sha256=Z2dDoi5Ac2uM1-nWkNqGTlfxCfOPxJrPIb-H0MLBM10,2891
+fluvius_energy_api/models/installation.py,sha256=Akyz9IT6Z3ZB-wQpn-ZxSx82j7MMm6hVgEQgtDBtOUw,2274
+fluvius_energy_api/models/mandate.py,sha256=Pd7Ju1XsppuGzudmeh9hguRWF-zwYR8nH3jY5NFGs-I,2578
+fluvius_energy_api/models/session.py,sha256=wipa5U24zj9WTbxyKsgDHLqTC8tC3Twok1IdUMGt1WE,1922
+fluvius_energy_api-0.1.0.dist-info/METADATA,sha256=uI-P5cJ2sbMh3gMQCh-yVIkJ_WzmABiklRvem3lGgMM,9646
+fluvius_energy_api-0.1.0.dist-info/WHEEL,sha256=WLgqFyCfm_KASv4WHyYy0P3pM_m7J5L9k2skdKLirC8,87
+fluvius_energy_api-0.1.0.dist-info/licenses/LICENSE,sha256=hIahDEOTzuHCU5J2nd07LWwkLW7Hko4UFO__ffsvB-8,34523
+fluvius_energy_api-0.1.0.dist-info/RECORD,,

fluvius_energy_api-0.1.0.dist-info/WHEEL

@@ -0,0 +1,4 @@
+Wheel-Version: 1.0
+Generator: hatchling 1.28.0
+Root-Is-Purelib: true
+Tag: py3-none-any