Pdfx Node.js Module

A Node.js wrapper for the pdfx.fr API - the fastest, most eco-friendly PDF generation service for developers.

Installation

npm install @solisoft/pdfx

Or with yarn:

yarn add @solisoft/pdfx

Configuration

Configure the module with your API key:

const pdfx = require('@solisoft/pdfx');

pdfx.configure({
  apiKey: 'your-api-key-here'
});

You can also set a custom base URL (useful for testing):

pdfx.configure({
  apiKey: 'your-api-key-here',
  baseUrl: 'https://custom-pdfx-instance.com'
});

Usage

Basic Usage

const pdfx = require('@solisoft/pdfx');
const fs = require('fs');

// Configure globally
pdfx.configure({
  apiKey: 'your-api-key'
});

// Create a client
const client = new pdfx.Client();

// Generate a PDF
async function generateInvoice() {
  try {
    const pdfData = await client.generatePdf({
      templateUuid: 'ea99e8b9-1234-5678-90ab-cdef12345678',
      data: {
        invoice: '001',
        customer: 'Acme Corp',
        amount: 1299
      }
    });

    // Save to file
    fs.writeFileSync('invoice.pdf', pdfData);
    console.log('PDF generated successfully!');
  } catch (error) {
    console.error('Error generating PDF:', error);
  }
}

generateInvoice();

Using Client-Specific API Key

You can override the global API key for specific clients:

const client = new pdfx.Client({ apiKey: 'different-api-key' });

const pdfData = await client.generatePdf({
  templateUuid: 'ea99e8b9-1234-5678-90ab-cdef12345678',
  data: { invoice: '002', customer: 'Beta Inc', amount: 2500 }
});

Error Handling

The module provides specific error classes for different scenarios:

const {
  Client,
  AuthenticationError,
  RequestError,
  ServerError,
  NetworkError,
  PdfxError
} = require('@solisoft/pdfx');

const client = new Client({ apiKey: 'your-api-key' });

try {
  const pdfData = await client.generatePdf({
    templateUuid: 'ea99e8b9-1234-5678-90ab-cdef12345678',
    data: { invoice: '003' }
  });
  
  fs.writeFileSync('output.pdf', pdfData);
} catch (error) {
  if (error instanceof AuthenticationError) {
    console.error('Invalid API key:', error.message);
  } else if (error instanceof RequestError) {
    console.error('Bad request:', error.message);
  } else if (error instanceof ServerError) {
    console.error('Server error:', error.message);
  } else if (error instanceof NetworkError) {
    console.error('Network error:', error.message);
  } else if (error instanceof PdfxError) {
    console.error('General error:', error.message);
  } else {
    console.error('Unexpected error:', error);
  }
}

TypeScript Support

This module includes TypeScript definitions:

import { Client, configure, GeneratePdfParams } from '@solisoft/pdfx';

configure({
  apiKey: 'your-api-key'
});

const client = new Client();

const params: GeneratePdfParams = {
  templateUuid: 'ea99e8b9-1234-5678-90ab-cdef12345678',
  data: {
    invoice: '001',
    customer: 'Acme Corp',
    amount: 1299
  }
};

const pdfData: Buffer = await client.generatePdf(params);

API Reference

configure(options)

Configure the module globally.

Parameters:

• apiKey (String): Your pdfx.fr API key
• baseUrl (String): Base URL for the API (default: "https://pdfx.fr")

new Client(options)

Create a new client instance.

Parameters:

• apiKey (String, optional): Override the global API key
• baseUrl (String, optional): Override the global base URL

client.generatePdf(params)

Generate a PDF using a template.

Parameters:

• templateUuid (String, required): The UUID of your template
• data (Object, optional): Data to interpolate into the template

Returns: Promise<Buffer> - The PDF binary data

Throws:

• AuthenticationError: Invalid API key
• RequestError: Invalid request parameters
• ServerError: Server error (5xx)
• NetworkError: Network connectivity issues

Error Classes

• PdfxError - Base error class
• AuthenticationError - Invalid API key (401)
• RequestError - Bad request (400)
• ServerError - Server error (5xx)
• NetworkError - Network connectivity issues

Development

Clone the repository and install dependencies:

git clone https://github.com/solisoft/pdfx-js.git
cd pdfx-js
npm install

Contributing

Bug reports and pull requests are welcome on GitHub at https://github.com/solisoft/pdfx-js.

License

The module is available as open source under the terms of the MIT License.

About pdfx.fr

pdfx.fr is a blazing-fast PDF generation API that:

• Generates PDFs in sub-100ms
• Supports Factur-X/ZUGFeRD e-invoicing
• Stores zero data (privacy by design)
• Runs on 100% renewable energy
• Offers 200 free PDFs per month

Visit pdfx.fr to create your account and get your API key.