gsuite-sdk 0.1.0__py3-none-any.whl

gsuite_gmail/parser.py

@@ -0,0 +1,155 @@
+"""Gmail response parsers - converts API responses to domain entities."""
+
+import base64
+from datetime import datetime
+from email.utils import parsedate_to_datetime
+
+from gsuite_gmail.label import Label, LabelType
+from gsuite_gmail.message import Attachment, Message
+
+
+class GmailParser:
+    """Parser for Gmail API responses."""
+
+    @staticmethod
+    def parse_message(
+        data: dict,
+        include_body: bool = True,
+    ) -> Message:
+        """
+        Parse Gmail API response to Message entity.
+
+        Args:
+            data: Raw API response dict
+            include_body: Whether to parse body content
+
+        Returns:
+            Message entity
+        """
+        payload = data.get("payload", {})
+        headers = payload.get("headers", [])
+
+        def get_header(name: str) -> str:
+            for h in headers:
+                if h.get("name", "").lower() == name.lower():
+                    return h.get("value", "")
+            return ""
+
+        # Parse date
+        date = GmailParser._parse_date(get_header("Date"), data.get("internalDate"))
+
+        # Parse body and attachments
+        plain, html, attachments = None, None, []
+        if include_body:
+            plain, html, attachments = GmailParser._parse_payload(payload, data["id"])
+
+        return Message(
+            id=data["id"],
+            thread_id=data.get("threadId", data["id"]),
+            subject=get_header("Subject"),
+            sender=get_header("From"),
+            recipient=get_header("To"),
+            cc=[addr.strip() for addr in get_header("Cc").split(",") if addr.strip()],
+            date=date,
+            snippet=data.get("snippet", ""),
+            plain=plain,
+            html=html,
+            labels=data.get("labelIds", []),
+            attachments=attachments,
+        )
+
+    @staticmethod
+    def parse_label(data: dict) -> Label:
+        """
+        Parse Gmail API response to Label entity.
+
+        Args:
+            data: Raw API response dict
+
+        Returns:
+            Label entity
+        """
+        return Label(
+            id=data["id"],
+            name=data.get("name", data["id"]),
+            type=LabelType.SYSTEM if data.get("type") == "system" else LabelType.USER,
+            messages_total=data.get("messagesTotal", 0),
+            messages_unread=data.get("messagesUnread", 0),
+            threads_total=data.get("threadsTotal", 0),
+            threads_unread=data.get("threadsUnread", 0),
+        )
+
+    @staticmethod
+    def _parse_date(date_header: str, internal_date: str | None) -> datetime | None:
+        """Parse date from header or internal timestamp."""
+        if date_header:
+            try:
+                return parsedate_to_datetime(date_header)
+            except (ValueError, TypeError):
+                pass
+
+        if internal_date:
+            try:
+                return datetime.fromtimestamp(int(internal_date) / 1000)
+            except (ValueError, TypeError):
+                pass
+
+        return None
+
+    @staticmethod
+    def _parse_payload(
+        payload: dict,
+        message_id: str,
+    ) -> tuple[str | None, str | None, list[Attachment]]:
+        """
+        Parse message payload for body content and attachments.
+
+        Args:
+            payload: Message payload dict
+            message_id: Parent message ID
+
+        Returns:
+            Tuple of (plain_text, html, attachments)
+        """
+        plain = None
+        html = None
+        attachments = []
+
+        def extract_parts(part: dict) -> None:
+            nonlocal plain, html
+
+            mime_type = part.get("mimeType", "")
+            body = part.get("body", {})
+            data = body.get("data")
+
+            # Text content
+            if data:
+                try:
+                    decoded = base64.urlsafe_b64decode(data).decode("utf-8", errors="replace")
+                    if mime_type == "text/plain" and not plain:
+                        plain = decoded
+                    elif mime_type == "text/html" and not html:
+                        html = decoded
+                except Exception:
+                    pass
+
+            # Attachments
+            filename = part.get("filename")
+            attachment_id = body.get("attachmentId")
+            if filename and attachment_id:
+                attachments.append(
+                    Attachment(
+                        id=attachment_id,
+                        filename=filename,
+                        mime_type=mime_type,
+                        size=body.get("size", 0),
+                        _message_id=message_id,
+                    )
+                )
+
+            # Recurse into nested parts
+            for sub_part in part.get("parts", []):
+                extract_parts(sub_part)
+
+        extract_parts(payload)
+        return plain, html, attachments

