KitPDF Creator

KitPDF Creator es una herramienta CLI moderna y robusta para generar PDFs a partir de plantillas HTML y datos JSON. Desarrollada en TypeScript con documentación completa y validación de tipos.

🚀 Características

• ✅ TypeScript completo - Código tipado y documentado
• ✅ Logging avanzado - Sistema de logs con Winston
• ✅ Cola de procesamiento - Procesamiento asíncrono con control de concurrencia
• ✅ Detección automática de Docker - Configuración optimizada para contenedores
• ✅ Múltiples modos - Batch y ondemand
• ✅ Minificación - Código optimizado para producción
• ✅ Documentación completa - JSDoc en todas las funciones

📦 Instalación

# Instalación global
npm install -g kitpdf-creator

# O usando npx
npx kitpdf-creator

🛠️ Desarrollo

Prerrequisitos

• Node.js 18+
• pnpm (recomendado) o npm

Configuración del proyecto

# Clonar el repositorio
git clone https://github.com/victor-arango/kitpdf-creator
cd kitpdf-creator

# Instalar dependencias
pnpm install

# Configurar el proyecto
npm start

Scripts disponibles

# Desarrollo
npm run dev          # Servidor de desarrollo Vite
npm run type-check   # Verificación de tipos TypeScript
npm run lint         # Linting con ESLint
npm run lint:fix     # Linting con auto-corrección

# Build
npm run build        # Build de producción
npm run build:vite   # Build con Vite
npm run clean        # Limpiar directorio dist

# Ejecución
npm start            # Ejecutar CLI
npm run build:cli    # Build y ejecutar

📖 Uso

Modo Interactivo

# Ejecutar el configurador interactivo
kitpdf

# O directamente
npm start

El CLI te guiará a través de:

1. Selección del modo (batch/ondemand)
2. Configuración automática del proyecto
3. Copia de plantillas y archivos necesarios

Modo Línea de Comandos

# Generar PDF desde archivo JSON
node api/cli-generator.js --input="/ruta/entrada.json" --output="/ruta/salida/"

# Con archivo de log personalizado
node api/cli-generator.js --input="data.json" --output="./pdfs" --log="mi-log.txt"

# Mostrar ayuda
node api/cli-generator.js --help

# Mostrar versión
node api/cli-generator.js --version

🏗️ Arquitectura

Estructura del Proyecto

src/
├── types/           # Definiciones de tipos TypeScript
│   └── index.ts     # Tipos principales y esquemas Zod
├── services/        # Servicios de negocio
│   └── pdf-service.ts # Generación de PDFs con Puppeteer
├── utils/           # Utilidades
│   ├── logger.ts    # Sistema de logging con Winston
│   ├── validation.ts # Validación con Zod
│   ├── file.ts      # Utilidades de archivos
│   └── queue.ts     # Sistema de cola de procesamiento
├── cli-generator.ts # CLI principal
└── index.ts         # Punto de entrada del configurador

templates/           # Plantillas de configuración
├── batch/          # Modo batch
└── ondeman/        # Modo ondemand
    └── api/        # API y utilidades

Servicios Principales

PDF Service (src/services/pdf-service.ts)

import { generatePDFFromHTML } from './services/pdf-service.js';

// Generar PDF básico
const pdfPath = await generatePDFFromHTML(
  '/path/to/template.html',
  '/path/to/output',
  'document-name',
  logger
);

// Generar múltiples PDFs en paralelo
const pdfPaths = await generateMultiplePDFs(
  [
    { htmlPath: '/path1.html', outputDir: '/output', fileName: 'doc1' },
    { htmlPath: '/path2.html', outputDir: '/output', fileName: 'doc2' }
  ],
  3, // maxConcurrency
  logger
);

Logger (src/utils/logger.ts)

import { getLogger } from './utils/logger.js';

// Inicializar logger
const logger = getLogger('/path/to/logs', 'app.log');

// Usar logger
logger.info('Aplicación iniciada');
logger.error('Error crítico', { error: 'details' });
logger.warn('Advertencia');
logger.debug('Información de debug');

// Logger temporal
const tempLogger = createTemporaryLogger({
  logDirectory: '/temp/logs',
  logFileName: 'temp-operation.log',
  level: 'debug'
});

Validación (src/utils/validation.ts)

import { validateJson, validateDocument } from './utils/validation.js';

// Validar JSON completo
const result = validateJson(invoiceData);
if (result.success) {
  console.log('Datos válidos:', result.data);
} else {
  console.error('Errores:', result.errors);
}

// Validar documento individual
const docValidation = validateDocument(singleDocument);
if (docValidation.success) {
  console.log('Documento válido');
}

// Formatear errores
const formattedErrors = formatValidationErrors(result.errors);
formattedErrors.forEach(error => console.error(error));

Cola de Procesamiento (src/utils/queue.ts)

import { createQueue, createPriorityQueue } from './utils/queue.js';

// Cola básica
const queue = createQueue('pdf-generation', 3, logger);

