kippy-api 0.1.0__py3-none-any.whl

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/_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/_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/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"),
+        }

kippy_api/client.py

@@ -0,0 +1,19 @@
+"""Concrete API client composed of endpoint mixins."""
+
+from __future__ import annotations
+
+from .activity import ActivityEndpoint
+from .kippymap import KippyMapEndpoint
+from .pets import PetsEndpoint
+from .settings import SettingsEndpoint
+
+__all__ = ["KippyApi"]
+
+
+class KippyApi(
+    ActivityEndpoint,
+    SettingsEndpoint,
+    KippyMapEndpoint,
+    PetsEndpoint,
+):
+    """Full-featured Kippy API client used by the integration."""

kippy_api/const.py

@@ -0,0 +1,108 @@
+"""Kippy wire protocol constants."""
+
+from types import SimpleNamespace
+
+# API endpoints.
+DEFAULT_HOST = "https://prod.kippyapi.eu"
+LOGIN_PATH = "/v2/login.php"
+GET_PETS_PATH = "/v2/GetPetKippyList.php"
+KIPPYMAP_ACTION_PATH = "/v2/kippymap_action.php"
+KIPPYMAP_MODIFY_SETTINGS_PATH = "/v2/kippymap_modifyKippySettings.php"
+GET_ACTIVITY_CATEGORIES_PATH = "/v2/vita/get_activities_cat.php"
+
+# Default request headers.
+REQUEST_HEADERS: dict[str, str] = {
+    "Content-Type": "text/plain; charset=utf-8",
+    "Accept": "application/json, */*;q=0.8",
+    "User-Agent": "kippy-ha/0.1 (+aiohttp)",
+}
+
+# Default app/device configuration.
+APP_IDENTITY = "evo"
+APP_SUB_IDENTITY = "evo"
+APP_IDENTITY_EVO = "1"
+PLATFORM_DEVICE = "10"
+APP_VERSION = "2.9.9"
+TIMEZONE = 1.0
+PHONE_COUNTRY_CODE = "1"
+TOKEN_DEVICE = None
+DEVICE_NAME = "homeassistant"
+T_ID = 1
+
+# Formula group and activity identifiers.
+FORMULA_GROUP = SimpleNamespace(SUM="SUM")
+ACTIVITY_ID = SimpleNamespace(ALL=0)
+
+# Values for the API ``return`` field.
+RETURN_VALUES = SimpleNamespace(
+    SUCCESS=0,
+    SUCCESS_TRUE=True,
+    # Returned when a kippymap action is performed on a device without an
+    # active subscription.
+    SUBSCRIPTION_FAILURE=False,
+    MALFORMED_REQUEST=[4, 13],
+    AUTHORIZATION_EXPIRED=6,
+    INVALID_CREDENTIALS=108,
+)
+
+# Return codes grouped by outcome.
+RETURN_CODES_SUCCESS = {
+    RETURN_VALUES.SUCCESS,
+    RETURN_VALUES.SUCCESS_TRUE,
+}
+
+# Mapping of failure codes to human readable errors.
+RETURN_CODE_ERRORS = {
+    **{code: "Malformed request" for code in RETURN_VALUES.MALFORMED_REQUEST},
+    RETURN_VALUES.AUTHORIZATION_EXPIRED: "Authorization expired",
+    RETURN_VALUES.INVALID_CREDENTIALS: "Invalid credentials",
+    RETURN_VALUES.SUBSCRIPTION_FAILURE: "Subscription inactive",
+}
+
+RETURN_CODES_FAILURE = set(RETURN_CODE_ERRORS)
+
+# Fields to redact from logs.
+SENSITIVE_LOG_FIELDS = {
+    "app_code",
+    "app_verification_code",
+    "petID",
+    "kippy_id",
+    "login_email",
+    "login_password_hash",
+    "login_password_hash_md5",
+    "lat",
+    "lng",
+    "gps_latitude",
+    "gps_longitude",
+}
+LOGIN_SENSITIVE_FIELDS = {
+    "login_email",
+    "login_password_hash",
+    "login_password_hash_md5",
+}
+
+# Mapping of operating status codes returned by the API.
+OPERATING_STATUS = SimpleNamespace(
+    IDLE=1,
+    UNKNOWN=2,
+    LIVE=5,
+    ENERGY_SAVING=18,
+)
+
+# App action identifiers used by the API.
+APP_ACTION = SimpleNamespace(
+    TURN_LIVE_TRACKING_ON=2,
+    TURN_LIVE_TRACKING_OFF=1,
+)
+
+# Names used by the API for location technologies.
+LOCALIZATION_TECHNOLOGY_LBS = "LBS (Low accuracy)"
+LOCALIZATION_TECHNOLOGY_GPS = "GPS"
+LOCALIZATION_TECHNOLOGY_WIFI = "Wifi"
+
+# Mapping of localization technology codes returned by the API.
+LOCALIZATION_TECHNOLOGY_MAP: dict[str, str] = {
+    "1": LOCALIZATION_TECHNOLOGY_LBS,
+    "2": LOCALIZATION_TECHNOLOGY_GPS,
+    "3": LOCALIZATION_TECHNOLOGY_WIFI,
+}

