DEV Community: Harpreet singh

How to generate invoice PDFs from a protected route in your own app

Harpreet singh — Tue, 08 Sep 2026 21:40:36 +0000

Your app already knows how to draw an invoice. There is a route — /invoices/:id — that pulls the line items, applies the tax rules, formats the currency and renders a page a customer can read. It is behind a login, because of course it is.

Then someone asks for a PDF, and the usual answer is to build the document a second time: a templating layer for a PDF library, a second set of layout primitives, a second place for the tax rounding to drift. Six months later the HTML invoice and the PDF invoice disagree about the total and nobody can say which one is right.

There is a shorter path: keep the one template you have and let a headless browser print it. The only genuinely hard part is auth, because the page is protected and the renderer is not your user.

The pattern

Four steps, all server-side:

A render route — the page you already have, or a print-flavoured sibling (/invoices/:id/print) with the nav and the download button stripped out.
A one-time credential — your backend mints a token: sixty seconds, single use, scoped to one invoice id.
One API call — your backend POSTs the URL plus that credential to a rendering API.
PDF bytes back — stream them, email them, or push them to object storage.

The customer's session is never involved and the token is dead before anyone could replay it.

Express, end to end

The token first. A random string in Redis with a 60-second TTL gives you real single use, because you can delete it on first read.

import crypto from "node:crypto";

const pending = new Map(); // in production: Redis, with a TTL

function mintRenderToken(invoiceId) {
  const token = crypto.randomBytes(32).toString("base64url");
  pending.set(token, { invoiceId, expires: Date.now() + 60_000 });
  return token;
}

// The print route trusts the token and nothing else.
app.get("/invoices/:id/print", (req, res, next) => {
  const key = req.get("x-render-token");
  const entry = pending.get(key);
  pending.delete(key);                                  // single use
  if (!entry || entry.expires < Date.now() || entry.invoiceId !== req.params.id) {
    return next();                                      // fall through to the session check
  }
  res.send(renderInvoiceHtml(loadInvoice(req.params.id)));
});

Now the render call. I use snaplab for this — hosted Chromium behind one REST endpoint — but the shape is the same wherever you send it.

app.get("/invoices/:id/pdf", requireSession, async (req, res) => {
  const token = mintRenderToken(req.params.id);

  const r = await fetch("https://snaplab.dev/api/render", {
    method: "POST",
    headers: {
      Authorization: `Bearer ${process.env.SNAPLAB_API_KEY}`,
      "Content-Type": "application/json",
    },
    body: JSON.stringify({
      url: `https://app.example.com/invoices/${req.params.id}/print`,
      format: "pdf",
      headers: { "X-Render-Token": token },
      filename: `invoice-${req.params.id}.pdf`,
      waitForSelector: "[data-invoice-ready]",
      pdf: {
        format: "A4",
        media: "print",
        printBackground: true,
        margin: { top: "18mm", right: "14mm", bottom: "20mm", left: "14mm" },
        footerTemplate: "@pageNumbers",
      },
    }),
  });

  if (!r.ok) throw new Error(`render failed ${r.status}: ${await r.text()}`);

  res.type("application/pdf");
  res.setHeader("content-disposition", `attachment; filename="invoice-${req.params.id}.pdf"`);
  res.send(Buffer.from(await r.arrayBuffer()));
});

That is the whole integration. One template, and the PDF is by construction the document the customer sees in the browser.

Session cookies instead

Some apps are easier to hand a cookie than to teach a new header:

{
  "url": "https://app.example.com/reports/q3",
  "format": "pdf",
  "cookies": [
    { "name": "session", "value": "…", "domain": "app.example.com", "path": "/", "secure": true, "sameSite": "Lax" }
  ],
  "pdf": { "format": "A4", "footerTemplate": "@pageNumbersUrl" }
}

Mint a fresh read-only service session for this rather than borrowing a live customer one. A cookie you created for a render is a cookie you can revoke the second it returns.

Python

import os, requests

