veolia-api-foxace 2.3.0__py3-none-any.whl

veolia_api/__init__.py

@@ -0,0 +1,15 @@
+"""veolia_api package"""
+
+from __future__ import annotations
+
+from .portals import VEOLIA_PORTAL_CLIENTS, VEOLIA_PORTALS, VeoliaPortal
+from .veolia_api import VeoliaAPI
+
+__all__ = [
+    "VEOLIA_PORTALS",
+    "VEOLIA_PORTAL_CLIENTS",
+    "VeoliaAPI",
+    "VeoliaPortal",
+]
+
+__version__ = "2.3.0"

veolia_api/constants.py

@@ -0,0 +1,40 @@
+"""Constants for the Veolia API."""
+
+from __future__ import annotations
+
+from enum import Enum
+from typing import Final
+
+from .portals import DEFAULT_BACKEND_URL, DEFAULT_PORTAL_URL, VEOLIA_PORTALS
+
+# URLS
+# Cognito authentication endpoint (region eu-west-3).
+LOGIN_URL: Final = "https://cognito-idp.eu-west-3.amazonaws.com"
+# Default data backend (national portal). Kept for backward compatibility;
+# the effective backend is resolved per portal (see portals.py).
+BACKEND_ISTEFR: Final = DEFAULT_BACKEND_URL
+
+# AUTH — default Cognito client id (national portal), for backward compatibility.
+LOGIN_CLIENT_ID: Final = VEOLIA_PORTALS[DEFAULT_PORTAL_URL].client_id
+
+# API Flow Endpoints
+CALLBACK_ENDPOINT: Final = "/callback"
+
+TYPE_FRONT: Final = "WEB_ORDINATEUR"
+
+# HTTP Methods
+GET: Final = "GET"
+POST: Final = "POST"
+
+# AsyncIO HTTP/Session
+TIMEOUT: Final = 15
+CONCURRENTS_TASKS: Final = 3
+# Re-login this many seconds before the token actually expires.
+TOKEN_EXPIRY_MARGIN: Final = 60
+
+
+class ConsumptionType(Enum):
+    """Consumption type."""
+
+    MONTHLY = "monthly"
+    YEARLY = "yearly"

veolia_api/exceptions.py

@@ -0,0 +1,35 @@
+"""Custom exception classes for Veolia API errors."""
+
+from __future__ import annotations
+
+
+class VeoliaAPIError(Exception):
+    """Base exception class for Veolia API errors."""
+
+
+class VeoliaAPIInvalidCredentialsError(VeoliaAPIError):
+    """Exception for missing or rejected credentials."""
+
+
+class VeoliaAPITokenError(VeoliaAPIError):
+    """Exception for access-token retrieval or validation failures."""
+
+
+class VeoliaAPIResponseError(VeoliaAPIError):
+    """Exception for unexpected API response payloads."""
+
+
+class VeoliaAPIGetDataError(VeoliaAPIError):
+    """Exception for data-fetching failures."""
+
+
+class VeoliaAPISetDataError(VeoliaAPIError):
+    """Exception for data-writing failures."""
+
+
+class VeoliaAPIUnknownError(VeoliaAPIError):
+    """Exception for unknown Veolia API errors."""
+
+
+class VeoliaAPIRateLimitError(VeoliaAPIError):
+    """Exception for HTTP 429 Too Many Requests."""

veolia_api/model.py

@@ -0,0 +1,64 @@
+"""Veolia API model."""
+
+from __future__ import annotations
+
+from dataclasses import dataclass
+from typing import Any
+
+
+@dataclass
+class AlertSettings:
+    """Alert settings.
+
+    daily_enabled: bool = To enable or disable daily alerts
+    daily_threshold: int = Daily threshold in liters (minimum 100)
+    daily_notif_email: bool = To enable or disable daily
+        alerts by email (Can't be disabled)
+    daily_notif_sms: bool = To enable or disable daily alerts by SMS
+    monthly_enabled: bool = To enable or disable monthly alerts
+    monthly_threshold: int = Monthly threshold in M3 (minimum 1)
+    monthly_notif_email: bool = To enable or disable monthly
+        alerts by email (Can't be disabled)
+    monthly_notif_sms: bool = To enable or disable monthly alerts by SMS.
+    """
+
+    daily_enabled: bool
+    daily_threshold: int
+    daily_notif_email: bool
+    daily_notif_sms: bool
+    monthly_enabled: bool
+    monthly_threshold: int
+    monthly_notif_email: bool
+    monthly_notif_sms: bool
+
+
+@dataclass
+class VeoliaAccountData:
+    """Data for the Veolia integration."""
+
+    access_token: str | None = None
+    token_expiration: float = 0
+    code: str | None = None
+    verifier: str | None = None
+    id_abonnement: str | None = None
+    numero_pds: str | None = None
+    contact_id: str | None = None
+    tiers_id: str | None = None
+    numero_compteur: str | None = None
+    date_debut_abonnement: str | None = None
+    solde: float | None = None
+    dernier_index_releve: float | None = None
+    date_index_releve: str | None = None
+    mode_releve: str | None = None
+    mode_paiement: str | None = None
+    numero_client: str | None = None
+    titulaire: str | None = None
+    marque: str | None = None
+    adresse_de_branchement: str | None = None
+    emplacement_compteur: str | None = None
+    libelle_contrat: str | None = None
+    statut: str | None = None
+    monthly_consumption: list[dict[str, Any]] | None = None
+    daily_consumption: list[dict[str, Any]] | None = None
+    alert_settings: AlertSettings | None = None
+    billing_plan: dict[str, Any] | None = None

