mailsocket 0.1.0__tar.gz → 0.1.2__tar.gz

{mailsocket-0.1.0 → mailsocket-0.1.2}/PKG-INFO

@@ -1,11 +1,13 @@
 Metadata-Version: 2.4
 Name: mailsocket
-Version: 0.1.0
+Version: 0.1.2
 Summary: Official Python client for the mailsocket REST API — one line to wait for an OTP.
 Author: mailsocket
 License-Expression: MIT
 Project-URL: Homepage, https://mailsocket.app
 Project-URL: Documentation, https://dash.mailsocket.app/docs
+Project-URL: Source, https://github.com/mailsocket/mailsocket-sdk/tree/main/python
+Project-URL: Issues, https://github.com/mailsocket/mailsocket-sdk/issues
 Keywords: mailsocket,email,otp,inbox,magic-link
 Classifier: Intended Audience :: Developers
 Classifier: Operating System :: OS Independent
@@ -70,11 +72,21 @@ client = Client(api_key, base_url="https://dash.mailsocket.app/api/v1")
 ### The moat
 
 ```python
-result = client.wait_for_otp(inbox_id, *, timeout=60, min_confidence=0.0, since=0) -> WaitResult
-result = client.wait_for_link(inbox_id, *, timeout=60, since=0)                       -> WaitResult
-result = client.wait(inbox_id, *, timeout=60, min_confidence=0.0, since=0)            -> WaitResult  # otp OR link
+result = client.wait_for_otp("inbox_abc123", timeout=60, min_confidence=0.0, since=0)
+result = client.wait_for_link("inbox_abc123", timeout=60, since=0)
+result = client.wait("inbox_abc123", timeout=60, min_confidence=0.0, since=0)  # otp OR link
 ```
 
+All three return a `WaitResult` and take keyword-only arguments after
+`inbox_id`. `timeout`/`min_confidence`/`since` shown above are the defaults —
+call with no extra arguments for the common case.
+
+| Method | Keyword args (all optional, keyword-only) | Returns |
+| --- | --- | --- |
+| `wait_for_otp(inbox_id, ...)` | `timeout=60`, `min_confidence=0.0`, `since=0` | `WaitResult` |
+| `wait_for_link(inbox_id, ...)` | `timeout=60`, `since=0` | `WaitResult` |
+| `wait(inbox_id, ...)` | `timeout=60`, `min_confidence=0.0`, `since=0` | `WaitResult` (otp OR link) |
+
 `WaitResult` exposes `.otp`, `.confidence`, `.magic_link` (and `.link` as an
 alias), plus the full `.message` dict. `str(result)` is the OTP (or the link).
 
@@ -100,7 +112,7 @@ Semantics:
 ## Develop
 
 ```bash
-cd sdks/python
+cd python
 python -m pytest -q
 ```
 

{mailsocket-0.1.0 → mailsocket-0.1.2}/README.md

@@ -46,11 +46,21 @@ client = Client(api_key, base_url="https://dash.mailsocket.app/api/v1")
 ### The moat
 
 ```python
-result = client.wait_for_otp(inbox_id, *, timeout=60, min_confidence=0.0, since=0) -> WaitResult
-result = client.wait_for_link(inbox_id, *, timeout=60, since=0)                       -> WaitResult
-result = client.wait(inbox_id, *, timeout=60, min_confidence=0.0, since=0)            -> WaitResult  # otp OR link
+result = client.wait_for_otp("inbox_abc123", timeout=60, min_confidence=0.0, since=0)
+result = client.wait_for_link("inbox_abc123", timeout=60, since=0)
+result = client.wait("inbox_abc123", timeout=60, min_confidence=0.0, since=0)  # otp OR link
 ```
 
+All three return a `WaitResult` and take keyword-only arguments after
+`inbox_id`. `timeout`/`min_confidence`/`since` shown above are the defaults —
+call with no extra arguments for the common case.
+
+| Method | Keyword args (all optional, keyword-only) | Returns |
+| --- | --- | --- |
+| `wait_for_otp(inbox_id, ...)` | `timeout=60`, `min_confidence=0.0`, `since=0` | `WaitResult` |
+| `wait_for_link(inbox_id, ...)` | `timeout=60`, `since=0` | `WaitResult` |
+| `wait(inbox_id, ...)` | `timeout=60`, `min_confidence=0.0`, `since=0` | `WaitResult` (otp OR link) |
+
 `WaitResult` exposes `.otp`, `.confidence`, `.magic_link` (and `.link` as an
 alias), plus the full `.message` dict. `str(result)` is the OTP (or the link).
 
