mailflat 0.4.0__tar.gz → 0.5.0__tar.gz

{mailflat-0.4.0 → mailflat-0.5.0}/PKG-INFO

@@ -1,6 +1,6 @@
 Metadata-Version: 2.4
 Name: mailflat
-Version: 0.4.0
+Version: 0.5.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
@@ -14,10 +14,16 @@ Classifier: Intended Audience :: Developers
 Classifier: License :: OSI Approved :: MIT License
 Classifier: Programming Language :: Python :: 3
 Classifier: Programming Language :: Python :: 3 :: Only
+Classifier: Programming Language :: Python :: 3.9
+Classifier: Programming Language :: Python :: 3.10
+Classifier: Programming Language :: Python :: 3.11
+Classifier: Programming Language :: Python :: 3.12
+Classifier: Programming Language :: Python :: 3.13
+Classifier: Programming Language :: Python :: 3.14
 Classifier: Topic :: Communications :: Email
 Classifier: Topic :: Software Development :: Testing
 Classifier: Typing :: Typed
-Requires-Python: >=3.8
+Requires-Python: >=3.9
 Requires-Dist: httpx<1,>=0.24
 Provides-Extra: dev
 Requires-Dist: langchain-core>=0.2; extra == 'dev'
@@ -105,9 +111,14 @@ for self-hosted / BYOD deployments. Supports use as a context manager (`with Mai
 
 - `.links` — URLs found in the body (HTML hrefs first). For "click the verification link" flows.
 - `.attachments` — metadata; `msg.attachments[0].download()` fetches the bytes.
+  ⚠️ `send()` cannot attach files yet, so you cannot produce an attachment from the SDK
+  alone — send one from a normal mail client to test this path.
 - `.spam` — `{score, required, is_spam, rules, scanner}`, or `None` when never scanned
-  (which is not the same as a score of 0).
-- `.headers` — raw headers; `Message-ID` lives here (threading, dedup).
+  (which is not the same as a score of 0). ⚠️ Spam scanning is currently **disabled** on
+  mailflat.net, so today this is `None` for every message.
+- `.headers` — raw headers, exactly as they arrived. Names are case-insensitive per
+  RFC 5322 but this is a plain dict, so **do not index it**: the real key is `Message-ID`,
+  and `headers["Message-Id"]` raises `KeyError`. Use `.header("message-id")` or `.message_id`.
 - `.mark_read()` / `.delete()` — act on this message directly.
 
 ## Errors

{mailflat-0.4.0 → mailflat-0.5.0}/README.md

@@ -76,9 +76,14 @@ for self-hosted / BYOD deployments. Supports use as a context manager (`with Mai
 
 - `.links` — URLs found in the body (HTML hrefs first). For "click the verification link" flows.
 - `.attachments` — metadata; `msg.attachments[0].download()` fetches the bytes.
+  ⚠️ `send()` cannot attach files yet, so you cannot produce an attachment from the SDK
+  alone — send one from a normal mail client to test this path.
 - `.spam` — `{score, required, is_spam, rules, scanner}`, or `None` when never scanned
-  (which is not the same as a score of 0).
-- `.headers` — raw headers; `Message-ID` lives here (threading, dedup).
+  (which is not the same as a score of 0). ⚠️ Spam scanning is currently **disabled** on
+  mailflat.net, so today this is `None` for every message.
+- `.headers` — raw headers, exactly as they arrived. Names are case-insensitive per
+  RFC 5322 but this is a plain dict, so **do not index it**: the real key is `Message-ID`,
+  and `headers["Message-Id"]` raises `KeyError`. Use `.header("message-id")` or `.message_id`.
 - `.mark_read()` / `.delete()` — act on this message directly.
 
 ## Errors

mailflat-0.5.0/pyproject.toml

@@ -0,0 +1,60 @@
+[build-system]
+requires = ["hatchling"]
+build-backend = "hatchling.build"
+
+[project]
+name = "mailflat"
+# The version comes from ONE source: src/mailflat/__init__.py::__version__ (see
+# [tool.hatch.version]). Hardcoding a `version = ...` here brings B-052 back: 0.3.1 was on
+# PyPI while the package itself reported `mailflat.__version__ == "0.3.0"`. Two sources drift.
+dynamic = ["version"]
+description = "Official Python SDK for MailFlat — disposable, automation-friendly email inboxes with one-line OTP retrieval."
+readme = "README.md"
+requires-python = ">=3.9"
+license = { text = "MIT" }
+authors = [{ name = "MailFlat", email = "support@mailflat.net" }]
+keywords = ["email", "disposable-email", "otp", "automation", "testing", "ai-agents", "temporary-email"]
+classifiers = [
+    "Development Status :: 4 - Beta",
+    "Intended Audience :: Developers",
+    "License :: OSI Approved :: MIT License",
+    "Programming Language :: Python :: 3",
+    "Programming Language :: Python :: 3 :: Only",
+    # BOTH ENDS of the range were actually run (3.11 + 3.14, 53 tests green). No separate
+    # claim is made about the versions in between: we use no version-specific API and every
+    # file carries `from __future__ import annotations`. Floor moved 3.8 → 3.9 because 3.8 is
+    # EOL and was NEVER tested, and claiming an untested version misleads people on PyPI.
+    "Programming Language :: Python :: 3.9",
+    "Programming Language :: Python :: 3.10",
+    "Programming Language :: Python :: 3.11",
+    "Programming Language :: Python :: 3.12",
+    "Programming Language :: Python :: 3.13",
+    "Programming Language :: Python :: 3.14",
+    "Topic :: Communications :: Email",
+    "Topic :: Software Development :: Testing",
+    "Typing :: Typed",
+]
+# UPPER BOUND: httpx is still pre-1.0 and 1.0 is a declared breaking threshold. Leaving it
+# unbounded invites a repeat of B-047 (mcp>=1.2 → mcp 2.0.0 removed the module → uvx
+# mailflat-mcp crashed). Fine on 0.28.1 today; the bound is raised deliberately when 1.0 ships.
+dependencies = ["httpx>=0.24,<1"]
+
+[project.urls]
+Homepage = "https://mailflat.net"
+# /docs is disabled in production (the FastAPI Swagger surface; see app/main.py).
+# This URL moves to the public documentation site once that page is live.
+Documentation = "https://mailflat.net"
+Source = "https://github.com/onderyentar/mailflat"
+
+[project.optional-dependencies]
+langchain = ["langchain-core>=0.2"]
+dev = ["pytest>=7", "respx>=0.20", "langchain-core>=0.2"]
+
+[tool.hatch.version]
+path = "src/mailflat/__init__.py"
+
+[tool.hatch.build.targets.wheel]
+packages = ["src/mailflat"]
+
+[tool.hatch.build.targets.sdist]
+include = ["src/mailflat", "README.md", "LICENSE"]

{mailflat-0.4.0 → mailflat-0.5.0}/src/mailflat/__init__.py

@@ -2,8 +2,6 @@
 
 `pip install mailflat` → `from mailflat import MailFlat`.
 
-NOT: Bu dosya YAYIN yüzeyi (`packages/`) → docstring'ler İngilizce (CLAUDE.md §3 istisnası).
-
 Connected to:
   - imports from: mailflat.client, mailflat.inbox, mailflat.errors
   - imported by:  user code, mailflat-mcp, mailflat.langchain
@@ -32,9 +30,9 @@ from .errors import (
 from .inbox import Attachment, Inbox, Message
 from .redact import redact_secrets
 
-# Paketin TEK sürüm kaynağı — pyproject.toml bunu [tool.hatch.version] ile okur.
-# Yayın = burayı yükselt, başka hiçbir yeri değil.
-__version__ = "0.4.0"
+# The package's ONLY version source — pyproject.toml reads it via [tool.hatch.version].
+# Releasing = bump this line and nothing else.
+__version__ = "0.5.0"
 
 __all__ = [
     "MailFlat",

{mailflat-0.4.0 → mailflat-0.5.0}/src/mailflat/client.py

@@ -3,8 +3,6 @@
 One account API key (X-API-Key) creates inboxes, lists them, reads mail/OTP and sends mail.
 Every higher layer (MCP, LangChain) calls this client, so behaviour lives in one place.
 
-NOT: Bu dosya YAYIN yüzeyi (`packages/`) → docstring'ler İngilizce (CLAUDE.md §3 istisnası).
-
 Connected to:
   - imports from: mailflat.inbox, mailflat.errors (+ httpx)
   - imported by:  mailflat.__init__
@@ -30,9 +28,10 @@ from .inbox import Inbox
 DEFAULT_BASE_URL = "https://mailflat.net"
 _RETRY_STATUSES = {429, 502, 503, 504}
 
-# Yalnız yan etkisi olmayan (idempotent) metotlar tekrar denenir. POST bilerek YOK:
-# /send'de MTA maili kabul edip ağ geçidi 504 dönerse, retry AYNI MAİLİ İKİNCİ KEZ yollar
-# ve kullanıcı bunu asla fark etmez. Idempotency-Key desteği gelene kadar POST tek atış.
+# Only side-effect-free (idempotent) methods are retried. POST is deliberately excluded:
+# if the MTA accepts a /send and the gateway then returns 504, a retry delivers THE SAME
+# MAIL TWICE and the user never finds out. POST stays single-shot until we support
+# Idempotency-Key.
 _IDEMPOTENT_METHODS = {"GET", "HEAD", "DELETE"}
 
 _MAX_BACKOFF = 8.0
@@ -41,18 +40,16 @@ logger = logging.getLogger("mailflat")
 
 
 def _retry_after_seconds(resp: httpx.Response) -> float | None:
-    """Parse the `Retry-After` header (seconds form). Returns None when absent/unparsable.
-
-    Bir sunucu "12 saniye bekle" diyorsa 1 saniyede geri dönmek, hem 429'u tekrar yemek
-    hem de rate limit penceresini uzatmak demek.
-    """
+    """Parse the `Retry-After` header (seconds form). Returns None when absent/unparsable."""
+    # Coming back after 1s when the server said "wait 12s" both earns another 429 and
+    # stretches the rate-limit window.
     raw = resp.headers.get("Retry-After")
     if not raw:
         return None
     try:
         return max(0.0, float(raw.strip()))
     except (TypeError, ValueError):
-        # HTTP-date biçimi de geçerli ama nadir; tahmin etmektense kendi backoff'umuza düşeriz.
+        # The HTTP-date form is valid but rare; rather than guess, fall back to our backoff.
         return None
 
 
@@ -84,7 +81,7 @@ class MailFlat:
         self.api_key = api_key
         self.base_url = base_url.rstrip("/")
         self.max_retries = max(0, max_retries)
-        # http_client enjeksiyonu testleri (httpx.MockTransport) kolaylaştırır.
+        # Injecting http_client keeps tests simple (httpx.MockTransport).
         self._http = http_client or httpx.Client(
             base_url=self.base_url,
             headers={"X-API-Key": api_key, "User-Agent": self.user_agent()},
@@ -93,11 +90,11 @@ class MailFlat:
 
     @staticmethod
     def user_agent() -> str:
-        """Return the `User-Agent` this client sends, e.g. `mailflat-python/0.4.0`.
+        """Return the `User-Agent` this client sends, e.g. `mailflat-python/<version>`.
 
-        Sunucu tarafında hangi SDK sürümünün sorun çıkardığını görebilmek için; sürüm
-        döngüsel import'a girmeden okunur.
+        Sending the version lets the server tell which SDK build is misbehaving.
         """
+        # Read the version here so the module level stays free of a circular import.
         from . import __version__
 
         return f"mailflat-python/{__version__}"
@@ -112,19 +109,26 @@ class MailFlat:
     def close(self) -> None:
         self._http.close()
 
-    # --------------------------------------------------------------- HTTP iç
-    def _request(self, method: str, path: str, json: dict[str, Any] | None = None) -> dict[str, Any]:
+    # -------------------------------------------------------------- HTTP internals
+    def _request(self, method: str, path: str, json: dict[str, Any] | None = None,
+                 *, idempotent: bool | None = None) -> dict[str, Any]:
+        """`idempotent=True` marks a call as safe to repeat regardless of its method.
+
+        mark_read/burn are POSTs but repeating them is harmless (same end state). It is
+        never passed for send: a repeated send delivers the same mail twice.
+        """
         attempt = 0
         while True:
             try:
                 resp = self._http.request(method, path, json=json)
-            except httpx.HTTPError as exc:  # ağ/timeout
+            except httpx.HTTPError as exc:  # network / timeout
                 raise MailFlatError(f"Network error: {exc}") from exc
 
             retry_after = _retry_after_seconds(resp)
+            can_repeat = method.upper() in _IDEMPOTENT_METHODS if idempotent is None else idempotent
             retriable = (
                 resp.status_code in _RETRY_STATUSES
-                and method.upper() in _IDEMPOTENT_METHODS
+                and can_repeat
                 and attempt < self.max_retries
             )
             if retriable:
@@ -148,25 +152,41 @@ class MailFlat:
                 logger.debug("%s %s failed with %s: %s", method, path, resp.status_code, detail)
                 raise_for_status(resp.status_code, detail, retry_after=retry_after)
 
-            if isinstance(data, dict) and data.get("error"):  # güvenlik: 200 + error
+            if isinstance(data, dict) and data.get("error"):  # safety net: 200 + error
                 raise MailFlatError(data["error"], status_code=resp.status_code)
             return data if isinstance(data, dict) else {}
 
     def _get(self, path: str) -> dict[str, Any]:
         return self._request("GET", path)
 
-    def _post(self, path: str, json: dict[str, Any] | None = None) -> dict[str, Any]:
-        return self._request("POST", path, json=json or {})
+    def _post(self, path: str, json: dict[str, Any] | None = None,
+              *, idempotent: bool = False) -> dict[str, Any]:
+        return self._request("POST", path, json=json or {}, idempotent=idempotent)
 
     def _delete(self, path: str) -> dict[str, Any]:
         return self._request("DELETE", path)
 
     def _get_bytes(self, path: str) -> httpx.Response:
-        """Raw response for binary endpoints (attachment download)."""
-        try:
-            resp = self._http.request("GET", path)
-        except httpx.HTTPError as exc:
-            raise MailFlatError(f"Network error: {exc}") from exc
+        """Raw response for binary endpoints (attachment download).
+
+        Retries on the same statuses as any other GET: this path bypassed the retry loop
+        entirely until 0.4.1, so an attachment download gave up on the first 503 while
+        every other read retried.
+        """
+        attempt = 0
+        while True:
+            try:
+                resp = self._http.request("GET", path)
+            except httpx.HTTPError as exc:
+                raise MailFlatError(f"Network error: {exc}") from exc
+            retry_after = _retry_after_seconds(resp)
+            if resp.status_code in _RETRY_STATUSES and attempt < self.max_retries:
+                attempt += 1
+                delay = retry_after if retry_after is not None else min(2 ** attempt * 0.5, _MAX_BACKOFF)
+                logger.debug("retrying GET %s after %s (status %s)", path, delay, resp.status_code)
+                time.sleep(min(delay, _MAX_BACKOFF))
+                continue
+            break
         if resp.status_code >= 400:
             detail = ""
             try:
@@ -210,7 +230,7 @@ class MailFlat:
         res = self._post("/api/v1/inboxes", payload)
         return Inbox(self, res["address"], **{k: v for k, v in res.items() if k != "address"})
 
-    # Landing snippet'leriyle birebir uyum için alias.
+    # Alias so the landing-page snippets match the SDK exactly.
     create_inbox = create
 
     def list(self) -> list[Inbox]:

{mailflat-0.4.0 → mailflat-0.5.0}/src/mailflat/errors.py

@@ -1,8 +1,5 @@
 """MailFlat SDK error types — maps HTTP status codes to meaningful Python exceptions.
 
-NOT: Bu dosya YAYIN yüzeyi (`packages/`) → docstring'ler İngilizce (CLAUDE.md §3 istisnası).
-Burada docstring bir yorum değil, kullanıcının `help()` ve IDE tooltip'inde gördüğü arayüzdür.
-
 Connected to:
   - imported by:  mailflat.client, mailflat.inbox, mailflat.__init__
 
@@ -36,10 +33,10 @@ class MailFlatPermissionError(MailFlatError):
     """403 — this API key does not own that inbox."""
 
 
-# Geriye dönük uyumluluk: 0.3.3'e kadar bu sınıfın adı `PermissionError` idi ve built-in'i
-# GÖLGELİYORDU. `except PermissionError` yazan kullanıcı, SDK'yı import etmemiş bir modülde
-# built-in'i yakalayıp bizimkini kaçırabilir (ya da tersi) — sessiz ve teşhisi zor bir hata.
-# Eski adı alias olarak bırakıyoruz ki mevcut kod kırılmasın.
+# Backwards compatibility: up to 0.3.3 this class was named `PermissionError` and SHADOWED
+# the built-in. Someone writing `except PermissionError` in a module that never imported the
+# SDK would catch the built-in and miss ours (or the reverse) — a silent, hard-to-diagnose
+# bug. The old name stays as an alias so existing code keeps working.
 PermissionError = MailFlatPermissionError  # noqa: A001 - deprecated alias, kept for compatibility
 
 

{mailflat-0.4.0 → mailflat-0.5.0}/src/mailflat/inbox.py

@@ -3,8 +3,6 @@
 `Inbox` is returned by the `MailFlat` client and carries the read, wait, send and delete
 methods. `Message` is the typed form of an /api/v1 email payload.
 
-NOT: Bu dosya YAYIN yüzeyi (`packages/`) → docstring'ler İngilizce (CLAUDE.md §3 istisnası).
-
 Connected to:
   - imports from: mailflat.errors
   - imported by:  mailflat.client, mailflat.__init__
@@ -23,11 +21,11 @@ from typing import TYPE_CHECKING, Any
 
 from .errors import EncryptedInboxError, MailFlatError, OTPTimeoutError
 
-if TYPE_CHECKING:  # döngüsel import'tan kaçın (sadece tip ipucu)
+if TYPE_CHECKING:  # avoid a circular import (type hint only)
     from .client import MailFlat
 
-# Sunucunun kabul ettiği yön filtreleri. "in" varsayılan: bir ajan için "mesaj geldi mi"
-# sorusuna kendi gönderdiği mail cevap olamaz.
+# Direction filters (server contract). "in" is the default: for an agent, "did a message
+# arrive?" cannot be answered by mail the agent itself sent.
 DIRECTIONS = ("in", "out", "all")
 
 
@@ -41,7 +39,8 @@ def _check_direction(direction: str) -> str:
 class Attachment:
     """Attachment metadata. The bytes are fetched on demand with `.download()`.
 
-    İçerik listede GELMEZ: tek ekli 5 MB'lık bir mail, mesaj listesini kullanılamaz yapardı.
+    Contents are never included in a message listing: a single 5 MB attachment would make
+    the list unusable, so the bytes live behind a separate request.
     """
 
     id: int | None = None
@@ -104,14 +103,18 @@ class Message:
     # read this instead of parsing the body themselves.
     links: list[str] = field(default_factory=list)
     attachments: list[Attachment] = field(default_factory=list)
-    # {score, required, is_spam, rules, scanner} — None means NOT SCANNED, which is not
-    # the same as a score of 0.0.
+    # {score, required, is_spam, rules, scanner}, or None when the message was NOT SCANNED
+    # (not the same as a score of 0.0).
+    # NOTE: spam scanning is currently disabled on mailflat.net, so in practice this is
+    # None for every message today. The field is wired end to end and will start carrying
+    # data as soon as scanning is switched back on.
     spam: dict[str, Any] | None = None
     # Raw message headers (Message-ID lives here — needed for threading and dedup).
     # None on encrypted inboxes: headers carry the Subject, so they go inside the envelope.
     headers: dict[str, Any] | 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.
+    # The Inbox this message came from (powers msg.delete()). Filled in by
+    # Inbox.messages() / latest() / wait_*.
     _inbox: "Inbox | None" = field(default=None, repr=False, compare=False)
 
     def delete(self) -> dict[str, Any]:
@@ -123,6 +126,26 @@ class Message:
             )
         return self._inbox.delete_message(self.id)
 
+    def header(self, name: str, default: Any = None) -> Any:
+        """Look up a header case-insensitively, e.g. `msg.header("message-id")`.
+
+        Header names are case-insensitive per RFC 5322, but `headers` is a plain dict whose
+        keys come straight off the wire — the real key is `Message-ID`, so
+        `headers["Message-Id"]` raises KeyError. Use this instead of indexing.
+        """
+        if not self.headers:
+            return default
+        target = name.replace("_", "-").lower()
+        for key, value in self.headers.items():
+            if str(key).lower() == target:
+                return value
+        return default
+
+    @property
+    def message_id(self) -> str | None:
+        """This message's `Message-ID`, or None when headers were not stored."""
+        return self.header("message-id")
+
     def mark_read(self) -> dict[str, Any]:
         """Mark this message as read, so the next poll can skip it."""
         if self._inbox is None or self.id is None:
@@ -170,14 +193,14 @@ class Inbox:
     def __init__(self, client: "MailFlat", address: str, **meta: Any) -> None:
         self._client = client
         self.address: str = address
-        # create/list yanıtından gelen ek alanlar (varsa)
+        # Extra fields carried by the create/list response, when present.
         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")
-        # backend yanıtının tamamı (Message.raw ile simetrik) — MCP/agent katmanı için.
+        # The full backend payload (symmetric with Message.raw) — used by the MCP/agent layer.
         self.raw: dict[str, Any] = {"address": address, **meta}
 
     def __repr__(self) -> str:
@@ -185,7 +208,7 @@ class Inbox:
 
     # ----------------------------------------------------------------- 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)."""
+        """Convert an API payload into a Message and attach this inbox (for msg.delete())."""
         m = Message.from_dict(data)
         m._inbox = self
         return m
@@ -276,7 +299,8 @@ class Inbox:
         )
         ctype = resp.headers.get("content-type", "")
         if ctype.startswith("application/json"):
-            # Şifreli kutuda sunucu çözemez → zarf JSON'u döner, baytları değil.
+            # On an encrypted inbox the server cannot decrypt: it returns the envelope
+            # JSON rather than the bytes.
             raise EncryptedInboxError(
                 "This inbox is end-to-end encrypted; the server cannot decrypt this attachment."
             )
@@ -302,14 +326,14 @@ class Inbox:
         tracking state on its own.
         """
         return self._client._post(
-            f"/api/v1/inboxes/{self.address}/messages/{message_id}/read")
+            f"/api/v1/inboxes/{self.address}/messages/{message_id}/read", idempotent=True)
 
     def burn(self) -> dict[str, Any]:
         """Delete every message in this inbox and keep the address.
 
         Useful between test scenarios: the address stays registered wherever you used it.
         """
-        return self._client._post(f"/api/v1/inboxes/{self.address}/burn")
+        return self._client._post(f"/api/v1/inboxes/{self.address}/burn", idempotent=True)
 
     def delete(self) -> dict[str, Any]:
         """Delete this inbox and all of its messages. Cannot be undone."""

{mailflat-0.4.0 → mailflat-0.5.0}/src/mailflat/langchain.py

@@ -3,17 +3,15 @@
 A thin LangChain shell over the `mailflat` SDK; all HTTP and behaviour live in the client.
 `langchain-core` is an optional dependency → `pip install mailflat[langchain]`.
 
-NOT: Bu dosya YAYIN yüzeyi (`packages/`) → docstring'ler İngilizce (CLAUDE.md §3 istisnası).
-
 Usage:
     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,
                                   # wait_for_message, send_email, mark_read, burn_inbox,
-                                  # delete_inbox  (delete_message bilerek YOK)
+                                  # delete_inbox  (delete_message is deliberately absent)
 
-⚠️ Araç çıktıları `redact_secrets()`'ten geçer: per-inbox `api_key` modelin bağlamına
-(ve oradan LangSmith trace'lerine) girmemeli — bkz. B-055.
+⚠️ Tool output goes through `redact_secrets()`: a per-inbox `api_key` must never reach the
+model's context (and from there LangSmith traces) — see B-055.
 
 Connected to:
   - imports from: mailflat.client (MailFlat), mailflat.redact, langchain_core.tools
@@ -28,7 +26,7 @@ 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
+except ImportError as exc:  # langchain-core is not installed → explain how to get it
     raise ImportError(
         "MailFlat's LangChain integration requires 'langchain-core'. "
         "Install it with:  pip install mailflat[langchain]"
@@ -57,7 +55,7 @@ class MailFlatToolkit:
         base_url: str = DEFAULT_BASE_URL,
         client: MailFlat | None = None,
     ) -> None:
-        # client enjeksiyonu testleri kolaylaştırır; yoksa api_key ile kurulur.
+        # Injecting a client keeps tests simple; otherwise one is built from api_key.
         self._client = client or MailFlat(api_key=api_key, base_url=base_url)
 
     # ------------------------------------------------------------------ tools
@@ -102,7 +100,7 @@ class MailFlatToolkit:
             try:
                 msgs = client.inbox(address).messages(direction=direction)
                 return redact_secrets({"ok": True, "emails": [m.raw for m in msgs]})
-            except ValueError as e:      # geçersiz direction — ağa çıkmadan
+            except ValueError as e:      # invalid direction — caught before any network call
                 return {"error": str(e)}
             except MailFlatError as e:
                 return {"error": str(e)}
@@ -211,6 +209,6 @@ class MailFlatToolkit:
             burn_inbox,
             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).
+        # from_function derives args_schema from the type hints and docstring itself,
+        # which side-steps the pydantic v1/v2 difference.
         return [StructuredTool.from_function(func=f) for f in funcs]

mailflat-0.5.0/src/mailflat/redact.py

@@ -0,0 +1,58 @@
+"""Strips secret fields from agent tool output (B-055).
+
+Why it exists: `create_inbox` and `list_inboxes` used to return the backend payload as-is,
+and that payload carried a per-inbox `api_key` (`mf_sk_...`). Tool output goes into the
+MODEL's context, and from there into prompt logs, tracing tools (LangSmith, AI SDK
+telemetry), error reports and the model's own later answers. `list_inboxes` leaked every
+inbox key on the account in a single call.
+
+The split is deliberate:
+  - **SDK = code surface.** `Inbox.api_key` stays; code a human wrote may use it.
+  - **Tool = model surface.** Everything passing through here is redacted.
+
+Redaction is **name-based, not value-based**: scanning message bodies for strings starting
+with `mf_` would corrupt a legitimate email that happens to discuss a test key. Matching on
+the field name is both exact and harmless.
+
+Connected to:
+  - imports from: —
+  - imported by:  mailflat.langchain and this package's tests. Within the repo,
+    `packages/mcp` (mailflat-mcp, a separate PyPI package) also imports it — that package
+    is not bundled here, so the reference is repo-level.
+
+Key exports:
+  - `redact_secrets(value)` — copy of the input with secret fields removed
+  - `SECRET_NAME_PARTS` — which field names count as secrets
+"""
+from __future__ import annotations
+
+from typing import Any
+
+#: A field is dropped when its normalised name CONTAINS one of these.
+#: Kept deliberately narrow: `token` is absent on purpose — fields like a domain
+#: `verify_token` are harmless and sometimes useful, and `otp` is the very thing the agent
+#: is after. None of the three below is ever useful to a model.
+SECRET_NAME_PARTS = ("apikey", "secret", "password")
+
+
+def _normalise(key: Any) -> str:
+    return str(key).replace("_", "").replace("-", "").lower()
+
+
+def _is_secret(key: Any) -> bool:
+    name = _normalise(key)
+    return any(part in name for part in SECRET_NAME_PARTS)
+
+
+def redact_secrets(value: Any) -> Any:
+    """Return a copy of `value` with secret fields removed. The input is not modified.
+
+    dict → secret keys dropped, remaining values cleaned recursively
+    list/tuple → every element cleaned (returned as a list; JSON carries a list anyway)
+    anything else → returned unchanged
+    """
+    if isinstance(value, dict):
+        return {k: redact_secrets(v) for k, v in value.items() if not _is_secret(k)}
+    if isinstance(value, (list, tuple)):
+        return [redact_secrets(v) for v in value]
+    return value

mailflat-0.4.0/pyproject.toml

@@ -1,50 +0,0 @@
-[build-system]
-requires = ["hatchling"]
-build-backend = "hatchling.build"
-
-[project]
-name = "mailflat"
-# Sürüm TEK KAYNAKTAN okunur: src/mailflat/__init__.py::__version__ (bkz. [tool.hatch.version]).
-# Buraya elle bir `version = ...` yazmak B-052'yi geri getirir: 0.3.1 yayımlanmışken paketin
-# kendisi `mailflat.__version__ == "0.3.0"` diyordu. İki kaynak = eninde sonunda ayrışma.
-dynamic = ["version"]
-description = "Official Python SDK for MailFlat — disposable, automation-friendly email inboxes with one-line OTP retrieval."
-readme = "README.md"
-requires-python = ">=3.8"
-license = { text = "MIT" }
-authors = [{ name = "MailFlat", email = "support@mailflat.net" }]
-keywords = ["email", "disposable-email", "otp", "automation", "testing", "ai-agents", "temporary-email"]
-classifiers = [
-    "Development Status :: 4 - Beta",
-    "Intended Audience :: Developers",
-    "License :: OSI Approved :: MIT License",
-    "Programming Language :: Python :: 3",
-    "Programming Language :: Python :: 3 :: Only",
-    "Topic :: Communications :: Email",
-    "Topic :: Software Development :: Testing",
-    "Typing :: Typed",
-]
-# ÜST SINIR: httpx henüz 1.0 ÖNCESİ ve 1.0 ilan edilmiş bir kırılma eşiği. Sınırsız bırakmak
-# B-047'nin (mcp>=1.2 → mcp 2.0.0 modülü kaldırdı → uvx mailflat-mcp çöktü) aynısına davetiye.
-# Bugün 0.28.1 ile sorunsuz; sınır 1.0 çıkınca bilinçli olarak yükseltilecek.
-dependencies = ["httpx>=0.24,<1"]
-
-[project.urls]
-Homepage = "https://mailflat.net"
-# /docs prod'da kapalı (FastAPI Swagger yüzeyi, bkz. app/main.py::_openapi_urls).
-# Public doküman sayfası açılınca burası oraya güncellenecek.
-Documentation = "https://mailflat.net"
-Source = "https://github.com/onderyentar/mailflat"
-
-[project.optional-dependencies]
-langchain = ["langchain-core>=0.2"]
-dev = ["pytest>=7", "respx>=0.20", "langchain-core>=0.2"]
-
-[tool.hatch.version]
-path = "src/mailflat/__init__.py"
-
-[tool.hatch.build.targets.wheel]
-packages = ["src/mailflat"]
-
-[tool.hatch.build.targets.sdist]
-include = ["src/mailflat", "README.md", "LICENSE"]

mailflat-0.4.0/src/mailflat/redact.py

@@ -1,60 +0,0 @@
-"""Strips secret fields from agent tool output (B-055).
-
-Neden var: `create_inbox` ve `list_inboxes` backend yanıtını olduğu gibi döndürüyordu ve o
-yanıtta per-inbox `api_key` (`mf_sk_…`) vardı. Araç çıktısı **model bağlamına** giriyor;
-oradan prompt loglarına, trace araçlarına (LangSmith, AI SDK telemetry), hata raporlarına ve
-modelin sonraki cevaplarına geçiyor. `list_inboxes` tek çağrıda hesabın **tüm** inbox
-anahtarlarını döküyordu.
-
-Ayrım bilinçli:
-  - **SDK = kod yüzeyi.** `Inbox.api_key` duruyor; insanın yazdığı kod onu kullanabilir.
-  - **Tool = model yüzeyi.** Buradan geçen her şey redakte edilir.
-
-Yöntem **isim bazlı**, değer bazlı değil: mesaj gövdesini tarayıp `mf_` ile başlayan
-string'leri silmek, kullanıcının kendi test anahtarını konu ettiği bir maili bozardı. Alan
-adına bakmak hem kesin hem zararsız.
-
-NOT: Bu dosya YAYIN yüzeyi (`packages/`) → docstring'ler İngilizce (CLAUDE.md §3 istisnası).
-
-Connected to:
-  - imports from: —
-  - imported by:  mailflat.langchain, mailflat's own tests. AYRICA repo içinde
-    `packages/mcp` (mailflat-mcp, ayrı PyPI paketi) buradan import eder — bu paketin
-    kendi içinde MCP yoktur, o yüzden referans repo düzeyindedir.
-
-Key exports:
-  - `redact_secrets(value)` — copy of the input with secret fields removed
-  - `SECRET_NAME_PARTS` — which field names count as secrets
-"""
-from __future__ import annotations
-
-from typing import Any
-
-#: Normalize edilmiş alan adı bunlardan birini İÇERİYORSA alan atılır.
-#: Dar tutuldu: `token` bilerek YOK — domain `verify_token` gibi alanlar zararsız ve
-#: gerektiğinde işe yarar, `otp` ise ajanın asıl istediği şey. Buradaki üçünün hiçbiri
-#: modele bir fayda sağlamıyor.
-SECRET_NAME_PARTS = ("apikey", "secret", "password")
-
-
-def _normalise(key: Any) -> str:
-    return str(key).replace("_", "").replace("-", "").lower()
-
-
-def _is_secret(key: Any) -> bool:
-    name = _normalise(key)
-    return any(part in name for part in SECRET_NAME_PARTS)
-
-
-def redact_secrets(value: Any) -> Any:
-    """Return a copy of `value` with secret fields removed. The input is not modified.
-
-    dict → secret keys dropped, remaining values cleaned recursively
-    list/tuple → every element cleaned (returned as a list; JSON carries a list anyway)
-    anything else → returned unchanged
-    """
-    if isinstance(value, dict):
-        return {k: redact_secrets(v) for k, v in value.items() if not _is_secret(k)}
-    if isinstance(value, (list, tuple)):
-        return [redact_secrets(v) for v in value]
-    return value