hookpdf

Official Node.js SDK for the HookPDF API — generate professional PDFs from HTML/CSS templates.

Install

npm i hookpdf

Requires Node.js 18+. Zero external dependencies.

Quick Start

const HookPDF = require('hookpdf');

const client = new HookPDF('hp_live_your_api_key');

// 1. Start a render job
const job = await client.render({
  templateId: 'your-template-id',
  payload: {
    customer_name: 'John Doe',
    invoice_no: 'INV-2026-001',
    total: 1250.00
  }
});

console.log(`Job queued: ${job.jobId}`);

// 2. Wait for completion and get the PDF URL
const report = await client.waitForReport(job.jobId);
console.log(`PDF ready: ${report.outputUrl}`);

ES Modules

import HookPDF from 'hookpdf';

const client = new HookPDF('hp_live_your_api_key');

API Reference

new HookPDF(apiKey, options?)

Create a new client instance.

| Parameter | Type | Default | Description | |-----------|------|---------|-------------| | apiKey | string | — | Your HookPDF API key | | options.baseUrl | string | https://api.hookpdf.com | API base URL | | options.timeout | number | 30000 | Request timeout (ms) |

client.render(params)

Enqueue a PDF render job.

const job = await client.render({
  templateId: 'uuid-here',
  payload: { name: 'John', date: '2026-03-05' },
  options: {
    pageSize: 'A4',           // default: 'A4'
    orientation: 'portrait',   // 'portrait' | 'landscape'
    locale: 'en-US'           // default: 'en-US'
  }
});
// → { jobId, status, isPreview }

client.renderPreview(params)

Same as render() but generates a watermarked, short-lived preview PDF. Does not count toward your credit quota.

const preview = await client.renderPreview({
  templateId: 'uuid-here',
  payload: { name: 'Test' }
});

client.getReport(jobId)

Get the current status of a render job.

const report = await client.getReport('job-uuid');
// → { id, templateId, status, outputUrl, errorCode, errorMessage, isPreview, createdAt, completedAt }

client.waitForReport(jobId, options?)

Poll until the job completes or fails.

| Parameter | Type | Default | Description | |-----------|------|---------|-------------| | options.interval | number | 2000 | Polling interval (ms) | | options.timeout | number | 120000 | Max wait time (ms) |

const report = await client.waitForReport(job.jobId, {
  interval: 3000,
  timeout: 60000
});

if (report.outputUrl) {
  console.log('Download:', report.outputUrl);
}

Error Handling

All API errors throw HookPDFError with structured details:

const { HookPDFError } = require('hookpdf');

try {
  await client.render({ templateId: 'bad-id', payload: {} });
} catch (err) {
  if (err instanceof HookPDFError) {
    console.error(err.message);     // Human-readable message
    console.error(err.status);      // HTTP status code (e.g. 401, 429)
    console.error(err.errorCode);   // API error code (e.g. 'INVALID_TEMPLATE')
    console.error(err.requestId);   // Request ID for support
  }
}

TypeScript

Full TypeScript definitions are included out of the box — no @types package needed.

import HookPDF, { Report, HookPDFError } from 'hookpdf';

const client = new HookPDF('hp_live_xxx');
const report: Report = await client.waitForReport('job-id');

Links

• HookPDF Website
• API Documentation
• Dashboard

License

MIT