chat_message.py

# Represents a single chat message within a Claude conversation, including
# its content blocks, attachments, and file references. Provides parsing
# from the raw JSON dict and timestamp conversion.

from dataclasses import dataclass, field
from datetime import datetime


@dataclass
class ChatMessage:
    """A single message in a Claude conversation.

    Attributes:
        uuid: Unique message identifier.
        text: Plain-text summary of the message.
        sender: Either 'human' or 'assistant'.
        created_at: ISO 8601 creation timestamp.
        updated_at: ISO 8601 last-updated timestamp.
        content: List of content block dicts (text, thinking, tool_use, etc.).
        attachments: List of attachment dicts with optional extracted_content.
        files: List of file reference dicts (filename only).
    """

    uuid: str
    text: str
    sender: str
    created_at: str
    updated_at: str
    content: list[dict] = field(default_factory=list)
    attachments: list[dict] = field(default_factory=list)
    files: list[dict] = field(default_factory=list)

    @classmethod
    def from_dict(cls, data: dict) -> "ChatMessage":
        """Parse a ChatMessage from a raw JSON dict.

        Args:
            data: Dict from the conversations JSON chat_messages array.

        Returns:
            A populated ChatMessage instance.
        """
        return cls(
            uuid=data.get("uuid", ""),
            text=data.get("text", ""),
            sender=data.get("sender", "unknown"),
            created_at=data.get("created_at", ""),
            updated_at=data.get("updated_at", ""),
            content=data.get("content", []),
            attachments=data.get("attachments", []),
            files=data.get("files", []),
        )

    def created_datetime(self) -> datetime | None:
        """Return the created_at timestamp as a datetime, or None if missing."""
        if not self.created_at:
            return None
        return datetime.fromisoformat(self.created_at)