twilldocs 0.1.0__py3-none-any.whl

twilldocs/__init__.py

@@ -0,0 +1,83 @@
+"""Official Python SDK for the Twill Docs document generation API."""
+
+from __future__ import annotations
+
+from .client import TwillDocs
+from .errors import (
+    TwillAuthenticationError,
+    TwillConflictError,
+    TwillConnectionError,
+    TwillError,
+    TwillNotFoundError,
+    TwillPermissionError,
+    TwillRateLimitError,
+    TwillServerError,
+    TwillTimeoutError,
+    TwillValidationError,
+)
+from .types import (
+    ApiKey,
+    Brand,
+    BrandTheme,
+    DeliveryItem,
+    DeliveryNoteInput,
+    Document,
+    Employee,
+    Health,
+    InvoiceInput,
+    IssuedBy,
+    LineItem,
+    NdaInput,
+    OfferLetterInput,
+    Party,
+    PayslipInput,
+    PayslipLine,
+    PurchaseOrderInput,
+    QuoteInput,
+    ReceiptInput,
+    SellerParty,
+    ServiceAgreementInput,
+    TemplateName,
+)
+
+__version__ = "0.1.0"
+
+__all__ = [
+    "TwillDocs",
+    # errors
+    "TwillError",
+    "TwillConnectionError",
+    "TwillTimeoutError",
+    "TwillAuthenticationError",
+    "TwillPermissionError",
+    "TwillNotFoundError",
+    "TwillConflictError",
+    "TwillServerError",
+    "TwillValidationError",
+    "TwillRateLimitError",
+    # shared types
+    "Party",
+    "SellerParty",
+    "LineItem",
+    "DeliveryItem",
+    "PayslipLine",
+    "Employee",
+    "IssuedBy",
+    "TemplateName",
+    # template inputs
+    "InvoiceInput",
+    "QuoteInput",
+    "ReceiptInput",
+    "PurchaseOrderInput",
+    "DeliveryNoteInput",
+    "PayslipInput",
+    "OfferLetterInput",
+    "NdaInput",
+    "ServiceAgreementInput",
+    # responses
+    "Document",
+    "ApiKey",
+    "Brand",
+    "BrandTheme",
+    "Health",
+]

twilldocs/client.py

