formfeed 0.1.0__tar.gz

formfeed-0.1.0/.gitignore

@@ -0,0 +1,19 @@
+node_modules
+dist
+tmp
+out-tsc
+coverage
+.nx/cache
+.nx/workspace-data
+
+# Python
+__pycache__/
+.pytest_cache/
+*.egg-info/
+.venv/
+
+# editors and systems
+.idea
+.vscode
+.DS_Store
+Thumbs.db

formfeed-0.1.0/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 Philipp Staudt IT-Dienstleistungen
+
+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.

formfeed-0.1.0/PKG-INFO

@@ -0,0 +1,70 @@
+Metadata-Version: 2.5
+Name: formfeed
+Version: 0.1.0
+Summary: Formfeed API client: template-based PDF and image generation (sync and async, httpx).
+Project-URL: Homepage, https://formfeed.dev
+Project-URL: Documentation, https://docs.formfeed.dev/api/sdks/python
+Project-URL: Source, https://github.com/formfeed-dev/formfeed/tree/main/packages/sdk-python
+Project-URL: Issues, https://github.com/formfeed-dev/formfeed/issues
+Project-URL: Changelog, https://docs.formfeed.dev/changelog
+Author-email: Formfeed <support@formfeed.dev>
+License-Expression: MIT
+License-File: LICENSE
+Keywords: api,formfeed,html-to-pdf,pdf,pdf-generation,sdk,templates
+Classifier: Development Status :: 4 - Beta
+Classifier: Intended Audience :: Developers
+Classifier: Operating System :: OS Independent
+Classifier: Programming Language :: Python :: 3
+Classifier: Programming Language :: Python :: 3 :: Only
+Classifier: Programming Language :: Python :: 3.10
+Classifier: Programming Language :: Python :: 3.11
+Classifier: Programming Language :: Python :: 3.12
+Classifier: Programming Language :: Python :: 3.13
+Classifier: Topic :: Office/Business
+Classifier: Topic :: Software Development :: Libraries :: Python Modules
+Classifier: Typing :: Typed
+Requires-Python: >=3.10
+Requires-Dist: httpx>=0.27
+Requires-Dist: pydantic>=2.5
+Description-Content-Type: text/markdown
+
+# formfeed (Python)
+
+Client for the Formfeed API: template-based PDF and image generation. Sync and async, built on
+httpx, pydantic models, retries on 429 and 503 with the server's `Retry-After`, an
+`Idempotency-Key` on every render, typed errors and webhook verification.
+
+```bash
+pip install formfeed
+```
+
+```python
+from formfeed import Formfeed
+
+client = Formfeed("ff_test_…")                      # region="us" or base_url="…" for other hosts
+render = client.renders.create(template="invoice-de", data={"invoice": {"number": "2026-001"}})
+open("invoice.pdf", "wb").write(client.renders.download(render))
+
+job = client.renders.batch([{"data": d} for d in rows], template="invoice-de", zip=True)
+job = client.jobs.wait_for(job.id)
+```
+
+```python
+from formfeed import AsyncFormfeed
+
+async with AsyncFormfeed("ff_test_…") as client:
+    render = await client.renders.create(html="<h1>Hello</h1>", output="png")
+```
+
+Webhooks:
+
+```python
+from formfeed import parse_webhook_event
+
+event = parse_webhook_event(secret, request.headers["Webhook-Signature"], request.body)
+```
+
+Errors raise `FormfeedError` with `code`, `status`, `problem` and `request_id`. Templates:
+`client.templates.all()`, `.version("invoice-de", "latest")`, `.create_version(...)`, `.publish(...)`.
+
+Documentation: <https://docs.formfeed.dev/api/sdks/python>

formfeed-0.1.0/README.md

@@ -0,0 +1,40 @@
+# formfeed (Python)
+
+Client for the Formfeed API: template-based PDF and image generation. Sync and async, built on
+httpx, pydantic models, retries on 429 and 503 with the server's `Retry-After`, an
+`Idempotency-Key` on every render, typed errors and webhook verification.
+
+```bash
+pip install formfeed
+```
+
+```python
+from formfeed import Formfeed
+
+client = Formfeed("ff_test_…")                      # region="us" or base_url="…" for other hosts
+render = client.renders.create(template="invoice-de", data={"invoice": {"number": "2026-001"}})
+open("invoice.pdf", "wb").write(client.renders.download(render))
+
+job = client.renders.batch([{"data": d} for d in rows], template="invoice-de", zip=True)
+job = client.jobs.wait_for(job.id)
+```
+
+```python
+from formfeed import AsyncFormfeed
+
+async with AsyncFormfeed("ff_test_…") as client:
+    render = await client.renders.create(html="<h1>Hello</h1>", output="png")
+```
+
+Webhooks:
+
+```python
+from formfeed import parse_webhook_event
+
+event = parse_webhook_event(secret, request.headers["Webhook-Signature"], request.body)
+```
+
+Errors raise `FormfeedError` with `code`, `status`, `problem` and `request_id`. Templates:
+`client.templates.all()`, `.version("invoice-de", "latest")`, `.create_version(...)`, `.publish(...)`.
+
+Documentation: <https://docs.formfeed.dev/api/sdks/python>

formfeed-0.1.0/pyproject.toml

