tescmd 0.1.2__py3-none-any.whl

tescmd/api/errors.py

@@ -0,0 +1,76 @@
+"""Exception hierarchy for Tesla Fleet API errors."""
+
+from __future__ import annotations
+
+
+class TeslaAPIError(Exception):
+    """Base exception for all Tesla Fleet API errors."""
+
+    def __init__(self, message: str, status_code: int | None = None) -> None:
+        super().__init__(message)
+        self.status_code = status_code
+
+
+class AuthError(TeslaAPIError):
+    """Raised on 401 / authentication failures."""
+
+
+class VehicleAsleepError(TeslaAPIError):
+    """Raised when the vehicle is asleep (HTTP 408)."""
+
+
+class VehicleNotFoundError(TeslaAPIError):
+    """Raised when the requested vehicle does not exist."""
+
+
+class CommandFailedError(TeslaAPIError):
+    """Raised when a vehicle command is rejected by the API."""
+
+    def __init__(
+        self,
+        message: str,
+        reason: str,
+        status_code: int | None = None,
+    ) -> None:
+        super().__init__(message, status_code)
+        self.reason = reason
+
+
+class RateLimitError(TeslaAPIError):
+    """Raised on HTTP 429 — too many requests."""
+
+    def __init__(
+        self,
+        message: str = "Rate limit exceeded",
+        retry_after: int | None = None,
+    ) -> None:
+        super().__init__(message, status_code=429)
+        self.retry_after = retry_after
+
+
+class RegistrationRequiredError(TeslaAPIError):
+    """Raised on HTTP 412 — app not registered with regional Fleet API."""
+
+
+class NetworkError(TeslaAPIError):
+    """Raised on connection / timeout errors."""
+
+
+class ConfigError(Exception):
+    """Raised for configuration problems (not an API error)."""
+
+
+class TierError(ConfigError):
+    """Command requires full-tier setup but only readonly is configured."""
+
+
+class SessionError(TeslaAPIError):
+    """ECDH session handshake failed."""
+
+
+class MissingScopesError(AuthError):
+    """Raised on HTTP 403 when the token lacks required OAuth scopes."""
+
+
+class KeyNotEnrolledError(TeslaAPIError):
+    """Vehicle rejected the command — key not enrolled."""

tescmd/api/partner.py

@@ -0,0 +1,40 @@
+"""Partner account API — public key retrieval and fleet telemetry errors."""
+
+from __future__ import annotations
+
+from typing import TYPE_CHECKING, Any
+
+if TYPE_CHECKING:
+    from tescmd.api.client import TeslaFleetClient
+
+
+class PartnerAPI:
+    """Partner-level endpoints (require partner token, not user token)."""
+
+    def __init__(self, client: TeslaFleetClient) -> None:
+        self._client = client
+
+    async def public_key(self, *, domain: str) -> dict[str, Any]:
+        """Get the public key registered for *domain*."""
+        data = await self._client.get(
+            "/api/1/partner_accounts/public_key",
+            params={"domain": domain},
+        )
+        result: dict[str, Any] = data.get("response", data)
+        return result
+
+    async def fleet_telemetry_error_vins(self) -> list[str]:
+        """List VINs that have recent fleet telemetry errors."""
+        data = await self._client.get(
+            "/api/1/partner_accounts/fleet_telemetry_error_vins",
+        )
+        result: list[str] = data.get("response", [])
+        return result
+
+    async def fleet_telemetry_errors(self) -> list[dict[str, Any]]:
+        """Get recent fleet telemetry errors across all vehicles."""
+        data = await self._client.get(
+            "/api/1/partner_accounts/fleet_telemetry_errors",
+        )
+        result: list[dict[str, Any]] = data.get("response", [])
+        return result

tescmd/api/sharing.py

