devhelm 1.2.0__tar.gz → 1.4.0__tar.gz

{devhelm-1.2.0 → devhelm-1.4.0}/PKG-INFO

@@ -1,6 +1,6 @@
 Metadata-Version: 2.4
 Name: devhelm
-Version: 1.2.0
+Version: 1.4.0
 Summary: DevHelm SDK for Python — typed client for monitors, incidents, alerting, and more
 Project-URL: Homepage, https://github.com/devhelmhq/sdk-python
 Project-URL: Repository, https://github.com/devhelmhq/sdk-python.git
@@ -108,6 +108,7 @@ The client exposes the following resource modules:
 | `client.api_keys`       | API key management                |
 | `client.dependencies`   | Service dependency tracking       |
 | `client.deploy_lock`    | Deploy lock for safe deployments  |
+| `client.services`       | Status Data catalog: vendor services, components, incidents, uptime |
 | `client.status`         | Dashboard overview                |
 
 ## Pagination

{devhelm-1.2.0 → devhelm-1.4.0}/README.md

@@ -84,6 +84,7 @@ The client exposes the following resource modules:
 | `client.api_keys`       | API key management                |
 | `client.dependencies`   | Service dependency tracking       |
 | `client.deploy_lock`    | Deploy lock for safe deployments  |
+| `client.services`       | Status Data catalog: vendor services, components, incidents, uptime |
 | `client.status`         | Dashboard overview                |
 
 ## Pagination

{devhelm-1.2.0 → devhelm-1.4.0}/docs/openapi/monitoring-api.json

@@ -2274,6 +2274,18 @@
         ],
         "summary": "List categories with service counts",
         "operationId": "listCategories",
+        "parameters": [
+          {
+            "name": "publishedOnly",
+            "in": "query",
+            "description": "Count only published services (curated public pSEO set); default false",
+            "required": false,
+            "schema": {
+              "type": "boolean",
+              "default": false
+            }
+          }
+        ],
         "responses": {
           "200": {
             "description": "OK",
@@ -13520,6 +13532,24 @@
               "type": "boolean"
             }
           },
+          {
+            "name": "search",
+            "in": "query",
+            "description": "Case-insensitive substring match on service name or slug",
+            "required": false,
+            "schema": {
+              "type": "string"
+            }
+          },
+          {
+            "name": "sort",
+            "in": "query",
+            "description": "Result ordering: 'recent' (default, newest first) or 'curated' (curated/recognizable first)",
+            "required": false,
+            "schema": {
+              "type": "string"
+            }
+          },
           {
             "name": "cursor",
             "in": "query",
@@ -13661,6 +13691,16 @@
               "type": "boolean",
               "default": false
             }
