wayfinder-paths 0.1.7__py3-none-any.whl

wayfinder_paths/core/clients/WayfinderClient.py

@@ -0,0 +1,269 @@
+import json
+import os
+import time
+from typing import Any
+
+import httpx
+from loguru import logger
+
+from wayfinder_paths.core.constants.base import DEFAULT_HTTP_TIMEOUT
+from wayfinder_paths.core.settings import settings
+
+
+class WayfinderClient:
+    def __init__(self, api_key: str | None = None):
+        """
+        Initialize WayfinderClient.
+
+        Args:
+            api_key: Optional API key for service account authentication.
+                    If provided, uses API key auth. Otherwise falls back to config.json.
+        """
+        self.api_base_url = f"{settings.WAYFINDER_API_URL}/"
+        timeout = httpx.Timeout(DEFAULT_HTTP_TIMEOUT)
+        self.client = httpx.AsyncClient(timeout=timeout)
+
+        self.headers = {
+            "Content-Type": "application/json",
+        }
+
+        self._api_key: str | None = api_key
+        self._access_token: str | None = None
+        self._refresh_token: str | None = None
+
+    def set_bearer_token(self, token: str) -> None:
+        """
+        Set runtime OAuth/JWT Bearer token for Django-backed Wayfinder services.
+        """
+        self.headers["Authorization"] = f"Bearer {token}"
+        self._access_token = token
+
+    def set_tokens(self, access: str | None, refresh: str | None) -> None:
+        """Set both access and refresh tokens and configure Authorization header."""
+        if access:
+            self.set_bearer_token(access)
+        if refresh:
+            self._refresh_token = refresh
+
+    def clear_auth(self) -> None:
+        """Clear Authorization headers (useful for logout or auth mode switch)."""
+        self.headers.pop("Authorization", None)
+
+    async def _refresh_access_token(self) -> bool:
+        """Attempt to refresh access token using stored refresh token."""
+        if not self._refresh_token:
+            logger.debug("No refresh token available")
+            return False
+        try:
+            logger.info("Attempting to refresh access token")
+            start_time = time.time()
+            url = f"{settings.WAYFINDER_API_URL}/auth/token/refresh/"
+            payload = {"refresh": self._refresh_token}
+            response = await self.client.post(
+                url, json=payload, headers={"Content-Type": "application/json"}
+            )
+            if response.status_code != 200:
+                logger.warning(
+                    f"Token refresh failed with status {response.status_code}"
+                )
+                return False
+            data = response.json()
+            new_access = data.get("access") or data.get("access_token")
+            if not new_access:
+                logger.warning("No access token in refresh response")
+                return False
+            self.set_bearer_token(new_access)
+            elapsed = time.time() - start_time
+            logger.info(f"Access token refreshed successfully in {elapsed:.2f}s")
+            return True
+        except Exception as e:
+            elapsed = time.time() - start_time
+            logger.error(f"Token refresh failed after {elapsed:.2f}s: {e}")
+            return False
+
+    def _load_config_credentials(self) -> dict[str, str | None]:
+        """
+        Load credentials from config.json. Path can be overridden via WAYFINDER_CONFIG_PATH.
+        Expected shape:
+        {
+          "user": { "username": ..., "password": ..., "refresh_token": ..., "api_key": ... },
+          "system": { "api_key": ... }
+        }
+        """
+        path = os.getenv("WAYFINDER_CONFIG_PATH", "config.json")
+        try:
+            with open(path) as f:
+                cfg = json.load(f)
+            user = cfg.get("user", {}) if isinstance(cfg, dict) else {}
+            system = cfg.get("system", {}) if isinstance(cfg, dict) else {}
+            return {
+                "username": user.get("username"),
+                "password": user.get("password"),
+                "refresh_token": user.get("refresh_token"),
+                "api_key": user.get("api_key") or system.get("api_key"),
+            }
+        except (FileNotFoundError, json.JSONDecodeError, OSError) as e:
+            logger.debug(f"Could not load config file at {path}: {e}")
+            return {
+                "username": None,
+                "password": None,
+                "refresh_token": None,
+                "api_key": None,
+            }
+        except Exception as e:
+            logger.warning(f"Unexpected error loading config file at {path}: {e}")
+            return {
+                "username": None,
+                "password": None,
+                "refresh_token": None,
+                "api_key": None,
+            }
+
+    async def _ensure_bearer_token(self) -> bool:
+        """
+        Ensure Authorization header is set. Priority: existing header > constructor api_key > config.json api_key > env api_key > config.json tokens > env tokens > username/password.
+        Raises PermissionError if no credentials found.
+        """
+        if self.headers.get("Authorization"):
+            return True
+
+        # Check for API key: constructor > config.json > environment
+        api_key = self._api_key
+        if not api_key:
+            creds = self._load_config_credentials()
+            api_key = creds.get("api_key") or os.getenv("WAYFINDER_API_KEY")
+
+        if api_key:
+            api_key = api_key.strip() if isinstance(api_key, str) else api_key
+            if not api_key:
+                raise ValueError("API key cannot be empty")
+            self.headers["Authorization"] = f"Bearer {api_key}"
+            return True
+
+        # Fall back to OAuth token-based auth
+        creds = self._load_config_credentials()
+        access = os.getenv("WAYFINDER_ACCESS_TOKEN")
+        refresh = creds.get("refresh_token") or os.getenv("WAYFINDER_REFRESH_TOKEN")
+
+        if access:
+            self.set_tokens(access, refresh)
+            return True
+
+        if refresh:
+            self._refresh_token = refresh
+            refreshed = await self._refresh_access_token()
+            if refreshed:
+                return True
+
+        username = creds.get("username") or os.getenv("WAYFINDER_USERNAME")
+        password = creds.get("password") or os.getenv("WAYFINDER_PASSWORD")
+
+        if username and password:
+            try:
+                url = f"{settings.WAYFINDER_API_URL}/auth/token/"
+                payload = {"username": username, "password": password}
+                response = await self.client.post(
+                    url,
+                    json=payload,
+                    headers={"Content-Type": "application/json"},
+                )
+                if response.status_code == 200:
+                    data = response.json()
+                    access = data.get("access") or data.get("access_token")
+                    refresh = data.get("refresh") or data.get("refresh_token")
+                self.set_tokens(access, refresh)
+                return bool(access)
+            except Exception as e:
+                logger.debug(f"Failed to authenticate with username/password: {e}")
+                pass
+
+        raise PermissionError(
+            "Not authenticated: provide api_key (via constructor, config.json, or WAYFINDER_API_KEY env var) for service account auth, "
+            "or username+password/refresh_token in config.json for personal access"
+        )
+
+    async def _request(
+        self,
+        method: str,
+        url: str,
+        *,
+        headers: dict[str, str] | None = None,
+        retry_on_401: bool = True,
+        **kwargs: Any,
+    ) -> httpx.Response:
+        """
+        Wrapper around httpx that injects headers and auto-refreshes tokens on 401 once.
+        Ensures API key or bearer token is set in headers when available (for service account auth and rate limits).
+        """
+        logger.debug(f"Making {method} request to {url}")
+        start_time = time.time()
+
+        # Ensure API key or bearer token is set in headers if available and not already set
+        # This ensures API keys are passed to all endpoints (including public ones) for rate limiting
+        if not self.headers.get("Authorization"):
+            # Try to get API key from constructor, config, or env
+            api_key = self._api_key
+            if not api_key:
+                creds = self._load_config_credentials()
+                api_key = creds.get("api_key") or os.getenv("WAYFINDER_API_KEY")
+
+            if api_key:
+                api_key = api_key.strip() if isinstance(api_key, str) else api_key
+                if api_key:
+                    self.headers["Authorization"] = f"Bearer {api_key}"
+
+        merged_headers = dict(self.headers)
+        if headers:
+            merged_headers.update(headers)
+        resp = await self.client.request(method, url, headers=merged_headers, **kwargs)
+
+        if resp.status_code == 401 and retry_on_401 and self._refresh_token:
+            logger.info("Received 401, attempting token refresh and retry")
+            refreshed = await self._refresh_access_token()
+            if refreshed:
+                merged_headers = dict(self.headers)
+                if headers:
+                    merged_headers.update(headers)
+                resp = await self.client.request(
+                    method, url, headers=merged_headers, **kwargs
+                )
+                logger.info("Retry after token refresh successful")
+            else:
+                logger.error("Token refresh failed, request will fail")
+
+        elapsed = time.time() - start_time
+        if resp.status_code >= 400:
+            logger.warning(
+                f"HTTP {resp.status_code} response for {method} {url} after {elapsed:.2f}s"
+            )
+        else:
+            logger.debug(
+                f"HTTP {resp.status_code} response for {method} {url} after {elapsed:.2f}s"
+            )
+
+        resp.raise_for_status()
+        return resp
+
+    async def _authed_request(
+        self,
+        method: str,
+        url: str,
+        *,
+        headers: dict[str, str] | None = None,
+        **kwargs: Any,
+    ) -> httpx.Response:
+        """
+        Ensure Authorization (via env/config creds) and perform the request.
+        Retries once on 401 by re-acquiring tokens.
+        """
+        ok = await self._ensure_bearer_token()
+        if not ok:
+            raise PermissionError("Not authenticated: set env tokens or credentials")
+        try:
+            return await self._request(method, url, headers=headers, **kwargs)
+        except httpx.HTTPStatusError as e:
+            if e.response is not None and e.response.status_code == 401:
+                # Retry after attempting re-acquire/refresh
+                await self._ensure_bearer_token()
+                return await self._request(method, url, headers=headers, **kwargs)
+            raise

