pyzonneplan 0.1.0__py3-none-any.whl

pyzonneplan/__init__.py

@@ -0,0 +1,79 @@
+"""Asynchronous Python client for the Zonneplan API."""
+
+from .auth import OtpChallenge, Token, generate_pkce_pair
+from .exceptions import (
+    ZonneplanAuthenticationError,
+    ZonneplanConnectionError,
+    ZonneplanError,
+    ZonneplanInvalidOtpError,
+    ZonneplanTimeoutError,
+)
+from .models import (
+    Account,
+    Address,
+    AddressGroup,
+    Battery,
+    BatteryChart,
+    BatteryControlMode,
+    BatteryHomeOptimization,
+    ChargePoint,
+    ChargePointSession,
+    ChargeSchedule,
+    Connection,
+    ConsumerPrices,
+    Contract,
+    DynamicChargingConstraints,
+    ElectricityDelivered,
+    ElectricityMeasurementGroup,
+    Gas,
+    GasMeasurementGroup,
+    Money,
+    PriceChartData,
+    PricePoint,
+    PriceRange,
+    PriceSeries,
+    PvInverter,
+    PvTotals,
+    SustainabilityScore,
+    UserAccount,
+)
+from .pyzonneplan import Zonneplan
+
+__all__ = [
+    "Account",
+    "Address",
+    "AddressGroup",
+    "Battery",
+    "BatteryChart",
+    "BatteryControlMode",
+    "BatteryHomeOptimization",
+    "ChargePoint",
+    "ChargePointSession",
+    "ChargeSchedule",
+    "Connection",
+    "ConsumerPrices",
+    "Contract",
+    "DynamicChargingConstraints",
+    "ElectricityDelivered",
+    "ElectricityMeasurementGroup",
+    "Gas",
+    "GasMeasurementGroup",
+    "Money",
+    "OtpChallenge",
+    "PriceChartData",
+    "PricePoint",
+    "PriceRange",
+    "PriceSeries",
+    "PvInverter",
+    "PvTotals",
+    "SustainabilityScore",
+    "Token",
+    "UserAccount",
+    "Zonneplan",
+    "ZonneplanAuthenticationError",
+    "ZonneplanConnectionError",
+    "ZonneplanError",
+    "ZonneplanInvalidOtpError",
+    "ZonneplanTimeoutError",
+    "generate_pkce_pair",
+]

pyzonneplan/auth.py

@@ -0,0 +1,85 @@
+"""Authentication value objects for the Zonneplan API.
+
+The actual login and refresh calls live on :class:`pyzonneplan.Zonneplan`, so
+they share its request handling (retries, timeouts, error mapping). This
+module only holds the data carried through that flow:
+
+1. POST /oauth/authorize-challenge  {response_type, email, code_challenge, ...}
+   -> HTTP 403 with ``otp_required: true`` and an ``auth_session``.
+      The 403 is the success path, not an error.
+2. POST /oauth/authorize-challenge  {auth_session, otp}
+   -> ``authorization_code``
+3. POST /oauth/token  {grant_type: authorization_code, code, code_verifier}
+   -> access + refresh token
+"""
+
+import base64
+import hashlib
+import secrets
+from dataclasses import dataclass
+from datetime import UTC, datetime, timedelta
+from typing import Any, Self
+
+# Refresh a little before the token actually expires.
+_EXPIRY_MARGIN = timedelta(seconds=60)
+
+
+def generate_pkce_pair() -> tuple[str, str]:
+    """Return a fresh ``(code_verifier, code_challenge)`` pair."""
+    verifier = secrets.token_urlsafe(96)[:128]
+    digest = hashlib.sha256(verifier.encode("ascii")).digest()
+    challenge = base64.urlsafe_b64encode(digest).rstrip(b"=").decode("ascii")
+    return verifier, challenge
+
+
+@dataclass(slots=True)
+class OtpChallenge:
+    """State carried between requesting and submitting the one-time password."""
+
+    auth_session: str
+    code_verifier: str
+    email: str
+
+
+@dataclass(slots=True)
+class Token:
+    """An access token and its refresh token."""
+
+    access_token: str
+    refresh_token: str
+    expires_at: datetime
+    token_type: str = "Bearer"  # noqa: S105 (a token type label, not a credential)
+
+    @property
+    def is_expired(self) -> bool:
+        """Return whether the access token needs refreshing."""
+        return datetime.now(UTC) >= self.expires_at - _EXPIRY_MARGIN
+
+    @classmethod
+    def from_response(cls, payload: dict[str, Any]) -> Self:
+        """Build a token from an /oauth/token response body."""
+        return cls(
+            access_token=payload["access_token"],
+            refresh_token=payload["refresh_token"],
+            expires_at=datetime.now(UTC) + timedelta(seconds=int(payload["expires_in"])),
+            token_type=payload.get("token_type", "Bearer"),
+        )
+
+    def as_dict(self) -> dict[str, Any]:
+        """Serialise for storage in a Home Assistant config entry."""
+        return {
+            "access_token": self.access_token,
+            "refresh_token": self.refresh_token,
+            "expires_at": self.expires_at.isoformat(),
+            "token_type": self.token_type,
+        }
+
+    @classmethod
+    def from_dict(cls, data: dict[str, Any]) -> Self:
+        """Restore a token previously stored with :meth:`as_dict`."""
+        return cls(
+            access_token=data["access_token"],
+            refresh_token=data["refresh_token"],
+            expires_at=datetime.fromisoformat(data["expires_at"]),
+            token_type=data.get("token_type", "Bearer"),
+        )

pyzonneplan/const.py

