honeycomb-api 0.1.0__py3-none-any.whl

honeycomb/models/recipient_builder.py

@@ -0,0 +1,248 @@
+"""Builder pattern for Honeycomb Recipients."""
+
+from __future__ import annotations
+
+from typing import Any, Literal
+
+from typing_extensions import Self
+
+from .recipients import RecipientCreate, RecipientType
+
+
+class RecipientMixin:
+    """Mixin providing recipient creation methods.
+
+    This mixin is designed to be composed into other builders (TriggerBuilder,
+    BurnAlertBuilder) to provide fluent methods for adding recipients.
+    """
+
+    def __init__(self) -> None:
+        """Initialize recipient storage."""
+        self._recipients: list[dict[str, Any]] = []  # Existing recipient IDs
+        self._new_recipients: list[dict[str, Any]] = []  # Inline-created recipients
+
+    def email(self, address: str) -> Self:
+        """Add an email recipient.
+
+        Args:
+            address: Email address to notify.
+
+        Returns:
+            Self for method chaining.
+        """
+        self._new_recipients.append(
+            {
+                "type": "email",
+                "target": address,
+            }
+        )
+        return self
+
+    def slack(self, channel: str) -> Self:
+        """Add a Slack recipient.
+
+        Args:
+            channel: Slack channel name (e.g., "#alerts").
+
+        Returns:
+            Self for method chaining.
+        """
+        self._new_recipients.append(
+            {
+                "type": "slack",
+                "target": channel,
+            }
+        )
+        return self
+
+    def pagerduty(
+        self,
+        routing_key: str,
+        severity: Literal["info", "warning", "error", "critical"] = "critical",
+    ) -> Self:
+        """Add a PagerDuty recipient.
+
+        Args:
+            routing_key: PagerDuty integration routing key.
+            severity: Alert severity level.
+
+        Returns:
+            Self for method chaining.
+        """
+        self._new_recipients.append(
+            {
+                "type": "pagerduty",
+                "target": routing_key,
+                "details": {"severity": severity},
+            }
+        )
+        return self
+
+    def webhook(self, url: str, name: str = "Webhook", secret: str | None = None) -> Self:
+        """Add a webhook recipient (inline format for triggers/burn alerts).
+
+        Args:
+            url: Webhook URL to POST to.
+            name: A name for this webhook (default: "Webhook").
+            secret: Optional webhook secret for signing.
+
+        Returns:
+            Self for method chaining.
+
+        Note:
+            This creates inline recipients for triggers/burn alerts.
+            For standalone recipient creation via Recipients API, use RecipientBuilder.webhook().
+        """
+        details: dict[str, Any] = {
+            "webhook_url": url,
+            "webhook_name": name,
+        }
+        if secret:
+            details["webhook_secret"] = secret
+
+        self._new_recipients.append(
+            {
+                "type": "webhook",
+                "target": url,
+                "details": details,
+            }
+        )
+        return self
+
+    def msteams(self, workflow_url: str) -> Self:
+        """Add an MS Teams workflow recipient.
+
+        Args:
+            workflow_url: MS Teams workflow webhook URL.
+
+        Returns:
+            Self for method chaining.
+        """
+        self._new_recipients.append(
+            {
+                "type": "msteams_workflow",
+                "target": workflow_url,
+            }
+        )
+        return self
+
+    def recipient_id(self, recipient_id: str) -> Self:
+        """Reference an existing recipient by ID.
+
+        Args:
+            recipient_id: ID of an existing recipient.
+
+        Returns:
+            Self for method chaining.
+        """
+        self._recipients.append({"id": recipient_id})
+        return self
+
+    def _get_all_recipients(self) -> list[dict[str, Any]]:
+        """Get combined list of recipients for API.
+
+        Returns:
+            List of recipient dictionaries.
+        """
+        return self._recipients + self._new_recipients
+
+
+class RecipientBuilder:
+    """Factory for creating standalone RecipientCreate objects.
+
+    This builder provides convenient factory methods for creating recipients
+    that can be saved independently using the Recipients API.
+
+    Example:
+        >>> recipient = RecipientBuilder.email("oncall@example.com")
+        >>> await client.recipients.create_async(recipient)
+    """
+
+    @staticmethod
+    def email(address: str) -> RecipientCreate:
+        """Create an email recipient.
+
+        Args:
+            address: Email address to notify.
+
+        Returns:
+            RecipientCreate object.
+        """
+        return RecipientCreate(type=RecipientType.EMAIL, details={"email_address": address})
+
+    @staticmethod
+    def slack(channel: str) -> RecipientCreate:
+        """Create a Slack recipient.
+
+        Args:
+            channel: Slack channel name (e.g., "#alerts").
+
+        Returns:
+            RecipientCreate object.
+        """
+        return RecipientCreate(type=RecipientType.SLACK, details={"slack_channel": channel})
+
+    @staticmethod
+    def pagerduty(
+        integration_key: str,
+        integration_name: str = "PagerDuty Integration",
+    ) -> RecipientCreate:
+        """Create a PagerDuty recipient.
+
+        Args:
+            integration_key: PagerDuty integration key (32 characters).
+            integration_name: A name for this integration.
+
+        Returns:
+            RecipientCreate object.
+        """
+        return RecipientCreate(
+            type=RecipientType.PAGERDUTY,
+            details={
+                "pagerduty_integration_key": integration_key,
+                "pagerduty_integration_name": integration_name,
+            },
+        )
+
+    @staticmethod
+    def webhook(
+        url: str,
+        name: str = "Webhook",
+        secret: str | None = None,
+    ) -> RecipientCreate:
+        """Create a webhook recipient.
+
+        Args:
+            url: Webhook URL to POST to.
+            name: A name for this webhook.
+            secret: Optional webhook secret for signing.
+
+        Returns:
+            RecipientCreate object.
+        """
+        details: dict[str, Any] = {
+            "webhook_url": url,
+            "webhook_name": name,
+        }
+        if secret:
+            details["webhook_secret"] = secret
+        return RecipientCreate(type=RecipientType.WEBHOOK, details=details)
+
+    @staticmethod
+    def msteams(workflow_url: str, name: str = "MS Teams") -> RecipientCreate:
+        """Create an MS Teams workflow recipient.
+
+        Args:
+            workflow_url: MS Teams workflow webhook URL.
+            name: A name for this recipient.
+
+        Returns:
+            RecipientCreate object.
+        """
+        return RecipientCreate(
+            type=RecipientType.MSTEAMS_WORKFLOW,
+            details={
+                "webhook_url": workflow_url,
+                "webhook_name": name,
+            },
+        )

