tescmd 0.1.2__py3-none-any.whl → 0.3.1__py3-none-any.whl

tescmd/__init__.py

@@ -1,3 +1,3 @@
 """tescmd — A Python CLI for querying and controlling Tesla vehicles via the Fleet API."""
 
-__version__ = "0.1.2"
+__version__ = "0.3.1"

tescmd/api/client.py

@@ -3,6 +3,8 @@
 from __future__ import annotations
 
 import asyncio
+import json
+import os as _os
 from typing import TYPE_CHECKING, Any
 
 import httpx
@@ -17,6 +19,7 @@ from tescmd.api.errors import (
     RateLimitError,
     RegistrationRequiredError,
     TeslaAPIError,
+    VCPRequiredError,
     VehicleAsleepError,
 )
 
@@ -24,6 +27,10 @@ from tescmd.api.errors import (
 # Region -> base URL mapping
 # ---------------------------------------------------------------------------
 
+# Allow a full override via TESLA_API_BASE_URL (e.g. for proxies / staging).
+# When set the region parameter is ignored and all requests go to this URL.
+_API_BASE_OVERRIDE: str | None = _os.environ.get("TESLA_API_BASE_URL")
+
 REGION_BASE_URLS: dict[str, str] = {
     "na": "https://fleet-api.prd.na.vn.cloud.tesla.com",
     "eu": "https://fleet-api.prd.eu.vn.cloud.tesla.com",
@@ -55,7 +62,7 @@ class TeslaFleetClient:
         on_token_refresh: Callable[[], Awaitable[str | None]] | None = None,
         on_rate_limit_wait: Callable[[int, int, int], Awaitable[None]] | None = None,
     ) -> None:
-        base_url = REGION_BASE_URLS.get(region)
+        base_url = _API_BASE_OVERRIDE or REGION_BASE_URLS.get(region)
         if base_url is None:
             msg = f"Unknown region {region!r}; expected one of {sorted(REGION_BASE_URLS)}"
             raise ValueError(msg)
@@ -159,11 +166,30 @@ class TeslaFleetClient:
         """Translate HTTP status codes to domain exceptions and return JSON."""
         if response.status_code == 429:
             raw = response.headers.get("retry-after")
-            retry_after: int | None = int(raw) if raw is not None else None
+            retry_after: int | None = None
+            if raw is not None:
+                try:
+                    retry_after = int(raw)
+                except ValueError:
+                    retry_after = 30  # Fallback for HTTP-date strings
             raise RateLimitError(retry_after=retry_after)
 
         if response.status_code == 408:
-            raise VehicleAsleepError("Vehicle is asleep", status_code=408)
+            # Tesla returns HTTP 408 for both "vehicle is asleep" and general
+            # request timeouts.  Inspect the body to distinguish the two.
+            body_text = response.text[:300]
+            body_lower = body_text.lower()
+            if "asleep" in body_lower or "offline" in body_lower or "unavailable" in body_lower:
+                raise VehicleAsleepError("Vehicle is asleep", status_code=408)
+            # No explicit sleep indicator — still raise VehicleAsleepError for
+            # backwards compatibility (most 408s *are* sleep), but include the
+            # raw body so callers can see what actually happened.
+            msg = (
+                f"Vehicle request timed out (HTTP 408): {body_text}"
+                if body_text
+                else "Vehicle is asleep"
+            )
+            raise VehicleAsleepError(msg, status_code=408)
 
         if response.status_code == 412:
             raise RegistrationRequiredError(
@@ -174,8 +200,16 @@ class TeslaFleetClient:
 
         if response.status_code == 403:
             text = response.text[:200]
-            if "missing scopes" in text.lower():
+            text_lower = text.lower()
+            if "missing scopes" in text_lower:
                 raise MissingScopesError(text, status_code=403)
+            if "vehicle command protocol required" in text_lower:
+                raise VCPRequiredError(
+                    "This command is not available via the Fleet API when "
+                    "Vehicle Command Protocol is enabled. Use the Tesla app "
+                    "or run tescmd behind a tesla-http-proxy.",
+                    status_code=403,
+                )
             raise AuthError(f"HTTP 403: {text}", status_code=403)
 
         if response.status_code >= 400:
@@ -185,5 +219,15 @@ class TeslaFleetClient:
                 status_code=response.status_code,
             )
 
-        result: dict[str, Any] = response.json()
+        # 204 No Content — return empty dict (no body to parse)
+        if response.status_code == 204:
+            return {}
+
+        try:
+            result: dict[str, Any] = response.json()
+        except json.JSONDecodeError as exc:
+            raise TeslaAPIError(
+                f"Invalid JSON response: {response.text[:200]}",
+                status_code=response.status_code,
+            ) from exc
         return result

tescmd/api/command.py

@@ -491,7 +491,7 @@ class CommandAPI:
         return await self._command(vin, "actuate_trunk", {"which_trunk": which_trunk})
 
     async def window_control(
-        self, vin: str, *, command: str, lat: float, lon: float
+        self, vin: str, *, command: str, lat: float = 0.0, lon: float = 0.0
     ) -> CommandResponse:
         return await self._command(
             vin, "window_control", {"command": command, "lat": lat, "lon": lon}

tescmd/api/errors.py

@@ -72,5 +72,18 @@ class MissingScopesError(AuthError):
     """Raised on HTTP 403 when the token lacks required OAuth scopes."""
 
 
+class VCPRequiredError(TeslaAPIError):
+    """Raised when the vehicle requires Vehicle Command Protocol for a command
+    that has no VCP proto definition (e.g. navigation commands)."""
+
+
 class KeyNotEnrolledError(TeslaAPIError):
     """Vehicle rejected the command — key not enrolled."""
+
+
+class TunnelError(ConfigError):
+    """Tunnel provider not available or setup failed."""
+
+
+class TailscaleError(TunnelError):
+    """Tailscale not installed, not running, or Funnel setup failed."""

tescmd/api/signed_command.py

@@ -103,7 +103,7 @@ class SignedCommandAPI:
 
         # Metadata + HMAC
         counter = session.next_counter()
-        expires_at = default_expiry(clock_offset=session.clock_offset)
+        expires_at = default_expiry(time_zero=session.time_zero)
         metadata_bytes = encode_metadata(
             epoch=session.epoch,
             expires_at=expires_at,
@@ -115,17 +115,16 @@ class SignedCommandAPI:
             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",
+            "(time_zero=%.1f), payload=%s, metadata=%s, hmac_tag=%s",
             command,
             vin,
             counter,
             expires_at,
-            session.clock_offset,
+            session.time_zero,
             payload.hex(),
             metadata_bytes.hex(),
             hmac_tag.hex(),
@@ -168,15 +167,18 @@ class SignedCommandAPI:
             # etc.) propagate so callers like auto_wake() can handle them.
             raise
 
-        result = self._parse_signed_response(data, vin, command)
+        result, fault = self._parse_signed_response(data, vin, command, domain)
         if result is not None:
             return result
 
         # Stale session — _parse_signed_response already invalidated the cache.
         # Retry once with a fresh handshake.
         if _retried:
+            fault_name = fault.name if fault else "unknown"
+            desc = FAULT_DESCRIPTIONS.get(fault, fault_name) if fault else fault_name
             raise SessionError(
-                f"Signed command '{command}' failed for {vin} after session refresh"
+                f"Signed command '{command}' failed for {vin} after session refresh "
+                f"(vehicle fault: {desc})"
             )
         logger.debug(
             "Stale session for %s (%s), retrying with fresh handshake",
@@ -194,15 +196,16 @@ class SignedCommandAPI:
         data: dict[str, Any],
         vin: str,
         command: str,
-    ) -> CommandResponse | None:
+        domain: Domain,
+    ) -> tuple[CommandResponse | None, MessageFault | 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.
+        ``(CommandResponse, None)`` on success.
 
-        Returns ``None`` if the fault indicates a stale session — the caller
-        should invalidate the session and retry with a fresh handshake.
+        Returns ``(None, fault)`` 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:
@@ -237,19 +240,21 @@ class SignedCommandAPI:
 
             # Stale session — invalidate and signal caller to retry.
             if fault in _STALE_SESSION_FAULTS:
-                self._session_mgr.invalidate(vin)
+                self._session_mgr.invalidate(vin, domain)
                 logger.debug(
                     "Stale session fault %s for %s, invalidated cache",
                     fault.name,
                     vin,
                 )
-                return None
+                return None, fault
 
             # All other faults — raise with descriptive message.
-            raise SessionError(f"Vehicle rejected command '{command}' for {vin}: {desc}")
+            raise SessionError(
+                f"Vehicle rejected command '{command}' for {vin}: {desc} (fault: {fault.name})"
+            )
 
         logger.debug("Signed command '%s' succeeded for %s", command, vin)
-        return CommandResponse(response=CommandResult(result=True))
+        return CommandResponse(response=CommandResult(result=True)), None
 
     # ------------------------------------------------------------------
     # Named method delegation

tescmd/api/vehicle.py

@@ -132,11 +132,29 @@ class VehicleAPI:
         return result
 
     async def fleet_telemetry_config_create(self, *, config: dict[str, Any]) -> dict[str, Any]:
-        """Create or update fleet telemetry server configuration."""
+        """Create or update fleet telemetry server configuration.
+
+        .. deprecated::
+            Tesla now requires the Vehicle Command HTTP Proxy for this
+            endpoint.  Use :meth:`fleet_telemetry_config_create_jws` instead.
+        """
         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_create_jws(
+        self, *, vins: list[str], token: str
+    ) -> dict[str, Any]:
+        """Create fleet telemetry config via the JWS-signed endpoint.
+
+        *token* is a compact JWS signed with the Tesla.SS256 algorithm
+        (Schnorr/P-256).  See :func:`tescmd.crypto.schnorr.sign_fleet_telemetry_config`.
+        """
+        payload = {"vins": vins, "token": token}
+        data = await self._client.post("/api/1/vehicles/fleet_telemetry_config_jws", json=payload)
+        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")

tescmd/auth/oauth.py

@@ -85,9 +85,13 @@ async def exchange_code(
     code_verifier: str,
     client_id: str,
     client_secret: str | None = None,
-    redirect_uri: str = "http://localhost:8085/callback",
+    redirect_uri: str | None = None,
 ) -> TokenData:
     """Exchange an authorization code for tokens."""
+    if redirect_uri is None:
+        from tescmd.models.auth import DEFAULT_REDIRECT_URI
+
+        redirect_uri = DEFAULT_REDIRECT_URI
     payload: dict[str, Any] = {
         "grant_type": "authorization_code",
         "code": code,

tescmd/auth/server.py

@@ -75,7 +75,11 @@ class _CallbackHandler(BaseHTTPRequestHandler):
 class OAuthCallbackServer(HTTPServer):
     """HTTPServer that waits for a single OAuth redirect callback."""
 
-    def __init__(self, port: int = 8085) -> None:
+    def __init__(self, port: int | None = None) -> None:
+        if port is None:
+            from tescmd.models.auth import DEFAULT_PORT
+
+            port = DEFAULT_PORT
         super().__init__(("127.0.0.1", port), _CallbackHandler)
         self.callback_event = threading.Event()
         self.callback_result: tuple[str | None, str | None, str | None] = (
@@ -104,5 +108,6 @@ class OAuthCallbackServer(HTTPServer):
     def stop(self) -> None:
         """Shut down the server and join the daemon thread."""
         self.shutdown()
+        self.server_close()
         if self._thread is not None:
             self._thread.join(timeout=5)

tescmd/auth/token_store.py

@@ -4,12 +4,15 @@ from __future__ import annotations
 
 import contextlib
 import json
+import logging
 import os
 import tempfile
 import warnings
 from pathlib import Path
 from typing import Any, Protocol
 
+logger = logging.getLogger(__name__)
+
 SERVICE_NAME = "tescmd"
 
 # Module-level flag so the file-fallback warning fires at most once.
@@ -227,7 +230,11 @@ class TokenStore:
         raw = self._backend.get(self._key("metadata"))
         if raw is None:
             return None
-        result: dict[str, Any] = json.loads(raw)
+        try:
+            result: dict[str, Any] = json.loads(raw)
+        except (json.JSONDecodeError, ValueError):
+            logger.warning("Corrupt token metadata — ignoring")
+            return None
         return result
 
     # -- mutators ------------------------------------------------------------

tescmd/cache/response_cache.py

@@ -3,6 +3,7 @@
 from __future__ import annotations
 
 import json
+import logging
 import time
 from dataclasses import dataclass
 from typing import TYPE_CHECKING, Any
@@ -12,6 +13,8 @@ from tescmd.cache.keys import cache_key
 if TYPE_CHECKING:
     from pathlib import Path
 
+logger = logging.getLogger(__name__)
+
 
 @dataclass(frozen=True)
 class CacheResult:
@@ -196,12 +199,16 @@ class ResponseCache:
 
     def _write_entry(self, path: Path, data: dict[str, Any], ttl: int) -> None:
         self._cache_dir.mkdir(parents=True, exist_ok=True)
+        now = time.time()
         entry = {
             "data": data,
-            "created_at": time.time(),
-            "expires_at": time.time() + ttl,
+            "created_at": now,
+            "expires_at": now + ttl,
         }
-        path.write_text(json.dumps(entry), encoding="utf-8")
+        # Atomic write: temp file + rename avoids torn reads.
+        tmp = path.with_suffix(".tmp")
+        tmp.write_text(json.dumps(entry), encoding="utf-8")
+        tmp.rename(path)
 
     @staticmethod
     def _read_json(path: Path) -> dict[str, Any] | None:
@@ -210,4 +217,5 @@ class ResponseCache:
         try:
             return json.loads(path.read_text(encoding="utf-8"))  # type: ignore[no-any-return]
         except (json.JSONDecodeError, OSError):
+            logger.warning("Corrupt or unreadable cache file: %s", path)
             return None

tescmd/cli/_client.py

@@ -4,6 +4,8 @@ from __future__ import annotations
 
 import asyncio
 import contextlib
+import logging
+import sys
 import time
 from pathlib import Path
 from typing import TYPE_CHECKING, Any, TypeVar
@@ -30,12 +32,15 @@ from tescmd.models.vehicle import VehicleData
 if TYPE_CHECKING:
     from collections.abc import Awaitable, Callable
 
+    from pydantic import BaseModel
     from rich.status import Status
 
     from tescmd.api.signed_command import SignedCommandAPI
     from tescmd.cli.main import AppContext
     from tescmd.output.formatter import OutputFormatter
 
+logger = logging.getLogger(__name__)
+
 T = TypeVar("T")
 
 # ---------------------------------------------------------------------------
@@ -52,20 +57,32 @@ _WAKE_BACKOFF_FACTOR = 1.5
 def _make_token_refresher(
     store: TokenStore, settings: AppSettings
 ) -> Callable[[], Awaitable[str | None]] | None:
-    """Return an async callback that refreshes the access token, or *None*."""
+    """Return an async callback that refreshes the access token, or *None*.
+
+    When the refresh token is expired/revoked (``login_required``),
+    prompts the user to re-authenticate via the browser on TTY.
+    In non-TTY mode, raises with guidance to run ``tescmd auth login``.
+    """
     refresh_token = store.refresh_token
     client_id = settings.client_id
     if not refresh_token or not client_id:
         return None
 
     async def _refresh() -> str | None:
+        from tescmd.api.errors import AuthError
         from tescmd.auth.oauth import refresh_access_token
 
-        token_data = await refresh_access_token(
-            refresh_token=refresh_token,
-            client_id=client_id,
-            client_secret=settings.client_secret,
-        )
+        try:
+            token_data = await refresh_access_token(
+                refresh_token=refresh_token,
+                client_id=client_id,
+                client_secret=settings.client_secret,
+            )
+        except AuthError as exc:
+            if "login_required" in str(exc):
+                return await reauth_on_expired_refresh(store, settings)
+            raise
+
         meta = store.metadata or {}
         store.save(
             access_token=token_data.access_token,
@@ -79,6 +96,66 @@ def _make_token_refresher(
     return _refresh
 
 
+async def reauth_on_expired_refresh(store: TokenStore, settings: AppSettings) -> str:
+    """Handle an expired/revoked refresh token by prompting for re-auth.
+
+    On TTY: asks the user to re-authenticate via the browser.
+    Non-TTY: raises with guidance to run ``tescmd auth login``.
+
+    Returns the new access token on success.
+    """
+    from tescmd.api.errors import AuthError
+    from tescmd.models.auth import DEFAULT_SCOPES
+
+    client_id = settings.client_id
+    if not client_id:
+        raise AuthError(
+            "Refresh token expired and TESLA_CLIENT_ID is not set. "
+            "Run 'tescmd auth login' to re-authenticate.",
+            status_code=401,
+        )
+
+    if not sys.stdin.isatty():
+        raise AuthError(
+            "Refresh token is invalid or expired. Run 'tescmd auth login' to re-authenticate.",
+            status_code=401,
+        )
+
+    click.echo("")
+    click.echo("Your refresh token has expired or been revoked.")
+    if not click.confirm("Re-authenticate via browser?", default=True):
+        raise AuthError(
+            "Re-authentication cancelled. Run 'tescmd auth login' to authenticate manually.",
+            status_code=401,
+        )
+
+    from tescmd.auth.oauth import login_flow
+
+    meta = store.metadata or {}
+    region = meta.get("region", "na")
+    scopes = meta.get("scopes", DEFAULT_SCOPES)
+    from tescmd.models.auth import DEFAULT_PORT
+
+    port = DEFAULT_PORT
+
+    click.echo("")
+    click.echo("Opening your browser to sign in to Tesla...")
+    click.echo("When prompted, click 'Select All' and then 'Allow'.")
+
+    token_data = await login_flow(
+        client_id=client_id,
+        client_secret=settings.client_secret,
+        redirect_uri=f"http://localhost:{port}/callback",
+        scopes=scopes,
+        port=port,
+        token_store=store,
+        region=region,
+    )
+
+    click.echo("Re-authenticated successfully.")
+    return token_data.access_token
+
+
 def _make_rate_limit_handler(
     formatter: OutputFormatter,
 ) -> Callable[[int, int, int], Awaitable[None]]:
@@ -278,15 +355,17 @@ async def cached_api_call(
     fetch: Callable[[], Awaitable[Any]],
     ttl: int | None = None,
     params: dict[str, str] | None = None,
+    model_class: type[BaseModel] | None = None,
 ) -> Any:
     """Fetch API data with transparent caching.
 
     1. Compute cache key via :func:`generic_cache_key`.
-    2. On hit → emit cache metadata, return cached dict.
-    3. On miss → call *fetch()*, serialise, store, return result.
+    2. On hit → reconstruct via *model_class* (if given), else return dict.
+    3. On miss → call *fetch()*, serialise to dict for cache, return original.
 
-    The caller's ``formatter.output()`` handles both Pydantic models (miss)
-    and plain dicts (hit).
+    When *model_class* is provided, cache hits are reconstructed with
+    ``model_class.model_validate(cached_dict)`` so callers always receive
+    Pydantic models regardless of hit/miss.
     """
     formatter = app_ctx.formatter
     cache = get_cache(app_ctx)
@@ -306,7 +385,7 @@ async def cached_api_call(
                 f" (TTL {cached.ttl_seconds}s)."
                 f" Use --fresh for live data.[/dim]"
             )
-        return cached.data
+        return _reconstruct(cached.data, model_class)
 
     result = await fetch()
 
@@ -325,6 +404,37 @@ async def cached_api_call(
     return result
 
 
+def _reconstruct(data: Any, model_class: type[BaseModel] | None) -> Any:
+    """Rebuild a Pydantic model from cached dict data.
+
+    * *model_class* provided + dict → ``model_class.model_validate(data)``
+    * *model_class* provided + list → validate each element
+    * *model_class* provided + ``{"_value": x}`` wrapper → unwrap scalar
+    * *model_class* is ``None`` → return raw cached data (dict / list)
+
+    If validation fails (e.g. cache corruption, schema change after upgrade),
+    falls back to returning the raw cached data with a warning log.
+    """
+    if model_class is None:
+        return data
+    if isinstance(data, dict) and "_value" in data and len(data) == 1:
+        return data["_value"]
+    try:
+        if isinstance(data, list):
+            return [
+                model_class.model_validate(item) if isinstance(item, dict) else item
+                for item in data
+            ]
+        if isinstance(data, dict):
+            return model_class.model_validate(data)
+    except Exception:
+        logger.warning(
+            "Cache reconstruction failed for %s — returning raw dict",
+            model_class.__name__,
+        )
+    return data
+
+
 async def cached_vehicle_data(
     app_ctx: AppContext,
     vehicle_api: VehicleAPI,
@@ -424,6 +534,23 @@ def _check_signing_requirement(
         )
 
 
+def check_command_guards(
+    cmd_api: CommandAPI | SignedCommandAPI,
+    method_name: str,
+) -> None:
+    """Enforce tier + VCSEC signing guards before executing a write command.
+
+    Raises :class:`TierError`, :class:`ConfigError`, or
+    :class:`KeyNotEnrolledError` on violation.
+
+    Called by both CLI :func:`execute_command` and the OpenClaw dispatcher.
+    """
+    settings = AppSettings()
+    if settings.setup_tier == "readonly":
+        raise TierError("This command requires 'full' tier setup. Run 'tescmd setup' to upgrade.")
+    _check_signing_requirement(cmd_api, method_name, settings)
+
+
 async def execute_command(
     app_ctx: AppContext,
     vin_positional: str | None,
@@ -438,17 +565,12 @@ async def execute_command(
     Resolves the VIN, obtains a :class:`CommandAPI`, calls *method_name* with
     ``auto_wake``, invalidates the cache, and outputs the result.
     """
-    # Tier enforcement — readonly tier cannot execute write commands
-    settings = AppSettings()
-    if settings.setup_tier == "readonly":
-        raise TierError("This command requires 'full' tier setup. Run 'tescmd setup' to upgrade.")
-
     formatter = app_ctx.formatter
     vin = require_vin(vin_positional, app_ctx.vin)
     client, vehicle_api, cmd_api = get_command_api(app_ctx)
 
-    # Guard: VCSEC commands require signed channel — don't silently fall back
-    _check_signing_requirement(cmd_api, method_name, settings)
+    # Guard: tier + VCSEC signing — fail fast before waking the vehicle
+    check_command_guards(cmd_api, method_name)
 
     try:
         method = getattr(cmd_api, method_name)
@@ -513,7 +635,7 @@ async def auto_wake(
 
     # Vehicle is asleep — decide whether to wake.
     if not auto:
-        if formatter.format not in ("json",):
+        if formatter.format not in ("json",) and sys.stdin.isatty():
             # Interactive TTY prompt with retry loop
             while True:
                 formatter.rich.info("")
@@ -552,7 +674,7 @@ async def auto_wake(
             )
 
     # Proceed with wake.
-    if formatter.format not in ("json",):
+    if formatter.format not in ("json",) and sys.stdin.isatty():
         with formatter.console.status("", spinner="dots") as status:
             await _wake_and_wait(vehicle_api, vin, timeout, status=status)
         formatter.rich.info("[green]Vehicle is awake.[/green]")

tescmd/cli/_options.py

@@ -101,10 +101,8 @@ def global_options(f: Any) -> Any:
             app_ctx.region = local_region
         if local_verbose:
             app_ctx.verbose = True
-            logging.basicConfig(
-                level=logging.DEBUG,
-                format="%(name)s %(levelname)s: %(message)s",
-            )
+            # Set root logger to DEBUG — basicConfig is called once in main.py
+            logging.getLogger().setLevel(logging.DEBUG)
         if local_no_cache:
             app_ctx.no_cache = True
         if local_wake: