hyperping 0.1.0__py3-none-any.whl

hyperping/_monitors_mixin.py

@@ -0,0 +1,250 @@
+"""Monitor operations mixin for HyperpingClient.
+
+Provides CRUD and reporting methods for Hyperping monitors. Mixed into
+:class:`~hyperping.client.HyperpingClient` at class definition time.
+"""
+
+from __future__ import annotations
+
+import logging
+from typing import Any
+
+from pydantic import ValidationError
+
+from hyperping.endpoints import Endpoint
+from hyperping.exceptions import HyperpingNotFoundError
+from hyperping.models import (
+    Monitor,
+    MonitorCreate,
+    MonitorReport,
+    MonitorUpdate,
+)
+
+logger = logging.getLogger(__name__)
+
+
+class MonitorsMixin:
+    """Monitor-related API operations."""
+
+    def _request(  # type: ignore[empty-body]
+        self,
+        method: str,
+        path: str,
+        json: dict[str, Any] | None = None,
+        params: dict[str, Any] | None = None,
+    ) -> dict[str, Any]: ...  # provided by HyperpingClient
+
+    def list_monitors(self) -> list[Monitor]:
+        """List all monitors in the account.
+
+        Returns:
+            List of :class:`Monitor` objects. Monitors that fail to parse
+            are silently skipped with a warning log.
+
+        Raises:
+            HyperpingAuthError: If the API key is invalid.
+            HyperpingAPIError: On unexpected API errors.
+        """
+        response = self._request("GET", Endpoint.MONITORS)
+
+        # Handle different response formats
+        if isinstance(response, list):
+            monitors_data = response
+        elif "monitors" in response:
+            monitors_data = response["monitors"]
+        else:
+            monitors_data = response.get("data", [])
+
+        monitors = []
+        skipped = 0
+        for data in monitors_data:
+            try:
+                monitors.append(Monitor.model_validate(data))
+            except (ValueError, ValidationError) as e:
+                skipped += 1
+                logger.warning(f"Failed to parse monitor data: {e}", extra={"data": data})
+
+        if skipped:
+            logger.warning(
+                f"{skipped} of {len(monitors_data)} monitors could not be parsed and were skipped"
+            )
+
+        return monitors
+
+    def get_monitor(self, monitor_id: str) -> Monitor:
+        """Get a single monitor by ID.
+
+        Args:
+            monitor_id: Monitor UUID
+
+        Returns:
+            Monitor object
+
+        Raises:
+            HyperpingNotFoundError: If monitor not found
+        """
+        response = self._request("GET", f"{Endpoint.MONITORS}/{monitor_id}")
+        return Monitor.model_validate(response)
+
+    def create_monitor(self, monitor: MonitorCreate) -> Monitor:
+        """Create a new monitor.
+
+        Args:
+            monitor: Monitor creation data.
+
+        Returns:
+            Created :class:`Monitor` object.
+
+        Raises:
+            HyperpingValidationError: If the payload fails server-side validation.
+            HyperpingAPIError: On unexpected API errors.
+        """
+        payload = monitor.model_dump(exclude_none=True)
+        response = self._request("POST", Endpoint.MONITORS, json=payload)
+        return Monitor.model_validate(response)
+
+    # Writable fields for the Hyperping monitor PUT endpoint
+    _MONITOR_WRITABLE_FIELDS: frozenset[str] = frozenset(
+        {
+            "name",
+            "url",
+            "protocol",
+            "http_method",
+            "check_frequency",
+            "regions",
+            "request_headers",
+            "request_body",
+            "follow_redirects",
+            "expected_status_code",
+            "required_keyword",
+            "paused",
+            "port",
+            "alerts_wait",
+            "escalation_policy",
+            "dns_record_type",
+            "dns_nameserver",
+            "dns_expected_answer",
+        }
+    )
+
+    def update_monitor(self, monitor_id: str, update: MonitorUpdate) -> Monitor:
+        """Update an existing monitor using read-modify-write.
+
+        The Hyperping v1 PUT endpoint requires a full payload. We fetch the
+        current state first and apply the update on top to avoid clobbering
+        fields not included in the partial update.
+
+        Args:
+            monitor_id: Monitor UUID
+            update: Fields to update
+
+        Returns:
+            Updated Monitor object
+        """
+        current = self.get_monitor(monitor_id)
+
+        # Build full payload from current writable state
+        payload: dict[str, Any] = current.model_dump(
+            mode="json",
+            exclude_none=True,
+            include=set(self._MONITOR_WRITABLE_FIELDS),
+        )
+
+        # Apply the requested changes on top of current state
+        payload.update(update.model_dump(exclude_none=True))
+
+        response = self._request("PUT", f"{Endpoint.MONITORS}/{monitor_id}", json=payload)
+        return Monitor.model_validate(response)
+
+    def delete_monitor(self, monitor_id: str) -> None:
+        """Delete a monitor.
+
+        Args:
+            monitor_id: Monitor UUID
+
+        Raises:
+            HyperpingNotFoundError: If monitor not found
+        """
+        self._request("DELETE", f"{Endpoint.MONITORS}/{monitor_id}")
+
+    def pause_monitor(self, monitor_id: str) -> Monitor:
+        """Pause a monitor.
+
+        Args:
+            monitor_id: Monitor UUID
+
+        Returns:
+            Updated Monitor object
+        """
+        return self.update_monitor(monitor_id, MonitorUpdate(paused=True))
+
+    def resume_monitor(self, monitor_id: str) -> Monitor:
+        """Resume a paused monitor.
+
+        Args:
+            monitor_id: Monitor UUID
+
+        Returns:
+            Updated Monitor object
+        """
+        return self.update_monitor(monitor_id, MonitorUpdate(paused=False))
+
+    def get_all_reports(self, period: str = "30d") -> list[MonitorReport]:
+        """Get uptime reports for all monitors in a single batch call.
+
+        Uses the v2 batch endpoint -- one API call for all monitors.
+
+        Args:
+            period: Report period (``1h``, ``24h``, ``7d``, ``30d``, ``90d``).
+
+        Returns:
+            List of :class:`MonitorReport` objects. Reports that fail to parse
+            are silently skipped with a warning log.
+
+        Raises:
+            HyperpingAuthError: If the API key is invalid.
+            HyperpingAPIError: On unexpected API errors.
+        """
+        response = self._request("GET", Endpoint.REPORTS, params={"period": period})
+        period_info = response.get("period", {})
+        monitors_data = response.get("monitors", [])
+
+        reports = []
+        skipped = 0
+        for m in monitors_data:
+            try:
+                reports.append(MonitorReport.model_validate({**m, "period": period_info}))
+            except (ValueError, ValidationError) as e:
+                skipped += 1
+                logger.warning(f"Failed to parse monitor report: {e}", extra={"data": m})
+
+        if skipped:
+            logger.warning(
+                f"{skipped} of {len(monitors_data)} reports could not be parsed and were skipped"
+            )
+
+        return reports
+
+    def get_monitor_report(
+        self,
+        monitor_id: str,
+        period: str = "30d",
+    ) -> MonitorReport:
+        """Get uptime report for a single monitor.
+
+        Fetches the batch report and filters by monitor UUID.
+
+        Args:
+            monitor_id: Monitor UUID
+            period: Report period (1h, 24h, 7d, 30d, 90d)
+
+        Returns:
+            MonitorReport object
+
+        Raises:
+            HyperpingNotFoundError: If no report found for the monitor
+        """
+        for r in self.get_all_reports(period):
+            if r.uuid == monitor_id:
+                return r
+        raise HyperpingNotFoundError(f"No report found for monitor: {monitor_id}")

