upgrait-heatcontrol-api 0.1.0.dev0__tar.gz

upgrait_heatcontrol_api-0.1.0.dev0/PKG-INFO

@@ -0,0 +1,70 @@
+Metadata-Version: 2.4
+Name: upgrait-heatcontrol-api
+Version: 0.1.0.dev0
+Summary: Async Python API client for the UPGRAIT HeatControl 3rd-party connector.
+Author: UPGRAIT GmbH
+License-Expression: LicenseRef-UPGRAIT-Proprietary
+Requires-Python: >=3.12
+Description-Content-Type: text/markdown
+Requires-Dist: aiohttp<4,>=3.12
+Requires-Dist: PyNaCl<2,>=1.5
+Requires-Dist: zeroconf<1,>=0.136
+
+# upgrait-heatcontrol-api
+
+Async Python API package for the UPGRAIT HeatControl 3rd-party connector.
+
+The package is intended to be the external dependency consumed by the Home Assistant integration and by other 3rd-party clients.
+
+Current feature set:
+
+- HTTP probing via `/api/ping`
+- device metadata parsing
+- pairing start via `/api/pair/start`
+- pairing confirmation via `/api/pair/confirm`
+- websocket bind/session transport
+- encrypted request/response handling over the websocket session
+- initial snapshot handling and live event subscription
+- Zeroconf service constants and discovery metadata parsing helpers
+
+Installation:
+
+```bash
+pip install upgrait-heatcontrol-api
+```
+
+Example:
+
+```python
+import asyncio
+
+from upgrait_heatcontrol_api import HeatControlApiClient, generate_keypair
+
+
+async def main() -> None:
+    async with HeatControlApiClient(host="192.168.2.116", port=8001) as client:
+        device = await client.async_get_device_info()
+        print(device.serial, device.version)
+
+        private_key, public_key = generate_keypair()
+
+        pairing = await client.async_start_pairing(
+            ha_instance_id="example-ha-instance",
+            display_name="Example Client",
+            integration_version="0.1.0.dev0",
+        )
+        print(pairing.expires_at)
+
+        # The 6-digit PIN must be entered by the user after it is shown on the UHC. (Only available in new local interface, version >1610)
+        # confirm = await client.async_confirm_pairing(...)
+        # connection = await client.async_connect_and_bind(...)
+
+
+asyncio.run(main())
+```
+
+Notes:
+
+- `HeatControlApiClient` can manage its own `aiohttp` session. In that case, either use `async with HeatControlApiClient(...)` or call `await client.close()`.
+- `HeatControlConnection.subscribe()` registers callbacks for live websocket events and returns an unsubscribe function.
+- Discovery helpers cover both the `/api/ping` `discovery` payload and Zeroconf TXT-record property normalization.

upgrait_heatcontrol_api-0.1.0.dev0/README.md

@@ -0,0 +1,58 @@
+# upgrait-heatcontrol-api
+
+Async Python API package for the UPGRAIT HeatControl 3rd-party connector.
+
+The package is intended to be the external dependency consumed by the Home Assistant integration and by other 3rd-party clients.
+
+Current feature set:
+
+- HTTP probing via `/api/ping`
+- device metadata parsing
+- pairing start via `/api/pair/start`
+- pairing confirmation via `/api/pair/confirm`
+- websocket bind/session transport
+- encrypted request/response handling over the websocket session
+- initial snapshot handling and live event subscription
+- Zeroconf service constants and discovery metadata parsing helpers
+
+Installation:
+
+```bash
+pip install upgrait-heatcontrol-api
+```
+
+Example:
+
+```python
+import asyncio
+
+from upgrait_heatcontrol_api import HeatControlApiClient, generate_keypair
+
+
+async def main() -> None:
+    async with HeatControlApiClient(host="192.168.2.116", port=8001) as client:
+        device = await client.async_get_device_info()
+        print(device.serial, device.version)
+
+        private_key, public_key = generate_keypair()
+
+        pairing = await client.async_start_pairing(
+            ha_instance_id="example-ha-instance",
+            display_name="Example Client",
+            integration_version="0.1.0.dev0",
+        )
+        print(pairing.expires_at)
+
+        # The 6-digit PIN must be entered by the user after it is shown on the UHC. (Only available in new local interface, version >1610)
+        # confirm = await client.async_confirm_pairing(...)
+        # connection = await client.async_connect_and_bind(...)
+
+
+asyncio.run(main())
+```
+
+Notes:
+
+- `HeatControlApiClient` can manage its own `aiohttp` session. In that case, either use `async with HeatControlApiClient(...)` or call `await client.close()`.
+- `HeatControlConnection.subscribe()` registers callbacks for live websocket events and returns an unsubscribe function.
+- Discovery helpers cover both the `/api/ping` `discovery` payload and Zeroconf TXT-record property normalization.

upgrait_heatcontrol_api-0.1.0.dev0/pyproject.toml

@@ -0,0 +1,32 @@
+[build-system]
+requires = ["setuptools>=78", "wheel"]
+build-backend = "setuptools.build_meta"
+
+[project]
+name = "upgrait-heatcontrol-api"
+version = "0.1.0.dev0"
+description = "Async Python API client for the UPGRAIT HeatControl 3rd-party connector."
+readme = "README.md"
+requires-python = ">=3.12"
+license = "LicenseRef-UPGRAIT-Proprietary"
+authors = [
+  {name = "UPGRAIT GmbH"}
+]
+dependencies = [
+  "aiohttp>=3.12,<4",
+  "PyNaCl>=1.5,<2",
+  "zeroconf>=0.136,<1"
+]
+
+[dependency-groups]
+dev = [
+  "pytest>=8.3,<9",
+  "pytest-asyncio>=0.24,<1",
+  "twine>=6,<7"
+]
+
+[tool.setuptools]
+package-dir = {"" = "src"}
+
+[tool.setuptools.packages.find]
+where = ["src"]

