openmail 0.1.5__py3-none-any.whl

openmail/models/attachment.py

@@ -0,0 +1,128 @@
+from __future__ import annotations
+
+from dataclasses import dataclass
+from typing import Optional
+
+
+def _normalize_content_id(cid: Optional[str]) -> Optional[str]:
+    if not cid:
+        return None
+    c = cid.strip()
+    # handle "<...>"
+    if c.startswith("<") and c.endswith(">") and len(c) >= 2:
+        c = c[1:-1].strip()
+    return c or None
+
+
+def _normalize_disposition(d: Optional[str]) -> Optional[str]:
+    if not d:
+        return None
+    d2 = d.strip().lower()
+    if d2 in ("inline", "attachment"):
+        return d2
+    return d2 or None
+
+
+@dataclass(frozen=True)
+class AttachmentMeta:
+    idx: int
+    part: str
+    filename: str
+    content_type: str
+    size: int
+    content_id: Optional[str] = None
+    disposition: Optional[str] = None
+    is_inline: bool = False
+    content_location: Optional[str] = None
+
+    def __post_init__(self) -> None:
+        # frozen=True, so use object.__setattr__
+        object.__setattr__(self, "content_id", _normalize_content_id(self.content_id))
+        object.__setattr__(self, "disposition", _normalize_disposition(self.disposition))
+
+        # If caller forgot to set is_inline, infer a sensible default:
+        # - explicit inline disposition OR
+        # - has content_id and is an image (typical CID-inline case)
+        inferred_inline = (self.disposition == "inline") or (
+            self.content_id is not None and self.content_type.lower().startswith("image/")
+        )
+        # Only override if it looks unset / default
+        if self.is_inline is False and inferred_inline:
+            object.__setattr__(self, "is_inline", True)
+
+    def __repr__(self) -> str:
+        extra = []
+        if self.disposition:
+            extra.append(f"disposition={self.disposition!r}")
+        if self.is_inline:
+            extra.append("is_inline=True")
+        if self.content_id:
+            extra.append(f"content_id={self.content_id!r}")
+        if self.content_location:
+            extra.append(f"content_location={self.content_location!r}")
+
+        extra_s = (", " + ", ".join(extra)) if extra else ""
+        return (
+            f"AttachmentMeta("
+            f"idx={self.idx!r}, "
+            f"part={self.part!r}, "
+            f"filename={self.filename!r}, "
+            f"content_type={self.content_type!r}, "
+            f"size={self.size} bytes"
+            f"{extra_s})"
+        )
+
+    def to_dict(self) -> dict:
+        # Preserve existing keys + add new ones.
+        return {
+            "idx": self.idx,
+            "part": self.part,
+            "filename": self.filename,
+            "content_type": self.content_type,
+            "size": self.size,
+            "content_id": self.content_id,
+            "disposition": self.disposition,
+            "is_inline": self.is_inline,
+            "content_location": self.content_location,
+        }
+
+
+@dataclass(frozen=True)
+class Attachment(AttachmentMeta):
+    data: bytes = b""
+
+    def __repr__(self) -> str:
+        # Keep Attachment repr aligned with AttachmentMeta, but still indicate it’s Attachment.
+        extra = []
+        if self.disposition:
+            extra.append(f"disposition={self.disposition!r}")
+        if self.is_inline:
+            extra.append("is_inline=True")
+        if self.content_id:
+            extra.append(f"content_id={self.content_id!r}")
+        if self.content_location:
+            extra.append(f"content_location={self.content_location!r}")
+
+        extra_s = (", " + ", ".join(extra)) if extra else ""
+        return (
+            f"Attachment("
+            f"idx={self.idx!r}, "
+            f"part={self.part!r}, "
+            f"filename={self.filename!r}, "
+            f"content_type={self.content_type!r}, "
+            f"size={self.size} bytes"
+            f"{extra_s})"
+        )
+
+    def to_dict(self) -> dict:
+        return {
+            "idx": self.idx,
+            "part": self.part,
+            "filename": self.filename,
+            "content_type": self.content_type,
+            "size": self.size,
+            "content_id": self.content_id,
+            "disposition": self.disposition,
+            "is_inline": self.is_inline,
+            "content_location": self.content_location,
+        }

openmail/models/message.py