@@ -0,0 +1,65 @@
+"""Vehicle sharing API — driver management and invites."""
+
+from __future__ import annotations
+
+from typing import TYPE_CHECKING, Any
+
+from tescmd.models.sharing import ShareDriverInfo, ShareInvite
+
+if TYPE_CHECKING:
+    from tescmd.api.client import TeslaFleetClient
+
+
+class SharingAPI:
+    """Vehicle sharing operations (drivers and invites)."""
+
+    def __init__(self, client: TeslaFleetClient) -> None:
+        self._client = client
+
+    async def add_driver(self, vin: str, *, email: str) -> ShareDriverInfo:
+        """Add a driver by email."""
+        data = await self._client.post(
+            f"/api/1/vehicles/{vin}/drivers",
+            json={"email": email},
+        )
+        return ShareDriverInfo.model_validate(data.get("response", {}))
+
+    async def remove_driver(self, vin: str, *, share_user_id: int) -> dict[str, Any]:
+        """Remove a driver by their share user ID."""
+        data = await self._client.delete(
+            f"/api/1/vehicles/{vin}/drivers",
+            json={"share_user_id": share_user_id},
+        )
+        result: dict[str, Any] = data.get("response", {})
+        return result
+
+    async def create_invite(self, vin: str) -> ShareInvite:
+        """Create a vehicle share invite."""
+        data = await self._client.post(f"/api/1/vehicles/{vin}/invitations")
+        return ShareInvite.model_validate(data.get("response", {}))
+
+    async def redeem_invite(self, *, code: str) -> ShareInvite:
+        """Redeem a vehicle share invite code.
+
+        This is an account-level endpoint (no VIN required) — the invite
+        code itself encodes the vehicle association.
+        """
+        data = await self._client.post(
+            "/api/1/invitations/redeem",
+            json={"code": code},
+        )
+        return ShareInvite.model_validate(data.get("response", {}))
+
+    async def revoke_invite(self, vin: str, *, invite_id: str) -> dict[str, Any]:
+        """Revoke a vehicle share invite."""
+        data = await self._client.post(
+            f"/api/1/vehicles/{vin}/invitations/{invite_id}/revoke",
+        )
+        result: dict[str, Any] = data.get("response", {})
+        return result
+
+    async def list_invites(self, vin: str) -> list[ShareInvite]:
+        """List active vehicle share invites."""
+        data = await self._client.get(f"/api/1/vehicles/{vin}/invitations")
+        raw_list: list[dict[str, Any]] = data.get("response", [])
+        return [ShareInvite.model_validate(inv) for inv in raw_list]

tescmd/api/signed_command.py

