nornweave 0.1.2__py3-none-any.whl

nornweave/models/event.py

@@ -0,0 +1,275 @@
+"""Event models for webhooks.
+
+Event models for webhook notifications and internal event tracking.
+"""
+
+from datetime import datetime
+from enum import Enum
+from typing import TYPE_CHECKING, Any, Literal
+
+from pydantic import BaseModel, Field
+
+if TYPE_CHECKING:
+    from nornweave.models.message import Message
+    from nornweave.models.thread import ThreadItem
+
+
+class EventType(str, Enum):
+    """
+    Event types for webhooks.
+
+    Supported event types for webhooks and notifications.
+    """
+
+    MESSAGE_RECEIVED = "message.received"
+    MESSAGE_SENT = "message.sent"
+    MESSAGE_DELIVERED = "message.delivered"
+    MESSAGE_BOUNCED = "message.bounced"
+    MESSAGE_COMPLAINED = "message.complained"
+    MESSAGE_REJECTED = "message.rejected"
+    DOMAIN_VERIFIED = "domain.verified"
+    # Legacy event types for backwards compatibility
+    THREAD_NEW_MESSAGE = "thread.new_message"
+    INBOX_CREATED = "inbox.created"
+    INBOX_DELETED = "inbox.deleted"
+
+
+class Recipient(BaseModel):
+    """
+    Recipient with delivery status.
+
+    Recipient with delivery status information.
+    """
+
+    address: str = Field(..., description="Recipient address")
+    status: str = Field(..., description="Recipient status")
+
+    model_config = {"extra": "forbid"}
+
+
+class SendEvent(BaseModel):
+    """
+    Event data for message sent.
+
+    Send event payload with recipient list.
+    """
+
+    inbox_id: str
+    thread_id: str
+    message_id: str
+    timestamp: datetime
+    recipients: list[str] = Field(..., description="Sent recipients")
+
+    model_config = {"extra": "forbid"}
+
+
+class DeliveryEvent(BaseModel):
+    """
+    Event data for message delivered.
+
+    Delivery confirmation event payload.
+    """
+
+    inbox_id: str
+    thread_id: str
+    message_id: str
+    timestamp: datetime
+    recipients: list[str] = Field(..., description="Delivered recipients")
+
+    model_config = {"extra": "forbid"}
+
+
+class BounceEvent(BaseModel):
+    """
+    Event data for message bounced.
+
+    Bounce event payload with type and affected recipients.
+    """
+
+    inbox_id: str
+    thread_id: str
+    message_id: str
+    timestamp: datetime
+    type: str = Field(..., description="Bounce type (hard/soft)")
+    sub_type: str = Field(..., description="Bounce sub-type")
+    recipients: list[Recipient] = Field(..., description="Bounced recipients with status")
+
+    model_config = {"extra": "forbid"}
+
+
+class ComplaintEvent(BaseModel):
+    """
+    Event data for spam complaint.
+
+    Spam complaint event payload.
+    """
+
+    inbox_id: str
+    thread_id: str
+    message_id: str
+    timestamp: datetime
+    type: str = Field(..., description="Complaint type")
+    sub_type: str = Field(..., description="Complaint sub-type")
+    recipients: list[str] = Field(..., description="Complained recipients")
+
+    model_config = {"extra": "forbid"}
+
+
+class RejectEvent(BaseModel):
+    """
+    Event data for message rejected.
+
+    Rejection event payload with reason.
+    """
+
+    inbox_id: str
+    thread_id: str
+    message_id: str
+    timestamp: datetime
+    reason: str = Field(..., description="Reject reason")
+
+    model_config = {"extra": "forbid"}
+
+
+class MessageReceivedEvent(BaseModel):
+    """
+    Webhook event for message received.
+
+    Webhook payload for inbound message received.
+    """
+
+    type: Literal["event"] = "event"
+    event_type: Literal["message.received"] = "message.received"
+    event_id: str
+    message: Message
+    thread: ThreadItem
+
+    model_config = {"extra": "forbid"}
+
+
+class MessageSentEvent(BaseModel):
+    """
+    Webhook event for message sent.
+
+    Webhook payload for message sent.
+    """
+
+    type: Literal["event"] = "event"
+    event_type: Literal["message.sent"] = "message.sent"
+    event_id: str
+    send: SendEvent
+
+    model_config = {"extra": "forbid"}
+
+
+class MessageDeliveredEvent(BaseModel):
+    """
+    Webhook event for message delivered.
+
+    Webhook payload for message delivered.
+    """
+
+    type: Literal["event"] = "event"
+    event_type: Literal["message.delivered"] = "message.delivered"
+    event_id: str
+    delivery: DeliveryEvent
+
+    model_config = {"extra": "forbid"}
+
+
+class MessageBouncedEvent(BaseModel):
+    """
+    Webhook event for message bounced.
+
+    Webhook payload for message bounced.
+    """
+
+    type: Literal["event"] = "event"
+    event_type: Literal["message.bounced"] = "message.bounced"
+    event_id: str
+    bounce: BounceEvent
+
+    model_config = {"extra": "forbid"}
+
+
+class MessageComplainedEvent(BaseModel):
+    """
+    Webhook event for spam complaint.
+
+    Webhook payload for spam complaint.
+    """
+
+    type: Literal["event"] = "event"
+    event_type: Literal["message.complained"] = "message.complained"
+    event_id: str
+    complaint: ComplaintEvent
+
+    model_config = {"extra": "forbid"}
+
+
+class MessageRejectedEvent(BaseModel):
+    """
+    Webhook event for message rejected.
+
+    Webhook payload for message rejected.
+    """
+
+    type: Literal["event"] = "event"
+    event_type: Literal["message.rejected"] = "message.rejected"
+    event_id: str
+    reject: RejectEvent
+
+    model_config = {"extra": "forbid"}
+
+
+# Type alias for all webhook events
+WebhookEvent = (
+    MessageReceivedEvent
+    | MessageSentEvent
+    | MessageDeliveredEvent
+    | MessageBouncedEvent
+    | MessageComplainedEvent
+    | MessageRejectedEvent
+)
+
+
+# Legacy models for backwards compatibility
+class EventCreate(BaseModel):
+    """Payload to create an event (id and created_at set by storage)."""
+
+    type: EventType = Field(..., description="Event type")
+    payload: dict[str, Any] = Field(
+        default_factory=dict,
+        description="Event payload",
+    )
+
+    model_config = {"extra": "forbid"}
+
+
+class Event(BaseModel):
+    """Event entity with id and timestamp."""
+
+    id: str = Field(..., description="Event id")
+    type: EventType = Field(..., description="Event type")
+    created_at: datetime = Field(default_factory=datetime.utcnow)
+    payload: dict[str, Any] = Field(
+        default_factory=dict,
+        description="Event payload",
+    )
+    # Additional fields for structured events
+    inbox_id: str | None = Field(None, description="Associated inbox ID")
+    thread_id: str | None = Field(None, description="Associated thread ID")
+    message_id: str | None = Field(None, description="Associated message ID")
+
+    model_config = {"extra": "forbid"}
+
+
+class ListEventsResponse(BaseModel):
+    """Response for listing events."""
+
+    count: int = Field(..., description="Total count of events")
+    limit: int | None = Field(None, description="Limit applied to results")
+    next_page_token: str | None = Field(None, description="Token for next page")
+    events: list[Event] = Field(..., description="Events ordered by timestamp descending")
+
+    model_config = {"extra": "forbid"}

