Sys.Pdf
Sys.Pdf works with PDF documents in server-side code. SimplePdf creates PDFs from HTML and opens existing PDFs for editing. The functions detect PDFs and scanned PDFs, render pages as PNG images, black out areas, and convert Word documents to PDF.
Functions that take BinaryOrBase64 accept a Buffer, ArrayBuffer, Uint8Array or Base64 string.
Availability: Server
Functions
Section titled “Functions”isPdf()
Section titled “isPdf()”isPdf(bufferOrBase64: Buffer | string): booleanChecks whether the data is a PDF, by looking for the %PDF- header at its start.
| Parameter | Type | Description |
|---|---|---|
bufferOrBase64 | Buffer | string | The data, as a Buffer or Base64 string. |
Returns: boolean · Availability: Server
isScannedPdf()
Section titled “isScannedPdf()”isScannedPdf(buffer: Buffer): booleanisScannedPdf(bufferOrBase64: Buffer | FsBasePath, pathComponents?: string | string[]): Promise<boolean>Checks whether a PDF has no text layer, as is typical for scanned documents. Lowgile treats a PDF as scanned when it contains no font object. Pass a Buffer to get the answer directly, or a file system base path and path components to check a file through Sys.Fs.
| Parameter | Type | Description |
|---|---|---|
bufferOrBase64 | Buffer | FsBasePath | The PDF as a Buffer, or the base path of a file, such as 'data' or 'tmp'. A Base64 string is not accepted. |
pathComponents | string | string[] | Path of the file below the base path. Only used with a base path. |
Returns: boolean for a Buffer, otherwise Promise<boolean> · Availability: Server
toPngImages()
Section titled “toPngImages()”toPngImages(bufferOrBase64s: BinaryOrBase64 | BinaryOrBase64[], options?: PdfToImageOptions): Promise<Buffer<ArrayBufferLike>[]>Renders every page of one or more PDFs as an image, using the pdf-to-img package (version ^6.2.0).
| Parameter | Type | Description |
|---|---|---|
bufferOrBase64s | BinaryOrBase64 | BinaryOrBase64[] | One PDF or a list of PDFs. |
options | PdfToImageOptions | Rendering options. |
PdfToImageOptions fields
| Field | Type | Required | Description |
|---|---|---|---|
format | "png" | "jpg" | "jpeg" | No | Image format. Default: png. |
password | string | No | Password of an encrypted PDF. |
scale | number | No | Zoom factor; higher values give larger, sharper images. Default: 2. |
renderParams | object | No | Further render parameters passed to pdf.js. |
docInitParams | object | No | Further document parameters passed to pdf.js. |
Returns: Promise<Buffer[]>, one image per page, the pages of all PDFs in order · Availability: Server
redactPdf()
Section titled “redactPdf()”redactPdf(pdfData: BinaryOrBase64, redactionBoxes: RedactionBox[][]): Promise<Buffer>Blacks out areas of a PDF and permanently removes the content beneath them, then removes the document metadata. The work is done by Lowgile Support Services, which must be configured for the instance (LOWGILE_SUPPORT_SERVICES_URL).
| Parameter | Type | Description |
|---|---|---|
pdfData | BinaryOrBase64 | The PDF. |
redactionBoxes | RedactionBox[][] | One array of boxes per page, in page order. Pass an empty array for a page without redactions. The outer array must have one entry per page. |
RedactionBox fields
Coordinates are percentages of the page width and height, from 0 to 100, measured from the top-left corner.
| Field | Type | Required | Description |
|---|---|---|---|
x1 | number | Yes | Left edge. |
y1 | number | Yes | Top edge. |
x2 | number | Yes | Right edge. |
y2 | number | Yes | Bottom edge. |
Returns: Promise<Buffer>, the redacted PDF · Availability: Server
convertDocxToPdf()
Section titled “convertDocxToPdf()”convertDocxToPdf(docxData: BinaryDataOrFile): Promise<BinaryFile<Buffer>>Converts a Word document to PDF. The conversion is done by Lowgile Support Services, which must be configured for the instance.
| Parameter | Type | Description |
|---|---|---|
docxData | BinaryDataOrFile | The document, either as binary data or as a file object with data, fileName and mimeType. The extension of fileName tells the converter the format; default: docx. |
Returns: Promise<BinaryFile<Buffer>>: the PDF in data, the file name with the extension changed to .pdf in fileName (default Document.pdf), and application/pdf in mimeType · Availability: Server
Note
File and Blob objects are part of the declared BinaryData type, but the conversion throws an Unsupported input type error for them. The same applies to toPngImages() and redactPdf().
Classes
Section titled “Classes”SimplePdf
Section titled “SimplePdf”Creates and opens PDF documents. The documents it returns are pdf-lib PDFDocument objects (npm package pdf-lib, version ^1.17.1): you can add pages, draw text and images, fill forms, and save the result with save().
const doc = await Sys.Pdf.SimplePdf.createPdfFromHtml('<h1>Order confirmation</h1>', { pageSize: 'A4', orientation: 'Portrait',})const page = doc.getPages()[0]page.drawText('Paid', { x: 50, y: 50, size: 24, color: Sys.Pdf.SimplePdf.Color.rgb(0, 0.5, 0) })const pdfBytes = await doc.save()createPdfFromHtml()
Section titled “createPdfFromHtml()”createPdfFromHtml(html: string, options?: CreatePdfOptions): Promise<SimplePdfDocument>Renders HTML to a PDF with wkhtmltopdf, which must be installed on the server, and opens the result for editing.
| Parameter | Type | Description |
|---|---|---|
html | string | The HTML document. |
options | CreatePdfOptions | Page size, margins, headers and footers and further wkhtmltopdf options. |
Returns: Promise<SimplePdfDocument> · Availability: Server
createBlankPdf()
Section titled “createBlankPdf()”createBlankPdf(options?: CreatePdfOptions): Promise<SimplePdfDocument>Creates a PDF with one empty page, rendered by wkhtmltopdf with the given options.
| Parameter | Type | Description |
|---|---|---|
options | CreatePdfOptions | Page size, margins and further wkhtmltopdf options. |
Returns: Promise<SimplePdfDocument> · Availability: Server
openExistingPdf()
Section titled “openExistingPdf()”openExistingPdf(buffer: ArrayBuffer | Buffer | string | Uint8Array): Promise<SimplePdfDocument>Opens an existing PDF for reading and editing, with pdf-lib’s PDFDocument.load.
| Parameter | Type | Description |
|---|---|---|
buffer | ArrayBuffer | Buffer | string | Uint8Array | The PDF, as bytes or as a Base64 string. |
Returns: Promise<SimplePdfDocument> · Availability: Server
const Fonts: typeof StandardFontsThe 14 standard PDF fonts, such as Helvetica or TimesRoman, for doc.embedFont(Sys.Pdf.SimplePdf.Fonts.Helvetica).
Type: typeof StandardFonts · Availability: Server
const Color: { rgb: (red: number, green: number, blue: number) => RGB cmyk: (cyan: number, magenta: number, yellow: number, key: number) => CMYK grayscale: (gray: number) => Grayscale}Creates colours for drawing with pdf-lib. Every component is a number from 0 to 1. The colour types are available as SimplePdf.Color.Color, SimplePdf.Color.RGB, SimplePdf.Color.CMYK and SimplePdf.Color.Grayscale.
Type: object · Availability: Server
CreatePdfOptions
Section titled “CreatePdfOptions”type CreatePdfOptions = Omit<Parameters<typeof WkHtmlToPdf>[1], (typeof ForbiddenWkOptions)[number]>The options of the wkhtmltopdf npm package (version ^0.4.0), such as pageSize, orientation, marginTop or footerCenter. For security, options that give access to the server, run scripts or write files are not allowed: output, allow, cacheDir, disableJavascript, enableJavascript, disableLocalFileAccess, enableLocalFileAccess, disablePlugins, enablePlugins, postFile, runScript, sslCrtPath, sslKeyPath and sslKeyPassword. Lowgile also removes them at runtime.
Availability: Server
SimplePdfDocument
Section titled “SimplePdfDocument”interface SimplePdfDocument extends Omit<PDFDocument, (typeof ForbiddenPdfDocumentMethods)[number]> {}A pdf-lib PDFDocument without the addJavaScript method, which Lowgile blocks.
Availability: Server
Related
Section titled “Related”- Sys.Image
- Sys.Fs
- Generate PDFs from data
- Extract structured data from a PDF
- Sys API overview