upgrait_heatcontrol_api-0.1.0.dev0/setup.cfg

@@ -0,0 +1,4 @@
+[egg_info]
+tag_build = 
+tag_date = 0
+

upgrait_heatcontrol_api-0.1.0.dev0/src/upgrait_heatcontrol_api/__init__.py

@@ -0,0 +1,41 @@
+"""Public exports for the UPGRAIT HeatControl API package."""
+
+from .client import HeatControlApiClient
+from .connection import HeatControlConnection
+from .crypto import generate_keypair
+from .discovery import (
+    DEFAULT_PORT,
+    MANUFACTURER,
+    MODEL,
+    SERVICE_TYPE,
+    DiscoveryAdvertisement,
+    ZeroconfDiscoveryInfo,
+)
+from .exceptions import (
+    HeatControlApiAuthError,
+    HeatControlApiConnectionError,
+    HeatControlApiError,
+    HeatControlApiInvalidPinError,
+    HeatControlApiProtocolError,
+)
+from .models import DeviceInfo, PairingConfirmResult, PairingStartResult
+
+__all__ = [
+    "DEFAULT_PORT",
+    "DeviceInfo",
+    "DiscoveryAdvertisement",
+    "HeatControlApiClient",
+    "HeatControlApiAuthError",
+    "HeatControlApiConnectionError",
+    "HeatControlApiError",
+    "HeatControlApiInvalidPinError",
+    "HeatControlApiProtocolError",
+    "HeatControlConnection",
+    "MANUFACTURER",
+    "MODEL",
+    "PairingConfirmResult",
+    "PairingStartResult",
+    "SERVICE_TYPE",
+    "ZeroconfDiscoveryInfo",
+    "generate_keypair",
+]

upgrait_heatcontrol_api-0.1.0.dev0/src/upgrait_heatcontrol_api/client.py

@@ -0,0 +1,183 @@
+"""Async client for the UHC 3rd-party connector."""
+
+from __future__ import annotations
+
+import asyncio
+from typing import Any
+
+import aiohttp
+
+from .connection import HeatControlConnection
+from .discovery import DEFAULT_PORT
+from .exceptions import (
+    HeatControlApiAuthError,
+    HeatControlApiConnectionError,
+    HeatControlApiError,
+    HeatControlApiInvalidPinError,
+)
+from .models import DeviceInfo, PairingConfirmResult, PairingStartResult
+
+
+class HeatControlApiClient:
+    """Async HTTP + websocket client for UPGRAIT HeatControl."""
+
+    def __init__(
+        self,
+        *,
+        host: str,
+        port: int = DEFAULT_PORT,
+        session: aiohttp.ClientSession | None = None,
+    ) -> None:
+        self.host = host
+        self.port = port
+        self._session = session
+        self._owns_session = session is None
+
+    async def __aenter__(self) -> "HeatControlApiClient":
+        return self
+
+    async def __aexit__(self, *_exc_info: object) -> None:
+        await self.close()
+
+    @property
+    def base_url(self) -> str:
+        return f"http://{self._network_location}"
+
+    @property
+    def ws_url(self) -> str:
+        return f"ws://{self._network_location}/ws"
+
+    @property
+    def _network_location(self) -> str:
+        host = self.host.strip()
+        if ":" in host and not host.startswith("["):
+            host = f"[{host}]"
+        return f"{host}:{self.port}"
+
+    async def async_ping(self) -> dict[str, Any]:
+        return await self._async_request("GET", "/api/ping")
+
+    async def async_get_device_info(self) -> DeviceInfo:
+        payload = await self.async_ping()
+        return DeviceInfo.from_ping_payload(payload)
+
+    async def async_start_pairing(
+        self,
+        *,
+        ha_instance_id: str,
+        display_name: str,
+        integration_version: str,
+    ) -> PairingStartResult:
+        payload = await self._async_request(
+            "POST",
+            "/api/pair/start",
+            json={
+                "ha_instance_id": ha_instance_id,
+                "display_name": display_name,
+                "integration_version": integration_version,
+            },
+        )
+        return PairingStartResult.from_payload(payload)
+
+    async def async_confirm_pairing(
+        self,
+        *,
+        pin: str,
+        ha_instance_id: str,
+        display_name: str,
+        integration_version: str,
+        ha_public_key: str,
+    ) -> PairingConfirmResult:
+        payload = await self._async_request(
+            "POST",
+            "/api/pair/confirm",
+            json={
+                "pin": pin,
+                "ha_instance_id": ha_instance_id,
+                "display_name": display_name,
+                "integration_version": integration_version,
+                "ha_public_key": ha_public_key,
+            },
+        )
+        return PairingConfirmResult.from_payload(payload)
+
+    async def async_connect_and_bind(
+        self,
+        *,
+        ha_instance_id: str,
+        ha_private_key: str,
+        server_public_key: str,
+    ) -> HeatControlConnection:
+        session = await self._get_session()
+        try:
+            ws = await session.ws_connect(self.ws_url, heartbeat=30)
+        except (aiohttp.ClientError, asyncio.TimeoutError) as exc:
+            raise HeatControlApiConnectionError(
+                f"failed to open websocket at {self.ws_url}: {exc}"
+            ) from exc
+
+        connection = HeatControlConnection(
+            session=session,
+            ws=ws,
+            ha_instance_id=ha_instance_id,
+            ha_private_key=ha_private_key,
+            server_public_key=server_public_key,
+        )
+        try:
+            await connection.start()
+        except Exception:
+            await connection.close()
+            raise
+        return connection
+
+    async def close(self) -> None:
+        if not self._owns_session or self._session is None:
+            return
+        if not self._session.closed:
+            await self._session.close()
+        self._session = None
+
+    async def _async_request(
+        self,
+        method: str,
+        path: str,
+        *,
+        json: dict[str, Any] | None = None,
+    ) -> dict[str, Any]:
+        session = await self._get_session()
+        try:
+            async with session.request(method, f"{self.base_url}{path}", json=json) as resp:
+                payload = await resp.json()
+        except (aiohttp.ClientError, asyncio.TimeoutError) as exc:
+            raise HeatControlApiConnectionError(
+                f"failed to reach HeatControl at {self.base_url}: {exc}"
+            ) from exc
+        except Exception as exc:
+            raise HeatControlApiError(f"{method} {path} returned invalid JSON: {exc}") from exc
+
+        if not isinstance(payload, dict):
+            raise HeatControlApiError(f"{method} {path} returned invalid JSON")
+
+        if resp.status >= 400 or payload.get("ok") is False:
+            error = payload.get("error")
+            code = str(error.get("code") if isinstance(error, dict) else f"http_{resp.status}")
+            message = str(
+                error.get("message") if isinstance(error, dict) else f"{method} {path} failed"
+            )
+            if code == "invalid_pin":
+                raise HeatControlApiInvalidPinError(message)
+            if code in {"pairing_not_active", "pairing_mismatch"}:
+                raise HeatControlApiAuthError(message)
+            raise HeatControlApiError(f"{code}: {message}")
+        return payload
+
+    async def _get_session(self) -> aiohttp.ClientSession:
+        if self._session is not None:
+            if not self._session.closed:
+                return self._session
+            if not self._owns_session:
+                raise HeatControlApiConnectionError("provided aiohttp session is closed")
+            self._session = None
+        self._session = aiohttp.ClientSession(timeout=aiohttp.ClientTimeout(total=10))
+        self._owns_session = True
+        return self._session