wayfinder_paths/core/clients/__init__.py

@@ -0,0 +1,48 @@
+"""
+Core client modules for API communication
+"""
+
+from wayfinder_paths.core.clients.AuthClient import AuthClient
+from wayfinder_paths.core.clients.BRAPClient import BRAPClient
+from wayfinder_paths.core.clients.ClientManager import ClientManager
+from wayfinder_paths.core.clients.HyperlendClient import HyperlendClient
+from wayfinder_paths.core.clients.LedgerClient import LedgerClient
+from wayfinder_paths.core.clients.PoolClient import PoolClient
+from wayfinder_paths.core.clients.protocols import (
+    BRAPClientProtocol,
+    HyperlendClientProtocol,
+    LedgerClientProtocol,
+    PoolClientProtocol,
+    SimulationClientProtocol,
+    TokenClientProtocol,
+    TransactionClientProtocol,
+    WalletClientProtocol,
+)
+from wayfinder_paths.core.clients.SimulationClient import SimulationClient
+from wayfinder_paths.core.clients.TokenClient import TokenClient
+from wayfinder_paths.core.clients.TransactionClient import TransactionClient
+from wayfinder_paths.core.clients.WalletClient import WalletClient
+from wayfinder_paths.core.clients.WayfinderClient import WayfinderClient
+
+__all__ = [
+    "WayfinderClient",
+    "ClientManager",
+    "AuthClient",
+    "TokenClient",
+    "WalletClient",
+    "TransactionClient",
+    "LedgerClient",
+    "PoolClient",
+    "BRAPClient",
+    "SimulationClient",
+    "HyperlendClient",
+    # Protocols for SDK usage
+    "TokenClientProtocol",
+    "HyperlendClientProtocol",
+    "LedgerClientProtocol",
+    "WalletClientProtocol",
+    "TransactionClientProtocol",
+    "PoolClientProtocol",
+    "BRAPClientProtocol",
+    "SimulationClientProtocol",
+]

