postern-client 0.1.0__tar.gz

postern_client-0.1.0/PKG-INFO

@@ -0,0 +1,175 @@
+Metadata-Version: 2.4
+Name: postern-client
+Version: 0.1.0
+Summary: Dependency-light Python client + CLI for the Postern mailbox API.
+Author-email: Conrad Rockenhaus <conrad@skyphusion.org>
+License: MIT
+Project-URL: Homepage, https://github.com/skyphusion-labs/postern
+Project-URL: Repository, https://github.com/skyphusion-labs/postern
+Project-URL: Documentation, https://github.com/skyphusion-labs/postern/tree/main/clients/python
+Project-URL: Issues, https://github.com/skyphusion-labs/postern/issues
+Keywords: email,postern,mailbox,agents,mcp,self-hosted,cloudflare
+Classifier: Development Status :: 4 - Beta
+Classifier: Intended Audience :: Developers
+Classifier: License :: OSI Approved :: MIT License
+Classifier: Programming Language :: Python :: 3
+Classifier: Programming Language :: Python :: 3.10
+Classifier: Programming Language :: Python :: 3.11
+Classifier: Programming Language :: Python :: 3.12
+Classifier: Topic :: Communications :: Email
+Classifier: Topic :: Software Development :: Libraries :: Python Modules
+Requires-Python: >=3.10
+Description-Content-Type: text/markdown
+Provides-Extra: dev
+Requires-Dist: mypy>=1.8; extra == "dev"
+
+# postern-client (Python)
+
+A dependency-light Python client + CLI for the **Postern mailbox API** (the
+token-gated `/api/*` surface served by the inbound/store worker). Built so crew
+agents and humans can hit the API without rebuilding tooling every session.
+
+Stack map: [docs/architecture.md](../../docs/architecture.md).
+
+```mermaid
+flowchart LR
+    script[Python script / CLI] -->|HTTPS Bearer| api[Postern Mailbox API]
+```
+
+- **Zero runtime dependencies.** Pure stdlib (`urllib`). No build step.
+- **Importable client** (`PosternClient`) and a **CLI** (`postern`).
+- **Per-user own key.** The API origin and token come from the environment
+  (`POSTERN_API_URL` / `POSTERN_API_TOKEN`); nothing is hardcoded, the token is
+  never logged, and the CLI **never** accepts the token as an argument (so it
+  cannot leak into shell history, `ps`, or argv).
+
+> Exposure posture: point `POSTERN_API_URL` at a loopback/mesh origin. The
+> project does not expose the API publicly; this client does not change that.
+
+## Install
+
+**PyPI** (recommended):
+
+```bash
+pip install postern-client
+postern --help
+```
+
+**From source** (development):
+
+```bash
+cd clients/python
+python -m venv .venv && . .venv/bin/activate
+pip install -e .            # no runtime deps; pip install -e '.[dev]' adds mypy
+```
+
+This installs the `postern` command. Without installing you can run it as a
+module: `python -m postern_client ...`.
+
+## Configure (bring your own key)
+
+```bash
+export POSTERN_API_URL=https://<the-postern-api-origin>
+export POSTERN_API_TOKEN=<your-postern-api-token>
+# verify the var is set WITHOUT echoing it:
+echo "POSTERN_API_TOKEN is ${POSTERN_API_TOKEN:+SET}"
+```
+
+See [`.env.example`](.env.example). The token is a real credential: keep it out
+of tracked files and shell history.
+
+## CLI usage
+
+```bash
+postern ping                                   # validate your token
+
+# send a message
+postern send --to alice@example.com --subject "Hello" --text "hi there"
+postern send --to a@x.com --to b@x.com --subject "Report" \
+  --html "<p>see attached thinking</p>" --header X-Tag=ops
+postern send --to a@x.com --subject "Long note" --text-file ./body.txt   # or - for stdin
+
+# reply to a stored message (threads automatically)
+postern reply <message-id> --text "thanks, got it"
+
+# list with filters + pagination
+postern list --direction inbound --limit 20
+postern list --from alice@example.com --cursor "<cursor-from-previous-page>"
+
+# read one message / a whole thread
+postern get <message-id>
+postern thread <thread-id>
+
+# search (mode: fts | semantic | hybrid)
+postern search "invoice overdue" --mode hybrid --limit 10
+
+# download the i-th attachment of a message
+postern attachment <message-id> 0 -o ./invoice.pdf
+```
+
+All commands print the API's JSON to stdout (so you can pipe into `jq`); the
+`attachment` command writes bytes to a file and prints a one-line summary to
+stderr. Exit codes: `0` ok, `1` error, `2` auth failure (bad/missing token).
+
+Override the origin (not the token) per invocation with `--api-url`:
+
+```bash
+postern --api-url http://127.0.0.1:8787 ping
+```
+
+## Library usage
+
+```python
+from postern_client import from_env, PosternClient, PosternError
+
+# build from POSTERN_API_URL / POSTERN_API_TOKEN
+client = from_env()
+
+# ...or construct explicitly (e.g. a token you loaded from your own secret store)
+client = PosternClient("https://postern.example", token)
+
+res = client.send("alice@example.com", "Hello", text="hi there")
+print(res["messageId"], res["threadId"])
+
+page = client.list_messages(direction="inbound", limit=20)
+for summary in page["items"]:
+    print(summary["messageId"], summary.get("subject"))
+if page["cursor"]:
+    nxt = client.list_messages(direction="inbound", limit=20, cursor=page["cursor"])
+
+msg = client.get_message("<message-id>")           # dict, or None if absent
+thread = client.get_thread("<thread-id>")          # list[dict]
+hits = client.search("invoice", mode="hybrid")     # {"items": [...], "cursor": ...}
+
+att = client.get_attachment("<message-id>", 0)     # Attachment(body, mime, filename)
+with open(att.filename, "wb") as fh:
+    fh.write(att.body)
+```
+
+Errors raise `PosternError` (with `.status` and the API `.code`, e.g.
+`E_FIELD_MISSING`); a bad token raises `PosternAuthError`. Methods return the
+API's parsed JSON, so the keys match the worker contract exactly.
+
+## API surface
+
+| method | endpoint | returns |
+|---|---|---|
+| `send` | `POST /api/send` | `{messageId, threadId, ...}` |
+| `reply` | `POST /api/reply` | `{messageId, threadId, ...}` |
+| `list_messages` | `GET /api/messages` | `{items: [summary], cursor}` |
+| `get_message` | `GET /api/messages/{id}` | message dict or `None` |
+| `get_thread` | `GET /api/threads/{id}` | `[message]` |
+| `search` | `GET /api/search` | `{items: [{message, ...}], cursor}` |
+| `get_attachment` | `GET /api/messages/{id}/attachments/{i}` | `Attachment(body, mime, filename)` |
+| `ping` | `GET /api/messages?limit=1` | `bool` |
+
+## Tests
+
+```bash
+cd clients/python
+python -m unittest discover -s postern_client/tests   # no network (injected transport)
+python -m mypy                                         # the type gate (house style)
+```
+
+The transport is injectable, so the suite runs entirely offline; the API is
+faked, no token or origin is needed to test.