@@ -0,0 +1,277 @@
+"""Signed command API — Vehicle Command Protocol over the signed_command endpoint.
+
+Routes commands through either the signed ECDH/HMAC path or the unsigned
+REST path depending on the command's registry entry.
+
+This class matches the :class:`CommandAPI` interface so callers (CLI modules)
+don't need to know which protocol path is in use.
+"""
+
+from __future__ import annotations
+
+import base64
+import logging
+from typing import TYPE_CHECKING, Any
+
+from tescmd.api.errors import KeyNotEnrolledError, SessionError, TeslaAPIError
+from tescmd.models.command import CommandResponse, CommandResult
+from tescmd.protocol.commands import get_command_spec
+from tescmd.protocol.encoder import (
+    build_signed_command,
+    default_expiry,
+    encode_routable_message,
+)
+from tescmd.protocol.metadata import encode_metadata
+from tescmd.protocol.payloads import build_command_payload
+from tescmd.protocol.protobuf.messages import (
+    FAULT_DESCRIPTIONS,
+    KEY_FAULTS,
+    MessageFault,
+    RoutableMessage,
+)
+from tescmd.protocol.signer import compute_hmac_tag
+
+if TYPE_CHECKING:
+    from tescmd.api.client import TeslaFleetClient
+    from tescmd.api.command import CommandAPI
+    from tescmd.protocol.protobuf.messages import Domain
+    from tescmd.protocol.session import SessionManager
+
+logger = logging.getLogger(__name__)
+
+# Faults indicating the ECDH session is stale and a fresh handshake is needed.
+_STALE_SESSION_FAULTS: frozenset[MessageFault] = frozenset(
+    {
+        MessageFault.ERROR_INVALID_SIGNATURE,
+        MessageFault.ERROR_INVALID_TOKEN_OR_COUNTER,
+        MessageFault.ERROR_INCORRECT_EPOCH,
+        MessageFault.ERROR_TIME_EXPIRED,
+    }
+)
+
+
+class SignedCommandAPI:
+    """Vehicle command API using the Vehicle Command Protocol (signed channel).
+
+    Commands registered in the protocol command registry with
+    ``requires_signing=True`` are routed through the ECDH session + HMAC
+    path.  Unsigned commands (e.g. ``wake_up``) pass through to the
+    legacy REST endpoint via the wrapped :class:`CommandAPI`.
+
+    Named methods (``charge_start``, ``door_lock``, etc.) are created
+    dynamically via :meth:`__getattr__` — each returns a dispatch wrapper
+    that routes through :meth:`_command`, which picks the signed or
+    unsigned path based on the command registry.
+    """
+
+    def __init__(
+        self,
+        client: TeslaFleetClient,
+        session_mgr: SessionManager,
+        unsigned_api: CommandAPI,
+    ) -> None:
+        self._client = client
+        self._session_mgr = session_mgr
+        self._unsigned_api = unsigned_api
+
+    async def _command(
+        self, vin: str, command: str, body: dict[str, Any] | None = None
+    ) -> CommandResponse:
+        """Execute a command — signed or unsigned depending on registry."""
+        spec = get_command_spec(command)
+
+        # Unknown commands or unsigned commands → legacy REST path
+        if spec is None or not spec.requires_signing:
+            return await self._unsigned_api._command(vin, command, body)
+
+        return await self._signed_command(vin, command, body, domain=spec.domain)
+
+    async def _signed_command(
+        self,
+        vin: str,
+        command: str,
+        body: dict[str, Any] | None,
+        *,
+        domain: Domain,
+        _retried: bool = False,
+    ) -> CommandResponse:
+        """Build, sign, and send a command via the signed_command endpoint."""
+        session = await self._session_mgr.get_session(vin, domain)
+
+        # Build protobuf payload for the command
+        payload = build_command_payload(command, body)
+
+        # Metadata + HMAC
+        counter = session.next_counter()
+        expires_at = default_expiry(clock_offset=session.clock_offset)
+        metadata_bytes = encode_metadata(
+            epoch=session.epoch,
+            expires_at=expires_at,
+            counter=counter,
+            domain=domain,
+            vin=vin,
+        )
+        hmac_tag = compute_hmac_tag(
+            session.signing_key,
+            metadata_bytes,
+            payload,
+            domain=domain,
+        )
+
+        logger.debug(
+            "Signed command '%s' for %s: counter=%d, expires_at=%d "
+            "(clock_offset=%d), payload=%s, metadata=%s, hmac_tag=%s",
+            command,
+            vin,
+            counter,
+            expires_at,
+            session.clock_offset,
+            payload.hex(),
+            metadata_bytes.hex(),
+            hmac_tag.hex(),
+        )
+
+        # Build RoutableMessage
+        msg = build_signed_command(
+            domain=domain,
+            payload=payload,
+            client_public_key=self._session_mgr.client_public_key,
+            epoch=session.epoch,
+            counter=counter,
+            expires_at=expires_at,
+            hmac_tag=hmac_tag,
+        )
+        encoded = encode_routable_message(msg)
+
+        logger.debug(
+            "Encoded RoutableMessage for %s: %s",
+            vin,
+            encoded[:80] + "..." if len(encoded) > 80 else encoded,
+        )
+
+        # POST to signed_command endpoint
+        try:
+            data = await self._client.post(
+                f"/api/1/vehicles/{vin}/signed_command",
+                json={"routable_message": encoded},
+            )
+        except TeslaAPIError as exc:
+            # Check for key-not-enrolled error pattern
+            err_msg = str(exc).lower()
+            if "not enrolled" in err_msg or "unknown key" in err_msg:
+                raise KeyNotEnrolledError(
+                    f"Key not enrolled on vehicle {vin}. "
+                    "Enroll via 'tescmd key enroll' and approve in the Tesla app.",
+                    status_code=422,
+                ) from exc
+            # Let domain-specific errors (VehicleAsleepError, RateLimitError,
+            # etc.) propagate so callers like auto_wake() can handle them.
+            raise
+
+        result = self._parse_signed_response(data, vin, command)
+        if result is not None:
+            return result
+
+        # Stale session — _parse_signed_response already invalidated the cache.
+        # Retry once with a fresh handshake.
+        if _retried:
+            raise SessionError(
+                f"Signed command '{command}' failed for {vin} after session refresh"
+            )
+        logger.debug(
+            "Stale session for %s (%s), retrying with fresh handshake",
+            vin,
+            command,
+        )
+        return await self._signed_command(vin, command, body, domain=domain, _retried=True)
+
+    # ------------------------------------------------------------------
+    # Response parsing
+    # ------------------------------------------------------------------
+
+    def _parse_signed_response(
+        self,
+        data: dict[str, Any],
+        vin: str,
+        command: str,
+    ) -> CommandResponse | None:
+        """Parse a signed_command endpoint response.
+
+        The endpoint returns ``{"response": "<base64-encoded RoutableMessage>"}``.
+        Decodes the protobuf, checks for vehicle-side fault codes, and returns
+        a ``CommandResponse`` on success.
+
+        Returns ``None`` if the fault indicates a stale session — the caller
+        should invalidate the session and retry with a fresh handshake.
+        """
+        response_b64: str = data.get("response", "")
+        if not response_b64:
+            raise SessionError(f"Empty signed_command response for {vin} ({command})")
+
+        try:
+            response_bytes = base64.b64decode(response_b64)
+        except Exception as exc:
+            raise SessionError(f"Failed to decode signed_command response: {exc}") from exc
+
+        msg = RoutableMessage.parse(response_bytes)
+        fault = msg.signed_message_fault
+
+        logger.debug(
+            "Signed command '%s' response for %s: fault=%s, has_protobuf_msg=%s, has_signature=%s",
+            command,
+            vin,
+            fault.name,
+            bool(msg.protobuf_message_as_bytes),
+            msg.signature_data is not None,
+        )
+
+        if fault != MessageFault.ERROR_NONE:
+            desc = FAULT_DESCRIPTIONS.get(fault, fault.name)
+
+            # Key not enrolled — permanent error, don't retry.
+            if fault in KEY_FAULTS:
+                raise KeyNotEnrolledError(
+                    f"Vehicle rejected command '{command}': {desc}",
+                    status_code=422,
+                )
+
+            # Stale session — invalidate and signal caller to retry.
+            if fault in _STALE_SESSION_FAULTS:
+                self._session_mgr.invalidate(vin)
+                logger.debug(
+                    "Stale session fault %s for %s, invalidated cache",
+                    fault.name,
+                    vin,
+                )
+                return None
+
+            # All other faults — raise with descriptive message.
+            raise SessionError(f"Vehicle rejected command '{command}' for {vin}: {desc}")
+
+        logger.debug("Signed command '%s' succeeded for %s", command, vin)
+        return CommandResponse(response=CommandResult(result=True))
+
+    # ------------------------------------------------------------------
+    # Named method delegation
+    # ------------------------------------------------------------------
+
+    def __getattr__(self, name: str) -> Any:
+        """Route named command methods through the signed path.
+
+        ``execute_command()`` calls ``getattr(cmd_api, method_name)(vin, **body)``
+        — we create wrapper methods that route through ``self._command()``
+        which picks the signed or unsigned path based on the command registry.
+        """
+        spec = get_command_spec(name)
+        if spec is not None:
+            # Return a wrapper that routes through the signed/unsigned dispatcher
+            async def _dispatch(vin: str, **kwargs: Any) -> CommandResponse:
+                return await self._command(vin, name, kwargs or None)
+
+            return _dispatch
+
+        # Non-command attributes (e.g. _client) → fall back to unsigned API
+        attr = getattr(self._unsigned_api, name, None)
+        if attr is not None:
+            return attr
+        raise AttributeError(f"'{type(self).__name__}' has no attribute '{name}'")