upgrait_heatcontrol_api-0.1.0.dev0/src/upgrait_heatcontrol_api/connection.py

@@ -0,0 +1,226 @@
+"""WebSocket connection handling for the UHC 3rd-party connector."""
+
+from __future__ import annotations
+
+import asyncio
+import contextlib
+import inspect
+import json
+import time
+from collections.abc import Awaitable, Callable
+from typing import Any
+
+import aiohttp
+from nacl.public import PrivateKey, PublicKey
+
+from .crypto import (
+    box_decrypt_json,
+    box_encrypt_json,
+    load_private_key,
+    load_public_key,
+    uuid4_hex,
+)
+from .exceptions import (
+    HeatControlApiAuthError,
+    HeatControlApiConnectionError,
+    HeatControlApiProtocolError,
+)
+
+
+EventCallback = Callable[[dict[str, Any]], Awaitable[None] | None]
+
+
+class HeatControlConnection:
+    """Bound websocket connection to a HeatControl device."""
+
+    def __init__(
+        self,
+        *,
+        session: aiohttp.ClientSession,
+        ws: aiohttp.ClientWebSocketResponse,
+        ha_instance_id: str,
+        ha_private_key: str,
+        server_public_key: str,
+    ) -> None:
+        self._session = session
+        self._ws = ws
+        self._ha_instance_id = ha_instance_id
+        self._ha_private_key = ha_private_key
+        self._server_public_key = server_public_key
+        self._ha_private_key_obj: PrivateKey = load_private_key(ha_private_key)
+        self._server_public_key_obj: PublicKey = load_public_key(server_public_key)
+        self._event_callbacks: list[EventCallback] = []
+        self._pending: dict[str, asyncio.Future[dict[str, Any]]] = {}
+        self._reader_task: asyncio.Task[Any] | None = None
+        self._initial_snapshot: asyncio.Future[dict[str, Any]] = asyncio.get_running_loop().create_future()
+        self._closed = False
+        self._reader_exception: Exception | None = None
+        self.snapshot: dict[str, Any] = {}
+
+    async def start(self) -> None:
+        bind_payload = box_encrypt_json(
+            self._ha_private_key_obj,
+            self._server_public_key_obj,
+            {
+                "ha_instance_id": self._ha_instance_id,
+                "ts_ms": int(time.time() * 1000),
+                "nonce": uuid4_hex(),
+            },
+        )
+        try:
+            await self._ws.send_json({"type": "bind", "payload": bind_payload})
+            ack = await asyncio.wait_for(self._ws.receive(), timeout=15)
+        except (aiohttp.ClientError, asyncio.TimeoutError) as exc:
+            raise HeatControlApiConnectionError(f"websocket bind failed: {exc}") from exc
+        if ack.type in {
+            aiohttp.WSMsgType.CLOSE,
+            aiohttp.WSMsgType.CLOSED,
+            aiohttp.WSMsgType.CLOSING,
+        }:
+            raise HeatControlApiConnectionError("websocket closed during bind")
+        if ack.type != aiohttp.WSMsgType.TEXT:
+            raise HeatControlApiAuthError("websocket bind failed")
+        try:
+            payload = json.loads(ack.data)
+        except json.JSONDecodeError as exc:
+            raise HeatControlApiProtocolError("bind acknowledgement was not valid JSON") from exc
+        if not isinstance(payload, dict):
+            raise HeatControlApiProtocolError("bind acknowledgement was not a JSON object")
+        if payload.get("type") == "error":
+            raise HeatControlApiAuthError(str(payload.get("error") or "websocket bind failed"))
+        if payload.get("type") != "bind_ack":
+            raise HeatControlApiAuthError(f"unexpected bind response: {payload}")
+        self._reader_task = asyncio.create_task(self._reader())
+        self.snapshot = await asyncio.wait_for(self._initial_snapshot, timeout=10)
+
+    def subscribe(self, callback: EventCallback) -> Callable[[], None]:
+        self._event_callbacks.append(callback)
+
+        def _unsubscribe() -> None:
+            with contextlib.suppress(ValueError):
+                self._event_callbacks.remove(callback)
+
+        return _unsubscribe
+
+    async def request(self, method: str, params: dict[str, Any] | None = None) -> Any:
+        self._raise_if_unavailable()
+        request_id = uuid4_hex()
+        future: asyncio.Future[dict[str, Any]] = asyncio.get_running_loop().create_future()
+        self._pending[request_id] = future
+        try:
+            await self._send_encrypted(
+                {
+                    "type": "req",
+                    "request_id": request_id,
+                    "method": method,
+                    "params": params or {},
+                }
+            )
+            response = await asyncio.wait_for(future, timeout=10)
+        finally:
+            self._pending.pop(request_id, None)
+
+        if response.get("ok") is not True:
+            error = response.get("error")
+            raise HeatControlApiProtocolError(str(error))
+        return response.get("result")
+
+    async def close(self) -> None:
+        self._closed = True
+        close_exc = HeatControlApiConnectionError("connection closed")
+        if not self._initial_snapshot.done():
+            self._initial_snapshot.set_exception(close_exc)
+        for future in list(self._pending.values()):
+            if not future.done():
+                future.set_exception(close_exc)
+        if self._reader_task is not None:
+            self._reader_task.cancel()
+            with contextlib.suppress(asyncio.CancelledError, Exception):
+                await self._reader_task
+        await self._ws.close()
+
+    async def _reader(self) -> None:
+        try:
+            async for msg in self._ws:
+                if msg.type != aiohttp.WSMsgType.TEXT:
+                    continue
+                outer = json.loads(msg.data)
+                msg_type = outer.get("type")
+                if msg_type == "close":
+                    raise HeatControlApiAuthError(str(outer.get("reason") or "connection closed"))
+                if msg_type != "msg":
+                    continue
+                payload_b64 = outer.get("payload")
+                if not isinstance(payload_b64, str):
+                    continue
+                inner = box_decrypt_json(
+                    self._server_public_key_obj,
+                    self._ha_private_key_obj,
+                    payload_b64,
+                )
+                inner_type = inner.get("type")
+                if inner_type == "res":
+                    request_id = str(inner.get("request_id") or "")
+                    future = self._pending.get(request_id)
+                    if future is not None and not future.done():
+                        future.set_result(inner)
+                elif inner_type == "evt":
+                    if isinstance(inner.get("topics"), dict):
+                        self.snapshot = dict(inner["topics"])
+                        if not self._initial_snapshot.done():
+                            self._initial_snapshot.set_result(dict(self.snapshot))
+                    elif isinstance(inner.get("topic"), str):
+                        self.snapshot[inner["topic"]] = inner.get("value")
+                    for callback in list(self._event_callbacks):
+                        result = callback(inner)
+                        if inspect.isawaitable(result):
+                            await result
+        except asyncio.CancelledError:
+            raise
+        except Exception as exc:
+            self._set_reader_exception(self._normalize_reader_exception(exc))
+        else:
+            if not self._closed:
+                self._set_reader_exception(
+                    HeatControlApiConnectionError("websocket connection closed")
+                )
+
+    async def _send_encrypted(self, payload: dict[str, Any]) -> None:
+        self._raise_if_unavailable()
+        encrypted = box_encrypt_json(
+            self._ha_private_key_obj,
+            self._server_public_key_obj,
+            payload,
+        )
+        await self._ws.send_json({"type": "msg", "payload": encrypted})
+
+    def _normalize_reader_exception(self, exc: Exception) -> Exception:
+        if isinstance(
+            exc,
+            (
+                HeatControlApiAuthError,
+                HeatControlApiConnectionError,
+                HeatControlApiProtocolError,
+            ),
+        ):
+            return exc
+        return HeatControlApiConnectionError(f"websocket reader failed: {exc}")
+
+    def _raise_if_unavailable(self) -> None:
+        if self._reader_exception is not None:
+            raise self._reader_exception
+        if self._closed or self._ws.closed:
+            raise HeatControlApiConnectionError("websocket connection is closed")
+        if self._reader_task is None:
+            raise HeatControlApiProtocolError("connection has not been started")
+        if self._reader_task.done():
+            raise HeatControlApiConnectionError("websocket reader is not running")
+
+    def _set_reader_exception(self, exc: Exception) -> None:
+        if self._reader_exception is None:
+            self._reader_exception = exc
+        if not self._initial_snapshot.done():
+            self._initial_snapshot.set_exception(self._reader_exception)
+        for future in list(self._pending.values()):
+            if not future.done():
+                future.set_exception(self._reader_exception)