def invoice_pdf(invoice_id: str) -> bytes:
    token = mint_render_token(invoice_id)   # 60s, single use, scoped to this id
    r = requests.post(
        "https://snaplab.dev/api/render",
        headers={"Authorization": f"Bearer {os.environ['SNAPLAB_API_KEY']}"},
        json={
            "url": f"https://app.example.com/invoices/{invoice_id}/print",
            "format": "pdf",
            "headers": {"X-Render-Token": token},
            "filename": f"invoice-{invoice_id}.pdf",
            "waitForSelector": "[data-invoice-ready]",
            "pdf": {
                "format": "A4",
                "media": "print",
                "printBackground": True,
                "margin": {"top": "18mm", "right": "14mm", "bottom": "20mm", "left": "14mm"},
                "footerTemplate": "@pageNumbers",
            },
        },
        timeout=60,
    )
    r.raise_for_status()
    return r.content

Sending a credential to a third party

Worth being precise about, because "just POST your session cookie somewhere" is not advice anyone should take on trust.

Host-scoped. headers and basicAuth are applied to the target host only. If the invoice page pulls a font from Google or a logo from a CDN, those subrequests go out clean — the token is not sprayed across every third-party asset. cookies obey the domain you set, exactly as a browser would.
Never persisted. Credentials live in the request body, are handed to that one browser context, and go away with it. Not written to the render record, not logged.
Never cached. A render that carried cookies, headers or basicAuth is excluded from the shared response cache — two customers' statements cannot collide on a fingerprint, and nobody else can get a cache hit on your document.
Short-lived. Scope the token to one record, not to an account. A leaked one is then worthless within the minute.

Page numbers

A four-page statement with no "Page 2 of 4" on it is an accident waiting to happen. Chromium draws header/footer templates in the paper margin, substituting the classes pageNumber, totalPages, date, title and url:

"footerTemplate": "<div style='font-size:9px;width:100%;padding:0 14mm;text-align:right;color:#666'>Page <span class='pageNumber'></span> of <span class='totalPages'></span></div>"

Because that is tedious to write inline, "@pageNumbers" and "@pageNumbersUrl" are presets for the two common cases. Two gotchas: templates inherit none of the page's CSS and start near zero font-size, so always set font-size; and give pdf.margin.top/bottom room to hold them, or they are silently clipped.

The rest of the page setup lives on the same object — pageRanges, width/height for non-standard stock, tagged for an accessible structure tree, outline to turn headings into PDF bookmarks.

Print CSS still decides the pagination

Set pdf.media: "print" (the default is screen, for backwards compatibility) and your print stylesheet is live:

@page { margin: 0; }                     /* let pdf.margin own the paper edge */

@media print {
  nav, .app-shell__sidebar, .download-btn { display: none !important; }
  .invoice-line, .totals-card { break-inside: avoid; }
  thead { display: table-header-group; }  /* repeat headers on every page */
  h2 { break-after: avoid; }
  p  { orphans: 3; widows: 3; }
}

display: table-header-group is the one people miss: without it, a long line-item table is labelled on page one and anonymous everywhere after.

Month-end is nine hundred invoices

Rendering those inside a request handler will time out. Queue them instead: POST /api/captures takes the same body, answers immediately, and calls a webhook per document with an HMAC signature you verify before trusting the payload. One caveat specific to this pattern — a queued render happens later, so batch tokens need minutes of life, not sixty seconds.

Five things that will bite you

Fonts arriving after the capture. Symptom: a PDF in Times New Roman. Wait on a marker your page sets from document.fonts.ready (waitForSelector: "[data-invoice-ready]"), or add a small delayMs.
Lazy images. loading="lazy" below the fold may never load, because printing does not scroll. Drop the attribute for print, or scroll first.
Cookie domain and flags. A wrong domain, or secure: true against an http URL, means the cookie is silently not sent — and you get your login page as a beautifully typeset PDF.
Redirects to login. Renderers follow them. Return 401 from the print route instead of redirecting, so a bad token is an API error rather than a wrong document.
Relative URLs when you send raw html. There is no base to resolve against: inline the CSS, use absolute image URLs, embed small assets as data URIs.

