mailflat 0.1.0__tar.gz → 0.3.0__tar.gz

mailflat-0.3.0/.gitignore

@@ -0,0 +1,6 @@
+dist/
+build/
+*.egg-info/
+.venv/
+__pycache__/
+.pytest_cache/

{mailflat-0.1.0 → mailflat-0.3.0}/PKG-INFO

@@ -1,6 +1,6 @@
 Metadata-Version: 2.4
 Name: mailflat
-Version: 0.1.0
+Version: 0.3.0
 Summary: Official Python SDK for MailFlat — disposable, automation-friendly email inboxes with one-line OTP retrieval.
 Project-URL: Homepage, https://mailflat.net
 Project-URL: Documentation, https://mailflat.net/docs
@@ -20,8 +20,11 @@ Classifier: Typing :: Typed
 Requires-Python: >=3.8
 Requires-Dist: httpx>=0.24
 Provides-Extra: dev
+Requires-Dist: langchain-core>=0.2; extra == 'dev'
 Requires-Dist: pytest>=7; extra == 'dev'
 Requires-Dist: respx>=0.20; extra == 'dev'
+Provides-Extra: langchain
+Requires-Dist: langchain-core>=0.2; extra == 'langchain'
 Description-Content-Type: text/markdown
 
 # MailFlat — Python SDK

{mailflat-0.1.0 → mailflat-0.3.0}/pyproject.toml

@@ -4,7 +4,7 @@ build-backend = "hatchling.build"
 
 [project]
 name = "mailflat"
-version = "0.1.0"
+version = "0.3.0"
 description = "Official Python SDK for MailFlat — disposable, automation-friendly email inboxes with one-line OTP retrieval."
 readme = "README.md"
 requires-python = ">=3.8"
@@ -29,7 +29,8 @@ Documentation = "https://mailflat.net/docs"
 Source = "https://github.com/onderyentar/mailflat"
 
 [project.optional-dependencies]
-dev = ["pytest>=7", "respx>=0.20"]
+langchain = ["langchain-core>=0.2"]
+dev = ["pytest>=7", "respx>=0.20", "langchain-core>=0.2"]
 
 [tool.hatch.build.targets.wheel]
 packages = ["src/mailflat"]

{mailflat-0.1.0 → mailflat-0.3.0}/src/mailflat/__init__.py

@@ -27,7 +27,7 @@ from .errors import (
 )
 from .inbox import Inbox, Message
 
