kerblwelt-api 0.1.0__py3-none-any.whl

kerblwelt_api/__init__.py

@@ -0,0 +1,47 @@
+"""Python API client for Kerbl Welt IoT platform."""
+
+from .client import KerblweltClient
+from .const import __version__
+from .exceptions import (
+    APIError,
+    AuthenticationError,
+    ConnectionError,
+    DeviceNotFoundError,
+    InvalidCredentialsError,
+    KerblweltError,
+    RateLimitError,
+    TokenExpiredError,
+    TokenRefreshError,
+    ValidationError,
+)
+from .models import (
+    AuthResponse,
+    DeviceEventCount,
+    DeviceType,
+    SmartSatelliteDevice,
+    User,
+)
+
+__all__ = [
+    # Client
+    "KerblweltClient",
+    # Exceptions
+    "KerblweltError",
+    "AuthenticationError",
+    "InvalidCredentialsError",
+    "TokenExpiredError",
+    "TokenRefreshError",
+    "APIError",
+    "ConnectionError",
+    "DeviceNotFoundError",
+    "RateLimitError",
+    "ValidationError",
+    # Models
+    "AuthResponse",
+    "User",
+    "DeviceType",
+    "SmartSatelliteDevice",
+    "DeviceEventCount",
+    # Version
+    "__version__",
+]

kerblwelt_api/auth.py

@@ -0,0 +1,191 @@
+"""Authentication module for Kerbl Welt API."""
+
+import logging
+from typing import Any
+
+import aiohttp
+
+from .const import (
+    BASE_URL,
+    CONTENT_TYPE_JSON,
+    ENDPOINT_AUTH_REFRESH,
+    ENDPOINT_AUTH_SIGN_IN,
+    HEADER_AUTHORIZATION,
+    HEADER_CONTENT_TYPE,
+)
+from .exceptions import (
+    AuthenticationError,
+    InvalidCredentialsError,
+    TokenExpiredError,
+    TokenRefreshError,
+)
+from .models import AuthResponse
+
+_LOGGER = logging.getLogger(__name__)
+
+
+class AuthManager:
+    """Manages authentication with Kerbl Welt API."""
+
+    def __init__(self, session: aiohttp.ClientSession) -> None:
+        """Initialize authentication manager.
+
+        Args:
+            session: aiohttp client session
+        """
+        self._session = session
+        self._access_token: str | None = None
+        self._refresh_token: str | None = None
+
+    @property
+    def access_token(self) -> str | None:
+        """Get current access token.
+
+        Returns:
+            Access token or None if not authenticated
+        """
+        return self._access_token
+
+    @property
+    def refresh_token(self) -> str | None:
+        """Get current refresh token.
+
+        Returns:
+            Refresh token or None if not authenticated
+        """
+        return self._refresh_token
+
+    @property
+    def is_authenticated(self) -> bool:
+        """Check if currently authenticated.
+
+        Returns:
+            True if access token is available
+        """
+        return self._access_token is not None
+
+    def get_auth_headers(self) -> dict[str, str]:
+        """Get authentication headers for API requests.
+
+        Returns:
+            Dictionary with Authorization header
+
+        Raises:
+            AuthenticationError: If not authenticated
+        """
+        if not self._access_token:
+            raise AuthenticationError("Not authenticated - access token not available")
+
+        return {HEADER_AUTHORIZATION: f"Bearer {self._access_token}"}
+
+    async def authenticate(self, email: str, password: str) -> AuthResponse:
+        """Authenticate with email and password.
+
+        Args:
+            email: User email address
+            password: User password
+
+        Returns:
+            AuthResponse containing access and refresh tokens
+
+        Raises:
+            InvalidCredentialsError: If credentials are invalid
+            AuthenticationError: If authentication fails for other reasons
+        """
+        url = f"{BASE_URL}{ENDPOINT_AUTH_SIGN_IN}"
+        payload = {"email": email, "password": password}
+        headers = {HEADER_CONTENT_TYPE: CONTENT_TYPE_JSON}
+
+        _LOGGER.debug("Authenticating user: %s", email)
+
+        try:
+            async with self._session.post(url, json=payload, headers=headers) as response:
+                if response.status == 201:
+                    data = await response.json()
+                    self._access_token = data["accessToken"]
+                    self._refresh_token = data["refreshToken"]
+
+                    _LOGGER.info("Authentication successful for user: %s", email)
+
+                    return AuthResponse(
+                        access_token=self._access_token,
+                        refresh_token=self._refresh_token,
+                    )
+                elif response.status == 401:
+                    _LOGGER.error("Invalid credentials for user: %s", email)
+                    raise InvalidCredentialsError("Invalid email or password")
+                else:
+                    error_text = await response.text()
+                    _LOGGER.error(
+                        "Authentication failed with status %d: %s", response.status, error_text
+                    )
+                    raise AuthenticationError(f"Authentication failed: {error_text}")
+
+        except aiohttp.ClientError as err:
+            _LOGGER.error("Network error during authentication: %s", err)
+            raise AuthenticationError(f"Network error during authentication: {err}") from err
+
+    async def refresh_access_token(self) -> AuthResponse:
+        """Refresh access token using refresh token.
+
+        Returns:
+            AuthResponse with new access and refresh tokens
+
+        Raises:
+            TokenRefreshError: If token refresh fails
+            AuthenticationError: If no refresh token is available
+        """
+        if not self._refresh_token:
+            raise AuthenticationError("No refresh token available")
+
+        url = f"{BASE_URL}{ENDPOINT_AUTH_REFRESH}"
+        payload = {"refreshToken": self._refresh_token}
+        headers = {HEADER_CONTENT_TYPE: CONTENT_TYPE_JSON}
+
+        _LOGGER.debug("Refreshing access token")
+
+        try:
+            async with self._session.post(url, json=payload, headers=headers) as response:
+                if response.status == 201:
+                    data = await response.json()
+                    self._access_token = data["accessToken"]
+                    self._refresh_token = data["refreshToken"]
+
+                    _LOGGER.info("Token refresh successful")
+
+                    return AuthResponse(
+                        access_token=self._access_token,
+                        refresh_token=self._refresh_token,
+                    )
+                elif response.status == 401:
+                    _LOGGER.error("Refresh token expired or invalid")
+                    self._access_token = None
+                    self._refresh_token = None
+                    raise TokenExpiredError("Refresh token expired - re-authentication required")
+                else:
+                    error_text = await response.text()
+                    _LOGGER.error("Token refresh failed with status %d: %s", response.status, error_text)
+                    raise TokenRefreshError(f"Token refresh failed: {error_text}")
+
+        except aiohttp.ClientError as err:
+            _LOGGER.error("Network error during token refresh: %s", err)
+            raise TokenRefreshError(f"Network error during token refresh: {err}") from err
+
+    def set_tokens(self, access_token: str, refresh_token: str) -> None:
+        """Manually set authentication tokens.
+
+        Useful for restoring a previous session.
+
+        Args:
+            access_token: Access token
+            refresh_token: Refresh token
+        """
+        self._access_token = access_token
+        self._refresh_token = refresh_token
+        _LOGGER.debug("Tokens set manually")
+
+    def clear_tokens(self) -> None:
+        """Clear stored authentication tokens."""
+        self._access_token = None
+        self._refresh_token = None
+        _LOGGER.debug("Tokens cleared")

