client.py

"""
OilPriceAPI Client

Main client class for interacting with OilPriceAPI.
"""

import json
import logging
import os
import time
from datetime import datetime
from typing import TYPE_CHECKING, Any, Dict, List, Optional, Tuple
from urllib.parse import urljoin

import httpx

if TYPE_CHECKING:
    from .visualization import PriceVisualizer

logger = logging.getLogger(__name__)

from ._subscriptions_common import unwrap_data
from .exceptions import (
    AuthenticationError,
    ConfigurationError,
    DataNotFoundError,
    OilPriceAPIError,
    RateLimitError,
    ServerError,
    TimeoutError,
    ValidationError,
)
from .models import DataConnectorPrice, MarketBrief
from .resources.alerts import AlertsResource
from .resources.analysis import AnalysisResource
from .resources.analytics import AnalyticsResource
from .resources.bunker_fuels import BunkerFuelsResource
from .resources.commodities import CommoditiesResource
from .resources.data_quality import DataQualityResource
from .resources.data_sources import DataSourcesResource
from .resources.demo import DemoResource
from .resources.diesel import DieselResource
from .resources.drilling import DrillingIntelligenceResource
from .resources.ei import EnergyIntelligenceResource
from .resources.forecasts import ForecastsResource
from .resources.futures import FuturesResource
from .resources.historical import HistoricalResource
from .resources.prices import PricesResource
from .resources.rig_counts import RigCountsResource
from .resources.storage import StorageResource
from .resources.subscriptions import SubscriptionsResource
from .resources.webhooks import WebhooksResource
from .retry import RetryStrategy


