@generatepdfs/node-sdk 1.0.0

package/LICENSE

@@ -0,0 +1,28 @@
+MIT License
+
+Copyright (c) 2024 GeneratePDFs
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.
+
+
+
+
+
+
+

package/README.md

@@ -0,0 +1,165 @@
+# GeneratePDFs Node.js SDK
+
+Node.js SDK for the [GeneratePDFs.com](https://generatepdfs.com) API, your go-to place for HTML to PDF.
+
+Upload your HTML files, along with any CSS files and images to generate a PDF. Alternatively provide a URL to generate a PDF from it's contents.
+
+## Installation
+
+```bash
+npm install @generatepdfs/node-sdk
+```
+
+## Get your API Token
+
+Sign up for an account on [GeneratePDFs.com](https://generatepdfs.com) and head to the API Tokens section and create a new token.
+
+## Usage
+
+### Basic Setup
+
+```javascript
+import { GeneratePDFs } from '@generatepdfs/node-sdk';
+
+const client = GeneratePDFs.connect('YOUR_API_TOKEN');
+```
+
+### Generate PDF from HTML File
+
+```javascript
+import { GeneratePDFs } from '@generatepdfs/node-sdk';
+
+// Simple HTML file
+const pdf = await client.generateFromHtml('/path/to/file.html');
+
+// HTML file with CSS
+const pdf = await client.generateFromHtml(
+  '/path/to/file.html',
+  '/path/to/file.css'
+);
+
+// HTML file with CSS and images
+const pdf = await client.generateFromHtml(
+  '/path/to/file.html',
+  '/path/to/file.css',
+  [
+    {
+      name: 'logo.png',
+      path: '/path/to/logo.png',
+      mimeType: 'image/png' // Optional, will be auto-detected
+    },
+    {
+      name: 'photo.jpg',
+      path: '/path/to/photo.jpg'
+    }
+  ]
+);
+```
+
+### Generate PDF from URL
+
+```javascript
+const pdf = await client.generateFromUrl('https://example.com');
+```
+
+### Get PDF by ID
+
+```javascript
+// Retrieve a PDF by its ID
+const pdf = await client.getPdf(123);
+```
+
+### Working with PDF Objects
+
+The SDK returns `Pdf` objects that provide easy access to PDF information and downloading:
+
+```javascript
+// Access PDF properties
+const pdfId = pdf.getId();
+const pdfName = pdf.getName();
+const status = pdf.getStatus();
+const downloadUrl = pdf.getDownloadUrl();
+const createdAt = pdf.getCreatedAt();
+
+// Check if PDF is ready
+if (pdf.isReady()) {
+  // Download PDF content as Buffer
+  const pdfContent = await pdf.download();
+  
+  // Or save directly to file
+  await pdf.downloadToFile('/path/to/save/output.pdf');
+}
+
+// Refresh PDF data from the API (useful for checking status updates)
+const refreshedPdf = await pdf.refresh();
+if (refreshedPdf.isReady()) {
+  const pdfContent = await refreshedPdf.download();
+}
+```
+
+### Client Methods
+
+- `generateFromHtml(htmlPath: string, cssPath?: string | null, images?: ImageInput[]): Promise<Pdf>` - Generate a PDF from HTML file(s)
+- `generateFromUrl(url: string): Promise<Pdf>` - Generate a PDF from a URL
+- `getPdf(id: number): Promise<Pdf>` - Retrieve a PDF by its ID
+- `downloadPdf(downloadUrl: string): Promise<Buffer>` - Download PDF binary content from a download URL
+
+### PDF Object Methods
+
+- `getId(): number` - Get the PDF ID
+- `getName(): string` - Get the PDF filename
+- `getStatus(): string` - Get the current status (pending, processing, completed, failed)
+- `getDownloadUrl(): string` - Get the download URL
+- `getCreatedAt(): Date` - Get the creation date
+- `isReady(): boolean` - Check if the PDF is ready for download
+- `download(): Promise<Buffer>` - Download and return PDF binary content
+- `downloadToFile(filePath: string): Promise<boolean>` - Download and save PDF to a file
+- `refresh(): Promise<Pdf>` - Refresh PDF data from the API and return a new Pdf instance with updated information
+
+## Requirements
+
+- Node.js 18.0 or higher
+
+## Testing
+
+To run the test suite, execute:
+
+```bash
+npm test
+```
+
+To run tests with coverage:
+
+```bash
+npm run test:coverage
+```
+
+## Contributing
+
+Contributions and suggestions are **welcome** and will be fully **credited**.
+
+We accept contributions via Pull Requests on [GitHub](https://github.com/GeneratePDFs/node-sdk).
+
+### Pull Requests
+
+- **Follow JavaScript best practices** - Write clean, maintainable code
+- **Add tests!** - Your patch won't be accepted if it doesn't have tests.
+- **Document any change in behaviour** - Make sure the README / CHANGELOG and any other relevant documentation are kept up-to-date.
+- **Consider our release cycle** - We try to follow semver. Randomly breaking public APIs is not an option.
+- **Create topic branches** - Don't ask us to pull from your master branch.
+- **One pull request per feature** - If you want to do more than one thing, send multiple pull requests.
+- **Send coherent history** - Make sure each individual commit in your pull request is meaningful. If you had to make multiple intermediate commits while developing, please squash them before submitting.
+
+## Changelog
+
+See [CHANGELOG.md](CHANGELOG.md) for a history of changes.
+
+## License
+
+This project is licensed under the MIT License. See the [LICENSE](LICENSE) file for details.
+
+
+
+
+
+

package/package.json

@@ -0,0 +1,40 @@
+{
+  "name": "@generatepdfs/node-sdk",
+  "version": "1.0.0",
+  "description": "Node.js SDK for GeneratePDFs.com API",
+  "type": "module",
+  "main": "src/index.js",
+  "files": [
+    "src"
+  ],
+  "scripts": {
+    "test": "NODE_OPTIONS=--experimental-vm-modules jest",
+    "test:watch": "NODE_OPTIONS=--experimental-vm-modules jest --watch",
+    "test:coverage": "NODE_OPTIONS=--experimental-vm-modules jest --coverage",
+    "lint": "eslint src --ext .js",
+    "lint:fix": "eslint src --ext .js --fix"
+  },
+  "keywords": [
+    "pdf",
+    "generate",
+    "api",
+    "sdk",
+    "nodejs"
+  ],
+  "author": "GeneratePDFs",
+  "license": "MIT",
+  "repository": {
+    "type": "git",
+    "url": "https://github.com/GeneratePDFs/node-sdk"
+  },
+  "engines": {
+    "node": ">=18.0.0"
+  },
+  "dependencies": {},
+  "devDependencies": {
+    "@jest/globals": "^29.7.0",
+    "eslint": "^8.57.0",
+    "jest": "^29.7.0"
+  }
+}
+

package/src/GeneratePDFs.js

@@ -0,0 +1,244 @@
+import { readFileSync, existsSync } from 'fs';
+import { Pdf } from './Pdf.js';
+import { InvalidArgumentException } from './exceptions/InvalidArgumentException.js';
+
+export class GeneratePDFs {
+  static BASE_URL = 'https://api.generatepdfs.com';
+  #apiToken;
+  #baseUrl;
+
+  constructor(apiToken) {
+    this.#apiToken = apiToken;
+    this.#baseUrl = GeneratePDFs.BASE_URL;
+  }
+
+  /**
+   * Create a new GeneratePDFs instance with the provided API token.
+   *
+   * @param {string} apiToken The API token for authentication
+   * @returns {GeneratePDFs} GeneratePDFs instance
+   */
+  static connect(apiToken) {
+    return new GeneratePDFs(apiToken);
+  }
+
+  /**
+   * Generate a PDF from HTML file(s) with optional CSS and images.
+   *
+   * @param {string} htmlPath Path to the HTML file
+   * @param {string|null} cssPath Optional path to the CSS file
+   * @param {Array<{name: string, path: string, mimeType?: string}>} images Optional array of image files
+   * @returns {Promise<Pdf>} PDF object containing PDF information
+   * @throws {InvalidArgumentException} If files are invalid
+   */
+  async generateFromHtml(htmlPath, cssPath = null, images = []) {
+    if (!existsSync(htmlPath)) {
+      throw new InvalidArgumentException(`HTML file not found or not readable: ${htmlPath}`);
+    }
+
+    const htmlContent = readFileSync(htmlPath);
+    const htmlBase64 = htmlContent.toString('base64');
+
+    const data = {
+      html: htmlBase64,
+    };
+
+    if (cssPath !== null && cssPath !== undefined) {
+      if (!existsSync(cssPath)) {
+        throw new InvalidArgumentException(`CSS file not found or not readable: ${cssPath}`);
+      }
+
+      const cssContent = readFileSync(cssPath);
+      data.css = cssContent.toString('base64');
+    }
+
+    if (images.length > 0) {
+      data.images = this.#processImages(images);
+    }
+
+    const response = await this.#makeRequest('/pdfs/generate', data);
+
+    if (!response.data) {
+      throw new InvalidArgumentException('Invalid API response: missing data');
+    }
+
+    return Pdf.fromArray(response.data, this);
+  }
+
+  /**
+   * Generate a PDF from a URL.
+   *
+   * @param {string} url The URL to convert to PDF
+   * @returns {Promise<Pdf>} PDF object containing PDF information
+   * @throws {InvalidArgumentException} If URL is invalid
+   */
+  async generateFromUrl(url) {
+    try {
+      new URL(url);
+    } catch {
+      throw new InvalidArgumentException(`Invalid URL: ${url}`);
+    }
+
+    const data = {
+      url: url,
+    };
+
+    const response = await this.#makeRequest('/pdfs/generate', data);
+
+    if (!response.data) {
+      throw new InvalidArgumentException('Invalid API response: missing data');
+    }
+
+    return Pdf.fromArray(response.data, this);
+  }
+
+  /**
+   * Get a PDF by its ID.
+   *
+   * @param {number} id The PDF ID
+   * @returns {Promise<Pdf>} PDF object containing PDF information
+   * @throws {InvalidArgumentException} If ID is invalid
+   */
+  async getPdf(id) {
+    if (id <= 0) {
+      throw new InvalidArgumentException(`Invalid PDF ID: ${id}`);
+    }
+
+    const response = await this.#makeGetRequest(`/pdfs/${id}`);
+
+    if (!response.data) {
+      throw new InvalidArgumentException('Invalid API response: missing data');
+    }
+
+    return Pdf.fromArray(response.data, this);
+  }
+
+  /**
+   * Process image files and return formatted array for API.
+   *
+   * @param {Array<{name: string, path: string, mimeType?: string}>} images Array of image inputs
+   * @returns {Array<{name: string, content: string, mime_type: string}>} Array of processed images
+   */
+  #processImages(images) {
+    const processed = [];
+
+    for (const image of images) {
+      if (!image.path || !image.name) {
+        continue;
+      }
+
+      const path = image.path;
+      const name = image.name;
+
+      if (!existsSync(path)) {
+        continue;
+      }
+
+      const content = readFileSync(path);
+      const contentBase64 = content.toString('base64');
+
+      // Detect mime type if not provided
+      const mimeType = image.mimeType ?? this.#detectMimeType(path);
+
+      processed.push({
+        name: name,
+        content: contentBase64,
+        mime_type: mimeType,
+      });
+    }
+
+    return processed;
+  }
+
+  /**
+   * Detect MIME type of a file based on extension.
+   *
+   * @param {string} filePath Path to the file
+   * @returns {string} MIME type
+   */
+  #detectMimeType(filePath) {
+    const extension = filePath.split('.').pop()?.toLowerCase() ?? '';
+    const mimeTypes = {
+      jpg: 'image/jpeg',
+      jpeg: 'image/jpeg',
+      png: 'image/png',
+      gif: 'image/gif',
+      webp: 'image/webp',
+      svg: 'image/svg+xml',
+    };
+
+    return mimeTypes[extension] ?? 'application/octet-stream';
+  }
+
+  /**
+   * Download a PDF from the API.
+   *
+   * @param {string} downloadUrl The download URL for the PDF
+   * @returns {Promise<Buffer>} PDF binary content as Buffer
+   */
+  async downloadPdf(downloadUrl) {
+    const response = await fetch(downloadUrl, {
+      headers: {
+        Authorization: `Bearer ${this.#apiToken}`,
+      },
+    });
+
+    if (!response.ok) {
+      throw new Error(`Failed to download PDF: ${response.statusText}`);
+    }
+
+    const arrayBuffer = await response.arrayBuffer();
+    return Buffer.from(arrayBuffer);
+  }
+
+  /**
+   * Make an HTTP POST request to the API.
+   *
+   * @param {string} endpoint API endpoint
+   * @param {Record<string, unknown>} data Request data
+   * @returns {Promise<{data?: {id: number, name: string, status: string, download_url: string, created_at: string}}>} Decoded JSON response
+   */
+  async #makeRequest(endpoint, data) {
+    const url = `${this.#baseUrl}${endpoint}`;
+
+    const response = await fetch(url, {
+      method: 'POST',
+      headers: {
+        Authorization: `Bearer ${this.#apiToken}`,
+        'Content-Type': 'application/json',
+      },
+      body: JSON.stringify(data),
+    });
+
+    if (!response.ok) {
+      const errorText = await response.text();
+      throw new Error(`API request failed: ${response.status} ${response.statusText} - ${errorText}`);
+    }
+
+    return await response.json();
+  }
+
+  /**
+   * Make an HTTP GET request to the API.
+   *
+   * @param {string} endpoint API endpoint
+   * @returns {Promise<{data?: {id: number, name: string, status: string, download_url: string, created_at: string}}>} Decoded JSON response
+   */
+  async #makeGetRequest(endpoint) {
+    const url = `${this.#baseUrl}${endpoint}`;
+
+    const response = await fetch(url, {
+      headers: {
+        Authorization: `Bearer ${this.#apiToken}`,
+      },
+    });
+
+    if (!response.ok) {
+      const errorText = await response.text();
+      throw new Error(`API request failed: ${response.status} ${response.statusText} - ${errorText}`);
+    }
+
+    return await response.json();
+  }
+}
+

