@n8n/workflow-sdk 0.9.0 → 0.11.0

package/dist/prompts/best-practices/guides/data-extraction.d.ts

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

package/dist/prompts/best-practices/guides/data-extraction.js

@@ -0,0 +1,124 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.DataExtractionBestPractices = void 0;
+const types_1 = require("../types");
+class DataExtractionBestPractices {
+    constructor() {
+        this.technique = types_1.WorkflowTechnique.DATA_EXTRACTION;
+        this.version = '1.0.0';
+        this.documentation = `# Best Practices: Data Extraction Workflows
+
+## Node Selection by Data Type
+
+Choose the right node for your data source. Use Extract From File for CSV, Excel, PDF, and text files to convert binary data to JSON for further processing.
+
+Use Information Extractor or AI nodes for extracting structured data from unstructured text such as PDFs or emails using LLMs.
+
+For binary data, ensure you use nodes like Extract From File to handle files properly.
+
+### 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
+
+## Data Structure & Type Management
+
+Normalize data structure early in your workflow. Use transformation nodes like Split Out, Aggregate, or Set to ensure your data matches n8n's expected structure: an array of objects with a json key.
+Not transforming incoming data to n8n's expected format causes downstream node failures.
+
+When working with large amounts of information, n8n's display can be hard to view. Use the Edit Fields node to help organize and view data more clearly during development and debugging.
+
+## Large File Handling
+
+Process files in batches or use sub-workflows to avoid memory issues. For large binary files, consider enabling filesystem mode (N8N_DEFAULT_BINARY_DATA_MODE=filesystem) if self-hosted, to store binary data on disk instead of memory.
+
+Processing too many items or large files at once can crash your instance. Always batch or split processing for large datasets to manage memory effectively.
+
+## Binary Data Management
+
+Binary data can be lost if intermediate nodes (like Set or Code) do not have "Include Other Input Fields" enabled, especially in sub-workflows. Always verify binary data is preserved through your workflow pipeline.
+
+## AI-Powered Extraction
+
+Leverage AI for unstructured data using nodes like Information Extractor or Summarization Chain to extract structured data from unstructured sources such as PDFs, emails, or web pages.
+
+## Recommended Nodes
+
+### Loop Over Items (n8n-nodes-base.splitInBatches)
+
+Purpose: Looping over a set of items extracted from a data set, for example if pulling a lot of data
+from a Google Sheet or database then looping over the items is required. This node MUST be used
+if the user mentions a large amount of data, it is necessary to batch the data to process all of it.
+
+### Extract From File (n8n-nodes-base.extractFromFile)
+
+Purpose: Converts binary data from CSV, Excel, PDF, and text files to JSON for processing
+
+Pitfalls:
+
+- Ensure the correct binary field name is specified in the node configuration
+- Verify file format compatibility before extraction
+
+### HTML Extract (n8n-nodes-base.htmlExtract)
+
+Purpose: Scrapes data from web pages using CSS selectors
+
+### Split Out (n8n-nodes-base.splitOut)
+
+Purpose: Processes arrays of items individually for sequential operations.
+Example: If retrieving a JSON array using a HTTP request, this will return a single item,
+containing that array. If you wish to use a Loop Over Items (n8n-nodes-base.splitInBatches) node]
+then you will need to split out the array into items before looping over it. In a scenario like
+this a split out node MUST be used before looping over the items.
+
+### Edit Fields (Set) (n8n-nodes-base.set)
+
+Purpose: Data transformation and mapping to normalize structure
+
+Pitfalls:
+
+- Enable "Include Other Input Fields" to preserve binary data
+- Pay attention to data types - mixing types causes unexpected failures
+
+### Information Extractor (@n8n/n8n-nodes-langchain.informationExtractor)
+
+Purpose: AI-powered extraction of structured data from unstructured text
+
+Pitfalls:
+
+- Requires proper schema definition for extraction
+
+### Summarization Chain (@n8n/n8n-nodes-langchain.chainSummarization)
+
+Purpose: Summarizes large text blocks using AI for condensed information extraction
+
+Pitfalls:
+
+- Context window limits may truncate very long documents
+- Verify summary quality matches requirements
+
+### HTTP Request (n8n-nodes-base.httpRequest)
+
+Purpose: Fetches data from APIs or web pages for extraction
+
+### Code (n8n-nodes-base.code)
+
+Purpose: Custom logic for complex data transformations
+
+## Common Pitfalls to Avoid
+
+Data Type Confusion: People often mix up data types - n8n can be very lenient but it can lead to problems. Pay close attention to what type you are getting and ensure consistency throughout the workflow.
+
+Binary Data Loss: Binary data can be lost if intermediate nodes (Set, Code) do not have "Include Other Input Fields" enabled, especially in sub-workflows. Always verify binary data preservation.
+
+Large Data Display Issues: n8n displaying large amounts of information can be hard to view during development. Use the Edit Fields node to help organize and view data more clearly.
+`;
+    }
+    getDocumentation() {
+        return this.documentation;
+    }
+}
+exports.DataExtractionBestPractices = DataExtractionBestPractices;
+//# sourceMappingURL=data-extraction.js.map

