flow-it-api 0.0.1.0b4__py3-none-any.whl

flow_it_api/__init__.py

@@ -0,0 +1,13 @@
+"""Python API library client for the FlowIt VMC machine."""
+
+import logging
+from importlib.metadata import PackageNotFoundError, version
+
+try:
+    __version__ = version("flow-it-api")
+except PackageNotFoundError:
+    # Package is not installed
+    __version__ = "0.0.0"
+
+_LOGGER = logging.getLogger(__name__)
+_LOGGER.info("Loading flow-it-api version %s", __version__)

flow_it_api/auth.py

@@ -0,0 +1,98 @@
+"""Authentication management for the FlowIt VMC API."""
+
+import time
+from typing import Optional
+
+import httpx
+
+from .const import DEFAULT_USERNAME, TIMEOUT
+from .exceptions import FlowItAuthError, FlowItConnectionError
+from .models import AuthResponse
+
+
+class Authenticator:
+    """Handles JWT authentication and token lifecycle."""
+
+    def __init__(
+        self,
+        host: str,
+        password: str,
+        username: str = DEFAULT_USERNAME,
+        client: Optional[httpx.AsyncClient] = None,
+    ):
+        """
+        Initialize the authenticator.
+
+        :param host: Base URL of the VMC machine.
+        :param password: API password.
+        :param username: API username.
+        :param client: Optional existing HTTPX async client.
+        """
+        self.host = host.rstrip("/")
+        self.username = username
+        self.password = password
+        self._client = client
+        self._token: Optional[str] = None
+        self._expires_at: float = 0
+
+    @property
+    def token(self) -> Optional[str]:
+        """
+        Return the current token if it is still valid.
+
+        :return: Token string or None if expired or not set.
+        """
+        if self._token and time.time() < self._expires_at:
+            return self._token
+        return None
+
+    async def login(self) -> str:
+        """
+        Login to the device and return the JWT token.
+
+        :return: JWT token string.
+        :raises FlowItAuthError: If credentials are invalid.
+        :raises FlowItConnectionError: If connection fails.
+        """
+        url = f"{self.host}/auth"
+        data = {"username": self.username, "password": self.password}
+
+        own_client = False
+        if self._client is None:
+            self._client = httpx.AsyncClient(timeout=TIMEOUT)
+            own_client = True
+
+        try:
+            response = await self._client.post(url, json=data)
+            if response.status_code == 401:
+                raise FlowItAuthError("Invalid credentials")
+
+            response.raise_for_status()
+            auth_data = AuthResponse(**response.json())
+
+            self._token = auth_data.token
+            # Set expiration with a 30s buffer
+            self._expires_at = time.time() + auth_data.expires_in - 30
+            return self._token
+        except httpx.HTTPError as e:
+            raise FlowItConnectionError(f"Failed to connect to {url}: {e}") from e
+        finally:
+            if own_client:
+                await self._client.aclose()
+                self._client = None
+
+    async def get_valid_token(self) -> str:
+        """
+        Return a valid token, logging in if necessary.
+
+        :return: Valid JWT token string.
+        """
+        token = self.token
+        if token:
+            return token
+        return await self.login()
+
+    def invalidate_token(self) -> None:
+        """Invalidate the current token forcing a re-login on next request."""
+        self._token = None
+        self._expires_at = 0

flow_it_api/client.py

