openmail 0.1.5__py3-none-any.whl

openmail/subscription/parser.py

@@ -0,0 +1,32 @@
+from __future__ import annotations
+
+import re
+from typing import List
+
+from openmail.models import UnsubscribeMethod
+
+_LIST_UNSUB_RE = re.compile(r"<\s*([^>]+?)\s*>")
+
+
+def parse_list_unsubscribe(value: str) -> List[UnsubscribeMethod]:
+    """
+    Parses:
+      <mailto:unsubscribe@x.com>, <https://x.com/unsub>
+    """
+    if not value:
+        return []
+
+    methods: List[UnsubscribeMethod] = []
+
+    for item in _LIST_UNSUB_RE.findall(value):
+        item = item.strip()
+
+        if item.lower().startswith("mailto:"):
+            addr = item[len("mailto:") :].split("?", 1)[0].strip()
+            if addr:
+                methods.append(UnsubscribeMethod("mailto", addr))
+
+        elif item.lower().startswith(("http://", "https://")):
+            methods.append(UnsubscribeMethod("http", item))
+
+    return methods

openmail/subscription/service.py

@@ -0,0 +1,237 @@
+from email.message import EmailMessage as PyEmailMessage
+from typing import Dict, List, Optional
+from urllib.parse import urljoin
+
+import requests
+from bs4 import BeautifulSoup
+
+from openmail.models import (
+    UnsubscribeActionResult,
+    UnsubscribeCandidate,
+    UnsubscribeMethod,
+)
+from openmail.smtp import SMTPClient
+from openmail.types import SendResult
+
+
+def _http_unsubscribe_flow(url: str, timeout: int = 10) -> tuple[bool, str]:
+    """
+    Best-effort HTTP unsubscribe:
+
+    1. GET the URL
+    2. If HTML, try to:
+       - find and submit an 'unsubscribe' / 'opt out' form
+       - otherwise, follow an 'unsubscribe' / 'opt out' link/button
+    3. Fall back to treating the initial GET as the unsubscribe action.
+    """
+    session = requests.Session()
+
+    r = session.get(url, timeout=timeout, allow_redirects=True)
+    status = r.status_code
+
+    content_type = r.headers.get("Content-Type", "")
+    if "html" not in content_type.lower():
+        ok = 200 <= status < 300
+        return ok, f"GET {r.url} -> HTTP {status} (non-HTML content)"
+
+    soup = BeautifulSoup(r.text, "html.parser")
+
+    def _is_unsub_text(s: str) -> bool:
+        s = s.lower()
+        return "unsubscribe" in s or "opt out" in s or "opt-out" in s or "optout" in s
+
+    unsub_form = None
+    for form in soup.find_all("form"):
+        text_parts = [
+            form.get("id", ""),
+            form.get("name", ""),
+            form.get("action", ""),
+            form.get_text(" ", strip=True),
+        ]
+        combined = " ".join(text_parts)
+        if _is_unsub_text(combined):
+            unsub_form = form
+            break
+
+    if unsub_form is not None:
+        action_attr = unsub_form.get("action") or ""
+        action_url = urljoin(r.url, action_attr) if action_attr else r.url
+        method = (unsub_form.get("method") or "post").lower()
+
+        data: dict[str, str] = {}
+        for inp in unsub_form.find_all("input"):
+            name = inp.get("name")
+            if not name:
+                continue
+
+            itype = (inp.get("type") or "text").lower()
+            value = inp.get("value", "")
+
+            if itype in ("checkbox", "radio"):
+                # Only send checked ones
+                if inp.has_attr("checked"):
+                    data[name] = value or "on"
+            else:
+                data[name] = value
+
+        for sel in unsub_form.find_all("select"):
+            name = sel.get("name")
+            if not name:
+                continue
+            selected = sel.find("option", selected=True) or sel.find("option")
+            if selected and selected.get("value") is not None:
+                data[name] = selected.get("value")
+
+        if method == "post":
+            r2 = session.post(action_url, data=data, timeout=timeout)
+        else:
+            r2 = session.get(action_url, params=data, timeout=timeout)
+
+        soup2 = BeautifulSoup(r2.text, "html.parser")
+        text = soup2.get_text(" ", strip=True)
+        text = " ".join(text.split())
+
+        ok = 200 <= r2.status_code < 300
+        detail = (
+            f"{method.upper()} {action_url} -> HTTP {r2.status_code} "
+            f"(submitted unsubscribe form). "
+            f"Final confirmation page body: \n {text[:2000]}"
+        )
+        return ok, detail
+
+    unsub_link = None
+    for tag in soup.find_all(["a", "button"]):
+        text = tag.get_text(" ", strip=True) or ""
+        if _is_unsub_text(text):
+            unsub_link = tag
+            break
+
+    if unsub_link is not None and unsub_link.name == "a":
+        href = unsub_link.get("href")
+        if href:
+            click_url = urljoin(r.url, href)
+            r2 = session.get(click_url, timeout=timeout, allow_redirects=True)
+            ok = 200 <= r2.status_code < 300
+            detail = f"GET {click_url} -> HTTP {r2.status_code} (clicked unsubscribe link)"
+            return ok, detail
+
+    ok = 200 <= status < 300
+    return ok, f"GET {r.url} -> HTTP {status} (no explicit form/link found)"
+
+
+class SubscriptionService:
+    def __init__(self, smtp: SMTPClient):
+        self.smtp = smtp
+
+    def unsubscribe(
+        self,
+        candidates: List[UnsubscribeCandidate],
+        *,
+        prefer: str = "mailto",
+        from_addr: Optional[str] = None,
+    ) -> Dict[str, List[UnsubscribeActionResult]]:
+        """
+        Executes unsubscribe actions.
+
+        Behavior:
+        - mailto: Sends an email to the unsubscribe address.
+        - http: Performs an HTTP GET request to the unsubscribe URL.
+        """
+        results: Dict[str, List[UnsubscribeActionResult]] = {
+            "sent": [],
+            "http": [],
+            "skipped": [],
+        }
+
+        for cand in candidates:
+            method = _choose_method(cand.methods, prefer)
+            if not method:
+                results["skipped"].append(
+                    UnsubscribeActionResult(
+                        ref=cand.ref,
+                        method=None,
+                        sent=False,
+                        note="No supported unsubscribe method",
+                    )
+                )
+                continue
+
+            if method.kind == "mailto":
+                msg = PyEmailMessage()
+                msg["To"] = method.value
+                msg["Subject"] = "Unsubscribe"
+                if from_addr:
+                    msg["From"] = from_addr
+                msg.set_content("Please unsubscribe me.")
+
+                try:
+                    send_res = self.smtp.send(msg, [method.value])
+                except Exception as exc:
+                    send_res = SendResult(ok=False, detail=f"error: {exc!r}")
+
+                results["sent"].append(
+                    UnsubscribeActionResult(
+                        ref=cand.ref,
+                        method=method,
+                        sent=True,
+                        send_result=send_res,
+                    )
+                )
+
+            elif method.kind == "http":
+                url = method.value
+                try:
+                    ok, detail = _http_unsubscribe_flow(url)
+                    send_result = SendResult(
+                        ok=ok,
+                        detail=detail,
+                    )
+                    results["http"].append(
+                        UnsubscribeActionResult(
+                            ref=cand.ref,
+                            method=method,
+                            sent=ok,
+                            send_result=send_result,
+                        )
+                    )
+                except Exception as e:
+                    results["http"].append(
+                        UnsubscribeActionResult(
+                            ref=cand.ref,
+                            method=method,
+                            sent=False,
+                            send_result=SendResult(ok=False, detail=str(e)),
+                            note="HTTP request failed",
+                        )
+                    )
+
+            else:
+                results["skipped"].append(
+                    UnsubscribeActionResult(
+                        ref=cand.ref,
+                        method=method,
+                        sent=False,
+                        note=f"Unsupported method kind: {method.kind}",
+                    )
+                )
+
+        return results
+
+
+def _choose_method(methods: List[UnsubscribeMethod], prefer: str) -> Optional[UnsubscribeMethod]:
+    prefer = prefer.lower()
+    if prefer == "mailto":
+        for m in methods:
+            if m.kind == "mailto":
+                return m
+        for m in methods:
+            if m.kind == "http":
+                return m
+    elif prefer == "http":
+        for m in methods:
+            if m.kind == "http":
+                return m
+        for m in methods:
+            if m.kind == "mailto":
+                return m
+    return methods[0] if methods else None