@@ -0,0 +1,46 @@
+"""Constants for the Zonneplan API client."""
+
+from decimal import Decimal
+from typing import Final
+
+API_SCHEME: Final = "https"
+API_URL: Final = "app-api.zonneplan.nl"
+
+AUTHORIZE_CHALLENGE_PATH: Final = "oauth/authorize-challenge"
+TOKEN_PATH: Final = "oauth/token"  # noqa: S105 (a URL path, not a credential)
+
+# Sent by the mobile app; the API rejects requests without them.
+APP_VERSION: Final = "5.10.1"
+APP_ENVIRONMENT: Final = "production"
+
+# Every monetary "amount" in the API is expressed in 1e-7 EUR.
+MONEY_FACTOR: Final = Decimal("0.0000001")
+
+# Energy values are Wh, power values are W.
+WH_TO_KWH: Final = Decimal("0.001")
+
+
+class ChartInterval:
+    """Supported battery chart intervals."""
+
+    DAYS: Final = "days"
+    MONTHS: Final = "months"
+
+
+class PriceChart:
+    """Supported consumer price charts."""
+
+    ELECTRICITY_HOURLY: Final = "electricity-hourly"
+    ELECTRICITY_QUARTER_HOURLY: Final = "electricity-quarter-hourly"
+    GAS_DAILY: Final = "gas-daily"
+
+
+class ContractType:
+    """Contract types returned by /user-accounts/me."""
+
+    ELECTRICITY: Final = "electricity"
+    GAS: Final = "gas"
+    PV_INSTALLATION: Final = "pv_installation"
+    P1_INSTALLATION: Final = "p1_installation"
+    CHARGE_POINT: Final = "charge_point_installation"
+    HOME_BATTERY: Final = "home_battery_installation"

pyzonneplan/exceptions.py

@@ -0,0 +1,21 @@
+"""Asynchronous Python client for Zonneplan."""
+
+
+class ZonneplanError(Exception):
+    """Generic exception for Zonneplan errors."""
+
+
+class ZonneplanConnectionError(ZonneplanError):
+    """Exception raised for connection errors."""
+
+
+class ZonneplanTimeoutError(ZonneplanError):
+    """Exception raised for timeout errors."""
+
+
+class ZonneplanAuthenticationError(ZonneplanError):
+    """Exception raised for authentication errors."""
+
+
+class ZonneplanInvalidOtpError(ZonneplanAuthenticationError):
+    """Exception raised when the submitted one-time password is rejected."""

pyzonneplan/models/__init__.py

@@ -0,0 +1,47 @@
+"""Typed models for the Zonneplan API."""
+
+from .account import Account, Address, AddressGroup, Connection, Contract, UserAccount
+from .consumption import ElectricityDelivered, ElectricityMeasurementGroup, Gas, GasMeasurementGroup
+from .devices import (
+    Battery,
+    BatteryChart,
+    BatteryControlMode,
+    BatteryHomeOptimization,
+    ChargePoint,
+    ChargePointSession,
+    ChargeSchedule,
+    DynamicChargingConstraints,
+    PvInverter,
+    PvTotals,
+)
+from .prices import ConsumerPrices, Money, PriceChartData, PricePoint, PriceRange, PriceSeries, SustainabilityScore
+
+__all__ = [
+    "Account",
+    "Address",
+    "AddressGroup",
+    "Battery",
+    "BatteryChart",
+    "BatteryControlMode",
+    "BatteryHomeOptimization",
+    "ChargePoint",
+    "ChargePointSession",
+    "ChargeSchedule",
+    "Connection",
+    "ConsumerPrices",
+    "Contract",
+    "DynamicChargingConstraints",
+    "ElectricityDelivered",
+    "ElectricityMeasurementGroup",
+    "Gas",
+    "GasMeasurementGroup",
+    "Money",
+    "PriceChartData",
+    "PricePoint",
+    "PriceRange",
+    "PriceSeries",
+    "PvInverter",
+    "PvTotals",
+    "SustainabilityScore",
+    "UserAccount",
+]

pyzonneplan/models/account.py

