quirepdf 0.1.0__py3-none-any.whl

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/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

quirepdf/errors.py

@@ -0,0 +1,63 @@
+"""The one error type the SDK raises for API, network and timeout failures."""
+
+import json
+from typing import Any, Dict, List, Optional
+
+FieldError = Dict[str, str]
+"""One validation problem: ``{"path": "items[0].qty", "message": "items[0].qty must be a number"}``."""
+
+
+class QuireError(Exception):
+    """Raised for every failed request.
+
+    Attributes:
+        status: HTTP status code, or ``0`` when no response arrived (network failure or timeout).
+        type: The API error type (``invalid_data``, ``unknown_template``, ``unauthorized``,
+            ``quota_exceeded``, ...), or ``"network"`` / ``"timeout"`` for client-side failures,
+            or ``"http_error"`` when the server sent a non-JSON error body.
+        message: Human-readable message from the API, e.g. ``customer.name is required``.
+        fields: Every validation problem as ``{"path", "message"}`` dicts (``invalid_data`` only;
+            empty otherwise).
+    """
+
+    def __init__(self, status: int, type: str, message: str, fields: Optional[List[FieldError]] = None) -> None:
+        super().__init__(message)
+        self.status = status
+        self.type = type
+        self.message = message
+        self.fields: List[FieldError] = list(fields or [])
+
+    def __str__(self) -> str:
+        lines = [self.message]
+        for f in self.fields:
+            msg = f.get("message", "")
+            # A single-problem error repeats that problem as its message; don't print it twice.
+            if msg and msg != self.message:
+                lines.append(f"  - {msg}")
+        return "\n".join(lines)
+
+    def __repr__(self) -> str:
+        return f"QuireError(status={self.status!r}, type={self.type!r}, message={self.message!r}, fields={self.fields!r})"
+
+    @classmethod
+    def from_response(cls, status: int, body: bytes) -> "QuireError":
+        """Build an error from an HTTP error response (``{"error": {"type", "message", "fields"?}}``)."""
+        type_, message = "http_error", f"HTTP {status}"
+        fields: List[FieldError] = []
+        payload: Any = None
+        try:
+            payload = json.loads(body.decode("utf-8")) if body else None
+        except ValueError:  # includes JSONDecodeError and UnicodeDecodeError
+            pass
+        err = payload.get("error") if isinstance(payload, dict) else None
+        if isinstance(err, dict):
+            type_ = str(err.get("type") or type_)
+            message = str(err.get("message") or message)
+            raw_fields = err.get("fields")
+            if isinstance(raw_fields, list):
+                fields = [
+                    {"path": str(f.get("path", "")), "message": str(f.get("message", ""))}
+                    for f in raw_fields
+                    if isinstance(f, dict)
+                ]
+        return cls(status, type_, message, fields)

quirepdf/types.py