veolia_api/portals.py

@@ -0,0 +1,75 @@
+"""Supported Veolia portals.
+
+Veolia operates several water-management portals. They all share the same
+AWS Cognito authentication flow (region ``eu-west-3``) but each portal has its
+own Cognito ``client_id`` and may expose its data on a different backend host.
+
+The national portal (``eau.veolia.fr``) and its delegated brandings (e.g. Eau
+de Toulouse Métropole) run on the default backend. Some independent deployments
+(e.g. Eau de Perpignan Méditerranée Métropole, ``www.ea-pm.fr``) run on their
+own backend.
+
+To add support for a portal, add an entry to :data:`VEOLIA_PORTALS`:
+
+* ``client_id`` — the Cognito app client id, found in the portal's JavaScript
+  bundle (``ClientId:"..."``) or in the network traffic when logging in.
+* ``backend_url`` — the ``*.istefr.fr`` host serving the account/consumption
+  data; omit it when the portal uses the default backend.
+"""
+
+from __future__ import annotations
+
+from dataclasses import dataclass
+
+# Default data backend, used by the national portal and its delegated brandings.
+DEFAULT_BACKEND_URL = "https://prd-ael-sirius-backend.istefr.fr"
+
+# Default portal, used when no portal is explicitly selected.
+DEFAULT_PORTAL_URL = "eau.veolia.fr"
+
+
+@dataclass(frozen=True)
+class VeoliaPortal:
+    """Configuration of a Veolia portal."""
+
+    client_id: str
+    backend_url: str = DEFAULT_BACKEND_URL
+
+
+# hostname (as returned by the commune reference API in ``url_redirection``,
+# or the portal's own hostname) -> portal configuration.
+VEOLIA_PORTALS: dict[str, VeoliaPortal] = {
+    "eau.veolia.fr": VeoliaPortal(
+        client_id="3kghade1fg54739kj8pkbova8j",
+    ),
+    "eaudetm.monespace.eau.veolia.fr": VeoliaPortal(
+        client_id="19bjc8ldefie683n889iiubjc8",  # Eau de Toulouse Métropole
+    ),
+    "www.ea-pm.fr": VeoliaPortal(
+        client_id="54e8dri103e65defj6p67eolli",  # Eau de Perpignan Méditerranée Métropole
+        backend_url="https://prd-ael-sirius-pmm-backend.istefr.fr",
+    ),
+}
+
+# Backward-compatible mapping hostname -> client_id (kept for consumers that
+# only need to test portal support or read the client id).
+VEOLIA_PORTAL_CLIENTS: dict[str, str] = {
+    hostname: portal.client_id for hostname, portal in VEOLIA_PORTALS.items()
+}
+
+
+def get_portal(portal_url: str | None) -> VeoliaPortal:
+    """Return the configuration for ``portal_url`` (or the default portal).
+
+    Raises:
+        ValueError: if ``portal_url`` is not a supported portal.
+
+    """
+    hostname = portal_url or DEFAULT_PORTAL_URL
+    try:
+        return VEOLIA_PORTALS[hostname]
+    except KeyError:
+        raise ValueError(
+            f"Unknown Veolia portal: {hostname!r}. "
+            f"Add it to VEOLIA_PORTALS in portals.py",
+        ) from None

veolia_api/veolia_api.py

