pyunipolsai 0.1.0__tar.gz

pyunipolsai-0.1.0/.gitignore

@@ -0,0 +1,17 @@
+__pycache__/
+*.py[cod]
+.pytest_cache/
+.ruff_cache/
+.mypy_cache/
+.hypothesis/
+.venv/
+venv/
+.DS_Store
+
+# reverse engineering working directories
+apk/
+decompiled/
+captures/
+.env.local
+dist/
+*.egg-info/

pyunipolsai-0.1.0/PKG-INFO

@@ -0,0 +1,115 @@
+Metadata-Version: 2.5
+Name: pyunipolsai
+Version: 0.1.0
+Summary: Async client for the Unipol (UnipolSai) Unibox telematics API
+Project-URL: Homepage, https://github.com/fezvrasta/ha-unipolsai
+Project-URL: Issues, https://github.com/fezvrasta/ha-unipolsai/issues
+Author: Federico Zivolo
+License-Expression: MIT
+Keywords: gps,telematics,unibox,unipol,unipolsai
+Classifier: Development Status :: 3 - Alpha
+Classifier: Intended Audience :: Developers
+Classifier: License :: OSI Approved :: MIT License
+Classifier: Programming Language :: Python :: 3.12
+Classifier: Programming Language :: Python :: 3.13
+Classifier: Topic :: Software Development :: Libraries
+Requires-Python: >=3.12
+Requires-Dist: aiohttp>=3.9
+Provides-Extra: test
+Requires-Dist: aioresponses>=0.7; extra == 'test'
+Requires-Dist: pytest-asyncio>=0.23; extra == 'test'
+Requires-Dist: pytest>=8; extra == 'test'
+Description-Content-Type: text/markdown
+
+# pyunipolsai
+
+Async Python client for the Unipol (UnipolSai) **Unibox** telematics API: vehicle position, driving statistics, and alert events for the black box fitted under an Italian Unipol motor policy.
+
+Built by reverse engineering the Android app and verifying every call against a live account. The findings behind it are written up in [`docs/FINDINGS.md`](https://github.com/FezVrasta/ha-unipolsai/blob/main/docs/FINDINGS.md).
+
+```python
+import asyncio
+from pyunipolsai import UnipolSaiClient
+
+
+async def main():
+    async with UnipolSaiClient(username="you@example.com", password="...") as client:
+        for vehicle in await client.async_get_vehicles():
+            position = await client.async_get_position(vehicle)
+            print(
+                vehicle.plate,
+                position.latitude,
+                position.longitude,
+                position.timestamp,
+                f"{position.quota.remaining} refreshes left",
+            )
+
+
+asyncio.run(main())
+```
+
+## What it does
+
+| Method | Returns | Cost |
+|---|---|---|
+| `async_get_vehicles()` | `list[Vehicle]`, usable ones by default | free |
+| `async_get_position(vehicle)` | `Position` | free |
+| `async_get_position(vehicle, force_refresh=True)` | `Position` | **spends daily quota** |
+| `async_get_services(vehicle)` | `dict[str, Service]` | free |
+| `async_get_notifications(vehicle, service)` | `list[Notification]` | free |
+| `async_get_usage(vehicle)` | `UsageStats` | free |
+
+## Things this API does that will surprise you
+
+The library handles all of these; they're listed so the behaviour isn't mistaken for a bug.
+
+**A bearer token is not enough.** Login also sets F5 BIG-IP session cookies that must ride on every request. The client keeps one cookie-persisting session and treats a 403 as "log in again" rather than "refresh the token". A stored long-lived token is not a workable auth model here.
+
+**Plates are country-prefixed** in URLs (`IT-AB123CD`). Pass a `Vehicle` or a bare plate; `normalise_plate` sorts it out.
+
+**Declared types lie.** Dates are declared `String` in the app but sent as epoch milliseconds. Distances are metres, times are seconds. `heading` is a cardinal letter (`"N"`), not degrees. `accuracy` is a small quality grade, *not* a radius, which is why this library calls it `Position.quality` — mapping a `1` onto something like Home Assistant's `gps_accuracy` would claim a one-metre fix.
+
+**There are two separate budgets.** `Position.quota` is the daily cap on *forced* refreshes (observed limit: 5). Plain reads never touch it. Separately, `Service.credits_available` is a slower pool that pays for having a service switched on. `rangeStatistics` needs no credits at all, so driving statistics are free to poll.
+
+**`force_refresh=True` is fire and forget.** It returns immediately with the *old* position and `pending_request` False; the flag goes true a few seconds later and the cycle takes roughly five minutes. It can finish without the position changing, which is what a car parked with the engine off looks like — and that costs no quota. Compare `timestamp` against the value you had before to tell success from give-up.
+
+**`async_get_notifications` returns only the most recent event** despite the plural field name, so two events inside one poll interval collapse into one. The app receives these as push; there is no push path here.
+
+**`date_range` is a single letter.** `g` is the whole contract period, `t` is a custom range needing epoch-millisecond `start`/`end`. Word-style values like `LAST_MONTH` are rejected.
+
+## Gateway credentials
+
+Requests carry the app's IBM API Connect credentials (`x-ibm-client-id`, `x-ibm-client-secret`, `x-unipol-tenant`). Working defaults ship in `const.py`: they are app-global rather than per-user, and travel inside a public Play Store app, so they are no more secret than any baked-in mobile API key.
+
+Unipol can rotate them. Override them if that happens, without waiting for a release:
+
+```python
+UnipolSaiClient(
+    username=..., password=..., client_id=..., client_secret=..., tenant=...
+)
+```
+
+[`docs/CAPTURE.md`](https://github.com/FezVrasta/ha-unipolsai/blob/main/docs/CAPTURE.md) explains how to capture new ones. It needs no account.
+
+## Install
+
+```bash
+pip install pyunipolsai
+```
+
+Developed in the [`ha-unipolsai`](https://github.com/FezVrasta/ha-unipolsai) repository
+alongside the Home Assistant integration that uses it, and released from a
+`pyunipolsai-vX.Y.Z` tag there.
+
+## Tests
+
+```bash
+pip install -e '.[test]'
+pytest
+```
+
+The fixtures are real captured payloads with identifiers replaced.
+
+## Scope
+
+This reads an account holder's own data. It breaks no pinning, defeats no authentication, and circumvents no protection. Respect the quota, don't hammer the gateway, and check Unipol's terms before building anything public on it.

pyunipolsai-0.1.0/README.md

@@ -0,0 +1,92 @@
+# pyunipolsai
+
+Async Python client for the Unipol (UnipolSai) **Unibox** telematics API: vehicle position, driving statistics, and alert events for the black box fitted under an Italian Unipol motor policy.
+
+Built by reverse engineering the Android app and verifying every call against a live account. The findings behind it are written up in [`docs/FINDINGS.md`](https://github.com/FezVrasta/ha-unipolsai/blob/main/docs/FINDINGS.md).
+
+```python
+import asyncio
+from pyunipolsai import UnipolSaiClient
+
+
+async def main():
+    async with UnipolSaiClient(username="you@example.com", password="...") as client:
+        for vehicle in await client.async_get_vehicles():
+            position = await client.async_get_position(vehicle)
+            print(
+                vehicle.plate,
+                position.latitude,
+                position.longitude,
+                position.timestamp,
+                f"{position.quota.remaining} refreshes left",
+            )
+
+
+asyncio.run(main())
+```
+
+## What it does
+
+| Method | Returns | Cost |
+|---|---|---|
+| `async_get_vehicles()` | `list[Vehicle]`, usable ones by default | free |
+| `async_get_position(vehicle)` | `Position` | free |
+| `async_get_position(vehicle, force_refresh=True)` | `Position` | **spends daily quota** |
+| `async_get_services(vehicle)` | `dict[str, Service]` | free |
+| `async_get_notifications(vehicle, service)` | `list[Notification]` | free |
+| `async_get_usage(vehicle)` | `UsageStats` | free |
+
+## Things this API does that will surprise you
+
+The library handles all of these; they're listed so the behaviour isn't mistaken for a bug.
+
+**A bearer token is not enough.** Login also sets F5 BIG-IP session cookies that must ride on every request. The client keeps one cookie-persisting session and treats a 403 as "log in again" rather than "refresh the token". A stored long-lived token is not a workable auth model here.
+
+**Plates are country-prefixed** in URLs (`IT-AB123CD`). Pass a `Vehicle` or a bare plate; `normalise_plate` sorts it out.
+
+**Declared types lie.** Dates are declared `String` in the app but sent as epoch milliseconds. Distances are metres, times are seconds. `heading` is a cardinal letter (`"N"`), not degrees. `accuracy` is a small quality grade, *not* a radius, which is why this library calls it `Position.quality` — mapping a `1` onto something like Home Assistant's `gps_accuracy` would claim a one-metre fix.
+
+**There are two separate budgets.** `Position.quota` is the daily cap on *forced* refreshes (observed limit: 5). Plain reads never touch it. Separately, `Service.credits_available` is a slower pool that pays for having a service switched on. `rangeStatistics` needs no credits at all, so driving statistics are free to poll.
+
+**`force_refresh=True` is fire and forget.** It returns immediately with the *old* position and `pending_request` False; the flag goes true a few seconds later and the cycle takes roughly five minutes. It can finish without the position changing, which is what a car parked with the engine off looks like — and that costs no quota. Compare `timestamp` against the value you had before to tell success from give-up.
+
+**`async_get_notifications` returns only the most recent event** despite the plural field name, so two events inside one poll interval collapse into one. The app receives these as push; there is no push path here.
+
+**`date_range` is a single letter.** `g` is the whole contract period, `t` is a custom range needing epoch-millisecond `start`/`end`. Word-style values like `LAST_MONTH` are rejected.
+
+## Gateway credentials
+
+Requests carry the app's IBM API Connect credentials (`x-ibm-client-id`, `x-ibm-client-secret`, `x-unipol-tenant`). Working defaults ship in `const.py`: they are app-global rather than per-user, and travel inside a public Play Store app, so they are no more secret than any baked-in mobile API key.
+
+Unipol can rotate them. Override them if that happens, without waiting for a release:
+
+```python
+UnipolSaiClient(
+    username=..., password=..., client_id=..., client_secret=..., tenant=...
+)
+```
+
+[`docs/CAPTURE.md`](https://github.com/FezVrasta/ha-unipolsai/blob/main/docs/CAPTURE.md) explains how to capture new ones. It needs no account.
+
+## Install
+
+```bash
+pip install pyunipolsai
+```
+
+Developed in the [`ha-unipolsai`](https://github.com/FezVrasta/ha-unipolsai) repository
+alongside the Home Assistant integration that uses it, and released from a
+`pyunipolsai-vX.Y.Z` tag there.
+
+## Tests
+
+```bash
+pip install -e '.[test]'
+pytest
+```
+
+The fixtures are real captured payloads with identifiers replaced.
+
+## Scope
+
+This reads an account holder's own data. It breaks no pinning, defeats no authentication, and circumvents no protection. Respect the quota, don't hammer the gateway, and check Unipol's terms before building anything public on it.

pyunipolsai-0.1.0/pyproject.toml

@@ -0,0 +1,36 @@
+[build-system]
+requires = ["hatchling"]
+build-backend = "hatchling.build"
+
+[project]
+name = "pyunipolsai"
+version = "0.1.0"
+description = "Async client for the Unipol (UnipolSai) Unibox telematics API"
+readme = "README.md"
+requires-python = ">=3.12"
+license = "MIT"
+authors = [{ name = "Federico Zivolo" }]
+keywords = ["unipol", "unipolsai", "unibox", "telematics", "gps"]
+classifiers = [
+  "Development Status :: 3 - Alpha",
+  "Intended Audience :: Developers",
+  "License :: OSI Approved :: MIT License",
+  "Programming Language :: Python :: 3.12",
+  "Programming Language :: Python :: 3.13",
+  "Topic :: Software Development :: Libraries",
+]
+dependencies = ["aiohttp>=3.9"]
+
+[project.urls]
+Homepage = "https://github.com/fezvrasta/ha-unipolsai"
+Issues = "https://github.com/fezvrasta/ha-unipolsai/issues"
+
+[project.optional-dependencies]
+test = ["pytest>=8", "pytest-asyncio>=0.23", "aioresponses>=0.7"]
+
+[tool.hatch.build.targets.wheel]
+packages = ["src/pyunipolsai"]
+
+[tool.pytest.ini_options]
+asyncio_mode = "auto"
+testpaths = ["tests"]

pyunipolsai-0.1.0/src/pyunipolsai/__init__.py

@@ -0,0 +1,58 @@
+"""Async client for the Unipol (UnipolSai) Unibox telematics API."""
+
+from __future__ import annotations
+
+from .client import UnipolSaiClient
+from .const import (
+    ALERT_SERVICES,
+    BASE_URL,
+    DEFAULT_CLIENT_ID,
+    DEFAULT_CLIENT_SECRET,
+    DEFAULT_TENANT,
+    DEFAULT_USER_AGENT,
+    SERVICE_CAR_FINDER,
+    SERVICE_RANGE_STATISTICS,
+)
+from .exceptions import (
+    UnipolSaiAuthError,
+    UnipolSaiConnectionError,
+    UnipolSaiError,
+)
+from .models import (
+    HEADING_DEGREES,
+    Notification,
+    Position,
+    Quota,
+    Service,
+    TelematicDevice,
+    UsageStats,
+    Vehicle,
+    normalise_plate,
+)
+
+__version__ = "0.1.0"
+
+__all__ = [
+    "ALERT_SERVICES",
+    "BASE_URL",
+    "DEFAULT_CLIENT_ID",
+    "DEFAULT_CLIENT_SECRET",
+    "DEFAULT_TENANT",
+    "DEFAULT_USER_AGENT",
+    "HEADING_DEGREES",
+    "SERVICE_CAR_FINDER",
+    "SERVICE_RANGE_STATISTICS",
+    "Notification",
+    "Position",
+    "Quota",
+    "Service",
+    "TelematicDevice",
+    "UnipolSaiAuthError",
+    "UnipolSaiClient",
+    "UnipolSaiConnectionError",
+    "UnipolSaiError",
+    "UsageStats",
+    "Vehicle",
+    "__version__",
+    "normalise_plate",
+]

pyunipolsai-0.1.0/src/pyunipolsai/client.py

@@ -0,0 +1,284 @@
+"""Async client for the Unipol apphub telematics API."""
+
+from __future__ import annotations
+
+import logging
+import uuid
+from typing import Any, Self
+
+import aiohttp
+
+from .const import (
+    BASE_URL,
+    DEFAULT_CLIENT_ID,
+    DEFAULT_CLIENT_SECRET,
+    DEFAULT_TENANT,
+    DEFAULT_USER_AGENT,
+)
+from .exceptions import UnipolSaiAuthError, UnipolSaiConnectionError, UnipolSaiError
+from .models import (
+    Notification,
+    Position,
+    Service,
+    UsageStats,
+    Vehicle,
+    normalise_plate,
+)
+
+_LOGGER = logging.getLogger(__name__)
+
+
+class UnipolSaiClient:
+    """Talks to `apphub.unipolsai.it`.
+
+    Three things about this API are not guessable from the app's code and
+    will produce confusing failures if changed:
+
+    * **The bearer token alone is not enough.** Login also sets F5 BIG-IP
+      session cookies (`MRHSession`, `JSESSIONID`, `TS*`) that must ride on
+      every subsequent request. Everything therefore shares one
+      cookie-persisting session, and a 403 means "log in again", not
+      "refresh the token". A stored long-lived token is not a workable
+      auth model.
+    * **Plates are country-prefixed** in the path: `IT-AB123CD`.
+    * **Telematics calls need `service_type` and `company_id` headers.**
+
+    Usage::
+
+        async with UnipolSaiClient(username="...", password="...") as client:
+            for vehicle in await client.async_get_vehicles():
+                print(await client.async_get_position(vehicle))
+    """
+
+    def __init__(
+        self,
+        username: str,
+        password: str,
+        *,
+        session: aiohttp.ClientSession | None = None,
+        client_id: str = DEFAULT_CLIENT_ID,
+        client_secret: str = DEFAULT_CLIENT_SECRET,
+        tenant: str = DEFAULT_TENANT,
+        user_agent: str = DEFAULT_USER_AGENT,
+    ) -> None:
+        """Create a client.
+
+        `session` must have a cookie jar; if you pass one, don't share it with
+        unrelated traffic. Omit it and the client owns its own.
+        """
+        self._username = username
+        self._password = password
+        self._client_id = client_id
+        self._client_secret = client_secret
+        self._tenant = tenant
+        self._user_agent = user_agent
+        self._session = session
+        self._owns_session = session is None
+        self._token: str | None = None
+
+    async def __aenter__(self) -> Self:
+        """Enter the context manager."""
+        return self
+
+    async def __aexit__(self, *_: object) -> None:
+        """Close the session on exit."""
+        await self.async_close()
+
+    async def async_close(self) -> None:
+        """Close the session, if this client created it."""
+        if self._owns_session and self._session is not None:
+            await self._session.close()
+            self._session = None
+
+    # -- plumbing ---------------------------------------------------------
+
+    @property
+    def _http(self) -> aiohttp.ClientSession:
+        if self._session is None:
+            self._session = aiohttp.ClientSession()
+        return self._session
+
+    def _headers(self, telematics: bool = False) -> dict[str, str]:
+        headers = {
+            "User-Agent": self._user_agent,
+            "source": "mobile",
+            "accept": "application/json",
+            "x-unipol-canale": "APP",
+            "x-unipol-requestid": str(uuid.uuid4()),
+            "x-ibm-client-id": self._client_id,
+            "x-ibm-client-secret": self._client_secret,
+            "x-unipol-tenant": self._tenant,
+        }
+        if self._token:
+            headers["Authorization"] = f"Bearer {self._token}"
+        if telematics:
+            # Fills the @HeaderMap on every TelematicsAutoService method.
+            headers["service_type"] = "Vehicle"
+            headers["company_id"] = "unipolsai"
+        return headers
+
+    async def async_login(self) -> None:
+        """Authenticate. Also establishes the F5 cookies on the session."""
+        self._token = None
+        try:
+            async with self._http.post(
+                f"{BASE_URL}login",
+                data={"username": self._username, "password": self._password},
+                headers=self._headers(),
+            ) as resp:
+                if resp.status in (401, 403):
+                    raise UnipolSaiAuthError("username or password rejected")
+                resp.raise_for_status()
+                body = await resp.json(content_type=None)
+        except aiohttp.ClientError as err:
+            raise UnipolSaiConnectionError(f"login failed: {err}") from err
+
+        # The JSON key is "token", even though the app's field is called value.
+        token = ((body or {}).get("JWT") or {}).get("token")
+        if not token:
+            raise UnipolSaiAuthError("login returned no token")
+        self._token = token
+
+    async def _get(self, path: str, telematics: bool = False, **params: Any) -> dict:
+        if self._token is None:
+            await self.async_login()
+
+        async def _do() -> tuple[int, Any]:
+            async with self._http.get(
+                BASE_URL + path,
+                params=params or None,
+                headers=self._headers(telematics),
+            ) as resp:
+                if resp.status in (401, 403):
+                    return resp.status, None
+                resp.raise_for_status()
+                return resp.status, await resp.json(content_type=None)
+
+        try:
+            status, body = await _do()
+            if status in (401, 403):
+                # 403003 "No credential" means the F5 session is gone, not
+                # just the JWT, so only a full login fixes it.
+                _LOGGER.debug("Re-authenticating after HTTP %s on %s", status, path)
+                await self.async_login()
+                status, body = await _do()
+                if status in (401, 403):
+                    raise UnipolSaiAuthError(f"still HTTP {status} after re-login")
+        except aiohttp.ClientError as err:
+            raise UnipolSaiConnectionError(f"{path} failed: {err}") from err
+
+        if isinstance(body, dict):
+            result = body.get("operationResult") or {}
+            if result.get("type") not in (0, None):
+                raise UnipolSaiError(
+                    f"{path}: {result.get('code')} {result.get('message')}"
+                )
+        return body or {}
+
+    @staticmethod
+    def _plate(vehicle: Vehicle | str) -> str:
+        return (
+            vehicle.api_plate
+            if isinstance(vehicle, Vehicle)
+            else normalise_plate(vehicle)
+        )
+
+    # -- endpoints --------------------------------------------------------
+
+    async def async_get_vehicles(self, usable_only: bool = True) -> list[Vehicle]:
+        """Vehicles with a telematics box.
+
+        Empty sections come back as `codice` 404/404404 with "Contratti non
+        trovati" inside an HTTP 200; that's a normal empty, not an error.
+        """
+        body = await self._get("api/priv/contesto-utente/v2/me/contrattiTelematici")
+        contracts = (body.get("auto") or {}).get("contrattiAuto") or []
+        vehicles = [v for c in contracts if (v := Vehicle.from_api(c))]
+        return [v for v in vehicles if v.usable] if usable_only else vehicles
+
+    async def async_get_position(
+        self, vehicle: Vehicle | str, *, force_refresh: bool = False
+    ) -> Position:
+        """Last known position.
+
+        `force_refresh` is **fire and forget**: it returns 200 immediately
+        with the *old* position and `pending_request` False, then the flag
+        goes true a few seconds later and the cycle takes about five minutes
+        to resolve. It can resolve without the position changing, which is
+        what a car parked with the engine off looks like, and that costs no
+        quota. Compare `timestamp` against the pre-request value to tell
+        success from give-up.
+
+        Plain reads are free; only a forced refresh touches the daily quota.
+        """
+        body = await self._get(
+            f"api/priv/telematici/auto/v1/vehicles/{self._plate(vehicle)}/lastPosition",
+            telematics=True,
+            # Required. Omitting it is HTTP 400 with an empty body.
+            update="true" if force_refresh else "false",
+        )
+        return Position.from_api(body.get("lastPosition"))
+
+    async def async_get_services(self, vehicle: Vehicle | str) -> dict[str, Service]:
+        """Value-added services, keyed by name."""
+        body = await self._get(
+            f"api/priv/telematici/auto/v1/vehicles/{self._plate(vehicle)}/vehicleVAS",
+            telematics=True,
+        )
+        return {
+            s["serviceName"]: Service.from_api(s)
+            for s in body.get("vehicleVAS") or []
+            if s.get("serviceName")
+        }
+
+    async def async_get_notifications(
+        self, vehicle: Vehicle | str, service: str
+    ) -> list[Notification]:
+        """Recent alert events for one service.
+
+        In practice the API returns only the single most recent event despite
+        the plural field name, so two events inside one poll interval collapse
+        into one. Reading is free; a service's credits pay for having it on.
+        """
+        body = await self._get(
+            f"api/priv/telematici/auto/v1/vehicles/"
+            f"{self._plate(vehicle)}/lastNotifications",
+            telematics=True,
+            vehicleVAS=service,
+        )
+        return [
+            Notification.from_api(n)
+            for n in body.get("serviceNotifications") or []
+            if n.get("id")
+        ]
+
+    async def async_get_usage(
+        self,
+        vehicle: Vehicle | str,
+        *,
+        date_range: str = "g",
+        start: int | None = None,
+        end: int | None = None,
+    ) -> UsageStats:
+        """Driving statistics. Free: this service needs no credits.
+
+        `date_range` is a single letter, not a word. `g` is the whole contract
+        period; `t` is a custom range and requires `start`/`end` as epoch
+        **milliseconds** (ISO dates return HTTP 500). Anything else is
+        rejected with `400100`.
+        """
+        params: dict[str, Any] = {"dateRange": date_range}
+        if date_range == "t":
+            if start is None or end is None:
+                raise ValueError("date_range 't' requires start and end")
+            params["startDate"] = start
+            params["endDate"] = end
+
+        body = await self._get(
+            f"api/priv/telematici/auto/v1/vehicles/"
+            f"{self._plate(vehicle)}/vehicleUsages",
+            telematics=True,
+            **params,
+        )
+        usages = body.get("vehicleUsages") or []
+        return UsageStats.from_api(usages[0] if usages else {})

pyunipolsai-0.1.0/src/pyunipolsai/const.py

@@ -0,0 +1,36 @@
+"""Constants for pyunipolsai."""
+
+from __future__ import annotations
+
+BASE_URL = "https://apphub.unipolsai.it/hub/"
+
+APP_VERSION = "6.3.18"
+APP_BUILD = "42642"
+
+# The gateway rejects some requests without a plausible app User-Agent; this
+# is the one the verified session used. Override it if you'd rather be honest
+# about who is calling, but test that the gateway still answers.
+DEFAULT_USER_AGENT = (
+    f"UnipolSaiApp/{APP_VERSION} Version Code {APP_BUILD} "
+    "(Android 14; sdk_gphone64_arm64; google emu64a;)"
+)
+
+# The app's IBM API Connect gateway credentials, captured from its cold-start
+# apicConfig call. App-global rather than per-user, and shipped inside a
+# public Play Store app, so no more secret than any baked-in mobile API key.
+# Overridable because Unipol can rotate them.
+DEFAULT_CLIENT_ID = "246a3dc4-9b99-47a1-859c-1840a0adf49a"
+DEFAULT_CLIENT_SECRET = "L6kT5mS5bW0pQ4qD1eT2fV8sL5qI0sD8eI5tK8sF0uI4kK1wM5"
+DEFAULT_TENANT = "e63a8acccacc90d4d4814149523bfe67f09746bf3c9221f3a6ea551e3c804283"
+
+# Alert services that emit notifications, and a stable snake_case name for
+# each. Keys are the API's own serviceName values.
+ALERT_SERVICES: dict[str, str] = {
+    "engineOn": "engine_on",
+    "carMovedEngineOff": "moved_engine_off",
+    "speedLimit": "speed_limit_exceeded",
+    "targetArea": "target_area",
+}
+
+SERVICE_CAR_FINDER = "carFinder"
+SERVICE_RANGE_STATISTICS = "rangeStatistics"

pyunipolsai-0.1.0/src/pyunipolsai/exceptions.py

@@ -0,0 +1,15 @@
+"""Exceptions raised by pyunipolsai."""
+
+from __future__ import annotations
+
+
+class UnipolSaiError(Exception):
+    """Base error, also raised for API-level `operationResult` failures."""
+
+
+class UnipolSaiConnectionError(UnipolSaiError):
+    """The API could not be reached."""
+
+
+class UnipolSaiAuthError(UnipolSaiError):
+    """Credentials were rejected, or the session could not be re-established."""

pyunipolsai-0.1.0/src/pyunipolsai/models.py

@@ -0,0 +1,322 @@
+"""Typed models for the Unipol telematics API.
+
+The API's own types are not trustworthy: dates are declared `String` in the
+app but sent as epoch milliseconds, distances are metres, times are seconds,
+`heading` is a cardinal letter rather than degrees, and `accuracy` is a small
+quality grade rather than a radius. Every one of those is normalised here so
+callers never have to know.
+"""
+
+from __future__ import annotations
+
+from dataclasses import dataclass, field
+from datetime import UTC, datetime
+from typing import Any
+
+# The API returns a cardinal letter. Degrees are offered as a convenience;
+# the resolution loss is the API's, not ours.
+HEADING_DEGREES: dict[str, float] = {
+    "N": 0,
+    "NNE": 22.5,
+    "NE": 45,
+    "ENE": 67.5,
+    "E": 90,
+    "ESE": 112.5,
+    "SE": 135,
+    "SSE": 157.5,
+    "S": 180,
+    "SSW": 202.5,
+    "SW": 225,
+    "WSW": 247.5,
+    "W": 270,
+    "WNW": 292.5,
+    "NW": 315,
+    "NNW": 337.5,
+}
+
+
+def _dt(value: Any) -> datetime | None:
+    """Epoch milliseconds to an aware datetime."""
+    if not isinstance(value, (int, float)):
+        return None
+    return datetime.fromtimestamp(value / 1000, tz=UTC)
+
+
+@dataclass(frozen=True, slots=True)
+class Quota:
+    """The daily budget for *forced* position refreshes.
+
+    Plain reads do not count against this; only `update=true` does.
+    """
+
+    used: int | None = None
+    limit: int | None = None
+
+    @property
+    def remaining(self) -> int | None:
+        """Forced refreshes left today, or None if the API did not say."""
+        if self.used is None or self.limit is None:
+            return None
+        return max(0, self.limit - self.used)
+
+    @property
+    def exhausted(self) -> bool:
+        """Whether the daily budget is spent."""
+        return self.remaining == 0
+
+    @classmethod
+    def from_api(cls, data: dict | None) -> Quota:
+        """Build from a `dailyFruitions` object."""
+        data = data or {}
+        return cls(used=data.get("current"), limit=data.get("max"))
+
+
+@dataclass(frozen=True, slots=True)
+class Position:
+    """A vehicle position reading."""
+
+    latitude: float | None = None
+    longitude: float | None = None
+    speed: int | None = None
+    heading: str | None = None
+    quality: int | None = None
+    timestamp: datetime | None = None
+    pending_request: bool = False
+    quota: Quota = field(default_factory=Quota)
+
+    @property
+    def heading_degrees(self) -> float | None:
+        """Bearing, if the cardinal letter maps to one."""
+        return HEADING_DEGREES.get(self.heading or "")
+
+    @classmethod
+    def from_api(cls, data: dict | None) -> Position:
+        """Build from a `lastPosition` object."""
+        data = data or {}
+        return cls(
+            latitude=data.get("lat"),
+            longitude=data.get("lon"),
+            speed=data.get("speed"),
+            heading=data.get("heading"),
+            # NOT metres. A small integer grade; do not pass it off as a
+            # GPS accuracy radius.
+            quality=data.get("accuracy"),
+            timestamp=_dt(data.get("date")),
+            pending_request=bool(data.get("pendingRequest")),
+            quota=Quota.from_api(data.get("dailyFruitions")),
+        )
+
+
+@dataclass(frozen=True, slots=True)
+class TelematicDevice:
+    """The black box itself."""
+
+    device_id: str | None = None
+    imei: str | None = None
+    device_type: str | None = None
+
+    @classmethod
+    def from_api(cls, data: dict | None) -> TelematicDevice:
+        """Build from a `dispositivoTelematico` object."""
+        data = data or {}
+        return cls(
+            device_id=data.get("idDispositivo"),
+            imei=data.get("imei"),
+            device_type=data.get("tipoDispositivo"),
+        )
+
+
+@dataclass(frozen=True, slots=True)
+class Vehicle:
+    """A vehicle with a Unibox on it."""
+
+    plate: str
+    make: str | None = None
+    model: str | None = None
+    contract_id: str | None = None
+    contract_open: bool = False
+    terminal_active: bool = False
+    device: TelematicDevice = field(default_factory=TelematicDevice)
+
+    @property
+    def api_plate(self) -> str:
+        """Country-prefixed plate, which is what every path segment wants."""
+        return normalise_plate(self.plate)
+
+    @property
+    def usable(self) -> bool:
+        """Whether it's worth talking to this vehicle at all."""
+        return self.contract_open and self.terminal_active
+
+    @classmethod
+    def from_api(cls, data: dict | None) -> Vehicle | None:
+        """Build from one contract, or None if it carries no plate."""
+        data = data or {}
+        vehicle = data.get("veicolo") or {}
+        plate = vehicle.get("targa")
+        if not plate:
+            return None
+        return cls(
+            plate=plate,
+            make=vehicle.get("marca"),
+            model=vehicle.get("modello"),
+            contract_id=data.get("identificativoTelematico"),
+            contract_open=data.get("statoContratto") == "open",
+            terminal_active=data.get("statoTerminale") == "active",
+            device=TelematicDevice.from_api(data.get("dispositivoTelematico")),
+        )
+
+
+@dataclass(frozen=True, slots=True)
+class Service:
+    """One value-added service on the box.
+
+    `credits_available` is a slower, separate budget from `Quota`: it pays for
+    having the service switched on, not for each read.
+    """
+
+    name: str
+    enabled: bool = False
+    activated: bool = False
+    requires_credits: bool = False
+    credits_available: int | None = None
+    credits_used: int | None = None
+    recharge_owner: str | None = None
+
+    @classmethod
+    def from_api(cls, data: dict) -> Service:
+        """Build from one `vehicleVAS` entry."""
+        return cls(
+            name=data["serviceName"],
+            enabled=bool(data.get("isServiceEnabled")),
+            activated=bool(data.get("isServiceActivated")),
+            requires_credits=bool(data.get("serviceRequiredCredits")),
+            credits_available=data.get("serviceAvailableCredits"),
+            credits_used=data.get("serviceCreditUsed"),
+            recharge_owner=data.get("rechargeOwnership"),
+        )
+
+
+@dataclass(frozen=True, slots=True)
+class Notification:
+    """An alert event produced by one service.
+
+    Carries its own coordinates, which are where the event happened and are
+    independent of the vehicle's current position.
+    """
+
+    id: str
+    occurred_at: datetime | None = None
+    latitude: float | None = None
+    longitude: float | None = None
+    speed: int | None = None
+    speed_limit: int | None = None
+    plate: str | None = None
+    provider: str | None = None
+
+    @classmethod
+    def from_api(cls, data: dict) -> Notification:
+        """Build from one `serviceNotifications` entry."""
+        return cls(
+            id=data["id"],
+            occurred_at=_dt(data.get("eventDate")),
+            latitude=data.get("latitude"),
+            longitude=data.get("longitude"),
+            speed=data.get("speed"),
+            # Zeroed for services where it has no meaning, e.g. engineOn.
+            speed_limit=data.get("speedLimitValue") or None,
+            plate=data.get("vehiclePlate"),
+            provider=data.get("tspName"),
+        )
+
+
+@dataclass(frozen=True, slots=True)
+class UsageStats:
+    """Driving statistics.
+
+    The API sends **metres** and **seconds**. Raw values are kept as sent and
+    the convenience properties convert, so nothing is lost to rounding.
+    """
+
+    raw: dict[str, Any] = field(default_factory=dict)
+
+    @property
+    def period_start(self) -> datetime | None:
+        """Start of the window these figures cover."""
+        return _dt(self.raw.get("fromDate"))
+
+    @property
+    def period_end(self) -> datetime | None:
+        """End of the window these figures cover."""
+        return _dt(self.raw.get("toDate"))
+
+    @property
+    def days_analysed(self) -> int | None:
+        """How many days went into the analysis."""
+        return self.raw.get("totalDaysUsedForAnalysis")
+
+    @property
+    def top_province(self) -> str | None:
+        """Province with the most distance driven in it."""
+        return self.raw.get("higherMileageProvinceFullName")
+
+    @property
+    def top_province_share(self) -> float | None:
+        """Percentage of distance driven in that province."""
+        return self.raw.get("higherMileageProvinceDrivingPerc")
+
+    def distance_m(self, kind: str = "total") -> int | None:
+        """Distance in metres.
+
+        `kind` is total, city, extraUrban, highway, other, daylight, or a
+        weekday name such as monday.
+        """
+        return self.raw.get(_DISTANCE_FIELDS.get(kind, kind))
+
+    def distance_km(self, kind: str = "total") -> float | None:
+        """Distance in kilometres, rounded to one decimal."""
+        value = self.distance_m(kind)
+        return None if value is None else round(value / 1000, 1)
+
+    def time_s(self, kind: str = "total") -> int | None:
+        """Driving time in seconds, same `kind` vocabulary as distance."""
+        return self.raw.get(_TIME_FIELDS.get(kind, kind))
+
+    def time_h(self, kind: str = "total") -> float | None:
+        """Driving time in hours, rounded to two decimals."""
+        value = self.time_s(kind)
+        return None if value is None else round(value / 3600, 2)
+
+    @classmethod
+    def from_api(cls, data: dict | None) -> UsageStats:
+        """Build from one `vehicleUsages` entry."""
+        return cls(raw=data or {})
+
+
+_KINDS = (
+    "total",
+    "city",
+    "extraUrban",
+    "highway",
+    "other",
+    "daylight",
+    "monday",
+    "tuesday",
+    "wednesday",
+    "thursday",
+    "friday",
+    "saturday",
+    "sunday",
+)
+_DISTANCE_FIELDS = {
+    k: ("totalDistance" if k == "total" else f"{k}DrivingDistance") for k in _KINDS
+}
+_TIME_FIELDS = {
+    k: ("totalDrivingTime" if k == "total" else f"{k}DrivingTime") for k in _KINDS
+}
+
+
+def normalise_plate(plate: str) -> str:
+    """`AB123CD` to `IT-AB123CD`. A bare plate is rejected by the API."""
+    plate = plate.strip().upper().replace(" ", "")
+    return plate if "-" in plate else f"IT-{plate}"

pyunipolsai-0.1.0/tests/fixtures/contracts.json

@@ -0,0 +1,13 @@
+{"auto": {"contrattiAuto": [
+  {"identificativoTelematico": "27778190", "statoContratto": "open",
+   "statoTerminale": "active",
+   "veicolo": {"tipo": 1, "marca": "VOLKSWAGEN", "modello": "T-ROC", "targa": "AB123CD"},
+   "dispositivoTelematico": {"idDispositivo": "999", "tipoDispositivo": "F",
+                             "imei": "000000000000000"}},
+  {"identificativoTelematico": "111", "statoContratto": "open",
+   "statoTerminale": "inactive",
+   "veicolo": {"marca": "FIAT", "modello": "PANDA", "targa": "ZZ999ZZ"},
+   "dispositivoTelematico": {}}],
+  "codice": 200200},
+ "immobili": {"contrattiImmobili": [], "codice": 404404, "message": "Contratti non trovati"},
+ "pet": {"contrattiPet": [], "codice": 404, "message": "Contratti non trovati"}}

pyunipolsai-0.1.0/tests/fixtures/last_position.json

@@ -0,0 +1,5 @@
+{"operationResult": {"type": 0},
+ "lastPosition": {"date": 1789889311000, "lat": 45.4642, "lon": 9.19,
+   "speed": 0, "heading": "N", "timeZone": 0, "daylightSavingTime": 0,
+   "accuracy": 1, "pendingRequest": false,
+   "dailyFruitions": {"current": 0, "max": 5}}}

pyunipolsai-0.1.0/tests/fixtures/notifications.json

@@ -0,0 +1,7 @@
+{"operationResult": {"type": 0},
+ "serviceNotifications": [
+  {"id": "68b1e071-0000-0000-0000-000000000000", "voucherId": "27778190",
+   "eventDate": 1789885957000, "userCode": "XXXXXX00X00X000X",
+   "vehiclePlate": "IT-AB123CD", "tspName": "Alfa", "accuracy": 1,
+   "latitude": 45.48, "longitude": 9.2, "speed": 0, "speedLimitValue": 0,
+   "targetAreaLatitude": 0.0, "targetAreaLongitude": 0.0, "targetAreaRadius": 0}]}

pyunipolsai-0.1.0/tests/fixtures/usage.json

@@ -0,0 +1,7 @@
+{"operationResult": {"type": 0},
+ "vehicleUsages": [{"statisticsDate": 1789689600000, "fromDate": 1781913600000,
+  "toDate": 1789689600000, "totalDistance": 5431730, "totalDrivingTime": 420215,
+  "cityDrivingDistance": 1378360, "highwayDrivingDistance": 1888260,
+  "cityDrivingTime": 149951, "mondayDrivingDistance": 749450,
+  "higherMileageProvince": "XX", "higherMileageProvinceFullName": "Province",
+  "higherMileageProvinceDrivingPerc": 41.58, "totalDaysUsedForAnalysis": 91}]}

pyunipolsai-0.1.0/tests/fixtures/vehicle_vas.json

@@ -0,0 +1,8 @@
+{"operationResult": {"type": 0},
+ "vehicleVAS": [
+  {"serviceName": "carFinder", "isServiceEnabled": true, "isServiceActivated": true,
+   "serviceRequiredCredits": true, "serviceAvailableCredits": 9,
+   "serviceCreditUsed": 1, "rechargeOwnership": "Unipol"},
+  {"serviceName": "rangeStatistics", "isServiceEnabled": true,
+   "isServiceActivated": true, "serviceRequiredCredits": false,
+   "rechargeOwnership": "Unipol"}]}

pyunipolsai-0.1.0/tests/test_models.py

@@ -0,0 +1,190 @@
+"""Model tests.
+
+Fixtures are real payloads captured from the live API, with identifiers
+replaced. They exist mainly to pin the parts of this API that are
+counter-intuitive: epoch-millisecond dates declared as strings, distances in
+metres, a cardinal-letter heading, and an `accuracy` that is a grade rather
+than a radius.
+"""
+
+from __future__ import annotations
+
+import json
+from datetime import UTC, datetime
+from pathlib import Path
+
+import pytest
+from pyunipolsai.models import normalise_plate
+
+from pyunipolsai import Notification, Position, Service, UsageStats, Vehicle
+
+FIXTURES = Path(__file__).parent / "fixtures"
+
+
+def load(name: str) -> dict:
+    return json.loads((FIXTURES / f"{name}.json").read_text())
+
+
+@pytest.mark.parametrize(
+    ("raw", "expected"),
+    [
+        ("AB123CD", "IT-AB123CD"),
+        ("ab123cd", "IT-AB123CD"),
+        (" ab 123 cd ", "IT-AB123CD"),
+        ("IT-AB123CD", "IT-AB123CD"),
+    ],
+)
+def test_normalise_plate(raw: str, expected: str) -> None:
+    assert normalise_plate(raw) == expected
+
+
+class TestPosition:
+    def test_parses_real_payload(self) -> None:
+        position = Position.from_api(load("last_position")["lastPosition"])
+        assert position.latitude == 45.4642
+        assert position.longitude == 9.19
+        assert position.speed == 0
+        assert position.pending_request is False
+
+    def test_date_is_epoch_millis_not_a_string(self) -> None:
+        """The app declares this field String; the wire sends a number."""
+        position = Position.from_api(load("last_position")["lastPosition"])
+        assert position.timestamp == datetime(2026, 9, 20, 7, 28, 31, tzinfo=UTC)
+
+    def test_heading_is_cardinal_with_degrees_derived(self) -> None:
+        position = Position.from_api({"heading": "NE"})
+        assert position.heading == "NE"
+        assert position.heading_degrees == 45
+
+    def test_unknown_heading_has_no_degrees(self) -> None:
+        assert Position.from_api({"heading": "??"}).heading_degrees is None
+
+    def test_accuracy_is_exposed_as_quality_not_metres(self) -> None:
+        """Naming matters here: 1 is a grade, not a one-metre fix."""
+        position = Position.from_api(load("last_position")["lastPosition"])
+        assert position.quality == 1
+        assert not hasattr(position, "accuracy")
+
+    def test_empty_payload_is_survivable(self) -> None:
+        position = Position.from_api(None)
+        assert position.latitude is None
+        assert position.quota.remaining is None
+
+
+class TestQuota:
+    def test_remaining_and_exhausted(self) -> None:
+        quota = Position.from_api(load("last_position")["lastPosition"]).quota
+        assert (quota.used, quota.limit) == (0, 5)
+        assert quota.remaining == 5
+        assert quota.exhausted is False
+
+    def test_exhausted_when_spent(self) -> None:
+        quota = Position.from_api({"dailyFruitions": {"current": 5, "max": 5}}).quota
+        assert quota.remaining == 0
+        assert quota.exhausted is True
+
+    def test_never_goes_negative(self) -> None:
+        quota = Position.from_api({"dailyFruitions": {"current": 9, "max": 5}}).quota
+        assert quota.remaining == 0
+
+
+class TestVehicle:
+    def test_parses_and_prefixes_plate(self) -> None:
+        contracts = load("contracts")["auto"]["contrattiAuto"]
+        vehicle = Vehicle.from_api(contracts[0])
+        assert vehicle is not None
+        assert vehicle.plate == "AB123CD"
+        assert vehicle.api_plate == "IT-AB123CD"
+        assert vehicle.make == "VOLKSWAGEN"
+        assert vehicle.device.imei == "000000000000000"
+        assert vehicle.usable is True
+
+    def test_inactive_terminal_is_not_usable(self) -> None:
+        contracts = load("contracts")["auto"]["contrattiAuto"]
+        vehicle = Vehicle.from_api(contracts[1])
+        assert vehicle is not None
+        assert vehicle.terminal_active is False
+        assert vehicle.usable is False
+
+    def test_missing_plate_yields_nothing(self) -> None:
+        assert Vehicle.from_api({"veicolo": {}}) is None
+
+
+class TestService:
+    def test_parses_credit_pool(self) -> None:
+        services = {
+            s["serviceName"]: Service.from_api(s)
+            for s in load("vehicle_vas")["vehicleVAS"]
+        }
+        car_finder = services["carFinder"]
+        assert car_finder.activated is True
+        assert car_finder.requires_credits is True
+        assert car_finder.credits_available == 9
+
+    def test_statistics_needs_no_credits(self) -> None:
+        services = {
+            s["serviceName"]: Service.from_api(s)
+            for s in load("vehicle_vas")["vehicleVAS"]
+        }
+        assert services["rangeStatistics"].requires_credits is False
+
+
+class TestNotification:
+    def test_parses_real_payload(self) -> None:
+        raw = load("notifications")["serviceNotifications"][0]
+        notification = Notification.from_api(raw)
+        assert notification.occurred_at == datetime(2026, 9, 20, 6, 32, 37, tzinfo=UTC)
+        assert notification.latitude == 45.48
+        assert notification.provider == "Alfa"
+
+    def test_zero_speed_limit_becomes_none(self) -> None:
+        """Zeroed fields become None.
+
+        `speedLimitValue` is shared across alert types and comes back zero
+        where it has no meaning, e.g. for engineOn.
+        """
+        raw = load("notifications")["serviceNotifications"][0]
+        assert Notification.from_api(raw).speed_limit is None
+
+
+class TestUsageStats:
+    def test_converts_metres_and_seconds(self) -> None:
+        usage = UsageStats.from_api(load("usage")["vehicleUsages"][0])
+        assert usage.distance_m("total") == 5431730
+        assert usage.distance_km("total") == 5431.7
+        assert usage.time_s("total") == 420215
+        assert usage.time_h("total") == 116.73
+
+    def test_average_speed_is_plausible(self) -> None:
+        """Sanity-check the units.
+
+        Metres over seconds should land in a believable range for mixed
+        driving. Treating distance as kilometres would put this at about
+        46,000 km/h.
+        """
+        usage = UsageStats.from_api(load("usage")["vehicleUsages"][0])
+        kmh = usage.distance_km() / usage.time_h()
+        assert 20 < kmh < 90
+
+    def test_breakdowns(self) -> None:
+        usage = UsageStats.from_api(load("usage")["vehicleUsages"][0])
+        assert usage.distance_km("city") == 1378.4
+        assert usage.distance_km("highway") == 1888.3
+        assert usage.distance_km("monday") == 749.5
+        assert usage.time_h("city") == 41.65
+
+    def test_metadata(self) -> None:
+        usage = UsageStats.from_api(load("usage")["vehicleUsages"][0])
+        assert usage.days_analysed == 91
+        assert usage.top_province == "Province"
+        assert usage.top_province_share == 41.58
+        # Equals the contract's dataInizio: dateRange 'g' really is
+        # "everything since the policy started".
+        assert usage.period_start == datetime(2026, 6, 20, 0, 0, tzinfo=UTC)
+
+    def test_unknown_kind_is_none_not_a_crash(self) -> None:
+        usage = UsageStats.from_api(load("usage")["vehicleUsages"][0])
+        assert usage.distance_km("spaceship") is None
+
+    def test_empty_payload(self) -> None:
+        assert UsageStats.from_api(None).distance_km() is None