wayfinder_paths/core/clients/protocols.py

@@ -0,0 +1,392 @@
+"""
+Protocol definitions for API clients.
+
+These protocols define the interface that all client implementations must satisfy.
+When used as an SDK, users can provide custom implementations that match these protocols.
+
+Note: AuthClient is excluded as SDK users handle their own authentication.
+"""
+
+from __future__ import annotations
+
+from typing import TYPE_CHECKING, Any, Protocol
+
+if TYPE_CHECKING:
+    from wayfinder_paths.core.clients.BRAPClient import BRAPQuote
+    from wayfinder_paths.core.clients.HyperlendClient import (
+        AssetsView,
+        LendRateHistory,
+        MarketEntry,
+        StableMarket,
+    )
+    from wayfinder_paths.core.clients.LedgerClient import (
+        StrategyTransactionList,
+        TransactionRecord,
+    )
+    from wayfinder_paths.core.clients.PoolClient import (
+        LlamaMatch,
+        LlamaReport,
+        PoolList,
+    )
+    from wayfinder_paths.core.clients.SimulationClient import SimulationResult
+    from wayfinder_paths.core.clients.TokenClient import (
+        GasToken,
+        TokenDetails,
+    )
+    from wayfinder_paths.core.clients.TransactionClient import TransactionPayload
+    from wayfinder_paths.core.clients.WalletClient import (
+        PoolBalance,
+        TokenBalance,
+    )
+
+
+class TokenClientProtocol(Protocol):
+    """Protocol for token-related operations"""
+
+    async def get_token_details(
+        self, token_id: str, force_refresh: bool = False
+    ) -> TokenDetails:
+        """Get token data including price from the token-details endpoint"""
+        ...
+
+    async def get_gas_token(self, chain_code: str) -> GasToken:
+        """Fetch the native gas token for a given chain code"""
+        ...
+
+
+class HyperlendClientProtocol(Protocol):
+    """Protocol for Hyperlend-related operations"""
+
+    async def get_stable_markets(
+        self,
+        *,
+        chain_id: int,
+        required_underlying_tokens: float | None = None,
+        buffer_bps: int | None = None,
+        min_buffer_tokens: float | None = None,
+        is_stable_symbol: bool | None = None,
+    ) -> list[StableMarket]:
+        """Fetch stable markets from Hyperlend"""
+        ...
+
+    async def get_assets_view(
+        self,
+        *,
+        chain_id: int,
+        user_address: str,
+    ) -> AssetsView:
+        """Fetch assets view for a user address from Hyperlend"""
+        ...
+
+    async def get_market_entry(
+        self,
+        *,
+        chain_id: int,
+        token_address: str,
+    ) -> MarketEntry:
+        """Fetch market entry from Hyperlend"""
+        ...
+
+    async def get_lend_rate_history(
+        self,
+        *,
+        chain_id: int,
+        token_address: str,
+        lookback_hours: int,
+    ) -> LendRateHistory:
+        """Fetch lend rate history from Hyperlend"""
+        ...
+
+
+class LedgerClientProtocol(Protocol):
+    """Protocol for strategy transaction history and bookkeeping operations"""
+
+    async def get_strategy_transactions(
+        self,
+        *,
+        wallet_address: str,
+        limit: int = 50,
+        offset: int = 0,
+    ) -> StrategyTransactionList:
+        """Fetch a paginated list of transactions for a given strategy wallet"""
+        ...
+
+    async def get_strategy_net_deposit(self, *, wallet_address: str) -> float:
+        """Fetch the net deposit (deposits - withdrawals) for a strategy"""
+        ...
+
+    async def get_strategy_latest_transactions(
+        self, *, wallet_address: str
+    ) -> StrategyTransactionList:
+        """Fetch the latest transactions for a strategy"""
+        ...
+
+    async def add_strategy_deposit(
+        self,
+        *,
+        wallet_address: str,
+        chain_id: int,
+        token_address: str,
+        token_amount: str | float,
+        usd_value: str | float,
+        data: dict[str, Any] | None = None,
+        strategy_name: str | None = None,
+    ) -> TransactionRecord:
+        """Record a deposit for a strategy"""
+        ...
+
+    async def add_strategy_withdraw(
+        self,
+        *,
+        wallet_address: str,
+        chain_id: int,
+        token_address: str,
+        token_amount: str | float,
+        usd_value: str | float,
+        data: dict[str, Any] | None = None,
+        strategy_name: str | None = None,
+    ) -> TransactionRecord:
+        """Record a withdrawal for a strategy"""
+        ...
+
+    async def add_strategy_operation(
+        self,
+        *,
+        wallet_address: str,
+        operation_data: dict[str, Any],
+        usd_value: str | float,
+        strategy_name: str | None = None,
+    ) -> TransactionRecord:
+        """Record a strategy operation (e.g., swaps, rebalances)"""
+        ...
+
+
+class WalletClientProtocol(Protocol):
+    """Protocol for wallet-related operations"""
+
+    async def get_token_balance_for_wallet(
+        self,
+        *,
+        token_id: str,
+        wallet_address: str,
+        human_readable: bool = True,
+    ) -> TokenBalance:
+        """Fetch a single token balance for an explicit wallet address"""
+        ...
+
+    async def get_pool_balance_for_wallet(
+        self,
+        *,
+        pool_address: str,
+        chain_id: int,
+        user_address: str,
+        human_readable: bool = True,
+    ) -> PoolBalance:
+        """Fetch a wallet's LP/share balance for a given pool address and chain"""
+        ...
+
+
+class TransactionClientProtocol(Protocol):
+    """Protocol for transaction operations"""
+
+    async def build_send(
+        self,
+        from_address: str,
+        to_address: str,
+        token_address: str,
+        amount: float,
+        chain_id: int,
+    ) -> TransactionPayload:
+        """Build a send transaction payload for EVM tokens/native transfers"""
+        ...
+
+
+class PoolClientProtocol(Protocol):
+    """Protocol for pool-related read operations"""
+
+    async def get_pools_by_ids(
+        self,
+        *,
+        pool_ids: str,
+        merge_external: bool | None = None,
+    ) -> PoolList:
+        """Fetch pools by comma-separated pool ids"""
+        ...
+
+    async def get_all_pools(self, *, merge_external: bool | None = None) -> PoolList:
+        """Fetch all pools"""
+        ...
+
+    async def get_llama_matches(self) -> dict[str, LlamaMatch]:
+        """Fetch Llama matches for pools"""
+        ...
+
+    async def get_llama_reports(self, *, identifiers: str) -> dict[str, LlamaReport]:
+        """Fetch Llama reports using identifiers"""
+        ...
+
+
+class BRAPClientProtocol(Protocol):
+    """Protocol for BRAP (Bridge/Router/Adapter Protocol) quote operations"""
+
+    async def get_quote(
+        self,
+        *,
+        from_token_address: str,
+        to_token_address: str,
+        from_chain_id: int,
+        to_chain_id: int,
+        from_address: str,
+        to_address: str,
+        amount1: str,
+        slippage: float | None = None,
+        wayfinder_fee: float | None = None,
+    ) -> BRAPQuote:
+        """Get a quote for a bridge/swap operation"""
+        ...
+
+
+class SimulationClientProtocol(Protocol):
+    """Protocol for blockchain transaction simulations"""
+
+    async def simulate_send(
+        self,
+        from_address: str,
+        to_address: str,
+        token_address: str,
+        amount: str,
+        chain_id: int,
+        initial_balances: dict[str, str],
+    ) -> SimulationResult:
+        """Simulate sending native ETH or ERC20 tokens"""
+        ...
+
+    async def simulate_approve(
+        self,
+        from_address: str,
+        to_address: str,
+        token_address: str,
+        amount: str,
+        chain_id: int,
+        initial_balances: dict[str, str],
+        clear_approval_first: bool = False,
+    ) -> SimulationResult:
+        """Simulate ERC20 token approval"""
+        ...
+
+    async def simulate_swap(
+        self,
+        from_token_address: str,
+        to_token_address: str,
+        from_chain_id: int,
+        to_chain_id: int,
+        amount: str,
+        from_address: str,
+        slippage: float,
+        initial_balances: dict[str, str],
+    ) -> SimulationResult:
+        """Simulate token swap operation"""
+        ...
+
+
+class HyperliquidExecutorProtocol(Protocol):
+    """Protocol for Hyperliquid order execution operations."""
+
+    async def place_market_order(
+        self,
+        *,
+        asset_id: int,
+        is_buy: bool,
+        slippage: float,
+        size: float,
+        address: str,
+        reduce_only: bool = False,
+        cloid: Any = None,
+        builder: dict[str, Any] | None = None,
+    ) -> dict[str, Any]:
+        """Place a market order."""
+        ...
+
+    async def cancel_order(
+        self,
+        *,
+        asset_id: int,
+        order_id: int,
+        address: str,
+    ) -> dict[str, Any]:
+        """Cancel an open order."""
+        ...
+
+    async def update_leverage(
+        self,
+        *,
+        asset_id: int,
+        leverage: int,
+        is_cross: bool,
+        address: str,
+    ) -> dict[str, Any]:
+        """Update leverage for an asset."""
+        ...
+
+    async def transfer_spot_to_perp(
+        self,
+        *,
+        amount: float,
+        address: str,
+    ) -> dict[str, Any]:
+        """Transfer USDC from spot to perp balance."""
+        ...
+
+    async def transfer_perp_to_spot(
+        self,
+        *,
+        amount: float,
+        address: str,
+    ) -> dict[str, Any]:
+        """Transfer USDC from perp to spot balance."""
+        ...
+
+    async def place_stop_loss(
+        self,
+        *,
+        asset_id: int,
+        is_buy: bool,
+        trigger_price: float,
+        size: float,
+        address: str,
+    ) -> dict[str, Any]:
+        """Place a stop-loss order."""
+        ...
+
+    async def place_limit_order(
+        self,
+        *,
+        asset_id: int,
+        is_buy: bool,
+        price: float,
+        size: float,
+        address: str,
+        reduce_only: bool = False,
+        builder: dict[str, Any] | None = None,
+    ) -> dict[str, Any]:
+        """Place a limit order."""
+        ...
+
+    async def withdraw(
+        self,
+        *,
+        amount: float,
+        address: str,
+    ) -> dict[str, Any]:
+        """Withdraw USDC from Hyperliquid to Arbitrum."""
+        ...
+
+    async def approve_builder_fee(
+        self,
+        *,
+        builder: str,
+        max_fee_rate: str,
+        address: str,
+    ) -> dict[str, Any]:
+        """Approve a builder fee for the user."""
+        ...