ironfang-render 1.0.0__tar.gz

ironfang_render-1.0.0/PKG-INFO

@@ -0,0 +1,103 @@
+Metadata-Version: 2.4
+Name: ironfang-render
+Version: 1.0.0
+Summary: Ironfang Render API client: screenshots, PDFs, QR codes, template images, clips and site previews from a URL or HTML.
+Author: Ironfang Ltd
+License-Expression: MIT
+Project-URL: Homepage, https://ironfang.com/render
+Project-URL: Documentation, https://ironfang.com/render/docs
+Keywords: screenshot,pdf,qr,html-to-image,ironfang
+Classifier: Programming Language :: Python :: 3
+Classifier: Programming Language :: Python :: 3 :: Only
+Classifier: Operating System :: OS Independent
+Classifier: Topic :: Internet :: WWW/HTTP
+Requires-Python: >=3.10
+Description-Content-Type: text/markdown
+
+# ironfang-render
+
+The official Python client for the [Ironfang Render](https://ironfang.com/render)
+API: screenshots, PDFs, QR codes, template images, clips and site previews
+from a URL or from HTML you send. No dependencies; Python 3.10 and later.
+
+Formerly `ironfang-renderwolf`. `import ironfang_renderwolf` and the old
+`Renderwolf` and `RenderwolfError` names still work with a deprecation
+warning, and webhooks still carry the `Renderwolf-*` headers.
+
+```sh
+pip install ironfang-render
+```
+
+```python
+import os
+from ironfang_render import IronfangRender
+
+with IronfangRender(api_key=os.environ["IRONFANG_API_KEY"]) as rw:
+    shot = rw.screenshot(url="https://example.com", full_page=True)
+    shot.save("page.png")
+    print(shot.credits, shot.render_ms, shot.request_id)
+```
+
+Every render returns the bytes plus what the API reports about them: content
+type, credits charged (zero on a cache hit), render time and the request id
+to quote to support. Long outputs stream: `save()` and `iter_bytes()` never
+hold a whole clip in memory.
+
+## Change the page before capture
+
+```python
+rw.screenshot(
+    html="<div class='chat-widget'>Chat</div><details id='details'><summary id='show-more'>Pricing</summary><p>Expanded pricing</p></details>",
+    css=".chat-widget { display: none !important; }",
+    script="document.querySelector('#show-more').textContent = 'Show pricing';",
+    actions=[
+        {"type": "click", "selector": "#show-more"},
+        {"type": "wait_for_selector", "selector": "#details[open]"},
+    ],
+).save("expanded.png")
+```
+
+The same options work with `rw.pdf()` and URL input. After normal load/waits,
+Ironfang Render applies CSS, awaits the script, then executes actions in order
+before settling and capture. JavaScript runs in the target page context as an
+async function body; use `await` or return a promise for asynchronous work. It
+has a five-second limit (or the remaining render timeout, if shorter).
+
+CSS is limited to 64 KiB of UTF-8, script to 16 KiB, and actions to 20. Actions
+are `click`, `hover`, `wait_for_selector` (presence), and `delay` with
+`duration_ms`; combined delays may total at most 10,000 ms. Selectors are limited
+to 1,024 UTF-8 bytes and share the render timeout. Invalid input returns
+`bad_request`; script/action execution errors return sanitized `render_failed`
+messages. A screenshot cache hit does not re-execute controls; use `no_cache`
+for fresh execution. [Full reference](https://ironfang.com/render/docs#page-controls).
+
+## Durable jobs
+
+```python
+job = rw.submit_job("pdf", {"html": invoice_html, "paper_format": "a4"}, idempotency_key=f"invoice-{invoice.id}")
+done = rw.wait_for_job(job["id"])
+if done["status"] == "succeeded":
+    rw.job_result(job["id"]).save(f"invoice-{invoice.id}.pdf")
+```
+
+## Verifying a webhook
+
+Run the check over the raw request body, before parsing it.
+
+```python
+from ironfang_render import verify_webhook
+
+ok = verify_webhook(
+    secret=os.environ["RENDER_WEBHOOK_SECRET"],
+    timestamp=request.headers["Renderwolf-Timestamp"],
+    signature=request.headers["Renderwolf-Signature"],
+    payload=request.get_data(),
+)
+```
+
+## Errors
+
+Failures raise `IronfangRenderError` with `status`, the API's `code`
+(`quota_exhausted`, `render_failed`, ...) and `request_id`. Synchronous
+renders are never retried by the client: a render that timed out may already
+have been charged, and retrying it blind doubles the bill.

ironfang_render-1.0.0/README.md

@@ -0,0 +1,87 @@
+# ironfang-render
+
+The official Python client for the [Ironfang Render](https://ironfang.com/render)
+API: screenshots, PDFs, QR codes, template images, clips and site previews
+from a URL or from HTML you send. No dependencies; Python 3.10 and later.
+
+Formerly `ironfang-renderwolf`. `import ironfang_renderwolf` and the old
+`Renderwolf` and `RenderwolfError` names still work with a deprecation
+warning, and webhooks still carry the `Renderwolf-*` headers.
+
+```sh
+pip install ironfang-render
+```
+
+```python
+import os
+from ironfang_render import IronfangRender
+
+with IronfangRender(api_key=os.environ["IRONFANG_API_KEY"]) as rw:
+    shot = rw.screenshot(url="https://example.com", full_page=True)
+    shot.save("page.png")
+    print(shot.credits, shot.render_ms, shot.request_id)
+```
+
+Every render returns the bytes plus what the API reports about them: content
+type, credits charged (zero on a cache hit), render time and the request id
+to quote to support. Long outputs stream: `save()` and `iter_bytes()` never
+hold a whole clip in memory.
+
+## Change the page before capture
+
+```python
+rw.screenshot(
+    html="<div class='chat-widget'>Chat</div><details id='details'><summary id='show-more'>Pricing</summary><p>Expanded pricing</p></details>",
+    css=".chat-widget { display: none !important; }",
+    script="document.querySelector('#show-more').textContent = 'Show pricing';",
+    actions=[
+        {"type": "click", "selector": "#show-more"},
+        {"type": "wait_for_selector", "selector": "#details[open]"},
+    ],
+).save("expanded.png")
+```
+
+The same options work with `rw.pdf()` and URL input. After normal load/waits,
+Ironfang Render applies CSS, awaits the script, then executes actions in order
+before settling and capture. JavaScript runs in the target page context as an
+async function body; use `await` or return a promise for asynchronous work. It
+has a five-second limit (or the remaining render timeout, if shorter).
+
+CSS is limited to 64 KiB of UTF-8, script to 16 KiB, and actions to 20. Actions
+are `click`, `hover`, `wait_for_selector` (presence), and `delay` with
+`duration_ms`; combined delays may total at most 10,000 ms. Selectors are limited
+to 1,024 UTF-8 bytes and share the render timeout. Invalid input returns
+`bad_request`; script/action execution errors return sanitized `render_failed`
+messages. A screenshot cache hit does not re-execute controls; use `no_cache`
+for fresh execution. [Full reference](https://ironfang.com/render/docs#page-controls).
+
+## Durable jobs
+
+```python
+job = rw.submit_job("pdf", {"html": invoice_html, "paper_format": "a4"}, idempotency_key=f"invoice-{invoice.id}")
+done = rw.wait_for_job(job["id"])
+if done["status"] == "succeeded":
+    rw.job_result(job["id"]).save(f"invoice-{invoice.id}.pdf")
+```
+
+## Verifying a webhook
+
+Run the check over the raw request body, before parsing it.
+
+```python
+from ironfang_render import verify_webhook
+
+ok = verify_webhook(
+    secret=os.environ["RENDER_WEBHOOK_SECRET"],
+    timestamp=request.headers["Renderwolf-Timestamp"],
+    signature=request.headers["Renderwolf-Signature"],
+    payload=request.get_data(),
+)
+```
+
+## Errors
+
+Failures raise `IronfangRenderError` with `status`, the API's `code`
+(`quota_exhausted`, `render_failed`, ...) and `request_id`. Synchronous
+renders are never retried by the client: a render that timed out may already
+have been charged, and retrying it blind doubles the bill.

ironfang_render-1.0.0/pyproject.toml

@@ -0,0 +1,30 @@
+[build-system]
+requires = ["setuptools>=69"]
+build-backend = "setuptools.build_meta"
+
+[project]
+name = "ironfang-render"
+version = "1.0.0"
+description = "Ironfang Render API client: screenshots, PDFs, QR codes, template images, clips and site previews from a URL or HTML."
+readme = "README.md"
+license = "MIT"
+requires-python = ">=3.10"
+authors = [{ name = "Ironfang Ltd" }]
+keywords = ["screenshot", "pdf", "qr", "html-to-image", "ironfang"]
+classifiers = [
+  "Programming Language :: Python :: 3",
+  "Programming Language :: Python :: 3 :: Only",
+  "Operating System :: OS Independent",
+  "Topic :: Internet :: WWW/HTTP",
+]
+dependencies = []
+
+[project.urls]
+Homepage = "https://ironfang.com/render"
+Documentation = "https://ironfang.com/render/docs"
+
+[tool.setuptools.packages.find]
+where = ["src"]
+
+[tool.pytest.ini_options]
+testpaths = ["tests"]

ironfang_render-1.0.0/setup.cfg

@@ -0,0 +1,4 @@
+[egg_info]
+tag_build = 
+tag_date = 0
+

ironfang_render-1.0.0/src/ironfang_render/__init__.py

@@ -0,0 +1,33 @@
+"""Ironfang Render API client.
+
+    from ironfang_render import IronfangRender
+
+    with IronfangRender(api_key=os.environ["IRONFANG_API_KEY"]) as rw:
+        shot = rw.screenshot(url="https://example.com", full_page=True)
+        shot.save("page.png")
+
+Every render returns the bytes plus what the API reports about them. Errors
+raise IronfangRenderError with the HTTP status, the API's error code and the
+request id to quote to support. Synchronous renders are never retried by the
+client: a render that timed out may already have been charged.
+"""
+
+from .client import IronfangRender, RenderResult, SitePreviewResult, VERSION
+from .errors import IronfangRenderError
+from .webhook import sign_webhook, verify_webhook
+
+# Deprecated names from ironfang-renderwolf, kept so existing code runs unchanged.
+Renderwolf = IronfangRender
+RenderwolfError = IronfangRenderError
+
+__all__ = [
+    "IronfangRender",
+    "RenderResult",
+    "SitePreviewResult",
+    "IronfangRenderError",
+    "Renderwolf",
+    "RenderwolfError",
+    "sign_webhook",
+    "verify_webhook",
+    "VERSION",
+]

ironfang_render-1.0.0/src/ironfang_render/client.py

@@ -0,0 +1,354 @@
+from __future__ import annotations
+
+import json
+import shutil
+import socket
+import time
+import urllib.error
+import urllib.parse
+import urllib.request
+from dataclasses import dataclass, field
+from email.message import Message
+from email.parser import BytesParser
+from pathlib import Path
+from typing import Any, BinaryIO, Iterator
+
+from .errors import IronfangRenderError
+
+VERSION = "1.0.0"
+DEFAULT_BASE_URL = "https://api.ironfang.com/render"
+TERMINAL = {"succeeded", "failed", "cancelled"}
+
+
+@dataclass
+class RenderResult:
+    """A finished render with the facts the API reports about it."""
+
+    content_type: str
+    credits: int
+    render_ms: int
+    cached: bool
+    request_id: str
+    headers: dict[str, str]
+    _response: Any = field(repr=False)
+    _bytes: bytes | None = field(default=None, repr=False)
+
+    @property
+    def bytes(self) -> bytes:
+        """The whole output. Read once and kept; prefer ``save`` or
+        ``iter_bytes`` for clips and long PDFs."""
+        if self._bytes is None:
+            try:
+                self._bytes = self._response.read()
+            finally:
+                self.close()
+        return self._bytes
+
+    def iter_bytes(self, chunk_size: int = 64 * 1024) -> Iterator[bytes]:
+        """Stream the output without holding it all in memory."""
+        if self._bytes is not None:
+            yield self._bytes
+            return
+        try:
+            while True:
+                chunk = self._response.read(chunk_size)
+                if not chunk:
+                    break
+                yield chunk
+        finally:
+            self.close()
+
+    def save(self, path: str | Path) -> Path:
+        """Stream the output to a file and return its path."""
+        target = Path(path)
+        with target.open("wb") as f:
+            self.write_to(f)
+        return target
+
+    def write_to(self, stream: BinaryIO) -> None:
+        if self._bytes is not None:
+            stream.write(self._bytes)
+            return
+        try:
+            shutil.copyfileobj(self._response, stream)
+        finally:
+            self.close()
+
+    def close(self) -> None:
+        """Release the response, including when output is abandoned."""
+        self._response.close()
+
+    def __enter__(self) -> "RenderResult":
+        return self
+
+    def __exit__(self, *exc: object) -> None:
+        self.close()
+
+
+@dataclass
+class SitePreviewResult:
+    """A site preview: the poster frame and the scrolling video."""
+
+    poster: bytes
+    video: bytes
+    credits: int
+    render_ms: int
+    output_seconds: float
+    cached: bool
+    request_id: str
+    headers: dict[str, str]
+
+    def save(self, video_path: str | Path, poster_path: str | Path | None = None) -> None:
+        Path(video_path).write_bytes(self.video)
+        if poster_path is not None:
+            Path(poster_path).write_bytes(self.poster)
+
+
+class IronfangRender:
+    """The Ironfang Render client. Use as a context manager or call ``close``."""
+
+    def __init__(
+        self,
+        api_key: str,
+        *,
+        base_url: str = DEFAULT_BASE_URL,
+        timeout: float = 90.0,
+        opener: urllib.request.OpenerDirector | None = None,
+    ):
+        if not api_key:
+            raise IronfangRenderError("an API key is required", status=0, code="missing_api_key")
+        self._api_key = api_key
+        self._base_url = base_url.rstrip("/")
+        self._timeout = timeout
+        self._opener = opener or urllib.request.build_opener(_NoRedirect)
+
+    def __enter__(self) -> "IronfangRender":
+        return self
+
+    def __exit__(self, *exc: object) -> None:
+        self.close()
+
+    def close(self) -> None:
+        self._opener.close()
+
+    # ---------------------------------------------------------------- renders
+
+    def screenshot(self, *, request_id: str | None = None, timeout: float | None = None, **request: Any) -> RenderResult:
+        return self._render("/v1/screenshot", request, request_id, timeout)
+
+    def pdf(self, *, request_id: str | None = None, timeout: float | None = None, **request: Any) -> RenderResult:
+        return self._render("/v1/pdf", request, request_id, timeout)
+
+    def qr(self, *, request_id: str | None = None, timeout: float | None = None, **request: Any) -> RenderResult:
+        return self._render("/v1/qr", request, request_id, timeout)
+
+    def image(self, template_id: str, *, request_id: str | None = None, timeout: float | None = None, **request: Any) -> RenderResult:
+        """Render one of your stored templates with variables filled in."""
+        return self._render(f"/v1/image/{urllib.parse.quote(template_id, safe='')}", request, request_id, timeout)
+
+    def clip(self, *, request_id: str | None = None, timeout: float | None = None, **request: Any) -> RenderResult:
+        return self._render("/v1/video", request, request_id, timeout)
+
+    def site_preview(self, *, request_id: str | None = None, timeout: float | None = None, **request: Any) -> SitePreviewResult:
+        resp = self._send("POST", "/v1/site-preview", request, request_id=request_id, timeout=timeout)
+        try:
+            headers = _headers(resp)
+            body = resp.read()
+        finally:
+            resp.close()
+        parts = _multipart(headers.get("content-type", ""), body)
+        if "poster" not in parts or "video" not in parts:
+            raise IronfangRenderError("the response did not include both preview files", status=200, code="bad_response", request_id=headers.get("x-ironfang-request-id"))
+        return SitePreviewResult(
+            poster=parts["poster"],
+            video=parts["video"],
+            credits=_int(headers.get("x-renderwolf-credits")),
+            render_ms=_int(headers.get("x-renderwolf-render-ms")),
+            output_seconds=float(headers.get("x-renderwolf-output-seconds") or 0),
+            cached=headers.get("x-renderwolf-cache") == "hit",
+            request_id=headers.get("x-ironfang-request-id", ""),
+            headers=headers,
+        )
+
+    def _render(self, path: str, request: dict[str, Any], request_id: str | None, timeout: float | None) -> RenderResult:
+        resp = self._send("POST", path, request, request_id=request_id, timeout=timeout)
+        headers = _headers(resp)
+        return RenderResult(
+            content_type=headers.get("content-type", "application/octet-stream").split(";")[0].strip(),
+            credits=_int(headers.get("x-renderwolf-credits")),
+            render_ms=_int(headers.get("x-renderwolf-render-ms")),
+            cached=headers.get("x-renderwolf-cache") == "hit",
+            request_id=headers.get("x-ironfang-request-id", ""),
+            headers=headers,
+            _response=resp,
+        )
+
+    # ------------------------------------------------------------------- jobs
+
+    def submit_job(self, kind: str, request: dict[str, Any], *, external_id: str | None = None, delivery: dict[str, Any] | None = None, idempotency_key: str | None = None) -> dict[str, Any]:
+        """Submit a durable job. ``idempotency_key`` makes a retried submission
+        return the same job rather than a second one."""
+        body: dict[str, Any] = {"kind": kind, "request": request}
+        if external_id:
+            body["external_id"] = external_id
+        if delivery:
+            body["delivery"] = delivery
+        extra = {"Idempotency-Key": idempotency_key} if idempotency_key else {}
+        return self._json("POST", "/v1/jobs", body, extra=extra)
+
+    def get_job(self, job_id: str) -> dict[str, Any]:
+        return self._json("GET", f"/v1/jobs/{urllib.parse.quote(job_id, safe='')}")
+
+    def list_jobs(self, *, status: str | None = None, cursor: str | None = None, limit: int | None = None) -> dict[str, Any]:
+        return self._json("GET", "/v1/jobs" + _query(status=status, cursor=cursor, limit=limit))
+
+    def cancel_job(self, job_id: str) -> dict[str, Any]:
+        return self._json("DELETE", f"/v1/jobs/{urllib.parse.quote(job_id, safe='')}")
+
+    def job_result(self, job_id: str) -> RenderResult:
+        """Download a succeeded job's result."""
+        resp = self._send("GET", f"/v1/jobs/{urllib.parse.quote(job_id, safe='')}/result", None, follow_redirects=True)
+        headers = _headers(resp)
+        return RenderResult(
+            content_type=headers.get("content-type", "application/octet-stream").split(";")[0].strip(),
+            credits=0, render_ms=0, cached=False,
+            request_id=headers.get("x-ironfang-request-id", ""),
+            headers=headers, _response=resp,
+        )
+
+    def wait_for_job(self, job_id: str, *, poll_seconds: float = 2.0, timeout: float = 600.0, should_stop: Any = None) -> dict[str, Any]:
+        """Poll until the job is terminal. Returns the job whatever the
+        outcome; check ``status``. ``should_stop`` is an optional callable
+        returning True to abandon the wait."""
+        deadline = time.monotonic() + timeout
+        while True:
+            job = self.get_job(job_id)
+            if job.get("status") in TERMINAL:
+                return job
+            if should_stop is not None and should_stop():
+                raise IronfangRenderError("wait abandoned", status=0, code="aborted")
+            if time.monotonic() >= deadline:
+                raise IronfangRenderError(f"job {job_id} did not finish within {timeout:g}s", status=0, code="timeout")
+            time.sleep(poll_seconds)
+
+    # ----------------------------------------------------------- destinations
+
+    def create_destination(self, **destination: Any) -> dict[str, Any]:
+        """Register where finished jobs go. A webhook destination's
+        ``signing_secret`` is returned here once and never again; keep it."""
+        return self._json("POST", "/v1/destinations", destination)
+
+    def list_destinations(self) -> dict[str, Any]:
+        return self._json("GET", "/v1/destinations")
+
+    def test_destination(self, destination_id: str) -> dict[str, Any]:
+        """Reach the destination now; a failure is reported in the body, not raised."""
+        return self._json("POST", f"/v1/destinations/{urllib.parse.quote(destination_id, safe='')}/test")
+
+    def delete_destination(self, destination_id: str) -> None:
+        resp = self._send("DELETE", f"/v1/destinations/{urllib.parse.quote(destination_id, safe='')}", None)
+        resp.close()
+
+    # --------------------------------------------------------------- the rest
+
+    def sign(self, **request: Any) -> dict[str, Any]:
+        """Mint a signed render URL that an <img> or an email can fetch directly."""
+        return self._json("POST", "/v1/sign", request)
+
+    def usage(self) -> dict[str, Any]:
+        return self._json("GET", "/v1/usage")
+
+    def requests(self, **filters: Any) -> dict[str, Any]:
+        """Request history for the last seven days."""
+        return self._json("GET", "/v1/requests" + _query(**filters))
+
+    # -------------------------------------------------------------- transport
+
+    def _json(self, method: str, path: str, body: Any = None, *, extra: dict[str, str] | None = None) -> dict[str, Any]:
+        resp = self._send(method, path, body, extra=extra)
+        try:
+            return json.loads(resp.read().decode())
+        finally:
+            resp.close()
+
+    def _send(self, method: str, path: str, body: Any, *, request_id: str | None = None, timeout: float | None = None, extra: dict[str, str] | None = None, follow_redirects: bool = False) -> Any:
+        headers = {
+            "Authorization": f"Bearer {self._api_key}",
+            "Accept": "application/json, */*",
+            "X-Ironfang-Client": f"ironfang-render-python/{VERSION}",
+        }
+        if extra:
+            headers.update(extra)
+        if request_id:
+            headers["X-Request-ID"] = request_id
+        data = None
+        if body is not None:
+            headers["Content-Type"] = "application/json"
+            data = json.dumps(body).encode()
+        url = self._base_url + path
+        req = urllib.request.Request(url, data=data, method=method, headers=headers)
+        opener = urllib.request.build_opener() if follow_redirects else self._opener
+        try:
+            # No retry here on purpose: a synchronous render that timed out
+            # may have been charged, and retrying it blind doubles the bill.
+            return opener.open(req, timeout=timeout or self._timeout)
+        except urllib.error.HTTPError as e:
+            raise _error_from(e) from None
+        except (urllib.error.URLError, socket.timeout, TimeoutError) as e:
+            reason = getattr(e, "reason", e)
+            if isinstance(reason, (socket.timeout, TimeoutError)) or isinstance(e, (socket.timeout, TimeoutError)):
+                raise IronfangRenderError(f"request timed out after {timeout or self._timeout:g}s", status=0, code="timeout") from None
+            raise IronfangRenderError(f"network error: {reason}", status=0, code="network_error") from None
+
+
+class _NoRedirect(urllib.request.HTTPRedirectHandler):
+    """Renders never redirect; a redirect on a render is a misconfiguration
+    worth surfacing rather than a hop to follow with the bearer key."""
+
+    def redirect_request(self, req, fp, code, msg, headers, newurl):  # type: ignore[override]
+        return None
+
+
+def _error_from(e: urllib.error.HTTPError) -> IronfangRenderError:
+    code = f"http_{e.code}"
+    message = f"request failed with HTTP {e.code}"
+    request_id = e.headers.get("X-Ironfang-Request-ID") if e.headers else None
+    try:
+        body = json.loads(e.read().decode())
+        err = body.get("error") or {}
+        code = err.get("code") or code
+        message = err.get("message") or message
+        request_id = body.get("request_id") or request_id
+    except Exception:
+        pass
+    finally:
+        e.close()
+    return IronfangRenderError(message, status=e.code, code=code, request_id=request_id)
+
+
+def _headers(resp: Any) -> dict[str, str]:
+    return {k.lower(): v for k, v in resp.headers.items()}
+
+
+def _int(v: str | None) -> int:
+    try:
+        return int(float(v or 0))
+    except ValueError:
+        return 0
+
+
+def _query(**params: Any) -> str:
+    clean = {k: v for k, v in params.items() if v not in (None, "")}
+    return ("?" + urllib.parse.urlencode(clean)) if clean else ""
+
+
+def _multipart(content_type: str, body: bytes) -> dict[str, bytes]:
+    msg = BytesParser().parsebytes(b"Content-Type: " + content_type.encode() + b"\r\n\r\n" + body)
+    parts: dict[str, bytes] = {}
+    for part in msg.walk():
+        name = part.get_param("name", header="content-disposition")
+        if name and not part.is_multipart():
+            payload = part.get_payload(decode=True)
+            if payload is not None:
+                parts[str(name)] = payload
+    return parts

ironfang_render-1.0.0/src/ironfang_render/errors.py

@@ -0,0 +1,24 @@
+class IronfangRenderError(Exception):
+    """An error the API returned, or a failure to reach it.
+
+    ``code`` is the API's stable error code (``bad_request``,
+    ``quota_exhausted``, ``render_failed``, ...) or a client-side one
+    (``network_error``, ``timeout``). ``request_id`` is the id to quote to
+    support; it is on every response the server produced, including errors.
+    """
+
+    def __init__(self, message: str, *, status: int, code: str, request_id: str | None = None):
+        super().__init__(message)
+        self.status = status
+        self.code = code
+        self.request_id = request_id
+
+    @property
+    def is_client_error(self) -> bool:
+        return 400 <= self.status < 500
+
+    def __str__(self) -> str:
+        base = super().__str__()
+        if self.request_id:
+            return f"{base} (request {self.request_id})"
+        return base

ironfang_render-1.0.0/src/ironfang_render/webhook.py

@@ -0,0 +1,48 @@
+"""Verify an Ironfang Render webhook delivery.
+
+Ironfang Render signs each delivery with HMAC-SHA256 over
+``<timestamp>.<raw body>`` using the endpoint's signing secret, and sends it
+as ``Renderwolf-Signature: v1=<hex>`` with ``Renderwolf-Timestamp`` beside it.
+Run the check over the raw bytes as received: re-serialising parsed JSON
+changes them and the signature will not match.
+"""
+
+from __future__ import annotations
+
+import hashlib
+import hmac
+import time
+
+
+def sign_webhook(secret: str, timestamp: str, payload: bytes | str) -> str:
+    """Compute the signature Ironfang Render would send."""
+    body = payload.encode() if isinstance(payload, str) else payload
+    mac = hmac.new(secret.encode(), (timestamp + ".").encode() + body, hashlib.sha256)
+    return "v1=" + mac.hexdigest()
+
+
+def verify_webhook(
+    *,
+    secret: str,
+    timestamp: str,
+    signature: str,
+    payload: bytes | str,
+    tolerance_seconds: int = 300,
+    now: float | None = None,
+) -> bool:
+    """Return True only for a genuine, recent delivery.
+
+    ``tolerance_seconds`` rejects a delivery whose timestamp is further than
+    that from now, so a captured delivery cannot be replayed later. Pass 0 to
+    skip the check, for tests with fixed timestamps.
+    """
+    if tolerance_seconds > 0:
+        try:
+            ts = float(timestamp)
+        except (TypeError, ValueError):
+            return False
+        current = time.time() if now is None else now
+        if abs(current - ts) > tolerance_seconds:
+            return False
+    expected = sign_webhook(secret, timestamp, payload)
+    return hmac.compare_digest(expected, signature.strip())

ironfang_render-1.0.0/src/ironfang_render.egg-info/PKG-INFO

@@ -0,0 +1,103 @@
+Metadata-Version: 2.4
+Name: ironfang-render
+Version: 1.0.0
+Summary: Ironfang Render API client: screenshots, PDFs, QR codes, template images, clips and site previews from a URL or HTML.
+Author: Ironfang Ltd
+License-Expression: MIT
+Project-URL: Homepage, https://ironfang.com/render
+Project-URL: Documentation, https://ironfang.com/render/docs
+Keywords: screenshot,pdf,qr,html-to-image,ironfang
+Classifier: Programming Language :: Python :: 3
+Classifier: Programming Language :: Python :: 3 :: Only
+Classifier: Operating System :: OS Independent
+Classifier: Topic :: Internet :: WWW/HTTP
+Requires-Python: >=3.10
+Description-Content-Type: text/markdown
+
+# ironfang-render
+
+The official Python client for the [Ironfang Render](https://ironfang.com/render)
+API: screenshots, PDFs, QR codes, template images, clips and site previews
+from a URL or from HTML you send. No dependencies; Python 3.10 and later.
+
+Formerly `ironfang-renderwolf`. `import ironfang_renderwolf` and the old
+`Renderwolf` and `RenderwolfError` names still work with a deprecation
+warning, and webhooks still carry the `Renderwolf-*` headers.
+
+```sh
+pip install ironfang-render
+```
+
+```python
+import os
+from ironfang_render import IronfangRender
+
+with IronfangRender(api_key=os.environ["IRONFANG_API_KEY"]) as rw:
+    shot = rw.screenshot(url="https://example.com", full_page=True)
+    shot.save("page.png")
+    print(shot.credits, shot.render_ms, shot.request_id)
+```
+
+Every render returns the bytes plus what the API reports about them: content
+type, credits charged (zero on a cache hit), render time and the request id
+to quote to support. Long outputs stream: `save()` and `iter_bytes()` never
+hold a whole clip in memory.
+
+## Change the page before capture
+
+```python
+rw.screenshot(
+    html="<div class='chat-widget'>Chat</div><details id='details'><summary id='show-more'>Pricing</summary><p>Expanded pricing</p></details>",
+    css=".chat-widget { display: none !important; }",
+    script="document.querySelector('#show-more').textContent = 'Show pricing';",
+    actions=[
+        {"type": "click", "selector": "#show-more"},
+        {"type": "wait_for_selector", "selector": "#details[open]"},
+    ],
+).save("expanded.png")
+```
+
+The same options work with `rw.pdf()` and URL input. After normal load/waits,
+Ironfang Render applies CSS, awaits the script, then executes actions in order
+before settling and capture. JavaScript runs in the target page context as an
+async function body; use `await` or return a promise for asynchronous work. It
+has a five-second limit (or the remaining render timeout, if shorter).
+
+CSS is limited to 64 KiB of UTF-8, script to 16 KiB, and actions to 20. Actions
+are `click`, `hover`, `wait_for_selector` (presence), and `delay` with
+`duration_ms`; combined delays may total at most 10,000 ms. Selectors are limited
+to 1,024 UTF-8 bytes and share the render timeout. Invalid input returns
+`bad_request`; script/action execution errors return sanitized `render_failed`
+messages. A screenshot cache hit does not re-execute controls; use `no_cache`
+for fresh execution. [Full reference](https://ironfang.com/render/docs#page-controls).
+
+## Durable jobs
+
+```python
+job = rw.submit_job("pdf", {"html": invoice_html, "paper_format": "a4"}, idempotency_key=f"invoice-{invoice.id}")
+done = rw.wait_for_job(job["id"])
+if done["status"] == "succeeded":
+    rw.job_result(job["id"]).save(f"invoice-{invoice.id}.pdf")
+```
+
+## Verifying a webhook
+
+Run the check over the raw request body, before parsing it.
+
+```python
+from ironfang_render import verify_webhook
+
+ok = verify_webhook(
+    secret=os.environ["RENDER_WEBHOOK_SECRET"],
+    timestamp=request.headers["Renderwolf-Timestamp"],
+    signature=request.headers["Renderwolf-Signature"],
+    payload=request.get_data(),
+)
+```
+
+## Errors
+
+Failures raise `IronfangRenderError` with `status`, the API's `code`
+(`quota_exhausted`, `render_failed`, ...) and `request_id`. Synchronous
+renders are never retried by the client: a render that timed out may already
+have been charged, and retrying it blind doubles the bill.

ironfang_render-1.0.0/src/ironfang_render.egg-info/SOURCES.txt

@@ -0,0 +1,13 @@
+README.md
+pyproject.toml
+src/ironfang_render/__init__.py
+src/ironfang_render/client.py
+src/ironfang_render/errors.py
+src/ironfang_render/webhook.py
+src/ironfang_render.egg-info/PKG-INFO
+src/ironfang_render.egg-info/SOURCES.txt
+src/ironfang_render.egg-info/dependency_links.txt
+src/ironfang_render.egg-info/top_level.txt
+src/ironfang_renderwolf/__init__.py
+tests/test_client.py
+tests/test_compat.py

ironfang_render-1.0.0/src/ironfang_render.egg-info/dependency_links.txt

@@ -0,0 +1 @@
+

ironfang_render-1.0.0/src/ironfang_render.egg-info/top_level.txt

@@ -0,0 +1,2 @@
+ironfang_render
+ironfang_renderwolf

ironfang_render-1.0.0/src/ironfang_renderwolf/__init__.py

@@ -0,0 +1,22 @@
+"""Deprecated: the package is now ironfang_render.
+
+Importing ironfang_renderwolf still works and gives the same objects, so
+existing code keeps running. Change imports to ironfang_render.
+"""
+
+import sys
+import warnings
+
+warnings.warn(
+    "ironfang_renderwolf is deprecated; import ironfang_render instead",
+    DeprecationWarning,
+    stacklevel=2,
+)
+
+import ironfang_render
+from ironfang_render import *  # noqa: F401,F403
+from ironfang_render import __all__  # noqa: F401
+from ironfang_render import client, errors, webhook
+
+for _name in ("client", "errors", "webhook"):
+    sys.modules[f"{__name__}.{_name}"] = getattr(ironfang_render, _name)

ironfang_render-1.0.0/tests/test_client.py

@@ -0,0 +1,249 @@
+import json
+import threading
+import time
+from http.server import BaseHTTPRequestHandler, HTTPServer
+
+import pytest
+
+from ironfang_render import IronfangRender, IronfangRenderError, sign_webhook, verify_webhook
+
+SEEN: list[dict] = []
+STATE = {"polls": 0, "hang": False}
+
+
+class Fake(BaseHTTPRequestHandler):
+    def log_message(self, *a):  # quiet
+        pass
+
+    def _reply(self, status, body: bytes, headers=None):
+        self.send_response(status)
+        self.send_header("X-Ironfang-Request-ID", "req-fixture")
+        for k, v in (headers or {}).items():
+            self.send_header(k, v)
+        self.send_header("Content-Length", str(len(body)))
+        self.end_headers()
+        self.wfile.write(body)
+
+    def do_POST(self):
+        raw = self.rfile.read(int(self.headers.get("Content-Length") or 0)).decode()
+        SEEN.append({"method": "POST", "path": self.path, "headers": {k.lower(): v for k, v in self.headers.items()}, "body": raw})
+        if STATE["hang"]:
+            time.sleep(2)
+            return
+        if self.path == "/v1/screenshot":
+            if "broken.example" in raw:
+                return self._reply(422, json.dumps({"error": {"code": "render_failed", "message": "navigate: context deadline exceeded"}, "request_id": "req-fixture"}).encode(), {"Content-Type": "application/json"})
+            return self._reply(200, bytes([137, 80, 78, 71]), {"Content-Type": "image/png", "X-Renderwolf-Credits": "1", "X-Renderwolf-Render-Ms": "812", "X-Renderwolf-Cache": "miss"})
+        if self.path == "/v1/qr":
+            return self._reply(200, bytes([137, 80, 78, 71]), {"Content-Type": "image/png", "X-Renderwolf-Credits": "0", "X-Renderwolf-Cache": "hit"})
+        if self.path == "/v1/jobs":
+            return self._reply(202, json.dumps({"id": "job-1", "kind": "pdf", "status": "queued"}).encode(), {"Content-Type": "application/json"})
+        if self.path == "/v1/site-preview":
+            b = b"xx"
+            body = (b"--" + b + b"\r\nContent-Disposition: form-data; name=\"poster\"; filename=\"poster.jpg\"\r\nContent-Type: image/jpeg\r\n\r\nJPEG\r\n"
+                    b"--" + b + b"\r\nContent-Disposition: form-data; name=\"video\"; filename=\"preview.mp4\"\r\nContent-Type: video/mp4\r\n\r\nMP4DATA\r\n--" + b + b"--\r\n")
+            return self._reply(200, body, {"Content-Type": "multipart/form-data; boundary=xx", "X-Renderwolf-Credits": "6", "X-Renderwolf-Output-Seconds": "6"})
+        self._reply(404, json.dumps({"error": {"code": "not_found", "message": "no such route"}}).encode(), {"Content-Type": "application/json"})
+
+    def do_GET(self):
+        SEEN.append({"method": "GET", "path": self.path, "headers": {k.lower(): v for k, v in self.headers.items()}, "body": ""})
+        if self.path == "/v1/jobs/job-1":
+            STATE["polls"] += 1
+            status = "running" if STATE["polls"] < 3 else "succeeded"
+            return self._reply(200, json.dumps({"id": "job-1", "status": status}).encode(), {"Content-Type": "application/json"})
+        if self.path == "/v1/jobs/job-1/result":
+            return self._reply(200, b"%PDF-1.7\n", {"Content-Type": "application/pdf"})
+        if self.path.startswith("/v1/requests"):
+            return self._reply(200, json.dumps({"requests": [{"id": "r1"}], "retention_days": 7}).encode(), {"Content-Type": "application/json"})
+        if self.path == "/v1/nope":
+            return self._reply(401, b"not json")
+        self._reply(404, json.dumps({"error": {"code": "not_found", "message": "no"}}).encode(), {"Content-Type": "application/json"})
+
+    def do_DELETE(self):
+        self.do_GET()
+
+
+@pytest.fixture(scope="module")
+def base_url():
+    server = HTTPServer(("127.0.0.1", 0), Fake)
+    thread = threading.Thread(target=server.serve_forever, daemon=True)
+    thread.start()
+    yield f"http://127.0.0.1:{server.server_port}"
+    server.shutdown()
+
+
+@pytest.fixture
+def rw(base_url):
+    with IronfangRender("rw_test_secret_key", base_url=base_url, timeout=5) as client:
+        yield client
+
+
+def test_render_sends_key_and_returns_facts(rw, tmp_path):
+    SEEN.clear()
+    request = {
+        "url": "https://acme.example", "full_page": True,
+        "css": ".chat-widget { display: none !important; }",
+        "script": "document.querySelector('#pricing')?.click();",
+        "actions": [{"type": "click", "selector": "#expand"}, {"type": "delay", "duration_ms": 100}],
+    }
+    out = rw.screenshot(**request, request_id="order-77")
+    req = SEEN[0]
+    assert req["headers"]["authorization"] == "Bearer rw_test_secret_key"
+    assert req["headers"]["x-ironfang-client"].startswith("ironfang-render-python/")
+    assert req["headers"]["x-request-id"] == "order-77"
+    assert json.loads(req["body"]) == request
+    assert out.content_type == "image/png"
+    assert out.credits == 1 and out.render_ms == 812 and out.cached is False
+    assert out.request_id == "req-fixture"
+    saved = out.save(tmp_path / "page.png")
+    assert saved.read_bytes() == bytes([137, 80, 78, 71])
+
+
+def test_cache_hit_is_free(rw):
+    out = rw.qr(data="https://acme.example")
+    assert out.cached is True and out.credits == 0
+    assert out.bytes[:1] == b"\x89"
+
+
+def test_streaming_does_not_need_the_whole_body_first(rw):
+    out = rw.screenshot(url="https://acme.example")
+    chunks = list(out.iter_bytes(chunk_size=2))
+    assert b"".join(chunks) == bytes([137, 80, 78, 71])
+
+
+def test_api_error_is_typed_and_never_carries_the_key(rw):
+    with pytest.raises(IronfangRenderError) as info:
+        rw.screenshot(url="https://broken.example")
+    err = info.value
+    assert err.status == 422 and err.code == "render_failed" and err.request_id == "req-fixture"
+    assert "deadline" in str(err) and "req-fixture" in str(err)
+    assert "rw_test_secret_key" not in str(err)
+
+
+def test_non_json_error_body(rw):
+    with pytest.raises(IronfangRenderError) as info:
+        rw._json("GET", "/v1/nope")
+    assert info.value.status == 401 and info.value.code == "http_401"
+
+
+def test_timeout_makes_exactly_one_attempt(rw):
+    STATE["hang"] = True
+    SEEN.clear()
+    try:
+        with pytest.raises(IronfangRenderError) as info:
+            rw.screenshot(url="https://slow.example", timeout=0.3)
+        assert info.value.code == "timeout"
+        assert len([s for s in SEEN if s["path"] == "/v1/screenshot"]) == 1
+    finally:
+        STATE["hang"] = False
+        time.sleep(2.1)  # let the hung handler finish before the next test
+
+
+def test_jobs_submit_wait_and_collect(rw):
+    STATE["polls"] = 0
+    SEEN.clear()
+    job = rw.submit_job("pdf", {"html": "<h1>Invoice</h1>"}, idempotency_key="inv-1042")
+    assert job["status"] == "queued"
+    assert SEEN[0]["headers"]["idempotency-key"] == "inv-1042"
+    done = rw.wait_for_job("job-1", poll_seconds=0.01)
+    assert done["status"] == "succeeded" and STATE["polls"] == 3
+    result = rw.job_result("job-1")
+    assert result.content_type == "application/pdf" and result.bytes.startswith(b"%PDF")
+
+
+def test_site_preview_splits_the_multipart(rw):
+    out = rw.site_preview(url="https://acme.example")
+    assert out.poster == b"JPEG" and out.video == b"MP4DATA"
+    assert out.credits == 6 and out.output_seconds == 6.0
+
+
+def test_history_filters(rw):
+    SEEN.clear()
+    out = rw.requests(outcome="error", kind="qr", limit=10)
+    assert SEEN[0]["path"] == "/v1/requests?outcome=error&kind=qr&limit=10"
+    assert out["retention_days"] == 7
+
+
+def test_refuses_to_start_without_a_key(base_url):
+    with pytest.raises(IronfangRenderError) as info:
+        IronfangRender("", base_url=base_url)
+    assert info.value.code == "missing_api_key"
+
+
+def test_default_base_is_the_canonical_one():
+    import io
+
+    class Opener:
+        urls: list[str] = []
+
+        def open(self, req, timeout=None):
+            self.urls.append(req.full_url)
+            return io.BytesIO(b"{}")
+
+    opener = Opener()
+    IronfangRender("rw_test_secret_key", opener=opener).usage()
+    # The launch-era /renderwolf prefix still answers, so a caller who set it stays where they are.
+    IronfangRender("rw_test_secret_key", base_url="https://api.ironfang.com/renderwolf/", opener=opener).usage()
+    assert opener.urls == ["https://api.ironfang.com/render/v1/usage", "https://api.ironfang.com/renderwolf/v1/usage"]
+
+
+def test_webhook_matches_the_go_implementation():
+    # Literal produced by internal/webhook.Signature([]byte("secret"), "1700000000", []byte("hello")).
+    assert sign_webhook("secret", "1700000000", "hello") == "v1=47b1df0ab12338b2685470b0d2b37033add7c3b2bc8172f313e77413f1bb78c8"
+
+
+def test_webhook_verification_rules():
+    secret, ts = "whsec_test", "1756480271"
+    payload = b'{"type":"render.job.succeeded","job":{"id":"job-1"}}'
+    sig = sign_webhook(secret, ts, payload)
+    assert verify_webhook(secret=secret, timestamp=ts, signature=sig, payload=payload, tolerance_seconds=0)
+    assert not verify_webhook(secret="other", timestamp=ts, signature=sig, payload=payload, tolerance_seconds=0)
+    assert not verify_webhook(secret=secret, timestamp=ts, signature=sig, payload=payload.replace(b"job-1", b"job-2"), tolerance_seconds=0)
+    # Raw bytes matter: the same JSON re-serialised must fail.
+    pretty = json.dumps(json.loads(payload), indent=2).encode()
+    assert not verify_webhook(secret=secret, timestamp=ts, signature=sig, payload=pretty, tolerance_seconds=0)
+    assert not verify_webhook(secret=secret, timestamp=ts, signature=sig, payload=payload, now=int(ts) + 3600)
+    assert verify_webhook(secret=secret, timestamp=ts, signature=sig, payload=payload, now=int(ts) + 60)
+
+
+@pytest.mark.parametrize("method", ["bytes", "write_to", "iter_bytes"])
+def test_result_closes_after_failed_read(method):
+    from ironfang_render.client import RenderResult
+    import io
+
+    class BrokenResponse:
+        closed = False
+        def read(self, *args):
+            raise OSError("read failed")
+        def close(self):
+            self.closed = True
+
+    response = BrokenResponse()
+    result = RenderResult("image/png", 0, 0, False, "fixture", {}, response)
+    with pytest.raises(OSError, match="read failed"):
+        if method == "bytes":
+            result.bytes
+        elif method == "write_to":
+            result.write_to(io.BytesIO())
+        else:
+            list(result.iter_bytes())
+    assert response.closed
+
+
+def test_result_closes_after_failed_write_and_when_abandoned():
+    from ironfang_render.client import RenderResult
+    import io
+
+    class BrokenWriter:
+        def write(self, data):
+            raise OSError("write failed")
+
+    response = io.BytesIO(b"render")
+    result = RenderResult("image/png", 0, 0, False, "fixture", {}, response)
+    with pytest.raises(OSError, match="write failed"):
+        result.write_to(BrokenWriter())
+    assert response.closed
+    response = io.BytesIO(b"abandoned")
+    with RenderResult("image/png", 0, 0, False, "fixture", {}, response):
+        pass
+    assert response.closed

ironfang_render-1.0.0/tests/test_compat.py

@@ -0,0 +1,17 @@
+import importlib
+import sys
+import warnings
+
+import ironfang_render
+
+
+def test_old_module_warns_and_gives_the_same_objects():
+    for name in [m for m in sys.modules if m.startswith("ironfang_renderwolf")]:
+        del sys.modules[name]
+    with warnings.catch_warnings(record=True) as caught:
+        warnings.simplefilter("always")
+        old = importlib.import_module("ironfang_renderwolf")
+    assert any(w.category is DeprecationWarning for w in caught)
+    assert old.Renderwolf is ironfang_render.IronfangRender
+    assert old.RenderwolfError is ironfang_render.IronfangRenderError
+    assert importlib.import_module("ironfang_renderwolf.webhook") is ironfang_render.webhook