package/src/Pdf.js

@@ -0,0 +1,154 @@
+import { writeFileSync } from 'fs';
+import { GeneratePDFs } from './GeneratePDFs.js';
+import { InvalidArgumentException } from './exceptions/InvalidArgumentException.js';
+import { RuntimeException } from './exceptions/RuntimeException.js';
+
+export class Pdf {
+  #client;
+  #id;
+  #name;
+  #status;
+  #downloadUrl;
+  #createdAt;
+
+  constructor(id, name, status, downloadUrl, createdAt, client) {
+    this.#id = id;
+    this.#name = name;
+    this.#status = status;
+    this.#downloadUrl = downloadUrl;
+    this.#createdAt = createdAt;
+    this.#client = client;
+  }
+
+  /**
+   * Create a Pdf instance from API response data.
+   *
+   * @param {{id: number, name: string, status: string, download_url: string, created_at: string}} data API response data
+   * @param {GeneratePDFs} client The GeneratePDFs client instance
+   * @returns {Pdf} Pdf instance
+   */
+  static fromArray(data, client) {
+    if (!data.id || !data.name || !data.status || !data.download_url || !data.created_at) {
+      throw new InvalidArgumentException('Invalid PDF data structure');
+    }
+
+    // Parse the created_at date
+    let createdAt;
+    try {
+      createdAt = new Date(data.created_at);
+      if (isNaN(createdAt.getTime())) {
+        throw new InvalidArgumentException(`Invalid created_at format: ${data.created_at}`);
+      }
+    } catch (error) {
+      if (error instanceof InvalidArgumentException) {
+        throw error;
+      }
+      throw new InvalidArgumentException(`Invalid created_at format: ${data.created_at}`);
+    }
+
+    return new Pdf(
+      Number(data.id),
+      String(data.name),
+      String(data.status),
+      String(data.download_url),
+      createdAt,
+      client
+    );
+  }
+
+  /**
+   * Get the PDF ID.
+   *
+   * @returns {number} PDF ID
+   */
+  getId() {
+    return this.#id;
+  }
+
+  /**
+   * Get the PDF name.
+   *
+   * @returns {string} PDF name
+   */
+  getName() {
+    return this.#name;
+  }
+
+  /**
+   * Get the PDF status.
+   *
+   * @returns {string} PDF status
+   */
+  getStatus() {
+    return this.#status;
+  }
+
+  /**
+   * Get the download URL.
+   *
+   * @returns {string} Download URL
+   */
+  getDownloadUrl() {
+    return this.#downloadUrl;
+  }
+
+  /**
+   * Get the creation date.
+   *
+   * @returns {Date} Creation date
+   */
+  getCreatedAt() {
+    return this.#createdAt;
+  }
+
+  /**
+   * Check if the PDF is ready for download.
+   *
+   * @returns {boolean} True if PDF is ready
+   */
+  isReady() {
+    return this.#status === 'completed';
+  }
+
+  /**
+   * Download the PDF content.
+   *
+   * @returns {Promise<Buffer>} PDF binary content as Buffer
+   * @throws {RuntimeException} If the PDF is not ready or download fails
+   */
+  async download() {
+    if (!this.isReady()) {
+      throw new RuntimeException(`PDF is not ready yet. Current status: ${this.#status}`);
+    }
+
+    return await this.#client.downloadPdf(this.#downloadUrl);
+  }
+
+  /**
+   * Download the PDF and save it to a file.
+   *
+   * @param {string} filePath Path where to save the PDF file
+   * @returns {Promise<boolean>} True on success
+   * @throws {RuntimeException} If the PDF is not ready or download fails
+   */
+  async downloadToFile(filePath) {
+    const content = await this.download();
+
+    try {
+      writeFileSync(filePath, content);
+      return true;
+    } catch (error) {
+      throw new RuntimeException(`Failed to write PDF to file: ${filePath}`);
+    }
+  }
+
+  /**
+   * Refresh the PDF data from the API.
+   *
+   * @returns {Promise<Pdf>} A new Pdf instance with updated data
+   */
+  async refresh() {
+    return await this.#client.getPdf(this.#id);
+  }
+}
+