@@ -0,0 +1,121 @@
+"""The Twill Docs API client."""
+
+from __future__ import annotations
+
+from typing import Any, Dict, Optional
+
+import httpx
+
+from .errors import TwillConnectionError, TwillError, TwillTimeoutError, error_from_response
+from .resources.api_keys import ApiKeys
+from .resources.brand import BrandResource
+from .resources.documents import Documents
+from .types import Health
+
+DEFAULT_BASE_URL = "https://api.twilldocs.com"
+
+
+class TwillDocs:
+    """
+    Client for the Twill Docs API.
+
+    >>> from twilldocs import TwillDocs
+    >>> twill = TwillDocs(api_key="twdc_...")
+    >>> doc = twill.documents.generate("invoice", {...})
+    >>> pdf = twill.documents.download(doc["id"])
+    """
+
+    def __init__(
+        self,
+        api_key: str,
+        *,
+        base_url: str = DEFAULT_BASE_URL,
+        timeout: float = 30.0,
+    ) -> None:
+        if not api_key:
+            raise TwillError(
+                "An api_key is required to construct the TwillDocs client.",
+                type="authentication_error",
+            )
+        self._api_key = api_key
+        self._base_url = base_url.rstrip("/")
+        self._http = httpx.Client(timeout=timeout)
+
+        self.documents = Documents(self)
+        self.api_keys = ApiKeys(self)
+        self.brand = BrandResource(self)
+
+    # -- lifecycle ----------------------------------------------------------
+
+    def close(self) -> None:
+        self._http.close()
+
+    def __enter__(self) -> "TwillDocs":
+        return self
+
+    def __exit__(self, *_exc: Any) -> None:
+        self.close()
+
+    # -- public endpoints ---------------------------------------------------
+
+    def health(self) -> Health:
+        """Unauthenticated dependency health check."""
+        return self.request_json("GET", "/v1/health", auth=False)
+
+    # -- internal transport -------------------------------------------------
+
+    def request_json(self, method: str, path: str, **kwargs: Any) -> Any:
+        """Send a request and parse the JSON response. :meta private:"""
+        response = self._send(method, path, **kwargs)
+        if response.status_code == 204 or not response.content:
+            return None
+        return response.json()
+
+    def request_bytes(self, method: str, path: str, **kwargs: Any) -> bytes:
+        """Send a request and return the raw response bytes. :meta private:"""
+        return self._send(method, path, **kwargs).content
+
+    def _send(
+        self,
+        method: str,
+        path: str,
+        *,
+        json_body: Any = None,
+        data: Optional[Dict[str, Any]] = None,
+        files: Optional[Dict[str, Any]] = None,
+        headers: Optional[Dict[str, str]] = None,
+        auth: bool = True,
+    ) -> httpx.Response:
+        request_headers: Dict[str, str] = {"Accept": "application/json"}
+        if headers:
+            request_headers.update(headers)
+        if auth:
+            request_headers["Authorization"] = f"Bearer {self._api_key}"
+
+        try:
+            response = self._http.request(
+                method,
+                self._base_url + path,
+                json=json_body,
+                data=data,
+                files=files,
+                headers=request_headers,
+            )
+        except httpx.TimeoutException as exc:
+            raise TwillTimeoutError(f"Request to {path} timed out.", type="timeout_error") from exc
+        except httpx.HTTPError as exc:
+            raise TwillConnectionError(f"Request to {path} failed: {exc}", type="connection_error") from exc
+
+        if response.is_error:
+            request_id = response.headers.get("x-request-id")
+            try:
+                body: Any = response.json()
+            except ValueError:
+                body = response.text
+            retry_after: Optional[int] = None
+            if response.status_code == 429:
+                header_value = response.headers.get("retry-after", "")
+                retry_after = int(header_value) if header_value.isdigit() else None
+            raise error_from_response(response.status_code, body, request_id, retry_after)
+
+        return response

twilldocs/errors.py

@@ -0,0 +1,97 @@
+"""Exception hierarchy for the Twill Docs SDK."""
+
+from __future__ import annotations
+
+from typing import Any, Dict, List, Optional
+
+
+class TwillError(Exception):
+    """Base class for every error raised by the SDK. Catch this to catch them all."""
+
+    def __init__(
+        self,
+        message: str,
+        *,
+        status: Optional[int] = None,
+        type: str = "api_error",
+        request_id: Optional[str] = None,
+        body: Any = None,
+    ) -> None:
+        super().__init__(message)
+        self.message = message
+        self.status = status
+        self.type = type
+        self.request_id = request_id
+        self.body = body
+
+
+class TwillConnectionError(TwillError):
+    """The request never reached the API (DNS, connection refused, socket error)."""
+
+
+class TwillTimeoutError(TwillError):
+    """The request exceeded the configured timeout."""
+
+
+class TwillAuthenticationError(TwillError):
+    """401 — missing, invalid, or revoked API key."""
+
+
+class TwillPermissionError(TwillError):
+    """403 — the key is valid but not allowed to perform this action."""
+
+
+class TwillNotFoundError(TwillError):
+    """404 — the resource doesn't exist (or isn't visible to this tenant)."""
+
+
+class TwillConflictError(TwillError):
+    """409 — the request conflicts with the resource's current state."""
+
+
+class TwillServerError(TwillError):
+    """5xx — something went wrong on the API's side. Usually safe to retry."""
+
+
+class TwillValidationError(TwillError):
+    """400 / 422 — the request was malformed or failed validation."""
+
+    def __init__(self, message: str, *, errors: Optional[Dict[str, List[str]]] = None, **kwargs: Any) -> None:
+        super().__init__(message, **kwargs)
+        self.errors = errors
+
+
+class TwillRateLimitError(TwillError):
+    """429 — rate limited. See ``retry_after`` for how long to wait."""
+
+    def __init__(self, message: str, *, retry_after: Optional[int] = None, **kwargs: Any) -> None:
+        super().__init__(message, **kwargs)
+        self.retry_after = retry_after
+
+
+def error_from_response(
+    status: int,
+    body: Any,
+    request_id: Optional[str] = None,
+    retry_after: Optional[int] = None,
+) -> TwillError:
+    """Build the most specific error subclass for an HTTP response."""
+    parsed = body if isinstance(body, dict) else {}
+    message = parsed.get("message") or f"Request failed with status {status}"
+    common: Dict[str, Any] = {"status": status, "request_id": request_id, "body": body}
+
+    if status in (400, 422):
+        return TwillValidationError(message, type="invalid_request_error", errors=parsed.get("errors"), **common)
+    if status == 401:
+        return TwillAuthenticationError(message, type="authentication_error", **common)
+    if status == 403:
+        return TwillPermissionError(message, type="permission_error", **common)
+    if status == 404:
+        return TwillNotFoundError(message, type="not_found_error", **common)
+    if status == 409:
+        return TwillConflictError(message, type="conflict_error", **common)
+    if status == 429:
+        return TwillRateLimitError(message, type="rate_limit_error", retry_after=retry_after, **common)
+    if status >= 500:
+        return TwillServerError(message, type="api_error", **common)
+    return TwillError(message, type="api_error", **common)

