openmail 0.1.5__py3-none-any.whl

openmail/email_query.py

@@ -0,0 +1,279 @@
+from __future__ import annotations
+
+from typing import TYPE_CHECKING, List, Optional, Sequence
+
+from openmail.imap import IMAPQuery, PagedSearchResult
+from openmail.models import EmailMessage, EmailOverview
+from openmail.utils import iso_days_ago
+
+if TYPE_CHECKING:
+    from openmail.email_manager import EmailManager
+
+
+class EmailQuery:
+    """
+    Builder that composes filters and only hits IMAP when you call .search() or .fetch().
+    """
+
+    def __init__(self, manager: Optional[EmailManager], mailbox: str = "INBOX"):
+        self._m = manager
+        self._mailbox = mailbox
+        self._q = IMAPQuery()
+        self._limit: int = 50
+
+    def mailbox(self, mailbox: str) -> EmailQuery:
+        self._mailbox = mailbox
+        return self
+
+    def limit(self, n: int) -> EmailQuery:
+        self._limit = n
+        return self
+
+    @property
+    def query(self) -> IMAPQuery:
+        """
+        The underlying IMAPQuery.
+
+        This is a LIVE object:
+        mutating it will affect this EmailQuery.
+
+        Example:
+            easy = EmailQuery(mgr)
+
+            # mutate existing IMAPQuery
+            easy.query.unseen().from_("alerts@example.com")
+
+            # later:
+            refs = easy.search()
+        """
+        return self._q
+
+    @query.setter
+    def query(self, value: IMAPQuery) -> None:
+        """
+        Replace the underlying IMAPQuery.
+
+        Example:
+            q = IMAPQuery().unseen().subject("invoice")
+            easy.query = q
+        """
+        if not isinstance(value, IMAPQuery):
+            raise TypeError("query must be an IMAPQuery")
+        self._q = value
+
+    def last_days(self, days: int) -> EmailQuery:
+        """Convenience: messages since N days ago (UTC)."""
+        if days < 0:
+            raise ValueError("days must be >= 0")
+        self._q.since(iso_days_ago(days))
+        return self
+
+    def from_any(self, *senders: str) -> EmailQuery:
+        """
+        FROM any of the senders (nested OR). Equivalent to:
+            OR FROM a OR FROM b FROM c ...
+        """
+        qs = [IMAPQuery().from_(s) for s in senders if s]
+        if len(qs) == 0:
+            return self
+        if len(qs) == 1:
+            self._q.parts += qs[0].parts
+            return self
+        self._q.or_(*qs)
+        return self
+
+    def to_any(self, *recipients: str) -> EmailQuery:
+        qs = [IMAPQuery().to(s) for s in recipients if s]
+        if len(qs) == 0:
+            return self
+        if len(qs) == 1:
+            self._q.parts += qs[0].parts
+            return self
+        self._q.or_(*qs)
+        return self
+
+    def subject_any(self, *needles: str) -> EmailQuery:
+        qs = [IMAPQuery().subject(s) for s in needles if s]
+        if len(qs) == 0:
+            return self
+        if len(qs) == 1:
+            self._q.parts += qs[0].parts
+            return self
+        self._q.or_(*qs)
+        return self
+
+    def text_any(self, *needles: str) -> EmailQuery:
+        qs = [IMAPQuery().text(s) for s in needles if s]
+        if len(qs) == 0:
+            return self
+        if len(qs) == 1:
+            self._q.parts += qs[0].parts
+            return self
+        self._q.or_(*qs)
+        return self
+
+    def recent_unread(self, days: int = 7) -> EmailQuery:
+        """UNSEEN AND SINCE (days ago)."""
+        self._q.unseen()
+        return self.last_days(days)
+
+    def inbox_triage(self, days: int = 14) -> EmailQuery:
+        """
+        A very common triage filter:
+        - not deleted
+        - not drafts
+        - recent window
+        - and either unseen OR flagged
+        """
+        triage_or = IMAPQuery().or_(
+            IMAPQuery().unseen(),
+            IMAPQuery().flagged(),
+        )
+        self._q.undeleted().undraft()
+        self.last_days(days)
+        self._q.raw(triage_or.build())
+        return self
+
+    def header_contains(self, name: str, needle: str) -> EmailQuery:
+        if name and needle:
+            self._q.header(name, needle)
+        return self
+
+    def for_thread_root(self, root: EmailMessage) -> EmailQuery:
+        """
+        Narrow this query to messages that look like they belong to the same
+        thread as `root`, based on its Message-ID.
+        """
+        if not root.message_id:
+            return self
+
+        mid = root.message_id
+
+        self._q.or_(
+            IMAPQuery().header("References", mid),
+            IMAPQuery().header("In-Reply-To", mid),
+        )
+        return self
+
+    def thread_like(
+        self, *, subject: Optional[str] = None, participants: Sequence[str] = ()
+    ) -> EmailQuery:
+        """
+        Approximate "thread" matching:
+        - optional SUBJECT contains `subject`
+        - AND (FROM any participants OR TO any participants OR CC any participants)
+        """
+        if subject:
+            self._q.subject(subject)
+
+        p = [x for x in participants if x]
+        if not p:
+            return self
+
+        q_from = [IMAPQuery().from_(x) for x in p]
+        q_to = [IMAPQuery().to(x) for x in p]
+        q_cc = [IMAPQuery().cc(x) for x in p]
+
+        self._q.or_(*(q_from + q_to + q_cc))
+        return self
+
+    def newsletters(self) -> EmailQuery:
+        """
+        Common newsletter identification:
+        - has List-Unsubscribe header
+        """
+        self._q.header("List-Unsubscribe", "")
+        return self
+
+    def from_domain(self, domain: str) -> EmailQuery:
+        """
+        Practical: FROM contains '@domain'.
+        (IMAP has no dedicated "domain" operator.)
+        """
+        if not domain:
+            return self
+        needle = domain if domain.startswith("@") else f"@{domain}"
+        self._q.from_(needle)
+        return self
+
+    def invoices_or_receipts(self) -> EmailQuery:
+        """Common finance mailbox query."""
+        return self.subject_any("invoice", "receipt", "payment", "order confirmation")
+
+    def security_alerts(self) -> EmailQuery:
+        """Common security / auth notifications."""
+        return self.subject_any(
+            "security alert",
+            "new sign-in",
+            "new login",
+            "password",
+            "verification code",
+            "one-time",
+            "2fa",
+        )
+
+    def with_attachments_hint(self) -> EmailQuery:
+        """
+        IMAP SEARCH cannot reliably filter 'has attachment' across servers.
+        """
+        hint = IMAPQuery().or_(
+            IMAPQuery().header("Content-Disposition", "attachment"),
+            IMAPQuery().header("Content-Type", "name="),
+            IMAPQuery().header("Content-Type", "filename="),
+        )
+
+        self._q.raw(hint.build())
+        return self
+
+    def raw(self, *tokens: str) -> EmailQuery:
+        self._q.raw(*tokens)
+        return self
+
+    def search(
+        self,
+        *,
+        before_uid: Optional[int] = None,
+        after_uid: Optional[int] = None,
+        refresh: bool = False,
+    ) -> PagedSearchResult:
+        return self._m.imap.search_page_cached(
+            mailbox=self._mailbox,
+            query=self._q,
+            page_size=self._limit,
+            before_uid=before_uid,
+            after_uid=after_uid,
+            refresh=refresh,
+        )
+
+    def fetch(
+        self,
+        *,
+        before_uid: Optional[int] = None,
+        after_uid: Optional[int] = None,
+        refresh: bool = False,
+        include_attachment_meta: bool = False,
+    ) -> tuple[PagedSearchResult, List[EmailMessage]]:
+        """
+        Fetch a page of full EmailMessage objects plus its paging metadata.
+        """
+        page = self.search(before_uid=before_uid, after_uid=after_uid, refresh=refresh)
+        if not page.refs:
+            return page, []
+        messages = self._m.imap.fetch(page.refs, include_attachment_meta=include_attachment_meta)
+        return page, messages
+
+    def fetch_overview(
+        self,
+        *,
+        before_uid: Optional[int] = None,
+        after_uid: Optional[int] = None,
+        refresh: bool = False,
+    ) -> tuple[PagedSearchResult, List[EmailOverview]]:
+        """
+        Fetch a page of EmailOverview objects plus its paging metadata.
+        """
+        page = self.search(before_uid=before_uid, after_uid=after_uid, refresh=refresh)
+        if not page.refs:
+            return page, []
+        overviews = self._m.imap.fetch_overview(page.refs)
+        return page, overviews