package/src/__tests__/GeneratePDFs.test.js

@@ -0,0 +1,385 @@
+import { describe, it, expect, beforeEach, jest } from '@jest/globals';
+import { writeFileSync, unlinkSync, existsSync } from 'fs';
+import { tmpdir } from 'os';
+import { join } from 'path';
+import { GeneratePDFs } from '../GeneratePDFs.js';
+import { Pdf } from '../Pdf.js';
+import { InvalidArgumentException } from '../exceptions/InvalidArgumentException.js';
+
+// Mock fetch globally
+const mockFetch = jest.fn();
+global.fetch = mockFetch;
+
+describe('GeneratePDFs', () => {
+  let apiToken;
+  let baseUrl;
+
+  beforeEach(() => {
+    apiToken = 'test-api-token';
+    baseUrl = 'https://api.generatepdfs.com';
+    jest.clearAllMocks();
+  });
+
+  describe('connect', () => {
+    it('creates a new GeneratePDFs instance', () => {
+      const client = GeneratePDFs.connect(apiToken);
+      expect(client).toBeInstanceOf(GeneratePDFs);
+    });
+  });
+
+  describe('generateFromHtml', () => {
+    it('throws exception when HTML file does not exist', async () => {
+      const client = GeneratePDFs.connect(apiToken);
+
+      await expect(
+        client.generateFromHtml('/non/existent/file.html')
+      ).rejects.toThrow(InvalidArgumentException);
+      await expect(
+        client.generateFromHtml('/non/existent/file.html')
+      ).rejects.toThrow('HTML file not found or not readable');
+    });
+
+    it('throws exception when CSS file does not exist', async () => {
+      const client = GeneratePDFs.connect(apiToken);
+      const htmlFile = join(tmpdir(), `test-${Date.now()}.html`);
+
+      writeFileSync(htmlFile, '<html><body>Test</body></html>');
+
+      try {
+        await expect(
+          client.generateFromHtml(htmlFile, '/non/existent/file.css')
+        ).rejects.toThrow(InvalidArgumentException);
+        await expect(
+          client.generateFromHtml(htmlFile, '/non/existent/file.css')
+        ).rejects.toThrow('CSS file not found or not readable');
+      } finally {
+        if (existsSync(htmlFile)) {
+          unlinkSync(htmlFile);
+        }
+      }
+    });
+
+    it('successfully generates PDF from HTML file', async () => {
+      const htmlFile = join(tmpdir(), `test-${Date.now()}.html`);
+      writeFileSync(htmlFile, '<html><body>Test</body></html>');
+
+      const mockResponse = {
+        data: {
+          id: 123,
+          name: 'test.pdf',
+          status: 'pending',
+          download_url: 'https://api.generatepdfs.com/pdfs/123/download/token',
+          created_at: '2024-01-01T12:00:00.000000Z',
+        },
+      };
+
+      mockFetch.mockResolvedValueOnce({
+        ok: true,
+        json: async () => mockResponse,
+      });
+
+      const client = GeneratePDFs.connect(apiToken);
+      const pdf = await client.generateFromHtml(htmlFile);
+
+      expect(pdf).toBeInstanceOf(Pdf);
+      expect(pdf.getId()).toBe(123);
+      expect(pdf.getName()).toBe('test.pdf');
+      expect(pdf.getStatus()).toBe('pending');
+
+      expect(mockFetch).toHaveBeenCalledWith(
+        `${baseUrl}/pdfs/generate`,
+        expect.objectContaining({
+          method: 'POST',
+          headers: expect.objectContaining({
+            Authorization: `Bearer ${apiToken}`,
+            'Content-Type': 'application/json',
+          }),
+        })
+      );
+
+      if (existsSync(htmlFile)) {
+        unlinkSync(htmlFile);
+      }
+    });
+
+    it('includes CSS when provided', async () => {
+      const htmlFile = join(tmpdir(), `test-${Date.now()}.html`);
+      const cssFile = join(tmpdir(), `test-${Date.now()}.css`);
+
+      writeFileSync(htmlFile, '<html><body>Test</body></html>');
+      writeFileSync(cssFile, 'body { color: red; }');
+
+      const mockResponse = {
+        data: {
+          id: 123,
+          name: 'test.pdf',
+          status: 'pending',
+          download_url: 'https://api.generatepdfs.com/pdfs/123/download/token',
+          created_at: '2024-01-01T12:00:00.000000Z',
+        },
+      };
+
+      mockFetch.mockResolvedValueOnce({
+        ok: true,
+        json: async () => mockResponse,
+      });
+
+      const client = GeneratePDFs.connect(apiToken);
+      const pdf = await client.generateFromHtml(htmlFile, cssFile);
+
+      expect(pdf).toBeInstanceOf(Pdf);
+
+      const fetchCall = mockFetch.mock.calls[0];
+      const body = JSON.parse(fetchCall[1]?.body);
+      expect(body.html).toBeDefined();
+      expect(body.css).toBeDefined();
+
+      if (existsSync(htmlFile)) {
+        unlinkSync(htmlFile);
+      }
+      if (existsSync(cssFile)) {
+        unlinkSync(cssFile);
+      }
+    });
+
+    it('includes images when provided', async () => {
+      const htmlFile = join(tmpdir(), `test-${Date.now()}.html`);
+      const imageFile = join(tmpdir(), `test-${Date.now()}.png`);
+
+      writeFileSync(htmlFile, '<html><body>Test</body></html>');
+      writeFileSync(imageFile, 'fake-image-content');
+
+      const mockResponse = {
+        data: {
+          id: 123,
+          name: 'test.pdf',
+          status: 'pending',
+          download_url: 'https://api.generatepdfs.com/pdfs/123/download/token',
+          created_at: '2024-01-01T12:00:00.000000Z',
+        },
+      };
+
+      mockFetch.mockResolvedValueOnce({
+        ok: true,
+        json: async () => mockResponse,
+      });
+
+      const client = GeneratePDFs.connect(apiToken);
+      const pdf = await client.generateFromHtml(htmlFile, null, [
+        {
+          name: 'test.png',
+          path: imageFile,
+        },
+      ]);
+
+      expect(pdf).toBeInstanceOf(Pdf);
+
+      const fetchCall = mockFetch.mock.calls[0];
+      const body = JSON.parse(fetchCall[1]?.body);
+      expect(body.html).toBeDefined();
+      expect(body.images).toBeDefined();
+      expect(Array.isArray(body.images)).toBe(true);
+      expect(body.images.length).toBeGreaterThan(0);
+
+      if (existsSync(htmlFile)) {
+        unlinkSync(htmlFile);
+      }
+      if (existsSync(imageFile)) {
+        unlinkSync(imageFile);
+      }
+    });
+
+    it('throws exception when API response is invalid', async () => {
+      const htmlFile = join(tmpdir(), `test-${Date.now()}.html`);
+      writeFileSync(htmlFile, '<html><body>Test</body></html>');
+
+      const mockResponse = {
+        // Missing 'data' key
+      };
+
+      const mockResponseObj = {
+        ok: true,
+        json: async () => mockResponse,
+      };
+
+      mockFetch.mockResolvedValueOnce(mockResponseObj);
+      mockFetch.mockResolvedValueOnce(mockResponseObj);
+
+      const client = GeneratePDFs.connect(apiToken);
+
+      await expect(client.generateFromHtml(htmlFile)).rejects.toThrow(InvalidArgumentException);
+      await expect(client.generateFromHtml(htmlFile)).rejects.toThrow('Invalid API response: missing data');
+
+      if (existsSync(htmlFile)) {
+        unlinkSync(htmlFile);
+      }
+    });
+
+    it('handles API errors', async () => {
+      const htmlFile = join(tmpdir(), `test-${Date.now()}.html`);
+      writeFileSync(htmlFile, '<html><body>Test</body></html>');
+
+      mockFetch.mockResolvedValueOnce({
+        ok: false,
+        status: 400,
+        statusText: 'Bad Request',
+        text: async () => 'Error message',
+      });
+
+      const client = GeneratePDFs.connect(apiToken);
+
+      await expect(client.generateFromHtml(htmlFile)).rejects.toThrow();
+
+      if (existsSync(htmlFile)) {
+        unlinkSync(htmlFile);
+      }
+    });
+  });
+
+  describe('generateFromUrl', () => {
+    it('throws exception for invalid URL', async () => {
+      const client = GeneratePDFs.connect(apiToken);
+
+      await expect(client.generateFromUrl('not-a-valid-url')).rejects.toThrow(InvalidArgumentException);
+      await expect(client.generateFromUrl('not-a-valid-url')).rejects.toThrow('Invalid URL');
+    });
+
+    it('successfully generates PDF from URL', async () => {
+      const mockResponse = {
+        data: {
+          id: 456,
+          name: 'url-example.com-2024-01-01-12-00-00.pdf',
+          status: 'pending',
+          download_url: 'https://api.generatepdfs.com/pdfs/456/download/token',
+          created_at: '2024-01-01T12:00:00.000000Z',
+        },
+      };
+
+      mockFetch.mockResolvedValueOnce({
+        ok: true,
+        json: async () => mockResponse,
+      });
+
+      const client = GeneratePDFs.connect(apiToken);
+      const pdf = await client.generateFromUrl('https://example.com');
+
+      expect(pdf).toBeInstanceOf(Pdf);
+      expect(pdf.getId()).toBe(456);
+      expect(pdf.getName()).toBe('url-example.com-2024-01-01-12-00-00.pdf');
+
+      const fetchCall = mockFetch.mock.calls[0];
+      const body = JSON.parse(fetchCall[1]?.body);
+      expect(body.url).toBe('https://example.com');
+    });
+  });
+
+  describe('getPdf', () => {
+    it('throws exception for invalid ID', async () => {
+      const client = GeneratePDFs.connect(apiToken);
+
+      await expect(client.getPdf(0)).rejects.toThrow(InvalidArgumentException);
+      await expect(client.getPdf(0)).rejects.toThrow('Invalid PDF ID: 0');
+
+      await expect(client.getPdf(-1)).rejects.toThrow(InvalidArgumentException);
+      await expect(client.getPdf(-1)).rejects.toThrow('Invalid PDF ID: -1');
+    });
+
+    it('successfully retrieves PDF by ID', async () => {
+      const mockResponse = {
+        data: {
+          id: 789,
+          name: 'retrieved.pdf',
+          status: 'completed',
+          download_url: 'https://api.generatepdfs.com/pdfs/789/download/token',
+          created_at: '2024-01-01T12:00:00.000000Z',
+        },
+      };
+
+      mockFetch.mockResolvedValueOnce({
+        ok: true,
+        json: async () => mockResponse,
+      });
+
+      const client = GeneratePDFs.connect(apiToken);
+      const pdf = await client.getPdf(789);
+
+      expect(pdf).toBeInstanceOf(Pdf);
+      expect(pdf.getId()).toBe(789);
+      expect(pdf.getName()).toBe('retrieved.pdf');
+      expect(pdf.getStatus()).toBe('completed');
+
+      expect(mockFetch).toHaveBeenCalledWith(
+        `${baseUrl}/pdfs/789`,
+        expect.objectContaining({
+          headers: expect.objectContaining({
+            Authorization: `Bearer ${apiToken}`,
+          }),
+        })
+      );
+    });
+
+    it('throws exception when API response is invalid', async () => {
+      const mockResponse = {
+        // Missing 'data' key
+      };
+
+      const mockResponseObj = {
+        ok: true,
+        json: async () => mockResponse,
+      };
+
+      mockFetch.mockResolvedValueOnce(mockResponseObj);
+      mockFetch.mockResolvedValueOnce(mockResponseObj);
+
+      const client = GeneratePDFs.connect(apiToken);
+
+      await expect(client.getPdf(123)).rejects.toThrow(InvalidArgumentException);
+      await expect(client.getPdf(123)).rejects.toThrow('Invalid API response: missing data');
+    });
+  });
+
+  describe('downloadPdf', () => {
+    it('successfully downloads PDF content', async () => {
+      const downloadUrl = 'https://api.generatepdfs.com/pdfs/123/download/token';
+      const pdfContent = '%PDF-1.4 fake pdf content';
+
+      mockFetch.mockResolvedValueOnce({
+        ok: true,
+        arrayBuffer: async () => {
+          const buffer = Buffer.from(pdfContent, 'utf-8');
+          return buffer.buffer.slice(buffer.byteOffset, buffer.byteOffset + buffer.byteLength);
+        },
+      });
+
+      const client = GeneratePDFs.connect(apiToken);
+      const content = await client.downloadPdf(downloadUrl);
+
+      expect(Buffer.isBuffer(content)).toBe(true);
+      expect(content.toString('utf-8')).toBe(pdfContent);
+
+      expect(mockFetch).toHaveBeenCalledWith(
+        downloadUrl,
+        expect.objectContaining({
+          headers: expect.objectContaining({
+            Authorization: `Bearer ${apiToken}`,
+          }),
+        })
+      );
+    });
+
+    it('throws exception when download fails', async () => {
+      const downloadUrl = 'https://api.generatepdfs.com/pdfs/123/download/token';
+
+      mockFetch.mockResolvedValueOnce({
+        ok: false,
+        status: 404,
+        statusText: 'Not Found',
+      });
+
+      const client = GeneratePDFs.connect(apiToken);
+
+      await expect(client.downloadPdf(downloadUrl)).rejects.toThrow();
+    });
+  });
+});
+

