py-livewire 0.1.0__py3-none-any.whl

py_livewire/client.py

@@ -0,0 +1,971 @@
+"""Async client of the LiveWire mobile API, modeled on the LiveWire EV app 1.9.0.
+
+The backend only answers the charging status for device UUIDs that are paired with
+the bike (other vehicle data like the position was served to unpaired UUIDs in
+testing). The UUID is generated by the client; pairing it is a cloud flow where the
+bike shows a code on its display that is sent back to the backend, see Client.pair().
+"""
+
+import asyncio
+import inspect
+import json
+import uuid
+from collections.abc import Awaitable, Callable, Collection, Iterable
+from datetime import UTC, datetime, time
+from typing import Any
+
+import aiohttp
+
+from . import const
+from .auth import Authenticator, jwt_subject
+from .exceptions import ApiError, NotPairedError, PairingError
+from .models import (
+    Bike,
+    ChargingSchedule,
+    ChargingStatus,
+    Location,
+    PairedUser,
+    SoftwareVersion,
+    TirePressure,
+)
+from .utils import to_bool, to_int
+
+BikeId = str | int
+
+_PAIRING_ERRORS = {
+    400: "the bike must be switched on, not in propulsion mode and not charging",
+    402: "the bike has no cellular connection",
+}
+
+_MAINTENANCE_OK = (const.CODE_OK, const.CODE_MAINTENANCE_OK)
+
+
+def _field(data: Any, *keys: str) -> Any:
+    for key in keys:
+        if not isinstance(data, dict):
+            return None
+        data = data.get(key)
+    return data
+
+
+def _dict(data: Any, *keys: str) -> dict[str, Any] | None:
+    res = _field(data, *keys)
+    return res if isinstance(res, dict) else None
+
+
+def _list(data: Any, *keys: str) -> list[Any]:
+    res = _field(data, *keys)
+    return res if isinstance(res, list) else []
+
+
+def _query(params: dict[str, Any] | None) -> list[tuple[str, str]]:
+    """Encode params like Retrofit: skip None, lowercase booleans, repeat lists."""
+    res = []
+    for key, value in (params or {}).items():
+        for v in value if isinstance(value, (list, tuple)) else [value]:
+            if v is not None:
+                res.append((key, str(v).lower() if isinstance(v, bool) else str(v)))
+    return res
+
+
+def _parse(text: str) -> Any:
+    if not text.strip():
+        return None
+    try:
+        return json.loads(text)
+    except ValueError:
+        return text
+
+
+def _error_message(data: Any, default: str) -> str:
+    if isinstance(data, dict):
+        error = data["error"] if isinstance(data.get("error"), dict) else data
+        for key in ("description", "detail", "message", "title"):
+            if error.get(key):
+                return str(error[key])
+    return default
+
+
+def _raise_for_error(
+    status: int, data: Any, ok_codes: Collection[str] = (const.CODE_OK,)
+) -> None:
+    """Raise for an error envelope, which mostly comes with HTTP 200, or HTTP error."""
+    error = _field(data, "error")
+    if isinstance(error, dict) and error:
+        code = None if error.get("code") is None else str(error["code"])
+        if code not in ok_codes:
+            message = f"{_error_message(data, 'unknown error')} (code {code})"
+            if code == const.CODE_NOT_PAIRED:
+                raise NotPairedError(
+                    f"{message}: device UUID not paired with the bike "
+                    "or bike not reachable",
+                    code=code,
+                    status=status,
+                )
+            raise ApiError(message, code=code, status=status)
+
+    if status >= 400:
+        raise ApiError(_error_message(data, f"HTTP {status}"), status=status)
+
+
+def _local_utc_offset() -> int:
+    offset = datetime.now().astimezone().utcoffset()
+    return int(offset.total_seconds() // 60) if offset else 0
+
+
+def _day(day: str) -> str:
+    name = day.strip()[:3].capitalize()
+    if name not in const.DAYS:
+        raise ValueError(
+            f"invalid day {day!r}, expected one of {', '.join(const.DAYS)}"
+        )
+    return name
+
+
+def _schedule_body(
+    days: Iterable[str], start: time, end: time, utc_offset_minutes: int | None
+) -> dict[str, Any]:
+    return {
+        "timezoneOffsetMinutes": _local_utc_offset()
+        if utc_offset_minutes is None
+        else utc_offset_minutes,
+        "days": [_day(d) for d in days],
+        "time": {"start": start.strftime("%H:%M"), "end": end.strftime("%H:%M")},
+    }
+
+
+def _now() -> str:
+    # The app sends the current instant, the backend returns all periods up to it
+    return datetime.now(UTC).isoformat(timespec="milliseconds").replace("+00:00", "Z")
+
+
+class Client:
+    """Client of the LiveWire mobile API.
+
+    device_uuid identifies this client to the backend. Without one a random UUID is
+    generated, which has to be paired with the bike (see pair()) before the charging
+    status is available. Keep the UUID after pairing and pass it in again later. The
+    UUID of a phone that is already paired works as well.
+    """
+
+    def __init__(
+        self,
+        email: str,
+        password: str,
+        device_uuid: str | None = None,
+        *,
+        session: aiohttp.ClientSession | None = None,
+        device_model: str = const.DEVICE_MODEL,
+        os_version: str = const.OS_VERSION,
+        language: str = const.LANGUAGE,
+        api_url: str = const.API_URL,
+        gigya_url: str = const.GIGYA_URL,
+    ):
+        if device_uuid is None:
+            device_uuid = str(uuid.uuid4())
+        else:
+            # validate, but keep the spelling: the backend may compare it as string
+            uuid.UUID(device_uuid)
+
+        self._device_uuid = device_uuid
+        self._session = session
+        self._owns_session = session is None
+        self._api_url = api_url.rstrip("/")
+        self._language = language
+        self._headers = {
+            "User-Agent": "Android",
+            "Content-Type": "application/json",
+            "Accept-Language": language,
+            "model": device_model,
+            "osVersion": os_version,
+        }
+        self._auth = Authenticator(
+            email,
+            password,
+            device_uuid,
+            self._headers,
+            gigya_url=gigya_url.rstrip("/"),
+            api_url=self._api_url,
+        )
+
+    async def __aenter__(self) -> "Client":
+        return self
+
+    async def __aexit__(self, *exc: object) -> None:
+        await self.close()
+
+    async def close(self) -> None:
+        if self._owns_session and self._session is not None:
+            await self._session.close()
+            self._session = None
+
+    @property
+    def device_uuid(self) -> str:
+        return self._device_uuid
+
+    @property
+    def user_id(self) -> str | None:
+        """The backend's UUID of the account, known after logging in."""
+        token = self._auth.token
+        return jwt_subject(token) if token else None
+
+    async def login(self) -> None:
+        """Log in. Optional, the first request logs in on demand."""
+        await self._auth.get_token(self._get_session())
+
+    def _get_session(self) -> aiohttp.ClientSession:
+        if self._session is None:
+            self._session = aiohttp.ClientSession()
+            self._owns_session = True
+        return self._session
+
+    async def _fetch(
+        self,
+        method: str,
+        url: str,
+        query: list[tuple[str, str]],
+        body: Any,
+        headers: dict[str, str] | None,
+    ) -> tuple[int, Any]:
+        async with self._get_session().request(
+            method, url, params=query, json=body, headers=headers
+        ) as resp:
+            return resp.status, _parse(await resp.text())
+
+    async def _send(
+        self,
+        method: str,
+        path: str,
+        *,
+        params: dict[str, Any] | None = None,
+        body: Any = None,
+        authed: bool = True,
+    ) -> tuple[int, Any]:
+        url = f"{self._api_url}/{path}"
+        if not authed:
+            return await self._fetch(method, url, _query(params), body, None)
+
+        query = _query({**(params or {}), "brand": const.BRAND})
+        token = await self._auth.get_token(self._get_session())
+        status, data = await self._fetch(
+            method,
+            url,
+            query,
+            body,
+            {**self._headers, "Authorization": f"Bearer {token}"},
+        )
+
+        if status == 401:
+            # The token expired, log in again once
+            token = await self._auth.refresh(self._get_session(), token)
+            status, data = await self._fetch(
+                method,
+                url,
+                query,
+                body,
+                {**self._headers, "Authorization": f"Bearer {token}"},
+            )
+
+        return status, data
+
+    async def _request(
+        self,
+        method: str,
+        path: str,
+        *,
+        params: dict[str, Any] | None = None,
+        body: Any = None,
+        ok_codes: Collection[str] = (const.CODE_OK,),
+        authed: bool = True,
+    ) -> Any:
+        status, data = await self._send(
+            method, path, params=params, body=body, authed=authed
+        )
+        _raise_for_error(status, data, ok_codes)
+        return data
+
+    # Bikes
+
+    async def get_bikes(self) -> list[Bike]:
+        """Bikes of the account, with whether this device UUID is paired with each."""
+        data = await self._request(
+            "GET", "getAllbikes/pairingStatus", params={"deviceUUID": self._device_uuid}
+        )
+        return [Bike.from_dict(b) for b in _list(data, "bikes")]
+
+    async def get_vin_info(self, vin: str) -> dict[str, Any] | None:
+        """Model, year and color of a VIN, as used for adding a bike."""
+        return _dict(await self._request("GET", f"newvinApi/lookup/{vin}"), "vin")
+
+    async def add_bike(self, bike: dict[str, Any]) -> dict[str, Any] | None:
+        """Add a bike to the account.
+
+        The app fills name, vin, make, model, modelNumber, modelCode, brandShortName,
+        year and color from get_vin_info(), and ownerProfileId with user_id.
+        """
+        return _dict(await self._request("POST", "bike", body=bike), "data", "bike")
+
+    async def update_bike(
+        self, bike_id: BikeId, bike: dict[str, Any]
+    ) -> dict[str, Any] | None:
+        """Change a bike, e.g. its name. bike carries all fields as for add_bike()."""
+        return _dict(
+            await self._request("PUT", f"bike/{bike_id}", body=bike), "data", "bike"
+        )
+
+    async def delete_bike(self, bike_id: BikeId) -> None:
+        """Remove a bike from the account."""
+        await self._request("DELETE", f"bike/{bike_id}")
+
+    # Pairing
+
+    async def is_paired(self, bike_id: BikeId) -> bool:
+        """Whether this device UUID is paired with the bike."""
+        data = await self._request(
+            "GET",
+            f"bikes/pairing/status/{bike_id}",
+            params={"deviceUUID": self._device_uuid},
+        )
+        return bool(to_bool(_field(data, "pairingStatus")))
+
+    async def request_pairing_code(self, bike_id: BikeId) -> None:
+        """Make the bike show a code on its display to pair this device UUID.
+
+        The bike must be switched on, not in propulsion mode and not charging, and
+        needs cellular reception. There is no working endpoint to cancel the request,
+        an unused code just expires.
+        """
+        data = await self._request(
+            "POST", f"bikes/{bike_id}/pair", params={"deviceUUID": self._device_uuid}
+        )
+
+        status = to_int(_field(data, "status"))
+        if status not in (None, 200):
+            reason = _PAIRING_ERRORS.get(status) or _error_message(
+                data, "pairing request failed"
+            )
+            raise PairingError(f"{reason} (status {status})", code=status)
+
+    async def verify_pairing_code(self, bike_id: BikeId, code: str) -> None:
+        """Send back the code the bike shows to complete pairing this device UUID."""
+        status, data = await self._send(
+            "POST",
+            f"bikes/{bike_id}/verify/code",
+            params={"deviceUUID": self._device_uuid},
+            body={"code": code},
+        )
+
+        result = to_int(_field(data, "code")) or to_int(_field(data, "error", "code"))
+        if result == const.CODE_ATTEMPTS_EXCEEDED:
+            raise PairingError("too many wrong codes, request a new one", code=result)
+        if result == const.CODE_WRONG_CODE:
+            raise PairingError("wrong code", code=result)
+
+        _raise_for_error(status, data)
+
+    async def pair(
+        self,
+        bike_id: BikeId,
+        get_code: Callable[[], str | Awaitable[str]],
+        *,
+        timeout: float = 60,
+        interval: float = 5,
+    ) -> None:
+        """Pair this device UUID with a bike.
+
+        Requests a pairing code, calls get_code() (plain or coroutine function) to
+        obtain the code shown on the bike's display, verifies it and waits until the
+        backend confirms the pairing. See request_pairing_code() for the bike's
+        required state.
+        """
+        await self.request_pairing_code(bike_id)
+
+        code = get_code()
+        if inspect.isawaitable(code):
+            code = await code
+        await self.verify_pairing_code(bike_id, str(code).strip())
+
+        loop = asyncio.get_running_loop()
+        deadline = loop.time() + timeout
+        while not await self.is_paired(bike_id):
+            if loop.time() >= deadline:
+                raise PairingError("the bike did not confirm the pairing")
+            await asyncio.sleep(interval)
+
+    async def get_paired_users(self, bike_id: BikeId) -> list[PairedUser]:
+        """Users and devices paired with a bike.
+
+        The backend answered this with HTTP 401 in testing, even for a paired device
+        UUID, so expect an ApiError.
+        """
+        data = await self._request(
+            "GET",
+            f"bikes/paired/users/{bike_id}",
+            params={"deviceUUID": self._device_uuid},
+        )
+        return [PairedUser.from_dict(u) for u in _list(data, "users")]
+
+    async def _unpair_params(
+        self, device_uuid: str | None, user_id: str | None
+    ) -> dict[str, Any]:
+        if user_id is None:
+            await self.login()
+            user_id = self.user_id
+        return {"deviceUUID": device_uuid or self._device_uuid, "userUUID": user_id}
+
+    async def request_unpairing_code(
+        self,
+        bike_id: BikeId,
+        device_uuid: str | None = None,
+        user_id: str | None = None,
+    ) -> None:
+        """Make the bike show a code to unpair a device, by default this client's own.
+
+        Even though this is a GET request, it triggers the code on the bike's display.
+        """
+        params = await self._unpair_params(device_uuid, user_id)
+        data = await self._request("GET", f"bikes/{bike_id}/unpair", params=params)
+
+        status = to_int(_field(data, "status"))
+        if status not in (None, 200):
+            raise PairingError(
+                f"{_error_message(data, 'unpairing request failed')} (status {status})",
+                code=status,
+            )
+
+    async def verify_unpairing_code(
+        self,
+        bike_id: BikeId,
+        code: str,
+        device_uuid: str | None = None,
+        user_id: str | None = None,
+    ) -> None:
+        """Send back the code the bike shows to complete unpairing a device."""
+        params = await self._unpair_params(device_uuid, user_id)
+        data = await self._request(
+            "POST",
+            f"bikes/{bike_id}/verify/unpair/code",
+            params=params,
+            body={"code": code},
+        )
+
+        status = to_int(_field(data, "status"))
+        if status not in (None, 200):
+            raise PairingError(
+                f"{_error_message(data, 'unpairing failed')} (status {status})",
+                code=status,
+            )
+
+    # Vehicle data
+
+    async def get_charging_status(self, bike_id: BikeId) -> ChargingStatus:
+        """Battery, charging, range and odometer data, queried from the bike.
+
+        Raises NotPairedError if this device UUID is not paired with the bike, or if the
+        backend cannot reach the bike.
+        """
+        data = await self._request(
+            "GET",
+            f"bikes/{bike_id}/charging/status",
+            ok_codes=(const.CODE_OK, const.CODE_PARTIAL),
+        )
+        return ChargingStatus.from_dict(data if isinstance(data, dict) else {})
+
+    async def get_location(self, bike_id: BikeId) -> Location:
+        """The last GPS position the bike reported."""
+        data = await self._request("GET", f"bike/{bike_id}/location")
+        return Location.from_dict(_dict(data, "data") or {})
+
+    async def get_tire_pressure(
+        self, bike_id: BikeId, model_code: str | None = None
+    ) -> TirePressure | None:
+        """Tire pressures, None if none reported. The app passes Bike.model_code."""
+        data = await self._request(
+            "GET", f"bikes/{bike_id}/status/tpms", params={"modelCode": model_code}
+        )
+        if not isinstance(data, dict) or to_int(data.get("code")) == const.CODE_NO_DATA:
+            return None
+        return TirePressure.from_dict(data)
+
+    async def get_software_versions(self) -> list[SoftwareVersion]:
+        """Installed and available vehicle software versions of the paired bikes."""
+        data = await self._request("GET", "bike/vsb-versions")
+        return [SoftwareVersion.from_dict(b) for b in _list(data, "bikes")]
+
+    async def get_software_release_notes(
+        self, bike_id: BikeId, versions: Iterable[str]
+    ) -> list[dict[str, Any]]:
+        """Release notes of vehicle software versions, e.g. SoftwareVersion.latest."""
+        data = await self._request(
+            "POST",
+            f"bike/{bike_id}/vsb-descriptions",
+            body={"vsbVersions": list(versions)},
+        )
+        return _list(data, "data")
+
+    async def get_charging_analytics(self, bike_id: BikeId) -> dict[str, Any] | None:
+        """Charging sessions and energy for the WEEK, MONTH, 3M and 6M periods."""
+        return _dict(
+            await self._request(
+                "GET", f"bikes/{bike_id}/charging/analytics", params={"date": _now()}
+            )
+        )
+
+    async def get_ride_analytics(self, bike_id: BikeId) -> dict[str, Any] | None:
+        """Rides, distance and efficiency for the WEEK, MONTH, 3M and 6M periods."""
+        return _dict(
+            await self._request(
+                "GET", f"bikes/{bike_id}/ride/analytics", params={"date": _now()}
+            )
+        )
+
+    async def set_enhanced_tracking(self, bike_id: BikeId, enabled: bool) -> str | None:
+        """Switch enhanced vehicle tracking of a stolen bike on or off.
+
+        While on, the bike reports its position every few minutes. Returns the tracking
+        status (STOLEN, SAFE or PENDING), which get_charging_status() reports as well.
+        """
+        data = await self._request(
+            "POST",
+            f"bikes/{bike_id}/tracking",
+            body={
+                "bikeId": str(bike_id),
+                "securityType": "STOLEN" if enabled else "SAFE",
+            },
+        )
+        status = _field(data, "securityType")
+        return None if status is None else str(status)
+
+    async def set_tracking_consent(self, bike_id: BikeId, consent: bool) -> None:
+        """Accept or decline the terms of enhanced vehicle tracking."""
+        await self._request(
+            "POST",
+            f"bikes/{bike_id}/terms",
+            body={"bikeId": str(bike_id), "consent": consent},
+        )
+
+    # Charging control
+
+    async def set_charge_limit(self, bike_id: BikeId, limit: int) -> None:
+        """Set the charge limit in percent, the app offers 70 to 100."""
+        await self._request(
+            "POST", f"bikes/{bike_id}/charging/limit", params={"maxLimit": limit}
+        )
+
+    async def start_charging(self, bike_id: BikeId) -> None:
+        """Start charging right away instead of waiting for a charging schedule."""
+        data = await self._request("POST", f"bikes/{bike_id}/charging/schedules/start")
+
+        status = to_int(_field(data, "status"))
+        if status is not None and status >= 400:
+            raise ApiError(
+                _error_message(data, "starting to charge failed"), status=status
+            )
+
+    async def get_charging_schedules(self, bike_id: BikeId) -> list[ChargingSchedule]:
+        data = await self._request("GET", f"bikes/{bike_id}/charging/schedules")
+        return [ChargingSchedule.from_dict(s) for s in _list(data, "schedules")]
+
+    async def add_charging_schedule(
+        self,
+        bike_id: BikeId,
+        days: Iterable[str],
+        start: time,
+        end: time,
+        *,
+        utc_offset_minutes: int | None = None,
+    ) -> ChargingSchedule:
+        """Add a charging window on the given days ("Mon" to "Sun").
+
+        start and end are local times at utc_offset_minutes, which defaults to the
+        offset of this machine. The window may cross midnight. The app allows up to 5
+        schedules.
+        """
+        data = await self._request(
+            "POST",
+            f"bikes/{bike_id}/charging/schedules",
+            body=_schedule_body(days, start, end, utc_offset_minutes),
+        )
+        return ChargingSchedule.from_dict(data if isinstance(data, dict) else {})
+
+    async def update_charging_schedule(
+        self,
+        bike_id: BikeId,
+        schedule_id: str,
+        days: Iterable[str],
+        start: time,
+        end: time,
+        *,
+        utc_offset_minutes: int | None = None,
+    ) -> ChargingSchedule:
+        """Change a charging schedule, see add_charging_schedule().
+
+        The app disables a schedule by setting no days.
+        """
+        data = await self._request(
+            "PUT",
+            f"bikes/{bike_id}/charging/schedules/{schedule_id}",
+            body=_schedule_body(days, start, end, utc_offset_minutes),
+        )
+        return ChargingSchedule.from_dict(data if isinstance(data, dict) else {})
+
+    async def delete_charging_schedule(self, bike_id: BikeId, schedule_id: str) -> bool:
+        """Delete a charging schedule, False if the bike has yet to confirm it."""
+        status, data = await self._send(
+            "DELETE", f"bikes/{bike_id}/charging/schedules/{schedule_id}"
+        )
+        _raise_for_error(status, data)
+        return status == 204
+
+    # Maintenance and roadside assistance
+
+    async def get_maintenance_records(self, bike_id: BikeId) -> list[dict[str, Any]]:
+        data = await self._request("GET", f"bikes/{bike_id}/maintenance/services")
+        return _list(data, "maintenances")
+
+    async def get_maintenance_schedule(
+        self, bike_id: BikeId, model_code: str, model_name: str
+    ) -> dict[str, Any] | None:
+        """The next service due, for Bike.model_code and Bike.model."""
+        data = await self._request(
+            "GET",
+            f"bikes/{bike_id}/maintenance-schedule",
+            params={"modelCode": model_code, "modelName": model_name},
+        )
+        return _dict(data, "maintenanceDto")
+
+    async def add_maintenance_record(
+        self, bike_id: BikeId, record: dict[str, Any]
+    ) -> list[dict[str, Any]]:
+        """Add a service record and return all records.
+
+        Keys: description, modelCode, modelName, odometerReadingOnService (miles),
+        nextServiceMiles and servicedDate as "dd-mm-yyyy".
+        """
+        data = await self._request(
+            "POST",
+            f"bikes/{bike_id}/maintenance/service",
+            body=record,
+            ok_codes=_MAINTENANCE_OK,
+        )
+        return _list(data, "maintenances")
+
+    async def update_maintenance_record(
+        self, record_id: int, record: dict[str, Any]
+    ) -> list[dict[str, Any]]:
+        """Change a service record, see add_maintenance_record()."""
+        data = await self._request(
+            "PUT",
+            f"bikes/maintenance/{record_id}",
+            body=record,
+            ok_codes=_MAINTENANCE_OK,
+        )
+        return _list(data, "maintenances")
+
+    async def delete_maintenance_record(self, record_id: int) -> None:
+        await self._request(
+            "DELETE", f"bikes/maintenance/{record_id}", ok_codes=_MAINTENANCE_OK
+        )
+
+    async def get_roadside_assistance(self, bike_id: BikeId) -> dict[str, Any] | None:
+        """The roadside assistance policy stored for a bike."""
+        return _dict(
+            await self._request("GET", f"bikes/{bike_id}/road-side-assistance"),
+            "roadAssistance",
+        )
+
+    async def add_roadside_assistance(
+        self,
+        bike_id: BikeId,
+        *,
+        vin: str,
+        company_name: str,
+        contact_number: str,
+        policy_number: str,
+    ) -> dict[str, Any] | None:
+        body = {
+            "vin": vin,
+            "companyName": company_name,
+            "contactNumber": contact_number,
+            "policyNumber": policy_number,
+        }
+        return _dict(
+            await self._request(
+                "POST", f"bikes/{bike_id}/road-side-assistance", body=body
+            ),
+            "roadAssistance",
+        )
+
+    async def update_roadside_assistance(
+        self,
+        record_id: int,
+        *,
+        vin: str,
+        company_name: str,
+        contact_number: str,
+        policy_number: str,
+    ) -> dict[str, Any] | None:
+        body = {
+            "vin": vin,
+            "companyName": company_name,
+            "contactNumber": contact_number,
+            "policyNumber": policy_number,
+        }
+        return _dict(
+            await self._request(
+                "PUT", f"bikes/road-side-assistance/{record_id}", body=body
+            ),
+            "roadAssistance",
+        )
+
+    async def delete_roadside_assistance(self, record_id: int) -> None:
+        await self._request("DELETE", f"bikes/road-side-assistance/{record_id}")
+
+    # Rides
+
+    async def get_rides(
+        self,
+        latitude: float,
+        longitude: float,
+        *,
+        radius_miles: float | None = None,
+        limit: int | None = None,
+        sub_types: Iterable[str] = (),
+        tags: Iterable[str] = (),
+        include_location_history: bool = False,
+        include_bookmarked: bool = True,
+    ) -> list[dict[str, Any]]:
+        """Curated rides around a position.
+
+        sub_types are HD or DEALER. tags are "tag=<name>" strings, the app knows the
+        names eaglerider, short-rides, day-rides, overnight-rides, lets-ride,
+        sturgis-rides, milwaukee-rides and daytona-rides.
+        """
+        data = await self._request(
+            "GET",
+            "rides",
+            params={
+                "lat": latitude,
+                "lon": longitude,
+                "radiusInMiles": radius_miles,
+                "limit": limit,
+                "type": "CURATED",
+                "subType": list(sub_types),
+                "tag": list(tags),
+                "includeLocationHistory": include_location_history,
+                "includeBookmarked": include_bookmarked,
+            },
+        )
+        return _list(data, "rides")
+
+    async def get_my_rides(self, units: str = "metric") -> list[dict[str, Any]]:
+        """Rides the user recorded or planned.
+
+        units is "metric" or "imperial", for the weather data.
+        """
+        data = await self._request(
+            "GET", "rides", params={"type": "CUSTOM", "includeWeather": units}
+        )
+        return _list(data, "rides")
+
+    async def get_ride(
+        self, ride_id: str, include_location_history: bool = False
+    ) -> dict[str, Any] | None:
+        data = await self._request(
+            "GET",
+            f"rides/{ride_id}",
+            params={"includeLocationHistory": include_location_history},
+        )
+        return _dict(data, "ride")
+
+    async def get_shared_ride(
+        self,
+        short_id: str,
+        *,
+        include_location_history: bool = True,
+        units: str = "metric",
+    ) -> dict[str, Any] | None:
+        """A ride by the short id of a share link."""
+        data = await self._request(
+            "GET",
+            f"rides/byShortId/{short_id}",
+            params={
+                "includeLocationHistory": include_location_history,
+                "includeWeather": units,
+            },
+        )
+        return _dict(data, "ride")
+
+    async def save_ride(
+        self,
+        ride: dict[str, Any],
+        *,
+        bookmark: bool = False,
+        imported: bool = False,
+        dont_save: bool = False,
+    ) -> dict[str, Any] | None:
+        """Save a new ride.
+
+        ride is shaped like the app's RidePostRequest: name, description, type
+        ("CUSTOM"), subType ("RECORDED" or "PLANNED"), waypoints, locationHistory,
+        rideAvoidances and so on, with dates as "yyyy-mm-ddThh:mm:ss+0000". Returns
+        the ride and record summaries.
+        """
+        data = await self._request(
+            "POST",
+            "ride",
+            params={
+                "dontSave": dont_save,
+                "imported": imported or None,
+                "bookmarkStatus": bookmark,
+            },
+            # the backend expects the ride as JSON encoded string
+            body={"ride": json.dumps(ride)},
+        )
+        return _dict(data, "data")
+
+    async def update_ride(
+        self, ride_id: str, ride: dict[str, Any]
+    ) -> dict[str, Any] | None:
+        """Replace a ride with a complete ride object, e.g. changed from get_ride()."""
+        # the app sends the ride as JSON in the query string
+        data = await self._request(
+            "PUT", f"ride/{ride_id}", params={"ride": json.dumps(ride)}
+        )
+        return _dict(data, "data", "ride")
+
+    async def rename_ride(
+        self, ride_id: str, name: str, description: str = ""
+    ) -> dict[str, Any] | None:
+        data = await self._request(
+            "PUT",
+            "update/ride",
+            params={
+                "rideString": json.dumps(
+                    {"id": ride_id, "name": name, "description": description}
+                ),
+            },
+        )
+        return _dict(data, "data", "ride")
+
+    async def delete_ride(self, ride_id: str) -> None:
+        await self._request("DELETE", f"ride/{ride_id}")
+
+    async def convert_recorded_ride(
+        self, ride_id: str, max_waypoints: int = 100
+    ) -> dict[str, Any] | None:
+        """Turn a recorded on-road ride into a route that can be navigated."""
+        data = await self._request(
+            "POST",
+            f"rides/record/convert/{ride_id}",
+            params={"maxWaypoints": max_waypoints},
+        )
+        return _dict(data, "data")
+
+    async def get_bookmarked_rides(self) -> list[dict[str, Any]]:
+        """Bookmarks with id, rideId and the ride."""
+        return _list(await self._request("GET", "rides/bookmarks"), "rideBookmarks")
+
+    async def bookmark_ride(self, ride_id: str) -> dict[str, Any] | None:
+        data = await self._request("POST", "rides/bookmark", body={"rideId": ride_id})
+        return _dict(data, "data", "rideBookmark")
+
+    async def remove_bookmark(self, bookmark_id: str) -> None:
+        """Remove a bookmark by its id, which is not the ride id."""
+        await self._request("DELETE", f"rides/bookmark/{bookmark_id}")
+
+    # Dealers
+
+    async def get_dealers(
+        self,
+        latitude: float,
+        longitude: float,
+        *,
+        radius_miles: float | None = 3000,
+        name: str | None = None,
+        max_results: int | None = None,
+        model_code: str | None = None,
+        service_only: bool = False,
+    ) -> list[dict[str, Any]]:
+        """Dealers around a position, optionally by name or only those with service."""
+        data = await self._request(
+            "GET",
+            "dealers/providesService" if service_only else "dealers",
+            params={
+                "name": name,
+                "lat": latitude,
+                "lon": longitude,
+                "radiusInMiles": radius_miles,
+                "maxResults": max_results,
+                "modelCode": model_code,
+            },
+        )
+        return _list(data, "dealers")
+
+    # Account and app information
+
+    async def get_notification_settings(self) -> list[dict[str, Any]]:
+        return _list(await self._request("GET", "setting"), "notificationConfig")
+
+    async def update_notification_setting(
+        self, setting: dict[str, Any]
+    ) -> dict[str, Any] | None:
+        """Change an entry of get_notification_settings().
+
+        Set its status to 1 (on) or 0 (off).
+        """
+        return _dict(await self._request("PUT", "setting", body=setting))
+
+    async def set_language(self, language: str, country: str) -> None:
+        """Set the account's app language, e.g. "en-US", and country, e.g. "US"."""
+        data = await self._request(
+            "PUT",
+            "update/language",
+            body={"appCountry": country, "appLanguage": language},
+        )
+
+        result = _field(data, "data", "responseType")
+        if result not in (None, "SUCCESS"):
+            raise ApiError(f"setting the language failed: {result}")
+
+    async def get_external_urls(
+        self, language: str | None = None
+    ) -> list[dict[str, Any]]:
+        """Links like owner manuals per model, with urlId such as "ownerManual_S2MH"."""
+        data = await self._request(
+            "GET", f"externalUrl/getByLang/{language or self._language}"
+        )
+        return _list(data, "response")
+
+    async def get_app_config(self) -> dict[str, Any] | None:
+        return _dict(await self._request("GET", "appConfig"), "config")
+
+    async def get_minimum_app_version(self) -> dict[str, Any] | None:
+        return _dict(await self._request("GET", "versions"), "data")
+
+    async def get_release_notes(
+        self, app_version: str = const.APP_VERSION
+    ) -> list[dict[str, Any]]:
+        """Release notes of an app version."""
+        data = await self._request(
+            "GET", f"appReleaseNote/{app_version}", params={"brandName": "S2"}
+        )
+        return _list(data, "response")
+
+    async def get_countries(self, language: str | None = None) -> dict[str, Any] | None:
+        """Countries with emergency numbers and supported languages, needs no login."""
+        return _dict(
+            await self._request(
+                "GET", f"countries/language/{language or self._language}", authed=False
+            )
+        )
+
+    async def delete_account(self) -> None:
+        """Delete the LiveWire account. This cannot be undone."""
+        data = await self._request("DELETE", "deleteUser")
+
+        code = to_int(_field(data, "code"))
+        if code not in (None, 200):
+            raise ApiError(
+                _error_message(data, "deleting the account failed"), code=str(code)
+            )