Initial commit

Author: MizterB

.gitignore

@@ -0,0 +1,3 @@
+.vscode
+__pycache__/
+.DS_Store

LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2023 MizterB
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

README.md

@@ -0,0 +1,13 @@
+# aiophyn
+
+An asynchronous library for Phyn Smart Water devices.
+
+This library is initially focused on supporting a Phyn integration for Home Assistant, providing:
+
+- Device state
+- Water consumption
+- Shutoff valve control
+
+## Acknowledgements
+
+This work follows the example of @bachya's excellent [aioflo](https://github.com/bachya/aioflo) library for Moen Flo devices.

aiophyn/__init__.py

@@ -0,0 +1,2 @@
+"""Define the aiophyn package."""
+from .api import async_get_api

aiophyn/api.py

@@ -0,0 +1,133 @@
+"""Define a base client for interacting with Flo."""
+import logging
+from datetime import datetime, timedelta
+from typing import Optional
+from urllib.parse import urlparse
+
+import boto3
+from aiohttp import ClientSession, ClientTimeout
+from aiohttp.client_exceptions import ClientError
+from pycognito.aws_srp import AWSSRP
+
+from .const import API_BASE
+from .device import Device
+from .errors import RequestError
+from .home import Home
+
+_LOGGER = logging.getLogger(__name__)
+
+DEFAULT_HEADER_CONTENT_TYPE: str = "application/json"
+DEFAULT_HEADER_USER_AGENT: str = "phyn/18 CFNetwork/1331.0.7 Darwin/21.4.0"
+DEFAULT_HEADER_CONNECTION = "keep-alive"
+DEFAULT_HEADER_API_KEY = "E7nfOgW6VI64fYpifiZSr6Me5w1Upe155zbu4lq8"
+DEFAULT_HEADER_ACCEPT: str = "application/json"
+DEFAULT_HEADER_ACCEPT_ENCODING = "gzip, deflate, br"
+
+COGNITO_REGION = "us-east-1"
+COGNITO_POOL_ID = "us-east-1_UAv6IUsyh"
+COGNITO_CLIENT_ID = "5q2m8ti0urmepg4lup8q0ptldq"
+
+DEFAULT_TIMEOUT: int = 10
+
+
+class API:
+    """Define the API object."""
+
+    def __init__(
+        self, username: str, password: str, *, session: Optional[ClientSession] = None
+    ) -> None:
+        """Initialize."""
+        self._username: str = username
+        self._password: str = password
+        self._session: ClientSession = session
+
+        self._token: Optional[str] = None
+        self._token_expiration: Optional[datetime] = None
+        self._user_id: Optional[str] = None
+        self._username: str = username
+
+        self.home: Home = Home(self._request)
+        self.device: Device = Device(self._request)
+
+    async def _request(self, method: str, url: str, **kwargs) -> dict:
+        """Make a request against the API."""
+        if self._token_expiration and datetime.now() >= self._token_expiration:
+            _LOGGER.info("Requesting new access token to replace expired one")
+
+            # Nullify the token so that the authentication request doesn't use it:
+            self._token = None
+
+            # Nullify the expiration so the authentication request doesn't get caught
+            # here:
+            self._token_expiration = None
+
+            await self.async_authenticate()
+
+        kwargs.setdefault("headers", {})
+        kwargs["headers"].update(
+            {
+                "Content-Type": DEFAULT_HEADER_CONTENT_TYPE,
+                "User-Agent": DEFAULT_HEADER_USER_AGENT,
+                "Connection": DEFAULT_HEADER_CONNECTION,
+                "x-api-key": DEFAULT_HEADER_API_KEY,
+                "Accept": DEFAULT_HEADER_ACCEPT,
+                "Accept-Encoding": DEFAULT_HEADER_ACCEPT_ENCODING,
+            }
+        )
+
+        if self._token:
+            kwargs["headers"]["Authorization"] = self._token
+
+        use_running_session = self._session and not self._session.closed
+
+        if use_running_session:
+            session = self._session
+        else:
+            session = ClientSession(timeout=ClientTimeout(total=DEFAULT_TIMEOUT))
+
+        try:
+            async with session.request(method, url, **kwargs) as resp:
+                data: dict = await resp.json(content_type=None)
+                resp.raise_for_status()
+                return data
+        except ClientError as err:
+            raise RequestError(f"There was an error while requesting {url}") from err
+        finally:
+            if not use_running_session:
+                await session.close()
+
+    async def async_authenticate(self) -> None:
+        """Authenticate the user and set the access token with its expiration."""
+        client = boto3.client("cognito-idp", region_name=COGNITO_REGION)
+        aws = AWSSRP(
+            username=self._username,
+            password=self._password,
+            pool_id=COGNITO_POOL_ID,
+            client_id=COGNITO_CLIENT_ID,
+            client=client,
+        )
+        auth_response: dict = aws.authenticate_user()
+
+        access_token = auth_response["AuthenticationResult"]["AccessToken"]
+        expires_in = auth_response["AuthenticationResult"]["ExpiresIn"]
+
+        self._token = access_token
+        self._token_expiration = datetime.now() + timedelta(seconds=expires_in)
+
+
+async def async_get_api(
+    username: str, password: str, *, session: Optional[ClientSession] = None
+) -> API:
+    """Instantiate an authenticated API object.
+
+    :param session: An ``aiohttp`` ``ClientSession``
+    :type session: ``aiohttp.client.ClientSession``
+    :param email: A Phyn email address
+    :type email: ``str``
+    :param password: A Phyn password
+    :type password: ``str``
+    :rtype: :meth:`aiophyn.api.API`
+    """
+    api = API(username, password, session=session)
+    await api.async_authenticate()
+    return api

