pyfenixcontrol 0.1.0__py3-none-any.whl

pyfenixcontrol/__init__.py

@@ -0,0 +1,46 @@
+"""Asynchronous Python client for the FENIX Control cloud API."""
+
+from __future__ import annotations
+
+from .auth import AbstractAuth, PasswordAuth
+from .client import FenixControlClient
+from .const import EnergyPeriod, HolidayMode, HvacState, PresetMode
+from .exceptions import (
+    FenixControlAuthError,
+    FenixControlConnectionError,
+    FenixControlError,
+    FenixControlResponseError,
+)
+from .models import (
+    Device,
+    EnergyMetric,
+    Installation,
+    Room,
+    decode_temperature,
+    encode_temperature,
+    parse_holiday_date,
+)
+
+__version__ = "0.1.0"
+
+__all__ = [
+    "AbstractAuth",
+    "Device",
+    "EnergyMetric",
+    "EnergyPeriod",
+    "FenixControlAuthError",
+    "FenixControlClient",
+    "FenixControlConnectionError",
+    "FenixControlError",
+    "FenixControlResponseError",
+    "HolidayMode",
+    "HvacState",
+    "Installation",
+    "PasswordAuth",
+    "PresetMode",
+    "Room",
+    "__version__",
+    "decode_temperature",
+    "encode_temperature",
+    "parse_holiday_date",
+]

pyfenixcontrol/auth.py

