from __future__ import annotations

from typing import TYPE_CHECKING, Any

from ..._constants import EMPTY_JSON
from ..._endpoints import Health
from ..._internal._schemas import APIEnvelope
from .._base import BaseResource

if TYPE_CHECKING:
    from ..._async_client import AsyncClient
else:
    AsyncClient = Any


class AsyncHealthResource(BaseResource[AsyncClient]):
    """Provides API health/liveness checks (async).

    Accessible via ``client.health``.
    """

    async def ping(self, action: str | None = None) -> APIEnvelope[None]:
        """Ping the API server.

        Args:
            action: Optional action hint forwarded to the API
                (e.g., ``"first_open"``).

        Returns:
            ``APIEnvelope[None]`` — the server returns no data payload on
            success.

        Example:
            >>> await client.health.ping()
        """
        return APIEnvelope[None].model_validate(
            await self._client.request_route(
                Health.PING,
                json={"action": action} if action else EMPTY_JSON,
            )
        )