postern_client-0.1.0/README.md

@@ -0,0 +1,150 @@
+# postern-client (Python)
+
+A dependency-light Python client + CLI for the **Postern mailbox API** (the
+token-gated `/api/*` surface served by the inbound/store worker). Built so crew
+agents and humans can hit the API without rebuilding tooling every session.
+
+Stack map: [docs/architecture.md](../../docs/architecture.md).
+
+```mermaid
+flowchart LR
+    script[Python script / CLI] -->|HTTPS Bearer| api[Postern Mailbox API]
+```
+
+- **Zero runtime dependencies.** Pure stdlib (`urllib`). No build step.
+- **Importable client** (`PosternClient`) and a **CLI** (`postern`).
+- **Per-user own key.** The API origin and token come from the environment
+  (`POSTERN_API_URL` / `POSTERN_API_TOKEN`); nothing is hardcoded, the token is
+  never logged, and the CLI **never** accepts the token as an argument (so it
+  cannot leak into shell history, `ps`, or argv).
+
+> Exposure posture: point `POSTERN_API_URL` at a loopback/mesh origin. The
+> project does not expose the API publicly; this client does not change that.
+
+## Install
+
+**PyPI** (recommended):
+
+```bash
+pip install postern-client
+postern --help
+```
+
+**From source** (development):
+
+```bash
+cd clients/python
+python -m venv .venv && . .venv/bin/activate
+pip install -e .            # no runtime deps; pip install -e '.[dev]' adds mypy
+```
+
+This installs the `postern` command. Without installing you can run it as a
+module: `python -m postern_client ...`.
+
+## Configure (bring your own key)
+
+```bash
+export POSTERN_API_URL=https://<the-postern-api-origin>
+export POSTERN_API_TOKEN=<your-postern-api-token>
+# verify the var is set WITHOUT echoing it:
+echo "POSTERN_API_TOKEN is ${POSTERN_API_TOKEN:+SET}"
+```
+
+See [`.env.example`](.env.example). The token is a real credential: keep it out
+of tracked files and shell history.
+
+## CLI usage
+
+```bash
+postern ping                                   # validate your token
+
+# send a message
+postern send --to alice@example.com --subject "Hello" --text "hi there"
+postern send --to a@x.com --to b@x.com --subject "Report" \
+  --html "<p>see attached thinking</p>" --header X-Tag=ops
+postern send --to a@x.com --subject "Long note" --text-file ./body.txt   # or - for stdin
+
+# reply to a stored message (threads automatically)
+postern reply <message-id> --text "thanks, got it"
+
+# list with filters + pagination
+postern list --direction inbound --limit 20
+postern list --from alice@example.com --cursor "<cursor-from-previous-page>"
+
+# read one message / a whole thread
+postern get <message-id>
+postern thread <thread-id>
+
+# search (mode: fts | semantic | hybrid)
+postern search "invoice overdue" --mode hybrid --limit 10
+
+# download the i-th attachment of a message
+postern attachment <message-id> 0 -o ./invoice.pdf
+```
+
+All commands print the API's JSON to stdout (so you can pipe into `jq`); the
+`attachment` command writes bytes to a file and prints a one-line summary to
+stderr. Exit codes: `0` ok, `1` error, `2` auth failure (bad/missing token).
+
+Override the origin (not the token) per invocation with `--api-url`:
+
+```bash
+postern --api-url http://127.0.0.1:8787 ping
+```
+
+## Library usage
+
+```python
+from postern_client import from_env, PosternClient, PosternError
+
+# build from POSTERN_API_URL / POSTERN_API_TOKEN
+client = from_env()
+
+# ...or construct explicitly (e.g. a token you loaded from your own secret store)
+client = PosternClient("https://postern.example", token)
+
+res = client.send("alice@example.com", "Hello", text="hi there")
+print(res["messageId"], res["threadId"])
+
+page = client.list_messages(direction="inbound", limit=20)
+for summary in page["items"]:
+    print(summary["messageId"], summary.get("subject"))
+if page["cursor"]:
+    nxt = client.list_messages(direction="inbound", limit=20, cursor=page["cursor"])
+
+msg = client.get_message("<message-id>")           # dict, or None if absent
+thread = client.get_thread("<thread-id>")          # list[dict]
+hits = client.search("invoice", mode="hybrid")     # {"items": [...], "cursor": ...}
+
+att = client.get_attachment("<message-id>", 0)     # Attachment(body, mime, filename)
+with open(att.filename, "wb") as fh:
+    fh.write(att.body)
+```
+
+Errors raise `PosternError` (with `.status` and the API `.code`, e.g.
+`E_FIELD_MISSING`); a bad token raises `PosternAuthError`. Methods return the
+API's parsed JSON, so the keys match the worker contract exactly.
+
+## API surface
+
+| method | endpoint | returns |
+|---|---|---|
+| `send` | `POST /api/send` | `{messageId, threadId, ...}` |
+| `reply` | `POST /api/reply` | `{messageId, threadId, ...}` |
+| `list_messages` | `GET /api/messages` | `{items: [summary], cursor}` |
+| `get_message` | `GET /api/messages/{id}` | message dict or `None` |
+| `get_thread` | `GET /api/threads/{id}` | `[message]` |
+| `search` | `GET /api/search` | `{items: [{message, ...}], cursor}` |
+| `get_attachment` | `GET /api/messages/{id}/attachments/{i}` | `Attachment(body, mime, filename)` |
+| `ping` | `GET /api/messages?limit=1` | `bool` |
+
+## Tests
+
+```bash
+cd clients/python
+python -m unittest discover -s postern_client/tests   # no network (injected transport)
+python -m mypy                                         # the type gate (house style)
+```
+
+The transport is injectable, so the suite runs entirely offline; the API is
+faked, no token or origin is needed to test.