openmail/errors.py

@@ -0,0 +1,16 @@
+class EmailManagerError(Exception): ...
+
+
+class ConfigError(EmailManagerError): ...
+
+
+class AuthError(EmailManagerError): ...
+
+
+class SMTPError(EmailManagerError): ...
+
+
+class IMAPError(EmailManagerError): ...
+
+
+class ParseError(EmailManagerError): ...

openmail/imap/__init__.py

@@ -0,0 +1,5 @@
+from openmail.imap.client import IMAPClient
+from openmail.imap.pagination import PagedSearchResult
+from openmail.imap.query import IMAPQuery
+
+__all__ = ["IMAPQuery", "IMAPClient", "PagedSearchResult"]

openmail/imap/attachment_parts.py

@@ -0,0 +1,55 @@
+# openmail/imap/attachment_parts.py
+from __future__ import annotations
+
+import imaplib
+from email.parser import BytesParser
+from email.policy import default as default_policy
+from typing import Optional
+
+from openmail.errors import IMAPError
+from openmail.imap.parser import decode_transfer
+
+
+def fetch_part_bytes(
+    conn: imaplib.IMAP4,
+    *,
+    uid: int,
+    part: str,
+) -> bytes:
+    """
+    Fetch a single BODY part and decode it according to its MIME headers'
+    Content-Transfer-Encoding.
+
+    This is used for:
+      - downloading attachments
+      - fetching inline CID images for HTML rewriting
+    """
+    typ, mime_data = conn.uid("FETCH", str(uid), f"(UID BODY.PEEK[{part}.MIME])")
+    if typ != "OK" or not mime_data:
+        raise IMAPError(f"FETCH attachment MIME failed uid={uid} part={part}: {mime_data}")
+
+    mime_bytes: Optional[bytes] = None
+    for item in mime_data:
+        if isinstance(item, tuple) and len(item) > 1 and isinstance(item[1], (bytes, bytearray)):
+            mime_bytes = bytes(item[1])
+            break
+
+    cte = None
+    if mime_bytes:
+        msg = BytesParser(policy=default_policy).parsebytes(mime_bytes)
+        cte = msg.get("Content-Transfer-Encoding")
+
+    typ, body_data = conn.uid("FETCH", str(uid), f"(UID BODY.PEEK[{part}])")
+    if typ != "OK" or not body_data:
+        raise IMAPError(f"FETCH attachment failed uid={uid} part={part}: {body_data}")
+
+    payload: Optional[bytes] = None
+    for item in body_data:
+        if isinstance(item, tuple) and len(item) > 1 and isinstance(item[1], (bytes, bytearray)):
+            payload = bytes(item[1])
+            break
+
+    if payload is None:
+        raise IMAPError(f"Attachment payload not found uid={uid} part={part}")
+
+    return decode_transfer(payload, cte)