+          },
+          {
+            "name": "publishedOnly",
+            "in": "query",
+            "description": "Resolve only published services (curated public pSEO set); 404 otherwise. Default false",
+            "required": false,
+            "schema": {
+              "type": "boolean",
+              "default": false
+            }
           }
         ],
         "responses": {
@@ -15358,6 +15398,18 @@
         "summary": "Global status summary across all services",
         "description": "Returns aggregate counts of services by status and a list of services currently experiencing issues.",
         "operationId": "getGlobalStatusSummary",
+        "parameters": [
+          {
+            "name": "publishedOnly",
+            "in": "query",
+            "description": "Aggregate only published services (curated public pSEO set); default false",
+            "required": false,
+            "schema": {
+              "type": "boolean",
+              "default": false
+            }
+          }
+        ],
         "responses": {
           "200": {
             "description": "OK",

{devhelm-1.2.0 → devhelm-1.4.0}/pyproject.toml

@@ -1,6 +1,6 @@
 [project]
 name = "devhelm"
-version = "1.2.0"
+version = "1.4.0"
 description = "DevHelm SDK for Python — typed client for monitors, incidents, alerting, and more"
 authors = [{ name = "DevHelm", email = "hello@devhelm.io" }]
 license = "MIT"

{devhelm-1.2.0 → devhelm-1.4.0}/src/devhelm/__init__.py

@@ -29,6 +29,7 @@ from devhelm.resources.monitors import Monitors
 from devhelm.resources.notification_policies import NotificationPolicies
 from devhelm.resources.resource_groups import ResourceGroups
 from devhelm.resources.secrets import Secrets
+from devhelm.resources.services import Services
 from devhelm.resources.status import Status
 from devhelm.resources.status_pages import StatusPages
 from devhelm.resources.tags import Tags
@@ -46,8 +47,11 @@ from devhelm.types import (
     ApiKeyDto,
     AssertionSeverity,
     AssertionTestResultDto,
+    BatchComponentUptimeDto,
+    CategoryDto,
     CheckResultDto,
     CheckTraceDto,
+    ComponentUptimeDayDto,
     ConfirmationPolicyType,
     CreateAlertChannelRequest,
     CreateApiKeyRequest,
@@ -69,6 +73,7 @@ from devhelm.types import (
     DashboardOverviewDto,
     DeployLockDto,
     EnvironmentDto,
+    GlobalStatusSummaryDto,
     IncidentDetailDto,
     IncidentDto,
     IncidentNewStatus,
@@ -78,6 +83,7 @@ from devhelm.types import (
     IncidentStatus,
     IncidentTimelineDto,
     IncidentUpdateCreatedBy,
+    LifecycleStatus,
     LinkedIncidentStatus,
     MaintenanceWindowDto,
     MembershipStatus,
@@ -99,8 +105,18 @@ from devhelm.types import (
     ResourceGroupHealthStatus,
     ResourceGroupMemberDto,
     RuleEvaluationDto,
+    ScheduledMaintenanceDto,
     SecretDto,
+    ServiceCatalogDto,
+    ServiceComponentDto,
+    ServiceDayDetailDto,
+    ServiceDetailDto,
+    ServiceIncidentDetailDto,
+    ServiceIncidentDto,
+    ServiceLiveStatusDto,
+    ServiceSubscribeRequest,
     ServiceSubscriptionDto,
+    ServiceUptimeResponse,
     StatusPageBranding,
     StatusPageComponentCurrentStatus,
     StatusPageComponentDto,
@@ -124,6 +140,7 @@ from devhelm.types import (
     TriggerRuleSeverity,
     TriggerRuleType,
     UpdateAlertChannelRequest,
+    UpdateAlertSensitivityRequest,
     UpdateAssertionSeverity,
     UpdateEnvironmentRequest,
     UpdateMaintenanceWindowRequest,
@@ -184,6 +201,7 @@ __all__ = [
     "Dependencies",
     "DeployLock",
     "MaintenanceWindows",
+    "Services",
     "Status",
     "StatusPages",
     # Response DTOs
@@ -216,6 +234,19 @@ __all__ = [
     "ApiKeyDto",
     "ApiKeyCreateResponse",
     "ServiceSubscriptionDto",
+    "ServiceCatalogDto",
+    "ServiceDetailDto",
+    "ServiceLiveStatusDto",
+    "ServiceComponentDto",
+    "ServiceIncidentDto",
+    "ServiceIncidentDetailDto",
+    "ServiceUptimeResponse",
+    "ServiceDayDetailDto",
+    "ScheduledMaintenanceDto",
+    "CategoryDto",
+    "GlobalStatusSummaryDto",
+    "BatchComponentUptimeDto",
+    "ComponentUptimeDayDto",
     "MonitorVersionDto",
     "CheckResultDto",
     "DashboardOverviewDto",
@@ -261,6 +292,8 @@ __all__ = [
     "UpdateWebhookEndpointRequest",
     "CreateApiKeyRequest",
     "AcquireDeployLockRequest",
+    "ServiceSubscribeRequest",
+    "UpdateAlertSensitivityRequest",
     # Enum aliases (descriptive names for codegen-numbered enums)
     "AffectedComponentStatus",
     "AlertDeliveryStatus",
@@ -272,6 +305,7 @@ __all__ = [
     "IncidentSeverity",
     "IncidentStatus",
     "IncidentUpdateCreatedBy",
+    "LifecycleStatus",
     "LinkedIncidentStatus",
     "MemberStatus",
     "MembershipStatus",

{devhelm-1.2.0 → devhelm-1.4.0}/src/devhelm/_errors.py

@@ -82,6 +82,11 @@ class DevhelmApiError(DevhelmError):
     The optional `request_id` field is the per-request id emitted by the
     API as the `X-Request-Id` response header and embedded in the JSON
     error body. Always include it in support tickets.
+
+    The optional `retry_after` field is the parsed value of the
+    `Retry-After` response header in whole seconds. It's populated on
+    rate-limit (429) responses that include the header so callers can back
+    off for exactly as long as the server asked; ``None`` otherwise.
     """
 
     status: int
@@ -93,6 +98,7 @@ class DevhelmApiError(DevhelmError):
     # narrowing. (Subclasses still inherit the same `str` type.)
     code: str
     request_id: str | None
+    retry_after: int | None
 
     def __init__(
         self,
@@ -103,6 +109,7 @@ class DevhelmApiError(DevhelmError):
         body: dict[str, Any] | str | None = None,
         code: str | None = None,
         request_id: str | None = None,
+        retry_after: int | None = None,
     ) -> None:
         super().__init__(message)
         self.status = status
@@ -113,6 +120,9 @@ class DevhelmApiError(DevhelmError):
         # `err.code` is never ``None`` for callers switching on category.
         self.code = code or "API_ERROR"
         self.request_id = request_id
+        # Parsed from the `Retry-After` response header (seconds). Populated
+        # on 429 / 503 responses that include it; ``None`` otherwise.
+        self.retry_after = retry_after
 
 
 class DevhelmAuthError(DevhelmApiError):
@@ -152,8 +162,28 @@ class DevhelmTransportError(DevhelmError):
             self.__cause__ = cause
 
 
+def _parse_retry_after(value: str | None) -> int | None:
+    """Parse a ``Retry-After`` header value into whole seconds.
+
+    The API emits ``Retry-After`` as an integer number of seconds. We parse
+    defensively: any non-integer value (an HTTP-date form, or garbage from a
+    misbehaving proxy) yields ``None`` rather than raising, so a malformed
+    header can never break error construction.
+    """
+    if value is None:
+        return None
+    try:
+        return int(value)
+    except (TypeError, ValueError):
+        return None
+
+
 def error_from_response(
-    status: int, body: str, *, request_id: str | None = None
+    status: int,
+    body: str,
+    *,
+    request_id: str | None = None,
+    retry_after: str | None = None,
 ) -> DevhelmApiError:
     """Map an HTTP error response to a typed DevhelmApiError subclass.
 
@@ -161,6 +191,11 @@ def error_from_response(
     pulled out at the call site (rather than re-parsed from the body) so the
     SDK still surfaces the id even when the server returns a non-JSON body
     (e.g. an HTML error page from a misconfigured proxy).
+
+    `retry_after` is the raw value of the `Retry-After` response header,
+    pulled out at the call site for the same reason. It's parsed into whole
+    seconds and surfaced as ``err.retry_after`` (e.g. on 429 responses) so
+    callers can back off for exactly as long as the server asked.
     """
     message = f"HTTP {status}"
     detail: str | None = None
@@ -195,6 +230,7 @@ def error_from_response(
         "body": parsed_body,
         "code": code,
         "request_id": resolved_request_id,
+        "retry_after": _parse_retry_after(retry_after),
     }
 
     if status in (401, 403):

{devhelm-1.2.0 → devhelm-1.4.0}/src/devhelm/_http.py

@@ -180,6 +180,7 @@ def checked_fetch(response: httpx.Response) -> _JsonResponse:
         response.status_code,
         response.text,
         request_id=response.headers.get("x-request-id"),
+        retry_after=response.headers.get("retry-after"),
     )
 
 

{devhelm-1.2.0 → devhelm-1.4.0}/src/devhelm/_pagination.py

@@ -151,9 +151,18 @@ def fetch_cursor_page(
     model_class: type[M],
     cursor: str | None = None,
     limit: int | None = None,
+    *,
+    extra_params: dict[str, Any] | None = None,
 ) -> CursorPage[M]:
-    """Fetch a single page from a cursor-paginated endpoint with validation."""
-    params: dict[str, Any] = {}
+    """Fetch a single page from a cursor-paginated endpoint with validation.
+
+    ``extra_params`` is merged into the request so callers can forward
+    server-side filter kwargs (``category``, ``search``, …) alongside the
+    cursor controls. Pagination keys (``cursor``, ``limit``) always win
+    over user-supplied ``extra_params`` to keep the iterator's invariants
+    intact.
+    """
+    params: dict[str, Any] = dict(extra_params) if extra_params else {}
     if cursor:
         params["cursor"] = cursor
     if limit:

{devhelm-1.2.0 → devhelm-1.4.0}/src/devhelm/client.py

@@ -15,6 +15,7 @@ from devhelm.resources.monitors import Monitors
 from devhelm.resources.notification_policies import NotificationPolicies
 from devhelm.resources.resource_groups import ResourceGroups
 from devhelm.resources.secrets import Secrets
+from devhelm.resources.services import Services
 from devhelm.resources.status import Status
 from devhelm.resources.status_pages import StatusPages
 from devhelm.resources.tags import Tags
@@ -53,6 +54,7 @@ class Devhelm:
     dependencies: Dependencies
     deploy_lock: DeployLock
     maintenance_windows: MaintenanceWindows
+    services: Services
     status: Status
     status_pages: StatusPages
 
@@ -99,5 +101,6 @@ class Devhelm:
         self.dependencies = Dependencies(client)
         self.deploy_lock = DeployLock(client)
         self.maintenance_windows = MaintenanceWindows(client)
+        self.services = Services(client)
         self.status = Status(client)
         self.status_pages = StatusPages(client)

{devhelm-1.2.0 → devhelm-1.4.0}/src/devhelm/resources/api_keys.py

@@ -3,7 +3,7 @@ from __future__ import annotations
 import httpx
 
 from devhelm._generated import ApiKeyCreateResponse, ApiKeyDto, CreateApiKeyRequest
-from devhelm._http import api_delete, api_post, path_param
+from devhelm._http import api_delete, api_get, api_post, path_param
 from devhelm._pagination import Page, fetch_all_pages, fetch_page
 from devhelm._validation import RequestBody, parse_single, validate_request
 
@@ -22,6 +22,14 @@ class ApiKeys:
         """List API keys with manual page control."""
         return fetch_page(self._client, "/api/v1/api-keys", ApiKeyDto, page, size)
 
+    def get(self, id: int | str) -> ApiKeyDto:
+        """Get a single API key by ID."""
+        return parse_single(
+            ApiKeyDto,
+            api_get(self._client, f"/api/v1/api-keys/{path_param(id)}"),
+            f"GET /api/v1/api-keys/{id}",
+        )
+
     def create(self, body: RequestBody[CreateApiKeyRequest]) -> ApiKeyCreateResponse:
         """Create an API key. Returns the key value (shown only once)."""
         body = validate_request(CreateApiKeyRequest, body, "apiKeys.create")

devhelm-1.4.0/src/devhelm/resources/dependencies.py

@@ -0,0 +1,100 @@
+from __future__ import annotations
+
+import httpx
+
+from devhelm._generated import (
+    ServiceSubscribeRequest,
+    ServiceSubscriptionDto,
+    UpdateAlertSensitivityRequest,
+)
+from devhelm._http import api_delete, api_get, api_patch, api_post, path_param
+from devhelm._pagination import Page, fetch_all_pages, fetch_page
+from devhelm._validation import parse_single, validate_request
+
+
+class Dependencies:
+    """Service dependency tracking (service subscriptions)."""
+
+    def __init__(self, client: httpx.Client) -> None:
+        self._client = client
+
+    def list(self) -> list[ServiceSubscriptionDto]:
+        """List all tracked service dependencies."""
+        return fetch_all_pages(
+            self._client, "/api/v1/service-subscriptions", ServiceSubscriptionDto
+        )
+
+    def list_page(self, page: int, size: int) -> Page[ServiceSubscriptionDto]:
+        """List tracked dependencies with manual page control."""
+        return fetch_page(
+            self._client,
+            "/api/v1/service-subscriptions",
+            ServiceSubscriptionDto,
+            page,
+            size,
+        )
+
+    def get(self, id: int | str) -> ServiceSubscriptionDto:
+        """Get a tracked dependency by ID."""
+        return parse_single(
+            ServiceSubscriptionDto,
+            api_get(self._client, f"/api/v1/service-subscriptions/{path_param(id)}"),
+            f"GET /api/v1/service-subscriptions/{id}",
+        )
+
+    def track(
+        self,
+        slug: str,
+        *,
+        component_id: str | None = None,
+        alert_sensitivity: str | None = None,
+    ) -> ServiceSubscriptionDto:
+        """Track a new service dependency by slug.
+
+        ``component_id`` subscribes to one component instead of the whole
+        service. ``alert_sensitivity`` is one of ``ALL``,
+        ``INCIDENTS_ONLY``, ``MAJOR_ONLY``, or ``AWARENESS`` (the API
+        default — silent tracking with no alert fan-out). The request body
+        is omitted entirely when neither kwarg is provided.
+        """
+        body: ServiceSubscribeRequest | None = None
+        if component_id is not None or alert_sensitivity is not None:
+            fields: dict[str, str] = {}
+            if component_id is not None:
+                fields["componentId"] = component_id
+            if alert_sensitivity is not None:
+                fields["alertSensitivity"] = alert_sensitivity
+            body = validate_request(
+                ServiceSubscribeRequest, fields, "dependencies.track"
+            )
+        return parse_single(
+            ServiceSubscriptionDto,
+            api_post(
+                self._client, f"/api/v1/service-subscriptions/{path_param(slug)}", body
+            ),
+            f"POST /api/v1/service-subscriptions/{slug}",
+        )
+
+    def update_alert_sensitivity(
+        self, subscription_id: int | str, alert_sensitivity: str
+    ) -> ServiceSubscriptionDto:
+        """Update the alert sensitivity on a tracked dependency.
+
+        ``alert_sensitivity`` is one of ``ALL``, ``INCIDENTS_ONLY``,
+        ``MAJOR_ONLY``, or ``AWARENESS``.
+        """
+        body = validate_request(
+            UpdateAlertSensitivityRequest,
+            {"alertSensitivity": alert_sensitivity},
+            "dependencies.update_alert_sensitivity",
+        )
+        path = f"/api/v1/service-subscriptions/{path_param(subscription_id)}"
+        return parse_single(
+            ServiceSubscriptionDto,
+            api_patch(self._client, f"{path}/alert-sensitivity", body),
+            f"PATCH /api/v1/service-subscriptions/{subscription_id}/alert-sensitivity",
+        )
+
+    def delete(self, id: int | str) -> None:
+        """Remove a tracked dependency."""
+        api_delete(self._client, f"/api/v1/service-subscriptions/{path_param(id)}")