cremalink 0.1.0b5__py3-none-any.whl

cremalink/resources/api_config.py

@@ -0,0 +1,30 @@
+"""
+This module provides a function to load the API configuration from the
+embedded `api_config.json` resource file.
+"""
+from __future__ import annotations
+
+import json
+from functools import lru_cache
+from importlib import resources
+from typing import Any
+
+
+@lru_cache
+def load_api_config() -> dict[str, Any]:
+    """
+    Loads the API configuration from the `api_config.json` resource file.
+
+    This function uses `importlib.resources` to access the JSON file.
+
+    The `@lru_cache` decorator memoizes the result, so the file is only read
+    and parsed once, improving performance on subsequent calls.
+
+    Returns:
+        A dictionary containing the API configuration data.
+    """
+    # Locate the 'api_config.json' file within the 'cremalink.resources' package.
+    resource = resources.files("cremalink.resources").joinpath("api_config.json")
+    # Open the resource file and load its JSON content.
+    with resource.open("r", encoding="utf-8") as f:
+        return json.load(f)

cremalink/resources/lang.json

@@ -0,0 +1,223 @@
+{
+  "language_comms_keys": {
+    "AE": "profiledCommunicationAE",
+    "AR": "profiledCommunicationCL",
+    "AT": "profiledCommunicationAT",
+    "AU": "profiledCommunicationAU",
+    "BD": "profiledCommunicationHKBDKHTH",
+    "BE": "profiledCommunicationBE",
+    "BG": "profiledCommunicationHRRSSIBG",
+    "BH": "profiledCommunicationAE",
+    "BR": "profiledCommunicationBR",
+    "CA": "profiledCommunicationCA",
+    "CH": "profiledCommunicationCH",
+    "CL": "profiledCommunicationCL",
+    "CO": "profiledCommunicationMXCO",
+    "CZ": "profiledCommunicationCZSKHU",
+    "DE": "profiledCommunicationDE",
+    "DK": "profiledCommunicationSEFINODK",
+    "EE": "profiledCommunicationPLEELTLV",
+    "EG": "profiledCommunicationAE",
+    "ES": "profiledCommunicationES",
+    "FI": "profiledCommunicationSEFINODK",
+    "FR": "profiledCommunicationFR",
+    "GB": "profiledCommunicationGB",
+    "GR": "profiledCommunicationGR",
+    "HK": "profiledCommunicationHKBDKHTH",
+    "HR": "profiledCommunicationHRRSSIBG",
+    "HU": "profiledCommunicationCZSKHU",
+    "ID": "profiledCommunicationHKBDKHTH",
+    "IE": "profiledCommunicationGB",
+    "IL": "profiledCommunicationAE",
+    "IN": "profiledCommunicationAE",
+    "IR": "profiledCommunicationAE",
+    "IT": "profiledCommunicationIT",
+    "JP": "profiledCommunicationJP",
+    "KH": "profiledCommunicationHKBDKHTH",
+    "KR": "profiledCommunicationKR",
+    "KW": "profiledCommunicationAE",
+    "LT": "profiledCommunicationPLEELTLV",
+    "LU": "profiledCommunicationBE",
+    "LV": "profiledCommunicationPLEELTLV",
+    "MT": "profiledCommunicationHRRSSIBG",
+    "MX": "profiledCommunicationMXCO",
+    "MY": "profiledCommunicationMY",
+    "NL": "profiledCommunicationNL",
+    "NO": "profiledCommunicationSEFINODK",
+    "NZ": "profiledCommunicationNZ",
+    "OM": "profiledCommunicationAE",
+    "PE": "profiledCommunicationCL",
+    "PH": "profiledCommunicationHKBDKHTH",
+    "PL": "profiledCommunicationPLEELTLV",
+    "PT": "profiledCommunicationPT",
+    "QA": "profiledCommunicationAE",
+    "RO": "profiledCommunicationRO",
+    "RS": "profiledCommunicationHRRSSIBG",
+    "SA": "profiledCommunicationAE",
+    "SE": "profiledCommunicationSEFINODK",
+    "SG": "profiledCommunicationSG",
+    "SI": "profiledCommunicationHRRSSIBG",
+    "SK": "profiledCommunicationCZSKHU",
+    "TH": "profiledCommunicationHKBDKHTH",
+    "TR": "profiledCommunicationTR",
+    "TW": "profiledCommunicationHKBDKHTH",
+    "UA": "profiledCommunicationUA",
+    "US": "profiledCommunicationUS",
+    "VN": "profiledCommunicationHKBDKHTH",
+    "ZA": "profiledCommunicationZA"
+  },
+  "language_countries": {
+    "ar-ae": "United Arab Emirates",
+    "ar-eg": "Egypt",
+    "ar-sa": "Saudi Arabia",
+    "br": "Bulgaria",
+    "cs": "Czechia",
+    "da": "Denmark",
+    "de": "Germany",
+    "de-at": "Austria",
+    "de-inf": "Switzerland",
+    "el": "Greece",
+    "en": "United Kingdom",
+    "en-ae": "United Arab Emirates",
+    "en-au": "Australia",
+    "en-bd": "Bangladesh",
+    "en-bh": "Bahrain",
+    "en-ca": "Canada",
+    "en-eg": "Egypt",
+    "en-hk": "Hong Kong",
+    "en-id": "Indonesia",
+    "en-ie": "Ireland",
+    "en-il": "Israel",
+    "en-in": "India",
+    "en-ir": "Iran",
+    "en-kh": "Cambodia",
+    "en-kw": "Kuwait",
+    "en-mt": "Malta",
+    "en-my": "Malaysia",
+    "en-nz": "New Zealand",
+    "en-om": "Oman",
+    "en-ph": "Philippines",
+    "en-qa": "Qatar",
+    "en-sa": "Saudi Arabia",
+    "en-sg": "Singapore",
+    "en-th": "Thailand",
+    "en-us": "United States",
+    "en-za": "South Africa",
+    "es": "Spain",
+    "es-ar": "Argentina",
+    "es-cl": "Chile",
+    "es-co": "Colombia",
+    "es-mx": "Mexico",
+    "es-pe": "Peru",
+    "et-ee": "Estonia",
+    "fa": "Iran",
+    "fi": "Finland",
+    "fr": "France",
+    "fr-be": "Belgium",
+    "fr-ca": "Canada",
+    "fr-ch": "Switzerland",
+    "hr": "Croatia",
+    "hu": "Hungary",
+    "it": "Italy",
+    "ja": "Japan",
+    "ko": "South Korea",
+    "lt-lt": "Lithuania",
+    "lu": "Luxembourg",
+    "lv-lv": "Latvia",
+    "mt-mt": "Malta",
+    "my": "Malaysia",
+    "nl": "Netherlands",
+    "nl-inf": "Belgium",
+    "no": "Norway",
+    "pl": "Poland",
+    "pt": "Portugal",
+    "pt-br": "Brazil",
+    "ro": "Romania",
+    "sk": "Slovakia",
+    "sl": "Slovenia",
+    "sr": "Serbia",
+    "sv": "Sweden",
+    "th": "Thailand",
+    "tr": "Turkey",
+    "uk": "Ukraine",
+    "vi": "Vietnam",
+    "zh-tw": "Taiwan"
+  },
+  "languages": {
+    "ar-ae": "AE",
+    "ar-eg": "EG",
+    "ar-sa": "SA",
+    "br": "BG",
+    "cs": "CZ",
+    "da": "DK",
+    "de": "DE",
+    "de-at": "AT",
+    "de-inf": "CH",
+    "el": "GR",
+    "en": "GB",
+    "en-ae": "AE",
+    "en-au": "AU",
+    "en-bd": "BD",
+    "en-bh": "BH",
+    "en-ca": "CA",
+    "en-eg": "EG",
+    "en-hk": "HK",
+    "en-id": "ID",
+    "en-ie": "IE",
+    "en-il": "IL",
+    "en-in": "IN",
+    "en-ir": "IR",
+    "en-kh": "KH",
+    "en-kw": "KW",
+    "en-mt": "MT",
+    "en-my": "MY",
+    "en-nz": "NZ",
+    "en-om": "OM",
+    "en-ph": "PH",
+    "en-qa": "QA",
+    "en-sa": "SA",
+    "en-sg": "SG",
+    "en-th": "TH",
+    "en-us": "US",
+    "en-za": "ZA",
+    "es": "ES",
+    "es-ar": "AR",
+    "es-cl": "CL",
+    "es-co": "CO",
+    "es-mx": "MX",
+    "es-pe": "PE",
+    "et-ee": "EE",
+    "fa": "IR",
+    "fi": "FI",
+    "fr": "FR",
+    "fr-be": "BE",
+    "fr-ca": "CA",
+    "fr-ch": "CH",
+    "hr": "HR",
+    "hu": "HU",
+    "it": "IT",
+    "ja": "JP",
+    "ko": "KR",
+    "lt-lt": "LT",
+    "lu": "LU",
+    "lv-lv": "LV",
+    "mt-mt": "MT",
+    "my": "MY",
+    "nl": "NL",
+    "nl-inf": "BE",
+    "no": "NO",
+    "pl": "PL",
+    "pt": "PT",
+    "pt-br": "BR",
+    "ro": "RO",
+    "sk": "SK",
+    "sl": "SI",
+    "sr": "RS",
+    "sv": "SE",
+    "th": "TH",
+    "tr": "TR",
+    "uk": "UA",
+    "vi": "VN",
+    "zh-tw": "TW"
+  }
+}