aiophyn/const.py

@@ -0,0 +1,2 @@
+"""Define package constants."""
+API_BASE: str = "https://api.phyn.com"

aiophyn/device.py

@@ -0,0 +1,90 @@
+"""Define /devices endpoints."""
+from typing import Awaitable, Callable, Optional
+
+from .const import API_BASE
+
+
+class Device:
+    """Define an object to handle the endpoints."""
+
+    def __init__(self, request: Callable[..., Awaitable]) -> None:
+        """Initialize."""
+        self._request: Callable[..., Awaitable] = request
+
+    async def get_state(self, device_id: str) -> dict:
+        """Return state of a device.
+
+        :param device_id: Unique identifier for the device
+        :type device_id: ``str``
+        :rtype: ``dict``
+        """
+        return await self._request("get", f"{API_BASE}/devices/{device_id}/state")
+
+    async def get_consumption(
+        self,
+        device_id: str,
+        duration: str,
+        precision: int = 6,
+        details: Optional[str] = False,
+        event_count: Optional[str] = False,
+        comparison: Optional[str] = False,
+    ) -> dict:
+        """Return water consumption of a device.
+
+        :param device_id: Unique identifier for the device
+        :type device_id: ``str``
+        :param duration: Date string formatted as 'YYYY/MM/DD', 'YYYY/MM', or 'YYYY'
+        :type duration: ``str``
+        :param precision: Decimal places of measurement precision
+        :type precision: ``int``
+        :param details: Include detailed breakdown of consumption
+        :type details: ``bool``
+        :param event_count: Include the event count
+        :type event_count: ``bool``
+        :param comparison: Include comparison data
+        :type comparison: ``bool``
+        :rtype: ``dict``
+        """
+
+        params = {
+            "device_id": device_id,
+            "duration": duration,
+            "precision": precision,
+        }
+
+        if details:
+            params["details"] = "Y"
+
+        if event_count:
+            params["event_count"] = "Y"
+
+        if comparison:
+            params["comparison"] = "Y"
+
+        return await self._request(
+            "get", f"{API_BASE}/devices/{device_id}/consumption/details", params=params
+        )
+
+    async def open_valve(self, device_id: str) -> None:
+        """Open a device shutoff valve.
+
+        :param device_id: Unique identifier for the device
+        :type device_id: ``str``
+        :rtype: ``dict``
+        """
+        return await self._request(
+            "post",
+            f"{API_BASE}/devices/{device_id}/sov/Open",
+        )
+
+    async def close_valve(self, device_id: str) -> None:
+        """Close a device shutoff valve.
+
+        :param device_id: Unique identifier for the device
+        :type device_id: ``str``
+        :rtype: ``dict``
+        """
+        return await self._request(
+            "post",
+            f"{API_BASE}/devices/{device_id}/sov/Close",
+        )

aiophyn/errors.py

@@ -0,0 +1,13 @@
+"""Define package errors."""
+
+
+class PhynError(Exception):
+    """Define a base error."""
+
+    ...
+
+
+class RequestError(PhynError):
+    """Define an error related to invalid requests."""
+
+    ...

aiophyn/home.py

@@ -0,0 +1,26 @@
+"""Define /home endpoints."""
+from typing import Awaitable, Callable
+
+from .const import API_BASE
+
+
+class Home:
+    """Define an object to handle the endpoints."""
+
+    def __init__(self, request: Callable[..., Awaitable]) -> None:
+        """Initialize."""
+        self._request: Callable[..., Awaitable] = request
+
+    async def get_info(
+        self,
+        user_id: str,
+    ) -> dict:
+        """Return info for all homes.
+
+        :param user_id: Phyn username (email)
+        :type user_id: ``str``
+        :rtype: ``list``
+        """
+        params = {"user_id": user_id}
+
+        return await self._request("get", f"{API_BASE}/homes", params=params)

examples/test_api.py

@@ -0,0 +1,53 @@
+"""Run an example script to quickly test."""
+import asyncio
+import logging
+from datetime import date
+
+from aiohttp import ClientSession
+
+from aiophyn import async_get_api
+from aiophyn.errors import PhynError
+
+_LOGGER = logging.getLogger()
+
+USERNAME = "USERNAME_HERE"
+PASSWORD = "PASSWORD_HERE"
+
+
+async def main() -> None:
+    """Create the aiohttp session and run the example."""
+    logging.basicConfig(level=logging.INFO)
+    async with ClientSession() as session:
+        try:
+            api = await async_get_api(USERNAME, PASSWORD, session=session)
+
+            all_home_info = await api.home.get_info(USERNAME)
+            _LOGGER.info(all_home_info)
+
+            home_info = all_home_info[0]
+            _LOGGER.info(home_info)
+
+            first_device_id = home_info["device_ids"][0]
+            device_state = await api.device.get_state(first_device_id)
+            _LOGGER.info(device_state)
+
+            duration_today = date.today().strftime("%Y/%m/%d")
+            consumption_info = await api.device.get_consumption(
+                first_device_id, duration_today, details=True
+            )
+            _LOGGER.info(consumption_info)
+
+            valve_status = device_state["sov_status"]["v"]
+            _LOGGER.info(valve_status)
+
+            # close_valve_response = await api.device.close_valve(first_device_id)
+            # _LOGGER.info(close_valve_response)
+
+            # open_valve_response = await api.device.open_valve(first_device_id)
+            # _LOGGER.info(open_valve_response)
+
+        except PhynError as err:
+            _LOGGER.error("There was an error: %s", err)
+
+
+asyncio.run(main())