@@ -0,0 +1,130 @@
+"""Models for /user-accounts/me."""
+
+from dataclasses import dataclass, field
+from datetime import datetime
+from typing import Any
+
+from mashumaro.mixins.orjson import DataClassORJSONMixin
+
+from pyzonneplan.const import ContractType
+
+
+@dataclass
+class Contract(DataClassORJSONMixin):
+    """A single product on a connection (PV, P1, battery, charge point, ...)."""
+
+    uuid: str
+    type: str
+    label: str | None = None
+    start_date: datetime | None = None
+    end_date: datetime | None = None
+    meta: dict[str, Any] = field(default_factory=dict)
+
+    @property
+    def is_active(self) -> bool:
+        """Return whether the contract has not ended yet."""
+        return self.end_date is None or self.end_date > datetime.now(self.end_date.tzinfo)
+
+    @property
+    def model_name(self) -> str | None:
+        """Return the hardware model, where the API exposes one."""
+        return self.meta.get("host_device_model_name") or self.meta.get("charge_point_model_name")
+
+    @property
+    def serial_number(self) -> str | None:
+        """Return the hardware serial, where the API exposes one."""
+        return self.meta.get("serial_number") or self.meta.get("identifier")
+
+
+@dataclass
+class Connection(DataClassORJSONMixin):
+    """A grid connection and the contracts attached to it."""
+
+    uuid: str
+    ean: str | None = None
+    market_segment: str | None = None
+    contracts: list[Contract] = field(default_factory=list)
+    features: list[dict[str, Any]] = field(default_factory=list)
+
+    def contracts_of_type(self, contract_type: str, *, active_only: bool = True) -> list[Contract]:
+        """Return the contracts of a given type."""
+        return [contract for contract in self.contracts if contract.type == contract_type and (not active_only or contract.is_active)]
+
+    def has(self, contract_type: str) -> bool:
+        """Return whether an active contract of this type exists."""
+        return bool(self.contracts_of_type(contract_type))
+
+    @property
+    def has_pv(self) -> bool:
+        """Return whether a solar installation is present."""
+        return self.has(ContractType.PV_INSTALLATION)
+
+    @property
+    def has_p1(self) -> bool:
+        """Return whether a P1 reader is present."""
+        return self.has(ContractType.P1_INSTALLATION)
+
+    @property
+    def has_battery(self) -> bool:
+        """Return whether a home battery is present."""
+        return self.has(ContractType.HOME_BATTERY)
+
+    @property
+    def has_charge_point(self) -> bool:
+        """Return whether a charge point is present."""
+        return self.has(ContractType.CHARGE_POINT)
+
+    @property
+    def has_gas_meter(self) -> bool:
+        """Return whether any P1 contract has recently reported gas."""
+        return any(contract.meta.get("gas_last_measured_at") for contract in self.contracts_of_type(ContractType.P1_INSTALLATION))
+
+
+@dataclass
+class Address(DataClassORJSONMixin):
+    """Postal address of an address group."""
+
+    id: str | None = None
+    street: str | None = None
+    number: str | None = None
+    addition: str | None = None
+    zipcode: str | None = None
+    city: str | None = None
+    sunrise: datetime | None = None
+    sunset: datetime | None = None
+
+
+@dataclass
+class AddressGroup(DataClassORJSONMixin):
+    """One address, with one or more connections."""
+
+    uuid: str
+    connections: list[Connection] = field(default_factory=list)
+    address: Address | None = None
+    is_representative: bool = False
+    organization_uuid: str | None = None
+
+
+@dataclass
+class UserAccount(DataClassORJSONMixin):
+    """The authenticated Zonneplan account."""
+
+    uuid: str
+    email: str | None = None
+    first_name: str | None = None
+    full_name: str | None = None
+    initials: str | None = None
+    is_representative: bool = False
+
+
+@dataclass
+class Account(DataClassORJSONMixin):
+    """Top level response of /user-accounts/me."""
+
+    user_account: UserAccount
+    address_groups: list[AddressGroup] = field(default_factory=list)
+
+    @property
+    def connections(self) -> list[Connection]:
+        """Return every connection across every address group."""
+        return [connection for address_group in self.address_groups for connection in address_group.connections]

pyzonneplan/models/consumption.py

@@ -0,0 +1,64 @@
+"""Models for the P1 electricity and gas consumption endpoints.
+
+Shape reverse-engineered from the dotted sensor key-paths (e.g.
+``measurement_groups.0.totals.d``) in fsaris/home-assistant-zonneplan-one's
+``const.py``, which reads these against the live API. No raw response has
+been captured yet, so the exact set of ``meta`` keys is not confirmed.
+"""
+
+from dataclasses import dataclass, field
+from decimal import Decimal
+from typing import Any
+
+from mashumaro.mixins.orjson import DataClassORJSONMixin
+
+from pyzonneplan.const import WH_TO_KWH
+
+
+@dataclass
+class ElectricityMeasurementGroup(DataClassORJSONMixin):
+    """One measurement window (today / this month / this year) of electricity-delivered."""
+
+    date: str | None = None
+    totals: dict[str, int] = field(default_factory=dict)
+    meta: dict[str, Any] = field(default_factory=dict)
+
+    @property
+    def delivered_kwh(self) -> Decimal | None:
+        """Return electricity consumed from the grid, in kWh."""
+        value = self.totals.get("d")
+        return None if value is None else Decimal(value) * WH_TO_KWH
+
+    @property
+    def returned_kwh(self) -> Decimal | None:
+        """Return electricity returned to the grid, in kWh."""
+        value = self.totals.get("p")
+        return None if value is None else Decimal(value) * WH_TO_KWH
+
+
+@dataclass
+class ElectricityDelivered(DataClassORJSONMixin):
+    """Response of /connections/{uuid}/electricity-delivered."""
+
+    measurement_groups: list[ElectricityMeasurementGroup] = field(default_factory=list)
+
+
+@dataclass
+class GasMeasurementGroup(DataClassORJSONMixin):
+    """One measurement window (today / this month / this year) of gas consumption."""
+
+    date: str | None = None
+    total: int | None = None
+    meta: dict[str, Any] = field(default_factory=dict)
+
+    @property
+    def total_m3(self) -> Decimal | None:
+        """Return gas consumed, in cubic meters."""
+        return None if self.total is None else Decimal(self.total) * WH_TO_KWH
+
+
+@dataclass
+class Gas(DataClassORJSONMixin):
+    """Response of /connections/{uuid}/gas."""
+
+    measurement_groups: list[GasMeasurementGroup] = field(default_factory=list)

pyzonneplan/models/devices.py