upgrait_heatcontrol_api-0.1.0.dev0/src/upgrait_heatcontrol_api/crypto.py

@@ -0,0 +1,72 @@
+"""PyNaCl helpers shared by the API client connection stack."""
+
+from __future__ import annotations
+
+import base64
+import json
+import uuid
+from typing import Any
+
+import nacl.utils
+from nacl.public import Box, PrivateKey, PublicKey
+
+
+def b64e(value: bytes) -> str:
+    return base64.b64encode(value).decode("ascii")
+
+
+def b64d(value: str) -> bytes:
+    padded = (value or "").strip()
+    padded += "=" * ((-len(padded)) % 4)
+    return base64.b64decode(padded.encode("ascii"), validate=True)
+
+
+def generate_keypair() -> tuple[str, str]:
+    private_key = PrivateKey.generate()
+    return b64e(bytes(private_key)), b64e(bytes(private_key.public_key))
+
+
+def load_private_key(value: str) -> PrivateKey:
+    return PrivateKey(b64d(value))
+
+
+def load_public_key(value: str) -> PublicKey:
+    return PublicKey(b64d(value))
+
+
+def uuid4_hex() -> str:
+    return uuid.uuid4().hex
+
+
+def box_encrypt_json(
+    sender_private_key: PrivateKey,
+    recipient_public_key: PublicKey,
+    payload: dict[str, Any],
+) -> str:
+    nonce = nacl.utils.random(Box.NONCE_SIZE)
+    plaintext = json.dumps(payload, separators=(",", ":"), ensure_ascii=False).encode(
+        "utf-8"
+    )
+    ciphertext = Box(sender_private_key, recipient_public_key).encrypt(
+        plaintext, nonce
+    ).ciphertext
+    return b64e(nonce + ciphertext)
+
+
+def box_decrypt_json(
+    sender_public_key: PublicKey,
+    recipient_private_key: PrivateKey,
+    payload_b64: str,
+) -> dict[str, Any]:
+    raw = b64d(payload_b64)
+    if len(raw) <= Box.NONCE_SIZE:
+        raise ValueError("payload too short")
+    nonce = raw[: Box.NONCE_SIZE]
+    ciphertext = raw[Box.NONCE_SIZE :]
+    plaintext = Box(recipient_private_key, sender_public_key).decrypt(
+        ciphertext, nonce
+    )
+    decoded = json.loads(plaintext.decode("utf-8"))
+    if not isinstance(decoded, dict):
+        raise ValueError("payload must decode to object")
+    return decoded