@@ -0,0 +1,221 @@
+"""Main client for interacting with the FlowIt VMC machine."""
+
+from functools import wraps
+from typing import Any, Callable, Optional, TypeVar, cast
+
+import httpx
+
+from .auth import Authenticator
+from .const import DEFAULT_USERNAME, TIMEOUT, Speed
+from .exceptions import FlowItCommandError, FlowItConnectionError, FlowItResponseError
+from .models import (
+    CommandRequest,
+    CommandResponse,
+    MachineData,
+    MachineInfoResponse,
+    MachineStatusResponse,
+)
+from .websocket import FlowItWebSocket
+
+F = TypeVar("F", bound=Callable[..., Any])
+
+
+def authenticated(func: F) -> F:
+    """
+    Decorator to ensure the client is authenticated before calling a method.
+
+    Automatically handles token refresh if a 401 Unauthorized is received.
+    """
+
+    @wraps(func)
+    async def wrapper(self: "FlowItVMCMachine", *args: Any, **kwargs: Any) -> Any:
+        token = await self._auth.get_valid_token()
+        try:
+            return await func(self, token, *args, **kwargs)
+        except httpx.HTTPStatusError as e:
+            if e.response.status_code == 401:
+                self._auth.invalidate_token()
+                token = await self._auth.get_valid_token()
+                return await func(self, token, *args, **kwargs)
+            raise
+
+    return cast(F, wrapper)
+
+
+class FlowItVMCMachine:
+    """Primary API client for FlowIt VMC devices."""
+
+    def __init__(
+        self,
+        host: str,
+        password: str,
+        username: str = DEFAULT_USERNAME,
+        session: Optional[httpx.AsyncClient] = None,
+    ):
+        """
+        Initialize the VMC machine client.
+
+        :param host: Base URL of the VMC machine.
+        :param password: API password.
+        :param username: API username.
+        :param session: Optional existing HTTPX async client (session).
+        """
+        self.host = host.rstrip("/")
+        self._session = session
+        self._own_session = False
+        if self._session is None:
+            self._session = httpx.AsyncClient(timeout=TIMEOUT)
+            self._own_session = True
+
+        self._auth = Authenticator(self.host, password, username, client=self._session)
+        self._state: Optional[MachineStatusResponse] = None
+        self._info: Optional[MachineInfoResponse] = None
+        self._ws: Optional[FlowItWebSocket] = None
+
+    @property
+    def websocket(self) -> FlowItWebSocket:
+        """
+        Return the websocket client for real-time updates.
+
+        :return: FlowItWebSocket instance.
+        """
+        if self._ws is None:
+            self._ws = FlowItWebSocket(
+                self.host, self._auth, on_data=self._async_handle_ws_data
+            )
+        return self._ws
+
+    async def _async_handle_ws_data(self, data: MachineData) -> None:
+        """
+        Internal handler for data received from the websocket.
+
+        :param data: Parsed machine data from the WS event.
+        """
+        if self._state:
+            self._state.data = data
+        else:
+            # If we don't have a full state yet, we just initialize the data part
+            # but we won't have the top-level fields like name, chrono_id, etc.
+            # until a refresh_state is called.
+            pass
+
+    @property
+    def machine_state(self) -> Optional[MachineData]:
+        """
+        Return the current machine data if available.
+
+        :return: MachineData or None.
+        """
+        if self._state:
+            return self._state.data
+        return None
+
+    @property
+    def is_connected(self) -> bool:
+        """
+        Return True if the client has successfully fetched the state.
+
+        :return: Connection status boolean.
+        """
+        return self._state is not None
+
+    @property
+    def _http(self) -> httpx.AsyncClient:
+        """Return the async client, ensuring it is initialized."""
+        if self._session is None:
+            # Fallback in case of unexpected state
+            self._session = httpx.AsyncClient(timeout=TIMEOUT)
+            self._own_session = True
+        return self._session
+
+    async def get_info(self) -> MachineInfoResponse:
+        """
+        Fetch basic machine information (Model, FW, HW versions).
+
+        Does not require authentication.
+
+        :return: MachineInfoResponse instance.
+        :raises FlowItConnectionError: If connection fails.
+        """
+        url = f"{self.host}/info"
+        try:
+            response = await self._http.get(url)
+            response.raise_for_status()
+            self._info = MachineInfoResponse(**response.json())
+            return self._info
+        except httpx.HTTPError as e:
+            raise FlowItConnectionError(f"Failed to fetch info: {e}") from e
+
+    @authenticated
+    async def refresh_state(self, token: str) -> MachineData:
+        """
+        Fetch the full machine state via REST API.
+
+        :param token: JWT token (provided by @authenticated).
+        :return: MachineData instance.
+        :raises FlowItConnectionError: If connection fails.
+        :raises FlowItResponseError: If parsing fails.
+        """
+        url = f"{self.host}/status"
+        headers = {"Authorization": f"Bearer {token}"}
+
+        try:
+            response = await self._http.get(url, headers=headers)
+            response.raise_for_status()
+            self._state = MachineStatusResponse(**response.json())
+            return self._state.data
+        except httpx.HTTPError as e:
+            raise FlowItConnectionError(f"Failed to refresh state: {e}") from e
+        except Exception as e:
+            raise FlowItResponseError(f"Failed to parse state response: {e}") from e
+
+    @authenticated
+    async def send_command(
+        self, token: str, speed: Speed, flow_in: bool, flow_out: bool
+    ) -> CommandResponse:
+        """
+        Send a command to update speed and flow settings.
+
+        :param token: JWT token (provided by @authenticated).
+        :param speed: Target fan speed level.
+        :param flow_in: Enable/disable inflow.
+        :param flow_out: Enable/disable outflow.
+        :return: CommandResponse instance.
+        :raises FlowItCommandError: If the command fails.
+        """
+        url = f"{self.host}/command"
+        headers = {"Authorization": f"Bearer {token}"}
+
+        command = CommandRequest(speed=speed, flowIn=flow_in, flowOut=flow_out)
+
+        try:
+            response = await self._http.post(
+                url, json=command.model_dump(), headers=headers
+            )
+            response.raise_for_status()
+            cmd_resp = CommandResponse(**response.json())
+
+            # Optimistically update local state if we have one
+            if self._state:
+                self._state.data.mode.speed = cmd_resp.speed
+                self._state.data.mode.flowIn = cmd_resp.flowIn
+                self._state.data.mode.flowOut = cmd_resp.flowOut
+
+            return cmd_resp
+        except httpx.HTTPError as e:
+            raise FlowItCommandError(f"Command failed: {e}") from e
+
+    async def close(self) -> None:
+        """Close the underlying HTTP client (if owned) and stop websocket listener."""
+        if self._ws:
+            await self._ws.stop()
+        if self._own_session and self._session:
+            await self._session.aclose()
+
+    async def __aenter__(self) -> "FlowItVMCMachine":
+        """Async context manager entry."""
+        return self
+
+    async def __aexit__(self, exc_type: Any, exc_val: Any, exc_tb: Any) -> None:
+        """Async context manager exit."""
+        await self.close()

