mailsocket 0.1.0__tar.gz

mailsocket-0.1.0/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 mailsocket
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

mailsocket-0.1.0/PKG-INFO

@@ -0,0 +1,108 @@
+Metadata-Version: 2.4
+Name: mailsocket
+Version: 0.1.0
+Summary: Official Python client for the mailsocket REST API — one line to wait for an OTP.
+Author: mailsocket
+License-Expression: MIT
+Project-URL: Homepage, https://mailsocket.app
+Project-URL: Documentation, https://dash.mailsocket.app/docs
+Keywords: mailsocket,email,otp,inbox,magic-link
+Classifier: Intended Audience :: Developers
+Classifier: Operating System :: OS Independent
+Classifier: Programming Language :: Python :: 3
+Classifier: Programming Language :: Python :: 3.9
+Classifier: Programming Language :: Python :: 3.10
+Classifier: Programming Language :: Python :: 3.11
+Classifier: Programming Language :: Python :: 3.12
+Classifier: Topic :: Communications :: Email
+Requires-Python: >=3.9
+Description-Content-Type: text/markdown
+License-File: LICENSE
+Provides-Extra: dev
+Requires-Dist: pytest>=7; extra == "dev"
+Dynamic: license-file
+
+# mailsocket — Python SDK
+
+The official Python client for the [mailsocket](https://mailsocket.app) v1 REST API.
+Ephemeral email inboxes, message retrieval, and — the whole point — **wait for the OTP in one line**.
+
+```python
+from mailsocket import Client
+
+client = Client("ms_live_...")            # your API key from the dashboard
+inbox = client.create_inbox(label="signup")  # -> {"id": "inbox_...", "address": "..."}
+
+# hand inbox["address"] to whatever form sends the code, then:
+result = client.wait_for_otp(inbox["id"])     # blocks up to 60s
+print(result.otp)         # "123456"
+print(result.confidence)  # 0.95
+```
+
+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.
+
+## Install
+
+```bash
+pip install mailsocket
+```
+
+Zero runtime dependencies — pure standard library (`urllib`). Python 3.9+.
+
+## API
+
+```python
+client = Client(api_key, base_url="https://dash.mailsocket.app/api/v1")
+```
+
+| Method | Returns |
+| --- | --- |
+| `create_inbox(label=None)` | `dict` — the inbox (`id`, `address`, ...) |
+| `list_inboxes(limit=None, cursor=None)` | `Page` — `.data` list + `.next_cursor` / `.has_more` |
+| `get_inbox(inbox_id)` | `dict` — inbox plus `message_count_month`, `webhook_configured` |
+| `delete_inbox(inbox_id)` | `None` |
+| `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 |
+
+### The moat
+
+```python
+result = client.wait_for_otp(inbox_id, *, timeout=60, min_confidence=0.0, since=0) -> WaitResult
+result = client.wait_for_link(inbox_id, *, timeout=60, since=0)                       -> WaitResult
+result = client.wait(inbox_id, *, timeout=60, min_confidence=0.0, since=0)            -> WaitResult  # otp OR link
+```
+
+`WaitResult` exposes `.otp`, `.confidence`, `.magic_link` (and `.link` as an
+alias), plus the full `.message` dict. `str(result)` is the OTP (or the link).
+
+Semantics:
+
+- Each HTTP call blocks server-side for up to 25s (`timeout` is clamped to
+  `[1, 25]`); the SDK re-calls until the **overall** `timeout` (seconds,
+  default 60) elapses.
+- `200` → the matching message. `204` → nothing yet, re-call immediately.
+- `429` → honours `Retry-After` and retries within the deadline. `404` → raises.
+- On overall deadline → `WaitTimeout`.
+
+## Errors
+
+`MailsocketError` (base) with subclasses:
+
+- `AuthError` — HTTP 401 (bad/missing key).
+- `NotFound` — HTTP 404.
+- `RateLimited` — HTTP 429, carries `.subcode` (`rate_limited`,
+  `too_many_wait_requests`, `wait_capacity`) and `.retry_after`.
+- `WaitTimeout` — no matching message within the overall deadline.
+
+## Develop
+
+```bash
+cd sdks/python
+python -m pytest -q
+```
+
+Tests are fully offline — they monkeypatch `urllib.request.urlopen` with a
+scripted responder, so nothing touches the live API.

mailsocket-0.1.0/README.md

@@ -0,0 +1,84 @@
+# mailsocket — Python SDK
+
+The official Python client for the [mailsocket](https://mailsocket.app) v1 REST API.
+Ephemeral email inboxes, message retrieval, and — the whole point — **wait for the OTP in one line**.
+
+```python
+from mailsocket import Client
+
+client = Client("ms_live_...")            # your API key from the dashboard
+inbox = client.create_inbox(label="signup")  # -> {"id": "inbox_...", "address": "..."}
+
+# hand inbox["address"] to whatever form sends the code, then:
+result = client.wait_for_otp(inbox["id"])     # blocks up to 60s
+print(result.otp)         # "123456"
+print(result.confidence)  # 0.95
+```
+
+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.
+
+## Install
+
+```bash
+pip install mailsocket
+```
+
+Zero runtime dependencies — pure standard library (`urllib`). Python 3.9+.
+
+## API
+
+```python
+client = Client(api_key, base_url="https://dash.mailsocket.app/api/v1")
+```
+
+| Method | Returns |
+| --- | --- |
+| `create_inbox(label=None)` | `dict` — the inbox (`id`, `address`, ...) |
+| `list_inboxes(limit=None, cursor=None)` | `Page` — `.data` list + `.next_cursor` / `.has_more` |
+| `get_inbox(inbox_id)` | `dict` — inbox plus `message_count_month`, `webhook_configured` |
+| `delete_inbox(inbox_id)` | `None` |
+| `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 |
+
+### The moat
+
+```python
+result = client.wait_for_otp(inbox_id, *, timeout=60, min_confidence=0.0, since=0) -> WaitResult
+result = client.wait_for_link(inbox_id, *, timeout=60, since=0)                       -> WaitResult
+result = client.wait(inbox_id, *, timeout=60, min_confidence=0.0, since=0)            -> WaitResult  # otp OR link
+```
+
+`WaitResult` exposes `.otp`, `.confidence`, `.magic_link` (and `.link` as an
+alias), plus the full `.message` dict. `str(result)` is the OTP (or the link).
+
+Semantics:
+
+- Each HTTP call blocks server-side for up to 25s (`timeout` is clamped to
+  `[1, 25]`); the SDK re-calls until the **overall** `timeout` (seconds,
+  default 60) elapses.
+- `200` → the matching message. `204` → nothing yet, re-call immediately.
+- `429` → honours `Retry-After` and retries within the deadline. `404` → raises.
+- On overall deadline → `WaitTimeout`.
+
+## Errors
+
+`MailsocketError` (base) with subclasses:
+
+- `AuthError` — HTTP 401 (bad/missing key).
+- `NotFound` — HTTP 404.
+- `RateLimited` — HTTP 429, carries `.subcode` (`rate_limited`,
+  `too_many_wait_requests`, `wait_capacity`) and `.retry_after`.
+- `WaitTimeout` — no matching message within the overall deadline.
+
+## Develop
+
+```bash
+cd sdks/python
+python -m pytest -q
+```
+
+Tests are fully offline — they monkeypatch `urllib.request.urlopen` with a
+scripted responder, so nothing touches the live API.

mailsocket-0.1.0/mailsocket/__init__.py

@@ -0,0 +1,17 @@
+"""Official Python SDK for the mailsocket v1 REST API."""
+
+from .client import Client, Page, WaitResult
+from .errors import AuthError, MailsocketError, NotFound, RateLimited, WaitTimeout
+
+__version__ = "0.1.0"
+
+__all__ = [
+    "Client",
+    "Page",
+    "WaitResult",
+    "MailsocketError",
+    "AuthError",
+    "NotFound",
+    "RateLimited",
+    "WaitTimeout",
+]

mailsocket-0.1.0/mailsocket/client.py

@@ -0,0 +1,329 @@
+"""Synchronous HTTP client for the mailsocket v1 REST API.
+
+Pure standard library (``urllib``) — no runtime dependencies.
+"""
+
+from __future__ import annotations
+
+import json
+import time as _time
+import urllib.error
+import urllib.parse
+import urllib.request
+
+from .errors import AuthError, MailsocketError, NotFound, RateLimited, WaitTimeout
+
+DEFAULT_BASE_URL = "https://dash.mailsocket.app/api/v1"
+WAIT_TIMEOUT_MAX = 25  # seconds — the server clamps the per-call wait to [1, 25]
+WAIT_SOCKET_BUFFER = 10  # seconds of client-side slack above the server block
+DEFAULT_RETRY_AFTER = 1.0  # seconds, when a 429 carries no Retry-After header
+
+__all__ = ["Client", "Page", "WaitResult"]
+
+
+def _monotonic() -> float:
+    return _time.monotonic()
+
+
+def _sleep(seconds: float) -> None:
+    _time.sleep(seconds)
+
+
+class Page:
+    """A page of results plus its pagination metadata.
+
+    Behaves like a list of ``.data`` while exposing ``.pagination``,
+    ``.next_cursor`` and ``.has_more``.
+    """
+
+    def __init__(self, data: list, pagination: dict | None):
+        self.data = data
+        self.pagination = pagination or {}
+
+    @property
+    def next_cursor(self):
+        return self.pagination.get("next_cursor")
+
+    @property
+    def has_more(self) -> bool:
+        return bool(self.pagination.get("has_more"))
+
+    def __len__(self) -> int:
+        return len(self.data)
+
+    def __iter__(self):
+        return iter(self.data)
+
+    def __getitem__(self, index):
+        return self.data[index]
+
+    def __repr__(self) -> str:
+        return f"Page(data={self.data!r}, pagination={self.pagination!r})"
+
+
+class WaitResult:
+    """The outcome of a ``wait_for_otp`` / ``wait_for_link`` / ``wait`` call."""
+
+    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")
+
+    @property
+    def link(self):
+        """Alias for ``magic_link``."""
+        return self.magic_link
+
+    def __repr__(self) -> str:
+        return (
+            f"WaitResult(otp={self.otp!r}, confidence={self.confidence!r}, "
+            f"magic_link={self.magic_link!r})"
+        )
+
+    def __str__(self) -> str:
+        return self.otp if self.otp is not None else (self.magic_link or "")
+
+
+class Client:
+    """A thin, synchronous client for the mailsocket v1 REST API."""
+
+    def __init__(
+        self,
+        api_key: str,
+        base_url: str = DEFAULT_BASE_URL,
+        *,
+        request_timeout: float = 30.0,
+    ):
+        if not api_key:
+            raise ValueError("api_key is required")
+        self._api_key = api_key
+        self._base_url = base_url.rstrip("/")
+        self._request_timeout = request_timeout
+
+    # -- public API -----------------------------------------------------------
+
+    def create_inbox(self, label: str | None = None) -> dict:
+        body = {} if label is None else {"label": label}
+        payload = self._request("POST", "/inboxes", json_body=body)
+        return payload["data"]
+
+    def list_inboxes(self, limit: int | None = None, cursor: str | None = None) -> Page:
+        payload = self._request("GET", "/inboxes", params=self._page_params(limit, cursor))
+        return Page(payload["data"], payload.get("pagination"))
+
+    def get_inbox(self, inbox_id: str) -> dict:
+        payload = self._request("GET", f"/inboxes/{inbox_id}")
+        return payload["data"]
+
+    def delete_inbox(self, inbox_id: str) -> None:
+        self._request("DELETE", f"/inboxes/{inbox_id}")
+
+    def list_messages(
+        self,
+        inbox_id: str,
+        has_otp: bool | None = None,
+        subject_contains: str | None = None,
+        sender: str | None = None,
+        limit: int | None = None,
+        cursor: str | None = None,
+    ) -> Page:
+        params = self._page_params(limit, cursor)
+        if has_otp is not None:
+            params["has_otp"] = "true" if has_otp else "false"
+        if subject_contains:
+            params["subject_contains"] = subject_contains
+        if sender:
+            params["from"] = sender  # the API names this filter ``from``
+        payload = self._request("GET", f"/inboxes/{inbox_id}/messages", params=params)
+        return Page(payload["data"], payload.get("pagination"))
+
+    def get_latest(self, inbox_id: str) -> dict:
+        payload = self._request("GET", f"/inboxes/{inbox_id}/messages/latest")
+        return payload["data"]
+
+    def get_message(self, message_id: str) -> dict:
+        payload = self._request("GET", f"/messages/{message_id}")
+        return payload["data"]
+
+    # -- the moat -------------------------------------------------------------
+
+    def wait_for_otp(
+        self,
+        inbox_id: str,
+        *,
+        timeout: float = 60.0,
+        min_confidence: float = 0.0,
+        since=0,
+    ) -> WaitResult:
+        """Wait for an OTP. Returns a :class:`WaitResult` with ``.otp`` etc."""
+        return self._wait(
+            inbox_id,
+            require="otp",
+            timeout=timeout,
+            min_confidence=min_confidence,
+            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``."""
+        return self._wait(
+            inbox_id, require="link", timeout=timeout, min_confidence=None, since=since
+        )
+
+    def wait(
+        self,
+        inbox_id: str,
+        *,
+        timeout: float = 60.0,
+        min_confidence: float = 0.0,
+        since=0,
+    ) -> WaitResult:
+        """Wait for either an OTP or a magic link."""
+        return self._wait(
+            inbox_id,
+            require="any",
+            timeout=timeout,
+            min_confidence=min_confidence,
+            since=since,
+        )
+
+    # -- internals ------------------------------------------------------------
+
+    def _wait(
+        self,
+        inbox_id: str,
+        *,
+        require: str,
+        timeout: float,
+        min_confidence: float | None,
+        since,
+    ) -> WaitResult:
+        deadline = _monotonic() + float(timeout)
+        while True:
+            remaining = deadline - _monotonic()
+            if remaining <= 0:
+                raise WaitTimeout(
+                    f"No matching message arrived within {timeout:g}s.", code="wait_timeout"
+                )
+            server_timeout = max(1.0, min(float(WAIT_TIMEOUT_MAX), remaining))
+            params = {"timeout": server_timeout, "require": require}
+            if since is not None:
+                params["since"] = since
+            if min_confidence is not None:
+                params["min_confidence"] = min_confidence
+
+            status, headers, body = self._request_http(
+                "GET",
+                f"/inboxes/{inbox_id}/messages/wait",
+                params=params,
+                socket_timeout=server_timeout + WAIT_SOCKET_BUFFER,
+            )
+            payload = self._parse_json(body)
+            if status == 200:
+                return WaitResult(payload["data"])
+            if status == 204:
+                continue
+            if status == 429:
+                retry_after = self._retry_after(headers)
+                sleep_for = retry_after if retry_after is not None else DEFAULT_RETRY_AFTER
+                if _monotonic() + sleep_for > deadline:
+                    raise WaitTimeout(
+                        f"No matching message arrived within {timeout:g}s.", code="wait_timeout"
+                    )
+                _sleep(sleep_for)
+                continue
+            self._raise_for_status(status, headers, payload)
+
+    def _request(self, method: str, path: str, *, params: dict | None = None, json_body=None):
+        status, headers, body = self._request_http(method, path, params=params, json_body=json_body)
+        payload = self._parse_json(body)
+        if 200 <= status < 300:
+            return payload
+        self._raise_for_status(status, headers, payload)
+
+    def _request_http(self, method, path, *, params=None, json_body=None, socket_timeout=None):
+        url = self._base_url + path
+        if params:
+            url += "?" + urllib.parse.urlencode(params, doseq=True)
+        headers = {
+            "Authorization": f"Bearer {self._api_key}",
+            "Accept": "application/json",
+            "User-Agent": "mailsocket-python/0.1.0",
+        }
+        data = None
+        if json_body is not None:
+            data = json.dumps(json_body).encode("utf-8")
+            headers["Content-Type"] = "application/json"
+        request = urllib.request.Request(url, data=data, headers=headers, method=method)
+        timeout = socket_timeout if socket_timeout is not None else self._request_timeout
+        try:
+            with urllib.request.urlopen(request, timeout=timeout) as response:
+                status = response.getcode()
+                response_headers = {k.lower(): v for k, v in response.headers.items()}
+                body = response.read()
+        except urllib.error.HTTPError as exc:
+            status = exc.code
+            response_headers = {k.lower(): v for k, v in exc.headers.items()}
+            body = exc.read()
+        except urllib.error.URLError as exc:
+            raise MailsocketError(f"Network error: {exc.reason}") from exc
+        return status, response_headers, body
+
+    def _raise_for_status(self, status: int, headers: dict, payload):
+        code = None
+        message = None
+        if isinstance(payload, dict) and isinstance(payload.get("error"), dict):
+            err = payload["error"]
+            code = err.get("code")
+            message = err.get("message")
+        if status == 401:
+            raise AuthError(
+                message or "Authentication required.",
+                code=code or "authentication_required",
+                status=401,
+            )
+        if status == 404:
+            raise NotFound(
+                message or "Resource not found.", code=code or "not_found", status=404
+            )
+        if status == 429:
+            raise RateLimited(
+                message or "Rate limit exceeded.",
+                code=code or "rate_limited",
+                subcode=code,
+                retry_after=self._retry_after(headers),
+            )
+        raise MailsocketError(message or f"HTTP {status}", code=code, status=status)
+
+    @staticmethod
+    def _parse_json(body: bytes) -> dict:
+        if not body:
+            return {}
+        try:
+            decoded = json.loads(body.decode("utf-8"))
+        except (ValueError, UnicodeDecodeError):
+            return {}
+        return decoded if isinstance(decoded, dict) else {}
+
+    @staticmethod
+    def _retry_after(headers: dict) -> float | None:
+        value = headers.get("retry-after")
+        if value is None:
+            return None
+        try:
+            seconds = float(value)
+        except (TypeError, ValueError):
+            return None
+        # A negative Retry-After (malformed server/proxy) must never become a
+        # negative sleep; clamp to 0 so the loop re-polls immediately instead.
+        return max(0.0, seconds)
+
+    @staticmethod
+    def _page_params(limit, cursor) -> dict:
+        params = {}
+        if limit is not None:
+            params["limit"] = limit
+        if cursor is not None:
+            params["cursor"] = cursor
+        return params

mailsocket-0.1.0/mailsocket/errors.py

@@ -0,0 +1,47 @@
+"""Typed exceptions raised by the mailsocket Python SDK."""
+
+from __future__ import annotations
+
+
+class MailsocketError(Exception):
+    """Base class for every error the SDK raises."""
+
+    def __init__(
+        self, message: str, *, code: str | None = None, status: int | None = None
+    ):
+        super().__init__(message)
+        self.code = code
+        self.status = status
+
+
+class AuthError(MailsocketError):
+    """The API key is missing or invalid (HTTP 401)."""
+
+
+class NotFound(MailsocketError):
+    """The requested resource does not exist or is not owned (HTTP 404)."""
+
+
+class RateLimited(MailsocketError):
+    """A rate limit was hit (HTTP 429).
+
+    Carries ``subcode`` (the server error code, e.g. ``rate_limited``,
+    ``too_many_wait_requests`` or ``wait_capacity``) and ``retry_after``
+    (seconds to wait, from the ``Retry-After`` header, or ``None``).
+    """
+
+    def __init__(
+        self,
+        message: str,
+        *,
+        code: str | None = None,
+        subcode: str | None = None,
+        retry_after: float | None = None,
+    ):
+        super().__init__(message, code=code, status=429)
+        self.subcode = subcode
+        self.retry_after = retry_after
+
+
+class WaitTimeout(MailsocketError):
+    """No matching message arrived before the overall wait deadline."""

mailsocket-0.1.0/mailsocket.egg-info/PKG-INFO

@@ -0,0 +1,108 @@
+Metadata-Version: 2.4
+Name: mailsocket
+Version: 0.1.0
+Summary: Official Python client for the mailsocket REST API — one line to wait for an OTP.
+Author: mailsocket
+License-Expression: MIT
+Project-URL: Homepage, https://mailsocket.app
+Project-URL: Documentation, https://dash.mailsocket.app/docs
+Keywords: mailsocket,email,otp,inbox,magic-link
+Classifier: Intended Audience :: Developers
+Classifier: Operating System :: OS Independent
+Classifier: Programming Language :: Python :: 3
+Classifier: Programming Language :: Python :: 3.9
+Classifier: Programming Language :: Python :: 3.10
+Classifier: Programming Language :: Python :: 3.11
+Classifier: Programming Language :: Python :: 3.12
+Classifier: Topic :: Communications :: Email
+Requires-Python: >=3.9
+Description-Content-Type: text/markdown
+License-File: LICENSE
+Provides-Extra: dev
+Requires-Dist: pytest>=7; extra == "dev"
+Dynamic: license-file
+
+# mailsocket — Python SDK
+
+The official Python client for the [mailsocket](https://mailsocket.app) v1 REST API.
+Ephemeral email inboxes, message retrieval, and — the whole point — **wait for the OTP in one line**.
+
+```python
+from mailsocket import Client
+
+client = Client("ms_live_...")            # your API key from the dashboard
+inbox = client.create_inbox(label="signup")  # -> {"id": "inbox_...", "address": "..."}
+
+# hand inbox["address"] to whatever form sends the code, then:
+result = client.wait_for_otp(inbox["id"])     # blocks up to 60s
+print(result.otp)         # "123456"
+print(result.confidence)  # 0.95
+```
+
+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.
+
+## Install
+
+```bash
+pip install mailsocket
+```
+
+Zero runtime dependencies — pure standard library (`urllib`). Python 3.9+.
+
+## API
+
+```python
+client = Client(api_key, base_url="https://dash.mailsocket.app/api/v1")
+```
+
+| Method | Returns |
+| --- | --- |
+| `create_inbox(label=None)` | `dict` — the inbox (`id`, `address`, ...) |
+| `list_inboxes(limit=None, cursor=None)` | `Page` — `.data` list + `.next_cursor` / `.has_more` |
+| `get_inbox(inbox_id)` | `dict` — inbox plus `message_count_month`, `webhook_configured` |
+| `delete_inbox(inbox_id)` | `None` |
+| `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 |
+
+### The moat
+
+```python
+result = client.wait_for_otp(inbox_id, *, timeout=60, min_confidence=0.0, since=0) -> WaitResult
+result = client.wait_for_link(inbox_id, *, timeout=60, since=0)                       -> WaitResult
+result = client.wait(inbox_id, *, timeout=60, min_confidence=0.0, since=0)            -> WaitResult  # otp OR link
+```
+
+`WaitResult` exposes `.otp`, `.confidence`, `.magic_link` (and `.link` as an
+alias), plus the full `.message` dict. `str(result)` is the OTP (or the link).
+
+Semantics:
+
+- Each HTTP call blocks server-side for up to 25s (`timeout` is clamped to
+  `[1, 25]`); the SDK re-calls until the **overall** `timeout` (seconds,
+  default 60) elapses.
+- `200` → the matching message. `204` → nothing yet, re-call immediately.
+- `429` → honours `Retry-After` and retries within the deadline. `404` → raises.
+- On overall deadline → `WaitTimeout`.
+
+## Errors
+
+`MailsocketError` (base) with subclasses:
+
+- `AuthError` — HTTP 401 (bad/missing key).
+- `NotFound` — HTTP 404.
+- `RateLimited` — HTTP 429, carries `.subcode` (`rate_limited`,
+  `too_many_wait_requests`, `wait_capacity`) and `.retry_after`.
+- `WaitTimeout` — no matching message within the overall deadline.
+
+## Develop
+
+```bash
+cd sdks/python
+python -m pytest -q
+```
+
+Tests are fully offline — they monkeypatch `urllib.request.urlopen` with a
+scripted responder, so nothing touches the live API.

mailsocket-0.1.0/mailsocket.egg-info/SOURCES.txt

@@ -0,0 +1,12 @@
+LICENSE
+README.md
+pyproject.toml
+mailsocket/__init__.py
+mailsocket/client.py
+mailsocket/errors.py
+mailsocket.egg-info/PKG-INFO
+mailsocket.egg-info/SOURCES.txt
+mailsocket.egg-info/dependency_links.txt
+mailsocket.egg-info/requires.txt
+mailsocket.egg-info/top_level.txt
+tests/test_client.py

mailsocket-0.1.0/mailsocket.egg-info/dependency_links.txt

@@ -0,0 +1 @@
+

mailsocket-0.1.0/mailsocket.egg-info/requires.txt

@@ -0,0 +1,3 @@
+
+[dev]
+pytest>=7

mailsocket-0.1.0/mailsocket.egg-info/top_level.txt

@@ -0,0 +1 @@
+mailsocket

mailsocket-0.1.0/pyproject.toml

@@ -0,0 +1,39 @@
+[build-system]
+requires = ["setuptools>=61"]
+build-backend = "setuptools.build_meta"
+
+[project]
+name = "mailsocket"
+version = "0.1.0"
+description = "Official Python client for the mailsocket REST API — one line to wait for an OTP."
+readme = "README.md"
+requires-python = ">=3.9"
+license = "MIT"
+license-files = ["LICENSE"]
+authors = [{ name = "mailsocket" }]
+keywords = ["mailsocket", "email", "otp", "inbox", "magic-link"]
+classifiers = [
+    "Intended Audience :: Developers",
+    "Operating System :: OS Independent",
+    "Programming Language :: Python :: 3",
+    "Programming Language :: Python :: 3.9",
+    "Programming Language :: Python :: 3.10",
+    "Programming Language :: Python :: 3.11",
+    "Programming Language :: Python :: 3.12",
+    "Topic :: Communications :: Email",
+]
+dependencies = []
+
+[project.optional-dependencies]
+dev = ["pytest>=7"]
+
+[project.urls]
+Homepage = "https://mailsocket.app"
+Documentation = "https://dash.mailsocket.app/docs"
+
+[tool.setuptools]
+packages = ["mailsocket"]
+
+[tool.pytest.ini_options]
+testpaths = ["tests"]
+pythonpath = ["."]

mailsocket-0.1.0/setup.cfg

@@ -0,0 +1,4 @@
+[egg_info]
+tag_build = 
+tag_date = 0
+

mailsocket-0.1.0/tests/test_client.py

@@ -0,0 +1,356 @@
+"""Offline unit tests for the mailsocket Python SDK (mocked transport, no network)."""
+
+import json
+
+import pytest
+
+import mailsocket
+from mailsocket import AuthError, MailsocketError, NotFound, RateLimited, WaitTimeout
+from mailsocket.client import Client, WaitResult
+
+OTP_MESSAGE = {
+    "id": "msg_123",
+    "inbox_id": "inbox_abc",
+    "from": "Acme <no-reply@acme.test>",
+    "to": ["user@in.inboxpipe.net"],
+    "cc": [],
+    "subject": "Your code",
+    "received_at": "2026-09-23T12:00:00Z",
+    "status": "parsed",
+    "otp": "123456",
+    "otp_confidence": 0.95,
+    "magic_link": None,
+    "links": [],
+    "detected_otp": "123456",
+    "envelope_from": "no-reply@acme.test",
+    "envelope_recipient": "user@in.inboxpipe.net",
+    "text": "Code: 123456",
+    "html": "<p>Code: 123456</p>",
+}
+
+LINK_MESSAGE = {
+    **OTP_MESSAGE,
+    "id": "msg_456",
+    "otp": None,
+    "otp_confidence": None,
+    "magic_link": "https://example.test/go?token=abc",
+    "links": ["https://example.test/go?token=abc"],
+}
+
+
+class FakeTransport:
+    """A scripted urllib transport recorded by the SDK."""
+
+    def __init__(self, responses):
+        self.responses = list(responses)  # list of (status, headers, payload)
+        self.calls = []  # list of (method, url) in call order
+
+    def __call__(self, request, timeout=None):
+        import io
+        from urllib.error import HTTPError
+
+        url = request.full_url
+        self.calls.append((request.get_method(), url))
+        status, headers, payload = self.responses.pop(0)
+        body = json.dumps(payload).encode("utf-8") if payload is not None else b""
+
+        class _Resp:
+            def __init__(self, status, headers, body):
+                self.status = status
+                self.headers = headers
+                self._body = body
+
+            def getcode(self):
+                return self.status
+
+            def read(self):
+                return self._body
+
+            def __enter__(self):
+                return self
+
+            def __exit__(self, *exc_info):
+                return False
+
+        if status >= 400:
+            raise HTTPError(url, status, "http error", headers, io.BytesIO(body))
+        return _Resp(status, headers, body)
+
+
+def make_client(responses, **kwargs):
+    transport = FakeTransport(responses)
+    client = Client("ms_live_test1234567890", base_url="https://example.test/api/v1", **kwargs)
+    return client, transport
+
+
+@pytest.fixture
+def client_factory(monkeypatch):
+    def build(responses, **kwargs):
+        client, transport = make_client(responses, **kwargs)
+        return client, transport
+
+    return build
+
+
+def _monkeypatch_transport(monkeypatch, client, transport):
+    monkeypatch.setattr("urllib.request.urlopen", transport)
+
+
+def test_wait_for_otp_returns_on_first_200(monkeypatch):
+    client, transport = make_client([(200, {}, {"data": OTP_MESSAGE})])
+    _monkeypatch_transport(monkeypatch, client, transport)
+
+    result = client.wait_for_otp("inbox_abc", timeout=60)
+
+    assert isinstance(result, WaitResult)
+    assert result.otp == "123456"
+    assert result.confidence == 0.95
+    assert str(result) == "123456"
+    assert len(transport.calls) == 1
+
+
+def test_wait_keeps_polling_through_204s_then_returns(monkeypatch):
+    responses = [
+        (204, {}, None),
+        (204, {}, None),
+        (200, {}, {"data": OTP_MESSAGE}),
+    ]
+    client, transport = make_client(responses)
+    _monkeypatch_transport(monkeypatch, client, transport)
+
+    result = client.wait_for_otp("inbox_abc", timeout=60)
+
+    assert result.otp == "123456"
+    assert len(transport.calls) == 3
+    # server-side timeout stays clamped to <= 25s on every call
+    for _, url in transport.calls:
+        assert "timeout=" in url
+        assert "require=otp" in url
+
+
+def test_wait_respects_overall_timeout_raises_wait_timeout(monkeypatch):
+    # A 204 means "the server blocked for `timeout` seconds and found nothing".
+    # Model that with a controllable clock: each 204 advances time by the
+    # server-side timeout requested, so the overall client deadline (60s) is
+    # eventually exhausted across multiple 25s-clamped calls.
+    import urllib.parse
+
+    clock = [0.0]
+    calls = []
+
+    def fake_open(request, timeout=None):
+        url = request.full_url
+        calls.append(url)
+        qs = urllib.parse.parse_qs(urllib.parse.urlsplit(url).query)
+        server_timeout = float(qs["timeout"][0])
+        clock[0] += server_timeout  # the server blocked this long
+
+        class _Resp:
+            def getcode(self):
+                return 204
+
+            def read(self):
+                return b""
+
+            @property
+            def headers(self):
+                return {}
+
+            def __enter__(self):
+                return self
+
+            def __exit__(self, *exc_info):
+                return False
+
+        return _Resp()
+
+    monkeypatch.setattr("urllib.request.urlopen", fake_open)
+    monkeypatch.setattr(mailsocket.client, "_monotonic", lambda: clock[0])
+    monkeypatch.setattr(mailsocket.client, "_sleep", lambda s: clock.__setitem__(0, clock[0] + s))
+
+    client = Client("ms_live_test1234567890", base_url="https://example.test/api/v1")
+
+    with pytest.raises(WaitTimeout):
+        client.wait_for_otp("inbox_abc", timeout=60)
+
+    # Server-side timeout was clamped to 25 on every call but the last.
+    requested = [
+        float(urllib.parse.parse_qs(urllib.parse.urlsplit(u).query)["timeout"][0]) for u in calls
+    ]
+    assert all(t <= 25 for t in requested)
+    assert requested[-1] <= 25
+
+
+def test_wait_429_parses_subcode_and_retries(monkeypatch):
+    responses = [
+        (
+            429,
+            {"Retry-After": "0"},
+            {"error": {"code": "too_many_wait_requests", "message": "Too many", "fields": {}}},
+        ),
+        (200, {}, {"data": OTP_MESSAGE}),
+    ]
+    client, transport = make_client(responses)
+    _monkeypatch_transport(monkeypatch, client, transport)
+
+    result = client.wait_for_otp("inbox_abc", timeout=60)
+
+    assert result.otp == "123456"
+    assert len(transport.calls) == 2
+
+
+def test_wait_429_raises_rate_limited_with_subcode_on_non_wait_endpoint(monkeypatch):
+    responses = [
+        (
+            429,
+            {"Retry-After": "7"},
+            {"error": {"code": "rate_limited", "message": "Rate limit exceeded.", "fields": {}}},
+        ),
+    ]
+    client, transport = make_client(responses)
+    _monkeypatch_transport(monkeypatch, client, transport)
+
+    with pytest.raises(RateLimited) as exc_info:
+        client.list_inboxes()
+
+    assert exc_info.value.subcode == "rate_limited"
+    assert exc_info.value.retry_after == 7.0
+    assert exc_info.value.status == 429
+
+
+def test_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) as exc_info:
+        client.list_inboxes()
+
+    assert exc_info.value.code == "authentication_required"
+
+
+def test_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):
+        client.get_inbox("inbox_missing")
+
+
+def test_wait_404_raises_not_found_immediately(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):
+        client.wait_for_otp("inbox_missing", timeout=60)
+
+
+def test_list_messages_maps_filter_params(monkeypatch):
+    responses = [(200, {}, {"data": [OTP_MESSAGE], "pagination": {"next_cursor": None, "has_more": False}})]
+    client, transport = make_client(responses)
+    _monkeypatch_transport(monkeypatch, client, transport)
+
+    page = client.list_messages("inbox_abc", has_otp=True, subject_contains="code", sender="acme.test")
+
+    assert page.has_more is False
+    assert page.next_cursor is None
+    assert len(page) == 1
+    assert page[0]["id"] == "msg_123"
+
+    url = transport.calls[0][1]
+    assert "has_otp=true" in url
+    assert "subject_contains=code" in url
+    assert "from=acme.test" in url  # sender is mapped to the API's `from` param
+
+
+def test_from_json_key_handled_on_message_dict(monkeypatch):
+    responses = [(200, {}, {"data": OTP_MESSAGE})]
+    client, transport = make_client(responses)
+    _monkeypatch_transport(monkeypatch, client, transport)
+
+    msg = client.get_message("msg_123")
+
+    assert msg["from"] == "Acme <no-reply@acme.test>"
+
+
+def test_wait_for_link_returns_link(monkeypatch):
+    responses = [(200, {}, {"data": LINK_MESSAGE})]
+    client, transport = make_client(responses)
+    _monkeypatch_transport(monkeypatch, client, transport)
+
+    result = client.wait_for_link("inbox_abc", timeout=60)
+
+    assert result.magic_link == "https://example.test/go?token=abc"
+    assert result.link == result.magic_link
+    assert result.otp is None
+    _, url = transport.calls[0]
+    assert "require=link" in url
+
+
+def test_wait_any_returns_otp_or_link(monkeypatch):
+    responses = [(200, {}, {"data": OTP_MESSAGE})]
+    client, transport = make_client(responses)
+    _monkeypatch_transport(monkeypatch, client, transport)
+
+    result = client.wait("inbox_abc", timeout=60)
+
+    assert result.otp == "123456"
+    _, url = transport.calls[0]
+    assert "require=any" in url
+
+
+def test_create_inbox_sends_label_and_parses_data(monkeypatch):
+    inbox = {
+        "id": "inbox_new",
+        "label": "signup",
+        "address": "x@in.inboxpipe.net",
+        "is_enabled": True,
+        "created_at": "2026-09-23T12:00:00Z",
+        "updated_at": "2026-09-23T12:00:00Z",
+    }
+    responses = [(201, {}, {"data": inbox})]
+    client, transport = make_client(responses)
+    _monkeypatch_transport(monkeypatch, client, transport)
+
+    result = client.create_inbox(label="signup")
+
+    assert result["id"] == "inbox_new"
+    method, url = transport.calls[0]
+    assert method == "POST"
+
+
+def test_create_inbox_without_label_sends_empty_body(monkeypatch):
+    inbox = {
+        "id": "inbox_new",
+        "label": "",
+        "address": "x@in.inboxpipe.net",
+        "is_enabled": True,
+        "created_at": "2026-09-23T12:00:00Z",
+        "updated_at": "2026-09-23T12:00:00Z",
+    }
+    responses = [(201, {}, {"data": inbox})]
+    client, transport = make_client(responses)
+    _monkeypatch_transport(monkeypatch, client, transport)
+
+    client.create_inbox()
+
+    assert len(transport.calls) == 1
+
+
+def test_error_types_are_mailsocket_subclasses():
+    assert issubclass(AuthError, MailsocketError)
+    assert issubclass(NotFound, MailsocketError)
+    assert issubclass(RateLimited, MailsocketError)
+    assert issubclass(WaitTimeout, MailsocketError)
+
+
+def test_version_exported():
+    assert hasattr(mailsocket, "__version__")