-__version__ = "0.1.0"
+__version__ = "0.3.0"
 
 __all__ = [
     "MailFlat",

{mailflat-0.1.0 → mailflat-0.3.0}/src/mailflat/inbox.py

@@ -42,6 +42,17 @@ class Message:
     send_error: str | None = None
     received_at: str | None = None
     raw: dict[str, Any] = field(default_factory=dict, repr=False)
+    # Bu mesajı döndüren Inbox (msg.delete() şekeri için). Inbox.messages()/latest()/wait_* doldurur.
+    _inbox: "Inbox | None" = field(default=None, repr=False, compare=False)
+
+    def delete(self) -> dict[str, Any]:
+        """Bu maili sil (inbox kalır). Mesaj bir Inbox'tan geldiyse çalışır."""
+        if self._inbox is None or self.id is None:
+            raise ValueError(
+                "This message isn't attached to an inbox (or has no id). "
+                "Use inbox.delete_message(message_id) instead."
+            )
+        return self._inbox.delete_message(self.id)
 
     @classmethod
     def from_dict(cls, data: dict[str, Any]) -> "Message":
@@ -75,26 +86,34 @@ class Inbox:
         self.address: str = address
         # create/list yanıtından gelen ek alanlar (varsa)
         self.name: str | None = meta.get("name")
+        self.api_key: str | None = meta.get("api_key")  # per-inbox key (mf_sk_...)
         self.retention_hours: int | None = meta.get("retention_hours")
         self.encrypted: bool = bool(meta.get("encrypted"))
         self.via_api: bool | None = meta.get("via_api")
         self.created_at: str | None = meta.get("created_at")
-        self._meta = meta
+        # backend yanıtının tamamı (Message.raw ile simetrik) — MCP/agent katmanı için.
+        self.raw: dict[str, Any] = {"address": address, **meta}
 
     def __repr__(self) -> str:
         return f"<Inbox {self.address!r}>"
 
     # ----------------------------------------------------------------- okuma
+    def _wrap(self, data: dict[str, Any]) -> Message:
+        """API mail dict'ini Message'a çevirir + bu inbox ref'ini iliştirir (msg.delete() için)."""
+        m = Message.from_dict(data)
+        m._inbox = self
+        return m
+
     def messages(self) -> list[Message]:
         """Inbox'taki tüm mesajları (yeniden eskiye) döndürür."""
         res = self._client._get(f"/api/v1/inboxes/{self.address}/messages")
-        return [Message.from_dict(e) for e in (res.get("emails") or [])]
+        return [self._wrap(e) for e in (res.get("emails") or [])]
 
     def latest(self) -> Message | None:
         """En son mesajı döndürür (yoksa None)."""
         res = self._client._get(f"/api/v1/inboxes/{self.address}/latest")
         email = res.get("email")
-        return Message.from_dict(email) if email else None
+        return self._wrap(email) if email else None
 
     def wait_for_message(
         self, *, timeout: float = 30, poll_interval: float = 1.0
@@ -113,7 +132,7 @@ class Inbox:
                 )
             email = res.get("email")
             if email:
-                return Message.from_dict(email)
+                return self._wrap(email)
             if time.monotonic() >= deadline:
                 raise OTPTimeoutError(
                     f"No message arrived for {self.address} within {timeout}s"
@@ -156,3 +175,7 @@ class Inbox:
     def delete(self) -> dict[str, Any]:
         """Inbox'u ve tüm mesajlarını siler. Geri alınamaz."""
         return self._client._delete(f"/api/v1/inboxes/{self.address}")
+
+    def delete_message(self, message_id: int) -> dict[str, Any]:
+        """Inbox'taki TEK bir maili siler (inbox kalır). `Message.delete()` bunu çağırır."""
+        return self._client._delete(f"/api/v1/inboxes/{self.address}/messages/{message_id}")

mailflat-0.3.0/src/mailflat/langchain.py

@@ -0,0 +1,155 @@
+"""MailFlat LangChain entegrasyonu — `MailFlatToolkit` + 6 araçlık LangChain tool seti.
+
+`mailflat` SDK'sının üstüne ince bir LangChain kabuğu; tüm HTTP/iş mantığı client'ta (DRY).
+`langchain-core` opsiyonel bağımlılıktır → `pip install mailflat[langchain]`.
+
+Kullanım:
+    from mailflat.langchain import MailFlatToolkit
+    toolkit = MailFlatToolkit(api_key=env("MAILFLAT_KEY"))
+    tools = toolkit.get_tools()   # create_inbox, list_inboxes, read_messages,
+                                  # wait_for_otp, send_email, delete_inbox
+
+Connected to:
+  - imports from: mailflat.client (MailFlat), langchain_core.tools (StructuredTool)
+  - imported by:  kullanıcı kodu (LangChain ajanları)
+
+Key exports:
+  - `MailFlatToolkit(api_key=..., base_url=...)` — `.get_tools()` → list[BaseTool]
+"""
+from __future__ import annotations
+
+from typing import TYPE_CHECKING, Any
+
+try:
+    from langchain_core.tools import BaseTool, StructuredTool
+except ImportError as exc:  # langchain-core kurulu değil → açıklayıcı hata
+    raise ImportError(
+        "MailFlat's LangChain integration requires 'langchain-core'. "
+        "Install it with:  pip install mailflat[langchain]"
+    ) from exc
+
+from .client import DEFAULT_BASE_URL, MailFlat
+from .errors import EncryptedInboxError, MailFlatError, OTPTimeoutError
+
+if TYPE_CHECKING:
+    from collections.abc import Sequence
+
+
+class MailFlatToolkit:
+    """MailFlat araçlarını bir LangChain ajanına bağlamak için toolkit.
+
+    >>> from mailflat.langchain import MailFlatToolkit
+    >>> toolkit = MailFlatToolkit(api_key="mf_live_...")
+    >>> tools = toolkit.get_tools()
+    """
+
+    def __init__(
+        self,
+        api_key: str | None = None,
+        *,
+        base_url: str = DEFAULT_BASE_URL,
+        client: MailFlat | None = None,
+    ) -> None:
+        # client enjeksiyonu testleri kolaylaştırır; yoksa api_key ile kurulur.
+        self._client = client or MailFlat(api_key=api_key, base_url=base_url)
+
+    # ------------------------------------------------------------------ tools
+    def get_tools(self) -> "Sequence[BaseTool]":
+        """6 MailFlat aracını LangChain `BaseTool` listesi olarak döndürür."""
+        client = self._client
+
+        def create_inbox(prefix: str = "", label: str = "", retention_hours: int = 0) -> dict:
+            """Create a real disposable email inbox and return its address.
+
+            Args:
+                prefix: Optional left-hand prefix (e.g. 'signup'); random if empty.
+                label: Optional human label to remember what this inbox is for.
+                retention_hours: Optional retention in hours; 0 = your plan's max,
+                    values above your plan are capped.
+            """
+            try:
+                inbox = client.create(
+                    prefix=prefix or None,
+                    label=label or None,
+                    retention_hours=retention_hours if retention_hours and retention_hours > 0 else None,
+                )
+                return inbox.raw
+            except MailFlatError as e:
+                return {"error": str(e)}
+
+        def list_inboxes() -> dict:
+            """List all inboxes available to this API key."""
+            try:
+                return {"ok": True, "inboxes": [i.raw for i in client.list()]}
+            except MailFlatError as e:
+                return {"error": str(e)}
+
+        def read_messages(address: str) -> dict:
+            """Read all messages in the given inbox address (newest first).
+
+            Args:
+                address: The full inbox address, e.g. signup-8f3@mailflat.net.
+            """
+            try:
+                return {"ok": True, "emails": [m.raw for m in client.inbox(address).messages()]}
+            except MailFlatError as e:
+                return {"error": str(e)}
+
+        def wait_for_otp(address: str, timeout: int = 30) -> dict:
+            """Poll the inbox until a one-time verification code (OTP) arrives.
+
+            Args:
+                address: The inbox address to poll.
+                timeout: Maximum seconds to wait before giving up (default 30).
+            """
+            try:
+                inbox = client.inbox(address)
+                otp = inbox.wait_for_otp(timeout=timeout)
+                latest = inbox.latest()
+                return {"otp_code": otp, "email": latest.raw if latest else None}
+            except OTPTimeoutError:
+                return {"otp_code": None, "error": "timeout"}
+            except EncryptedInboxError as e:
+                return {"otp_code": None, "encrypted": True, "error": str(e)}
+            except MailFlatError as e:
+                return {"otp_code": None, "error": str(e)}
+
+        def send_email(
+            address: str, to: str, subject: str = "", body: str = "", html: str = ""
+        ) -> dict:
+            """Send an email FROM the given inbox address (DKIM-signed via MailFlat's MTA).
+
+            Args:
+                address: The inbox address to send from (must belong to this API key).
+                to: Recipient email address.
+                subject: Email subject line.
+                body: Plain-text body.
+                html: Optional HTML body.
+            """
+            try:
+                return client.inbox(address).send(to, subject=subject, body=body, html=html or None)
+            except MailFlatError as e:
+                return {"error": str(e)}
+
+        def delete_inbox(address: str) -> dict:
+            """Delete an inbox and all its messages by address. Irreversible.
+
+            Args:
+                address: The inbox address to delete.
+            """
+            try:
+                return client.inbox(address).delete()
+            except MailFlatError as e:
+                return {"error": str(e)}
+
+        funcs: list[Any] = [
+            create_inbox,
+            list_inboxes,
+            read_messages,
+            wait_for_otp,
+            send_email,
+            delete_inbox,
+        ]
+        # from_function tip ipuçları + docstring'den args_schema'yı kendisi çıkarır
+        # (pydantic v1/v2 sürüm farkı bu yolla atlanır).
+        return [StructuredTool.from_function(func=f) for f in funcs]

mailflat-0.1.0/.gitignore

@@ -1,38 +0,0 @@
-# Python
-__pycache__/
-*.py[cod]
-venv/
-.venv/
-*.db
-*.db-wal
-*.db-shm
-
-# env — secret'lar asla commit edilmez (.env.example HARİÇ, o şablon)
-.env
-.env.*
-!.env.example
-
-# secrets — DKIM gizli anahtarı + SSH key'ler
-*.pem
-*_key
-*_key.pub
-id_rsa*
-id_ed25519*
-
-# Node / Next.js
-node_modules/
-.next/
-dist/
-out/
-
-# Playwright (E2E) — test çıktıları + indirilen browser'lar
-test-results/
-playwright-report/
-playwright/.cache/
-.last-run.json
-
-# OS / editor
-.DS_Store
-.idea/
-.vscode/
-/Keys