flow_it_api/const.py

@@ -0,0 +1,48 @@
+"""Constants for the FlowIt VMC API."""
+
+from enum import IntEnum, StrEnum
+
+
+class Speed(StrEnum):
+    """VMC Fan speed levels."""
+
+    OFF = "off"
+    LEVEL_1 = "1"
+    LEVEL_2 = "2"
+    LEVEL_3 = "3"
+    LEVEL_4 = "4"
+    LEVEL_5 = "5"
+    AUTO = "auto"
+    BOOST = "boost"
+
+
+class BypassMode(StrEnum):
+    """VMC Bypass operation modes."""
+
+    IN_OUT = "0"
+    IN_ONLY = "1"
+    OUT_ONLY = "2"
+
+
+class FilterStatus(IntEnum):
+    """Filter cleanliness status percentage/level."""
+
+    DIRTY_0 = 0
+    DIRTY_25 = 1
+    DIRTY_50 = 2
+    DIRTY_75 = 3
+    CLEAN = 4
+
+
+class AlertFilterStatus(IntEnum):
+    """Alert status for filter maintenance."""
+
+    CLEAN = 0
+    DIRTY = 1
+    CLOGGED = 2
+    MISSING = 3
+    NOT_CHECKED = 4
+
+
+DEFAULT_USERNAME = "api"
+TIMEOUT = 10

flow_it_api/exceptions.py

@@ -0,0 +1,21 @@
+"""Exceptions for the FlowIt VMC API."""
+
+
+class FlowItError(Exception):
+    """Base exception for flow-it-api."""
+
+
+class FlowItAuthError(FlowItError):
+    """Exception raised for authentication errors."""
+
+
+class FlowItConnectionError(FlowItError):
+    """Exception raised for connection errors."""
+
+
+class FlowItResponseError(FlowItError):
+    """Exception raised for invalid or error responses from the device."""
+
+
+class FlowItCommandError(FlowItError):
+    """Exception raised when a command fails."""