kerblwelt_api/client.py

@@ -0,0 +1,272 @@
+"""Main API client for Kerbl Welt."""
+
+import logging
+from typing import Any
+
+import aiohttp
+
+from .auth import AuthManager
+from .const import (
+    BASE_URL,
+    DEFAULT_CONNECT_TIMEOUT,
+    DEFAULT_TIMEOUT,
+    DEVICE_TYPE_SMART_SATELLITE,
+    ENDPOINT_DEVICES,
+    ENDPOINT_EVENT_COUNT,
+    ENDPOINT_USER,
+)
+from .exceptions import APIError, ConnectionError, DeviceNotFoundError
+from .models import DeviceEventCount, SmartSatelliteDevice, User
+
+_LOGGER = logging.getLogger(__name__)
+
+
+class KerblweltClient:
+    """Client for interacting with Kerbl Welt API."""
+
+    def __init__(
+        self,
+        session: aiohttp.ClientSession | None = None,
+        timeout: int = DEFAULT_TIMEOUT,
+    ) -> None:
+        """Initialize Kerbl Welt API client.
+
+        Args:
+            session: Optional aiohttp client session. If not provided, one will be created.
+            timeout: Request timeout in seconds
+        """
+        self._session = session
+        self._own_session = session is None
+        self._timeout = timeout
+        self._auth: AuthManager | None = None
+
+    async def __aenter__(self) -> "KerblweltClient":
+        """Async context manager entry."""
+        if self._own_session:
+            timeout = aiohttp.ClientTimeout(
+                total=self._timeout,
+                connect=DEFAULT_CONNECT_TIMEOUT,
+            )
+            self._session = aiohttp.ClientSession(timeout=timeout)
+
+        self._auth = AuthManager(self._session)  # type: ignore
+        return self
+
+    async def __aexit__(self, *args: Any) -> None:
+        """Async context manager exit."""
+        await self.close()
+
+    async def close(self) -> None:
+        """Close the client session."""
+        if self._own_session and self._session:
+            await self._session.close()
+            self._session = None
+
+    @property
+    def is_authenticated(self) -> bool:
+        """Check if client is authenticated.
+
+        Returns:
+            True if authenticated, False otherwise
+        """
+        return self._auth is not None and self._auth.is_authenticated
+
+    async def authenticate(self, email: str, password: str) -> None:
+        """Authenticate with Kerbl Welt API.
+
+        Args:
+            email: User email address
+            password: User password
+
+        Raises:
+            InvalidCredentialsError: If credentials are invalid
+            AuthenticationError: If authentication fails
+        """
+        if not self._auth:
+            raise RuntimeError("Client not initialized - use async context manager")
+
+        await self._auth.authenticate(email, password)
+
+    def set_tokens(self, access_token: str, refresh_token: str) -> None:
+        """Set authentication tokens manually.
+
+        Useful for restoring a previous session.
+
+        Args:
+            access_token: Access token
+            refresh_token: Refresh token
+        """
+        if not self._auth:
+            raise RuntimeError("Client not initialized - use async context manager")
+
+        self._auth.set_tokens(access_token, refresh_token)
+
+    async def refresh_token(self) -> None:
+        """Refresh the access token.
+
+        Raises:
+            TokenRefreshError: If token refresh fails
+        """
+        if not self._auth:
+            raise RuntimeError("Client not initialized - use async context manager")
+
+        await self._auth.refresh_access_token()
+
+    async def _request(
+        self,
+        method: str,
+        endpoint: str,
+        **kwargs: Any,
+    ) -> dict[str, Any]:
+        """Make an authenticated API request.
+
+        Args:
+            method: HTTP method (GET, POST, etc.)
+            endpoint: API endpoint path
+            **kwargs: Additional arguments for aiohttp request
+
+        Returns:
+            Response JSON data
+
+        Raises:
+            APIError: If API request fails
+            ConnectionError: If connection fails
+        """
+        if not self._session:
+            raise RuntimeError("Client not initialized - use async context manager")
+
+        if not self._auth or not self._auth.is_authenticated:
+            raise RuntimeError("Not authenticated - call authenticate() first")
+
+        url = f"{BASE_URL}{endpoint}"
+        headers = kwargs.pop("headers", {})
+        headers.update(self._auth.get_auth_headers())
+
+        _LOGGER.debug("Making %s request to %s", method, endpoint)
+
+        try:
+            async with self._session.request(method, url, headers=headers, **kwargs) as response:
+                if response.status == 200:
+                    return await response.json()
+                elif response.status == 201:
+                    return await response.json()
+                elif response.status == 401:
+                    error_text = await response.text()
+                    _LOGGER.error("Unauthorized request to %s: %s", endpoint, error_text)
+                    raise APIError(f"Unauthorized: {error_text}", status_code=401)
+                elif response.status == 404:
+                    error_text = await response.text()
+                    _LOGGER.error("Not found: %s - %s", endpoint, error_text)
+                    raise APIError(f"Not found: {error_text}", status_code=404)
+                elif response.status == 429:
+                    error_text = await response.text()
+                    _LOGGER.error("Rate limited: %s", error_text)
+                    raise APIError(f"Rate limited: {error_text}", status_code=429)
+                else:
+                    error_text = await response.text()
+                    _LOGGER.error(
+                        "API request failed with status %d: %s", response.status, error_text
+                    )
+                    raise APIError(
+                        f"API request failed: {error_text}", status_code=response.status
+                    )
+
+        except aiohttp.ClientError as err:
+            _LOGGER.error("Connection error during request to %s: %s", endpoint, err)
+            raise ConnectionError(f"Connection error: {err}") from err
+
+    async def get_user(self) -> User:
+        """Get current user information.
+
+        Returns:
+            User object with account information
+
+        Raises:
+            APIError: If API request fails
+        """
+        _LOGGER.debug("Fetching user information")
+        data = await self._request("GET", ENDPOINT_USER)
+        return User.from_dict(data)
+
+    async def get_devices(self) -> list[SmartSatelliteDevice]:
+        """Get all Smart Satellite devices for the authenticated user.
+
+        Returns:
+            List of SmartSatelliteDevice objects
+
+        Raises:
+            APIError: If API request fails
+        """
+        _LOGGER.debug("Fetching devices")
+        data = await self._request("GET", ENDPOINT_DEVICES)
+
+        # Parse Smart Satellite devices
+        devices = []
+        for device_data in data.get("smartSatellite", []):
+            devices.append(SmartSatelliteDevice.from_dict(device_data))
+
+        _LOGGER.info("Found %d Smart Satellite device(s)", len(devices))
+        return devices
+
+    async def get_device(self, device_id: str) -> SmartSatelliteDevice:
+        """Get a specific Smart Satellite device by ID.
+
+        Args:
+            device_id: Device UUID
+
+        Returns:
+            SmartSatelliteDevice object
+
+        Raises:
+            DeviceNotFoundError: If device is not found
+            APIError: If API request fails
+        """
+        devices = await self.get_devices()
+
+        for device in devices:
+            if device.id == device_id:
+                return device
+
+        raise DeviceNotFoundError(device_id)
+
+    async def get_device_event_count(self, device_id: str) -> DeviceEventCount:
+        """Get event count for a Smart Satellite device.
+
+        Args:
+            device_id: Device UUID
+
+        Returns:
+            DeviceEventCount object
+
+        Raises:
+            APIError: If API request fails
+        """
+        endpoint = ENDPOINT_EVENT_COUNT.format(
+            device_type=DEVICE_TYPE_SMART_SATELLITE,
+            device_id=device_id,
+        )
+
+        _LOGGER.debug("Fetching event count for device %s", device_id)
+        data = await self._request("GET", endpoint)
+        return DeviceEventCount.from_dict(data)
+
+    async def get_all_device_data(self) -> dict[str, tuple[SmartSatelliteDevice, DeviceEventCount]]:
+        """Get all devices with their event counts.
+
+        Useful for efficient bulk fetching.
+
+        Returns:
+            Dictionary mapping device ID to tuple of (device, event_count)
+
+        Raises:
+            APIError: If API request fails
+        """
+        devices = await self.get_devices()
+        result = {}
+
+        for device in devices:
+            event_count = await self.get_device_event_count(device.id)
+            result[device.id] = (device, event_count)
+
+        _LOGGER.info("Fetched data for %d device(s)", len(result))
+        return result