tescmd/api/user.py

@@ -0,0 +1,38 @@
+"""User account API — wraps /api/1/users endpoints."""
+
+from __future__ import annotations
+
+from typing import TYPE_CHECKING, Any
+
+from tescmd.models.user import FeatureConfig, UserInfo, UserRegion, VehicleOrder
+
+if TYPE_CHECKING:
+    from tescmd.api.client import TeslaFleetClient
+
+
+class UserAPI:
+    """User account operations (no VIN required)."""
+
+    def __init__(self, client: TeslaFleetClient) -> None:
+        self._client = client
+
+    async def me(self) -> UserInfo:
+        """Fetch the current user's profile."""
+        data = await self._client.get("/api/1/users/me")
+        return UserInfo.model_validate(data.get("response", {}))
+
+    async def region(self) -> UserRegion:
+        """Fetch the user's regional Fleet API endpoint."""
+        data = await self._client.get("/api/1/users/region")
+        return UserRegion.model_validate(data.get("response", {}))
+
+    async def orders(self) -> list[VehicleOrder]:
+        """Fetch the user's vehicle orders."""
+        data = await self._client.get("/api/1/users/orders")
+        raw_list: list[dict[str, Any]] = data.get("response", [])
+        return [VehicleOrder.model_validate(o) for o in raw_list]
+
+    async def feature_config(self) -> FeatureConfig:
+        """Fetch the user's feature flags."""
+        data = await self._client.get("/api/1/users/feature_config")
+        return FeatureConfig.model_validate(data.get("response", {}))

