mailflat 0.4.0__tar.gz → 0.4.1__tar.gz

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

@@ -1,6 +1,6 @@
 Metadata-Version: 2.4
 Name: mailflat
-Version: 0.4.0
+Version: 0.4.1
 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.4.1}/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.4.0 → mailflat-0.4.1}/pyproject.toml

@@ -10,7 +10,7 @@ name = "mailflat"
 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"
+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"]
@@ -20,6 +20,16 @@ classifiers = [
     "License :: OSI Approved :: MIT License",
     "Programming Language :: Python :: 3",
     "Programming Language :: Python :: 3 :: Only",
+    # Aralığın İKİ UCU gerçekten koşuldu (3.11 + 3.14, 53 test yeşil). Aradaki sürümler için
+    # ayrı bir iddia yok: sürüme özgü API kullanmıyoruz ve `from __future__ import annotations`
+    # her dosyada var. Alt sınır 3.8 → 3.9: 3.8 EOL ve HİÇ test edilmedi; test edilmemiş bir
+    # sürümü desteklediğini söylemek, PyPI'da kullanıcıyı yanlış filtrelemeye götürür.
+    "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",

{mailflat-0.4.0 → mailflat-0.4.1}/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
@@ -15,6 +13,12 @@ Key exports:
     `NotFoundError`, `RateLimitError`, `APIError`, `OTPTimeoutError`, `EncryptedInboxError`
   - `redact_secrets()` — strips secret fields from agent tool output (used by MCP/LangChain)
 """
+# NOT: `packages/` YAYIN yüzeyi → docstring'ler İngilizce (CLAUDE.md §3).
+# Bu satırın kendisi bilerek YORUM: aynı notu docstring'e koymak tam da kaçındığımız
+# şeydi — `help()` docstring'i basar, yorumu basmaz.
+# NOT: `packages/` YAYIN yüzeyi → docstring'ler İngilizce (CLAUDE.md §3).
+# Bu satır bilerek YORUM: docstring'e Türkçe not koymak, tam da kaçındığımız şeydi —
+# `help()` docstring'i basar, yorumu basmaz.
 from __future__ import annotations
 
 from .client import MailFlat
@@ -34,7 +38,7 @@ 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"
+__version__ = "0.4.1"
 
 __all__ = [
     "MailFlat",

{mailflat-0.4.0 → mailflat-0.4.1}/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__
@@ -15,6 +13,12 @@ Key exports:
   - `.list()` — list of `Inbox`
   - `.inbox(address)` — attach to an existing address
 """
+# NOT: `packages/` YAYIN yüzeyi → docstring'ler İngilizce (CLAUDE.md §3).
+# Bu satırın kendisi bilerek YORUM: aynı notu docstring'e koymak tam da kaçındığımız
+# şeydi — `help()` docstring'i basar, yorumu basmaz.
+# NOT: `packages/` YAYIN yüzeyi → docstring'ler İngilizce (CLAUDE.md §3).
+# Bu satır bilerek YORUM: docstring'e Türkçe not koymak, tam da kaçındığımız şeydi —
+# `help()` docstring'i basar, yorumu basmaz.
 from __future__ import annotations
 
 import logging
@@ -41,11 +45,9 @@ 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."""
+    # Sunucu "12 saniye bekle" derken 1 saniyede dönmek hem 429'u tekrar yemek hem de
+    # rate limit penceresini uzatmak demekti.
     raw = resp.headers.get("Retry-After")
     if not raw:
         return None
@@ -95,9 +97,9 @@ class MailFlat:
     def user_agent() -> str:
         """Return the `User-Agent` this client sends, e.g. `mailflat-python/0.4.0`.
 
-        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.
         """
+        # Sürüm burada okunuyor ki modül seviyesinde döngüsel import oluşmasın.
         from . import __version__
 
         return f"mailflat-python/{__version__}"
@@ -113,7 +115,13 @@ class MailFlat:
         self._http.close()
 
     # --------------------------------------------------------------- HTTP iç
-    def _request(self, method: str, path: str, json: dict[str, Any] | None = None) -> dict[str, Any]:
+    def _request(self, method: str, path: str, json: dict[str, Any] | None = None,
+                 *, idempotent: bool | None = None) -> dict[str, Any]:
+        """`idempotent=True` → metodu ne olursa olsun retry edilebilir sayılır.
+
+        mark_read/burn POST ama tekrarı zararsız (aynı sonuç). send için ASLA verilmez:
+        tekrarlanan bir send aynı maili ikinci kez teslim eder (B-058).
+        """
         attempt = 0
         while True:
             try:
@@ -122,9 +130,10 @@ class MailFlat:
                 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:
@@ -155,18 +164,34 @@ class MailFlat:
     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:

{mailflat-0.4.0 → mailflat-0.4.1}/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__
 
@@ -16,6 +13,9 @@ Key exports:
   - `OTPTimeoutError` — wait_for_otp / wait_for_message timed out
   - `EncryptedInboxError` — end-to-end encrypted inbox cannot be read through the API
 """
+# NOT: `packages/` YAYIN yüzeyi → docstring'ler İngilizce (CLAUDE.md §3).
+# Bu satırın kendisi bilerek YORUM: aynı notu docstring'e koymak tam da kaçındığımız
+# şeydi — `help()` docstring'i basar, yorumu basmaz.
 from __future__ import annotations
 
 

{mailflat-0.4.0 → mailflat-0.4.1}/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__
@@ -15,6 +13,9 @@ Key exports:
   - `Message` — `.otp`, `.subject`, `.text`, `.html`, `.links`, `.attachments`, `.spam`, ...
   - `Attachment` — `.filename`, `.size_bytes`, `.download()`
 """
+# NOT: `packages/` YAYIN yüzeyi → docstring'ler İngilizce (CLAUDE.md §3).
+# Bu satırın kendisi bilerek YORUM: aynı notu docstring'e koymak tam da kaçındığımız
+# şeydi — `help()` docstring'i basar, yorumu basmaz.
 from __future__ import annotations
 
 import time
@@ -26,8 +27,8 @@ from .errors import EncryptedInboxError, MailFlatError, OTPTimeoutError
 if TYPE_CHECKING:  # döngüsel import'tan kaçın (sadece tip ipucu)
     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.
+# Yön filtreleri (sunucu sözleşmesi). "in" varsayılan: bir ajan için "mesaj geldi mi"
+# sorusuna kendi gönderdiği mail cevap olamaz. (Yorum — help() çıktısına girmez.)
 DIRECTIONS = ("in", "out", "all")
 
 
@@ -41,7 +42,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,8 +106,11 @@ 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.
@@ -123,6 +128,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:
@@ -302,14 +327,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.4.1}/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
@@ -22,6 +20,9 @@ Connected to:
 Key exports:
   - `MailFlatToolkit(api_key=..., base_url=...)` — `.get_tools()` → list[BaseTool]
 """
+# NOT: `packages/` YAYIN yüzeyi → docstring'ler İngilizce (CLAUDE.md §3).
+# Bu satırın kendisi bilerek YORUM: aynı notu docstring'e koymak tam da kaçındığımız
+# şeydi — `help()` docstring'i basar, yorumu basmaz.
 from __future__ import annotations
 
 from typing import TYPE_CHECKING, Any

{mailflat-0.4.0 → mailflat-0.4.1}/src/mailflat/redact.py

@@ -1,31 +1,32 @@
 """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.
+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.
 
-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.
+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.
 
-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ı).
+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, 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.
+  - 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
 """
+# NOT: `packages/` YAYIN yüzeyi → docstring'ler İngilizce (CLAUDE.md §3).
+# Bu satırın kendisi bilerek YORUM: aynı notu docstring'e koymak tam da kaçındığımız
+# şeydi — `help()` docstring'i basar, yorumu basmaz.
 from __future__ import annotations
 
 from typing import Any