postern_client-0.1.0/postern_client/__init__.py

@@ -0,0 +1,27 @@
+"""postern-client: a dependency-light Python client + CLI for the Postern mailbox API.
+
+See client.py for the importable PosternClient and cli.py for the `postern`
+command. The API origin and token come from the environment
+(POSTERN_API_URL / POSTERN_API_TOKEN); nothing is hardcoded and the token is
+never logged.
+"""
+
+from __future__ import annotations
+
+from .client import (
+    Attachment,
+    PosternAuthError,
+    PosternClient,
+    PosternError,
+    from_env,
+)
+
+__all__ = [
+    "PosternClient",
+    "PosternError",
+    "PosternAuthError",
+    "Attachment",
+    "from_env",
+]
+
+__version__ = "0.1.0"

postern_client-0.1.0/postern_client/__main__.py

@@ -0,0 +1,8 @@
+"""`python -m postern_client` entrypoint -> the CLI."""
+
+from __future__ import annotations
+
+from .cli import main
+
+if __name__ == "__main__":
+    raise SystemExit(main())

postern_client-0.1.0/postern_client/cli.py

@@ -0,0 +1,214 @@
+"""Thin CLI over the Postern API client.
+
+Usage: `postern <command> ...` (or `python -m postern_client <command> ...`).
+The API origin and token come from the environment (POSTERN_API_URL /
+POSTERN_API_TOKEN); the token is NEVER accepted as a command-line argument, so it
+cannot leak into shell history, `ps`, or argv. Results print as JSON to stdout.
+"""
+
+from __future__ import annotations
+
+import argparse
+import json
+import sys
+from typing import Optional, Sequence
+
+from .client import Attachment, PosternAuthError, PosternClient, PosternError, from_env
+
+
+def _read_body(inline: Optional[str], path: Optional[str]) -> Optional[str]:
+    """Resolve a body field from an inline string or a file ('-' = stdin)."""
+    if path is not None:
+        if path == "-":
+            return sys.stdin.read()
+        with open(path, "r", encoding="utf-8") as fh:
+            return fh.read()
+    return inline
+
+
+def _parse_headers(items: Optional[Sequence[str]]) -> dict[str, str]:
+    headers: dict[str, str] = {}
+    for item in items or []:
+        if "=" not in item:
+            raise SystemExit(f"--header must be KEY=VALUE, got: {item}")
+        key, value = item.split("=", 1)
+        headers[key.strip()] = value
+    return headers
+
+
+def _emit(obj: object) -> None:
+    json.dump(obj, sys.stdout, indent=2, ensure_ascii=False, sort_keys=True)
+    sys.stdout.write("\n")
+
+
+def build_parser() -> argparse.ArgumentParser:
+    p = argparse.ArgumentParser(
+        prog="postern",
+        description="Reusable client for the Postern mailbox API. "
+        "Reads POSTERN_API_URL and POSTERN_API_TOKEN from the environment "
+        "(the token is never a CLI argument).",
+    )
+    p.add_argument(
+        "--api-url",
+        default=None,
+        help="override POSTERN_API_URL (the token still comes only from the env)",
+    )
+    sub = p.add_subparsers(dest="command", required=True)
+
+    sub.add_parser("ping", help="validate the token against the API")
+
+    s = sub.add_parser("send", help="send a new message")
+    s.add_argument("--to", action="append", required=True, metavar="ADDR", help="recipient (repeatable)")
+    s.add_argument("--subject", required=True)
+    s.add_argument("--text", help="plain-text body")
+    s.add_argument("--text-file", help="read the plain-text body from a file ('-' = stdin)")
+    s.add_argument("--html", help="HTML body")
+    s.add_argument("--html-file", help="read the HTML body from a file ('-' = stdin)")
+    s.add_argument("--from", dest="from_addr", help="From override (must be on the allowed domain)")
+    s.add_argument("--reply-to", dest="reply_to", help="Reply-To address")
+    s.add_argument("--cc", action="append", metavar="ADDR", help="CC (repeatable)")
+    s.add_argument("--bcc", action="append", metavar="ADDR", help="BCC (repeatable)")
+    s.add_argument("--header", action="append", metavar="KEY=VALUE", help="extra header (repeatable)")
+
+    r = sub.add_parser("reply", help="reply to a stored message")
+    r.add_argument("message_id", help="message_id of the stored message to reply to")
+    r.add_argument("--text", help="plain-text body")
+    r.add_argument("--text-file", help="read the plain-text body from a file ('-' = stdin)")
+    r.add_argument("--html", help="HTML body")
+    r.add_argument("--html-file", help="read the HTML body from a file ('-' = stdin)")
+    r.add_argument("--from", dest="from_addr", help="From override (must be on the allowed domain)")
+    r.add_argument("--cc", action="append", metavar="ADDR", help="CC (repeatable)")
+    r.add_argument("--bcc", action="append", metavar="ADDR", help="BCC (repeatable)")
+
+    ls = sub.add_parser("list", help="list messages (filters + pagination)")
+    ls.add_argument("--to")
+    ls.add_argument("--from", dest="from_addr")
+    ls.add_argument("--thread")
+    ls.add_argument("--direction", choices=["inbound", "outbound"])
+    ls.add_argument("--q", help="free-text filter")
+    ls.add_argument("--limit", type=int)
+    ls.add_argument("--cursor", help="pagination cursor from a previous page")
+
+    g = sub.add_parser("get", help="get one message by id")
+    g.add_argument("message_id")
+
+    t = sub.add_parser("thread", help="get every message in a thread")
+    t.add_argument("thread_id")
+
+    sc = sub.add_parser("search", help="search messages")
+    sc.add_argument("query")
+    sc.add_argument("--mode", choices=["fts", "semantic", "hybrid"])
+    sc.add_argument("--limit", type=int)
+    sc.add_argument("--cursor")
+
+    a = sub.add_parser("attachment", help="download an attachment by message id + index")
+    a.add_argument("message_id")
+    a.add_argument("index", type=int)
+    a.add_argument("-o", "--output", help="write to this path (default: the attachment filename)")
+    return p
+
+
+def _run(client: PosternClient, args: argparse.Namespace) -> int:
+    cmd = args.command
+    if cmd == "ping":
+        ok = client.ping()
+        _emit({"ok": ok})
+        return 0 if ok else 1
+
+    if cmd == "send":
+        text = _read_body(args.text, args.text_file)
+        html = _read_body(args.html, args.html_file)
+        if text is None and html is None:
+            raise SystemExit("send needs a body: pass --text/--text-file or --html/--html-file")
+        _emit(
+            client.send(
+                args.to,
+                args.subject,
+                text=text,
+                html=html,
+                from_addr=args.from_addr,
+                reply_to=args.reply_to,
+                cc=args.cc,
+                bcc=args.bcc,
+                headers=_parse_headers(args.header),
+            )
+        )
+        return 0
+
+    if cmd == "reply":
+        text = _read_body(args.text, args.text_file)
+        html = _read_body(args.html, args.html_file)
+        if text is None and html is None:
+            raise SystemExit("reply needs a body: pass --text/--text-file or --html/--html-file")
+        _emit(
+            client.reply(
+                args.message_id,
+                text=text,
+                html=html,
+                from_addr=args.from_addr,
+                cc=args.cc,
+                bcc=args.bcc,
+            )
+        )
+        return 0
+
+    if cmd == "list":
+        _emit(
+            client.list_messages(
+                to=args.to,
+                from_addr=args.from_addr,
+                thread=args.thread,
+                direction=args.direction,
+                q=args.q,
+                limit=args.limit,
+                cursor=args.cursor,
+            )
+        )
+        return 0
+
+    if cmd == "get":
+        msg = client.get_message(args.message_id)
+        if msg is None:
+            print(f"message not found: {args.message_id}", file=sys.stderr)
+            return 1
+        _emit(msg)
+        return 0
+
+    if cmd == "thread":
+        _emit(client.get_thread(args.thread_id))
+        return 0
+
+    if cmd == "search":
+        _emit(client.search(args.query, mode=args.mode, limit=args.limit, cursor=args.cursor))
+        return 0
+
+    if cmd == "attachment":
+        att: Attachment = client.get_attachment(args.message_id, args.index)
+        out = args.output or att.filename
+        with open(out, "wb") as fh:
+            fh.write(att.body)
+        # Metadata to stderr so stdout stays clean if a caller pipes it.
+        print(f"wrote {len(att.body)} bytes to {out} ({att.mime})", file=sys.stderr)
+        return 0
+
+    raise SystemExit(f"unknown command: {cmd}")
+
+
+def main(argv: Optional[Sequence[str]] = None) -> int:
+    args = build_parser().parse_args(argv)
+    try:
+        # An origin override is fine on the CLI (not a secret); the token still
+        # comes only from POSTERN_API_TOKEN.
+        client = from_env(base_url=args.api_url, transport=None)
+        return _run(client, args)
+    except PosternAuthError as e:
+        print(f"auth failed: {e} (check POSTERN_API_TOKEN)", file=sys.stderr)
+        return 2
+    except PosternError as e:
+        detail = f" [{e.code}]" if getattr(e, "code", None) else ""
+        print(f"error{detail}: {e}", file=sys.stderr)
+        return 1
+
+
+if __name__ == "__main__":
+    raise SystemExit(main())

