mailsocket 0.1.1__tar.gz → 0.1.3__tar.gz

{mailsocket-0.1.1 → mailsocket-0.1.3}/PKG-INFO

@@ -1,6 +1,6 @@
 Metadata-Version: 2.4
 Name: mailsocket
-Version: 0.1.1
+Version: 0.1.3
 Summary: Official Python client for the mailsocket REST API — one line to wait for an OTP.
 Author: mailsocket
 License-Expression: MIT
@@ -112,9 +112,15 @@ Semantics:
 ## Develop
 
 ```bash
-cd sdks/python
+cd python
 python -m pytest -q
 ```
 
-Tests are fully offline — they monkeypatch `urllib.request.urlopen` with a
-scripted responder, so nothing touches the live API.
+Tests make no external or live-API requests. Most monkeypatch
+`urllib.request.urlopen` with a scripted responder, and a few start a real local
+`http.server` on `127.0.0.1` to check actual request behaviour, e.g. that an
+invalid id never reaches the network.
+
+## Changelog
+
+- **0.1.3** — `_seg` now rejects an empty id or a bare `.`/`..` id with a `MailsocketError` (`code="invalid_id"`) before any request is made, matching the TypeScript SDK's contract.

{mailsocket-0.1.1 → mailsocket-0.1.3}/README.md

@@ -86,9 +86,15 @@ Semantics:
 ## Develop
 
 ```bash
-cd sdks/python
+cd python
 python -m pytest -q
 ```
 
-Tests are fully offline — they monkeypatch `urllib.request.urlopen` with a
-scripted responder, so nothing touches the live API.
+Tests make no external or live-API requests. Most monkeypatch
+`urllib.request.urlopen` with a scripted responder, and a few start a real local
+`http.server` on `127.0.0.1` to check actual request behaviour, e.g. that an
+invalid id never reaches the network.
+
+## Changelog
+
+- **0.1.3** — `_seg` now rejects an empty id or a bare `.`/`..` id with a `MailsocketError` (`code="invalid_id"`) before any request is made, matching the TypeScript SDK's contract.

{mailsocket-0.1.1 → mailsocket-0.1.3}/mailsocket/__init__.py

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

{mailsocket-0.1.1 → mailsocket-0.1.3}/mailsocket/client.py

@@ -29,6 +29,24 @@ def _sleep(seconds: float) -> None:
     _time.sleep(seconds)
 
 