kerblwelt_api/const.py

@@ -0,0 +1,46 @@
+"""Constants for Kerbl Welt API."""
+
+# API Configuration
+BASE_URL = "https://backend.kerbl-iot.com/api/v0.1"
+WEBSOCKET_URL = "wss://backend.kerbl-iot.com/ws/v0.1/socket.io/"
+
+# API Endpoints
+ENDPOINT_AUTH_SIGN_IN = "/auth/sign-in"
+ENDPOINT_AUTH_REFRESH = "/auth/refresh"
+ENDPOINT_USER = "/user"
+ENDPOINT_DEVICES = "/device"
+ENDPOINT_EVENT_COUNT = "/device/event-count/{device_type}/{device_id}"
+ENDPOINT_ADMIN_MESSAGE = "/admin-message/for-user"
+ENDPOINT_MAINTENANCE_PING = "/maintenance/ping"
+ENDPOINT_MAINTENANCE_BRANCH = "/maintenance/deployed_branch"
+
+# Device Types
+DEVICE_TYPE_SMART_SATELLITE = "smart-satellite"
+DEVICE_TYPE_SMART_COOP = "smart-coop"
+DEVICE_TYPE_SMART_ENERGIZER = "smart-energizer"
+DEVICE_TYPE_SMART_MOUSE_TRAP = "smart-mouse-trap"
+DEVICE_TYPE_SMART_LIGHT = "smart-light"
+DEVICE_TYPE_SMART_WEATHER = "smart-weather"
+DEVICE_TYPE_SMART_TRACKER = "smart-tracker"
+DEVICE_TYPE_SMART_SOS = "smart-sos"
+DEVICE_TYPE_SMART_CHICKEN_DOOR = "smart-chicken-door"
+DEVICE_TYPE_SMART_ADS = "smart-ads"
+
+# HTTP Headers
+HEADER_AUTHORIZATION = "Authorization"
+HEADER_CONTENT_TYPE = "Content-Type"
+HEADER_ACCEPT = "Accept"
+
+# Content Types
+CONTENT_TYPE_JSON = "application/json"
+
+# Default Timeouts (seconds)
+DEFAULT_TIMEOUT = 30
+DEFAULT_CONNECT_TIMEOUT = 10
+
+# Token Expiration (approximate, in seconds)
+ACCESS_TOKEN_EXPIRY = 15 * 24 * 60 * 60  # ~15 days
+REFRESH_TOKEN_EXPIRY = 40 * 24 * 60 * 60  # ~40 days
+
+# Version
+__version__ = "0.1.0"