twilldocs/resources/__init__.py

@@ -0,0 +1,5 @@
+from .api_keys import ApiKeys
+from .brand import BrandResource
+from .documents import Documents
+
+__all__ = ["Documents", "ApiKeys", "BrandResource"]

twilldocs/resources/api_keys.py

@@ -0,0 +1,27 @@
+"""The API keys resource."""
+
+from __future__ import annotations
+
+from typing import TYPE_CHECKING, List
+
+from ..types import ApiKey
+
+if TYPE_CHECKING:
+    from ..client import TwillDocs
+
+
+class ApiKeys:
+    def __init__(self, client: "TwillDocs") -> None:
+        self._client = client
+
+    def list(self) -> List[ApiKey]:
+        """List the tenant's API keys, newest first."""
+        response = self._client.request_json("GET", "/v1/api-keys")
+        return response["data"]
+
+    def revoke(self, id: int) -> ApiKey:
+        """
+        Revoke an API key. Idempotent — revoking an already-revoked key
+        succeeds. The API rejects (409) revoking the tenant's only active key.
+        """
+        return self._client.request_json("DELETE", f"/v1/api-keys/{id}")

twilldocs/resources/brand.py

@@ -0,0 +1,48 @@
+"""The brand resource."""
+
+from __future__ import annotations
+
+from typing import TYPE_CHECKING, Any, Dict, Optional, Tuple, Union
+
+from ..types import Brand
+
+if TYPE_CHECKING:
+    from ..client import TwillDocs
+
+# A logo upload, in the shape httpx expects for a file field:
+#   (filename, content)  or  (filename, content, content_type)
+LogoFile = Union[Tuple[str, bytes], Tuple[str, bytes, str]]
+
+
+class BrandResource:
+    def __init__(self, client: "TwillDocs") -> None:
+        self._client = client
+
+    def retrieve(self) -> Brand:
+        """Fetch the tenant's current brand (theme + logo state + available themes)."""
+        return self._client.request_json("GET", "/v1/brand")
+
+    def update(self, *, theme: Optional[str] = None, logo: Optional[LogoFile] = None) -> Brand:
+        """
+        Update the theme and/or upload a logo (max 1 MB). Both are optional.
+
+        ``logo`` is a tuple of ``(filename, content)`` or
+        ``(filename, content, content_type)``, e.g.
+        ``("logo.png", png_bytes, "image/png")``.
+        """
+        data: Dict[str, Any] = {}
+        files: Dict[str, Any] = {}
+        if theme is not None:
+            data["theme"] = theme
+        if logo is not None:
+            files["logo"] = logo
+        return self._client.request_json(
+            "POST",
+            "/v1/brand",
+            data=data or None,
+            files=files or None,
+        )
+
+    def delete_logo(self) -> Brand:
+        """Remove the tenant's logo."""
+        return self._client.request_json("DELETE", "/v1/brand/logo")

