place-integration-api 0.2.5__tar.gz → 0.2.7__tar.gz

{place_integration_api-0.2.5/src/place_integration_api.egg-info → place_integration_api-0.2.7}/PKG-INFO

@@ -1,6 +1,6 @@
 Metadata-Version: 2.4
 Name: place-integration-api
-Version: 0.2.5
+Version: 0.2.7
 Summary: Python APIs for Cognito-authenticated MQTT flows and Home Assistant discovery for Gentex Place.
 Author-email: Nicholas Aelick <niaexa@syntronic.com>, Andrew Tran <andrew.tran@gentex.com>
 Project-URL: Homepage, https://placehomesolutions.com
@@ -27,3 +27,15 @@ Dynamic: license-file
 # Place integration API
 
 This project contains a python API to connect MQTT data from Place devices to Place's Home Assistant integration
+
+## Setup
+
+This repo utilizes VS Code [Dev Containers](https://marketplace.visualstudio.com/items?itemName=ms-vscode-remote.remote-containers) so you don't need to alter your global python environment.
+
+## Installing dependencies
+
+Use `pip` to install required dependencies by running `pip install -r requirements.txt` from the project root.
+
+## Updating dependencies
+
+During the course of development, if new packages are added, it's recommended to update [`requirements.txt`](./requirements.txt) by running `pip freeze > requirements.txt`.

place_integration_api-0.2.7/README.md

@@ -0,0 +1,15 @@
+# Place integration API
+
+This project contains a python API to connect MQTT data from Place devices to Place's Home Assistant integration
+
+## Setup
+
+This repo utilizes VS Code [Dev Containers](https://marketplace.visualstudio.com/items?itemName=ms-vscode-remote.remote-containers) so you don't need to alter your global python environment.
+
+## Installing dependencies
+
+Use `pip` to install required dependencies by running `pip install -r requirements.txt` from the project root.
+
+## Updating dependencies
+
+During the course of development, if new packages are added, it's recommended to update [`requirements.txt`](./requirements.txt) by running `pip freeze > requirements.txt`.

{place_integration_api-0.2.5 → place_integration_api-0.2.7}/pyproject.toml

@@ -4,7 +4,7 @@ build-backend = "setuptools.build_meta"
 
 [project]
 name = "place-integration-api"
-version = "0.2.5"
+version = "0.2.7"
 description = "Python APIs for Cognito-authenticated MQTT flows and Home Assistant discovery for Gentex Place."
 readme = "README.md"
 requires-python = ">=3.11"

{place_integration_api-0.2.5 → place_integration_api-0.2.7}/src/place/auth/abstract_auth.py

@@ -25,9 +25,11 @@ class AbstractAuth(ABC):
         access_token = await self.async_get_access_token()
         headers["authorization"] = f"Bearer {access_token}"
 
-        return await self.websession.request(
+        resp = await self.websession.request(
             method,
             url,
             **kwargs,
             headers=headers,
         )
+        resp.raise_for_status()
+        return resp

place_integration_api-0.2.7/src/place/errors.py

@@ -0,0 +1,13 @@
+"""Errors for the Place API."""
+
+
+class PlaceApiError(Exception):
+    """Base error for Place API failures."""
+
+
+class PlaceFulfillmentError(PlaceApiError):
+    """Raised when the fulfillment API reports a business-logic failure."""
+
+
+class PlaceMqttConnectionError(PlaceApiError):
+    """Raised when the MQTT broker rejects or fails to establish a connection."""

{place_integration_api-0.2.5 → place_integration_api-0.2.7}/src/place/mqtt_client.py

@@ -2,14 +2,17 @@ from __future__ import annotations
 
 import hashlib
 import hmac
+import threading
 import uuid
 from datetime import datetime, timezone
 from typing import Callable
 from urllib.parse import quote
 
 import paho.mqtt.client as mqtt
+from paho.mqtt.reasoncodes import ReasonCode
 
 from .config import ALGORITHM, EXPIRE_SEC, KEEP_ALIVE_SEC, PATH, REGION, SCHEME, SERVICE
+from .errors import PlaceMqttConnectionError
 from .models import Credentials
 
 
@@ -92,12 +95,17 @@ class MqttClient:
         self.endpoint = endpoint
         self.credentials = credentials
         self._client: mqtt.Client | None = None
+        self._connected_event = threading.Event()
+        self._connect_error: ReasonCode | None = None
 
     def connect(
         self,
         on_message: Callable[[str, bytes], None] | None = None,
         on_connect: Callable[[], None] | None = None,
     ) -> None:
+        self._connected_event.clear()
+        self._connect_error = None
+
         signed_uri = get_signed_uri(
             access_key_id=self.credentials.access_key_id,
             secret_access_key=self.credentials.secret_access_key,
@@ -119,8 +127,12 @@ class MqttClient:
         def _on_connect(_client, _userdata, _flags, reason_code, _properties):
             if reason_code.is_failure:
                 print(f"Connect failed: {reason_code}")
+                self._connect_error = reason_code
+                self._connected_event.set()
                 return
             print("Connected")
+            self._connect_error = None
+            self._connected_event.set()
             if on_connect:
                 try:
                     on_connect()
@@ -149,6 +161,23 @@ class MqttClient:
         if self._client:
             self._client.loop_stop()
 
+    def wait_for_connection(self, timeout: float = 10.0) -> None:
+        """Block until the initial CONNACK is received.
+
+        Raises PlaceMqttConnectionError if the broker rejects the connection
+        or none arrives within timeout, tearing down the client in that case.
+        """
+        if not self._connected_event.wait(timeout):
+            self.disconnect()
+            self.loop_stop()
+            raise PlaceMqttConnectionError("Timed out waiting for MQTT CONNACK")
+        if self._connect_error is not None:
+            self.disconnect()
+            self.loop_stop()
+            raise PlaceMqttConnectionError(
+                f"MQTT connection rejected: {self._connect_error}"
+            )
+
     def subscribe(self, topic: str, qos: int = 1) -> None:
         assert self._client is not None
         self._client.subscribe(topic, qos=qos)

place_integration_api-0.2.7/src/place/provider.py

@@ -0,0 +1,43 @@
+from __future__ import annotations
+
+from typing import Any
+
+from aiohttp import ContentTypeError
+
+from .auth.abstract_auth import AbstractAuth
+from .errors import PlaceFulfillmentError
+from .models.discover_device import DiscoverDevice
+from .config import FULFILLMENT_URL
+
+
+async def _send_command(authorized_session: AbstractAuth, command: str) -> dict[str, Any]:
+    """Send a fulfillment command and return the parsed response body."""
+    body = {"command": command, "data": {}}
+    resp = await authorized_session.request("POST", FULFILLMENT_URL, json=body)
+    try:
+        data = await resp.json()
+    except (ContentTypeError, ValueError) as err:
+        raise PlaceFulfillmentError(
+            f"Invalid response from fulfillment API: {err}"
+        ) from err
+    if not isinstance(data, dict):
+        raise PlaceFulfillmentError(f"Invalid response from fulfillment API: {data!r}")
+    if not data.get("success", True):
+        raise PlaceFulfillmentError(f"Home Assistant error: {data.get('message', data)}")
+    return data
+
+
+class Provider:
+    def __init__(self, authorized_session: AbstractAuth) -> None:
+        self.authorized_session = authorized_session
+
+    async def discover(self) -> list[DiscoverDevice]:
+        data = await _send_command(self.authorized_session, "DISCOVER")
+        devices_raw = (data.get("data") or {}).get("devices") or []
+        return [DiscoverDevice.from_dict(raw) for raw in devices_raw]
+
+    async def enable(self):
+        return await _send_command(self.authorized_session, "ENABLE")
+
+    async def disable(self):
+        return await _send_command(self.authorized_session, "DISABLE")

{place_integration_api-0.2.5 → place_integration_api-0.2.7/src/place_integration_api.egg-info}/PKG-INFO

@@ -1,6 +1,6 @@
 Metadata-Version: 2.4
 Name: place-integration-api
-Version: 0.2.5
+Version: 0.2.7
 Summary: Python APIs for Cognito-authenticated MQTT flows and Home Assistant discovery for Gentex Place.
 Author-email: Nicholas Aelick <niaexa@syntronic.com>, Andrew Tran <andrew.tran@gentex.com>
 Project-URL: Homepage, https://placehomesolutions.com
@@ -27,3 +27,15 @@ Dynamic: license-file
 # Place integration API
 
 This project contains a python API to connect MQTT data from Place devices to Place's Home Assistant integration
+
+## Setup
+
+This repo utilizes VS Code [Dev Containers](https://marketplace.visualstudio.com/items?itemName=ms-vscode-remote.remote-containers) so you don't need to alter your global python environment.
+
+## Installing dependencies
+
+Use `pip` to install required dependencies by running `pip install -r requirements.txt` from the project root.
+
+## Updating dependencies
+
+During the course of development, if new packages are added, it's recommended to update [`requirements.txt`](./requirements.txt) by running `pip freeze > requirements.txt`.

{place_integration_api-0.2.5 → place_integration_api-0.2.7}/src/place_integration_api.egg-info/SOURCES.txt

@@ -2,6 +2,7 @@ LICENSE
 README.md
 pyproject.toml
 src/place/config.py
+src/place/errors.py
 src/place/messages.py
 src/place/mqtt_client.py
 src/place/provider.py

place_integration_api-0.2.7/tests/test_auth.py

@@ -0,0 +1,70 @@
+from __future__ import annotations
+
+import asyncio
+from unittest.mock import AsyncMock, MagicMock, patch
+
+import pytest
+from aiohttp import ClientResponseError
+
+from place.auth import get_iot_credentials
+from place.auth.abstract_auth import AbstractAuth
+
+
+class _FakeAuth(AbstractAuth):
+    async def async_get_access_token(self) -> str:
+        return "token"
+
+
+@patch("place.auth.srp_auth.boto3")
+def test_get_iot_credentials_success(mock_boto3: MagicMock) -> None:
+    identity_client = MagicMock()
+    mock_boto3.client.return_value = identity_client
+
+    identity_client.get_id.return_value = {"IdentityId": "identity-123"}
+    identity_client.get_credentials_for_identity.return_value = {
+        "Credentials": {
+            "AccessKeyId": "AKIA...",
+            "SecretKey": "secret",
+            "SessionToken": "session",
+        }
+    }
+
+
+    creds = get_iot_credentials(
+        id_token="id-token",
+        access_token="access-token",
+    )
+
+    assert creds.access_key_id == "AKIA..."
+    assert creds.secret_access_key == "secret"
+    assert creds.session_token == "session"
+    assert creds.identity_id == "identity-123"
+    assert creds.access_token == "access-token"
+
+
+def test_request_raises_for_non_2xx_status() -> None:
+    response = MagicMock()
+    response.raise_for_status.side_effect = ClientResponseError(
+        request_info=MagicMock(), history=(), status=401
+    )
+    websession = MagicMock()
+    websession.request = AsyncMock(return_value=response)
+
+    auth = _FakeAuth(websession)
+
+    with pytest.raises(ClientResponseError):
+        asyncio.run(auth.request("POST", "https://example.com"))
+
+
+def test_request_returns_response_for_2xx_status() -> None:
+    response = MagicMock()
+    response.raise_for_status.return_value = None
+    websession = MagicMock()
+    websession.request = AsyncMock(return_value=response)
+
+    auth = _FakeAuth(websession)
+
+    result = asyncio.run(auth.request("POST", "https://example.com"))
+
+    assert result is response
+    response.raise_for_status.assert_called_once()

place_integration_api-0.2.7/tests/test_mqtt_client.py

@@ -0,0 +1,138 @@
+from __future__ import annotations
+
+from unittest.mock import MagicMock, patch
+
+from paho.mqtt.packettypes import PacketTypes
+from paho.mqtt.reasoncodes import ReasonCode
+import pytest
+
+from place.errors import PlaceMqttConnectionError
+from place.models import Credentials
+from place.mqtt_client import get_signed_uri, MqttClient
+
+
+def test_get_signed_uri_includes_host_and_token() -> None:
+    uri = get_signed_uri(
+        access_key_id="AKIA...",
+        secret_access_key="secret",
+        session_token="token123",
+        host="example.iot.amazonaws.com",
+    )
+    assert uri.startswith("wss://example.iot.amazonaws.com/mqtt?")
+    assert "X-Amz-Algorithm=" in uri
+    assert "X-Amz-Signature=" in uri
+    assert "X-Amz-Security-Token=token123" in uri
+
+
+@patch("place.mqtt_client.mqtt.Client")
+@patch("place.mqtt_client.get_signed_uri")
+def test_mqtt_client_connect_sets_up_client(
+    mock_get_signed_uri: MagicMock,
+    mock_client_cls: MagicMock,
+) -> None:
+    mock_get_signed_uri.return_value = "wss://example.iot.amazonaws.com/mqtt?x=1"
+    client = MagicMock()
+    mock_client_cls.return_value = client
+
+    creds = Credentials(
+        access_key_id="AKIA...",
+        secret_access_key="secret",
+        session_token="token",
+        identity_id="identity-123",
+    )
+
+    mqtt_client = MqttClient(
+        endpoint="example.iot.amazonaws.com",
+        credentials=creds,
+    )
+    mqtt_client.connect()
+
+    mock_get_signed_uri.assert_called_once()
+    client.ws_set_options.assert_called()
+    client.tls_set.assert_called_once()
+    client.connect.assert_called_once()
+
+
+@patch("place.mqtt_client.mqtt.Client")
+@patch("place.mqtt_client.get_signed_uri")
+def test_wait_for_connection_succeeds_on_connack_success(
+    mock_get_signed_uri: MagicMock,
+    mock_client_cls: MagicMock,
+) -> None:
+    mock_get_signed_uri.return_value = "wss://example.iot.amazonaws.com/mqtt?x=1"
+    client = MagicMock()
+    mock_client_cls.return_value = client
+
+    creds = Credentials(
+        access_key_id="AKIA...",
+        secret_access_key="secret",
+        session_token="token",
+        identity_id="identity-123",
+    )
+    mqtt_client = MqttClient(endpoint="example.iot.amazonaws.com", credentials=creds)
+    mqtt_client.connect()
+
+    client.on_connect(
+        client, None, None, ReasonCode(PacketTypes.CONNACK, identifier=0), None
+    )
+
+    mqtt_client.wait_for_connection(timeout=1)
+
+    client.disconnect.assert_not_called()
+    client.loop_stop.assert_not_called()
+
+
+@patch("place.mqtt_client.mqtt.Client")
+@patch("place.mqtt_client.get_signed_uri")
+def test_wait_for_connection_raises_on_connack_rejection(
+    mock_get_signed_uri: MagicMock,
+    mock_client_cls: MagicMock,
+) -> None:
+    mock_get_signed_uri.return_value = "wss://example.iot.amazonaws.com/mqtt?x=1"
+    client = MagicMock()
+    mock_client_cls.return_value = client
+
+    creds = Credentials(
+        access_key_id="AKIA...",
+        secret_access_key="secret",
+        session_token="token",
+        identity_id="identity-123",
+    )
+    mqtt_client = MqttClient(endpoint="example.iot.amazonaws.com", credentials=creds)
+    mqtt_client.connect()
+
+    client.on_connect(
+        client, None, None, ReasonCode(PacketTypes.CONNACK, identifier=135), None
+    )
+
+    with pytest.raises(PlaceMqttConnectionError, match="rejected"):
+        mqtt_client.wait_for_connection(timeout=1)
+
+    client.disconnect.assert_called_once()
+    client.loop_stop.assert_called_once()
+
+
+@patch("place.mqtt_client.mqtt.Client")
+@patch("place.mqtt_client.get_signed_uri")
+def test_wait_for_connection_raises_on_timeout(
+    mock_get_signed_uri: MagicMock,
+    mock_client_cls: MagicMock,
+) -> None:
+    mock_get_signed_uri.return_value = "wss://example.iot.amazonaws.com/mqtt?x=1"
+    client = MagicMock()
+    mock_client_cls.return_value = client
+
+    creds = Credentials(
+        access_key_id="AKIA...",
+        secret_access_key="secret",
+        session_token="token",
+        identity_id="identity-123",
+    )
+    mqtt_client = MqttClient(endpoint="example.iot.amazonaws.com", credentials=creds)
+    mqtt_client.connect()
+
+    with pytest.raises(PlaceMqttConnectionError, match="Timed out"):
+        mqtt_client.wait_for_connection(timeout=0.05)
+
+    client.disconnect.assert_called_once()
+    client.loop_stop.assert_called_once()

{place_integration_api-0.2.5 → place_integration_api-0.2.7}/tests/test_provider.py

@@ -2,8 +2,11 @@ from __future__ import annotations
 
 import asyncio
 
+import pytest
+
 from place.auth.abstract_auth import AbstractAuth
 from place.config import FULFILLMENT_URL
+from place.errors import PlaceFulfillmentError
 from place.provider import Provider
 
 
@@ -101,3 +104,79 @@ def test_provider_disable_sends_disable_command() -> None:
 
     assert auth.calls == [("POST", FULFILLMENT_URL, {"json": {"command": "DISABLE", "data": {}}})]
     assert result == payload
+
+
+def test_provider_discover_raises_on_success_false() -> None:
+    payload = {"success": False, "message": "not authorized"}
+
+    class DummyAuth(AbstractAuth):
+        async def async_get_access_token(self) -> str:
+            return "token"
+
+        async def request(self, method, url, **kwargs):
+            class DummyResponse:
+                async def json(self_inner):
+                    return payload
+
+            return DummyResponse()
+
+    provider = Provider(DummyAuth(None))
+
+    with pytest.raises(PlaceFulfillmentError):
+        asyncio.run(provider.discover())
+
+
+def test_provider_enable_raises_on_success_false() -> None:
+    payload = {"success": False, "message": "not authorized"}
+
+    class DummyAuth(AbstractAuth):
+        async def async_get_access_token(self) -> str:
+            return "token"
+
+        async def request(self, method, url, **kwargs):
+            class DummyResponse:
+                async def json(self_inner):
+                    return payload
+
+            return DummyResponse()
+
+    provider = Provider(DummyAuth(None))
+
+    with pytest.raises(PlaceFulfillmentError):
+        asyncio.run(provider.enable())
+
+
+def test_provider_raises_on_non_dict_response() -> None:
+    class DummyAuth(AbstractAuth):
+        async def async_get_access_token(self) -> str:
+            return "token"
+
+        async def request(self, method, url, **kwargs):
+            class DummyResponse:
+                async def json(self_inner):
+                    return None
+
+            return DummyResponse()
+
+    provider = Provider(DummyAuth(None))
+
+    with pytest.raises(PlaceFulfillmentError):
+        asyncio.run(provider.discover())
+
+
+def test_provider_raises_on_invalid_json_body() -> None:
+    class DummyAuth(AbstractAuth):
+        async def async_get_access_token(self) -> str:
+            return "token"
+
+        async def request(self, method, url, **kwargs):
+            class DummyResponse:
+                async def json(self_inner):
+                    raise ValueError("Expecting value: line 1 column 1 (char 0)")
+
+            return DummyResponse()
+
+    provider = Provider(DummyAuth(None))
+
+    with pytest.raises(PlaceFulfillmentError):
+        asyncio.run(provider.discover())

place_integration_api-0.2.5/README.md

@@ -1,3 +0,0 @@
-# Place integration API
-
-This project contains a python API to connect MQTT data from Place devices to Place's Home Assistant integration

place_integration_api-0.2.5/src/place/provider.py

@@ -1,38 +0,0 @@
-from __future__ import annotations
-
-from .auth.abstract_auth import AbstractAuth
-from .models.discover_device import DiscoverDevice
-from .config import FULFILLMENT_URL
-
-class Provider:
-    def __init__(self, authorized_session: AbstractAuth) -> None:
-        self.authorized_session = authorized_session
-
-
-    async def discover(self) -> list[DiscoverDevice]:
-        body = {"command": "DISCOVER", "data": {}}
-        resp = await self.authorized_session.request("POST", FULFILLMENT_URL, json=body)
-        data = await resp.json()
-        if not data.get("success", True):
-            raise RuntimeError(f"Home Assistant error: {data.get('message', data)}")
-        devices_raw = (data.get("data") or {}).get("devices") or []
-        devices: list[DiscoverDevice] = []
-        for raw in devices_raw:
-            devices.append(DiscoverDevice.from_dict(raw))
-        return devices
-
-    async def enable(self):
-        body = {"command": "ENABLE", "data": {}}
-        resp = await self.authorized_session.request("POST", FULFILLMENT_URL, json=body)
-        data = await resp.json()
-        if not data.get("success", True):
-            raise RuntimeError(f"Home Assistant error: {data.get('message', data)}")
-        return data
-    
-    async def disable(self):
-        body = {"command": "DISABLE", "data": {}}
-        resp = await self.authorized_session.request("POST", FULFILLMENT_URL, json=body)
-        data = await resp.json()
-        if not data.get("success", True):
-            raise RuntimeError(f"Home Assistant error: {data.get('message', data)}")
-        return data

place_integration_api-0.2.5/tests/test_auth.py

@@ -1,31 +0,0 @@
-from __future__ import annotations
-
-from unittest.mock import MagicMock, patch
-from place.auth import get_iot_credentials
-
-
-@patch("place.auth.srp_auth.boto3")
-def test_get_iot_credentials_success(mock_boto3: MagicMock) -> None:
-    identity_client = MagicMock()
-    mock_boto3.client.return_value = identity_client
-
-    identity_client.get_id.return_value = {"IdentityId": "identity-123"}
-    identity_client.get_credentials_for_identity.return_value = {
-        "Credentials": {
-            "AccessKeyId": "AKIA...",
-            "SecretKey": "secret",
-            "SessionToken": "session",
-        }
-    }
-
-
-    creds = get_iot_credentials(
-        id_token="id-token",
-        access_token="access-token",
-    )
-
-    assert creds.access_key_id == "AKIA..."
-    assert creds.secret_access_key == "secret"
-    assert creds.session_token == "session"
-    assert creds.identity_id == "identity-123"
-    assert creds.access_token == "access-token"

place_integration_api-0.2.5/tests/test_mqtt_client.py

@@ -1,48 +0,0 @@
-from __future__ import annotations
-
-from unittest.mock import MagicMock, patch
-
-from place.models import Credentials
-from place.mqtt_client import get_signed_uri, MqttClient
-
-
-def test_get_signed_uri_includes_host_and_token() -> None:
-    uri = get_signed_uri(
-        access_key_id="AKIA...",
-        secret_access_key="secret",
-        session_token="token123",
-        host="example.iot.amazonaws.com",
-    )
-    assert uri.startswith("wss://example.iot.amazonaws.com/mqtt?")
-    assert "X-Amz-Algorithm=" in uri
-    assert "X-Amz-Signature=" in uri
-    assert "X-Amz-Security-Token=token123" in uri
-
-
-@patch("place.mqtt_client.mqtt.Client")
-@patch("place.mqtt_client.get_signed_uri")
-def test_mqtt_client_connect_sets_up_client(
-    mock_get_signed_uri: MagicMock,
-    mock_client_cls: MagicMock,
-) -> None:
-    mock_get_signed_uri.return_value = "wss://example.iot.amazonaws.com/mqtt?x=1"
-    client = MagicMock()
-    mock_client_cls.return_value = client
-
-    creds = Credentials(
-        access_key_id="AKIA...",
-        secret_access_key="secret",
-        session_token="token",
-        identity_id="identity-123",
-    )
-
-    mqtt_client = MqttClient(
-        endpoint="example.iot.amazonaws.com",
-        credentials=creds,
-    )
-    mqtt_client.connect()
-
-    mock_get_signed_uri.assert_called_once()
-    client.ws_set_options.assert_called()
-    client.tls_set.assert_called_once()
-    client.connect.assert_called_once()