thermoworks-cloud 0.1.1__py3-none-any.whl

thermoworks_cloud/__init__.py

@@ -0,0 +1,4 @@
+from .auth import AuthFactory
+from .core import ThermoworksCloud
+
+__all__ = ["ThermoworksCloud", "AuthFactory"]

thermoworks_cloud/auth.py

@@ -0,0 +1,291 @@
+"""Manage authentication for the Thermoworks Cloud API."""
+
+from abc import ABC, abstractmethod
+from datetime import datetime, timedelta
+from enum import Enum
+from typing import Protocol, TypedDict, cast
+
+from aiohttp import ClientResponse, ClientResponseError, ClientSession
+
+from .models.user_credentials import UserCredentials, UserLoginResponse
+
+class Auth(Protocol):
+    """
+    Interface for making authenticated requests.
+    """
+    @property
+    def user_id(self) -> str:
+        ...
+        
+    async def async_get_access_token(self) -> str:
+        ...
+
+    async def request(self, method, url, **kwargs) -> ClientResponse:
+        ...
+
+class _AuthBase(ABC, Auth):
+    """Abstract class to make authenticated requests."""
+
+    def __init__(self, websession: ClientSession, host: str, api_key: str) -> None:
+        """Initialize the auth."""
+        self.websession = websession
+        self.host = host
+        self.api_key = api_key
+
+    @abstractmethod
+    async def async_get_access_token(self) -> str:
+        """Return a valid access token."""
+
+    async def request(self, method, url) -> ClientResponse:
+        """Make a request."""
+
+        access_token = await self.async_get_access_token()
+        headers = {
+            "authorization": f"Bearer {access_token}"
+        }
+        url = f"{self.host}/{url}?key={self.api_key}"
+
+        return await self.websession.request(
+            method,
+            url,
+            headers=headers,
+        )
+
+
+def is_expired(expiration_time, buffer_seconds=60):
+    """Determine if the key needs renewal based on a buffer time.
+
+    Args:
+        expiration_time (datetime): The calculated expiration time of the key.
+        buffer_seconds (int): Time before expiration to renew the key (default is 60 seconds).
+
+    Returns:
+        bool: True if the key needs renewal, False otherwise.
+
+    """
+    # Get the current time
+    current_time = datetime.now()
+    experation_threshold = expiration_time - timedelta(seconds=buffer_seconds)
+
+    # Check if the key is within the renewal buffer time
+    return current_time >= experation_threshold
+
+
+class WebConfigResponse(TypedDict):
+    """Similar to <https://firebase.google.com/docs/reference/firebase-management/rest/v1beta1/projects>."""
+
+    projectId: str
+    appId: str
+    databaseURL: str
+    storageBucket: str
+    locationId: str
+    authDomain: str
+    messagingSenderId: str
+    measurementId: str
+
+
+class FirestoreError(TypedDict):
+    """See <https://firebase.google.com/docs/reference/rest/auth#section-error-format>."""
+
+    message: str
+    domain: str
+    reason: str
+
+
+class ErrorResponse(TypedDict):
+    """See <https://firebase.google.com/docs/reference/rest/auth#section-error-format>."""
+
+    code: int
+    message: str
+    errors: list[FirestoreError]
+
+
+class AuthenticationErrorReason(Enum):
+    """From <https://firebase.google.com/docs/reference/rest/auth?authuser=0#section-sign-in-email-password>."""
+
+    INVALID_EMAIL = "INVALID_EMAIL"
+    EMAIL_NOT_FOUND = "EMAIL_NOT_FOUND"
+    INVALID_PASSWORD = "INVALID_PASSWORD"
+    USER_DISABLED = "USER_DISABLED"
+
+
+class AuthenticationError(Exception):
+    """Custom exception for authentication errors."""
+
+    def __init__(
+        self,
+        message: str,
+        reason: AuthenticationErrorReason,
+        details: list[FirestoreError],
+    ) -> None:
+        """Initialize an authentication error."""
+
+        super().__init__(f"Error authenticating with Firestore: {reason.value}")
+        self.message = message
+        self.reason = reason
+        self.details = details
+
+
+class _TokenManager:
+    """Manage access tokens for Auth."""
+
+    _IDENTITY_HOST = "https://identitytoolkit.googleapis.com"
+    _TOKEN_HOST = "https://securetoken.googleapis.com"
+
+    _user_credentials: UserCredentials
+
+
+    def __init__(self, websession: ClientSession, api_key: str) -> None:
+        """Initialize token manager."""
+        self._websession = websession
+        self._api_key = api_key
+
+    async def login(self, email: str, password: str) -> None:
+        """Exchange login credentials for token credentials."""
+
+        url = f"{self._IDENTITY_HOST}/v1/accounts:signInWithPassword"
+        query = {"key": self._api_key}
+        headers = {"Content-Type": "application/json"}
+        json = {
+            "email": email,
+            "password": password,
+            "returnSecureToken": True,
+        }
+
+        response = await self._websession.request(
+            "post", url, headers=headers, json=json, params=query
+        )
+
+        if response.ok:
+            login_response = await response.json()
+            cast(UserLoginResponse, login_response)
+            self._user_credentials = UserCredentials.from_user_login_response(
+                login_response
+            )
+        elif response.status == 400:
+            login_response = await response.json()
+            if login_response["error"]:
+                error_response = cast(ErrorResponse, login_response["error"])
+                error_message = error_response["message"]
+                error_details = error_response["errors"]
+
+                if error_message in AuthenticationErrorReason._value2member_map_:
+                    raise AuthenticationError(
+                        message=f"Authentication failed: {error_message}",
+                        reason=AuthenticationErrorReason(error_message),
+                        details=error_details,
+                    )
+        else:
+            try:
+                response.raise_for_status()
+            except ClientResponseError as e:
+                raise RuntimeError("Unable to authenticate") from e
+
+    @property
+    def user_id(self) -> str:
+        """Return id of the user that the manager is authenticate with."""
+        return self._user_credentials.user_id
+
+    @property
+    def access_token(self) -> str:
+        """Return an access token for use with Auth."""
+        return self._user_credentials.access_token
+
+    def is_token_valid(self) -> bool:
+        """Return a bool indicating whether the token is expired."""
+
+        return not is_expired(self._user_credentials.expiration_time)
+
+    async def refresh_access_token(self) -> None:
+        """Refresh the access token."""
+
+        url = f"{self._TOKEN_HOST}/v1/token?key={self._api_key}"
+        headers = {"Content-Type": "application/json"}
+        json = {
+            "grant_type": "refresh_token",
+            "refresh_token": self._user_credentials.refresh_token,
+        }
+
+        response = await self._websession.request(
+            "post", url, headers=headers, json=json
+        )
+        response.raise_for_status()
+        refresh_token_response = await response.json()
+        self._user_credentials = UserCredentials.from_refresh_token_response(
+            refresh_token_response
+        )
+
+
+class _Auth(_AuthBase):
+    """Execute authenticated requests."""
+
+    def __init__(
+        self,
+        websession: ClientSession,
+        api_url_root: str,
+        api_key: str,
+        token_manager: _TokenManager,
+    ) -> None:
+        """Initialize the auth."""
+        super().__init__(websession, api_url_root, api_key)
+        self.token_manager = token_manager
+
+    @property
+    def user_id(self) -> str:
+        """The id of the user that is authenticated."""
+        return self.token_manager.user_id
+
+    async def async_get_access_token(self) -> str:
+        """Return a valid access token."""
+        if self.token_manager.is_token_valid():
+            return self.token_manager.access_token
+
+        await self.token_manager.refresh_access_token()
+        return self.token_manager.access_token
+
+
+class AuthFactory:
+    """Create Auth objects."""
+
+    _API_KEY = "AIzaSyCf079iccUFc1k7VHdGXng22zXDy8Y3KEY"
+    _APP_ID = "1:78998049458:web:b41e9d405d8c7de95eefab"
+    _FIREBASE_HOST = "https://firebase.googleapis.com"
+    _FIRESTORE_HOST = "https://firestore.googleapis.com"
+
+    _config: WebConfigResponse
+
+    def __init__(self, websession: ClientSession) -> None:
+        """Initialize the factory."""
+
+        assert websession is not None, "parameter cannot be None"
+        self._websession = websession
+
+    async def get_config(self) -> None:
+        """Get the Firestore project information for this application."""
+
+        url = f"{self._FIREBASE_HOST}/v1alpha/projects/-/apps/{self._APP_ID}/webConfig"
+        headers = {
+            "accept": "application/json",
+            "x-goog-api-key": self._API_KEY,
+        }
+
+        try:
+            response = await self._websession.request("get", url, headers=headers)
+            response.raise_for_status()
+            self._config: WebConfigResponse = await response.json()
+        except Exception as e:
+            raise RuntimeError("Unable to fetch application configuration") from e
+
+    async def build_auth(self, email: str, password: str) -> Auth:
+        """Build an Auth instance."""
+
+        await self.get_config()
+
+        token_manager = _TokenManager(self._websession, self._API_KEY)
+        await token_manager.login(email, password)
+        return _Auth(
+            self._websession,
+            api_url_root=f"{self._FIRESTORE_HOST}/v1/projects/{self._config['projectId']}/databases/(default)/documents",
+            api_key=self._API_KEY,
+            token_manager=token_manager,
+        )