openmail/types.py

@@ -0,0 +1,30 @@
+from __future__ import annotations
+
+from dataclasses import dataclass
+from typing import Optional
+
+
+@dataclass(frozen=True)
+class EmailRef:
+    uid: int
+    mailbox: str = "INBOX"
+
+    def to_dict(self) -> dict:
+        return {
+            "uid": self.uid,
+            "mailbox": self.mailbox,
+        }
+
+
+@dataclass(frozen=True)
+class SendResult:
+    ok: bool
+    message_id: Optional[str] = None
+    detail: Optional[str] = None
+
+    def to_dict(self) -> dict:
+        return {
+            "ok": self.ok,
+            "message_id": self.message_id,
+            "detail": self.detail,
+        }

openmail/utils/__init__.py

@@ -0,0 +1,39 @@
+from openmail.utils.utils import (
+    best_effort_date,
+    build_email_context,
+    build_references,
+    dedup_addrs,
+    ensure_forward_subject,
+    ensure_reply_subject,
+    get_header,
+    iso_days_ago,
+    looks_binary,
+    parse_addrs,
+    parse_list_mailbox_name,
+    quote_forward_html,
+    quote_forward_text,
+    quote_original_reply_html,
+    quote_original_reply_text,
+    remove_addr,
+    safe_decode,
+)
+
+__all__ = [
+    "iso_days_ago",
+    "ensure_forward_subject",
+    "ensure_reply_subject",
+    "parse_addrs",
+    "dedup_addrs",
+    "remove_addr",
+    "get_header",
+    "build_references",
+    "build_email_context",
+    "quote_original_reply_text",
+    "quote_original_reply_html",
+    "quote_forward_text",
+    "quote_forward_html",
+    "parse_list_mailbox_name",
+    "safe_decode",
+    "looks_binary",
+    "best_effort_date",
+]