hyperping/_outages_mixin.py

@@ -0,0 +1,102 @@
+"""Outage operations mixin for HyperpingClient.
+
+Provides methods for managing auto-detected outages (v2 API). Mixed into
+:class:`~hyperping.client.HyperpingClient` at class definition time.
+"""
+
+from __future__ import annotations
+
+import logging
+from typing import Any, cast
+
+from hyperping.endpoints import Endpoint
+from hyperping.exceptions import HyperpingNotFoundError
+
+logger = logging.getLogger(__name__)
+
+
+class OutagesMixin:
+    """Outage-related API operations."""
+
+    def _request(  # type: ignore[empty-body]
+        self,
+        method: str,
+        path: str,
+        json: dict[str, Any] | None = None,
+        params: dict[str, Any] | None = None,
+    ) -> dict[str, Any]: ...  # provided by HyperpingClient
+
+    def list_outages(self) -> list[dict[str, Any]]:
+        """List auto-detected outages.
+
+        Returns raw dicts since the exact API response shape is not fully
+        documented. The command layer normalizes the response defensively.
+
+        Returns:
+            List of outage dicts from the API.
+            Empty list if the endpoint is not available (404).
+        """
+        try:
+            data = self._request("GET", Endpoint.OUTAGES)
+            if isinstance(data, list):
+                return data
+            if isinstance(data, dict) and "outages" in data:
+                return cast(list[dict[str, Any]], data["outages"])
+            return []
+        except HyperpingNotFoundError:
+            logger.debug("Outage endpoint not available (404)")
+            return []
+
+    def acknowledge_outage(self, outage_id: str, message: str | None = None) -> dict[str, Any]:
+        """Acknowledge an outage.
+
+        Args:
+            outage_id: Outage UUID.
+            message: Optional acknowledgement message.
+
+        Returns:
+            API response dict.
+
+        Raises:
+            HyperpingNotFoundError: If outage not found.
+        """
+        json_body = {"message": message} if message else None
+        return self._request(
+            "POST",
+            f"{Endpoint.OUTAGES}/{outage_id}/acknowledge",
+            json=json_body,
+        )
+
+    def resolve_outage(self, outage_id: str, message: str | None = None) -> dict[str, Any]:
+        """Resolve an outage.
+
+        Args:
+            outage_id: Outage UUID.
+            message: Optional resolution message.
+
+        Returns:
+            API response dict.
+
+        Raises:
+            HyperpingNotFoundError: If outage not found.
+        """
+        json_body = {"message": message} if message else None
+        return self._request(
+            "POST",
+            f"{Endpoint.OUTAGES}/{outage_id}/resolve",
+            json=json_body,
+        )
+
+    def escalate_outage(self, outage_id: str) -> dict[str, Any]:
+        """Escalate an outage.
+
+        Args:
+            outage_id: Outage UUID.
+
+        Returns:
+            API response dict.
+
+        Raises:
+            HyperpingNotFoundError: If outage not found.
+        """
+        return self._request("POST", f"{Endpoint.OUTAGES}/{outage_id}/escalate")

