nornweave 0.1.3__py3-none-any.whl → 0.1.4__py3-none-any.whl

nornweave/yggdrasil/routes/v1/attachments.py

@@ -0,0 +1,317 @@
+"""Attachment endpoints."""
+
+import base64
+import hashlib
+import hmac
+import time
+from datetime import datetime  # noqa: TC003 - needed at runtime for Pydantic
+from enum import Enum
+from typing import Literal
+
+from fastapi import APIRouter, Depends, HTTPException, Query, Response, status
+from pydantic import BaseModel
+
+from nornweave.core.config import Settings, get_settings
+from nornweave.core.interfaces import StorageInterface  # noqa: TC001 - needed at runtime
+from nornweave.core.storage import create_attachment_storage
+from nornweave.yggdrasil.dependencies import get_storage
+
+router = APIRouter()
+
+
+# -----------------------------------------------------------------------------
+# Response Models
+# -----------------------------------------------------------------------------
+class AttachmentMeta(BaseModel):
+    """Lightweight attachment metadata for listings."""
+
+    id: str
+    message_id: str
+    filename: str
+    content_type: str
+    size: int
+    created_at: datetime | None = None
+
+
+class AttachmentDetail(BaseModel):
+    """Full attachment metadata."""
+
+    id: str
+    message_id: str
+    filename: str
+    content_type: str
+    size: int
+    disposition: str | None = None
+    content_id: str | None = None
+    storage_backend: str | None = None
+    content_hash: str | None = None
+    created_at: datetime | None = None
+    download_url: str | None = None
+
+
+class AttachmentListResponse(BaseModel):
+    """Response model for attachment list."""
+
+    items: list[AttachmentMeta]
+    count: int
+
+
+class AttachmentBase64Response(BaseModel):
+    """Response model for base64 attachment content."""
+
+    content: str
+    content_type: str
+    filename: str
+
+
+class ContentFormat(str, Enum):
+    """Content format options."""
+
+    BINARY = "binary"
+    BASE64 = "base64"
+
+
+# -----------------------------------------------------------------------------
+# URL Signing Utilities
+# -----------------------------------------------------------------------------
+def _get_signing_secret(settings: Settings) -> str:
+    """Get the signing secret for URL verification."""
+    return settings.webhook_secret or "default-signing-secret"
+
+
+def _sign_url(attachment_id: str, expiry: int, secret: str) -> str:
+    """Create HMAC signature for URL."""
+    message = f"{attachment_id}:{expiry}"
+    signature = hmac.new(
+        secret.encode(),
+        message.encode(),
+        hashlib.sha256,
+    ).hexdigest()[:32]
+    return signature
+
+
+def _verify_signed_url(
+    attachment_id: str,
+    token: str | None,
+    expires: int | None,
+    secret: str,
+) -> bool:
+    """Verify a signed download URL."""
+    if token is None or expires is None:
+        return True  # No signature required (direct access)
+
+    # Check expiry
+    if expires < time.time():
+        return False
+
+    # Verify signature
+    expected = _sign_url(attachment_id, expires, secret)
+    return hmac.compare_digest(token, expected)
+
+
+# -----------------------------------------------------------------------------
+# Endpoints
+# -----------------------------------------------------------------------------
+@router.get("/attachments", response_model=AttachmentListResponse)
+async def list_attachments(
+    message_id: str | None = Query(None, description="Filter by message ID"),
+    thread_id: str | None = Query(None, description="Filter by thread ID"),
+    inbox_id: str | None = Query(None, description="Filter by inbox ID"),
+    limit: int = Query(100, ge=1, le=500),
+    offset: int = Query(0, ge=0),
+    storage: StorageInterface = Depends(get_storage),
+) -> AttachmentListResponse:
+    """List attachments with exactly one filter (message_id, thread_id, or inbox_id)."""
+    # Validate exactly one filter is provided
+    filters = [f for f in [message_id, thread_id, inbox_id] if f is not None]
+    if len(filters) == 0:
+        raise HTTPException(
+            status_code=status.HTTP_400_BAD_REQUEST,
+            detail="Exactly one filter required: message_id, thread_id, or inbox_id",
+        )
+    if len(filters) > 1:
+        raise HTTPException(
+            status_code=status.HTTP_400_BAD_REQUEST,
+            detail="Only one filter allowed: message_id, thread_id, or inbox_id",
+        )
+
+    # Get attachments based on filter
+    if message_id:
+        # Verify message exists
+        message = await storage.get_message(message_id)
+        if message is None:
+            raise HTTPException(
+                status_code=status.HTTP_404_NOT_FOUND,
+                detail=f"Message {message_id} not found",
+            )
+        attachments = await storage.list_attachments_for_message(message_id)
+    elif thread_id:
+        # Verify thread exists
+        thread = await storage.get_thread(thread_id)
+        if thread is None:
+            raise HTTPException(
+                status_code=status.HTTP_404_NOT_FOUND,
+                detail=f"Thread {thread_id} not found",
+            )
+        attachments = await storage.list_attachments_for_thread(
+            thread_id, limit=limit, offset=offset
+        )
+    else:  # inbox_id
+        # Verify inbox exists
+        assert inbox_id is not None  # Guaranteed by filter logic above
+        inbox = await storage.get_inbox(inbox_id)
+        if inbox is None:
+            raise HTTPException(
+                status_code=status.HTTP_404_NOT_FOUND,
+                detail=f"Inbox {inbox_id} not found",
+            )
+        attachments = await storage.list_attachments_for_inbox(
+            inbox_id,
+            limit=limit,
+            offset=offset,
+        )
+
+    return AttachmentListResponse(
+        items=[
+            AttachmentMeta(
+                id=a["id"],
+                message_id=a["message_id"],
+                filename=a["filename"],
+                content_type=a["content_type"],
+                size=a["size_bytes"],
+                created_at=a.get("created_at"),
+            )
+            for a in attachments
+        ],
+        count=len(attachments),
+    )
+
+
+@router.get("/attachments/{attachment_id}", response_model=AttachmentDetail)
+async def get_attachment(
+    attachment_id: str,
+    storage: StorageInterface = Depends(get_storage),
+    settings: Settings = Depends(get_settings),
+) -> AttachmentDetail:
+    """Get attachment metadata by ID."""
+    attachment = await storage.get_attachment(attachment_id)
+    if attachment is None:
+        raise HTTPException(
+            status_code=status.HTTP_404_NOT_FOUND,
+            detail=f"Attachment {attachment_id} not found",
+        )
+
+    # Generate download URL
+    download_url: str | None = None
+    storage_backend_name = attachment.get("storage_backend")
+
+    if storage_backend_name in ("s3", "gcs") and attachment.get("storage_path"):
+        # Use cloud provider's presigned URL
+        try:
+            storage_backend = create_attachment_storage(settings)
+            download_url = await storage_backend.get_download_url(
+                attachment["storage_path"],
+                filename=attachment["filename"],
+            )
+        except Exception:
+            pass  # Fall back to no download URL
+    elif attachment.get("storage_path") or storage_backend_name == "database":
+        # Generate signed URL for local/database storage
+        expiry = int(time.time() + 3600)  # 1 hour
+        secret = _get_signing_secret(settings)
+        token = _sign_url(attachment_id, expiry, secret)
+        download_url = f"/v1/attachments/{attachment_id}/content?token={token}&expires={expiry}"
+
+    return AttachmentDetail(
+        id=attachment["id"],
+        message_id=attachment["message_id"],
+        filename=attachment["filename"],
+        content_type=attachment["content_type"],
+        size=attachment["size_bytes"],
+        disposition=attachment.get("disposition"),
+        content_id=attachment.get("content_id"),
+        storage_backend=storage_backend_name,
+        content_hash=attachment.get("content_hash"),
+        created_at=attachment.get("created_at"),
+        download_url=download_url,
+    )
+
+
+@router.get("/attachments/{attachment_id}/content", response_model=None)
+async def get_attachment_content(
+    attachment_id: str,
+    response_format: Literal["binary", "base64"] = Query(
+        "binary", alias="format", description="Response format"
+    ),
+    token: str | None = Query(None, description="Signed URL token"),
+    expires: int | None = Query(None, description="Signed URL expiry timestamp"),
+    storage: StorageInterface = Depends(get_storage),
+    settings: Settings = Depends(get_settings),
+) -> Response | AttachmentBase64Response:
+    """Download attachment content.
+
+    For local/database storage, requires valid signed URL (token + expires).
+    For cloud storage (S3/GCS), use the presigned URL from attachment metadata.
+    """
+    # Get attachment metadata
+    attachment = await storage.get_attachment(attachment_id)
+    if attachment is None:
+        raise HTTPException(
+            status_code=status.HTTP_404_NOT_FOUND,
+            detail=f"Attachment {attachment_id} not found",
+        )
+
+    storage_backend_name = attachment.get("storage_backend")
+
+    # Verify signed URL for local/database backends
+    if storage_backend_name in ("local", "database", None):
+        secret = _get_signing_secret(settings)
+        if not _verify_signed_url(attachment_id, token, expires, secret):
+            raise HTTPException(
+                status_code=status.HTTP_401_UNAUTHORIZED,
+                detail="Invalid or expired download URL",
+            )
+
+    # Retrieve content
+    content: bytes
+    if storage_backend_name == "database":
+        # Content stored in database
+        if attachment.get("content") is None:
+            raise HTTPException(
+                status_code=status.HTTP_404_NOT_FOUND,
+                detail="Attachment content not found in database",
+            )
+        content = attachment["content"]
+    elif attachment.get("storage_path"):
+        # Content stored externally
+        try:
+            storage_backend = create_attachment_storage(settings)
+            content = await storage_backend.retrieve(attachment["storage_path"])
+        except FileNotFoundError as exc:
+            raise HTTPException(
+                status_code=status.HTTP_404_NOT_FOUND,
+                detail="Attachment content not found in storage",
+            ) from exc
+    else:
+        raise HTTPException(
+            status_code=status.HTTP_404_NOT_FOUND,
+            detail="Attachment content location unknown",
+        )
+
+    # Return in requested format
+    if response_format == "base64":
+        return AttachmentBase64Response(
+            content=base64.b64encode(content).decode("ascii"),
+            content_type=attachment["content_type"],
+            filename=attachment["filename"],
+        )
+    else:
+        # Binary response
+        return Response(
+            content=content,
+            media_type=attachment["content_type"],
+            headers={
+                "Content-Disposition": f'attachment; filename="{attachment["filename"]}"',
+                "Content-Length": str(len(content)),
+            },
+        )