package/dist/prompts/best-practices/guides/data-extraction.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"data-extraction.js","sourceRoot":"","sources":["../../../../src/prompts/best-practices/guides/data-extraction.ts"],"names":[],"mappings":";;;AACA,oCAA6C;AAE7C,MAAa,2BAA2B;IAAxC;QACU,cAAS,GAAG,yBAAiB,CAAC,eAAe,CAAC;QAC9C,YAAO,GAAG,OAAO,CAAC;QAEV,kBAAa,GAAG;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;CA4GjC,CAAC;IAKF,CAAC;IAHA,gBAAgB;QACf,OAAO,IAAI,CAAC,aAAa,CAAC;IAC3B,CAAC;CACD;AArHD,kEAqHC"}

package/dist/prompts/best-practices/guides/data-persistence.d.ts

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

package/dist/prompts/best-practices/guides/data-persistence.js

@@ -0,0 +1,199 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.DataPersistenceBestPractices = void 0;
+const types_1 = require("../types");
+class DataPersistenceBestPractices {
+    constructor() {
+        this.technique = types_1.WorkflowTechnique.DATA_PERSISTENCE;
+        this.version = '1.0.0';
+        this.documentation = `# Best Practices: Data Persistence
+
+## Overview
+
+Data persistence involves storing, updating, or retrieving records from durable storage systems. This technique is essential when you need to maintain data beyond the lifetime of a single workflow execution, or when you need to access existing data that users have stored in their spreadsheets, tables, or databases as part of your workflow logic.
+
+## When to Use Data Persistence
+
+Use data persistence when you need to:
+- Store workflow results for later retrieval or audit trails
+- Maintain records that multiple workflows can access and update
+- Create a centralized data repository for your automation
+- Archive historical data for reporting or compliance
+- Build data that persists across workflow executions
+- Track changes or maintain state over time
+- Store raw form inputs
+
+## Choosing the Right Storage Node
+
+### Data Table (n8n-nodes-base.dataTable) - PREFERRED
+
+**Best for:** Quick setup, small to medium amounts of data
+
+Advantages:
+- No credentials or external configuration required
+- Built directly into n8n
+- Fast and reliable for small to medium datasets
+- Ideal for prototyping and internal workflows
+- No additional costs or external dependencies
+
+When to use:
+- Internal workflow data storage
+- Temporary or staging data
+- Admin/audit trails
+- Simple record keeping
+- Development and testing
+
+### Google Sheets (n8n-nodes-base.googleSheets)
+
+**Best for:** Collaboration, reporting, easy data sharing
+
+Advantages:
+- Familiar spreadsheet interface for non-technical users
+- Easy to share and collaborate on data
+- Built-in visualization and formula capabilities
+- Good for reporting and dashboards
+- Accessible from anywhere
+
+When to use:
+- Data needs to be viewed/edited by multiple people
+- Non-technical users need access to data
+- Integration with other Google Workspace tools
+- Simple data structures without complex relationships
+- Workflow needs access to existing spreadsheets in Google Sheets
+
+Pitfalls:
+- API rate limits can affect high-volume workflows
+- Not suitable for frequently changing data
+- Performance degrades with very large datasets (>10k rows)
+
+### Airtable (n8n-nodes-base.airtable)
+
+**Best for:** Structured data with relationships, rich field types
+
+Advantages:
+- Supports relationships between tables
+- Rich field types (attachments, select, links, etc.)
+- Better structure than spreadsheets
+
+When to use:
+- Data has relationships or references between records
+- Need structured database-like features
+- Managing projects, tasks, or inventory
+- Workflow needs access to existing data in Airtable
+
+Pitfalls:
+- Requires Airtable account and API key
+- Schema changes require careful planning
+
+## Storage Patterns
+
+### Immediate Storage Pattern
+
+Store data immediately after collection or generation:
+
+\`\`\`mermaid
+flowchart LR
+    Trigger --> Process_Data["Process Data"]
+    Process_Data --> Storage_Node["Storage Node"]
+    Storage_Node --> Continue_Workflow["Continue Workflow"]
+\`\`\`
+
+Best for: Raw data preservation, audit trails, form submissions
+
+### Batch Storage Pattern
+
+Collect multiple items and store them together:
+
+\`\`\`mermaid
+flowchart LR
+    Trigger --> Loop_Split["Loop/Split"]
+    Loop_Split --> Process["Process"]
+    Process --> Aggregate["Aggregate"]
+    Aggregate --> Storage_Node["Storage Node"]
+\`\`\`
+
+Best for: Processing lists, batch operations, scheduled aggregations
+
+### Update Pattern
+
+Retrieve, modify, and update existing records:
+
+\`\`\`mermaid
+flowchart LR
+    Trigger --> Retrieve["Retrieve from Storage"]
+    Retrieve --> Modify["Modify"]
+    Modify --> Update_Storage["Update Storage Node"]
+\`\`\`
+
+Best for: Maintaining state, updating records, tracking changes
+
+### Lookup Pattern
+
+Query storage to retrieve specific records:
+
+\`\`\`mermaid
+flowchart LR
+    Trigger --> Query_Storage["Query Storage Node"]
+    Query_Storage --> Use_Data["Use Retrieved Data"]
+    Use_Data --> Continue_Workflow["Continue Workflow"]
+\`\`\`
+
+Best for: Enrichment, validation, conditional logic based on stored data
+
+## Key Considerations
+
+### Data Structure
+
+- **Plan your schema ahead:** Define what fields you need before creating storage
+- **Use consistent field names:** Match field names across your workflow for easy mapping
+- **Consider data types:** Ensure your storage supports the data types you need
+- **Think about relationships:** If data is related, consider Airtable or use multiple tables
+
+### Performance
+
+- **Batch operations when possible:** Multiple small writes are slower than batch operations
+- **Use appropriate operations:** Use "append" for new records, "update" for modifications
+- **Consider API limits:** Google Sheets has rate limits; plan accordingly for high-volume workflows
+
+### Data Integrity
+
+- **Store raw data first:** Keep unmodified input before transformations
+- **Handle errors gracefully:** Use error handling to prevent data loss on failures
+- **Validate before storing:** Ensure data quality before persistence
+- **Avoid duplicates:** Use unique identifiers or upsert operations when appropriate
+
+## Referencing Documents, Sheets, or Tables
+
+When configuring storage nodes, use ResourceLocator mode "list". This will allow users to select from existing documents, sheets, or tables rather than passing IDs dynamically.
+Use modes "id", "url" or "name" only when user specifically mentions it in their prompt.
+
+## Important Distinctions
+
+### Storage vs. Transformation
+
+- **Set/Merge nodes are NOT storage:** They transform data in memory only
+- **Storage happens explicitly:** Data won't persist unless you explicitly write it to storage
+
+### Temporary vs. Persistent Storage
+
+- **NOT covered by this technique:** Redis, caching, session storage, in-memory operations
+- **This technique covers:** Durable storage that persists beyond workflow execution
+- **Focus on permanence:** Use these nodes when you need data to survive restarts and be queryable later
+
+## Common Pitfalls to Avoid
+
+### Not Handling Duplicates
+
+Without proper unique identifiers or upsert logic, you may create duplicate records. Use unique IDs or check for existing records before inserting.
+
+### Ignoring Storage Limits
+
+Each storage system has limits (row counts, API rates, file sizes). Design your workflow to work within these constraints or implement pagination/batching.
+`;
+    }
+    getDocumentation() {
+        return this.documentation;
+    }
+}
+exports.DataPersistenceBestPractices = DataPersistenceBestPractices;
+//# sourceMappingURL=data-persistence.js.map

