@xenterprises/fastify-xpdf 1.0.0 → 1.1.0

package/.dockerignore

@@ -0,0 +1,62 @@
+# Git
+.git
+.gitignore
+.gitattributes
+
+# Node modules (will be installed in container)
+node_modules
+npm-debug.log*
+yarn-debug.log*
+yarn-error.log*
+lerna-debug.log*
+
+# Dependencies
+.npm
+.eslintcache
+*.tsbuildinfo
+
+# Temporary files
+.DS_Store
+Thumbs.db
+*.tmp
+.env.local
+.env.*.local
+
+# IDE
+.vscode
+.idea
+*.swp
+*.swo
+*.swn
+*~
+
+# Test & Coverage
+coverage
+.nyc_output
+test
+*.test.js
+
+# Build artifacts (if any)
+dist
+build
+out
+
+# Docker files (not needed in image)
+Dockerfile*
+docker-compose*.yml
+.dockerignore
+
+# CI/CD
+.github
+.gitlab-ci.yml
+
+# Documentation (optional - include if you want docs in image)
+# *.md
+
+# Example/demo files
+examples
+demo
+
+# Logs
+logs
+*.log

package/.env.example

@@ -1,11 +1,121 @@
-# Puppeteer Configuration (optional - uses defaults if not provided)
+# ============================================================================
+# xPDF Fastify Plugin - Environment Configuration
+# ============================================================================
+# This file defines environment variables for the xPDF module.
+# Copy this to .env and update values for your environment.
+# ============================================================================
+
+# ============================================================================
+# SERVER CONFIGURATION
+# ============================================================================
+
+# Server port (default: 3000)
+PORT=3000
+
+# Node environment (development | production | test)
+NODE_ENV=development
+
+# Server hostname/domain (used in example server)
+DOMAIN=http://localhost:3000
+
+# ============================================================================
+# PUPPETEER CONFIGURATION
+# ============================================================================
+# Optional - uses sensible defaults if not provided
+
+# Run in headless mode (true | false)
+# Default: true
+# Set to false for debugging (displays browser window)
 PUPPETEER_HEADLESS=true
-PUPPETEER_ARGS=--no-sandbox,--disable-setuid-sandbox
 
-# xPDF Configuration
+# Chrome/Chromium launch arguments (comma-separated)
+# Default: --no-sandbox,--disable-setuid-sandbox
+# Examples:
+#   Production:  --no-sandbox,--disable-dev-shm-usage
+#   Docker:      --no-sandbox,--disable-gpu
+# PUPPETEER_ARGS=--no-sandbox,--disable-setuid-sandbox
+
+# Path to Chromium/Chrome executable
+# Leave empty to auto-detect or use system-installed browser
+# Example: /usr/bin/chromium-browser
+# PUPPETEER_EXECUTABLE_PATH=
+
+# Timeout for page operations in milliseconds (default: 30000)
+# PUPPETEER_TIMEOUT=30000
+
+# ============================================================================
+# xPDF PLUGIN CONFIGURATION
+# ============================================================================
+
+# Default PDF page format
+# Options: A4, Letter, A3, A5, Tabloid, Ledger
+# Default: A4
 PDF_DEFAULT_FORMAT=A4
-PDF_DEFAULT_FOLDER=pdfs
+
+# Default page margins (in CSS units: cm, mm, in, px)
+# Default: 1cm on all sides
+# PDF_MARGIN_TOP=1cm
+# PDF_MARGIN_RIGHT=1cm
+# PDF_MARGIN_BOTTOM=1cm
+# PDF_MARGIN_LEFT=1cm
+
+# Print background graphics and colors
+# Default: true
+# PDF_PRINT_BACKGROUND=true
+
+# ============================================================================
+# xSTORAGE INTEGRATION (Optional)
+# ============================================================================
+# Only required if PDF_USE_STORAGE=true
+
+# Enable saving PDFs to xStorage (S3-compatible storage)
+# Default: false
+# Set to true to automatically save generated/merged PDFs
 PDF_USE_STORAGE=false
 