@@ -0,0 +1,372 @@
+"""Authentication for the FENIX Control cloud.
+
+The client never deals with credentials directly. It asks an
+:class:`AbstractAuth` implementation for a bearer token, so the same client
+works with the bundled username/password flow (:class:`PasswordAuth`) or with
+tokens managed elsewhere, e.g. Home Assistant's OAuth2 helpers.
+"""
+
+from __future__ import annotations
+
+import asyncio
+import base64
+import hashlib
+import json
+import logging
+import secrets
+import time
+import urllib.parse
+from abc import ABC, abstractmethod
+from html.parser import HTMLParser
+from typing import TYPE_CHECKING, Any
+
+import aiohttp
+
+from .const import (
+    DEFAULT_CLIENT_ID,
+    DEFAULT_REDIRECT_URI,
+    DEFAULT_REQUEST_TIMEOUT,
+    DEFAULT_SCOPES,
+    IDENTITY_BASE_URL,
+    OEM_CLIENT,
+)
+from .exceptions import (
+    FenixControlAuthError,
+    FenixControlConnectionError,
+    FenixControlResponseError,
+)
+
+if TYPE_CHECKING:
+    from collections.abc import Mapping
+
+_LOGGER = logging.getLogger(__name__)
+
+_HTTP_OK = 200
+_HTTP_FOUND = 302
+_HTTP_BAD_REQUEST = 400
+_HTTP_UNAUTHORIZED = 401
+_HTTP_SERVER_ERROR = 500
+
+#: Refresh the access token this many seconds before it expires.
+TOKEN_EXPIRY_MARGIN = 60.0
+_DEFAULT_TOKEN_LIFETIME = 3600.0
+
+_CSRF_FIELD = "__RequestVerificationToken"
+_RETURN_URL_FIELD = "ReturnUrl"
+
+
+class AbstractAuth(ABC):
+    """Supplies bearer tokens to :class:`~pyfenixcontrol.FenixControlClient`."""
+
+    def __init__(self, session: aiohttp.ClientSession) -> None:
+        """Initialize with the HTTP session used for all requests."""
+        self._session = session
+
+    @property
+    def session(self) -> aiohttp.ClientSession:
+        """Return the HTTP session shared with the client."""
+        return self._session
+
+    @abstractmethod
+    async def async_get_access_token(self) -> str:
+        """Return a valid access token, refreshing it if needed.
+
+        Raise :class:`FenixControlAuthError` if no token can be obtained
+        without user interaction.
+        """
+
+    async def async_invalidate_access_token(self) -> None:
+        """Mark the current access token as rejected by the API.
+
+        Called by the client after an HTTP 401. Implementations that can
+        refresh on demand should drop the cached token so the next
+        :meth:`async_get_access_token` obtains a fresh one.
+        """
+
+
+def generate_pkce_pair() -> tuple[str, str]:
+    """Return a PKCE ``(code_verifier, code_challenge)`` pair (S256)."""
+    code_verifier = secrets.token_urlsafe(96)[:128]
+    digest = hashlib.sha256(code_verifier.encode("ascii")).digest()
+    code_challenge = base64.urlsafe_b64encode(digest).decode("ascii").rstrip("=")
+    return code_verifier, code_challenge
+
+
+class _LoginFormParser(HTMLParser):
+    """Collect the hidden inputs of the identity server login form."""
+
+    def __init__(self) -> None:
+        super().__init__()
+        self.fields: dict[str, str] = {}
+
+    def handle_starttag(self, tag: str, attrs: list[tuple[str, str | None]]) -> None:
+        if tag != "input":
+            return
+        values = dict(attrs)
+        name = values.get("name")
+        value = values.get("value")
+        if name in (_CSRF_FIELD, _RETURN_URL_FIELD) and value:
+            self.fields.setdefault(name, value)
+
+
+def parse_login_form(html: str) -> tuple[str, str] | None:
+    """Return ``(csrf_token, return_url)`` from the login page, if present."""
+    parser = _LoginFormParser()
+    parser.feed(html)
+    parser.close()
+    csrf = parser.fields.get(_CSRF_FIELD)
+    return_url = parser.fields.get(_RETURN_URL_FIELD)
+    if csrf and return_url:
+        return csrf, return_url
+    return None
+
+
+class PasswordAuth(AbstractAuth):
+    """OAuth2 authorization-code + PKCE login using account e-mail and password.
+
+    This drives the identity server's login form the same way the FENIX
+    Control app does. Tokens are kept in memory and refreshed automatically;
+    if the refresh token stops working, a full login is performed again.
+
+    The identity server tracks the login form with cookies, so ``session``
+    must have a working cookie jar. Identity-server cookies are cleared before
+    every full login so a cached session can never log in a different account.
+    """
+
+    def __init__(
+        self,
+        session: aiohttp.ClientSession,
+        username: str,
+        password: str,
+        *,
+        client_id: str = DEFAULT_CLIENT_ID,
+        redirect_uri: str = DEFAULT_REDIRECT_URI,
+        scopes: str = DEFAULT_SCOPES,
+        identity_url: str = IDENTITY_BASE_URL,
+        request_timeout: float = DEFAULT_REQUEST_TIMEOUT,
+    ) -> None:
+        """Initialize the password-based authenticator."""
+        super().__init__(session)
+        self._username = username
+        self._password = password
+        self._client_id = client_id
+        self._redirect_uri = redirect_uri
+        self._redirect_scheme = urllib.parse.urlsplit(redirect_uri).scheme
+        self._scopes = scopes
+        self._identity_url = identity_url.rstrip("/")
+        self._timeout = aiohttp.ClientTimeout(total=request_timeout)
+        self._lock = asyncio.Lock()
+        self._access_token: str | None = None
+        self._refresh_token: str | None = None
+        self._expires_at = 0.0
+
+    @property
+    def token_url(self) -> str:
+        """Return the OAuth2 token endpoint."""
+        return f"{self._identity_url}/connect/token"
+
+    async def async_get_access_token(self) -> str:
+        """Return a valid access token, refreshing or logging in as needed."""
+        async with self._lock:
+            if self._access_token and time.monotonic() < self._expires_at:
+                return self._access_token
+            if self._refresh_token:
+                try:
+                    await self._refresh()
+                except (FenixControlAuthError, FenixControlResponseError) as err:
+                    _LOGGER.debug("Token refresh failed (%s), logging in again", err)
+                    await self._login()
+            else:
+                await self._login()
+            if self._access_token is None:  # pragma: no cover - defensive
+                msg = "No access token after login"
+                raise FenixControlAuthError(msg)
+            return self._access_token
+
+    async def async_invalidate_access_token(self) -> None:
+        """Force the next token request to refresh."""
+        self._expires_at = 0.0
+
+    async def async_login(self) -> None:
+        """Perform a full login now, e.g. to validate credentials.
+
+        Raises :class:`FenixControlAuthError` for invalid credentials and
+        :class:`FenixControlConnectionError` if the cloud is unreachable.
+        """
+        async with self._lock:
+            await self._login()
+
+    # -- internals ---------------------------------------------------------
+
+    async def _request(
+        self, method: str, url: str, **kwargs: Any
+    ) -> tuple[int, Mapping[str, str], str]:
+        """Send a request and return ``(status, headers, body)``."""
+        try:
+            async with self._session.request(
+                method, url, timeout=self._timeout, **kwargs
+            ) as resp:
+                return resp.status, resp.headers, await resp.text()
+        except (aiohttp.ClientError, TimeoutError) as err:
+            msg = f"Error communicating with identity server: {err}"
+            raise FenixControlConnectionError(msg) from err
+
+    def _store_tokens(self, body: str, *, require_refresh: bool) -> None:
+        try:
+            tokens = json.loads(body) if body else {}
+        except ValueError as err:
+            msg = "Invalid JSON from token endpoint"
+            raise FenixControlResponseError(msg) from err
+        access = tokens.get("access_token") if isinstance(tokens, dict) else None
+        if not access:
+            msg = "Token endpoint response has no access_token"
+            raise FenixControlResponseError(msg)
+        refresh = tokens.get("refresh_token") or (
+            None if require_refresh else self._refresh_token
+        )
+        if not refresh:
+            msg = "Token endpoint response has no refresh_token"
+            raise FenixControlResponseError(msg)
+        lifetime = float(tokens.get("expires_in") or _DEFAULT_TOKEN_LIFETIME)
+        self._access_token = access
+        self._refresh_token = refresh
+        self._expires_at = time.monotonic() + max(lifetime - TOKEN_EXPIRY_MARGIN, 0)
+
+    @staticmethod
+    def _raise_for_token_status(status: int, what: str) -> None:
+        if status == _HTTP_OK:
+            return
+        msg = f"{what} failed: HTTP {status}"
+        if status in (_HTTP_BAD_REQUEST, _HTTP_UNAUTHORIZED):
+            raise FenixControlAuthError(msg)
+        raise FenixControlResponseError(msg, status)
+
+    async def _refresh(self) -> None:
+        _LOGGER.debug("Refreshing access token")
+        status, _, body = await self._request(
+            "POST",
+            self.token_url,
+            data={
+                "grant_type": "refresh_token",
+                "refresh_token": self._refresh_token,
+                "client_id": self._client_id,
+            },
+        )
+        self._raise_for_token_status(status, "Token refresh")
+        self._store_tokens(body, require_refresh=False)
+
+    def _unexpected(self, step: str, status: int) -> Exception:
+        msg = f"{step}: unexpected HTTP {status}"
+        if status >= _HTTP_SERVER_ERROR:
+            return FenixControlResponseError(msg, status)
+        return FenixControlAuthError(msg)
+
+    def _is_app_redirect(self, url: str) -> bool:
+        return urllib.parse.urlsplit(url).scheme == self._redirect_scheme
+
+    async def _login(self) -> None:
+        _LOGGER.debug("Starting OAuth2 PKCE login")
+        self._access_token = None
+        self._refresh_token = None
+        self._expires_at = 0.0
+        self._session.cookie_jar.clear_domain(
+            urllib.parse.urlsplit(self._identity_url).hostname or ""
+        )
+
+        code_verifier, code_challenge = generate_pkce_pair()
+        state = secrets.token_urlsafe(32)
+        params = {
+            "client_id": self._client_id,
+            "response_type": "code id_token",
+            "scope": self._scopes,
+            "redirect_uri": self._redirect_uri,
+            "nonce": secrets.token_urlsafe(32),
+            "code_challenge": code_challenge,
+            "code_challenge_method": "S256",
+            "state": state,
+            "oemclient": OEM_CLIENT,
+        }
+        authorize_url = (
+            f"{self._identity_url}/connect/authorize?{urllib.parse.urlencode(params)}"
+        )
+        status, headers, _ = await self._request(
+            "GET", authorize_url, allow_redirects=False
+        )
+        location = headers.get("Location")
+        if status != _HTTP_FOUND or not location:
+            raise self._unexpected("Authorization request", status)  # noqa: EM101, TRY003
+        login_url = urllib.parse.urljoin(self._identity_url, location)
+
+        if self._is_app_redirect(login_url):
+            callback_url = login_url  # identity server still had a session
+        else:
+            callback_url = await self._submit_credentials(login_url)
+
+        code = await self._read_authorization_code(callback_url, state)
+
+        status, _, body = await self._request(
+            "POST",
+            self.token_url,
+            headers={"Content-Type": "application/x-www-form-urlencoded"},
+            data={
+                "grant_type": "authorization_code",
+                "code": code,
+                "redirect_uri": self._redirect_uri,
+                "code_verifier": code_verifier,
+                "client_id": self._client_id,
+            },
+        )
+        self._raise_for_token_status(status, "Token exchange")
+        self._store_tokens(body, require_refresh=True)
+        _LOGGER.debug("OAuth2 login completed")
+
+    async def _submit_credentials(self, login_url: str) -> str:
+        status, _, page = await self._request("GET", login_url)
+        if status != _HTTP_OK:
+            raise self._unexpected("Login page", status)  # noqa: EM101, TRY003
+        form = parse_login_form(page)
+        if form is None:
+            msg = "Login form not found on identity server page"
+            raise FenixControlResponseError(msg, status)
+        csrf_token, return_url = form
+
+        status, headers, _ = await self._request(
+            "POST",
+            login_url,
+            data={
+                "ReturnUrl": return_url,
+                "Username": self._username,
+                "Password": self._password,
+                "button": "login",
+                _CSRF_FIELD: csrf_token,
+            },
+            allow_redirects=False,
+        )
+        location = headers.get("Location")
+        if status == _HTTP_FOUND and location:
+            return urllib.parse.urljoin(self._identity_url, location)
+        if status == _HTTP_OK:
+            # The login page is rendered again with a validation message.
+            msg = "Invalid username or password"
+            raise FenixControlAuthError(msg)
+        raise self._unexpected("Login form submission", status)  # noqa: EM101, TRY003
+
+    async def _read_authorization_code(self, callback_url: str, state: str) -> str:
+        if not self._is_app_redirect(callback_url):
+            # /connect/authorize/callback answers with a redirect to the app URI.
+            _, headers, _ = await self._request(
+                "GET", callback_url, allow_redirects=False
+            )
+            callback_url = headers.get("Location", callback_url)
+
+        fragment = urllib.parse.parse_qs(urllib.parse.urlsplit(callback_url).fragment)
+        code = fragment.get("code", [None])[0]
+        id_token = fragment.get("id_token", [None])[0]
+        returned_state = fragment.get("state", [None])[0]
+        if returned_state != state:
+            msg = "OAuth2 state mismatch in authorization response"
+            raise FenixControlAuthError(msg)
+        if not code or not id_token:
+            msg = "Authorization response is missing code or id_token"
+            raise FenixControlAuthError(msg)
+        return code