honeycomb/models/recipients.py

@@ -0,0 +1,43 @@
+"""Pydantic models for Honeycomb Recipients."""
+
+from __future__ import annotations
+
+from datetime import datetime
+from enum import Enum
+from typing import Any
+
+from pydantic import BaseModel, Field
+
+
+class RecipientType(str, Enum):
+    """Recipient notification types."""
+
+    EMAIL = "email"
+    SLACK = "slack"
+    PAGERDUTY = "pagerduty"
+    WEBHOOK = "webhook"
+    MSTEAMS = "msteams"
+    MSTEAMS_WORKFLOW = "msteams_workflow"
+
+
+class RecipientCreate(BaseModel):
+    """Model for creating a new recipient."""
+
+    type: RecipientType = Field(description="Type of recipient")
+    details: dict[str, Any] = Field(description="Recipient-specific configuration (varies by type)")
+
+    def model_dump_for_api(self) -> dict:
+        """Serialize for API request."""
+        return {"type": self.type.value, "details": self.details}
+
+
+class Recipient(BaseModel):
+    """A Honeycomb notification recipient (response model)."""
+
+    id: str = Field(description="Unique identifier")
+    type: RecipientType = Field(description="Type of recipient")
+    details: dict[str, Any] = Field(description="Recipient-specific configuration (varies by type)")
+    created_at: datetime | None = Field(default=None, description="Creation timestamp")
+    updated_at: datetime | None = Field(default=None, description="Last update timestamp")
+
+    model_config = {"extra": "allow"}

honeycomb/models/service_map_dependencies.py