@@ -0,0 +1,642 @@
+"""Veolia API client."""
+
+from __future__ import annotations
+
+import asyncio
+import itertools
+import logging
+import re
+from datetime import UTC, date, datetime, timedelta
+from http import HTTPStatus
+from typing import TYPE_CHECKING, Any, cast
+from urllib.parse import urlencode
+
+import aiohttp
+from tenacity import (
+    retry,
+    retry_if_exception_type,
+    stop_after_attempt,
+    wait_exponential,
+)
+
+from .constants import (
+    CONCURRENTS_TASKS,
+    GET,
+    LOGIN_URL,
+    POST,
+    TIMEOUT,
+    TOKEN_EXPIRY_MARGIN,
+    TYPE_FRONT,
+    ConsumptionType,
+)
+from .exceptions import (
+    VeoliaAPIGetDataError,
+    VeoliaAPIInvalidCredentialsError,
+    VeoliaAPIRateLimitError,
+    VeoliaAPIResponseError,
+    VeoliaAPISetDataError,
+    VeoliaAPITokenError,
+)
+from .model import AlertSettings, VeoliaAccountData
+from .portals import get_portal
+
+if TYPE_CHECKING:
+    from collections.abc import Coroutine, Iterator
+
+_LOGGER = logging.getLogger(__name__)
+
+
+class VeoliaAPI:
+    """Veolia API client."""
+
+    def __init__(
+        self,
+        username: str,
+        password: str,
+        session: aiohttp.ClientSession | None = None,
+        portal_url: str | None = None,
+    ) -> None:
+        """Initialize the Veolia API client.
+
+        Args:
+            username: Veolia account email.
+            password: Veolia account password.
+            session: optional shared aiohttp session.
+            portal_url: hostname of the Veolia portal to use (see
+                ``VEOLIA_PORTALS``). Defaults to the national portal.
+
+        """
+        self.username = username
+        self.password = password
+        portal = get_portal(portal_url)
+        self._client_id = portal.client_id
+        self._backend_url = portal.backend_url
+        self.account_data = VeoliaAccountData()
+        self._owns_session = session is None
+        self.session = session or aiohttp.ClientSession(
+            timeout=aiohttp.ClientTimeout(total=TIMEOUT),
+        )
+
+    async def close(self) -> None:
+        """Release the HTTP session if this client owns it."""
+        if self._owns_session and not self.session.closed:
+            await self.session.close()
+
+    @staticmethod
+    def _log_request(
+        url: str,
+        method: str,
+        params: dict[str, Any] | None,
+        json_data: dict[str, Any] | None,
+        headers: dict[str, str],
+    ) -> None:
+        """Debug-log a request with credentials redacted.
+
+        The Cognito login payload carries the password in ``AuthParameters``;
+        headers carry the bearer token.
+        """
+        safe_params = {**params} if params else {}
+        if "password" in safe_params:
+            safe_params["password"] = "REDACTED"
+
+        safe_headers = {**headers}
+        if "Authorization" in safe_headers:
+            safe_headers["Authorization"] = "REDACTED"
+
+        safe_json = None
+        if json_data is not None:
+            safe_json = {**json_data}
+            auth_params = safe_json.get("AuthParameters")
+            if isinstance(auth_params, dict) and "PASSWORD" in auth_params:
+                safe_json["AuthParameters"] = {**auth_params, "PASSWORD": "REDACTED"}
+            for key in list(safe_json):
+                if key.lower() == "password":
+                    safe_json[key] = "REDACTED"
+
+        _LOGGER.debug(
+            "Making %s request to %s with params: %s, headers: %s, json: %s",
+            method,
+            url,
+            safe_params,
+            safe_headers,
+            safe_json,
+        )
+
+    @retry(
+        reraise=True,
+        stop=stop_after_attempt(5),
+        wait=wait_exponential(multiplier=1, min=1, max=16),
+        retry=retry_if_exception_type((aiohttp.ClientError, VeoliaAPIRateLimitError)),
+    )
+    async def _send_request(
+        self,
+        url: str,
+        method: str,
+        params: dict[str, Any] | None = None,
+        json_data: dict[str, Any] | None = None,
+        is_login: bool = False,
+    ) -> aiohttp.ClientResponse:
+        """Make an HTTP request with support for params, headers and JSON body."""
+        req_headers = {
+            "User-Agent": (
+                "Mozilla/5.0 (X11; Linux x86_64) "
+                "AppleWebKit/537.36 (KHTML, like Gecko) "
+                "Chrome/140.0.0.0 Safari/537.36"
+            ),
+            "Accept": "*/*",
+        }
+
+        if self.account_data.access_token:
+            req_headers["Authorization"] = f"Bearer {self.account_data.access_token}"
+
+        if method == POST:
+            req_headers["Content-Type"] = "application/json"
+
+        self._log_request(url, method, params, json_data, req_headers)
+
+        kwargs: dict[str, Any] = {
+            "headers": req_headers,
+            "allow_redirects": False,
+            # Per-request timeout: the injected shared session (e.g. the Home
+            # Assistant one) has no total timeout of its own.
+            "timeout": aiohttp.ClientTimeout(total=TIMEOUT),
+        }
+
+        if params:
+            kwargs["params"] = params
+
+        if json_data is not None:
+            req_headers["Content-Type"] = "application/json"
+            kwargs["json"] = json_data
+
+        if is_login:
+            req_headers["Content-Type"] = "application/x-amz-json-1.1"
+            req_headers["x-amz-target"] = (
+                "AWSCognitoIdentityProviderService.InitiateAuth"
+            )
+
+        elif method.upper() == POST and params:
+            req_headers.update(
+                {
+                    "Content-Type": "application/x-www-form-urlencoded",
+                    "Cache-Control": "no-cache",
+                },
+            )
+            kwargs["data"] = urlencode(params)
+
+        response = await self.session.request(method.upper(), url, **kwargs)
+        _LOGGER.debug("Received response with status code %s", response.status)
+        if response.status == HTTPStatus.TOO_MANY_REQUESTS:
+            _LOGGER.warning(
+                "Rate limit hit (HTTP 429) for %s %s, retrying...",
+                method,
+                url,
+            )
+            raise VeoliaAPIRateLimitError("HTTP 429 Too Many Requests")
+
+        if not is_login and response.status == HTTPStatus.UNAUTHORIZED:
+            raise VeoliaAPITokenError("Authentication rejected (HTTP 401)")
+
+        return response
+
+    async def login(self) -> bool:
+        """Login to the Veolia API."""
+        _LOGGER.info("Logging in...")
+        email_regex = r"^[a-zA-Z0-9_.+-]+@[a-zA-Z0-9-]+\.[a-zA-Z0-9-.]+$"
+
+        if not self.username or not self.password:
+            raise VeoliaAPIInvalidCredentialsError("Missing username or password")
+        if not re.match(email_regex, self.username):
+            raise VeoliaAPIInvalidCredentialsError("Invalid email format")
+        _LOGGER.debug("Starting login process...")
+        await self._get_access_token()
+        await self._get_client_data()
+
+        # Check if login was successful
+        if (
+            self.account_data.access_token
+            and self.account_data.id_abonnement
+            and self.account_data.numero_pds
+            and self.account_data.contact_id
+            and self.account_data.tiers_id
+            and self.account_data.numero_compteur
+            and self.account_data.date_debut_abonnement
+        ):
+            _LOGGER.info("Login successful")
+            return True
+        return False
+
+    async def _check_token(self) -> None:
+        """Check if the access token is still valid, re-login otherwise."""
+        if (
+            not self.account_data.access_token
+            or datetime.now(UTC).timestamp()
+            >= self.account_data.token_expiration - TOKEN_EXPIRY_MARGIN
+        ):
+            _LOGGER.debug("No access token or token expired")
+            await self.login()
+
+    async def _get_access_token(self) -> None:
+        """Request the access token."""
+        token_url = f"{LOGIN_URL}"
+        _LOGGER.debug("Requesting access token...")
+        json_payload = {
+            "ClientId": self._client_id,
+            "AuthFlow": "USER_PASSWORD_AUTH",
+            "AuthParameters": {"USERNAME": self.username, "PASSWORD": self.password},
+        }
+
+        response = await self._send_request(
+            url=token_url,
+            method=POST,
+            json_data=json_payload,
+            is_login=True,
+        )
+
+        token_data = await response.json(content_type="json")
+
+        if response.status != HTTPStatus.OK:
+            error_type = token_data.get("__type", "")
+            if error_type in ("NotAuthorizedException", "UserNotFoundException"):
+                raise VeoliaAPIInvalidCredentialsError(
+                    token_data.get("message", "Invalid credentials"),
+                )
+            raise VeoliaAPITokenError(
+                "Token API call error: " + token_data.get("message", "Unknown error"),
+            )
+
+        authentication_result = token_data.get("AuthenticationResult")
+        if not authentication_result:
+            raise VeoliaAPITokenError("Authentication failed")
+
+        self.account_data.access_token = authentication_result.get("AccessToken")
+        if not self.account_data.access_token:
+            raise VeoliaAPITokenError("Access token not found")
+
+        self.account_data.token_expiration = (
+            datetime.now(UTC)
+            + timedelta(seconds=authentication_result.get("ExpiresIn", 0))
+        ).timestamp()
+        _LOGGER.debug("OK - Access token retrieved")
+
+    async def _get_client_data(self) -> None:
+        """Get the account data."""
+        _LOGGER.debug("Fetching user & billing data...")
+        url = f"{self._backend_url}/espace-client?type-front={TYPE_FRONT}"
+        response = await self._send_request(url=url, method=GET)
+        if response.status != HTTPStatus.OK:
+            raise VeoliaAPIGetDataError(
+                f"call to= espace-client failed with http status= {response.status}",
+            )
+
+        userdata = await response.json()
+        self.account_data.id_abonnement = (
+            userdata.get("contacts", None)[0]
+            .get("tiers", None)[0]
+            .get("abonnements", None)[0]
+            .get("id_abonnement", None)
+        )
+        self.account_data.tiers_id = (
+            userdata.get("contacts", None)[0].get("tiers", None)[0].get("id", None)
+        )
+        self.account_data.contact_id = userdata.get("contacts", None)[0].get(
+            "id_contact",
+            None,
+        )
+        self.account_data.numero_compteur = (
+            userdata.get("contacts", None)[0]
+            .get("tiers", None)[0]
+            .get("abonnements", None)[0]
+            .get("numero_compteur", None)
+        )
+        if (
+            not self.account_data.id_abonnement
+            or not self.account_data.tiers_id
+            or not self.account_data.contact_id
+            or not self.account_data.numero_compteur
+        ):
+            raise VeoliaAPIResponseError("Some user data not found in the response")
+
+        # Contract details (optional)
+        abonnement = (
+            (userdata.get("contacts") or [{}])[0]
+            .get("tiers", [{}])[0]
+            .get("abonnements", [{}])[0]
+        )
+        self.account_data.adresse_de_branchement = abonnement.get(
+            "adresse_de_branchement",
+        )
+        self.account_data.emplacement_compteur = abonnement.get("emplacement_compteur")
+        self.account_data.libelle_contrat = abonnement.get("libelle_contrat")
+        self.account_data.statut = abonnement.get("statut")
+        _LOGGER.debug("OK - Fetch done for user & billing data")
+
+        # Facturation request
+        url_facturation = f"{self._backend_url}/abonnements/{self.account_data.id_abonnement}/facturation"
+        response_facturation = await self._send_request(url=url_facturation, method=GET)
+        if response_facturation.status != HTTPStatus.OK:
+            raise VeoliaAPIGetDataError(
+                f"call to= facturation failed with http status= {response_facturation.status}",
+            )
+
+        facturation_data = await response_facturation.json()
+        self.account_data.numero_pds = facturation_data.get("numero_pds")
+        self.account_data.solde = facturation_data.get("solde")
+        self.account_data.dernier_index_releve = facturation_data.get(
+            "dernier_index_releve",
+        )
+        self.account_data.date_index_releve = facturation_data.get("date_index_releve")
+        self.account_data.mode_releve = facturation_data.get("mode_releve")
+        self.account_data.mode_paiement = facturation_data.get("mode_paiement")
+        self.account_data.numero_client = facturation_data.get("numero_client")
+        self.account_data.titulaire = facturation_data.get("titulaire")
+        self.account_data.marque = facturation_data.get("marque")
+        if not self.account_data.numero_pds:
+            raise VeoliaAPIResponseError("numero_pds not found in the response")
+
+        self.account_data.date_debut_abonnement = facturation_data.get(
+            "date_debut_abonnement",
+        )
+        if not self.account_data.date_debut_abonnement:
+            raise VeoliaAPIResponseError(
+                "date_debut_abonnement not found in the response",
+            )
+        _LOGGER.debug("OK - Billing data received")
+
+    async def _get_consumption_data(
+        self,
+        data_type: ConsumptionType,
+        year: int,
+        month: int | None = None,
+    ) -> list[dict[str, Any]]:
+        """Get the water consumption data."""
+        date_debut_str = self.account_data.date_debut_abonnement
+        if not date_debut_str:
+            raise VeoliaAPIGetDataError("Subscription start date unknown, login first")
+        date_debut = datetime.strptime(date_debut_str, "%Y-%m-%d").replace(tzinfo=UTC)
+        if month is not None:
+            requested_date = datetime(year, month, 1, tzinfo=UTC)
+        else:
+            requested_date = datetime(year, 1, 1, tzinfo=UTC)
+
+        if requested_date < date_debut:
+            _LOGGER.warning(
+                "Requested data for %s-%s is before subscription start date %s. Request aborted.",
+                year,
+                month,
+                self.account_data.date_debut_abonnement,
+            )
+            return []
+
+        params = {
+            "annee": year,
+            "numero-pds": self.account_data.numero_pds,
+            "date-debut-abonnement": self.account_data.date_debut_abonnement,
+        }
+
+        if data_type == ConsumptionType.MONTHLY and month is not None:
+            params["mois"] = month
+            endpoint = "journalieres"
+            _LOGGER.debug(
+                "Fetching daily consumption data for : %s-%s",
+                year,
+                month,
+            )
+        elif data_type == ConsumptionType.YEARLY:
+            endpoint = "mensuelles"
+            _LOGGER.debug("Fetching monthly consumption data for year : %s", year)
+        else:
+            raise ValueError("Invalid data type or missing month for monthly data")
+
+        url = f"{self._backend_url}/consommations/{self.account_data.id_abonnement}/{endpoint}"
+
+        response = await self._send_request(
+            url=url,
+            method=GET,
+            params=params,
+        )
+        if response.status != HTTPStatus.OK:
+            raise VeoliaAPIGetDataError(
+                f"call to= consommations failed with http status= {response.status}",
+            )
+        _LOGGER.debug("OK - Fetch done for %s-%s", year, month)
+        return cast("list[dict[str, Any]]", await response.json())
+
+    async def get_alerts_settings(self) -> AlertSettings:
+        """Get the consumption alerts.
+
+        Response example:
+        {
+            "seuils": {
+                "journalier": {
+                    "valeur": 100,
+                    "unite": "L",
+                    "moyen_contact": {
+                        "souscrit_par_email": true,
+                        "souscrit_par_mobile": true
+                    }
+                },
+                "mensuel": {
+                    "valeur": 5,
+                    "unite": "M3",
+                    "moyen_contact": {
+                        "souscrit_par_email": true,
+                        "souscrit_par_mobile": false
+                    }
+                }
+            }
+        }.
+        """
+        await self._check_token()
+
+        _LOGGER.debug("Fetching alerts settings...")
+        params = {
+            "abo_id": self.account_data.id_abonnement,
+        }
+        url = f"{self._backend_url}/alertes/{self.account_data.numero_pds}"
+        response = await self._send_request(
+            url=url,
+            method=GET,
+            params=params,
+        )
+
+        if response.status == HTTPStatus.NO_CONTENT:
+            _LOGGER.info("No alerts settings found")
+            return AlertSettings(
+                daily_enabled=False,
+                daily_threshold=0,
+                daily_notif_email=False,
+                daily_notif_sms=False,
+                monthly_enabled=False,
+                monthly_threshold=0,
+                monthly_notif_email=False,
+                monthly_notif_sms=False,
+            )
+
+        if response.status == HTTPStatus.OK:
+            data = await response.json()
+            seuils = data.get("seuils", {})
+            daily_alert = seuils.get("journalier", None)
+            monthly_alert = seuils.get("mensuel", None)
+
+            _LOGGER.debug("Alerts settings: %s", data)
+            _LOGGER.debug("OK - Fetch done for alerts settings")
+
+            return AlertSettings(
+                daily_enabled=bool(daily_alert),
+                daily_threshold=daily_alert["valeur"] if daily_alert else 0,
+                daily_notif_email=(
+                    daily_alert["moyen_contact"]["souscrit_par_email"]
+                    if daily_alert
+                    else False
+                ),
+                daily_notif_sms=(
+                    daily_alert["moyen_contact"]["souscrit_par_mobile"]
+                    if daily_alert
+                    else False
+                ),
+                monthly_enabled=bool(monthly_alert),
+                monthly_threshold=(monthly_alert["valeur"] if monthly_alert else 0),
+                monthly_notif_email=(
+                    monthly_alert["moyen_contact"]["souscrit_par_email"]
+                    if monthly_alert
+                    else False
+                ),
+                monthly_notif_sms=(
+                    monthly_alert["moyen_contact"]["souscrit_par_mobile"]
+                    if monthly_alert
+                    else False
+                ),
+            )
+        raise VeoliaAPIGetDataError(
+            f"call to= alertes failed with http status= {response.status}",
+        )
+
+    async def _get_mensualisation_plan(self) -> dict[str, Any]:
+        """Get the plan de mensualisation for the given abonnement ID."""
+        _LOGGER.debug("Getting mensualisation plan...")
+        url = f"{self._backend_url}/abonnements/{self.account_data.id_abonnement}/facturation/mensualisation/plan"
+
+        response = await self._send_request(url=url, method=GET)
+
+        if response.status == HTTPStatus.NO_CONTENT:
+            _LOGGER.info("No mensualisation plan found")
+            return {}
+
+        if response.status == HTTPStatus.OK:
+            _LOGGER.debug("OK - Mensualisation plan received")
+            return cast("dict[str, Any]", await response.json())
+
+        _LOGGER.warning(
+            "call to mensualisation/plan failed with HTTP status %s",
+            response.status,
+        )
+        return {}
+
+    @staticmethod
+    def _iter_months(start_date: date, end_date: date) -> Iterator[tuple[int, int]]:
+        """Yield (year, month) pairs covering [start_date, end_date]."""
+        y, m = start_date.year, start_date.month
+        while (y < end_date.year) or (y == end_date.year and m <= end_date.month):
+            yield y, m
+            if m == 12:  # noqa: PLR2004
+                y, m = y + 1, 1
+            else:
+                m += 1
+
+    async def fetch_all_data(self, start_date: date, end_date: date) -> None:
+        """Fetch consumption for a date range and store in the dataclass.
+
+        - monthly_consumption: list of yearly payloads for each covered year
+        - daily_consumption: list of monthly payloads for each covered (year, month)
+        """
+        _LOGGER.info(
+            "Fetching all data for range %s -> %s...",
+            start_date,
+            end_date,
+        )
+        await self._check_token()
+
+        semaphore = asyncio.Semaphore(CONCURRENTS_TASKS)
+
+        async def _sem_task(
+            task_coro: Coroutine[Any, Any, list[dict[str, Any]]],
+        ) -> list[dict[str, Any]]:
+            """Semaphore coro."""
+            async with semaphore:
+                return await task_coro
+
+        years = list(range(start_date.year, end_date.year + 1))
+        monthly_tasks = [
+            _sem_task(self._get_consumption_data(ConsumptionType.YEARLY, y))
+            for y in years
+        ]
+        daily_tasks = [
+            _sem_task(self._get_consumption_data(ConsumptionType.MONTHLY, y, m))
+            for (y, m) in self._iter_months(start_date, end_date)
+        ]
+
+        monthly_results = await asyncio.gather(*monthly_tasks) if monthly_tasks else []
+        daily_results = await asyncio.gather(*daily_tasks) if daily_tasks else []
+
+        self.account_data.monthly_consumption = list(
+            itertools.chain.from_iterable(monthly_results),
+        )
+        self.account_data.daily_consumption = list(
+            itertools.chain.from_iterable(daily_results),
+        )
+        # Fetch other data with no historical
+        self.account_data.billing_plan = await self._get_mensualisation_plan()
+        self.account_data.alert_settings = await self.get_alerts_settings()
+        _LOGGER.info("OK - All data fetched for range")
+
+    async def set_alerts_settings(self, alert_settings: AlertSettings) -> bool:
+        """Set the consumption alerts."""
+        await self._check_token()
+
+        _LOGGER.debug("Setting alerts params...")
+        url = f"{self._backend_url}/alertes/{self.account_data.numero_pds}"
+        payload: dict[str, Any] = {}
+
+        if alert_settings.daily_enabled:
+            payload["alerte_journaliere"] = {
+                "seuil": alert_settings.daily_threshold,
+                "unite": "L",
+                "souscrite": True,
+                "contact_channel": {
+                    "subscribed_by_email": alert_settings.daily_notif_email,
+                    "subscribed_by_mobile": alert_settings.daily_notif_sms,
+                },
+            }
+
+        if alert_settings.monthly_enabled:
+            payload["alerte_mensuelle"] = {
+                "seuil": alert_settings.monthly_threshold,
+                "unite": "M3",
+                "souscrite": True,
+                "contact_channel": {
+                    "subscribed_by_email": alert_settings.monthly_notif_email,
+                    "subscribed_by_mobile": alert_settings.monthly_notif_sms,
+                },
+            }
+
+        payload.update(
+            {
+                "contact_id": self.account_data.contact_id,
+                "numero_compteur": self.account_data.numero_compteur,
+                "tiers_id": self.account_data.tiers_id,
+                "abo_id": str(self.account_data.id_abonnement),
+                "type_front": TYPE_FRONT,
+            },
+        )
+
+        _LOGGER.debug("Alert settings payload: %s", payload)
+
+        response = await self._send_request(url=url, method=POST, json_data=payload)
+        if response.status != HTTPStatus.NO_CONTENT:
+            raise VeoliaAPISetDataError(
+                f"Failed to set alerts settings with status code {response.status}, maybe alert are not supported on this account ?",
+            )
+
+        _LOGGER.debug("OK - Alerts settings set")
+        return True