@@ -0,0 +1,48 @@
+[build-system]
+requires = ["hatchling>=1.25"]
+build-backend = "hatchling.build"
+
+[project]
+name = "formfeed"
+version = "0.1.0"
+description = "Formfeed API client: template-based PDF and image generation (sync and async, httpx)."
+readme = "README.md"
+# PEP 639: the SPDX expression replaces the licence classifier, the two must not be combined
+license = "MIT"
+license-files = ["LICENSE"]
+requires-python = ">=3.10"
+authors = [{ name = "Formfeed", email = "support@formfeed.dev" }]
+keywords = ["formfeed", "pdf", "pdf-generation", "html-to-pdf", "templates", "api", "sdk"]
+classifiers = [
+  "Development Status :: 4 - Beta",
+  "Intended Audience :: Developers",
+  "Operating System :: OS Independent",
+  "Programming Language :: Python :: 3",
+  "Programming Language :: Python :: 3 :: Only",
+  "Programming Language :: Python :: 3.10",
+  "Programming Language :: Python :: 3.11",
+  "Programming Language :: Python :: 3.12",
+  "Programming Language :: Python :: 3.13",
+  "Topic :: Office/Business",
+  "Topic :: Software Development :: Libraries :: Python Modules",
+  "Typing :: Typed",
+]
+dependencies = ["httpx>=0.27", "pydantic>=2.5"]
+
+[project.urls]
+Homepage = "https://formfeed.dev"
+Documentation = "https://docs.formfeed.dev/api/sdks/python"
+Source = "https://github.com/formfeed-dev/formfeed/tree/main/packages/sdk-python"
+Issues = "https://github.com/formfeed-dev/formfeed/issues"
+Changelog = "https://docs.formfeed.dev/changelog"
+
+[tool.hatch.build.targets.wheel]
+packages = ["src/formfeed"]
+
+# the source archive carries what a rebuild and the tests need, not the workspace's project.json
+[tool.hatch.build.targets.sdist]
+include = ["src/formfeed", "tests", "README.md", "LICENSE", "pyproject.toml"]
+
+[tool.pytest.ini_options]
+testpaths = ["tests"]
+pythonpath = ["src"]

formfeed-0.1.0/src/formfeed/__init__.py

@@ -0,0 +1,33 @@
+"""Formfeed API client (spec 10 §1): sync and async, retries on 429/503, idempotency keys, typed errors."""
+
+from .client import AsyncFormfeed, Formfeed
+from .errors import FormfeedError
+from .models import (
+    Job,
+    Render,
+    RenderPage,
+    Template,
+    Usage,
+    TemplateVersion,
+    WebhookEndpoint,
+    WebhookEvent,
+)
+from .webhooks import parse_webhook_event, verify_webhook_signature
+
+__all__ = [
+    "AsyncFormfeed",
+    "Formfeed",
+    "FormfeedError",
+    "Job",
+    "Render",
+    "RenderPage",
+    "Template",
+    "Usage",
+    "TemplateVersion",
+    "WebhookEndpoint",
+    "WebhookEvent",
+    "parse_webhook_event",
+    "verify_webhook_signature",
+]
+
+__version__ = "0.1.0"

formfeed-0.1.0/src/formfeed/client.py

