petsafe-api 3.0.4__tar.gz → 3.1.1__tar.gz

{petsafe_api-3.0.4 → petsafe_api-3.1.1}/PKG-INFO

@@ -1,6 +1,6 @@
 Metadata-Version: 2.4
 Name: petsafe-api
-Version: 3.0.4
+Version: 3.1.1
 Summary: Provides ability to connect and control a PetSafe Smart Feed, Scoopfree, and Smart Door devices using the PetSafe API.
 Home-page: https://github.com/ThomasHFWright/petsafe-api
 Author: Jordan Stremming & Dominick Meglio & Thomas Wright
@@ -9,11 +9,15 @@ License: MIT
 Classifier: Programming Language :: Python :: 3
 Classifier: License :: OSI Approved :: MIT License
 Classifier: Operating System :: OS Independent
-Requires-Python: >=3.6
+Requires-Python: >=3.9
 Description-Content-Type: text/markdown
 License-File: LICENSE
 Requires-Dist: httpx
 Requires-Dist: botocore
+Provides-Extra: ble
+Requires-Dist: bleak; extra == "ble"
+Requires-Dist: cbor2; extra == "ble"
+Requires-Dist: cryptography; extra == "ble"
 Dynamic: author
 Dynamic: author-email
 Dynamic: classifier
@@ -22,6 +26,7 @@ Dynamic: description-content-type
 Dynamic: home-page
 Dynamic: license
 Dynamic: license-file
+Dynamic: provides-extra
 Dynamic: requires-dist
 Dynamic: requires-python
 Dynamic: summary
@@ -52,7 +57,57 @@ Thank you to both projects for building the API integrations for existing feeder
 If installing from source code,
 `python setup.py install`
 
-## Login tokens
+## Local SmartDoor control and provisioning (3.1.0)
+
+`LocalPetSafeClient` connects to a compatible local server using its HTTPS origin
+and API token. It does not use a PetSafe vendor login, and returns the same
+`DeviceSmartDoor` objects as the cloud client, so existing methods are reused:
+
+```python
+import asyncio
+import petsafe
+
+
+async def main() -> None:
+    async with petsafe.LocalPetSafeClient(
+        "https://petsafe.example", "LOCAL_API_TOKEN"
+    ) as client:
+        door = (await client.get_smartdoors())[0]
+        await door.lock()
+        await door.unlock()
+        await door.smart_mode()
+
+
+asyncio.run(main())
+```
+
+BLE provisioning dependencies are optional: `pip install petsafe-api[ble]`.
+[`SetupClient`](petsafe/setup.py) creates a server-correlated setup session;
+the BLE entry point is
+[`provision_smartdoor`](petsafe/provisioning.py):
+
+```python
+from petsafe import SetupClient
+from petsafe.provisioning import WifiNetwork, provision_smartdoor
+
+
+async def provision() -> None:
+    async with SetupClient(SERVER_ORIGIN, API_TOKEN) as setup:
+        session = await setup.create(DEVICE_ID, "provision")
+        result = await provision_smartdoor(
+            ble_device,
+            session.endpoint,
+            WifiNetwork(ssid=SSID, password=PASSWORD, bssid=BSSID_BYTES),
+            confirm=setup.confirmation(session),
+        )
+```
+
+Local operation requires a compatible server and a hostname resolving to it. Provisioning
+also requires supported BLE hardware or a nearby proxy and an HTTPS hostname and
+certificate trusted by the SmartDoor; hardware testing used an Amazon-trusted
+certificate. A raw IP address is not a supported or promised substitute.
+
+## Cloud login tokens
 You **must** use tokens to interact with the PetSafe Smart-Feed API.  
 There are two methods to retrieve tokens:
 

{petsafe_api-3.0.4 → petsafe_api-3.1.1}/README.md

@@ -24,7 +24,57 @@ Thank you to both projects for building the API integrations for existing feeder
 If installing from source code,
 `python setup.py install`
 
-## Login tokens
+## Local SmartDoor control and provisioning (3.1.0)
+
+`LocalPetSafeClient` connects to a compatible local server using its HTTPS origin
+and API token. It does not use a PetSafe vendor login, and returns the same
+`DeviceSmartDoor` objects as the cloud client, so existing methods are reused:
+
+```python
+import asyncio
+import petsafe
+
+
+async def main() -> None:
+    async with petsafe.LocalPetSafeClient(
+        "https://petsafe.example", "LOCAL_API_TOKEN"
+    ) as client:
+        door = (await client.get_smartdoors())[0]
+        await door.lock()
+        await door.unlock()
+        await door.smart_mode()
+
+
+asyncio.run(main())
+```
+
+BLE provisioning dependencies are optional: `pip install petsafe-api[ble]`.
+[`SetupClient`](petsafe/setup.py) creates a server-correlated setup session;
+the BLE entry point is
+[`provision_smartdoor`](petsafe/provisioning.py):
+
+```python
+from petsafe import SetupClient
+from petsafe.provisioning import WifiNetwork, provision_smartdoor
+
+
+async def provision() -> None:
+    async with SetupClient(SERVER_ORIGIN, API_TOKEN) as setup:
+        session = await setup.create(DEVICE_ID, "provision")
+        result = await provision_smartdoor(
+            ble_device,
+            session.endpoint,
+            WifiNetwork(ssid=SSID, password=PASSWORD, bssid=BSSID_BYTES),
+            confirm=setup.confirmation(session),
+        )
+```
+
+Local operation requires a compatible server and a hostname resolving to it. Provisioning
+also requires supported BLE hardware or a nearby proxy and an HTTPS hostname and
+certificate trusted by the SmartDoor; hardware testing used an Amazon-trusted
+certificate. A raw IP address is not a supported or promised substitute.
+
+## Cloud login tokens
 You **must** use tokens to interact with the PetSafe Smart-Feed API.  
 There are two methods to retrieve tokens:
 