cremalink/transports/__init__.py

@@ -0,0 +1,7 @@
+"""
+This package contains the different transport implementations for communicating
+with coffee machines, such as via the local network or the cloud.
+
+Each sub-package (e.g., `local`, `cloud`) provides a concrete implementation
+of the `DeviceTransport` protocol.
+"""

cremalink/transports/base.py

@@ -0,0 +1,94 @@
+"""
+This module defines the abstract base protocol for device communication transports.
+"""
+from __future__ import annotations
+
+from typing import Any, Protocol
+
+
+class DeviceTransport(Protocol):
+    """
+    A protocol defining the standard interface for all device transports.
+
+    A transport is responsible for the low-level details of communicating with a
+    coffee machine, whether it's over a local network (HTTP) or via the cloud.
+    This class uses `typing.Protocol` to allow for structural subtyping, meaning
+    any class that implements these methods will be considered a valid transport.
+    """
+
+    def configure(self) -> None:
+        """
+        Performs any necessary setup or configuration for the transport.
+        This could include authentication, connection setup, etc.
+        """
+        ...
+
+    def send_command(self, command: str) -> Any:
+        """
+        Sends a command to the device.
+
+        Args:
+            command: The command payload to be sent.
+
+        Returns:
+            The response from the device, with the format depending on the
+            transport implementation.
+        """
+        ...
+
+    def set_mappings(self, command_map: dict[str, Any], property_map: dict[str, Any]) -> None:
+        """
+        (Optional) Provides the transport with device-specific command and property maps.
+
+        This can be used by transports that need to perform lookups or translations.
+
+        Args:
+            command_map: A dictionary mapping command aliases to their details.
+            property_map: A dictionary mapping property aliases to their details.
+        """
+        ...
+
+    def get_monitor(self) -> Any:
+        """
+        Retrieves the current monitoring status data from the device.
+
+        Returns:
+            The raw monitoring data.
+        """
+        ...
+
+    def refresh_monitor(self) -> Any:
+        """
+        Requests the device to send an updated monitoring status.
+        """
+        ...
+
+    def get_properties(self) -> Any:
+        """
+        Fetches a set of properties from the device.
+
+        Returns:
+            A collection of device properties.
+        """
+        ...
+
+    def get_property(self, name: str) -> Any:
+        """
+        Fetches a single, specific property from the device.
+
+        Args:
+            name: The name of the property to retrieve.
+
+        Returns:
+            The value of the requested property.
+        """
+        ...
+
+    def health(self) -> Any:
+        """
+        Performs a health check to verify connectivity with the device.
+
+        Returns:
+            A status indicating the health of the connection.
+        """
+        ...

