@ulvio/html-to-pdf

Official TypeScript SDK for the Ulvio html-to-pdf microservice.

A thin, zero-dependency wrapper around the service's POST /api/html-to-pdf Server-Sent-Events endpoint. It streams progress events and resolves with the final result.

Talking to the hosted Ulvio platform instead of a self-hosted instance? Use @ulvio/client, whose htmlToPdf sub-client targets the platform gateway (with auth + rate limiting). This package talks directly to a standalone html-to-pdf service.

Install

npm install @ulvio/html-to-pdf

Requires Node.js 24+.

Configuration

import { HtmlToPdfClient } from '@ulvio/html-to-pdf';

const client = new HtmlToPdfClient({
  baseUrl: process.env.HTML_TO_PDF_URL, // e.g. http://localhost:3002
});

baseUrl is required. If it's missing when a method is called, the call throws an HtmlToPdfError with code not_configured — distinct from runtime/network errors, so misconfiguration is easy to detect:

import { HtmlToPdfError, NOT_CONFIGURED_CODE } from '@ulvio/html-to-pdf';

try {
  await client.convert({ html, outputMode: 'base64' });
} catch (err) {
  if (err instanceof HtmlToPdfError && err.code === NOT_CONFIGURED_CODE) {
    // surface a deployment-time configuration error
  }
  throw err;
}

You can also inject a custom fetch implementation via { fetch }.

Usage

Convert HTML to a base64 PDF

The html field must be base64-encoded. Use the exported encodeHtml helper, or the renderHtml convenience which encodes for you.

import { HtmlToPdfClient, encodeHtml } from '@ulvio/html-to-pdf';

const client = new HtmlToPdfClient({ baseUrl });

const { pdf } = await client.convert(
  { html: encodeHtml('<h1>Invoice</h1>'), outputMode: 'base64' },
  {
    onQueued: ({ position }) => console.log('queued at', position),
    onProcessing: ({ step, progress }) => console.log(step, progress),
  },
);
// `pdf` is a base64 string

renderHtml is the same thing for plain HTML:

const { pdf } = await client.renderHtml('<h1>Invoice</h1>', { format: 'A4' });

Render from a URL

const { pdf } = await client.convert({
  sourceUrl: 'https://example.com/invoice/1',
  outputMode: 'base64',
});

Upload the PDF directly to a presigned URL

Instead of returning the PDF, the service can PUT it to a presigned URL:

const { uploaded, bytes } = await client.convert({
  sourceUrl: 'https://example.com/invoice/1',
  uploadUrl: presignedPutUrl,
});

Provide exactly one input (html or sourceUrl) and exactly one output (outputMode: 'base64' or uploadUrl).

Render options

await client.convert({
  html: encodeHtml('<h1>Report</h1>'),
  outputMode: 'base64',
  options: {
    format: 'A4',                 // default A4
    printBackground: true,        // default true
    margin: { top: '1cm', bottom: '1cm' },
    displayHeaderFooter: true,
    headerTemplate: '<div style="font-size:8px">Header</div>',
    footerTemplate: '<div style="font-size:8px">Page <span class="pageNumber"></span></div>',
  },
});

Errors

Every failure surfaces as an HtmlToPdfError with a code:

| code | Meaning | | ---------------------- | --------------------------------------------------- | | not_configured | baseUrl was not set on the client | | request_failed | Non-2xx response (e.g. a 400 validation error) | | html_to_pdf_error | The service emitted an SSE error event | | html_to_pdf_truncated| The SSE stream ended without a complete event | | html_to_pdf_no_body | The response had no body to stream |

HtmlToPdfError also carries status (HTTP status, when available) and response (the parsed error body).

API

• new HtmlToPdfClient({ baseUrl, fetch? })
• client.convert(params, callbacks?) — base64 or upload mode (overloaded return type)
• client.renderHtml(html, options?, callbacks?) — convenience for plain HTML
• encodeHtml(html) — base64-encode a UTF-8 HTML string
• HtmlToPdfError, NOT_CONFIGURED_CODE

Exported types: HtmlToPdfConfig, PdfOptions, HtmlToPdfRequest (and the Base64/Upload variants), HtmlToPdfResponse (and variants), QueuedEvent, ProcessingEvent, HtmlToPdfCallbacks, ErrorResponseBody.

License

UNLICENSED — internal Ulvio package.