upgrait_heatcontrol_api-0.1.0.dev0/src/upgrait_heatcontrol_api/discovery.py

@@ -0,0 +1,87 @@
+"""Discovery constants and metadata helpers shared by the API package and integrations."""
+
+from __future__ import annotations
+
+from dataclasses import dataclass
+from typing import Any
+
+from zeroconf import ServiceInfo
+
+DEFAULT_PORT = 8001
+SERVICE_TYPE = "_upgrait-hc._tcp.local."
+MANUFACTURER = "UPGRAIT GmbH"
+MODEL = "HeatControl"
+
+
+def _decode_discovery_value(value: object) -> str | None:
+    if value is None:
+        return None
+    if isinstance(value, bytes):
+        decoded = value.decode("utf-8", errors="strict").strip()
+        return decoded or None
+    if isinstance(value, str):
+        stripped = value.strip()
+        return stripped or None
+    raise ValueError(f"unsupported discovery value type: {type(value).__name__}")
+
+
+@dataclass(slots=True, frozen=True)
+class DiscoveryAdvertisement:
+    """Metadata returned by the connector ping endpoint for discovery state."""
+
+    service_type: str
+    advertised: bool
+    ip: str | None = None
+    service_name: str | None = None
+    last_error: str | None = None
+
+    @classmethod
+    def from_payload(cls, payload: dict[str, Any]) -> "DiscoveryAdvertisement":
+        if not isinstance(payload, dict):
+            raise ValueError("discovery payload must be an object")
+        advertised = payload.get("advertised")
+        if not isinstance(advertised, bool):
+            raise ValueError("discovery advertised must be a boolean")
+        service_type = payload.get("service_type")
+        if not isinstance(service_type, str) or not service_type.strip():
+            raise ValueError("discovery service_type must be a non-empty string")
+        return cls(
+            service_type=service_type.strip(),
+            advertised=advertised,
+            ip=_decode_discovery_value(payload.get("ip")),
+            service_name=_decode_discovery_value(payload.get("service_name")),
+            last_error=_decode_discovery_value(payload.get("last_error")),
+        )
+
+
+@dataclass(slots=True, frozen=True)
+class ZeroconfDiscoveryInfo:
+    """Normalized Zeroconf TXT-record properties for HeatControl discovery."""
+
+    name: str | None = None
+    serial: str | None = None
+    vendor: str | None = None
+    model: str | None = None
+    version: str | None = None
+
+    @classmethod
+    def from_properties(
+        cls, properties: dict[str | bytes, str | bytes]
+    ) -> "ZeroconfDiscoveryInfo":
+        normalized: dict[str, str | None] = {}
+        for key, value in properties.items():
+            normalized_key = _decode_discovery_value(key)
+            if normalized_key is None:
+                continue
+            normalized[normalized_key.lower()] = _decode_discovery_value(value)
+        return cls(
+            name=normalized.get("name"),
+            serial=normalized.get("serial"),
+            vendor=normalized.get("vendor"),
+            model=normalized.get("model"),
+            version=normalized.get("version"),
+        )
+
+    @classmethod
+    def from_service_info(cls, service_info: ServiceInfo) -> "ZeroconfDiscoveryInfo":
+        return cls.from_properties(service_info.properties)

upgrait_heatcontrol_api-0.1.0.dev0/src/upgrait_heatcontrol_api/exceptions.py

@@ -0,0 +1,21 @@
+"""Exception hierarchy for the HeatControl API package."""
+
+
+class HeatControlApiError(RuntimeError):
+    """Base API error."""
+
+
+class HeatControlApiConnectionError(HeatControlApiError):
+    """Raised when the device cannot be reached."""
+
+
+class HeatControlApiAuthError(HeatControlApiError):
+    """Raised when pairing or websocket binding is rejected."""
+
+
+class HeatControlApiInvalidPinError(HeatControlApiAuthError):
+    """Raised when the pairing pin is invalid."""
+
+
+class HeatControlApiProtocolError(HeatControlApiError):
+    """Raised when the connector speaks an unexpected protocol."""

