mailsocket 0.1.3__tar.gz → 0.3.0__tar.gz

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

@@ -1,6 +1,6 @@
 Metadata-Version: 2.4
 Name: mailsocket
-Version: 0.1.3
+Version: 0.3.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
@@ -30,17 +31,34 @@ The official Python client for the [mailsocket](https://mailsocket.app) v1 REST
 Ephemeral email inboxes, message retrieval, and — the whole point — **wait for the OTP in one line**.
 
 ```python
+import time
+
 from mailsocket import Client
 
 client = Client("ms_live_...")            # your API key from the dashboard
 inbox = client.create_inbox(label="signup")  # -> {"id": "inbox_...", "address": "..."}
 
+started = time.time()                         # take the cutoff BEFORE the trigger
 # hand inbox["address"] to whatever form sends the code, then:
-result = client.wait_for_otp(inbox["id"])     # blocks up to 60s
+result = client.wait_for_otp(inbox["id"], since=started)  # blocks up to 60s
 print(result.otp)         # "123456"
 print(result.confidence)  # 0.95
 ```
 
+Take `started` just before you trigger the email and pass it as `since`: a
+code that lands before `wait_for_otp` starts is still caught, and an older
+code in a reused inbox is not.
+
+No email handy? `client.send_test_code(inbox_id)` drops a sample code into
+the inbox so you can see the whole loop work:
+
+```python
+started = time.time()
+client.send_test_code(inbox["id"])            # -> {"message_id": "msg_...", "sent_at": "..."}
+result = client.wait_for_otp(inbox["id"], since=started)
+print(result.otp)         # the sample code
+```
+
 No polling loop. No regex over the email body. `wait_for_otp` long-polls the
 server (which already knows how to extract the code) and hands back a
 deterministic result with a confidence score.
@@ -68,13 +86,22 @@ client = Client(api_key, base_url="https://dash.mailsocket.app/api/v1")
 | `list_messages(inbox_id, has_otp=None, subject_contains=None, sender=None, ...)` | `Page` — `sender` maps to the API's `from` filter |
 | `get_latest(inbox_id)` | `dict` — newest message |
 | `get_message(message_id)` | `dict` — full message |
+| `send_test_code(inbox_id)` | `dict` — `message_id`, `sent_at` of a sample OTP email put straight into the inbox (no mail server; 5 per inbox / 20 per account per hour) |
 
 ### 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
+```
+
+With a cutoff taken before the trigger (the usual case):
+
+```python
+started = time.time()
+# trigger the email here
+result = client.wait_for_otp("inbox_abc123", since=started)
 ```
 
 All three return a `WaitResult` and take keyword-only arguments after
@@ -83,9 +110,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).
@@ -104,11 +138,16 @@ Semantics:
 `MailsocketError` (base) with subclasses:
 
 - `AuthError` — HTTP 401 (bad/missing key).
-- `NotFound` — HTTP 404.
+- `NotFound` — HTTP 404 (also an unknown, deleted or foreign inbox in
+  `send_test_code`).
 - `RateLimited` — HTTP 429, carries `.subcode` (`rate_limited`,
   `too_many_wait_requests`, `wait_capacity`) and `.retry_after`.
 - `WaitTimeout` — no matching message within the overall deadline.
 
+`send_test_code` on a disabled inbox raises the base `MailsocketError` with
+`code="inbox_disabled"` and `status=409`. Over its hourly quota it raises
+`RateLimited`; `.retry_after` says how many seconds until it frees up.
+
 ## Develop
 
 ```bash
@@ -123,4 +162,13 @@ invalid id never reaches the network.
 
 ## Changelog
 
+- **0.3.0** — new `Client.send_test_code(inbox_id)` (`POST /inboxes/{id}/test-code`):
+  puts one sample OTP email into your own inbox without going through the
+  mail server, and returns `{"message_id", "sent_at"}`. README samples now
+  take `started = time.time()` before the trigger and pass `since=started`.
+- **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.3.0}/README.md

