kippy-api 0.1.0__tar.gz

kippy_api-0.1.0/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2025 Thomas Wright
+
+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.

kippy_api-0.1.0/PKG-INFO

@@ -0,0 +1,94 @@
+Metadata-Version: 2.4
+Name: kippy-api
+Version: 0.1.0
+Summary: Asynchronous Python client for the Kippy pet tracker API
+Author: Thomas Wright
+License-Expression: MIT
+Project-URL: Source, https://github.com/ThomasHFWright/kippy-api
+Project-URL: Issues, https://github.com/ThomasHFWright/kippy-api/issues
+Requires-Python: >=3.13
+Description-Content-Type: text/markdown
+License-File: LICENSE
+Requires-Dist: aiohttp<4,>=3.11
+Dynamic: license-file
+
+# Kippy API
+
+An asynchronous Python client for Kippy pet trackers, extracted from
+[the Kippy Home Assistant integration](https://github.com/ThomasHFWright/kippy-homeassistant).
+Python 3.13 or newer is required. `aiohttp` is the only runtime dependency.
+
+## Use
+
+```python
+import asyncio
+import os
+from zoneinfo import ZoneInfo
+
+from aiohttp import ClientSession
+from kippy_api import KippyApi
+
+
+async def main():
+    async with ClientSession() as session:
+        api = await KippyApi.async_create(session)
+        await api.login(os.environ["KIPPY_EMAIL"], os.environ["KIPPY_PASSWORD"])
+        pets = await api.get_pet_kippy_list()
+        # Pass the reporting timezone explicitly; the machine timezone is ignored.
+        if pets:
+            await api.get_activity_categories(
+                pets[0]["petID"],
+                "2026-09-01",
+                "2026-09-02",
+                2,
+                1,
+                timezone=ZoneInfo("Europe/London"),
+            )
+
+
+asyncio.run(main())
+```
+
+You own the session and close it. The client never closes or replaces it. Existing
+endpoint names and dictionary results are preserved: `get_pet_kippy_list`,
+`kippymap_action`, `modify_kippy_settings`, and `get_activity_categories`.
+Use `do_sms=False` for cached map reads; device commands can change your tracker.
+
+Catch `KippyAuthError` for missing/invalid credentials or exhausted authentication
+refresh, `KippyConnectionError` for transport failures, and `KippyResponseError`
+for rejected or malformed responses. All inherit `KippyError` and expose optional
+`status` and `return_code` metadata. Requests time out after 30 seconds and only
+confirmed authentication failures receive one retry after login. Network timeouts
+never retry commands. Concurrent token expiry shares a login refresh.
+
+The client preserves known successful HTTP 401 bodies and the vendor's existing
+TLS cipher compatibility setting, with certificate and hostname checks enabled.
+It logs response status only, never account or location payloads. API result
+metadata may be vendor supplied; avoid logging whole response objects.
+
+The package has no Home Assistant imports, polling, entities, translation loading,
+or credential file handling. See [the protocol reference](https://github.com/ThomasHFWright/kippyAPIs)
+for the reverse-engineered API.
+
+## Development
+
+```sh
+uv sync --frozen --group dev
+uv run ruff check .
+uv run ruff format --check .
+uv run mypy
+uv run pytest
+uv run python -m build
+uv run twine check dist/*
+```
+
+Tests use synthetic responses and a local HTTP server; they do not require
+credentials or contact Kippy. CI also installs the built wheel into an environment
+without Home Assistant. `uv.lock` pins development tooling; the library dependency
+range remains compatible with the consuming application's aiohttp version.
+
+For development with the adjacent Home Assistant integration, install this folder
+editable in its environment. Do not release an integration dependency on `0.1.0`
+until that version is published and its installation from PyPI is verified.
+
+Original source copyright (c) 2025 Thomas Wright, MIT license.

kippy_api-0.1.0/README.md

@@ -0,0 +1,80 @@
+# Kippy API
+
+An asynchronous Python client for Kippy pet trackers, extracted from
+[the Kippy Home Assistant integration](https://github.com/ThomasHFWright/kippy-homeassistant).
+Python 3.13 or newer is required. `aiohttp` is the only runtime dependency.
+
+## Use
+
+```python
+import asyncio
+import os
+from zoneinfo import ZoneInfo
+
+from aiohttp import ClientSession
+from kippy_api import KippyApi
+
+
+async def main():
+    async with ClientSession() as session:
+        api = await KippyApi.async_create(session)
+        await api.login(os.environ["KIPPY_EMAIL"], os.environ["KIPPY_PASSWORD"])
+        pets = await api.get_pet_kippy_list()
+        # Pass the reporting timezone explicitly; the machine timezone is ignored.
+        if pets:
+            await api.get_activity_categories(
+                pets[0]["petID"],
+                "2026-09-01",
+                "2026-09-02",
+                2,
+                1,
+                timezone=ZoneInfo("Europe/London"),
+            )
+
+
+asyncio.run(main())
+```
+
+You own the session and close it. The client never closes or replaces it. Existing
+endpoint names and dictionary results are preserved: `get_pet_kippy_list`,
+`kippymap_action`, `modify_kippy_settings`, and `get_activity_categories`.
+Use `do_sms=False` for cached map reads; device commands can change your tracker.
+
+Catch `KippyAuthError` for missing/invalid credentials or exhausted authentication
+refresh, `KippyConnectionError` for transport failures, and `KippyResponseError`
+for rejected or malformed responses. All inherit `KippyError` and expose optional
+`status` and `return_code` metadata. Requests time out after 30 seconds and only
+confirmed authentication failures receive one retry after login. Network timeouts
+never retry commands. Concurrent token expiry shares a login refresh.
+
+The client preserves known successful HTTP 401 bodies and the vendor's existing
+TLS cipher compatibility setting, with certificate and hostname checks enabled.
+It logs response status only, never account or location payloads. API result
+metadata may be vendor supplied; avoid logging whole response objects.
+
+The package has no Home Assistant imports, polling, entities, translation loading,
+or credential file handling. See [the protocol reference](https://github.com/ThomasHFWright/kippyAPIs)
+for the reverse-engineered API.
+
+## Development
+
+```sh
+uv sync --frozen --group dev
+uv run ruff check .
+uv run ruff format --check .
+uv run mypy
+uv run pytest
+uv run python -m build
+uv run twine check dist/*
+```
+
+Tests use synthetic responses and a local HTTP server; they do not require
+credentials or contact Kippy. CI also installs the built wheel into an environment
+without Home Assistant. `uv.lock` pins development tooling; the library dependency
+range remains compatible with the consuming application's aiohttp version.
+
+For development with the adjacent Home Assistant integration, install this folder
+editable in its environment. Do not release an integration dependency on `0.1.0`
+until that version is published and its installation from PyPI is verified.
+
+Original source copyright (c) 2025 Thomas Wright, MIT license.

kippy_api-0.1.0/pyproject.toml

@@ -0,0 +1,41 @@
+[build-system]
+requires = ["setuptools>=77"]
+build-backend = "setuptools.build_meta"
+
+[project]
+name = "kippy-api"
+version = "0.1.0"
+description = "Asynchronous Python client for the Kippy pet tracker API"
+readme = "README.md"
+requires-python = ">=3.13"
+license = "MIT"
+license-files = ["LICENSE"]
+authors = [{name = "Thomas Wright"}]
+dependencies = ["aiohttp>=3.11,<4"]
+
+[project.urls]
+Source = "https://github.com/ThomasHFWright/kippy-api"
+Issues = "https://github.com/ThomasHFWright/kippy-api/issues"
+
+[dependency-groups]
+dev = ["pytest>=8", "pytest-asyncio>=1", "pytest-cov>=6", "ruff>=0.12", "mypy>=1.15", "build>=1.2", "twine>=6"]
+
+[tool.setuptools.package-data]
+kippy_api = ["py.typed"]
+
+[tool.pytest.ini_options]
+asyncio_mode = "auto"
+asyncio_default_fixture_loop_scope = "function"
+testpaths = ["tests"]
+addopts = "--cov=kippy_api --cov-report=term-missing --cov-fail-under=95"
+
+[tool.ruff]
+target-version = "py313"
+
+[tool.ruff.lint]
+select = ["E4", "E7", "E9", "F", "I", "UP"]
+
+[tool.mypy]
+python_version = "3.13"
+files = ["src/kippy_api"]
+check_untyped_defs = true

kippy_api-0.1.0/setup.cfg

@@ -0,0 +1,4 @@
+[egg_info]
+tag_build = 
+tag_date = 0
+

kippy_api-0.1.0/src/kippy_api/__init__.py

@@ -0,0 +1,17 @@
+"""Asynchronous client for the Kippy pet tracker API."""
+
+from .client import KippyApi
+from .exceptions import (
+    KippyAuthError,
+    KippyConnectionError,
+    KippyError,
+    KippyResponseError,
+)
+
+__all__ = [
+    "KippyApi",
+    "KippyAuthError",
+    "KippyConnectionError",
+    "KippyError",
+    "KippyResponseError",
+]

kippy_api-0.1.0/src/kippy_api/_base.py

@@ -0,0 +1,229 @@
+"""HTTP requests and authentication for the Kippy API."""
+
+from __future__ import annotations
+
+import asyncio
+import hashlib
+import json
+import logging
+import ssl
+from collections.abc import Mapping
+from typing import Any, Self
+
+from aiohttp import ClientError, ClientSession, ClientTimeout
+
+from ._utils import (
+    _decode_json,
+    _get_return_code,
+    _return_code_error,
+    _treat_401_as_success,
+)
+from .const import (
+    APP_IDENTITY,
+    APP_IDENTITY_EVO,
+    APP_VERSION,
+    DEFAULT_HOST,
+    DEVICE_NAME,
+    LOGIN_PATH,
+    PHONE_COUNTRY_CODE,
+    PLATFORM_DEVICE,
+    REQUEST_HEADERS,
+    RETURN_VALUES,
+    TIMEZONE,
+    TOKEN_DEVICE,
+)
+from .exceptions import KippyAuthError, KippyConnectionError, KippyResponseError
+
+_LOGGER = logging.getLogger(__name__)
+_REQUEST_TIMEOUT = ClientTimeout(total=30)
+
+
+class BaseKippyApi:
+    """API wrapper using a session owned and closed by the caller."""
+
+    def __init__(
+        self,
+        session: ClientSession,
+        host: str = DEFAULT_HOST,
+        ssl_context: ssl.SSLContext | None = None,
+    ) -> None:
+        """Initialize the API client without creating network resources."""
+        self._session = session
+        self._host = host.rstrip("/")
+        self._auth: dict[str, Any] | None = None
+        self._credentials: tuple[str, str] | None = None
+        self._ssl_context = ssl_context
+        self._login_lock = asyncio.Lock()
+
+    @classmethod
+    async def async_create(
+        cls, session: ClientSession, host: str = DEFAULT_HOST
+    ) -> Self:
+        """Create a client retaining the original endpoint TLS compatibility."""
+        ctx = await asyncio.to_thread(ssl.create_default_context)
+        # Keep certificate/hostname verification; retain the existing cipher policy
+        # until the vendor endpoint can be validated without this workaround.
+        ctx.set_ciphers("DEFAULT@SECLEVEL=1")
+        if hasattr(ssl, "OP_LEGACY_SERVER_CONNECT"):
+            ctx.options |= ssl.OP_LEGACY_SERVER_CONNECT
+        return cls(session, host, ctx)
+
+    @property
+    def session(self) -> ClientSession:
+        """Return the session owned by the caller."""
+        return self._session
+
+    @property
+    def app_code(self) -> str | None:
+        """Return the cached app code."""
+        return self._auth.get("app_code") if self._auth else None
+
+    @property
+    def app_verification_code(self) -> str | None:
+        """Return the cached app verification code."""
+        return self._auth.get("app_verification_code") if self._auth else None
+
+    async def login(
+        self, email: str, password: str, force: bool = False
+    ) -> dict[str, Any]:
+        """Authenticate and cache tokens, serializing concurrent logins."""
+        async with self._login_lock:
+            if not force and self._auth is not None:
+                return self._auth
+            self._auth = None
+            data = await self._post(
+                LOGIN_PATH,
+                {
+                    "login_email": email,
+                    "login_password_hash": hashlib.sha256(
+                        password.encode()
+                    ).hexdigest(),
+                    "login_password_hash_md5": hashlib.md5(
+                        password.encode()
+                    ).hexdigest(),
+                    "app_identity": APP_IDENTITY,
+                    "app_identity_evo": APP_IDENTITY_EVO,
+                    "platform_device": PLATFORM_DEVICE,
+                    "app_version": APP_VERSION,
+                    "timezone": TIMEZONE,
+                    "phone_country_code": PHONE_COUNTRY_CODE,
+                    "token_device": TOKEN_DEVICE,
+                    "device_name": DEVICE_NAME,
+                },
+                REQUEST_HEADERS,
+            )
+            if not all(data.get(key) for key in ("app_code", "app_verification_code")):
+                raise KippyResponseError(
+                    "Login response is missing authentication tokens"
+                )
+            self._auth = data
+            self._credentials = (email, password)
+            return data
+
+    async def ensure_login(self) -> None:
+        """Authenticate if cached tokens are unavailable."""
+        if self._auth is not None:
+            return
+        if self._credentials is None:
+            raise KippyAuthError("No credentials available")
+        await self.login(*self._credentials)
+
+    def cache_authentication(
+        self, auth: Mapping[str, Any], *, credentials: tuple[str, str] | None = None
+    ) -> None:
+        """Seed authentication for callers restoring a cached session."""
+        self._auth = dict(auth)
+        if credentials is not None:
+            self._credentials = credentials
+
+    async def _authenticated_payload(
+        self,
+        *,
+        identity: str | None = APP_IDENTITY,
+        extra: Mapping[str, Any] | None = None,
+    ) -> dict[str, Any]:
+        """Build an endpoint payload using cached authentication."""
+        await self.ensure_login()
+        if not self.app_code or not self.app_verification_code:
+            raise KippyAuthError("No authentication tokens available")
+        payload = {
+            "app_code": self.app_code,
+            "app_verification_code": self.app_verification_code,
+        }
+        if identity is not None:
+            payload["app_identity"] = identity
+        if extra:
+            payload.update(extra)
+        return payload
+
+    async def _post(
+        self, path: str, payload: dict[str, Any], headers: dict[str, str]
+    ) -> dict[str, Any]:
+        """Send one bounded request and classify errors without logging payloads."""
+        try:
+            async with self._session.post(
+                f"{self._host}{path}",
+                data=json.dumps(payload),
+                headers=headers,
+                ssl=self._ssl_context or True,
+                timeout=_REQUEST_TIMEOUT,
+                allow_redirects=False,
+                raise_for_status=False,
+            ) as response:
+                text = await response.text()
+                status = response.status
+        except (ClientError, TimeoutError) as err:
+            raise KippyConnectionError("Request failed or timed out") from err
+
+        _LOGGER.debug("API response status=%s", status)
+        data = _decode_json(text)
+        code = _get_return_code(data)
+        success = data is not None and _treat_401_as_success(path, data)
+        if status == 401 and success and data is not None:
+            return data
+        # Explicit non-authentication result codes take precedence over the
+        # vendor's unreliable HTTP 401 status (e.g. inactive subscriptions).
+        auth_error = code in (
+            RETURN_VALUES.AUTHORIZATION_EXPIRED,
+            RETURN_VALUES.INVALID_CREDENTIALS,
+        )
+        if (200 <= status < 300 or status in (401, 403)) and (
+            (status in (401, 403) and code is None)
+            or auth_error
+            or (path == LOGIN_PATH and code is False)
+        ):
+            raise KippyAuthError(
+                "Authentication failed", status=status, return_code=code
+            )
+        if not 200 <= status < 300:
+            raise KippyResponseError(
+                "Server rejected request", status=status, return_code=code
+            )
+        if data is None:
+            raise KippyResponseError("Response is not a JSON object", status=status)
+        if not success:
+            raise KippyResponseError(
+                _return_code_error(code), status=status, return_code=code
+            )
+        return data
+
+    async def post_with_refresh(
+        self, path: str, payload: dict[str, Any], headers: dict[str, str]
+    ) -> dict[str, Any]:
+        """Retry once only after a confirmed authentication failure."""
+        auth = self._auth
+        try:
+            return await self._post(path, payload, headers)
+        except KippyAuthError:
+            if self._credentials is None:
+                raise
+            # Invalidate only the tokens used by this request. Concurrent expired
+            # requests share the login lock and reuse the first refreshed session.
+            if self._auth is auth:
+                self._auth = None
+            await self.ensure_login()
+        payload.update(
+            app_code=self.app_code,
+            app_verification_code=self.app_verification_code,
+        )
+        return await self._post(path, payload, headers)

kippy_api-0.1.0/src/kippy_api/_utils.py

@@ -0,0 +1,116 @@
+"""Utility helpers shared across Kippy API modules."""
+
+from __future__ import annotations
+
+import json
+from datetime import datetime, timedelta
+from typing import Any, cast
+
+from .const import RETURN_CODE_ERRORS, RETURN_CODES_SUCCESS, SENSITIVE_LOG_FIELDS
+
+
+def _redact_tree(data: Any, sensitive: set[str]) -> Any:
+    """Recursively redact sensitive fields within ``data``."""
+
+    if isinstance(data, dict):
+        return {
+            key: ("***" if key in sensitive else _redact_tree(value, sensitive))
+            for key, value in data.items()
+        }
+    if isinstance(data, list):
+        return [_redact_tree(item, sensitive) for item in data]
+    return data
+
+
+def _redact(data: dict[str, Any], extra: set[str] | None = None) -> dict[str, Any]:
+    """Return a copy of ``data`` with sensitive fields redacted."""
+
+    sensitive = SENSITIVE_LOG_FIELDS | (extra or set())
+    return cast(dict[str, Any], _redact_tree(data, sensitive))
+
+
+def _redact_json(text: str) -> str:
+    """Redact sensitive fields from JSON ``text`` if possible."""
+
+    try:
+        data = json.loads(text)
+    except json.JSONDecodeError:
+        return "<non-JSON response>"
+    return json.dumps(_redact_tree(data, SENSITIVE_LOG_FIELDS))
+
+
+def _decode_json(text: str) -> dict[str, Any] | None:
+    """Decode ``text`` as JSON, returning ``None`` on failure."""
+
+    try:
+        data = json.loads(text)
+        return data if isinstance(data, dict) else None
+    except json.JSONDecodeError:
+        return None
+
+
+def _get_return_code(data: dict[str, Any] | None) -> int | bool | str | None:
+    """Extract the API ``return`` code from ``data`` if present."""
+
+    if not isinstance(data, dict):
+        return None
+    if (code := data.get("return")) is None:
+        code = data.get("Result")
+    if code is None:
+        return None
+    if isinstance(code, bool):
+        return code
+    if isinstance(code, int):
+        return code
+    if isinstance(code, str):
+        try:
+            return int(code)
+        except ValueError:
+            return code
+    return None
+
+
+def _return_code_error(code: Any) -> str:
+    """Return a human readable error for ``code``.
+
+    If ``code`` is unknown, include the code in the message.
+    """
+
+    if not isinstance(code, (int, str, bool)):
+        return "Missing or invalid API return code"
+    if (msg := RETURN_CODE_ERRORS.get(code)) is not None:
+        return f"{msg} (code {code})"
+    return (
+        f"Unknown error code {code}"
+        if isinstance(code, int)
+        else "Unknown API return code"
+    )
+
+
+def _treat_401_as_success(path: str, data: dict[str, Any]) -> bool:
+    """Determine if a 401 response should be treated as a success."""
+
+    return_code = _get_return_code(data)
+    if isinstance(return_code, bool):
+        return return_code
+    return return_code in RETURN_CODES_SUCCESS
+
+
+def _weeks_param(start: datetime, end: datetime) -> str:
+    """Return a JSON list of ISO weeks between ``start`` and ``end``."""
+
+    weeks_list: list[dict[str, str]] = []
+    current = start - timedelta(days=start.weekday())
+    while current <= end:
+        year, week, _ = current.isocalendar()
+        entry = {"year": str(year), "number": str(week)}
+        weeks_list.append(entry)
+        current += timedelta(days=7)
+    return json.dumps(weeks_list)
+
+
+def _tz_hours(dt: datetime) -> float:
+    """Return timezone offset in hours for ``dt``."""
+
+    tz_offset = dt.utcoffset() or timedelta()
+    return tz_offset.total_seconds() / 3600

kippy_api-0.1.0/src/kippy_api/activity.py

@@ -0,0 +1,83 @@
+"""API endpoint for retrieving activity statistics."""
+
+from __future__ import annotations
+
+from datetime import datetime, tzinfo
+from typing import Any
+
+from ._base import BaseKippyApi
+from ._utils import _tz_hours, _weeks_param
+from .const import (
+    ACTIVITY_ID,
+    FORMULA_GROUP,
+    GET_ACTIVITY_CATEGORIES_PATH,
+    REQUEST_HEADERS,
+    T_ID,
+)
+from .exceptions import KippyResponseError
+
+
+class ActivityEndpoint(BaseKippyApi):
+    """Mixin implementing the activity category endpoint."""
+
+    async def get_activity_categories(
+        self,
+        pet_id: int | str,
+        from_date: str,
+        to_date: str,
+        time_division: int,
+        _weeks: int,
+        *,
+        timezone: tzinfo,
+    ) -> dict[str, Any]:
+        """Retrieve activity categories for a pet."""
+
+        start = datetime.strptime(from_date, "%Y-%m-%d")
+        end = datetime.strptime(to_date, "%Y-%m-%d")
+
+        if not isinstance(timezone, tzinfo):
+            raise ValueError("timezone must be a tzinfo instance")
+        if end < start:
+            raise ValueError("to_date must not precede from_date")
+        start_ts = int(start.replace(tzinfo=timezone).timestamp())
+        end_ts = int(end.replace(tzinfo=timezone).timestamp())
+
+        tz_hours_value = _tz_hours(start.replace(tzinfo=timezone))
+        weeks_value = _weeks_param(start, end)
+
+        time_divisions = {1: "h", 2: "d", 3: "w"}.get(time_division, "h")
+
+        payload = await self._authenticated_payload(
+            extra={
+                "petID": pet_id,
+                "activityID": ACTIVITY_ID.ALL,
+                "fromDate": start_ts,
+                "toDate": end_ts,
+                "timeDivisions": time_divisions,
+                "formulaGroup": FORMULA_GROUP.SUM,
+                "tID": T_ID,
+                "timezone": tz_hours_value,
+                "weeks": weeks_value,
+            }
+        )
+
+        data = await self.post_with_refresh(
+            GET_ACTIVITY_CATEGORIES_PATH, payload, REQUEST_HEADERS
+        )
+
+        if "data" in data:
+            payload = data.get("data") or {}
+            if not isinstance(payload, dict):
+                raise KippyResponseError("Activity data must be an object")
+        else:
+            payload = {
+                "activities": data.get("ActivitiesData"),
+                "avg": data.get("AVGData"),
+                "health": data.get("HealthData"),
+            }
+
+        return {
+            "activities": payload.get("activities"),
+            "avg": payload.get("avg"),
+            "health": payload.get("health"),
+        }