tescmd 0.1.2__py3-none-any.whl

tescmd/__init__.py

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

tescmd/__main__.py

@@ -0,0 +1,5 @@
+"""Allow running as: python -m tescmd"""
+
+from tescmd.cli.main import main
+
+main()

tescmd/_internal/async_utils.py

@@ -0,0 +1,25 @@
+"""Asyncio utilities."""
+
+from __future__ import annotations
+
+import asyncio
+from typing import TYPE_CHECKING, Any
+
+if TYPE_CHECKING:
+    from collections.abc import Coroutine
+
+
+def run_async(coro: Coroutine[Any, Any, Any]) -> Any:
+    """Run an async coroutine from synchronous code."""
+    try:
+        loop = asyncio.get_running_loop()
+    except RuntimeError:
+        loop = None
+
+    if loop and loop.is_running():
+        import concurrent.futures
+
+        with concurrent.futures.ThreadPoolExecutor() as pool:
+            return pool.submit(asyncio.run, coro).result()
+    else:
+        return asyncio.run(coro)

tescmd/_internal/permissions.py

@@ -0,0 +1,43 @@
+"""Cross-platform file-permission helpers."""
+
+from __future__ import annotations
+
+import os
+import stat
+import subprocess
+import sys
+from typing import TYPE_CHECKING
+
+if TYPE_CHECKING:
+    from pathlib import Path
+
+
+def secure_file(path: Path) -> None:
+    """Set *path* to owner-only read/write (best-effort).
+
+    * **Unix** — ``chmod 0600``
+    * **Windows** — ``icacls`` grant to current user, remove inherited ACLs
+
+    Failures are silently ignored so callers never crash on permission
+    quirks (Docker volumes, network mounts, etc.).
+    """
+    try:
+        if sys.platform == "win32":
+            _secure_file_windows(path)
+        else:
+            path.chmod(stat.S_IRUSR | stat.S_IWUSR)
+    except OSError:
+        pass
+
+
+def _secure_file_windows(path: Path) -> None:
+    """Restrict *path* to the current user via ``icacls``."""
+    username = os.environ.get("USERNAME", "")
+    if not username:
+        return
+    # Remove inherited permissions, then grant owner full control
+    subprocess.run(
+        ["icacls", str(path), "/inheritance:r", "/grant:r", f"{username}:(R,W)"],
+        capture_output=True,
+        check=False,
+    )

tescmd/_internal/vin.py

@@ -0,0 +1,44 @@
+"""Smart VIN resolution and validation."""
+
+from __future__ import annotations
+
+import os
+import re
+
+# ISO 3779: VINs are 17 alphanumeric characters, excluding I, O, Q.
+_VIN_PATTERN = re.compile(r"^[A-HJ-NPR-Z0-9]{17}$")
+
+
+class InvalidVINError(ValueError):
+    """Raised when a VIN fails format validation."""
+
+
+def validate_vin(vin: str) -> str:
+    """Validate that *vin* matches the ISO 3779 VIN format.
+
+    Returns the uppercased VIN on success; raises :class:`InvalidVINError`
+    on failure.
+    """
+    upper = vin.upper()
+    if not _VIN_PATTERN.match(upper):
+        raise InvalidVINError(
+            f"Invalid VIN {vin!r}: must be 17 alphanumeric characters "
+            "(excluding I, O, Q per ISO 3779)."
+        )
+    return upper
+
+
+def resolve_vin(
+    *,
+    vin_positional: str | None = None,
+    vin_flag: str | None = None,
+) -> str | None:
+    """Resolve VIN from multiple sources in priority order.
+
+    Resolution: positional arg > --vin flag > TESLA_VIN env > None.
+    """
+    if vin_positional:
+        return vin_positional
+    if vin_flag:
+        return vin_flag
+    return os.environ.get("TESLA_VIN")

tescmd/api/__init__.py

@@ -0,0 +1 @@
+"""Tesla Fleet API client layer."""

tescmd/api/charging.py