kippy_api/exceptions.py

@@ -0,0 +1,29 @@
+"""Errors returned by the Kippy client."""
+
+
+class KippyError(Exception):
+    """Base error with optional HTTP and API result metadata."""
+
+    def __init__(
+        self,
+        message: str,
+        *,
+        status: int | None = None,
+        return_code: int | bool | str | None = None,
+    ) -> None:
+        """Store safe error metadata without retaining response bodies."""
+        super().__init__(message)
+        self.status = status
+        self.return_code = return_code
+
+
+class KippyAuthError(KippyError):
+    """Credentials are missing, invalid, or expired."""
+
+
+class KippyConnectionError(KippyError):
+    """A network request failed or timed out."""
+
+
+class KippyResponseError(KippyError):
+    """The server rejected the request or returned an invalid response."""

kippy_api/kippymap.py

@@ -0,0 +1,61 @@
+"""API endpoint for fetching Kippy Map location data."""
+
+from __future__ import annotations
+
+from typing import Any
+
+from ._base import BaseKippyApi
+from .const import KIPPYMAP_ACTION_PATH, LOCALIZATION_TECHNOLOGY_MAP, REQUEST_HEADERS
+
+
+class KippyMapEndpoint(BaseKippyApi):
+    """Mixin implementing the Kippy Map action endpoint."""
+
+    async def kippymap_action(
+        self,
+        kippy_id: int,
+        do_sms: bool = True,
+        app_action: int | None = None,
+        geofence_id: int | None = None,
+    ) -> dict[str, Any]:
+        """Perform a Kippy Map action for a specific device."""
+
+        payload = await self._authenticated_payload(
+            extra={
+                "kippy_id": kippy_id,
+                "do_sms": int(do_sms),
+            }
+        )
+        if app_action is not None:
+            payload["app_action"] = app_action
+        if geofence_id is not None:
+            payload["geofence_id"] = geofence_id
+
+        data = await self.post_with_refresh(
+            KIPPYMAP_ACTION_PATH, payload, REQUEST_HEADERS
+        )
+
+        response = data.get("data")
+        if not isinstance(response, dict):
+            response = dict(data)
+
+        lat = response.pop("lat", None)
+        if lat is not None:
+            response["gps_latitude"] = lat
+        lng = response.pop("lng", None)
+        if lng is not None:
+            response["gps_longitude"] = lng
+        radius = response.pop("radius", None)
+        if radius is not None:
+            response["gps_accuracy"] = radius
+        altitude = response.pop("altitude", None)
+        if altitude is not None:
+            response["gps_altitude"] = altitude
+
+        tech = response.get("localization_tecnology")
+        if tech is not None:
+            response["localization_technology"] = LOCALIZATION_TECHNOLOGY_MAP.get(
+                str(tech), str(tech)
+            )
+
+        return response

kippy_api/pets.py

@@ -0,0 +1,35 @@
+"""API endpoint dealing with pet metadata."""
+
+from __future__ import annotations
+
+from typing import Any
+
+from ._base import BaseKippyApi
+from .const import APP_SUB_IDENTITY, GET_PETS_PATH, REQUEST_HEADERS
+from .exceptions import KippyResponseError
+
+
+class PetsEndpoint(BaseKippyApi):
+    """Mixin providing access to the pet list endpoint."""
+
+    async def get_pet_kippy_list(self) -> list[dict[str, Any]]:
+        """Retrieve the list of pets associated with the account."""
+
+        payload = await self._authenticated_payload(
+            extra={"app_sub_identity": APP_SUB_IDENTITY}
+        )
+
+        data = await self.post_with_refresh(GET_PETS_PATH, payload, REQUEST_HEADERS)
+        pets = data.get("data", [])
+        if not isinstance(pets, list) or any(not isinstance(pet, dict) for pet in pets):
+            raise KippyResponseError("Pet data must be a list of objects")
+        for pet in pets:
+            if "enableGPSOnDefault" in pet and "gpsOnDefault" not in pet:
+                value = pet.pop("enableGPSOnDefault")
+                if isinstance(value, str):
+                    try:
+                        value = int(value)
+                    except ValueError:
+                        value = 1 if value.lower() in ("true", "1") else 0
+                pet["gpsOnDefault"] = int(bool(value))
+        return pets