postern_client-0.1.0/postern_client/client.py

@@ -0,0 +1,348 @@
+"""Dependency-light client for the Postern mailbox API (CONTRACT section 4).
+
+Postern is a token-gated HTTP mailbox API served by the inbound/store worker.
+This client is the reusable Python surface over it so crew agents and humans hit
+the same API without rebuilding tooling each session. It is pure stdlib (urllib),
+mirroring the IMAP proxy's client, so it has zero runtime dependencies and is
+unit-testable without a live server (the transport is injectable).
+
+PER-USER OWN KEY: the API origin and token come from the environment
+(POSTERN_API_URL / POSTERN_API_TOKEN) or are passed explicitly; this module never
+hardcodes either and never logs the token. Each user brings their own key.
+"""
+
+from __future__ import annotations
+
+import json
+import os
+import urllib.error
+import urllib.parse
+import urllib.request
+from dataclasses import dataclass
+from typing import Any, Mapping, Optional, Sequence, Union
+
+__all__ = [
+    "PosternClient",
+    "PosternError",
+    "PosternAuthError",
+    "Attachment",
+    "from_env",
+]
+
+# A recipient field accepts a single address or a list; mirrors SendRequest.
+Addresses = Union[str, Sequence[str]]
+
+
+class PosternError(Exception):
+    """A non-2xx response or transport failure from the Postern API.
+
+    `code` is the API's stable error code (e.g. E_NOT_FOUND) when present.
+    """
+
+    def __init__(self, message: str, status: Optional[int] = None, code: Optional[str] = None) -> None:
+        super().__init__(message)
+        self.status = status
+        self.code = code
+
+
+class PosternAuthError(PosternError):
+    """401 from the Postern API: the bearer token is missing or wrong."""
+
+
+@dataclass
+class Attachment:
+    """The bytes + metadata of one fetched attachment."""
+
+    body: bytes
+    mime: str
+    filename: str
+
+
+# Injectable transport so tests supply a fake without a live server. Takes a
+# fully-formed urllib Request, returns (status, headers, body_bytes).
+class _UrllibTransport:
+    def __init__(self, timeout: float) -> None:
+        self._timeout = timeout
+
+    def __call__(self, req: urllib.request.Request) -> tuple[int, Mapping[str, str], bytes]:
+        try:
+            with urllib.request.urlopen(req, timeout=self._timeout) as resp:
+                return resp.status, dict(resp.headers), resp.read()
+        except urllib.error.HTTPError as e:
+            return e.code, dict(e.headers or {}), e.read()
+        except urllib.error.URLError as e:
+            raise PosternError(f"request failed: {e.reason}") from e
+
+
+def _addr_list(value: Optional[Addresses]) -> Optional[list[str]]:
+    if value is None:
+        return None
+    if isinstance(value, str):
+        return [value]
+    return list(value)
+
+
+class PosternClient:
+    """Client over the Postern mailbox API (read + write halves).
+
+    base_url is the worker origin (e.g. https://postern.example); token is the
+    Postern API token sent as Authorization: Bearer. The token is never logged.
+    Methods return the API's parsed JSON (dicts/lists) so the shapes match the
+    CONTRACT exactly; callers read the documented keys.
+    """
+
+    def __init__(self, base_url: str, token: str, timeout: float = 30.0, transport: Any = None) -> None:
+        if not base_url:
+            raise PosternError("base_url (POSTERN_API_URL) is required")
+        if not token:
+            raise PosternError("token (POSTERN_API_TOKEN) is required")
+        self._base = base_url.rstrip("/")
+        self._token = token
+        self._transport = transport or _UrllibTransport(timeout)
+        self._ua = "postern-client"
+
+    # --- write half ---------------------------------------------------------
+
+    def send(
+        self,
+        to: Addresses,
+        subject: str,
+        *,
+        text: Optional[str] = None,
+        html: Optional[str] = None,
+        from_addr: Optional[str] = None,
+        reply_to: Optional[str] = None,
+        cc: Optional[Addresses] = None,
+        bcc: Optional[Addresses] = None,
+        headers: Optional[Mapping[str, str]] = None,
+    ) -> dict[str, Any]:
+        """POST /api/send. Returns the SendResult ({messageId, threadId, ...})."""
+        body: dict[str, Any] = {"to": _addr_list(to), "subject": subject}
+        if text is not None:
+            body["text"] = text
+        if html is not None:
+            body["html"] = html
+        if from_addr is not None:
+            body["from"] = from_addr
+        if reply_to is not None:
+            body["replyTo"] = reply_to
+        if cc is not None:
+            body["cc"] = _addr_list(cc)
+        if bcc is not None:
+            body["bcc"] = _addr_list(bcc)
+        if headers:
+            body["headers"] = dict(headers)
+        return self._json("POST", "/api/send", body=body)
+
+    def reply(
+        self,
+        message_id: str,
+        *,
+        text: Optional[str] = None,
+        html: Optional[str] = None,
+        from_addr: Optional[str] = None,
+        cc: Optional[Addresses] = None,
+        bcc: Optional[Addresses] = None,
+    ) -> dict[str, Any]:
+        """POST /api/reply to a stored message. Returns the SendResult."""
+        body: dict[str, Any] = {"messageId": message_id}
+        if text is not None:
+            body["text"] = text
+        if html is not None:
+            body["html"] = html
+        if from_addr is not None:
+            body["from"] = from_addr
+        if cc is not None:
+            body["cc"] = _addr_list(cc)
+        if bcc is not None:
+            body["bcc"] = _addr_list(bcc)
+        return self._json("POST", "/api/reply", body=body)
+
+    # --- read half ----------------------------------------------------------
+
+    def list_messages(
+        self,
+        *,
+        to: Optional[str] = None,
+        from_addr: Optional[str] = None,
+        thread: Optional[str] = None,
+        direction: Optional[str] = None,
+        q: Optional[str] = None,
+        limit: Optional[int] = None,
+        cursor: Optional[str] = None,
+    ) -> dict[str, Any]:
+        """GET /api/messages. Returns {items: [summary...], cursor: str|None}."""
+        params: dict[str, str] = {}
+        if to:
+            params["to"] = to
+        if from_addr:
+            params["from"] = from_addr
+        if thread:
+            params["thread"] = thread
+        if direction:
+            params["direction"] = direction
+        if q:
+            params["q"] = q
+        if limit is not None:
+            params["limit"] = str(limit)
+        if cursor:
+            params["cursor"] = cursor
+        return self._json("GET", "/api/messages", params=params)
+
+    def get_message(self, message_id: str) -> Optional[dict[str, Any]]:
+        """GET /api/messages/{id}. Returns the message dict, or None if absent."""
+        try:
+            body = self._json("GET", f"/api/messages/{urllib.parse.quote(message_id, safe='')}")
+        except PosternError as e:
+            if e.status == 404:
+                return None
+            raise
+        msg = body.get("message")
+        return msg if isinstance(msg, dict) else None
+
+    def get_thread(self, thread_id: str) -> list[dict[str, Any]]:
+        """GET /api/threads/{id}. Returns the list of message dicts in the thread."""
+        body = self._json("GET", f"/api/threads/{urllib.parse.quote(thread_id, safe='')}")
+        msgs = body.get("messages", [])
+        return list(msgs) if isinstance(msgs, list) else []
+
+    def search(
+        self,
+        q: str,
+        *,
+        mode: Optional[str] = None,
+        limit: Optional[int] = None,
+        cursor: Optional[str] = None,
+    ) -> dict[str, Any]:
+        """GET /api/search. Returns {items: [{message, ...}], cursor: str|None}."""
+        params: dict[str, str] = {"q": q}
+        if mode:
+            params["mode"] = mode
+        if limit is not None:
+            params["limit"] = str(limit)
+        if cursor:
+            params["cursor"] = cursor
+        return self._json("GET", "/api/search", params=params)
+
+    def get_attachment(self, message_id: str, index: int) -> Attachment:
+        """GET /api/messages/{id}/attachments/{i}. Returns the raw Attachment bytes."""
+        path = f"/api/messages/{urllib.parse.quote(message_id, safe='')}/attachments/{int(index)}"
+        status, hdrs, raw = self._request("GET", path)
+        if status == 401:
+            raise PosternAuthError("Postern API rejected the token", status=401)
+        if status >= 400:
+            raise PosternError(f"Postern API error (HTTP {status})", status=status)
+        mime = hdrs.get("content-type") or hdrs.get("Content-Type") or "application/octet-stream"
+        disp = hdrs.get("content-disposition") or hdrs.get("Content-Disposition") or ""
+        filename = _filename_from_disposition(disp) or f"attachment-{index}"
+        return Attachment(body=raw, mime=mime, filename=filename)
+
+    def ping(self) -> bool:
+        """Validate the token by hitting an authed endpoint; True if accepted."""
+        try:
+            self._json("GET", "/api/messages", params={"limit": "1"})
+            return True
+        except PosternAuthError:
+            return False
+
+    # --- internals ----------------------------------------------------------
+
+    def _request(
+        self,
+        method: str,
+        path: str,
+        *,
+        params: Optional[dict[str, str]] = None,
+        body: Optional[dict[str, Any]] = None,
+    ) -> tuple[int, Mapping[str, str], bytes]:
+        url = self._base + path
+        if params:
+            # urlencode quotes every value, so caller-supplied filters cannot
+            # smuggle extra query params or break the URL (injection-safe).
+            url += "?" + urllib.parse.urlencode(params)
+        data = json.dumps(body).encode("utf-8") if body is not None else None
+        req = urllib.request.Request(url, data=data, method=method)
+        req.add_header("Authorization", f"Bearer {self._token}")
+        req.add_header("Accept", "application/json")
+        if data is not None:
+            req.add_header("Content-Type", "application/json")
+        # urllib's default User-Agent trips Cloudflare error 1010; identify.
+        req.add_header("User-Agent", self._ua)
+        return self._transport(req)
+
+    def _json(
+        self,
+        method: str,
+        path: str,
+        *,
+        params: Optional[dict[str, str]] = None,
+        body: Optional[dict[str, Any]] = None,
+    ) -> dict[str, Any]:
+        status, _hdrs, raw = self._request(method, path, params=params, body=body)
+        parsed: dict[str, Any] = {}
+        if raw:
+            try:
+                loaded = json.loads(raw.decode("utf-8"))
+                if isinstance(loaded, dict):
+                    parsed = loaded
+            except (ValueError, UnicodeDecodeError) as e:
+                if status < 400:
+                    raise PosternError(f"invalid JSON from Postern API: {e}") from e
+        if status == 401:
+            raise PosternAuthError(
+                parsed.get("message") or "Postern API rejected the token",
+                status=401,
+                code=parsed.get("error"),
+            )
+        if status >= 400:
+            raise PosternError(
+                parsed.get("message") or f"Postern API error (HTTP {status})",
+                status=status,
+                code=parsed.get("error"),
+            )
+        return parsed
+
+
+def _filename_from_disposition(disp: str) -> Optional[str]:
+    # content-disposition: attachment; filename="safe-name.ext"
+    marker = "filename="
+    i = disp.find(marker)
+    if i < 0:
+        return None
+    name = disp[i + len(marker):].strip()
+    if name.startswith('"'):
+        end = name.find('"', 1)
+        return name[1:end] if end > 0 else name[1:]
+    return name.split(";")[0].strip() or None
+
+
+def from_env(
+    env: Optional[Mapping[str, str]] = None,
+    *,
+    base_url: Optional[str] = None,
+    transport: Any = None,
+) -> PosternClient:
+    """Build a PosternClient from POSTERN_API_URL / POSTERN_API_TOKEN.
+
+    Per-user own key: both come from the environment, never hardcoded. The token
+    is ALWAYS read from POSTERN_API_TOKEN (never an argument), so it cannot leak
+    into argv; only the non-secret origin may be overridden via `base_url`. Raises
+    PosternError naming the missing variable so the user knows what to export.
+    """
+    e = os.environ if env is None else env
+    base = (base_url if base_url is not None else (e.get("POSTERN_API_URL") or "")).strip()
+    token = e.get("POSTERN_API_TOKEN") or ""
+    if not base:
+        raise PosternError("POSTERN_API_URL is not set (export the Postern API origin)")
+    if not base.startswith(("http://", "https://")):
+        raise PosternError("POSTERN_API_URL must start with http:// or https://")
+    if not token:
+        raise PosternError("POSTERN_API_TOKEN is not set (export your Postern API token)")
+    timeout_raw = (e.get("POSTERN_API_TIMEOUT") or "").strip()
+    timeout = 30.0
+    if timeout_raw:
+        try:
+            timeout = float(timeout_raw)
+        except ValueError as exc:
+            raise PosternError("POSTERN_API_TIMEOUT must be a number") from exc
+    return PosternClient(base, token, timeout=timeout, transport=transport)

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

