edapitool 0.6.3__py3-none-any.whl

APITool/capi.py

@@ -0,0 +1,292 @@
+"""
+Elite Dangerous Companion API (CAPI) client.
+
+Provides access to game data including:
+- Commander profile
+- Market data
+- Fleet carrier information
+- Ship/module data
+"""
+
+import json
+import time
+from datetime import datetime
+from pathlib import Path
+from typing import Optional, Any
+
+import requests
+
+from .constants import (
+    CAPI_SERVER_LIVE,
+    CAPI_SERVER_LEGACY,
+    CAPI_SERVER_BETA,
+    CAPI_PATH_PROFILE,
+    CAPI_PATH_MARKET,
+    CAPI_PATH_SHIPYARD,
+    CAPI_PATH_FLEETCARRIER,
+    CAPI_PATH_COMMUNITYGOALS,
+    DEFAULT_TIMEOUT,
+    FLEETCARRIER_TIMEOUT,
+    MIN_QUERY_INTERVAL,
+    FLEETCARRIER_COOLDOWN,
+)
+from .auth import FrontierAuth
+
+
+class CAPIError(Exception):
+    """Base exception for CAPI errors."""
+
+    pass
+
+
+class CAPIAuthError(CAPIError):
+    """Authentication error with CAPI."""
+
+    pass
+
+
+class CAPIRateLimitError(CAPIError):
+    """Rate limit exceeded."""
+
+    pass
+
+
+class CAPINoDataError(CAPIError):
+    """No data available (e.g., no fleet carrier owned)."""
+
+    pass
+
+
+class CAPIClient:
+    """
+    Client for the Elite Dangerous Companion API.
+
+    Example usage:
+        auth = FrontierAuth(client_id="your_client_id")
+        if not auth.is_authenticated:
+            auth.authorize()
+
+        client = CAPIClient(auth)
+        profile = client.get_profile()
+        carrier = client.get_fleet_carrier()
+    """
+
+    def __init__(
+        self,
+        auth: FrontierAuth,
+        server: str = CAPI_SERVER_LIVE,
+        debug_dir: Optional[Path] = None,
+        fleet_carrier_cooldown: Optional[float] = None,
+    ):
+        """
+        Initialize the CAPI client.
+
+        Args:
+            auth: Authenticated FrontierAuth instance
+            server: CAPI server URL (default: live server)
+            debug_dir: Optional directory to save debug JSON responses
+            fleet_carrier_cooldown: seconds to enforce between fleet-carrier
+                queries, defaulting to FLEETCARRIER_COOLDOWN. This is OUR
+                politeness, not a limit Frontier imposes -- measured: two
+                calls one second apart both succeeded in about a second and
+                returned byte-identical cached data. A long-running publisher
+                may lower it deliberately; passing a number here is how that
+                is said out loud, rather than by building a fresh client per
+                call and letting the counter start from zero each time.
+        """
+        self.auth = auth
+        self.server = server
+        self.debug_dir = debug_dir
+        self.fleet_carrier_cooldown = (
+            FLEETCARRIER_COOLDOWN if fleet_carrier_cooldown is None
+            else fleet_carrier_cooldown
+        )
+        self._last_query_time: float = 0
+        self._last_fc_query_time: float = 0
+
+    def _get_headers(self) -> dict:
+        """Get request headers with authorization."""
+        token = self.auth.access_token
+        if not token:
+            raise CAPIAuthError("No access token available. Please authenticate first.")
+        return {
+            "Authorization": f"Bearer {token}",
+            "User-Agent": "EDAPITool/0.1.0",
+        }
+
+    def _check_rate_limit(self, is_fleet_carrier: bool = False) -> None:
+        """Check and enforce rate limiting."""
+        now = time.time()
+
+        if is_fleet_carrier:
+            elapsed = now - self._last_fc_query_time
+            if elapsed < self.fleet_carrier_cooldown:
+                wait_time = self.fleet_carrier_cooldown - elapsed
+                raise CAPIRateLimitError(
+                    f"Fleet carrier query cooldown. Wait {wait_time:.0f} seconds."
+                )
+        else:
+            elapsed = now - self._last_query_time
+            if elapsed < MIN_QUERY_INTERVAL:
+                # For regular queries, just wait
+                time.sleep(MIN_QUERY_INTERVAL - elapsed)
+
+    def _save_debug(self, endpoint: str, data: dict) -> None:
+        """Save response to debug file if debug_dir is set."""
+        if not self.debug_dir:
+            return
+
+        self.debug_dir.mkdir(parents=True, exist_ok=True)
+        timestamp = datetime.now().strftime("%Y%m%d_%H%M%S")
+        endpoint_name = endpoint.strip("/").replace("/", "_")
+        filename = f"{endpoint_name}.{timestamp}.json"
+        filepath = self.debug_dir / filename
+
+        with open(filepath, "w", encoding="utf-8") as f:
+            json.dump(data, f, indent=2, ensure_ascii=False)
+
+    def _request(
+        self,
+        endpoint: str,
+        timeout: int = DEFAULT_TIMEOUT,
+        is_fleet_carrier: bool = False,
+    ) -> dict:
+        """
+        Make an authenticated request to the CAPI.
+
+        Args:
+            endpoint: API endpoint path
+            timeout: Request timeout in seconds
+            is_fleet_carrier: Whether this is a fleet carrier query
+
+        Returns:
+            JSON response as dictionary
+
+        Raises:
+            CAPIAuthError: Authentication failed
+            CAPIRateLimitError: Rate limit exceeded
+            CAPINoDataError: No data available
+            CAPIError: Other API errors
+        """
+        self._check_rate_limit(is_fleet_carrier)
+
+        url = f"{self.server}{endpoint}"
+
+        try:
+            response = requests.get(
+                url,
+                headers=self._get_headers(),
+                timeout=timeout,
+            )
+
+            # Update query times
+            if is_fleet_carrier:
+                self._last_fc_query_time = time.time()
+            self._last_query_time = time.time()
+
+            # Handle response codes
+            if response.status_code == 200:
+                data = response.json()
+                self._save_debug(endpoint, data)
+                return data
+
+            elif response.status_code == 204:
+                raise CAPINoDataError(f"No data available for {endpoint}")
+
+            elif response.status_code == 401:
+                raise CAPIAuthError("Authentication failed. Token may be expired.")
+
+            elif response.status_code == 422:
+                # Token expired, try to refresh
+                if self.auth.refresh():
+                    # Retry the request
+                    return self._request(endpoint, timeout, is_fleet_carrier)
+                raise CAPIAuthError("Token expired and refresh failed.")
+
+            elif response.status_code == 429:
+                raise CAPIRateLimitError("Rate limit exceeded. Please wait.")
+
+            else:
+                raise CAPIError(
+                    f"CAPI request failed: {response.status_code} - {response.text}"
+                )
+
+        except requests.Timeout:
+            raise CAPIError(f"Request timed out after {timeout} seconds")
+        except requests.RequestException as e:
+            raise CAPIError(f"Request failed: {e}")
+
+    def get_profile(self) -> dict:
+        """
+        Get commander profile data.
+
+        Returns:
+            Commander profile including name, credits, ranks, ships, etc.
+        """
+        return self._request(CAPI_PATH_PROFILE)
+
+    def get_market(self) -> dict:
+        """
+        Get current station market data.
+
+        Returns:
+            Market data for the current docked station.
+        """
+        return self._request(CAPI_PATH_MARKET)
+
+    def get_shipyard(self) -> dict:
+        """
+        Get current station shipyard data.
+
+        Returns:
+            Available ships at the current docked station.
+        """
+        return self._request(CAPI_PATH_SHIPYARD)
+
+    def get_fleet_carrier(self) -> dict:
+        """
+        Get fleet carrier data.
+
+        Returns:
+            Complete fleet carrier data including:
+            - Identity (callsign, name)
+            - Location and status
+            - Cargo and inventory
+            - Market orders
+            - Financial information
+            - Services and crew
+            - Travel history
+
+        Raises:
+            CAPINoDataError: Player doesn't own a fleet carrier
+            CAPIRateLimitError: Must wait 15 minutes between queries
+        """
+        return self._request(
+            CAPI_PATH_FLEETCARRIER,
+            timeout=FLEETCARRIER_TIMEOUT,
+            is_fleet_carrier=True,
+        )
+
+    def get_community_goals(self) -> dict:
+        """
+        Get active community goals.
+
+        Returns:
+            List of active community goals with progress.
+        """
+        return self._request(CAPI_PATH_COMMUNITYGOALS)
+
+    @staticmethod
+    def use_live_server() -> str:
+        """Get the live server URL."""
+        return CAPI_SERVER_LIVE
+
+    @staticmethod
+    def use_legacy_server() -> str:
+        """Get the legacy server URL."""
+        return CAPI_SERVER_LEGACY
+
+    @staticmethod
+    def use_beta_server() -> str:
+        """Get the beta/PTS server URL."""
+        return CAPI_SERVER_BETA