-# Port for example server
-PORT=3000
+# Default folder in storage for saved PDFs
+# Default: pdfs
+PDF_DEFAULT_FOLDER=pdfs
+
+# S3-Compatible Storage Endpoint
+# Example: https://s3.amazonaws.com or https://minio.example.com
+# STORAGE_ENDPOINT=https://s3.amazonaws.com
+
+# AWS Region or storage provider region
+# Example: us-east-1, us-west-2, auto
+# STORAGE_REGION=us-east-1
+
+# Access Key ID for S3-compatible storage
+# STORAGE_ACCESS_KEY_ID=your_access_key
+
+# Secret Access Key for S3-compatible storage
+# STORAGE_SECRET_ACCESS_KEY=your_secret_key
+
+# S3 Bucket name
+# STORAGE_BUCKET=my-pdfs-bucket
+
+# Public URL for accessing stored files
+# Used in response URLs when PDF is saved to storage
+# Example: https://cdn.example.com/pdfs or https://my-bucket.s3.amazonaws.com
+# STORAGE_PUBLIC_URL=https://my-bucket.s3.amazonaws.com
+
+# ============================================================================
+# LOGGING & MONITORING
+# ============================================================================
+
+# Fastify logger level (trace, debug, info, warn, error, fatal)
+LOG_LEVEL=info
+
+# Enable request logging
+# LOG_REQUESTS=true
+
+# ============================================================================
+# SECURITY & RATE LIMITING (for HTTP endpoints)
+# ============================================================================
+
+# Enable HTTPS enforcement (if behind reverse proxy)
+# HTTPS_ONLY=false
+
+# Rate limiting: max requests per minute
+# RATE_LIMIT_WINDOW=1m
+# RATE_LIMIT_MAX=100

package/.gitlab-ci.yml

@@ -0,0 +1,45 @@
+# ============================================================================
+# GitLab CI/CD Pipeline - xPDF
+# ============================================================================
+# Runs tests on merge requests and commits to main/master
+
+stages:
+  - test
+
+variables:
+  NODE_ENV: test
+
+# ============================================================================
+# Shared Configuration
+# ============================================================================
+.shared_rules: &shared_rules
+  rules:
+    - if: '$CI_PIPELINE_SOURCE == "merge_request_event"'
+    - if: '$CI_COMMIT_BRANCH == "main"'
+    - if: '$CI_COMMIT_BRANCH == "master"'
+    - if: '$CI_COMMIT_TAG'
+
+# ============================================================================
+# STAGE: TEST
+# ============================================================================
+test:
+  stage: test
+  image: node:20-alpine
+  <<: *shared_rules
+
+  cache:
+    key: ${CI_COMMIT_REF_SLUG}
+    paths:
+      - node_modules/
+
+  before_script:
+    - npm ci
+
+  script:
+    - echo "Running xPDF tests..."
+    - npm test
+    - npm audit --audit-level=high || true
+
+  retry:
+    max: 2
+    when: runner_system_failure

package/index.d.ts