@@ -0,0 +1,224 @@
+"""Models for the PV, battery and charge point endpoints."""
+
+from dataclasses import dataclass, field
+from datetime import datetime
+from decimal import Decimal
+from typing import Any
+
+from mashumaro.mixins.orjson import DataClassORJSONMixin
+
+from pyzonneplan.const import MONEY_FACTOR, WH_TO_KWH
+
+from .account import Contract
+
+
+def _euro(value: int | None) -> Decimal | None:
+    """Convert a 1e-7 EUR amount to euro."""
+    return None if value is None else Decimal(value) * MONEY_FACTOR
+
+
+@dataclass(slots=True)
+class PvInverter:
+    """Typed view on a pv_installation contract's meta block."""
+
+    contract: Contract
+
+    @property
+    def uuid(self) -> str:
+        """Return the installation UUID."""
+        return self.contract.uuid
+
+    @property
+    def model_name(self) -> str | None:
+        """Return the inverter model."""
+        return self.contract.meta.get("inverter_model_name")
+
+    @property
+    def inverter_firmware_version(self) -> str | None:
+        """Return the inverter firmware version."""
+        return self.contract.meta.get("inverter_firmware_version")
+
+    @property
+    def module_firmware_version(self) -> str | None:
+        """Return the module firmware version."""
+        return self.contract.meta.get("module_firmware_version")
+
+    @property
+    def installation_wp(self) -> int | None:
+        """Return the total installed peak power."""
+        return self.contract.meta.get("installation_wp")
+
+    @property
+    def panel_wp(self) -> int | None:
+        """Return the peak power per panel."""
+        return self.contract.meta.get("panel_wp")
+
+    @property
+    def panel_count(self) -> int | None:
+        """Return the number of panels."""
+        return self.contract.meta.get("panel_count")
+
+    @property
+    def last_measured_power(self) -> int | None:
+        """Return the last measured production, in W."""
+        return self.contract.meta.get("last_measured_power_value")
+
+    @property
+    def total_power_measured(self) -> int | None:
+        """Return lifetime production, in Wh."""
+        return self.contract.meta.get("total_power_measured")
+
+    @property
+    def total_earned(self) -> Decimal | None:
+        """Return lifetime earnings."""
+        return _euro(self.contract.meta.get("total_earned"))
+
+    @property
+    def total_day(self) -> Decimal | None:
+        """Return today's earnings."""
+        return _euro(self.contract.meta.get("total_day"))
+
+
+@dataclass
+class PvTotals(DataClassORJSONMixin):
+    """Response of /connections/{uuid}/pv-installation."""
+
+    total_today: int | None = None
+
+    @property
+    def yield_today_kwh(self) -> Decimal | None:
+        """Return combined yield today across all inverters, in kWh."""
+        return None if self.total_today is None else Decimal(self.total_today) * WH_TO_KWH
+
+
+@dataclass
+class Battery(DataClassORJSONMixin):
+    """Response of /connections/{uuid}/home-battery-installation/{uuid}."""
+
+    battery_state: str | None = None
+    inverter_state: str | None = None
+    state_of_charge: int | None = None
+    power_ac: int | None = None
+    cycle_count: int | None = None
+    backup_power_usable_capacity_wh: int | None = None
+    first_measured_at: datetime | None = None
+    last_measured_at: datetime | None = None
+    total_earned: int | None = None
+    total_day: int | None = None
+    average_day: int | None = None
+    delivery_day: int | None = None
+    production_day: int | None = None
+    dynamic_charging_enabled: bool | None = None
+    dynamic_load_balancing_enabled: bool | None = None
+    dynamic_load_balancing_overload_active: bool | None = None
+    manual_control_enabled: bool | None = None
+    self_consumption_enabled: bool | None = None
+    home_optimization_enabled: bool | None = None
+    home_optimization_active: bool | None = None
+    grid_congestion_active: bool | None = None
+    backup_power_active: bool | None = None
+
+    @property
+    def earned_total(self) -> Decimal | None:
+        """Return lifetime trading result."""
+        return _euro(self.total_earned)
+
+    @property
+    def earned_today(self) -> Decimal | None:
+        """Return today's trading result."""
+        return _euro(self.total_day)
+
+    @property
+    def is_charging(self) -> bool | None:
+        """Return whether the battery is currently charging."""
+        return None if self.power_ac is None else self.power_ac > 0
+
+
+@dataclass
+class BatteryControlMode(DataClassORJSONMixin):
+    """Response of /api/contracts/{uuid}/home-battery/control-mode."""
+
+    control_mode: str | None = None
+
+
+@dataclass
+class BatteryHomeOptimization(DataClassORJSONMixin):
+    """Response of the home_optimization control-mode endpoint."""
+
+    max_desired_charge_power_watts: int | None = None
+    max_desired_discharge_power_watts: int | None = None
+
+
+@dataclass
+class ChargeSchedule(DataClassORJSONMixin):
+    """A single planned charging window."""
+
+    start_time: datetime | None = None
+    end_time: datetime | None = None
+
+
+@dataclass
+class DynamicChargingConstraints(DataClassORJSONMixin):
+    """User constraints for a dynamic charging session."""
+
+    desired_distance_in_kilometers: int | None = None
+    desired_additional_battery_percentage: int | None = None
+    desired_end_time: datetime | None = None
+
+
+@dataclass
+class ChargePointSession(DataClassORJSONMixin):
+    """The currently running or last charging session."""
+
+    start_time: datetime | None = None
+    charged_distance_in_kilometers: int | None = None
+
+
+@dataclass
+class ChargePoint(DataClassORJSONMixin):
+    """Response of /connections/{uuid}/charge-points/{uuid}."""
+
+    state: str | None = None
+    start_mode: str | None = None
+    power_actual: int | None = None
+    energy_delivered_session: int | None = None
+    session_charging_cost_total: int | None = None
+    charging_cost_total: int | None = None
+    session_flex_result: int | None = None
+    session_average_cost_in_cents: int | None = None
+    dynamic_load_balancing_health: str | None = None
+    selected_vehicle: str | None = None
+    connectivity_state: bool | None = None
+    can_charge: bool | None = None
+    can_schedule: bool | None = None
+    charging_manually: bool | None = None
+    charging_automatically: bool | None = None
+    plug_and_charge: bool | None = None
+    overload_protection_active: bool | None = None
+    dynamic_charging_enabled: bool | None = None
+    charge_on_solar_enabled: bool | None = None
+    dynamic_charging_flex_enabled: bool | None = None
+    dynamic_charging_flex_suppressed: bool | None = None
+    charge_schedules: list[ChargeSchedule] = field(default_factory=list)
+    charge_point_session: ChargePointSession | None = None
+    dynamic_charging_user_constraints: DynamicChargingConstraints | None = None
+
+    @property
+    def session_cost(self) -> Decimal | None:
+        """Return the cost of the running session."""
+        return _euro(self.session_charging_cost_total)
+
+    @property
+    def next_schedule(self) -> ChargeSchedule | None:
+        """Return the next planned charging window."""
+        return self.charge_schedules[0] if self.charge_schedules else None
+
+
+@dataclass
+class BatteryChart(DataClassORJSONMixin):
+    """Response of the battery chart endpoints.
+
+    Shape still needs a captured payload; the raw body is kept meanwhile.
+    """
+
+    raw: dict[str, Any] = field(default_factory=dict)

