lojack-api 0.5.0__py3-none-any.whl

lojack_api/exceptions.py

@@ -0,0 +1,93 @@
+"""Exceptions for the LoJack client library."""
+
+from typing import Any
+
+
+class LoJackError(Exception):
+    """Base exception for all LoJack client errors."""
+
+    def __init__(self, message: str = "", *args: Any) -> None:
+        self.message = message
+        super().__init__(message, *args)
+
+
+class AuthenticationError(LoJackError):
+    """Raised when authentication fails (invalid credentials, expired token, etc.)."""
+
+    pass
+
+
+class AuthorizationError(LoJackError):
+    """Raised when the user is not authorized to perform an action."""
+
+    pass
+
+
+class ApiError(LoJackError):
+    """Raised when the API returns an error response."""
+
+    def __init__(
+        self,
+        message: str = "",
+        status_code: int | None = None,
+        response_body: str | None = None,
+    ) -> None:
+        super().__init__(message)
+        self.status_code = status_code
+        self.response_body = response_body
+
+    def __str__(self) -> str:
+        if self.status_code:
+            return f"{self.message} (HTTP {self.status_code})"
+        return self.message
+
+
+class ConnectionError(LoJackError):
+    """Raised when a connection to the API cannot be established."""
+
+    pass
+
+
+class TimeoutError(LoJackError):
+    """Raised when an API request times out."""
+
+    pass
+
+
+class DeviceNotFoundError(LoJackError):
+    """Raised when a requested device is not found."""
+
+    def __init__(self, device_id: str, message: str | None = None) -> None:
+        self.device_id = device_id
+        super().__init__(message or f"Device not found: {device_id}")
+
+
+class CommandError(LoJackError):
+    """Raised when a device command fails."""
+
+    def __init__(
+        self,
+        command: str,
+        device_id: str,
+        message: str | None = None,
+        reason: str | None = None,
+    ) -> None:
+        self.command = command
+        self.device_id = device_id
+        self.reason = reason
+        super().__init__(
+            message or f"Command '{command}' failed for device {device_id}"
+        )
+
+
+class InvalidParameterError(LoJackError):
+    """Raised when an invalid parameter is provided."""
+
+    def __init__(self, parameter: str, value: Any, reason: str | None = None) -> None:
+        self.parameter = parameter
+        self.value = value
+        self.reason = reason
+        msg = f"Invalid parameter '{parameter}': {value}"
+        if reason:
+            msg += f" ({reason})"
+        super().__init__(msg)

lojack_api/models.py