thermoworks_cloud/core.py

@@ -0,0 +1,85 @@
+"""Accessor for the Thermoworks Cloud API."""
+
+import logging
+
+from thermoworks_cloud.utils import format_client_response
+from .auth import Auth
+from .models.device import Device, document_to_device
+from .models.device_channel import DeviceChannel, document_to_device_channel
+from .models.user import User, document_to_user
+
+
+_LOGGER = logging.getLogger(__name__)
+
+class ThermoworksCloud:
+    """Accessor for the Thermoworks Cloud API."""
+
+    def __init__(self, auth: Auth) -> None:
+        """Initialize the API."""
+        self._auth = auth
+
+    async def get_user(self) -> User:
+        """Fetch information for the authenticated user."""
+
+        try:
+            response = await self._auth.request("get", f"users/{self._auth.user_id}")
+            if response.ok:
+                user_document = await response.json()
+                return document_to_user(user_document)
+      
+            try:
+                error_response = await format_client_response(response)
+            except:
+                error_response = "Could not read response body."
+            _LOGGER.error("Received error response while getting user: %s", error_response)
+
+            response.raise_for_status()
+
+        except Exception as e:
+            raise RuntimeError("Failed to get user") from e
+            
+
+    async def get_device(self, device_serial: str) -> Device:
+        """Fetch a device by serial number."""
+
+        try:
+            response = await self._auth.request("get", f"devices/{device_serial}")
+            if response.ok:
+                device_document = await response.json()
+                return document_to_device(device_document)
+            
+            try:
+                error_response = await format_client_response(response)
+            except:
+                error_response = "Could not read response body."
+            _LOGGER.error("Received error response while getting device: %s", error_response)
+
+            response.raise_for_status()
+
+        except Exception as e:
+            raise RuntimeError("Failed to get device") from e
+            
+
+    async def get_device_channel(
+        self, device_serial: str, channel: str
+    ) -> DeviceChannel:
+        """Fetch channel information for a device."""
+
+        try:
+            response = await self._auth.request(
+                "get", f"devices/{device_serial}/channels/{channel}"
+            )
+            if response.ok:
+                device_channel_document = await response.json()
+                return document_to_device_channel(device_channel_document)
+            
+            try:
+                error_response = await format_client_response(response)
+            except:
+                error_response = "Could not read response body."
+            _LOGGER.error("Received error response while getting device channel: %s", error_response)
+
+            response.raise_for_status()
+
+        except Exception as e:
+            raise RuntimeError("Failed to get device channel") from e

