@n8n/ai-workflow-builder 0.31.1 → 0.32.0

package/dist/tools/best-practices/document-processing.js

@@ -0,0 +1,324 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.DocumentProcessingBestPractices = void 0;
+const categorization_1 = require("../../types/categorization");
+class DocumentProcessingBestPractices {
+    technique = categorization_1.WorkflowTechnique.DOCUMENT_PROCESSING;
+    version = '1.0.0';
+    documentation = `# Best Practices: Document Processing Workflows
+
+## Workflow Design
+
+Document processing workflows extract and act on content from files like PDFs, images, Word documents, and spreadsheets. Design your workflow following these core patterns:
+
+### Core Architecture Pattern
+Trigger → Capture Binary → Extract Text → Parse/Transform → Route to Destination → Notify
+
+### Common Flow Patterns
+
+**Simple Document Processing:**
+- Gmail Trigger → Check file type → Extract from File → DataTable → Slack notification
+- Best for: Basic text-based PDFs with straightforward data extraction
+
+**Complex Document Processing with AI:**
+- Webhook → File Type Check → OCR (if image) → AI Extract → Validate → CRM Update → Multiple notifications
+- Best for: Varied document formats requiring intelligent parsing
+
+**Batch Document Processing:**
+- Main workflow: Schedule Trigger → Fetch Files → Split In Batches → Sub-workflow → Merge Results → Bulk Update
+- Sub-workflow When Executed by Another Workflow -> Process result
+- Best for: High-volume processing with API rate limits
+
+**Multi-Source Document Aggregation:**
+- Multiple Triggers (Email + Drive + Webhook) → Set common fields → Standardize → Process → Store
+- Best for: Documents from various channels needing unified processing
+
+### Branching Strategy
+
+Always branch early based on document characteristics:
+- **File Type Branching**: Use IF/Switch nodes immediately after ingestion to route PDFs vs images vs spreadsheets
+- **Provider Branching**: Route documents to provider-specific processing (e.g., different invoice formats)
+- **Quality Branching**: Separate high-confidence extractions from those needing manual review
+
+## Binary Data Management
+Documents in n8n are handled as binary data that must be carefully preserved throughout the workflow.
+
+### Referencing Binary Data from Other Nodes
+When you need to reference binary data from a previous node, use this syntax:
+- Expression: '{{ $('Node Name').item.binary.property_name }}' or {{ $binary.property_name }} if previous item
+- Example for Gmail attachments: '{{ $('Gmail Trigger').item.binary.attachment_0 }}' or {{ $binary.attachment_0 }} if previous item
+- Example for webhook data: '{{ $('Webhook').item.binary.data }}' or {{ $binary.data }} if previous item
+- Important: The property name depends on how the previous node names the binary data
+
+### Preserving Binary Data
+- Many nodes (Code, Edit Fields, AI nodes) output JSON and drop binary data by default
+- Use parallel branches: one for processing, one to preserve the original file
+- Rejoin branches with Merge node in pass-through mode
+- Alternative: Configure nodes to keep binary (e.g., Edit field node's "Include Other Input Fields" option ON)
+
+### Memory Optimization
+For high-volume processing:
+- Process files sequentially or in small batches
+- Drop unnecessary binary data after extraction to free memory
+
+## Text Extraction Strategy
+
+Choose extraction method based on document type and content:
+
+### Critical: File Type Detection
+**ALWAYS check the file type before using Extract from File node** (unless the file type is already known):
+- Use IF node to check file extension or MIME type first
+- The Extract from File node has multiple operations, each for a specific file type:
+  - "Extract from PDF" for PDF files
+  - "Extract from MS Excel" for Excel files (.xlsx, .xls)
+  - "Extract from MS Word" for Word documents (.docx, .doc)
+  - "Extract from CSV" for CSV files
+  - "Extract from HTML" for HTML files
+  - "Extract from RTF" for Rich Text Format files
+  - "Extract from Text File" for plain text files
+- Using the wrong operation will result in errors or empty output
+
+### Decision Tree for Extraction
+1. **Check file type** → Route to appropriate extraction method
+2. **Scanned image/PDF?** → Use OCR service (OCR.space, AWS Textract, Google Vision)
+3. **Structured invoice/receipt?** → Use specialized parser (Mindee) or AI extraction
+4. **Text-based document?** → Use Extract from File with the correct operation for that file type
+
+### Fallback Strategy
+Always implement fallback for extraction failures:
+- Check if text extraction returns empty
+- If empty, automatically route to OCR
+- If OCR fails, send to manual review queue
+
+## Data Parsing & Classification
+
+### AI-Powered Extraction Pattern
+For varied or complex documents:
+
+Option 1 - Using Document Loader (Recommended for binary files):
+1. Pass binary data directly to Document Loader node (set Data Source to "Binary")
+2. Connect to AI Agent or LLM Chain for processing
+3. Use Structured Output Parser to ensure consistent JSON
+4. Validate extracted fields before processing
+
+Option 2 - Using text extraction:
+1. Extract raw text using Extract from File or OCR
+2. Pass to AI Agent or LLM Chain with structured prompt
+3. Use Structured Output Parser to ensure consistent JSON
+4. Validate extracted fields before processing
+
+Example system prompt structure:
+"Extract the following fields from the document: [field list]. Return as JSON with this schema: [schema example]"
+
+### Document Classification Flow
+Classify before processing for better accuracy:
+1. Initial AI classification (Invoice vs Receipt vs Contract)
+2. Route to specialized sub-workflow based on type
+3. Use type-specific prompts and validation rules
+4. This reduces errors and improves extraction quality
+
+## Error Handling Strategy
+
+Build resilience at every step:
+
+### Validation Checkpoints
+- After extraction: Verify text not empty
+- After AI parsing: Validate JSON schema
+- Before database insert: Check required fields
+- After API calls: Verify success response
+
+## Performance Optimization
+
+### Batch Processing Strategy
+- Use Split In Batches node: process 5-10 files at a time
+- Implement delays between batches for rate-limited APIs
+- Monitor memory usage and adjust batch size accordingly
+
+## Recommended Nodes
+
+### Triggers & Input
+
+**Gmail Trigger (n8n-nodes-base.gmailTrigger)**
+Purpose: Monitor Gmail for emails with attachments (Recommended over IMAP)
+Advantages: Real-time processing, simpler authentication, better integration with Google Workspace
+Critical Configuration for Attachments:
+- **MUST set "Simplify" to FALSE** - otherwise attachments won't be available
+- **MUST set "Download Attachments" to TRUE** to retrieve files
+- Set appropriate label filters
+- Set "Property Prefix Name" (e.g., "attachment_") - attachments will be named with this prefix plus index
+- Important: When referencing its binary data, it will be referenced "attachment_0", "attachment_1", etc., NOT "data"
+
+**Email Read (IMAP) (n8n-nodes-base.emailReadImap)**
+Purpose: Alternative email fetching if there's no specialized node for email provider
+Configuration:
+- Enable "Download Attachments" to retrieve files
+- Set "Property Prefix Name" (e.g., "attachment_") - attachments will be named with this prefix plus index
+- Important: When referencing binary data, it will be referenced "attachment_0", "attachment_1", etc., NOT "data"
+
+**HTTP Webhook (n8n-nodes-base.webhook)**
+Purpose: Receive file uploads from web forms
+Configuration: Enable "Raw Body" for binary data
+
+**Google Drive Trigger (n8n-nodes-base.googleDriveTrigger)**
+Purpose: Monitor folders for new documents
+Configuration: Set appropriate folder and file type filters
+
+### Text Extraction
+
+**Extract from File (n8n-nodes-base.extractFromFile)**
+Purpose: Extract text from various file formats using format-specific operations
+Critical: ALWAYS check file type first with an IF or Switch before and select the correct operation (Extract from PDF, Extract from MS Excel, etc.)
+Output: Extracted text is returned under the "text" key in JSON (e.g., access with {{ $json.text }})
+Pitfalls: Returns empty for scanned documents - always check and fallback to OCR; Using wrong operation causes errors
+
+**AWS Textract (n8n-nodes-base.awsTextract)**
+Purpose: Advanced OCR with table and form detection
+Best for: Structured documents like invoices and forms
+
+**Mindee (n8n-nodes-base.mindee)**
+Purpose: Specialized invoice and receipt parsing
+Returns: Structured JSON with line items, totals, dates
+
+### Data Processing
+
+**AI Agent (@n8n/n8n-nodes-langchain.agent)**
+Purpose: Intelligent document parsing and decision making
+Configuration: Include structured output tools for consistent results
+
+**LLM Chain (@n8n/n8n-nodes-langchain.chainLlm)**
+Purpose: Document classification and data extraction
+Use with: Structured Output Parser for JSON consistency
+
+**Document Loader (@n8n/n8n-nodes-langchain.documentLoader)**
+Purpose: Load and process documents directly from binary data for AI processing
+Critical: Use the "Binary" data source option to handle binary files directly - no need to convert to JSON first
+Configuration: Select "Binary" as Data Source, specify the binary property name (by default data unless renamed in a previous node)
+Best for: Direct document processing in AI workflows without intermediate extraction steps
+
+**Structured Output Parser (@n8n/n8n-nodes-langchain.outputParserStructured)**
+Purpose: Ensure AI outputs match expected JSON schema
+Critical for: Database inserts and API calls
+
+### Vector Storage (for RAG/Semantic Search)
+**Simple Vector Store (@n8n/n8n-nodes-langchain.vectorStore) - RECOMMENDED**
+Purpose: Easy-to-setup vector storage for document embeddings
+Advantages:
+- No external dependencies or API keys required
+- Works out of the box with local storage
+- Perfect for prototyping and small to medium datasets
+Configuration: Just connect and use - no complex setup needed
+Best for: Most document processing workflows that need semantic search
+
+### Flow Control
+
+**Split In Batches (n8n-nodes-base.splitInBatches)**
+Purpose: Process multiple documents in controlled batches
+Configuration: Set batch size based on API limits and memory
+Outputs (in order):
+- Output 0 "done": Executes after all batches are processed - use for final aggregation or notifications
+- Output 1 "loop": Connect processing nodes here - executes for each batch
+Important: Connect processing logic to the second output (loop), completion logic to the first output (done)
+
+**Merge (n8n-nodes-base.merge)**
+Purpose: Combine data from multiple branches that need to execute together
+Critical: Merge node waits for ALL input branches to complete - do NOT use for independent/optional branches
+Modes: Use "Pass Through" to preserve binary from one branch
+
+**Edit Fields (Set) (n8n-nodes-base.set)**
+Purpose: Better choice for combining data from separate/independent branches
+Use for: Adding fields from different sources, preserving binary while adding processed data
+Configuration: Set common fields and use "Include Other Input Fields" OFF to preserve existing data including binary
+
+**Execute Workflow Trigger (n8n-nodes-base.executeWorkflowTrigger)**
+Purpose: Start point for sub-workflows that are called by other workflows
+Configuration: Automatically receives data from the calling workflow including binary data
+Best practice: Use for modular workflow design, heavy processing tasks, or reusable workflow components
+Pairing: Must be used with Execute Workflow node in the parent workflow
+
+**Execute Workflow (n8n-nodes-base.executeWorkflow)**
+Purpose: Call and execute another workflow from within the current workflow
+Critical configurations:
+- Workflow ID: Use expression "{{ $workflow.id }}" to reference sub-workflows in the same workflow
+- Choose execution mode: "Run Once for All Items" or "Run Once for Each Item"
+- Binary data is automatically passed to the sub-workflow
+Best practice: Use for delegating heavy processing, creating reusable modules, or managing memory in large batch operations
+
+### Data Destinations
+
+**DataTable (n8n-nodes-base.dataTable)**
+Purpose: Store extracted data in n8n's built-in data tables
+Operations: Insert, Update, Select rows without external dependencies
+Best for: Self-contained workflows that don't require external storage
+
+**Google Sheets (n8n-nodes-base.googleSheets)**
+Purpose: Log extracted data in external spreadsheet
+Operations: Use "Append" for new rows, "Update" with key column for existing
+Best for: Collaborative review and manual data validation
+
+**Database Nodes**
+- Postgres (n8n-nodes-base.postgres)
+- MySQL (n8n-nodes-base.mySql)
+- MongoDB (n8n-nodes-base.mongoDb)
+Purpose: Store structured extraction results in production databases
+Best Practice: Validate data schema before insert
+
+### Utilities
+
+**IF/Switch (n8n-nodes-base.if, n8n-nodes-base.switch)**
+Purpose: Route based on file type, extraction quality, or classification
+
+**Function/Code (n8n-nodes-base.function, n8n-nodes-base.code)**
+Purpose: Custom validation, data transformation, or regex extraction
+
+**HTTP Request (n8n-nodes-base.httpRequest)**
+Purpose: Call external OCR APIs (OCR.space, Google Vision, Mistral OCR)
+Configuration: Set "Response Format: File" for downloads
+Critical: NEVER set API keys directly in the request - user can set credentials from the UI for secure API key management
+
+## Common Pitfalls to Avoid
+
+### Binary Data Loss
+
+**Problem**: Binary file "disappears" after processing nodes
+**Solution**:
+- Use Merge node to reattach binary after processing
+- Or configure nodes to explicitly keep binary data
+- In Code nodes: copy items[0].binary to output
+
+### Incorrect OCR Fallback
+
+**Problem**: Not detecting when text extraction fails
+**Solution**:
+- Always check if extraction result is empty
+- Implement automatic OCR fallback for scanned documents
+- Don't assume all PDFs have extractable text
+
+### API Format Mismatches
+
+**Problem**: Sending files in wrong format to APIs
+**Solution**:
+- Check if API needs multipart/form-data vs Base64
+- Use "Extract from File" and "Convert to File" format conversion
+
+### Memory Overload
+
+**Problem**: Workflow crashes with large or multiple files
+**Solution**:
+- Process files sequentially or in small batches
+- Enable filesystem mode for binary data storage
+- Drop unnecessary data after extraction
+- Create a sub-workflow in the same workflow using "When Executed by Another Workflow" and "Execute Workflow". Delegate the heavy part of the workflow to the sub-workflow.
+
+### Duplicate Processing
+
+**Problem**: Same documents processed repeatedly
+**Solution**:
+- Configure email triggers to mark as read
+- Use "unseen" filters for email fetching
+- Implement deduplication logic based on file hash or name`;
+    getDocumentation() {
+        return this.documentation;
+    }
+}
+exports.DocumentProcessingBestPractices = DocumentProcessingBestPractices;
+//# sourceMappingURL=document-processing.js.map