@@ -0,0 +1,102 @@
+"""Charging history API — wraps /api/1/dx/charging endpoints."""
+
+from __future__ import annotations
+
+from typing import TYPE_CHECKING, Any
+
+if TYPE_CHECKING:
+    from tescmd.api.client import TeslaFleetClient
+
+
+class ChargingAPI:
+    """Charging history and invoice operations (composition over TeslaFleetClient)."""
+
+    def __init__(self, client: TeslaFleetClient) -> None:
+        self._client = client
+
+    async def charging_history(
+        self,
+        *,
+        vin: str | None = None,
+        start_time: str | None = None,
+        end_time: str | None = None,
+        page_no: int | None = None,
+        page_size: int | None = None,
+        sort_by: str | None = None,
+        sort_order: str | None = None,
+    ) -> dict[str, Any]:
+        """Fetch paginated Supercharger charging history.
+
+        Args:
+            vin: Filter by vehicle VIN.
+            start_time: ISO-8601 start time filter.
+            end_time: ISO-8601 end time filter.
+            page_no: Page number (0-based).
+            page_size: Results per page.
+            sort_by: Field to sort by.
+            sort_order: Sort order (ASC or DESC).
+        """
+        params: dict[str, str] = {}
+        if vin is not None:
+            params["vin"] = vin
+        if start_time is not None:
+            params["startTime"] = start_time
+        if end_time is not None:
+            params["endTime"] = end_time
+        if page_no is not None:
+            params["pageNo"] = str(page_no)
+        if page_size is not None:
+            params["pageSize"] = str(page_size)
+        if sort_by is not None:
+            params["sortBy"] = sort_by
+        if sort_order is not None:
+            params["sortOrder"] = sort_order
+        data = await self._client.get("/api/1/dx/charging/history", params=params)
+        result: dict[str, Any] = data.get("response", {})
+        return result
+
+    async def charging_sessions(
+        self,
+        *,
+        vin: str | None = None,
+        date_from: str | None = None,
+        date_to: str | None = None,
+        limit: int | None = None,
+        offset: int | None = None,
+    ) -> dict[str, Any]:
+        """Fetch charging sessions (business accounts only).
+
+        Args:
+            vin: Filter by vehicle VIN.
+            date_from: ISO-8601 start date.
+            date_to: ISO-8601 end date.
+            limit: Max results to return.
+            offset: Pagination offset.
+        """
+        params: dict[str, str] = {}
+        if vin is not None:
+            params["vin"] = vin
+        if date_from is not None:
+            params["date_from"] = date_from
+        if date_to is not None:
+            params["date_to"] = date_to
+        if limit is not None:
+            params["limit"] = str(limit)
+        if offset is not None:
+            params["offset"] = str(offset)
+        data = await self._client.get("/api/1/dx/charging/sessions", params=params)
+        result: dict[str, Any] = data.get("response", {})
+        return result
+
+    async def charging_invoice(self, invoice_id: str) -> dict[str, Any]:
+        """Download a charging invoice.
+
+        Args:
+            invoice_id: The invoice identifier.
+
+        Returns:
+            Invoice response data (may contain a download URL or inline content).
+        """
+        data = await self._client.get(f"/api/1/dx/charging/invoice/{invoice_id}")
+        result: dict[str, Any] = data.get("response", data) if isinstance(data, dict) else {}
+        return result

tescmd/api/client.py