@@ -0,0 +1,552 @@
+"""Sync and async clients (httpx). Every behaviour mirrors ``@formfeed/sdk`` so the two SDKs stay in step."""
+
+from __future__ import annotations
+
+import asyncio
+import random
+import time
+import uuid
+from typing import Any, Generic, TypeVar
+
+import httpx
+
+from .errors import FormfeedError
+from .models import Job, Region, Render, RenderPage, Template, TemplatePage, TemplateVersion, Usage, WebhookEndpoint
+
+HOSTS: dict[str, str] = {"eu": "https://api-eu.formfeed.dev/v1", "us": "https://api-us.formfeed.dev/v1"}
+USER_AGENT = "formfeed-sdk-python/0.1"
+RETRY_STATUSES = (429, 503)
+
+T = TypeVar("T")
+
+
+def _backoff(attempt: int, retry_after: str | None) -> float:
+    """Seconds to wait: the server's Retry-After when present, else 0.5 s doubling, plus jitter, capped at 30 s."""
+    base = 0.5 * 2 ** (attempt - 1)
+    if retry_after:
+        try:
+            value = float(retry_after)
+            if value > 0:
+                base = value
+        except ValueError:
+            pass
+    return min(30.0, base + random.random() * 0.25)
+
+
+def _problem_error(res: httpx.Response) -> FormfeedError:
+    try:
+        problem = res.json() if res.content else {}
+    except ValueError:
+        problem = {}
+    if not isinstance(problem, dict):
+        problem = {}
+    return FormfeedError(
+        str(problem.get("code") or f"http_{res.status_code}"),
+        str(problem.get("detail") or problem.get("title") or f"HTTP {res.status_code}"),
+        res.status_code,
+        problem,
+        res.headers.get("x-request-id"),
+    )
+
+
+def _query(**params: Any) -> dict[str, Any]:
+    return {k: v for k, v in params.items() if v is not None and v != ""}
+
+
+class _Base(Generic[T]):
+    def __init__(
+        self,
+        api_key: str,
+        *,
+        region: Region = "eu",
+        base_url: str | None = None,
+        max_retries: int = 3,
+        timeout: float = 120.0,
+        transport: httpx.BaseTransport | httpx.AsyncBaseTransport | None = None,
+    ) -> None:
+        if not api_key:
+            raise FormfeedError("invalid_request", "api_key is required")
+        self.api_key = api_key
+        self.base_url = (base_url or HOSTS[region]).rstrip("/")
+        self.max_retries = max_retries
+        self.timeout = timeout
+        self._transport = transport
+
+    def _headers(self, body: Any, idempotency_key: str | None) -> dict[str, str]:
+        headers = {"authorization": f"Bearer {self.api_key}", "accept": "application/json", "user-agent": USER_AGENT}
+        if body is not None:
+            headers["content-type"] = "application/json"
+        if idempotency_key:
+            headers["idempotency-key"] = idempotency_key
+        return headers
+
+    @staticmethod
+    def _decode(res: httpx.Response) -> Any:
+        if res.status_code == 204 or not res.content:
+            return None
+        return res.json()
+
+
+class Formfeed(_Base[Any]):
+    """Synchronous client.
+
+    >>> client = Formfeed("ff_test_…")
+    >>> render = client.renders.create(template="invoice-de", data={"invoice": {...}})
+    >>> pdf = client.renders.download(render)
+    """
+
+    def __init__(self, api_key: str, **options: Any) -> None:
+        super().__init__(api_key, **options)
+        self._http = httpx.Client(timeout=self.timeout, transport=self._transport)  # type: ignore[arg-type]
+        self.renders = _Renders(self)
+        self.jobs = _Jobs(self)
+        self.webhooks = _Webhooks(self)
+        self.templates = _Templates(self)
+        self.account = _Account(self)
+
+    def close(self) -> None:
+        self._http.close()
+
+    def __enter__(self) -> "Formfeed":
+        return self
+
+    def __exit__(self, *exc: object) -> None:
+        self.close()
+
+    def request(self, method: str, path: str, body: Any = None, *, idempotency_key: str | None = None) -> Any:
+        """Raw request with auth, retries and problem mapping; for endpoints without a helper."""
+        url = f"{self.base_url}{path}"
+        headers = self._headers(body, idempotency_key)
+        attempt = 0
+        while True:
+            try:
+                res = self._http.request(method, url, json=body, headers=headers)
+            except httpx.HTTPError as e:
+                if attempt < self.max_retries:
+                    attempt += 1
+                    time.sleep(_backoff(attempt, None))
+                    continue
+                raise FormfeedError("network_error", str(e)) from e
+            if res.status_code in RETRY_STATUSES and attempt < self.max_retries:
+                attempt += 1
+                time.sleep(_backoff(attempt, res.headers.get("retry-after")))
+                continue
+            if res.is_error:
+                raise _problem_error(res)
+            return self._decode(res)
+
+    def download_url(self, url: str) -> bytes:
+        res = self._http.get(url)
+        if res.is_error:
+            raise FormfeedError("download_failed", f"download answered HTTP {res.status_code}", res.status_code)
+        return res.content
+
+
+class AsyncFormfeed(_Base[Any]):
+    """Asynchronous client with the same surface as :class:`Formfeed`; every method is awaitable."""
+
+    def __init__(self, api_key: str, **options: Any) -> None:
+        super().__init__(api_key, **options)
+        self._http = httpx.AsyncClient(timeout=self.timeout, transport=self._transport)  # type: ignore[arg-type]
+        self.renders = _AsyncRenders(self)
+        self.jobs = _AsyncJobs(self)
+        self.webhooks = _AsyncWebhooks(self)
+        self.templates = _AsyncTemplates(self)
+        self.account = _AsyncAccount(self)
+
+    async def aclose(self) -> None:
+        await self._http.aclose()
+
+    async def __aenter__(self) -> "AsyncFormfeed":
+        return self
+
+    async def __aexit__(self, *exc: object) -> None:
+        await self.aclose()
+
+    async def request(self, method: str, path: str, body: Any = None, *, idempotency_key: str | None = None) -> Any:
+        url = f"{self.base_url}{path}"
+        headers = self._headers(body, idempotency_key)
+        attempt = 0
+        while True:
+            try:
+                res = await self._http.request(method, url, json=body, headers=headers)
+            except httpx.HTTPError as e:
+                if attempt < self.max_retries:
+                    attempt += 1
+                    await asyncio.sleep(_backoff(attempt, None))
+                    continue
+                raise FormfeedError("network_error", str(e)) from e
+            if res.status_code in RETRY_STATUSES and attempt < self.max_retries:
+                attempt += 1
+                await asyncio.sleep(_backoff(attempt, res.headers.get("retry-after")))
+                continue
+            if res.is_error:
+                raise _problem_error(res)
+            return self._decode(res)
+
+    async def download_url(self, url: str) -> bytes:
+        res = await self._http.get(url)
+        if res.is_error:
+            raise FormfeedError("download_failed", f"download answered HTTP {res.status_code}", res.status_code)
+        return res.content
+
+
+# --- sync namespaces --------------------------------------------------------------------------
+
+
+def _render_body(template: str | None, html: str | None, url: str | None, data: dict[str, Any] | None, options: dict[str, Any]) -> dict[str, Any]:
+    body: dict[str, Any] = {k: v for k, v in options.items() if v is not None}
+    if template is not None:
+        body["template"] = template
+    if html is not None:
+        body["html"] = html
+    if url is not None:
+        body["url"] = url
+    if data is not None:
+        body["data"] = data
+    return body
+
+
+class _Renders:
+    def __init__(self, client: Formfeed) -> None:
+        self._c = client
+
+    def create(
+        self,
+        *,
+        template: str | None = None,
+        html: str | None = None,
+        url: str | None = None,
+        data: dict[str, Any] | None = None,
+        idempotency_key: str | None = None,
+        **options: Any,
+    ) -> Render:
+        """Renders a template, HTML or URL. Sync by default; ``mode="async"`` returns a queued render."""
+        body = _render_body(template, html, url, data, options)
+        return Render.model_validate(self._c.request("POST", "/renders", body, idempotency_key=idempotency_key or str(uuid.uuid4())))
+
+    def get(self, render_id: str) -> Render:
+        return Render.model_validate(self._c.request("GET", f"/renders/{render_id}"))
+
+    def wait_for(self, render_id: str, *, timeout: float = 120.0, interval: float = 1.0) -> Render:
+        """Polls until the render succeeded or failed."""
+        deadline = time.monotonic() + timeout
+        while True:
+            render = self.get(render_id)
+            if render.finished:
+                return render
+            if time.monotonic() + interval > deadline:
+                raise FormfeedError("timeout", f"render {render_id} did not finish within the wait time")
+            time.sleep(interval)
+
+    def download(self, render: Render | str) -> bytes:
+        target = self.get(render) if isinstance(render, str) else render
+        if not target.download_url:
+            raise FormfeedError("not_ready", f"render {target.id} has no output ({target.status})")
+        return self._c.download_url(target.download_url)
+
+    def list(
+        self,
+        *,
+        template: str | None = None,
+        status: str | None = None,
+        environment: str | None = None,
+        since: str | None = None,
+        until: str | None = None,
+        limit: int | None = None,
+        cursor: str | None = None,
+    ) -> RenderPage:
+        """Page of renders, newest first."""
+        params = httpx.QueryParams(_query(template=template, status=status, environment=environment, since=since, until=until, limit=limit, cursor=cursor))
+        return RenderPage.model_validate(self._c.request("GET", f"/renders{'?' + str(params) if params else ''}"))
+
+    def all(self, **filters: Any) -> list[Render]:
+        """Every render matching the filters, following the cursor."""
+        out: list[Render] = []
+        cursor: str | None = None
+        while True:
+            page = self.list(cursor=cursor, **filters)
+            out.extend(page.data)
+            cursor = page.next_cursor
+            if not cursor:
+                return out
+
+    def delete_outputs(self, render_id: str) -> None:
+        """Removes the stored files of a render before they expire (needs the file:delete scope)."""
+        self._c.request("DELETE", f"/renders/{render_id}/outputs")
+
+    def batch(self, items: list[dict[str, Any]], *, template: str | None = None, idempotency_key: str | None = None, **options: Any) -> Job:
+        body: dict[str, Any] = {"items": items, **{k: v for k, v in options.items() if v is not None}}
+        if template is not None:
+            body["template"] = template
+        return Job.model_validate(self._c.request("POST", "/renders/batch", body, idempotency_key=idempotency_key or str(uuid.uuid4())))
+
+
+class _Jobs:
+    def __init__(self, client: Formfeed) -> None:
+        self._c = client
+
+    def get(self, job_id: str) -> Job:
+        return Job.model_validate(self._c.request("GET", f"/jobs/{job_id}"))
+
+    def wait_for(self, job_id: str, *, timeout: float = 600.0, interval: float = 2.0) -> Job:
+        deadline = time.monotonic() + timeout
+        while True:
+            job = self.get(job_id)
+            if job.finished:
+                return job
+            if time.monotonic() + interval > deadline:
+                raise FormfeedError("timeout", f"job {job_id} did not finish within the wait time")
+            time.sleep(interval)
+
+
+class _Webhooks:
+    def __init__(self, client: Formfeed) -> None:
+        self._c = client
+
+    def list(self) -> list[WebhookEndpoint]:
+        return [WebhookEndpoint.model_validate(e) for e in self._c.request("GET", "/webhooks")["data"]]
+
+    def create(self, url: str, *, events: list[str] | None = None, description: str | None = None) -> WebhookEndpoint:
+        return WebhookEndpoint.model_validate(self._c.request("POST", "/webhooks", _query(url=url, events=events, description=description)))
+
+    def update(self, endpoint_id: str, **patch: Any) -> WebhookEndpoint:
+        return WebhookEndpoint.model_validate(self._c.request("PUT", f"/webhooks/{endpoint_id}", patch))
+
+    def delete(self, endpoint_id: str) -> None:
+        self._c.request("DELETE", f"/webhooks/{endpoint_id}")
+
+    def test(self, endpoint_id: str) -> dict[str, Any]:
+        return self._c.request("POST", f"/webhooks/{endpoint_id}/test")
+
+
+class _Templates:
+    def __init__(self, client: Formfeed) -> None:
+        self._c = client
+
+    def list(self, *, kind: str | None = None, engine: str | None = None, tag: str | None = None, q: str | None = None, limit: int | None = None, cursor: str | None = None) -> TemplatePage:
+        params = httpx.QueryParams(_query(kind=kind, engine=engine, tag=tag, q=q, limit=limit, cursor=cursor))
+        return TemplatePage.model_validate(self._c.request("GET", f"/templates{'?' + str(params) if params else ''}"))
+
+    def all(self, **filters: Any) -> list[Template]:
+        """Every template of the workspace, following the cursor."""
+        out: list[Template] = []
+        cursor: str | None = None
+        while True:
+            page = self.list(cursor=cursor, **filters)
+            out.extend(page.data)
+            cursor = page.next_cursor
+            if not cursor:
+                return out
+
+    def get(self, id_or_slug: str) -> Template:
+        return Template.model_validate(self._c.request("GET", f"/templates/{id_or_slug}"))
+
+    def create(self, **template: Any) -> Template:
+        return Template.model_validate(self._c.request("POST", "/templates", template))
+
+    def update(self, id_or_slug: str, **patch: Any) -> Template:
+        return Template.model_validate(self._c.request("PUT", f"/templates/{id_or_slug}", patch))
+
+    def archive(self, id_or_slug: str) -> None:
+        self._c.request("DELETE", f"/templates/{id_or_slug}")
+
+    def version(self, id_or_slug: str, which: str | int = "published") -> TemplateVersion:
+        """``which``: ``published``, ``latest`` or a version number; carries the files."""
+        return TemplateVersion.model_validate(self._c.request("GET", f"/templates/{id_or_slug}/versions/{which}"))
+
+    def versions(self, id_or_slug: str) -> list[TemplateVersion]:
+        return [TemplateVersion.model_validate(v) for v in self._c.request("GET", f"/templates/{id_or_slug}/versions")["data"]]
+
+    def create_version(self, id_or_slug: str, **version: Any) -> TemplateVersion:
+        return TemplateVersion.model_validate(self._c.request("POST", f"/templates/{id_or_slug}/versions", version))
+
+    def publish(self, id_or_slug: str, number: int) -> TemplateVersion:
+        return TemplateVersion.model_validate(self._c.request("POST", f"/templates/{id_or_slug}/versions/{number}/publish"))
+
+    def schema(self, id_or_slug: str) -> dict[str, Any]:
+        return self._c.request("GET", f"/templates/{id_or_slug}/schema")
+
+
+class _Account:
+    def __init__(self, client: Formfeed) -> None:
+        self._c = client
+
+    def get(self) -> dict[str, Any]:
+        return self._c.request("GET", "/account")
+
+    def usage(self, period: str = "current") -> Usage:
+        """Units of the current period, or of ``YYYY-MM``, with a daily series and per template."""
+        return Usage.model_validate(self._c.request("GET", f"/usage?period={period}"))
+
+
+# --- async namespaces -------------------------------------------------------------------------
+
+
+class _AsyncRenders:
+    def __init__(self, client: AsyncFormfeed) -> None:
+        self._c = client
+
+    async def create(
+        self,
+        *,
+        template: str | None = None,
+        html: str | None = None,
+        url: str | None = None,
+        data: dict[str, Any] | None = None,
+        idempotency_key: str | None = None,
+        **options: Any,
+    ) -> Render:
+        body = _render_body(template, html, url, data, options)
+        return Render.model_validate(await self._c.request("POST", "/renders", body, idempotency_key=idempotency_key or str(uuid.uuid4())))
+
+    async def get(self, render_id: str) -> Render:
+        return Render.model_validate(await self._c.request("GET", f"/renders/{render_id}"))
+
+    async def wait_for(self, render_id: str, *, timeout: float = 120.0, interval: float = 1.0) -> Render:
+        deadline = time.monotonic() + timeout
+        while True:
+            render = await self.get(render_id)
+            if render.finished:
+                return render
+            if time.monotonic() + interval > deadline:
+                raise FormfeedError("timeout", f"render {render_id} did not finish within the wait time")
+            await asyncio.sleep(interval)
+
+    async def download(self, render: Render | str) -> bytes:
+        target = await self.get(render) if isinstance(render, str) else render
+        if not target.download_url:
+            raise FormfeedError("not_ready", f"render {target.id} has no output ({target.status})")
+        return await self._c.download_url(target.download_url)
+
+    async def list(
+        self,
+        *,
+        template: str | None = None,
+        status: str | None = None,
+        environment: str | None = None,
+        since: str | None = None,
+        until: str | None = None,
+        limit: int | None = None,
+        cursor: str | None = None,
+    ) -> RenderPage:
+        """Page of renders, newest first."""
+        params = httpx.QueryParams(_query(template=template, status=status, environment=environment, since=since, until=until, limit=limit, cursor=cursor))
+        return RenderPage.model_validate(await self._c.request("GET", f"/renders{'?' + str(params) if params else ''}"))
+
+    async def all(self, **filters: Any) -> list[Render]:
+        """Every render matching the filters, following the cursor."""
+        out: list[Render] = []
+        cursor: str | None = None
+        while True:
+            page = await self.list(cursor=cursor, **filters)
+            out.extend(page.data)
+            cursor = page.next_cursor
+            if not cursor:
+                return out
+
+    async def delete_outputs(self, render_id: str) -> None:
+        """Removes the stored files of a render before they expire (needs the file:delete scope)."""
+        await self._c.request("DELETE", f"/renders/{render_id}/outputs")
+
+    async def batch(self, items: list[dict[str, Any]], *, template: str | None = None, idempotency_key: str | None = None, **options: Any) -> Job:
+        body: dict[str, Any] = {"items": items, **{k: v for k, v in options.items() if v is not None}}
+        if template is not None:
+            body["template"] = template
+        return Job.model_validate(await self._c.request("POST", "/renders/batch", body, idempotency_key=idempotency_key or str(uuid.uuid4())))
+
+
+class _AsyncJobs:
+    def __init__(self, client: AsyncFormfeed) -> None:
+        self._c = client
+
+    async def get(self, job_id: str) -> Job:
+        return Job.model_validate(await self._c.request("GET", f"/jobs/{job_id}"))
+
+    async def wait_for(self, job_id: str, *, timeout: float = 600.0, interval: float = 2.0) -> Job:
+        deadline = time.monotonic() + timeout
+        while True:
+            job = await self.get(job_id)
+            if job.finished:
+                return job
+            if time.monotonic() + interval > deadline:
+                raise FormfeedError("timeout", f"job {job_id} did not finish within the wait time")
+            await asyncio.sleep(interval)
+
+
+class _AsyncWebhooks:
+    def __init__(self, client: AsyncFormfeed) -> None:
+        self._c = client
+
+    async def list(self) -> list[WebhookEndpoint]:
+        return [WebhookEndpoint.model_validate(e) for e in (await self._c.request("GET", "/webhooks"))["data"]]
+
+    async def create(self, url: str, *, events: list[str] | None = None, description: str | None = None) -> WebhookEndpoint:
+        return WebhookEndpoint.model_validate(await self._c.request("POST", "/webhooks", _query(url=url, events=events, description=description)))
+
+    async def update(self, endpoint_id: str, **patch: Any) -> WebhookEndpoint:
+        return WebhookEndpoint.model_validate(await self._c.request("PUT", f"/webhooks/{endpoint_id}", patch))
+
+    async def delete(self, endpoint_id: str) -> None:
+        await self._c.request("DELETE", f"/webhooks/{endpoint_id}")
+
+    async def test(self, endpoint_id: str) -> dict[str, Any]:
+        return await self._c.request("POST", f"/webhooks/{endpoint_id}/test")
+
+
+class _AsyncTemplates:
+    def __init__(self, client: AsyncFormfeed) -> None:
+        self._c = client
+
+    async def list(self, *, kind: str | None = None, engine: str | None = None, tag: str | None = None, q: str | None = None, limit: int | None = None, cursor: str | None = None) -> TemplatePage:
+        params = httpx.QueryParams(_query(kind=kind, engine=engine, tag=tag, q=q, limit=limit, cursor=cursor))
+        return TemplatePage.model_validate(await self._c.request("GET", f"/templates{'?' + str(params) if params else ''}"))
+
+    async def all(self, **filters: Any) -> list[Template]:
+        out: list[Template] = []
+        cursor: str | None = None
+        while True:
+            page = await self.list(cursor=cursor, **filters)
+            out.extend(page.data)
+            cursor = page.next_cursor
+            if not cursor:
+                return out
+
+    async def get(self, id_or_slug: str) -> Template:
+        return Template.model_validate(await self._c.request("GET", f"/templates/{id_or_slug}"))
+
+    async def create(self, **template: Any) -> Template:
+        return Template.model_validate(await self._c.request("POST", "/templates", template))
+
+    async def update(self, id_or_slug: str, **patch: Any) -> Template:
+        return Template.model_validate(await self._c.request("PUT", f"/templates/{id_or_slug}", patch))
+
+    async def archive(self, id_or_slug: str) -> None:
+        await self._c.request("DELETE", f"/templates/{id_or_slug}")
+
+    async def version(self, id_or_slug: str, which: str | int = "published") -> TemplateVersion:
+        return TemplateVersion.model_validate(await self._c.request("GET", f"/templates/{id_or_slug}/versions/{which}"))
+
+    async def versions(self, id_or_slug: str) -> list[TemplateVersion]:
+        return [TemplateVersion.model_validate(v) for v in (await self._c.request("GET", f"/templates/{id_or_slug}/versions"))["data"]]
+
+    async def create_version(self, id_or_slug: str, **version: Any) -> TemplateVersion:
+        return TemplateVersion.model_validate(await self._c.request("POST", f"/templates/{id_or_slug}/versions", version))
+
+    async def publish(self, id_or_slug: str, number: int) -> TemplateVersion:
+        return TemplateVersion.model_validate(await self._c.request("POST", f"/templates/{id_or_slug}/versions/{number}/publish"))
+
+    async def schema(self, id_or_slug: str) -> dict[str, Any]:
+        return await self._c.request("GET", f"/templates/{id_or_slug}/schema")
+
+
+class _AsyncAccount:
+    def __init__(self, client: AsyncFormfeed) -> None:
+        self._c = client
+
+    async def get(self) -> dict[str, Any]:
+        return await self._c.request("GET", "/account")
+
+    async def usage(self, period: str = "current") -> Usage:
+        """Units of the current period, or of ``YYYY-MM``, with a daily series and per template."""
+        return Usage.model_validate(await self._c.request("GET", f"/usage?period={period}"))