package/dist/tools/best-practices/document-processing.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"document-processing.js","sourceRoot":"","sources":["../../../src/tools/best-practices/document-processing.ts"],"names":[],"mappings":";;;AACA,2DAA2D;AAE3D,MAAa,+BAA+B;IAClC,SAAS,GAAG,kCAAiB,CAAC,mBAAmB,CAAC;IAClD,OAAO,GAAG,OAAO,CAAC;IAEV,aAAa,GAAG;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;2DAsTyB,CAAC;IAE3D,gBAAgB;QACf,OAAO,IAAI,CAAC,aAAa,CAAC;IAC3B,CAAC;CACD;AA/TD,0EA+TC"}

package/dist/tools/best-practices/enrichment.d.ts

@@ -0,0 +1,7 @@
+import type { BestPracticesDocument } from '../../types/best-practices';
+export declare class EnrichmentBestPractices implements BestPracticesDocument {
+    readonly technique: "enrichment";
+    readonly version = "1.0.0";
+    private readonly documentation;
+    getDocumentation(): string;
+}

package/dist/tools/best-practices/enrichment.js

@@ -0,0 +1,271 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.EnrichmentBestPractices = void 0;
+const categorization_1 = require("../../types/categorization");
+class EnrichmentBestPractices {
+    technique = categorization_1.WorkflowTechnique.ENRICHMENT;
+    version = '1.0.0';
+    documentation = `# Best Practices: Data Enrichment Workflows
+
+## Workflow Design
+
+### Core Principles
+- Start with data retrieval and validation before enrichment
+- Process data incrementally to avoid overwhelming APIs
+- Always include error handling for failed enrichments
+- Design for reusability with sub-workflows where appropriate
+
+### Architecture Pattern
+1. **Input Stage**: Validate and prepare incoming data
+2. **Enrichment Stage**: Parallel or sequential API calls based on dependencies
+3. **Transformation Stage**: Normalize and merge enriched data
+4. **Output Stage**: Format and deliver enriched results
+
+## Data Enrichment Guidelines
+
+### 1. Input Validation
+**Always validate incoming data before enrichment**
+- Use IF node (n8n-nodes-base.if) to check for required fields
+- Implement Set node (n8n-nodes-base.set) to standardize data format
+- Add Code node (n8n-nodes-base.code) for complex validation logic
+
+### 2. API Rate Limiting
+**Respect external service limits**
+- Implement Wait node (n8n-nodes-base.wait) between batch requests
+- Use SplitInBatches node (n8n-nodes-base.splitInBatches) for large datasets
+- Set batch size: 10-50 items depending on API limits
+- Add delay: 1-2 seconds between batches
+
+### 3. Error Handling
+**Build resilient enrichment flows**
+- Wrap API calls in Try/Catch pattern using Error Trigger node
+- Use StopAndError node (n8n-nodes-base.stopAndError) for critical failures
+- Implement fallback enrichment sources with Switch node (n8n-nodes-base.switch)
+- Log failures to database or file for later retry
+
+### 4. Data Merging
+**Combine enriched data effectively**
+- Use Merge node (n8n-nodes-base.merge) with "Merge By Key" mode
+- Specify unique identifiers for accurate matching
+- Handle missing enrichment data with default values
+- Preserve original data alongside enrichments
+
+### 5. Caching Strategy
+**Minimize redundant API calls**
+- Check cache before making external requests
+- Use Redis node (n8n-nodes-base.redis) or database for caching
+- Set appropriate TTL values:
+  - Static data: 7-30 days
+  - Dynamic data: 1-24 hours
+  - Real-time data: No caching
+
+### 6. Field Mapping
+**Standardize enriched data structure**
+- Use Set node to rename fields consistently
+- Remove unnecessary fields with unset operations
+- Apply data transformations in Code node for complex mappings
+- Document field mappings in workflow description
+
+### 7. Quality Scoring
+**Assess enrichment quality**
+- Add confidence scores to enriched fields
+- Track enrichment source for each field
+- Implement validation rules for enriched data
+- Flag incomplete or suspicious enrichments
+
+## Recommended Nodes
+
+### Essential Nodes
+
+**HTTP Request** (n8n-nodes-base.httpRequest):
+- Purpose: Primary enrichment API calls
+- Use cases: Call external APIs for data enrichment
+- Best practices: Configure proper authentication, handle timeouts
+
+**Merge** (n8n-nodes-base.merge):
+- Purpose: Combine original and enriched data
+- Modes: Merge By Key, Merge By Index, Append
+- Best practices: Use unique identifiers for matching, handle missing data
+
+**Set** (n8n-nodes-base.set):
+- Purpose: Transform and standardize data
+- Use cases: Rename fields, remove unnecessary data, add metadata
+- Best practices: Use "Keep Only Set" carefully, document transformations
+
+**IF** (n8n-nodes-base.if):
+- Purpose: Conditional enrichment logic
+- Use cases: Validate required fields, route based on data quality
+- Best practices: Check for null values, validate data types
+
+**SplitInBatches** (n8n-nodes-base.splitInBatches):
+- Purpose: Process large datasets in chunks
+- Use cases: Handle datasets with 100+ items
+- Best practices: Set appropriate batch size (10-50 items), add delays
+
+### Enrichment Sources
+
+**Clearbit** (n8n-nodes-base.clearbit):
+- Purpose: Company and person enrichment
+- Use cases: Enrich email addresses with company data, get person details
+- Best practices: Handle rate limits, cache results
+
+**Hunter** (n8n-nodes-base.hunter):
+- Purpose: Email finder and verification
+- Use cases: Find email addresses, verify email validity
+- Best practices: Respect API quotas, handle verification failures
+
+**Brandfetch** (n8n-nodes-base.Brandfetch):
+- Purpose: Company branding data
+- Use cases: Get company logos, colors, brand assets
+- Best practices: Cache brand data, handle missing brands
+
+**OpenAI** (@n8n/n8n-nodes-langchain.openAi):
+- Purpose: AI-powered data enrichment
+- Use cases: Extract insights, classify data, generate descriptions
+- Best practices: Minimize token usage, batch similar requests
+
+**Google Sheets** (n8n-nodes-base.googleSheets):
+- Purpose: Lookup table enrichment
+- Use cases: Reference data enrichment, mapping tables
+- Best practices: Use efficient lookup methods, cache sheet data
+
+### Utility Nodes
+
+**Code** (n8n-nodes-base.code):
+- Purpose: Custom enrichment logic
+- Use cases: Complex transformations, custom algorithms
+- Best practices: Keep code modular, handle errors gracefully
+
+**Wait** (n8n-nodes-base.wait):
+- Purpose: Rate limiting delays
+- Use cases: Add delays between API calls, implement backoff
+- Best practices: Use appropriate delay values (1-2 seconds)
+
+**DateTime** (n8n-nodes-base.dateTime):
+- Purpose: Timestamp handling
+- Use cases: Add enrichment timestamps, calculate ages
+- Best practices: Use consistent timezone handling
+
+**Redis** (n8n-nodes-base.redis):
+- Purpose: Caching layer
+- Use cases: Cache enrichment results, track processed items
+- Best practices: Set appropriate TTL, handle cache misses
+
+**Error Trigger** (n8n-nodes-base.errorTrigger):
+- Purpose: Error handling workflow
+- Use cases: Global error handling, logging failures
+- Best practices: Implement retry logic, alert on critical failures
+
+**Switch** (n8n-nodes-base.switch):
+- Purpose: Route based on enrichment results
+- Use cases: Fallback enrichment sources, quality-based routing
+- Best practices: Always define default case
+
+**Stop and Error** (n8n-nodes-base.stopAndError):
+- Purpose: Halt workflow on critical failures
+- Use cases: Stop processing on invalid data, critical API failures
+- Best practices: Use for unrecoverable errors only
+
+## Common Pitfalls to Avoid
+
+### Performance Issues
+
+**Problem**: Enriching all fields for every record
+- **Solution**: Only enrich fields that are actually needed
+- Profile your workflow to identify bottlenecks
+- Use conditional enrichment based on data needs
+
+**Problem**: Sequential processing of independent enrichments
+- **Solution**: Use parallel branches for non-dependent enrichments
+- Split workflow into parallel paths
+- Merge results after parallel processing
+
+**Problem**: No batching for large datasets
+- **Solution**: Always use SplitInBatches for >100 items
+- Set appropriate batch sizes (10-50 items)
+- Add delays between batches
+
+### Data Quality Problems
+
+**Problem**: Overwriting original data with enrichments
+- **Solution**: Preserve original data and add enriched fields separately
+- Use Set node to add new fields without removing original ones
+- Document which fields are enriched
+
+**Problem**: Not handling null or missing enrichment results
+- **Solution**: Implement fallback values and error flags
+- Use IF nodes to check for empty results
+- Add default values for missing enrichments
+
+**Problem**: Mixing data types in enriched fields
+- **Solution**: Enforce consistent data types through validation
+- Convert types explicitly in Set or Code nodes
+- Document expected data types
+
+### Resource Management
+
+**Problem**: No rate limiting on external APIs
+- **Solution**: Implement delays and respect API quotas
+- Use Wait node between API calls
+- Monitor API usage and adjust delays
+
+**Problem**: Infinite retry loops on failures
+- **Solution**: Set maximum retry attempts (typically 3)
+- Use exponential backoff for retries
+- Log failed attempts for manual review
+
+**Problem**: No caching of expensive enrichments
+- **Solution**: Cache results with appropriate expiration times
+- Use Redis or database for caching
+- Set TTL based on data freshness requirements
+
+### Workflow Design Flaws
+
+**Problem**: Single point of failure for entire enrichment
+- **Solution**: Use error boundaries and continue on failure options
+- Enable "Continue on Fail" for non-critical enrichments
+- Implement Error Trigger workflow
+
+**Problem**: Hard-coded API keys in workflows
+- **Solution**: Use credentials and environment variables
+- Store sensitive data in n8n credentials system
+- Never commit credentials in workflow JSON
+
+**Problem**: No monitoring or logging of enrichment quality
+- **Solution**: Add metrics collection and alerting
+- Log enrichment success/failure rates
+- Track enrichment coverage and quality
+
+### Common Error Scenarios
+
+**API Rate Limits**:
+- Implement exponential backoff
+- Add Wait nodes with increasing delays
+- Use SplitInBatches to control request rate
+
+**Invalid API Responses**:
+- Validate response structure before processing
+- Use IF nodes to check response format
+- Log unexpected responses for debugging
+
+**Timeout Issues**:
+- Set reasonable timeout values (10-30s)
+- Use shorter timeouts for non-critical enrichments
+- Implement retry logic for timeouts
+
+**Data Mismatches**:
+- Use fuzzy matching for lookups
+- Normalize data before matching
+- Handle missing keys gracefully
+
+**Duplicate Enrichments**:
+- Implement deduplication logic
+- Check cache before enriching
+- Use unique identifiers for tracking
+`;
+    getDocumentation() {
+        return this.documentation;
+    }
+}
+exports.EnrichmentBestPractices = EnrichmentBestPractices;
+//# sourceMappingURL=enrichment.js.map

package/dist/tools/best-practices/enrichment.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"enrichment.js","sourceRoot":"","sources":["../../../src/tools/best-practices/enrichment.ts"],"names":[],"mappings":";;;AACA,2DAA2D;AAE3D,MAAa,uBAAuB;IAC1B,SAAS,GAAG,kCAAiB,CAAC,UAAU,CAAC;IACzC,OAAO,GAAG,OAAO,CAAC;IAEV,aAAa,GAAG;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;CAiQjC,CAAC;IAED,gBAAgB;QACf,OAAO,IAAI,CAAC,aAAa,CAAC;IAC3B,CAAC;CACD;AA1QD,0DA0QC"}

package/dist/tools/best-practices/human-in-the-loop.d.ts

@@ -0,0 +1,7 @@
+import type { BestPracticesDocument } from '../../types/best-practices';
+export declare class HumanInTheLoopBestPractices implements BestPracticesDocument {
+    readonly technique: "human_in_the_loop";
+    readonly version = "1.0.0";
+    private readonly documentation;
+    getDocumentation(): string;
+}