@@ -0,0 +1,113 @@
+from __future__ import annotations
+
+from dataclasses import dataclass, field
+from datetime import datetime
+from typing import TYPE_CHECKING, Dict, List, Optional, Sequence, Set
+
+from openmail.types import EmailRef
+
+if TYPE_CHECKING:
+    from openmail.models.attachment import Attachment
+
+
+@dataclass(frozen=True)
+class EmailAddress:
+    email: str
+    name: Optional[str] = None
+
+    @property
+    def display(self) -> str:
+        if self.name:
+            return f"{self.name} <{self.email}>"
+        return self.email
+
+    def __str__(self) -> str:
+        return self.display
+
+    def __repr__(self) -> str:
+        return f"EmailAddress(email={self.email!r}, name={self.name!r})"
+
+    def to_dict(self) -> dict:
+        return {
+            "email": self.email,
+            "name": self.name,
+        }
+
+
+@dataclass(frozen=True)
+class EmailMessage:
+    ref: EmailRef
+    subject: str
+    from_email: EmailAddress
+    to: Sequence[EmailAddress]
+    cc: Sequence[EmailAddress] = field(default_factory=list)
+    bcc: Sequence[EmailAddress] = field(default_factory=list)
+    text: Optional[str] = None
+    html: Optional[str] = None
+    attachments: List[Attachment] = field(default_factory=list)
+
+    # IMAP metadata
+    received_at: Optional[datetime] = None
+    sent_at: Optional[datetime] = None
+    message_id: Optional[str] = None
+    headers: Dict[str, str] = field(default_factory=dict)
+
+    def __repr__(self) -> str:
+        return (
+            f"EmailMessage("
+            f"subject={self.subject!r}, "
+            f"from={self.from_email!r}, "
+            f"to={list(self.to)!r}, "
+            f"received_at={self.received_at!r})"
+            f"attachments={len(self.attachments)})"
+        )
+
+    def to_dict(self) -> dict:
+        return {
+            "ref": self.ref.to_dict(),
+            "subject": self.subject,
+            "from_email": self.from_email.to_dict(),
+            "to": [addr.to_dict() for addr in self.to],
+            "cc": [addr.to_dict() for addr in self.cc],
+            "bcc": [addr.to_dict() for addr in self.bcc],
+            "text": self.text,
+            "html": self.html,
+            "attachments": [att.to_dict() for att in self.attachments],
+            "received_at": self.received_at.isoformat() if self.received_at else None,
+            "sent_at": self.sent_at.isoformat() if self.sent_at else None,
+            "message_id": self.message_id,
+            "headers": self.headers,
+        }
+
+
+@dataclass(frozen=True)
+class EmailOverview:
+    ref: EmailRef
+    subject: str
+    from_email: EmailAddress
+    to: Sequence[EmailAddress]
+    flags: Set[str]
+    headers: Dict[str, str]
+    received_at: Optional[datetime] = None
+    sent_at: Optional[datetime] = None
+
+    def __repr__(self) -> str:
+        return (
+            f"EmailOverview("
+            f"subject={self.subject!r}, "
+            f"from={self.from_email!r}, "
+            f"to={list(self.to)!r}, "
+            f"received_at={self.received_at!r})"
+        )
+
+    def to_dict(self) -> dict:
+        return {
+            "ref": self.ref.to_dict(),
+            "subject": self.subject,
+            "from_email": self.from_email.to_dict(),
+            "to": [addr.to_dict() for addr in self.to],
+            "flags": list(self.flags),
+            "headers": self.headers,
+            "received_at": self.received_at.isoformat() if self.received_at else None,
+            "sent_at": self.sent_at.isoformat() if self.sent_at else None,
+        }

openmail/models/subscription.py

@@ -0,0 +1,45 @@
+from __future__ import annotations
+
+from dataclasses import dataclass
+from typing import List, Optional
+
+from openmail.types import EmailRef, SendResult
+
+
+@dataclass(frozen=True)
+class UnsubscribeMethod:
+    """
+    One unsubscribe mechanism from List-Unsubscribe.
+    """
+
+    kind: str  # "mailto" | "http"
+    value: str
+
+
+@dataclass(frozen=True)
+class UnsubscribeCandidate:
+    """
+    An email that supports unsubscribe.
+    """
+
+    ref: EmailRef
+    from_email: str
+    subject: str
+    methods: List[UnsubscribeMethod]
+
+    def __repr__(self) -> str:
+        kinds = "; ".join({m.kind for m in self.methods})
+        return f"UnsubscribeCandidate(" f"from={self.from_email!r}, " f"methods={kinds})"
+
+
+@dataclass(frozen=True)
+class UnsubscribeActionResult:
+    ref: EmailRef
+    method: Optional[UnsubscribeMethod]
+    sent: bool
+    send_result: Optional[SendResult] = None
+    note: Optional[str] = None
+
+    def __repr__(self) -> str:
+        detail = self.send_result.detail if self.send_result else "None"
+        return "UnsubscribeActionResult(" f"sent={self.sent!r}, " f"detail={detail!r})"