petsafe_api-3.1.1/petsafe/__init__.py

@@ -0,0 +1,4 @@
+from . import devices, general, pets
+from .client import PetSafeClient
+from .local import LocalPetSafeClient
+from .setup import InvalidSetupResponse, SetupAPIError, SetupClient, SetupSession

petsafe_api-3.1.1/petsafe/local.py

@@ -0,0 +1,118 @@
+"""Client for a PetSafe local-control server."""
+from __future__ import annotations
+
+import asyncio
+import json
+from typing import Any, Optional
+from urllib.parse import unquote, urlsplit
+
+import httpx
+
+from .devices import DeviceSmartDoor
+from .setup import _TOKEN
+
+MAX_RESPONSE_BYTES = 1024 * 1024
+
+
+class LocalPetSafeClient:
+    """Minimal async client exposing the cloud-compatible local API surface."""
+
+    def __init__(self, server_url: str, api_token: str, *,
+                 client: Optional[httpx.AsyncClient] = None) -> None:
+        if (type(api_token) is not str or not api_token or len(api_token) > 4096
+                or not _TOKEN.fullmatch(api_token)):
+            raise ValueError("api_token must be a valid bearer token")
+        try:
+            url = httpx.URL(server_url)
+        except (TypeError, httpx.InvalidURL) as error:
+            raise ValueError("server_url must be an HTTPS origin") from error
+        if (type(server_url) is not str or len(server_url) > 2048 or url.scheme != "https"
+                or not url.host or url.userinfo or url.path != "/" or url.query or url.fragment):
+            raise ValueError("server_url must be an HTTPS origin")
+        self._origin = (url.scheme, url.host, url.port or 443)
+        self._base_url = str(url).rstrip("/") + "/local/"
+        self._api_token = api_token
+        self._owned = client is None
+        self._client = client or httpx.AsyncClient(timeout=30, follow_redirects=False)
+
+    def __repr__(self) -> str:
+        return f"{type(self).__name__}(server_url={self._base_url[:-7]!r})"
+
+    async def __aenter__(self) -> "LocalPetSafeClient":
+        return self
+
+    async def __aexit__(self, *_: Any) -> None:
+        await self.aclose()
+
+    async def aclose(self) -> None:
+        if self._owned:
+            await self._client.aclose()
+
+    def _request_url(self, path: str) -> str:
+        if type(path) is not str or len(path) > 2048 or "\\" in path:
+            raise ValueError("path must be a relative API path")
+        parsed = urlsplit(path)
+        decoded = unquote(unquote(parsed.path))
+        if (parsed.scheme or parsed.netloc or parsed.fragment or decoded.startswith("/")
+                or "\\" in decoded or any(part in (".", "..") for part in decoded.split("/"))):
+            raise ValueError("path must be a relative API path without traversal")
+        url = httpx.URL(self._base_url + path)
+        if (url.scheme, url.host, url.port or 443) != self._origin:
+            raise ValueError("path must remain on the configured server")
+        return str(url)
+
+    async def _request(self, method: str, path: str, data: Optional[dict] = None) -> httpx.Response:
+        request = self._client.build_request(
+            method, self._request_url(path),
+            headers={"Authorization": f"Bearer {self._api_token}", "Accept": "application/json"},
+            json=data, timeout=30,
+        )
+        response = await self._client.send(request, stream=True, follow_redirects=False)
+        try:
+            response.raise_for_status()
+            body = bytearray()
+            async for chunk in response.aiter_bytes():
+                body.extend(chunk)
+                if len(body) > MAX_RESPONSE_BYTES:
+                    raise httpx.HTTPError("local API response is too large")
+            headers = response.headers.copy()
+            headers.pop("content-encoding", None)
+            headers.pop("content-length", None)
+            return httpx.Response(
+                response.status_code, headers=headers, content=bytes(body),
+                request=request, extensions=response.extensions,
+            )
+        finally:
+            await response.aclose()
+
+    async def api_get(self, path: str = "") -> httpx.Response:
+        return await self._request("GET", path)
+
+    async def api_patch(self, path: str = "", data: Optional[dict] = None) -> httpx.Response:
+        return await self._request("PATCH", path, data)
+
+    async def api_post(self, path: str = "", data: Optional[dict] = None) -> httpx.Response:
+        return await self._request("POST", path, data)
+
+    async def api_delete(self, path: str = "") -> httpx.Response:
+        return await self._request("DELETE", path)
+
+    async def get_smartdoors(self) -> list[DeviceSmartDoor]:
+        response = await self.api_get("smartdoor/product/product")
+        payload = json.loads(response.content.decode("UTF-8"))
+        devices = payload.get("data", payload) if isinstance(payload, dict) else payload
+        if not isinstance(devices, list) or any(not isinstance(data, dict) for data in devices):
+            raise ValueError("Unexpected response payload for SmartDoor devices")
+        doors = [DeviceSmartDoor(self, data) for data in devices]
+        preferences = await asyncio.gather(*(door.get_preferences() for door in doors))
+        for door, prefs in zip(doors, preferences):
+            for name in ("friendlyName", "tz"):
+                if name in prefs:
+                    door.data[name] = prefs[name]
+        return doors
+
+    async def get_feeders(self) -> list:
+        return []
+
+    async def get_litterboxes(self) -> list:
+        return []