vexity 0.1.0__tar.gz

vexity-0.1.0/.gitignore

@@ -0,0 +1,6 @@
+.venv/
+dist/
+__pycache__/
+.pytest_cache/
+.ruff_cache/
+*.out

vexity-0.1.0/LICENSE

@@ -0,0 +1,25 @@
+MIT License
+
+Copyright (c) 2026 Vexity
+
+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.
+
+The MIT licence covers the code of this package only. Use of the Vexity API and
+of the data it returns is governed by the Vexity Terms and Conditions
+(https://vexity.net/terms) and the Redistribution Policy (https://vexity.net/redistribution).

vexity-0.1.0/PKG-INFO

@@ -0,0 +1,79 @@
+Metadata-Version: 2.5
+Name: vexity
+Version: 0.1.0
+Summary: Official Python client for the Vexity options-analytics API: ETag-aware reads, incremental windows and the live socket.
+Author-email: Vexity <vexity@jzn-management.com>
+License: MIT License
+        
+        Copyright (c) 2026 Vexity
+        
+        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.
+        
+        The MIT licence covers the code of this package only. Use of the Vexity API and
+        of the data it returns is governed by the Vexity Terms and Conditions
+        (https://vexity.net/terms) and the Redistribution Policy (https://vexity.net/redistribution).
+License-File: LICENSE
+Keywords: api-client,gamma-exposure,options,vexity
+Requires-Python: >=3.11
+Requires-Dist: httpx>=0.27
+Requires-Dist: msgpack>=1.0
+Requires-Dist: websockets>=13
+Requires-Dist: zstandard>=0.23; python_version < '3.14'
+Description-Content-Type: text/markdown
+
+# vexity
+
+Official Python client for the [Vexity](https://vexity.net) options-analytics API.
+
+```python
+import vexity
+
+client = vexity.Vexity()                      # reads VEXITY_API_KEY
+levels = client.levels("SPX", scope="full")   # the JSON body, as a dict
+
+window = client.window("series", "SPX", names="spot,net_gex_oi", scope="latest", step="1m", span="2h")
+update = window.poll()                        # the first call reads the window; later calls read only the tail and merge it
+
+with client.live() as live:                   # zstd socket, redials by the server's own client policy
+    live.subscribe("levels", "SPX", scope="full", every_ms=5000)
+    for event in live:
+        print(event)
+```
+
+What it does for you, with no flags:
+
+- Sends `If-None-Match` and stores answers. A 304 saves the body, not the request, and happens only on reads that move slowly (contracts, surface, series envelopes, a window between chain cycles): live levels, frame and grid bodies change every second, so poll them rarely or use the socket. A closed window (`immutable`) is served from the store with no request, and `Vexity(store=EtagStore(directory=...))` keeps it across runs.
+- `Window` reads a live window once in full (following `next_cursor`), then asks `from=<the step boundary at or before the newest held timestamp>` (the newest timestamp itself on an aligned series, so the first returned bucket is a whole one) and merges by the documented rule: drop the held points at or after the answer's first timestamp, append the answer. A step of a session day is read in full each poll. A frame read with neither `from` nor `to` is a single frame, not a window. A tail is about 1 % of a full re-read; when `resolution_ms`, `projection_id`, `compute_version`, the view or the lanes change, the window is read again in full.
+- Waits `Retry-After` (seconds or HTTP date) and paces itself when the key's budget reaches zero; a wait longer than `max_wait_s` raises `RateLimited` instead of hanging.
+- Raises typed errors (`AuthError`, `PlanError`, `Forbidden`, `NotFound`, `RateLimited`, `BadRequest`, `ServerError`, `TransportError`), each carrying the server's `reason`, `detail` and `request_id`.
+- Live sockets use zstd framing, take `every_ms` as the server's rung, answer a `gap` by waiting for the next snapshot, and redial on the generated backoff; a `Reconnected` event says to read REST once for the span it was down.
+
+Instant reads and sockets ride compact protobuf by default, at compact layout 2 (`compact=plugin&compact_layout=2&layout_id=<id>`; on sockets the `compact.layout.2` feature), the layout that carries every member, the freshness pairs (`book_stale`, `basis_stale`, ...) included. A decoded body equals its JSON twin; a member the JSON omits because it does not apply reads `None`. Windows (`Window`) follow the same default. `Vexity(compact=False)`, or `compact=False` on one call, reads JSON instead.
+
+What the pin does and does not promise: layout 2 is the newest layout this release of `vexity` was generated from (the pin moves with the release, not with the server). The server checks the layout id this release sends and answers 409 when a required member changed, and the SDK checks the layout the server served (the ETag's `-cpb2`) and the layout a socket negotiated; each failure raises `LayoutMismatch` and tells you to upgrade `vexity` or pass `compact=False`. Layout 2 can still grow in place with optional members: a member this release does not know is skipped with an `UnknownMembersWarning` naming it, so upgrade when you see one, or read JSON. The warning is raised once per member and process. A server release that adds a member keeps the previous layout id accepted (the `register` job refuses a release that drops it), so an older SDK keeps working and only warns.
+
+The live socket takes the key in its URL, as the API requires, so keep the `websockets` logger above DEBUG. The key is read from `VEXITY_API_KEY` or `api_key=`; it is masked in `repr` and never logged.
+
+## User-Agent
+
+Requests and the socket send `vexity-py/<version>`. Pass `Vexity(app="myapp/1.2")` to append your own name (`vexity-py/0.1.0 myapp/1.2`) so Vexity can reach heavy users.
+
+## Licence and use of the data
+
+The code of this package is MIT licensed. Use of the Vexity API and of the data it returns is governed by the [Vexity Terms and Conditions](https://vexity.net/terms) and the [Redistribution Policy](https://vexity.net/redistribution), not by the MIT licence. In particular the data may be cached transiently, not accumulated into datasets of your own. `EtagStore(directory=...)` is an opt-in revalidation cache: it keeps closed answers only until their `max-age` lapses so a re-run does not fetch them again, and it is not an archive. Entries are deleted when their `max-age` lapses, so a read after that downloads the body again instead of revalidating. Questions: vexity@jzn-management.com.

vexity-0.1.0/README.md

@@ -0,0 +1,40 @@
+# vexity
+
+Official Python client for the [Vexity](https://vexity.net) options-analytics API.
+
+```python
+import vexity
+
+client = vexity.Vexity()                      # reads VEXITY_API_KEY
+levels = client.levels("SPX", scope="full")   # the JSON body, as a dict
+
+window = client.window("series", "SPX", names="spot,net_gex_oi", scope="latest", step="1m", span="2h")
+update = window.poll()                        # the first call reads the window; later calls read only the tail and merge it
+
+with client.live() as live:                   # zstd socket, redials by the server's own client policy
+    live.subscribe("levels", "SPX", scope="full", every_ms=5000)
+    for event in live:
+        print(event)
+```
+
+What it does for you, with no flags:
+
+- Sends `If-None-Match` and stores answers. A 304 saves the body, not the request, and happens only on reads that move slowly (contracts, surface, series envelopes, a window between chain cycles): live levels, frame and grid bodies change every second, so poll them rarely or use the socket. A closed window (`immutable`) is served from the store with no request, and `Vexity(store=EtagStore(directory=...))` keeps it across runs.
+- `Window` reads a live window once in full (following `next_cursor`), then asks `from=<the step boundary at or before the newest held timestamp>` (the newest timestamp itself on an aligned series, so the first returned bucket is a whole one) and merges by the documented rule: drop the held points at or after the answer's first timestamp, append the answer. A step of a session day is read in full each poll. A frame read with neither `from` nor `to` is a single frame, not a window. A tail is about 1 % of a full re-read; when `resolution_ms`, `projection_id`, `compute_version`, the view or the lanes change, the window is read again in full.
+- Waits `Retry-After` (seconds or HTTP date) and paces itself when the key's budget reaches zero; a wait longer than `max_wait_s` raises `RateLimited` instead of hanging.
+- Raises typed errors (`AuthError`, `PlanError`, `Forbidden`, `NotFound`, `RateLimited`, `BadRequest`, `ServerError`, `TransportError`), each carrying the server's `reason`, `detail` and `request_id`.
+- Live sockets use zstd framing, take `every_ms` as the server's rung, answer a `gap` by waiting for the next snapshot, and redial on the generated backoff; a `Reconnected` event says to read REST once for the span it was down.
+
+Instant reads and sockets ride compact protobuf by default, at compact layout 2 (`compact=plugin&compact_layout=2&layout_id=<id>`; on sockets the `compact.layout.2` feature), the layout that carries every member, the freshness pairs (`book_stale`, `basis_stale`, ...) included. A decoded body equals its JSON twin; a member the JSON omits because it does not apply reads `None`. Windows (`Window`) follow the same default. `Vexity(compact=False)`, or `compact=False` on one call, reads JSON instead.
+
+What the pin does and does not promise: layout 2 is the newest layout this release of `vexity` was generated from (the pin moves with the release, not with the server). The server checks the layout id this release sends and answers 409 when a required member changed, and the SDK checks the layout the server served (the ETag's `-cpb2`) and the layout a socket negotiated; each failure raises `LayoutMismatch` and tells you to upgrade `vexity` or pass `compact=False`. Layout 2 can still grow in place with optional members: a member this release does not know is skipped with an `UnknownMembersWarning` naming it, so upgrade when you see one, or read JSON. The warning is raised once per member and process. A server release that adds a member keeps the previous layout id accepted (the `register` job refuses a release that drops it), so an older SDK keeps working and only warns.
+
+The live socket takes the key in its URL, as the API requires, so keep the `websockets` logger above DEBUG. The key is read from `VEXITY_API_KEY` or `api_key=`; it is masked in `repr` and never logged.
+
+## User-Agent
+
+Requests and the socket send `vexity-py/<version>`. Pass `Vexity(app="myapp/1.2")` to append your own name (`vexity-py/0.1.0 myapp/1.2`) so Vexity can reach heavy users.
+
+## Licence and use of the data
+
+The code of this package is MIT licensed. Use of the Vexity API and of the data it returns is governed by the [Vexity Terms and Conditions](https://vexity.net/terms) and the [Redistribution Policy](https://vexity.net/redistribution), not by the MIT licence. In particular the data may be cached transiently, not accumulated into datasets of your own. `EtagStore(directory=...)` is an opt-in revalidation cache: it keeps closed answers only until their `max-age` lapses so a re-run does not fetch them again, and it is not an archive. Entries are deleted when their `max-age` lapses, so a read after that downloads the body again instead of revalidating. Questions: vexity@jzn-management.com.

vexity-0.1.0/pyproject.toml

@@ -0,0 +1,49 @@
+[project]
+name = "vexity"
+version = "0.1.0"
+description = "Official Python client for the Vexity options-analytics API: ETag-aware reads, incremental windows and the live socket."
+readme = "README.md"
+requires-python = ">=3.11"
+license = { file = "LICENSE" }
+authors = [{ name = "Vexity", email = "vexity@jzn-management.com" }]
+keywords = ["vexity", "options", "gamma-exposure", "api-client"]
+dependencies = [
+    "httpx>=0.27",
+    "msgpack>=1.0",
+    "websockets>=13",
+    "zstandard>=0.23; python_version < '3.14'",
+]
+
+[build-system]
+requires = ["hatchling"]
+build-backend = "hatchling.build"
+
+[tool.hatch.build.targets.sdist]
+include = ["src/vexity", "README.md", "LICENSE", "pyproject.toml"]
+
+[tool.hatch.build.targets.wheel]
+packages = ["src/vexity"]
+
+[dependency-groups]
+dev = ["pytest>=8"]
+
+[tool.pytest.ini_options]
+testpaths = ["tests"]
+pythonpath = ["src"]
+addopts = "-q"
+
+[tool.ruff]
+target-version = "py311"
+line-length = 270
+
+[tool.ruff.lint]
+select = ["E", "F", "W", "I", "B", "UP", "SIM", "RUF", "N"]
+ignore = ["E501", "N818"]
+
+[tool.ruff.lint.isort]
+known-first-party = ["vexity"]
+combine-as-imports = true
+
+[tool.ruff.format]
+quote-style = "double"
+line-ending = "lf"

vexity-0.1.0/src/vexity/__init__.py

@@ -0,0 +1,41 @@
+"""Official Python client for the Vexity options-analytics API."""
+
+__version__ = "0.1.0"
+
+from vexity.client import Response, Vexity
+from vexity.errors import (
+    AuthError,
+    BadRequest,
+    DecodeError,
+    Forbidden,
+    LayoutMismatch,
+    NotFound,
+    PlanError,
+    RateLimited,
+    ServerError,
+    SocketClosed,
+    TransportError,
+    VexityError,
+)
+from vexity.etag_store import EtagStore
+from vexity.windows import Update, Window
+
+__all__ = [
+    "AuthError",
+    "BadRequest",
+    "DecodeError",
+    "EtagStore",
+    "Forbidden",
+    "LayoutMismatch",
+    "NotFound",
+    "PlanError",
+    "RateLimited",
+    "Response",
+    "ServerError",
+    "SocketClosed",
+    "TransportError",
+    "Update",
+    "Vexity",
+    "VexityError",
+    "Window",
+]

vexity-0.1.0/src/vexity/client.py

@@ -0,0 +1,259 @@
+"""The request pipeline: auth, `If-None-Match`, immutable reads from the store, compact bodies at the pinned layout, pacing, retries and typed errors."""
+
+from __future__ import annotations
+
+import hashlib
+import json
+import os
+import random
+import re
+import time
+from collections.abc import Mapping
+from dataclasses import dataclass
+from types import TracebackType
+from typing import Any, Literal
+from urllib.parse import quote
+
+import httpx
+
+import vexity
+from vexity.client_contract_gen import COMPACT_LAYOUT_PARAM, COMPACT_MEDIA_TYPE, COMPACT_PARAM, COMPACT_PLUGIN, RateBudget, compact_body_of
+from vexity.client_policy_gen import backoff_base_ms, backoff_cap_ms, backoff_ceiling_ms, classify_http
+from vexity.compact.decode import COMPACT_LAYOUT
+from vexity.compact.layout_gen import COMPACT_LAYOUT_ID, COMPACT_LAYOUTS
+from vexity.errors import ACTION_ERRORS, DecodeError, LayoutMismatch, TransportError, VexityError
+from vexity.etag_store import EtagStore, Stored
+from vexity.pacing import Pacer
+from vexity.windows import Window
+
+DEFAULT_BASE_URL = "https://vexity.net"
+V2_PREFIX = "/api/v2/"
+COMPACT_LAYOUT_ID_PARAM = "layout_id"
+_LAYOUT_ETAG = re.compile(rf'-cpb{COMPACT_LAYOUT}(-[a-z]+)?"$')
+_APP = re.compile(r"[\x21-\x7e][\x20-\x7e]{0,62}[\x21-\x7e]|[\x21-\x7e]")
+_MAX_AGE = re.compile(r"max-age=([0-9]+)")
+_QUERY_SAFE = ",:-._~"
+
+
+@dataclass(frozen=True, slots=True)
+class Response:
+    """One answer. `source` is `network` (200), `revalidated` (304, stored body) or `store` (immutable, no request made). `layout` is the compact layout the body was read at, None for JSON."""
+
+    body: Any
+    status: int
+    source: Literal["network", "revalidated", "store"]
+    etag: str
+    budget: RateBudget | None
+    request_id: str
+    layout: int | None
+
+
+def user_agent(app: str | None) -> str:
+    """`vexity-py/<version>`, then the caller's own `app` name (`myapp/1.2`) so heavy users can be reached."""
+    if app is not None and not _APP.fullmatch(app):
+        raise ValueError("app is 1 to 64 printable ASCII characters, e.g. 'myapp/1.2'")
+    return f"vexity-py/{vexity.__version__}" + (f" {app}" if app else "")
+
+
+def wire_params(params: Mapping[str, Any] | None) -> dict[str, str]:
+    """The query values as the server reads them: a list joins with commas, True is `true`, None drops, `from_` is `from`."""
+    out: dict[str, str] = {}
+    for key, value in (params or {}).items():
+        if value is None:
+            continue
+        if isinstance(value, bool):
+            value = "true" if value else "false"
+        elif isinstance(value, (list, tuple)):
+            value = ",".join(str(v) for v in value)
+        out[key.rstrip("_")] = str(value)
+    return out
+
+
+def canonical_query(params: Mapping[str, Any] | None) -> str:
+    """Sorted, percent-escaped `k=v` pairs of `wire_params`."""
+    return "&".join(f"{k}={quote(v, safe=_QUERY_SAFE)}" for k, v in sorted(wire_params(params).items()))
+
+
+def _fresh_until(headers: httpx.Headers) -> float:
+    cache = headers.get("cache-control", "")
+    found = _MAX_AGE.search(cache)
+    return time.time() + int(found[1]) if found and "immutable" in cache and "no-store" not in cache else 0.0
+
+
+class Vexity:
+    """Synchronous client. Instant reads ride compact protobuf at the pinned layout (every member, freshness pairs included); `compact=False` reads JSON instead."""
+
+    def __init__(
+        self,
+        api_key: str | None = None,
+        *,
+        base_url: str = DEFAULT_BASE_URL,
+        compact: bool = True,
+        app: str | None = None,
+        store: EtagStore | None = None,
+        max_retries: int = 3,
+        max_wait_s: float = 120.0,
+        timeout_s: float = 30.0,
+        transport: httpx.BaseTransport | None = None,
+    ):
+        key = api_key or os.environ.get("VEXITY_API_KEY", "")
+        if not key:
+            raise ValueError("no API key: pass api_key= or set VEXITY_API_KEY")
+        self._key = key
+        self.base_url = base_url.rstrip("/")
+        self._key_tag = hashlib.sha256(f"{self.base_url}\n{key}".encode()).hexdigest()[:16]
+        self.compact = compact
+        self.store = store if store is not None else EtagStore()
+        self._max_retries = max_retries
+        self.pacer = Pacer(max_wait_s=max_wait_s)
+        self.user_agent = user_agent(app)
+        self._http = httpx.Client(base_url=self.base_url, timeout=timeout_s, transport=transport, headers={"Authorization": f"Bearer {key}", "User-Agent": self.user_agent})
+
+    @property
+    def api_key(self) -> str:
+        """The credential, for the live socket URL only; never logged and masked in `repr`."""
+        return self._key
+
+    def __repr__(self) -> str:
+        return f"Vexity(base_url={self.base_url!r}, api_key=***)"
+
+    def __enter__(self) -> Vexity:
+        return self
+
+    def __exit__(self, exc_type: type[BaseException] | None, exc: BaseException | None, tb: TracebackType | None) -> None:
+        self.close()
+
+    def close(self) -> None:
+        self._http.close()
+
+    def get(self, path: str, params: Mapping[str, Any] | None = None, *, compact: bool | None = None) -> Response:
+        """GET `path` (a v2 path such as `/api/v2/levels/SPX`) with the efficient defaults."""
+        query = canonical_query(params)
+        resource = path[len(V2_PREFIX) :].split("/", 1)[0] if path.startswith(V2_PREFIX) else ""
+        asked = wire_params(params)
+        body_name = compact_body_of(resource, lambda key: asked.get(key, "")) if (self.compact if compact is None else compact) else None
+        if body_name not in COMPACT_LAYOUTS:
+            body_name = None
+        if body_name is not None:
+            query = canonical_query({**(params or {}), COMPACT_PARAM: COMPACT_PLUGIN, COMPACT_LAYOUT_PARAM: COMPACT_LAYOUT, COMPACT_LAYOUT_ID_PARAM: COMPACT_LAYOUT_ID})
+        url = f"{path}?{query}" if query else path
+        key = f"{self._key_tag}|{url}|{'compact' if body_name else 'json'}"
+        stored = self.store.get(key)
+        if stored is not None and stored.fresh_until > time.time():
+            return self._response(stored, 200, "store", "", body_name)
+        headers = {"Accept": COMPACT_MEDIA_TYPE if body_name else "application/json"}
+        if stored is not None:
+            headers["If-None-Match"] = stored.etag
+        resp = self._send("GET", url, headers)
+        request_id = resp.headers.get("x-request-id", "")
+        if resp.status_code == 304 and stored is not None:
+            return self._response(stored, 304, "revalidated", request_id, body_name)
+        if resp.status_code != 200:
+            raise DecodeError(f"{path} answered {resp.status_code}, which is not an answer to this read", status=resp.status_code, request_id=request_id)
+        if body_name is not None and not _LAYOUT_ETAG.search(resp.headers.get("etag", "")):
+            raise LayoutMismatch(f"asked compact layout {COMPACT_LAYOUT} and the server answered another ({resp.headers.get('etag', '')!r}): upgrade vexity or pass compact=False", status=200, request_id=request_id)
+        fresh = Stored(resp.headers.get("etag", ""), resp.content, resp.headers.get("content-type", ""), _fresh_until(resp.headers), COMPACT_LAYOUT if body_name else None)
+        if fresh.etag and "no-store" not in resp.headers.get("cache-control", ""):
+            self.store.put(key, fresh)
+        return self._response(fresh, resp.status_code, "network", request_id, body_name)
+
+    def post(self, path: str, body: Mapping[str, Any]) -> Any:
+        resp = self._send("POST", path, {"Accept": "application/json"}, json_body=body)
+        try:
+            return resp.json()
+        except ValueError as e:
+            raise DecodeError(f"{path} answered a body that is not JSON", status=resp.status_code) from e
+
+    def read(self, resource: str, ticker: str, /, *, compact: bool | None = None, **params: Any) -> Any:
+        """The body of `/api/v2/{resource}/{ticker}`."""
+        return self.get(f"{V2_PREFIX}{resource}/{ticker}", params, compact=compact).body
+
+    def levels(self, ticker: str, **params: Any) -> Any:
+        return self.read("levels", ticker, **params)
+
+    def frame(self, ticker: str, **params: Any) -> Any:
+        return self.read("frame", ticker, **params)
+
+    def profile(self, ticker: str, **params: Any) -> Any:
+        return self.read("profile", ticker, **params)
+
+    def series(self, ticker: str, **params: Any) -> Any:
+        return self.read("series", ticker, **params)
+
+    def contracts(self, ticker: str, **params: Any) -> Any:
+        return self.read("contracts", ticker, **params)
+
+    def surface(self, ticker: str, **params: Any) -> Any:
+        return self.read("surface", ticker, **params)
+
+    def me(self) -> Any:
+        return self.get(f"{V2_PREFIX}me").body
+
+    def catalogue(self, **params: Any) -> Any:
+        return self.get(f"{V2_PREFIX}catalogue", params).body
+
+    def window(self, resource: str, ticker: str, /, *, span: str | None = None, **params: Any) -> Window:
+        """A live window read once in full, then by tails: see `Window`."""
+        return Window(self, resource, ticker, span=span, params=params)
+
+    def live(self, **options: Any):
+        """A live socket session: see `vexity.live.Live`."""
+        from vexity.live.session import Live
+
+        return Live(self, **options)
+
+    def _response(self, stored: Stored, status: int, source: Literal["network", "revalidated", "store"], request_id: str, body_name: str | None) -> Response:
+        if body_name is None:
+            try:
+                body = json.loads(stored.body)
+            except ValueError as e:
+                raise DecodeError("the answer is not JSON", status=status, request_id=request_id) from e
+        else:
+            from vexity.compact.decode import CompactError, decode_compact
+
+            try:
+                body = decode_compact(body_name, stored.body)
+            except CompactError as e:
+                raise DecodeError(f"the compact answer does not read as {body_name}: {e}", status=status, request_id=request_id) from e
+        return Response(body, status, source, stored.etag, self.pacer.budget, request_id, stored.layout)
+
+    def _send(self, method: str, url: str, headers: dict[str, str], *, json_body: Mapping[str, Any] | None = None) -> httpx.Response:
+        failures = 0
+        while True:
+            self.pacer.wait()
+            resp: httpx.Response | None = None
+            try:
+                resp = self._http.request(method, url, headers=headers, json=json_body)
+            except httpx.TransportError as e:
+                status, reason, detail, request_id, retry_ms = 0, "", str(e) or type(e).__name__, "", 0
+            else:
+                self.pacer.observe({k.lower(): v for k, v in resp.headers.items()})
+                if resp.status_code < 400:
+                    return resp
+                status = resp.status_code
+                reason, detail, request_id = _error_fields(resp)
+                if status == 409 and detail.startswith("layout_mismatch"):
+                    raise LayoutMismatch(f"the server writes another compact layout than this vexity release reads: upgrade vexity or pass compact=False ({detail})", status=409, reason=reason, detail=detail, request_id=request_id)
+                retry_ms = self.pacer.retry_after({k.lower(): v for k, v in resp.headers.items()})
+            decision = classify_http(status, reason, retry_ms, "mint")
+            error_class = ACTION_ERRORS[decision.action] if status else TransportError
+            if decision.action in ("rate", "backoff") and failures < self._max_retries and not self.pacer.too_long(decision.wait_ms):
+                failures += 1
+                delay = decision.wait_ms if decision.action == "rate" else max(decision.wait_ms, int(random.uniform(0, backoff_ceiling_ms(failures, backoff_base_ms(), backoff_cap_ms()))))
+                self.pacer.block(delay)
+                continue
+            raise error_class(f"{method} {url.split('?', 1)[0]} answered {status or 'no status'} {reason}".strip(), status=status, reason=reason, detail=detail, request_id=request_id, retry_after_ms=retry_ms)
+
+
+def _error_fields(resp: httpx.Response) -> tuple[str, str, str]:
+    request_id = resp.headers.get("x-request-id", "")
+    try:
+        body = resp.json()
+    except ValueError:
+        return "", resp.text[:200], request_id
+    if not isinstance(body, dict):
+        return "", "", request_id
+    return str(body.get("reason", "")), str(body.get("detail", "")), str(body.get("request_id", request_id))
+
+
+__all__ = ["Response", "Vexity", "VexityError", "canonical_query"]