formfeed-0.1.0/src/formfeed/errors.py

@@ -0,0 +1,30 @@
+from __future__ import annotations
+
+from typing import Any
+
+
+class FormfeedError(Exception):
+    """An API problem (RFC 9457) or a transport failure.
+
+    ``code`` is the problem code (``quota_exceeded``, ``template_not_found`` …) or ``network_error`` /
+    ``timeout`` / ``not_ready`` for client-side failures; ``status`` is the HTTP status, 0 when none.
+    """
+
+    def __init__(
+        self,
+        code: str,
+        message: str,
+        status: int = 0,
+        problem: dict[str, Any] | None = None,
+        request_id: str | None = None,
+    ) -> None:
+        super().__init__(message)
+        self.code = code
+        self.message = message
+        self.status = status
+        self.problem = problem
+        self.request_id = request_id
+
+    def __str__(self) -> str:  # pragma: no cover - formatting
+        suffix = f" (request {self.request_id})" if self.request_id else ""
+        return f"{self.code}: {self.message}{suffix}"

formfeed-0.1.0/src/formfeed/models.py

@@ -0,0 +1,150 @@
+"""Response models. Extra fields the API adds later are kept (``extra="allow"``) so clients never break on additions."""
+
+from __future__ import annotations
+
+from typing import Any, Literal
+
+from pydantic import BaseModel, ConfigDict
+
+Region = Literal["eu", "us"]
+Engine = Literal["jinja2", "liquid", "handlebars"]
+OutputFormat = Literal["pdf", "png", "jpg", "webp"]
+RenderStatus = Literal["queued", "rendering", "succeeded", "failed"]
+
+
+class _Model(BaseModel):
+    model_config = ConfigDict(extra="allow", populate_by_name=True)
+
+
+class RenderTemplateRef(_Model):
+    id: str
+    slug: str
+    version: int
+
+
+class Render(_Model):
+    id: str
+    status: RenderStatus
+    output: str | None = None
+    download_url: str | None = None
+    expires_at: str | None = None
+    bytes: int | None = None
+    page_count: int | None = None
+    units: float = 0
+    region: str | None = None
+    environment: str | None = None
+    template: RenderTemplateRef | None = None
+    engine_version: str | None = None
+    template_checksum: str | None = None
+    output_sha256: str | None = None
+    deduplicated: bool = False
+    timings: dict[str, float] | None = None
+    error: dict[str, Any] | None = None
+    meta: dict[str, Any] = {}
+    created_at: str | None = None
+    completed_at: str | None = None
+
+    @property
+    def finished(self) -> bool:
+        return self.status in ("succeeded", "failed")
+
+
+class Job(_Model):
+    id: str
+    type: str = "batch"
+    status: str
+    total: int = 0
+    succeeded: int = 0
+    failed: int = 0
+    zip_url: str | None = None
+    zip_expires_at: str | None = None
+    items: list[Render] = []
+    meta: dict[str, Any] = {}
+    created_at: str | None = None
+    completed_at: str | None = None
+
+    @property
+    def finished(self) -> bool:
+        return self.status not in ("queued", "processing")
+
+
+class WebhookEndpoint(_Model):
+    id: str
+    url: str
+    events: list[str] = []
+    enabled: bool = True
+    description: str | None = None
+    consecutive_failures: int = 0
+    secret: str | None = None
+    created_at: str | None = None
+    updated_at: str | None = None
+
+
+class Template(_Model):
+    id: str
+    slug: str
+    name: str
+    description: str | None = None
+    kind: str
+    engine: str
+    tags: list[str] = []
+    published_version: int | None = None
+    latest_version: int = 0
+    created_at: str | None = None
+    updated_at: str | None = None
+
+
+class TemplateVersion(_Model):
+    id: str
+    number: int
+    status: str
+    checksum: str
+    change_note: str | None = None
+    created_at: str | None = None
+    published_at: str | None = None
+    html: str | None = None
+    css: str | None = None
+    head: str | None = None
+    settings: dict[str, Any] | None = None
+    sample_data: dict[str, Any] | None = None
+    data_schema: dict[str, Any] | None = None
+    i18n: dict[str, Any] | None = None
+
+
+class UsageDay(_Model):
+    date: str
+    units: float = 0
+    renders: int = 0
+
+
+class UsageTemplate(_Model):
+    template: str
+    units: float = 0
+
+
+class Usage(_Model):
+    period: str
+    included: float = 0
+    used: float = 0
+    overage_used: float = 0
+    overage_balance: float = 0
+    daily: list[UsageDay] = []
+    by_template: list[UsageTemplate] = []
+
+
+class RenderPage(_Model):
+    data: list[Render]
+    next_cursor: str | None = None
+
+
+class TemplatePage(_Model):
+    data: list[Template]
+    next_cursor: str | None = None
+
+
+class WebhookEvent(_Model):
+    id: str
+    type: str
+    created_at: str
+    workspace_id: str | None = None
+    data: Any = None