nornweave/yggdrasil/routes/v1/messages.py

@@ -1,5 +1,7 @@
 """Message endpoints."""
 
+import base64
+import binascii
 import contextlib
 import uuid
 from datetime import UTC, datetime
@@ -8,36 +10,54 @@ from typing import Any
 from fastapi import APIRouter, Depends, HTTPException, status
 from pydantic import BaseModel, Field
 
+from nornweave.core.config import Settings, get_settings
 from nornweave.core.interfaces import (  # noqa: TC001 - needed at runtime for FastAPI
     EmailProvider,
     StorageInterface,
 )
+from nornweave.core.storage import AttachmentMetadata, create_attachment_storage
+from nornweave.models.attachment import AttachmentUpload, SendAttachment
 from nornweave.models.message import Message, MessageDirection
 from nornweave.models.thread import Thread
+from nornweave.verdandi.summarize import generate_thread_summary
 from nornweave.yggdrasil.dependencies import get_email_provider, get_storage
 
 router = APIRouter()
 
 
 class MessageResponse(BaseModel):
-    """Response model for a message."""
+    """Response model for a message with all email metadata fields."""
 
     id: str
     thread_id: str
     inbox_id: str
     direction: str
     provider_message_id: str | None
-    content_raw: str
-    content_clean: str
-    metadata: dict[str, Any]
-    created_at: datetime | None
+    subject: str | None = None
+    from_address: str | None = None
+    to_addresses: list[str] = Field(default_factory=list)
+    cc_addresses: list[str] | None = None
+    bcc_addresses: list[str] | None = None
+    reply_to_addresses: list[str] | None = None
+    text: str | None = None
+    html: str | None = None
+    content_clean: str = ""
+    timestamp: datetime | None = None
+    labels: list[str] = Field(default_factory=list)
+    preview: str | None = None
+    size: int = 0
+    in_reply_to: str | None = None
+    references: list[str] | None = None
+    metadata: dict[str, Any] = Field(default_factory=dict)
+    created_at: datetime | None = None
 
 
 class MessageListResponse(BaseModel):