gsuite_gmail/query.py

@@ -0,0 +1,227 @@
+"""Gmail query builder for intuitive searches."""
+
+from dataclasses import dataclass
+
+
+@dataclass
+class Query:
+    """
+    Gmail search query builder.
+
+    Supports combining queries with & (AND) and | (OR).
+
+    Example:
+        q = newer_than(days=7) & has_attachment() & from_("boss@company.com")
+        messages = gmail.search(q)
+    """
+
+    _query: str
+
+    def __str__(self) -> str:
+        return self._query
+
+    def __and__(self, other: "Query") -> "Query":
+        """Combine with AND."""
+        return Query(f"{self._query} {other._query}")
+
+    def __or__(self, other: "Query") -> "Query":
+        """Combine with OR."""
+        return Query(f"({self._query}) OR ({other._query})")
+
+    def __invert__(self) -> "Query":
+        """Negate query."""
+        return Query(f"-({self._query})")
+
+
+def from_(address: str) -> Query:
+    """Messages from a specific sender."""
+    return Query(f"from:{address}")
+
+
+def to(address: str) -> Query:
+    """Messages to a specific recipient."""
+    return Query(f"to:{address}")
+
+
+def subject(text: str) -> Query:
+    """Messages with subject containing text."""
+    if " " in text:
+        return Query(f'subject:"{text}"')
+    return Query(f"subject:{text}")
+
+
+def has_words(words: str) -> Query:
+    """Messages containing specific words."""
+    return Query(words)
+
+
+def has_attachment() -> Query:
+    """Messages with attachments."""
+    return Query("has:attachment")
+
+
+def is_unread() -> Query:
+    """Unread messages."""
+    return Query("is:unread")
+
+
+def is_read() -> Query:
+    """Read messages."""
+    return Query("is:read")
+
+
+def is_starred() -> Query:
+    """Starred messages."""
+    return Query("is:starred")
+
+
+def is_important() -> Query:
+    """Important messages."""
+    return Query("is:important")
+
+
+def in_inbox() -> Query:
+    """Messages in inbox."""
+    return Query("in:inbox")
+
+
+def in_sent() -> Query:
+    """Sent messages."""
+    return Query("in:sent")
+
+
+def in_drafts() -> Query:
+    """Draft messages."""
+    return Query("in:drafts")
+
+
+def in_trash() -> Query:
+    """Trashed messages."""
+    return Query("in:trash")
+
+
+def in_spam() -> Query:
+    """Spam messages."""
+    return Query("in:spam")
+
+
+def label(name: str) -> Query:
+    """Messages with a specific label."""
+    if " " in name:
+        return Query(f'label:"{name}"')
+    return Query(f"label:{name}")
+
+
+def newer_than(days: int | None = None, months: int | None = None) -> Query:
+    """Messages newer than a time period."""
+    if days:
+        return Query(f"newer_than:{days}d")
+    if months:
+        return Query(f"newer_than:{months}m")
+    raise ValueError("Specify days or months")
+
+
+def older_than(days: int | None = None, months: int | None = None) -> Query:
+    """Messages older than a time period."""
+    if days:
+        return Query(f"older_than:{days}d")
+    if months:
+        return Query(f"older_than:{months}m")
+    raise ValueError("Specify days or months")
+
+
+def after(date: str) -> Query:
+    """Messages after a date (YYYY/MM/DD)."""
+    return Query(f"after:{date}")
+
+
+def before(date: str) -> Query:
+    """Messages before a date (YYYY/MM/DD)."""
+    return Query(f"before:{date}")
+
+
+def filename(name: str) -> Query:
+    """Messages with attachment matching filename."""
+    return Query(f"filename:{name}")
+
+
+def size_larger(bytes: int) -> Query:
+    """Messages larger than size in bytes."""
+    return Query(f"larger:{bytes}")
+
+
+def size_smaller(bytes: int) -> Query:
+    """Messages smaller than size in bytes."""
+    return Query(f"smaller:{bytes}")
+
+
+def category(name: str) -> Query:
+    """Messages in a category (primary, social, promotions, updates, forums)."""
+    return Query(f"category:{name}")
+
+
+def raw(query_string: str) -> Query:
+    """Raw Gmail query string."""
+    return Query(query_string)
+
+
+# Convenience function to build query from dict (like simplegmail)
+def construct_query(
+    from_: str | None = None,
+    to: str | None = None,
+    subject: str | None = None,
+    unread: bool | None = None,
+    starred: bool | None = None,
+    newer_than: tuple[int, str] | None = None,  # (2, "day")
+    older_than: tuple[int, str] | None = None,
+    labels: list[str] | None = None,
+    has_attachment: bool | None = None,
+    exclude_starred: bool | None = None,
+) -> Query:
+    """
+    Build query from parameters.
+
+    Args:
+        from_: Sender email
+        to: Recipient email
+        subject: Subject contains
+        unread: True for unread only
+        starred: True for starred only
+        newer_than: Tuple of (amount, unit) e.g., (2, "day")
+        older_than: Tuple of (amount, unit)
+        labels: List of label names
+        has_attachment: True for messages with attachments
+        exclude_starred: True to exclude starred
+
+    Returns:
+        Query object
+    """
+    parts = []
+
+    if from_:
+        parts.append(f"from:{from_}")
+    if to:
+        parts.append(f"to:{to}")
+    if subject:
+        parts.append(f'subject:"{subject}"' if " " in subject else f"subject:{subject}")
+    if unread:
+        parts.append("is:unread")
+    if starred:
+        parts.append("is:starred")
+    if exclude_starred:
+        parts.append("-is:starred")
+    if newer_than:
+        amount, unit = newer_than
+        unit_map = {"day": "d", "days": "d", "d": "d", "month": "m", "months": "m", "m": "m"}
+        parts.append(f"newer_than:{amount}{unit_map.get(unit, unit)}")
+    if older_than:
+        amount, unit = older_than
+        unit_map = {"day": "d", "days": "d", "d": "d", "month": "m", "months": "m", "m": "m"}
+        parts.append(f"older_than:{amount}{unit_map.get(unit, unit)}")
+    if labels:
+        for lbl in labels:
+            parts.append(f'label:"{lbl}"' if " " in lbl else f"label:{lbl}")
+    if has_attachment:
+        parts.append("has:attachment")
+
+    return Query(" ".join(parts))

