mailsocket-mcp 0.2.2__tar.gz → 0.3.0__tar.gz

{mailsocket_mcp-0.2.2 → mailsocket_mcp-0.3.0}/PKG-INFO

@@ -1,6 +1,6 @@
 Metadata-Version: 2.4
 Name: mailsocket-mcp
-Version: 0.2.2
+Version: 0.3.0
 Summary: MCP server exposing mailsocket inboxes + wait-for-OTP to AI agents.
 Author: mailsocket
 License-Expression: MIT
@@ -19,7 +19,7 @@ Classifier: Topic :: Communications :: Email
 Requires-Python: >=3.10
 Description-Content-Type: text/markdown
 License-File: LICENSE
-Requires-Dist: mailsocket>=0.1.3
+Requires-Dist: mailsocket>=0.2.0
 Requires-Dist: mcp<3.0,>=2.0
 Provides-Extra: dev
 Requires-Dist: pytest>=7; extra == "dev"
@@ -39,8 +39,8 @@ no second HTTP client, no re-implemented polling.
 | Tool | What the agent gets |
 | --- | --- |
 | `create_inbox(label?)` | a fresh inbox `id` + `address` |
-| `wait_for_otp(inbox_id, timeout?=60, min_confidence?=0)` | **the headline** — blocks (bounded: requested deadline clamped to 120s locally, 55s on the remote server) and returns the OTP string + confidence + subject/from |
-| `wait_for_link(inbox_id, timeout?=60)` | the extracted magic link (returned, *not* followed) |
+| `wait_for_otp(inbox_id, timeout?=60, min_confidence?=0, since?)` | **the headline** — blocks (bounded: requested deadline clamped to 120s locally, 55s on the remote server) and returns the OTP string + confidence + subject/from/id/received_at. Default `since` omitted: only messages arriving after this call are matched. |
+| `wait_for_link(inbox_id, timeout?=60, since?)` | the extracted magic link (returned, *not* followed) + subject/from/id/received_at. Default `since` omitted: only messages arriving after this call are matched. |
 | `list_inboxes(limit?, cursor?)` | one page of inboxes owned by the key (server default page size 25) + `next_cursor`/`has_more` |
 | `list_messages(inbox_id, has_otp?, subject_contains?, sender?, limit?, cursor?)` | one page of messages, optionally filtered (server default page size 25) + `next_cursor`/`has_more` |
 | `get_latest(inbox_id)` | the newest message, without blocking |
@@ -50,6 +50,21 @@ Errors from the SDK (`AuthError` / `NotFound` / `RateLimited` / `WaitTimeout`)
 are turned into clean MCP tool errors — no stack traces, and the API key is
 never echoed back.
 
+### Reusing an inbox
+
+`create_inbox` needs no `since` — a fresh inbox only ever has new messages.
+By default, `wait_for_otp`/`wait_for_link` omit `since` entirely, so the
+server matches only messages arriving AFTER the call (the request start
+time). But if you reuse an existing inbox (e.g. to request a second
+OTP/link), pass `since` explicitly: otherwise a call with no `since` will
+correctly ignore anything already sitting in the inbox, which is right for
+most reuse, but if you actually WANT to catch a code that already arrived
+before you called the tool, pass either the time right before you triggered
+the new email (ISO8601 or unix seconds), or the `id` of the last message you
+saw (`msg_...`, meaning "only messages after that one") — both tools return
+`id`/`received_at` on the matched message so you can chain `since=<id>` into
+the next call on that same inbox.
+
 ## Requirements
 
 - Python 3.10+
@@ -183,6 +198,13 @@ remote-transport tests talk to a local fake upstream on `127.0.0.1`.
 
 ## Changelog
 
+- **0.3.0** — BEHAVIOUR CHANGE (via `mailsocket>=0.2.0`): `wait_for_otp` /
+  `wait_for_link` now omit `since` by default instead of forwarding `0`
+  ("any message already in the inbox"). The old default could return a
+  STALE OTP/link already sitting in a reused inbox; the new default matches
+  only messages arriving after the call. Pass `since=0` explicitly to keep
+  the old behaviour.
+- **0.2.3** — `wait_for_otp` / `wait_for_link` accept an optional `since` (ISO8601, unix seconds or a message id) so a reused inbox returns the NEW code; results include the message `id` and `received_at`.
 - **0.2.2** — depends on `mailsocket>=0.1.3` (stricter `_seg` id validation in the underlying Python SDK).
 
 <!-- mcp-name: app.mailsocket/mailsocket-mcp -->