kerblwelt_api/exceptions.py

@@ -0,0 +1,76 @@
+"""Exceptions for Kerbl Welt API."""
+
+
+class KerblweltError(Exception):
+    """Base exception for Kerbl Welt API errors."""
+
+    pass
+
+
+class AuthenticationError(KerblweltError):
+    """Raised when authentication fails."""
+
+    pass
+
+
+class InvalidCredentialsError(AuthenticationError):
+    """Raised when login credentials are invalid."""
+
+    pass
+
+
+class TokenExpiredError(AuthenticationError):
+    """Raised when access token has expired."""
+
+    pass
+
+
+class TokenRefreshError(AuthenticationError):
+    """Raised when token refresh fails."""
+
+    pass
+
+
+class APIError(KerblweltError):
+    """Raised when API request fails."""
+
+    def __init__(self, message: str, status_code: int | None = None) -> None:
+        """Initialize API error.
+
+        Args:
+            message: Error message
+            status_code: HTTP status code if available
+        """
+        super().__init__(message)
+        self.status_code = status_code
+
+
+class ConnectionError(KerblweltError):
+    """Raised when connection to API fails."""
+
+    pass
+
+
+class DeviceNotFoundError(KerblweltError):
+    """Raised when requested device is not found."""
+
+    def __init__(self, device_id: str) -> None:
+        """Initialize device not found error.
+
+        Args:
+            device_id: ID of the device that was not found
+        """
+        super().__init__(f"Device not found: {device_id}")
+        self.device_id = device_id
+
+
+class RateLimitError(APIError):
+    """Raised when API rate limit is exceeded."""
+
+    pass
+
+
+class ValidationError(KerblweltError):
+    """Raised when input validation fails."""
+
+    pass

kerblwelt_api/models.py

