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

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

@@ -1,6 +1,6 @@
 Metadata-Version: 2.4
 Name: mailsocket-mcp
-Version: 0.2.3
+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, 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 |
-| `wait_for_link(inbox_id, timeout?=60, since?)` | the extracted magic link (returned, *not* followed) + subject/from/id/received_at |
+| `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 |
@@ -53,14 +53,17 @@ never echoed back.
 ### Reusing an inbox
 
 `create_inbox` needs no `since` — a fresh inbox only ever has new messages.
-But if you reuse an existing inbox (e.g. to request a second OTP/link), pass
-`since` to `wait_for_otp`/`wait_for_link`: otherwise the wait can match the
-OLDEST retained message instead of the new one you just triggered. 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.
+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
 
@@ -195,6 +198,12 @@ 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).
 

{mailsocket_mcp-0.2.3 → 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, 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 |
-| `wait_for_link(inbox_id, timeout?=60, since?)` | the extracted magic link (returned, *not* followed) + subject/from/id/received_at |
+| `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 |
@@ -26,14 +26,17 @@ never echoed back.
 ### Reusing an inbox
 
 `create_inbox` needs no `since` — a fresh inbox only ever has new messages.
-But if you reuse an existing inbox (e.g. to request a second OTP/link), pass
-`since` to `wait_for_otp`/`wait_for_link`: otherwise the wait can match the
-OLDEST retained message instead of the new one you just triggered. 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.
+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
 
@@ -168,6 +171,12 @@ 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).
 

{mailsocket_mcp-0.2.3 → 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.3"
+__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
@@ -481,12 +481,13 @@ def wait_for_otp(
     ``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). A fresh inbox straight from
-    ``create_inbox`` needs nothing here — the default already matches
-    anything in it. When REUSING an inbox for a second code, 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 the oldest one still
-    retained in the inbox.
+    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
@@ -537,12 +538,13 @@ def wait_for_link(
     ``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). A fresh inbox straight from
-    ``create_inbox`` needs nothing here — the default already matches
-    anything in it. When REUSING an inbox for a second link, 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 the oldest one still
-    retained in the inbox.
+    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

{mailsocket_mcp-0.2.3 → 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.3
+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, 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 |
-| `wait_for_link(inbox_id, timeout?=60, since?)` | the extracted magic link (returned, *not* followed) + subject/from/id/received_at |
+| `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 |
@@ -53,14 +53,17 @@ never echoed back.
 ### Reusing an inbox
 
 `create_inbox` needs no `since` — a fresh inbox only ever has new messages.
-But if you reuse an existing inbox (e.g. to request a second OTP/link), pass
-`since` to `wait_for_otp`/`wait_for_link`: otherwise the wait can match the
-OLDEST retained message instead of the new one you just triggered. 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.
+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
 
@@ -195,6 +198,12 @@ 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).
 

{mailsocket_mcp-0.2.3 → 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.3 → mailsocket_mcp-0.3.0}/pyproject.toml

@@ -4,7 +4,7 @@ build-backend = "setuptools.build_meta"
 
 [project]
 name = "mailsocket-mcp"
-version = "0.2.3"
+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.3 → mailsocket_mcp-0.3.0}/tests/test_server.py

@@ -61,13 +61,13 @@ 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):
+    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):
+    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
@@ -237,7 +237,7 @@ def test_wait_for_otp_returns_otp_and_confidence(fake_client):
     assert inbox_id == "inbox_abc"
     assert timeout == 60
     assert min_conf == 0.0
-    assert since == 0  # absent -> SDK default unchanged
+    assert since is None  # absent -> SDK omits since (server uses request start time)
 
 
 def test_wait_for_otp_timeout_is_clamped(fake_client):
@@ -263,6 +263,17 @@ def test_wait_for_otp_since_passed_through(fake_client):
     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",
@@ -307,7 +318,7 @@ def test_wait_for_link_returns_magic_link(fake_client):
     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 == 0  # absent -> SDK default unchanged
+    assert since is None  # absent -> SDK omits since (server uses request start time)
 
 
 def test_wait_for_link_since_passed_through(fake_client):
@@ -428,14 +439,14 @@ def test_version_exported():
 
 
 def test_metadata_consistency_across_files():
-    """Versions match everywhere: MCP 0.2.3 (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.3"
-    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