pyfenixcontrol/client.py

@@ -0,0 +1,356 @@
+"""Asynchronous client for the FENIX Control cloud API."""
+
+from __future__ import annotations
+
+import asyncio
+import json
+import logging
+from datetime import UTC, datetime
+from typing import TYPE_CHECKING, Any
+
+import aiohttp
+
+from .const import (
+    API_BASE_URL,
+    DEFAULT_MAX_RETRIES,
+    DEFAULT_REQUEST_TIMEOUT,
+    HOLIDAY_EPOCH_DATE,
+    IDENTITY_BASE_URL,
+    EnergyPeriod,
+    HolidayMode,
+    PresetMode,
+)
+from .exceptions import (
+    FenixControlAuthError,
+    FenixControlConnectionError,
+    FenixControlError,
+    FenixControlResponseError,
+)
+from .models import (
+    Device,
+    EnergyMetric,
+    Installation,
+    encode_temperature,
+    format_holiday_date,
+)
+
+if TYPE_CHECKING:
+    from .auth import AbstractAuth
+
+_LOGGER = logging.getLogger(__name__)
+
+_HTTP_OK = 200
+_HTTP_NO_CONTENT = 204
+_HTTP_SUCCESS_MAX = 300
+_HTTP_UNAUTHORIZED = 401
+_HTTP_SERVER_ERROR = 500
+
+#: Error bodies may echo account identifiers; only log a short prefix at debug.
+_BODY_LOG_LIMIT = 256
+
+_CONFIG_REPLACE_PATH = "/iotmanagement/v1/devices/twin/properties/config/replace"
+_INSTALLATION_JOB_PATH = "/iotmanagement/v1/devices/installationcontroljob"
+
+
+def _format_api_date(value: datetime) -> str:
+    """Format a datetime for consumption endpoints (UTC, naive values = UTC)."""
+    utc = value.replace(tzinfo=UTC) if value.tzinfo is None else value.astimezone(UTC)
+    return utc.strftime("%Y-%m-%dT%H:%M:%S.%fZ")
+
+
+class FenixControlClient:
+    """Client for FENIX TFT WiFi thermostats via the FENIX Control cloud.
+
+    All network access goes through ``auth.session``; the client owns no
+    resources and needs no explicit close.
+    """
+
+    def __init__(
+        self,
+        auth: AbstractAuth,
+        *,
+        api_url: str = API_BASE_URL,
+        identity_url: str = IDENTITY_BASE_URL,
+        request_timeout: float = DEFAULT_REQUEST_TIMEOUT,
+        max_retries: int = DEFAULT_MAX_RETRIES,
+    ) -> None:
+        """Initialize the client.
+
+        ``max_retries`` applies to HTTP 5xx responses only, with exponential
+        backoff (1 s, 2 s, ...). Client errors are never retried; a single
+        HTTP 401 triggers one token refresh and a retry.
+        """
+        self._auth = auth
+        self._api_url = api_url.rstrip("/")
+        self._identity_url = identity_url.rstrip("/")
+        self._timeout = aiohttp.ClientTimeout(total=request_timeout)
+        self._max_retries = max_retries
+        self._user_id: str | None = None
+
+    @property
+    def user_id(self) -> str | None:
+        """Account subject id (``sub``), available after :meth:`get_user_id`."""
+        return self._user_id
+
+    # -- transport ---------------------------------------------------------
+
+    async def _request(
+        self,
+        method: str,
+        url: str,
+        *,
+        json_body: dict[str, Any] | None = None,
+        empty_on_no_content: bool = False,
+    ) -> Any:
+        """Send an authenticated request and return the decoded JSON body."""
+        auth_retried = False
+        attempt = 0
+        while True:
+            token = await self._auth.async_get_access_token()
+            headers = {"Authorization": f"Bearer {token}", "Accept": "application/json"}
+            try:
+                async with self._auth.session.request(
+                    method,
+                    url,
+                    headers=headers,
+                    json=json_body,
+                    timeout=self._timeout,
+                    allow_redirects=False,
+                ) as resp:
+                    status = resp.status
+                    body = await resp.text()
+            except (aiohttp.ClientError, TimeoutError) as err:
+                msg = f"Error communicating with FENIX cloud: {err}"
+                raise FenixControlConnectionError(msg) from err
+
+            if _HTTP_OK <= status < _HTTP_SUCCESS_MAX:
+                if status == _HTTP_NO_CONTENT or not body:
+                    return [] if empty_on_no_content else None
+                try:
+                    return json.loads(body)
+                except ValueError as err:
+                    msg = f"{method} {url}: invalid JSON response"
+                    raise FenixControlResponseError(msg, status) from err
+
+            _LOGGER.debug(
+                "%s %s -> HTTP %s: %s", method, url, status, body[:_BODY_LOG_LIMIT]
+            )
+
+            if status == _HTTP_UNAUTHORIZED:
+                if auth_retried:
+                    msg = f"{method} {url}: HTTP 401 with a fresh token"
+                    raise FenixControlAuthError(msg)
+                auth_retried = True
+                await self._auth.async_invalidate_access_token()
+                continue
+
+            if status >= _HTTP_SERVER_ERROR and attempt < self._max_retries:
+                delay = 2**attempt
+                attempt += 1
+                _LOGGER.debug(
+                    "HTTP %s, retry %d/%d in %ds",
+                    status,
+                    attempt,
+                    self._max_retries,
+                    delay,
+                )
+                await asyncio.sleep(delay)
+                continue
+
+            msg = f"{method} {url}: HTTP {status}"
+            raise FenixControlResponseError(msg, status)
+
+    async def _get(self, path: str, *, empty_on_no_content: bool = False) -> Any:
+        return await self._request(
+            "GET", f"{self._api_url}{path}", empty_on_no_content=empty_on_no_content
+        )
+
+    async def _put(self, path: str, body: dict[str, Any]) -> Any:
+        return await self._request("PUT", f"{self._api_url}{path}", json_body=body)
+
+    async def _require_user_id(self) -> str:
+        return self._user_id or await self.get_user_id()
+
+    # -- account & topology ------------------------------------------------
+
+    async def get_user_id(self) -> str:
+        """Fetch and cache the account subject id from OIDC ``userinfo``."""
+        data = await self._request("GET", f"{self._identity_url}/connect/userinfo")
+        sub = data.get("sub") if isinstance(data, dict) else None
+        if not sub:
+            msg = "userinfo response has no 'sub'"
+            raise FenixControlResponseError(msg)
+        self._user_id = str(sub)
+        return self._user_id
+
+    async def get_installations(self) -> list[Installation]:
+        """Return the installations (homes) the account administers."""
+        user_id = await self._require_user_id()
+        data = await self._get(
+            f"/businessmodule/v1/installations/admins/{user_id}",
+            empty_on_no_content=True,
+        )
+        if not isinstance(data, list):
+            msg = "installations response is not a list"
+            raise FenixControlResponseError(msg)
+        return [Installation.from_api(i) for i in data if isinstance(i, dict)]
+
+    async def get_device_properties(self, device_id: str) -> dict[str, Any]:
+        """Return the raw device twin properties of one thermostat."""
+        data = await self._get(
+            f"/iotmanagement/v1/configuration/{device_id}/{device_id}/v1/content/"
+        )
+        if not isinstance(data, dict):
+            msg = f"properties of device {device_id} are not an object"
+            raise FenixControlResponseError(msg)
+        return data
+
+    async def get_devices(
+        self, installations: list[Installation] | None = None
+    ) -> list[Device]:
+        """Return the state of every thermostat.
+
+        A device whose properties cannot be fetched is skipped (and logged);
+        authentication and connection errors are raised, since they affect
+        the whole account.
+        """
+        if installations is None:
+            installations = await self.get_installations()
+        devices: list[Device] = []
+        for installation in installations:
+            for room in installation.rooms:
+                for device_id in room.device_ids:
+                    try:
+                        props = await self.get_device_properties(device_id)
+                    except (FenixControlAuthError, FenixControlConnectionError):
+                        raise
+                    except FenixControlError as err:
+                        _LOGGER.warning("Skipping device %s: %s", device_id, err)
+                        continue
+                    devices.append(
+                        Device.from_api(device_id, props, installation, room)
+                    )
+        return devices
+
+    async def trigger_installation_update(self, installation_id: str) -> None:
+        """Ask the thermostats of an installation to report fresh values.
+
+        This is what the app sends when it is opened ("user connected").
+        """
+        await self._put(
+            "/iotmanagement/v1/devices/userconnected",
+            {"A1": await self._require_user_id(), "In": installation_id},
+        )
+
+    # -- control -----------------------------------------------------------
+
+    async def set_target_temperature(self, device_id: str, celsius: float) -> None:
+        """Set the target temperature (°C); switches the device to manual."""
+        await self._put(
+            _CONFIG_REPLACE_PATH,
+            {
+                "Id_deviceId": device_id,
+                "S1": device_id,
+                "configurationVersion": "v1.0",
+                "data": [
+                    {"wattsType": "Dm", "wattsTypeValue": int(PresetMode.MANUAL)},
+                    {"wattsType": "Ma", "wattsTypeValue": encode_temperature(celsius)},
+                ],
+            },
+        )
+
+    async def set_preset_mode(self, device_id: str, mode: PresetMode | int) -> None:
+        """Set the operating mode of a thermostat."""
+        try:
+            mode = PresetMode(mode)
+        except ValueError as err:
+            msg = f"Invalid preset mode: {mode}"
+            raise ValueError(msg) from err
+        await self._put(
+            _CONFIG_REPLACE_PATH,
+            {
+                "Id_deviceId": device_id,
+                "S1": device_id,
+                "configurationVersion": "v1.0",
+                "data": [{"wattsType": "Dm", "wattsTypeValue": int(mode)}],
+            },
+        )
+
+    async def set_holiday_schedule(
+        self,
+        installation_id: str,
+        start: datetime,
+        end: datetime,
+        mode: HolidayMode | int,
+    ) -> None:
+        """Schedule a holiday for a whole installation.
+
+        ``start``/``end`` are written as wall-clock time of the installation;
+        pass naive or local datetimes, they are not converted.
+        """
+        mode = HolidayMode(mode)
+        if mode is HolidayMode.NONE:
+            msg = "Use cancel_holiday_schedule() to clear a holiday"
+            raise ValueError(msg)
+        if end <= start:
+            msg = "Holiday end must be after start"
+            raise ValueError(msg)
+        await self._put_holiday(
+            installation_id,
+            format_holiday_date(start),
+            format_holiday_date(end),
+            int(mode),
+        )
+
+    async def cancel_holiday_schedule(self, installation_id: str) -> None:
+        """Remove the holiday schedule of an installation."""
+        await self._put_holiday(
+            installation_id, HOLIDAY_EPOCH_DATE, HOLIDAY_EPOCH_DATE, 0
+        )
+
+    async def _put_holiday(
+        self, installation_id: str, start: str, end: str, mode: int
+    ) -> None:
+        await self._put(
+            _INSTALLATION_JOB_PATH,
+            {
+                "In": installation_id,
+                "A1": await self._require_user_id(),
+                "data": [
+                    {"timestamp": None, "wattsType": "H1", "wattsTypeValue": start},
+                    {"timestamp": None, "wattsType": "H2", "wattsTypeValue": end},
+                    {
+                        "timestamp": None,
+                        "wattsType": "H3",
+                        "wattsTypeValue": [mode, 0, 0],
+                    },
+                ],
+            },
+        )
+
+    # -- energy ------------------------------------------------------------
+
+    async def get_room_energy(
+        self,
+        installation_id: str,
+        room_id: str,
+        start: datetime,
+        end: datetime,
+        period: EnergyPeriod | str = EnergyPeriod.HOUR,
+    ) -> list[EnergyMetric]:
+        """Return energy consumption (Wh) of a room between ``start`` and ``end``.
+
+        Datetimes are converted to UTC; naive values are taken as UTC.
+        """
+        user_id = await self._require_user_id()
+        period = EnergyPeriod(period)
+        data = await self._get(
+            "/DataProcessing/v1/metricsAggregat/consommation/room/"
+            f"{installation_id}/{room_id}/{user_id}/{period.value}/Wc/"
+            f"{_format_api_date(start)}/{_format_api_date(end)}",
+            empty_on_no_content=True,
+        )
+        if not isinstance(data, list):
+            msg = "energy response is not a list"
+            raise FenixControlResponseError(msg)
+        return [EnergyMetric.from_api(item) for item in data if isinstance(item, dict)]

