mailsocket 0.2.0__tar.gz → 0.3.0__tar.gz

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

@@ -1,6 +1,6 @@
 Metadata-Version: 2.4
 Name: mailsocket
-Version: 0.2.0
+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
@@ -31,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.
@@ -69,6 +86,7 @@ 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
 
@@ -78,6 +96,14 @@ 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
 `inbox_id`. `timeout`/`min_confidence`/`since` shown above are the defaults —
 call with no extra arguments for the common case.
@@ -112,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
@@ -131,6 +162,10 @@ 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

{mailsocket-0.2.0 → 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,6 +59,7 @@ 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
 
@@ -51,6 +69,14 @@ 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
 `inbox_id`. `timeout`/`min_confidence`/`since` shown above are the defaults —
 call with no extra arguments for the common case.
@@ -85,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
@@ -104,6 +135,10 @@ 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

{mailsocket-0.2.0 → 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.2.0"
+__version__ = "0.3.0"
 
 __all__ = [
     "Client",

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

@@ -201,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(
@@ -320,7 +339,7 @@ class Client:
             url += "?" + urllib.parse.urlencode(params, doseq=True)
         headers = {
             "Accept": "application/json",
-            "User-Agent": "mailsocket-python/0.2.0",
+            "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.2.0 → mailsocket-0.3.0}/mailsocket.egg-info/PKG-INFO

@@ -1,6 +1,6 @@
 Metadata-Version: 2.4
 Name: mailsocket
-Version: 0.2.0
+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
@@ -31,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.
@@ -69,6 +86,7 @@ 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
 
@@ -78,6 +96,14 @@ 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
 `inbox_id`. `timeout`/`min_confidence`/`since` shown above are the defaults —
 call with no extra arguments for the common case.
@@ -112,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
@@ -131,6 +162,10 @@ 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

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

@@ -4,7 +4,7 @@ build-backend = "setuptools.build_meta"
 
 [project]
 name = "mailsocket"
-version = "0.2.0"
+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"

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

@@ -557,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:
@@ -581,7 +582,7 @@ def test_metadata_consistency_across_files():
     from pathlib import Path
 
     root = Path(__file__).resolve().parents[1]
-    expected = "0.2.0"
+    expected = "0.3.0"
 
     pyproject = tomllib.loads((root / "pyproject.toml").read_text())
     assert pyproject["project"]["version"] == expected
@@ -657,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