ai-pdf-builder 0.1.0 → 0.3.0

package/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 Strykr AI
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

package/README.md

@@ -2,6 +2,35 @@
 
 Professional PDF generation from Markdown using Pandoc and LaTeX. Create beautiful whitepapers, memos, agreements, and term sheets with ease.
 
+## Table of Contents
+
+- [Features](#features)
+- [Prerequisites](#prerequisites)
+- [Installation](#installation)
+- [Quick Start](#quick-start)
+- [Usage Examples](#usage-examples)
+  - [Basic PDF Generation](#basic-pdf-generation)
+  - [Generate a Business Memo](#generate-a-business-memo)
+  - [Generate a Legal Agreement](#generate-a-legal-agreement)
+  - [Generate a Term Sheet](#generate-a-term-sheet)
+  - [Generate a Whitepaper](#generate-a-whitepaper)
+  - [Custom Colors](#custom-colors)
+  - [Save to File](#save-to-file)
+  - [Custom Templates](#custom-templates)
+  - [List Available Templates](#list-available-templates)
+  - [Check System Requirements](#check-system-requirements)
+- [Integration with Next.js](#integration-with-nextjs)
+- [API Reference](#api-reference)
+- [Built-in Templates](#built-in-templates)
+- [Troubleshooting](#troubleshooting)
+- [Error Handling](#error-handling)
+- [TypeScript Best Practices](#typescript-best-practices)
+- [Advanced Topics](#advanced-topics)
+- [Production Deployment](#production-deployment)
+- [FAQ](#faq)
+- [License](#license)
+- [Contributing](#contributing)
+
 ## Features
 
 - **Multiple Document Types**: Built-in templates for memos, agreements, term sheets, and whitepapers
@@ -498,10 +527,643 @@ const result = await generatePDF({
 });
 ```
 
+## Error Handling
+
+Proper error handling is crucial for production applications.
+
+### Basic Error Handling
+
+```typescript
+import { generatePDF } from 'ai-pdf-builder';
+
+try {
+  const result = await generatePDF({
+    content: markdownContent,
+    metadata: { title: 'My Document' }
+  });
+  
+  if (!result.success) {
+    console.error('PDF generation failed:', result.error);
+    
+    // Handle specific errors
+    if (result.error?.includes('Pandoc')) {
+      console.error('Pandoc is not installed. Please install it first.');
+      // Guide user to installation instructions
+    } else if (result.error?.includes('pdflatex')) {
+      console.error('LaTeX is not installed. Please install TeX Live or MiKTeX.');
+    } else if (result.error?.includes('timeout')) {
+      console.error('Generation timed out. Try increasing the timeout option.');
+    }
+    
+    return;
+  }
+  
+  // Success - use result.buffer or result.path
+  console.log(`PDF generated successfully: ${result.fileSize} bytes`);
+  
+} catch (error) {
+  console.error('Unexpected error:', error);
+  // Handle system-level errors
+}
+```
+
+### Retry Logic
+
+```typescript
+async function generateWithRetry(
+  options: PDFOptions, 
+  maxRetries: number = 3
+): Promise<PDFResult> {
+  for (let attempt = 1; attempt <= maxRetries; attempt++) {
+    const result = await generatePDF(options);
+    
+    if (result.success) {
+      return result;
+    }
+    
+    console.warn(`Attempt ${attempt}/${maxRetries} failed:`, result.error);
+    
+    // Wait before retry (exponential backoff)
+    if (attempt < maxRetries) {
+      await new Promise(resolve => setTimeout(resolve, 1000 * attempt));
+    }
+  }
+  
+  throw new Error(`PDF generation failed after ${maxRetries} attempts`);
+}
+```
+
+### Error Handling in Express
+
+```typescript
+app.post('/api/pdf', async (req, res) => {
+  try {
+    const { content, title } = req.body;
+    
+    const result = await generatePDF({
+      content,
+      metadata: { title },
+      timeout: 30000
+    });
+    
+    if (!result.success) {
+      return res.status(500).json({ 
+        error: 'PDF generation failed',
+        details: result.error 
+      });
+    }
+    
+    res.setHeader('Content-Type', 'application/pdf');
+    res.setHeader('Content-Disposition', `attachment; filename="${title}.pdf"`);
+    res.send(result.buffer);
+    
+  } catch (error) {
+    console.error('PDF generation error:', error);
+    res.status(500).json({ error: 'Internal server error' });
+  }
+});
+```
+
+## TypeScript Best Practices
+
+Get the most out of TypeScript's type system for safer code.
+
+### Fully Typed Configuration
+
+```typescript
+import { 
+  generatePDF, 
+  PDFOptions, 
+  PDFResult, 
+  DocumentMetadata,
+  ColorConfig,
+  TemplateConfig 
+} from 'ai-pdf-builder';
+
+// Type-safe metadata
+const metadata: DocumentMetadata = {
+  title: 'Annual Report',
+  author: 'Jane Doe',
+  date: new Date().toLocaleDateString('en-US'),
+  version: 'v2.0',
+  subtitle: 'Financial Year 2025'
+};
+
+// Type-safe color configuration
+const colors: ColorConfig = {
+  primary: '59,130,246',    // RGB format
+  secondary: '107,114,128',
+  accent: '17,24,39'
+};
+
+// Complete options with type checking
+const options: PDFOptions = {
+  content: markdownContent,
+  metadata,
+  customColors: colors,
+  template: 'default',
+  toc: true,
+  tocDepth: 2,
+  numberSections: true,
+  fontSize: 11,
+  margin: '1in',
+  paperSize: 'letter',
+  timeout: 60000
+};
+
+const result: PDFResult = await generatePDF(options);
+
+// Type-safe result handling
+if (result.success && result.buffer) {
+  const size: number = result.fileSize || 0;
+  const pages: number = result.pageCount || 0;
+  console.log(`Generated ${pages} pages (${size} bytes)`);
+}
+```
+
+### Custom Type Guards
+
+```typescript
+import { PDFResult } from 'ai-pdf-builder';
+
+function isSuccessfulResult(result: PDFResult): result is PDFResult & { 
+  success: true; 
+  buffer: Buffer 
+} {
+  return result.success && !!result.buffer;
+}
+
+// Use the type guard
+const result = await generatePDF(options);
+if (isSuccessfulResult(result)) {
+  // TypeScript knows result.buffer is defined here
+  saveToFile(result.buffer);
+}
+```
+
+### Extending Types
+
+```typescript
+import { DocumentMetadata } from 'ai-pdf-builder';
+
+// Extend with custom metadata
+interface CustomMetadata extends DocumentMetadata {
+  department?: string;
+  classification?: 'public' | 'internal' | 'confidential';
+  reviewers?: string[];
+}
+
+const metadata: CustomMetadata = {
+  title: 'Security Report',
+  author: 'Security Team',
+  date: '2026-01-22',
+  department: 'IT Security',
+  classification: 'confidential',
+  reviewers: ['Alice', 'Bob']
+};
+```
+
+## Advanced Topics
+
+### Batch Processing
+
+Generate multiple PDFs concurrently:
+
+```typescript
+import { generatePDF } from 'ai-pdf-builder';
+import pLimit from 'p-limit';
+
+async function generateBatch(documents: Array<{ content: string; title: string }>) {
+  // Limit concurrent operations to avoid overwhelming the system
+  const limit = pLimit(3);
+  
+  const tasks = documents.map(doc => 
+    limit(() => generatePDF({
+      content: doc.content,
+      metadata: { title: doc.title }
+    }))
+  );
+  
+  const results = await Promise.all(tasks);
+  
+  // Process results
+  const successful = results.filter(r => r.success);
+  const failed = results.filter(r => !r.success);
+  
+  console.log(`Generated ${successful.length}/${results.length} PDFs`);
+  return { successful, failed };
+}
+```
+
+### Performance Optimization
+
+Tips for large documents:
+
+```typescript
+// 1. Increase timeout for large documents
+const result = await generatePDF({
+  content: largeMarkdownContent,
+  timeout: 180000 // 3 minutes
+});
+
+// 2. Disable TOC for faster generation
+const result = await generatePDF({
+  content,
+  toc: false,  // Skip table of contents
+  numberSections: false
+});
+
+// 3. Use simpler templates
+const result = await generatePDF({
+  content,
+  template: 'default'  // Simpler than termsheet template
+});
+
+// 4. Process in chunks for very large documents
+async function generateLargeDocument(sections: string[]) {
+  const pdfs = await Promise.all(
+    sections.map(section => generatePDF({
+      content: section,
+      toc: false
+    }))
+  );
+  // Merge PDFs using a library like pdf-lib
+}
+```
+
+### Memory Management
+
+For high-volume operations:
+
+```typescript
+import { generatePDF } from 'ai-pdf-builder';
+
+// Monitor memory usage
+function logMemoryUsage() {
+  const used = process.memoryUsage();
+  console.log({
+    rss: `${Math.round(used.rss / 1024 / 1024)}MB`,
+    heapUsed: `${Math.round(used.heapUsed / 1024 / 1024)}MB`
+  });
+}
+
+// Process in batches to avoid memory issues
+async function processLargeQueue(queue: any[], batchSize = 10) {
+  for (let i = 0; i < queue.length; i += batchSize) {
+    const batch = queue.slice(i, i + batchSize);
+    await Promise.all(batch.map(item => generatePDF(item)));
+    
+    // Allow garbage collection between batches
+    await new Promise(resolve => setImmediate(resolve));
+    logMemoryUsage();
+  }
+}
+```
+
+### Custom Template Creation
+
+Create your own LaTeX templates:
+
+```typescript
+import { registerTemplate, generatePDF } from 'ai-pdf-builder';
+import * as path from 'path';
+
+// Register a custom template
+registerTemplate({
+  name: 'company-branded',
+  path: path.join(__dirname, 'templates', 'company.latex'),
+  description: 'Company branded template with logo',
+  supportedDocTypes: ['memo', 'whitepaper', 'report']
+});
+
+// Use the custom template
+const result = await generatePDF({
+  content: markdownContent,
+  template: 'company-branded',
+  customColors: {
+    primary: '0,102,204',  // Company blue
+    secondary: '128,128,128'
+  }
+});
+```
+
+See [TEMPLATE_GUIDE.md](./TEMPLATE_GUIDE.md) for a complete guide to creating custom LaTeX templates.
+
+## Production Deployment
+
+### Docker Deployment
+
+**Dockerfile:**
+
+```dockerfile
+FROM pandoc/latex:latest
+
+# Install Node.js
+RUN apk add --no-cache nodejs npm
+
+# Set working directory
+WORKDIR /app
+
+# Copy package files
+COPY package*.json ./
+RUN npm ci --only=production
+
+# Copy application
+COPY . .
+
+# Install required LaTeX packages
+RUN tlmgr update --self && \
+    tlmgr install \
+    collection-fontsrecommended \
+    fancyhdr \
+    titlesec \
+    enumitem \
+    xcolor \
+    booktabs \
+    longtable \
+    geometry \
+    hyperref \
+    setspace \
+    array \
+    multirow \
+    listings
+
+EXPOSE 3000
+
+CMD ["node", "server.js"]
+```
+
+**docker-compose.yml:**
+
+```yaml
+version: '3.8'
+services:
+  pdf-generator:
+    build: .
+    ports:
+      - "3000:3000"
+    environment:
+      - NODE_ENV=production
+      - MAX_CONCURRENT_PDFS=3
+    volumes:
+      - pdf-cache:/app/cache
+    mem_limit: 2g
+    mem_reservation: 1g
+
+volumes:
+  pdf-cache:
+```
+
+### Next.js Production Configuration
+
+```typescript
+// next.config.js
+module.exports = {
+  experimental: {
+    serverComponentsExternalPackages: ['ai-pdf-builder']
+  },
+  // Increase API route timeout for PDF generation
+  api: {
+    responseLimit: '8mb'
+  }
+};
+
+// app/api/pdf/route.ts
+import { generatePDF } from 'ai-pdf-builder';
+import { NextResponse } from 'next/server';
+
+export const maxDuration = 60; // 60 seconds timeout
+
+export async function POST(request: Request) {
+  const { content, title } = await request.json();
+  
+  const result = await generatePDF({
+    content,
+    metadata: { title },
+    timeout: 50000 // Leave buffer before Next.js timeout
+  });
+  
+  if (!result.success) {
+    return NextResponse.json({ error: result.error }, { status: 500 });
+  }
+  
+  return new NextResponse(result.buffer, {
+    headers: {
+      'Content-Type': 'application/pdf',
+      'Content-Disposition': `attachment; filename="${title}.pdf"`,
+      'Cache-Control': 'no-store'
+    }
+  });
+}
+```
+
+### Serverless Considerations
+
+**AWS Lambda:**
+
+```typescript
+// Lambda function with custom runtime
+// NOTE: Lambda has a 512MB /tmp limit and 15min timeout
+import { generatePDF } from 'ai-pdf-builder';
+
+export const handler = async (event) => {
+  // Use /tmp for working directory
+  const result = await generatePDF({
+    content: event.content,
+    metadata: event.metadata,
+    workDir: '/tmp/pdf-work',
+    timeout: 840000 // 14 minutes (leave buffer)
+  });
+  
+  if (result.success) {
+    // Upload to S3 instead of returning (size limits)
+    await uploadToS3(result.buffer, event.key);
+    return { statusCode: 200, body: JSON.stringify({ url: s3Url }) };
+  }
+  
+  return { statusCode: 500, body: JSON.stringify({ error: result.error }) };
+};
+```
+
+**Note:** For serverless, consider using the container approach or a dedicated PDF generation service due to Pandoc/LaTeX size requirements.
+
+### Error Monitoring
+
+**Sentry Integration:**
+
+```typescript
+import * as Sentry from '@sentry/node';
+import { generatePDF } from 'ai-pdf-builder';
+
+Sentry.init({ dsn: process.env.SENTRY_DSN });
+
+async function generateWithMonitoring(options) {
+  const transaction = Sentry.startTransaction({
+    op: 'pdf.generate',
+    name: 'Generate PDF'
+  });
+  
+  try {
+    const result = await generatePDF(options);
+    
+    if (!result.success) {
+      Sentry.captureMessage('PDF generation failed', {
+        level: 'error',
+        extra: { error: result.error, options }
+      });
+    }
+    
+    transaction.setStatus('ok');
+    return result;
+    
+  } catch (error) {
+    Sentry.captureException(error);
+    transaction.setStatus('internal_error');
+    throw error;
+  } finally {
+    transaction.finish();
+  }
+}
+```
+
+## FAQ
+
+### Why is my PDF generation slow?
+
+PDF generation involves multiple steps (Markdown parsing, LaTeX compilation, font rendering). Typical generation times:
+- Simple document (1-5 pages): 1-3 seconds
+- Medium document (10-20 pages): 3-8 seconds  
+- Large document (50+ pages): 10-30 seconds
+
+**To improve performance:**
+- Disable TOC if not needed (`toc: false`)
+- Use simpler templates (`template: 'default'`)
+- Process documents concurrently for batch operations
+- Cache generated PDFs when possible
+
+### Can I use this in a serverless environment?
+
+Yes, but with caveats:
+- **Docker-based serverless** (AWS Fargate, Cloud Run): ✅ Recommended
+- **Traditional Lambda/Functions**: ⚠️ Challenging due to Pandoc/LaTeX dependencies (~300MB)
+
+For traditional serverless, consider:
+1. Using a custom Lambda layer with Pandoc/LaTeX
+2. Calling a dedicated PDF generation service
+3. Using AWS Lambda Container Images
+
+### How do I debug LaTeX errors?
+
+```typescript
+// Enable detailed error logging
+const result = await generatePDF({
+  content: markdownContent,
+  metadata: { title: 'Debug Test' }
+});
+
+if (!result.success) {
+  console.error('Full error:', result.error);
+  // LaTeX errors typically mention line numbers and commands
+  // Example: "LaTeX Error: Environment Shaded undefined"
+}
+```
+
+Common LaTeX errors:
+- **"pdflatex not found"**: Install LaTeX (see Prerequisites)
+- **"Unicode character not set up"**: Use ASCII alternatives or configure unicode support
+- **"Environment undefined"**: Missing LaTeX package
+
+### What Markdown features are supported?
+
+Supported (via Pandoc):
+- ✅ Headers (H1-H6)
+- ✅ Lists (ordered, unordered, nested)
+- ✅ Bold, italic, code
+- ✅ Links and URLs
+- ✅ Tables (simple and grid)
+- ✅ Code blocks with syntax highlighting
+- ✅ Blockquotes
+- ✅ Horizontal rules
+- ✅ Images (if file paths are accessible)
+
+Limited support:
+- ⚠️ HTML (basic tags only)
+- ⚠️ Complex tables (may need LaTeX syntax)
+- ⚠️ Emojis (depends on LaTeX font support)
+
+Not supported:
+- ❌ GitHub-flavored Markdown task lists
+- ❌ Mermaid diagrams (consider rendering to image first)
+
+### How do I add images to my PDFs?
+
+```typescript
+const content = `
+# Document with Images
+
+![Company Logo](./assets/logo.png)
+
+Regular text here.
+
+![Chart](./charts/quarterly-results.png){ width=80% }
+`;
+
+const result = await generatePDF({
+  content,
+  metadata: { title: 'Document with Images' }
+});
+```
+
+**Requirements:**
+- Image paths must be accessible from where the code runs
+- Supported formats: PNG, JPG, PDF
+- Use relative or absolute paths
+- Control size with Pandoc syntax: `{ width=50% }` or `{ height=3in }`
+
+### Can I generate PDFs from HTML?
+
+Yes, convert HTML to Markdown first or use Pandoc's HTML input:
+
+```typescript
+import { generatePDF } from 'ai-pdf-builder';
+import TurndownService from 'turndown';
+
+// Convert HTML to Markdown
+const turndown = new TurndownService();
+const markdown = turndown.turndown(htmlContent);
+
+const result = await generatePDF({
+  content: markdown,
+  metadata: { title: 'From HTML' }
+});
+```
+
+### How do I handle concurrent requests?
+
+Use a queue system to limit concurrent PDF generations:
+
+```typescript
+import Queue from 'bull';
+import { generatePDF } from 'ai-pdf-builder';
+
+const pdfQueue = new Queue('pdf-generation', process.env.REDIS_URL);
+
+// Limit to 3 concurrent jobs
+pdfQueue.process(3, async (job) => {
+  return await generatePDF(job.data.options);
+});
+
+// Add jobs
+app.post('/api/pdf', async (req, res) => {
+  const job = await pdfQueue.add({ options: req.body });
+  res.json({ jobId: job.id });
+});
+```
+
 ## License
 
 MIT
 
 ## Contributing
 
-Contributions welcome! Please read our contributing guidelines before submitting PRs.
+Contributions welcome! Please read our [CONTRIBUTING.md](./CONTRIBUTING.md) guidelines before submitting PRs.