APITool/cargo.py

@@ -0,0 +1,148 @@
+"""
+The shared column contract for every generated cargo tab.
+
+An inventory tab -- the fleet carrier's hold, the ship's hold, and whatever
+comes next -- publishes the same three columns in the same three places:
+
+    A          margin, always empty
+    B          Commodity     <- the lookup key
+    C          Quantity      <- VLOOKUP index 2
+    D          Unit Price    <- VLOOKUP index 3
+
+**Everything right of D is that tab's own business.** The carrier carries a
+total value because it has real prices and someone reads that tab by eye; the
+ship carries symbol and stolen flags. Neither needs the other's tail, and
+forcing one would mean emitting columns a producer cannot fill.
+
+Why the first three are fixed, and why this module exists to fix them:
+
+A spreadsheet reads these tabs with ``VLOOKUP($B5, <tab>!$B:$D, 3, FALSE)``.
+That ``3`` is a LITERAL, not a reference. Insert a column left of D and Google
+Sheets widens the range to ``$B:$E`` automatically -- and leaves the literal
+alone. Measured 2026-09-08 on a throwaway tab: after inserting one column,
+index 2 returned the newly inserted column and index 3 returned Quantity.
+Every lookup shifted one column right, silently, with no error anywhere.
+
+There were 476 such formulas in the live workbook when this was written. So
+the constraint is not "keep the columns tidy" -- it is **never insert a column
+left of D**, and the test that asserts these indices is the only thing
+standing between a refactor and several hundred quietly wrong numbers.
+
+Adding a column to the RIGHT of D is always safe, which is where a future
+``Category`` belongs if it is ever wanted.
+"""
+
+from __future__ import annotations
+
+from typing import Iterable, Sequence
+
+# Column A is left empty as a margin, matching FreighterData and MarketData.
+MARGIN = ""
+
+# The three columns every cargo tab shares, in order, starting at column B.
+CONTRACT_HEADERS = ["Commodity", "Quantity", "Unit Price"]
+
+# What a spreadsheet passes as VLOOKUP's index argument against $B:$D.
+# These are the numbers that appear as literals in the sheet's formulas, so
+# they are part of the published contract and cannot change without editing
+# every formula that uses them.
+INDEX_COMMODITY = 1
+INDEX_QUANTITY = 2
+INDEX_UNIT_PRICE = 3
+
+# The A1 range a consumer should look up against.
+LOOKUP_RANGE = "$B:$D"
+
+
+def header_row(extra: Sequence[str] = ()) -> list:
+    """
+    The header row: margin, the three contract headers, then this tab's own.
+
+    ``extra`` lands right of Unit Price, where adding columns is safe.
+    """
+    return [MARGIN, *CONTRACT_HEADERS, *extra]
+
+
+def data_row(
+    commodity: str,
+    quantity: object,
+    unit_price: object = "",
+    extra: Sequence[object] = (),
+) -> list:
+    """
+    One commodity row.
+
+    ``unit_price`` defaults to empty rather than zero. A blank cell reads as
+    "not known" and sums as nothing; a zero reads as "worthless", which is a
+    different and wrong claim about cargo whose price this tool has no source
+    for. Sheets coerces the empty string to 0 in arithmetic, so a SUM over the
+    column still works.
+    """
+    return [MARGIN, commodity, quantity, unit_price, *extra]
+
+
+def lookup_formula(key_cell: str, tab: str, index: int) -> str:
+    """
+    The formula a sheet should use against a cargo tab.
+
+    Rendered here so the documentation, the README and any --show-formula
+    output cannot drift from the contract they describe.
+
+    IFNA rather than IFERROR: IFNA blanks a commodity that is not in the tab,
+    but still surfaces a #REF! if the tab is renamed or deleted. IFERROR hides
+    that too, and a silently blank column feeds the sheet's arithmetic a
+    number that looks deliberate.
+    """
+    return f'=IFNA(VLOOKUP({key_cell}, {tab}!{LOOKUP_RANGE}, {index}, FALSE), "")'
+
+
+def verify_contract(grid: Iterable[Sequence], header_row_index: int) -> None:
+    """
+    Raise unless a built grid honours the contract.
+
+    Cheap enough to call from a producer before writing, and the thing a test
+    asserts. Checks the header text and, crucially, that the contract columns
+    sit at the offsets the published VLOOKUP indices name.
+    """
+    rows = list(grid)
+    if header_row_index >= len(rows):
+        raise ValueError(f"no header row at index {header_row_index}")
+    header = list(rows[header_row_index])
+
+    if not header or header[0] != MARGIN:
+        raise ValueError(f"column A must be an empty margin, found {header[:1]!r}")
+
+    # Check the INDICES, not the header list. Comparing the B-D slice against
+    # CONTRACT_HEADERS would be equivalent -- and was, in the first draft --
+    # but it reports "the headers differ" when what actually broke is "index 3
+    # no longer means Unit Price". The index is what the user's formulas carry
+    # as a literal, so it is what the error should name.
+    #
+    # VLOOKUP index N against $B:$D is header[N], because the margin is at 0.
+    for index, expected in (
+        (INDEX_COMMODITY, "Commodity"),
+        (INDEX_QUANTITY, "Quantity"),
+        (INDEX_UNIT_PRICE, "Unit Price"),
+    ):
+        found = header[index] if index < len(header) else None
+        if found != expected:
+            raise ValueError(
+                f"VLOOKUP index {index} must address {expected!r}, found {found!r}. "
+                f"Cargo tabs expose {CONTRACT_HEADERS} in columns B-D; a column "
+                f"was inserted or renamed left of D, which shifts every lookup "
+                f"in the workbook without raising anything in the sheet."
+            )
+
+
+__all__ = [
+    "CONTRACT_HEADERS",
+    "INDEX_COMMODITY",
+    "INDEX_QUANTITY",
+    "INDEX_UNIT_PRICE",
+    "LOOKUP_RANGE",
+    "MARGIN",
+    "data_row",
+    "header_row",
+    "lookup_formula",
+    "verify_contract",
+]