equilab 0.1.1__py3-none-any.whl

equilab-0.1.1.dist-info/METADATA

@@ -0,0 +1,105 @@
+Metadata-Version: 2.5
+Name: equilab
+Version: 0.1.1
+Summary: Async, read-only Python client for the unofficial Equilab cloud API
+Project-URL: Homepage, https://github.com/Danw33/py-equilab
+Project-URL: Repository, https://github.com/Danw33/py-equilab
+Project-URL: Issues, https://github.com/Danw33/py-equilab/issues
+Project-URL: Changelog, https://github.com/Danw33/py-equilab/blob/main/CHANGELOG.md
+Author-email: Daniel Wilson <hello@danw.io>
+License-Expression: Apache-2.0
+License-File: LICENSE
+License-File: NOTICE
+Keywords: asyncio,equestrian,equilab,home-assistant
+Classifier: Development Status :: 3 - Alpha
+Classifier: Framework :: AsyncIO
+Classifier: Intended Audience :: Developers
+Classifier: License :: OSI Approved :: Apache Software License
+Classifier: Operating System :: OS Independent
+Classifier: Programming Language :: Python :: 3
+Classifier: Programming Language :: Python :: 3.11
+Classifier: Programming Language :: Python :: 3.12
+Classifier: Programming Language :: Python :: 3.13
+Classifier: Programming Language :: Python :: 3.14
+Classifier: Topic :: Home Automation
+Classifier: Typing :: Typed
+Requires-Python: >=3.11
+Requires-Dist: aiohttp<4,>=3.11.0
+Provides-Extra: test
+Requires-Dist: mypy==2.3.1; extra == 'test'
+Requires-Dist: pytest-asyncio==1.4.0; extra == 'test'
+Requires-Dist: pytest-cov==7.1.0; extra == 'test'
+Requires-Dist: pytest==9.1.1; extra == 'test'
+Requires-Dist: ruff==0.16.7; extra == 'test'
+Description-Content-Type: text/markdown
+
+# py-equilab: Equilab API Client Python Library
+
+An **unofficial**, asynchronous, read-only Python client for the Equilab cloud API.
+
+This library provides authentication, token renewal, bounded concurrent reads,
+rate-limit observations, Firestore decoding, and typed domain models for Equilab
+accounts, horses, training sessions, riders, and stables/groups. It does not modify
+cloud data, bypass subscription entitlements, or download route recordings.
+
+> [!IMPORTANT]
+> This independent project is unofficial and is not affiliated with, endorsed by,
+> or supported by Equilab or Equestrian Insights. The upstream API is undocumented
+> and may change without notice. Use only with an account and data you are authorised
+> to access.
+
+## Installation
+
+```sh
+python -m pip install equilab
+```
+
+## Usage
+
+```python
+import aiohttp
+
+from pyequilab import EquilabClient
+
+
+async def get_account(email: str, password: str) -> dict:
+    async with aiohttp.ClientSession() as session:
+        client = EquilabClient(session)
+        await client.async_login(email, password)
+        return await client.async_get_user()
+```
+
+Long-running applications should persist `client.refresh_token` securely. Pass an
+`on_token` callback to receive rotated refresh tokens. Callers own the supplied
+`aiohttp.ClientSession`; the library never closes it.
+
+## Supported operations
+
+- Sign in and renew authentication tokens.
+- Read the authenticated user profile.
+- Read referenced horses, training sessions, and stables/groups.
+- Read the latest notification without marking it as read.
+- Normalise the subset of domain data used by downstream applications.
+
+All public network operations are asynchronous. Exceptions contain safe generic
+messages and never include response bodies, credentials, identifiers, or request URLs.
+
+## Development
+
+```sh
+python -m pip install -e '.[test]'
+pytest --cov=pyequilab --cov-branch --cov-report=term-missing
+ruff check .
+ruff format --check .
+mypy
+```
+
+See [CONTRIBUTING.md](CONTRIBUTING.md) for the release process.
+
+## Licence
+
+Copyright © 2026 Daniel Wilson ([@Danw33](https://github.com/Danw33))
+
+Licensed under the Apache License, Version 2.0. See [LICENSE](LICENSE) and [NOTICE](NOTICE).
+
+Equilab and Equestrian Insights AB are trademarks of their respective owners.

equilab-0.1.1.dist-info/RECORD

@@ -0,0 +1,9 @@
+pyequilab/__init__.py,sha256=ZKAfYXMr_YLVgIXsDdG9YbHtEjLQ4A-VSGuguiA23R4,655
+pyequilab/api.py,sha256=uSzrFhr1f6C0wwXtoOqP6n5eTiUsqeDm7FToN7CnqbU,11873
+pyequilab/models.py,sha256=sH_3vv2BqbNCjplvY51sTAw476DuPu2SGKHdLzVm_8c,10828
+pyequilab/py.typed,sha256=AbpHGcgLb-kRsJGnwFEktk7uzpZOCcBY74-YBdrKVGs,1
+equilab-0.1.1.dist-info/METADATA,sha256=NPhDJBYKdLnBy2kvaVveoFvaYTHGYbkD7XqMxhEPlLw,3765
+equilab-0.1.1.dist-info/WHEEL,sha256=zOwg4jB6zX2kU910N-cMawjivD6tO8NEWvE12je1bVk,87
+equilab-0.1.1.dist-info/licenses/LICENSE,sha256=xx0jnfkXJvxRnG63LTGOxlggYnIysveWIZ6H3PNdCrQ,11357
+equilab-0.1.1.dist-info/licenses/NOTICE,sha256=1yLltYao5FomTx6YhYkoIK4vDqiQVJjTLpd3fM13LU4,333
+equilab-0.1.1.dist-info/RECORD,,

equilab-0.1.1.dist-info/WHEEL

@@ -0,0 +1,4 @@
+Wheel-Version: 1.0
+Generator: hatchling 1.32.0
+Root-Is-Purelib: true
+Tag: py3-none-any

equilab-0.1.1.dist-info/licenses/LICENSE

@@ -0,0 +1,201 @@
+                                 Apache License
+                           Version 2.0, January 2004
+                        http://www.apache.org/licenses/
+
+   TERMS AND CONDITIONS FOR USE, REPRODUCTION, AND DISTRIBUTION
+
+   1. Definitions.
+
+      "License" shall mean the terms and conditions for use, reproduction,
+      and distribution as defined by Sections 1 through 9 of this document.
+
+      "Licensor" shall mean the copyright owner or entity authorized by
+      the copyright owner that is granting the License.
+
+      "Legal Entity" shall mean the union of the acting entity and all
+      other entities that control, are controlled by, or are under common
+      control with that entity. For the purposes of this definition,
+      "control" means (i) the power, direct or indirect, to cause the
+      direction or management of such entity, whether by contract or
+      otherwise, or (ii) ownership of fifty percent (50%) or more of the
+      outstanding shares, or (iii) beneficial ownership of such entity.
+
+      "You" (or "Your") shall mean an individual or Legal Entity
+      exercising permissions granted by this License.
+
+      "Source" form shall mean the preferred form for making modifications,
+      including but not limited to software source code, documentation
+      source, and configuration files.
+
+      "Object" form shall mean any form resulting from mechanical
+      transformation or translation of a Source form, including but
+      not limited to compiled object code, generated documentation,
+      and conversions to other media types.
+
+      "Work" shall mean the work of authorship, whether in Source or
+      Object form, made available under the License, as indicated by a
+      copyright notice that is included in or attached to the work
+      (an example is provided in the Appendix below).
+
+      "Derivative Works" shall mean any work, whether in Source or Object
+      form, that is based on (or derived from) the Work and for which the
+      editorial revisions, annotations, elaborations, or other modifications
+      represent, as a whole, an original work of authorship. For the purposes
+      of this License, Derivative Works shall not include works that remain
+      separable from, or merely link (or bind by name) to the interfaces of,
+      the Work and Derivative Works thereof.
+
+      "Contribution" shall mean any work of authorship, including
+      the original version of the Work and any modifications or additions
+      to that Work or Derivative Works thereof, that is intentionally
+      submitted to Licensor for inclusion in the Work by the copyright owner
+      or by an individual or Legal Entity authorized to submit on behalf of
+      the copyright owner. For the purposes of this definition, "submitted"
+      means any form of electronic, verbal, or written communication sent
+      to the Licensor or its representatives, including but not limited to
+      communication on electronic mailing lists, source code control systems,
+      and issue tracking systems that are managed by, or on behalf of, the
+      Licensor for the purpose of discussing and improving the Work, but
+      excluding communication that is conspicuously marked or otherwise
+      designated in writing by the copyright owner as "Not a Contribution."
+
+      "Contributor" shall mean Licensor and any individual or Legal Entity
+      on behalf of whom a Contribution has been received by Licensor and
+      subsequently incorporated within the Work.
+
+   2. Grant of Copyright License. Subject to the terms and conditions of
+      this License, each Contributor hereby grants to You a perpetual,
+      worldwide, non-exclusive, no-charge, royalty-free, irrevocable
+      copyright license to reproduce, prepare Derivative Works of,
+      publicly display, publicly perform, sublicense, and distribute the
+      Work and such Derivative Works in Source or Object form.
+
+   3. Grant of Patent License. Subject to the terms and conditions of
+      this License, each Contributor hereby grants to You a perpetual,
+      worldwide, non-exclusive, no-charge, royalty-free, irrevocable
+      (except as stated in this section) patent license to make, have made,
+      use, offer to sell, sell, import, and otherwise transfer the Work,
+      where such license applies only to those patent claims licensable
+      by such Contributor that are necessarily infringed by their
+      Contribution(s) alone or by combination of their Contribution(s)
+      with the Work to which such Contribution(s) was submitted. If You
+      institute patent litigation against any entity (including a
+      cross-claim or counterclaim in a lawsuit) alleging that the Work
+      or a Contribution incorporated within the Work constitutes direct
+      or contributory patent infringement, then any patent licenses
+      granted to You under this License for that Work shall terminate
+      as of the date such litigation is filed.
+
+   4. Redistribution. You may reproduce and distribute copies of the
+      Work or Derivative Works thereof in any medium, with or without
+      modifications, and in Source or Object form, provided that You
+      meet the following conditions:
+
+      (a) You must give any other recipients of the Work or
+          Derivative Works a copy of this License; and
+
+      (b) You must cause any modified files to carry prominent notices
+          stating that You changed the files; and
+
+      (c) You must retain, in the Source form of any Derivative Works
+          that You distribute, all copyright, patent, trademark, and
+          attribution notices from the Source form of the Work,
+          excluding those notices that do not pertain to any part of
+          the Derivative Works; and
+
+      (d) If the Work includes a "NOTICE" text file as part of its
+          distribution, then any Derivative Works that You distribute must
+          include a readable copy of the attribution notices contained
+          within such NOTICE file, excluding those notices that do not
+          pertain to any part of the Derivative Works, in at least one
+          of the following places: within a NOTICE text file distributed
+          as part of the Derivative Works; within the Source form or
+          documentation, if provided along with the Derivative Works; or,
+          within a display generated by the Derivative Works, if and
+          wherever such third-party notices normally appear. The contents
+          of the NOTICE file are for informational purposes only and
+          do not modify the License. You may add Your own attribution
+          notices within Derivative Works that You distribute, alongside
+          or as an addendum to the NOTICE text from the Work, provided
+          that such additional attribution notices cannot be construed
+          as modifying the License.
+
+      You may add Your own copyright statement to Your modifications and
+      may provide additional or different license terms and conditions
+      for use, reproduction, or distribution of Your modifications, or
+      for any such Derivative Works as a whole, provided Your use,
+      reproduction, and distribution of the Work otherwise complies with
+      the conditions stated in this License.
+
+   5. Submission of Contributions. Unless You explicitly state otherwise,
+      any Contribution intentionally submitted for inclusion in the Work
+      by You to the Licensor shall be under the terms and conditions of
+      this License, without any additional terms or conditions.
+      Notwithstanding the above, nothing herein shall supersede or modify
+      the terms of any separate license agreement you may have executed
+      with Licensor regarding such Contributions.
+
+   6. Trademarks. This License does not grant permission to use the trade
+      names, trademarks, service marks, or product names of the Licensor,
+      except as required for reasonable and customary use in describing the
+      origin of the Work and reproducing the content of the NOTICE file.
+
+   7. Disclaimer of Warranty. Unless required by applicable law or
+      agreed to in writing, Licensor provides the Work (and each
+      Contributor provides its Contributions) on an "AS IS" BASIS,
+      WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or
+      implied, including, without limitation, any warranties or conditions
+      of TITLE, NON-INFRINGEMENT, MERCHANTABILITY, or FITNESS FOR A
+      PARTICULAR PURPOSE. You are solely responsible for determining the
+      appropriateness of using or redistributing the Work and assume any
+      risks associated with Your exercise of permissions under this License.
+
+   8. Limitation of Liability. In no event and under no legal theory,
+      whether in tort (including negligence), contract, or otherwise,
+      unless required by applicable law (such as deliberate and grossly
+      negligent acts) or agreed to in writing, shall any Contributor be
+      liable to You for damages, including any direct, indirect, special,
+      incidental, or consequential damages of any character arising as a
+      result of this License or out of the use or inability to use the
+      Work (including but not limited to damages for loss of goodwill,
+      work stoppage, computer failure or malfunction, or any and all
+      other commercial damages or losses), even if such Contributor
+      has been advised of the possibility of such damages.
+
+   9. Accepting Warranty or Additional Liability. While redistributing
+      the Work or Derivative Works thereof, You may choose to offer,
+      and charge a fee for, acceptance of support, warranty, indemnity,
+      or other liability obligations and/or rights consistent with this
+      License. However, in accepting such obligations, You may act only
+      on Your own behalf and on Your sole responsibility, not on behalf
+      of any other Contributor, and only if You agree to indemnify,
+      defend, and hold each Contributor harmless for any liability
+      incurred by, or claims asserted against, such Contributor by reason
+      of your accepting any such warranty or additional liability.
+
+   END OF TERMS AND CONDITIONS
+
+   APPENDIX: How to apply the Apache License to your work.
+
+      To apply the Apache License to your work, attach the following
+      boilerplate notice, with the fields enclosed by brackets "[]"
+      replaced with your own identifying information. (Don't include
+      the brackets!)  The text should be enclosed in the appropriate
+      comment syntax for the file format. We also recommend that a
+      file or class name and description of purpose be included on the
+      same "printed page" as the copyright notice for easier
+      identification within third-party archives.
+
+   Copyright [yyyy] [name of copyright owner]
+
+   Licensed under the Apache License, Version 2.0 (the "License");
+   you may not use this file except in compliance with the License.
+   You may obtain a copy of the License at
+
+       http://www.apache.org/licenses/LICENSE-2.0
+
+   Unless required by applicable law or agreed to in writing, software
+   distributed under the License is distributed on an "AS IS" BASIS,
+   WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
+   See the License for the specific language governing permissions and
+   limitations under the License.

equilab-0.1.1.dist-info/licenses/NOTICE

@@ -0,0 +1,8 @@
+py-equilab
+Copyright © 2026 Daniel Wilson (https://github.com/Danw33)
+
+Licensed under the Apache License, Version 2.0.
+
+Equilab and related names and marks are the property of their respective
+owners. This independent project is unofficial and is not affiliated with,
+endorsed by, or supported by Equilab or Equestrian Insights AB.

pyequilab/__init__.py

@@ -0,0 +1,39 @@
+"""Async, read-only client for the unofficial Equilab cloud API."""
+
+from .api import (
+    AccessError,
+    AuthError,
+    EquilabClient,
+    EquilabError,
+    MissingError,
+    RateLimitError,
+    active_ids,
+)
+from .models import (
+    GAITS,
+    Horse,
+    Profile,
+    Training,
+    horse_from_data,
+    number,
+    rider_from_data,
+    stable_from_data,
+)
+
+__all__ = [
+    "GAITS",
+    "AccessError",
+    "AuthError",
+    "EquilabClient",
+    "EquilabError",
+    "Horse",
+    "MissingError",
+    "Profile",
+    "RateLimitError",
+    "Training",
+    "active_ids",
+    "horse_from_data",
+    "number",
+    "rider_from_data",
+    "stable_from_data",
+]

pyequilab/api.py

@@ -0,0 +1,296 @@
+"""Small, read-only Firebase client; independent of Home Assistant.
+
+No admin credentials, entitlement changes, storage downloads or cloud writes.
+The sole POST operations authenticate and refresh authentication.
+"""
+
+from __future__ import annotations
+
+import asyncio
+import math
+import time
+from collections.abc import Callable
+from datetime import datetime
+from typing import Any, TypedDict
+from urllib.parse import quote
+
+import aiohttp
+
+PROJECT = "project-847196107745527358"
+API_KEY = "AIzaSyCRPTesSPploBVb2SMXbloWDyEkmHB1Wx8"
+AUTH_URL = f"https://identitytoolkit.googleapis.com/v1/accounts:signInWithPassword?key={API_KEY}"
+TOKEN_URL = f"https://securetoken.googleapis.com/v1/token?key={API_KEY}"
+ROOT = f"https://firestore.googleapis.com/v1/projects/{PROJECT}/databases/(default)/documents"
+
+
+class EquilabError(Exception):
+    """Safe public exception; never includes response bodies or URLs."""
+
+
+class AuthError(EquilabError):
+    """Authentication expired or rejected."""
+
+
+class AccessError(EquilabError):
+    """Document access denied."""
+
+
+class MissingError(EquilabError):
+    """Document no longer exists."""
+
+
+class RateLimitError(EquilabError):
+    """Upstream quota exceeded."""
+
+
+class RateLimitObservations(TypedDict):
+    """Non-sensitive rate-limit metadata observed from the service."""
+
+    http_429_count: int
+    headers: dict[str, str]
+
+
+def decode(value: dict[str, Any]) -> Any:
+    """Decode Firestore values, retaining timezone-aware timestamps."""
+    if "nullValue" in value:
+        return None
+    for key, converter in (
+        ("stringValue", str),
+        ("booleanValue", bool),
+        ("integerValue", int),
+        ("doubleValue", float),
+    ):
+        if key in value:
+            return converter(value[key])
+    if "timestampValue" in value:
+        return datetime.fromisoformat(value["timestampValue"].replace("Z", "+00:00"))
+    if "mapValue" in value:
+        return {k: decode(v) for k, v in value["mapValue"].get("fields", {}).items()}
+    if "arrayValue" in value:
+        return [decode(v) for v in value["arrayValue"].get("values", [])]
+    # Unsupported types are intentionally not surfaced or dereferenced.
+    return None
+
+
+def active_ids(value: Any) -> set[str]:
+    """Only explicitly active boolean index entries confer discovery."""
+    if not isinstance(value, dict):
+        return set()
+    return {k for k, v in value.items() if isinstance(k, str) and v is True}
+
+
+class EquilabClient:
+    """Use a caller-owned session, with serialized refresh and bounded reads."""
+
+    def __init__(
+        self,
+        session: aiohttp.ClientSession,
+        *,
+        uid: str = "",
+        refresh_token: str = "",
+        on_token: Callable[[str], None] | None = None,
+    ):
+        self.session = session
+        self.uid = uid
+        self.refresh_token = refresh_token
+        self.on_token = on_token
+        self._id_token = ""
+        self._expires = 0.0
+        self._refresh_lock = asyncio.Lock()
+        self._read_limit = asyncio.Semaphore(4)
+        self.rate_limit_observations: RateLimitObservations = {
+            "http_429_count": 0,
+            "headers": {},
+        }
+
+    async def _request(
+        self, method: str, url: str, *, auth: bool = False, **kwargs: Any
+    ) -> dict[str, Any]:
+        try:
+            async with self.session.request(
+                method,
+                url,
+                timeout=aiohttp.ClientTimeout(total=30),
+                allow_redirects=False,
+                **kwargs,
+            ) as response:
+                observed = {
+                    k.lower(): str(v)[:200]
+                    for k, v in response.headers.items()
+                    if k.lower()
+                    in {
+                        "retry-after",
+                        "ratelimit-limit",
+                        "ratelimit-remaining",
+                        "ratelimit-reset",
+                        "ratelimit",
+                        "ratelimit-policy",
+                        "x-ratelimit-limit",
+                        "x-ratelimit-remaining",
+                        "x-ratelimit-reset",
+                    }
+                }
+                self.rate_limit_observations["headers"].update(observed)
+                if response.status == 429:
+                    self.rate_limit_observations["http_429_count"] += 1
+                    raise RateLimitError("Cloud rate limit; try again later")
+                if response.status == 401:
+                    raise AuthError("Authentication rejected")
+                if response.status == 403:
+                    raise AccessError("Cloud access denied")
+                if response.status == 404:
+                    raise MissingError("Document not found")
+                if response.status >= 500:
+                    raise EquilabError("Cloud service unavailable")
+                if response.status == 400 and auth:
+                    body = await response.json()
+                    code = body.get("error", {}).get("message", "").split(" : ")[0]
+                    if code in {
+                        "INVALID_LOGIN_CREDENTIALS",
+                        "INVALID_PASSWORD",
+                        "EMAIL_NOT_FOUND",
+                        "USER_DISABLED",
+                        "USER_NOT_FOUND",
+                        "INVALID_REFRESH_TOKEN",
+                        "TOKEN_EXPIRED",
+                        "INVALID_EMAIL",
+                    }:
+                        raise AuthError("Authentication rejected")
+                    if code == "TOO_MANY_ATTEMPTS_TRY_LATER":
+                        raise RateLimitError("Too many authentication attempts")
+                    raise EquilabError("Authentication service rejected request")
+                if response.status != 200:
+                    raise EquilabError("Unexpected cloud response")
+                body = await response.json()
+                if not isinstance(body, dict):
+                    raise EquilabError("Invalid cloud response")
+                return body
+        except (aiohttp.ClientError, TimeoutError, ValueError, TypeError, AttributeError):
+            raise EquilabError("Could not communicate with Equilab") from None
+
+    def _tokens(self, body: dict[str, Any], *, refresh: bool) -> None:
+        uid_value = body.get("user_id" if refresh else "localId")
+        token_value = body.get("id_token" if refresh else "idToken")
+        renewal_value = body.get("refresh_token" if refresh else "refreshToken")
+        try:
+            expiry = float(body.get("expires_in" if refresh else "expiresIn", 3600))
+        except (TypeError, ValueError):
+            raise EquilabError("Invalid authentication response") from None
+        if not (
+            isinstance(uid_value, str)
+            and uid_value
+            and isinstance(token_value, str)
+            and token_value
+            and isinstance(renewal_value, str)
+            and renewal_value
+        ):
+            raise EquilabError("Incomplete authentication response")
+        if not math.isfinite(expiry) or expiry <= 0:
+            raise EquilabError("Invalid token lifetime")
+        if self.uid and self.uid != uid_value:
+            raise AuthError("Account identity changed")
+        self.uid, self._id_token = uid_value, token_value
+        self._expires = time.monotonic() + max(0, expiry - 60)
+        changed = self.refresh_token != renewal_value
+        self.refresh_token = renewal_value
+        if changed and self.on_token:
+            self.on_token(renewal_value)
+
+    async def async_login(self, email: str, password: str) -> None:
+        body = await self._request(
+            "POST",
+            AUTH_URL,
+            auth=True,
+            json={
+                "email": email.strip(),
+                "password": password,
+                "returnSecureToken": True,
+            },
+        )
+        self._tokens(body, refresh=False)
+
+    async def _async_ensure_token(self, rejected: str | None = None) -> None:
+        async with self._refresh_lock:
+            if self._id_token and time.monotonic() < self._expires:
+                if rejected is None or rejected != self._id_token:
+                    return
+            if not self.refresh_token:
+                raise AuthError("Sign in required")
+            body = await self._request(
+                "POST",
+                TOKEN_URL,
+                auth=True,
+                data={
+                    "grant_type": "refresh_token",
+                    "refresh_token": self.refresh_token,
+                },
+            )
+            self._tokens(body, refresh=True)
+
+    async def _async_document(self, collection: str, identifier: str) -> dict[str, Any]:
+        """Read one referenced document; refresh once on a rejected ID token."""
+        if not isinstance(identifier, str) or not identifier:
+            raise EquilabError("Invalid document identifier")
+        async with self._read_limit:
+            await self._async_ensure_token()
+            url = f"{ROOT}/{quote(collection, safe='')}/{quote(identifier, safe='')}"
+            for attempt in range(2):
+                token = self._id_token
+                try:
+                    body = await self._request(
+                        "GET",
+                        url,
+                        headers={
+                            "Authorization": f"Bearer {token}",
+                        },
+                    )
+                    return {k: decode(v) for k, v in body.get("fields", {}).items()}
+                except AuthError:
+                    if attempt:
+                        raise
+                    await self._async_ensure_token(rejected=token)
+                except (ValueError, TypeError, AttributeError, OverflowError):
+                    raise EquilabError("Invalid document data") from None
+            raise AuthError("Sign in required")
+
+    async def async_get_user(self, identifier: str | None = None) -> dict[str, Any]:
+        """Return a decoded user document."""
+        return await self._async_document("users", identifier or self.uid)
+
+    async def async_get_horse(self, identifier: str) -> dict[str, Any]:
+        """Return a decoded horse document."""
+        return await self._async_document("horses", identifier)
+
+    async def async_get_training(self, identifier: str) -> dict[str, Any]:
+        """Return a decoded training document."""
+        return await self._async_document("trainings", identifier)
+
+    async def async_get_stable(self, identifier: str) -> dict[str, Any]:
+        """Return a decoded stable or group document."""
+        return await self._async_document("stables", identifier)
+
+    async def async_get_latest_notification(self) -> list[dict[str, Any]]:
+        """Read only the most recent inbox item; never acknowledge it."""
+        async with self._read_limit:
+            await self._async_ensure_token()
+            url = f"{ROOT}/users/{quote(self.uid, safe='')}/notifications"
+            for attempt in range(2):
+                token = self._id_token
+                try:
+                    body = await self._request(
+                        "GET",
+                        url,
+                        params={"pageSize": "1", "orderBy": "date desc"},
+                        headers={"Authorization": f"Bearer {token}"},
+                    )
+                    return [
+                        {k: decode(v) for k, v in item.get("fields", {}).items()}
+                        for item in body.get("documents", [])
+                    ]
+                except AuthError:
+                    if attempt:
+                        raise
+                    await self._async_ensure_token(rejected=token)
+                except (ValueError, TypeError, AttributeError, OverflowError):
+                    raise EquilabError("Invalid notification data") from None
+            raise AuthError("Sign in required")

pyequilab/models.py

@@ -0,0 +1,303 @@
+"""Normalized, deliberately minimal models; no raw profiles or notes retained."""
+
+from __future__ import annotations
+
+import math
+from dataclasses import dataclass, field
+from datetime import date, datetime, timedelta
+from typing import Any, cast
+
+from .api import active_ids
+
+TYPE_NAMES: dict[str, str] = {
+    "-KgsjZPxgZP7Nsj_cXvV": "Show jumping",
+    "-KgsjZPxgZP7Nsj_cXvW": "Dressage",
+    "-KgsjZPyo4n1dAYIvVQe": "Flatwork",
+    "-KgsjZPyo4n1dAYIvVQf": "Hacking",
+    "-KgsjZPyo4n1dAYIvVQg": "Trotting training",
+    "-KgsjZPyo4n1dAYIvVQh": "Gallop training",
+    "-KgsjZPyo4n1dAYIvVQi": "Cardio",
+    "-KgsjZPzi754NLdGfZ4p": "Lungeing",
+    "-KgsjZPzi754NLdGfZ4q": "Long reining",
+    "-KgsjZPzi754NLdGfZ4r": "Walk training",
+    "-KgsjZPzi754NLdGfZ4s": "Competition",
+    "-KgsjZPzi754NLdGfZ4t": "Poles",
+    "-KgsjZPzi754NLdGfZ4u": "Eventing",
+    "-KgsjZPzi754NLdGfZ4v": "Strength",
+    "-KgsjZPzi754NLdGfZ4y": "Driving",
+    "-KgsjZPzi754NLdGfZ4x": "Suppleness",
+    "-KgsjZPzi754NLdGfZ4a": "Western riding",
+    "-KgsjZPzi754NLdGfZ4c": "Groundwork",
+    "-KgsjZPzi754NLdGfZ4i": "Cross country",
+    "-KgsjZPzi754NLdGfZ4z": "Endurance riding",
+    "-KgsjZPzi754NLdGfZ4l": "Hunting",
+    "-KgsjZPzi754NLdGfZ4m": "Reining",
+    "-KgsjZPzi754NLdGfZ4n": "Barrel racing",
+    "-KgsjZPzi754NLdGfZ4b": "Western pleasure",
+    "-KgsjZPzi754NLdGfZ4d": "Working equitation",
+    "-KgsjZPzi754NLdGfZ4e": "Polocrosse",
+    "-KgsjZPzi754NLdGfZ4g": "Polo",
+    "-KgsjZPzi754NLdGfZ5a": "Vaulting",
+    "-KgsjZPzi754NLdGfZ5b": "Cutting",
+    "-KgsjZPzi754NLdGfZ5c": "Mounted games",
+    "-KgsjZPzi754NLdGfZ5d": "Hunter jumping",
+    "-KgsjZPzi754NLdGfZ5e": "Harness racing",
+    "-KgsjZPzi754NLdGfZ5f": "Combined driving",
+    "-KgsjZPzi754NLdGfZ5g": "Icelandic horse riding",
+    "-KgsjZPzi754NLdGfZ4f": "Other",
+}
+GAITS: tuple[str, ...] = ("stand", "walk", "trot", "canter", "tolt", "unknown")
+
+
+def number(value: Any) -> float | None:
+    if isinstance(value, bool) or not isinstance(value, (int, float)):
+        return None
+    return float(value) if math.isfinite(value) and value >= 0 else None
+
+
+def text(value: Any) -> str | None:
+    return value if isinstance(value, str) and value else None
+
+
+def best_records(data: dict[str, Any]) -> dict[str, float | None]:
+    """Equilab's reported personal bests, not estimates from accessible history."""
+    records = data.get("records")
+    if not isinstance(records, list):
+        return {}
+    result: dict[str, float | None] = {}
+    for kind in ("distance", "duration", "speed"):
+        values = [
+            number(r.get("value")) for r in records if isinstance(r, dict) and r.get("type") == kind
+        ]
+        result["record_" + kind] = max((v for v in values if v is not None), default=None)
+    return result
+
+
+@dataclass(frozen=True)
+class Training:
+    id: str
+    start: datetime | None
+    kind: str | None
+    duration: float | None
+    distance: float | None
+    energy: float | None
+    gaits: dict[str, float | None] = field(default_factory=dict)
+    stats: dict[str, float | None] = field(default_factory=dict)
+    rider_id: str | None = None
+    horse_id: str | None = None
+    rider_energy: float | None = None
+
+    @classmethod
+    def parse(cls, identifier: str, data: dict[str, Any]) -> Training:
+        start = data.get("date")
+        if not isinstance(start, datetime) or start.tzinfo is None:
+            start = None
+        total = data.get("total")
+        total = total if isinstance(total, dict) else {}
+        kinds = sorted({TYPE_NAMES.get(k, "Other") for k in active_ids(data.get("trainingTypes"))})
+        gaits: dict[str, float | None] = {}
+        stats: dict[str, float | None] = {}
+        for gait in GAITS:
+            values = data.get(gait)
+            gaits[gait] = number(values.get("time")) if isinstance(values, dict) else None
+        for gait in (*GAITS, "total"):
+            values = data.get(gait)
+            if not isinstance(values, dict):
+                continue
+            for source, target, multiplier in (
+                ("pace", "speed", 1),
+                ("topSpeed", "top_speed", 1),
+                ("beat", "tempo", 60),
+                ("counter", "strides", 1),
+                ("stride", "stride_length", 1),
+                ("distance", "distance", 1),
+                ("leftTurnsDuration", "left_rein", 1),
+                ("rightTurnsDuration", "right_rein", 1),
+            ):
+                value = number(values.get(source))
+                stats[f"{gait}_{target}"] = value * multiplier if value is not None else None
+        weather = data.get("weather")
+        if isinstance(weather, dict):
+            for key in ("temperature", "apparentTemperature", "windSpeed", "humidity", "pressure"):
+                value = weather.get(key)
+                if (
+                    isinstance(value, (int, float))
+                    and not isinstance(value, bool)
+                    and math.isfinite(value)
+                ):
+                    if key == "humidity":
+                        value = value * 100 if 0 <= value <= 1 else None
+                    stats[f"weather_{key}"] = value
+        transitions = data.get("transitionData")
+        if isinstance(transitions, dict):
+            counts = [
+                number(v)
+                for row in transitions.values()
+                if isinstance(row, dict)
+                for v in row.values()
+            ]
+            stats["transitions"] = (
+                sum(cast(float, value) for value in counts)
+                if all(value is not None for value in counts)
+                else None
+            )
+        return cls(
+            identifier,
+            start,
+            ", ".join(kinds) or None,
+            number(total.get("time")),
+            number(total.get("distance")),
+            number(data.get("horseEnergyMj")),
+            gaits,
+            stats,
+            text(data.get("user")),
+            text(data.get("horse")),
+            number(data.get("riderEnergy")),
+        )
+
+    @property
+    def end(self) -> datetime | None:
+        if self.start is None or self.duration is None:
+            return None
+        try:
+            return self.start + timedelta(seconds=max(1, self.duration))
+        except OverflowError:
+            return None
+
+
+@dataclass(frozen=True)
+class Horse:
+    id: str
+    name: str
+    breed: str | None
+    birthday: str | None
+    category: str | None
+    level: str | None
+    owned: bool
+    trainings: tuple[Training, ...]
+    skipped: int = 0
+    profile: dict[str, Any] = field(default_factory=dict)
+
+    @property
+    def latest(self) -> Training | None:
+        candidates = [training for training in self.trainings if training.start is not None]
+        return max(candidates, key=lambda training: cast(datetime, training.start), default=None)
+
+    def aggregate(self, period: str, metric: str, now: datetime) -> float | int | None:
+        """Calendar periods in HA's timezone; missing data never becomes zero."""
+        start = now.replace(hour=0, minute=0, second=0, microsecond=0)
+        start = (
+            start - timedelta(days=start.weekday()) if period == "week" else start.replace(day=1)
+        )
+        if self.skipped or any(t.start is None for t in self.trainings):
+            return None
+        items = [
+            training
+            for training in self.trainings
+            if training.start is not None and start <= training.start <= now
+        ]
+        if metric == "count":
+            return len(items)
+        values = [getattr(t, metric) for t in items]
+        return sum(values) if all(v is not None for v in values) else None
+
+
+def horse_from_data(
+    identifier: str,
+    data: dict[str, Any],
+    owned: bool,
+    trainings: tuple[Training, ...],
+    skipped: int,
+) -> Horse:
+    birth = data.get("birthDate")
+    birthday = birth.date().isoformat() if isinstance(birth, datetime) else None
+    if isinstance(birth, str):
+        try:
+            birthday = date.fromisoformat(birth[:10]).isoformat()
+        except ValueError:
+            pass
+    return Horse(
+        identifier,
+        text(data.get("name")) or "Horse",
+        text(data.get("horseBreed")),
+        birthday,
+        text(data.get("category")),
+        text(data.get("level")),
+        owned,
+        trainings,
+        skipped,
+        {
+            **best_records(data),
+            "owner_id": text(data.get("ownerId")),
+            "stable_id": text(data.get("stableId")),
+            "weight": number(data.get("weight")),
+            "tack_weight": number(data.get("toolWeight")),
+            "records_count": len(data["records"])
+            if isinstance(data.get("records"), list)
+            else None,
+        },
+    )
+
+
+@dataclass(frozen=True)
+class Profile:
+    id: str
+    name: str
+    model: str
+    values: dict[str, Any]
+    trainings: tuple[Training, ...] = ()
+    skipped: int = 0
+
+    latest = Horse.latest
+    aggregate = Horse.aggregate
+
+
+def rider_from_data(
+    identifier: str,
+    data: dict[str, Any],
+    trainings: tuple[Training, ...],
+    skipped: int,
+    notifications: list[dict[str, Any]],
+) -> Profile:
+    values: dict[str, Any] = {
+        key: text(data.get(key)) for key in ("firstName", "lastName", "city", "discipline")
+    }
+    values.update(best_records(data))
+    for key in (
+        "totalTrainingCount",
+        "totalTrainingDistance",
+        "totalTrainingTime",
+        "unseenNotificationCount",
+    ):
+        values[key] = number(data.get(key))
+    for key in ("achievements", "records"):
+        values[key + "Count"] = len(data[key]) if isinstance(data.get(key), (dict, list)) else None
+    latest = max(
+        (n for n in notifications if isinstance(n.get("date"), datetime) and n["date"].tzinfo),
+        key=lambda n: n["date"],
+        default={},
+    )
+    values["lastNotification"] = latest.get("date")
+    values["lastNotificationType"] = text(latest.get("type"))
+    name = " ".join(filter(None, (values["firstName"], values["lastName"]))) or "Rider"
+    return Profile(identifier, name, "Rider", values, tuple(trainings), skipped)
+
+
+def stable_from_data(identifier: str, data: dict[str, Any]) -> Profile:
+    values: dict[str, Any] = {key: text(data.get(key)) for key in ("type", "privacy", "ownerId")}
+    values["horseCount"] = (
+        len(active_ids(data["horses"])) if isinstance(data.get("horses"), dict) else None
+    )
+    for key, maximum in (("lat", 90), ("lon", 180)):
+        value = data.get(key)
+        values[key] = (
+            value
+            if isinstance(value, (int, float))
+            and not isinstance(value, bool)
+            and math.isfinite(value)
+            and abs(value) <= maximum
+            else None
+        )
+    return Profile(
+        identifier, text(data.get("name")) or "Stable or group", "Stable / Group", values
+    )

pyequilab/py.typed

@@ -0,0 +1 @@
+