@@ -0,0 +1,267 @@
+/**
+ * xPDF - Fastify Plugin for PDF Generation and Manipulation
+ * TypeScript Type Definitions
+ *
+ * @module @xenterprises/fastify-xpdf
+ * @version 1.0.0
+ */
+
+import { FastifyPluginAsync, FastifyInstance } from 'fastify';
+
+/**
+ * PDF Generation Options
+ */
+export interface PDFGenerationOptions {
+  /** Output filename (auto-generated if not provided) */
+  filename?: string;
+
+  /** Page format: A4, Letter, A3, A5, Tabloid, Ledger */
+  format?: 'A4' | 'Letter' | 'A3' | 'A5' | 'Tabloid' | 'Ledger';
+
+  /** Landscape orientation */
+  landscape?: boolean;
+
+  /** Page margins */
+  margin?: {
+    top?: string;
+    right?: string;
+    bottom?: string;
+    left?: string;
+  };
+
+  /** Print background graphics and colors */
+  printBackground?: boolean;
+
+  /** Save to xStorage after generation */
+  saveToStorage?: boolean;
+
+  /** Storage folder path */
+  folder?: string;
+}
+
+/**
+ * PDF Generation Result
+ */
+export interface PDFGenerationResult {
+  /** PDF buffer */
+  buffer: Buffer;
+
+  /** Generated filename */
+  filename: string;
+
+  /** File size in bytes */
+  size: number;
+
+  /** Storage key (only if saved to storage) */
+  storageKey?: string;
+
+  /** Public URL (only if saved to storage) */
+  url?: string;
+}
+
+/**
+ * PDF Merge Options
+ */
+export interface PDFMergeOptions extends PDFGenerationOptions {
+  // Inherits from PDFGenerationOptions
+}
+
+/**
+ * PDF Merge Result
+ */
+export interface PDFMergeResult extends PDFGenerationResult {
+  /** Total page count in merged PDF */
+  pageCount: number;
+}
+
+/**
+ * PDF Form Field
+ */
+export interface PDFFormField {
+  /** Field name */
+  name: string;
+
+  /** Field type: text, checkbox, radio, etc. */
+  type: string;
+
+  /** Current field value */
+  value: any;
+}
+
+/**
+ * PDF Form Filling Options
+ */
+export interface PDFFormFillingOptions extends PDFGenerationOptions {
+  /** Flatten form after filling (make non-editable) */
+  flatten?: boolean;
+}
+
+/**
+ * PDF Form Filling Result
+ */
+export interface PDFFormFillingResult extends PDFGenerationResult {
+  // Inherits from PDFGenerationResult
+}
+
+/**
+ * Plugin Configuration Options
+ */
+export interface XPDFPluginOptions {
+  /** Enable saving to xStorage automatically */
+  useStorage?: boolean;
+
+  /** Default storage folder */
+  defaultFolder?: string;
+
+  /** Puppeteer launch options */
+  headless?: boolean;
+
+  /** Chrome/Chromium launch arguments */
+  args?: string[];
+
+  /** Executable path for Chrome/Chromium */
+  executablePath?: string;
+
+  /** Default page format */
+  format?: string;
+
+  /** Print background by default */
+  printBackground?: boolean;
+
+  /** Default page margins */
+  margin?: {
+    top?: string;
+    right?: string;
+    bottom?: string;
+    left?: string;
+  };
+}
+
+/**
+ * Helper Functions
+ */
+export namespace helpers {
+  /**
+   * Generate unique PDF filename
+   * @param baseName Base filename without extension
+   * @returns Unique filename with timestamp
+   */
+  function generatePdfFilename(baseName?: string): string;
+
+  /**
+   * Validate PDF buffer
+   * @param buffer Buffer to validate
+   * @returns True if valid PDF
+   */
+  function isValidPdfBuffer(buffer: Buffer): boolean;
+
+  /**
+   * Get PDF metadata
+   * @param buffer PDF buffer
+   * @returns Metadata including page count and file size
+   */
+  function getPdfMetadata(buffer: Buffer): Promise<{
+    pageCount: number;
+    fileSize: number;
+  }>;
+
+  /**
+   * Format PDF options with defaults
+   * @param options User options
+   * @param defaults Default options
+   * @returns Merged options
+   */
+  function formatPdfOptions(options: any, defaults: any): any;
+}
+
+/**
+ * xPDF Service Methods (available on fastify.xPDF)
+ */
+export interface XPDFService {
+  /**
+   * Generate PDF from HTML
+   * @param html HTML content
+   * @param options Generation options
+   * @returns PDF generation result
+   */
+  generateFromHtml(
+    html: string,
+    options?: PDFGenerationOptions
+  ): Promise<PDFGenerationResult>;
+
+  /**
+   * Generate PDF from Markdown
+   * @param markdown Markdown content
+   * @param options Generation options
+   * @returns PDF generation result
+   */
+  generateFromMarkdown(
+    markdown: string,
+    options?: PDFGenerationOptions
+  ): Promise<PDFGenerationResult>;
+
+  /**
+   * Fill PDF form fields
+   * @param pdfBuffer Source PDF buffer
+   * @param fieldValues Key-value pairs of field names and values
+   * @param options Filling options
+   * @returns Filled PDF result
+   */
+  fillForm(
+    pdfBuffer: Buffer,
+    fieldValues: Record<string, any>,
+    options?: PDFFormFillingOptions
+  ): Promise<PDFFormFillingResult>;
+
+  /**
+   * List all form fields in a PDF
+   * @param pdfBuffer Source PDF buffer
+   * @returns Array of form fields
+   */
+  listFormFields(pdfBuffer: Buffer): Promise<PDFFormField[]>;
+
+  /**
+   * Merge multiple PDFs into one
+   * @param pdfBuffers Array of PDF buffers
+   * @param options Merge options
+   * @returns Merged PDF result
+   */
+  mergePDFs(
+    pdfBuffers: Buffer[],
+    options?: PDFMergeOptions
+  ): Promise<PDFMergeResult>;
+}
+
+/**
+ * Fastify Instance with xPDF Decoration
+ */
+declare module 'fastify' {
+  interface FastifyInstance {
+    /** xPDF service methods */
+    xPDF: XPDFService;
+  }
+}
+
+/**
+ * xPDF Plugin
+ * Registers PDF generation and manipulation capabilities
+ *
+ * @example
+ * ```typescript
+ * import Fastify from 'fastify';
+ * import xPDF from '@xenterprises/fastify-xpdf';
+ *
+ * const fastify = Fastify();
+ *
+ * await fastify.register(xPDF, {
+ *   useStorage: true,
+ *   defaultFolder: 'pdfs'
+ * });
+ *
+ * // Use xPDF methods
+ * const result = await fastify.xPDF.generateFromHtml('<h1>Hello</h1>');
+ * ```
+ */
+declare const xPDF: FastifyPluginAsync<XPDFPluginOptions>;
+
+export default xPDF;

package/package.json

@@ -1,7 +1,7 @@
 {
   "name": "@xenterprises/fastify-xpdf",
   "type": "module",
-  "version": "1.0.0",
+  "version": "1.1.0",
   "description": "Fastify plugin for PDF generation and manipulation. Convert HTML/Markdown to PDF, fill forms, and merge PDFs.",
   "main": "src/index.js",
   "exports": {