upgrait_heatcontrol_api-0.1.0.dev0/src/upgrait_heatcontrol_api/models.py

@@ -0,0 +1,145 @@
+"""Value objects used by the HeatControl API package."""
+
+from __future__ import annotations
+
+from dataclasses import dataclass
+from typing import Any
+
+from .discovery import MANUFACTURER, MODEL
+
+
+def _require_object(payload: dict[str, Any], field: str) -> dict[str, Any]:
+    value = payload.get(field)
+    if not isinstance(value, dict):
+        raise ValueError(f"{field} payload missing object")
+    return value
+
+
+def _require_str(payload: dict[str, Any], field: str) -> str:
+    value = payload.get(field)
+    if not isinstance(value, str):
+        raise ValueError(f"{field} must be a string")
+    stripped = value.strip()
+    if not stripped:
+        raise ValueError(f"{field} must not be empty")
+    return stripped
+
+
+def _optional_str(payload: dict[str, Any], field: str) -> str | None:
+    value = payload.get(field)
+    if value is None:
+        return None
+    if not isinstance(value, str):
+        raise ValueError(f"{field} must be a string when provided")
+    stripped = value.strip()
+    return stripped or None
+
+
+def _require_int(payload: dict[str, Any], field: str) -> int:
+    value = payload.get(field)
+    if isinstance(value, bool):
+        raise ValueError(f"{field} must be an integer")
+    if isinstance(value, int):
+        return value
+    if isinstance(value, str):
+        stripped = value.strip()
+        if stripped:
+            try:
+                return int(stripped, 10)
+            except ValueError as exc:
+                raise ValueError(f"{field} must be an integer") from exc
+    raise ValueError(f"{field} must be an integer")
+
+
+def _require_bool(payload: dict[str, Any], field: str) -> bool:
+    value = payload.get(field)
+    if isinstance(value, bool):
+        return value
+    if isinstance(value, int) and value in {0, 1}:
+        return bool(value)
+    if isinstance(value, str):
+        normalized = value.strip().lower()
+        if normalized in {"true", "1"}:
+            return True
+        if normalized in {"false", "0"}:
+            return False
+    raise ValueError(f"{field} must be a boolean")
+
+
+@dataclass(slots=True, frozen=True)
+class DeviceInfo:
+    """Device information returned by the connector ping endpoint."""
+
+    serial: str
+    version: str
+    server_public_key: str
+    manufacturer: str = MANUFACTURER
+    model: str = MODEL
+    name: str | None = None
+
+    @classmethod
+    def from_ping_payload(cls, payload: dict[str, Any]) -> "DeviceInfo":
+        device = _require_object(payload, "device")
+        protocol = _require_object(payload, "protocol")
+        serial = _require_str(device, "serial")
+        version = _require_str(device, "version")
+        server_public_key = _require_str(protocol, "server_public_key")
+        manufacturer = _optional_str(device, "manufacturer") or MANUFACTURER
+        model = _optional_str(device, "model") or MODEL
+        name = _optional_str(device, "name")
+        return cls(
+            serial=serial,
+            version=version,
+            server_public_key=server_public_key,
+            manufacturer=manufacturer,
+            model=model,
+            name=name,
+        )
+
+
+@dataclass(slots=True, frozen=True)
+class PairingStartResult:
+    """Metadata returned after starting pairing."""
+
+    expires_at: int
+    pairing_active: bool
+    replaces_existing_binding: bool
+    existing_binding_display_name: str | None = None
+    server_public_key: str | None = None
+
+    @classmethod
+    def from_payload(cls, payload: dict[str, Any]) -> "PairingStartResult":
+        result = _require_object(payload, "result")
+        return cls(
+            expires_at=_require_int(result, "expires_at"),
+            pairing_active=_require_bool(result, "pairing_active"),
+            replaces_existing_binding=_require_bool(result, "replaces_existing_binding"),
+            existing_binding_display_name=_optional_str(
+                result, "existing_binding_display_name"
+            ),
+            server_public_key=_optional_str(result, "server_public_key"),
+        )
+
+
+@dataclass(slots=True, frozen=True)
+class PairingConfirmResult:
+    """Metadata returned after confirming pairing."""
+
+    ha_instance_id: str
+    display_name: str
+    integration_version: str
+    revision: int
+    confirmed_at: int
+    server_public_key: str
+
+    @classmethod
+    def from_payload(cls, payload: dict[str, Any]) -> "PairingConfirmResult":
+        result = _require_object(payload, "result")
+        return cls(
+            ha_instance_id=_require_str(result, "ha_instance_id"),
+            display_name=_require_str(result, "display_name"),
+            integration_version=_require_str(result, "integration_version"),
+            revision=_require_int(result, "revision"),
+            confirmed_at=_require_int(result, "confirmed_at"),
+            server_public_key=_require_str(result, "server_public_key"),
+        )

upgrait_heatcontrol_api-0.1.0.dev0/src/upgrait_heatcontrol_api.egg-info/PKG-INFO