pyzonneplan/models/prices.py

@@ -0,0 +1,84 @@
+"""Models for the consumer price chart endpoint."""
+
+from dataclasses import dataclass, field
+from datetime import datetime
+from decimal import Decimal
+
+from mashumaro.mixins.orjson import DataClassORJSONMixin
+
+from pyzonneplan.const import MONEY_FACTOR
+
+
+@dataclass
+class Money(DataClassORJSONMixin):
+    """A monetary amount, expressed in the API's 1e-7 EUR unit."""
+
+    amount: int
+
+    @property
+    def euro(self) -> Decimal:
+        """Return the amount converted to euro."""
+        return Decimal(self.amount) * MONEY_FACTOR
+
+
+@dataclass
+class SustainabilityScore(DataClassORJSONMixin):
+    """How sustainable the energy is during a price interval, in permille."""
+
+    permille: int
+
+    @property
+    def fraction(self) -> Decimal:
+        """Return the score as a fraction between 0 and 1."""
+        return Decimal(self.permille) / 1000
+
+
+@dataclass
+class PricePoint(DataClassORJSONMixin):
+    """A single price interval within a chart.
+
+    ``tariff_group`` is only present on the hourly electricity chart, not on
+    the quarter-hourly one.
+    """
+
+    start_date: datetime
+    end_date: datetime
+    price_tax_included: Money
+    price_tax_excluded: Money
+    sustainability_score: SustainabilityScore | None = None
+    tariff_group: str | None = None
+
+
+@dataclass
+class PriceRange(DataClassORJSONMixin):
+    """The date range a chart covers."""
+
+    start_date: datetime
+    end_date: datetime
+
+
+@dataclass
+class PriceSeries(DataClassORJSONMixin):
+    """The list of price points making up a chart."""
+
+    prices: list[PricePoint] = field(default_factory=list)
+
+
+@dataclass
+class PriceChartData(DataClassORJSONMixin):
+    """The ``chart`` object of a consumer price chart response."""
+
+    range: PriceRange
+    series: PriceSeries
+
+
+@dataclass
+class ConsumerPrices(DataClassORJSONMixin):
+    """Response of /api/consumer-prices/charts/{chart_name}."""
+
+    chart: PriceChartData
+
+    @property
+    def prices(self) -> list[PricePoint]:
+        """Return the price points, flattened out of the nested chart/series structure."""
+        return self.chart.series.prices

pyzonneplan/pyzonneplan.py

