import os

import ipinfo

from .models import IPDetails


def ipinfo_lookup(ip: str | None, **kwargs) -> IPDetails:
    """
    Retrieve detailed information about an IP address using the ipinfo.io service.

    This function fetches comprehensive information about the specified IP address,
    including geolocation data, ISP details, and country information. If no IP is
    provided, it returns information about the client's current IP address.

    Args:
        ip: The IP address to look up. If None, returns information about the
            client's current IP address.
        **kwargs: Additional arguments to pass to the ipinfo handler. These can
            include timeout settings, cache settings, or other ipinfo.io options.

    Returns:
        IPDetails: A Pydantic model containing detailed information about the IP,
                  including location, organization, and country details.

    Raises:
        ipinfo.exceptions.RequestQuotaExceededError: If the API request quota is exceeded
        ipinfo.exceptions.RequestFailedError: If the API request fails
        ValueError: If the provided IP address is invalid

    Example:
        >>> details = ipinfo_lookup("8.8.8.8")
        >>> print(details.country)
        'US'
        >>> print(details.org)
        'Google LLC'
    """

    handler = ipinfo.getHandler(
        access_token=os.environ.get("IPINFO_API_TOKEN", None),
        headers={"user-agent": "mcp-server-ipinfo", "custom_header": "yes"},
        **kwargs,
    )

    details = handler.getDetails(ip_address=ip)

    return IPDetails(**details.all)