pyfenixcontrol/const.py

@@ -0,0 +1,75 @@
+"""Constants and enumerations for the FENIX Control cloud API."""
+
+from __future__ import annotations
+
+from enum import IntEnum, StrEnum
+from typing import Final
+
+API_BASE_URL: Final = "https://vs2-fe-apim-prod.azure-api.net"
+IDENTITY_BASE_URL: Final = "https://vs2-fe-identity-prod.azurewebsites.net"
+
+# Public OAuth2 client of the FENIX Control mobile app (PKCE, no secret).
+# Pass your own ``client_id`` to :class:`~pyfenixcontrol.PasswordAuth` once a
+# dedicated client is issued.
+DEFAULT_CLIENT_ID: Final = "b1760b2e-69f1-4e89-8233-5840a9accdf8"
+DEFAULT_REDIRECT_URI: Final = "fenix://callback"
+OEM_CLIENT: Final = "fenix"
+DEFAULT_SCOPES: Final = (
+    "profile openid offline_access "
+    "DataProcessing.Read DataProcessing.Write "
+    "Device.Read Device.Write "
+    "Installation.Read Installation.Write "
+    "IOTManagement.Read IOTManagement.Write "
+    "Room.Read Room.Write "
+    "TermOfUse.Read TermOfUse.Write"
+)
+
+DEFAULT_REQUEST_TIMEOUT: Final = 10.0
+DEFAULT_MAX_RETRIES: Final = 2
+
+# Sentinel the backend uses in H1/H2 for "no holiday schedule". Not a valid date.
+HOLIDAY_EPOCH_DATE: Final = "00/00/1970 00:00:00"
+HOLIDAY_DATE_FORMAT: Final = "%d/%m/%Y %H:%M:%S"
+
+#: Divisor applied to raw temperature values when none is given by the API.
+DEFAULT_DIV_FACTOR: Final = 10
+
+
+class PresetMode(IntEnum):
+    """Operating mode of a thermostat (``Cm`` read / ``Dm`` write)."""
+
+    OFF = 0
+    HOLIDAYS = 1
+    PROGRAM = 2
+    DEFROST = 4
+    BOOST = 5
+    MANUAL = 6
+
+
+class HvacState(IntEnum):
+    """Heating state reported in ``Hs`` outside holiday mode."""
+
+    IDLE = 0
+    HEATING = 1
+    OFF = 2
+
+
+class HolidayMode(IntEnum):
+    """Holiday behaviour of an installation (``H3[0]`` / ``H4``)."""
+
+    NONE = 0
+    OFF = 1
+    REDUCE = 2
+    DEFROST = 5
+    SUNDAY = 8
+
+
+class EnergyPeriod(StrEnum):
+    """Aggregation period of the energy consumption endpoint."""
+
+    HOUR = "Hour"
+    DAY = "Day"
+    WEEK = "Week"
+    MONTH = "Month"
+    QUARTER = "Quarter"
+    YEAR = "Year"