gsuite_gmail/thread.py

@@ -0,0 +1,54 @@
+"""Gmail Thread entity."""
+
+from dataclasses import dataclass, field
+from typing import TYPE_CHECKING
+
+if TYPE_CHECKING:
+    from gsuite_gmail.message import Message
+
+
+@dataclass
+class Thread:
+    """
+    Gmail thread (conversation).
+
+    A thread is a collection of related messages.
+    """
+
+    id: str
+    messages: list["Message"] = field(default_factory=list)
+    snippet: str = ""
+
+    @property
+    def subject(self) -> str:
+        """Get thread subject from first message."""
+        if self.messages:
+            return self.messages[0].subject
+        return ""
+
+    @property
+    def message_count(self) -> int:
+        """Get number of messages in thread."""
+        return len(self.messages)
+
+    @property
+    def participants(self) -> set[str]:
+        """Get all unique email addresses in thread."""
+        emails = set()
+        for msg in self.messages:
+            emails.add(msg.sender)
+            emails.add(msg.recipient)
+        return emails
+
+    @property
+    def has_unread(self) -> bool:
+        """Check if thread has any unread messages."""
+        return any(msg.is_unread for msg in self.messages)
+
+    @property
+    def labels(self) -> set[str]:
+        """Get all unique labels from all messages."""
+        all_labels = set()
+        for msg in self.messages:
+            all_labels.update(msg.labels)
+        return all_labels