@@ -0,0 +1,175 @@
+Metadata-Version: 2.4
+Name: postern-client
+Version: 0.1.0
+Summary: Dependency-light Python client + CLI for the Postern mailbox API.
+Author-email: Conrad Rockenhaus <conrad@skyphusion.org>
+License: MIT
+Project-URL: Homepage, https://github.com/skyphusion-labs/postern
+Project-URL: Repository, https://github.com/skyphusion-labs/postern
+Project-URL: Documentation, https://github.com/skyphusion-labs/postern/tree/main/clients/python
+Project-URL: Issues, https://github.com/skyphusion-labs/postern/issues
+Keywords: email,postern,mailbox,agents,mcp,self-hosted,cloudflare
+Classifier: Development Status :: 4 - Beta
+Classifier: Intended Audience :: Developers
+Classifier: License :: OSI Approved :: MIT License
+Classifier: Programming Language :: Python :: 3
+Classifier: Programming Language :: Python :: 3.10
+Classifier: Programming Language :: Python :: 3.11
+Classifier: Programming Language :: Python :: 3.12
+Classifier: Topic :: Communications :: Email
+Classifier: Topic :: Software Development :: Libraries :: Python Modules
+Requires-Python: >=3.10
+Description-Content-Type: text/markdown
+Provides-Extra: dev
+Requires-Dist: mypy>=1.8; extra == "dev"
+
+# postern-client (Python)
+
+A dependency-light Python client + CLI for the **Postern mailbox API** (the
+token-gated `/api/*` surface served by the inbound/store worker). Built so crew
+agents and humans can hit the API without rebuilding tooling every session.
+
+Stack map: [docs/architecture.md](../../docs/architecture.md).
+
+```mermaid
+flowchart LR
+    script[Python script / CLI] -->|HTTPS Bearer| api[Postern Mailbox API]
+```
+
+- **Zero runtime dependencies.** Pure stdlib (`urllib`). No build step.
+- **Importable client** (`PosternClient`) and a **CLI** (`postern`).
+- **Per-user own key.** The API origin and token come from the environment
+  (`POSTERN_API_URL` / `POSTERN_API_TOKEN`); nothing is hardcoded, the token is
+  never logged, and the CLI **never** accepts the token as an argument (so it
+  cannot leak into shell history, `ps`, or argv).
+
+> Exposure posture: point `POSTERN_API_URL` at a loopback/mesh origin. The
+> project does not expose the API publicly; this client does not change that.
+
+## Install
+
+**PyPI** (recommended):
+
+```bash
+pip install postern-client
+postern --help
+```
+
+**From source** (development):
+
+```bash
+cd clients/python
+python -m venv .venv && . .venv/bin/activate
+pip install -e .            # no runtime deps; pip install -e '.[dev]' adds mypy
+```
+
+This installs the `postern` command. Without installing you can run it as a
+module: `python -m postern_client ...`.
+
+## Configure (bring your own key)
+
+```bash
+export POSTERN_API_URL=https://<the-postern-api-origin>
+export POSTERN_API_TOKEN=<your-postern-api-token>
+# verify the var is set WITHOUT echoing it:
+echo "POSTERN_API_TOKEN is ${POSTERN_API_TOKEN:+SET}"
+```
+
+See [`.env.example`](.env.example). The token is a real credential: keep it out
+of tracked files and shell history.
+
+## CLI usage
+
+```bash
+postern ping                                   # validate your token
+
+# send a message
+postern send --to alice@example.com --subject "Hello" --text "hi there"
+postern send --to a@x.com --to b@x.com --subject "Report" \
+  --html "<p>see attached thinking</p>" --header X-Tag=ops
+postern send --to a@x.com --subject "Long note" --text-file ./body.txt   # or - for stdin
+
+# reply to a stored message (threads automatically)
+postern reply <message-id> --text "thanks, got it"
+
+# list with filters + pagination
+postern list --direction inbound --limit 20
+postern list --from alice@example.com --cursor "<cursor-from-previous-page>"
+
+# read one message / a whole thread
+postern get <message-id>
+postern thread <thread-id>
+
+# search (mode: fts | semantic | hybrid)
+postern search "invoice overdue" --mode hybrid --limit 10
+
+# download the i-th attachment of a message
+postern attachment <message-id> 0 -o ./invoice.pdf
+```
+
+All commands print the API's JSON to stdout (so you can pipe into `jq`); the
+`attachment` command writes bytes to a file and prints a one-line summary to
+stderr. Exit codes: `0` ok, `1` error, `2` auth failure (bad/missing token).
+
+Override the origin (not the token) per invocation with `--api-url`:
+
+```bash
+postern --api-url http://127.0.0.1:8787 ping
+```
+
+## Library usage
+
+```python
+from postern_client import from_env, PosternClient, PosternError
+
+# build from POSTERN_API_URL / POSTERN_API_TOKEN
+client = from_env()
+
+# ...or construct explicitly (e.g. a token you loaded from your own secret store)
+client = PosternClient("https://postern.example", token)
+
+res = client.send("alice@example.com", "Hello", text="hi there")
+print(res["messageId"], res["threadId"])
+
+page = client.list_messages(direction="inbound", limit=20)
+for summary in page["items"]:
+    print(summary["messageId"], summary.get("subject"))
+if page["cursor"]:
+    nxt = client.list_messages(direction="inbound", limit=20, cursor=page["cursor"])
+
+msg = client.get_message("<message-id>")           # dict, or None if absent
+thread = client.get_thread("<thread-id>")          # list[dict]
+hits = client.search("invoice", mode="hybrid")     # {"items": [...], "cursor": ...}
+
+att = client.get_attachment("<message-id>", 0)     # Attachment(body, mime, filename)
+with open(att.filename, "wb") as fh:
+    fh.write(att.body)
+```
+
+Errors raise `PosternError` (with `.status` and the API `.code`, e.g.
+`E_FIELD_MISSING`); a bad token raises `PosternAuthError`. Methods return the
+API's parsed JSON, so the keys match the worker contract exactly.
+
+## API surface
+
+| method | endpoint | returns |
+|---|---|---|
+| `send` | `POST /api/send` | `{messageId, threadId, ...}` |
+| `reply` | `POST /api/reply` | `{messageId, threadId, ...}` |
+| `list_messages` | `GET /api/messages` | `{items: [summary], cursor}` |
+| `get_message` | `GET /api/messages/{id}` | message dict or `None` |
+| `get_thread` | `GET /api/threads/{id}` | `[message]` |
+| `search` | `GET /api/search` | `{items: [{message, ...}], cursor}` |
+| `get_attachment` | `GET /api/messages/{id}/attachments/{i}` | `Attachment(body, mime, filename)` |
+| `ping` | `GET /api/messages?limit=1` | `bool` |
+
+## Tests
+
+```bash
+cd clients/python
+python -m unittest discover -s postern_client/tests   # no network (injected transport)
+python -m mypy                                         # the type gate (house style)
+```
+
+The transport is injectable, so the suite runs entirely offline; the API is
+faked, no token or origin is needed to test.

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