@@ -0,0 +1,254 @@
+"""Data models for Kerbl Welt API."""
+
+from dataclasses import dataclass
+from datetime import datetime
+from typing import Any
+
+
+@dataclass
+class AuthResponse:
+    """Authentication response containing tokens."""
+
+    access_token: str
+    refresh_token: str
+
+
+@dataclass
+class DeviceType:
+    """Device type information."""
+
+    id: str
+    name: str
+
+
+@dataclass
+class User:
+    """User account information."""
+
+    id: str
+    email: str
+    language: str
+    timezone: str
+    device_types: str
+    is_test_user: bool
+    is_support: bool
+    username: str | None = None
+    temp_email: str | None = None
+    telephone_number: str | None = None
+    telephone_number_country_code: str | None = None
+    image_uri: str | None = None
+    push_notification_sound: str | None = None
+    privacy_policy_target: str | None = None
+    privacy_policy_current: str | None = None
+    terms_of_use_target: str | None = None
+    terms_of_use_current: str | None = None
+    double_opt_in_confirmed_at: datetime | None = None
+    telephone_double_opt_in_confirmed_at: datetime | None = None
+    allow_ads: bool = True
+    owned_service_group: str | None = None
+    roles: list[str] | None = None
+
+    @classmethod
+    def from_dict(cls, data: dict[str, Any]) -> "User":
+        """Create User from API response dictionary.
+
+        Args:
+            data: API response data
+
+        Returns:
+            User instance
+        """
+        # Parse datetime fields
+        double_opt_in = None
+        if data.get("doubleOptInConfirmedAt"):
+            double_opt_in = datetime.fromisoformat(
+                data["doubleOptInConfirmedAt"].replace("Z", "+00:00")
+            )
+
+        telephone_opt_in = None
+        if data.get("telephoneDoubleOptInConfirmedAt"):
+            telephone_opt_in = datetime.fromisoformat(
+                data["telephoneDoubleOptInConfirmedAt"].replace("Z", "+00:00")
+            )
+
+        return cls(
+            id=data["id"],
+            email=data["email"],
+            language=data["language"],
+            timezone=data["timezone"],
+            device_types=data["deviceTypes"],
+            is_test_user=data["isTestUser"],
+            is_support=data["isSupport"],
+            username=data.get("username"),
+            temp_email=data.get("tempEmail"),
+            telephone_number=data.get("telephoneNumber"),
+            telephone_number_country_code=data.get("telephoneNumberCountryCode"),
+            image_uri=data.get("imageUri"),
+            push_notification_sound=data.get("pushNotificationSound"),
+            privacy_policy_target=data.get("privacyPolicyTarget"),
+            privacy_policy_current=data.get("privacyPolicyCurrent"),
+            terms_of_use_target=data.get("termsOfUseTarget"),
+            terms_of_use_current=data.get("termsOfUseCurrent"),
+            double_opt_in_confirmed_at=double_opt_in,
+            telephone_double_opt_in_confirmed_at=telephone_opt_in,
+            allow_ads=data.get("allowAds", True),
+            owned_service_group=data.get("ownedServiceGroup"),
+            roles=data.get("roles", []),
+        )
+
+
+@dataclass
+class SmartSatelliteDevice:
+    """Smart Satellite electric fence monitor device."""
+
+    id: str
+    user_id: str
+    description: str
+    identifier: str
+    registered_at: datetime
+    push_notifications: bool
+    email_notifications: bool
+    email_addresses_notifications: str
+    is_online: bool
+    timezone: str
+    linking_identifier: str
+    active: bool
+    brand: str
+    battery_voltage: float
+    fence_voltage: int  # Volts
+    mode: int
+    fence_voltage_alarm_threshold: int  # Volts
+    signal_quality: int  # 0-100%
+    battery_state: int  # 0-100%
+    current_error: str
+    device_type: DeviceType
+    offline_since: datetime | None = None
+    first_online_at: datetime | None = None
+    firmware_version: str | None = None
+    target_firmware_version: str | None = None
+    firmware_update_state: str | None = None
+    firmware_release_date: datetime | None = None
+    item_number: str | None = None
+    offline_notified: datetime | None = None
+    image_uri: str | None = None
+    do_desired_and_actual_state_match: bool = True
+    mac: str | None = None
+    connection_version: str | None = None
+    fence_voltage_target: int | None = None
+    fence_voltage_alarm_threshold_desired: int | None = None
+
+    @property
+    def is_fence_voltage_ok(self) -> bool:
+        """Check if fence voltage is above alarm threshold.
+
+        Returns:
+            True if voltage is above threshold, False otherwise
+        """
+        return self.fence_voltage >= self.fence_voltage_alarm_threshold
+
+    @property
+    def is_battery_low(self) -> bool:
+        """Check if battery is low (below 20%).
+
+        Returns:
+            True if battery is below 20%, False otherwise
+        """
+        return self.battery_state < 20
+
+    @classmethod
+    def from_dict(cls, data: dict[str, Any]) -> "SmartSatelliteDevice":
+        """Create SmartSatelliteDevice from API response dictionary.
+
+        Args:
+            data: API response data
+
+        Returns:
+            SmartSatelliteDevice instance
+        """
+        # Parse datetime fields
+        registered_at = datetime.fromisoformat(data["registeredAt"].replace("Z", "+00:00"))
+
+        offline_since = None
+        if data.get("offlineSince"):
+            offline_since = datetime.fromisoformat(data["offlineSince"].replace("Z", "+00:00"))
+
+        first_online_at = None
+        if data.get("firstOnlineAt"):
+            first_online_at = datetime.fromisoformat(
+                data["firstOnlineAt"].replace("Z", "+00:00")
+            )
+
+        offline_notified = None
+        if data.get("offlineNotified"):
+            offline_notified = datetime.fromisoformat(
+                data["offlineNotified"].replace("Z", "+00:00")
+            )
+
+        firmware_release_date = None
+        if data.get("firmwareReleaseDate"):
+            firmware_release_date = datetime.fromisoformat(
+                data["firmwareReleaseDate"].replace("Z", "+00:00")
+            )
+
+        # Parse device type
+        device_type = DeviceType(
+            id=data["deviceType"]["id"],
+            name=data["deviceType"]["name"],
+        )
+
+        return cls(
+            id=data["id"],
+            user_id=data["userId"],
+            description=data["description"],
+            identifier=data["identifier"],
+            registered_at=registered_at,
+            push_notifications=data["pushNotifications"],
+            email_notifications=data["emailNotifications"],
+            email_addresses_notifications=data["emailAddressesNotifications"],
+            is_online=data["isOnline"],
+            timezone=data["timezone"],
+            linking_identifier=data["linkingIdentifier"],
+            active=data["active"],
+            brand=data["brand"],
+            battery_voltage=data["batteryVoltage"],
+            fence_voltage=data["fenceVoltage"],
+            mode=data["mode"],
+            fence_voltage_alarm_threshold=data["fenceVoltageAlarmThreshold"],
+            signal_quality=data["signalQuality"],
+            battery_state=data["batteryState"],
+            current_error=data["currentError"],
+            device_type=device_type,
+            offline_since=offline_since,
+            first_online_at=first_online_at,
+            firmware_version=data.get("firmwareVersion"),
+            target_firmware_version=data.get("targetFirmwareVersion"),
+            firmware_update_state=data.get("firmwareUpdateState"),
+            firmware_release_date=firmware_release_date,
+            item_number=data.get("itemNumber"),
+            offline_notified=offline_notified,
+            image_uri=data.get("imageUri"),
+            do_desired_and_actual_state_match=data.get("doDesiredAndActualStateMatch", True),
+            mac=data.get("mac"),
+            connection_version=data.get("connectionVersion"),
+            fence_voltage_target=data.get("fenceVoltageTarget"),
+            fence_voltage_alarm_threshold_desired=data.get("fenceVoltageAlarmThresholdDesired"),
+        )
+
+
+@dataclass
+class DeviceEventCount:
+    """Count of new events for a device."""
+
+    new: int
+
+    @classmethod
+    def from_dict(cls, data: dict[str, Any]) -> "DeviceEventCount":
+        """Create DeviceEventCount from API response dictionary.
+
+        Args:
+            data: API response data
+
+        Returns:
+            DeviceEventCount instance
+        """
+        return cls(new=data["new"])