-    """Response model for message list."""
+    """Response model for message list with pagination support."""
 
     items: list[MessageResponse]
     count: int
+    total: int
 
 
 class SendMessageRequest(BaseModel):
@@ -48,6 +68,9 @@ class SendMessageRequest(BaseModel):
     subject: str = Field(..., min_length=1)
     body: str = Field(..., description="Markdown body content")
     reply_to_thread_id: str | None = None
+    attachments: list[AttachmentUpload] | None = Field(
+        None, description="Optional list of attachments to send"
+    )
 
 
 class SendMessageResponse(BaseModel):
@@ -60,38 +83,78 @@ class SendMessageResponse(BaseModel):
 
 
 def _message_to_response(msg: Message) -> MessageResponse:
-    """Convert Message model to response."""
+    """Convert Message model to response with all email metadata fields."""
     return MessageResponse(
         id=msg.id,
         thread_id=msg.thread_id,
         inbox_id=msg.inbox_id,
         direction=msg.direction.value,
         provider_message_id=msg.provider_message_id,
-        content_raw=msg.content_raw,
-        content_clean=msg.content_clean,
-        metadata=msg.metadata,
+        subject=msg.subject,
+        from_address=msg.from_address,
+        to_addresses=msg.to if msg.to else [],
+        cc_addresses=msg.cc,
+        bcc_addresses=msg.bcc,
+        reply_to_addresses=msg.reply_to,
+        text=msg.text,
+        html=msg.html,
+        content_clean=msg.content_clean or "",
+        timestamp=msg.timestamp,
+        labels=msg.labels if msg.labels else [],
+        preview=msg.preview,
+        size=msg.size,
+        in_reply_to=msg.in_reply_to,
+        references=msg.references,
+        metadata=msg.metadata if msg.metadata else {},
         created_at=msg.created_at,
     )
 
 
 @router.get("/messages", response_model=MessageListResponse)
 async def list_messages(
-    inbox_id: str,
+    inbox_id: str | None = None,
+    thread_id: str | None = None,
+    q: str | None = None,
     limit: int = 50,
     offset: int = 0,
     storage: StorageInterface = Depends(get_storage),
 ) -> MessageListResponse:
