npm package: @solisoft/pdfx
Description: A Node.js wrapper for the pdfx.fr API - the fastest, most eco-friendly PDF generation service for developers
Author: Solisoft
Latest version: 1.0.0

# Pdfx Node.js Module

A Node.js wrapper for the [pdfx.fr](https://pdfx.fr) API - the fastest, most eco-friendly PDF generation service for developers.

## Installation

```bash
npm install @solisoft/pdfx
```

Or with yarn:

```bash
yarn add @solisoft/pdfx
```

## Configuration

Configure the module with your API key:

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

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

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

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

## Usage

### Basic Usage

```javascript
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:

```javascript
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:

```javascript
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:

```typescript
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:

```bash
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](https://opensource.org/licenses/MIT).

## About pdfx.fr

[pdfx.fr](https://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](https://pdfx.fr) to create your account and get your API key.