@@ -4,17 +4,34 @@ The official Python client for the [mailsocket](https://mailsocket.app) v1 REST
 Ephemeral email inboxes, message retrieval, and — the whole point — **wait for the OTP in one line**.
 
 ```python
+import time
+
 from mailsocket import Client
 
 client = Client("ms_live_...")            # your API key from the dashboard
 inbox = client.create_inbox(label="signup")  # -> {"id": "inbox_...", "address": "..."}
 
+started = time.time()                         # take the cutoff BEFORE the trigger
 # hand inbox["address"] to whatever form sends the code, then:
-result = client.wait_for_otp(inbox["id"])     # blocks up to 60s
+result = client.wait_for_otp(inbox["id"], since=started)  # blocks up to 60s
 print(result.otp)         # "123456"
 print(result.confidence)  # 0.95
 ```
 
+Take `started` just before you trigger the email and pass it as `since`: a
+code that lands before `wait_for_otp` starts is still caught, and an older
+code in a reused inbox is not.
+
+No email handy? `client.send_test_code(inbox_id)` drops a sample code into
+the inbox so you can see the whole loop work:
+
+```python
+started = time.time()
+client.send_test_code(inbox["id"])            # -> {"message_id": "msg_...", "sent_at": "..."}
+result = client.wait_for_otp(inbox["id"], since=started)
+print(result.otp)         # the sample code
+```
+
 No polling loop. No regex over the email body. `wait_for_otp` long-polls the
 server (which already knows how to extract the code) and hands back a
 deterministic result with a confidence score.
@@ -42,13 +59,22 @@ client = Client(api_key, base_url="https://dash.mailsocket.app/api/v1")
 | `list_messages(inbox_id, has_otp=None, subject_contains=None, sender=None, ...)` | `Page` — `sender` maps to the API's `from` filter |
 | `get_latest(inbox_id)` | `dict` — newest message |
 | `get_message(message_id)` | `dict` — full message |
+| `send_test_code(inbox_id)` | `dict` — `message_id`, `sent_at` of a sample OTP email put straight into the inbox (no mail server; 5 per inbox / 20 per account per hour) |
 
 ### 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
+```
+
+With a cutoff taken before the trigger (the usual case):
+
+```python
+started = time.time()
+# trigger the email here
+result = client.wait_for_otp("inbox_abc123", since=started)
 ```
 
 All three return a `WaitResult` and take keyword-only arguments after
@@ -57,9 +83,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).
@@ -78,11 +111,16 @@ Semantics:
 `MailsocketError` (base) with subclasses:
 
 - `AuthError` — HTTP 401 (bad/missing key).
-- `NotFound` — HTTP 404.
+- `NotFound` — HTTP 404 (also an unknown, deleted or foreign inbox in
+  `send_test_code`).
 - `RateLimited` — HTTP 429, carries `.subcode` (`rate_limited`,
   `too_many_wait_requests`, `wait_capacity`) and `.retry_after`.
 - `WaitTimeout` — no matching message within the overall deadline.
 
+`send_test_code` on a disabled inbox raises the base `MailsocketError` with
+`code="inbox_disabled"` and `status=409`. Over its hourly quota it raises
+`RateLimited`; `.retry_after` says how many seconds until it frees up.
+
 ## Develop
 
 ```bash
@@ -97,4 +135,13 @@ invalid id never reaches the network.
 
 ## Changelog
 
+- **0.3.0** — new `Client.send_test_code(inbox_id)` (`POST /inboxes/{id}/test-code`):
+  puts one sample OTP email into your own inbox without going through the
+  mail server, and returns `{"message_id", "sent_at"}`. README samples now
+  take `started = time.time()` before the trigger and pass `since=started`.
+- **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.3.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.3.0"
 
 __all__ = [
     "Client",

{mailsocket-0.1.3 → mailsocket-0.3.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):
@@ -184,6 +201,25 @@ class Client:
         payload = self._request("GET", f"/messages/{_seg(message_id)}")
         return payload["data"]
 
+    def send_test_code(self, inbox_id: str) -> dict:
+        """Put one sample OTP email (a random 6-digit code) into ``inbox_id``.
+
+        Calls ``POST /inboxes/{id}/test-code`` and returns its ``data`` dict:
+        ``{"message_id": "msg_...", "sent_at": "..."}``. The message does NOT
+        go through the mail server: it is stored and parsed like real inbound
+        mail, so a pending or later wait (with a ``since`` from before this
+        call) returns it. Use it to prove the wait loop end to end without
+        sending real email.
+
+        Shares the dashboard "Send a test code" quota (5 per inbox, 20 per
+        account per hour). Errors: :class:`NotFound` for an unknown, deleted
+        or foreign inbox; :class:`RateLimited` (with ``retry_after``) over the
+        quota; :class:`MailsocketError` with ``code="inbox_disabled"``
+        (HTTP 409) for a disabled inbox.
+        """
+        payload = self._request("POST", f"/inboxes/{_seg(inbox_id)}/test-code")
+        return payload["data"]
+
     # -- the moat -------------------------------------------------------------
 
     def wait_for_otp(
@@ -192,9 +228,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 +246,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 +262,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 +339,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.3.0",
         }
         headers.update(self._extra_headers)
         # Set last so nothing in extra_headers can ever replace it.

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

@@ -1,6 +1,6 @@
 Metadata-Version: 2.4
 Name: mailsocket
-Version: 0.1.3
+Version: 0.3.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
@@ -30,17 +31,34 @@ The official Python client for the [mailsocket](https://mailsocket.app) v1 REST
 Ephemeral email inboxes, message retrieval, and — the whole point — **wait for the OTP in one line**.
 
 ```python
+import time
+
 from mailsocket import Client
 
 client = Client("ms_live_...")            # your API key from the dashboard
 inbox = client.create_inbox(label="signup")  # -> {"id": "inbox_...", "address": "..."}
 
+started = time.time()                         # take the cutoff BEFORE the trigger
 # hand inbox["address"] to whatever form sends the code, then:
-result = client.wait_for_otp(inbox["id"])     # blocks up to 60s
+result = client.wait_for_otp(inbox["id"], since=started)  # blocks up to 60s
 print(result.otp)         # "123456"
 print(result.confidence)  # 0.95
 ```
 
+Take `started` just before you trigger the email and pass it as `since`: a
+code that lands before `wait_for_otp` starts is still caught, and an older
+code in a reused inbox is not.
+
+No email handy? `client.send_test_code(inbox_id)` drops a sample code into
+the inbox so you can see the whole loop work:
+
+```python
+started = time.time()
+client.send_test_code(inbox["id"])            # -> {"message_id": "msg_...", "sent_at": "..."}
+result = client.wait_for_otp(inbox["id"], since=started)
+print(result.otp)         # the sample code
+```
+
 No polling loop. No regex over the email body. `wait_for_otp` long-polls the
 server (which already knows how to extract the code) and hands back a
 deterministic result with a confidence score.
@@ -68,13 +86,22 @@ client = Client(api_key, base_url="https://dash.mailsocket.app/api/v1")
 | `list_messages(inbox_id, has_otp=None, subject_contains=None, sender=None, ...)` | `Page` — `sender` maps to the API's `from` filter |
 | `get_latest(inbox_id)` | `dict` — newest message |
 | `get_message(message_id)` | `dict` — full message |
+| `send_test_code(inbox_id)` | `dict` — `message_id`, `sent_at` of a sample OTP email put straight into the inbox (no mail server; 5 per inbox / 20 per account per hour) |
 
 ### 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
+```
+
+With a cutoff taken before the trigger (the usual case):
+
+```python
+started = time.time()
+# trigger the email here
+result = client.wait_for_otp("inbox_abc123", since=started)
 ```
 
 All three return a `WaitResult` and take keyword-only arguments after
@@ -83,9 +110,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).
@@ -104,11 +138,16 @@ Semantics:
 `MailsocketError` (base) with subclasses:
 
 - `AuthError` — HTTP 401 (bad/missing key).
-- `NotFound` — HTTP 404.
+- `NotFound` — HTTP 404 (also an unknown, deleted or foreign inbox in
+  `send_test_code`).
 - `RateLimited` — HTTP 429, carries `.subcode` (`rate_limited`,
   `too_many_wait_requests`, `wait_capacity`) and `.retry_after`.
 - `WaitTimeout` — no matching message within the overall deadline.
 
+`send_test_code` on a disabled inbox raises the base `MailsocketError` with
+`code="inbox_disabled"` and `status=409`. Over its hourly quota it raises
+`RateLimited`; `.retry_after` says how many seconds until it frees up.
+
 ## Develop
 
 ```bash
@@ -123,4 +162,13 @@ invalid id never reaches the network.
 
 ## Changelog
 
+- **0.3.0** — new `Client.send_test_code(inbox_id)` (`POST /inboxes/{id}/test-code`):
+  puts one sample OTP email into your own inbox without going through the
+  mail server, and returns `{"message_id", "sent_at"}`. README samples now
+  take `started = time.time()` before the trigger and pass `since=started`.
+- **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.3.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.3.0}/pyproject.toml

@@ -4,7 +4,7 @@ build-backend = "setuptools.build_meta"
 
 [project]
 name = "mailsocket"
-version = "0.1.3"
+version = "0.3.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.3.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),
@@ -492,6 +557,7 @@ def test_invalid_id_rejected_before_any_request_hits_real_server(raw):
             lambda: client.wait_for_otp(raw, timeout=5),
             lambda: client.wait_for_link(raw, timeout=5),
             lambda: client.wait(raw, timeout=5),
+            lambda: client.send_test_code(raw),
         ]
         for call in calls:
             with pytest.raises(MailsocketError) as exc_info:
@@ -510,13 +576,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.3.0"
 
     pyproject = tomllib.loads((root / "pyproject.toml").read_text())
     assert pyproject["project"]["version"] == expected
@@ -592,3 +658,138 @@ def test_no_extra_headers_is_backwards_compatible(monkeypatch):
     sent = capture.headers[0]
     assert set(sent) >= {"authorization", "accept", "user-agent"}
     assert "x-forwarded-proto" not in sent
+
+
+# -- send_test_code (POST /inboxes/{id}/test-code) ----------------------------
+
+TEST_CODE_DATA = {"message_id": "msg_test1", "sent_at": "2026-10-08T12:00:00Z"}
+
+
+def test_send_test_code_posts_and_returns_data(monkeypatch):
+    client, transport = make_client([(201, {}, {"data": TEST_CODE_DATA})])
+    _monkeypatch_transport(monkeypatch, client, transport)
+
+    data = client.send_test_code("inbox_abc")
+
+    assert data == TEST_CODE_DATA
+    assert transport.calls == [("POST", "https://example.test/api/v1/inboxes/inbox_abc/test-code")]
+
+
+def test_send_test_code_sends_no_body(monkeypatch):
+    seen = []
+
+    def capture(request, timeout=None):
+        seen.append((request.get_method(), request.data, dict(request.header_items())))
+
+        class _Resp:
+            headers = {}
+
+            def getcode(self):
+                return 201
+
+            def read(self):
+                return json.dumps({"data": TEST_CODE_DATA}).encode()
+
+            def __enter__(self):
+                return self
+
+            def __exit__(self, *exc_info):
+                return False
+
+        return _Resp()
+
+    monkeypatch.setattr("urllib.request.urlopen", capture)
+    Client("ms_live_test1234567890", base_url="https://example.test/api/v1").send_test_code("inbox_abc")
+    method, body, headers = seen[0]
+    assert method == "POST"
+    assert body is None
+    assert headers["Authorization"] == "Bearer ms_live_test1234567890"
+
+
+def test_send_test_code_encodes_id_as_one_segment(monkeypatch):
+    client, transport = make_client([(201, {}, {"data": TEST_CODE_DATA})])
+    _monkeypatch_transport(monkeypatch, client, transport)
+
+    client.send_test_code("a/b?c")
+
+    assert transport.calls[0][1] == "https://example.test/api/v1/inboxes/a%2Fb%3Fc/test-code"
+
+
+def test_send_test_code_404_raises_not_found(monkeypatch):
+    responses = [(404, {}, {"error": {"code": "not_found", "message": "Resource not found.", "fields": {}}})]
+    client, transport = make_client(responses)
+    _monkeypatch_transport(monkeypatch, client, transport)
+
+    with pytest.raises(NotFound) as exc_info:
+        client.send_test_code("inbox_foreign")
+    assert exc_info.value.status == 404
+
+
+def test_send_test_code_429_raises_rate_limited_with_retry_after(monkeypatch):
+    slept = []
+    monkeypatch.setattr(mailsocket.client, "_sleep", lambda s: slept.append(s))
+    responses = [
+        (
+            429,
+            {"Retry-After": "1800"},
+            {"error": {"code": "rate_limited", "message": "Too many test codes. Try again at 13:00 UTC.", "fields": {}}},
+        )
+    ]
+    client, transport = make_client(responses)
+    _monkeypatch_transport(monkeypatch, client, transport)
+
+    with pytest.raises(RateLimited) as exc_info:
+        client.send_test_code("inbox_abc")
+    err = exc_info.value
+    assert err.retry_after == 1800.0
+    assert err.subcode == "rate_limited"
+    assert "Try again at" in str(err)
+    assert len(transport.calls) == 1  # never retried
+    assert slept == []
+
+
+def test_send_test_code_disabled_inbox_raises_mailsocket_error(monkeypatch):
+    responses = [
+        (
+            409,
+            {},
+            {"error": {"code": "inbox_disabled", "message": "This inbox is disabled. Enable it to receive a test code.", "fields": {}}},
+        )
+    ]
+    client, transport = make_client(responses)
+    _monkeypatch_transport(monkeypatch, client, transport)
+
+    with pytest.raises(MailsocketError) as exc_info:
+        client.send_test_code("inbox_abc")
+    err = exc_info.value
+    assert type(err) is MailsocketError
+    assert err.code == "inbox_disabled"
+    assert err.status == 409
+
+
+def test_send_test_code_401_raises_auth_error(monkeypatch):
+    responses = [(401, {}, {"error": {"code": "authentication_required", "message": "Auth required.", "fields": {}}})]
+    client, transport = make_client(responses)
+    _monkeypatch_transport(monkeypatch, client, transport)
+
+    with pytest.raises(AuthError):
+        client.send_test_code("inbox_abc")
+
+
+def test_readme_wait_samples_take_a_cutoff_before_the_trigger():
+    """Every runnable wait sample in the README passes since=started, with
+    started taken before the trigger (ux4 SDK follow-up)."""
+    from pathlib import Path
+
+    readme = (Path(__file__).resolve().parents[1] / "README.md").read_text()
+    blocks = readme.split("```python")[1:]
+    samples = [b.split("```")[0] for b in blocks]
+    waits = [s for s in samples if "wait_for_otp(" in s and "since=None" not in s]
+    assert waits, "no wait sample found"
+    for sample in waits:
+        assert "started = time.time()" in sample
+        assert sample.index("started = time.time()") < sample.index("wait_for_otp(")
+        for line in sample.splitlines():
+            if "wait_for_otp(" in line or "wait_for_link(" in line:
+                assert "since=" in line, line
+    assert "client.send_test_code(inbox" in readme