openmail/models/task.py

@@ -0,0 +1,24 @@
+from __future__ import annotations
+
+from dataclasses import dataclass, field
+from typing import Dict, List, Optional
+
+
+@dataclass
+class Task:
+    """
+    Common task structure that can be used in different domains
+    """
+
+    id: Optional[str] = None
+    title: Optional[str] = None
+    description: Optional[str] = None
+    due_date: Optional[str] = None
+    priority: Optional[str] = None
+    status: Optional[str] = None
+    assignee: Optional[str] = None
+    tags: List[str] = field(default_factory=list)
+    source_system: Optional[str] = None
+    source_id: Optional[str] = None
+    source_link: Optional[str] = None
+    metadata: Dict[str, str] = field(default_factory=dict)

openmail/smtp/__init__.py

@@ -0,0 +1,7 @@
+from openmail.smtp.client import SMTPClient
+from openmail.smtp.templates import RenderedTemplate
+
+__all__ = [
+    "SMTPClient",
+    "RenderedTemplate",
+]

openmail/smtp/builder.py

@@ -0,0 +1,41 @@
+from __future__ import annotations
+
+from email.message import EmailMessage as PyEmailMessage
+from email.utils import make_msgid
+
+from openmail.models import EmailMessage
+
+
+def build_mime_message(msg: EmailMessage) -> PyEmailMessage:
+    m = PyEmailMessage()
+    m["Subject"] = msg.subject
+    m["From"] = msg.from_email
+    m["To"] = ", ".join(msg.to)
+    if msg.cc:
+        m["Cc"] = ", ".join(msg.cc)
+    if msg.message_id:
+        m["Message-ID"] = msg.message_id
+    else:
+        m["Message-ID"] = make_msgid()
+
+    # headers
+    for k, v in msg.headers.items():
+        if k.lower() not in {"subject", "from", "to", "cc", "bcc", "message-id"}:
+            m[k] = v
+
+    # body
+    if msg.text is not None and msg.html is not None:
+        m.set_content(msg.text)
+        m.add_alternative(msg.html, subtype="html")
+    elif msg.html is not None:
+        m.set_content("This email contains HTML content.")
+        m.add_alternative(msg.html, subtype="html")
+    else:
+        m.set_content(msg.text or "")
+
+    # attachments
+    for a in msg.attachments:
+        maintype, subtype = (a.content_type.split("/", 1) + ["octet-stream"])[:2]
+        m.add_attachment(a.data, maintype=maintype, subtype=subtype, filename=a.filename)
+
+    return m

openmail/smtp/client.py

