@xenterprises/fastify-xpdf 1.0.0

package/.env.example

@@ -0,0 +1,11 @@
+# Puppeteer Configuration (optional - uses defaults if not provided)
+PUPPETEER_HEADLESS=true
+PUPPETEER_ARGS=--no-sandbox,--disable-setuid-sandbox
+
+# xPDF Configuration
+PDF_DEFAULT_FORMAT=A4
+PDF_DEFAULT_FOLDER=pdfs
+PDF_USE_STORAGE=false
+
+# Port for example server
+PORT=3000

package/CHANGELOG.md

@@ -0,0 +1,106 @@
+# Changelog
+
+All notable changes to this project will be documented in this file.
+
+The format is based on [Keep a Changelog](https://keepachangelog.com/en/1.0.0/),
+and this project adheres to [Semantic Versioning](https://semver.org/spec/v2.0.0.html).
+
+## [1.0.0] - 2024-12-29
+
+### Added
+- Initial release of xPDF Fastify v5 plugin
+- HTML to PDF generation using Puppeteer
+- Markdown to PDF generation with styled formatting
+- PDF form filling with support for text, checkbox, radio, and dropdown fields
+- PDF form flattening (make fields non-editable)
+- PDF merging - combine multiple PDFs into one
+- Optional xStorage integration for cloud storage (S3-compatible)
+- Lazy Puppeteer browser initialization for resource efficiency
+- Automatic browser cleanup on Fastify shutdown
+- Comprehensive error handling and input validation
+- Configurable page formats (A4, Letter, A3, A5, etc.)
+- Support for custom margins and landscape orientation
+- Helper utilities for PDF operations
+- 64 comprehensive tests across 14 test suites
+- Complete documentation (README + QUICK_START)
+- Example HTTP server implementation
+
+### Features
+- **Library pattern**: Decorate methods on Fastify instance, not HTTP routes
+- **xStorage integration**: Optional, auto-detected, seamless cloud storage
+- **Configuration profiles**: Development, production, and high-performance configs
+- **Memory efficient**: Pages closed after use, lazy initialization
+- **Concurrent operations**: Stress tested with 5+ simultaneous PDF generations
+- **Unicode support**: Handles emoji, CJK, Arabic, and other Unicode content
+
+### Documentation
+- Complete README with API reference
+- Quick Start guide with 10-step setup
+- 11 real-world usage examples
+- Configuration guide with profiles
+- Troubleshooting section
+- Best practices guide
+
+### Security
+- Input validation on HTML/Markdown content
+- PDF buffer validation before processing
+- No eval or dynamic code execution
+- Sandboxing configuration for Puppeteer
+- Content type enforcement for storage
+
+### Tested Environments
+- Node.js v20+ (ES modules)
+- Fastify v5.1.0+
+- macOS and Linux
+
+---
+
+## [Future Versions - Planned]
+
+### [1.1.0] - Planned
+- Configuration validation using Zod
+- Browser initialization retry logic
+- Concurrency limiting with optional queue support
+- Prometheus metrics integration
+- Error code standardization
+- Production error sanitization
+
+### [1.2.0] - Planned
+- PDF text extraction
+- PDF page splitting
+- PDF watermarking
+- PDF encryption with password protection
+- Digital signature support
+- Content Security Policy headers for HTML
+- Optional HTML sanitization integration
+
+### [2.0.0] - Planned (Breaking Changes)
+- Separate Puppeteer pool service option
+- WebWorker-based page handling
+- Streaming API for large PDFs
+- Performance optimizations
+
+---
+
+## Notes
+
+### Dependencies
+- **puppeteer**: ^23.0.0 (HTML to PDF rendering engine)
+- **pdf-lib**: ^1.17.1 (PDF manipulation and form operations)
+- **marked**: ^15.0.0 (Markdown to HTML conversion)
+- **fastify-plugin**: ^5.0.0 (Fastify plugin wrapper)
+
+### System Requirements
+- Node.js >= 20.0.0
+- Fastify >= 5.0.0
+- Chrome/Chromium browser (downloaded automatically by Puppeteer)
+- At least 512MB RAM (recommended 1GB+)
+
+### License
+ISC
+
+### Author
+Tim Mushen
+
+### Repository
+https://gitlab.com/x-enterprises/fastify-plugins/fastify-x-pdf

package/LICENSE

@@ -0,0 +1,15 @@
+ISC License
+
+Copyright (c) 2024 Tim Mushen
+
+Permission to use, copy, modify, and/or distribute this software for any
+purpose with or without fee is hereby granted, provided that the above
+copyright notice and this permission notice appear in all copies.
+
+THE SOFTWARE IS PROVIDED "AS IS" AND THE AUTHOR DISCLAIMS ALL WARRANTIES
+WITH REGARD TO THIS SOFTWARE INCLUDING ALL IMPLIED WARRANTIES OF
+MERCHANTABILITY AND FITNESS. IN NO EVENT SHALL THE AUTHOR BE LIABLE FOR
+ANY SPECIAL, DIRECT, INDIRECT, OR CONSEQUENTIAL DAMAGES OR ANY DAMAGES
+WHATSOEVER RESULTING FROM LOSS OF USE, DATA OR PROFITS, WHETHER IN AN
+ACTION OF CONTRACT, NEGLIGENCE OR OTHER TORTIOUS ACTION, ARISING OUT OF
+OR IN CONNECTION WITH THE USE OR PERFORMANCE OF THIS SOFTWARE.

package/QUICK_START.md

@@ -0,0 +1,462 @@
+# Quick Start Guide
+
+Get up and running with xPDF in 5 minutes.
+
+## 1. Install
+
+```bash
+npm install @xenterprises/fastify-xpdf puppeteer marked pdf-lib
+```
+
+**For optional storage integration:**
+
+```bash
+npm install @xenterprises/fastify-xstorage
+```
+
+## 2. Basic Setup
+
+```javascript
+import Fastify from "fastify";
+import xPDF from "@xenterprises/fastify-xpdf";
+
+const fastify = Fastify({ logger: true });
+
+// Register xPDF
+await fastify.register(xPDF, {
+  headless: true,
+  useStorage: false,
+  defaultFolder: "pdfs",
+});
+
+await fastify.listen({ port: 3000 });
+```
+
+## 3. Generate PDF from HTML
+
+```javascript
+// Simple HTML to PDF
+const result = await fastify.xPDF.generateFromHtml(
+  "<h1>Hello World</h1><p>This is a PDF</p>",
+  {
+    filename: "hello.pdf",
+  }
+);
+
+console.log(result);
+// {
+//   buffer: Buffer,
+//   filename: "hello.pdf",
+//   size: 12345
+// }
+
+// Save buffer to file
+import fs from "fs";
+fs.writeFileSync("hello.pdf", result.buffer);
+```
+
+## 4. Generate PDF from Markdown
+
+```javascript
+const markdown = `
+# My Document
+
+This is **bold** and this is *italic*.
+
+## Section
+
+- Point 1
+- Point 2
+- Point 3
+
+\`\`\`javascript
+console.log("Code blocks work!");
+\`\`\`
+`;
+
+const result = await fastify.xPDF.generateFromMarkdown(markdown, {
+  filename: "document.pdf",
+});
+
+fs.writeFileSync("document.pdf", result.buffer);
+```
+
+## 5. Fill PDF Forms
+
+```javascript
+// Read a PDF form
+const pdfBuffer = fs.readFileSync("form-template.pdf");
+
+// Fill form fields
+const result = await fastify.xPDF.fillForm(
+  pdfBuffer,
+  {
+    firstName: "John",
+    lastName: "Doe",
+    email: "john@example.com",
+    agreeToTerms: true,
+  },
+  {
+    flatten: true, // Make non-editable
+    filename: "form-filled.pdf",
+  }
+);
+
+fs.writeFileSync("form-filled.pdf", result.buffer);
+```
+
+## 6. List Form Fields
+
+Before filling a form, see what fields are available:
+
+```javascript
+const pdfBuffer = fs.readFileSync("form-template.pdf");
+
+const fields = await fastify.xPDF.listFormFields(pdfBuffer);
+
+console.log(fields);
+// [
+//   { name: "firstName", type: "text", value: null },
+//   { name: "lastName", type: "text", value: null },
+//   { name: "email", type: "text", value: null },
+//   { name: "agreeToTerms", type: "checkbox", value: false }
+// ]
+```
+
+## 7. Merge PDFs
+
+```javascript
+// Read multiple PDFs
+const page1 = fs.readFileSync("page1.pdf");
+const page2 = fs.readFileSync("page2.pdf");
+const page3 = fs.readFileSync("page3.pdf");
+
+// Merge them
+const result = await fastify.xPDF.mergePDFs([page1, page2, page3], {
+  filename: "merged.pdf",
+});
+
+console.log(result);
+// {
+//   buffer: Buffer,
+//   filename: "merged.pdf",
+//   size: 345678,
+//   pageCount: 15  // Total pages
+// }
+
+fs.writeFileSync("merged.pdf", result.buffer);
+```
+
+## 8. With xStorage Integration
+
+```javascript
+import xStorage from "@xenterprises/fastify-xstorage";
+import xPDF from "@xenterprises/fastify-xpdf";
+
+const fastify = Fastify();
+
+// Register xStorage first
+await fastify.register(xStorage, {
+  endpoint: "https://nyc3.digitaloceanspaces.com",
+  region: "nyc3",
+  accessKeyId: process.env.DO_SPACES_KEY,
+  secretAccessKey: process.env.DO_SPACES_SECRET,
+  bucket: "my-bucket",
+  publicUrl: "https://my-bucket.nyc3.digitaloceanspaces.com",
+});
+
+// Register xPDF
+await fastify.register(xPDF, {
+  useStorage: true,
+  defaultFolder: "pdfs",
+});
+
+// Now PDFs save automatically to storage
+const result = await fastify.xPDF.generateFromHtml("<h1>Invoice</h1>", {
+  filename: "invoice.pdf",
+  saveToStorage: true,
+  folder: "invoices",
+});
+
+console.log(result.url);
+// https://my-bucket.nyc3.digitaloceanspaces.com/invoices/invoice-xxx.pdf
+```
+
+## 9. HTTP Endpoints
+
+Use xPDF in your routes:
+
+```javascript
+// HTML to PDF endpoint
+fastify.post("/api/pdf/html", async (request, reply) => {
+  const { html, filename = "document.pdf" } = request.body;
+
+  const result = await fastify.xPDF.generateFromHtml(html, {
+    filename,
+    saveToStorage: true,
+    folder: "generated",
+  });
+
+  return {
+    success: true,
+    url: result.url,
+    filename: result.filename,
+  };
+});
+
+// Markdown to PDF endpoint
+fastify.post("/api/pdf/markdown", async (request, reply) => {
+  const { markdown } = request.body;
+
+  const result = await fastify.xPDF.generateFromMarkdown(markdown, {
+    saveToStorage: true,
+  });
+
+  return { success: true, url: result.url };
+});
+
+// Form filling endpoint
+fastify.post("/api/pdf/fill-form", async (request, reply) => {
+  const { formUrl, fieldValues } = request.body;
+
+  // Download form from storage
+  const key = formUrl.replace(process.env.STORAGE_PUBLIC_URL + "/", "");
+  const pdfBuffer = await fastify.xStorage.download(key);
+
+  // Fill and save
+  const result = await fastify.xPDF.fillForm(pdfBuffer, fieldValues, {
+    flatten: true,
+    saveToStorage: true,
+    folder: "submitted-forms",
+  });
+
+  return { success: true, url: result.url };
+});
+
+// Merge PDFs endpoint
+fastify.post("/api/pdf/merge", async (request, reply) => {
+  const { pdfUrls } = request.body;
+
+  // Download all PDFs
+  const buffers = await Promise.all(
+    pdfUrls.map((url) => {
+      const key = url.replace(process.env.STORAGE_PUBLIC_URL + "/", "");
+      return fastify.xStorage.download(key);
+    })
+  );
+
+  // Merge
+  const result = await fastify.xPDF.mergePDFs(buffers, {
+    saveToStorage: true,
+    folder: "merged",
+  });
+
+  return {
+    success: true,
+    url: result.url,
+    pages: result.pageCount,
+  };
+});
+```
+
+## 10. Common Use Cases
+
+### Invoice Generation
+
+```javascript
+const invoiceHtml = `
+  <h1>Invoice #INV-2024-001</h1>
+  <p><strong>Date:</strong> January 1, 2024</p>
+  <table>
+    <tr>
+      <th>Item</th>
+      <th>Qty</th>
+      <th>Price</th>
+    </tr>
+    <tr>
+      <td>Widget</td>
+      <td>10</td>
+      <td>$100.00</td>
+    </tr>
+  </table>
+  <h2>Total: $1,000.00</h2>
+`;
+
+const result = await fastify.xPDF.generateFromHtml(invoiceHtml, {
+  filename: "invoice-001.pdf",
+  saveToStorage: true,
+  folder: "invoices",
+});
+```
+
+### Certificate Generation
+
+```javascript
+const certificateHtml = `
+  <div style="text-align: center; padding: 2cm;">
+    <h1>Certificate of Completion</h1>
+    <p style="font-size: 18px; margin: 2cm 0;">
+      This certifies that <strong>Jane Doe</strong>
+    </p>
+    <p>has successfully completed the course</p>
+    <p style="font-size: 16px; color: #0066cc;">
+      <strong>Advanced Web Development</strong>
+    </p>
+    <p style="margin-top: 3cm;">January 1, 2024</p>
+  </div>
+`;
+
+const result = await fastify.xPDF.generateFromHtml(certificateHtml, {
+  filename: "certificate-jane-doe.pdf",
+  format: "A4",
+  landscape: false,
+});
+```
+
+### Report with Multiple Sections
+
+```javascript
+const sections = [
+  { title: "Executive Summary", content: "..." },
+  { title: "Findings", content: "..." },
+  { title: "Recommendations", content: "..." },
+];
+
+const reportHtml = sections
+  .map((s) => `<h2>${s.title}</h2><p>${s.content}</p>`)
+  .join("");
+
+const result = await fastify.xPDF.generateFromHtml(reportHtml, {
+  filename: "report.pdf",
+  saveToStorage: true,
+  folder: "reports",
+});
+```
+
+## Tips & Tricks
+
+### Styled HTML Documents
+
+```javascript
+const styledHtml = `
+  <style>
+    body { font-family: Arial, sans-serif; }
+    h1 { color: #0066cc; border-bottom: 2px solid #0066cc; }
+    table { width: 100%; border-collapse: collapse; }
+    th { background: #f4f4f4; padding: 8px; text-align: left; }
+    td { padding: 8px; border-bottom: 1px solid #ddd; }
+  </style>
+
+  <h1>Report</h1>
+  <table>
+    <tr><th>Col 1</th><th>Col 2</th></tr>
+    <tr><td>Data</td><td>Data</td></tr>
+  </table>
+`;
+
+await fastify.xPDF.generateFromHtml(styledHtml);
+```
+
+### Custom Page Margins
+
+```javascript
+await fastify.xPDF.generateFromHtml(html, {
+  margin: {
+    top: "2cm",
+    right: "1.5cm",
+    bottom: "2cm",
+    left: "1.5cm",
+  },
+});
+```
+
+### Different Page Sizes
+
+```javascript
+// Letter size (US)
+await fastify.xPDF.generateFromHtml(html, { format: "Letter" });
+
+// A3 (larger)
+await fastify.xPDF.generateFromHtml(html, { format: "A3" });
+
+// A5 (smaller)
+await fastify.xPDF.generateFromHtml(html, { format: "A5" });
+```
+
+### Landscape Orientation
+
+```javascript
+await fastify.xPDF.generateFromHtml(html, {
+  landscape: true,
+});
+```
+
+### Batch Form Filling
+
+```javascript
+const applicationData = [
+  { firstName: "John", lastName: "Doe", email: "john@example.com" },
+  { firstName: "Jane", lastName: "Smith", email: "jane@example.com" },
+  { firstName: "Bob", lastName: "Johnson", email: "bob@example.com" },
+];
+
+for (const data of applicationData) {
+  const template = await fastify.xStorage.download("forms/template.pdf");
+
+  await fastify.xPDF.fillForm(template, data, {
+    flatten: true,
+    filename: `application-${data.lastName}.pdf`,
+    saveToStorage: true,
+    folder: "applications",
+  });
+}
+```
+
+## Troubleshooting
+
+### Chrome Not Found
+
+Install Chromium:
+
+```bash
+# macOS
+brew install chromium
+
+# Linux
+apt-get install chromium-browser
+```
+
+Or use sandbox args:
+
+```javascript
+await fastify.register(xPDF, {
+  args: ["--no-sandbox", "--disable-setuid-sandbox"],
+});
+```
+
+### Timeout Errors
+
+Reduce HTML complexity or use async images:
+
+```javascript
+// ❌ Large external image
+const html = '<img src="https://example.com/huge-image.jpg">';
+
+// ✅ Optimized image
+const html = '<img src="/images/logo.png" style="width: 200px;">';
+```
+
+### Form Fields Not Filling
+
+List fields first to verify names:
+
+```javascript
+const fields = await fastify.xPDF.listFormFields(pdfBuffer);
+console.log(fields); // Check exact names
+```
+
+## Next Steps
+
+- [Full Documentation](./README.md)
+- [Complete Examples](./EXAMPLES.md)
+- [Testing Guide](./TESTING.md)