@@ -0,0 +1,312 @@
+"""Asynchronous Python client for the Zonneplan API."""
+
+from __future__ import annotations
+
+import asyncio
+import socket
+from dataclasses import dataclass
+from http import HTTPStatus
+from importlib import metadata
+from typing import Any, NoReturn, Self
+
+import orjson
+from aiohttp import ClientError, ClientResponseError, ClientSession
+from aiohttp.hdrs import METH_GET, METH_POST
+from tenacity import AsyncRetrying, retry_if_exception_type, stop_after_attempt, wait_exponential
+from yarl import URL
+
+from pyzonneplan.auth import OtpChallenge, Token, generate_pkce_pair
+from pyzonneplan.const import (
+    API_SCHEME,
+    API_URL,
+    APP_ENVIRONMENT,
+    APP_VERSION,
+    AUTHORIZE_CHALLENGE_PATH,
+    TOKEN_PATH,
+    PriceChart,
+)
+from pyzonneplan.exceptions import (
+    ZonneplanAuthenticationError,
+    ZonneplanConnectionError,
+    ZonneplanInvalidOtpError,
+    ZonneplanTimeoutError,
+)
+from pyzonneplan.models.account import Account
+from pyzonneplan.models.consumption import ElectricityDelivered, Gas
+from pyzonneplan.models.prices import ConsumerPrices
+
+try:
+    VERSION = metadata.version(__package__)
+except metadata.PackageNotFoundError:  # pragma: no cover
+    VERSION = "DEV-0.0.0"
+
+
+@dataclass
+class Zonneplan:
+    """Asynchronous Python client for the Zonneplan API.
+
+    Zonneplan uses an OAuth2 authorization-code flow with PKCE, but the
+    user-facing step is a one-time password mailed to the account address
+    instead of a browser redirect. The flow is three calls:
+
+    1. POST /oauth/authorize-challenge  {response_type, email, code_challenge, ...}
+       -> HTTP 403 with ``otp_required: true`` and an ``auth_session``.
+          The 403 is the success path, not an error.
+    2. POST /oauth/authorize-challenge  {auth_session, otp}
+       -> ``authorization_code``
+    3. POST /oauth/token  {grant_type: authorization_code, code, code_verifier}
+       -> access + refresh token
+
+    Every other request checks the current token before it goes out and
+    transparently refreshes it once it's within its expiry margin.
+    """
+
+    request_timeout: float = 10.0
+    session: ClientSession | None = None
+
+    def __init__(
+        self,
+        email: str,
+        request_timeout: float = 10.0,
+        session: ClientSession | None = None,
+        max_retries: int = 3,
+        token: Token | None = None,
+    ) -> None:
+        """Initialize the Zonneplan client.
+
+        Pass a previously-obtained ``token`` (see :attr:`token` and
+        :meth:`pyzonneplan.auth.Token.as_dict`) to restore a session without
+        going through the OTP flow again.
+        """
+        self._email = email
+        self._session = session
+        self.request_timeout = request_timeout
+        self._close_session = session is None
+        self._token = token
+        self._max_retries = max_retries
+
+    @property
+    def token(self) -> Token | None:
+        """Return the current token, or ``None`` before login."""
+        return self._token
+
+    async def _request(
+        self,
+        uri: str,
+        *,
+        method: str = METH_GET,
+        params: dict[str, Any] | None = None,
+        json_body: dict[str, Any] | None = None,
+        timeout: float | None = None,
+        allow_forbidden: bool = False,
+        authenticated: bool = True,
+    ) -> Any:
+        """Handle a request to the Zonneplan API.
+
+        Args:
+        ----
+            uri: Request URI, without the leading '/', for example 'user-accounts/me'.
+            method: HTTP method to use.
+            params: Query parameters to include in the request.
+            json_body: JSON body to include in the request.
+            timeout: Timeout for the request (in seconds).
+            allow_forbidden: Treat a 403 response as success instead of raising.
+                Zonneplan's OTP challenge endpoint returns 403 on the happy path.
+            authenticated: Whether this call should refresh an expiring token
+                and send it along. False for the OTP/token endpoints
+                themselves, which would otherwise recurse into a refresh.
+
+        Returns:
+        -------
+            The JSON-decoded response body, or ``None`` for an empty response.
+
+        Raises:
+        ------
+            ZonneplanAuthenticationError: If the access token is invalid or missing.
+            ZonneplanConnectionError: On network errors.
+            ZonneplanTimeoutError: If the request times out.
+
+        """
+        if authenticated and self._token is not None and self._token.is_expired:
+            await self.async_refresh_token()
+
+        url = URL.build(scheme=API_SCHEME, host=API_URL, path="/").join(URL(uri))
+
+        headers = {
+            "content-type": "application/json;charset=utf-8",
+            "user-agent": f"pyzonneplan/{VERSION}",
+            "x-app-version": APP_VERSION,
+            "x-app-environment": APP_ENVIRONMENT,
+        }
+        if self._token is not None:
+            headers["authorization"] = f"Bearer {self._token.access_token}"
+
+        if self._session is None:
+            self._session = ClientSession()
+            self._close_session = True
+
+        if timeout is None:
+            timeout = self.request_timeout
+
+        async for attempt in AsyncRetrying(
+            retry=retry_if_exception_type((ZonneplanConnectionError, ZonneplanTimeoutError)),
+            wait=wait_exponential(multiplier=1, min=1, max=10),
+            stop=stop_after_attempt(self._max_retries + 1),
+            reraise=True,
+        ):
+            with attempt:
+                body = b""
+                try:
+                    async with asyncio.timeout(timeout):
+                        response = await self._session.request(
+                            method,
+                            url,
+                            headers=headers,
+                            params=params,
+                            json=json_body,
+                        )
+                        # Read the body before raise_for_status(), which releases
+                        # the response (and with it, the body stream) before raising.
+                        body = await response.read()
+                        if not (allow_forbidden and response.status == HTTPStatus.FORBIDDEN):
+                            response.raise_for_status()
+                except TimeoutError as err:
+                    msg = f"Timeout error while accessing {method} {url}: {err}"
+                    raise ZonneplanTimeoutError(msg) from err
+                except ClientResponseError as err:
+                    self._raise_for_client_response_error(method, url, err, body)
+                except (ClientError, socket.gaierror) as err:
+                    msg = f"Unexpected error during {method} {url}: {err}"
+                    raise ZonneplanConnectionError(msg) from err
+
+        if response.status in (204, 304):
+            return None
+
+        return orjson.loads(body)
+
+    @staticmethod
+    def _raise_for_client_response_error(method: str, url: URL, err: ClientResponseError, body: bytes) -> NoReturn:
+        """Map a failed HTTP response to the appropriate Zonneplan exception."""
+        body_text = body.decode(errors="replace")
+        match err.status:
+            case 400 | 401 | 403:
+                # Zonneplan returns a plain 400 (not 401/403) for a rejected or
+                # expired OTP/refresh grant, so treat it as an authentication
+                # failure too, not a connection error.
+                msg = f"Authentication failed for {method} {url}: {err} ({body_text})"
+                raise ZonneplanAuthenticationError(msg) from err
+            case _:
+                msg = f"Connection error for {method} {url}: {err} ({body_text})"
+                raise ZonneplanConnectionError(msg) from err
+
+    async def async_request_otp(self, source_name: str) -> OtpChallenge:
+        """Start the login and have Zonneplan mail a one-time password."""
+        code_verifier, code_challenge = generate_pkce_pair()
+        payload = {
+            "response_type": "code",
+            "email": self._email,
+            "code_challenge": code_challenge,
+            "code_challenge_method": "S256",
+            "source_name": source_name[:255],
+        }
+
+        response = await self._request(
+            AUTHORIZE_CHALLENGE_PATH,
+            method=METH_POST,
+            json_body=payload,
+            allow_forbidden=True,
+            authenticated=False,
+        )
+
+        if not response.get("otp_required") or "auth_session" not in response:
+            msg = "Zonneplan did not return an OTP challenge"
+            raise ZonneplanAuthenticationError(msg)
+
+        return OtpChallenge(auth_session=response["auth_session"], code_verifier=code_verifier, email=self._email)
+
+    async def async_submit_otp(self, challenge: OtpChallenge, otp: str) -> Token:
+        """Exchange the mailed one-time password for a token, and use it for further requests."""
+        try:
+            response = await self._request(
+                AUTHORIZE_CHALLENGE_PATH,
+                method=METH_POST,
+                json_body={"auth_session": challenge.auth_session, "otp": otp},
+                authenticated=False,
+            )
+        except ZonneplanAuthenticationError as err:
+            msg = "Zonneplan rejected the one-time password"
+            raise ZonneplanInvalidOtpError(msg) from err
+
+        authorization_code = response.get("authorization_code")
+        if not authorization_code:
+            msg = "Zonneplan rejected the one-time password"
+            raise ZonneplanInvalidOtpError(msg)
+
+        token = await self._async_request_token(
+            {
+                "grant_type": "authorization_code",
+                "code": authorization_code,
+                "code_verifier": challenge.code_verifier,
+            }
+        )
+        self._token = token
+        return token
+
+    async def async_refresh_token(self) -> Token:
+        """Exchange the current refresh token for a new one, regardless of whether it has expired yet."""
+        if self._token is None:
+            msg = "Cannot refresh a token before logging in"
+            raise ZonneplanAuthenticationError(msg)
+
+        self._token = await self._async_request_token({"grant_type": "refresh_token", "refresh_token": self._token.refresh_token})
+        return self._token
+
+    async def _async_request_token(self, grant: dict[str, str]) -> Token:
+        """Call the token endpoint and parse the result."""
+        response = await self._request(TOKEN_PATH, method=METH_POST, json_body=grant, authenticated=False)
+        return Token.from_response(response)
+
+    async def async_get_account(self) -> Account:
+        """Fetch the authenticated Zonneplan account, its addresses and connections."""
+        response = await self._request("user-accounts/me")
+        return Account.from_dict(response["data"])
+
+    async def async_get_consumer_prices(self, chart: str = PriceChart.ELECTRICITY_HOURLY) -> ConsumerPrices:
+        """Fetch a consumer price chart (see :class:`pyzonneplan.const.PriceChart` for valid ``chart`` values)."""
+        response = await self._request(f"api/consumer-prices/charts/{chart}")
+        return ConsumerPrices.from_dict(response["data"])
+
+    async def async_get_electricity_delivered(self, connection_uuid: str) -> ElectricityDelivered:
+        """Fetch electricity delivery/production data (P1) for a connection."""
+        response = await self._request(f"connections/{connection_uuid}/electricity-delivered")
+        return ElectricityDelivered.from_dict(response["data"])
+
+    async def async_get_gas(self, connection_uuid: str) -> Gas:
+        """Fetch gas consumption data (P1) for a connection."""
+        response = await self._request(f"connections/{connection_uuid}/gas")
+        return Gas.from_dict(response["data"])
+
+    async def close(self) -> None:
+        """Close open client session."""
+        if self._session and self._close_session:
+            await self._session.close()
+
+    async def __aenter__(self) -> Self:
+        """Async enter.
+
+        Returns
+        -------
+            The Zonneplan object.
+
+        """
+        return self
+
+    async def __aexit__(self, *_exc_info: object) -> None:
+        """Async exit.
+
+        Args:
+        ----
+            _exc_info: Exec type.
+
+        """
+        await self.close()