twilldocs/resources/documents.py

@@ -0,0 +1,121 @@
+"""The documents resource."""
+
+from __future__ import annotations
+
+import time
+import uuid
+from typing import TYPE_CHECKING, Any, Literal, Optional, overload
+
+from ..errors import TwillError, TwillTimeoutError
+from ..types import (
+    DeliveryNoteInput,
+    Document,
+    InvoiceInput,
+    NdaInput,
+    OfferLetterInput,
+    PayslipInput,
+    PurchaseOrderInput,
+    QuoteInput,
+    ReceiptInput,
+    ServiceAgreementInput,
+)
+
+if TYPE_CHECKING:
+    from ..client import TwillDocs
+
+
+class Documents:
+    def __init__(self, client: "TwillDocs") -> None:
+        self._client = client
+
+    # -- create -------------------------------------------------------------
+    # One overload per template so the `input` type is checked against the
+    # template you name — passing a receipt payload to "invoice" is an error.
+
+    @overload
+    def create(self, template: Literal["invoice"], input: InvoiceInput, *, idempotency_key: Optional[str] = None) -> Document: ...
+    @overload
+    def create(self, template: Literal["quote"], input: QuoteInput, *, idempotency_key: Optional[str] = None) -> Document: ...
+    @overload
+    def create(self, template: Literal["receipt"], input: ReceiptInput, *, idempotency_key: Optional[str] = None) -> Document: ...
+    @overload
+    def create(self, template: Literal["purchase_order"], input: PurchaseOrderInput, *, idempotency_key: Optional[str] = None) -> Document: ...
+    @overload
+    def create(self, template: Literal["delivery_note"], input: DeliveryNoteInput, *, idempotency_key: Optional[str] = None) -> Document: ...
+    @overload
+    def create(self, template: Literal["payslip"], input: PayslipInput, *, idempotency_key: Optional[str] = None) -> Document: ...
+    @overload
+    def create(self, template: Literal["offer_letter"], input: OfferLetterInput, *, idempotency_key: Optional[str] = None) -> Document: ...
+    @overload
+    def create(self, template: Literal["nda"], input: NdaInput, *, idempotency_key: Optional[str] = None) -> Document: ...
+    @overload
+    def create(self, template: Literal["service_agreement"], input: ServiceAgreementInput, *, idempotency_key: Optional[str] = None) -> Document: ...
+
+    def create(self, template: str, input: Any, *, idempotency_key: Optional[str] = None) -> Document:
+        """
+        Create a document. Returns immediately with a ``pending`` document while
+        the PDF renders asynchronously.
+
+        The ``idempotency_key`` (auto-generated if omitted) makes a retried
+        request return the original document instead of a duplicate.
+        """
+        key = idempotency_key or uuid.uuid4().hex
+        return self._client.request_json(
+            "POST",
+            "/v1/documents",
+            json_body={"template": template, "input": input},
+            headers={"Idempotency-Key": key},
+        )
+
+    # -- retrieve / download ------------------------------------------------
+
+    def retrieve(self, id: int) -> Document:
+        """Fetch a document's current status."""
+        return self._client.request_json("GET", f"/v1/documents/{id}")
+
+    def download(self, id: int) -> bytes:
+        """Download the rendered PDF bytes. Only valid once the document has succeeded."""
+        return self._client.request_bytes("GET", f"/v1/documents/{id}/download")
+
+    def wait_until_ready(self, id: int, *, interval: float = 1.0, timeout: float = 60.0) -> Document:
+        """Poll until the document finishes rendering (or fails / times out)."""
+        deadline = time.monotonic() + timeout
+        while True:
+            doc = self.retrieve(id)
+            if doc["status"] == "succeeded":
+                return doc
+            if doc["status"] == "failed":
+                raise TwillError(
+                    f"Render failed for document {id}: {doc.get('error') or 'unknown error'}",
+                    type="api_error",
+                    body=doc,
+                )
+            if time.monotonic() + interval > deadline:
+                raise TwillTimeoutError(f"Timed out waiting for document {id} to render.", type="timeout_error")
+            time.sleep(interval)
+
+    # -- generate (create + wait) -------------------------------------------
+
+    @overload
+    def generate(self, template: Literal["invoice"], input: InvoiceInput, *, idempotency_key: Optional[str] = None, interval: float = 1.0, timeout: float = 60.0) -> Document: ...
+    @overload
+    def generate(self, template: Literal["quote"], input: QuoteInput, *, idempotency_key: Optional[str] = None, interval: float = 1.0, timeout: float = 60.0) -> Document: ...
+    @overload
+    def generate(self, template: Literal["receipt"], input: ReceiptInput, *, idempotency_key: Optional[str] = None, interval: float = 1.0, timeout: float = 60.0) -> Document: ...
+    @overload
+    def generate(self, template: Literal["purchase_order"], input: PurchaseOrderInput, *, idempotency_key: Optional[str] = None, interval: float = 1.0, timeout: float = 60.0) -> Document: ...
+    @overload
+    def generate(self, template: Literal["delivery_note"], input: DeliveryNoteInput, *, idempotency_key: Optional[str] = None, interval: float = 1.0, timeout: float = 60.0) -> Document: ...
+    @overload
+    def generate(self, template: Literal["payslip"], input: PayslipInput, *, idempotency_key: Optional[str] = None, interval: float = 1.0, timeout: float = 60.0) -> Document: ...
+    @overload
+    def generate(self, template: Literal["offer_letter"], input: OfferLetterInput, *, idempotency_key: Optional[str] = None, interval: float = 1.0, timeout: float = 60.0) -> Document: ...
+    @overload
+    def generate(self, template: Literal["nda"], input: NdaInput, *, idempotency_key: Optional[str] = None, interval: float = 1.0, timeout: float = 60.0) -> Document: ...
+    @overload
+    def generate(self, template: Literal["service_agreement"], input: ServiceAgreementInput, *, idempotency_key: Optional[str] = None, interval: float = 1.0, timeout: float = 60.0) -> Document: ...
+
+    def generate(self, template: str, input: Any, *, idempotency_key: Optional[str] = None, interval: float = 1.0, timeout: float = 60.0) -> Document:
+        """Create a document and wait for it to finish rendering."""
+        created = self.create(template, input, idempotency_key=idempotency_key)  # type: ignore[call-overload]
+        return self.wait_until_ready(created["id"], interval=interval, timeout=timeout)