formfeed-0.1.0/src/formfeed/webhooks.py

@@ -0,0 +1,59 @@
+"""Webhook signature verification (spec 04 §2.4): ``Webhook-Signature: t=<unix>,v1=<hex hmac-sha256(secret, t + "." + body)>``."""
+
+from __future__ import annotations
+
+import hashlib
+import hmac
+import json
+import re
+import time
+from typing import Any
+
+from .models import WebhookEvent
+
+_HEX64 = re.compile(r"^[0-9a-f]{64}$")
+
+
+def verify_webhook_signature(
+    secret: str,
+    signature_header: str | None,
+    raw_body: bytes | str,
+    *,
+    tolerance_seconds: int = 300,
+    now: int | None = None,
+) -> bool:
+    """True when the header matches the raw body. Pass the body exactly as received: the signature covers the bytes on the wire."""
+    if not signature_header or not secret:
+        return False
+    parts: dict[str, str] = {}
+    for kv in signature_header.split(","):
+        key, _, value = kv.strip().partition("=")
+        parts[key] = value
+    try:
+        t = int(parts.get("t", ""))
+    except ValueError:
+        return False
+    v1 = parts.get("v1", "").lower()
+    if not _HEX64.match(v1):
+        return False
+    current = now if now is not None else int(time.time())
+    if abs(current - t) > tolerance_seconds:
+        return False
+    body = raw_body.encode("utf-8") if isinstance(raw_body, str) else raw_body
+    expected = hmac.new(secret.encode("utf-8"), f"{t}.".encode("utf-8") + body, hashlib.sha256).hexdigest()
+    return hmac.compare_digest(expected, v1)
+
+
+def parse_webhook_event(
+    secret: str,
+    signature_header: str | None,
+    raw_body: bytes | str,
+    *,
+    tolerance_seconds: int = 300,
+    now: int | None = None,
+) -> WebhookEvent:
+    """Parses a verified event body; raises ``ValueError`` when the signature does not match."""
+    if not verify_webhook_signature(secret, signature_header, raw_body, tolerance_seconds=tolerance_seconds, now=now):
+        raise ValueError("invalid webhook signature")
+    payload: dict[str, Any] = json.loads(raw_body)
+    return WebhookEvent.model_validate(payload)