thermoworks_cloud/models/device.py

@@ -0,0 +1,101 @@
+from dataclasses import dataclass
+from datetime import datetime
+
+from thermoworks_cloud.utils import parse_datetime
+
+
+@dataclass
+class BigQueryInfo:
+    table_id: str
+    dataset_id: str
+
+
+@dataclass
+class Device:
+    device_id: str
+    serial: str
+    label: str
+    type: str
+    firmware: str
+    color: str
+    thumbnail: str
+    device_display_units: str
+    iot_device_id: str
+    device_name: str
+    account_id: str
+    status: str
+    battery_state: str
+    big_query_info: BigQueryInfo
+    battery: int
+    wifi_strength: int
+    recording_interval_in_seconds: int
+    transmit_interval_in_seconds: int
+    pending_load: bool
+    battery_alert_sent: bool
+    export_version: float
+    last_seen: datetime
+    last_purged: datetime
+    last_archive: datetime
+    last_telemetry_saved: datetime
+    last_wifi_connection: datetime
+    last_bluetooth_connection: datetime
+    session_start: datetime
+    create_time: datetime
+    update_time: datetime
+
+
+def parse_big_query_info(data: dict) -> BigQueryInfo:
+    """Parse bigQuery into a BigQueryInfo dataclass."""
+    fields = data["fields"]
+    return BigQueryInfo(
+        table_id=fields["tableId"]["stringValue"],
+        dataset_id=fields["datasetId"]["stringValue"],
+    )
+
+
+def document_to_device(document: dict) -> Device:
+    """Convert a Firestore Document object into a Device object."""
+    fields = document["fields"]
+
+    return Device(
+        device_id=fields["deviceId"]["stringValue"],
+        serial=fields["serial"]["stringValue"],
+        label=fields["label"]["stringValue"],
+        type=fields["type"]["stringValue"],
+        firmware=fields["firmware"]["stringValue"],
+        color=fields["color"]["stringValue"],
+        thumbnail=fields["thumbnail"]["stringValue"],
+        device_display_units=fields["deviceDisplayUnits"]["stringValue"],
+        iot_device_id=fields["iotDeviceId"]["stringValue"],
+        device_name=fields["device"]["stringValue"],
+        account_id=fields["accountId"]["stringValue"],
+        status=fields["status"]["stringValue"],
+        battery_state=fields["batteryState"]["stringValue"],
+        big_query_info=parse_big_query_info(fields["bigQuery"]["mapValue"]),
+        battery=int(fields["battery"]["integerValue"]),
+        wifi_strength=int(fields["wifi_stength"]["integerValue"]),
+        recording_interval_in_seconds=int(
+            fields["recordingIntervalInSeconds"]["integerValue"]
+        ),
+        transmit_interval_in_seconds=int(
+            fields["transmitIntervalInSeconds"]["integerValue"]
+        ),
+        pending_load=fields["pendingLoad"]["booleanValue"],
+        battery_alert_sent=fields["batteryAlertSent"]["booleanValue"],
+        export_version=fields["exportVersion"]["doubleValue"],
+        last_seen=parse_datetime(fields["lastSeen"]["timestampValue"]),
+        last_purged=parse_datetime(fields["lastPurged"]["timestampValue"]),
+        last_archive=parse_datetime(fields["lastArchive"]["timestampValue"]),
+        last_telemetry_saved=parse_datetime(
+            fields["lastTelemetrySaved"]["timestampValue"]
+        ),
+        last_wifi_connection=parse_datetime(
+            fields["lastWifiConnection"]["timestampValue"]
+        ),
+        last_bluetooth_connection=parse_datetime(
+            fields["lastBluetoothConnection"]["timestampValue"]
+        ),
+        session_start=parse_datetime(fields["sessionStart"]["timestampValue"]),
+        create_time=parse_datetime(document["createTime"]),
+        update_time=parse_datetime(document["updateTime"]),
+    )

