eero-client 2.2.0__tar.gz

eero-client-2.2.0/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) [year] [fullname]
+
+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.

eero-client-2.2.0/PKG-INFO

@@ -0,0 +1,97 @@
+Metadata-Version: 2.1
+Name: eero-client
+Version: 2.2.0
+Summary: Manage eero network devices
+Home-page: https://github.com/EvanSchalton/eero-client
+Author: Evan Schalton
+Author-email: Evan.Schalton@Gmail.com
+License: MIT License
+Keywords: eero
+Classifier: Development Status :: 4 - Beta
+Classifier: Intended Audience :: Developers
+Classifier: Natural Language :: English
+Classifier: Operating System :: OS Independent
+Classifier: Programming Language :: Python :: 3
+Classifier: Programming Language :: Python :: 3.10
+Classifier: Programming Language :: Python :: 3.11
+Classifier: Typing :: Typed
+Classifier: Topic :: Software Development :: Libraries :: Python Modules
+Classifier: Topic :: Utilities
+Classifier: License :: OSI Approved :: MIT License
+Requires-Python: >=3.10
+Description-Content-Type: text/markdown
+License-File: LICENSE
+
+# Unofficial client for [Eero Mesh Routers](https://eero.com)
+
+
+# SDK Design Considerations
+The SDK leverages pydantic to return models for all supported endpoints, endpoints are created using a method factory and configurations in the [routes.py](/eero//client//routes/routes.py) file allowing for easy extension.
+
+- `GET` Methods are exposed as class properties
+- `POST` Methods are exposed as class methods with `**kwargs` for route params (if applicable).
+
+As this is an undocumented API, I was only able to create models for the objects returned in my network, please consider contributing / updating models if your network has additional parameters.
+
+
+# Usage Example
+[example.ipynb](/example.ipynb)
+
+## Authentication
+```
+from eero import Eero, FileSessionStorage
+
+session = FileSessionStorage("session.cookie")
+eero = Eero(session=session)
+
+if not eero.is_authenticated:
+    auth_source = input("Phone Number or Email: ")
+    user_token = eero.login(auth_source)
+    verification_code = input("verification key from email or SMS: ")
+    eero.login_verify(verification_code, user_token)
+```
+
+## Routes
+### Get Requests
+[GET_RESOURCES](/eero//client/routes/routes.py) defines the get properties in the structure of `{property_name: tuple[url, response_model]}`
+
+The following get properties are defined:
+```
+account
+ac_compat
+device_blacklist
+devices
+diagnostics
+eeros
+forwards
+ouicheck
+guestnetwork
+profiles
+reservations
+speedtest
+updates
+support
+insights
+routing
+thread
+networks
+```
+### Post Requests
+[POST_RESOURCES](/eero//client/routes/routes.py) defines the post methods in the structure of `{property_name: tuple[url, response_model]}`
+
+The following get properties are defined:
+```
+burst_reporters
+reboot
+reboot_eero - takes in the id of the error to reboot, available from the client.eeros get endpoint. 
+run_speedtest
+```
+# Inspiration
+Thank you to `Max von Webel` for his original work, [eero-client](https://github.com/343max/eero-client), I hadn't considered accesssing my router's data until I saw his project and only opted to fork and rewrite to add more of my own opinionated design patterns.
+
+# Future Plans
+## Device Triangulation
+I played with the idea of using the signal strength for each connected device captured while looping over the network turn off all but one eero at a time, and the relative 3D coordinates of the eero devices to create a 3D rendering of all of the devices in my home. This worked decently well for devices in a room with an eero, but for obstructed devices their positions there were too many intersection points with a mesh of four units. If I circle back to this in the future I may add code in a post. 
+
+## Home Assistant Integration
+My next goal is to expose the eeros & devices in Home Assistant through an integration, when I'm successful I'll post a link to that repo/HACS integration here my intent is to use this SDK as the foundation for that work.

eero-client-2.2.0/README.md

@@ -0,0 +1,73 @@
+# Unofficial client for [Eero Mesh Routers](https://eero.com)
+
+
+# SDK Design Considerations
+The SDK leverages pydantic to return models for all supported endpoints, endpoints are created using a method factory and configurations in the [routes.py](/eero//client//routes/routes.py) file allowing for easy extension.
+
+- `GET` Methods are exposed as class properties
+- `POST` Methods are exposed as class methods with `**kwargs` for route params (if applicable).
+
+As this is an undocumented API, I was only able to create models for the objects returned in my network, please consider contributing / updating models if your network has additional parameters.
+
+
+# Usage Example
+[example.ipynb](/example.ipynb)
+
+## Authentication
+```
+from eero import Eero, FileSessionStorage
+
+session = FileSessionStorage("session.cookie")
+eero = Eero(session=session)
+
+if not eero.is_authenticated:
+    auth_source = input("Phone Number or Email: ")
+    user_token = eero.login(auth_source)
+    verification_code = input("verification key from email or SMS: ")
+    eero.login_verify(verification_code, user_token)
+```
+
+## Routes
+### Get Requests
+[GET_RESOURCES](/eero//client/routes/routes.py) defines the get properties in the structure of `{property_name: tuple[url, response_model]}`
+
+The following get properties are defined:
+```
+account
+ac_compat
+device_blacklist
+devices
+diagnostics
+eeros
+forwards
+ouicheck
+guestnetwork
+profiles
+reservations
+speedtest
+updates
+support
+insights
+routing
+thread
+networks
+```
+### Post Requests
+[POST_RESOURCES](/eero//client/routes/routes.py) defines the post methods in the structure of `{property_name: tuple[url, response_model]}`
+
+The following get properties are defined:
+```
+burst_reporters
+reboot
+reboot_eero - takes in the id of the error to reboot, available from the client.eeros get endpoint. 
+run_speedtest
+```
+# Inspiration
+Thank you to `Max von Webel` for his original work, [eero-client](https://github.com/343max/eero-client), I hadn't considered accesssing my router's data until I saw his project and only opted to fork and rewrite to add more of my own opinionated design patterns.
+
+# Future Plans
+## Device Triangulation
+I played with the idea of using the signal strength for each connected device captured while looping over the network turn off all but one eero at a time, and the relative 3D coordinates of the eero devices to create a 3D rendering of all of the devices in my home. This worked decently well for devices in a room with an eero, but for obstructed devices their positions there were too many intersection points with a mesh of four units. If I circle back to this in the future I may add code in a post. 
+
+## Home Assistant Integration
+My next goal is to expose the eeros & devices in Home Assistant through an integration, when I'm successful I'll post a link to that repo/HACS integration here my intent is to use this SDK as the foundation for that work.

eero-client-2.2.0/eero/__init__.py

@@ -0,0 +1,14 @@
+from .client import Eero
+from .exceptions import ClientException
+from .logger import log_setup
+from .session import FileSessionStorage, SessionStorage
+from .version import __version__
+
+log_setup()
+__all__ = [
+    "ClientException",
+    "Eero",
+    "SessionStorage",
+    "FileSessionStorage",
+    "__version__",
+]

eero-client-2.2.0/eero/client/__init__.py

@@ -0,0 +1,3 @@
+from .clients import Eero
+
+__all__ = ["Eero"]

eero-client-2.2.0/eero/client/api_client.py

@@ -0,0 +1,68 @@
+import json
+from http import HTTPStatus
+from logging import getLogger
+from typing import Any
+
+import requests
+
+from ..exceptions import ClientException
+from .models import ErrorMeta
+
+logger = getLogger("eero")
+
+API_VERSION = "2.2"
+
+
+class APIClient(object):
+    API_ENDPOINT = "https://api-user.e2ro.com/{}/{}"
+
+    def _parse_response(self, action, response) -> dict[str, Any]:
+        data = json.loads(response.text)
+        logger.debug("Response for %s: %s", action, data)
+        try:
+            if data["meta"]["code"] not in [
+                HTTPStatus.OK,
+                HTTPStatus.CREATED,
+                HTTPStatus.ACCEPTED,
+            ]:
+                client_exception = ClientException(
+                    data["meta"]["code"], data["meta"].get("error", "Unknown Error")
+                )
+                logger.error(client_exception)
+
+                try:
+                    ErrorMeta.model_validate(data)
+                    return data
+                except Exception:
+                    raise client_exception
+        except ClientException as e:
+            raise e
+        except Exception as e:
+            logger.error("KeyError - Failed to parse response: %s [%s]", data, e)
+            try:
+                raise ClientException(
+                    data.get("result", {}).get("error", {}).get("requestId"),
+                    data.get("result", {}).get("error", {}).get("message"),
+                ) from e
+            except KeyError:
+                raise ClientException(
+                    data.get("meta", {}).get("code", HTTPStatus.INTERNAL_SERVER_ERROR),
+                    data.get("meta", {}).get("error", "Unknown Error"),
+                ) from e
+        return data.get("data", data.get("meta", {}))
+
+    def request(self, method, action, **kwargs):
+        response = requests.request(
+            method, self.API_ENDPOINT.format(API_VERSION, action), **kwargs
+        )
+        return self._parse_response(action, response)
+
+    def post(self, action, **kwargs):
+        response = requests.post(
+            self.API_ENDPOINT.format(API_VERSION, action), **kwargs
+        )
+        return self._parse_response(action, response)
+
+    def get(self, action, **kwargs):
+        response = requests.get(self.API_ENDPOINT.format(API_VERSION, action), **kwargs)
+        return self._parse_response(action, response)

eero-client-2.2.0/eero/client/clients/__init__.py

@@ -0,0 +1,4 @@
+from .eero import Eero
+from .network import NetworkClient
+
+__all__ = ["Eero", "NetworkClient"]

eero-client-2.2.0/eero/client/clients/eero.py

@@ -0,0 +1,43 @@
+from ..api_client import APIClient
+from ..models.account import Account
+from ..routes.method_factory import make_method
+from ..routes.routes import GET_RESOURCES
+from .eero_auth_handler import EeroAuthHandler
+from .network import NetworkClient
+
+
+class Eero(EeroAuthHandler):
+    def __init__(self, session, api_client=APIClient | None) -> None:
+        self.session = session
+        if api_client is None:
+            api_client = APIClient()
+        self.client = api_client
+        self._network_clients: dict[str, NetworkClient] | None = None  # type: ignore
+
+    @property
+    def network_clients(self) -> dict[str, NetworkClient]:  # type: ignore
+        if self._network_clients is None:
+            if not self.is_authenticated:
+                raise ValueError("Not authenticated")
+            self._network_clients = {
+                i.name: NetworkClient(
+                    network_info=i,
+                    session=self.session,
+                    client=self.client,
+                    **i.model_dump(),
+                )
+                for i in self.account().networks.data
+            }
+
+        return self._network_clients
+
+    @network_clients.setter
+    def network_clients(self, network_clients: dict[str, NetworkClient]):  # type: ignore
+        self._network_clients = network_clients
+
+    def account(self) -> Account:
+        return make_method(
+            method="get",
+            action="account",
+            resource=GET_RESOURCES["account"],
+        )(self)

eero-client-2.2.0/eero/client/clients/eero_auth_handler.py

@@ -0,0 +1,51 @@
+from ...exceptions import ClientException
+from ..api_client import APIClient
+
+
+class EeroAuthHandler:
+    def __init__(self, session):
+        self.session = session
+        self.client = APIClient()
+
+    @property
+    def _cookie_dict(self):
+        if not self.is_authenticated:
+            return dict()
+        else:
+            return dict(s=self.session.cookie)
+
+    @property
+    def is_authenticated(self) -> bool:
+        return self.session.cookie is not None
+
+    def login(self, identifier):
+        # type(string) -> string
+        json = dict(login=identifier)
+        data = self.client.post("login", json=json)
+        return data["user_token"]
+
+    def login_verify(self, verification_code, user_token):
+        response = self.client.post(
+            "login/verify",
+            json=dict(code=verification_code),
+            cookies=dict(s=user_token),
+        )
+        self.session.cookie = user_token
+        return response
+
+    def refreshed(self, func):
+        try:
+            return func()
+        except ClientException as exception:
+            if (
+                exception.status == 401
+                and exception.error_message == "error.session.refresh"
+            ):
+                self.login_refresh()
+                return func()
+            else:
+                raise
+
+    def login_refresh(self):
+        response = self.client.post("login/refresh", cookies=self._cookie_dict)
+        self.session.cookie = response["user_token"]

eero-client-2.2.0/eero/client/clients/network.py

@@ -0,0 +1,34 @@
+from typing import Any, cast
+
+from ...session import SessionStorage
+from ..api_client import APIClient
+from ..models import NetworkInfo
+from ..routes import APITypes, network_client_methods
+from .eero_auth_handler import EeroAuthHandler
+
+
+def __network_client____init___(
+    self,
+    session: SessionStorage,
+    network_info: NetworkInfo,
+    client: APIClient | None = None,
+    **kwargs: Any,
+) -> None:
+    self.network_info = network_info
+    self.session = session
+    if client is None:
+        client = APIClient()
+    self.client = client
+
+
+NetworkClient = type(
+    "NetworkClient",
+    (APITypes, EeroAuthHandler),
+    {
+        "__init__": __network_client____init___,
+        "network_info": cast(NetworkInfo, None),
+        "session": cast(SessionStorage, None),
+        "client": cast(APIClient, None),
+        **network_client_methods,
+    },
+)

eero-client-2.2.0/eero/client/models/__init__.py

@@ -0,0 +1,38 @@
+from .ac_compat import ACCompat
+from .account import Account, NetworkInfo
+from .burst_reporters import BurstReporters
+from .device import Device
+from .diagnostics import Diagnostics
+from .error_meta import ErrorMeta
+from .forward import Forward
+from .networks import EeroDevice, GuestNetwork, Networks
+from .no_data_meta import NoDataMeta
+from .profile import Profile
+from .reservation import Reservation
+from .routing import Routing
+from .speedtest import Speedtest
+from .support import Support
+from .thread import Thread
+from .updates import Updates
+
+__all__ = [
+    "Account",
+    "NetworkInfo",
+    "Networks",
+    "Device",
+    "ACCompat",
+    "Diagnostics",
+    "EeroDevice",
+    "Forward",
+    "GuestNetwork",
+    "Profile",
+    "Reservation",
+    "Speedtest",
+    "Updates",
+    "Support",
+    "Routing",
+    "Thread",
+    "ErrorMeta",
+    "BurstReporters",
+    "NoDataMeta",
+]

eero-client-2.2.0/eero/client/models/ac_compat.py

@@ -0,0 +1,5 @@
+from pydantic import BaseModel
+
+
+class ACCompat(BaseModel):
+    enabled: bool

eero-client-2.2.0/eero/client/models/account.py

@@ -0,0 +1,87 @@
+from datetime import datetime
+
+from pydantic import BaseModel
+
+
+class Phone(BaseModel):
+    value: str
+    country_code: str
+    national_number: str
+    verified: bool
+
+
+class Email(BaseModel):
+    value: str
+    verified: bool
+
+
+class NetworkInfo(BaseModel):
+    url: str
+    name: str
+    created: str
+    nickname_label: str | None = None
+    access_expires_on: datetime | None = None
+    amazon_directed_id: str
+
+    @property
+    def id(self):
+        return self.url.split("/")[-1]
+
+
+class Networks(BaseModel):
+    count: int
+    data: list[NetworkInfo]
+
+
+class Auth(BaseModel):
+    type: str
+    provider_id: str | None = None
+    service_id: str | None = None
+
+
+class PremiumDetails(BaseModel):
+    trial_ends: datetime | None = None
+    has_payment_info: bool
+    tier: str
+    is_iap_customer: bool
+    payment_method: str | None = None
+    interval: str
+    next_billing_event_date: datetime | None = None
+
+
+class PushSettings(BaseModel):
+    networkOffline: bool
+    nodeOffline: bool
+
+
+class Consent(BaseModel):
+    consented: bool
+
+
+class Consents(BaseModel):
+    marketing_emails: Consent
+
+
+class Account(BaseModel):
+    name: str
+    phone: Phone
+    email: Email
+    log_id: str
+    organization_id: str | None = None
+    image_assets: list[str] | None = None
+    networks: Networks
+    auth: Auth
+    role: str | None = None
+    is_beta_bug_reporter_eligible: bool
+    can_transfer: bool
+    is_premium_capable: bool
+    payment_failed: bool
+    premium_status: str
+    premium_details: PremiumDetails
+    push_settings: PushSettings
+    trust_certificates_etag: str
+    consents: Consents
+    can_migrate_to_amazon_login: bool
+    eero_for_business: bool
+    mdu_program: bool
+    business_details: str | None = None

eero-client-2.2.0/eero/client/models/burst_reporters.py

@@ -0,0 +1,7 @@
+from datetime import datetime
+
+from pydantic import BaseModel
+
+
+class BurstReporters(BaseModel):
+    next_burst: datetime

eero-client-2.2.0/eero/client/models/device.py

@@ -0,0 +1,118 @@
+from datetime import datetime
+
+from pydantic import BaseModel, ConfigDict
+
+
+class DeviceSource(BaseModel):
+    location: str | None = None
+    is_gateway: bool | None = None
+    model: str | None = None
+    display_name: str | None = None
+    serial_number: str | None = None
+    is_proxied_node: bool | None = None
+    url: str | None = None
+
+
+class RateInfo(BaseModel):
+    rate_bps: int | str | None = None
+    mcs: int | str | None = None
+    nss: int | str | None = None
+    guard_interval: str | None = None
+    channel_width: str | None = None
+    phy_type: str | None = None
+
+
+class DeviceEthernetStatus(BaseModel):
+    has_carrier: bool
+    interface_number: int
+    speed: str
+    is_wan_port: bool
+    is_lte: bool
+    port_name: str
+
+
+class DeviceConnectivity(BaseModel):
+    rx_bitrate: str | None = None
+    signal: str | None = None
+    signal_avg: str | None = None
+    score: float | None = None
+    score_bars: int | None = None
+    frequency: int | None = None
+    rx_rate_info: RateInfo | None = None
+    tx_rate_info: RateInfo | None = None
+    ethernet_status: DeviceEthernetStatus | None = None
+
+
+class Interface(BaseModel):
+    frequency: str | None = None
+    frequency_unit: str | None = None
+
+
+class Profile(BaseModel):
+    url: str
+    name: str
+    paused: bool
+
+
+class HomeKit(BaseModel):
+    registered: bool
+    protection_mode: str
+
+
+class DeviceRingLTE(BaseModel):
+    is_not_pausable: bool
+    ring_managed: bool
+    lte_enabled: bool
+
+
+class AmazonDevicesDetail(BaseModel):
+    model_config = ConfigDict(protected_namespaces=())
+
+    model_name_internal: str | None = None
+
+
+class RoutingDeviceData(BaseModel):
+    url: str
+    mac: str
+    nickname: str | None = None
+
+
+class ProfileDevice(RoutingDeviceData):
+    model_config = ConfigDict(protected_namespaces=())
+    manufacturer: str | None = None
+    manufacturer_device_type_id: str | None = None
+    ip: str | None = None
+    ips: list[str]
+    hostname: str | None = None
+    connected: bool
+    wireless: bool
+    connection_type: str | None = None
+    source: DeviceSource
+    last_active: datetime | None = None
+    first_active: datetime | None = None
+    connectivity: DeviceConnectivity
+    interface: Interface
+    usage: str | None = None
+    homekit: HomeKit | None = None
+    device_type: str
+    auth: str | None = None
+    paused: bool
+    display_name: str | None = None
+    is_private: bool
+    model_name: str | None = None
+
+
+class Device(ProfileDevice):
+    eui64: str
+    ipv6_addresses: list[str]
+    profile: Profile | None = None
+    blacklisted: bool | None = None
+    is_guest: bool
+    channel: int | None = None
+    secondary_wan_deny_access: bool
+    ring_lte: DeviceRingLTE
+    ipv4: str | None = None
+    is_proxied_node: bool
+    amazon_devices_detail: AmazonDevicesDetail | None = None
+    ssid: str | None = None
+    subnet_kind: str | None = None

eero-client-2.2.0/eero/client/models/diagnostics.py

@@ -0,0 +1,5 @@
+from pydantic import BaseModel
+
+
+class Diagnostics(BaseModel):
+    status: str