kippy_api/settings.py

@@ -0,0 +1,34 @@
+"""API endpoint for updating tracker settings."""
+
+from __future__ import annotations
+
+from typing import Any
+
+from ._base import BaseKippyApi
+from .const import KIPPYMAP_MODIFY_SETTINGS_PATH, REQUEST_HEADERS
+
+
+class SettingsEndpoint(BaseKippyApi):
+    """Mixin implementing device settings updates."""
+
+    async def modify_kippy_settings(
+        self,
+        kippy_id: int,
+        *,
+        update_frequency: float | None = None,
+        gps_on_default: bool | None = None,
+        energy_saving_mode: bool | None = None,
+    ) -> dict[str, Any]:
+        """Modify settings for a specific device."""
+
+        payload = await self._authenticated_payload(extra={"modify_kippy_id": kippy_id})
+        if update_frequency is not None:
+            payload["update_frequency"] = float(f"{float(update_frequency):.1f}")
+        if gps_on_default is not None:
+            payload["gps_on_default"] = bool(gps_on_default)
+        if energy_saving_mode is not None:
+            payload["energy_saving_mode"] = int(energy_saving_mode)
+
+        return await self.post_with_refresh(
+            KIPPYMAP_MODIFY_SETTINGS_PATH, payload, REQUEST_HEADERS
+        )

kippy_api-0.1.0.dist-info/METADATA

@@ -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.dist-info/RECORD

@@ -0,0 +1,16 @@
+kippy_api/__init__.py,sha256=wf7fV1mgVxZoDJX2neTxbwu7_g_Xma2hGRxL9CXbdQ0,326
+kippy_api/_base.py,sha256=A32xGkgp75l7q8q2HuqKNxaHhdlyLSzwZcsCddPt_Bc,8391
+kippy_api/_utils.py,sha256=-POr9VSjGhbKV8rOPIwceY_uBixoS9iCD89yrVpSeDA,3494
+kippy_api/activity.py,sha256=B2uD0HCawsvFKKhj2aAPopnF5M19i5ELpbNgAnqPoAA,2573
+kippy_api/client.py,sha256=BT8ISYH1kFV6Mcc-Rf-GaIP3t3_9zb6kOZjfBzpCllA,435
+kippy_api/const.py,sha256=ikwXDmW7kALvFXiAYYFvSZo1mJU9V8H6FCVP5S3KMDY,2898
+kippy_api/exceptions.py,sha256=_j9UiLNpJm3bopEXfCwo5BrAxyXE2gKb9UzSEnNEfWo,783
+kippy_api/kippymap.py,sha256=ffikIJOd1K70hOCLC6IeH5dG1pN3b71M4kF6NtVuZpM,1894
+kippy_api/pets.py,sha256=7CIOtJzOpPXJ1CtVJgtSf8k9KvudNOGj5OEztQ75nj4,1339
+kippy_api/py.typed,sha256=47DEQpj8HBSa-_TImW-5JCeuQeRkm5NMpJWZG3hSuFU,0
+kippy_api/settings.py,sha256=wK30pqyTxzdlU3sPIHRdItxnbe1l_H1T_dFYKmJEocA,1154
+kippy_api-0.1.0.dist-info/licenses/LICENSE,sha256=LqqX94CPe2sqmUem3SGH6CsiKaPHLHdsk9USCg4GgpI,1070
+kippy_api-0.1.0.dist-info/METADATA,sha256=E-9QDDEHxZQfaay_nDILymR_QO4J_QVYF98q-E9Xqq4,3573
+kippy_api-0.1.0.dist-info/WHEEL,sha256=YVMoNqKzERt-wjUZwJ33xBGAwnFl-4cqbYkTtWa4itE,91
+kippy_api-0.1.0.dist-info/top_level.txt,sha256=Pg3XRpEwaf1_kbOW0cZRpqI07tqeQIpAXWX7uvwd-BY,10
+kippy_api-0.1.0.dist-info/RECORD,,

kippy_api-0.1.0.dist-info/WHEEL

@@ -0,0 +1,5 @@
+Wheel-Version: 1.0
+Generator: setuptools (84.0.0)
+Root-Is-Purelib: true
+Tag: py3-none-any
+

kippy_api-0.1.0.dist-info/licenses/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.dist-info/top_level.txt

@@ -0,0 +1 @@
+kippy_api