Metadata-Version: 2.4
Name: energyid-webhooks
Version: 0.0.17
Summary: Light weight Python package to interface with EnergyID Webhooks
Author-email: Jan Pecinovsky <jan@energieid.be>, Oscar Swyns <oscar@energieid.be>
License-Expression: MIT
Project-URL: Homepage, https://github.com/EnergieID/energyid-webhooks-py
Project-URL: Bug Tracker, https://github.com/EnergieID/energyid-webhooks-py/issues
Classifier: Development Status :: 3 - Alpha
Classifier: Intended Audience :: Developers
Classifier: Intended Audience :: Science/Research
Classifier: Natural Language :: English
Classifier: Operating System :: OS Independent
Classifier: Programming Language :: Python :: 3
Classifier: Topic :: Scientific/Engineering
Classifier: Topic :: Scientific/Engineering :: Mathematics
Classifier: Topic :: Scientific/Engineering :: Physics
Classifier: Topic :: Software Development :: Libraries :: Python Modules
Classifier: Typing :: Typed
Requires-Python: >=3.11
Description-Content-Type: text/markdown
License-File: LICENSE
Requires-Dist: aiohttp>=3.11.12
Requires-Dist: backoff>=2.2.1
Requires-Dist: requests>=2.32.3
Dynamic: license-file

# energyid-webhooks

Python package for interfacing with EnergyID Webhooks (supports both V1 and V2 APIs)

## Installation

```bash
pip install energyid-webhooks
```

## Features

- **V2 API support** with device provisioning and claiming
- Authentication with automatic token renewal
- Smart sensor bundling for efficient data transmission
- Async support
- Full type hints

## Type Checking

This package is fully type-hinted and checked with strict mypy settings.

## V2 API Usage (Recommended)

The V2 API includes device provisioning, authentication, and smart bundling:

```python
import asyncio
from energyid_webhooks import WebhookClient

# Create the client
client = WebhookClient(
    provisioning_key="your_provisioning_key",
    provisioning_secret="your_provisioning_secret",
    device_id="unique_device_id",
    device_name="My Device",
    reauth_interval=24  # Hours between token refresh
)

async def main():
    # Authenticate with EnergyID
    is_claimed = await client.authenticate()

    if not is_claimed:
        # Device needs to be claimed
        claim_info = client.get_claim_info()
        print(f"Claim your device at {claim_info['claim_url']} with code {claim_info['claim_code']}")
        # Wait for claiming...
        return

    # Add and update sensors
    await client.update_sensor("el", 1250.5)  # Electricity consumption
    await client.update_sensor("pv", 3560.2)  # Solar production

    # Synchronize with EnergyID
    await client.synchronize_sensors()

    # Or enable automatic synchronization
    client.start_auto_sync(interval_seconds=300)  # Every 5 minutes

    # Don't forget to close when done
    await client.close()

asyncio.run(main())
```

### Refused credentials

`authenticate()` raises `EnergyIDAuthenticationError` when EnergyID refuses the provisioning key and secret (HTTP 401) or the linked record is closed (HTTP 403). The client also signs in again by itself (before its token expires, and after a directive request is rejected), so `send_data()`, `synchronize_sensors()`, `get_directives()` and `get_directive_data()` can raise it too. Ask the user for new credentials; retrying does not help. `start_auto_sync()` only logs errors, so call `synchronize_sensors()` yourself if you need to react to this one. The error subclasses `aiohttp.ClientResponseError`, so existing handlers keep working.

### Directives

A device whose record was granted directive access can read the directive schedules:

```python
import datetime as dt

directives = await client.get_directives()
for directive in directives:
    schedule = await client.get_directive_data(directive.id)
    state = schedule.state_at(dt.datetime.now(dt.UTC))
    print(directive.title, state.current, state.next_change, state.next_signal)
```

Each point in a schedule starts a slot that lasts one `interval`. Day and week slots (`P1D`, `P7D`) follow the local calendar: on the day the clocks change, a slot still runs until the next point when that point starts at the same local time. When the interval has no fixed length (`P1M`, `P1Y`), a slot lasts until the next point, and the last one never ends. `state_at()` returns the active point (`None` outside every slot), the next time the signal value changes, and the point that starts then (`None` when the change is to no signal: a gap or the end of the last slot). `signal_at()` returns only the active point. Both need a timezone-aware moment.

## V1 API Usage (Legacy)

The original API is still available for backward compatibility:

```python
from energyid_webhooks import WebhookClientV1, WebhookPayload

url = "https://app.energyid.eu/integrations/WebhookIn/..."

client = WebhookClientV1(url)

# Post some data to the webhook
data = {
    'remoteId': 'my-solar-inverter',
    'remoteName': 'My Solar Panels',
    'metric': 'solarPhotovoltaicProduction',
    'metricKind': 'total',
    'unit': 'kWh',
    'interval': 'P1D',
    'data': [['2022-10-05T08:00+0200', 0.004]]
}

client.post(data)
```

## V1 Async Usage (Legacy)

```python
import asyncio
from energyid_webhooks import WebhookClientAsyncV1

url = "https://app.energyid.eu/integrations/WebhookIn/..."

client = WebhookClientAsyncV1(url)

async def main():
    data = {
        'remoteId': 'my-solar-inverter',
        'remoteName': 'My Solar Panels',
        'metric': 'solarPhotovoltaicProduction',
        'metricKind': 'total',
        'unit': 'kWh',
        'interval': 'P1D',
        'data': [['2022-10-05T08:00+0200', 0.004]]
    }

    await client.post(data)

asyncio.run(main())
```

## Demos

See the [demos](demos/) folder for cURL, Python notebook, Node-RED, and Apache NiFi examples.

Node-RED examples include:

- [nodered_flow.json](demos/nodered_flow.json): generic incoming webhook flow.
- [nodered_mqtt_bridge_flow.json](demos/nodered_mqtt_bridge_flow.json): MQTT-to-EnergyID bridge flow with per-device claiming, buffering, and upload policy handling.

## Development

### Setup

```bash
python3 -m venv venv
source venv/bin/activate
pip install -r requirements.txt
```