twilldocs/types.py

@@ -0,0 +1,220 @@
+"""Typed shapes for the Twill Docs API — template inputs and responses.
+
+Uses ``TypedDict`` so editors and mypy check the payloads you build, while the
+values stay plain dicts at runtime.
+"""
+
+from __future__ import annotations
+
+from typing import Dict, List, Literal, Optional
+
+from typing_extensions import NotRequired, TypedDict
+
+# -- Shared building blocks --------------------------------------------------
+
+
+class Party(TypedDict):
+    name: str
+    address: str
+    email: NotRequired[str]
+
+
+class SellerParty(TypedDict):
+    name: str
+    address: str
+    email: NotRequired[str]
+    tax_id: NotRequired[str]
+
+
+class LineItem(TypedDict):
+    description: str
+    quantity: float
+    unit_price: float  # per-unit price, not the line total
+
+
+class DeliveryItem(TypedDict):
+    description: str
+    quantity: float
+    unit: NotRequired[str]
+
+
+class PayslipLine(TypedDict):
+    description: str
+    amount: float
+
+
+class Employee(TypedDict):
+    name: str
+    id: NotRequired[str]
+    position: NotRequired[str]
+
+
+class IssuedBy(TypedDict):
+    name: str
+    title: str
+
+
+# -- Template inputs ---------------------------------------------------------
+
+
+class InvoiceInput(TypedDict):
+    invoice_number: str
+    issue_date: str
+    due_date: str
+    currency: str
+    seller: SellerParty
+    buyer: Party
+    line_items: List[LineItem]
+    tax_rate: NotRequired[float]
+    notes: NotRequired[str]
+
+
+class QuoteInput(TypedDict):
+    quote_number: str
+    issue_date: str
+    valid_until: str
+    currency: str
+    seller: SellerParty
+    buyer: Party
+    line_items: List[LineItem]
+    tax_rate: NotRequired[float]
+    notes: NotRequired[str]
+
+
+class ReceiptInput(TypedDict):
+    receipt_number: str
+    issue_date: str
+    currency: str
+    seller: SellerParty
+    buyer: Party
+    line_items: List[LineItem]
+    tax_rate: NotRequired[float]
+    notes: NotRequired[str]
+    payment_method: NotRequired[str]
+
+
+class PurchaseOrderInput(TypedDict):
+    po_number: str
+    issue_date: str
+    currency: str
+    seller: SellerParty
+    buyer: Party
+    line_items: List[LineItem]
+    needed_by: NotRequired[str]
+    tax_rate: NotRequired[float]
+    notes: NotRequired[str]
+
+
+# `from` is a Python keyword, so this one uses the functional TypedDict syntax.
+DeliveryNoteInput = TypedDict(
+    "DeliveryNoteInput",
+    {
+        "delivery_note_number": str,
+        "delivery_date": str,
+        "carrier": NotRequired[str],
+        "tracking_number": NotRequired[str],
+        "items": List[DeliveryItem],
+        "notes": NotRequired[str],
+        "from": Party,
+        "to": Party,
+    },
+)
+
+
+class PayslipInput(TypedDict):
+    payslip_number: str
+    pay_period_start: str
+    pay_period_end: str
+    currency: str
+    employee: Employee
+    employer: Party
+    earnings: List[PayslipLine]
+    deductions: NotRequired[List[PayslipLine]]
+    notes: NotRequired[str]
+
+
+class OfferLetterInput(TypedDict):
+    candidate_name: str
+    position: str
+    start_date: str
+    salary_amount: float
+    salary_currency: str
+    issued_by: IssuedBy
+    company: Party
+    department: NotRequired[str]
+    offer_expiry_date: NotRequired[str]
+    reporting_manager: NotRequired[str]
+    salary_frequency: NotRequired[Literal["annual", "monthly"]]
+    benefits: NotRequired[str]
+
+
+class NdaInput(TypedDict):
+    effective_date: str
+    term_months: int
+    governing_law: str
+    purpose: str
+    disclosing_party: Party
+    receiving_party: Party
+
+
+class ServiceAgreementInput(TypedDict):
+    effective_date: str
+    term_description: str
+    services_description: str
+    fees_description: str
+    governing_law: str
+    provider: Party
+    client: Party
+
+
+TemplateName = Literal[
+    "invoice",
+    "quote",
+    "receipt",
+    "purchase_order",
+    "delivery_note",
+    "payslip",
+    "offer_letter",
+    "nda",
+    "service_agreement",
+]
+
+# -- Responses ---------------------------------------------------------------
+
+DocumentStatus = Literal["pending", "processing", "succeeded", "failed"]
+
+
+class Document(TypedDict):
+    id: int
+    status: DocumentStatus
+    error: NotRequired[Optional[str]]
+    created_at: NotRequired[str]
+
+
+class ApiKey(TypedDict):
+    id: int
+    name: Optional[str]
+    last_used_at: Optional[str]
+    revoked_at: Optional[str]
+    created_at: str
+
+
+class BrandTheme(TypedDict):
+    name: str
+    label: str
+    available: bool
+
+
+class Brand(TypedDict):
+    theme: str
+    has_logo: bool
+    themes: List[BrandTheme]
+
+
+class HealthCheck(TypedDict):
+    ok: bool
+
+
+class Health(TypedDict):
+    status: Literal["ok", "degraded"]
+    checks: Dict[str, HealthCheck]