@@ -0,0 +1,698 @@
+"""Typed data for Quire's gallery templates.
+
+GENERATED by scripts/gen_types.py from templates/*/schema.json. Do not edit by hand;
+re-run ``python3 scripts/gen_types.py`` after changing a schema.
+
+Each template has a ``<Name>Data`` TypedDict (``InvoiceData``, ``ReceiptData``, ...).
+Python 3.9 has no ``NotRequired``, so an object with both required and optional keys is a
+private required base class (``total=True``) plus a public ``total=False`` subclass.
+"""
+
+from typing import Any, Dict, List, Literal, TypedDict
+
+__all__ = [
+    "CertificateData",
+    "CertificateIssuer",
+    "CertificateSignature",
+    "CreditNoteCustomer",
+    "CreditNoteData",
+    "CreditNoteItem",
+    "CreditNoteOriginalInvoice",
+    "CreditNoteSeller",
+    "CreditNoteTax",
+    "InvoiceCustomer",
+    "InvoiceData",
+    "InvoiceDiscount",
+    "InvoiceItem",
+    "InvoicePayment",
+    "InvoiceSeller",
+    "InvoiceTax",
+    "QuoteCustomer",
+    "QuoteData",
+    "QuoteDiscount",
+    "QuoteSection",
+    "QuoteSectionItem",
+    "QuoteSeller",
+    "QuoteTax",
+    "ReceiptCustomer",
+    "ReceiptData",
+    "ReceiptDiscount",
+    "ReceiptItem",
+    "ReceiptNote",
+    "ReceiptPayment",
+    "ReceiptSeller",
+    "ReceiptSupport",
+    "ReceiptTax",
+    "StatementAging",
+    "StatementCustomer",
+    "StatementData",
+    "StatementEntry",
+    "StatementPayment",
+    "StatementSeller",
+    "DocumentData",
+    "TemplateName",
+    "TEMPLATE_DATA_TYPES",
+]
+
+
+class _CertificateIssuerRequired(TypedDict):
+    """Required keys of :class:`CertificateIssuer`."""
+
+    # [1 to 60 chars]
+    name: str
+
+
+class CertificateIssuer(_CertificateIssuerRequired, total=False):
+    """The organisation awarding the certificate"""
+
+    # Muted line under the issuer name, e.g. a website [max 80 chars]
+    tagline: str
+
+
+class _CertificateSignatureRequired(TypedDict):
+    """Required keys of :class:`CertificateSignature`."""
+
+    # [1 to 50 chars]
+    name: str
+
+
+class CertificateSignature(_CertificateSignatureRequired, total=False):
+    """``signatures[]`` in :class:`CertificateData`."""
+
+    # [max 60 chars]
+    title: str
+
+
+class _CertificateDataRequired(TypedDict):
+    """Required keys of :class:`CertificateData`."""
+
+    # The organisation awarding the certificate
+    issuer: CertificateIssuer
+    # Recipient's full name. Long names are shrunk to fit, then wrapped. [1 to 100 chars]
+    recipient: str
+    # Course or achievement name [1 to 140 chars]
+    achievement: str
+    # Date of issue, pre-formatted for display [1 to 40 chars]
+    date: str
+    # One or two signature lines. With one, the date of issue takes the other slot. [1 to 2 items]
+    signatures: List[CertificateSignature]
+
+
+class CertificateData(_CertificateDataRequired, total=False):
+    """Data for the ``certificate`` template (Certificate)."""
+
+    # Brand colour for the frame, seal and title, e.g. #0f766e [pattern ^#[0-9a-fA-F]{6}$]
+    accent: str
+    # e.g. Certificate of achievement [default "Certificate of completion"; 1 to 60 chars]
+    title: str
+    # [default "This certifies that"; max 60 chars]
+    intro: str
+    # Text between the name and the achievement [default "has successfully completed"; max 80 chars]
+    statement: str
+    # Muted line under the achievement, e.g. hours, grade, format [max 220 chars]
+    details: str
+    # [max 40 chars]
+    credential_id: str
+    # Verification link, shown in small monospace text [max 100 chars]
+    verify_url: str
+
+
+class _CreditNoteOriginalInvoiceRequired(TypedDict):
+    """Required keys of :class:`CreditNoteOriginalInvoice`."""
+
+    # [1 to 40 chars]
+    number: str
+
+
+class CreditNoteOriginalInvoice(_CreditNoteOriginalInvoiceRequired, total=False):
+    """The invoice this credit is issued against"""
+
+    # Original invoice date, pre-formatted for display
+    date: str
+    # Original invoice total
+    amount: float
+
+
+class _CreditNoteSellerRequired(TypedDict):
+    """Required keys of :class:`CreditNoteSeller`."""
+
+    # [non-empty]
+    name: str
+
+
+class CreditNoteSeller(_CreditNoteSellerRequired, total=False):
+    """The business issuing the credit (shown as 'From')"""
+
+    # Shown under the brand name
+    email: str
+    address: List[str]
+    tax_id: str
+
+
+class _CreditNoteCustomerRequired(TypedDict):
+    """Required keys of :class:`CreditNoteCustomer`."""
+
+    # [non-empty]
+    name: str
+
+
+class CreditNoteCustomer(_CreditNoteCustomerRequired, total=False):
+    """The customer receiving the credit (shown as 'Billed to')"""
+
+    company: str
+    address: List[str]
+    email: str
+
+
+class _CreditNoteItemRequired(TypedDict):
+    """Required keys of :class:`CreditNoteItem`."""
+
+    description: str
+    # [>= 0]
+    qty: float
+    # [>= 0]
+    unit_price: float
+
+
+class CreditNoteItem(_CreditNoteItemRequired, total=False):
+    """``items[]`` in :class:`CreditNoteData`."""
+
+    detail: str
+
+
+class CreditNoteTax(TypedDict):
+    """Tax credited back, applied to the subtotal"""
+
+    label: str
+    # [0 to 1]
+    rate: float
+
+
+class _CreditNoteDataRequired(TypedDict):
+    """Required keys of :class:`CreditNoteData`."""
+
+    # Credit note number, e.g. CN-2026-0019 [1 to 40 chars]
+    number: str
+    # Issue date, pre-formatted for display [non-empty]
+    issued: str
+    # The invoice this credit is issued against
+    original_invoice: CreditNoteOriginalInvoice
+    # The business issuing the credit (shown as 'From')
+    seller: CreditNoteSeller
+    # The customer receiving the credit (shown as 'Billed to')
+    customer: CreditNoteCustomer
+    # Credited lines. Use positive quantities and prices; they are shown as credit. [at least 1
+    # item]
+    items: List[CreditNoteItem]
+
+
+class CreditNoteData(_CreditNoteDataRequired, total=False):
+    """Data for the ``credit-note`` template (Credit note)."""
+
+    # [default "issued"]
+    status: Literal["issued", "applied", "refunded"]
+    # Currency symbol prefix [default "$"; max 4 chars]
+    currency: str
+    # Brand colour, e.g. #7048e8 [pattern ^#[0-9a-fA-F]{6}$]
+    accent: str
+    # Why the credit was issued [max 600 chars]
+    reason: str
+    # Tax credited back, applied to the subtotal
+    tax: CreditNoteTax
+    # How this credit will be applied, e.g. refunded to the original card [max 600 chars]
+    application: str
+    # [max 600 chars]
+    notes: str
+
+
+class _InvoiceSellerRequired(TypedDict):
+    """Required keys of :class:`InvoiceSeller`."""
+
+    # [non-empty]
+    name: str
+    address: List[str]
+
+
+class InvoiceSeller(_InvoiceSellerRequired, total=False):
+    """``seller`` in :class:`InvoiceData`."""
+
+    email: str
+    tax_id: str
+
+
+class _InvoiceCustomerRequired(TypedDict):
+    """Required keys of :class:`InvoiceCustomer`."""
+
+    # [non-empty]
+    name: str
+    address: List[str]
+
+
+class InvoiceCustomer(_InvoiceCustomerRequired, total=False):
+    """``customer`` in :class:`InvoiceData`."""
+
+    company: str
+    email: str
+
+
+class _InvoiceItemRequired(TypedDict):
+    """Required keys of :class:`InvoiceItem`."""
+
+    description: str
+    # [>= 0]
+    qty: float
+    unit_price: float
+
+
+class InvoiceItem(_InvoiceItemRequired, total=False):
+    """``items[]`` in :class:`InvoiceData`."""
+
+    detail: str
+
+
+class InvoiceDiscount(TypedDict):
+    """``discount`` in :class:`InvoiceData`."""
+
+    label: str
+    # [0 to 1]
+    rate: float
+
+
+class InvoiceTax(TypedDict):
+    """``tax`` in :class:`InvoiceData`."""
+
+    label: str
+    # [0 to 1]
+    rate: float
+
+
+class InvoicePayment(TypedDict, total=False):
+    """``payment`` in :class:`InvoiceData`."""
+
+    method: str
+    link: str
+    bank: str
+
+
+class _InvoiceDataRequired(TypedDict):
+    """Required keys of :class:`InvoiceData`."""
+
+    # Invoice number, e.g. INV-2026-0142
+    number: str
+    # Issue date, pre-formatted for display
+    issued: str
+    # Due date, pre-formatted for display
+    due: str
+    seller: InvoiceSeller
+    customer: InvoiceCustomer
+    # [at least 1 item]
+    items: List[InvoiceItem]
+
+
+class InvoiceData(_InvoiceDataRequired, total=False):
+    """Data for the ``invoice`` template (Invoice)."""
+
+    # [default "due"]
+    status: Literal["draft", "due", "paid", "overdue", "void"]
+    # Currency symbol prefix [default "$"; max 4 chars]
+    currency: str
+    # Brand colour, e.g. #3b5bdb [pattern ^#[0-9a-fA-F]{6}$]
+    accent: str
+    discount: InvoiceDiscount
+    tax: InvoiceTax
+    payment: InvoicePayment
+    notes: str
+
+
+class _QuoteSellerRequired(TypedDict):
+    """Required keys of :class:`QuoteSeller`."""
+
+    # [non-empty]
+    name: str
+
+
+class QuoteSeller(_QuoteSellerRequired, total=False):
+    """The business preparing the quote (shown as 'Prepared by')"""
+
+    # Person responsible, e.g. 'Jonas Berg, Account Director'
+    contact: str
+    email: str
+    phone: str
+    address: List[str]
+
+
+class _QuoteCustomerRequired(TypedDict):
+    """Required keys of :class:`QuoteCustomer`."""
+
+    # [non-empty]
+    name: str
+
+
+class QuoteCustomer(_QuoteCustomerRequired, total=False):
+    """The client receiving the quote (shown as 'Prepared for')"""
+
+    company: str
+    address: List[str]
+    email: str
+
+
+class _QuoteSectionItemRequired(TypedDict):
+    """Required keys of :class:`QuoteSectionItem`."""
+
+    description: str
+    # [>= 0]
+    qty: float
+    unit_price: float
+
+
+class QuoteSectionItem(_QuoteSectionItemRequired, total=False):
+    """``sections[].items[]`` in :class:`QuoteData`."""
+
+    detail: str
+    # Shown after the quantity, e.g. hrs, days [max 12 chars]
+    unit: str
+
+
+class _QuoteSectionRequired(TypedDict):
+    """Required keys of :class:`QuoteSection`."""
+
+    # [at least 1 item]
+    items: List[QuoteSectionItem]
+
+
+class QuoteSection(_QuoteSectionRequired, total=False):
+    """``sections[]`` in :class:`QuoteData`."""
+
+    title: str
+    # Short muted text shown next to the section title
+    note: str
+
+
+class QuoteDiscount(TypedDict):
+    """``discount`` in :class:`QuoteData`."""
+
+    label: str
+    # [0 to 1]
+    rate: float
+
+
+class QuoteTax(TypedDict):
+    """``tax`` in :class:`QuoteData`."""
+
+    label: str
+    # [0 to 1]
+    rate: float
+
+
+class _QuoteDataRequired(TypedDict):
+    """Required keys of :class:`QuoteData`."""
+
+    # Quote number, e.g. Q-2026-0057 [non-empty]
+    number: str
+    # Issue date, pre-formatted for display [non-empty]
+    issued: str
+    # Expiry date, pre-formatted for display [non-empty]
+    valid_until: str
+    # The business preparing the quote (shown as 'Prepared by')
+    seller: QuoteSeller
+    # The client receiving the quote (shown as 'Prepared for')
+    customer: QuoteCustomer
+    # Line items grouped into sections. Use a single section without a title for an ungrouped quote.
+    # Titles and subtotals are shown when there is more than one section. [at least 1 item]
+    sections: List[QuoteSection]
+
+
+class QuoteData(_QuoteDataRequired, total=False):
+    """Data for the ``quote`` template (Quote)."""
+
+    # [default "sent"]
+    status: Literal["draft", "sent", "accepted", "expired"]
+    # Currency symbol prefix [default "$"; max 4 chars]
+    currency: str
+    # Brand colour, e.g. #c2410c [pattern ^#[0-9a-fA-F]{6}$]
+    accent: str
+    # Short project title
+    project: str
+    # One-paragraph project summary
+    summary: str
+    discount: QuoteDiscount
+    tax: QuoteTax
+    terms: List[str]
+    # Text above the signature lines. Defaults to a sign-and-return instruction.
+    acceptance_note: str
+
+
+class _ReceiptSellerRequired(TypedDict):
+    """Required keys of :class:`ReceiptSeller`."""
+
+    # [non-empty]
+    name: str
+
+
+class ReceiptSeller(_ReceiptSellerRequired, total=False):
+    """``seller`` in :class:`ReceiptData`."""
+
+    # Shown under the brand name
+    email: str
+    address: List[str]
+    tax_id: str
+
+
+class _ReceiptCustomerRequired(TypedDict):
+    """Required keys of :class:`ReceiptCustomer`."""
+
+    # [non-empty]
+    name: str
+
+
+class ReceiptCustomer(_ReceiptCustomerRequired, total=False):
+    """``customer`` in :class:`ReceiptData`."""
+
+    company: str
+    address: List[str]
+    email: str
+
+
+class _ReceiptPaymentRequired(TypedDict):
+    """Required keys of :class:`ReceiptPayment`."""
+
+    # e.g. Visa •••• 4242 [non-empty]
+    method: str
+
+
+class ReceiptPayment(_ReceiptPaymentRequired, total=False):
+    """``payment`` in :class:`ReceiptData`."""
+
+    # [max 40 chars]
+    transaction_id: str
+
+
+class _ReceiptItemRequired(TypedDict):
+    """Required keys of :class:`ReceiptItem`."""
+
+    description: str
+    # [>= 0]
+    qty: float
+    unit_price: float
+
+
+class ReceiptItem(_ReceiptItemRequired, total=False):
+    """``items[]`` in :class:`ReceiptData`."""
+
+    detail: str
+
+
+class ReceiptDiscount(TypedDict):
+    """``discount`` in :class:`ReceiptData`."""
+
+    label: str
+    # [0 to 1]
+    rate: float
+
+
+class ReceiptTax(TypedDict):
+    """``tax`` in :class:`ReceiptData`."""
+
+    label: str
+    # [0 to 1]
+    rate: float
+
+
+class ReceiptSupport(TypedDict, total=False):
+    """``support`` in :class:`ReceiptData`."""
+
+    # [default "Questions?"]
+    title: str
+    email: str
+    phone: str
+    url: str
+
+
+class _ReceiptNoteRequired(TypedDict):
+    """Required keys of :class:`ReceiptNote`."""
+
+    text: str
+
+
+class ReceiptNote(_ReceiptNoteRequired, total=False):
+    """``note`` in :class:`ReceiptData`."""
+
+    # e.g. Refund policy [default "Notes"]
+    title: str
+
+
+class _ReceiptDataRequired(TypedDict):
+    """Required keys of :class:`ReceiptData`."""
+
+    # Receipt number, e.g. RCPT-2026-0388 [non-empty]
+    number: str
+    # Payment date, pre-formatted for display [non-empty]
+    paid_on: str
+    seller: ReceiptSeller
+    customer: ReceiptCustomer
+    payment: ReceiptPayment
+    # [at least 1 item]
+    items: List[ReceiptItem]
+
+
+class ReceiptData(_ReceiptDataRequired, total=False):
+    """Data for the ``receipt`` template (Receipt)."""
+
+    # Currency symbol prefix [default "$"; max 4 chars]
+    currency: str
+    # Brand colour, e.g. #0b7285 [pattern ^#[0-9a-fA-F]{6}$]
+    accent: str
+    discount: ReceiptDiscount
+    tax: ReceiptTax
+    support: ReceiptSupport
+    note: ReceiptNote
+
+
+class _StatementSellerRequired(TypedDict):
+    """Required keys of :class:`StatementSeller`."""
+
+    # [non-empty]
+    name: str
+
+
+class StatementSeller(_StatementSellerRequired, total=False):
+    """The business issuing the statement. The address is shown under 'Remit to'."""
+
+    # Shown under the brand name
+    email: str
+    address: List[str]
+
+
+class _StatementCustomerRequired(TypedDict):
+    """Required keys of :class:`StatementCustomer`."""
+
+    # [non-empty]
+    name: str
+
+
+class StatementCustomer(_StatementCustomerRequired, total=False):
+    """The account holder (shown as 'Statement for')"""
+
+    company: str
+    # Customer account number [max 30 chars]
+    account: str
+    address: List[str]
+    email: str
+
+
+class _StatementEntryRequired(TypedDict):
+    """Required keys of :class:`StatementEntry`."""
+
+    # Pre-formatted, e.g. 4 Sep [1 to 16 chars]
+    date: str
+    # [non-empty]
+    description: str
+
+
+class StatementEntry(_StatementEntryRequired, total=False):
+    """``entries[]`` in :class:`StatementData`."""
+
+    # e.g. INV-2026-0431 [max 18 chars]
+    reference: str
+    # [>= 0]
+    charge: float
+    # [>= 0]
+    payment: float
+
+
+class StatementAging(TypedDict):
+    """Outstanding balance by age"""
+
+    current: float
+    days_1_30: float
+    days_31_60: float
+    days_61_90: float
+    days_90_plus: float
+
+
+class StatementPayment(TypedDict, total=False):
+    """Payment instructions"""
+
+    method: str
+    # [max 80 chars]
+    link: str
+    bank: str
+    # Reference the customer should quote when paying [max 30 chars]
+    reference: str
+
+
+class _StatementDataRequired(TypedDict):
+    """Required keys of :class:`StatementData`."""
+
+    # Statement date, pre-formatted for display, e.g. 30 Sep 2026 [non-empty]
+    date: str
+    # Statement period, pre-formatted, e.g. 1 Sep – 30 Sep 2026 [1 to 60 chars]
+    period: str
+    # Balance at the start of the period. Negative means the customer is in credit.
+    opening_balance: float
+    # The business issuing the statement. The address is shown under 'Remit to'.
+    seller: StatementSeller
+    # The account holder (shown as 'Statement for')
+    customer: StatementCustomer
+    # Activity in the period, oldest first. The running balance is computed from opening_balance.
+    # Put invoices and debits in 'charge', payments and credits in 'payment'.
+    entries: List[StatementEntry]
+
+
+class StatementData(_StatementDataRequired, total=False):
+    """Data for the ``statement`` template (Statement of account)."""
+
+    # When the balance is due, pre-formatted for display
+    due_date: str
+    # Badge next to the balance. Defaults to 'due' when the closing balance is positive, 'paid' when
+    # it is zero and 'credit' when it is negative.
+    status: Literal["due", "overdue", "paid", "credit"]
+    # Currency symbol prefix [default "$"; max 4 chars]
+    currency: str
+    # Brand colour, e.g. #b45309 [pattern ^#[0-9a-fA-F]{6}$]
+    accent: str
+    # Outstanding balance by age
+    aging: StatementAging
+    # Payment instructions
+    payment: StatementPayment
+    # [max 600 chars]
+    notes: str
+
+
+DocumentData = Dict[str, Any]
+"""The ``document`` template accepts any JSON object: reserved keys shape the header, every other
+key becomes a section."""
+
+TemplateName = Literal["certificate", "credit-note", "document", "invoice", "quote", "receipt", "statement"]
+"""Names of the templates these types were generated from."""
+
+TEMPLATE_DATA_TYPES: Dict[str, Any] = {
+    "certificate": CertificateData,
+    "credit-note": CreditNoteData,
+    "document": DocumentData,
+    "invoice": InvoiceData,
+    "quote": QuoteData,
+    "receipt": ReceiptData,
+    "statement": StatementData,
+}
+"""Template name -> its data type."""

