pdf4me

TypeScript/JavaScript ESM client for the PDF4me API. Convert, optimize, merge, split, stamp, and extract content from documents with async functions and typed results. Provides 106 actions across 18 modules.

Requires Node.js 22 or newer and a PDF4me API key.

• API reference for every action: https://docs.pdf4me.com/pdf4me-api/
• Create an API key: https://dev.pdf4me.com/dashboard/#/api-keys/

Installation

npm install pdf4me@^10

This README describes the ESM API in version 10. For a source checkout, run npm install and npm run build in this package directory, then run npm install /absolute/path/to/pdf4me from your application directory.

Upgrading from 9.x

Version 10 is a rewrite. A ^9 dependency range will not pick up version 10 on its own; pin pdf4me@^9.10.15 to stay on 9.x.

Two changes break every call site, so you will find them immediately:

• ESM only. require("pdf4me") no longer resolves. Use import.
• A client plus standalone actions. pdf4me.createClient(key) returning one object of methods is replaced by new Pdf4meClient(key) plus action functions imported from subpaths, called as action(client, source, options).

Three more changes compile and run, but misbehave. These are worth checking by hand:

• Binary results are Uint8Array, not Buffer. Buffer subclasses Uint8Array, so writeFile and friends still work — but Buffer-only methods quietly produce nonsense rather than throwing:

  result.toString("base64"); // 9.x: base64. 10: "0,255,65,128"
  Buffer.from(result).toString("base64"); // do this instead

• Every action polls. Version 10 submits isAsync: true and polls until the job completes, so a call that was one round trip may now block for up to maxWait (default 300 000 ms) and can throw Pdf4meTimeoutError — a failure mode 9.x did not have.

• Redirects are rejected. 9.x followed them; version 10 sets redirect: "error". If you route traffic through a proxy that answers 3xx, point baseUrl at the final destination.

Also: Node 22 is now required and declared in engines, but npm only warns on a mismatch by default — a project still on Node 18 will install version 10 and fail at runtime. Thumbnail creation (createThumbnail/createThumbnails) and PDF/A validation (validate/validateDocument) have no version 10 equivalent, as the v2 API does not expose them. The license changed from ISC to MIT.

The full method-by-method mapping, including renames and the integrationConfig replacement, ships with the package as MIGRATION.md — read it at node_modules/pdf4me/MIGRATION.md after installing.

Quick start

Set your API key in the environment:

export PDF4ME_API_KEY="your-api-key"

Save this as optimize-pdf.mjs and put an input.pdf in the same working directory. The example uploads the PDF for optimization and saves the result as optimized.pdf.

import { readFile, writeFile } from "node:fs/promises";
import { Pdf4meClient } from "pdf4me";
import { optimize } from "pdf4me/optimize";

const apiKey = process.env.PDF4ME_API_KEY;
if (!apiKey) {
  throw new Error("Set PDF4ME_API_KEY before running this example.");
}

const client = new Pdf4meClient(apiKey);
const data = await readFile("input.pdf");
const result = await optimize(client, data, { docName: "input.pdf" });
await writeFile("optimized.pdf", result);
console.log("Saved optimized.pdf");

Run it with:

node optimize-pdf.mjs

The same imports work in TypeScript ESM projects, with types included in the package. Actions take a reusable client first, source content next (when applicable), and an options object last.

Requests and results

Every action submits isAsync: true and awaits the completed result. Both an immediate HTTP 200 and an HTTP 202 job followed by polling are supported. File actions return Uint8Array, accepted by Node's writeFile. JSON actions return typed models, such as DocMetadata or SplitPdfRes. Models and enum constants are exported from the action's module and the models subpath. Unknown response fields are retained in additionalData.

Source content accepts a Uint8Array (including Node Buffer), base64 string, pdf4meblobid://... reference, or URL. Bytes are base64-encoded automatically. Actions with multiple inputs accept ordered arrays; addAttachmentToPdf takes an attachments object mapping filenames to content.

import { merge } from "pdf4me/merge-split";
import { stamp, StampAlignX } from "pdf4me/edit";

const merged = await merge(client, [firstPdf, secondPdf]);
const stamped = await stamp(client, merged, {
  text: "DRAFT",
  alignX: StampAlignX.Center,
});

All options interfaces are exported, for example OptimizeOptions. The default optimize profile is Max. Explicit null does not select a default. Every action accepts extra, an object serialized as additional request fields. Use the API's field names and avoid keys already supplied by the action options.

Client configuration and errors

const client = new Pdf4meClient(apiKey, {
  baseUrl: "https://api.pdf4me.com",
  timeout: 100_000,
  maxWait: 300_000,
  pollInterval: 10_000,
});

All durations are milliseconds (the Python client uses seconds). timeout caps each request, including reading its body. maxWait caps polling after the initial job submission, including in-flight status requests. Numeric and HTTP-date Retry-After values control polling; pollInterval is the fallback.

Failures throw Pdf4meException, with message, responseStatusCode, traceId and responseHeaders. Request/job time limits throw Pdf4meTimeoutError. Malformed queued responses and invalid local inputs throw ordinary errors. Network failures propagate from fetch. Authentication uses Authorization: Basic <apiKey> and HTTP redirects are rejected. The library does not log credentials or documents. Fetch owns its connection pool; no client close method is needed. A custom fetch can be supplied for testing or transport configuration.

Modules

| Import subpath | Actions | | ------------------------ | ------: | | ai-document-extraction | 14 | | barcode | 7 | | convert | 13 | | edit | 7 | | excel | 1 | | extract | 8 | | find-search | 2 | | forms | 2 | | generate | 6 | | image | 13 | | merge-split | 5 | | optimize | 1 | | organize | 5 | | pdf | 16 | | pdf4me | 1 | | security | 2 | | word | 2 | | zugferd | 1 |

License

MIT. The full text ships with the package as LICENSE.