API Reference

Complete reference for all functions exported by @pdfsamurai/pdfsamurai-js.

generatePdf

Generates a PDF from a template.

import { generatePdf } from "@pdfsamurai/pdfsamurai-js";

const pdf = await generatePdf({
  templateId: "your-template-id",
  dynamicData: { customerName: "John Doe" },
});

Parameters

Name	Type	Required	Description
templateId	string	Yes	The ID of the template to generate
dynamicData	Object	No	Key-value pairs to replace template placeholders
apiKey	string	No	API key. Overrides the global key set with configure()

note

A developer key must be set via configure() before calling this function. See Authentication.

Returns Promise<Blob> in the browser, Promise<Buffer> in Node.js.

generatePdfBase64

Same as generatePdf, but returns the PDF as a base64-encoded string instead of a binary.

import { generatePdfBase64 } from "@pdfsamurai/pdfsamurai-js";

const base64 = await generatePdfBase64({
  templateId: "your-template-id",
  dynamicData: { customerName: "John Doe" },
});

Parameters — same as generatePdf.

Returns Promise<string>.

getTemplates

Fetches the list of templates available for the given API key.

import { getTemplates } from "@pdfsamurai/pdfsamurai-js";

const templates = await getTemplates();

Parameters

Name	Type	Required	Description
apiKey	string	No	API key. Overrides the global key set with configure()

Returns Promise<Array>.

getTemplateDynamicDataKeys

Fetches the dynamic data keys defined in a template. Useful for discovering which placeholders a template expects.

import { getTemplateDynamicDataKeys } from "@pdfsamurai/pdfsamurai-js";

const keys = await getTemplateDynamicDataKeys({
  templateId: "your-template-id",
});

Parameters

Name	Type	Required	Description
templateId	string	Yes	The ID of the template
apiKey	string	No	API key. Overrides the global key set with configure()

Returns Promise<Array>.

configure

Sets global configuration for all subsequent function calls. You must call configure() with at least a developerKey before using any other function.

import { configure } from "@pdfsamurai/pdfsamurai-js";

configure({
  apiKey: "your-api-key",
  developerKey: "your-developer-key",
  urlAccessPolicy: myPolicy,
});

Parameters

Name	Type	Required	Description
apiKey	string	No	API key used by all subsequent calls
developerKey	string	No	Developer key that identifies your app or integration. See Integration — Developer keys
urlAccessPolicy	function	No	Controls which URLs can be fetched when templates reference external images via dynamic data. See URL Access Policy

preloadEngine

Preloads the WASM engine used for PDF generation. Call this ahead of time to make the first generatePdf call faster.

import { preloadEngine } from "@pdfsamurai/pdfsamurai-js";

const binary = await preloadEngine();

Returns Promise<ArrayBuffer> — the WASM binary, which can be passed to setPreloadedWasmBinary.

setPreloadedWasmBinary

Sets a preloaded WASM binary for the engine to use. This is useful in Node.js worker thread setups where you want to load the binary once in the main thread and share it across workers, avoiding redundant downloads.

import { preloadEngine, setPreloadedWasmBinary } from "@pdfsamurai/pdfsamurai-js";

// Main thread: load once
const binary = await preloadEngine();

// Worker thread: reuse the binary
setPreloadedWasmBinary(binary);

Parameters

Name	Type	Required	Description
binary	ArrayBuffer	Yes	The WASM binary returned by preloadEngine()

cleanup

Cleans up cached resources (fonts, images, templates, auth tokens) and terminates background Web Workers. Works in both browser and Node.js.

Call this when you no longer need PDF generation to free memory. Subsequent calls to any generation function will reinitialize resources automatically.

import { cleanup } from "@pdfsamurai/pdfsamurai-js";

cleanup();

createUrlAccessPolicy

Creates a URL access policy that adds restrictions on top of the built-in SSRF protection. See URL Access Policy for full details.

import { createUrlAccessPolicy } from "@pdfsamurai/pdfsamurai-js";

const policy = createUrlAccessPolicy({
  allowedDomains: ["cdn.myapp.com"],
  requireHttps: true,
});

Parameters

Name	Type	Required	Description
allowedDomains	string[]	No	Only allow these hostnames
requireHttps	boolean	No	Block plain HTTP, only allow HTTPS. Default: false

Returns a callback compatible with configure({ urlAccessPolicy }).

Error codes

All functions throw PdfSamuraiError on failure. The code property identifies the type of error:

Code	Description
INVALID_INPUT	Missing or invalid parameters
UNAUTHORIZED	Invalid or missing API key
NETWORK_ERROR	Failed to reach the PDFSamurai API
PDF_GENERATION_FAILED	PDF generation failed
WASM_INIT_FAILED	WASM engine failed to initialize
WASM_LOAD_FAILED	WASM engine failed to load
WORKER_FAILED	Web Worker failed
TIMEOUT	Operation timed out

import { generatePdf, PdfSamuraiError } from "@pdfsamurai/pdfsamurai-js";

try {
  const pdf = await generatePdf({ templateId: "abc123" });
} catch (error) {
  if (error instanceof PdfSamuraiError) {
    console.error(error.code, error.message);
  }
}