quirepdf-0.1.0.dist-info/METADATA

@@ -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.dist-info/RECORD

@@ -0,0 +1,9 @@
+quirepdf/__init__.py,sha256=I1ZxHwLsv_gaDc3Eav5jveiVUcAwEaYTyQ7dN44HCDA,732
+quirepdf/client.py,sha256=MtgKs_WXeU-9a-6vWAEHyWXphqha0RBE7h_LkV2-RPA,11494
+quirepdf/errors.py,sha256=FqI6wgOW_3WuS21jVe315m4_r_bu8N_CZuCh3j9Csq8,2810
+quirepdf/py.typed,sha256=47DEQpj8HBSa-_TImW-5JCeuQeRkm5NMpJWZG3hSuFU,0
+quirepdf/types.py,sha256=1YbV4k9AgfU9j39R8Q-BeflbT7jokceBUgxZAus-8f8,17679
+quirepdf-0.1.0.dist-info/METADATA,sha256=nBQb3s742354v09kV2PQUw2544RvffEgVeXeJFxwRa0,4948
+quirepdf-0.1.0.dist-info/WHEEL,sha256=W3fkpkm7-wf9vBI5Z-7s0eWkeM-spu78I8Neb98DeEg,87
+quirepdf-0.1.0.dist-info/licenses/LICENSE,sha256=ZW-qhkKnBmVhrfiWVu5aSfxUhhwaL-LHGLcCaJNYzwo,1066
+quirepdf-0.1.0.dist-info/RECORD,,

quirepdf-0.1.0.dist-info/WHEEL

@@ -0,0 +1,4 @@
+Wheel-Version: 1.0
+Generator: hatchling 1.32.4
+Root-Is-Purelib: true
+Tag: py3-none-any

quirepdf-0.1.0.dist-info/licenses/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.