{mailsocket_mcp-0.2.2 → mailsocket_mcp-0.3.0}/README.md

@@ -12,8 +12,8 @@ no second HTTP client, no re-implemented polling.
 | Tool | What the agent gets |
 | --- | --- |
 | `create_inbox(label?)` | a fresh inbox `id` + `address` |
-| `wait_for_otp(inbox_id, timeout?=60, min_confidence?=0)` | **the headline** — blocks (bounded: requested deadline clamped to 120s locally, 55s on the remote server) and returns the OTP string + confidence + subject/from |
-| `wait_for_link(inbox_id, timeout?=60)` | the extracted magic link (returned, *not* followed) |
+| `wait_for_otp(inbox_id, timeout?=60, min_confidence?=0, since?)` | **the headline** — blocks (bounded: requested deadline clamped to 120s locally, 55s on the remote server) and returns the OTP string + confidence + subject/from/id/received_at. Default `since` omitted: only messages arriving after this call are matched. |
+| `wait_for_link(inbox_id, timeout?=60, since?)` | the extracted magic link (returned, *not* followed) + subject/from/id/received_at. Default `since` omitted: only messages arriving after this call are matched. |
 | `list_inboxes(limit?, cursor?)` | one page of inboxes owned by the key (server default page size 25) + `next_cursor`/`has_more` |
 | `list_messages(inbox_id, has_otp?, subject_contains?, sender?, limit?, cursor?)` | one page of messages, optionally filtered (server default page size 25) + `next_cursor`/`has_more` |
 | `get_latest(inbox_id)` | the newest message, without blocking |
@@ -23,6 +23,21 @@ Errors from the SDK (`AuthError` / `NotFound` / `RateLimited` / `WaitTimeout`)
 are turned into clean MCP tool errors — no stack traces, and the API key is
 never echoed back.
 
+### Reusing an inbox
+
+`create_inbox` needs no `since` — a fresh inbox only ever has new messages.
+By default, `wait_for_otp`/`wait_for_link` omit `since` entirely, so the
+server matches only messages arriving AFTER the call (the request start
+time). But if you reuse an existing inbox (e.g. to request a second
+OTP/link), pass `since` explicitly: otherwise a call with no `since` will
+correctly ignore anything already sitting in the inbox, which is right for
+most reuse, but if you actually WANT to catch a code that already arrived
+before you called the tool, pass either the time right before you triggered
+the new email (ISO8601 or unix seconds), or the `id` of the last message you
+saw (`msg_...`, meaning "only messages after that one") — both tools return
+`id`/`received_at` on the matched message so you can chain `since=<id>` into
+the next call on that same inbox.
+
 ## Requirements
 
 - Python 3.10+
@@ -156,6 +171,13 @@ remote-transport tests talk to a local fake upstream on `127.0.0.1`.
 
 ## Changelog
 
+- **0.3.0** — BEHAVIOUR CHANGE (via `mailsocket>=0.2.0`): `wait_for_otp` /
+  `wait_for_link` now omit `since` by default instead of forwarding `0`
+  ("any message already in the inbox"). The old default could return a
+  STALE OTP/link already sitting in a reused inbox; the new default matches
+  only messages arriving after the call. Pass `since=0` explicitly to keep
+  the old behaviour.
+- **0.2.3** — `wait_for_otp` / `wait_for_link` accept an optional `since` (ISO8601, unix seconds or a message id) so a reused inbox returns the NEW code; results include the message `id` and `received_at`.
 - **0.2.2** — depends on `mailsocket>=0.1.3` (stricter `_seg` id validation in the underlying Python SDK).
 
 <!-- mcp-name: app.mailsocket/mailsocket-mcp -->

{mailsocket_mcp-0.2.2 → mailsocket_mcp-0.3.0}/mailsocket_mcp/server.py