thermoworks_cloud/models/device_channel.py

@@ -0,0 +1,107 @@
+from dataclasses import dataclass
+from datetime import datetime
+
+from thermoworks_cloud.utils import parse_datetime
+
+
+@dataclass
+class Reading:
+    """A temperature reading from a device channel."""
+
+    value: float
+    """"The temperature units as a string like "F" """
+    units: str
+
+
+@dataclass
+class Alarm:
+    """An alarm on a device channel."""
+
+    enabled: bool
+    alarming: bool
+    value: int
+    """"The temperature units as a string like "F" """
+    units: str
+
+
+@dataclass
+class MinMaxReading:
+    reading: Reading
+    date_reading: datetime
+
+
+@dataclass
+class DeviceChannel:
+    last_telemetry_saved: datetime
+    value: float
+    """"The temperature units as a string like "F" """
+    units: str
+    """"The only observed value for this field is "NORMAL"."""
+    status: str
+    type: str
+    """Customer provided 'name' for this device channel."""
+    label: str
+    last_seen: datetime
+    alarm_high: Alarm | None
+    alarm_low: Alarm | None
+    """The device channel number"""
+    number: str
+    minimum: MinMaxReading | None
+    maximum: MinMaxReading | None
+    show_avg_temp: bool
+
+
+def parse_alarm(alarm_data: dict) -> Alarm:
+    """Parse alarm data into an Alarm object."""
+    return Alarm(
+        enabled=alarm_data["fields"]["enabled"]["booleanValue"],
+        alarming=alarm_data["fields"]["alarming"]["booleanValue"],
+        value=int(alarm_data["fields"]["value"]["integerValue"]),
+        units=alarm_data["fields"]["units"]["stringValue"],
+    )
+
+
+def parse_min_max_reading(data: dict) -> MinMaxReading:
+    """Parse minimum or maximum reading data."""
+    return MinMaxReading(
+        reading=Reading(
+            value=data["fields"]["reading"]["mapValue"]["fields"]["value"][
+                "doubleValue"
+            ],
+            units=data["fields"]["reading"]["mapValue"]["fields"]["units"][
+                "stringValue"
+            ],
+        ),
+        date_reading=parse_datetime(data["fields"]["dateReading"]["timestampValue"]),
+    )
+
+
+def document_to_device_channel(document: dict) -> DeviceChannel:
+    """Convert a Firestore Document object into a Device object."""
+    fields = document["fields"]
+
+    return DeviceChannel(
+        last_telemetry_saved=parse_datetime(
+            fields["lastTelemetrySaved"]["timestampValue"]
+        ),
+        value=fields["value"]["doubleValue"],
+        units=fields["units"]["stringValue"],
+        status=fields["status"]["stringValue"],
+        type=fields["type"]["stringValue"],
+        label=fields["label"]["stringValue"],
+        last_seen=parse_datetime(fields["lastSeen"]["timestampValue"]),
+        alarm_high=parse_alarm(fields["alarmHigh"]["mapValue"])
+        if "alarmHigh" in fields
+        else None,
+        alarm_low=parse_alarm(fields["alarmLow"]["mapValue"])
+        if "alarmLow" in fields
+        else None,
+        number=fields["number"]["stringValue"],
+        minimum=parse_min_max_reading(fields["minimum"]["mapValue"])
+        if "minimum" in fields
+        else None,
+        maximum=parse_min_max_reading(fields["maximum"]["mapValue"])
+        if "maximum" in fields
+        else None,
+        show_avg_temp=fields["showAvgTemp"]["booleanValue"],
+    )