queue.add({
  htmlPath: '/path/to/template.html',
  outputDir: '/path/to/output',
  fileName: 'document-1',
  callback: (pdfPath) => console.log('PDF generado:', pdfPath),
  error: (error) => console.error('Error:', error.message)
});

// Cola con prioridades
const priorityQueue = createPriorityQueue('high-priority', 2, logger);

priorityQueue.addHighPriority({
  htmlPath: '/urgent.html',
  outputDir: '/output',
  fileName: 'urgent-doc',
  callback: (pdfPath) => console.log('Urgente completado:', pdfPath),
  error: (error) => console.error('Error urgente:', error.message)
});

📋 Esquema de Datos

Estructura JSON de Entrada

{
  "Documents": [
    {
      "IdUnico": "document-123",
      "NombrePDFSinExtension": "factura",
      "Nombre": "Juan Pérez",
      "Direccion": "Calle 123 #45-67",
      "Ciudad": "Bogotá",
      "Nit": "12345678-9",
      "Factura": "FAC-001",
      "TotalPagar": "150000",
      "ChannelServicesSPD": [
        {
          "conceptoDetalle": "Servicio de energía",
          "NumeroMedidor": "123456789",
          "ConsumoPromedio": "150",
          "Category_ServiceSPD": "Residencial",
          "Estrato_ServiceSPD": "3",
          "valorUnidadConsumo": "1000",
          "CostoUnidadConsumo": "1000",
          "TotalValorConsumo": "150000",
          "TotalValorTablaConceptos": "150000"
        }
      ]
    }
  ]
}

Validación de Tipos

Todos los datos se validan automáticamente usando esquemas Zod:

// Esquemas disponibles
import {
  DocumentSchema,
  ChannelServicesSPDSchema,
  ChannelNotasNivelPrincipalSchema,
  validateJson,
  validateDocument
} from './types/index.js';

// Validación automática
const validation = validateJson(data);
if (!validation.success) {
  console.error('Datos inválidos:', validation.errors);
}

🔧 Configuración

Variables de Entorno

# Nivel de logging
LOG_LEVEL=info  # error, warn, info, debug

# Configuración de Docker
DOCKER_MODE=true  # Detección automática

# Configuración de Puppeteer
PUPPETEER_EXECUTABLE_PATH=/usr/bin/chromium-browser

Configuración de Docker

El servicio detecta automáticamente si se está ejecutando en Docker y ajusta la configuración:

FROM node:18-alpine

# Instalar Chromium para Docker
RUN apk add --no-cache chromium

# Configurar Puppeteer
ENV PUPPETEER_EXECUTABLE_PATH=/usr/bin/chromium-browser
ENV PUPPETEER_SKIP_CHROMIUM_DOWNLOAD=true

# Copiar aplicación
COPY . /app
WORKDIR /app

# Instalar dependencias
RUN npm install

# Exponer puerto
EXPOSE 3000

# Comando de inicio
CMD ["npm", "start"]

📊 Monitoreo y Logs

Estructura de Logs

Los logs se guardan en formato JSON con timestamps:

{
  "timestamp": "2024-01-15T10:30:45.123Z",
  "level": "info",
  "message": "PDF generado exitosamente",
  "pdfPath": "/output/document-123.pdf",
  "duration": 2.5
}

Niveles de Log

• error - Errores críticos
• warn - Advertencias
• info - Información general
• debug - Información detallada para desarrollo

Rotación de Logs

• Tamaño máximo: 5MB por archivo
• Máximo 5 archivos de respaldo
• Rotación automática

🧪 Testing

# Verificación de tipos
npm run type-check

# Linting
npm run lint

# Build de prueba
npm run build

# Ejecución de prueba
npm run build:cli

📦 Build y Distribución

Build de Producción

# Build completo
npm run build

# Verificar resultado
ls -la dist/
# index.cjs (código minificado)
# templates/ (plantillas)

Estructura del Paquete npm

kitpdf-creator-1.0.2.tgz
├── dist/
│   ├── index.cjs          # Código principal minificado
│   └── templates/         # Plantillas
│       ├── batch/
│       └── ondeman/
└── package.json

🤝 Contribución

1. Fork el proyecto
2. Crea una rama para tu feature (git checkout -b feature/AmazingFeature)
3. Commit tus cambios (git commit -m 'Add some AmazingFeature')
4. Push a la rama (git push origin feature/AmazingFeature)
5. Abre un Pull Request

Guías de Contribución

• Usa TypeScript para todo el código nuevo
• Documenta todas las funciones con JSDoc
• Mantén la cobertura de tipos al 100%
• Sigue las convenciones de ESLint
• Agrega tests para nuevas funcionalidades

📄 Licencia

Este proyecto está bajo la Licencia MIT - ver el archivo LICENSE para detalles.

👨‍💻 Autor

Victor Arango Dev

• GitHub: @Victor Arango | Dev
• Email: [email protected]

🙏 Agradecimientos

• Puppeteer - Generación de PDFs
• Winston - Sistema de logging
• Zod - Validación de esquemas
• TypeScript - Tipado estático
• Vite - Build tool

📈 Roadmap

⭐ Si este proyecto te ayuda, ¡dale una estrella en GitHub!