@@ -0,0 +1,70 @@
+Metadata-Version: 2.4
+Name: upgrait-heatcontrol-api
+Version: 0.1.0.dev0
+Summary: Async Python API client for the UPGRAIT HeatControl 3rd-party connector.
+Author: UPGRAIT GmbH
+License-Expression: LicenseRef-UPGRAIT-Proprietary
+Requires-Python: >=3.12
+Description-Content-Type: text/markdown
+Requires-Dist: aiohttp<4,>=3.12
+Requires-Dist: PyNaCl<2,>=1.5
+Requires-Dist: zeroconf<1,>=0.136
+
+# upgrait-heatcontrol-api
+
+Async Python API package for the UPGRAIT HeatControl 3rd-party connector.
+
+The package is intended to be the external dependency consumed by the Home Assistant integration and by other 3rd-party clients.
+
+Current feature set:
+
+- HTTP probing via `/api/ping`
+- device metadata parsing
+- pairing start via `/api/pair/start`
+- pairing confirmation via `/api/pair/confirm`
+- websocket bind/session transport
+- encrypted request/response handling over the websocket session
+- initial snapshot handling and live event subscription
+- Zeroconf service constants and discovery metadata parsing helpers
+
+Installation:
+
+```bash
+pip install upgrait-heatcontrol-api
+```
+
+Example:
+
+```python
+import asyncio
+
+from upgrait_heatcontrol_api import HeatControlApiClient, generate_keypair
+
+
+async def main() -> None:
+    async with HeatControlApiClient(host="192.168.2.116", port=8001) as client:
+        device = await client.async_get_device_info()
+        print(device.serial, device.version)
+
+        private_key, public_key = generate_keypair()
+
+        pairing = await client.async_start_pairing(
+            ha_instance_id="example-ha-instance",
+            display_name="Example Client",
+            integration_version="0.1.0.dev0",
+        )
+        print(pairing.expires_at)
+
+        # The 6-digit PIN must be entered by the user after it is shown on the UHC. (Only available in new local interface, version >1610)
+        # confirm = await client.async_confirm_pairing(...)
+        # connection = await client.async_connect_and_bind(...)
+
+
+asyncio.run(main())
+```
+
+Notes:
+
+- `HeatControlApiClient` can manage its own `aiohttp` session. In that case, either use `async with HeatControlApiClient(...)` or call `await client.close()`.
+- `HeatControlConnection.subscribe()` registers callbacks for live websocket events and returns an unsubscribe function.
+- Discovery helpers cover both the `/api/ping` `discovery` payload and Zeroconf TXT-record property normalization.

upgrait_heatcontrol_api-0.1.0.dev0/src/upgrait_heatcontrol_api.egg-info/SOURCES.txt

@@ -0,0 +1,15 @@
+README.md
+pyproject.toml
+src/upgrait_heatcontrol_api/__init__.py
+src/upgrait_heatcontrol_api/client.py
+src/upgrait_heatcontrol_api/connection.py
+src/upgrait_heatcontrol_api/crypto.py
+src/upgrait_heatcontrol_api/discovery.py
+src/upgrait_heatcontrol_api/exceptions.py
+src/upgrait_heatcontrol_api/models.py
+src/upgrait_heatcontrol_api.egg-info/PKG-INFO
+src/upgrait_heatcontrol_api.egg-info/SOURCES.txt
+src/upgrait_heatcontrol_api.egg-info/dependency_links.txt
+src/upgrait_heatcontrol_api.egg-info/requires.txt
+src/upgrait_heatcontrol_api.egg-info/top_level.txt
+tests/test_client.py

upgrait_heatcontrol_api-0.1.0.dev0/src/upgrait_heatcontrol_api.egg-info/dependency_links.txt

@@ -0,0 +1 @@
+

upgrait_heatcontrol_api-0.1.0.dev0/src/upgrait_heatcontrol_api.egg-info/requires.txt

@@ -0,0 +1,3 @@
+aiohttp<4,>=3.12
+PyNaCl<2,>=1.5
+zeroconf<1,>=0.136

upgrait_heatcontrol_api-0.1.0.dev0/src/upgrait_heatcontrol_api.egg-info/top_level.txt

@@ -0,0 +1 @@
+upgrait_heatcontrol_api

upgrait_heatcontrol_api-0.1.0.dev0/tests/test_client.py

