hyperping 1.4.0__tar.gz → 1.5.0__tar.gz

{hyperping-1.4.0 → hyperping-1.5.0}/CHANGELOG.md

@@ -5,6 +5,115 @@ All notable changes to this project will be documented in this file.
 The format is based on [Keep a Changelog](https://keepachangelog.com/en/1.1.0/),
 and this project adheres to [Semantic Versioning](https://semver.org/spec/v2.0.0.html).
 
+## [1.5.0] - 2026-04-20
+
+### Added
+
+- **`AsyncHyperpingMcpClient`** -- full async counterpart to `HyperpingMcpClient`. All 16
+  MCP methods available via `await`. Uses `httpx.AsyncClient`, `asyncio.Lock`, and async
+  retry with `asyncio.sleep`. Exported from `hyperping` top-level.
+- **Typed MCP returns** -- all 16 MCP client methods now return Pydantic models instead of
+  raw `dict[str, Any]`. Models verified against the live API.
+- **New models**: `TimeGroup`, `ResponseTimeReport`, `AlertHistory`, `MonitorMetricsSummary`,
+  `MttrReport`, `MttaReport`, `ProbeLogResponse`, `TeamMember`, `OutageMonitorSummary`.
+- **MCP error handling parity** -- both sync and async transports now map HTTP 404, 429,
+  400/422 to the same exception types as the REST client (`HyperpingNotFoundError`,
+  `HyperpingRateLimitError`, `HyperpingValidationError`).
+- **MCP retry logic** -- automatic retry with exponential backoff on transient server
+  errors (500, 502, 503, 504) up to `max_retries` times (default 2).
+- **Thread safety** -- `threading.Lock` (sync) and `asyncio.Lock` (async) protect the
+  request ID counter and initialization flag.
+- **83 new tests** covering async MCP transport, client coverage, sync transport error
+  paths, async maintenance/outages, and protocol base classes. Overall coverage: 96%.
+
+### Changed
+
+- **Forward-compatible models** -- all 28 response models changed from `extra="ignore"` to
+  `extra="allow"`. New API fields are preserved instead of silently dropped.
+- **Typed sub-objects** -- `OutageTimeline.outage` is now typed `Outage` (was `dict`),
+  `.monitor` is `OutageMonitorSummary` (was `dict`).
+
+## [1.4.1] - 2026-04-20
+
+### Fixed
+
+- HTTP 403 from MCP server now correctly raises `HyperpingAuthError` (was
+  `HyperpingAPIError`). The Hyperping MCP server returns 403 for invalid API keys;
+  the transport only handled 401. Now matches REST client behavior.
+- `MCP_URL` defined in single location (`endpoints.py`); removed duplicate in
+  `_mcp_transport.py`.
+- MCP handshake version string uses `__version__` instead of hardcoded `"1.4.0"`.
+
+## [1.4.0] - 2026-04-19
+
+### Added
+
+- **`HyperpingMcpClient`** -- new client for Hyperping MCP server features not available
+  via the REST API. Uses JSON-RPC 2.0 over HTTP at `/v1/mcp` with the same Bearer token
+  API key. Provides 16 typed methods: `get_status_summary`, `get_monitor_response_time`,
+  `get_monitor_mtta`, `get_monitor_mttr`, `get_monitor_anomalies`, `get_monitor_http_logs`,
+  `list_recent_alerts`, `list_on_call_schedules`, `get_on_call_schedule`,
+  `list_escalation_policies`, `get_escalation_policy`, `list_team_members`,
+  `list_integrations`, `get_integration`, `get_outage_timeline`, `search_monitors_by_name`.
+- **`McpTransport`** -- low-level JSON-RPC 2.0 transport with auto-initialization handshake,
+  double-parse response extraction, and error mapping to existing SDK exception types.
+- **`MCP_URL`** constant exported from `hyperping` top-level.
+- **Sync outage methods** -- `create_outage`, `delete_outage`, `get_outage`,
+  `unacknowledge_outage` added to `OutagesMixin` (were only in async client).
+- **Verification script** -- `scripts/verify_endpoints.py` for testing endpoints against
+  the live API.
+
+### Changed
+
+- **Maintenance update** uses `model_dump(include=...)` instead of hard-coded field list.
+- **Incident update error handling** -- `add_incident_update` now provides context when
+  the POST succeeds but the follow-up GET fails.
+
+### Removed
+
+- **Speculative REST methods** -- 12 methods that called nonexistent REST endpoints
+  (on-call, alerts, anomalies, integrations, probe logs, response time, MTTA, status
+  summary, outage timeline, monitor search) removed from `HyperpingClient` and
+  `AsyncHyperpingClient`. These features are MCP-only; use `HyperpingMcpClient` instead.
+- **8 speculative mixin files** (sync + async) deleted.
+- **8 speculative Endpoint enum entries** removed from `endpoints.py`.
+
+### Fixed
+
+- HTTP 403 from MCP server now correctly raises `HyperpingAuthError` (was
+  `HyperpingAPIError`). Matches REST client behavior.
+- `MCP_URL` defined in single location (`endpoints.py`), not duplicated.
+- MCP handshake version uses `__version__` instead of hardcoded string.
+- `pytest` bumped to 9.0.3 (CVE-2025-71176).
+
+## [1.3.0] - 2026-04-18 [YANKED]
+
+v1.3.0 added 18 speculative REST methods for MCP-discovered features (reporting,
+observability, on-call, integrations). All 12 endpoint paths were guessed from MCP
+tool names and **none of them work via the REST API** (verified: 10x 404, 2x 401).
+These features are only accessible through the MCP server (JSON-RPC 2.0). Superseded
+by v1.4.0 which replaces the broken REST methods with a proper `HyperpingMcpClient`.
+
+## [1.2.1] - 2026-04-17
+
+### Fixed
+
+- Bump `pytest` to 9.0.3 (CVE-2025-71176).
+
+## [1.2.0] - 2026-04-17
+
+### Added
+
+- **Sync outage methods** -- `create_outage`, `delete_outage`, `get_outage`,
+  `unacknowledge_outage` added to `OutagesMixin` for feature parity with async client.
+
+### Changed
+
+- **Maintenance update** uses `model_dump(include=...)` instead of hard-coded field
+  enumeration for robustness.
+- **Incident update error handling** -- `add_incident_update` now provides context when
+  the POST succeeds but the follow-up GET fails.
+
 ## [1.1.0] - 2026-04-09
 
 ### Added
@@ -30,6 +139,13 @@ and this project adheres to [Semantic Versioning](https://semver.org/spec/v2.0.0
 - **`collect_all_pages` / `collect_all_pages_async`** helpers in `_utils.py` for
   transparent multi-page result aggregation.
 
+## [1.0.1] - 2026-04-05
+
+### Fixed
+
+- Fix version string in `pyproject.toml` (was out of sync with `_version.py`).
+- Fix package metadata: incorrect email address in project config.
+
 ## [1.0.0] - 2026-04-05
 
 First stable release. The public API is production-ready and covered by semver

{hyperping-1.4.0 → hyperping-1.5.0}/PKG-INFO

@@ -1,6 +1,6 @@
 Metadata-Version: 2.4
 Name: hyperping
-Version: 1.4.0
+Version: 1.5.0
 Summary: Python SDK for the Hyperping uptime monitoring and incident management API
 Project-URL: Homepage, https://github.com/develeap/hyperping-python
 Project-URL: Documentation, https://github.com/develeap/hyperping-python#readme
@@ -98,6 +98,18 @@ async def main():
 
 The async client supports all the same resources, retry behaviour, and circuit breaker as the sync client. Use `RetryConfig` and `CircuitBreakerConfig` in exactly the same way.
 
+An async MCP client is also available:
+
+```python
+from hyperping import AsyncHyperpingMcpClient
+
+async def main():
+    async with AsyncHyperpingMcpClient(api_key="sk_...") as mcp:
+        summary = await mcp.get_status_summary()
+        members = await mcp.list_team_members()
+        anomalies = await mcp.get_monitor_anomalies("mon_uuid")
+```
+
 ## Authentication
 
 Pass your API key directly or via environment variable:
@@ -181,6 +193,43 @@ sub  = client.add_subscriber("sp_uuid", "user@example.com")
 client.remove_subscriber("sp_uuid", sub.id)
 ```
 
+### MCP Client (on-call, alerts, anomalies, integrations)
+
+Some Hyperping features are only available via the MCP server (JSON-RPC 2.0),
+not the REST API. Use `HyperpingMcpClient` for these:
+
+```python
+from hyperping import HyperpingMcpClient
+
+with HyperpingMcpClient(api_key="sk_...") as mcp:
+    # Status & reporting
+    summary = mcp.get_status_summary()
+    mtta = mcp.get_monitor_mtta("mon_uuid")
+    mttr = mcp.get_monitor_mttr("mon_uuid")
+    response_time = mcp.get_monitor_response_time("mon_uuid")
+
+    # On-call & escalation
+    schedules = mcp.list_on_call_schedules()
+    policies = mcp.list_escalation_policies()
+    members = mcp.list_team_members()
+
+    # Observability
+    anomalies = mcp.get_monitor_anomalies("mon_uuid")
+    logs = mcp.get_monitor_http_logs("mon_uuid")
+    alerts = mcp.list_recent_alerts()
+
+    # Integrations
+    integrations = mcp.list_integrations()
+
+    # Outage timeline & monitor search
+    timeline = mcp.get_outage_timeline("out_uuid")
+    results = mcp.search_monitors_by_name("api")
+```
+
+The MCP client uses the same API key as `HyperpingClient`. All methods return
+plain dicts/lists; use the exported Pydantic models (e.g., `OnCallSchedule`,
+`EscalationPolicy`) for validation if needed.
+
 ### Healthchecks
 
 ```python

{hyperping-1.4.0 → hyperping-1.5.0}/README.md

@@ -61,6 +61,18 @@ async def main():
 
 The async client supports all the same resources, retry behaviour, and circuit breaker as the sync client. Use `RetryConfig` and `CircuitBreakerConfig` in exactly the same way.
 
+An async MCP client is also available:
+
+```python
+from hyperping import AsyncHyperpingMcpClient
+
+async def main():
+    async with AsyncHyperpingMcpClient(api_key="sk_...") as mcp:
+        summary = await mcp.get_status_summary()
+        members = await mcp.list_team_members()
+        anomalies = await mcp.get_monitor_anomalies("mon_uuid")
+```
+
 ## Authentication
 
 Pass your API key directly or via environment variable:
@@ -144,6 +156,43 @@ sub  = client.add_subscriber("sp_uuid", "user@example.com")
 client.remove_subscriber("sp_uuid", sub.id)
 ```
 
+### MCP Client (on-call, alerts, anomalies, integrations)
+
+Some Hyperping features are only available via the MCP server (JSON-RPC 2.0),
+not the REST API. Use `HyperpingMcpClient` for these:
+
+```python
+from hyperping import HyperpingMcpClient
+
+with HyperpingMcpClient(api_key="sk_...") as mcp:
+    # Status & reporting
+    summary = mcp.get_status_summary()
+    mtta = mcp.get_monitor_mtta("mon_uuid")
+    mttr = mcp.get_monitor_mttr("mon_uuid")
+    response_time = mcp.get_monitor_response_time("mon_uuid")
+
+    # On-call & escalation
+    schedules = mcp.list_on_call_schedules()
+    policies = mcp.list_escalation_policies()
+    members = mcp.list_team_members()
+
+    # Observability
+    anomalies = mcp.get_monitor_anomalies("mon_uuid")
+    logs = mcp.get_monitor_http_logs("mon_uuid")
+    alerts = mcp.list_recent_alerts()
+
+    # Integrations
+    integrations = mcp.list_integrations()
+
+    # Outage timeline & monitor search
+    timeline = mcp.get_outage_timeline("out_uuid")
+    results = mcp.search_monitors_by_name("api")
+```
+
+The MCP client uses the same API key as `HyperpingClient`. All methods return
+plain dicts/lists; use the exported Pydantic models (e.g., `OnCallSchedule`,
+`EscalationPolicy`) for validation if needed.
+
 ### Healthchecks
 
 ```python

{hyperping-1.4.0 → hyperping-1.5.0}/pyproject.toml

@@ -4,7 +4,7 @@ build-backend = "hatchling.build"
 
 [project]
 name = "hyperping"
-version = "1.4.0"
+version = "1.5.0"
 description = "Python SDK for the Hyperping uptime monitoring and incident management API"
 readme = {file = "README.md", content-type = "text/markdown"}
 license = {text = "MIT"}

{hyperping-1.4.0 → hyperping-1.5.0}/src/hyperping/__init__.py

@@ -15,7 +15,7 @@ Quick start::
 """
 
 from hyperping._async_client import AsyncHyperpingClient
-from hyperping._mcp_transport import MCP_URL
+from hyperping._async_mcp_client import AsyncHyperpingMcpClient
 from hyperping._version import __version__
 from hyperping.client import (
     CircuitBreaker,
@@ -26,6 +26,7 @@ from hyperping.client import (
 )
 from hyperping.endpoints import (
     API_BASE,
+    MCP_URL,
     APIVersion,
     Endpoint,
 )
@@ -40,7 +41,7 @@ from hyperping.mcp_client import HyperpingMcpClient
 from hyperping.models import (
     DEFAULT_REGIONS,
     AddIncidentUpdateRequest,
-    AlertNotification,
+    AlertHistory,
     DnsRecordType,
     EscalationPolicy,
     Healthcheck,
@@ -64,10 +65,13 @@ from hyperping.models import (
     MonitorCreate,
     MonitorFrequency,
     MonitorListResponse,
+    MonitorMetricsSummary,
     MonitorProtocol,
     MonitorReport,
     MonitorTimeout,
     MonitorUpdate,
+    MttaReport,
+    MttrReport,
     NotificationOption,
     OnCallSchedule,
     Outage,
@@ -77,14 +81,18 @@ from hyperping.models import (
     OutageTimeline,
     OutageTimelineEvent,
     ProbeLog,
+    ProbeLogResponse,
     Region,
     ReportPeriod,
     RequestHeader,
+    ResponseTimeReport,
     StatusPage,
     StatusPageCreate,
     StatusPageSubscriber,
     StatusPageUpdate,
     StatusSummary,
+    TeamMember,
+    TimeGroup,
 )
 
 __all__ = [
@@ -92,6 +100,7 @@ __all__ = [
     "__version__",
     # Clients
     "AsyncHyperpingClient",
+    "AsyncHyperpingMcpClient",
     "HyperpingClient",
     "HyperpingMcpClient",
     # MCP
@@ -156,14 +165,21 @@ __all__ = [
     # Observability
     "MonitorAnomaly",
     "ProbeLog",
-    "AlertNotification",
+    "ProbeLogResponse",
     # On-call
     "OnCallSchedule",
     "EscalationPolicy",
+    "TeamMember",
     # Integrations
     "Integration",
     # Reporting
     "StatusSummary",
+    "TimeGroup",
+    "ResponseTimeReport",
+    "AlertHistory",
+    "MonitorMetricsSummary",
+    "MttrReport",
+    "MttaReport",
     # Healthchecks
     "Healthcheck",
     "HealthcheckCreate",

hyperping-1.5.0/src/hyperping/_async_mcp_client.py

@@ -0,0 +1,249 @@
+"""Async high-level typed MCP client for the Hyperping MCP server.
+
+Wraps :class:`~hyperping._async_mcp_transport.AsyncMcpTransport` with typed
+convenience methods that mirror the MCP tool names exposed by the server.
+
+Example::
+
+    from hyperping import AsyncHyperpingMcpClient
+
+    async with AsyncHyperpingMcpClient(api_key="sk_...") as mcp:
+        summary = await mcp.get_status_summary()
+        print(summary.total, summary.up, summary.down)
+"""
+
+from __future__ import annotations
+
+from typing import Any
+
+from pydantic import SecretStr
+
+from hyperping._async_mcp_transport import AsyncMcpTransport
+from hyperping.endpoints import MCP_URL
+from hyperping.models._integration_models import Integration
+from hyperping.models._monitor_models import Monitor
+from hyperping.models._observability_models import MonitorAnomaly, ProbeLogResponse
+from hyperping.models._oncall_models import EscalationPolicy, OnCallSchedule, TeamMember
+from hyperping.models._outage_models import OutageTimeline
+from hyperping.models._reporting_models import (
+    AlertHistory,
+    MttaReport,
+    MttrReport,
+    ResponseTimeReport,
+    StatusSummary,
+)
+
+
+class AsyncHyperpingMcpClient:
+    """Async high-level client for Hyperping MCP server tools.
+
+    Provides typed convenience methods for every MCP tool. Methods return
+    Pydantic models matching the verified API response shapes.
+
+    Supports the same ``api_key`` formats (``str`` or ``SecretStr``) and
+    async context-manager pattern as
+    :class:`~hyperping._async_client.AsyncHyperpingClient`.
+    """
+
+    def __init__(
+        self,
+        api_key: str | SecretStr,
+        base_url: str = MCP_URL,
+        timeout: float = 30.0,
+    ) -> None:
+        self._transport = AsyncMcpTransport(
+            api_key=api_key,
+            base_url=base_url,
+            timeout=timeout,
+        )
+
+    # ==================== Internal ====================
+
+    async def _call(self, tool: str, args: dict[str, Any] | None = None) -> Any:
+        """Call an MCP tool via the transport."""
+        return await self._transport.call_tool(tool, args or {})
+
+    # ==================== Context Manager ====================
+
+    async def close(self) -> None:
+        """Close the underlying HTTP transport."""
+        await self._transport.close()
+
+    async def __aenter__(self) -> AsyncHyperpingMcpClient:
+        return self
+
+    async def __aexit__(self, *args: object) -> None:
+        await self.close()
+
+    # ==================== Status & Reporting ====================
+
+    async def get_status_summary(self) -> StatusSummary:
+        """Get aggregate monitor status counts."""
+        return StatusSummary.model_validate(await self._call("get_status_summary"))
+
+    async def get_monitor_response_time(
+        self,
+        monitor_uuid: str,
+        **kwargs: Any,
+    ) -> ResponseTimeReport:
+        """Get response time metrics for a monitor.
+
+        Args:
+            monitor_uuid: Monitor UUID.
+            **kwargs: Additional arguments forwarded to the MCP tool.
+        """
+        return ResponseTimeReport.model_validate(
+            await self._call("get_monitor_response_time", {"uuid": monitor_uuid, **kwargs})
+        )
+
+    async def get_monitor_mtta(
+        self,
+        monitor_uuid: str | None = None,
+        **kwargs: Any,
+    ) -> MttaReport:
+        """Get mean time to acknowledge metrics.
+
+        Args:
+            monitor_uuid: Optional monitor UUID to scope the query.
+            **kwargs: Additional arguments forwarded to the MCP tool.
+        """
+        args: dict[str, Any] = {**kwargs}
+        if monitor_uuid is not None:
+            args["uuid"] = monitor_uuid
+        return MttaReport.model_validate(await self._call("get_monitor_mtta", args))
+
+    async def get_monitor_mttr(
+        self,
+        monitor_uuid: str | None = None,
+        **kwargs: Any,
+    ) -> MttrReport:
+        """Get mean time to resolve metrics.
+
+        Args:
+            monitor_uuid: Optional monitor UUID to scope the query.
+            **kwargs: Additional arguments forwarded to the MCP tool.
+        """
+        args: dict[str, Any] = {**kwargs}
+        if monitor_uuid is not None:
+            args["uuid"] = monitor_uuid
+        return MttrReport.model_validate(await self._call("get_monitor_mttr", args))
+
+    # ==================== Observability ====================
+
+    async def get_monitor_anomalies(self, monitor_uuid: str) -> list[MonitorAnomaly]:
+        """Get anomalies detected for a monitor.
+
+        Args:
+            monitor_uuid: Monitor UUID.
+        """
+        data = await self._call("get_monitor_anomalies", {"uuid": monitor_uuid})
+        raw = data.get("anomalies", []) if isinstance(data, dict) else []
+        return [MonitorAnomaly.model_validate(a) for a in raw]
+
+    async def get_monitor_http_logs(
+        self,
+        monitor_uuid: str,
+        **kwargs: Any,
+    ) -> ProbeLogResponse:
+        """Get HTTP probe logs for a monitor.
+
+        Args:
+            monitor_uuid: Monitor UUID.
+            **kwargs: Additional arguments forwarded to the MCP tool.
+        """
+        data = await self._call("get_monitor_http_logs", {"uuid": monitor_uuid, **kwargs})
+        return ProbeLogResponse.model_validate(data)
+
+    # ==================== Alerts ====================
+
+    async def list_recent_alerts(self, **kwargs: Any) -> AlertHistory:
+        """List recent alert notifications.
+
+        Args:
+            **kwargs: Additional arguments forwarded to the MCP tool.
+        """
+        return AlertHistory.model_validate(await self._call("list_recent_alerts", {**kwargs}))
+
+    # ==================== On-Call ====================
+
+    async def list_on_call_schedules(self) -> list[OnCallSchedule]:
+        """List all on-call schedules."""
+        data = await self._call("list_on_call_schedules")
+        raw = data.get("schedules", []) if isinstance(data, dict) else []
+        return [OnCallSchedule.model_validate(s) for s in raw]
+
+    async def get_on_call_schedule(self, uuid: str) -> OnCallSchedule:
+        """Get a single on-call schedule by UUID.
+
+        Args:
+            uuid: Schedule UUID.
+        """
+        return OnCallSchedule.model_validate(
+            await self._call("get_on_call_schedule", {"uuid": uuid})
+        )
+
+    # ==================== Escalation Policies ====================
+
+    async def list_escalation_policies(self) -> list[EscalationPolicy]:
+        """List all escalation policies."""
+        data = await self._call("list_escalation_policies")
+        raw = data if isinstance(data, list) else []
+        return [EscalationPolicy.model_validate(p) for p in raw]
+
+    async def get_escalation_policy(self, uuid: str) -> EscalationPolicy:
+        """Get a single escalation policy by UUID.
+
+        Args:
+            uuid: Escalation policy UUID.
+        """
+        return EscalationPolicy.model_validate(
+            await self._call("get_escalation_policy", {"uuid": uuid})
+        )
+
+    # ==================== Team ====================
+
+    async def list_team_members(self) -> list[TeamMember]:
+        """List all team members."""
+        data = await self._call("list_team_members")
+        raw = data if isinstance(data, list) else []
+        return [TeamMember.model_validate(m) for m in raw]
+
+    # ==================== Integrations ====================
+
+    async def list_integrations(self) -> list[Integration]:
+        """List all notification channel integrations."""
+        data = await self._call("list_integrations")
+        raw = data if isinstance(data, list) else []
+        return [Integration.model_validate(i) for i in raw]
+
+    async def get_integration(self, uuid: str) -> Integration:
+        """Get a single integration by UUID.
+
+        Args:
+            uuid: Integration UUID.
+        """
+        return Integration.model_validate(await self._call("get_integration", {"uuid": uuid}))
+
+    # ==================== Outages ====================
+
+    async def get_outage_timeline(self, outage_uuid: str) -> OutageTimeline:
+        """Get the lifecycle timeline for an outage.
+
+        Args:
+            outage_uuid: Outage UUID.
+        """
+        return OutageTimeline.model_validate(
+            await self._call("get_outage_timeline", {"uuid": outage_uuid})
+        )
+
+    # ==================== Monitors ====================
+
+    async def search_monitors_by_name(self, query: str) -> list[Monitor]:
+        """Search monitors by name.
+
+        Args:
+            query: Search string to match against monitor names.
+        """
+        data = await self._call("search_monitors_by_name", {"query": query})
+        raw = data if isinstance(data, list) else []
+        return [Monitor.model_validate(m) for m in raw]