openmail/imap/bodystructure.py

@@ -0,0 +1,296 @@
+from __future__ import annotations
+
+import re
+from dataclasses import dataclass
+from typing import Any, Dict, List, Optional, Tuple
+
+from openmail.models import AttachmentMeta
+
+BODYSTRUCTURE_RE = re.compile(r"BODYSTRUCTURE\s+(\(.*\))", re.IGNORECASE | re.DOTALL)
+
+
+def _tokenize(s: str) -> List[str]:
+    out: List[str] = []
+    i = 0
+    n = len(s)
+    while i < n:
+        c = s[i]
+        if c.isspace():
+            i += 1
+            continue
+        if c in ("(", ")"):
+            out.append(c)
+            i += 1
+            continue
+        if c == '"':
+            i += 1
+            buf = []
+            while i < n:
+                if s[i] == '"' and s[i - 1] != "\\":
+                    break
+                buf.append(s[i])
+                i += 1
+            out.append("".join(buf))
+            i += 1
+            continue
+
+        j = i
+        while j < n and (not s[j].isspace()) and s[j] not in ("(", ")"):
+            j += 1
+        out.append(s[i:j])
+        i = j
+
+    return out
+
+
+def _parse_tokens(tokens: List[str], idx: int = 0) -> Tuple[Any, int]:
+    if tokens[idx] != "(":
+        return tokens[idx], idx + 1
+
+    idx += 1
+    lst: List[Any] = []
+    while idx < len(tokens) and tokens[idx] != ")":
+        tok = tokens[idx]
+        if tok == "(":
+            node, idx = _parse_tokens(tokens, idx)
+            lst.append(node)
+        else:
+            lst.append(tok)
+            idx += 1
+
+    if idx >= len(tokens) or tokens[idx] != ")":
+        raise ValueError("Unbalanced parentheses in BODYSTRUCTURE")
+
+    idx += 1
+    return lst, idx
+
+
+def parse_bodystructure(bodystructure_str: str) -> Any:
+    tokens = _tokenize(bodystructure_str)
+    tree, _ = _parse_tokens(tokens, 0)
+    return tree
+
+
+@dataclass(frozen=True)
+class TextPartRef:
+    part: str
+    content_type: str
+    charset: Optional[str]
+
+
+def _parse_param_list(x: Any) -> Dict[str, str]:
+    if not isinstance(x, list):
+        return {}
+    out: Dict[str, str] = {}
+    i = 0
+    while i + 1 < len(x):
+        out[str(x[i]).lower()] = str(x[i + 1])
+        i += 2
+    return out
+
+
+def _find_disposition_filename(dispo: Any) -> Optional[str]:
+    if not isinstance(dispo, list) or not dispo:
+        return None
+    params = _parse_param_list(dispo[1]) if len(dispo) > 1 else {}
+    return params.get("filename") or params.get("name")
+
+
+def _leaf_size(node: list) -> int:
+    try:
+        return int(node[6])
+    except Exception:
+        return 0
+
+
+def _leaf_content_type(node: list) -> str:
+    try:
+        return f"{str(node[0]).lower()}/{str(node[1]).lower()}"
+    except Exception:
+        return "application/octet-stream"
+
+
+def _leaf_charset(node: list) -> Optional[str]:
+    params = _parse_param_list(node[2]) if len(node) > 2 else {}
+    return params.get("charset")
+
+
+def _leaf_filename(node: list) -> str:
+    params = _parse_param_list(node[2]) if len(node) > 2 else {}
+    dispo = _leaf_disposition(node)
+    fn = _find_disposition_filename(dispo) or params.get("name")
+    return fn or "attachment"
+
+
+def _leaf_content_id(node: list) -> Optional[str]:
+    """
+    BODYSTRUCTURE body-fld-id is typically at index 3 for leaf parts:
+      ... SP body-fld-id SP body-fld-desc ...
+    Servers often return NIL if absent.
+    """
+    try:
+        cid = node[3]
+        if cid is None:
+            return None
+        cid_str = str(cid)
+        if cid_str.upper() == "NIL":
+            return None
+        cid_str = cid_str.strip().strip("<>").strip()
+        return cid_str or None
+    except Exception:
+        return None
+
+
+def _leaf_content_location(node: list) -> Optional[str]:
+    """
+    Some servers include body-fld-md5 at node[5], but Content-Location is not
+    a standard BODYSTRUCTURE field. However, some servers stash it in
+    "body-ext-1part" params (rare). We try to find it in any param list.
+    If not found, return None.
+    """
+    # Try leaf params (node[2]) first
+    try:
+        params = _parse_param_list(node[2]) if len(node) > 2 else {}
+        # Not standard, but some providers may place it here
+        for k in ("content-location", "content_location", "location"):
+            if k in params:
+                return str(params[k]).strip() or None
+    except Exception:
+        pass
+
+    # Then try disposition params if present
+    dispo = _leaf_disposition(node)
+    if isinstance(dispo, list) and len(dispo) > 1:
+        dparams = _parse_param_list(dispo[1])
+        for k in ("content-location", "content_location", "location"):
+            if k in dparams:
+                return str(dparams[k]).strip() or None
+
+    return None
+
+
+def _leaf_disposition(node: list) -> Optional[list]:
+    """
+    Disposition lives in body-ext-1part and its index differs between
+    text vs non-text leafs. Find it structurally instead.
+    Expected form: ("INLINE" params) or ("ATTACHMENT" params)
+    """
+    if not isinstance(node, list):
+        return None
+    for el in node:
+        if isinstance(el, list) and el:
+            head = str(el[0]).upper()
+            if head in ("INLINE", "ATTACHMENT"):
+                return el
+    return None
+
+
+def _leaf_disposition_kind(node: list) -> Optional[str]:
+    dispo = _leaf_disposition(node)
+    if not (isinstance(dispo, list) and dispo):
+        return None
+    head = str(dispo[0]).strip().lower()
+    if head in ("inline", "attachment"):
+        return head
+    return head or None
+
+
+def _leaf_is_inline_image(node: list) -> bool:
+    ctype = _leaf_content_type(node)
+    if not ctype.startswith("image/"):
+        return False
+    dispo_kind = _leaf_disposition_kind(node) or ""
+    # Many inline images have no filename; CID is the key signal.
+    return bool(_leaf_content_id(node) or dispo_kind == "inline")
+
+
+def _leaf_is_attachment(node: list) -> bool:
+    """
+    "Attachment" for our purposes includes:
+      - traditional attachments (filename/name)
+      - inline images that we must fetch to resolve cid: links
+    """
+    if not isinstance(node, list) or len(node) < 7:
+        return False
+
+    params = _parse_param_list(node[2]) if len(node) > 2 else {}
+    dispo = _leaf_disposition(node)
+    disp_filename = _find_disposition_filename(dispo)
+
+    if disp_filename or ("name" in params):
+        return True
+
+    # Important: include CID inline images as "attachments" so HTML can resolve them.
+    if _leaf_is_inline_image(node):
+        return True
+
+    return False
+
+
+def extract_text_and_attachments(
+    bodystructure: Any,
+) -> Tuple[List[TextPartRef], List[AttachmentMeta]]:
+    text_parts: List[TextPartRef] = []
+    atts: List[AttachmentMeta] = []
+
+    def walk(node: Any, prefix: str) -> None:
+        if isinstance(node, list) and node:
+            # Multipart: consecutive list children, followed by subtype atom(s)
+            if isinstance(node[0], list):
+                child_index = 1
+                for child in node:
+                    if not isinstance(child, list):
+                        break
+                    part_no = f"{prefix}.{child_index}" if prefix else str(child_index)
+                    walk(child, part_no)
+                    child_index += 1
+                return
+
+            # Leaf
+            ctype = _leaf_content_type(node)
+            if ctype in ("text/plain", "text/html"):
+                text_parts.append(
+                    TextPartRef(
+                        part=prefix or "1",
+                        content_type=ctype,
+                        charset=_leaf_charset(node),
+                    )
+                )
+                return
+
+            if _leaf_is_attachment(node):
+                cid = _leaf_content_id(node)
+                dispo_kind = _leaf_disposition_kind(node)  # "inline"/"attachment"/None
+                is_inline = _leaf_is_inline_image(node) or (dispo_kind == "inline")
+
+                atts.append(
+                    AttachmentMeta(
+                        idx=len(atts),
+                        part=prefix or "1",
+                        filename=_leaf_filename(node),
+                        content_type=ctype,
+                        size=_leaf_size(node),
+                        # NEW FIELDS
+                        content_id=cid,
+                        disposition=dispo_kind,
+                        is_inline=is_inline,
+                        content_location=_leaf_content_location(node),
+                    )
+                )
+                return
+
+    walk(bodystructure, "")
+    return text_parts, atts
+
+
+def pick_best_text_parts(
+    parts: List[TextPartRef],
+) -> Tuple[Optional[TextPartRef], Optional[TextPartRef]]:
+    plain = next((p for p in parts if p.content_type == "text/plain"), None)
+    html = next((p for p in parts if p.content_type == "text/html"), None)
+    return plain, html
+
+
+def extract_bodystructure_from_fetch_meta(meta_str: str) -> Optional[str]:
+    m = BODYSTRUCTURE_RE.search(meta_str)
+    return m.group(1) if m else None