dimplex-controller 0.2.1__tar.gz → 0.4.0__tar.gz

{dimplex_controller-0.2.1 → dimplex_controller-0.4.0}/PKG-INFO

@@ -1,6 +1,6 @@
 Metadata-Version: 2.4
 Name: dimplex-controller
-Version: 0.2.1
+Version: 0.4.0
 Summary: Python client for Dimplex heating controllers (GDHV IoT)
 License: MIT
 License-File: LICENSE

{dimplex_controller-0.2.1 → dimplex_controller-0.4.0}/dimplex_controller/__init__.py

@@ -2,7 +2,8 @@
 
 from .client import DimplexControl
 from .exceptions import DimplexApiError, DimplexAuthError, DimplexConnectionError, DimplexError
-from .models import Appliance, ApplianceModeSettings, ApplianceStatus, Hub, Zone
+from .models import Appliance, ApplianceModeSettings, ApplianceStatus, Hub, TsiEnergyReport, Zone
+from .telemetry import parse_telemetry_points
 
 __all__ = [
     "DimplexControl",
@@ -11,6 +12,8 @@ __all__ = [
     "Appliance",
     "ApplianceStatus",
     "ApplianceModeSettings",
+    "TsiEnergyReport",
+    "parse_telemetry_points",
     "DimplexError",
     "DimplexApiError",
     "DimplexAuthError",

dimplex_controller-0.4.0/dimplex_controller/auth.py

@@ -0,0 +1,329 @@
+import json
+import logging
+import os
+import re
+import time
+from urllib.parse import parse_qs, urlparse
+
+import aiohttp
+
+from .const import (
+    AUTH_URL,
+    B2C_POLICY,
+    CLIENT_ID,
+    HTTP_OK,
+    REDIRECT_URI,
+    SCOPE,
+)
+from .exceptions import DimplexAuthError
+
+_LOGGER = logging.getLogger(__name__)
+
+
+class AuthManager:
+    """Manages authentication for Dimplex Control."""
+
+    def __init__(self, session: aiohttp.ClientSession, token_data: dict | None = None):
+        """Initialize the auth manager."""
+        self._session = session
+        self._access_token: str | None = token_data.get("access_token") if token_data else None
+        self._refresh_token: str | None = token_data.get("refresh_token") if token_data else None
+        self._expires_at: float = token_data.get("expires_at", 0) if token_data else 0
+
+    @property
+    def is_authenticated(self) -> bool:
+        """Check if we have a valid access token."""
+        return self._access_token is not None and time.time() < self._expires_at
+
+    async def get_access_token(self) -> str:
+        """Get a valid access token, refreshing if necessary."""
+        if not self._refresh_token:
+            raise DimplexAuthError("No refresh token available. User must authenticate first.")
+
+        if self.is_authenticated:
+            return self._access_token  # type: ignore[return-value]
+
+        # Token expired or missing, try refresh
+        await self.refresh_tokens()
+        return self._access_token  # type: ignore[return-value]
+
+    async def refresh_tokens(self) -> None:
+        """Refresh the access token using the refresh token."""
+        _LOGGER.debug("Refreshing access token")
+        payload = {
+            "client_id": CLIENT_ID,
+            "grant_type": "refresh_token",
+            "refresh_token": self._refresh_token,
+            "scope": SCOPE,
+            "client_info": "1",
+        }
+
+        async with self._session.post(f"{AUTH_URL}/token", data=payload) as resp:
+            if resp.status != HTTP_OK:
+                text = await resp.text()
+                _LOGGER.error("Failed to refresh token: %s", text)
+                raise DimplexAuthError(f"Failed to refresh token: {resp.status} - {text}")
+
+            data = await resp.json()
+            self._update_tokens(data)
+
+    def _update_tokens(self, data: dict) -> None:
+        """Update internal token state from API response."""
+        self._access_token = data.get("access_token")
+        self._refresh_token = data.get("refresh_token")
+        expires_in = data.get("expires_in", 3600)
+        self._expires_at = time.time() + expires_in - 60  # Buffer 60s
+
+    def get_login_url(self) -> str:
+        """Generate the login URL for the user to visit."""
+        # Note: This is a simplified URL generation.
+        # In a real app, we might need state, nonce, code_challenge (PKCE).
+        # Based on logs, iOS app uses standard OAuth2.
+        # Constructing a URL for manual copy-paste might be tricky if it strictly requires a custom scheme redirect.
+        # But we can try the standard authorize endpoint.
+
+        params = {
+            "client_id": CLIENT_ID,
+            "response_type": "code",
+            "redirect_uri": REDIRECT_URI,
+            "scope": SCOPE,
+            "response_mode": "query",
+        }
+        from urllib.parse import urlencode
+
+        return f"{AUTH_URL}/authorize?{urlencode(params)}"
+
+    async def exchange_code(self, code: str) -> None:
+        """Exchange authorization code for tokens."""
+        payload = {
+            "client_id": CLIENT_ID,
+            "grant_type": "authorization_code",
+            "code": code,
+            "redirect_uri": REDIRECT_URI,
+            "scope": SCOPE,
+        }
+
+        _LOGGER.info(f"Exchanging code for tokens at {AUTH_URL}/token")
+        client_id = payload["client_id"]
+        redirect_uri = payload["redirect_uri"]
+        code_preview = code[:10]
+        _LOGGER.info(f"Payload: client_id={client_id}, redirect_uri={redirect_uri}, " f"code={code_preview}...")
+
+        async with self._session.post(f"{AUTH_URL}/token", data=payload) as resp:
+            _LOGGER.info(f"Token exchange response status: {resp.status}")
+            if resp.status != HTTP_OK:
+                text = await resp.text()
+                _LOGGER.error(f"Token exchange failed: {text}")
+                raise DimplexAuthError(f"Failed to exchange code: {text}")
+
+            data = await resp.json()
+            self._update_tokens(data)
+
+    @staticmethod
+    def _build_cookie_header(cookie_jar, url: str) -> str:
+        """Build an unquoted Cookie header from an aiohttp cookie jar.
+
+        Python's http.cookies wraps values containing +, /, or = in
+        double-quotes, but Azure AD B2C expects raw unquoted values.
+        """
+        filtered = cookie_jar.filter_cookies(url)
+        return "; ".join(f"{m.key}={m.value}" for m in filtered.values())
+
+    @staticmethod
+    def _parse_b2c_login_page(html: str, page_url: str) -> dict:
+        """Extract B2C form fields from the login page HTML.
+
+        Returns a dict with csrf, tx, p, post_url, confirmed_url.
+        Raises DimplexAuthError if required fields cannot be found.
+        """
+        csrf_match = re.search(r'"csrf"\s*:\s*"([^"]+)"', html)
+        if not csrf_match:
+            raise DimplexAuthError("Could not find CSRF token in B2C login page")
+        csrf = csrf_match.group(1)
+
+        tx_match = re.search(r'"transId"\s*:\s*"([^"]+)"', html)
+        if not tx_match:
+            raise DimplexAuthError("Could not find transId in B2C login page")
+        tx = tx_match.group(1)
+
+        # Build base URL by stripping the authorize endpoint.
+        # The B2C login page URL contains /tfp/{tenant}/{policy}/oauth2/v2.0/authorize
+        # and may redirect to /{tenant}/{policy}/oauth2/v2.0/authorize
+        if "/oauth2/v2.0/authorize" in page_url:
+            base_url = page_url.split("/oauth2/v2.0/authorize")[0]
+        else:
+            parsed = urlparse(page_url)
+            base_url = f"{parsed.scheme}://{parsed.netloc}" f"/gdhvb2c.onmicrosoft.com/{B2C_POLICY}"
+
+        return {
+            "csrf": csrf,
+            "tx": tx,
+            "p": B2C_POLICY,
+            "post_url": f"{base_url}/SelfAsserted?tx={tx}&p={B2C_POLICY}",
+            "confirmed_url": (f"{base_url}/api/CombinedSigninAndSignup/confirmed"),
+        }
+
+    async def headless_login(self, email: str, password: str) -> None:
+        """Perform a headless login via Azure AD B2C to obtain tokens.
+
+        Uses direct HTTP credential submission so users don't need to
+        manually extract auth codes from browser network traffic.
+        """
+        jar = aiohttp.CookieJar(unsafe=True)
+        start_url = self.get_login_url()
+
+        async with aiohttp.ClientSession(cookie_jar=jar) as session:
+            # Step 1: GET the auth URI, follow redirects to B2C login page
+            _LOGGER.debug("Fetching B2C login page: %s", start_url)
+            async with session.get(start_url, allow_redirects=True) as resp:
+                login_html = await resp.text()
+                page_url = str(resp.url)
+                if resp.status != HTTP_OK:
+                    raise DimplexAuthError(f"B2C login page returned HTTP {resp.status}")
+
+            # Step 2: Parse the login page for CSRF, transaction ID, policy
+            fields = self._parse_b2c_login_page(login_html, page_url)
+            _LOGGER.debug(
+                "Parsed B2C login page: csrf=%s... tx=%s... p=%s",
+                fields["csrf"][:16],
+                fields["tx"][:40],
+                fields["p"],
+            )
+
+            # Step 3: POST credentials to SelfAsserted endpoint
+            post_data = {
+                "request_type": "RESPONSE",
+                "email": email,
+                "password": password,
+            }
+            parsed_page = urlparse(page_url)
+            origin = f"{parsed_page.scheme}://{parsed_page.netloc}"
+            post_headers = {
+                "X-CSRF-TOKEN": fields["csrf"],
+                "X-Requested-With": "XMLHttpRequest",
+                "Referer": page_url,
+                "Origin": origin,
+                "Accept": "application/json, text/javascript, */*; q=0.01",
+                "Content-Type": "application/x-www-form-urlencoded; charset=UTF-8",
+            }
+
+            # Build an unquoted Cookie header — aiohttp wraps values
+            # containing +/= in double-quotes, but B2C requires raw values.
+            cookie_header = self._build_cookie_header(jar, fields["post_url"])
+            post_headers["Cookie"] = cookie_header
+            _LOGGER.debug("Submitting credentials to %s", fields["post_url"])
+
+            # Use DummyCookieJar so POST response cookies aren't
+            # re-injected with quoted values on the next request.
+            async with aiohttp.ClientSession(
+                cookie_jar=aiohttp.DummyCookieJar(),
+            ) as raw_session:
+                async with raw_session.post(
+                    fields["post_url"],
+                    data=post_data,
+                    headers=post_headers,
+                    allow_redirects=False,
+                ) as resp:
+                    body = await resp.text()
+                    if resp.status != HTTP_OK:
+                        raise DimplexAuthError(f"Credential submission returned HTTP {resp.status}")
+                    try:
+                        resp_data = json.loads(body)
+                        if str(resp_data.get("status")) == "400":
+                            raise DimplexAuthError("Invalid email or password")
+                    except json.JSONDecodeError:
+                        pass
+
+                    # Merge POST response cookies into the cookie header
+                    cookies: dict[str, str] = {}
+                    for part in cookie_header.split("; "):
+                        if "=" in part:
+                            n, v = part.split("=", 1)
+                            cookies[n] = v
+                    for raw_sc in resp.headers.getall("Set-Cookie", []):
+                        sc_pair = raw_sc.split(";", 1)[0]
+                        if "=" in sc_pair:
+                            n, v = sc_pair.split("=", 1)
+                            cookies[n] = v
+                    cookie_header = "; ".join(f"{n}={v}" for n, v in cookies.items())
+
+                # Step 4: GET the confirmed endpoint and follow redirects
+                confirmed_qs = (
+                    f"rememberMe=false" f"&csrf_token={fields['csrf']}" f"&tx={fields['tx']}" f"&p={fields['p']}"
+                )
+                next_url: str = fields["confirmed_url"] + "?" + confirmed_qs
+                confirmed_headers = {"Cookie": cookie_header}
+
+                for _ in range(20):  # max redirect hops
+                    _LOGGER.debug("Following redirect: %s", next_url[:120])
+                    async with raw_session.get(
+                        next_url,
+                        headers=confirmed_headers,
+                        allow_redirects=False,
+                    ) as resp:
+                        resp_body = await resp.text()
+                        if resp.status in (301, 302, 303, 307, 308):
+                            location = resp.headers.get("Location", "")
+                            if not location:
+                                raise DimplexAuthError("Redirect without Location header")
+                            if location.startswith(REDIRECT_URI) and (
+                                len(location) == len(REDIRECT_URI) or location[len(REDIRECT_URI)] in ("?", "/")
+                            ):
+                                _LOGGER.debug(
+                                    "Captured redirect with code: %s...",
+                                    location[:120],
+                                )
+                                parsed = urlparse(location)
+                                query = parse_qs(parsed.query)
+                                code = query.get("code", [""])[0]
+                                if not code:
+                                    raise DimplexAuthError("Redirect URL missing auth code")
+                                await self.exchange_code(code)
+                                return
+                            if not location.startswith("http"):
+                                location = (
+                                    f"{parsed_page.scheme}://{parsed_page.netloc}" + location
+                                    if location.startswith("/")
+                                    else location
+                                )
+                            next_url = location
+                            continue
+                        if resp.status == HTTP_OK:
+                            redirect_match = re.search(
+                                rf"({re.escape(REDIRECT_URI)}\?[^\s\"'<]+)",
+                                resp_body,
+                            )
+                            if redirect_match:
+                                parsed = urlparse(redirect_match.group(1))
+                                query = parse_qs(parsed.query)
+                                code = query.get("code", [""])[0]
+                                if code:
+                                    await self.exchange_code(code)
+                                    return
+                            raise DimplexAuthError("Reached 200 response without finding redirect URL")
+                        raise DimplexAuthError(f"Unexpected HTTP {resp.status} during redirect chain")
+
+            raise DimplexAuthError("Exceeded maximum redirect hops without capturing auth code")
+
+    def save_tokens(self, file_path: str) -> None:
+        """Save current tokens to a JSON file."""
+        data = {
+            "access_token": self._access_token,
+            "refresh_token": self._refresh_token,
+            "expires_at": self._expires_at,
+        }
+        with open(file_path, "w") as f:
+            json.dump(data, f, indent=2)
+        _LOGGER.info("Tokens saved to %s", file_path)
+
+    @classmethod
+    def load_tokens(cls, file_path: str) -> dict | None:
+        """Load tokens from a JSON file."""
+        if not os.path.exists(file_path):
+            return None
+        try:
+            with open(file_path) as f:
+                return json.load(f)
+        except Exception as e:
+            _LOGGER.error("Failed to load tokens from %s: %s", file_path, e)
+            return None

{dimplex_controller-0.2.1 → dimplex_controller-0.4.0}/dimplex_controller/client.py

@@ -1,5 +1,5 @@
 import logging
-from typing import Dict, List, Optional
+from datetime import datetime, timedelta, timezone
 
 import aiohttp
 
@@ -21,12 +21,25 @@ from .models import (
     ApplianceStatus,
     Hub,
     TimerModeSettings,
+    TsiEnergyReport,
     UserContext,
     Zone,
 )
 
 _LOGGER = logging.getLogger(__name__)
 
+# Default lookback when the caller does not pin a start date. The energy
+# endpoint is paginated server-side; 30 days is a reasonable default that
+# keeps the response small while still giving the caller a meaningful window.
+DEFAULT_TSI_REPORT_DAYS = 30
+DEFAULT_TSI_INTERVAL = "01:00:00"
+
+
+def _iso_utc_days_ago(days: int) -> str:
+    """Return an ISO-8601 UTC timestamp ``days`` before now (no microseconds)."""
+    dt = datetime.now(timezone.utc) - timedelta(days=days)
+    return dt.replace(microsecond=0).isoformat().replace("+00:00", "Z")
+
 
 class DimplexControl:
     """Main client for Dimplex Control API."""
@@ -34,8 +47,8 @@ class DimplexControl:
     def __init__(
         self,
         session: aiohttp.ClientSession,
-        refresh_token: Optional[str] = None,
-        access_token: Optional[str] = None,
+        refresh_token: str | None = None,
+        access_token: str | None = None,
         expires_at: float = 0,
     ):
         """Initialize the client."""
@@ -45,7 +58,7 @@ class DimplexControl:
         if access_token:
             token_data["access_token"] = access_token
         if expires_at:
-            token_data["expires_at"] = expires_at
+            token_data["expires_at"] = expires_at  # type: ignore[assignment]
 
         self._session = session
         self.auth = AuthManager(session, token_data)
@@ -55,7 +68,7 @@ class DimplexControl:
         """Check if authenticated."""
         return self.auth.is_authenticated
 
-    async def _request(self, method: str, endpoint: str, **kwargs) -> Dict:
+    async def _request(self, method: str, endpoint: str, **kwargs) -> dict:
         """Make an authenticated request."""
         token = await self.auth.get_access_token()
         headers = kwargs.pop("headers", {})
@@ -92,13 +105,13 @@ class DimplexControl:
             _LOGGER.error("Connection error during API request: %s", e)
             raise DimplexConnectionError(f"Connection error: {e}") from e
 
-    async def get_hubs(self) -> List[Hub]:
+    async def get_hubs(self) -> list[Hub]:
         """Get all hubs for the user."""
         data = await self._request("GET", "/Hubs/GetUserHubs")
         # Log analysis shows list of objects
         return [Hub(**h) for h in data]
 
-    async def get_hub_zones(self, hub_id: str) -> List[Zone]:
+    async def get_hub_zones(self, hub_id: str) -> list[Zone]:
         """Get zones and appliances for a hub."""
         data = await self._request("GET", "/Zones/GetZonesAndAppliancesForHubId", params={"HubId": hub_id})
         return [Zone(**z) for z in data]
@@ -109,7 +122,7 @@ class DimplexControl:
         data = await self._request("POST", "/Zones/GetZone", json=payload)
         return Zone(**data)
 
-    async def get_appliance_overview(self, hub_id: str, appliance_ids: List[str]) -> List[ApplianceStatus]:
+    async def get_appliance_overview(self, hub_id: str, appliance_ids: list[str]) -> list[ApplianceStatus]:
         """Get status overview for specific appliances."""
         payload = {"HubId": hub_id, "ApplianceIds": appliance_ids}
         data = await self._request("POST", "/RemoteControl/GetApplianceOverview", json=payload)
@@ -159,18 +172,55 @@ class DimplexControl:
         pass
 
     async def set_appliance_mode(
-        self, hub_id: str, appliance_ids: List[str], mode_settings: ApplianceModeSettings
+        self, hub_id: str, appliance_ids: list[str], mode_settings: ApplianceModeSettings
     ) -> None:
         """Set appliance mode (Boost, Away, etc.)."""
         payload = {"Settings": mode_settings.dict(), "HubId": hub_id, "ApplianceIds": appliance_ids}
         await self._request("POST", "/RemoteControl/SetApplianceMode", json=payload)
 
-    async def set_eco_start(self, hub_id: str, appliance_ids: List[str], enable: bool) -> None:
+    async def set_eco_start(self, hub_id: str, appliance_ids: list[str], enable: bool) -> None:
         """Enable/Disable EcoStart."""
         payload = {"Enable": enable, "HubId": hub_id, "ApplianceIds": appliance_ids}
         await self._request("POST", "/RemoteControl/SetEcoStart", json=payload)
 
-    async def set_open_window_detection(self, hub_id: str, appliance_ids: List[str], enable: bool) -> None:
+    async def set_open_window_detection(self, hub_id: str, appliance_ids: list[str], enable: bool) -> None:
         """Enable/Disable Open Window Detection."""
         payload = {"Enable": enable, "HubId": hub_id, "ApplianceIds": appliance_ids}
         await self._request("POST", "/RemoteControl/SetOpenWindowDetection", json=payload)
+
+    async def get_tsi_energy_report(
+        self,
+        hub_id: str | None = None,
+        report_type: int = 1,
+        interval: str = DEFAULT_TSI_INTERVAL,
+        start_date: str | None = None,
+        include_previous_period: bool = False,
+        days_back: int = DEFAULT_TSI_REPORT_DAYS,
+    ) -> TsiEnergyReport:
+        """Fetch the Time Series Insights energy report for a hub.
+
+        Returns a :class:`~dimplex_controller.models.TsiEnergyReport`. The
+        cloud response is the same regardless of ``hub_id`` (the field is
+        informational), so ``hub_id`` is only required to populate the
+        returned model. Each per-appliance list is left as the raw payload —
+        use :func:`dimplex_controller.telemetry.parse_telemetry_points` to
+        normalise the points into ``(timestamp, value)`` tuples.
+
+        When the hub has no metered appliances (e.g. non-QRAD heaters, or a
+        quiet summer hub) the per-appliance lists come back empty; that is
+        treated as success, not an error.
+        """
+        if start_date is None:
+            start_date = _iso_utc_days_ago(days_back)
+
+        payload = {
+            "TsiReportType": report_type,
+            "Interval": interval,
+            "StartDate": start_date,
+            "IncludePreviousPeriod": include_previous_period,
+        }
+        data = await self._request("POST", "/Reports/GetTsiEnergyReportDataForHub", json=payload)
+        return TsiEnergyReport(
+            HubId=(hub_id or data.get("HubId", "")),
+            ApplianceTelemetryData=data.get("ApplianceTelemetryData", {}) or {},
+        )

{dimplex_controller-0.2.1 → dimplex_controller-0.4.0}/dimplex_controller/const.py

@@ -19,3 +19,4 @@ HEADER_DEVICE_MODEL = "iPhone18,1"
 CLIENT_ID = "6c983ca3-506e-4933-8993-0e18e6a24bbd"
 SCOPE = "https://gdhvb2c.onmicrosoft.com/Mobile/read offline_access openid profile"
 REDIRECT_URI = "msal6c983ca3-506e-4933-8993-0e18e6a24bbd://auth/"
+B2C_POLICY = "B2C_1A_DimplexControlSignupSignin"

dimplex_controller-0.4.0/dimplex_controller/models.py

@@ -0,0 +1,117 @@
+from datetime import datetime, time
+
+from pydantic import BaseModel, Field
+
+
+class Appliance(BaseModel):
+    ApplianceId: str
+    ApplianceType: str
+    ApplianceModel: str | None = None
+    ZoneId: str
+    FriendlyName: str
+    ZoneName: str
+    Icon: str | None = None
+    IconColor: str | None = None
+    InstallationDate: datetime | None = None
+    HasConnectivity: bool | None = None
+
+
+class Zone(BaseModel):
+    ZoneId: str
+    ZoneName: str
+    HubId: str
+    ZoneType: str
+    Appliances: list[Appliance] = Field(default_factory=list)
+
+
+class Hub(BaseModel):
+    HubId: str
+    Name: str | None = Field(None, alias="HubName")
+    FriendlyName: str | None = None
+
+
+class TimerPeriod(BaseModel):
+    DayOfWeek: int
+    StartTime: str  # Kept as str for easy JSON serialization
+    EndTime: str
+    Temperature: float
+
+    @property
+    def start_time_obj(self) -> time:
+        return datetime.strptime(self.StartTime, "%H:%M:%S").time()
+
+    @property
+    def end_time_obj(self) -> time:
+        return datetime.strptime(self.EndTime, "%H:%M:%S").time()
+
+
+class TimerModeSettings(BaseModel):
+    HubId: str
+    ApplianceId: str
+    TimerMode: int
+    TimerPeriods: list[TimerPeriod] = Field(default_factory=list)
+
+
+class UserContext(BaseModel):
+    Id: str
+    EmailAddress: str | None = None
+    Name: str | None = None
+
+
+class ApplianceStatus(BaseModel):
+    """Represents the real-time status of an appliance as returned by GetApplianceOverview."""
+
+    HubId: str
+    ApplianceId: str
+    ZoneId: str
+    StatusTwo: int | None = None
+    ApplianceModes: int | None = None
+    RoomTemperature: float | None = None
+    ActiveSetPointTemperature: int | None = None
+    NormalTemperature: float | None = None
+    AwayDateTime: str | None = None
+    AwayTemperature: float | None = None
+    BoostDuration: int | None = None
+    BoostTemperature: float | None = None
+    OpenWindowEnabled: bool | None = None
+    EcoStartEnabled: bool | None = None
+    SetbackEnabled: bool | None = None
+    SetbackEnabledInStatusFrame: bool | None = None
+    SetbackTemperature: float | None = None
+    ComfortStatus: bool | None = None
+    AvailableHotWater: float | None = None
+    LockStatus: int | None = None
+    ErrorCode: str | None = None
+    WarningCode: str | None = None
+
+
+class ApplianceModeSettings(BaseModel):
+    """Settings used to control appliance modes like Boost or Away."""
+
+    ApplianceModes: int
+    Status: int
+    Temperature: float = 23.0
+    Time: int = 0
+    Date: str = "0001-01-01T00:00:00"
+    StatusTwo: int = 0
+    NumberOfDays: int = 0
+    Frequency: int = 0
+
+
+class TsiEnergyReport(BaseModel):
+    """Response from `POST /Reports/GetTsiEnergyReportDataForHub`.
+
+    The cloud returns one telemetry bucket per appliance registered to the hub.
+    Each bucket is a list of points whose individual shape is undocumented and
+    appears to vary by firmware; entries are normalised by
+    :func:`dimplex_controller.telemetry.parse_telemetry_points` so callers do
+    not have to know the wire format.
+    """
+
+    HubId: str
+    ApplianceTelemetryData: dict[str, list] = Field(default_factory=dict)
+
+
+# `TsiReportType` integer values understood by the API. We do not know the
+# canonical mapping; these are observed in traffic captures.
+TSI_REPORT_TYPE_ENERGY = 1

dimplex_controller-0.4.0/dimplex_controller/telemetry.py

@@ -0,0 +1,133 @@
+"""Telemetry parsing for the Dimplex Reports API.
+
+The response from `POST /Reports/GetTsiEnergyReportDataForHub` contains
+``ApplianceTelemetryData``: a dict keyed by appliance id, with one list of
+``telemetry points`` per appliance. The shape of each point is not documented
+and varies between firmware versions, so we normalise whatever the cloud
+sends into ``(timestamp, value)`` tuples.
+"""
+
+from __future__ import annotations
+
+from collections.abc import Iterable
+from datetime import datetime, timezone
+from typing import Any
+
+# Keys the cloud has been observed using, in priority order. The first match
+# wins. Case-insensitive lookup is done by lowercasing the dict before
+# scanning, so callers do not have to worry about casing.
+_TIMESTAMP_KEYS = (
+    "timestamp",
+    "time",
+    "ts",
+    "t",
+    "datetime",
+    "date",
+    "from",
+    "start",
+)
+_VALUE_KEYS = (
+    "value",
+    "kwh",
+    "energy",
+    "consumption",
+    "energykwh",
+    "amount",
+    "v",
+)
+
+
+def _coerce_timestamp(raw: Any) -> datetime | None:
+    """Best-effort conversion of ``raw`` into a ``datetime``.
+
+    Accepts ``datetime`` instances, ISO-8601 strings, and Unix epoch numbers
+    (seconds or milliseconds). Returns ``None`` if the value cannot be parsed.
+    """
+    if raw is None:
+        return None
+    if isinstance(raw, datetime):
+        return raw
+    if isinstance(raw, int | float):
+        ts = float(raw)
+        if ts > 1e12:
+            ts = ts / 1000.0
+        try:
+            return datetime.fromtimestamp(ts, tz=timezone.utc)
+        except (OverflowError, OSError, ValueError):
+            return None
+    if isinstance(raw, str):
+        text = raw.strip()
+        if not text:
+            return None
+        try:
+            return datetime.fromisoformat(text.replace("Z", "+00:00"))
+        except ValueError:
+            return None
+    return None
+
+
+def _coerce_value(raw: Any) -> float | None:
+    """Best-effort conversion of ``raw`` into a ``float``."""
+    if raw is None:
+        return None
+    if isinstance(raw, bool):
+        return None
+    if isinstance(raw, int | float):
+        return float(raw)
+    if isinstance(raw, str):
+        try:
+            return float(raw.strip())
+        except ValueError:
+            return None
+    return None
+
+
+def _iter_items(point: Any) -> Iterable[tuple[str, Any]] | None:
+    """Yield ``(key, value)`` pairs from a dict-like ``point``.
+
+    Returns ``None`` for non-dict points so the caller can fall through to the
+    list / scalar branches.
+    """
+    if not isinstance(point, dict):
+        return None
+    lower = {str(k).lower(): v for k, v in point.items()}
+    return ((k, lower.get(k)) for k in (*_TIMESTAMP_KEYS, *_VALUE_KEYS))
+
+
+def parse_telemetry_points(points: Any) -> list[tuple[datetime | None, float]]:
+    """Normalise a list of telemetry points into ``(timestamp, value)`` pairs.
+
+    Each entry in ``points`` may be:
+
+    * a ``dict`` with one of the recognised timestamp/value keys
+    * a 2-element ``[timestamp, value]`` list or tuple
+    * a bare scalar (treated as a cumulative value at an unknown timestamp)
+
+    Unparseable entries are silently skipped. The order of the input list is
+    preserved.
+    """
+    if not isinstance(points, list):
+        return []
+
+    out: list[tuple[datetime | None, float]] = []
+    for point in points:
+        ts: datetime | None = None
+        value: float | None = None
+
+        items = _iter_items(point)
+        if items is not None:
+            for key, raw in items:
+                if key in _TIMESTAMP_KEYS and ts is None:
+                    ts = _coerce_timestamp(raw)
+                elif key in _VALUE_KEYS and value is None:
+                    value = _coerce_value(raw)
+        elif isinstance(point, list | tuple) and len(point) == 2:
+            ts = _coerce_timestamp(point[0])
+            value = _coerce_value(point[1])
+        else:
+            value = _coerce_value(point)
+
+        if value is None:
+            continue
+        out.append((ts, value))
+    return out

{dimplex_controller-0.2.1 → dimplex_controller-0.4.0}/pyproject.toml

@@ -1,6 +1,6 @@
 [tool.poetry]
 name = "dimplex-controller"
-version = "0.2.1"
+version = "0.4.0"
 description = "Python client for Dimplex heating controllers (GDHV IoT)"
 authors = ["Kieran Roper"]
 license = "MIT"
@@ -18,6 +18,7 @@ classifiers = [
     "Programming Language :: Python :: 3.10",
     "Programming Language :: Python :: 3.11",
     "Programming Language :: Python :: 3.12",
+    "Programming Language :: Python :: 3.13",
     "Topic :: Home Automation",
 ]
 packages = [{ include = "dimplex_controller" }]
@@ -31,6 +32,7 @@ python-dotenv = "^1.2.1"
 [tool.poetry.group.dev.dependencies]
 pytest = "^8.0.0"
 pytest-asyncio = "^0.23.0"
+pytest-cov = "^6.0.0"
 aresponses = "^3.0.0"
 ruff = "^0.3.0"
 pre-commit = "^3.6.0"
@@ -41,7 +43,18 @@ line-length = 120
 target-version = "py310"
 
 [tool.ruff.lint]
-select = ["E", "F", "I", "W"]
+select = ["E", "F", "I", "W", "UP", "B", "SIM"]
+# E501 (line length) is handled by the formatter; long strings/comments are fine.
+ignore = ["E501"]
+
+[tool.mypy]
+# Loose by design — the library is mostly untyped and a strict pass is out of
+# scope for the CI modernisation. The two auth.py return-narrowing issues and
+# the client.py expires_at assignment are pre-existing and either fixed in
+# place or # type: ignore-d; remove when a full typing pass lands.
+python_version = "3.10"
+files = ["dimplex_controller"]
+ignore_missing_imports = true
 
 [build-system]
 requires = ["poetry-core"]

dimplex_controller-0.2.1/dimplex_controller/auth.py

@@ -1,304 +0,0 @@
-import json
-import logging
-import os
-import re
-import time
-from typing import Dict, Optional
-from urllib.parse import parse_qs, urlencode, urlparse
-
-import aiohttp
-from bs4 import BeautifulSoup
-
-from .const import (
-    AUTH_URL,
-    CLIENT_ID,
-    HTTP_OK,
-    REDIRECT_URI,
-    SCOPE,
-)
-from .exceptions import DimplexAuthError
-
-_LOGGER = logging.getLogger(__name__)
-
-
-class AuthManager:
-    """Manages authentication for Dimplex Control."""
-
-    def __init__(self, session: aiohttp.ClientSession, token_data: Optional[Dict] = None):
-        """Initialize the auth manager."""
-        self._session = session
-        self._access_token: Optional[str] = token_data.get("access_token") if token_data else None
-        self._refresh_token: Optional[str] = token_data.get("refresh_token") if token_data else None
-        self._expires_at: float = token_data.get("expires_at", 0) if token_data else 0
-
-    @property
-    def is_authenticated(self) -> bool:
-        """Check if we have a valid access token."""
-        return self._access_token is not None and time.time() < self._expires_at
-
-    async def get_access_token(self) -> str:
-        """Get a valid access token, refreshing if necessary."""
-        if not self._refresh_token:
-            raise DimplexAuthError("No refresh token available. User must authenticate first.")
-
-        if self.is_authenticated:
-            return self._access_token
-
-        # Token expired or missing, try refresh
-        await self.refresh_tokens()
-        return self._access_token
-
-    async def refresh_tokens(self) -> None:
-        """Refresh the access token using the refresh token."""
-        _LOGGER.debug("Refreshing access token")
-        payload = {
-            "client_id": CLIENT_ID,
-            "grant_type": "refresh_token",
-            "refresh_token": self._refresh_token,
-            "scope": SCOPE,
-            "client_info": "1",
-        }
-
-        async with self._session.post(f"{AUTH_URL}/token", data=payload) as resp:
-            if resp.status != HTTP_OK:
-                text = await resp.text()
-                _LOGGER.error("Failed to refresh token: %s", text)
-                raise DimplexAuthError(f"Failed to refresh token: {resp.status} - {text}")
-
-            data = await resp.json()
-            self._update_tokens(data)
-
-    def _update_tokens(self, data: Dict) -> None:
-        """Update internal token state from API response."""
-        self._access_token = data.get("access_token")
-        self._refresh_token = data.get("refresh_token")
-        expires_in = data.get("expires_in", 3600)
-        self._expires_at = time.time() + expires_in - 60  # Buffer 60s
-
-    def get_login_url(self) -> str:
-        """Generate the login URL for the user to visit."""
-        # Note: This is a simplified URL generation.
-        # In a real app, we might need state, nonce, code_challenge (PKCE).
-        # Based on logs, iOS app uses standard OAuth2.
-        # Constructing a URL for manual copy-paste might be tricky if it strictly requires a custom scheme redirect.
-        # But we can try the standard authorize endpoint.
-
-        params = {
-            "client_id": CLIENT_ID,
-            "response_type": "code",
-            "redirect_uri": REDIRECT_URI,
-            "scope": SCOPE,
-            "response_mode": "query",
-        }
-        from urllib.parse import urlencode
-
-        return f"{AUTH_URL}/authorize?{urlencode(params)}"
-
-    async def exchange_code(self, code: str) -> None:
-        """Exchange authorization code for tokens."""
-        payload = {
-            "client_id": CLIENT_ID,
-            "grant_type": "authorization_code",
-            "code": code,
-            "redirect_uri": REDIRECT_URI,
-            "scope": SCOPE,
-        }
-
-        _LOGGER.info(f"Exchanging code for tokens at {AUTH_URL}/token")
-        client_id = payload["client_id"]
-        redirect_uri = payload["redirect_uri"]
-        code_preview = code[:10]
-        _LOGGER.info(f"Payload: client_id={client_id}, redirect_uri={redirect_uri}, " f"code={code_preview}...")
-
-        async with self._session.post(f"{AUTH_URL}/token", data=payload) as resp:
-            _LOGGER.info(f"Token exchange response status: {resp.status}")
-            if resp.status != HTTP_OK:
-                text = await resp.text()
-                _LOGGER.error(f"Token exchange failed: {text}")
-                raise DimplexAuthError(f"Failed to exchange code: {text}")
-
-            data = await resp.json()
-            self._update_tokens(data)
-
-    async def headless_login(self, email, password) -> None:
-        """Perform a headless login to obtain tokens."""
-        # 1. Get the login page
-        params = {
-            "client_id": CLIENT_ID,
-            "response_type": "code",
-            "redirect_uri": REDIRECT_URI,
-            "scope": SCOPE,
-            "response_mode": "query",
-        }
-        start_url = f"{AUTH_URL}/authorize?{urlencode(params)}"
-        _LOGGER.debug(f"Fetching login page: {start_url}")
-
-        async with self._session.get(start_url) as resp:
-            html = await resp.text()
-            final_url = str(resp.url)
-
-        # 2. Extract SETTINGS and CSRF
-        match = re.search(r"SETTINGS\s*=\s*({.*?});", html, re.DOTALL | re.MULTILINE)
-        if not match:
-            raise DimplexAuthError("Could not find SETTINGS in login page")
-
-        try:
-            settings = json.loads(match.group(1))
-        except json.JSONDecodeError:
-            raise DimplexAuthError("Failed to parse SETTINGS JSON from login page")
-
-        csrf_token = settings.get("csrf")
-        trans_id = settings.get("transId")
-
-        if not csrf_token or not trans_id:
-            raise DimplexAuthError("Missing csrf or transId in login page SETTINGS")
-
-        # 3. Construct SelfAsserted URL
-        if "/oauth2/v2.0/authorize" in final_url:
-            base_url = final_url.split("/oauth2/v2.0/authorize")[0]
-        else:
-            base_url = "https://gdhvb2c.b2clogin.com/gdhvb2c.onmicrosoft.com/B2C_1A_DimplexControlSignupSignin"
-
-        post_url = f"{base_url}/SelfAsserted"
-
-        params = {
-            "tx": trans_id,
-            "p": "B2C_1A_DimplexControlSignupSignin",
-        }
-
-        post_url_with_params = f"{post_url}?{urlencode(params)}"
-
-        # 4. Submit Credentials
-        # Extract hidden fields from the form to ensure we aren't missing anything
-        soup = BeautifulSoup(html, "html.parser")
-        form = soup.find("form", {"id": "localAccountForm"}) or soup.find("form")
-
-        form_data = {}
-        if form:
-            for input_tag in form.find_all("input"):
-                name = input_tag.get("name")
-                value = input_tag.get("value", "")
-                if name:
-                    form_data[name] = value
-
-        # Overwrite with credentials
-        form_data.update(
-            {
-                "request_type": "RESPONSE",
-                "email": email,
-                "password": password,
-            }
-        )
-
-        headers = {
-            "X-CSRF-TOKEN": csrf_token,
-            "X-Requested-With": "XMLHttpRequest",
-            "Content-Type": "application/x-www-form-urlencoded; charset=UTF-8",
-            "Origin": "https://gdhvb2c.b2clogin.com",
-            "Referer": final_url,
-        }
-
-        _LOGGER.debug(f"Submitting credentials to {post_url_with_params}")
-        # _LOGGER.debug(f"Form data: {form_data}") # Security risk to log password
-
-        async with self._session.post(post_url_with_params, data=form_data, headers=headers) as resp:
-            resp_text = await resp.text()
-            _LOGGER.debug(f"Login response status: {resp.status}")
-
-            try:
-                resp_json = json.loads(resp_text)
-                _LOGGER.debug(f"Login response JSON: {resp_json}")
-            except json.JSONDecodeError:
-                _LOGGER.debug(f"Login response Text: {resp_text}")
-                raise DimplexAuthError(f"Login response was not valid JSON: {resp_text[:100]}")
-
-            if resp_json.get("status") != "200":
-                status = resp_json.get("status")
-                message = resp_json.get("message") or resp_json.get("reason", "Unknown reason")
-                raise DimplexAuthError(f"Login failed: {status} - {message}")
-
-        # 5. Follow the 'Confirmed' step to get the actual code
-        # After a successful SelfAsserted, we usually need to make a GET to
-        # the 'CombinedSigninAndSignup' or similar endpoint to finalize the
-        # flow and get the redirect to our app with the code.
-        # Or, sometimes the SelfAsserted response sets a cookie and we just
-        # need to hit the authorize endpoint again.
-
-        # Let's try hitting the original authorize URL again (or the one we were redirected to).
-        # Since cookies are in the session, it should now redirect us to the app with the code.
-
-        _LOGGER.debug("Credentials accepted. Fetching authorize URL again to get code.")
-
-        # We need to allow redirects to capture the final msauth:// url
-        # aiohttp generic session checks redirects.
-        # But since the scheme is custom (msal...), aiohttp might throw an error or stop.
-
-        try:
-            async with self._session.get(start_url, allow_redirects=True) as resp:
-                # If we are here, it means we didn't crash on custom scheme yet,
-                # or we are at a page that directs us.
-                # Check history
-                pass
-        except aiohttp.ClientError:
-            # This might happen if the redirect schema is not http/https
-            # We can inspect the error or just capture it from the history if possible
-            pass
-        except Exception:
-            # If it tries to redirect to msal..., it might fail if aiohttp doesn't support it.
-            # We can disable redirects and follow manually to catch it.
-            pass
-
-        # Manual redirect following to catch custom scheme
-        current_url = start_url
-        code = None
-
-        for _ in range(10):  # Max redirects
-            async with self._session.get(current_url, allow_redirects=False) as resp:
-                if resp.status in (302, 303, 301):
-                    location = resp.headers.get("Location")
-                    if not location:
-                        break
-
-                    if location.startswith(REDIRECT_URI) or "code=" in location:
-                        # Success!
-                        _LOGGER.debug(f"Found redirect with code: {location}")
-                        # Extract code
-                        parsed = urlparse(location)
-                        query = parse_qs(parsed.query)
-                        code = query.get("code", [""])[0]
-                        break
-
-                    current_url = location
-                else:
-                    break
-
-        if not code:
-            raise DimplexAuthError(
-                "Failed to obtain auth code after successful login. Redirect URI might have changed."
-            )
-
-        _LOGGER.debug(f"Got code: {code[:10]}...")
-        await self.exchange_code(code)
-
-    def save_tokens(self, file_path: str) -> None:
-        """Save current tokens to a JSON file."""
-        data = {
-            "access_token": self._access_token,
-            "refresh_token": self._refresh_token,
-            "expires_at": self._expires_at,
-        }
-        with open(file_path, "w") as f:
-            json.dump(data, f, indent=2)
-        _LOGGER.info("Tokens saved to %s", file_path)
-
-    @classmethod
-    def load_tokens(cls, file_path: str) -> Optional[Dict]:
-        """Load tokens from a JSON file."""
-        if not os.path.exists(file_path):
-            return None
-        try:
-            with open(file_path, "r") as f:
-                return json.load(f)
-        except Exception as e:
-            _LOGGER.error("Failed to load tokens from %s: %s", file_path, e)
-            return None

dimplex_controller-0.2.1/dimplex_controller/models.py

@@ -1,99 +0,0 @@
-from datetime import datetime, time
-from typing import List, Optional
-
-from pydantic import BaseModel, Field
-
-
-class Appliance(BaseModel):
-    ApplianceId: str
-    ApplianceType: str
-    ApplianceModel: Optional[str] = None
-    ZoneId: str
-    FriendlyName: str
-    ZoneName: str
-    Icon: Optional[str] = None
-    IconColor: Optional[str] = None
-    InstallationDate: Optional[datetime] = None
-    HasConnectivity: Optional[bool] = None
-
-
-class Zone(BaseModel):
-    ZoneId: str
-    ZoneName: str
-    HubId: str
-    ZoneType: str
-    Appliances: List[Appliance] = Field(default_factory=list)
-
-
-class Hub(BaseModel):
-    HubId: str
-    Name: Optional[str] = Field(None, alias="HubName")
-    FriendlyName: Optional[str] = None
-
-
-class TimerPeriod(BaseModel):
-    DayOfWeek: int
-    StartTime: str  # Kept as str for easy JSON serialization
-    EndTime: str
-    Temperature: float
-
-    @property
-    def start_time_obj(self) -> time:
-        return datetime.strptime(self.StartTime, "%H:%M:%S").time()
-
-    @property
-    def end_time_obj(self) -> time:
-        return datetime.strptime(self.EndTime, "%H:%M:%S").time()
-
-
-class TimerModeSettings(BaseModel):
-    HubId: str
-    ApplianceId: str
-    TimerMode: int
-    TimerPeriods: List[TimerPeriod] = Field(default_factory=list)
-
-
-class UserContext(BaseModel):
-    Id: str
-    EmailAddress: Optional[str] = None
-    Name: Optional[str] = None
-
-
-class ApplianceStatus(BaseModel):
-    """Represents the real-time status of an appliance as returned by GetApplianceOverview."""
-
-    HubId: str
-    ApplianceId: str
-    ZoneId: str
-    StatusTwo: Optional[int] = None
-    ApplianceModes: Optional[int] = None
-    RoomTemperature: Optional[float] = None
-    ActiveSetPointTemperature: Optional[int] = None
-    NormalTemperature: Optional[float] = None
-    AwayDateTime: Optional[str] = None
-    AwayTemperature: Optional[float] = None
-    BoostDuration: Optional[int] = None
-    BoostTemperature: Optional[float] = None
-    OpenWindowEnabled: Optional[bool] = None
-    EcoStartEnabled: Optional[bool] = None
-    SetbackEnabled: Optional[bool] = None
-    SetbackEnabledInStatusFrame: Optional[bool] = None
-    SetbackTemperature: Optional[float] = None
-    ComfortStatus: Optional[bool] = None
-    AvailableHotWater: Optional[float] = None
-    LockStatus: Optional[int] = None
-    ErrorCode: Optional[str] = None
-    WarningCode: Optional[str] = None
-
-
-class ApplianceModeSettings(BaseModel):
-    """Settings used to control appliance modes like Boost or Away."""
-
-    ApplianceModes: int
-    Status: int
-    Temperature: float = 23.0
-    Time: int = 0
-    Date: str = "0001-01-01T00:00:00"
-    StatusTwo: int = 0
-    NumberOfDays: int = 0
-    Frequency: int = 0