@@ -0,0 +1,285 @@
+"""Data models for LoJack API responses.
+
+These are simple dataclasses representing the raw data from the API.
+For objects with methods (refresh, lock, etc.), see device.py.
+"""
+
+from __future__ import annotations
+
+from dataclasses import dataclass, field
+from datetime import datetime, timezone
+from typing import Any
+
+
+@dataclass
+class Location:
+    """A single location point from the API."""
+
+    latitude: float | None = None
+    longitude: float | None = None
+    timestamp: datetime | None = None
+    accuracy: float | None = None
+    speed: float | None = None
+    heading: float | None = None
+    address: str | None = None
+    raw: dict[str, Any] = field(default_factory=dict)
+
+    @classmethod
+    def from_api(cls, data: dict[str, Any]) -> Location:
+        """Parse a location from API response data."""
+        loc = cls(raw=data)
+
+        # Handle nested coordinates (Spireon format)
+        coords = data.get("coordinates", {})
+
+        loc.latitude = (
+            data.get("latitude")
+            or data.get("lat")
+            or coords.get("latitude")
+            or coords.get("lat")
+        )
+        loc.longitude = (
+            data.get("longitude")
+            or data.get("lng")
+            or data.get("lon")
+            or coords.get("longitude")
+            or coords.get("lng")
+        )
+        loc.accuracy = data.get("accuracy") or data.get("hdop")
+        loc.speed = data.get("speed")
+        loc.heading = data.get("heading") or data.get("bearing") or data.get("course")
+        loc.address = data.get("address") or data.get("formattedAddress")
+
+        # Parse timestamp - try multiple formats
+        ts = (
+            data.get("timestamp")
+            or data.get("time")
+            or data.get("recorded_at")
+            or data.get("eventDateTime")
+            or data.get("dateTime")
+        )
+        if ts:
+            loc.timestamp = _parse_timestamp(ts)
+
+        return loc
+
+    @classmethod
+    def from_event(cls, event_data: dict[str, Any]) -> Location:
+        """Parse a location from a Spireon event.
+
+        Spireon events have a nested structure:
+        {
+            "location": {"lat": 40.7128, "lng": -74.0060},
+            "heading": 180,
+            "speed": 35,
+            "date": "2024-01-15T12:00:00.000+0000",
+            ...
+        }
+        """
+        loc = cls(raw=event_data)
+
+        # Get nested location object
+        location_data = event_data.get("location", {})
+
+        # Parse coordinates from nested location or top-level
+        loc.latitude = (
+            location_data.get("lat")
+            or location_data.get("latitude")
+            or event_data.get("lat")
+            or event_data.get("latitude")
+        )
+        loc.longitude = (
+            location_data.get("lng")
+            or location_data.get("lon")
+            or location_data.get("longitude")
+            or event_data.get("lng")
+            or event_data.get("lon")
+            or event_data.get("longitude")
+        )
+
+        # Speed and heading are at top level in events
+        loc.speed = event_data.get("speed")
+        loc.heading = (
+            event_data.get("heading")
+            or event_data.get("bearing")
+            or event_data.get("course")
+        )
+        loc.accuracy = event_data.get("accuracy") or event_data.get("hdop")
+        loc.address = event_data.get("address") or event_data.get("formattedAddress")
+
+        # Parse timestamp - events use "date" field
+        ts = (
+            event_data.get("date")
+            or event_data.get("eventDateTime")
+            or event_data.get("dateTime")
+            or event_data.get("timestamp")
+        )
+        if ts:
+            loc.timestamp = _parse_timestamp(ts)
+
+        return loc
+
+
+@dataclass
+class DeviceInfo:
+    """Basic device information from the API."""
+
+    id: str
+    name: str | None = None
+    device_type: str | None = None
+    status: str | None = None
+    last_seen: datetime | None = None
+    raw: dict[str, Any] = field(default_factory=dict)
+
+    @classmethod
+    def from_api(cls, data: dict[str, Any]) -> DeviceInfo:
+        """Parse device info from API response data."""
+        # Handle Spireon's nested "attributes" structure
+        attrs = data.get("attributes", {})
+        status_obj = data.get("status", {})
+
+        device = cls(
+            id=data.get("id") or data.get("device_id") or data.get("assetId") or "",
+            name=data.get("name") or attrs.get("name") or data.get("device_name"),
+            device_type=data.get("type") or attrs.get("type") or data.get("device_type"),
+            status=(
+                status_obj.get("status")
+                if isinstance(status_obj, dict)
+                else data.get("status")
+            ),
+            raw=data,
+        )
+
+        ts = (
+            data.get("last_seen")
+            or data.get("lastSeen")
+            or data.get("last_updated")
+            or data.get("lastEventDateTime")
+        )
+        if ts:
+            device.last_seen = _parse_timestamp(ts)
+
+        return device
+
+
+@dataclass
+class VehicleInfo(DeviceInfo):
+    """Vehicle-specific information extending DeviceInfo."""
+
+    vin: str | None = None
+    make: str | None = None
+    model: str | None = None
+    year: int | None = None
+    license_plate: str | None = None
+    odometer: float | None = None
+
+    @classmethod
+    def from_api(cls, data: dict[str, Any]) -> VehicleInfo:
+        """Parse vehicle info from API response data."""
+        # Handle Spireon's nested "attributes" structure
+        attrs = data.get("attributes", {})
+        status_obj = data.get("status", {})
+
+        vehicle = cls(
+            id=(
+                data.get("id")
+                or data.get("device_id")
+                or data.get("vehicle_id")
+                or data.get("assetId")
+                or ""
+            ),
+            name=data.get("name") or attrs.get("name") or data.get("vehicle_name"),
+            device_type=(
+                data.get("type")
+                or attrs.get("type")
+                or data.get("device_type")
+                or "vehicle"
+            ),
+            status=(
+                status_obj.get("status")
+                if isinstance(status_obj, dict)
+                else data.get("status")
+            ),
+            raw=data,
+            vin=data.get("vin") or attrs.get("vin"),
+            make=data.get("make") or attrs.get("make"),
+            model=data.get("model") or attrs.get("model"),
+            license_plate=(
+                data.get("license_plate")
+                or data.get("licensePlate")
+                or attrs.get("licensePlate")
+                or attrs.get("license_plate")
+            ),
+        )
+
+        # Parse year from either top-level or attributes
+        year = data.get("year") or attrs.get("year")
+        if year is not None:
+            try:
+                vehicle.year = int(year)
+            except (ValueError, TypeError):
+                pass
+
+        # Parse odometer from either top-level or attributes
+        odometer = data.get("odometer") or data.get("mileage") or attrs.get("odometer")
+        if odometer is not None:
+            try:
+                vehicle.odometer = float(odometer)
+            except (ValueError, TypeError):
+                pass
+
+        ts = (
+            data.get("last_seen")
+            or data.get("lastSeen")
+            or data.get("last_updated")
+            or data.get("lastEventDateTime")
+        )
+        if ts:
+            vehicle.last_seen = _parse_timestamp(ts)
+
+        return vehicle
+
+
+def _parse_timestamp(ts: Any) -> datetime | None:
+    """Parse various timestamp formats into datetime."""
+    if ts is None:
+        return None
+
+    if isinstance(ts, datetime):
+        return ts
+
+    if isinstance(ts, (int, float)):
+        # Unix timestamp (seconds or milliseconds)
+        if ts > 1e12:  # Likely milliseconds
+            ts = ts / 1000
+        try:
+            return datetime.fromtimestamp(ts, tz=timezone.utc)
+        except (ValueError, OSError):
+            return None
+
+    if isinstance(ts, str):
+        # Try ISO format first
+        for fmt in (
+            "%Y-%m-%dT%H:%M:%S.%fZ",
+            "%Y-%m-%dT%H:%M:%SZ",
+            "%Y-%m-%dT%H:%M:%S.%f%z",
+            "%Y-%m-%dT%H:%M:%S%z",
+            "%Y-%m-%dT%H:%M:%S",
+            "%Y-%m-%d %H:%M:%S",
+        ):
+            try:
+                dt = datetime.strptime(ts, fmt)
+                if dt.tzinfo is None:
+                    dt = dt.replace(tzinfo=timezone.utc)
+                return dt
+            except ValueError:
+                continue
+
+        # Try fromisoformat as fallback
+        try:
+            dt = datetime.fromisoformat(ts.replace("Z", "+00:00"))
+            return dt
+        except ValueError:
+            pass
+
+    return None