twilldocs-0.1.0.dist-info/METADATA

@@ -0,0 +1,174 @@
+Metadata-Version: 2.4
+Name: twilldocs
+Version: 0.1.0
+Summary: Official Python SDK for the Twill Docs document generation API.
+Project-URL: Homepage, https://www.twilldocs.com
+Project-URL: Repository, https://github.com/twilldocs/twilldocs-python
+Author: Twill Docs
+License: MIT
+License-File: LICENSE
+Keywords: api,documents,invoice,pdf,sdk,twilldocs
+Classifier: License :: OSI Approved :: MIT License
+Classifier: Programming Language :: Python :: 3
+Classifier: Typing :: Typed
+Requires-Python: >=3.9
+Requires-Dist: httpx>=0.24
+Requires-Dist: typing-extensions>=4.0
+Description-Content-Type: text/markdown
+
+# Twill Docs — Python SDK
+
+The official Python SDK for [Twill Docs](https://www.twilldocs.com), the
+document infrastructure API. Turn structured data into production-ready PDFs —
+invoices, receipts, payslips, and more — with typed payloads.
+
+- **Typed templates** — each document type has a `TypedDict` input, checked by mypy and your editor.
+- **Typed errors** — catch `TwillRateLimitError`, `TwillValidationError`, and friends.
+- Built on [httpx](https://www.python-httpx.org/).
+
+## Install
+
+```bash
+pip install twilldocs
+```
+
+Requires Python 3.9+.
+
+## Quickstart
+
+```python
+from twilldocs import TwillDocs
+
+twill = TwillDocs(api_key="twdc_...")
+
+# Create an invoice, wait for it to render, then download the PDF.
+doc = twill.documents.generate("invoice", {
+    "invoice_number": "INV-1001",
+    "issue_date": "2026-07-22",
+    "due_date": "2026-08-21",
+    "currency": "USD",
+    "seller": {"name": "Northwind Studio", "address": "500 Market St", "tax_id": "US123456789"},
+    "buyer": {"name": "Acme Corp", "address": "1 Infinite Loop"},
+    "line_items": [
+        {"description": "Consulting", "quantity": 3, "unit_price": 1200},
+        {"description": "Travel expenses", "quantity": 1, "unit_price": 340},
+    ],
+    "tax_rate": 0.085,
+})
+
+pdf = twill.documents.download(doc["id"])  # bytes
+open(f"invoice-{doc['id']}.pdf", "wb").write(pdf)
+```
+
+You supply line items and the tax rate; **Twill computes the totals** and renders
+the document.
+
+## Configuration
+
+```python
+twill = TwillDocs(
+    api_key="twdc_...",                 # required
+    base_url="https://api.twilldocs.com",  # default; use http://localhost:8080 for local dev
+    timeout=30.0,                       # per-request timeout in seconds
+)
+```
+
+The client holds a connection pool — reuse one instance, or use it as a context
+manager:
+
+```python
+with TwillDocs(api_key="twdc_...") as twill:
+    twill.documents.generate("receipt", {...})
+```
+
+## Documents
+
+```python
+doc = twill.documents.create("invoice", {...})   # returns immediately, status "pending"
+twill.documents.retrieve(doc["id"])              # check status
+twill.documents.wait_until_ready(doc["id"])      # poll until succeeded / failed
+pdf = twill.documents.download(doc["id"])         # bytes
+twill.documents.generate("invoice", {...})       # create + wait, in one call
+```
+
+Every `create`/`generate` sends an idempotency key automatically (override with
+`idempotency_key=...`), so a retried request never produces a duplicate.
+
+### Templates
+
+The template name you pass narrows the accepted input type. Templates and their
+input `TypedDict`s:
+
+| Template | Input type |
+| -------- | ---------- |
+| `invoice` | `InvoiceInput` |
+| `quote` | `QuoteInput` |
+| `receipt` | `ReceiptInput` |
+| `purchase_order` | `PurchaseOrderInput` |
+| `delivery_note` | `DeliveryNoteInput` |
+| `payslip` | `PayslipInput` |
+| `offer_letter` | `OfferLetterInput` |
+| `nda` | `NdaInput` |
+| `service_agreement` | `ServiceAgreementInput` |
+
+All input types are importable for building payloads with full typing:
+
+```python
+from twilldocs import InvoiceInput
+```
+
+## API keys
+
+```python
+keys = twill.api_keys.list()
+twill.api_keys.revoke(keys[0]["id"])
+```
+
+## Brand
+
+```python
+twill.brand.retrieve()
+twill.brand.update(theme="modern")
+twill.brand.update(logo=("logo.png", open("logo.png", "rb").read(), "image/png"))
+twill.brand.delete_logo()
+```
+
+## Errors
+
+Every failure raises a subclass of `TwillError`:
+
+```python
+from twilldocs import TwillValidationError, TwillRateLimitError, TwillError
+import time
+
+try:
+    twill.documents.generate("invoice", data)
+except TwillValidationError as e:
+    print("Invalid input:", e.errors)     # per-field messages
+except TwillRateLimitError as e:
+    time.sleep(e.retry_after or 1)
+except TwillError as e:
+    print(e.status, e.type, e.message)
+```
+
+| Class | When |
+| ----- | ---- |
+| `TwillValidationError` | 400 / 422 (`.errors` has field messages) |
+| `TwillAuthenticationError` | 401 |
+| `TwillPermissionError` | 403 |
+| `TwillNotFoundError` | 404 |
+| `TwillConflictError` | 409 |
+| `TwillRateLimitError` | 429 (`.retry_after` seconds) |
+| `TwillServerError` | 5xx |
+| `TwillConnectionError` | network failure before a response |
+| `TwillTimeoutError` | request exceeded `timeout` |
+
+## Health
+
+```python
+twill.health()  # {"status": "ok" | "degraded", "checks": {...}}
+```
+
+## License
+
+[MIT](./LICENSE)

twilldocs-0.1.0.dist-info/RECORD

@@ -0,0 +1,13 @@
+twilldocs/__init__.py,sha256=SASJ15jurYTsjXtlKbxSxE01wZ7ka9GVcJFWfUhHaR0,1593
+twilldocs/client.py,sha256=RyLUgEMsHueTL0H4qFRhm42BaKeG_OzoTiGmg4xRAsY,4062
+twilldocs/errors.py,sha256=4CEXCGO93yK9Lq5iOpRw2F1ejxD_vWXhpVng2W7tP5E,3312
+twilldocs/py.typed,sha256=47DEQpj8HBSa-_TImW-5JCeuQeRkm5NMpJWZG3hSuFU,0
+twilldocs/types.py,sha256=3qFhFBWec3yCyv8rAQG9WHcnARUt9kgTJ7d5PpCCf5k,4584
+twilldocs/resources/__init__.py,sha256=6t9VX4xmxWFoyJDarcq3PHSFBGEKd94HghBz2omcHGM,149
+twilldocs/resources/api_keys.py,sha256=AdBCzUhdhk9ECNlPnb7Op0NtO9QyZc-fhePKpNtcj48,772
+twilldocs/resources/brand.py,sha256=tqF7QeGr2NUkgwCptjNR0HS4nKZxlXSlfK8PW3miD00,1548
+twilldocs/resources/documents.py,sha256=8saLE-BISBEecGAzEVBiEzTTIJXilCIZJNTNrv5glaI,6371
+twilldocs-0.1.0.dist-info/METADATA,sha256=MLbv6kkn2nM4np59EUAAwGMzDt8g015E19lMCaOSeW0,4989
+twilldocs-0.1.0.dist-info/WHEEL,sha256=lCkmxWfQsSc9CfIClYeavTdQeEX2toPqufh9gI35EQA,87
+twilldocs-0.1.0.dist-info/licenses/LICENSE,sha256=v9tbhsf4CNXRzKrTQoOLIO-SSSWTMes-Lyn906rwzGs,1067
+twilldocs-0.1.0.dist-info/RECORD,,

twilldocs-0.1.0.dist-info/WHEEL

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

twilldocs-0.1.0.dist-info/licenses/LICENSE

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