Skip to content
superPDF

superPDF AI for JavaScript and TypeScript

The superPDF AI SDK for Node.js: every PDF tool as a typed async function, run on your computer. npm install @superpdf/cli.

The @superpdf/cli package includes a typed SDK for Node.js: every superPDF AI tool is an async function that runs in your process, with no server and no subprocess. It is the same code as the CLI, the MCP server, the local API and the Python package, so results match everywhere. Nothing is uploaded.

Install

Terminal
npm install @superpdf/cli

Node.js 22 or later, on macOS, Linux or Windows. TypeScript types come with the package. It works with import and with require().

Read a PDF

TypeScript
import { exportPages, exportPdf, exportJson } from '@superpdf/cli';

const markdown = await exportPdf('report.pdf');            // headings, tables, charts, OCR
const html = await exportPdf('report.pdf', { format: 'html', pages: '1-3' });
const pages = await exportPages('report.pdf');             // [{ page: 1, markdown: '…' }]
const structure = await exportJson('report.pdf');          // title, pages, sections

Each takes a path or the PDF’s bytes (a Buffer or Uint8Array), and the options pages (such as "1, 3-5"), tables: 'html' (Markdown tables as HTML, keeping merged header cells), ocr: false to skip OCR on scanned pages, and onMessage for progress notes.

Convert, edit and compare

Every tool is a function named after it (pdf_to_docx is toDocx) that takes the tool’s input, with the same field names as the MCP server and the API, and returns its typed result:

TypeScript
import { toDocx, extractTables, merge, fillForm, compare } from '@superpdf/cli';

const word = await toDocx({ input: 'report.pdf', output: 'report.docx' });
console.log(word.tables, 'tables');

await extractTables({ input: 'report.pdf', format: 'csv', output: 'tables.csv' });
await merge({ inputs: ['a.pdf', 'b.pdf'], output: 'combined.pdf' });
await fillForm({ input: 'form.pdf', values: { Name: 'Ada' }, output: 'filled.pdf' });

const changes = await compare({ before: 'v1.pdf', after: 'v2.pdf' });
console.log(changes.summary);   // 1 of 4 pages changed: page 3.
GroupFunctions
Read and compareinfo, listFiles, readText, extractStructure, outline, compare
ConverttoDocx, toPptx, toEpub, extractTables, fromImages, fromMarkdown, fromOffice
Pagesmerge, split, extractPages, removePages, rotatePages, resizePages
ChangeaddPageLabels, addWatermark, addText, fillForm, flatten, removeMetadata, repair, protect, unlock
Several steps or filesrunPipeline, runBatch

tools() lists every tool with its JSON input schema, and runTool(name, input) runs one by its tool name. Fields and results are listed in the endpoint reference; the SDK takes the same inputs.

TypeScript

The types are generated from the tool schemas, so the compiler checks field names, required fields and allowed values:

TypeScript
import { rotatePages, toDocx, type ToDocxResult } from '@superpdf/cli';

const result: ToDocxResult = await toDocx({ input: 'report.pdf', output: 'report.docx' });

// Error: angle must be 90, 180 or 270
await rotatePages({ input: 'report.pdf', angle: 45, output: 'rotated.pdf' });

Each tool has an input type and a result type named after its function, such as ToDocxInput and ToDocxResult.

Paths, folders and progress

  • Paths may be absolute or relative to the current folder.
  • Folders: each call may only use the folders of the paths you give it. To set them yourself, pass { allowDirs: ['/path/to/folder'] } as the second argument.
  • Outputs must not exist yet; superPDF never overwrites a file.
  • Progress: long tools such as runBatch report { onProgress: (done, total, message) => … }.
TypeScript
import { runBatch } from '@superpdf/cli';

await runBatch(
  {
    inputs: ['reports/q1.pdf', 'reports/q2.pdf'],
    steps: [{ action: 'watermark', options: { text: 'DRAFT' } }],
    output_folder: 'reports/drafts',
  },
  {
    allowDirs: ['reports'],
    onProgress: (done, total) => console.log(`${done}/${total}`),
  },
);

Errors

Every failure throws SuperPDFError with superPDF’s message and a code: validation, conflict (the output already exists), not_found, busy or operation_failed. Invalid input also lists each field in errors.

TypeScript
import { toDocx, SuperPDFError } from '@superpdf/cli';

try {
  await toDocx({ input: 'report.pdf', output: 'report.docx' });
} catch (error) {
  if (error instanceof SuperPDFError && error.code === 'conflict') {
    console.log('report.docx already exists');
  }
}

Source and releases

superPDF AI’s command-line tool, MCP server, local API and Python package are open source (Apache-2.0).