@@ -0,0 +1,189 @@
+"""Async HTTP client for the Tesla Fleet API."""
+
+from __future__ import annotations
+
+import asyncio
+from typing import TYPE_CHECKING, Any
+
+import httpx
+
+if TYPE_CHECKING:
+    from collections.abc import Awaitable, Callable
+
+from tescmd.api.errors import (
+    AuthError,
+    MissingScopesError,
+    NetworkError,
+    RateLimitError,
+    RegistrationRequiredError,
+    TeslaAPIError,
+    VehicleAsleepError,
+)
+
+# ---------------------------------------------------------------------------
+# Region -> base URL mapping
+# ---------------------------------------------------------------------------
+
+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",
+    "cn": "https://fleet-api.prd.cn.vn.cloud.tesla.com",
+}
+
+# ---------------------------------------------------------------------------
+# Tesla Fleet API documented rate limits (per device, per account).
+# See: https://developer.tesla.com/docs/fleet-api/billing-and-limits
+# ---------------------------------------------------------------------------
+
+RATE_LIMITS = {
+    "data": 60,  # Realtime data: 60 req/min
+    "commands": 30,  # Device commands: 30 req/min
+    "wakes": 3,  # Wakes: 3 req/min
+    "auth": 20,  # Auth: 20 req/sec
+}
+_RATE_LIMIT_MAX_RETRIES = 3
+
+
+class TeslaFleetClient:
+    """Low-level async HTTP client for Tesla Fleet API endpoints."""
+
+    def __init__(
+        self,
+        access_token: str,
+        region: str = "na",
+        timeout: float = 30.0,
+        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)
+        if base_url is None:
+            msg = f"Unknown region {region!r}; expected one of {sorted(REGION_BASE_URLS)}"
+            raise ValueError(msg)
+
+        self._access_token = access_token
+        self._on_token_refresh = on_token_refresh
+        self._on_rate_limit_wait = on_rate_limit_wait
+        self._client = httpx.AsyncClient(
+            base_url=base_url,
+            timeout=timeout,
+            headers={"Authorization": f"Bearer {access_token}"},
+        )
+
+    # -- public helpers -----------------------------------------------------
+
+    async def get(self, path: str, **kwargs: Any) -> dict[str, Any]:
+        """Issue a GET request and return the parsed JSON body."""
+        return await self._request("GET", path, **kwargs)
+
+    async def post(self, path: str, **kwargs: Any) -> dict[str, Any]:
+        """Issue a POST request and return the parsed JSON body."""
+        return await self._request("POST", path, **kwargs)
+
+    async def delete(self, path: str, **kwargs: Any) -> dict[str, Any]:
+        """Issue a DELETE request and return the parsed JSON body."""
+        return await self._request("DELETE", path, **kwargs)
+
+    def update_token(self, access_token: str) -> None:
+        """Replace the current access token and update the header."""
+        self._access_token = access_token
+        self._client.headers["Authorization"] = f"Bearer {access_token}"
+
+    async def close(self) -> None:
+        """Close the underlying HTTP client."""
+        await self._client.aclose()
+
+    # -- async context manager -----------------------------------------------
+
+    async def __aenter__(self) -> TeslaFleetClient:
+        return self
+
+    async def __aexit__(
+        self,
+        exc_type: type[BaseException] | None,
+        exc_val: BaseException | None,
+        exc_tb: Any,
+    ) -> None:
+        await self.close()
+
+    # -- internal ------------------------------------------------------------
+
+    async def _request(
+        self,
+        method: str,
+        path: str,
+        **kwargs: Any,
+    ) -> dict[str, Any]:
+        """Issue an HTTP request with automatic retry on 429 rate-limit responses."""
+        for attempt in range(_RATE_LIMIT_MAX_RETRIES + 1):
+            try:
+                return await self._send(method, path, **kwargs)
+            except RateLimitError as exc:
+                if attempt >= _RATE_LIMIT_MAX_RETRIES:
+                    raise
+                wait = exc.retry_after or min(2 ** (attempt + 1), 30)
+                if self._on_rate_limit_wait:
+                    await self._on_rate_limit_wait(wait, attempt + 1, _RATE_LIMIT_MAX_RETRIES)
+                else:
+                    await asyncio.sleep(wait)
+        raise RateLimitError()  # unreachable, satisfies type checker
+
+    async def _send(
+        self,
+        method: str,
+        path: str,
+        *,
+        _retried: bool = False,
+        **kwargs: Any,
+    ) -> dict[str, Any]:
+        """Send a single HTTP request, handling auth refresh on 401."""
+        try:
+            response = await self._client.request(method, path, **kwargs)
+        except httpx.TimeoutException as exc:
+            raise NetworkError(f"Request timed out: {exc}") from exc
+        except httpx.ConnectError as exc:
+            raise NetworkError(f"Connection error: {exc}") from exc
+
+        # Handle 401 with optional token refresh
+        if response.status_code == 401 and not _retried:
+            if self._on_token_refresh is not None:
+                new_token = await self._on_token_refresh()
+                if new_token is not None:
+                    self.update_token(new_token)
+                    return await self._send(method, path, _retried=True, **kwargs)
+            raise AuthError("Authentication failed", status_code=401)
+
+        return self._parse_response(response)
+
+    @staticmethod
+    def _parse_response(response: httpx.Response) -> dict[str, Any]:
+        """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
+            raise RateLimitError(retry_after=retry_after)
+
+        if response.status_code == 408:
+            raise VehicleAsleepError("Vehicle is asleep", status_code=408)
+
+        if response.status_code == 412:
+            raise RegistrationRequiredError(
+                "Your application is not registered with the Tesla Fleet API "
+                "for this region. Run 'tescmd auth register' to fix this.",
+                status_code=412,
+            )
+
+        if response.status_code == 403:
+            text = response.text[:200]
+            if "missing scopes" in text.lower():
+                raise MissingScopesError(text, status_code=403)
+            raise AuthError(f"HTTP 403: {text}", status_code=403)
+
+        if response.status_code >= 400:
+            text = response.text[:200]
+            raise TeslaAPIError(
+                f"HTTP {response.status_code}: {text}",
+                status_code=response.status_code,
+            )
+
+        result: dict[str, Any] = response.json()
+        return result