@@ -0,0 +1,218 @@
+from __future__ import annotations
+
+import copy
+import smtplib
+import ssl
+import threading
+from dataclasses import dataclass, field
+from email.message import EmailMessage as PyEmailMessage
+from email.utils import parseaddr
+from typing import Iterable, List
+
+from openmail import SMTPConfig
+from openmail.auth import AuthContext
+from openmail.errors import AuthError, ConfigError, SMTPError
+from openmail.types import SendResult
+
+
+@dataclass
+class SMTPClient:
+    config: SMTPConfig
+    _server: smtplib.SMTP | None = field(default=None, init=False, repr=False)
+    _lock: threading.RLock = field(default_factory=threading.RLock, init=False, repr=False)
+    _sent_since_connect: int = field(default=0, init=False, repr=False)
+
+    max_messages_per_connection: int = 100
+
+    @classmethod
+    def from_config(cls, config: SMTPConfig) -> SMTPClient:
+        if not config.host:
+            raise ConfigError("SMTP host required")
+        if config.use_ssl and config.use_starttls:
+            raise ConfigError("Choose use_ssl or use_starttls (not both)")
+        return cls(config)
+
+    def _from_email(self) -> str:
+        if self.config.from_email:
+            return self.config.from_email
+        raise ConfigError("No from_email set")
+
+    def _open_new_server(self) -> smtplib.SMTP:
+        cfg = self.config
+        try:
+            if cfg.use_ssl:
+                ctx = ssl.create_default_context()
+                server = smtplib.SMTP_SSL(cfg.host, cfg.port, timeout=cfg.timeout, context=ctx)
+                server.ehlo()
+            else:
+                server = smtplib.SMTP(cfg.host, cfg.port, timeout=cfg.timeout)
+                server.ehlo()
+                if cfg.use_starttls:
+                    ctx = ssl.create_default_context()
+                    server.starttls(context=ctx)
+                    server.ehlo()
+
+            if cfg.auth is None:
+                raise ConfigError("SMTPConfig.auth is required (PasswordAuth or OAuth2Auth)")
+
+            try:
+                cfg.auth.apply_smtp(server, AuthContext(host=cfg.host, port=cfg.port))
+            except smtplib.SMTPAuthenticationError as e:
+                try:
+                    server.quit()
+                except Exception:
+                    pass
+                raise AuthError(f"SMTP auth failed: {e}") from e
+
+            self._sent_since_connect = 0
+
+            return server
+
+        except AuthError:
+            raise
+        except smtplib.SMTPException as e:
+            raise SMTPError(f"SMTP connection failed: {e}") from e
+        except OSError as e:
+            raise SMTPError(f"SMTP network error: {e}") from e
+
+    def _get_server(self) -> smtplib.SMTP:
+        # Must be called with self._lock held
+        if self._server is not None:
+            return self._server
+        self._server = self._open_new_server()
+        return self._server
+
+    def _reset_server(self) -> None:
+        # Must be called with self._lock held
+        if self._server is not None:
+            try:
+                self._server.quit()
+            except Exception:
+                pass
+        self._server = None
+        self._sent_since_connect = 0
+
+    def _run_with_server(self, op):
+        """
+        Run an operation with a server, handling:
+        - thread-safety (RLock)
+        - reconnect-on-disconnect (retry once)
+
+        `op` is a callable taking a single `smtplib.SMTP` argument.
+        """
+        last_exc: BaseException | None = None
+
+        for _ in range(2):
+            with self._lock:
+                server = self._get_server()
+                try:
+                    result = op(server)
+                    if self._sent_since_connect >= self.max_messages_per_connection:
+                        self._reset_server()
+                    return result
+                except smtplib.SMTPServerDisconnected as e:
+                    # Connection dropped; reset and retry with a fresh one.
+                    last_exc = e
+                    self._reset_server()
+                except AuthError:
+                    raise
+                except smtplib.SMTPException as e:
+                    raise SMTPError(f"SMTP operation failed: {e}") from e
+
+        # If we get here, we had repeated disconnects
+        raise SMTPError(f"SMTP connection repeatedly disconnected: {last_exc}") from last_exc
+
+    def _send_with_known_server(
+        self, server: smtplib.SMTP, msg: PyEmailMessage, from_email: str, recipients: list[str]
+    ) -> SendResult:
+        try:
+            server.send_message(msg, from_addr=from_email, to_addrs=recipients)
+        except smtplib.SMTPAuthenticationError as e:
+            raise AuthError(f"SMTP auth failed during send: {e}") from e
+
+        self._sent_since_connect += 1
+        return SendResult(ok=True, message_id=str(msg["Message-ID"]))
+
+    def send(self, msg: PyEmailMessage, recipients: List[str]) -> SendResult:
+        if not recipients:
+            raise ConfigError("send(): recipients list is empty")
+
+        hdr_from = msg.get("From")
+        if hdr_from:
+            _, from_email = parseaddr(hdr_from)
+            if not from_email:
+                from_email = self._from_email()
+        else:
+            from_email = self._from_email()
+            # keep the message self-consistent for debugging/logging
+            msg = copy.deepcopy(msg)
+            msg["From"] = from_email
+
+        def _impl(server: smtplib.SMTP) -> SendResult:
+            return self._send_with_known_server(server, msg, from_email, recipients)
+
+        return self._run_with_server(_impl)
+
+    def send_many(self, batch: Iterable[tuple[PyEmailMessage, Iterable[str]]]) -> list[SendResult]:
+        """
+        Send multiple messages in a single (or minimal) SMTP session.
+        """
+        prepared: list[tuple[PyEmailMessage, str, list[str]]] = []
+
+        for msg, rcpts_iter in batch:
+            rcpts = list(rcpts_iter)
+            if not rcpts:
+                raise ConfigError("send_many(): one of the messages has no recipients")
+
+            hdr_from = msg.get("From")
+            if hdr_from:
+                _, from_email = parseaddr(hdr_from)
+                if not from_email:
+                    from_email = self._from_email()
+                final_msg = msg
+            else:
+                from_email = self._from_email()
+                final_msg = copy.deepcopy(msg)
+                final_msg["From"] = from_email
+
+            prepared.append((final_msg, from_email, rcpts))
+
+        results: list[SendResult] = []
+        i = 0
+
+        def _impl(server: smtplib.SMTP) -> list[SendResult]:
+            nonlocal i, results
+            while i < len(prepared):
+                msg, from_email, recipients = prepared[i]
+                res = self._send_with_known_server(server, msg, from_email, recipients)
+                results.append(res)
+                i += 1
+            return results
+
+        return self._run_with_server(_impl)
+
+    def ping(self) -> None:
+        """
+        Minimal SMTP health check.
+        """
+
+        def _impl(server: smtplib.SMTP) -> None:
+            try:
+                code, reply = server.noop()
+            except smtplib.SMTPAuthenticationError as e:
+                raise AuthError(f"SMTP auth failed during ping: {e}") from e
+            if code != 250:
+                raise SMTPError(f"SMTP NOOP failed: {code} {reply!r}")
+
+        self._run_with_server(_impl)
+
+    def close(self) -> None:
+        with self._lock:
+            self._reset_server()
+
+    def __enter__(self) -> SMTPClient:
+        # lazy connect;
+        return self
+
+    def __exit__(self, exc_type, exc, tb) -> None:
+        self.close()