pyzonneplan-0.1.0.dist-info/METADATA

@@ -0,0 +1,152 @@
+Metadata-Version: 2.5
+Name: pyzonneplan
+Version: 0.1.0
+Summary: Asynchronous Python client for the Zonneplan API
+Project-URL: Homepage, https://github.com/erwindouna/pyzonneplan
+Project-URL: Repository, https://github.com/erwindouna/pyzonneplan
+Project-URL: Documentation, https://erwindouna.github.io/pyzonneplan/
+Project-URL: Bug Tracker, https://github.com/erwindouna/pyzonneplan/issues
+Project-URL: Changelog, https://github.com/erwindouna/pyzonneplan/releases
+Author-email: Erwin Douna <e.douna@gmail.com>
+Maintainer-email: Erwin Douna <e.douna@gmail.com>
+License-Expression: MIT
+License-File: LICENSE
+Keywords: api,async,battery,charge-point,client,pv,solar,zonneplan
+Classifier: Framework :: AsyncIO
+Classifier: Intended Audience :: Developers
+Classifier: License :: OSI Approved :: MIT License
+Classifier: Natural Language :: English
+Classifier: Programming Language :: Python :: 3
+Classifier: Programming Language :: Python :: 3.12
+Classifier: Programming Language :: Python :: 3.13
+Classifier: Programming Language :: Python :: 3.14
+Classifier: Topic :: Software Development :: Libraries :: Python Modules
+Requires-Python: <4,>=3.12
+Requires-Dist: aiohttp>=3.0.0
+Requires-Dist: mashumaro<4,>=3.17
+Requires-Dist: orjson<4,>=3.10.16
+Requires-Dist: tenacity>=9.0.0
+Requires-Dist: yarl>=1.6.0
+Description-Content-Type: text/markdown
+
+# pyzonneplan
+
+[![GitHub Release][releases-shield]][releases]
+[![Python Versions][python-versions-shield]][pypi]
+![Project Stage][project-stage-shield]
+![Project Maintenance][maintenance-shield]
+[![License][license-shield]](LICENSE)
+
+[![GitHub Activity][commits-shield]][commits-url]
+[![PyPI Downloads][downloads-shield]][downloads-url]
+[![GitHub Last Commit][last-commit-shield]][commits-url]
+[![Open in Dev Containers][devcontainer-shield]][devcontainer]
+
+[![Build Status][build-shield]][build-url]
+[![Typing Status][typing-shield]][typing-url]
+[![Code Coverage][codecov-shield]][codecov-url]
+
+Asynchronous Python client for the Zonneplan API.
+
+## About
+
+pyzonneplan is an async client for the [Zonneplan](https://www.zonneplan.nl/) API, focused on:
+
+- Solar (PV) installation data
+- Dynamic pricing and energy consumption data
+- Home battery monitoring and control modes
+- EV charge point sessions and schedules
+
+The library is under active development and endpoint coverage will keep expanding.
+
+## Installation
+
+```bash
+pip install pyzonneplan
+```
+
+## Usage
+
+Zonneplan authenticates with a one-time password mailed to the account address, rather than a plain username/password login:
+
+```python
+import asyncio
+
+from aiohttp import ClientSession
+from pyzonneplan import ZonneplanAuth
+
+
+async def main() -> None:
+    async with ClientSession() as session:
+        auth = ZonneplanAuth(session=session)
+        challenge = await auth.async_request_otp("you@example.com", source_name="pyzonneplan")
+
+        otp = input("Enter the one-time password mailed to you: ")
+        token = await auth.async_submit_otp(challenge, otp)
+
+        print("Access token:", token.access_token)
+
+
+if __name__ == "__main__":
+    asyncio.run(main())
+```
+
+Store `token.as_dict()` and restore it later with `Token.from_dict(...)`; refresh it
+with `auth.async_refresh_token(token)` once it is close to `token.expires_at`.
+
+More examples can be found in the examples directory.
+
+## Documentation
+
+Project documentation and API reference: https://erwindouna.github.io/pyzonneplan/
+
+## Contributing
+
+Contributions are welcome. Please open an issue or pull request.
+
+For local development:
+
+```bash
+uv sync --all-groups && uv run pre-commit install
+```
+
+Run checks:
+
+```bash
+uv run pre-commit run --all-files
+```
+
+Run tests:
+
+```bash
+uv run pytest
+```
+
+## License
+
+MIT License
+
+Copyright (c) 2026 Erwin Douna
+
+<!-- MARKDOWN LINKS & IMAGES -->
+
+[build-shield]: https://github.com/erwindouna/pyzonneplan/actions/workflows/tests.yaml/badge.svg
+[build-url]: https://github.com/erwindouna/pyzonneplan/actions/workflows/tests.yaml
+[codecov-shield]: https://codecov.io/gh/erwindouna/pyzonneplan/branch/main/graph/badge.svg
+[codecov-url]: https://codecov.io/gh/erwindouna/pyzonneplan
+[commits-shield]: https://img.shields.io/github/commit-activity/y/erwindouna/pyzonneplan.svg
+[commits-url]: https://github.com/erwindouna/pyzonneplan/commits/main
+[devcontainer-shield]: https://img.shields.io/static/v1?label=Dev%20Containers&message=Open&color=blue&logo=visualstudiocode
+[devcontainer]: https://vscode.dev/redirect?url=vscode://ms-vscode-remote.remote-containers/cloneInVolume?url=https://github.com/erwindouna/pyzonneplan
+[downloads-shield]: https://img.shields.io/pypi/dm/pyzonneplan
+[downloads-url]: https://pypistats.org/packages/pyzonneplan
+[last-commit-shield]: https://img.shields.io/github/last-commit/erwindouna/pyzonneplan.svg
+[license-shield]: https://img.shields.io/github/license/erwindouna/pyzonneplan.svg
+[project-stage-shield]: https://img.shields.io/badge/project%20stage-experimental-yellow.svg
+[maintenance-shield]: https://img.shields.io/maintenance/yes/2026.svg
+[pypi]: https://pypi.org/project/pyzonneplan/
+[python-versions-shield]: https://img.shields.io/pypi/pyversions/pyzonneplan
+[releases-shield]: https://img.shields.io/github/release/erwindouna/pyzonneplan.svg
+[releases]: https://github.com/erwindouna/pyzonneplan/releases
+[typing-shield]: https://github.com/erwindouna/pyzonneplan/actions/workflows/typing.yaml/badge.svg
+[typing-url]: https://github.com/erwindouna/pyzonneplan/actions/workflows/typing.yaml

pyzonneplan-0.1.0.dist-info/RECORD

@@ -0,0 +1,15 @@
+pyzonneplan/__init__.py,sha256=eMXcPFJclwHYcQDJY7QEFHJ5UsyGupBsTgXP0sKZREY,1671
+pyzonneplan/auth.py,sha256=XRwGM5A6ELCGUbOQ5BhDjLGaV_SI2bNAxpahOO7Qlcc,2995
+pyzonneplan/const.py,sha256=NvZBJoy8rskTTAFWUbg0OcLy5AhRk412GxE_0vPH-Es,1320
+pyzonneplan/exceptions.py,sha256=nEP3DIACm-oo6u76LIUQSNbWnAhJC-3n3-QBnpxmXJg,576
+pyzonneplan/py.typed,sha256=47DEQpj8HBSa-_TImW-5JCeuQeRkm5NMpJWZG3hSuFU,0
+pyzonneplan/pyzonneplan.py,sha256=VJ7TcRSreLrlETBgtYvmlr-sVNMUFHU1mC45_snrP1A,12291
+pyzonneplan/models/__init__.py,sha256=p4y_46R9AHd7QUwyFSnBnaAH11HXirO-E8xR78PvM9k,1164
+pyzonneplan/models/account.py,sha256=5du0_HxZNYD_m3bQbatql9xy0_AAES8xkTKpDOwUFwQ,4217
+pyzonneplan/models/consumption.py,sha256=yse-RosHQI1QTSmjvmiC19DeXKQnk0gdR53sYYzfhgc,2152
+pyzonneplan/models/devices.py,sha256=Cp8ZJK_kXKCFL_mMD2sA4520ronyaDo7_9cLB_yPDGw,7330
+pyzonneplan/models/prices.py,sha256=6WM9Q5KAaOKi4rvO3xqvu9QzPsyu9FyqP8nRbB5CXp4,2087
+pyzonneplan-0.1.0.dist-info/METADATA,sha256=_5WBqBAeAM0iDRjxgmMJ7Xwk0BODH56XpZ7G7vy8E-c,5447
+pyzonneplan-0.1.0.dist-info/WHEEL,sha256=zOwg4jB6zX2kU910N-cMawjivD6tO8NEWvE12je1bVk,87
+pyzonneplan-0.1.0.dist-info/licenses/LICENSE,sha256=9_z2DWVpibayR1RoHyYPtK-gNWS7OIr1GjuqCT8mSqk,1068
+pyzonneplan-0.1.0.dist-info/RECORD,,

pyzonneplan-0.1.0.dist-info/WHEEL

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

pyzonneplan-0.1.0.dist-info/licenses/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 Erwin Douna
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.