@@ -76,7 +86,7 @@ Semantics:
 ## Develop
 
 ```bash
-cd sdks/python
+cd python
 python -m pytest -q
 ```
 

{mailsocket-0.1.0 → mailsocket-0.1.2}/mailsocket/__init__.py

@@ -3,7 +3,7 @@
 from .client import Client, Page, WaitResult
 from .errors import AuthError, MailsocketError, NotFound, RateLimited, WaitTimeout
 
-__version__ = "0.1.0"
+__version__ = "0.1.2"
 
 __all__ = [
     "Client",

{mailsocket-0.1.0 → mailsocket-0.1.2}/mailsocket/client.py

@@ -29,6 +29,18 @@ def _sleep(seconds: float) -> None:
     _time.sleep(seconds)
 
 
+def _seg(value) -> str:
+    """Percent-encode an id as ONE path segment (``/``, ``?``, ``#``, ``..`` safe).
+
+    ``quote`` leaves ``.`` alone (unreserved), so a bare ``.``/``..`` segment
+    is additionally encoded as ``%2E`` so no proxy can treat it as traversal.
+    """
+    encoded = urllib.parse.quote(str(value), safe="")
+    if encoded in (".", ".."):
+        encoded = encoded.replace(".", "%2E")
+    return encoded
+
+
 class Page:
     """A page of results plus its pagination metadata.
 
@@ -94,12 +106,32 @@ class Client:
         base_url: str = DEFAULT_BASE_URL,
         *,
         request_timeout: float = 30.0,
+        extra_headers: dict[str, str] | None = None,
+        retry_wait_on_429: bool = True,
     ):
+        """Create a client.
+
+        ``extra_headers`` (optional) are sent on every request, e.g. a fixed
+        ``Host`` when calling the API through an internal address. They can
+        never override ``Authorization``; that header always carries
+        ``api_key``.
+
+        ``retry_wait_on_429`` (default True): the ``wait*`` helpers sleep for
+        ``Retry-After`` and retry on HTTP 429 until their deadline. Pass False
+        to raise :class:`RateLimited` immediately instead (used by the shared
+        remote MCP server so a rate-limited caller doesn't hold a worker slot).
+        """
         if not api_key:
             raise ValueError("api_key is required")
         self._api_key = api_key
         self._base_url = base_url.rstrip("/")
         self._request_timeout = request_timeout
+        self._retry_wait_on_429 = retry_wait_on_429
+        self._extra_headers = {
+            str(name): str(value)
+            for name, value in (extra_headers or {}).items()
+            if str(name).lower() != "authorization"
+        }
 
     # -- public API -----------------------------------------------------------
 
@@ -113,11 +145,11 @@ class Client:
         return Page(payload["data"], payload.get("pagination"))
 
     def get_inbox(self, inbox_id: str) -> dict:
-        payload = self._request("GET", f"/inboxes/{inbox_id}")
+        payload = self._request("GET", f"/inboxes/{_seg(inbox_id)}")
         return payload["data"]
 
     def delete_inbox(self, inbox_id: str) -> None:
-        self._request("DELETE", f"/inboxes/{inbox_id}")
+        self._request("DELETE", f"/inboxes/{_seg(inbox_id)}")
 
     def list_messages(
         self,
@@ -135,15 +167,15 @@ class Client:
             params["subject_contains"] = subject_contains
         if sender:
             params["from"] = sender  # the API names this filter ``from``
-        payload = self._request("GET", f"/inboxes/{inbox_id}/messages", params=params)
+        payload = self._request("GET", f"/inboxes/{_seg(inbox_id)}/messages", params=params)
         return Page(payload["data"], payload.get("pagination"))
 
     def get_latest(self, inbox_id: str) -> dict:
-        payload = self._request("GET", f"/inboxes/{inbox_id}/messages/latest")
+        payload = self._request("GET", f"/inboxes/{_seg(inbox_id)}/messages/latest")
         return payload["data"]
 
     def get_message(self, message_id: str) -> dict:
-        payload = self._request("GET", f"/messages/{message_id}")
+        payload = self._request("GET", f"/messages/{_seg(message_id)}")
         return payload["data"]
 
     # -- the moat -------------------------------------------------------------
@@ -215,7 +247,7 @@ class Client:
 
             status, headers, body = self._request_http(
                 "GET",
-                f"/inboxes/{inbox_id}/messages/wait",
+                f"/inboxes/{_seg(inbox_id)}/messages/wait",
                 params=params,
                 socket_timeout=server_timeout + WAIT_SOCKET_BUFFER,
             )
@@ -225,6 +257,8 @@ class Client:
             if status == 204:
                 continue
             if status == 429:
+                if not self._retry_wait_on_429:
+                    self._raise_for_status(status, headers, payload)
                 retry_after = self._retry_after(headers)
                 sleep_for = retry_after if retry_after is not None else DEFAULT_RETRY_AFTER
                 if _monotonic() + sleep_for > deadline:
@@ -247,10 +281,12 @@ class Client:
         if params:
             url += "?" + urllib.parse.urlencode(params, doseq=True)
         headers = {
-            "Authorization": f"Bearer {self._api_key}",
             "Accept": "application/json",
-            "User-Agent": "mailsocket-python/0.1.0",
+            "User-Agent": "mailsocket-python/0.1.2",
         }
+        headers.update(self._extra_headers)
+        # Set last so nothing in extra_headers can ever replace it.
+        headers["Authorization"] = f"Bearer {self._api_key}"
         data = None
         if json_body is not None:
             data = json.dumps(json_body).encode("utf-8")

{mailsocket-0.1.0 → mailsocket-0.1.2}/mailsocket.egg-info/PKG-INFO

@@ -1,11 +1,13 @@
 Metadata-Version: 2.4
 Name: mailsocket
-Version: 0.1.0
+Version: 0.1.2
 Summary: Official Python client for the mailsocket REST API — one line to wait for an OTP.
 Author: mailsocket
 License-Expression: MIT
 Project-URL: Homepage, https://mailsocket.app
 Project-URL: Documentation, https://dash.mailsocket.app/docs
+Project-URL: Source, https://github.com/mailsocket/mailsocket-sdk/tree/main/python
+Project-URL: Issues, https://github.com/mailsocket/mailsocket-sdk/issues
 Keywords: mailsocket,email,otp,inbox,magic-link
 Classifier: Intended Audience :: Developers
 Classifier: Operating System :: OS Independent
@@ -70,11 +72,21 @@ client = Client(api_key, base_url="https://dash.mailsocket.app/api/v1")
 ### The moat
 
 ```python
-result = client.wait_for_otp(inbox_id, *, timeout=60, min_confidence=0.0, since=0) -> WaitResult
-result = client.wait_for_link(inbox_id, *, timeout=60, since=0)                       -> WaitResult
-result = client.wait(inbox_id, *, timeout=60, min_confidence=0.0, since=0)            -> WaitResult  # otp OR link
+result = client.wait_for_otp("inbox_abc123", timeout=60, min_confidence=0.0, since=0)
+result = client.wait_for_link("inbox_abc123", timeout=60, since=0)
+result = client.wait("inbox_abc123", timeout=60, min_confidence=0.0, since=0)  # otp OR link
 ```
 
+All three return a `WaitResult` and take keyword-only arguments after
+`inbox_id`. `timeout`/`min_confidence`/`since` shown above are the defaults —
+call with no extra arguments for the common case.
+
+| Method | Keyword args (all optional, keyword-only) | Returns |
+| --- | --- | --- |
+| `wait_for_otp(inbox_id, ...)` | `timeout=60`, `min_confidence=0.0`, `since=0` | `WaitResult` |
+| `wait_for_link(inbox_id, ...)` | `timeout=60`, `since=0` | `WaitResult` |
+| `wait(inbox_id, ...)` | `timeout=60`, `min_confidence=0.0`, `since=0` | `WaitResult` (otp OR link) |
+
 `WaitResult` exposes `.otp`, `.confidence`, `.magic_link` (and `.link` as an
 alias), plus the full `.message` dict. `str(result)` is the OTP (or the link).
 
@@ -100,7 +112,7 @@ Semantics:
 ## Develop
 
 ```bash
-cd sdks/python
+cd python
 python -m pytest -q
 ```
 

{mailsocket-0.1.0 → mailsocket-0.1.2}/pyproject.toml

@@ -4,7 +4,7 @@ build-backend = "setuptools.build_meta"
 
 [project]
 name = "mailsocket"
-version = "0.1.0"
+version = "0.1.2"
 description = "Official Python client for the mailsocket REST API — one line to wait for an OTP."
 readme = "README.md"
 requires-python = ">=3.9"
@@ -30,6 +30,8 @@ dev = ["pytest>=7"]
 [project.urls]
 Homepage = "https://mailsocket.app"
 Documentation = "https://dash.mailsocket.app/docs"
+Source = "https://github.com/mailsocket/mailsocket-sdk/tree/main/python"
+Issues = "https://github.com/mailsocket/mailsocket-sdk/issues"
 
 [tool.setuptools]
 packages = ["mailsocket"]

{mailsocket-0.1.0 → mailsocket-0.1.2}/tests/test_client.py

@@ -199,6 +199,91 @@ def test_wait_429_parses_subcode_and_retries(monkeypatch):
     assert len(transport.calls) == 2
 
 
+HOSTILE_IDS = [
+    ("in?x=1", "in%3Fx%3D1"),
+    ("in#frag", "in%23frag"),
+    ("../../admin", "..%2F..%2Fadmin"),
+    ("..", "%2E%2E"),
+    (".", "%2E"),
+    ("a/b", "a%2Fb"),
+    ("sp ce&%", "sp%20ce%26%25"),
+]
+
+
+@pytest.mark.parametrize("raw, encoded", HOSTILE_IDS)
+def test_ids_are_quoted_as_one_path_segment_everywhere(monkeypatch, raw, encoded):
+    """opus P3-2: every id interpolated into a URL path is quote(..., safe="")."""
+    import urllib.parse
+
+    page = {"data": [], "pagination": {}}
+    responses = [
+        (200, {}, {"data": {"id": "x"}}),  # get_inbox
+        (204, {}, None),  # delete_inbox
+        (200, {}, page),  # list_messages
+        (200, {}, {"data": {"id": "x"}}),  # get_latest
+        (200, {}, {"data": {"id": "x"}}),  # get_message
+        (200, {}, {"data": OTP_MESSAGE}),  # wait_for_otp
+        (200, {}, {"data": LINK_MESSAGE}),  # wait_for_link
+        (200, {}, {"data": OTP_MESSAGE}),  # wait
+    ]
+    client, transport = make_client(responses)
+    _monkeypatch_transport(monkeypatch, client, transport)
+
+    client.get_inbox(raw)
+    client.delete_inbox(raw)
+    client.list_messages(raw, has_otp=True)
+    client.get_latest(raw)
+    client.get_message(raw)
+    client.wait_for_otp(raw, timeout=5)
+    client.wait_for_link(raw, timeout=5)
+    client.wait(raw, timeout=5)
+
+    expected_paths = [
+        f"/api/v1/inboxes/{encoded}",
+        f"/api/v1/inboxes/{encoded}",
+        f"/api/v1/inboxes/{encoded}/messages",
+        f"/api/v1/inboxes/{encoded}/messages/latest",
+        f"/api/v1/messages/{encoded}",
+        f"/api/v1/inboxes/{encoded}/messages/wait",
+        f"/api/v1/inboxes/{encoded}/messages/wait",
+        f"/api/v1/inboxes/{encoded}/messages/wait",
+    ]
+    assert len(transport.calls) == len(expected_paths)
+    for (_, url), expected in zip(transport.calls, expected_paths):
+        parts = urllib.parse.urlsplit(url)
+        assert parts.netloc == "example.test"
+        assert parts.path == expected, url
+        assert parts.fragment == ""
+        # the id never leaks into the query string
+        assert "x=1" not in parts.query and "frag" not in parts.query
+    # a normal id is unchanged
+    assert mailsocket.client._seg("inbox_abc123") == "inbox_abc123"
+
+
+def test_wait_429_raises_immediately_when_retry_disabled(monkeypatch):
+    """retry_wait_on_429=False (remote MCP): no sleep, one call, RateLimited."""
+    slept = []
+    monkeypatch.setattr(mailsocket.client, "_sleep", lambda s: slept.append(s))
+    responses = [
+        (
+            429,
+            {"Retry-After": "2"},
+            {"error": {"code": "too_many_wait_requests", "message": "Too many", "fields": {}}},
+        ),
+        (200, {}, {"data": OTP_MESSAGE}),
+    ]
+    client, transport = make_client(responses, retry_wait_on_429=False)
+    _monkeypatch_transport(monkeypatch, client, transport)
+
+    with pytest.raises(RateLimited) as exc_info:
+        client.wait_for_otp("inbox_abc", timeout=60)
+
+    assert exc_info.value.subcode == "too_many_wait_requests"
+    assert exc_info.value.retry_after == 2.0
+    assert len(transport.calls) == 1
+    assert slept == []
+
+
 def test_wait_429_raises_rate_limited_with_subcode_on_non_wait_endpoint(monkeypatch):
     responses = [
         (
@@ -354,3 +439,88 @@ def test_error_types_are_mailsocket_subclasses():
 
 def test_version_exported():
     assert hasattr(mailsocket, "__version__")
+
+
+def test_metadata_consistency_across_files():
+    """0.1.2 must match everywhere: pyproject, __version__, user agent."""
+    import re
+    import tomllib
+    from pathlib import Path
+
+    root = Path(__file__).resolve().parents[1]
+    expected = "0.1.2"
+
+    pyproject = tomllib.loads((root / "pyproject.toml").read_text())
+    assert pyproject["project"]["version"] == expected
+    assert mailsocket.__version__ == expected
+
+    client_src = (root / "mailsocket" / "client.py").read_text()
+    match = re.search(r'"mailsocket-python/([^"]+)"', client_src)
+    assert match, "User-Agent literal not found in client.py"
+    assert match.group(1) == expected
+
+
+# -- extra_headers ------------------------------------------------------------
+
+
+class _HeaderCapture:
+    def __init__(self):
+        self.headers = []
+
+    def __call__(self, request, timeout=None):
+        self.headers.append({k.lower(): v for k, v in request.header_items()})
+
+        class _Resp:
+            headers = {}
+
+            def getcode(self):
+                return 200
+
+            def read(self):
+                return json.dumps({"data": {"id": "inbox_1"}}).encode()
+
+            def __enter__(self):
+                return self
+
+            def __exit__(self, *exc_info):
+                return False
+
+        return _Resp()
+
+
+def test_extra_headers_are_sent(monkeypatch):
+    capture = _HeaderCapture()
+    monkeypatch.setattr("urllib.request.urlopen", capture)
+    client = Client(
+        "ms_live_test1234567890",
+        base_url="http://web:8000/api/v1",
+        extra_headers={"Host": "dash.mailsocket.app", "X-Forwarded-Proto": "https"},
+    )
+    client.get_inbox("inbox_1")
+    sent = capture.headers[0]
+    assert sent["host"] == "dash.mailsocket.app"
+    assert sent["x-forwarded-proto"] == "https"
+    assert sent["authorization"] == "Bearer ms_live_test1234567890"
+
+
+@pytest.mark.parametrize("name", ["Authorization", "authorization", "AUTHORIZATION"])
+def test_extra_headers_cannot_override_authorization(monkeypatch, name):
+    capture = _HeaderCapture()
+    monkeypatch.setattr("urllib.request.urlopen", capture)
+    client = Client(
+        "ms_live_test1234567890",
+        base_url="https://example.test/api/v1",
+        extra_headers={name: "Bearer ms_live_ATTACKER_KEY_000"},
+    )
+    client.get_inbox("inbox_1")
+    auths = [v for k, v in capture.headers[0].items() if k == "authorization"]
+    assert auths == ["Bearer ms_live_test1234567890"]
+
+
+def test_no_extra_headers_is_backwards_compatible(monkeypatch):
+    capture = _HeaderCapture()
+    monkeypatch.setattr("urllib.request.urlopen", capture)
+    Client("ms_live_test1234567890", base_url="https://example.test/api/v1").get_inbox("i")
+    sent = capture.headers[0]
+    assert set(sent) >= {"authorization", "accept", "user-agent"}
+    assert "x-forwarded-proto" not in sent