@@ -52,7 +52,7 @@ __all__ = [
 # Canonical version, re-exported as ``mailsocket_mcp.__version__`` (see
 # __init__.py). Defined here, not in __init__.py, because __init__.py imports
 # this module at package-load time and a circular self-import would break.
-__version__ = "0.2.2"
+__version__ = "0.3.0"
 
 # The headline wait is bounded: an agent can request up to the transport's
 # ceiling as the overall deadline (clamped), though transport overhead can push
@@ -461,6 +461,7 @@ def wait_for_otp(
     inbox_id: str,
     timeout: float = DEFAULT_WAIT_TIMEOUT,
     min_confidence: float = 0.0,
+    since: str | int | float | None = None,
 ) -> dict:
     """Block (bounded) until an OTP arrives in ``inbox_id`` and return it.
 
@@ -477,21 +478,36 @@ def wait_for_otp(
     slightly after the ceiling in practice. On a timeout just call it again.
     ``min_confidence`` filters out low-confidence OTP extractions.
 
+    ``since`` (optional) only matches messages that arrived after this point:
+    an ISO8601 timestamp, unix seconds, or a message id (``msg_...``, meaning
+    "only messages after that one"; an unknown id falls back to the oldest
+    message, so prefer a timestamp if unsure). Omitted (the default), the
+    server matches only messages that arrive during this call — the right
+    choice for a fresh inbox from ``create_inbox``. When REUSING an inbox for
+    a second code and you want to catch one that already arrived before this
+    call, pass either the time just before you triggered this email, or the
+    ``id`` of the last message you saw, so you get the NEW code instead of
+    missing it.
+
     Side effects: none beyond the long-poll HTTP call(s) needed to satisfy the
     wait (``openWorldHint`` — it talks to the live mailsocket API and blocks
     for up to ``timeout`` seconds). Returns the OTP string, a confidence
-    score, and the subject/from of the matching message. Raises a clean tool
-    error (``WaitTimeout``) if nothing matching arrives before the deadline.
+    score, the subject/from of the matching message, and its ``id`` /
+    ``received_at`` (chain ``since=<id>`` into the next call on this inbox).
+    Raises a clean tool error (``WaitTimeout``) if nothing matching arrives
+    before the deadline.
     """
+    kwargs = {} if since is None else {"since": since}
     result = _get_client().wait_for_otp(
         inbox_id,
         timeout=_clamp_timeout(timeout),
         min_confidence=min_confidence,
+        **kwargs,
     )
     return {
         "otp": result.otp,
         "confidence": result.confidence,
-        **_ctx(result, ("subject", "from")),
+        **_ctx(result, ("subject", "from", "id", "received_at")),
     }
 
 
@@ -502,6 +518,7 @@ def wait_for_otp(
 def wait_for_link(
     inbox_id: str,
     timeout: float = DEFAULT_WAIT_TIMEOUT,
+    since: str | int | float | None = None,
 ) -> dict:
     """Block (bounded) until a magic link arrives in ``inbox_id`` and return it.
 
@@ -518,15 +535,29 @@ def wait_for_link(
     return slightly after the ceiling in practice. On a timeout just call it
     again.
 
+    ``since`` (optional) only matches messages that arrived after this point:
+    an ISO8601 timestamp, unix seconds, or a message id (``msg_...``, meaning
+    "only messages after that one"; an unknown id falls back to the oldest
+    message, so prefer a timestamp if unsure). Omitted (the default), the
+    server matches only messages that arrive during this call — the right
+    choice for a fresh inbox from ``create_inbox``. When REUSING an inbox for
+    a second link and you want to catch one that already arrived before this
+    call, pass either the time just before you triggered this email, or the
+    ``id`` of the last message you saw, so you get the NEW link instead of
+    missing it.
+
     Side effects: none beyond the long-poll HTTP call(s) needed to satisfy the
     wait (``openWorldHint`` — it talks to the live mailsocket API and blocks
-    for up to ``timeout`` seconds). Raises a clean tool error (``WaitTimeout``)
-    if no link arrives before the deadline.
+    for up to ``timeout`` seconds). Returns the magic link, the subject/from
+    of the matching message, and its ``id`` / ``received_at`` (chain
+    ``since=<id>`` into the next call on this inbox). Raises a clean tool
+    error (``WaitTimeout``) if no link arrives before the deadline.
     """
-    result = _get_client().wait_for_link(inbox_id, timeout=_clamp_timeout(timeout))
+    kwargs = {} if since is None else {"since": since}
+    result = _get_client().wait_for_link(inbox_id, timeout=_clamp_timeout(timeout), **kwargs)
     return {
         "magic_link": result.magic_link,
-        **_ctx(result, ("subject", "from")),
+        **_ctx(result, ("subject", "from", "id", "received_at")),
     }
 
 

{mailsocket_mcp-0.2.2 → mailsocket_mcp-0.3.0}/mailsocket_mcp.egg-info/PKG-INFO

@@ -1,6 +1,6 @@
 Metadata-Version: 2.4
 Name: mailsocket-mcp
-Version: 0.2.2
+Version: 0.3.0
 Summary: MCP server exposing mailsocket inboxes + wait-for-OTP to AI agents.
 Author: mailsocket
 License-Expression: MIT
@@ -19,7 +19,7 @@ Classifier: Topic :: Communications :: Email
 Requires-Python: >=3.10
 Description-Content-Type: text/markdown
 License-File: LICENSE
-Requires-Dist: mailsocket>=0.1.3
+Requires-Dist: mailsocket>=0.2.0
 Requires-Dist: mcp<3.0,>=2.0
 Provides-Extra: dev
 Requires-Dist: pytest>=7; extra == "dev"
@@ -39,8 +39,8 @@ no second HTTP client, no re-implemented polling.
 | Tool | What the agent gets |
 | --- | --- |
 | `create_inbox(label?)` | a fresh inbox `id` + `address` |
-| `wait_for_otp(inbox_id, timeout?=60, min_confidence?=0)` | **the headline** — blocks (bounded: requested deadline clamped to 120s locally, 55s on the remote server) and returns the OTP string + confidence + subject/from |
-| `wait_for_link(inbox_id, timeout?=60)` | the extracted magic link (returned, *not* followed) |
+| `wait_for_otp(inbox_id, timeout?=60, min_confidence?=0, since?)` | **the headline** — blocks (bounded: requested deadline clamped to 120s locally, 55s on the remote server) and returns the OTP string + confidence + subject/from/id/received_at. Default `since` omitted: only messages arriving after this call are matched. |
+| `wait_for_link(inbox_id, timeout?=60, since?)` | the extracted magic link (returned, *not* followed) + subject/from/id/received_at. Default `since` omitted: only messages arriving after this call are matched. |
 | `list_inboxes(limit?, cursor?)` | one page of inboxes owned by the key (server default page size 25) + `next_cursor`/`has_more` |
 | `list_messages(inbox_id, has_otp?, subject_contains?, sender?, limit?, cursor?)` | one page of messages, optionally filtered (server default page size 25) + `next_cursor`/`has_more` |
 | `get_latest(inbox_id)` | the newest message, without blocking |
@@ -50,6 +50,21 @@ Errors from the SDK (`AuthError` / `NotFound` / `RateLimited` / `WaitTimeout`)
 are turned into clean MCP tool errors — no stack traces, and the API key is
 never echoed back.
 
+### Reusing an inbox
+
+`create_inbox` needs no `since` — a fresh inbox only ever has new messages.
+By default, `wait_for_otp`/`wait_for_link` omit `since` entirely, so the
+server matches only messages arriving AFTER the call (the request start
+time). But if you reuse an existing inbox (e.g. to request a second
+OTP/link), pass `since` explicitly: otherwise a call with no `since` will
+correctly ignore anything already sitting in the inbox, which is right for
+most reuse, but if you actually WANT to catch a code that already arrived
+before you called the tool, pass either the time right before you triggered
+the new email (ISO8601 or unix seconds), or the `id` of the last message you
+saw (`msg_...`, meaning "only messages after that one") — both tools return
+`id`/`received_at` on the matched message so you can chain `since=<id>` into
+the next call on that same inbox.
+
 ## Requirements
 
 - Python 3.10+
@@ -183,6 +198,13 @@ remote-transport tests talk to a local fake upstream on `127.0.0.1`.
 
 ## Changelog
 
+- **0.3.0** — BEHAVIOUR CHANGE (via `mailsocket>=0.2.0`): `wait_for_otp` /
+  `wait_for_link` now omit `since` by default instead of forwarding `0`
+  ("any message already in the inbox"). The old default could return a
+  STALE OTP/link already sitting in a reused inbox; the new default matches
+  only messages arriving after the call. Pass `since=0` explicitly to keep
+  the old behaviour.
+- **0.2.3** — `wait_for_otp` / `wait_for_link` accept an optional `since` (ISO8601, unix seconds or a message id) so a reused inbox returns the NEW code; results include the message `id` and `received_at`.
 - **0.2.2** — depends on `mailsocket>=0.1.3` (stricter `_seg` id validation in the underlying Python SDK).
 
 <!-- mcp-name: app.mailsocket/mailsocket-mcp -->

{mailsocket_mcp-0.2.2 → mailsocket_mcp-0.3.0}/mailsocket_mcp.egg-info/requires.txt

@@ -1,4 +1,4 @@
-mailsocket>=0.1.3
+mailsocket>=0.2.0
 mcp<3.0,>=2.0
 
 [dev]

{mailsocket_mcp-0.2.2 → mailsocket_mcp-0.3.0}/pyproject.toml

@@ -4,7 +4,7 @@ build-backend = "setuptools.build_meta"
 
 [project]
 name = "mailsocket-mcp"
-version = "0.2.2"
+version = "0.3.0"
 description = "MCP server exposing mailsocket inboxes + wait-for-OTP to AI agents."
 readme = "README.md"
 requires-python = ">=3.10"
@@ -22,7 +22,7 @@ classifiers = [
     "Topic :: Communications :: Email",
 ]
 dependencies = [
-    "mailsocket>=0.1.3",  # published on PyPI as `mailsocket` (0.1.3 adds strict _seg validation)
+    "mailsocket>=0.2.0",  # published on PyPI as `mailsocket` (0.2.0: since defaults to omitted, not 0 — see CHANGELOG)
     "mcp>=2.0,<3.0",
 ]
 

{mailsocket_mcp-0.2.2 → mailsocket_mcp-0.3.0}/tests/test_server.py

@@ -61,14 +61,14 @@ class FakeClient:
         self.created.append(label)
         return {"id": "inbox_1", "address": "x@in.inboxpipe.net"}
 
-    def wait_for_otp(self, inbox_id, *, timeout=60.0, min_confidence=0.0, since=0):
-        self.wait_otp_calls.append((inbox_id, timeout, min_confidence))
+    def wait_for_otp(self, inbox_id, *, timeout=60.0, min_confidence=0.0, since=None):
+        self.wait_otp_calls.append((inbox_id, timeout, min_confidence, since))
         if isinstance(self.wait_otp, Exception):
             raise self.wait_otp
         return self.wait_otp
 
-    def wait_for_link(self, inbox_id, *, timeout=60.0, since=0):
-        self.wait_link_calls.append((inbox_id, timeout))
+    def wait_for_link(self, inbox_id, *, timeout=60.0, since=None):
+        self.wait_link_calls.append((inbox_id, timeout, since))
         if isinstance(self.wait_link, Exception):
             raise self.wait_link
         return self.wait_link
@@ -233,10 +233,11 @@ def test_wait_for_otp_returns_otp_and_confidence(fake_client):
     assert result.is_error is False
     text = result.content[0].text
     assert '"123456"' in text
-    inbox_id, timeout, min_conf = fake_client.wait_otp_calls[0]
+    inbox_id, timeout, min_conf, since = fake_client.wait_otp_calls[0]
     assert inbox_id == "inbox_abc"
     assert timeout == 60
     assert min_conf == 0.0
+    assert since is None  # absent -> SDK omits since (server uses request start time)
 
 
 def test_wait_for_otp_timeout_is_clamped(fake_client):
@@ -244,14 +245,55 @@ def test_wait_for_otp_timeout_is_clamped(fake_client):
 
     call_tool("wait_for_otp", {"inbox_id": "inbox_abc", "timeout": 9999})
 
-    _, timeout, _ = fake_client.wait_otp_calls[0]
+    _, timeout, _, _ = fake_client.wait_otp_calls[0]
     assert timeout == MAX_WAIT_TIMEOUT
 
     call_tool("wait_for_otp", {"inbox_id": "inbox_abc", "timeout": 0})
-    _, timeout, _ = fake_client.wait_otp_calls[1]
+    _, timeout, _, _ = fake_client.wait_otp_calls[1]
     assert timeout == 1.0
 
 
+def test_wait_for_otp_since_passed_through(fake_client):
+    fake_client.wait_otp = FakeWaitResult(otp="123456")
+
+    call_tool("wait_for_otp", {"inbox_id": "inbox_abc", "since": "msg_111"})
+
+    inbox_id, _, _, since = fake_client.wait_otp_calls[0]
+    assert inbox_id == "inbox_abc"
+    assert since == "msg_111"
+
+
+def test_wait_for_otp_explicit_since_zero_passed_through(fake_client):
+    """since=0 (include messages already in the inbox) must reach the SDK as 0,
+    not be dropped as falsy and turned into the new request-start default."""
+    fake_client.wait_otp = FakeWaitResult(otp="123456")
+
+    call_tool("wait_for_otp", {"inbox_id": "inbox_abc", "since": 0})
+
+    _, _, _, since = fake_client.wait_otp_calls[0]
+    assert since == 0
+
+
+def test_wait_for_otp_result_carries_id_and_received_at(fake_client):
+    fake_client.wait_otp = FakeWaitResult(
+        otp="123456",
+        confidence=0.95,
+        message={
+            "subject": "Your code",
+            "from": "Acme <no-reply@acme.test>",
+            "id": "msg_999",
+            "received_at": "2024-01-01T00:00:00Z",
+        },
+    )
+
+    result = call_tool("wait_for_otp", {"inbox_id": "inbox_abc"})
+
+    assert result.is_error is False
+    text = result.content[0].text
+    assert '"msg_999"' in text
+    assert '"2024-01-01T00:00:00Z"' in text
+
+
 def test_wait_for_otp_wait_timeout_is_clean_error(fake_client):
     fake_client.wait_otp = WaitTimeout("No matching message arrived within 60s.")
 
@@ -274,6 +316,38 @@ def test_wait_for_link_returns_magic_link(fake_client):
 
     assert result.is_error is False
     assert "https://example.test/go?token=abc" in result.content[0].text
+    inbox_id, timeout, since = fake_client.wait_link_calls[0]
+    assert inbox_id == "inbox_abc"
+    assert since is None  # absent -> SDK omits since (server uses request start time)
+
+
+def test_wait_for_link_since_passed_through(fake_client):
+    fake_client.wait_link = FakeWaitResult(magic_link="https://example.test/go?token=abc")
+
+    call_tool("wait_for_link", {"inbox_id": "inbox_abc", "since": "2024-01-01T00:00:00Z"})
+
+    inbox_id, _, since = fake_client.wait_link_calls[0]
+    assert inbox_id == "inbox_abc"
+    assert since == "2024-01-01T00:00:00Z"
+
+
+def test_wait_for_link_result_carries_id_and_received_at(fake_client):
+    fake_client.wait_link = FakeWaitResult(
+        magic_link="https://example.test/go?token=abc",
+        message={
+            "subject": "Sign in",
+            "from": "Acme <no-reply@acme.test>",
+            "id": "msg_777",
+            "received_at": "2024-02-02T00:00:00Z",
+        },
+    )
+
+    result = call_tool("wait_for_link", {"inbox_id": "inbox_abc"})
+
+    assert result.is_error is False
+    text = result.content[0].text
+    assert '"msg_777"' in text
+    assert '"2024-02-02T00:00:00Z"' in text
 
 
 # -- create_inbox / list_messages / delete -----------------------------------
@@ -365,14 +439,14 @@ def test_version_exported():
 
 
 def test_metadata_consistency_across_files():
-    """Versions match everywhere: MCP 0.2.2 (pyproject, server.json, __version__)
-    and its Python SDK sibling 0.1.3 (pyproject, __version__, user agent)."""
+    """Versions match everywhere: MCP 0.3.0 (pyproject, server.json, __version__)
+    and its Python SDK sibling 0.2.0 (pyproject, __version__, user agent)."""
     import tomllib
     from pathlib import Path
 
     root = Path(__file__).resolve().parents[1]
-    expected = "0.2.2"
-    expected_sdk = "0.1.3"
+    expected = "0.3.0"
+    expected_sdk = "0.2.0"
 
     pyproject = tomllib.loads((root / "pyproject.toml").read_text())
     assert pyproject["project"]["version"] == expected