@zola_do/document-manipulator 0.2.4 → 0.2.6

package/README.md

@@ -1,7 +1,21 @@
 # @zola_do/document-manipulator
 
+[![npm version](https://img.shields.io/npm/v/@zola_do/document-manipulator.svg)](https://www.npmjs.com/package/@zola_do/document-manipulator)
+[![npm downloads](https://img.shields.io/npm/dm/@zola_do/document-manipulator.svg)](https://www.npmjs.com/package/@zola_do/document-manipulator)
+[![License: ISC](https://img.shields.io/badge/License-ISC-blue.svg)](https://opensource.org/licenses/ISC)
+
 PDF and DOCX merge, conversion, and template population for NestJS.
 
+## Overview
+
+`@zola_do/document-manipulator` provides:
+
+- **PDF Merging** — Combine multiple PDFs into one
+- **DOCX Merging** — Combine multiple Word documents
+- **Document Conversion** — Convert between formats (DOCX ↔ PDF ↔ HTML)
+- **Template Population** — Fill DOCX templates with data
+- **MinIO Integration** — Store and retrieve documents
+
 ## Installation
 
 ```bash
@@ -12,23 +26,30 @@ npm install @zola_do/document-manipulator
 npm install @zola_do/nestjs-shared
 ```
 
-## Dependencies
+### Dependencies
+
+```bash
+npm install @zola_do/minio
+npm install docx-templates pdf-lib @scholarcy/docx-merger
+npm install axios form-data
+npm install libreoffice-convert
+```
+
+**Note:** For document conversion, LibreOffice must be installed on the system.
 
-This package depends on:
+## Operations notes
 
-- `@zola_do/minio` — Object storage for documents
-- `docx-templates` — DOCX template filling
-- `pdf-lib` — PDF manipulation
-- `libreoffice-convert` — Document format conversion (requires LibreOffice installed)
+- **LibreOffice / soffice:** Runs as a subprocess during conversion. In production, enforce **timeouts** on conversion calls in your app, bound **temporary directories**, and avoid running converters as root. On Linux, consider `systemd` `MemoryMax` / `CPUQuota` for the worker process or dedicated job containers.
+- **Cloud conversion:** For serverless or locked-down containers without LibreOffice, route conversions through an external API by implementing a thin wrapper in your app (keep secrets and quotas in your infrastructure, not in this library).
 
-## Usage
+## Quick Start
 
-### Module Setup
+### 1. Register Modules
 
 ```typescript
-import { Module } from '@nestjs/common';
-import { DocumentManipulatorModule } from '@zola_do/document-manipulator';
-import { MinIoModule } from '@zola_do/minio';
+import { Module } from "@nestjs/common";
+import { DocumentManipulatorModule } from "@zola_do/document-manipulator";
+import { MinIoModule } from "@zola_do/minio";
 
 @Module({
   imports: [MinIoModule, DocumentManipulatorModule],
@@ -36,62 +57,437 @@ import { MinIoModule } from '@zola_do/minio';
 export class AppModule {}
 ```
 
-### Merging PDFs
+### 2. Use Service
 
 ```typescript
-import { Injectable } from '@nestjs/common';
-import { DocumentManipulatorService } from '@zola_do/document-manipulator';
+import { Injectable } from "@nestjs/common";
+import { DocumentManipulatorService } from "@zola_do/document-manipulator";
 
 @Injectable()
 export class ReportService {
   constructor(private readonly docService: DocumentManipulatorService) {}
 
-  async mergePdfs(pdfBuffers: Buffer[]) {
-    await this.docService.mergePdf(pdfBuffers);
-    // Merged PDF uploaded to MinIO
+  async mergeInvoices(invoiceIds: string[]) {
+    // Get PDF buffers
+    const pdfBuffers = await Promise.all(
+      invoiceIds.map((id) => this.getInvoicePdf(id)),
+    );
+
+    // Merge PDFs
+    const mergedBuffer = await this.docService.mergePdf(pdfBuffers);
+
+    // Upload to MinIO
+    return await this.minioService.uploadBuffer(
+      mergedBuffer,
+      `merged-invoice-${Date.now()}.pdf`,
+      "application/pdf",
+      "invoices",
+    );
   }
 }
 ```
 
-### Merging DOCX
+## PDF Operations
+
+### Merge PDFs
+
+Combine multiple PDF buffers into one:
 
 ```typescript
-await this.docService.mergeDocx(docxBuffers);
+async mergePdfs(pdfBuffers: Buffer[]) {
+  const merged = await this.docService.mergePdf(pdfBuffers);
+  return merged; // Single PDF Buffer
+}
 ```
 
-### Populating Templates
+**Example: Merge invoice PDFs**
+
+```typescript
+async generateMergedInvoice(orderId: string): Promise<Buffer> {
+  const order = await this.orderService.findOne(orderId);
+
+  // Get each item's PDF
+  const itemPdfs = await Promise.all(
+    order.items.map(item => this.getItemPdf(item.id))
+  );
+
+  // Add cover page
+  const coverPage = await this.generateCoverPage(order);
+  const allPdfs = [coverPage, ...itemPdfs];
+
+  return this.docService.mergePdf(allPdfs);
+}
+```
+
+### Convert Document to PDF
+
+Convert DOCX to PDF (requires LibreOffice):
+
+```typescript
+async convertToPdf(docxBuffer: Buffer): Promise<Buffer> {
+  const pdfBuffer = await this.docService.convertDocument(docxBuffer, '.pdf');
+  return pdfBuffer;
+}
+```
+
+## DOCX Operations
+
+### Merge DOCX Files
+
+Combine multiple Word documents:
+
+```typescript
+async mergeDocx(docxBuffers: Buffer[]) {
+  const merged = await this.docService.mergeDocx(docxBuffers);
+  return merged; // Single DOCX Buffer
+}
+```
+
+**Example: Merge contract sections**
+
+```typescript
+async generateContract(contractId: string): Promise<Buffer> {
+  const contract = await this.contractService.findOne(contractId);
+
+  const sections = [
+    await this.loadTemplate('contracts/header.docx'),
+    await this.loadTemplate(`contracts/${contract.type}/body.docx`),
+    await this.loadTemplate('contracts/terms.docx'),
+    await this.loadTemplate('contracts/signatures.docx'),
+  ];
+
+  return this.docService.mergeDocx(sections);
+}
+```
+
+### Convert DOCX to HTML
+
+```typescript
+async convertToHtml(docxBuffer: Buffer): Promise<Buffer> {
+  const htmlBuffer = await this.docService.convertDocument(docxBuffer, '.html');
+  return htmlBuffer;
+}
+```
+
+### Convert DOCX to PDF
+
+```typescript
+async convertDocxToPdf(docxBuffer: Buffer): Promise<Buffer> {
+  const pdfBuffer = await this.docService.convertDocument(docxBuffer, '.pdf');
+  return pdfBuffer;
+}
+```
+
+## Template Population
 
 Fill DOCX templates with data:
 
 ```typescript
-const populatedBuffer = await this.docService.populateTemplate(
-  templateBuffer,
-  { public_body: 'Procurement of procedure' },
-);
+async populateTemplate(
+  templateBuffer: Buffer,
+  data: Record<string, any>,
+): Promise<Buffer> {
+  const result = await this.docService.populateTemplate(templateBuffer, data);
+  return result;
+}
+```
+
+**Example: Generate personalized document**
+
+```typescript
+async generateOfferLetter(employeeId: string): Promise<Buffer> {
+  const employee = await this.employeeService.findOne(employeeId);
+  const template = await this.loadTemplate('offer-letter.docx');
+
+  return this.docService.populateTemplate(template, {
+    candidateName: employee.fullName,
+    position: employee.position,
+    startDate: employee.startDate.toLocaleDateString(),
+    salary: employee.salary.toLocaleString(),
+    benefits: employee.benefits,
+    companyName: 'Acme Corporation',
+    hrName: 'Jane Smith',
+    offerDate: new Date().toLocaleDateString(),
+  });
+}
+```
+
+## Document Conversion
+
+### Supported Conversions
+
+| Input | Output | Method      |
+| ----- | ------ | ----------- |
+| DOCX  | PDF    | LibreOffice |
+| DOCX  | HTML   | LibreOffice |
+| DOCX  | ODT    | LibreOffice |
+| DOC   | DOCX   | LibreOffice |
+
+### Using LibreOffice
+
+**Note:** LibreOffice must be installed for conversion to work.
+
+```bash
+# macOS
+brew install libreoffice
+
+# Ubuntu/Debian
+sudo apt install libreoffice
+
+# Windows
+# Download from https://www.libreoffice.org/download/download/
+```
+
+### Remote Conversion Service
+
+For serverless environments without LibreOffice:
+
+```typescript
+async convertViaRemote(docxBuffer: Buffer): Promise<Buffer> {
+  // Configure remote endpoint in environment
+  // DOCUMENT_CONVERT_ENDPOINT=https://convert.example.com
+
+  return await this.docService.convertDocument(docxBuffer, '.pdf');
+}
+```
+
+## FileHelperService
+
+Utility service for file operations:
+
+```typescript
+import { Injectable } from "@nestjs/common";
+import { FileHelperService } from "@zola_do/document-manipulator";
+
+@Injectable()
+export class DocumentService {
+  constructor(
+    private readonly docService: DocumentManipulatorService,
+    private readonly fileHelper: FileHelperService,
+  ) {}
+
+  async processDocument(buffer: Buffer, filename: string) {
+    // Get file extension
+    const ext = this.fileHelper.getFileExtension(filename);
+
+    // Get MIME type
+    const mime = this.fileHelper.getMimeType(filename);
+
+    // Validate file type
+    if (!this.fileHelper.isValidDocumentType(ext)) {
+      throw new BadRequestException("Invalid document type");
+    }
+
+    // Get file size
+    const size = this.fileHelper.getFileSize(buffer);
+
+    // ... process document
+  }
+}
+```
+
+### FileHelper Methods
+
+```typescript
+class FileHelperService {
+  getFileExtension(filename: string): string;
+  getMimeType(filename: string): string;
+  isValidDocumentType(extension: string): boolean;
+  isValidImageType(extension: string): boolean;
+  getFileSize(buffer: Buffer): number;
+  sanitizeFilename(filename: string): string;
+}
 ```
 
-### Converting Documents
+## Document Architecture
+
+```
+┌─────────────────────────────────────────────────────────────────────┐
+│                   Document Manipulation Flow                        │
+├─────────────────────────────────────────────────────────────────────┤
+│                                                                      │
+│  Source Documents                                                    │
+│  ┌─────────┐ ┌─────────┐ ┌─────────┐                               │
+│  │ DOCX 1  │ │ DOCX 2  │ │ DOCX 3  │                               │
+│  └────┬────┘ └────┬────┘ └────┬────┘                               │
+│       │           │           │                                      │
+│       └───────────┼───────────┘                                      │
+│                   │                                                  │
+│                   ▼                                                  │
+│         ┌─────────────────┐                                         │
+│         │  Document       │                                         │
+│         │  Manipulator    │                                         │
+│         │  Service        │                                         │
+│         └────────┬────────┘                                         │
+│                  │                                                   │
+│        ┌─────────┼─────────┐                                        │
+│        │         │         │                                        │
+│        ▼         ▼         ▼                                        │
+│  ┌──────────┐ ┌──────────┐ ┌──────────┐                            │
+│  │  merge   │ │ populate │ │ convert  │                            │
+│  │  PDFs    │ │ template │ │ formats  │                            │
+│  └────┬─────┘ └────┬─────┘ └────┬─────┘                            │
+│       │            │            │                                   │
+│       ▼            ▼            ▼                                   │
+│  ┌──────────┐ ┌──────────┐ ┌──────────┐                            │
+│  │  Merged  │ │ Filled   │ │  Output  │                            │
+│  │  PDF     │ │ Template │ │  Format  │                            │
+│  └──────────┘ └──────────┘ └──────────┘                            │
+│                                                                      │
+└─────────────────────────────────────────────────────────────────────┘
+```
 
-Convert between formats (requires LibreOffice):
+## Environment Variables
+
+| Variable                    | Description                   | Required    |
+| --------------------------- | ----------------------------- | ----------- |
+| `DOCUMENT_CONVERT_ENDPOINT` | Remote conversion service URL | No          |
+| `MINIO_ENDPOINT`            | MinIO server endpoint         | For storage |
+| `MINIO_PORT`                | MinIO port                    | For storage |
+| `MINIO_ACCESSKEY`           | MinIO access key              | For storage |
+| `MINIO_SECRETKEY`           | MinIO secret key              | For storage |
+
+## API Reference
+
+### Module
 
 ```typescript
-const htmlBuffer = await this.docService.convertDocument(
-  docxBuffer,
-  '.html',
-);
+DocumentManipulatorModule.forRoot(options?: DocumentManipulatorModuleOptions)
 ```
 
-## Exports
+### Service
+
+```typescript
+class DocumentManipulatorService {
+  // PDF Operations
+  async mergePdf(pdfBuffers: Buffer[]): Promise<Buffer>;
+
+  // DOCX Operations
+  async mergeDocx(docxBuffers: Buffer[]): Promise<Buffer>;
+
+  // Template Operations
+  async populateTemplate(
+    templateBuffer: Buffer,
+    data: Record<string, any>,
+  ): Promise<Buffer>;
+
+  // Conversion
+  async convertDocument(
+    buffer: Buffer,
+    outputExtension: ".pdf" | ".html" | ".odt",
+  ): Promise<Buffer>;
+}
+```
+
+### FileHelperService
+
+```typescript
+class FileHelperService {
+  getFileExtension(filename: string): string;
+  getMimeType(filename: string): string;
+  isValidDocumentType(extension: string): boolean;
+  isValidImageType(extension: string): boolean;
+  getFileSize(buffer: Buffer): number;
+  sanitizeFilename(filename: string): string;
+}
+```
+
+## Common Use Cases
+
+### 1. Generate Merged Invoice Report
+
+```typescript
+async generateInvoiceReport(date: Date): Promise<Buffer> {
+  const orders = await this.orderService.findByDate(date);
 
-- `DocumentManipulatorModule` — Register the module
-- `DocumentManipulatorService` — Merge, convert, populate templates
-- `FileHelperService` — File utilities
+  const orderPdfs = await Promise.all(
+    orders.map(order => this.generateOrderPdf(order.id))
+  );
+
+  const header = await this.generateReportHeader(date);
+
+  return this.docService.mergePdf([header, ...orderPdfs]);
+}
+```
+
+### 2. Create Package Documents
+
+```typescript
+async createContractPackage(contractId: string): Promise<Buffer> {
+  const contract = await this.contractService.findOne(contractId);
+
+  // Generate each document from template
+  const [cover, terms, specs, pricing] = await Promise.all([
+    this.populateTemplate('cover.docx', contract),
+    this.populateTemplate('terms.docx', contract),
+    this.populateTemplate('specs.docx', contract),
+    this.populateTemplate('pricing.docx', contract),
+  ]);
+
+  // Merge all DOCX
+  return this.docService.mergeDocx([cover, terms, specs, pricing]);
+}
+```
+
+### 3. Export to Multiple Formats
+
+```typescript
+async exportDocument(documentId: string, format: string): Promise<Buffer> {
+  const doc = await this.documentService.findOne(documentId);
+
+  switch (format) {
+    case 'pdf':
+      return this.docService.convertDocument(doc.buffer, '.pdf');
+    case 'html':
+      return this.docService.convertDocument(doc.buffer, '.html');
+    default:
+      return doc.buffer; // Return original DOCX
+  }
+}
+```
+
+## Troubleshooting
+
+### Q: LibreOffice not found?
+
+Ensure LibreOffice is installed and in PATH:
+
+```bash
+which libreoffice
+# or
+which soffice
+```
+
+### Q: Conversion fails?
+
+Check that the input buffer is a valid document:
+
+```typescript
+if (buffer.length === 0) {
+  throw new Error("Empty buffer");
+}
+```
+
+### Q: PDF merge produces blank pages?
+
+Ensure PDF buffers are valid:
+
+```typescript
+// Verify PDF header
+if (!buffer.slice(0, 4).equals(Buffer.from("%PDF"))) {
+  throw new Error("Invalid PDF buffer");
+}
+```
 
 ## Related Packages
 
 - [@zola_do/docx](../docx) — DOCX template processing
 - [@zola_do/minio](../minio) — Required for storage
 
+## License
+
+ISC
+
 ## Community
 
 - [Contributing](../../CONTRIBUTING.md)

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@zola_do/document-manipulator",
-  "version": "0.2.4",
+  "version": "0.2.6",
   "description": "PDF/DOCX merge, conversion, template population for NestJS",
   "author": "zolaDO",
   "license": "ISC",