formfeed-0.1.0/tests/test_client.py

@@ -0,0 +1,155 @@
+import hashlib
+import hmac
+import json
+import time
+
+import httpx
+import pytest
+
+from formfeed import AsyncFormfeed, Formfeed, FormfeedError, parse_webhook_event, verify_webhook_signature
+
+RENDER = {"id": "rnd_1", "status": "succeeded", "download_url": "https://cdn.test/o/x.pdf?exp=1&sig=2", "page_count": 1, "units": 1}
+
+
+def _json(body, status=200, headers=None):
+    return httpx.Response(status, json=body, headers=headers or {})
+
+
+class Recorder:
+    def __init__(self, responder):
+        self.calls: list[httpx.Request] = []
+        self._responder = responder
+
+    def handler(self, request: httpx.Request) -> httpx.Response:
+        self.calls.append(request)
+        return self._responder(request, len(self.calls))
+
+
+def sync_client(responder, **options) -> tuple[Formfeed, Recorder]:
+    rec = Recorder(responder)
+    return Formfeed("ff_test_k", transport=httpx.MockTransport(rec.handler), **options), rec
+
+
+def test_render_sends_auth_idempotency_and_maps_the_response():
+    client, rec = sync_client(lambda req, n: _json(RENDER, 201))
+    render = client.renders.create(template="invoice", data={"a": 1}, output="pdf")
+    assert render.id == "rnd_1" and render.finished
+    req = rec.calls[0]
+    assert req.url == "https://api-eu.formfeed.dev/v1/renders"
+    assert req.headers["authorization"] == "Bearer ff_test_k"
+    assert len(req.headers["idempotency-key"]) > 10
+    assert json.loads(req.content) == {"template": "invoice", "data": {"a": 1}, "output": "pdf"}
+
+
+def test_retries_429_with_retry_after_then_succeeds(monkeypatch):
+    monkeypatch.setattr("formfeed.client.time.sleep", lambda s: None)
+    client, rec = sync_client(lambda req, n: _json({"code": "rate_limited"}, 429, {"retry-after": "1"}) if n < 3 else _json(RENDER))
+    assert client.renders.get("rnd_1").status == "succeeded"
+    assert len(rec.calls) == 3
+
+
+def test_problems_become_typed_errors():
+    client, _ = sync_client(lambda req, n: _json({"code": "quota_exceeded", "detail": "Monthly units used up", "status": 402}, 402, {"x-request-id": "req_9"}))
+    with pytest.raises(FormfeedError) as e:
+        client.renders.create(html="<p>x</p>")
+    assert e.value.code == "quota_exceeded"
+    assert e.value.status == 402
+    assert e.value.request_id == "req_9"
+    assert "Monthly units" in str(e.value)
+
+
+def test_wait_for_and_download(monkeypatch):
+    monkeypatch.setattr("formfeed.client.time.sleep", lambda s: None)
+    states = iter(["queued", "rendering", "succeeded"])
+
+    def responder(req, n):
+        if req.url.host == "cdn.test":
+            return httpx.Response(200, content=b"%PDF")
+        return _json({**RENDER, "status": next(states)})
+
+    client, _ = sync_client(responder)
+    render = client.renders.wait_for("rnd_1", interval=0)
+    assert render.status == "succeeded"
+    assert client.renders.download(render) == b"%PDF"
+
+
+def test_usage_reads_a_period():
+    client, rec = sync_client(
+        lambda req, n: _json(
+            {"period": "2026-09", "included": 15000, "used": 120, "overage_used": 0, "overage_balance": 0,
+             "daily": [{"date": "2026-09-07", "units": 3, "renders": 2}], "by_template": [{"template": "invoice", "units": 3}]}
+        )
+    )
+    usage = client.account.usage("2026-08")
+    assert usage.period == "2026-09"
+    assert usage.daily[0].renders == 2
+    assert usage.by_template[0].template == "invoice"
+    assert rec.calls[0].url.params.get("period") == "2026-08"
+
+
+def test_renders_list_follows_the_cursor_and_deletes_outputs():
+    def responder(req, n):
+        if req.method == "DELETE":
+            return httpx.Response(204)
+        cursor = req.url.params.get("cursor")
+        return _json({"data": [RENDER], "next_cursor": None if cursor else "c1"})
+
+    client, rec = sync_client(responder)
+    page = client.renders.list(status="succeeded", limit=1)
+    assert len(page.data) == 1 and page.next_cursor == "c1"
+    assert rec.calls[0].url.params.get("status") == "succeeded"
+
+    every = client.renders.all(template="invoice")
+    assert len(every) == 2
+    assert rec.calls[-1].url.params.get("cursor") == "c1"
+
+    client.renders.delete_outputs("rnd_1")
+    assert rec.calls[-1].method == "DELETE"
+    assert rec.calls[-1].url.path == "/v1/renders/rnd_1/outputs"
+
+
+def test_templates_follow_the_cursor_and_address_versions():
+    def responder(req, n):
+        if req.url.path == "/v1/templates":
+            cursor = req.url.params.get("cursor")
+            return _json({"data": [{"id": "tpl_1", "slug": "a", "name": "A", "kind": "pdf", "engine": "jinja2"}], "next_cursor": None if cursor else "c1"})
+        if req.url.path.endswith("/versions/latest"):
+            return _json({"id": "v", "number": 3, "status": "draft", "checksum": "x", "html": "<p>"})
+        return _json({"id": "v", "number": 4, "status": "published", "checksum": "y"})
+
+    client, rec = sync_client(responder)
+    assert len(client.templates.all(kind="pdf")) == 2
+    assert rec.calls[0].url.params["kind"] == "pdf"
+    assert rec.calls[1].url.params["cursor"] == "c1"
+    assert client.templates.version("a", "latest").html == "<p>"
+    assert client.templates.publish("a", 4).status == "published"
+    assert rec.calls[-1].url.path == "/v1/templates/a/versions/4/publish"
+
+
+def test_async_client_has_the_same_surface():
+    import asyncio
+
+    rec = Recorder(lambda req, n: _json(RENDER, 201))
+
+    async def scenario():
+        async with AsyncFormfeed("ff_test_k", transport=httpx.MockTransport(rec.handler), region="us") as client:
+            return await client.renders.create(html="<p>x</p>")
+
+    render = asyncio.run(scenario())
+    assert render.id == "rnd_1"
+    assert rec.calls[0].url.host == "api-us.formfeed.dev"
+
+
+def test_webhook_signature_round_trip():
+    secret = "whsec_test"
+    body = b'{"id":"evt_1","type":"render.completed","created_at":"2026-09-09T00:00:00Z","workspace_id":null,"data":{"id":"rnd_1"}}'
+    t = int(time.time())
+    sig = hmac.new(secret.encode(), f"{t}.".encode() + body, hashlib.sha256).hexdigest()
+    header = f"t={t},v1={sig}"
+    assert verify_webhook_signature(secret, header, body)
+    assert not verify_webhook_signature(secret, header, body + b" ")
+    assert not verify_webhook_signature(secret, header, body, now=t + 1000)
+    event = parse_webhook_event(secret, header, body)
+    assert event.type == "render.completed" and event.data == {"id": "rnd_1"}
+    with pytest.raises(ValueError):
+        parse_webhook_event("other", header, body)