pdfnoodle

Node.js SDK for the PDFNoodle API.

Features

TypeScript-first with full type definitions
Dual ESM/CJS support
Zero runtime dependencies (uses native fetch)
Automatic polling with exponential backoff for long-running PDF generations
Consistent { data, error } response pattern

Installation

npm install pdfnoodle

Requires Node.js 20+.

Quick Start

import { PdfNoodle } from 'pdfnoodle';

const pdfnoodle = new PdfNoodle('pdfnoodle_api_...');
// or set PDFNOODLE_API_KEY environment variable

// Generate PDF from HTML
const { data, error } = await pdfnoodle.pdf.fromHTML({
  html: '<h1>Invoice #001</h1><p>Total: $100</p>',
  pdfParams: { format: 'A4', printBackground: true },
});

if (data) {
  console.log(data.signedUrl); // temporary download URL
}

API

Constructor

const pdfnoodle = new PdfNoodle(apiKey?: string);

The API key can be passed directly or read from the PDFNOODLE_API_KEY environment variable. The base URL defaults to https://api.pdfnoodle.com and can be overridden with PDFNOODLE_BASE_URL.

PDF Generation

// Synchronous HTML to PDF (auto-polls if server returns 202)
const result = await pdfnoodle.pdf.fromHTML(payload, pollingOptions?);

// Asynchronous HTML to PDF (requires webhook)
const result = await pdfnoodle.pdf.fromHTMLAsync(payload);

// Synchronous template to PDF (auto-polls if server returns 202)
const result = await pdfnoodle.pdf.fromTemplate(payload, pollingOptions?);

// Asynchronous template to PDF (requires webhook)
const result = await pdfnoodle.pdf.fromTemplateAsync(payload);

// Check generation status
const result = await pdfnoodle.pdf.getStatus(requestId);

Automatic Polling

When sync endpoints take longer than 30 seconds, the API returns a 202 status. The SDK automatically polls the status endpoint until completion. Configure polling behavior:

const result = await pdfnoodle.pdf.fromHTML(payload, {
  pollInterval: 2000,       // initial delay between polls (ms)
  maxAttempts: 20,           // max polls before timeout
  backoffMultiplier: 1.5,    // exponential backoff factor
  maxPollInterval: 10000,    // max delay cap (ms)
  signal: abortController.signal, // cancel polling
});

Templates

// Create a template (AI-powered)
const result = await pdfnoodle.templates.create({
  prompt: 'Create an invoice template',
  displayName: 'Standard Invoice',
});

// Get a template
const result = await pdfnoodle.templates.get(templateId);

// List all templates
const result = await pdfnoodle.templates.list();

// Get template variables schema
const result = await pdfnoodle.templates.getVariables(templateId);

Tools

// Get a signed upload URL
const result = await pdfnoodle.tools.getSignedUploadUrl(fileName?);

// Merge PDFs
const result = await pdfnoodle.tools.mergePdfs({ urls: [...] });

// Split PDF
const result = await pdfnoodle.tools.splitPdf({ url, splitMode: 'ranges', ranges: '1-3,5' });

// Compress PDF
const result = await pdfnoodle.tools.compressPdf({ url, compressLevel: 'medium' });

// Convert Markdown to PDF
const result = await pdfnoodle.tools.markdownToPdf({ markdown: '# Hello' });

// Update PDF metadata
const result = await pdfnoodle.tools.updatePdfMetadata({
  url,
  metadata: { title: 'Report', author: 'Acme' },
});

Response Pattern

All methods return { data, error }:

const { data, error } = await pdfnoodle.pdf.fromHTML({ html: '...' });

if (error) {
  console.error(error.name, error.message);
  return;
}

console.log(data.signedUrl);

License

MIT