cremalink/transports/cloud/__init__.py

@@ -0,0 +1,9 @@
+"""
+This package contains the transport implementation for communicating with
+devices via the cloud.
+
+It exposes the `CloudTransport` class as the main entry point.
+"""
+from cremalink.transports.cloud.transport import CloudTransport
+
+__all__ = ["CloudTransport"]

cremalink/transports/cloud/transport.py

@@ -0,0 +1,166 @@
+"""
+This module provides the `CloudTransport` class, which handles communication
+with a coffee machine via the manufacturer's cloud API (Ayla Networks).
+"""
+from __future__ import annotations
+
+import time
+from typing import Any, Optional
+
+import requests
+
+from cremalink.parsing.monitor.decode import build_monitor_snapshot
+from cremalink.transports.base import DeviceTransport
+from cremalink.resources import load_api_config
+
+API_USER_AGENT = "datatransport/3.1.2 android/"
+TOKEN_USER_AGENT = "DeLonghiComfort/3 CFNetwork/1568.300.101 Darwin/24.2.0"
+
+
+class CloudTransport(DeviceTransport):
+    """
+    A transport for communicating with a device via the cloud API.
+
+    This transport interacts directly with the Ayla cloud service endpoints,
+    using a short-lived access token for authentication. Upon initialization,
+    it fetches key device metadata from the cloud and stores it.
+    """
+
+    def __init__(self, dsn: str, access_token: str, device_map_path: Optional[str] = None) -> None:
+        """
+        Initializes the CloudTransport.
+
+        Args:
+            dsn: The Device Serial Number.
+            access_token: A valid OAuth access token for the cloud API.
+            device_map_path: Optional path to a device-specific command map file.
+        """
+        self.api_conf = load_api_config()
+        self.gigya_api = self.api_conf.get("GIGYA")
+        self.ayla_api = self.api_conf.get("AYLA")
+
+        self.dsn = dsn
+        self.access_token = access_token
+        self.device_map_path = device_map_path
+        self.command_map: dict[str, Any] = {}
+        self.property_map: dict[str, Any] = {}
+
+        # Fetch device metadata from the cloud immediately upon initialization.
+        device = self._get(".json").get("device", {})
+        self.id = device.get("key")  # The Ayla internal device ID
+        self.model = device.get("model")
+        self.is_lan_enabled = device.get("lan_enabled", False)
+        self.type = device.get("type")
+        self.is_online = device.get("connection_status", False) == "Online"
+        self.ip = device.get("lan_ip")
+
+        # Fetch LAN key, which might be needed for other operations.
+        lan = self._get("/lan.json") or {}
+        self.lan_key = lan.get("lanip", {}).get("lanip_key")
+
+    def configure(self) -> None:
+        """Configuration is handled during __init__, so this is a no-op."""
+        return None
+
+    # ---- helpers ----
+    def _get(self, path: str) -> dict:
+        """Helper for making authenticated GET requests using the device DSN."""
+        response = requests.get(
+            url=f"{self.ayla_api.get('API_URL')}/dsns/{self.dsn}{path}",
+            headers={
+                "User-Agent": API_USER_AGENT,
+                "Authorization": f"auth_token {self.access_token}",
+                "Accept": "application/json",
+            },
+        )
+        response.raise_for_status()
+        return response.json()
+
+    def _get_by_id(self, path: str) -> dict:
+        """Helper for making authenticated GET requests using the internal device ID."""
+        response = requests.get(
+            url=f"{self.ayla_api.get('API_URL')}/devices/{self.id}{path}",
+            headers={
+                "User-Agent": API_USER_AGENT,
+                "Authorization": f"auth_token {self.access_token}",
+                "Accept": "application/json",
+            },
+        )
+        response.raise_for_status()
+        return response.json()
+
+    def _post(self, path: str, data: dict) -> dict:
+        """Helper for making authenticated POST requests."""
+        response = requests.post(
+            url=f"{self.ayla_api.get('API_URL')}/dsns/{self.dsn}{path}",
+            headers={
+                "User-Agent": API_USER_AGENT,
+                "Authorization": f"auth_token {self.access_token}",
+                "Accept": "application/json",
+                "Content-Type": "application/json",
+            },
+            json=data,
+        )
+        response.raise_for_status()
+        return response.json()
+
+    # ---- DeviceTransport Implementation ----
+    def send_command(self, command: str) -> Any:
+        """Sends a command to the device by creating a new 'datapoint' via the cloud API."""
+        payload = {"datapoint": {"value": command}}
+        return self._post(path="/properties/data_request/datapoints.json", data=payload)
+
+    def set_mappings(self, command_map: dict[str, Any], property_map: dict[str, Any]) -> None:
+        """Stores the provided command and property maps on the instance."""
+        self.command_map = command_map
+        self.property_map = property_map
+
+    def get_properties(self) -> Any:
+        """Fetches all properties for the device from the cloud API."""
+        return self._get("/properties.json")
+
+    def get_property(self, name: str) -> Any:
+        """Fetches a single, specific property by name."""
+        props = self._get(f"/properties.json?names[]={name}")
+        # The API returns a list, even for a single property.
+        if props and isinstance(props, list):
+            return props[0].get("property")
+        return None
+
+    def get_monitor(self) -> Any:
+        """
+        Fetches, parses, and returns the device's monitoring status.
+
+        This works by fetching the specific 'monitor' property, extracting its
+        base64 value, and then decoding it into a structured snapshot.
+        """
+        property_name = self.property_map.get("monitor", "d302_monitor")
+        prop = self.get_property(property_name) or {}
+        raw_b64 = prop.get("value")
+        received_at = prop.get("updated_at")
+
+        try:
+            # Convert timestamp string to float if possible, otherwise use current time.
+            received_ts = float(received_at) if received_at is not None else time.time()
+        except (TypeError, ValueError):
+            received_ts = time.time()
+        payload = {
+            "monitor": {"data": {"value": raw_b64}},
+            "monitor_b64": raw_b64,
+            "received_at": received_ts,
+        }
+        return build_monitor_snapshot(payload, source="cloud", device_id=self.dsn or self.id)
+
+    def refresh_monitor(self) -> Any:
+        """
+        The cloud API does not provide a direct way to force a monitor refresh.
+        This method is a no-op.
+        """
+        return None
+
+    def health(self) -> Any:
+        """
+        Returns the device's online status as determined during initialization.
+        This does not perform a live health check.
+        """
+        return {"online": self.is_online}

cremalink/transports/local/__init__.py

@@ -0,0 +1,9 @@
+"""
+This package contains the transport implementation for communicating with
+devices over the local network (LAN).
+
+It exposes the `LocalTransport` class as the main entry point.
+"""
+from cremalink.transports.local.transport import LocalTransport
+
+__all__ = ["LocalTransport"]