@@ -0,0 +1,12 @@
+README.md
+pyproject.toml
+postern_client/__init__.py
+postern_client/__main__.py
+postern_client/cli.py
+postern_client/client.py
+postern_client.egg-info/PKG-INFO
+postern_client.egg-info/SOURCES.txt
+postern_client.egg-info/dependency_links.txt
+postern_client.egg-info/entry_points.txt
+postern_client.egg-info/requires.txt
+postern_client.egg-info/top_level.txt

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

@@ -0,0 +1 @@
+

postern_client-0.1.0/postern_client.egg-info/entry_points.txt

@@ -0,0 +1,2 @@
+[console_scripts]
+postern = postern_client.cli:main

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

@@ -0,0 +1,3 @@
+
+[dev]
+mypy>=1.8

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

@@ -0,0 +1 @@
+postern_client

postern_client-0.1.0/pyproject.toml

@@ -0,0 +1,51 @@
+[build-system]
+requires = ["setuptools>=68"]
+build-backend = "setuptools.build_meta"
+
+[project]
+name = "postern-client"
+version = "0.1.0"
+description = "Dependency-light Python client + CLI for the Postern mailbox API."
+readme = "README.md"
+requires-python = ">=3.10"
+license = { text = "MIT" }
+authors = [{ name = "Conrad Rockenhaus", email = "conrad@skyphusion.org" }]
+keywords = ["email", "postern", "mailbox", "agents", "mcp", "self-hosted", "cloudflare"]
+classifiers = [
+  "Development Status :: 4 - Beta",
+  "Intended Audience :: Developers",
+  "License :: OSI Approved :: MIT License",
+  "Programming Language :: Python :: 3",
+  "Programming Language :: Python :: 3.10",
+  "Programming Language :: Python :: 3.11",
+  "Programming Language :: Python :: 3.12",
+  "Topic :: Communications :: Email",
+  "Topic :: Software Development :: Libraries :: Python Modules",
+]
+# Pure stdlib (urllib): zero runtime dependencies, so it drops into any agent or
+# script without a build step. The transport is injectable, so tests need nothing.
+dependencies = []
+
+[project.urls]
+Homepage = "https://github.com/skyphusion-labs/postern"
+Repository = "https://github.com/skyphusion-labs/postern"
+Documentation = "https://github.com/skyphusion-labs/postern/tree/main/clients/python"
+Issues = "https://github.com/skyphusion-labs/postern/issues"
+
+[project.optional-dependencies]
+# Tests use stdlib unittest only; mypy is the type gate (house convention, mirrors
+# the worker's `tsc --noEmit`).
+dev = ["mypy>=1.8"]
+
+[project.scripts]
+postern = "postern_client.cli:main"
+
+[tool.setuptools]
+packages = ["postern_client"]
+
+[tool.mypy]
+python_version = "3.10"
+warn_unused_ignores = true
+warn_redundant_casts = true
+files = ["postern_client"]
+exclude = "postern_client/tests/"

postern_client-0.1.0/setup.cfg

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