@@ -0,0 +1,222 @@
+import asyncio
+
+import pytest
+
+from upgrait_heatcontrol_api import DiscoveryAdvertisement, ZeroconfDiscoveryInfo
+from upgrait_heatcontrol_api.crypto import (
+    box_decrypt_json,
+    box_encrypt_json,
+    generate_keypair,
+    load_private_key,
+    load_public_key,
+)
+from upgrait_heatcontrol_api.client import HeatControlApiClient
+from upgrait_heatcontrol_api.connection import HeatControlConnection
+from upgrait_heatcontrol_api.exceptions import (
+    HeatControlApiConnectionError,
+    HeatControlApiProtocolError,
+)
+from upgrait_heatcontrol_api.models import DeviceInfo, PairingConfirmResult, PairingStartResult
+
+
+def test_base_url_uses_default_port() -> None:
+    client = HeatControlApiClient(host="192.0.2.10")
+    assert client.base_url == "http://192.0.2.10:8001"
+
+
+def test_base_url_wraps_ipv6_host() -> None:
+    client = HeatControlApiClient(host="2001:db8::1")
+    assert client.base_url == "http://[2001:db8::1]:8001"
+    assert client.ws_url == "ws://[2001:db8::1]:8001/ws"
+
+
+def test_device_info_from_ping_payload() -> None:
+    device = DeviceInfo.from_ping_payload(
+        {
+            "ok": True,
+            "protocol": {"server_public_key": "Zm9vYmFyYmF6cXV4Zm9vYmFyYmF6cXV4Zm9vYmFyYg=="},
+            "device": {
+                "serial": "UHC123456",
+                "version": "2026.03",
+                "manufacturer": "UPGRAIT GmbH",
+                "model": "HeatControl",
+            },
+        }
+    )
+    assert device.serial == "UHC123456"
+    assert device.version == "2026.03"
+    assert device.server_public_key
+
+
+def test_pairing_models_from_payloads() -> None:
+    start = PairingStartResult.from_payload(
+        {
+            "ok": True,
+            "result": {
+                "pairing_active": True,
+                "expires_at": 123,
+                "replaces_existing_binding": False,
+                "server_public_key": "server_key",
+            },
+        }
+    )
+    confirm = PairingConfirmResult.from_payload(
+        {
+            "ok": True,
+            "result": {
+                "ha_instance_id": "ha-id",
+                "display_name": "Home Assistant",
+                "integration_version": "0.1.0-dev",
+                "revision": 2,
+                "confirmed_at": 456,
+                "server_public_key": "server_key",
+            },
+        }
+    )
+    assert start.pairing_active is True
+    assert confirm.revision == 2
+
+
+def test_pairing_start_model_rejects_invalid_boolean_strings() -> None:
+    with pytest.raises(ValueError, match="pairing_active must be a boolean"):
+        PairingStartResult.from_payload(
+            {
+                "ok": True,
+                "result": {
+                    "pairing_active": "yes",
+                    "expires_at": 123,
+                    "replaces_existing_binding": False,
+                },
+            }
+        )
+
+
+def test_pairing_confirm_model_requires_non_empty_strings() -> None:
+    with pytest.raises(ValueError, match="server_public_key must not be empty"):
+        PairingConfirmResult.from_payload(
+            {
+                "ok": True,
+                "result": {
+                    "ha_instance_id": "ha-id",
+                    "display_name": "Home Assistant",
+                    "integration_version": "0.1.0-dev",
+                    "revision": 2,
+                    "confirmed_at": 456,
+                    "server_public_key": " ",
+                },
+            }
+        )
+
+
+def test_discovery_helpers_parse_payloads() -> None:
+    advertisement = DiscoveryAdvertisement.from_payload(
+        {
+            "service_type": "_upgrait-hc._tcp.local.",
+            "advertised": True,
+            "ip": "192.0.2.10",
+            "service_name": "UPGRAIT HeatControl UHC123._upgrait-hc._tcp.local.",
+            "last_error": None,
+        }
+    )
+    zeroconf_info = ZeroconfDiscoveryInfo.from_properties(
+        {
+            b"name": b"UPGRAIT HeatControl",
+            b"serial": b"UHC123456",
+            b"vendor": b"UPGRAIT GmbH",
+            b"model": b"HeatControl",
+            b"version": b"2026.03",
+        }
+    )
+    assert advertisement.advertised is True
+    assert zeroconf_info.serial == "UHC123456"
+
+
+def test_crypto_roundtrip() -> None:
+    sender_private_b64, sender_public_b64 = generate_keypair()
+    recipient_private_b64, recipient_public_b64 = generate_keypair()
+    payload = {"type": "req", "method": "ping"}
+    encrypted = box_encrypt_json(
+        load_private_key(sender_private_b64),
+        load_public_key(recipient_public_b64),
+        payload,
+    )
+    decrypted = box_decrypt_json(
+        load_public_key(sender_public_b64),
+        load_private_key(recipient_private_b64),
+        encrypted,
+    )
+    assert decrypted == payload
+
+
+@pytest.mark.asyncio
+async def test_client_closes_only_owned_session() -> None:
+    external_session = object()
+    client = HeatControlApiClient(host="192.0.2.10", session=external_session)  # type: ignore[arg-type]
+    await client.close()
+    assert client._session is external_session
+
+
+@pytest.mark.asyncio
+async def test_client_close_releases_owned_session() -> None:
+    client = HeatControlApiClient(host="192.0.2.10")
+    session = await client._get_session()
+    await client.close()
+    assert session.closed is True
+    assert client._session is None
+
+
+class _FakeWebSocket:
+    def __init__(self) -> None:
+        self.closed = False
+
+    async def close(self) -> None:
+        self.closed = True
+
+    async def send_json(self, _payload: object) -> None:
+        return None
+
+
+@pytest.mark.asyncio
+async def test_connection_request_raises_reader_failure_immediately() -> None:
+    connection = HeatControlConnection(
+        session=object(),  # type: ignore[arg-type]
+        ws=_FakeWebSocket(),  # type: ignore[arg-type]
+        ha_instance_id="ha-id",
+        ha_private_key=generate_keypair()[0],
+        server_public_key=generate_keypair()[1],
+    )
+    connection._reader_exception = HeatControlApiConnectionError("reader failed")
+    with pytest.raises(HeatControlApiConnectionError, match="reader failed"):
+        await connection.request("cfg_get")
+
+
+@pytest.mark.asyncio
+async def test_connection_request_requires_started_connection() -> None:
+    private_key, _public_key = generate_keypair()
+    _server_private_key, server_public_key = generate_keypair()
+    connection = HeatControlConnection(
+        session=object(),  # type: ignore[arg-type]
+        ws=_FakeWebSocket(),  # type: ignore[arg-type]
+        ha_instance_id="ha-id",
+        ha_private_key=private_key,
+        server_public_key=server_public_key,
+    )
+    with pytest.raises(HeatControlApiProtocolError, match="has not been started"):
+        await connection.request("cfg_get")
+
+
+@pytest.mark.asyncio
+async def test_connection_request_raises_if_reader_task_stopped() -> None:
+    private_key, _public_key = generate_keypair()
+    _server_private_key, server_public_key = generate_keypair()
+    connection = HeatControlConnection(
+        session=object(),  # type: ignore[arg-type]
+        ws=_FakeWebSocket(),  # type: ignore[arg-type]
+        ha_instance_id="ha-id",
+        ha_private_key=private_key,
+        server_public_key=server_public_key,
+    )
+    connection._reader_task = asyncio.create_task(asyncio.sleep(0))
+    await connection._reader_task
+    with pytest.raises(HeatControlApiConnectionError, match="reader is not running"):
+        await connection.request("cfg_get")