kerblwelt_api-0.1.0.dist-info/METADATA

@@ -0,0 +1,323 @@
+Metadata-Version: 2.4
+Name: kerblwelt-api
+Version: 0.1.0
+Summary: Python API client for Kerbl Welt IoT platform (AKO Smart Satellite electric fence monitors)
+Author-email: Steve Garrity <sgarrity@gmail.com>
+License: MIT
+Project-URL: Homepage, https://github.com/stgarrity/kerblwelt-api
+Project-URL: Repository, https://github.com/stgarrity/kerblwelt-api
+Project-URL: Issues, https://github.com/stgarrity/kerblwelt-api/issues
+Keywords: kerbl,ako,smart-satellite,electric-fence,iot,api-client
+Classifier: Development Status :: 3 - Alpha
+Classifier: Intended Audience :: Developers
+Classifier: License :: OSI Approved :: MIT License
+Classifier: Programming Language :: Python :: 3
+Classifier: Programming Language :: Python :: 3.11
+Classifier: Programming Language :: Python :: 3.12
+Classifier: Programming Language :: Python :: 3.13
+Classifier: Topic :: Home Automation
+Classifier: Topic :: Software Development :: Libraries :: Python Modules
+Requires-Python: >=3.11
+Description-Content-Type: text/markdown
+License-File: LICENSE
+Requires-Dist: aiohttp>=3.9.0
+Provides-Extra: dev
+Requires-Dist: pytest>=7.0; extra == "dev"
+Requires-Dist: pytest-aiohttp>=1.0.0; extra == "dev"
+Requires-Dist: pytest-asyncio>=0.21.0; extra == "dev"
+Requires-Dist: pytest-cov>=4.0.0; extra == "dev"
+Requires-Dist: black>=23.0.0; extra == "dev"
+Requires-Dist: ruff>=0.1.0; extra == "dev"
+Requires-Dist: mypy>=1.0.0; extra == "dev"
+Dynamic: license-file
+
+# Kerblwelt API Client
+
+Python API client for [Kerbl Welt IoT platform](https://app.kerbl-iot.com), which powers the AKO Smart Satellite electric fence monitoring system.
+
+## Features
+
+- **Async/await** support for efficient I/O operations
+- **Full type hints** for better IDE support and type checking
+- **Automatic token management** with refresh capability
+- **Comprehensive error handling** with custom exceptions
+- **Data models** using Python dataclasses
+- **Well-tested** with pytest
+
+## Installation
+
+```bash
+pip install kerblwelt-api
+```
+
+Or for development:
+
+```bash
+git clone https://github.com/stgarrity/kerblwelt-api
+cd kerblwelt-api
+pip install -e ".[dev]"
+```
+
+## Quick Start
+
+```python
+import asyncio
+from kerblwelt_api import KerblweltClient
+
+async def main():
+    async with KerblweltClient() as client:
+        # Authenticate
+        await client.authenticate("your-email@example.com", "your-password")
+
+        # Get all devices
+        devices = await client.get_devices()
+
+        for device in devices:
+            print(f"Device: {device.description}")
+            print(f"  Fence Voltage: {device.fence_voltage}V")
+            print(f"  Battery: {device.battery_state}%")
+            print(f"  Signal: {device.signal_quality}%")
+            print(f"  Online: {device.is_online}")
+            print(f"  Status: {'OK' if device.is_fence_voltage_ok else 'LOW VOLTAGE!'}")
+
+if __name__ == "__main__":
+    asyncio.run(main())
+```
+
+## Usage
+
+### Authentication
+
+```python
+async with KerblweltClient() as client:
+    # Method 1: Authenticate with credentials
+    await client.authenticate("email@example.com", "password")
+
+    # Method 2: Restore previous session with tokens
+    client.set_tokens(
+        access_token="eyJhbGci...",
+        refresh_token="eyJhbGci..."
+    )
+```
+
+### Get User Information
+
+```python
+user = await client.get_user()
+print(f"User: {user.email}")
+print(f"Timezone: {user.timezone}")
+print(f"Language: {user.language}")
+```
+
+### Get Devices
+
+```python
+# Get all Smart Satellite devices
+devices = await client.get_devices()
+
+# Get a specific device by ID
+device = await client.get_device("device-uuid-here")
+
+# Get device with event count
+device_data = await client.get_all_device_data()
+for device_id, (device, events) in device_data.items():
+    print(f"{device.description}: {events.new} new events")
+```
+
+### Access Device Properties
+
+```python
+device = devices[0]
+
+# Basic info
+print(device.description)      # User-defined name
+print(device.id)                # Device UUID
+print(device.identifier)        # Serial number
+
+# Status
+print(device.is_online)         # Online/offline
+print(device.is_fence_voltage_ok)  # Voltage above threshold
+print(device.is_battery_low)    # Battery below 20%
+
+# Measurements
+print(device.fence_voltage)     # Current voltage (V)
+print(device.battery_voltage)   # Battery voltage (V)
+print(device.battery_state)     # Battery percentage (0-100)
+print(device.signal_quality)    # Signal strength (0-100)
+
+# Thresholds
+print(device.fence_voltage_alarm_threshold)  # Alert threshold (V)
+
+# Timestamps
+print(device.registered_at)     # Registration date
+print(device.first_online_at)   # First connection
+print(device.offline_since)     # Last offline time
+```
+
+### Token Refresh
+
+The client automatically handles token expiration. You can also manually refresh:
+
+```python
+try:
+    devices = await client.get_devices()
+except TokenExpiredError:
+    await client.refresh_token()
+    devices = await client.get_devices()
+```
+
+### Error Handling
+
+```python
+from kerblwelt_api import (
+    InvalidCredentialsError,
+    DeviceNotFoundError,
+    APIError,
+    ConnectionError,
+)
+
+try:
+    await client.authenticate("email@example.com", "wrong-password")
+except InvalidCredentialsError:
+    print("Invalid email or password")
+except ConnectionError:
+    print("Cannot connect to Kerbl Welt API")
+except APIError as e:
+    print(f"API error: {e}")
+```
+
+## API Reference
+
+### KerblweltClient
+
+Main client class for interacting with Kerbl Welt API.
+
+**Methods:**
+
+- `authenticate(email: str, password: str) -> None` - Authenticate with credentials
+- `set_tokens(access_token: str, refresh_token: str) -> None` - Set tokens manually
+- `refresh_token() -> None` - Refresh the access token
+- `get_user() -> User` - Get current user information
+- `get_devices() -> list[SmartSatelliteDevice]` - Get all Smart Satellite devices
+- `get_device(device_id: str) -> SmartSatelliteDevice` - Get specific device
+- `get_device_event_count(device_id: str) -> DeviceEventCount` - Get event count
+- `get_all_device_data() -> dict` - Get all devices with event counts
+- `close() -> None` - Close the client session
+
+**Properties:**
+
+- `is_authenticated: bool` - Check if client is authenticated
+
+### SmartSatelliteDevice
+
+Represents an AKO Smart Satellite electric fence monitor.
+
+**Key Attributes:**
+
+- `id: str` - Device UUID
+- `description: str` - User-defined device name
+- `fence_voltage: int` - Current fence voltage in volts
+- `battery_voltage: float` - Battery voltage in volts
+- `battery_state: int` - Battery percentage (0-100)
+- `signal_quality: int` - Signal strength (0-100)
+- `is_online: bool` - Device online status
+- `fence_voltage_alarm_threshold: int` - Alert threshold in volts
+
+**Helper Properties:**
+
+- `is_fence_voltage_ok: bool` - Voltage above threshold
+- `is_battery_low: bool` - Battery below 20%
+
+### Exceptions
+
+All exceptions inherit from `KerblweltError`:
+
+- `AuthenticationError` - Base authentication error
+  - `InvalidCredentialsError` - Wrong email/password
+  - `TokenExpiredError` - Token has expired
+  - `TokenRefreshError` - Token refresh failed
+- `APIError` - API request failed
+- `ConnectionError` - Network connection failed
+- `DeviceNotFoundError` - Device ID not found
+- `RateLimitError` - API rate limit exceeded
+- `ValidationError` - Input validation failed
+
+## Development
+
+### Setup
+
+```bash
+# Clone repository
+git clone https://github.com/stgarrity/kerblwelt-api
+cd kerblwelt-api
+
+# Create virtual environment
+python3 -m venv venv
+source venv/bin/activate
+
+# Install with dev dependencies
+pip install -e ".[dev]"
+```
+
+### Running Tests
+
+```bash
+# Run all tests
+pytest
+
+# Run with coverage
+pytest --cov=kerblwelt_api
+
+# Run specific test file
+pytest tests/test_client.py
+```
+
+### Code Quality
+
+```bash
+# Format code
+black kerblwelt_api tests
+
+# Lint code
+ruff check kerblwelt_api tests
+
+# Type checking
+mypy kerblwelt_api
+```
+
+## Requirements
+
+- Python 3.11 or higher
+- aiohttp 3.9.0 or higher
+
+## License
+
+MIT License - see [LICENSE](LICENSE) file for details.
+
+## Contributing
+
+Contributions are welcome! Please:
+
+1. Fork the repository
+2. Create a feature branch (`git checkout -b feature/amazing-feature`)
+3. Commit your changes (`git commit -m 'Add amazing feature'`)
+4. Push to the branch (`git push origin feature/amazing-feature`)
+5. Open a Pull Request
+
+## Acknowledgments
+
+- Built for the [Kerbl Welt IoT platform](https://app.kerbl-iot.com)
+- Powers AKO Smart Satellite electric fence monitors
+- Designed for integration with Home Assistant
+
+## Links
+
+- [Kerbl Welt Web App](https://app.kerbl-iot.com)
+- [AKO Smart Satellite Product Info](https://www.kerbl.com/en/product/ako-smart-satellite/)
+- [Home Assistant Integration](https://github.com/stgarrity/homeassistant-kerblwelt)
+
+## Support
+
+For issues and questions:
+- [GitHub Issues](https://github.com/stgarrity/kerblwelt-api/issues)
+- Email: sgarrity@gmail.com

kerblwelt_api-0.1.0.dist-info/RECORD

@@ -0,0 +1,11 @@
+kerblwelt_api/__init__.py,sha256=wXuxZu59Net4TbAta0V3goe5gf_HHIpZlDCU8HSgl7A,943
+kerblwelt_api/auth.py,sha256=gHuvSfUcIajTytKjQvU5sYWob-wqP8bnnGfq7-Qva1k,6561
+kerblwelt_api/client.py,sha256=mMTA1C6uvBEO8mv0PspbOLPrwhwH7Qk6IKYH7goyejI,8882
+kerblwelt_api/const.py,sha256=Ey8osqGHs4M5jyvdc2CP2dPruCrSh-afjqES9lJY__4,1446
+kerblwelt_api/exceptions.py,sha256=ocYOM7k2VE11ZdbPoinz60danZZNOD0FnZgFobCxWEo,1596
+kerblwelt_api/models.py,sha256=n5AUlPJQQ353QFoCIpRVRbvByQDZqsS04JKkhT207lY,8434
+kerblwelt_api-0.1.0.dist-info/licenses/LICENSE,sha256=VT1yKHLweBlpBR7vx-Xyy3jzNcdhCsevHJG5db7ln5E,1070
+kerblwelt_api-0.1.0.dist-info/METADATA,sha256=9NQaNHJDr2h6QnPZpLLG_ox4CdI63-QqXq63uK7PlOc,8859
+kerblwelt_api-0.1.0.dist-info/WHEEL,sha256=_zCd3N1l69ArxyTb8rzEoP9TpbYXkqRFSNOD5OuxnTs,91
+kerblwelt_api-0.1.0.dist-info/top_level.txt,sha256=7VQM_VwLfGfNdhZXWY4GUv4-GBgZ2Cr9kBDJkquz6ik,14
+kerblwelt_api-0.1.0.dist-info/RECORD,,

kerblwelt_api-0.1.0.dist-info/WHEEL

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

kerblwelt_api-0.1.0.dist-info/licenses/LICENSE

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

kerblwelt_api-0.1.0.dist-info/top_level.txt

@@ -0,0 +1 @@
+kerblwelt_api