📄 @contract-js/core

PDF Contract Generation from EJS Templates

Generate PDF contracts from EJS templates with digital signature support and comprehensive metadata management.

🎯 Purpose

Generate professional PDF contracts from EJS templates with support for dynamic data, comprehensive metadata management, and digital signature integration.

✨ Features

• PDF Generation – Convert EJS templates to PDF documents using Puppeteer
• Template Rendering – Render EJS templates with dynamic data
• Metadata Management – Set and extract PDF metadata (title, author, creator, producer, etc.)
• Template Loading – Load EJS templates from file system
• Browser Configuration – Customize Puppeteer browser options for different environments
• Digital Signature Ready – Generate PDFs compatible with digital signatures
• TypeScript Support – Full TypeScript support with comprehensive type definitions

🚀 Usage

Basic PDF Generation

import { generatePdf } from '@contract-js/core';

const result = await generatePdf({
  templateContent: '<h1>Hello <%= name %>!</h1>',
  templateData: {
    name: 'John Doe'
  },
  pdfConfig: {
    metadata: {
      title: 'Sample Contract',
      author: 'ABC Corp',
      creator: 'Contract-JS',
      producer: 'Contract-JS PDF Engine'
    }
  },
  browserOptions: {
    disableDevShmUsage: true,
    disableGpu: true
  }
});

console.log(`PDF generated: ${result.pdfKB}KB`);
console.log(`Hash: ${result.pdfHash}`);

Template Loading and Rendering

import { loadTemplate, generatePdf } from '@contract-js/core';

// Load template from file
const templateContent = await loadTemplate({
  templatePath: './template.ejs'
});

// Generate PDF with loaded template
const result = await generatePdf({
  templateContent,
  templateData: {
    title: 'Service Agreement',
    clientName: 'John Doe',
    date: '2024-01-15'
  },
  pdfConfig: {
    options: {
      format: 'A4',
      margin: {
        top: '20mm',
        bottom: '20mm',
        left: '15mm',
        right: '15mm'
      }
    },
    metadata: {
      title: 'Service Agreement',
      author: 'ABC Corp',
      creator: 'Contract-JS Generator',
      producer: 'Contract-JS PDF Engine',
      keywords: ['contract', 'agreement', 'service']
    }
  }
});

PDF Metadata Extraction

import { getPdfMetadata } from '@contract-js/core';
import { readFile } from 'node:fs/promises';

const pdfBuffer = await readFile('contract.pdf');
const metadata = await getPdfMetadata(pdfBuffer);

console.log('PDF Metadata:', {
  title: metadata.title,
  author: metadata.author,
  creator: metadata.creator,
  producer: metadata.producer,
  createDate: metadata.createDate,
  modDate: metadata.modDate
});

📦 Installation

# npm
npm install @contract-js/core

# pnpm (recommended)
pnpm add @contract-js/core

# yarn
yarn add @contract-js/core

📋 API Reference

Core Functions

| Function | Description | Parameters | Returns | |----------|-------------|------------|---------| | generatePdf | Generate PDF from EJS template | templateContent, templateData, templateOptions?, pdfConfig?, browserOptions? | Promise<PDFResult> | | loadTemplate | Load EJS template from file | templatePath, templateReadOptions? | Promise<string> | | getPdfMetadata | Extract metadata from PDF | pdfBuffer | Promise<PDFMetadata> |

Types

PDFResult

type PDFResult = {
  pdfBuffer: Buffer;
  pdfHash: string;
  pdfKB: number;
};

PDFMetadata

type PDFMetadata = {
  title?: string;
  author?: string;
  subject?: string;
  keywords?: string[];
  producer?: string;
  creator?: string;
  createDate?: Date;
  modDate?: Date;
};

TemplateData

type TemplateData = {
  [key: string]: string | number | TemplateData;
};

BrowserOptions

type BrowserOptions = {
  executablePath?: string;
  disableDevShmUsage?: boolean;
  disableGpu?: boolean;
  singleProcess?: boolean;
};

PDF Configuration Options

The pdfConfig parameter accepts:

{
  options?: PDFOptions; // Puppeteer PDF options
  metadata?: PDFMetadata; // PDF metadata
}

Browser Configuration Options

The browserOptions parameter allows customization of Puppeteer browser settings:

{
  executablePath?: string; // Custom Chrome/Chromium executable path
  disableDevShmUsage?: boolean; // Disable /dev/shm usage (useful in Docker)
  disableGpu?: boolean; // Disable GPU acceleration
  singleProcess?: boolean; // Run in single process mode
}

Default PDF Options

• Format: A4
• Print Background: true
• Margins: 20mm top/bottom, 15mm left/right

Default Metadata

• Creator: Contract-JS Generator
• Producer: Contract-JS PDF Engine
• Create Date: Current date

🔧 Advanced Usage

Custom PDF Options

const result = await generatePdf({
  templateContent,
  templateData,
  pdfConfig: {
    options: {
      format: 'Letter',
      printBackground: true,
      margin: {
        top: '1in',
        bottom: '1in',
        left: '0.5in',
        right: '0.5in'
      },
      displayHeaderFooter: true,
      headerTemplate: '<div>Header</div>',
      footerTemplate: '<div>Footer</div>'
    }
  }
});

Template Options

const result = await generatePdf({
  templateContent,
  templateData,
  templateOptions: {
    delimiter: '%',
    openDelimiter: '<%',
    closeDelimiter: '%>',
    strict: false
  }
});

Browser Options (Docker/Server Environments)

const result = await generatePdf({
  templateContent,
  templateData,
  browserOptions: {
    disableDevShmUsage: true, // Recommended for Docker
    disableGpu: true, // Recommended for headless servers
    singleProcess: true // For memory-constrained environments
  }
});

🛠️ Dependencies

• pdf-lib: PDF manipulation and metadata management
• puppeteer: HTML to PDF conversion
• ejs: Template engine
• @contract-js/pdf-utils: PDF utilities (hash generation)

📝 License

Licensed under the Apache License, Version 2.0 (the "License"); you may not use this file except in compliance with the License. You may obtain a copy of the License at

http://www.apache.org/licenses/LICENSE-2.0

Unless required by applicable law or agreed to in writing, software distributed under the License is distributed on an "AS IS" BASIS, WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied. See the License for the specific language governing permissions and limitations under the License.

Copyright © Jeonhui