@@ -0,0 +1,126 @@
+"""Pydantic models for Honeycomb Service Map Dependencies."""
+
+from __future__ import annotations
+
+from enum import Enum
+from typing import Any
+
+from pydantic import BaseModel, Field
+
+
+class ServiceMapNodeType(str, Enum):
+    """Type of node in the service map."""
+
+    SERVICE = "service"
+
+
+class ServiceMapNode(BaseModel):
+    """A node in the service map (typically a service).
+
+    Attributes:
+        name: Name of the service or node.
+        type: Type of the node. Currently only 'service' is supported.
+    """
+
+    name: str = Field(..., description="Name of the service or node")
+    type: ServiceMapNodeType = Field(
+        default=ServiceMapNodeType.SERVICE,
+        description="Type of the node. Currently only 'service' is supported.",
+    )
+
+
+class ServiceMapDependency(BaseModel):
+    """A dependency relationship between two services.
+
+    Attributes:
+        parent_node: The upstream service (caller).
+        child_node: The downstream service (callee).
+        call_count: Number of calls between the parent and child services.
+    """
+
+    parent_node: ServiceMapNode = Field(..., description="The upstream service (caller)")
+    child_node: ServiceMapNode = Field(..., description="The downstream service (callee)")
+    call_count: int = Field(..., description="Number of calls between services")
+
+
+class ServiceMapDependencyRequestStatus(str, Enum):
+    """Status of a Service Map Dependencies request."""
+
+    PENDING = "pending"
+    READY = "ready"
+    ERROR = "error"
+
+
+class ServiceMapDependencyRequestCreate(BaseModel):
+    """Request to create a Service Map Dependencies query.
+
+    Time range can be specified in several ways:
+    - time_range only: Seconds before now
+    - start_time + time_range: Seconds after start_time
+    - end_time + time_range: Seconds before end_time
+    - start_time + end_time: Explicit time range
+
+    Attributes:
+        start_time: Absolute start time in seconds since UNIX epoch.
+        end_time: Absolute end time in seconds since UNIX epoch.
+        time_range: Time range in seconds (default: 7200 = 2 hours).
+        filters: Optional list of service nodes to filter by.
+    """
+
+    start_time: int | None = Field(
+        default=None,
+        description="Absolute start time in seconds since UNIX epoch",
+    )
+    end_time: int | None = Field(
+        default=None,
+        description="Absolute end time in seconds since UNIX epoch",
+    )
+    time_range: int = Field(
+        default=7200,
+        ge=1,
+        description="Time range in seconds (default: 7200 = 2 hours)",
+    )
+    filters: list[ServiceMapNode] | None = Field(
+        default=None,
+        description="Optional list of service nodes to filter dependencies by",
+    )
+
+    def model_dump_for_api(self) -> dict[str, Any]:
+        """Serialize for API request, excluding None values."""
+        data: dict[str, Any] = {"time_range": self.time_range}
+        if self.start_time is not None:
+            data["start_time"] = self.start_time
+        if self.end_time is not None:
+            data["end_time"] = self.end_time
+        if self.filters:
+            data["filters"] = [f.model_dump() for f in self.filters]
+        return data
+
+
+class ServiceMapDependencyRequest(BaseModel):
+    """Response from creating a Service Map Dependencies request.
+
+    Attributes:
+        request_id: Unique identifier for the request.
+        status: Status of the request (pending, ready, error).
+    """
+
+    request_id: str = Field(..., description="Unique identifier for the request")
+    status: ServiceMapDependencyRequestStatus = Field(..., description="Status of the request")
+
+
+class ServiceMapDependencyResult(BaseModel):
+    """Result of a Service Map Dependencies query.
+
+    Attributes:
+        request_id: Unique identifier for the request.
+        status: Status of the request (pending, ready, error).
+        dependencies: List of service dependencies (None if pending/error).
+    """
+
+    request_id: str = Field(..., description="Unique identifier for the request")
+    status: ServiceMapDependencyRequestStatus = Field(..., description="Status of the request")
+    dependencies: list[ServiceMapDependency] | None = Field(
+        default=None,
+        description="List of service dependencies (None if pending/error)",
+    )