nornweave/models/inbox.py

@@ -0,0 +1,33 @@
+"""Inbox model."""
+
+from typing import Any
+
+from pydantic import BaseModel, Field
+
+
+class InboxBase(BaseModel):
+    """Shared inbox fields."""
+
+    email_address: str = Field(..., description="Full email address for this inbox")
+    name: str | None = Field(None, description="Human-readable name")
+    provider_config: dict[str, Any] = Field(
+        default_factory=dict,
+        description="Provider-specific metadata (e.g. route_id, domain, webhook_id)",
+    )
+
+
+class InboxCreate(BaseModel):
+    """Payload to create an inbox."""
+
+    name: str = Field(..., min_length=1, description="Display name")
+    email_username: str = Field(..., min_length=1, description="Local part (e.g. support)")
+
+    model_config = {"extra": "forbid"}
+
+
+class Inbox(InboxBase):
+    """Inbox entity with id."""
+
+    id: str = Field(..., description="Unique inbox id (e.g. UUID)")
+
+    model_config = {"extra": "forbid"}

nornweave/models/message.py

@@ -0,0 +1,284 @@
+"""Message models.
+
+Message models for email content and metadata.
+"""
+
+from datetime import datetime  # noqa: TC003 - needed at runtime for Pydantic
+from enum import Enum
+from typing import TYPE_CHECKING, Any
+
+from pydantic import BaseModel, Field
+
+if TYPE_CHECKING:
+    from nornweave.models.attachment import Attachment, AttachmentMeta, SendAttachment
+
+
+class MessageDirection(str, Enum):
+    """Message direction."""
+
+    INBOUND = "inbound"
+    OUTBOUND = "outbound"
+
+
+class MessageItem(BaseModel):
+    """
+    Message summary for list views (without full body content).
+
+    Summary model for message list views.
+    """
+
+    inbox_id: str = Field(..., description="ID of inbox")
+    thread_id: str = Field(..., description="ID of thread")
+    message_id: str = Field(..., description="ID of message")
+    labels: list[str] = Field(default_factory=list, description="Labels of message")
+    timestamp: datetime = Field(..., description="Time at which message was sent or drafted")
+    from_address: str = Field(..., alias="from", description="Sender address")
+    to: list[str] = Field(..., description="Recipient addresses")
+    cc: list[str] | None = Field(None, description="CC recipient addresses")
+    bcc: list[str] | None = Field(None, description="BCC recipient addresses")
+    subject: str | None = Field(None, description="Subject of message")
+    preview: str | None = Field(None, description="Text preview of message")
+    attachments: list[AttachmentMeta] | None = Field(None, description="Attachments in message")
+    in_reply_to: str | None = Field(None, description="Message-ID of message being replied to")
+    references: list[str] | None = Field(
+        None, description="Message-IDs of previous messages in thread"
+    )
+    headers: dict[str, str] | None = Field(None, description="Headers in message")
+    size: int = Field(..., description="Size of message in bytes")
+    updated_at: datetime = Field(..., description="Time at which message was last updated")
+    created_at: datetime = Field(..., description="Time at which message was created")
+
+    model_config = {"extra": "forbid", "populate_by_name": True}
+
+
+class Message(BaseModel):
+    """
+    Full message model with body content.
+
+    Complete message model with body content.
+    """
+
+    inbox_id: str = Field(..., description="ID of inbox")
+    thread_id: str = Field(..., description="ID of thread")
+    message_id: str = Field(..., alias="id", description="ID of message")
+    labels: list[str] = Field(default_factory=list, description="Labels of message")
+    timestamp: datetime | None = Field(
+        None, description="Time at which message was sent or drafted"
+    )
+    from_address: str | None = Field(None, alias="from", description="Sender address")
+    reply_to: list[str] | None = Field(None, description="Reply-to addresses")
+    to: list[str] = Field(default_factory=list, description="Recipient addresses")
+    cc: list[str] | None = Field(None, description="CC recipient addresses")
+    bcc: list[str] | None = Field(None, description="BCC recipient addresses")
+    subject: str | None = Field(None, description="Subject of message")
+    preview: str | None = Field(None, description="Text preview of message")
+    text: str | None = Field(None, alias="content_raw", description="Plain text body of message")
+    html: str | None = Field(None, description="HTML body of message")
+    extracted_text: str | None = Field(
+        None,
+        alias="content_clean",
+        description="Extracted new text content (without quoted replies)",
+    )
+    extracted_html: str | None = Field(
+        None, description="Extracted new HTML content (without quoted replies)"
+    )
+    attachments: list[Attachment] | None = Field(None, description="Attachments in message")
+    in_reply_to: str | None = Field(None, description="Message-ID of message being replied to")
+    references: list[str] | None = Field(
+        None, description="Message-IDs of previous messages in thread"
+    )
+    headers: dict[str, str] | None = Field(
+        None, alias="metadata", description="All headers in message"
+    )
+    size: int = Field(0, description="Size of message in bytes")
+    direction: MessageDirection = Field(
+        default=MessageDirection.INBOUND, description="Inbound or outbound"
+    )
+    provider_message_id: str | None = Field(None, description="Provider's Message-ID header")
+    updated_at: datetime | None = Field(None, description="Time at which message was last updated")
+    created_at: datetime | None = Field(None, description="Time at which message was created")
+
+    model_config = {"populate_by_name": True}
+
+    @property
+    def id(self) -> str:
+        """Alias for message_id for compatibility."""
+        return self.message_id
+
+    @property
+    def content_raw(self) -> str | None:
+        """Alias for text for backwards compatibility."""
+        return self.text
+
+    @property
+    def content_clean(self) -> str | None:
+        """Alias for extracted_text for backwards compatibility."""
+        return self.extracted_text
+
+    @property
+    def metadata(self) -> dict[str, str] | None:
+        """Alias for headers for backwards compatibility."""
+        return self.headers
+
+
+class ListMessagesResponse(BaseModel):
+    """
+    Response for listing messages.
+
+    Paginated response for message listing.
+    """
+
+    count: int = Field(..., description="Total count of messages")
+    limit: int | None = Field(None, description="Limit applied to results")
+    next_page_token: str | None = Field(None, description="Token for next page")
+    messages: list[MessageItem] = Field(..., description="Messages ordered by timestamp descending")
+
+    model_config = {"extra": "forbid"}
+
+
+class SendMessageRequest(BaseModel):
+    """
+    Request to send a new message.
+
+    Request payload for sending a new message.
+    """
+
+    labels: list[str] | None = None
+    reply_to: str | list[str] | None = Field(None, description="Reply-to address(es)")
+    to: str | list[str] | None = Field(None, description="Recipient address(es)")
+    cc: str | list[str] | None = Field(None, description="CC address(es)")
+    bcc: str | list[str] | None = Field(None, description="BCC address(es)")
+    subject: str | None = None
+    text: str | None = Field(None, description="Plain text body")
+    html: str | None = Field(None, description="HTML body")
+    attachments: list[SendAttachment] | None = None
+    headers: dict[str, str] | None = None
+
+    model_config = {"extra": "forbid"}
+
+    def get_to_list(self) -> list[str]:
+        """Get 'to' as a list."""
+        if self.to is None:
+            return []
+        return [self.to] if isinstance(self.to, str) else list(self.to)
+
+    def get_cc_list(self) -> list[str]:
+        """Get 'cc' as a list."""
+        if self.cc is None:
+            return []
+        return [self.cc] if isinstance(self.cc, str) else list(self.cc)
+
+    def get_bcc_list(self) -> list[str]:
+        """Get 'bcc' as a list."""
+        if self.bcc is None:
+            return []
+        return [self.bcc] if isinstance(self.bcc, str) else list(self.bcc)
+
+    def get_reply_to_list(self) -> list[str]:
+        """Get 'reply_to' as a list."""
+        if self.reply_to is None:
+            return []
+        return [self.reply_to] if isinstance(self.reply_to, str) else list(self.reply_to)
+
+
+class SendMessageResponse(BaseModel):
+    """
+    Response after sending a message.
+
+    Response after sending a message.
+    """
+
+    message_id: str
+    thread_id: str
+
+    model_config = {"extra": "forbid"}
+
+
+class ReplyToMessageRequest(BaseModel):
+    """
+    Request to reply to a specific message.
+
+    Request payload for replying to a message.
+    """
+
+    labels: list[str] | None = None
+    reply_to: str | list[str] | None = None
+    to: str | list[str] | None = Field(None, description="Override recipients")
+    cc: str | list[str] | None = None
+    bcc: str | list[str] | None = None
+    reply_all: bool | None = Field(
+        None, description="Reply to all recipients of the original message"
+    )
+    text: str | None = None
+    html: str | None = None
+    attachments: list[SendAttachment] | None = None
+    headers: dict[str, str] | None = None
+
+    model_config = {"extra": "forbid"}
+
+    def get_to_list(self) -> list[str]:
+        """Get 'to' as a list."""
+        if self.to is None:
+            return []
+        return [self.to] if isinstance(self.to, str) else list(self.to)
+
+
+class UpdateMessageRequest(BaseModel):
+    """
+    Request to update message labels.
+
+    Request payload for updating message labels.
+    """
+
+    add_labels: list[str] | None = Field(None, description="Labels to add to message")
+    remove_labels: list[str] | None = Field(None, description="Labels to remove from message")
+
+    model_config = {"extra": "forbid"}
+
+
+# Legacy compatibility models (for existing codebase)
+class MessageBase(BaseModel):
+    """Shared message fields (legacy compatibility)."""
+
+    thread_id: str = Field(..., description="Thread id")
+    inbox_id: str = Field(..., description="Inbox id")
+    provider_message_id: str | None = Field(None, description="Provider Message-ID header")
+    direction: MessageDirection = Field(..., description="Inbound or outbound")
+    content_raw: str = Field("", description="Original HTML/plain text")
+    content_clean: str = Field("", description="LLM-ready Markdown")
+    metadata: dict[str, Any] = Field(
+        default_factory=dict,
+        description="Headers, token counts, sentiment, etc.",
+    )
+
+
+class MessageCreate(BaseModel):
+    """Payload to send a message (outbound via API)."""
+
+    inbox_id: str
+    to: list[str] = Field(..., min_length=1)
+    subject: str = Field(..., min_length=1)
+    body: str = Field(..., description="Markdown body")
+    reply_to_thread_id: str | None = None
+    cc: list[str] | None = None
+    bcc: list[str] | None = None
+    attachments: list[SendAttachment] | None = None
+
+    model_config = {"extra": "forbid"}
+
+
+class MessageInCreate(BaseModel):
+    """Payload to create a message on ingestion (inbound webhook)."""
+
+    thread_id: str = Field(..., description="Thread id")
+    inbox_id: str = Field(..., description="Inbox id")
+    provider_message_id: str | None = Field(None, description="Provider Message-ID header")
+    direction: MessageDirection = Field(..., description="Inbound or outbound")
+    content_raw: str = Field("", description="Original HTML/plain text")
+    content_clean: str = Field("", description="LLM-ready Markdown")
+    metadata: dict[str, Any] = Field(
+        default_factory=dict,
+        description="Headers, token counts, sentiment, etc.",
+    )
+
+    model_config = {"extra": "forbid"}