-    """List messages for an inbox."""
-    # Verify inbox exists
-    inbox = await storage.get_inbox(inbox_id)
-    if inbox is None:
+    """
+    List and search messages with flexible filters.
+
+    At least one of inbox_id or thread_id must be provided.
+    Optional text search (q) searches across subject, body, sender, and attachment filenames.
+    """
+    # Validate at least one filter is provided
+    if inbox_id is None and thread_id is None:
         raise HTTPException(
-            status_code=status.HTTP_404_NOT_FOUND,
-            detail=f"Inbox {inbox_id} not found",
+            status_code=status.HTTP_422_UNPROCESSABLE_ENTITY,
+            detail="At least one filter (inbox_id or thread_id) is required",
         )
 
-    messages = await storage.list_messages_for_inbox(
-        inbox_id,
+    # Verify inbox exists if provided
+    if inbox_id:
+        inbox = await storage.get_inbox(inbox_id)
+        if inbox is None:
+            raise HTTPException(
+                status_code=status.HTTP_404_NOT_FOUND,
+                detail=f"Inbox {inbox_id} not found",
+            )
+
+    # Verify thread exists if provided
+    if thread_id:
+        thread = await storage.get_thread(thread_id)
+        if thread is None:
+            raise HTTPException(
+                status_code=status.HTTP_404_NOT_FOUND,
+                detail=f"Thread {thread_id} not found",
+            )
+
+    # Use advanced search method with all filters
+    messages, total = await storage.search_messages_advanced(
+        inbox_id=inbox_id,
+        thread_id=thread_id,
+        query=q,
         limit=limit,
         offset=offset,
     )
@@ -99,6 +162,7 @@ async def list_messages(
     return MessageListResponse(
         items=[_message_to_response(m) for m in messages],
         count=len(messages),
+        total=total,
     )
 
 
@@ -122,11 +186,14 @@ async def send_message(
     payload: SendMessageRequest,
     storage: StorageInterface = Depends(get_storage),
     email_provider: EmailProvider = Depends(get_email_provider),
+    settings: Settings = Depends(get_settings),
 ) -> SendMessageResponse:
     """Send an outbound message.
 
     If reply_to_thread_id is provided, the message is added to that thread.
     Otherwise, a new thread is created.
+
+    Supports optional attachments which are stored and sent with the email.
     """
     # Get inbox
     inbox = await storage.get_inbox(payload.inbox_id)
@@ -158,6 +225,80 @@ async def send_message(
         created_thread = await storage.create_thread(new_thread)
         thread_id = created_thread.id
 
+    # Generate message ID early so we can link attachments
+    message_id = str(uuid.uuid4())
+
+    # Process attachments if provided
+    attachment_records: list[dict[str, Any]] = []
+    provider_attachments: list[SendAttachment] = []
+
+    if payload.attachments:
+        # Create storage backend
+        storage_backend = create_attachment_storage(settings)
+
+        for i, attachment in enumerate(payload.attachments):
+            # Validate and decode base64 content
+            try:
+                content_bytes = base64.b64decode(attachment.content_base64)
+            except (binascii.Error, ValueError) as e:
+                raise HTTPException(
+                    status_code=status.HTTP_400_BAD_REQUEST,
+                    detail=f"Invalid base64 content in attachment {i}: {e}",
+                )
+
+            if len(content_bytes) == 0:
+                raise HTTPException(
+                    status_code=status.HTTP_422_UNPROCESSABLE_ENTITY,
+                    detail=f"Attachment {i} has empty content",
+                )
+
+            # Generate attachment ID and store
+            attachment_id = str(uuid.uuid4())
+
+            metadata = AttachmentMetadata(
+                attachment_id=attachment_id,
+                message_id=message_id,
+                filename=attachment.filename,
+                content_type=attachment.content_type,
+                content_disposition=attachment.disposition.value,
+                content_id=attachment.content_id,
+            )
+
+            # Store in configured backend
+            storage_result = await storage_backend.store(
+                attachment_id=attachment_id,
+                content=content_bytes,
+                metadata=metadata,
+            )
+
+            # Prepare attachment record for database
+            attachment_records.append(
+                {
+                    "attachment_id": attachment_id,
+                    "filename": attachment.filename,
+                    "content_type": attachment.content_type,
+                    "size_bytes": storage_result.size_bytes,
+                    "disposition": attachment.disposition.value,
+                    "content_id": attachment.content_id,
+                    "storage_path": storage_result.storage_key,
+                    "storage_backend": storage_result.backend,
+                    "content_hash": storage_result.content_hash,
+                    # For database backend, also store content
+                    "content": content_bytes if storage_result.backend == "database" else None,
+                }
+            )
+
+            # Prepare attachment for email provider
+            provider_attachments.append(
+                SendAttachment(
+                    filename=attachment.filename,
+                    content_type=attachment.content_type,
+                    content_disposition=attachment.disposition,
+                    content_id=attachment.content_id,
+                    content=attachment.content_base64,  # Keep as base64 for provider
+                )
+            )
+
     # Send email via provider
     # Log error but continue to store the message attempt
     provider_message_id: str | None = None
@@ -167,11 +308,12 @@ async def send_message(
             subject=payload.subject,
             body=payload.body,
             from_address=inbox.email_address,
+            attachments=provider_attachments if provider_attachments else None,
         )
 
     # Create message record
     message = Message(
-        message_id=str(uuid.uuid4()),
+        message_id=message_id,
         thread_id=thread_id,
         inbox_id=payload.inbox_id,
         provider_message_id=provider_message_id,
@@ -186,12 +328,30 @@ async def send_message(
     )
     created_message = await storage.create_message(message)
 
+    # Create attachment records linked to the message
+    for rec in attachment_records:
+        await storage.create_attachment(
+            message_id=created_message.id,
+            filename=rec["filename"],
+            content_type=rec["content_type"],
+            size_bytes=rec["size_bytes"],
+            disposition=rec["disposition"],
+            content_id=rec["content_id"],
+            storage_path=rec["storage_path"],
+            storage_backend=rec["storage_backend"],
+            content_hash=rec["content_hash"],
+            content=rec["content"],
+        )
+
     # Update thread's last_message_at
     thread = await storage.get_thread(thread_id)
     if thread:
         thread.last_message_at = created_message.created_at
         await storage.update_thread(thread)
 
+    # Fire-and-forget thread summarization
+    await generate_thread_summary(storage, thread_id)
+
     return SendMessageResponse(
         id=created_message.id,
         thread_id=thread_id,

nornweave/yggdrasil/routes/v1/threads.py

@@ -26,6 +26,7 @@ class ThreadDetailResponse(BaseModel):
 
     id: str
     subject: str
+    summary: str | None = None
     messages: list[ThreadMessageResponse]
 
 
@@ -35,6 +36,7 @@ class ThreadSummaryResponse(BaseModel):
     id: str
     inbox_id: str
     subject: str
+    summary: str | None = None
     last_message_at: datetime | None
     participant_hash: str | None
 
@@ -74,6 +76,7 @@ async def list_threads(
                 id=t.id,
                 inbox_id=t.inbox_id,
                 subject=t.subject,
+                summary=t.summary,
                 last_message_at=t.last_message_at,
                 participant_hash=t.participant_hash,
             )
@@ -138,5 +141,6 @@ async def get_thread(
     return ThreadDetailResponse(
         id=thread.id,
         subject=thread.subject,
+        summary=thread.summary,
         messages=thread_messages,
     )

nornweave/yggdrasil/routes/webhooks/mailgun.py

@@ -13,6 +13,7 @@ from nornweave.core.interfaces import (
 from nornweave.models.message import Message, MessageDirection
 from nornweave.models.thread import Thread
 from nornweave.verdandi.parser import html_to_markdown
+from nornweave.verdandi.summarize import generate_thread_summary
 from nornweave.yggdrasil.dependencies import get_storage
 
 router = APIRouter()
@@ -133,4 +134,7 @@ async def mailgun_webhook(
         thread.received_timestamp = created_message.created_at
         await storage.update_thread(thread)
 
+    # Fire-and-forget thread summarization
+    await generate_thread_summary(storage, thread_id)
+
     return {"status": "received", "message_id": created_message.id, "thread_id": thread_id}