openmail/utils/utils.py

@@ -0,0 +1,295 @@
+import html as _html
+import re
+from datetime import datetime, timedelta, timezone
+from email.utils import formataddr, getaddresses, parsedate_to_datetime
+from typing import Dict, List, Optional
+
+from openmail.models import EmailMessage
+
+
+def iso_days_ago(days: int) -> str:
+    return (datetime.now(timezone.utc) - timedelta(days=days)).date().isoformat()
+
+
+def ensure_forward_subject(subject: str) -> str:
+    """
+    Ensure the subject is prefixed with 'Fwd:' (or 'Fw:') exactly once.
+    """
+    if not subject:
+        return "Fwd:"
+    lower = subject.lower()
+    if lower.startswith("fwd:") or lower.startswith("fw:"):
+        return subject
+    return f"Fwd: {subject}"
+
+
+def ensure_reply_subject(subj: Optional[str]) -> str:
+    if not subj:
+        return "Re:"
+    s = subj.strip()
+    if s.lower().startswith("re:"):
+        return subj
+    return f"Re: {subj}"
+
+
+def parse_addrs(*values: Optional[str]) -> List[tuple[str, str]]:
+    out: List[tuple[str, str]] = []
+    for v in values:
+        if v:
+            out.extend(getaddresses([v]))
+    return out
+
+
+def dedup_addrs(pairs: List[tuple[str, str]]) -> List[str]:
+    seen: set[str] = set()
+    result: List[str] = []
+    for name, addr in pairs:
+        addr_norm = addr.strip().lower()
+        if not addr_norm or addr_norm in seen:
+            continue
+        seen.add(addr_norm)
+        result.append(formataddr((name, addr)) if name else addr)
+    return result
+
+
+def remove_addr(pairs: List[tuple[str, str]], remove: Optional[str]) -> List[tuple[str, str]]:
+    if not remove:
+        return pairs
+    rm_norm = remove.strip().lower()
+    return [(n, a) for (n, a) in pairs if a.strip().lower() != rm_norm]
+
+
+def get_header(headers: Dict[str, str], key: str) -> Optional[str]:
+    """Case-insensitive header lookup from EmailMessage.headers."""
+    key_lower = key.lower()
+    for k, v in headers.items():
+        if k.lower() == key_lower:
+            return v
+    return None
+
+
+def build_references(existing_refs: Optional[str], orig_mid: str) -> str:
+    if not existing_refs:
+        return orig_mid
+    if orig_mid in existing_refs:
+        return existing_refs
+    return f"{existing_refs} {orig_mid}"
+
+
+def build_email_context(msg: EmailMessage) -> str:
+    """
+    Build a text block representing one email for prompts.
+    """
+    subject = msg.subject
+    from_addr = msg.from_email
+    date = msg.received_at
+    body = msg.text
+
+    date_part = f"Date: {date}\n" if date else ""
+
+    return f"From: {from_addr}\n" f"Subject: {subject}\n" f"{date_part}" f"Body:\n{body}\n"
+
+
+def quote_original_reply_text(original: EmailMessage) -> str:
+    """
+    Build a plain-text quoted block of the original email, e.g.:
+
+    On 2026-01-12T10:00:00+00:00, alice@example.com wrote:
+    > line 1
+    > line 2
+    """
+    if original.received_at:
+        date_str = original.received_at.isoformat()
+    else:
+        date_str = "an earlier date"
+
+    header = f"On {date_str}, {original.from_email} wrote:"
+
+    # Body to quote
+    body = original.text or ""
+    if not body and original.html:
+        body = "[original HTML body omitted]"
+
+    quoted_body_lines = [f"> {line}" for line in body.splitlines()] if body else []
+    return "\n".join([header, *quoted_body_lines])
+
+
+def quote_original_reply_html(original: EmailMessage) -> str:
+    """
+    Build an HTML quoted block of the original email.
+
+    Uses <blockquote> for the body, and a short 'On ..., X wrote:' header.
+    """
+    if original.received_at:
+        date_str = original.received_at.isoformat()
+    else:
+        date_str = "an earlier date"
+
+    header_html = f"On {_html.escape(date_str)}, " f"{_html.escape(original.from_email)} wrote:"
+
+    if original.html:
+        body_html = f"<blockquote>{original.html}</blockquote>"
+    elif original.text:
+        body_html = "<blockquote><pre>" + _html.escape(original.text) + "</pre></blockquote>"
+    else:
+        body_html = "<blockquote><em>(no body)</em></blockquote>"
+
+    return f"<p>{header_html}</p>\n{body_html}"
+
+
+def quote_forward_text(original: EmailMessage) -> str:
+    """
+    Build the quoted plain text block for a forwarded message.
+    """
+    quoted_lines: List[str] = []
+    quoted_lines.append("")
+    quoted_lines.append("---- Forwarded message ----")
+    quoted_lines.append(f"From: {original.from_email}")
+    if original.to:
+        quoted_lines.append(f"To: {', '.join(original.to)}")
+    if original.cc:
+        quoted_lines.append(f"Cc: {', '.join(original.cc)}")
+    if original.received_at:
+        quoted_lines.append(f"Date: {original.received_at.isoformat()}")
+    if original.subject:
+        quoted_lines.append(f"Subject: {original.subject}")
+    quoted_lines.append("")
+    if original.text:
+        quoted_lines.append(original.text)
+
+    return "\n".join(quoted_lines)
+
+
+def quote_forward_html(original: EmailMessage) -> Optional[str]:
+    """
+    Build the quoted HTML block for a forwarded message.
+    """
+
+    if not (original.html or original.text):
+        return None
+
+    html_parts: List[str] = []
+
+    html_parts.append("<hr>")
+    html_parts.append("<p>---- Forwarded message ----</p>")
+
+    header_lines: List[str] = []
+    header_lines.append(f"From: {original.from_email}")
+    if original.to:
+        header_lines.append(f"To: {', '.join(original.to)}")
+    if original.cc:
+        header_lines.append(f"Cc: {', '.join(original.cc)}")
+    if original.received_at:
+        header_lines.append(f"Date: {original.received_at.isoformat()}")
+    if original.subject:
+        header_lines.append(f"Subject: {original.subject}")
+
+    header_html = "<br>".join(_html.escape(line) for line in header_lines)
+    html_parts.append(f"<p>{header_html}</p>")
+
+    if original.html:
+        html_parts.append(original.html)
+    else:
+        html_parts.append("<pre>" + _html.escape(original.text or "") + "</pre>")
+
+    return "\n".join(html_parts)
+
+
+def parse_list_mailbox_name(raw: bytes | str) -> str | None:
+    """
+    Parse a single IMAP LIST response line and extract the mailbox name.
+    Handles typical formats like:
+        (\\HasNoChildren) "/" "INBOX"
+        (\\Noselect) "/" "[Gmail]/All Mail"
+        (\\HasNoChildren) "/" INBOX
+    Returns the decoded mailbox name or None if it can't be parsed.
+    """
+    if isinstance(raw, bytes):
+        s = raw.decode(errors="ignore")
+    else:
+        s = str(raw)
+
+    s = s.strip()
+
+    m = re.match(r'\((?P<flags>.*?)\)\s+(?P<delim>NIL|".*?"|\S+)\s+(?P<name>.+)', s)
+    if not m:
+        return None
+
+    name = m.group("name").strip()
+
+    if name.startswith('"') and name.endswith('"'):
+        name = name[1:-1]
+
+    try:
+        from imaplib import _decode_utf7 as decode_utf7  # type: ignore[attr-defined]
+
+        name = decode_utf7(name)
+    except Exception:
+        pass
+
+    return name or None
+
+
+def safe_decode(data: bytes) -> Optional[str]:
+    """
+    Try UTF-8 decode, fallback to latin-1.
+    Returns decoded string or None if decoding fails.
+    """
+    if not data:
+        return ""
+    try:
+        return data.decode("utf-8")
+    except UnicodeDecodeError:
+        try:
+            return data.decode("latin-1")
+        except Exception:
+            return None
+
+
+def looks_binary(text: str) -> bool:
+    """
+    Heuristic to detect binary-like decoded content.
+    If >30% of characters are control chars or weird unicode blocks.
+    """
+    if not text:
+        return False
+    control_chars = sum(ch < " " for ch in text)
+    return (control_chars / len(text)) > 0.3
+
+
+def best_effort_date(date_header: str | None, internaldate_raw: str | None) -> datetime | None:
+    """
+    Pick the best possible date for an email, trying:
+    1. Header Date
+    2. IMAP INTERNALDATE
+    """
+
+    def _parse_one(raw: str | None) -> datetime | None:
+        if not raw:
+            return None
+        try:
+            dt = parsedate_to_datetime(raw)
+            if dt is None:
+                return None
+            if dt.tzinfo is None:
+                dt = dt.replace(tzinfo=timezone.utc)
+            else:
+                dt = dt.astimezone(timezone.utc)
+            return dt
+        except (TypeError, ValueError, OverflowError):
+            return None
+
+    header_dt = _parse_one(date_header)
+    internal_dt = _parse_one(internaldate_raw)
+
+    # Prefer header date if it looks sane
+    if header_dt is not None:
+        earliest = datetime(1970, 1, 1, tzinfo=timezone.utc)
+        latest = datetime.now(timezone.utc) + timedelta(days=1)
+        if earliest <= header_dt <= latest:
+            return header_dt
+
+    if internal_dt is not None:
+        return internal_dt
+
+    return None