flow_it_api/models.py

@@ -0,0 +1,182 @@
+"""Data models for the FlowIt VMC API."""
+
+from typing import Annotated, Any
+
+from pydantic import BaseModel, BeforeValidator, ConfigDict, Field
+
+from .const import AlertFilterStatus, BypassMode, FilterStatus, Speed
+
+
+def parse_bool(v: Any) -> bool:
+    """
+    Parse a value as a boolean.
+
+    Supports string values like "TRUE" and "FALSE".
+    """
+    if isinstance(v, str):
+        if v.upper() == "TRUE":
+            return True
+        if v.upper() == "FALSE":
+            return False
+    return bool(v)
+
+
+FlowItBool = Annotated[bool, BeforeValidator(parse_bool)]
+
+
+def parse_sensor_value(v: Any) -> float | None:
+    """Parse sensor reading, returning None if 0."""
+    try:
+        val = float(v)
+        if val == 0.0:
+            return None
+        return val
+    except (TypeError, ValueError):
+        return None
+
+
+FlowItSensorValue = Annotated[float | None, BeforeValidator(parse_sensor_value)]
+
+
+class SensorReadings(BaseModel):
+    """Raw sensor readings (pressure, temperature, humidity)."""
+
+    pressure: FlowItSensorValue
+    temperature: FlowItSensorValue
+    humidity: FlowItSensorValue
+
+    @property
+    def temperature_celsius(self) -> float | None:
+        """Return temperature in Celsius."""
+        if self.temperature is None:
+            return None
+        return round(self.temperature - 273.15, 2)
+
+
+class MachineSensors(BaseModel):
+    """Collection of all machine sensors."""
+
+    Sin: SensorReadings = Field(..., description="Inflow sensor before fan")
+    Sout: SensorReadings = Field(..., description="Inflow sensor after fan")
+    Iin: SensorReadings = Field(..., description="Extraction sensor before fan")
+    Iout: SensorReadings = Field(..., description="Extraction sensor after fan")
+
+
+class MachineMode(BaseModel):
+    """Machine operation mode and environmental data."""
+
+    speed: Speed
+    autoSpeed: str
+    flowIn: FlowItBool
+    flowOut: FlowItBool
+    bypassMode: BypassMode
+    iaq: int
+    temperatureIn: FlowItSensorValue
+    temperatureOut: FlowItSensorValue
+    humidityIn: FlowItSensorValue
+    humidityOut: FlowItSensorValue
+    pressureIn: FlowItSensorValue
+    pressureOut: FlowItSensorValue
+    bypassOn: FlowItBool = False
+
+    @property
+    def temperatureIn_celsius(self) -> float | None:
+        """Return inflow temperature in Celsius."""
+        if self.temperatureIn is None:
+            return None
+        return round(self.temperatureIn - 273.15, 2)
+
+    @property
+    def temperatureOut_celsius(self) -> float | None:
+        """Return outflow temperature in Celsius."""
+        if self.temperatureOut is None:
+            return None
+        return round(self.temperatureOut - 273.15, 2)
+
+
+class FilterDetail(BaseModel):
+    """Detailed filter information."""
+
+    status: FilterStatus
+    changed: int
+
+
+class MachineFilter(BaseModel):
+    """Machine filter status (HEPA and G4)."""
+
+    hepa: FilterDetail
+    g4: FilterDetail
+
+
+class MachineAlert(BaseModel):
+    """Machine alerts and diagnostic status."""
+
+    update_reboot: FlowItBool
+    worries: FlowItBool
+    ice: FlowItBool
+    condensation: FlowItBool
+    filterS: AlertFilterStatus
+    filterI: AlertFilterStatus
+    warmup: FlowItBool
+    service: FlowItBool
+    fault_code: str = Field(..., alias="fault-code")
+    net_fault_code: str = Field(..., alias="net-fault-code")
+    version: str
+
+
+class MachineData(BaseModel):
+    """Complete machine data container."""
+
+    event: str
+    sensors: MachineSensors
+    mode: MachineMode
+    filter: MachineFilter
+    alert: MachineAlert
+
+
+class MachineStatusResponse(BaseModel):
+    """Full machine status response from REST/WS."""
+
+    model_config = ConfigDict(populate_by_name=True)
+
+    lastUpdate: int
+    chrono_id: str
+    status: FlowItBool
+    name: str
+    data: MachineData
+
+
+class MachineInfoResponse(BaseModel):
+    """Machine information response (version info)."""
+
+    model: str
+    api_ver: str
+    fw_ver: str
+    hw_ver: str
+    hostname: str
+
+
+class AuthResponse(BaseModel):
+    """Authentication response with JWT token."""
+
+    token: str
+    user: str
+    expires_in: int
+
+
+class CommandRequest(BaseModel):
+    """Request model for sending commands to the machine."""
+
+    type_message: str = "set_parameters"
+    speed: Speed
+    flowIn: bool
+    flowOut: bool
+
+
+class CommandResponse(BaseModel):
+    """Response from a command execution."""
+
+    status: str
+    speed: Speed
+    flowIn: bool
+    flowOut: bool