package/dist/prompts/best-practices/guides/data-persistence.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"data-persistence.js","sourceRoot":"","sources":["../../../../src/prompts/best-practices/guides/data-persistence.ts"],"names":[],"mappings":";;;AACA,oCAA6C;AAE7C,MAAa,4BAA4B;IAAzC;QACU,cAAS,GAAG,yBAAiB,CAAC,gBAAgB,CAAC;QAC/C,YAAO,GAAG,OAAO,CAAC;QAEV,kBAAa,GAAG;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;CAuLjC,CAAC;IAKF,CAAC;IAHA,gBAAgB;QACf,OAAO,IAAI,CAAC,aAAa,CAAC;IAC3B,CAAC;CACD;AAhMD,oEAgMC"}

package/dist/prompts/best-practices/guides/data-transformation.d.ts

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

package/dist/prompts/best-practices/guides/data-transformation.js

@@ -0,0 +1,148 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.DataTransformationBestPractices = void 0;
+const types_1 = require("../types");
+class DataTransformationBestPractices {
+    constructor() {
+        this.technique = types_1.WorkflowTechnique.DATA_TRANSFORMATION;
+        this.version = '1.0.0';
+        this.documentation = `# Best Practices: Data Transformation
+
+## Workflow Design
+
+### Core Principles
+- **Structure**: Always follow Input → Transform → Output pattern
+- **Optimization**: Filter and reduce data early to improve performance
+
+### Design Best Practices
+- Plan transformation requirements in plain language before building
+- Use Modular Design: Create reusable sub-workflows for common tasks like "Data Cleaning" or "Error Handler"
+- Batch datasets over 100 items using Split In Batches node to prevent timeouts
+
+## Recommended Nodes
+
+### Essential Transformation Nodes
+
+#### Edit Fields (Set) (n8n-nodes-base.set)
+
+**Purpose**: Create, modify, rename fields; change data types
+
+**Key Setting**: "Keep Only Set" - drops all fields not explicitly defined (default: disabled)
+
+**Use Cases**:
+- Extract specific columns
+- Add calculated fields
+- Convert data types (string to number)
+- Format dates using expressions
+
+**Pitfalls**:
+- Not understanding "Keep Only Set" behavior can lead to data loss
+- Enabled: Drops all fields not explicitly defined (data loss risk)
+- Disabled: Carries forward all fields (potential bloat)
+- Always verify output structure after configuration
+
+**Testing tip**: When transforming data from a workflow trigger, you can set values with a fallback default e.g. set name to {{$json.name || 'Jane Doe'}} to help test the workflow.
+
+#### IF/Filter Nodes
+
+**IF Node** (n8n-nodes-base.if):
+- **Purpose**: Conditional processing and routing
+- **Best Practice**: Use early to validate inputs and remove bad data
+- **Example**: Check if required fields exist before processing
+
+**Filter Node** (n8n-nodes-base.filter):
+- **Purpose**: Filter items based on conditions
+- **Best Practice**: Use early in workflow to reduce data volume
+
+#### Merge Node (n8n-nodes-base.merge)
+
+**Purpose**: Combine two data streams
+
+**Modes**:
+- Merge by Key (like database join)
+- Merge by Index
+- Append
+
+**Pitfalls**:
+- **Missing Keys**: Trying to merge on non-existent fields
+- **Field Name Mismatch**: Different field names in sources
+- **Solution**: Use Edit Fields node to normalize field names before merging
+
+#### Code Node (n8n-nodes-base.code)
+
+**Execution Modes**:
+- "Run Once per Item": Process each item independently
+- "Run Once for All Items": Access entire dataset (for aggregation)
+
+**Return Format**: Must return array of objects with json property
+\`\`\`javascript
+return items; // or return [{ json: {...} }];
+\`\`\`
+
+**Pitfalls**:
+- Wrong return format: Not returning array of objects with json property
+- Overly complex: Stuffing entire workflow logic in one Code node
+- Keep code nodes focused on single transformation aspect
+
+#### Summarize Node (n8n-nodes-base.summarize)
+
+**Purpose**: Pivot table-style aggregations (count, sum, average, min/max)
+
+**Configuration**:
+- Fields to Summarize: Choose aggregation function
+- Fields to Split By: Grouping keys
+
+**Output**: Single item with summary or multiple items per group
+
+### Data Restructuring Nodes
+
+- **Split Out** (n8n-nodes-base.splitOut): Convert single item with array into multiple items
+- **Aggregate** (n8n-nodes-base.aggregate): Combine multiple items into one
+- **Remove Duplicates** (n8n-nodes-base.removeDuplicates): Delete duplicate items based on field criteria
+- **Sort** (n8n-nodes-base.sort): Order items alphabetically/numerically
+- **Limit** (n8n-nodes-base.limit): Trim to maximum number of items
+
+### Batch Processing
+
+**Split In Batches** (n8n-nodes-base.splitInBatches):
+- **Purpose**: Process large datasets in chunks
+- **Use When**: Handling 100+ items with expensive operations (API calls, AI)
+
+## Input Data Validation
+- Validate external data before processing: check for nulls, empty values, and edge cases (special chars, empty arrays)
+
+## Common Pitfalls to Avoid
+
+### Critical Mistakes
+
+#### Edit Fields Node Issues
+- **Mistake**: Not understanding "Keep Only Set" behavior
+  - Enabled: Drops all fields not explicitly defined (data loss risk)
+  - Disabled: Carries forward all fields (potential bloat)
+- **Solution**: Always verify output structure after configuration
+
+#### Code Node Errors
+- **Wrong Return Format**: Not returning array of objects with json property
+- **Fix**: Always return \`items\` or \`[{ json: {...} }]\`
+- **Overly Complex**: Stuffing entire workflow logic in one Code node
+- **Fix**: Keep code nodes focused on single transformation aspect
+
+#### Merge Node Problems
+- **Field Name Mismatch**: Different field names in sources
+- **Fix**: Normalize field names with Edit Fields before merging
+
+### Performance Pitfalls
+- Processing large datasets without batching → timeouts
+- Not filtering early → unnecessary processing overhead
+- Excessive node chaining → visual clutter and slow execution
+
+### Data Validation Pitfalls
+- Assuming input data is always perfect → runtime errors
+`;
+    }
+    getDocumentation() {
+        return this.documentation;
+    }
+}
+exports.DataTransformationBestPractices = DataTransformationBestPractices;
+//# sourceMappingURL=data-transformation.js.map

package/dist/prompts/best-practices/guides/data-transformation.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"data-transformation.js","sourceRoot":"","sources":["../../../../src/prompts/best-practices/guides/data-transformation.ts"],"names":[],"mappings":";;;AACA,oCAA6C;AAE7C,MAAa,+BAA+B;IAA5C;QACU,cAAS,GAAG,yBAAiB,CAAC,mBAAmB,CAAC;QAClD,YAAO,GAAG,OAAO,CAAC;QAEV,kBAAa,GAAG;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;CAoIjC,CAAC;IAKF,CAAC;IAHA,gBAAgB;QACf,OAAO,IAAI,CAAC,aAAa,CAAC;IAC3B,CAAC;CACD;AA7ID,0EA6IC"}

package/dist/prompts/best-practices/guides/document-processing.d.ts

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