tescmd/api/vehicle.py

@@ -0,0 +1,150 @@
+"""High-level Vehicle API built on top of TeslaFleetClient."""
+
+from __future__ import annotations
+
+from typing import TYPE_CHECKING, Any
+
+from tescmd.models.sharing import ShareDriverInfo
+from tescmd.models.vehicle import NearbyChargingSites, Vehicle, VehicleData
+
+if TYPE_CHECKING:
+    from tescmd.api.client import TeslaFleetClient
+
+
+class VehicleAPI:
+    """Vehicle-related API operations (composition over TeslaFleetClient)."""
+
+    def __init__(self, client: TeslaFleetClient) -> None:
+        self._client = client
+
+    async def list_vehicles(self) -> list[Vehicle]:
+        """Return all vehicles associated with the account."""
+        data = await self._client.get("/api/1/vehicles")
+        raw_list: list[dict[str, object]] = data.get("response", [])
+        return [Vehicle.model_validate(v) for v in raw_list]
+
+    async def get_vehicle(self, vin: str) -> Vehicle:
+        """Fetch a single vehicle by VIN."""
+        data = await self._client.get(f"/api/1/vehicles/{vin}")
+        return Vehicle.model_validate(data["response"])
+
+    async def get_vehicle_data(
+        self,
+        vin: str,
+        *,
+        endpoints: list[str] | None = None,
+    ) -> VehicleData:
+        """Fetch full vehicle data, optionally filtered to *endpoints*."""
+        path = f"/api/1/vehicles/{vin}/vehicle_data"
+        params: dict[str, str] = {}
+        if endpoints:
+            params["endpoints"] = ";".join(endpoints)
+        data = await self._client.get(path, params=params)
+        return VehicleData.model_validate(data["response"])
+
+    async def wake(self, vin: str) -> Vehicle:
+        """Send a wake-up command and return the vehicle state."""
+        data = await self._client.post(f"/api/1/vehicles/{vin}/wake_up")
+        return Vehicle.model_validate(data["response"])
+
+    async def mobile_enabled(self, vin: str) -> bool:
+        """Check if mobile access is enabled for the vehicle."""
+        data = await self._client.get(f"/api/1/vehicles/{vin}/mobile_enabled")
+        return bool(data.get("response", False))
+
+    async def nearby_charging_sites(self, vin: str) -> NearbyChargingSites:
+        """Fetch nearby Superchargers and destination chargers."""
+        data = await self._client.get(f"/api/1/vehicles/{vin}/nearby_charging_sites")
+        return NearbyChargingSites.model_validate(data.get("response", {}))
+
+    async def recent_alerts(self, vin: str) -> list[dict[str, Any]]:
+        """Fetch recent vehicle alerts."""
+        data = await self._client.get(f"/api/1/vehicles/{vin}/recent_alerts")
+        result: list[dict[str, Any]] = data.get("response", [])
+        return result
+
+    async def release_notes(self, vin: str) -> dict[str, Any]:
+        """Fetch firmware release notes."""
+        data = await self._client.get(f"/api/1/vehicles/{vin}/release_notes")
+        result: dict[str, Any] = data.get("response", {})
+        return result
+
+    async def service_data(self, vin: str) -> dict[str, Any]:
+        """Fetch vehicle service data."""
+        data = await self._client.get(f"/api/1/vehicles/{vin}/service_data")
+        result: dict[str, Any] = data.get("response", {})
+        return result
+
+    async def list_drivers(self, vin: str) -> list[ShareDriverInfo]:
+        """List drivers associated with the vehicle."""
+        data = await self._client.get(f"/api/1/vehicles/{vin}/drivers")
+        raw_list: list[dict[str, Any]] = data.get("response", [])
+        return [ShareDriverInfo.model_validate(d) for d in raw_list]
+
+    # ------------------------------------------------------------------
+    # Extended vehicle data endpoints
+    # ------------------------------------------------------------------
+
+    async def eligible_subscriptions(self, vin: str) -> dict[str, Any]:
+        """Check subscription eligibility for the vehicle."""
+        data = await self._client.get(
+            "/api/1/dx/vehicles/subscriptions/eligibility", params={"vin": vin}
+        )
+        result: dict[str, Any] = data.get("response", {})
+        return result
+
+    async def eligible_upgrades(self, vin: str) -> dict[str, Any]:
+        """Check upgrade eligibility for the vehicle."""
+        data = await self._client.get(
+            "/api/1/dx/vehicles/upgrades/eligibility", params={"vin": vin}
+        )
+        result: dict[str, Any] = data.get("response", {})
+        return result
+
+    async def options(self, vin: str) -> dict[str, Any]:
+        """Fetch vehicle option codes."""
+        data = await self._client.get("/api/1/dx/vehicles/options", params={"vin": vin})
+        result: dict[str, Any] = data.get("response", {})
+        return result
+
+    async def specs(self, vin: str) -> dict[str, Any]:
+        """Fetch vehicle specifications."""
+        data = await self._client.get(f"/api/1/vehicles/{vin}/specs")
+        result: dict[str, Any] = data.get("response", {})
+        return result
+
+    async def warranty_details(self) -> dict[str, Any]:
+        """Fetch warranty details."""
+        data = await self._client.get("/api/1/dx/warranty/details")
+        result: dict[str, Any] = data.get("response", {})
+        return result
+
+    async def fleet_status(self) -> dict[str, Any]:
+        """Fetch fleet status for all vehicles."""
+        data = await self._client.post("/api/1/vehicles/fleet_status")
+        result: dict[str, Any] = data.get("response", {})
+        return result
+
+    async def fleet_telemetry_config(self, vin: str) -> dict[str, Any]:
+        """Fetch fleet telemetry configuration for a vehicle."""
+        data = await self._client.get(f"/api/1/vehicles/{vin}/fleet_telemetry_config")
+        result: dict[str, Any] = data.get("response", {})
+        return result
+
+    async def fleet_telemetry_config_create(self, *, config: dict[str, Any]) -> dict[str, Any]:
+        """Create or update fleet telemetry server configuration."""
+        data = await self._client.post("/api/1/vehicles/fleet_telemetry_config", json=config)
+        result: dict[str, Any] = data.get("response", {})
+        return result
+
+    async def fleet_telemetry_config_delete(self, vin: str) -> dict[str, Any]:
+        """Remove fleet telemetry configuration from a vehicle."""
+        data = await self._client.delete(f"/api/1/vehicles/{vin}/fleet_telemetry_config")
+        result: dict[str, Any] = data.get("response", {})
+        return result
+
+    async def fleet_telemetry_errors(self, vin: str) -> dict[str, Any]:
+        """Fetch fleet telemetry errors."""
+        data = await self._client.get(f"/api/1/vehicles/{vin}/fleet_telemetry_errors")
+        result: dict[str, Any] = data.get("response", {})
+        return result

tescmd/auth/__init__.py

@@ -0,0 +1 @@
+"""Authentication: OAuth2 PKCE flow, token persistence, callback server."""