quirepdf 0.1.0__tar.gz

quirepdf-0.1.0/.gitignore

@@ -0,0 +1,14 @@
+engine/target/
+node_modules/
+site/dist/
+site/.astro/
+sdk-js/dist/
+mcp/dist/
+__pycache__/
+*.egg-info/
+out/
+.DS_Store
+*.log
+# Local secrets (billing keys etc.); never commit.
+.env.local
+*.env.local

quirepdf-0.1.0/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 Quire PDF
+
+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.

quirepdf-0.1.0/PKG-INFO

@@ -0,0 +1,134 @@
+Metadata-Version: 2.5
+Name: quirepdf
+Version: 0.1.0
+Summary: Python SDK for the Quire API: send JSON, get back a polished PDF.
+Project-URL: Homepage, https://quirepdf.dev
+Project-URL: Documentation, https://quirepdf.dev/docs/sdk-python
+Project-URL: Pricing, https://quirepdf.dev/pricing
+Author-email: Quire PDF <support@quirepdf.dev>
+License-Expression: MIT
+License-File: LICENSE
+Keywords: invoice,json-to-pdf,pdf,pdf-generation,quire,receipt,typst
+Classifier: Intended Audience :: Developers
+Classifier: Operating System :: OS Independent
+Classifier: Programming Language :: Python :: 3
+Classifier: Programming Language :: Python :: 3 :: Only
+Classifier: Topic :: Office/Business
+Classifier: Topic :: Printing
+Classifier: Typing :: Typed
+Requires-Python: >=3.9
+Description-Content-Type: text/markdown
+
+# quirepdf (Python)
+
+Send JSON, get back a polished PDF. Python 3.9+, standard library only, synchronous.
+
+## Install
+
+```sh
+pip install quirepdf
+```
+
+## Quickstart
+
+Any JSON object renders. Quire picks the best-matching template, or a clean generic layout:
+
+```python
+from quirepdf import Quire
+
+client = Quire()  # reads QUIRE_API_KEY (and QUIRE_API_URL)
+
+order = {
+    "order_id": "ORD-88213",
+    "customer": {"name": "Lena Fischer", "email": "lena@example.de"},
+    "lines": [{"sku": "TS-BLK-M", "name": "Organic tee", "qty": 2, "price": 29.0}],
+    "currency": "€",
+}
+result = client.render(order)
+result.save("order.pdf")
+print(result.template, result.template_source, result.pages)  # document fallback 1
+if result.hint:
+    print("almost matched:", result.hint)  # e.g. "invoice (seller is required)"
+```
+
+Name a template and use the generated types so your editor checks the fields:
+
+```python
+from quirepdf.types import InvoiceData
+
+invoice: InvoiceData = {
+    "number": "INV-2026-0142",
+    "issued": "1 Oct 2026",
+    "due": "15 Oct 2026",
+    "seller": {"name": "Northwind Studio", "address": ["221 Market Street", "San Francisco, CA 94105"]},
+    "customer": {"name": "Ravi Kumar", "address": ["14 Residency Road", "Bengaluru 560025"]},
+    "items": [{"description": "Pro plan", "qty": 1, "unit_price": 49}],
+    "status": "due",  # Literal["draft", "due", "paid", "overdue", "void"]
+}
+
+pdf = client.render(invoice, template="invoice")
+png = client.render(invoice, template="invoice", format="png", page=1)  # preview one page
+print(pdf.content[:5], len(png.content), pdf.render_ms, pdf.quota)    # Quota(limit=100, remaining=97)
+```
+
+`RenderResult` fields: `content` (the file as `bytes`), `content_type`, `pages`, `template`,
+`template_source` (`explicit` | `detected` | `fallback`), `hint`, `render_ms`, `quota`, and `save(path)`.
+
+Other calls:
+
+```python
+check = client.validate(invoice, template="invoice")   # free, nothing rendered
+check.valid, check.errors                               # False, [{"path": "...", "message": "..."}]
+
+client.templates.list()            # [{"name": "invoice", "title": "Invoice", ...}, ...]
+client.templates.get("invoice")    # {"template": {...}, "schema": {...}, "sample": {...}}
+client.usage()                     # {"plan": "free", "used": 3, "limit": 100, "remaining": 97, ...}
+
+new = client.keys.create(name="ci")   # new["api_key"] is shown only once
+client.keys.list()                    # [{"id", "prefix", "name", "current": bool, ...}]
+client.keys.revoke(new["key"]["id"])
+```
+
+## Errors
+
+Every failure raises `QuireError` with `status`, `type`, `message` and `fields`:
+
+```python
+from quirepdf import QuireError
+
+try:
+    client.render({"number": "INV-1"}, template="invoice")
+except QuireError as err:
+    print(err.status, err.type)  # 422 invalid_data
+    print(err)                   # data has 5 problems
+                                 #   - issued is required
+                                 #   - due is required ...
+    for f in err.fields:
+        print(f["path"], f["message"])
+```
+
+Common types: `invalid_data`, `unknown_template`, `unauthorized`, `quota_exceeded`, `bad_request`,
+`payload_too_large`, `timeout`. Client-side failures have `status == 0`: `type == "network"`
+(can't connect) or `type == "timeout"` (no reply within `timeout` seconds). The SDK never retries.
+
+## Configuration
+
+| Argument   | Environment     | Default                 |
+|------------|-----------------|-------------------------|
+| `api_key`  | `QUIRE_API_KEY` | none (no `Authorization` header is sent) |
+| `base_url` | `QUIRE_API_URL` | `https://api.quirepdf.dev` |
+| `timeout`  |                 | `30.0` seconds          |
+
+```python
+client = Quire(api_key="qk_...", base_url="http://127.0.0.1:8787", timeout=10)
+```
+
+A local engine in open mode (`make serve`) needs no key.
+
+## Development
+
+```sh
+python3 scripts/gen_types.py          # regenerate src/quirepdf/types.py after a schema change
+python3 scripts/gen_types.py --check  # fail if it is stale
+PYTHONPATH=src python3 -m unittest discover -s tests -v   # runs against engine/target/release/quire-engine (make build)
+```

quirepdf-0.1.0/README.md

@@ -0,0 +1,113 @@
+# quirepdf (Python)
+
+Send JSON, get back a polished PDF. Python 3.9+, standard library only, synchronous.
+
+## Install
+
+```sh
+pip install quirepdf
+```
+
+## Quickstart
+
+Any JSON object renders. Quire picks the best-matching template, or a clean generic layout:
+
+```python
+from quirepdf import Quire
+
+client = Quire()  # reads QUIRE_API_KEY (and QUIRE_API_URL)
+
+order = {
+    "order_id": "ORD-88213",
+    "customer": {"name": "Lena Fischer", "email": "lena@example.de"},
+    "lines": [{"sku": "TS-BLK-M", "name": "Organic tee", "qty": 2, "price": 29.0}],
+    "currency": "€",
+}
+result = client.render(order)
+result.save("order.pdf")
+print(result.template, result.template_source, result.pages)  # document fallback 1
+if result.hint:
+    print("almost matched:", result.hint)  # e.g. "invoice (seller is required)"
+```
+
+Name a template and use the generated types so your editor checks the fields:
+
+```python
+from quirepdf.types import InvoiceData
+
+invoice: InvoiceData = {
+    "number": "INV-2026-0142",
+    "issued": "1 Oct 2026",
+    "due": "15 Oct 2026",
+    "seller": {"name": "Northwind Studio", "address": ["221 Market Street", "San Francisco, CA 94105"]},
+    "customer": {"name": "Ravi Kumar", "address": ["14 Residency Road", "Bengaluru 560025"]},
+    "items": [{"description": "Pro plan", "qty": 1, "unit_price": 49}],
+    "status": "due",  # Literal["draft", "due", "paid", "overdue", "void"]
+}
+
+pdf = client.render(invoice, template="invoice")
+png = client.render(invoice, template="invoice", format="png", page=1)  # preview one page
+print(pdf.content[:5], len(png.content), pdf.render_ms, pdf.quota)    # Quota(limit=100, remaining=97)
+```
+
+`RenderResult` fields: `content` (the file as `bytes`), `content_type`, `pages`, `template`,
+`template_source` (`explicit` | `detected` | `fallback`), `hint`, `render_ms`, `quota`, and `save(path)`.
+
+Other calls:
+
+```python
+check = client.validate(invoice, template="invoice")   # free, nothing rendered
+check.valid, check.errors                               # False, [{"path": "...", "message": "..."}]
+
+client.templates.list()            # [{"name": "invoice", "title": "Invoice", ...}, ...]
+client.templates.get("invoice")    # {"template": {...}, "schema": {...}, "sample": {...}}
+client.usage()                     # {"plan": "free", "used": 3, "limit": 100, "remaining": 97, ...}
+
+new = client.keys.create(name="ci")   # new["api_key"] is shown only once
+client.keys.list()                    # [{"id", "prefix", "name", "current": bool, ...}]
+client.keys.revoke(new["key"]["id"])
+```
+
+## Errors
+
+Every failure raises `QuireError` with `status`, `type`, `message` and `fields`:
+
+```python
+from quirepdf import QuireError
+
+try:
+    client.render({"number": "INV-1"}, template="invoice")
+except QuireError as err:
+    print(err.status, err.type)  # 422 invalid_data
+    print(err)                   # data has 5 problems
+                                 #   - issued is required
+                                 #   - due is required ...
+    for f in err.fields:
+        print(f["path"], f["message"])
+```
+
+Common types: `invalid_data`, `unknown_template`, `unauthorized`, `quota_exceeded`, `bad_request`,
+`payload_too_large`, `timeout`. Client-side failures have `status == 0`: `type == "network"`
+(can't connect) or `type == "timeout"` (no reply within `timeout` seconds). The SDK never retries.
+
+## Configuration
+
+| Argument   | Environment     | Default                 |
+|------------|-----------------|-------------------------|
+| `api_key`  | `QUIRE_API_KEY` | none (no `Authorization` header is sent) |
+| `base_url` | `QUIRE_API_URL` | `https://api.quirepdf.dev` |
+| `timeout`  |                 | `30.0` seconds          |
+
+```python
+client = Quire(api_key="qk_...", base_url="http://127.0.0.1:8787", timeout=10)
+```
+
+A local engine in open mode (`make serve`) needs no key.
+
+## Development
+
+```sh
+python3 scripts/gen_types.py          # regenerate src/quirepdf/types.py after a schema change
+python3 scripts/gen_types.py --check  # fail if it is stale
+PYTHONPATH=src python3 -m unittest discover -s tests -v   # runs against engine/target/release/quire-engine (make build)
+```

quirepdf-0.1.0/pyproject.toml

@@ -0,0 +1,35 @@
+[build-system]
+requires = ["hatchling>=1.18"]
+build-backend = "hatchling.build"
+
+[project]
+name = "quirepdf"
+version = "0.1.0"
+description = "Python SDK for the Quire API: send JSON, get back a polished PDF."
+readme = "README.md"
+requires-python = ">=3.9"
+license = "MIT"
+license-files = ["LICENSE"]
+authors = [{ name = "Quire PDF", email = "support@quirepdf.dev" }]
+keywords = ["pdf", "pdf-generation", "invoice", "receipt", "json-to-pdf", "typst", "quire"]
+dependencies = []
+classifiers = [
+  "Programming Language :: Python :: 3",
+  "Programming Language :: Python :: 3 :: Only",
+  "Operating System :: OS Independent",
+  "Intended Audience :: Developers",
+  "Topic :: Office/Business",
+  "Topic :: Printing",
+  "Typing :: Typed",
+]
+
+[project.urls]
+Homepage = "https://quirepdf.dev"
+Documentation = "https://quirepdf.dev/docs/sdk-python"
+Pricing = "https://quirepdf.dev/pricing"
+
+[tool.hatch.build.targets.wheel]
+packages = ["src/quirepdf"]
+
+[tool.hatch.build.targets.sdist]
+include = ["src/quirepdf", "README.md", "LICENSE"]

quirepdf-0.1.0/src/quirepdf/__init__.py

@@ -0,0 +1,38 @@
+"""Quire: send JSON, get back a polished PDF.
+
+    from quirepdf import Quire
+
+    client = Quire()  # reads QUIRE_API_KEY and QUIRE_API_URL
+    client.render(data).save("invoice.pdf")
+
+Typed template data lives in ``quirepdf.types`` (``InvoiceData``, ``ReceiptData``, ...).
+"""
+
+from .client import (
+    CreatedKey,
+    KeyInfo,
+    Quire,
+    Quota,
+    RenderResult,
+    TemplateDetail,
+    TemplateMeta,
+    Usage,
+    ValidationResult,
+    __version__,
+)
+from .errors import FieldError, QuireError
+
+__all__ = [
+    "Quire",
+    "QuireError",
+    "RenderResult",
+    "ValidationResult",
+    "Quota",
+    "FieldError",
+    "TemplateMeta",
+    "TemplateDetail",
+    "Usage",
+    "KeyInfo",
+    "CreatedKey",
+    "__version__",
+]

quirepdf-0.1.0/src/quirepdf/client.py

@@ -0,0 +1,322 @@
+"""Synchronous Quire API client (standard library only)."""
+
+import decimal
+import http.client
+import json
+import os
+import pathlib
+import socket
+import urllib.error
+import urllib.parse
+import urllib.request
+from dataclasses import dataclass, field
+from email.message import Message
+from typing import Any, Dict, List, Mapping, Optional, TypedDict, Union
+
+from .errors import FieldError, QuireError
+
+__version__ = "0.1.0"
+
+DEFAULT_BASE_URL = "https://api.quirepdf.dev"
+USER_AGENT = f"quirepdf-python/{__version__}"
+
+PathLike = Union[str, "os.PathLike[str]"]
+
+
+# ---------- response shapes ----------
+
+
+class TemplateMeta(TypedDict):
+    """One entry of ``templates.list()``."""
+
+    name: str
+    title: str
+    description: str
+    category: str
+    tags: List[str]
+    version: str
+
+
+class TemplateDetail(TypedDict):
+    """``templates.get(name)``: metadata, the JSON Schema for the data, and valid sample data."""
+
+    template: TemplateMeta
+    schema: Dict[str, Any]
+    sample: Dict[str, Any]
+
+
+class Usage(TypedDict):
+    """``usage()``: renders used in the current calendar month."""
+
+    email: str
+    plan: str
+    period: str
+    used: int
+    limit: int
+    remaining: int
+
+
+class KeyInfo(TypedDict):
+    """An API key as listed by ``keys.list()`` (never includes the secret)."""
+
+    id: str
+    prefix: str
+    name: Optional[str]
+    created_at: int
+    last_used_at: Optional[int]
+    current: bool
+    """True for the key this client is authenticated with (added by the SDK)."""
+
+
+class CreatedKey(TypedDict):
+    """``keys.create()``: the new key's info plus its secret, which is shown only once."""
+
+    key: Dict[str, Any]
+    api_key: str
+
+
+@dataclass(frozen=True)
+class Quota:
+    """Monthly render quota after this render (accounts mode only)."""
+
+    limit: int
+    remaining: int
+
+
+@dataclass
+class RenderResult:
+    """A rendered document.
+
+    The file is in ``content`` rather than a field named ``bytes`` (the name the cross-language
+    spec uses): ``bytes`` would shadow the built-in type inside the class and read ambiguously at
+    call sites (``result.bytes`` next to ``bytes(...)``), and ``content`` matches the convention
+    Python HTTP libraries use for a binary response body.
+    """
+
+    content: bytes = field(repr=False)
+    content_type: str
+    pages: int
+    template: str
+    template_source: str
+    """``explicit`` (you named it), ``detected`` (the data matched its schema) or ``fallback``
+    (the generic ``document`` layout)."""
+    hint: Optional[str] = None
+    """On fallback: a template that almost matched and why, e.g. ``invoice (seller is required)``."""
+    render_ms: float = 0.0
+    quota: Optional[Quota] = None
+
+    def save(self, path: PathLike) -> pathlib.Path:
+        """Write the document to ``path`` and return it as a ``pathlib.Path``."""
+        p = pathlib.Path(path)
+        p.write_bytes(self.content)
+        return p
+
+
+@dataclass
+class ValidationResult:
+    """Outcome of ``validate()``: which template the data resolves to, and every problem with it."""
+
+    valid: bool
+    template: str
+    source: str
+    hint: Optional[str] = None
+    errors: List[FieldError] = field(default_factory=list)
+
+
+# ---------- transport ----------
+
+
+@dataclass
+class _Response:
+    status: int
+    headers: Message
+    body: bytes
+
+    def json(self) -> Any:
+        return json.loads(self.body.decode("utf-8")) if self.body else None
+
+
+class _NoRedirect(urllib.request.HTTPRedirectHandler):
+    """Never follow redirects: urllib would turn a POST into a GET and forward the API key to
+    whatever host the redirect names. A 3xx surfaces as a ``QuireError`` instead."""
+
+    def redirect_request(self, req, fp, code, msg, headers, newurl):  # type: ignore[no-untyped-def]
+        return None
+
+
+def _json_default(value: Any) -> Any:
+    if isinstance(value, decimal.Decimal):
+        return int(value) if value == value.to_integral_value() else float(value)
+    raise TypeError(f"Object of type {type(value).__name__} is not JSON serializable")
+
+
+# ---------- client ----------
+
+
+class Quire:
+    """Client for the Quire API.
+
+    >>> from quirepdf import Quire
+    >>> client = Quire()  # QUIRE_API_KEY / QUIRE_API_URL from the environment
+    >>> client.render({"title": "Hello", "items": [{"name": "Tea", "qty": 2}]}).save("hello.pdf")
+
+    Args:
+        api_key: API key. Defaults to ``QUIRE_API_KEY``. When neither is set no ``Authorization``
+            header is sent (fine for open-mode servers; others reply ``unauthorized``).
+        base_url: API root. Defaults to ``QUIRE_API_URL``, else ``https://api.quirepdf.dev``.
+        timeout: Seconds to wait for each request.
+    """
+
+    def __init__(self, api_key: Optional[str] = None, base_url: Optional[str] = None, timeout: float = 30.0) -> None:
+        self.api_key: Optional[str] = api_key or os.environ.get("QUIRE_API_KEY") or None
+        self.base_url: str = (base_url or os.environ.get("QUIRE_API_URL") or DEFAULT_BASE_URL).rstrip("/")
+        self.timeout = timeout
+        self.templates = Templates(self)
+        self.keys = Keys(self)
+        self._opener = urllib.request.build_opener(_NoRedirect)
+
+    def __repr__(self) -> str:
+        key = f"{self.api_key[:8]}..." if self.api_key else None
+        return f"Quire(base_url={self.base_url!r}, api_key={key!r}, timeout={self.timeout!r})"
+
+    # ----- documents -----
+
+    def render(
+        self,
+        data: Mapping[str, Any],
+        template: Optional[str] = None,
+        format: str = "pdf",
+        page: Optional[int] = None,
+    ) -> RenderResult:
+        """Render ``data`` to a PDF (or one page as PNG with ``format="png"``).
+
+        Without ``template`` the API picks the best-matching gallery template, or the generic
+        ``document`` layout (see ``RenderResult.template_source`` and ``hint``).
+        """
+        path = f"/v1/render/{_segment(template)}" if template else "/v1/render"
+        query: Dict[str, Any] = {"format": format if format != "pdf" else None, "page": page}
+        res = self._request("POST", path, query=query, body=data)
+        h = res.headers
+        limit, remaining = _int(h.get("x-quota-limit")), _int(h.get("x-quota-remaining"))
+        return RenderResult(
+            content=res.body,
+            content_type=(h.get("content-type") or "").split(";")[0].strip(),
+            pages=_int(h.get("x-pages")) or 0,
+            template=h.get("x-template") or (template or ""),
+            template_source=h.get("x-template-source") or ("explicit" if template else ""),
+            hint=h.get("x-template-hint") or None,
+            render_ms=_float(h.get("x-render-ms")) or 0.0,
+            quota=Quota(limit, remaining) if limit is not None and remaining is not None else None,
+        )
+
+    def validate(self, data: Mapping[str, Any], template: Optional[str] = None) -> ValidationResult:
+        """Check ``data`` without rendering (free, not metered). Invalid data is a result, not an error."""
+        body = self._request("POST", "/v1/validate", query={"template": template}, body=data).json()
+        return ValidationResult(
+            valid=bool(body.get("valid")),
+            template=body.get("template") or "",
+            source=body.get("source") or "",
+            hint=body.get("hint") or None,
+            errors=[{"path": str(e.get("path", "")), "message": str(e.get("message", ""))} for e in body.get("errors") or []],
+        )
+
+    def usage(self) -> Usage:
+        """Renders used this month on your plan (accounts mode only)."""
+        return self._request("GET", "/v1/usage").json()  # type: ignore[no-any-return]
+
+    # ----- transport -----
+
+    def _request(
+        self,
+        method: str,
+        path: str,
+        query: Optional[Mapping[str, Any]] = None,
+        body: Any = None,
+    ) -> _Response:
+        url = self.base_url + path
+        params = {k: str(v) for k, v in (query or {}).items() if v is not None}
+        if params:
+            url += "?" + urllib.parse.urlencode(params)
+        headers = {"User-Agent": USER_AGENT}
+        if self.api_key:
+            headers["Authorization"] = f"Bearer {self.api_key}"
+        data = None
+        if body is not None:
+            data = json.dumps(body, ensure_ascii=False, default=_json_default).encode("utf-8")
+            headers["Content-Type"] = "application/json"
+        req = urllib.request.Request(url, data=data, headers=headers, method=method)
+        try:
+            with self._opener.open(req, timeout=self.timeout) as resp:
+                return _Response(resp.status, resp.headers, resp.read())
+        except urllib.error.HTTPError as e:
+            try:
+                raw = e.read()
+            except (OSError, http.client.HTTPException):
+                raw = b""
+            finally:
+                e.close()
+            raise QuireError.from_response(e.code, raw) from None
+        except urllib.error.URLError as e:
+            if isinstance(e.reason, (socket.timeout, TimeoutError)):
+                raise self._timeout(method, path) from e
+            raise QuireError(0, "network", f"can't reach {self.base_url} ({e.reason})") from e
+        except (socket.timeout, TimeoutError) as e:  # timed out while reading the response
+            raise self._timeout(method, path) from e
+        except (OSError, http.client.HTTPException) as e:
+            raise QuireError(0, "network", f"connection to {self.base_url} failed ({e or type(e).__name__})") from e
+
+    def _timeout(self, method: str, path: str) -> QuireError:
+        return QuireError(0, "timeout", f"{method} {path} timed out after {self.timeout:g}s")
+
+
+class Templates:
+    """``client.templates``: the template catalog."""
+
+    def __init__(self, client: Quire) -> None:
+        self._client = client
+
+    def list(self) -> List[TemplateMeta]:
+        return self._client._request("GET", "/v1/templates").json()["templates"]  # type: ignore[no-any-return]
+
+    def get(self, name: str) -> TemplateDetail:
+        return self._client._request("GET", f"/v1/templates/{_segment(name)}").json()  # type: ignore[no-any-return]
+
+
+class Keys:
+    """``client.keys``: API keys of the authenticated account (accounts mode only)."""
+
+    def __init__(self, client: Quire) -> None:
+        self._client = client
+
+    def list(self) -> List[KeyInfo]:
+        """Active keys. ``current`` marks the key this client uses."""
+        body = self._client._request("GET", "/v1/keys").json()
+        current = body.get("current_key_id")
+        return [dict(k, current=k.get("id") == current) for k in body.get("keys") or []]  # type: ignore[misc]
+
+    def create(self, name: Optional[str] = None) -> CreatedKey:
+        """Create a key. The secret is in ``["api_key"]`` and is returned only this once."""
+        body = {"name": name} if name is not None else {}
+        return self._client._request("POST", "/v1/keys", body=body).json()  # type: ignore[no-any-return]
+
+    def revoke(self, key_id: str) -> None:
+        """Revoke a key by id. The API refuses to revoke your only active key (``last_key``)."""
+        self._client._request("DELETE", f"/v1/keys/{_segment(key_id)}")
+
+
+def _segment(value: str) -> str:
+    return urllib.parse.quote(value, safe="")
+
+
+def _int(value: Optional[str]) -> Optional[int]:
+    try:
+        return int(value) if value is not None else None
+    except ValueError:
+        return None
+
+
+def _float(value: Optional[str]) -> Optional[float]:
+    try:
+        return float(value) if value is not None else None
+    except ValueError:
+        return None