openmail/smtp/templates.py

@@ -0,0 +1,16 @@
+from __future__ import annotations
+
+from dataclasses import dataclass
+from typing import Mapping, Optional
+
+
+@dataclass(frozen=True)
+class RenderedTemplate:
+    subject: str
+    text: Optional[str] = None
+    html: Optional[str] = None
+
+
+def render_template(name: str, context: Mapping[str, object]) -> RenderedTemplate:
+    # Backbone placeholder. Later: Jinja2 file loader.
+    raise NotImplementedError("Template rendering not implemented yet")

openmail/subscription/__init__.py

@@ -0,0 +1,7 @@
+from openmail.subscription.detector import SubscriptionDetector
+from openmail.subscription.service import SubscriptionService
+
+__all__ = [
+    "SubscriptionDetector",
+    "SubscriptionService",
+]

openmail/subscription/detector.py

@@ -0,0 +1,58 @@
+from __future__ import annotations
+
+from typing import List, Optional
+
+from openmail.imap import IMAPClient, IMAPQuery
+from openmail.models import UnsubscribeCandidate
+from openmail.subscription.parser import parse_list_unsubscribe
+
+
+class SubscriptionDetector:
+    def __init__(self, imap: IMAPClient):
+        self.imap = imap
+
+    def find(
+        self,
+        *,
+        mailbox: str = "INBOX",
+        limit: int = 200,
+        since: Optional[str] = None,
+        unseen_only: bool = False,
+    ) -> List[UnsubscribeCandidate]:
+        q = IMAPQuery()
+        if unseen_only:
+            q.unseen()
+        if since:
+            q.since(since)
+
+        page = self.imap.search_page_cached(mailbox=mailbox, query=q, page_size=limit)
+        msgs = self.imap.fetch(page.refs)
+
+        out: List[UnsubscribeCandidate] = []
+        for ref, msg in zip(page.refs, msgs):
+            headers = msg.headers
+            lu = _get_header(headers, "List-Unsubscribe")
+            if not lu:
+                continue
+
+            methods = parse_list_unsubscribe(lu)
+            if not methods:
+                continue
+
+            out.append(
+                UnsubscribeCandidate(
+                    ref=ref,
+                    from_email=msg.from_email,
+                    subject=msg.subject,
+                    methods=methods,
+                )
+            )
+        return out
+
+
+def _get_header(headers: dict, name: str) -> str:
+    name = name.lower()
+    for k, v in headers.items():
+        if k.lower() == name:
+            return v
+    return ""