veolia_api_foxace-2.3.0.dist-info/METADATA

@@ -0,0 +1,128 @@
+Metadata-Version: 2.4
+Name: veolia-api-foxace
+Version: 2.3.0
+Summary: Async client for the Veolia water portals (eau.veolia.fr and delegated portals)
+License: MIT
+License-File: LICENSE
+Keywords: python,veolia
+Author: Jezza34000
+Author-email: info@mail.com
+Maintainer: foXaCe
+Requires-Python: >=3.11
+Classifier: License :: OSI Approved :: MIT License
+Classifier: Operating System :: OS Independent
+Classifier: Programming Language :: Python :: 3
+Classifier: Programming Language :: Python :: 3.11
+Classifier: Programming Language :: Python :: 3.12
+Classifier: Programming Language :: Python :: 3.13
+Classifier: Programming Language :: Python :: 3.14
+Requires-Dist: aiohttp (>=3.11.11,<4.0.0)
+Requires-Dist: tenacity (>=9.1.2,<10.0.0)
+Project-URL: Homepage, https://github.com/foXaCe/veolia-api
+Project-URL: Repository, https://github.com/foXaCe/veolia-api
+Description-Content-Type: text/markdown
+
+<p align=center>
+    <img src="https://upload.wikimedia.org/wikipedia/fi/thumb/2/2a/Veolia-logo.svg/250px-Veolia-logo.svg.png"/>
+</p>
+
+<p>
+    <a href="https://pypi.org/project/veolia-api-foxace/"><img src="https://img.shields.io/pypi/v/veolia-api-foxace.svg"/></a>
+    <a href="https://img.shields.io/badge/pre--commit-enabled-brightgreen?logo=pre-commit&logoColor=white"><img src="https://img.shields.io/badge/pre--commit-enabled-brightgreen?logo=pre-commit&logoColor=white" /></a>
+    <a href="https://github.com/psf/black"><img src="https://img.shields.io/badge/code%20style-black-000000.svg" /></a>
+    <a href="https://github.com/foXaCe/veolia-api/actions"><img src="https://github.com/foXaCe/veolia-api/workflows/CI/badge.svg"/></a>
+</p>
+
+Async Python client for the Veolia water portal API (`eau.veolia.fr`).
+
+## Table of contents
+
+- [Installation](#installation)
+- [Usage](#usage)
+- [Contributing](#contributing)
+- [Credits](#credits)
+- [License](#license)
+
+## Installation
+
+First of all, you need to install [devbox](https://www.jetify.com/docs/devbox/installing-devbox) **if you don't have a python environment**
+
+Once the previous step is done, simply run
+
+```bash
+devbox shell
+cp .env.example .env   # fill in your credentials
+python usage_example.py
+```
+
+That's it !
+
+If you already have a python environment just run
+
+```bash
+pip install veolia-api-foxace
+```
+
+## Usage
+
+```python
+"""Example of usage of the Veolia API"""
+
+import asyncio
+from datetime import date
+
+import aiohttp
+
+from veolia_api.veolia_api import VeoliaAPI
+
+
+async def main() -> None:
+    """Main function."""
+
+    async with aiohttp.ClientSession() as session:
+        client_api = VeoliaAPI("your@email.com", "password", session)
+
+        await client_api.fetch_all_data(date(2025, 1, 1), date(2025, 9, 1))
+
+        # Display fetched data
+        print(client_api.account_data.daily_consumption)
+        print(client_api.account_data.monthly_consumption)
+        print(client_api.account_data.alert_settings.daily_enabled)
+
+
+if __name__ == "__main__":
+    asyncio.run(main())
+
+```
+
+You can use usage_example.py
+
+### Portals
+
+Veolia operates several portals. They share the same Cognito authentication flow
+but each has its own `client_id`, and some run on a dedicated data backend. Select
+a portal with the `portal_url` argument (defaults to the national portal):
+
+```python
+client_api = VeoliaAPI("your@email.com", "password", session, portal_url="www.ea-pm.fr")
+```
+
+| `portal_url`                      | Description                             | Backend  |
+| --------------------------------- | --------------------------------------- | -------- |
+| `eau.veolia.fr` (default)         | Veolia France (national)                | default  |
+| `eaudetm.monespace.eau.veolia.fr` | Eau de Toulouse Métropole               | default  |
+| `www.ea-pm.fr`                    | Eau de Perpignan Méditerranée Métropole | dedicated |
+
+To add a portal, add an entry to `VEOLIA_PORTALS` in
+[`veolia_api/portals.py`](veolia_api/portals.py) with its `client_id` (found in
+the portal's JavaScript bundle as `ClientId:"..."`) and, if different from the
+default, its `backend_url`.
+
+## Contributing
+
+Contributions are welcome. Please read [CONTRIBUTING.md](CONTRIBUTING.md) for guidelines on reporting bugs, suggesting features, and submitting pull requests.
+
+## Credits
+
+This repository is inspired by the work done by @CorentinGrard. Thanks to him for his work.
+

veolia_api_foxace-2.3.0.dist-info/RECORD

@@ -0,0 +1,10 @@
+veolia_api/__init__.py,sha256=Sjxz59Bl5-QVk6e3kr3an6uqkdyEfcJy2ieBFQIHMWE,295
+veolia_api/constants.py,sha256=RcSVuABALHa7ahLz3tfAugk4qoc3SUA6BZ73yJDxMFk,1094
+veolia_api/exceptions.py,sha256=tjikhgfeEVdGfRHsGeUphDfsjolgtrC4S5rASXoKeD4,904
+veolia_api/model.py,sha256=TgsTMceRvbeYRiccioGKy4bxXIyTN32S5o5_RrCeB5Y,2097
+veolia_api/portals.py,sha256=vZlwt430MF0sl9XFOxn8JdoG2HN9gbFaBDw-S-5IL_w,2717
+veolia_api/veolia_api.py,sha256=PfT_PHUnEC2xm28eY5RAUBUdeRMHBfQZjq2kQWI_JVM,23799
+veolia_api_foxace-2.3.0.dist-info/METADATA,sha256=wmxYVq_e471-EI4Bq2zj3DTgLFoYe2rKFDh117Uz-u8,4334
+veolia_api_foxace-2.3.0.dist-info/WHEEL,sha256=EGEvSphFYqXKs23-kQBeyNoJP1nrT8ZJKQoi5p5DYL8,88
+veolia_api_foxace-2.3.0.dist-info/licenses/LICENSE,sha256=PT_M2vrKC4ksLkpuXcIi9ojgypP-egmv5DXftkVP_04,1067
+veolia_api_foxace-2.3.0.dist-info/RECORD,,

veolia_api_foxace-2.3.0.dist-info/WHEEL

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

veolia_api_foxace-2.3.0.dist-info/licenses/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2025 Jezza34000
+
+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.