pyfenixcontrol/exceptions.py

@@ -0,0 +1,27 @@
+"""Exceptions raised by pyfenixcontrol."""
+
+from __future__ import annotations
+
+
+class FenixControlError(Exception):
+    """Base class for all pyfenixcontrol errors."""
+
+
+class FenixControlConnectionError(FenixControlError):
+    """The cloud could not be reached (network error, timeout, DNS)."""
+
+
+class FenixControlAuthError(FenixControlError):
+    """Authentication failed or the credentials/tokens are no longer valid.
+
+    Callers should treat this as "user action required" (e.g. a reauth flow).
+    """
+
+
+class FenixControlResponseError(FenixControlError):
+    """The cloud returned an unexpected status or an unparsable body."""
+
+    def __init__(self, message: str, status: int | None = None) -> None:
+        """Initialize with an optional HTTP status code."""
+        super().__init__(message)
+        self.status = status

pyfenixcontrol/models.py

@@ -0,0 +1,230 @@
+"""Data models returned by :class:`~pyfenixcontrol.FenixControlClient`."""
+
+from __future__ import annotations
+
+from dataclasses import dataclass, field
+from datetime import UTC, datetime
+from typing import TYPE_CHECKING, Any
+
+from .const import DEFAULT_DIV_FACTOR, HOLIDAY_DATE_FORMAT, HOLIDAY_EPOCH_DATE
+
+if TYPE_CHECKING:
+    from collections.abc import Mapping
+
+
+def decode_temperature(entry: Mapping[str, Any] | None) -> float | None:
+    """Decode a ``{"value", "divFactor"}`` entry (°F x divFactor) to °C."""
+    if not entry:
+        return None
+    value = entry.get("value")
+    if not isinstance(value, int | float) or isinstance(value, bool):
+        return None
+    div = entry.get("divFactor") or 1
+    fahrenheit = value / div
+    return (fahrenheit - 32.0) * 5.0 / 9.0
+
+
+def encode_temperature(celsius: float, div_factor: int = DEFAULT_DIV_FACTOR) -> int:
+    """Encode °C to the raw API value (°F x divFactor, rounded)."""
+    return round((celsius * 9.0 / 5.0 + 32.0) * div_factor)
+
+
+def parse_holiday_date(value: str | None) -> datetime | None:
+    """Parse a holiday ``H1``/``H2`` string to a naive local datetime.
+
+    The backend stores holiday dates in the installation's local time without
+    an offset. Returns ``None`` for the "no holiday" sentinel or invalid input.
+    """
+    if not value or value == HOLIDAY_EPOCH_DATE:
+        return None
+    try:
+        return datetime.strptime(value, HOLIDAY_DATE_FORMAT)  # noqa: DTZ007
+    except (TypeError, ValueError):
+        return None
+
+
+def format_holiday_date(value: datetime) -> str:
+    """Format a datetime for the holiday ``H1``/``H2`` fields."""
+    return value.strftime(HOLIDAY_DATE_FORMAT)
+
+
+def _prop(props: Mapping[str, Any], key: str) -> Any:
+    entry = props.get(key)
+    if isinstance(entry, dict):
+        return entry.get("value")
+    return None
+
+
+def _as_int(value: Any) -> int | None:
+    if isinstance(value, bool):
+        return None
+    if isinstance(value, int):
+        return value
+    if isinstance(value, float) and value.is_integer():
+        return int(value)
+    return None
+
+
+def _as_str(value: Any) -> str | None:
+    return value if isinstance(value, str) else None
+
+
+@dataclass(frozen=True, slots=True)
+class Room:
+    """A room (``Zn``) of an installation and the thermostats in it."""
+
+    id: str
+    name: str | None
+    device_ids: tuple[str, ...]
+
+    @classmethod
+    def from_api(cls, data: Mapping[str, Any]) -> Room:
+        """Build from an entry of an installation's ``rooms`` list."""
+        devices = data.get("devices") or []
+        return cls(
+            id=str(data.get("Zn", "")),
+            name=_as_str(data.get("Rn")),
+            device_ids=tuple(
+                str(dev["Id_deviceId"])
+                for dev in devices
+                if isinstance(dev, dict) and dev.get("Id_deviceId")
+            ),
+        )
+
+
+@dataclass(frozen=True, slots=True)
+class Installation:
+    """An installation (home) the account administers."""
+
+    id: str
+    name: str | None
+    rooms: tuple[Room, ...]
+    raw: Mapping[str, Any] = field(repr=False, compare=False)
+
+    @classmethod
+    def from_api(cls, data: Mapping[str, Any]) -> Installation:
+        """Build from an entry of ``/installations/admins/{sub}``."""
+        rooms = data.get("rooms") or []
+        return cls(
+            id=str(data.get("id", "")),
+            name=_as_str(data.get("Il")),
+            rooms=tuple(Room.from_api(r) for r in rooms if isinstance(r, dict)),
+            raw=data,
+        )
+
+
+@dataclass(frozen=True, slots=True)
+class Device:
+    """Current state of one thermostat.
+
+    Field reference (property keys of the device twin):
+
+    * ``Cm`` - preset mode, see :class:`~pyfenixcontrol.PresetMode`
+    * ``Hs`` - heating state (:class:`~pyfenixcontrol.HvacState`); while in
+      holiday mode it carries the holiday mode instead
+    * ``H1``/``H2`` - holiday start/end, ``H3[0]`` - scheduled holiday mode,
+      ``H4`` - currently active holiday mode (primary holiday indicator)
+    * ``Ma`` - target, ``At`` - room, ``bo`` - floor, ``Sp`` - holiday target
+      temperature
+    """
+
+    id: str
+    name: str | None
+    installation_id: str
+    installation_name: str | None
+    room_id: str
+    software_version: str | None
+    model: str | None
+    target_temperature: float | None
+    room_temperature: float | None
+    floor_temperature: float | None
+    holiday_target_temperature: float | None
+    preset_mode: int | None
+    hvac_state: int | None
+    holiday_start: str | None
+    holiday_end: str | None
+    holiday_mode: int
+    active_holiday_mode: int
+    raw: Mapping[str, Any] = field(repr=False, compare=False)
+
+    @classmethod
+    def from_api(
+        cls,
+        device_id: str,
+        props: Mapping[str, Any],
+        installation: Installation,
+        room: Room,
+    ) -> Device:
+        """Build from the device twin ``content`` properties."""
+        h3 = _prop(props, "H3")
+        holiday_mode = _as_int(h3[0]) if isinstance(h3, list) and h3 else None
+        name = _prop(props, "Rn")
+        return cls(
+            id=device_id,
+            name=_as_str(name),
+            installation_id=installation.id,
+            installation_name=installation.name,
+            room_id=room.id,
+            software_version=_as_str(_prop(props, "Sv")),
+            model=None if _prop(props, "Ty") is None else str(_prop(props, "Ty")),
+            target_temperature=decode_temperature(props.get("Ma")),
+            room_temperature=decode_temperature(props.get("At")),
+            floor_temperature=decode_temperature(props.get("bo")),
+            holiday_target_temperature=decode_temperature(props.get("Sp")),
+            preset_mode=_as_int(_prop(props, "Cm")),
+            hvac_state=_as_int(_prop(props, "Hs")),
+            holiday_start=_as_str(_prop(props, "H1")),
+            holiday_end=_as_str(_prop(props, "H2")),
+            holiday_mode=holiday_mode or 0,
+            active_holiday_mode=_as_int(_prop(props, "H4")) or 0,
+            raw=props,
+        )
+
+    @property
+    def holiday_end_date(self) -> datetime | None:
+        """Holiday end as naive local datetime, ``None`` if not scheduled."""
+        return parse_holiday_date(self.holiday_end)
+
+    @property
+    def holiday_active(self) -> bool:
+        """Return True while a holiday mode is in effect (``H4`` != 0)."""
+        return self.active_holiday_mode != 0
+
+
+@dataclass(frozen=True, slots=True)
+class EnergyMetric:
+    """One aggregated energy consumption bucket of a room (Wh)."""
+
+    start: datetime | None
+    value: float
+    processed_value: float
+    raw: Mapping[str, Any] = field(repr=False, compare=False)
+
+    @classmethod
+    def from_api(cls, data: Mapping[str, Any]) -> EnergyMetric:
+        """Build from an item of the ``metricsAggregat/consommation`` endpoint."""
+        start: datetime | None = None
+        start_raw = data.get("startDateOfMetric")
+        if isinstance(start_raw, str):
+            try:
+                start = datetime.fromisoformat(start_raw)
+            except ValueError:
+                start = None
+            else:
+                start = (
+                    start.replace(tzinfo=UTC)
+                    if start.tzinfo is None
+                    else start.astimezone(UTC)
+                )
+        return cls(
+            start=start,
+            value=_as_float(data.get("sum")),
+            processed_value=_as_float(data.get("processedDataWithAggregator")),
+            raw=data,
+        )
+
+
+def _as_float(value: Any) -> float:
+    if isinstance(value, bool) or not isinstance(value, int | float):
+        return 0.0
+    return float(value)

