mailsocket 0.1.3__tar.gz → 0.2.0__tar.gz

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

@@ -1,6 +1,6 @@
 Metadata-Version: 2.4
 Name: mailsocket
-Version: 0.1.3
+Version: 0.2.0
 Summary: Official Python client for the mailsocket REST API — one line to wait for an OTP.
 Author: mailsocket
 License-Expression: MIT
@@ -17,6 +17,7 @@ Classifier: Programming Language :: Python :: 3.10
 Classifier: Programming Language :: Python :: 3.11
 Classifier: Programming Language :: Python :: 3.12
 Classifier: Topic :: Communications :: Email
+Classifier: Typing :: Typed
 Requires-Python: >=3.9
 Description-Content-Type: text/markdown
 License-File: LICENSE
@@ -72,9 +73,9 @@ client = Client(api_key, base_url="https://dash.mailsocket.app/api/v1")
 ### The moat
 
 ```python
-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
+result = client.wait_for_otp("inbox_abc123", timeout=60, min_confidence=0.0, since=None)
+result = client.wait_for_link("inbox_abc123", timeout=60, since=None)
+result = client.wait("inbox_abc123", timeout=60, min_confidence=0.0, since=None)  # otp OR link
 ```
 
 All three return a `WaitResult` and take keyword-only arguments after
@@ -83,9 +84,16 @@ 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) |
+| `wait_for_otp(inbox_id, ...)` | `timeout=60`, `min_confidence=0.0`, `since=None` | `WaitResult` |
+| `wait_for_link(inbox_id, ...)` | `timeout=60`, `since=None` | `WaitResult` |
+| `wait(inbox_id, ...)` | `timeout=60`, `min_confidence=0.0`, `since=None` | `WaitResult` (otp OR link) |
+
+`since=None` (the default) omits the param, so the server uses its own
+default: the request start time — a code that arrives during this call is
+caught, and a stale code already in a reused inbox is not. Pass `since=0` to
+restore the old "any message already in the inbox" behaviour (useful right
+after `create_inbox`, where there's nothing stale to match), or a message id
+/ timestamp to continue after a specific point.
 
 `WaitResult` exposes `.otp`, `.confidence`, `.magic_link` (and `.link` as an
 alias), plus the full `.message` dict. `str(result)` is the OTP (or the link).
@@ -123,4 +131,9 @@ invalid id never reaches the network.
 
 ## Changelog
 
+- **0.2.0** — BEHAVIOUR CHANGE: `wait_for_otp`/`wait_for_link`/`wait` now
+  default `since=None`, which omits the param so the server uses the
+  request start time, instead of the old `since=0` ("any message already
+  in the inbox"). The old default silently returned a STALE OTP/link from a
+  reused inbox. Pass `since=0` explicitly to keep the old behaviour.
 - **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.3 → mailsocket-0.2.0}/README.md

@@ -46,9 +46,9 @@ client = Client(api_key, base_url="https://dash.mailsocket.app/api/v1")
 ### The moat
 
 ```python
-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
+result = client.wait_for_otp("inbox_abc123", timeout=60, min_confidence=0.0, since=None)
+result = client.wait_for_link("inbox_abc123", timeout=60, since=None)
+result = client.wait("inbox_abc123", timeout=60, min_confidence=0.0, since=None)  # otp OR link
 ```
 
 All three return a `WaitResult` and take keyword-only arguments after
@@ -57,9 +57,16 @@ 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) |
+| `wait_for_otp(inbox_id, ...)` | `timeout=60`, `min_confidence=0.0`, `since=None` | `WaitResult` |
+| `wait_for_link(inbox_id, ...)` | `timeout=60`, `since=None` | `WaitResult` |
+| `wait(inbox_id, ...)` | `timeout=60`, `min_confidence=0.0`, `since=None` | `WaitResult` (otp OR link) |
+
+`since=None` (the default) omits the param, so the server uses its own
+default: the request start time — a code that arrives during this call is
+caught, and a stale code already in a reused inbox is not. Pass `since=0` to
+restore the old "any message already in the inbox" behaviour (useful right
+after `create_inbox`, where there's nothing stale to match), or a message id
+/ timestamp to continue after a specific point.
 
 `WaitResult` exposes `.otp`, `.confidence`, `.magic_link` (and `.link` as an
 alias), plus the full `.message` dict. `str(result)` is the OTP (or the link).
@@ -97,4 +104,9 @@ invalid id never reaches the network.
 
 ## Changelog
 
+- **0.2.0** — BEHAVIOUR CHANGE: `wait_for_otp`/`wait_for_link`/`wait` now
+  default `since=None`, which omits the param so the server uses the
+  request start time, instead of the old `since=0` ("any message already
+  in the inbox"). The old default silently returned a STALE OTP/link from a
+  reused inbox. Pass `since=0` explicitly to keep the old behaviour.
 - **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.3 → mailsocket-0.2.0}/mailsocket/__init__.py

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

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

@@ -10,6 +10,7 @@ import time as _time
 import urllib.error
 import urllib.parse
 import urllib.request
+from dataclasses import dataclass, field
 
 from .errors import AuthError, MailsocketError, NotFound, RateLimited, WaitTimeout
 
@@ -79,14 +80,30 @@ class Page:
         return f"Page(data={self.data!r}, pagination={self.pagination!r})"
 
 
+@dataclass(frozen=True, eq=False)
 class WaitResult:
-    """The outcome of a ``wait_for_otp`` / ``wait_for_link`` / ``wait`` call."""
+    """The outcome of a ``wait_for_otp`` / ``wait_for_link`` / ``wait`` call.
+
+    #31 (trust-audit-OUT.md): a frozen dataclass, backward compatible with
+    the plain-class shape it replaces — same four public attributes
+    (``.message``, ``.otp``, ``.confidence``, ``.magic_link``), the derived
+    ``.link`` property, and the same ``repr()``/``str()``. Instances are now
+    immutable (``frozen=True``); ``eq=False`` keeps equality/hashing
+    identity-based exactly as the old plain class, since ``message`` is a
+    dict and value-equality would make ``hash()`` raise ``TypeError``.
+    """
+
+    message: dict
+    otp: str | None = field(init=False)
+    confidence: float | None = field(init=False)
+    magic_link: str | None = field(init=False)
 
-    def __init__(self, message: dict):
-        self.message = message
-        self.otp = message.get("otp")
-        self.confidence = message.get("otp_confidence")
-        self.magic_link = message.get("magic_link")
+    def __post_init__(self):
+        # frozen=True disallows plain attribute assignment even inside
+        # __post_init__, hence object.__setattr__.
+        object.__setattr__(self, "otp", self.message.get("otp"))
+        object.__setattr__(self, "confidence", self.message.get("otp_confidence"))
+        object.__setattr__(self, "magic_link", self.message.get("magic_link"))
 
     @property
     def link(self):
@@ -192,9 +209,16 @@ class Client:
         *,
         timeout: float = 60.0,
         min_confidence: float = 0.0,
-        since=0,
+        since=None,
     ) -> WaitResult:
-        """Wait for an OTP. Returns a :class:`WaitResult` with ``.otp`` etc."""
+        """Wait for an OTP. Returns a :class:`WaitResult` with ``.otp`` etc.
+
+        ``since`` defaults to ``None``, which omits the param entirely so the
+        server's own default applies (the request start time) — a caller
+        only sees messages that arrive during this call, never a stale OTP
+        already sitting in a reused inbox. Pass ``since=0`` to restore the
+        old behaviour: match any message already in the inbox.
+        """
         return self._wait(
             inbox_id,
             require="otp",
@@ -203,8 +227,12 @@ class Client:
             since=since,
         )
 
-    def wait_for_link(self, inbox_id: str, *, timeout: float = 60.0, since=0) -> WaitResult:
-        """Wait for a magic link. Returns a :class:`WaitResult` with ``.link``."""
+    def wait_for_link(self, inbox_id: str, *, timeout: float = 60.0, since=None) -> WaitResult:
+        """Wait for a magic link. Returns a :class:`WaitResult` with ``.link``.
+
+        ``since`` defaults to ``None`` (omitted -> server uses the request
+        start time). Pass ``since=0`` to include messages already in the inbox.
+        """
         return self._wait(
             inbox_id, require="link", timeout=timeout, min_confidence=None, since=since
         )
@@ -215,9 +243,13 @@ class Client:
         *,
         timeout: float = 60.0,
         min_confidence: float = 0.0,
-        since=0,
+        since=None,
     ) -> WaitResult:
-        """Wait for either an OTP or a magic link."""
+        """Wait for either an OTP or a magic link.
+
+        ``since`` defaults to ``None`` (omitted -> server uses the request
+        start time). Pass ``since=0`` to include messages already in the inbox.
+        """
         return self._wait(
             inbox_id,
             require="any",
@@ -288,7 +320,7 @@ class Client:
             url += "?" + urllib.parse.urlencode(params, doseq=True)
         headers = {
             "Accept": "application/json",
-            "User-Agent": "mailsocket-python/0.1.3",
+            "User-Agent": "mailsocket-python/0.2.0",
         }
         headers.update(self._extra_headers)
         # Set last so nothing in extra_headers can ever replace it.

{mailsocket-0.1.3 → mailsocket-0.2.0}/mailsocket.egg-info/PKG-INFO

@@ -1,6 +1,6 @@
 Metadata-Version: 2.4
 Name: mailsocket
-Version: 0.1.3
+Version: 0.2.0
 Summary: Official Python client for the mailsocket REST API — one line to wait for an OTP.
 Author: mailsocket
 License-Expression: MIT
@@ -17,6 +17,7 @@ Classifier: Programming Language :: Python :: 3.10
 Classifier: Programming Language :: Python :: 3.11
 Classifier: Programming Language :: Python :: 3.12
 Classifier: Topic :: Communications :: Email
+Classifier: Typing :: Typed
 Requires-Python: >=3.9
 Description-Content-Type: text/markdown
 License-File: LICENSE
@@ -72,9 +73,9 @@ client = Client(api_key, base_url="https://dash.mailsocket.app/api/v1")
 ### The moat
 
 ```python
-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
+result = client.wait_for_otp("inbox_abc123", timeout=60, min_confidence=0.0, since=None)
+result = client.wait_for_link("inbox_abc123", timeout=60, since=None)
+result = client.wait("inbox_abc123", timeout=60, min_confidence=0.0, since=None)  # otp OR link
 ```
 
 All three return a `WaitResult` and take keyword-only arguments after
@@ -83,9 +84,16 @@ 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) |
+| `wait_for_otp(inbox_id, ...)` | `timeout=60`, `min_confidence=0.0`, `since=None` | `WaitResult` |
+| `wait_for_link(inbox_id, ...)` | `timeout=60`, `since=None` | `WaitResult` |
+| `wait(inbox_id, ...)` | `timeout=60`, `min_confidence=0.0`, `since=None` | `WaitResult` (otp OR link) |
+
+`since=None` (the default) omits the param, so the server uses its own
+default: the request start time — a code that arrives during this call is
+caught, and a stale code already in a reused inbox is not. Pass `since=0` to
+restore the old "any message already in the inbox" behaviour (useful right
+after `create_inbox`, where there's nothing stale to match), or a message id
+/ timestamp to continue after a specific point.
 
 `WaitResult` exposes `.otp`, `.confidence`, `.magic_link` (and `.link` as an
 alias), plus the full `.message` dict. `str(result)` is the OTP (or the link).
@@ -123,4 +131,9 @@ invalid id never reaches the network.
 
 ## Changelog
 
+- **0.2.0** — BEHAVIOUR CHANGE: `wait_for_otp`/`wait_for_link`/`wait` now
+  default `since=None`, which omits the param so the server uses the
+  request start time, instead of the old `since=0` ("any message already
+  in the inbox"). The old default silently returned a STALE OTP/link from a
+  reused inbox. Pass `since=0` explicitly to keep the old behaviour.
 - **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.3 → mailsocket-0.2.0}/mailsocket.egg-info/SOURCES.txt

@@ -4,6 +4,7 @@ pyproject.toml
 mailsocket/__init__.py
 mailsocket/client.py
 mailsocket/errors.py
+mailsocket/py.typed
 mailsocket.egg-info/PKG-INFO
 mailsocket.egg-info/SOURCES.txt
 mailsocket.egg-info/dependency_links.txt

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

@@ -4,7 +4,7 @@ build-backend = "setuptools.build_meta"
 
 [project]
 name = "mailsocket"
-version = "0.1.3"
+version = "0.2.0"
 description = "Official Python client for the mailsocket REST API — one line to wait for an OTP."
 readme = "README.md"
 requires-python = ">=3.9"
@@ -21,6 +21,7 @@ classifiers = [
     "Programming Language :: Python :: 3.11",
     "Programming Language :: Python :: 3.12",
     "Topic :: Communications :: Email",
+    "Typing :: Typed",
 ]
 dependencies = []
 
@@ -36,6 +37,9 @@ Issues = "https://github.com/mailsocket/mailsocket-sdk/issues"
 [tool.setuptools]
 packages = ["mailsocket"]
 
+[tool.setuptools.package-data]
+mailsocket = ["py.typed"]
+
 [tool.pytest.ini_options]
 testpaths = ["tests"]
 pythonpath = ["."]

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

@@ -1,6 +1,7 @@
 """Offline unit tests for the mailsocket Python SDK (mocked transport, no network)."""
 
 import json
+import urllib.parse
 
 import pytest
 
@@ -109,6 +110,70 @@ def test_wait_for_otp_returns_on_first_200(monkeypatch):
     assert len(transport.calls) == 1
 
 
+def test_wait_result_equality_and_hash_are_identity_based():
+    """R2 FIX 3 (GPT review): frozen=True makes WaitResult immutable, but
+    equality/hash must stay identity-based exactly as the old plain class —
+    value-equality would make hash() raise TypeError because ``message``
+    is an unhashable dict."""
+    a = WaitResult(dict(OTP_MESSAGE))
+    b = WaitResult(dict(OTP_MESSAGE))
+
+    assert a == a
+    assert a != b  # same field values, but distinct instances
+    assert hash(a) == hash(a)
+    assert hash(a) != hash(b) or a is b  # identity-based hash, no collision assumed
+    assert {a, b} == {a, b}  # hashable: usable in a set/dict key
+
+
+def test_wait_for_otp_default_since_is_omitted(monkeypatch):
+    """since=None default must OMIT the `since` param so the server uses the
+    request start time, not match a stale message already in a reused inbox.
+    Revert-proof: restoring since=0 as the default fails this test."""
+    client, transport = make_client([(200, {}, {"data": OTP_MESSAGE})])
+    _monkeypatch_transport(monkeypatch, client, transport)
+
+    client.wait_for_otp("inbox_abc", timeout=60)
+
+    _, url = transport.calls[0]
+    query = urllib.parse.parse_qs(urllib.parse.urlsplit(url).query)
+    assert "since" not in query
+
+
+def test_wait_for_link_default_since_is_omitted(monkeypatch):
+    client, transport = make_client([(200, {}, {"data": LINK_MESSAGE})])
+    _monkeypatch_transport(monkeypatch, client, transport)
+
+    client.wait_for_link("inbox_abc", timeout=60)
+
+    _, url = transport.calls[0]
+    query = urllib.parse.parse_qs(urllib.parse.urlsplit(url).query)
+    assert "since" not in query
+
+
+def test_wait_default_since_is_omitted(monkeypatch):
+    client, transport = make_client([(200, {}, {"data": OTP_MESSAGE})])
+    _monkeypatch_transport(monkeypatch, client, transport)
+
+    client.wait("inbox_abc", timeout=60)
+
+    _, url = transport.calls[0]
+    query = urllib.parse.parse_qs(urllib.parse.urlsplit(url).query)
+    assert "since" not in query
+
+
+def test_wait_for_otp_explicit_since_zero_still_sent(monkeypatch):
+    """Explicit since=0 ("include messages already in the inbox") must still
+    be forwarded as a literal 0 on the wire."""
+    client, transport = make_client([(200, {}, {"data": OTP_MESSAGE})])
+    _monkeypatch_transport(monkeypatch, client, transport)
+
+    client.wait_for_otp("inbox_abc", timeout=60, since=0)
+
+    _, url = transport.calls[0]
+    query = urllib.parse.parse_qs(urllib.parse.urlsplit(url).query)
+    assert query["since"] == ["0"]
+
+
 def test_wait_keeps_polling_through_204s_then_returns(monkeypatch):
     responses = [
         (204, {}, None),
@@ -510,13 +575,13 @@ def test_version_exported():
 
 
 def test_metadata_consistency_across_files():
-    """0.1.3 must match everywhere: pyproject, __version__, user agent."""
+    """Version must match everywhere: pyproject, __version__, user agent."""
     import re
     import tomllib
     from pathlib import Path
 
     root = Path(__file__).resolve().parents[1]
-    expected = "0.1.3"
+    expected = "0.2.0"
 
     pyproject = tomllib.loads((root / "pyproject.toml").read_text())
     assert pyproject["project"]["version"] == expected