hyperping/_statuspages_mixin.py

@@ -0,0 +1,226 @@
+"""Status page operations mixin for HyperpingClient.
+
+Provides CRUD and subscriber methods for Hyperping status pages (v2 API). Mixed into
+:class:`~hyperping.client.HyperpingClient` at class definition time.
+"""
+
+from __future__ import annotations
+
+import logging
+from typing import Any
+
+from pydantic import ValidationError
+
+from hyperping.endpoints import Endpoint
+from hyperping.models import (
+    StatusPage,
+    StatusPageCreate,
+    StatusPageSubscriber,
+    StatusPageUpdate,
+)
+
+logger = logging.getLogger(__name__)
+
+
+class StatusPagesMixin:
+    """Status page-related API operations."""
+
+    def _request(  # type: ignore[empty-body]
+        self,
+        method: str,
+        path: str,
+        json: dict[str, Any] | None = None,
+        params: dict[str, Any] | None = None,
+    ) -> dict[str, Any]: ...  # provided by HyperpingClient
+
+    def list_status_pages(self, search: str | None = None) -> list[StatusPage]:
+        """List all status pages.
+
+        Args:
+            search: Optional search query to filter by name.
+
+        Returns:
+            List of :class:`StatusPage` objects. Pages that fail to parse
+            are silently skipped with a warning log.
+
+        Raises:
+            HyperpingAuthError: If the API key is invalid.
+            HyperpingAPIError: On unexpected API errors.
+        """
+        query_params: dict[str, Any] = {}
+        if search:
+            query_params["search"] = search
+
+        response = self._request(
+            "GET",
+            Endpoint.STATUSPAGES,
+            params=query_params if query_params else None,
+        )
+
+        if isinstance(response, list):
+            pages_data = response
+        elif "statuspages" in response:
+            pages_data = response["statuspages"]
+        else:
+            pages_data = response.get("data", [])
+
+        pages = []
+        skipped = 0
+        for data in pages_data:
+            try:
+                pages.append(StatusPage.model_validate(data))
+            except (ValueError, ValidationError) as e:
+                skipped += 1
+                logger.warning(f"Failed to parse status page data: {e}", extra={"data": data})
+
+        if skipped:
+            logger.warning(
+                f"{skipped} of {len(pages_data)} status pages could not be parsed and were skipped"
+            )
+
+        return pages
+
+    def get_status_page(self, status_page_id: str) -> StatusPage:
+        """Get a single status page by ID.
+
+        Args:
+            status_page_id: Status page UUID.
+
+        Returns:
+            :class:`StatusPage` object.
+
+        Raises:
+            HyperpingNotFoundError: If status page not found.
+        """
+        response = self._request("GET", f"{Endpoint.STATUSPAGES}/{status_page_id}")
+        return StatusPage.model_validate(response)
+
+    def create_status_page(self, status_page: StatusPageCreate) -> StatusPage:
+        """Create a new status page.
+
+        Args:
+            status_page: Status page creation data.
+
+        Returns:
+            Created :class:`StatusPage` object.
+
+        Raises:
+            HyperpingValidationError: If the payload fails server-side validation.
+            HyperpingAPIError: On unexpected API errors.
+        """
+        payload = status_page.model_dump(exclude_none=True, by_alias=True)
+        response = self._request("POST", Endpoint.STATUSPAGES, json=payload)
+        return StatusPage.model_validate(response)
+
+    def update_status_page(
+        self,
+        status_page_id: str,
+        update: StatusPageUpdate,
+    ) -> StatusPage:
+        """Update an existing status page.
+
+        Args:
+            status_page_id: Status page UUID.
+            update: Fields to update.
+
+        Returns:
+            Updated :class:`StatusPage` object.
+
+        Raises:
+            HyperpingNotFoundError: If status page not found.
+            HyperpingValidationError: If the payload fails server-side validation.
+            HyperpingAPIError: On unexpected API errors.
+        """
+        payload = update.model_dump(exclude_none=True, by_alias=True)
+        response = self._request("PUT", f"{Endpoint.STATUSPAGES}/{status_page_id}", json=payload)
+        return StatusPage.model_validate(response)
+
+    def delete_status_page(self, status_page_id: str) -> None:
+        """Delete a status page.
+
+        Args:
+            status_page_id: Status page UUID.
+
+        Raises:
+            HyperpingNotFoundError: If status page not found.
+        """
+        self._request("DELETE", f"{Endpoint.STATUSPAGES}/{status_page_id}")
+
+    def list_subscribers(self, status_page_id: str) -> list[StatusPageSubscriber]:
+        """List subscribers for a status page.
+
+        Args:
+            status_page_id: Status page UUID.
+
+        Returns:
+            List of :class:`StatusPageSubscriber` objects.
+
+        Raises:
+            HyperpingNotFoundError: If status page not found.
+            HyperpingAPIError: On unexpected API errors.
+        """
+        response = self._request(
+            "GET", f"{Endpoint.STATUSPAGES}/{status_page_id}/subscribers"
+        )
+
+        if isinstance(response, list):
+            subscribers_data = response
+        elif "subscribers" in response:
+            subscribers_data = response["subscribers"]
+        else:
+            subscribers_data = response.get("data", [])
+
+        subscribers = []
+        skipped = 0
+        for data in subscribers_data:
+            try:
+                subscribers.append(StatusPageSubscriber.model_validate(data))
+            except (ValueError, ValidationError) as e:
+                skipped += 1
+                logger.warning(f"Failed to parse subscriber data: {e}", extra={"data": data})
+
+        if skipped:
+            logger.warning(
+                f"{skipped} of {len(subscribers_data)} subscribers could not be parsed "
+                "and were skipped"
+            )
+
+        return subscribers
+
+    def add_subscriber(self, status_page_id: str, email: str) -> StatusPageSubscriber:
+        """Add a subscriber to a status page.
+
+        Args:
+            status_page_id: Status page UUID.
+            email: Subscriber email address.
+
+        Returns:
+            Created :class:`StatusPageSubscriber` object.
+
+        Raises:
+            HyperpingNotFoundError: If status page not found.
+            HyperpingValidationError: If the email is invalid.
+            HyperpingAPIError: On unexpected API errors.
+        """
+        payload = {"email": email}
+        response = self._request(
+            "POST",
+            f"{Endpoint.STATUSPAGES}/{status_page_id}/subscribers",
+            json=payload,
+        )
+        return StatusPageSubscriber.model_validate(response)
+
+    def remove_subscriber(self, status_page_id: str, subscriber_id: str) -> None:
+        """Remove a subscriber from a status page.
+
+        Args:
+            status_page_id: Status page UUID.
+            subscriber_id: Subscriber ID.
+
+        Raises:
+            HyperpingNotFoundError: If status page or subscriber not found.
+        """
+        self._request(
+            "DELETE",
+            f"{Endpoint.STATUSPAGES}/{status_page_id}/subscribers/{subscriber_id}",
+        )

hyperping/_version.py

@@ -0,0 +1 @@
+__version__ = "0.1.0"