pyfenixcontrol-0.1.0.dist-info/METADATA

@@ -0,0 +1,145 @@
+Metadata-Version: 2.5
+Name: pyfenixcontrol
+Version: 0.1.0
+Summary: Asynchronous Python client for the FENIX Control cloud API (FENIX TFT WiFi thermostats).
+Project-URL: Homepage, https://github.com/baracudaz/pyfenixcontrol
+Project-URL: Source, https://github.com/baracudaz/pyfenixcontrol
+Project-URL: Issues, https://github.com/baracudaz/pyfenixcontrol/issues
+Project-URL: Changelog, https://github.com/baracudaz/pyfenixcontrol/blob/main/CHANGELOG.md
+Author-email: Stanislav Likavčan <likavcan@gmail.com>
+License-Expression: MIT
+License-File: LICENSE
+Keywords: asyncio,fenix,fenix control,home assistant,tft,thermostat
+Classifier: Development Status :: 4 - Beta
+Classifier: Framework :: AsyncIO
+Classifier: Intended Audience :: Developers
+Classifier: Operating System :: OS Independent
+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 :: Home Automation
+Classifier: Typing :: Typed
+Requires-Python: >=3.12
+Requires-Dist: aiohttp>=3.9.0
+Description-Content-Type: text/markdown
+
+# pyfenixcontrol
+
+Asynchronous Python client for the **FENIX Control** cloud, used by FENIX TFT WiFi
+thermostats. It powers the FENIX integration for [Home Assistant](https://www.home-assistant.io/),
+but has no Home Assistant dependency and can be used from any asyncio code.
+
+- Fully typed (`py.typed`), `asyncio` + `aiohttp`, Python 3.12+
+- Read thermostats, rooms and installations; set target temperature and operating mode
+- Installation-wide holiday schedules
+- Room energy consumption at hourly … yearly aggregation
+- Pluggable authentication: bundled e-mail/password login, or bring your own OAuth2 tokens
+- Automatic token refresh, single retry on HTTP 401, backoff on HTTP 5xx
+
+## Installation
+
+```bash
+pip install pyfenixcontrol
+```
+
+## Quick start
+
+```python
+import asyncio
+
+import aiohttp
+
+from pyfenixcontrol import FenixControlClient, PasswordAuth, PresetMode
+
+
+async def main() -> None:
+    async with aiohttp.ClientSession() as session:
+        auth = PasswordAuth(session, "you@example.com", "password")
+        client = FenixControlClient(auth)
+
+        for device in await client.get_devices():
+            print(device.name, device.room_temperature, device.target_temperature)
+
+        await client.set_target_temperature(device.id, 21.5)
+        await client.set_preset_mode(device.id, PresetMode.PROGRAM)
+
+
+asyncio.run(main())
+```
+
+## Authentication
+
+The client never sees credentials. It asks an `AbstractAuth` for a bearer token:
+
+```python
+from pyfenixcontrol import AbstractAuth
+
+
+class MyAuth(AbstractAuth):
+    async def async_get_access_token(self) -> str:
+        return await my_token_store.get_valid_token()
+
+    async def async_invalidate_access_token(self) -> None:
+        # Called after an HTTP 401; optional.
+        await my_token_store.mark_expired()
+```
+
+`PasswordAuth` performs the OAuth2 authorization-code + PKCE login used by the
+FENIX Control app and keeps tokens in memory. `await auth.async_login()` validates
+credentials up front (e.g. in a setup wizard).
+
+`PasswordAuth` needs an `aiohttp` session with a working cookie jar, because the
+identity server tracks its login form with cookies. Cookies of the identity host
+are cleared before each full login.
+
+## API overview
+
+| Method | Description |
+|---|---|
+| `get_user_id()` | Account subject id (cached on the client) |
+| `get_installations()` | Installations (homes) with their rooms and device ids |
+| `get_devices(installations=None)` | `Device` state of every thermostat |
+| `get_device_properties(device_id)` | Raw device twin properties |
+| `trigger_installation_update(installation_id)` | Ask thermostats to report fresh values |
+| `set_target_temperature(device_id, celsius)` | Set target °C (switches to manual) |
+| `set_preset_mode(device_id, mode)` | `PresetMode.OFF / PROGRAM / MANUAL / DEFROST / BOOST / HOLIDAYS` |
+| `set_holiday_schedule(installation_id, start, end, mode)` | Holiday for the whole installation |
+| `cancel_holiday_schedule(installation_id)` | Remove the holiday schedule |
+| `get_room_energy(installation_id, room_id, start, end, period)` | `EnergyMetric` buckets in Wh |
+
+### Errors
+
+| Exception | Meaning |
+|---|---|
+| `FenixControlAuthError` | Credentials or tokens rejected – user action needed |
+| `FenixControlConnectionError` | Network error or timeout – retry later |
+| `FenixControlResponseError` | Unexpected status or body (`.status` holds the HTTP code) |
+
+All inherit from `FenixControlError`.
+
+### Units and conventions
+
+- Temperatures are °C. The API transports °F × `divFactor`;
+  `decode_temperature()` / `encode_temperature()` convert.
+- Holiday `start`/`end` are wall-clock times of the installation (no time zone
+  conversion). Energy queries convert to UTC; naive datetimes are taken as UTC.
+- Every model keeps the original payload in `.raw` for fields not yet modelled.
+
+## Development
+
+```bash
+uv sync
+uv run pytest --cov
+uv run ruff check . && uv run ruff format --check . && uv run mypy
+```
+
+Tests run against a local fake of the cloud and identity server; no account is needed.
+
+Releases: bump `__version__`, update `CHANGELOG.md`, publish a GitHub release
+tagged `vX.Y.Z`. The release workflow publishes to PyPI via trusted publishing.
+
+## License
+
+MIT – see [LICENSE](LICENSE). Not an official product of FENIX Trading s.r.o.
+unless stated otherwise in the project metadata.

pyfenixcontrol-0.1.0.dist-info/RECORD

@@ -0,0 +1,11 @@
+pyfenixcontrol/__init__.py,sha256=0AL_EG4g_h6KByDtlGe5orpC0NJAIMW2T8cXCslhu4s,1014
+pyfenixcontrol/auth.py,sha256=qaay2tA5Lwk81765HBy2I5bOu1lujxZ151m0rvTj-yk,14045
+pyfenixcontrol/client.py,sha256=rYIPoopYoUWpFWkFzh-ZzJp7QVD0z2_BG1cYCrJFbBI,12931
+pyfenixcontrol/const.py,sha256=7IAx6SweSuB42xyEtREwpvRUq5br8GsYVpNMUBxpGYA,1996
+pyfenixcontrol/exceptions.py,sha256=Cin8gvEHMtUYGNnupJBe-ZwjcKdJfW77IVFFaq6DW0A,834
+pyfenixcontrol/models.py,sha256=p5MtJO--i1XcpcZMIfHK1_q-ntXTodOeBqoaqEU32QM,7627
+pyfenixcontrol/py.typed,sha256=47DEQpj8HBSa-_TImW-5JCeuQeRkm5NMpJWZG3hSuFU,0
+pyfenixcontrol-0.1.0.dist-info/METADATA,sha256=SENxfEH7WXfjy_L7SmIsVtqUkRNvJVlZxiIzg_TnHHM,5497
+pyfenixcontrol-0.1.0.dist-info/WHEEL,sha256=W3fkpkm7-wf9vBI5Z-7s0eWkeM-spu78I8Neb98DeEg,87
+pyfenixcontrol-0.1.0.dist-info/licenses/LICENSE,sha256=pMqdasdX58PScxBDpEviSCkbDtikyx-JCqBzqutD95k,1081
+pyfenixcontrol-0.1.0.dist-info/RECORD,,

pyfenixcontrol-0.1.0.dist-info/WHEEL

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

pyfenixcontrol-0.1.0.dist-info/licenses/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2025-2026 Stanislav Likavčan
+
+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.