+def _seg(value) -> str:
+    """Percent-encode an id as ONE path segment (``/``, ``?``, ``#``, ``..`` safe).
+
+    An empty id and the bare dot segments ``.`` / ``..`` are rejected with a
+    :class:`MailsocketError` before any request is made (same contract as the
+    TypeScript SDK's ``seg``): urllib's request machinery would otherwise let
+    them collapse into a different path than the caller intended. No real id
+    is ever one of these.
+    """
+    raw = str(value)
+    if raw in ("", ".", ".."):
+        raise MailsocketError(
+            f"Invalid id {raw!r}: ids must be non-empty and not \".\" or \"..\".",
+            code="invalid_id",
+        )
+    return urllib.parse.quote(raw, safe="")
+
+
 class Page:
     """A page of results plus its pagination metadata.
 
@@ -94,12 +112,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 +151,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 +173,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 +253,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 +263,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 +287,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.1",
+            "User-Agent": "mailsocket-python/0.1.3",
         }
+        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.1 → mailsocket-0.1.3}/mailsocket.egg-info/PKG-INFO

@@ -1,6 +1,6 @@
 Metadata-Version: 2.4
 Name: mailsocket
-Version: 0.1.1
+Version: 0.1.3
 Summary: Official Python client for the mailsocket REST API — one line to wait for an OTP.
 Author: mailsocket
 License-Expression: MIT
@@ -112,9 +112,15 @@ Semantics:
 ## Develop
 
 ```bash
-cd sdks/python
+cd python
 python -m pytest -q
 ```
 
-Tests are fully offline — they monkeypatch `urllib.request.urlopen` with a
-scripted responder, so nothing touches the live API.
+Tests make no external or live-API requests. Most monkeypatch
+`urllib.request.urlopen` with a scripted responder, and a few start a real local
+`http.server` on `127.0.0.1` to check actual request behaviour, e.g. that an
+invalid id never reaches the network.
+
+## Changelog
+
+- **0.1.3** — `_seg` now rejects an empty id or a bare `.`/`..` id with a `MailsocketError` (`code="invalid_id"`) before any request is made, matching the TypeScript SDK's contract.

{mailsocket-0.1.1 → mailsocket-0.1.3}/pyproject.toml

@@ -4,7 +4,7 @@ build-backend = "setuptools.build_meta"
 
 [project]
 name = "mailsocket"
-version = "0.1.1"
+version = "0.1.3"
 description = "Official Python client for the mailsocket REST API — one line to wait for an OTP."
 readme = "README.md"
 requires-python = ">=3.9"

{mailsocket-0.1.1 → mailsocket-0.1.3}/tests/test_client.py

@@ -199,6 +199,89 @@ 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"),
+    ("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 = [
         (
@@ -352,18 +435,88 @@ def test_error_types_are_mailsocket_subclasses():
     assert issubclass(WaitTimeout, MailsocketError)
 
 
+# -- F2: _seg rejects "" / "." / ".." before any request (parity with TS) -----
+
+
+def test_seg_rejects_empty_and_dot_segments():
+    for raw in ("", ".", ".."):
+        with pytest.raises(MailsocketError) as exc_info:
+            mailsocket.client._seg(raw)
+        assert exc_info.value.code == "invalid_id"
+
+
+INVALID_IDS = ["", ".", ".."]
+
+
+@pytest.mark.parametrize("raw", INVALID_IDS)
+def test_invalid_id_rejected_before_any_request_hits_real_server(raw):
+    """Nothing reaches the network: a real local http.server never sees a request."""
+    import http.server
+    import threading
+
+    seen = []
+
+    class Handler(http.server.BaseHTTPRequestHandler):
+        def _record(self):
+            seen.append(self.path)
+            self.send_response(200)
+            self.send_header("Content-Type", "application/json")
+            self.end_headers()
+            self.wfile.write(json.dumps({"data": {"id": "x"}}).encode())
+
+        def do_GET(self):
+            self._record()
+
+        def do_DELETE(self):
+            self._record()
+
+        def do_POST(self):
+            self._record()
+
+        def log_message(self, format, *args):
+            pass  # keep test output clean
+
+    server = http.server.HTTPServer(("127.0.0.1", 0), Handler)
+    thread = threading.Thread(target=server.serve_forever, daemon=True)
+    thread.start()
+    try:
+        base_url = f"http://127.0.0.1:{server.server_port}/api/v1"
+        client = Client("ms_live_test1234567890", base_url=base_url)
+
+        calls = [
+            lambda: client.get_inbox(raw),
+            lambda: client.delete_inbox(raw),
+            lambda: client.list_messages(raw),
+            lambda: client.get_latest(raw),
+            lambda: client.get_message(raw),
+            lambda: client.wait_for_otp(raw, timeout=5),
+            lambda: client.wait_for_link(raw, timeout=5),
+            lambda: client.wait(raw, timeout=5),
+        ]
+        for call in calls:
+            with pytest.raises(MailsocketError) as exc_info:
+                call()
+            assert exc_info.value.code == "invalid_id"
+            assert not isinstance(exc_info.value, WaitTimeout)
+
+        assert seen == []  # nothing ever reached the network
+    finally:
+        server.shutdown()
+        thread.join(timeout=5)
+
+
 def test_version_exported():
     assert hasattr(mailsocket, "__version__")
 
 
 def test_metadata_consistency_across_files():
-    """0.1.1 must match everywhere: pyproject, __version__, user agent, and MCP sibling."""
+    """0.1.3 must match everywhere: pyproject, __version__, user agent."""
     import re
     import tomllib
     from pathlib import Path
 
     root = Path(__file__).resolve().parents[1]
-    expected = "0.1.1"
+    expected = "0.1.3"
 
     pyproject = tomllib.loads((root / "pyproject.toml").read_text())
     assert pyproject["project"]["version"] == expected
@@ -373,3 +526,69 @@ def test_metadata_consistency_across_files():
     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