class OilPriceAPI:
    """Main synchronous client for OilPriceAPI.

    Thread Safety: The underlying httpx.Client is thread-safe and can be used
    from multiple threads. However, you should not modify client attributes
    (like headers) after initialization when using from multiple threads.

    Resource Management: Always use context managers (with statement) or
    explicitly call close() to ensure proper cleanup of network resources.
    Do not rely on __del__ for cleanup as it is non-deterministic.

    Args:
        api_key: API key for authentication. If not provided, uses OILPRICEAPI_KEY env var.
        base_url: Base URL for API. Defaults to production.
        timeout: Request timeout in seconds. Defaults to 30.
        max_retries: Maximum retry attempts for failed requests. Defaults to 3.
        retry_on: Status codes to retry on. Defaults to [429, 500, 502, 503, 504].

    Example:
        >>> # Recommended: Use context manager for automatic cleanup
        >>> with OilPriceAPI() as client:
        ...     price = client.prices.get("BRENT_CRUDE_USD")
        ...     print(f"Brent: ${price.value:.2f}")

        >>> # Or explicitly manage lifecycle
        >>> client = OilPriceAPI()
        >>> try:
        ...     price = client.prices.get("BRENT_CRUDE_USD")
        ... finally:
        ...     client.close()
    """

    DEFAULT_BASE_URL = "https://api.oilpriceapi.com"
    DEFAULT_TIMEOUT = 30
    DEFAULT_MAX_RETRIES = 3
    DEFAULT_RETRY_CODES = [429, 500, 502, 503, 504]

    def __init__(
        self,
        api_key: Optional[str] = None,
        base_url: Optional[str] = None,
        timeout: Optional[float] = None,
        max_retries: Optional[int] = None,
        retry_on: Optional[List[int]] = None,
        headers: Optional[Dict[str, str]] = None,
        app_url: Optional[str] = None,
        app_name: Optional[str] = None,
        enable_telemetry: bool = False,
    ):
        # Get API key from parameter or environment
        self.api_key = api_key or os.environ.get("OILPRICEAPI_KEY")
        if not self.api_key:
            logger.error("API key not provided - client initialization failed")
            raise ConfigurationError(
                "API key required. Set OILPRICEAPI_KEY environment variable or pass api_key parameter."
            )

        # Configuration
        self.base_url = (base_url or self.DEFAULT_BASE_URL).rstrip("/")
        self.timeout = timeout or self.DEFAULT_TIMEOUT
        self.max_retries = max_retries or self.DEFAULT_MAX_RETRIES
        self.retry_on = retry_on or self.DEFAULT_RETRY_CODES

        # Initialize retry strategy
        self._retry_strategy = RetryStrategy(
            max_retries=self.max_retries,
            retry_on=self.retry_on
        )

        logger.debug(
            f"Initialized OilPriceAPI client: base_url={self.base_url}, "
            f"timeout={self.timeout}s, max_retries={self.max_retries}"
        )

        # Store telemetry settings
        self.app_url = app_url
        self.app_name = app_name

        # Build headers
        import sys

        from .version import SDK_NAME, SDK_VERSION
        python_version = f"{sys.version_info.major}.{sys.version_info.minor}.{sys.version_info.micro}"
        self.headers = {
            "Authorization": f"Token {self.api_key}",
            "Content-Type": "application/json",
            "Accept": "application/json",
            "User-Agent": f"{SDK_NAME}/{SDK_VERSION} python/{python_version}",
            "X-SDK-Name": SDK_NAME,
            "X-SDK-Version": SDK_VERSION,
            "X-SDK-Language": "python",
            "X-Client-Type": "sdk",
        }

        # Add optional telemetry headers (10% bonus for app_url!)
        if self.app_url:
            self.headers["X-App-URL"] = self.app_url
        if self.app_name:
            self.headers["X-App-Name"] = self.app_name

        if headers:
            self.headers.update(headers)

        # Create HTTP client
        self._client = httpx.Client(
            base_url=self.base_url,
            headers=self.headers,
            timeout=self.timeout,
            follow_redirects=True,
        )

        # Initialize resources
        self.prices = PricesResource(self)
        self.historical = HistoricalResource(self)
        self.diesel = DieselResource(self)
        self.alerts = AlertsResource(self)
        self.commodities = CommoditiesResource(self)
        self.futures = FuturesResource(self)
        self.storage = StorageResource(self)
        self.rig_counts = RigCountsResource(self)
        self.bunker_fuels = BunkerFuelsResource(self)
        self.analytics = AnalyticsResource(self)
        self.analysis = AnalysisResource(self)
        self.forecasts = ForecastsResource(self)
        self.data_quality = DataQualityResource(self)
        self.drilling = DrillingIntelligenceResource(self)
        self.ei = EnergyIntelligenceResource(self)
        self.webhooks = WebhooksResource(self)
        self.data_sources = DataSourcesResource(self)
        # Agent watch subscriptions + event polling (#3245 Phase 2).
        self.subscriptions = SubscriptionsResource(self)
        # Public, no-auth demo endpoints (/v1/demo/*).
        self.demo = DemoResource(self)

        # Initialize visualization (optional)
        self.viz: Optional["PriceVisualizer"]
        try:
            from .visualization import PriceVisualizer
            self.viz = PriceVisualizer(self)
        except ImportError:
            self.viz = None

        # Initialize telemetry (opt-in, disabled by default)
        from .telemetry import Telemetry
        self._telemetry = Telemetry(enabled=enable_telemetry)

    def request(
        self,
        method: str,
        path: str,
        params: Optional[Dict[str, Any]] = None,
        json_data: Optional[Dict[str, Any]] = None,
        timeout: Optional[float] = None,
        **kwargs
    ) -> Dict[str, Any]:
        """Make HTTP request to API.

        Warning: This method uses blocking time.sleep() for retries.
        For async/await applications, use AsyncOilPriceAPI instead.

        Args:
            method: HTTP method (GET, POST, etc.)
            path: API endpoint path
            params: Query parameters
            json_data: JSON body data
            timeout: Request timeout in seconds. If None, uses client's default timeout.
            **kwargs: Additional httpx request arguments

        Returns:
            Parsed JSON response dict

        Raises:
            OilPriceAPIError: On API errors
            AuthenticationError: On 401 status
            RateLimitError: On 429 status
            DataNotFoundError: On 404 status
            ServerError: On 5xx status
            TimeoutError: On request timeout
        """
        # Ensure path starts with / for proper urljoin behavior
        if not path.startswith('/'):
            path = '/' + path
        url = urljoin(self.base_url + '/', path)

        # Use provided timeout or default
        effective_timeout = timeout if timeout is not None else self.timeout

        # Retry logic using retry strategy
        last_exception: Optional[OilPriceAPIError] = None
        start_time = time.time()
        for attempt in range(self.max_retries):
            try:
                logger.debug(f"API request: {method} {url} (attempt {attempt + 1}/{self.max_retries})")

                response = self._client.request(
                    method=method,
                    url=url,
                    params=params,
                    json=json_data,
                    timeout=effective_timeout,
                    **kwargs
                )

                logger.debug(f"API response: {response.status_code} for {method} {url}")

                # Handle different status codes
                if response.status_code == 200:
                    self._telemetry.track_request(
                        operation=self._sanitize_path_for_telemetry(method, path),
                        duration=time.time() - start_time,
                        success=True,
                    )
                    return response.json()
                elif response.status_code == 401:
                    logger.error(f"Authentication failed for {url}")
                    raise AuthenticationError("Invalid API key or authentication failed")
                elif response.status_code == 404:
                    error_data = self._safe_parse_json(response)
                    raise DataNotFoundError(
                        message=error_data.get("error", "Resource not found"),
                        commodity=params.get("commodity") if params else None,
                    )
                elif response.status_code == 422:
                    error_data = self._safe_parse_json(response)
                    raise ValidationError(
                        message=error_data.get("error", "Validation failed"),
                        field=error_data.get("field"),
                        value=error_data.get("value"),
                    )
                elif response.status_code == 429:
                    # Parse rate limit headers
                    reset_time = self._parse_rate_limit_reset(response.headers)
                    retry_after = response.headers.get("Retry-After")
                    logger.warning(
                        f"Rate limit exceeded. Limit: {response.headers.get('X-RateLimit-Limit')}, "
                        f"Remaining: {response.headers.get('X-RateLimit-Remaining')}"
                    )

                    # Auto-retry with Retry-After if we have attempts left
                    if self._retry_strategy.should_retry(attempt, 429):
                        wait_time = min(float(retry_after), 60.0) if retry_after else self._retry_strategy.calculate_wait_time(attempt)
                        logger.info(f"Rate limited. Retrying in {wait_time}s (attempt {attempt + 1}/{self.max_retries})")
                        time.sleep(wait_time)
                        continue

                    raise RateLimitError(
                        message="Rate limit exceeded",
                        reset_time=reset_time,
                        limit=response.headers.get("X-RateLimit-Limit"),
                        remaining=response.headers.get("X-RateLimit-Remaining"),
                    )
                elif response.status_code >= 500:
                    if self._retry_strategy.should_retry(attempt, response.status_code):
                        wait_time = self._retry_strategy.calculate_wait_time(attempt)
                        self._retry_strategy.log_retry(
                            attempt,
                            f"Server error {response.status_code}",
                            wait_time,
                            is_async=False
                        )
                        time.sleep(wait_time)
                        continue
                    raise ServerError(
                        message=f"Server error: {response.status_code}",
                        status_code=response.status_code,
                    )
                else:
                    error_data = self._safe_parse_json(response)
                    raise OilPriceAPIError(
                        message=error_data.get("error", f"Unexpected error: {response.status_code}"),
                        status_code=response.status_code,
                        response=error_data,
                    )

            except httpx.TimeoutException:
                last_exception = TimeoutError(
                    message="Request timed out",
                    timeout=self.timeout,
                )
                if self._retry_strategy.should_retry_on_exception(attempt):
                    wait_time = self._retry_strategy.calculate_wait_time(attempt)
                    self._retry_strategy.log_retry(
                        attempt,
                        "Request timeout",
                        wait_time,
                        is_async=False
                    )
                    time.sleep(wait_time)
                    continue
                logger.error(f"Request timed out after {self.max_retries} attempts")
                raise last_exception
            except httpx.RequestError as e:
                last_exception = OilPriceAPIError(
                    message=f"Request failed: {str(e)}",
                )
                if self._retry_strategy.should_retry_on_exception(attempt):
                    wait_time = self._retry_strategy.calculate_wait_time(attempt)
                    self._retry_strategy.log_retry(
                        attempt,
                        f"Request error: {e}",
                        wait_time,
                        is_async=False
                    )
                    time.sleep(wait_time)
                    continue
                logger.error(f"Request failed after {self.max_retries} attempts: {e}")
                raise last_exception

        if last_exception:
            self._telemetry.track_request(
                operation=f"{method} {path}",
                duration=time.time() - start_time,
                success=False,
                error_type=type(last_exception).__name__,
            )
            raise last_exception

        raise OilPriceAPIError("Max retries exceeded")

    def request_with_headers(
        self,
        method: str,
        path: str,
        params: Optional[Dict[str, Any]] = None,
        json_data: Optional[Dict[str, Any]] = None,
        timeout: Optional[float] = None,
        **kwargs
    ) -> Tuple[Dict[str, Any], httpx.Headers]:
        """Make HTTP request and return (json_body, headers) tuple.

        Identical to request() but also returns response headers so callers
        can inspect pagination headers like X-Has-Next, X-Page, X-Per-Page.

        Returns:
            Tuple of (parsed JSON dict, httpx.Headers)
        """
        # Ensure path starts with / for proper urljoin behavior
        if not path.startswith('/'):
            path = '/' + path
        url = urljoin(self.base_url + '/', path)

        effective_timeout = timeout if timeout is not None else self.timeout

        last_exception: Optional[OilPriceAPIError] = None
        for attempt in range(self.max_retries):
            try:
                response = self._client.request(
                    method=method,
                    url=url,
                    params=params,
                    json=json_data,
                    timeout=effective_timeout,
                    **kwargs
                )

                if response.status_code == 200:
                    return response.json(), response.headers
                elif response.status_code == 401:
                    raise AuthenticationError("Invalid API key or authentication failed")
                elif response.status_code == 404:
                    error_data = self._safe_parse_json(response)
                    raise DataNotFoundError(
                        message=error_data.get("error", "Resource not found"),
                        commodity=params.get("commodity") if params else None,
                    )
                elif response.status_code == 422:
                    error_data = self._safe_parse_json(response)
                    raise ValidationError(
                        message=error_data.get("error", "Validation failed"),
                        field=error_data.get("field"),
                        value=error_data.get("value"),
                    )
                elif response.status_code == 429:
                    reset_time = self._parse_rate_limit_reset(response.headers)
                    retry_after = response.headers.get("Retry-After")

                    if self._retry_strategy.should_retry(attempt, 429):
                        wait_time = min(float(retry_after), 60.0) if retry_after else self._retry_strategy.calculate_wait_time(attempt)
                        logger.info(f"Rate limited. Retrying in {wait_time}s (attempt {attempt + 1}/{self.max_retries})")
                        time.sleep(wait_time)
                        continue

                    raise RateLimitError(
                        message="Rate limit exceeded",
                        reset_time=reset_time,
                        limit=response.headers.get("X-RateLimit-Limit"),
                        remaining=response.headers.get("X-RateLimit-Remaining"),
                    )
                elif response.status_code >= 500:
                    if self._retry_strategy.should_retry(attempt, response.status_code):
                        wait_time = self._retry_strategy.calculate_wait_time(attempt)
                        time.sleep(wait_time)
                        continue
                    raise ServerError(
                        message=f"Server error: {response.status_code}",
                        status_code=response.status_code,
                    )
                else:
                    error_data = self._safe_parse_json(response)
                    raise OilPriceAPIError(
                        message=error_data.get("error", f"Unexpected error: {response.status_code}"),
                        status_code=response.status_code,
                        response=error_data,
                    )

            except httpx.TimeoutException:
                last_exception = TimeoutError(
                    message="Request timed out",
                    timeout=self.timeout,
                )
                if self._retry_strategy.should_retry_on_exception(attempt):
                    wait_time = self._retry_strategy.calculate_wait_time(attempt)
                    time.sleep(wait_time)
                    continue
                raise last_exception
            except httpx.RequestError as e:
                last_exception = OilPriceAPIError(message=f"Request failed: {str(e)}")
                if self._retry_strategy.should_retry_on_exception(attempt):
                    wait_time = self._retry_strategy.calculate_wait_time(attempt)
                    time.sleep(wait_time)
                    continue
                raise last_exception

        if last_exception:
            raise last_exception

        raise OilPriceAPIError("Max retries exceeded")

    @staticmethod
    def _sanitize_path_for_telemetry(method: str, path: str) -> str:
        """Strip resource IDs from path to avoid leaking user data in telemetry."""
        import re
        # Replace UUIDs and numeric IDs with :id
        sanitized = re.sub(r'/[0-9a-f]{8}-[0-9a-f]{4}-[0-9a-f]{4}-[0-9a-f]{4}-[0-9a-f]{12}', '/:id', path)
        sanitized = re.sub(r'/\d+', '/:id', sanitized)
        return f"{method} {sanitized}"

    def _safe_parse_json(self, response: httpx.Response) -> Dict[str, Any]:
        """Safely parse JSON response."""
        try:
            return response.json()
        except json.JSONDecodeError:
            return {"error": response.text or "Unknown error"}

    def _parse_rate_limit_reset(self, headers: httpx.Headers) -> Optional[datetime]:
        """Parse rate limit reset time from headers."""
        reset_header = headers.get("X-RateLimit-Reset")
        if reset_header:
            try:
                # Try parsing as Unix timestamp
                timestamp = float(reset_header)
                return datetime.fromtimestamp(timestamp)
            except (ValueError, TypeError):
                # Try parsing as ISO format
                try:
                    return datetime.fromisoformat(reset_header)
                except (ValueError, TypeError):
                    pass
        return None

    def get_data_connector_prices(
        self,
        fuel_type: Optional[str] = None,
        port: Optional[str] = None,
        region: Optional[str] = None,
        since: Optional[str] = None
    ) -> List[DataConnectorPrice]:
        """
        Get prices from connected data sources (BYOS - Bring Your Own Subscription).

        Requires Data Connector feature enabled on your organization.

        Args:
            fuel_type: Filter by fuel type (VLSFO, MGO, IFO380)
            port: Filter by port name
            region: Filter by region (AMERICAS, EMEA, APAC)
            since: ISO 8601 timestamp to fetch prices after

        Returns:
            List of DataConnectorPrice objects

        Example:
            >>> prices = client.get_data_connector_prices(fuel_type='VLSFO')
            >>> for p in prices:
            ...     print(f"{p.port}: ${p.price}/{p.unit}")
        """
        params = {}
        if fuel_type:
            params['fuel_type'] = fuel_type
        if port:
            params['port'] = port
        if region:
            params['region'] = region
        if since:
            params['since'] = since

        response = self.request('GET', '/v1/prices/data-connector', params=params)
        prices_data = response.get('data', {}).get('prices', [])
        return [DataConnectorPrice(**p) for p in prices_data]

    def market_brief(
        self,
        codes: List[str],
        narrative: bool = False,
    ) -> MarketBrief:
        """Get a multi-commodity structured (+ optional narrative) market brief.

        Composes existing price/forecast data for the given commodity codes into
        a single structured summary (#3245 Phase 1a). Counts as one request.

        Args:
            codes: Commodity codes to include (e.g. ["BRENT_CRUDE_USD", "WTI"]).
            narrative: When True, request a natural-language narrative as well.

        Returns:
            A MarketBrief model.

        Example:
            >>> brief = client.market_brief(["BRENT_CRUDE_USD"], narrative=True)
            >>> print(brief.commodities[0].price)
        """
        params: Dict[str, Any] = {"codes": ",".join(codes)}
        if narrative:
            params["narrative"] = "true"

        response = self.request(
            method="GET",
            path="/v1/market-brief",
            params=params,
        )
        return MarketBrief(**unwrap_data(response))

    def close(self):
        """Close the HTTP client and flush telemetry."""
        self._telemetry.close()
        self._client.close()

    def __enter__(self):
        """Context manager entry."""
        return self

    def __exit__(self, exc_type, exc_val, exc_tb):
        """Context manager exit."""
        self.close()

    def __del__(self):
        """Cleanup on deletion.

        Note: Relying on __del__ for cleanup is non-deterministic.
        Prefer using context managers (with statement) or explicitly calling close().
        """
        try:
            self.close()
        except Exception:
            # Silently fail during cleanup - cannot handle exceptions in __del__
            # GC is already running, logging or raising would cause issues
            pass