charts.py

"""Charts category client for chart calculations."""

from __future__ import annotations

from astroapi.categories.base import BaseCategoryClient
from astroapi.types.requests import (
    CompositeChartRequest,
    DirectionRequest,
    LunarReturnRequest,
    NatalChartRequest,
    NatalTransitsRequest,
    ProgressionRequest,
    SolarReturnRequest,
    SynastryChartRequest,
    TransitChartRequest,
    VenusReturnRequest,
)
from astroapi.types.responses import (
    CompositeChartResponse,
    DirectionResponse,
    GenericResponse,
    NatalChartResponse,
    ProgressionResponse,
    ReturnChartResponse,
    SynastryChartResponse,
    TransitChartResponse,
)
from astroapi.utils.validators import validate_datetime_location, validate_subject


class ChartsClient(BaseCategoryClient):
    """Client for chart calculation endpoints.

    Provides access to natal, synastry, composite, transit, return,
    progression, and direction charts.
    """

    API_PREFIX = "/api/v3/charts"

    def get_natal_chart(self, request: NatalChartRequest) -> NatalChartResponse:
        """Calculate natal chart for a subject.

        Args:
            request: Natal chart request parameters

        Returns:
            Natal chart response

        Raises:
            AstrologyError: If validation fails or API request fails
        """
        validate_subject(request.subject)

        url = self._build_url("natal")
        data = self._http.post(url, json=request.model_dump(exclude_none=True))
        return NatalChartResponse(**data)

    def get_synastry_chart(self, request: SynastryChartRequest) -> SynastryChartResponse:
        """Calculate synastry chart for two subjects.

        Args:
            request: Synastry chart request parameters

        Returns:
            Synastry chart response

        Raises:
            AstrologyError: If validation fails or API request fails
        """
        validate_subject(request.subject1)
        validate_subject(request.subject2)

        url = self._build_url("synastry")
        data = self._http.post(url, json=request.model_dump(exclude_none=True))
        return SynastryChartResponse(**data)

    def get_composite_chart(self, request: CompositeChartRequest) -> CompositeChartResponse:
        """Calculate composite chart for two subjects.

        Args:
            request: Composite chart request parameters

        Returns:
            Composite chart response

        Raises:
            AstrologyError: If validation fails or API request fails
        """
        validate_subject(request.subject1)
        validate_subject(request.subject2)

        url = self._build_url("composite")
        data = self._http.post(url, json=request.model_dump(exclude_none=True))
        return CompositeChartResponse(**data)

    def get_transit_chart(self, request: TransitChartRequest) -> TransitChartResponse:
        """Calculate transit chart.

        Args:
            request: Transit chart request parameters

        Returns:
            Transit chart response

        Raises:
            AstrologyError: If validation fails or API request fails
        """
        validate_subject(request.natal_subject)
        validate_datetime_location(request.transit_datetime)

        url = self._build_url("transit")
        data = self._http.post(url, json=request.model_dump(exclude_none=True))
        return TransitChartResponse(**data)

    def get_solar_return(self, request: SolarReturnRequest) -> ReturnChartResponse:
        """Calculate solar return chart.

        Args:
            request: Solar return request parameters

        Returns:
            Solar return chart response

        Raises:
            AstrologyError: If validation fails or API request fails
        """
        validate_subject(request.subject)
        if request.return_location:
            validate_datetime_location(request.return_location)

        url = self._build_url("returns", "solar")
        data = self._http.post(url, json=request.model_dump(exclude_none=True))
        return ReturnChartResponse(**data)

    def get_lunar_return(self, request: LunarReturnRequest) -> ReturnChartResponse:
        """Calculate lunar return chart.

        Args:
            request: Lunar return request parameters

        Returns:
            Lunar return chart response

        Raises:
            AstrologyError: If validation fails or API request fails
        """
        validate_subject(request.subject)
        if request.return_location:
            validate_datetime_location(request.return_location)

        url = self._build_url("returns", "lunar")
        data = self._http.post(url, json=request.model_dump(exclude_none=True))
        return ReturnChartResponse(**data)

    def get_progression(self, request: ProgressionRequest) -> ProgressionResponse:
        """Calculate progression chart.

        Args:
            request: Progression request parameters

        Returns:
            Progression chart response

        Raises:
            AstrologyError: If validation fails or API request fails
        """
        validate_subject(request.subject)
        if request.location:
            validate_datetime_location(request.location)

        url = self._build_url("progressions")
        data = self._http.post(url, json=request.model_dump(exclude_none=True))
        return ProgressionResponse(**data)

    def get_secondary_progression(self, request: ProgressionRequest) -> ProgressionResponse:
        """Calculate secondary progression chart.

        Args:
            request: Progression request parameters

        Returns:
            Secondary progression response

        Raises:
            AstrologyError: If validation fails or API request fails
        """
        validate_subject(request.subject)
        if request.location:
            validate_datetime_location(request.location)

        url = self._build_url("progressions", "secondary")
        data = self._http.post(url, json=request.model_dump(exclude_none=True))
        return ProgressionResponse(**data)

    def get_solar_arc_progression(self, request: ProgressionRequest) -> ProgressionResponse:
        """Calculate solar arc progression chart.

        Args:
            request: Progression request parameters

        Returns:
            Solar arc progression response

        Raises:
            AstrologyError: If validation fails or API request fails
        """
        validate_subject(request.subject)
        if request.location:
            validate_datetime_location(request.location)

        url = self._build_url("progressions", "solar-arc")
        data = self._http.post(url, json=request.model_dump(exclude_none=True))
        return ProgressionResponse(**data)

    def get_direction(self, request: DirectionRequest) -> DirectionResponse:
        """Calculate direction chart.

        Args:
            request: Direction request parameters

        Returns:
            Direction chart response

        Raises:
            AstrologyError: If validation fails or API request fails
        """
        validate_subject(request.subject)

        url = self._build_url("directions")
        data = self._http.post(url, json=request.model_dump(exclude_none=True))
        return DirectionResponse(**data)

    def get_primary_direction(self, request: DirectionRequest) -> DirectionResponse:
        """Calculate primary direction chart.

        Args:
            request: Direction request parameters

        Returns:
            Primary direction response

        Raises:
            AstrologyError: If validation fails or API request fails
        """
        validate_subject(request.subject)

        url = self._build_url("directions", "primary")
        data = self._http.post(url, json=request.model_dump(exclude_none=True))
        return DirectionResponse(**data)

    def get_symbolic_direction(self, request: DirectionRequest) -> DirectionResponse:
        """Calculate symbolic direction chart.

        Args:
            request: Direction request parameters

        Returns:
            Symbolic direction response

        Raises:
            AstrologyError: If validation fails or API request fails
        """
        validate_subject(request.subject)

        url = self._build_url("directions", "symbolic")
        data = self._http.post(url, json=request.model_dump(exclude_none=True))
        return DirectionResponse(**data)

    def get_venus_return(self, request: VenusReturnRequest) -> ReturnChartResponse:
        """Calculate Venus return chart."""
        validate_subject(request.subject)
        if request.return_location:
            validate_datetime_location(request.return_location)

        url = self._build_url("returns", "venus")
        data = self._http.post(url, json=request.model_dump(exclude_none=True))
        return ReturnChartResponse(**data)

    def get_natal_transits(self, request: NatalTransitsRequest) -> GenericResponse:
        """Get natal transit period analysis."""
        validate_subject(request.natal_subject)

        url = self._build_url("natal-transits")
        data = self._http.post(url, json=request.model_dump(exclude_none=True))
        return GenericResponse(**data)