Full write-up with the security details and the async batch flow: snaplab.dev/blog/pdf-from-protected-route. Free tier is 100 renders a month, no card, if you want to try the pattern before committing to it.

Give Claude Code and Cursor eyes: a hosted MCP screenshot tool in one command

Harpreet singh — Tue, 08 Sep 2026 21:16:02 +0000

Coding agents are surprisingly blind. Claude Code can read your CSS, but it cannot tell you that the hero text is overlapping the nav on mobile. Cursor can write a Playwright test, but it cannot glance at the page it just changed. The fix is small: give the agent a tool that returns a real screenshot.

This post sets that up with the Model Context Protocol (MCP) in one command, using a hosted server so there is nothing to run locally.

What you get

Four tools appear in the agent:

screenshot – URL or raw HTML in, PNG/JPEG/WebP out, returned inline as an image so the model can look at it. Options: fullPage, width/height, mobile, darkMode, blockAds, dismissBanners.
pdf – the same, but a print-quality PDF (A4/Letter, landscape, margins).
html_to_image – HTML/CSS in, a 1200×630 image out. Handy for OG cards.
usage – how many renders you have left this month.

Renders run in real Chromium on the server with hard timeouts, ad blocking and cookie-banner dismissal, so the agent sees what a user sees, not a consent modal.

Setup: Claude Code

claude mcp add --transport http snaplab https://snaplab.dev/mcp \
  --header "Authorization: Bearer sk_live_…"

Get a key at snaplab.dev/app/keys. The free tier is 100 renders a month, no card.

Setup: Claude Desktop or Cursor

Add this to your MCP config (claude_desktop_config.json, or Cursor → Settings → MCP):

{
  "mcpServers": {
    "snaplab": {
      "type": "http",
      "url": "https://snaplab.dev/mcp",
      "headers": { "Authorization": "Bearer sk_live_…" }
    }
  }
}

That is the whole install. Streamable HTTP, no npm package, no Docker, nothing to keep updated.

What it looks like in practice

You: Check the pricing page on staging at 390px wide and tell me if anything overflows.

Claude: (calls screenshot with url, mobile: true, fullPage: true) The plan cards stack correctly, but the comparison table overflows by about 180px; the third column is cut off. Here is the capture. Want me to make the table scroll horizontally on small screens?

Because the image comes back as an inline content block, the model reasons about the pixels directly. No OCR, no "please describe the page".

Other prompts that work well:

"Screenshot https://example.com in dark mode and compare it to the light version."
"Render this HTML as a 1200×630 card and show me." (paste the HTML)
"Make a PDF of the docs page and tell me how many pages it is."

Why hosted instead of a local Playwright MCP

A local browser MCP is great on your laptop. It is less great in CI, in a devcontainer, on a teammate's machine without Chromium, or inside an agent that runs in the cloud. A hosted server means every environment gets the same renderer, and the agent never has to install or babysit a browser.

The trade-off is that the renderer only sees what the public internet sees. For a local dev server, tunnel it (ngrok, Cloudflare Tunnel) or pass the HTML directly with html instead of url.

Security notes

The server refuses private and loopback addresses, cloud metadata endpoints and non-HTTP schemes, so an agent cannot be tricked into screenshotting your internal network.
Keys are hashed at rest and shown once. Revoke from the dashboard.
Nothing is stored beyond the render cache (24 h) and any captures you explicitly persist.

Beyond MCP

The same API behind the MCP server is a plain REST endpoint (POST /api/render), has signed URLs so you can put a screenshot straight into an <img> tag, an n8n community node, a JS SDK (npm i snaplab), and an Apify actor. Docs: snaplab.dev/docs.

If you try it with your agent, I would like to hear what it got right and where it fell short. Reply here or email snaplab@hsingh.app.