flow_it_api/websocket.py

@@ -0,0 +1,92 @@
+"""WebSocket client for the FlowIt VMC API."""
+
+import asyncio
+import json
+import logging
+from typing import Awaitable, Callable, Optional
+
+import websockets
+
+from .auth import Authenticator
+from .models import MachineData, MachineStatusResponse
+
+_LOGGER = logging.getLogger(__name__)
+
+
+class FlowItWebSocket:
+    """Handles real-time updates from the VMC machine via WebSocket."""
+
+    def __init__(
+        self,
+        host: str,
+        auth: Authenticator,
+        on_data: Optional[Callable[[MachineData], Awaitable[None]]] = None,
+    ):
+        """
+        Initialize the WebSocket client.
+
+        :param host: Base URL of the VMC machine.
+        :param auth: Authenticator instance for token management.
+        :param on_data: Optional async callback for received data.
+        """
+        self.host = (
+            host.replace("http://", "ws://").replace("https://", "wss://").rstrip("/")
+        )
+        self._auth = auth
+        self._on_data = on_data
+        self._stop = False
+        self._task: Optional[asyncio.Task] = None
+
+    async def listen(self) -> None:
+        """
+        Start the websocket listener loop.
+
+        Handles reconnection and authentication automatically.
+        """
+        url = f"{self.host}/ws"
+
+        while not self._stop:
+            try:
+                token = await self._auth.get_valid_token()
+                headers = {"Authorization": f"Bearer {token}"}
+
+                async with websockets.connect(url, additional_headers=headers) as ws:
+                    _LOGGER.info("Connected to WebSocket: %s", url)
+                    async for message in ws:
+                        if self._stop:
+                            break
+
+                        try:
+                            data_dict = json.loads(message)
+                            # The WS might send the full MachineStatusResponse or just MachineData
+                            # Based on specs, it's usually the full status
+                            status = MachineStatusResponse(**data_dict)
+                            if self._on_data:
+                                await self._on_data(status.data)
+                        except Exception as e:
+                            _LOGGER.error("Failed to parse WebSocket message: %s", e)
+
+            except (websockets.ConnectionClosed, OSError) as e:
+                if not self._stop:
+                    _LOGGER.warning("WebSocket connection lost, retrying in 5s: %s", e)
+                    await asyncio.sleep(5)
+            except Exception as e:
+                if not self._stop:
+                    _LOGGER.error("WebSocket unexpected error: %s", e)
+                    await asyncio.sleep(5)
+
+    def start(self) -> None:
+        """Start the websocket listener in a background task."""
+        self._stop = False
+        self._task = asyncio.create_task(self.listen())
+
+    async def stop(self) -> None:
+        """Stop the websocket listener and cancel the task."""
+        self._stop = True
+        if self._task:
+            self._task.cancel()
+            try:
+                await self._task
+            except asyncio.CancelledError:
+                pass
+            self._task = None