tarot.py

"""Tarot category client."""

from __future__ import annotations

from astroapi.categories.base import BaseCategoryClient
from astroapi.types.requests import (
    DrawCardsRequest,
    TarotBirthCardsRequest,
    TarotDignitiesRequest,
    TarotNatalReportRequest,
    TarotOptimalTimesRequest,
    TarotQuintessenceRequest,
    TarotReadingRequest,
    TarotReportRequest,
    TarotTimingRequest,
)
from astroapi.types.responses import DrawCardsResponse, GenericResponse, TarotReadingResponse


class TarotClient(BaseCategoryClient):
    """Client for tarot endpoints.

    Provides tarot card drawing and reading functionality.
    """

    API_PREFIX = "/api/v3/tarot"

    def draw_cards(self, request: DrawCardsRequest) -> DrawCardsResponse:
        """Draw tarot cards.

        Args:
            request: Draw cards request parameters

        Returns:
            Drawn cards response

        Raises:
            AstrologyError: If API request fails
        """
        url = self._build_url("draw")
        data = self._http.post(url, json=request.model_dump(exclude_none=True))
        return DrawCardsResponse(**data)

    def get_reading(self, request: TarotReadingRequest) -> TarotReadingResponse:
        """Get tarot reading interpretation.

        Args:
            request: Tarot reading request parameters

        Returns:
            Tarot reading response

        Raises:
            AstrologyError: If API request fails
        """
        url = self._build_url("reading")
        data = self._http.post(url, json=request.model_dump(exclude_none=True))
        return TarotReadingResponse(**data)

    # Glossary endpoints

    def get_cards_glossary(self, language: str | None = None) -> GenericResponse:
        """Get tarot cards glossary."""
        params = {}
        if language:
            params["language"] = language
        url = self._build_url("glossary", "cards")
        data = self._http.get(url, params=params if params else None)
        return GenericResponse(**data)

    def get_spreads_glossary(self, language: str | None = None) -> GenericResponse:
        """Get tarot spreads glossary."""
        params = {}
        if language:
            params["language"] = language
        url = self._build_url("glossary", "spreads")
        data = self._http.get(url, params=params if params else None)
        return GenericResponse(**data)

    def get_card_detail(self, card_id: str, language: str | None = None) -> GenericResponse:
        """Get detail for a specific tarot card."""
        params = {}
        if language:
            params["language"] = language
        url = self._build_url("glossary", "cards", card_id)
        data = self._http.get(url, params=params if params else None)
        return GenericResponse(**data)

    # Cards endpoints

    def search_cards(self, query: str | None = None, **kwargs: str) -> GenericResponse:
        """Search tarot cards."""
        params: dict[str, str] = {}
        if query:
            params["q"] = query
        params.update(kwargs)
        url = self._build_url("cards", "search")
        data = self._http.get(url, params=params if params else None)
        return GenericResponse(**data)

    def get_daily_card(self, user_id: str, language: str | None = None) -> GenericResponse:
        """Get daily tarot card.

        Args:
            user_id: Unique user identifier for consistent daily draws
            language: Language code (optional)
        """
        params: dict[str, str] = {"user_id": user_id}
        if language:
            params["language"] = language
        url = self._build_url("cards", "daily")
        data = self._http.get(url, params=params)
        return GenericResponse(**data)

    # Reports endpoints

    def get_single_card_report(self, request: TarotReportRequest) -> GenericResponse:
        """Get single card tarot report."""
        url = self._build_url("reports", "single")
        data = self._http.post(url, json=request.model_dump(exclude_none=True))
        return GenericResponse(**data)

    def get_three_card_report(self, request: TarotReportRequest) -> GenericResponse:
        """Get three card tarot report."""
        url = self._build_url("reports", "three-card")
        data = self._http.post(url, json=request.model_dump(exclude_none=True))
        return GenericResponse(**data)

    def get_celtic_cross_report(self, request: TarotReportRequest) -> GenericResponse:
        """Get Celtic cross tarot report."""
        url = self._build_url("reports", "celtic-cross")
        data = self._http.post(url, json=request.model_dump(exclude_none=True))
        return GenericResponse(**data)

    def get_synastry_report(self, request: TarotReportRequest) -> GenericResponse:
        """Get tarot synastry report."""
        url = self._build_url("reports", "synastry")
        data = self._http.post(url, json=request.model_dump(exclude_none=True))
        return GenericResponse(**data)

    def get_houses_spread(self, request: TarotReportRequest) -> GenericResponse:
        """Get tarot houses spread report."""
        url = self._build_url("reports", "houses")
        data = self._http.post(url, json=request.model_dump(exclude_none=True))
        return GenericResponse(**data)

    def get_tree_of_life_spread(self, request: TarotReportRequest) -> GenericResponse:
        """Get tarot Tree of Life spread report."""
        url = self._build_url("reports", "tree-of-life")
        data = self._http.post(url, json=request.model_dump(exclude_none=True))
        return GenericResponse(**data)

    # Analysis endpoints

    def get_quintessence(self, request: TarotQuintessenceRequest) -> GenericResponse:
        """Get tarot quintessence calculation."""
        url = self._build_url("analysis", "quintessence")
        data = self._http.post(url, json=request.model_dump(exclude_none=True))
        return GenericResponse(**data)

    def get_birth_cards(self, request: TarotBirthCardsRequest) -> GenericResponse:
        """Get tarot birth cards."""
        url = self._build_url("analysis", "birth-cards")
        data = self._http.post(url, json=request.model_dump(exclude_none=True))
        return GenericResponse(**data)

    def get_dignities_analysis(self, request: TarotDignitiesRequest) -> GenericResponse:
        """Get tarot elemental dignities analysis."""
        url = self._build_url("analysis", "dignities")
        data = self._http.post(url, json=request.model_dump(exclude_none=True))
        return GenericResponse(**data)

    def analyze_timing(self, request: TarotTimingRequest) -> GenericResponse:
        """Analyze tarot timing."""
        url = self._build_url("analysis", "timing")
        data = self._http.post(url, json=request.model_dump(exclude_none=True))
        return GenericResponse(**data)

    def get_optimal_times(self, request: TarotOptimalTimesRequest) -> GenericResponse:
        """Get optimal times via tarot."""
        url = self._build_url("analysis", "optimal-times")
        data = self._http.post(url, json=request.model_dump(exclude_none=True))
        return GenericResponse(**data)

    def get_transit_report(self, request: TarotNatalReportRequest) -> GenericResponse:
        """Get tarot transit report."""
        url = self._build_url("analysis", "transit-report")
        data = self._http.post(url, json=request.model_dump(exclude_none=True))
        return GenericResponse(**data)

    def get_natal_report(self, request: TarotNatalReportRequest) -> GenericResponse:
        """Get tarot natal report."""
        url = self._build_url("analysis", "natal-report")
        data = self._http.post(url, json=request.model_dump(exclude_none=True))
        return GenericResponse(**data)