lojack_api/transport.py

@@ -0,0 +1,184 @@
+"""HTTP transport layer using aiohttp.
+
+This module handles all HTTP communication with the LoJack API.
+It is designed to be compatible with Home Assistant's async patterns.
+"""
+
+from __future__ import annotations
+
+import asyncio
+import ssl
+from typing import Any
+
+import aiohttp
+
+from .exceptions import (
+    ApiError,
+    AuthenticationError,
+    AuthorizationError,
+    ConnectionError,
+    TimeoutError,
+)
+
+
+class AiohttpTransport:
+    """Async HTTP transport using aiohttp.
+
+    This class manages HTTP communication and can accept an external
+    aiohttp.ClientSession (recommended for Home Assistant) or create its own.
+
+    Args:
+        base_url: The base URL for API requests (e.g., "https://api.lojack.com").
+        session: Optional existing aiohttp.ClientSession to use.
+        timeout: Request timeout in seconds (default: 30).
+        ssl_context: Optional SSL context for custom certificate handling.
+    """
+
+    def __init__(
+        self,
+        base_url: str,
+        session: aiohttp.ClientSession | None = None,
+        timeout: float = 30.0,
+        ssl_context: ssl.SSLContext | None = None,
+    ) -> None:
+        self.base_url = base_url.rstrip("/")
+        self._external_session = session is not None
+        self._session = session
+        self._timeout = aiohttp.ClientTimeout(total=timeout)
+        self._ssl_context = ssl_context
+        self._closed = False
+
+    @property
+    def closed(self) -> bool:
+        """Return True if the transport has been closed."""
+        return self._closed
+
+    async def _get_session(self) -> aiohttp.ClientSession:
+        """Get or create the aiohttp session."""
+        if self._closed:
+            raise ConnectionError("Transport has been closed")
+
+        if self._session is None or self._session.closed:
+            ssl_arg = self._ssl_context if self._ssl_context is not None else False
+            connector = aiohttp.TCPConnector(ssl=ssl_arg)
+            self._session = aiohttp.ClientSession(
+                timeout=self._timeout,
+                connector=connector,
+            )
+        return self._session
+
+    async def request(
+        self,
+        method: str,
+        path: str,
+        *,
+        params: dict[str, Any] | None = None,
+        json: Any | None = None,
+        data: Any | None = None,
+        headers: dict[str, str] | None = None,
+    ) -> Any:
+        """Make an HTTP request to the API.
+
+        Args:
+            method: HTTP method (GET, POST, PUT, DELETE, etc.).
+            path: API path (will be joined with base_url).
+            params: Optional query parameters.
+            json: Optional JSON body (will be serialized).
+            data: Optional form data body.
+            headers: Optional additional headers.
+
+        Returns:
+            Parsed JSON response if Content-Type is application/json,
+            otherwise the response text.
+
+        Raises:
+            AuthenticationError: For 401 responses.
+            AuthorizationError: For 403 responses.
+            ApiError: For other HTTP errors.
+            ConnectionError: For network connectivity issues.
+            TimeoutError: For request timeouts.
+        """
+        session = await self._get_session()
+        url = f"{self.base_url}/{path.lstrip('/')}"
+
+        try:
+            async with session.request(
+                method,
+                url,
+                params=params,
+                json=json,
+                data=data,
+                headers=headers,
+                ssl=self._ssl_context,
+            ) as resp:
+                return await self._handle_response(resp)
+
+        except aiohttp.ClientResponseError as e:
+            raise self._map_http_error(e.status, str(e)) from e
+        except asyncio.TimeoutError as e:
+            raise TimeoutError(f"Request to {url} timed out") from e
+        except aiohttp.ClientConnectorError as e:
+            raise ConnectionError(f"Failed to connect to {url}: {e}") from e
+        except aiohttp.ClientError as e:
+            raise ConnectionError(f"Request failed: {e}") from e
+
+    async def _handle_response(self, resp: aiohttp.ClientResponse) -> Any:
+        """Process the HTTP response."""
+        # Check for error status codes
+        if resp.status >= 400:
+            body = await self._safe_read_body(resp)
+            raise self._map_http_error(resp.status, body, body)
+
+        # Parse response based on content type
+        content_type = resp.headers.get("Content-Type", "")
+
+        if "application/json" in content_type:
+            try:
+                return await resp.json()
+            except (aiohttp.ContentTypeError, ValueError):
+                # If JSON parsing fails, return text
+                text = await resp.text()
+                return text
+
+        return await resp.text()
+
+    async def _safe_read_body(self, resp: aiohttp.ClientResponse) -> str:
+        """Safely read response body for error messages."""
+        try:
+            return await resp.text()
+        except Exception:
+            return ""
+
+    def _map_http_error(
+        self,
+        status: int,
+        message: str,
+        body: str | None = None,
+    ) -> AuthenticationError | AuthorizationError | ApiError:
+        """Map HTTP status codes to appropriate exceptions."""
+        if status == 401:
+            return AuthenticationError(message or "Authentication failed")
+        if status == 403:
+            return AuthorizationError(message or "Access denied")
+        return ApiError(message or f"HTTP {status}", status_code=status, response_body=body)
+
+    async def close(self) -> None:
+        """Close the transport and release resources.
+
+        If the session was provided externally, it will NOT be closed
+        (the caller is responsible for managing it).
+        """
+        if self._closed:
+            return
+
+        self._closed = True
+
+        if self._session and not self._external_session:
+            if not self._session.closed:
+                await self._session.close()
+
+        self._session = None
+
+
+# Keep backward compatibility alias
+AiohttpClient = AiohttpTransport