package/src/__tests__/Pdf.test.js

@@ -0,0 +1,260 @@
+import { describe, it, expect, beforeEach, jest } from '@jest/globals';
+import { writeFileSync, unlinkSync, existsSync } from 'fs';
+import { tmpdir } from 'os';
+import { join } from 'path';
+import { GeneratePDFs } from '../GeneratePDFs.js';
+import { Pdf } from '../Pdf.js';
+import { InvalidArgumentException } from '../exceptions/InvalidArgumentException.js';
+import { RuntimeException } from '../exceptions/RuntimeException.js';
+
+// Mock fetch globally
+const mockFetch = jest.fn();
+global.fetch = mockFetch;
+
+describe('Pdf', () => {
+  let client;
+  let apiToken;
+
+  beforeEach(() => {
+    apiToken = 'test-api-token';
+    client = GeneratePDFs.connect(apiToken);
+    jest.clearAllMocks();
+  });
+
+  describe('fromArray', () => {
+    it('creates Pdf instance from valid data', () => {
+      const data = {
+        id: 123,
+        name: 'test.pdf',
+        status: 'completed',
+        download_url: 'https://api.generatepdfs.com/pdfs/123/download/token',
+        created_at: '2024-01-01T12:00:00.000000Z',
+      };
+
+      const pdf = Pdf.fromArray(data, client);
+
+      expect(pdf).toBeInstanceOf(Pdf);
+      expect(pdf.getId()).toBe(123);
+      expect(pdf.getName()).toBe('test.pdf');
+      expect(pdf.getStatus()).toBe('completed');
+      expect(pdf.getDownloadUrl()).toBe('https://api.generatepdfs.com/pdfs/123/download/token');
+    });
+
+    it('throws exception when required fields are missing', () => {
+      const data = {
+        id: 123,
+        // Missing other required fields
+      };
+
+      expect(() => Pdf.fromArray(data, client)).toThrow(InvalidArgumentException);
+      expect(() => Pdf.fromArray(data, client)).toThrow('Invalid PDF data structure');
+    });
+
+    it('throws exception when created_at format is invalid', () => {
+      const data = {
+        id: 123,
+        name: 'test.pdf',
+        status: 'completed',
+        download_url: 'https://api.generatepdfs.com/pdfs/123/download/token',
+        created_at: 'invalid-date-format',
+      };
+
+      expect(() => Pdf.fromArray(data, client)).toThrow(InvalidArgumentException);
+      expect(() => Pdf.fromArray(data, client)).toThrow('Invalid created_at format');
+    });
+  });
+
+  describe('getters', () => {
+    it('return correct values', () => {
+      const data = {
+        id: 456,
+        name: 'document.pdf',
+        status: 'pending',
+        download_url: 'https://api.generatepdfs.com/pdfs/456/download/token',
+        created_at: '2024-01-01T12:00:00.000000Z',
+      };
+
+      const pdf = Pdf.fromArray(data, client);
+
+      expect(pdf.getId()).toBe(456);
+      expect(pdf.getName()).toBe('document.pdf');
+      expect(pdf.getStatus()).toBe('pending');
+      expect(pdf.getDownloadUrl()).toBe('https://api.generatepdfs.com/pdfs/456/download/token');
+      expect(pdf.getCreatedAt()).toBeInstanceOf(Date);
+    });
+  });
+
+  describe('isReady', () => {
+    it('returns true when status is completed', () => {
+      const data = {
+        id: 123,
+        name: 'test.pdf',
+        status: 'completed',
+        download_url: 'https://api.generatepdfs.com/pdfs/123/download/token',
+        created_at: '2024-01-01T12:00:00.000000Z',
+      };
+
+      const pdf = Pdf.fromArray(data, client);
+
+      expect(pdf.isReady()).toBe(true);
+    });
+
+    it('returns false when status is not completed', () => {
+      const data = {
+        id: 123,
+        name: 'test.pdf',
+        status: 'pending',
+        download_url: 'https://api.generatepdfs.com/pdfs/123/download/token',
+        created_at: '2024-01-01T12:00:00.000000Z',
+      };
+
+      const pdf = Pdf.fromArray(data, client);
+
+      expect(pdf.isReady()).toBe(false);
+    });
+  });
+
+  describe('download', () => {
+    it('throws exception when PDF is not ready', async () => {
+      const data = {
+        id: 123,
+        name: 'test.pdf',
+        status: 'pending',
+        download_url: 'https://api.generatepdfs.com/pdfs/123/download/token',
+        created_at: '2024-01-01T12:00:00.000000Z',
+      };
+
+      const pdf = Pdf.fromArray(data, client);
+
+      await expect(pdf.download()).rejects.toThrow(RuntimeException);
+      await expect(pdf.download()).rejects.toThrow('PDF is not ready yet');
+    });
+
+    it('successfully downloads PDF content', async () => {
+      const data = {
+        id: 123,
+        name: 'test.pdf',
+        status: 'completed',
+        download_url: 'https://api.generatepdfs.com/pdfs/123/download/token',
+        created_at: '2024-01-01T12:00:00.000000Z',
+      };
+
+      const pdfContent = '%PDF-1.4 fake pdf content';
+
+      mockFetch.mockResolvedValueOnce({
+        ok: true,
+        arrayBuffer: async () => {
+          const buffer = Buffer.from(pdfContent, 'utf-8');
+          return buffer.buffer.slice(buffer.byteOffset, buffer.byteOffset + buffer.byteLength);
+        },
+      });
+
+      const pdf = Pdf.fromArray(data, client);
+      const content = await pdf.download();
+
+      expect(Buffer.isBuffer(content)).toBe(true);
+      expect(content.toString('utf-8')).toBe(pdfContent);
+    });
+  });
+
+  describe('downloadToFile', () => {
+    it('successfully saves PDF to file', async () => {
+      const data = {
+        id: 123,
+        name: 'test.pdf',
+        status: 'completed',
+        download_url: 'https://api.generatepdfs.com/pdfs/123/download/token',
+        created_at: '2024-01-01T12:00:00.000000Z',
+      };
+
+      const pdfContent = '%PDF-1.4 fake pdf content';
+      const tempFile = join(tmpdir(), `test-${Date.now()}.pdf`);
+
+      mockFetch.mockResolvedValueOnce({
+        ok: true,
+        arrayBuffer: async () => {
+          const buffer = Buffer.from(pdfContent, 'utf-8');
+          return buffer.buffer.slice(buffer.byteOffset, buffer.byteOffset + buffer.byteLength);
+        },
+      });
+
+      const pdf = Pdf.fromArray(data, client);
+
+      try {
+        const result = await pdf.downloadToFile(tempFile);
+
+        expect(result).toBe(true);
+        expect(existsSync(tempFile)).toBe(true);
+        // Note: We can't easily read the file back in the test environment
+        // but the file existence check is sufficient
+      } finally {
+        if (existsSync(tempFile)) {
+          unlinkSync(tempFile);
+        }
+      }
+    });
+  });
+
+  describe('fromArray with different status values', () => {
+    it('handles different status values', () => {
+      const statuses = ['pending', 'processing', 'completed', 'failed'];
+
+      for (const status of statuses) {
+        const data = {
+          id: 123,
+          name: 'test.pdf',
+          status: status,
+          download_url: 'https://api.generatepdfs.com/pdfs/123/download/token',
+          created_at: '2024-01-01T12:00:00.000000Z',
+        };
+
+        const pdf = Pdf.fromArray(data, client);
+
+        expect(pdf.getStatus()).toBe(status);
+        expect(pdf.isReady()).toBe(status === 'completed');
+      }
+    });
+  });
+
+  describe('refresh', () => {
+    it('successfully updates PDF data', async () => {
+      const initialData = {
+        id: 123,
+        name: 'test.pdf',
+        status: 'pending',
+        download_url: 'https://api.generatepdfs.com/pdfs/123/download/token',
+        created_at: '2024-01-01T12:00:00.000000Z',
+      };
+
+      const pdf = Pdf.fromArray(initialData, client);
+
+      // Verify initial state
+      expect(pdf.getStatus()).toBe('pending');
+
+      const mockResponse = {
+        data: {
+          id: 123,
+          name: 'test.pdf',
+          status: 'completed',
+          download_url: 'https://api.generatepdfs.com/pdfs/123/download/new-token',
+          created_at: '2024-01-01T12:00:00.000000Z',
+        },
+      };
+
+      mockFetch.mockResolvedValueOnce({
+        ok: true,
+        json: async () => mockResponse,
+      });
+
+      // Refresh the PDF
+      const refreshedPdf = await pdf.refresh();
+
+      // Verify refreshed state
+      expect(refreshedPdf).toBeInstanceOf(Pdf);
+      expect(refreshedPdf.getId()).toBe(123);
+      expect(refreshedPdf.getStatus()).toBe('completed');
+      expect(refreshedPdf.getDownloadUrl()).toBe('https://api.generatepdfs.com/pdfs/123/download/new-token');
+    });
+  });
+});
+

package/src/exceptions/InvalidArgumentException.js

@@ -0,0 +1,8 @@
+export class InvalidArgumentException extends Error {
+  constructor(message) {
+    super(message);
+    this.name = 'InvalidArgumentException';
+    Object.setPrototypeOf(this, InvalidArgumentException.prototype);
+  }
+}
+

package/src/exceptions/RuntimeException.js

@@ -0,0 +1,8 @@
+export class RuntimeException extends Error {
+  constructor(message) {
+    super(message);
+    this.name = 'RuntimeException';
+    Object.setPrototypeOf(this, RuntimeException.prototype);
+  }
+}
+

package/src/index.js

@@ -0,0 +1,5 @@
+export { GeneratePDFs } from './GeneratePDFs.js';
+export { Pdf } from './Pdf.js';
+export { InvalidArgumentException } from './exceptions/InvalidArgumentException.js';
+export { RuntimeException } from './exceptions/RuntimeException.js';
+