@formepdf/sdk

TypeScript client for the Forme hosted PDF API.

Installation

npm install @formepdf/sdk

Quick start

import { Forme } from '@formepdf/sdk';

const forme = new Forme('your-api-key');

// Render a template to PDF
const pdf = await forme.render('invoice', {
  customerName: 'Acme Corp',
  items: [{ name: 'Widget', price: 9.99 }],
});

// pdf is a Uint8Array — write to file, return as response, etc.
await fs.writeFile('invoice.pdf', pdf);

// Extract embedded data from a PDF
const data = await forme.extract(pdf);
// data === { customerName: 'Acme Corp', items: [...] }

Constructor

new Forme(apiKey: string, options?: { baseUrl?: string })

| Option | Default | Description | | --------- | ---------------------------- | ------------------------ | | baseUrl | https://api.formepdf.com | API base URL |

Methods

render(slug, data?, options?)

Render a template to PDF bytes.

• slug — Template identifier
• data — Template data (sent as JSON body, defaults to {})
• options.s3 — Optional S3 upload config ({ bucket, key, accessKeyId, secretAccessKey, region?, endpoint? })
• Returns Promise<Uint8Array> (or Promise<{ url: string }> when s3 is provided)

renderAsync(slug, data?, options?)

Start an async render job.

• options.webhookUrl — URL to receive a POST when the job completes
• Returns Promise<{ jobId: string; status: string }>

getJob(jobId)

Poll an async job's status.

• Returns Promise<JobResult> — includes pdfBase64 when complete

merge(pdfs)

Merge multiple PDFs into one.

• pdfs — Array of Uint8Array (2–20 PDFs)
• Returns Promise<Uint8Array>

certify(pdf, options)

Certify a PDF with an X.509 digital certificate.

• pdf — PDF file bytes
• options.certificate — PEM-encoded certificate string
• options.privateKey — PEM-encoded private key string
• options.certificateId — Or use a saved certificate ID (instead of raw PEM)
• options.reason / options.location / options.contact — Optional metadata
• Returns Promise<Uint8Array>

redact(pdf, options)

Redact sensitive content from a PDF.

• pdf — PDF file bytes
• options.patterns — Array of { pattern, pattern_type: 'Literal' | 'Regex' }
• options.presets — Built-in presets like ['ssn', 'email', 'phone']
• options.template — Saved redaction template slug
• options.redactions — Explicit regions { page, x, y, width, height }[]
• Returns Promise<Uint8Array>

extract(pdf)

Extract embedded data from a PDF generated by Forme.

• pdf — PDF file bytes
• Returns Promise<unknown | null> — null if the PDF has no embedded data

Error handling

import { Forme, FormeError } from '@formepdf/sdk';

try {
  const pdf = await forme.render('invoice', data);
} catch (err) {
  if (err instanceof FormeError) {
    console.error(`API error ${err.status}: ${err.message}`);
  }
}

Requirements

Node.js 18+ (uses global fetch).