@n8n/ai-workflow-builder 1.16.0 → 1.17.0

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

@@ -1,152 +0,0 @@
-"use strict";
-Object.defineProperty(exports, "__esModule", { value: true });
-exports.SchedulingBestPractices = void 0;
-const categorization_1 = require("../../types/categorization");
-class SchedulingBestPractices {
-    technique = categorization_1.WorkflowTechnique.SCHEDULING;
-    version = '1.0.0';
-    documentation = `# Best Practices: Scheduling Workflows
-
-## Workflow Design
-
-Structure scheduled workflows to perform focused, well-defined tasks.
-
-For recurring tasks, use Schedule Trigger node with clear naming (e.g., "Daily 08:00 Trigger", "Every 6h Cron").
-
-Prevent overlapping executions by ensuring worst-case execution time < schedule interval. For frequent schedules, implement mutex/lock mechanisms using external systems if needed.
-
-## Scheduling Patterns
-
-### Recurring Schedules
-
-Use Schedule Trigger in two modes:
-- **Interval Mode**: User-friendly dropdowns for common schedules (every X minutes, daily at 09:00, weekly on Mondays)
-- **Cron Expression Mode**: Complex patterns using 5-field syntax (m h dom mon dow) with optional seconds field. Example: \`0 9 * * 1\` triggers every Monday at 09:00
-
-Multiple schedules can be combined in single Schedule Trigger node using multiple Trigger Rules. Useful when same logic applies to different timings.
-
-### One-Time Events
-
-For event-relative scheduling, use Wait node to pause workflow until specified time/date.
-
-Note: Cron expressions with specific dates (e.g., \`0 12 22 10 *\` for Oct 22 at 12:00) will repeat annually on that date.
-
-### Conditional Scheduling
-
-PREFER conditional logic over complex cron expressions. Use IF/Switch nodes after Schedule Trigger for runtime conditions:
-- Check if today is last day of month before running monthly reports
-- Skip execution on holidays by checking against a holiday list in a data table
-- Route to "weekday" vs "weekend" processing based on current day
-
-This approach is more readable and maintainable than complex cron patterns.
-
-## Time Zone Handling
-
-When building scheduled workflows:
-- If user specifies a timezone, set it in the Schedule Trigger node's timezone parameter
-- If user mentions times without timezone, use the schedule as specified (instance default will apply)
-- For Wait nodes, be aware they use server system time, not workflow timezone
-
-## Recommended Nodes
-
-### Schedule Trigger (n8n-nodes-base.scheduleTrigger)
-
-Primary node for running workflows on schedule. Supports interval mode for simple schedules and cron mode for complex patterns.
-
-### Wait (n8n-nodes-base.wait)
-
-Pause workflow execution until specified time or duration.
-
-Use Cases:
-- Delay actions relative to events
-- One-off timers per data item
-- Follow-up actions after specific duration
-
-Best Practices:
-- Use n8n Data Tables for waits longer than 24 hours (store scheduled time, check periodically)
-- Avoid wait times longer than 7 days - use a polling pattern instead
-
-### IF (n8n-nodes-base.if)
-
-Add conditional logic to scheduled workflows.
-
-Use Cases:
-- Check date conditions (last day of month using expression: \`{{ $now.day === $now.endOf('month').day }}\`)
-- Skip execution based on external data (e.g., holiday check)
-- Route to different actions conditionally
-
-Best Practices:
-- Enable "Convert types where required" for comparisons
-- Prefer IF nodes over complex cron expressions for readability
-
-### Switch (n8n-nodes-base.switch)
-
-Multiple conditional branches for complex routing.
-
-Use Cases:
-- Different actions based on day of week (e.g., \`{{ $now.weekday }}\` returns 1-7)
-- Time-based routing (morning vs afternoon processing)
-- Multi-path conditional execution
-
-### n8n Data Tables (n8n-nodes-base.n8nTables)
-
-Purpose: Store scheduling state and pending tasks
-
-Use Cases:
-- Track last execution time for catch-up logic
-- Store list of pending one-time tasks with scheduled times
-- Implement custom scheduling queue with polling
-
-Best Practices:
-- Query efficiently with proper filters
-- Clean up completed tasks periodically
-
-## Common Pitfalls to Avoid
-
-### Missed Schedules During Downtime
-
-**Problem**: Scheduled runs missed when n8n instance is down. No automatic catch-up for missed triggers.
-
-**Solution**: Design idempotent workflows with catch-up logic:
-- Store last successful run timestamp in n8n Data Tables
-- On each run, check if enough time has passed since last run
-- Example: For a task that should run once per 24 hours, schedule it every 4 hours but only execute if last run was >20 hours ago
-
-### Overlapping Executions
-
-**Problem**: Next scheduled run starts before previous completes, causing race conditions or resource conflicts.
-
-**Solution**:
-- Increase interval to exceed worst-case execution time
-- Implement mutex/lock using n8n Data Tables (check/set "running" flag at start, clear at end)
-- Add execution check at workflow start
-
-### Wait Node Timezone Confusion
-
-**Problem**: Wait node uses server system time, ignoring workflow timezone setting. Wait until "10:00" may not match expected timezone.
-
-**Solution**:
-- Account for server timezone when setting Wait times
-- Use relative durations (e.g., "wait 2 hours") instead of absolute times when possible
-- Prefer Schedule Trigger for timezone-aware scheduling
-
-### First Execution Timing
-
-**Problem**: First execution after activation doesn't match expected schedule. Activation time affects next run calculation.
-
-**Solution**:
-- Use manual execution for immediate first run if needed
-- Understand that schedule recalculates from activation moment
-
-### Cron Syntax
-
-n8n supports both 5-field and 6-field (with seconds) cron syntax. Use 6 fields if you want to specify seconds (e.g., prefix with 0 for seconds: \`0 0 9 * * *\` for 9 AM daily).
-
-For simple schedules, prefer Interval mode over cron for better readability.
-`;
-    getDocumentation() {
-        return this.documentation;
-    }
-}
-exports.SchedulingBestPractices = SchedulingBestPractices;
-//# sourceMappingURL=scheduling.js.map

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

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

package/dist/tools/best-practices/scraping-and-research.d.ts

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

package/dist/tools/best-practices/scraping-and-research.js

@@ -1,158 +0,0 @@
-"use strict";
-Object.defineProperty(exports, "__esModule", { value: true });
-exports.ScrapingAndResearchBestPractices = void 0;
-const categorization_1 = require("../../types/categorization");
-class ScrapingAndResearchBestPractices {
-    technique = categorization_1.WorkflowTechnique.SCRAPING_AND_RESEARCH;
-    version = '1.0.0';
-    documentation = `# Best Practices: Scraping & Research Workflows
-
-## Performance & Resource Management
-
-Batch requests and introduce delays to avoid hitting API rate limits or overloading target servers. Use Wait nodes and
-batching options in HTTP Request nodes. When 429 rate limiting errors occur due to receiving too many requests,
-implement batching to reduce request frequency or use the "Retry on Fail" feature to automatically handle throttled
-responses.
-
-Workflows processing large datasets can crash due to memory constraints. Use the Split In Batches node to process 200
-rows at a time to reduce memory usage, leverage built-in nodes instead of custom code, and increase execution timeouts
-via environment variables for better resource management.
-
-## Looping & Pagination
-
-Implement robust looping for paginated data. Use Set, IF, and Code nodes to manage page numbers and loop conditions,
-ensuring you don't miss data or create infinite loops. Leverage n8n's built-in mechanisms rather than manual approaches:
-use the $runIndex variable to track iterations without additional code nodes, and employ workflow static data or node
-run indexes to maintain state across loop cycles.
-
-## Recommended Nodes
-
-### HTTP Request (n8n-nodes-base.httpRequest)
-
-Purpose: Fetches web pages or API data for scraping and research workflows
-
-Pitfalls:
-
-- Depending on the data which the user wishes to scrape/research, it maybe against the terms of service to attempt to
-fetch it from the site directly. Using scraping nodes is the best way to get around this
-- Double-check URL formatting, query parameters, and ensure all required fields are present to avoid bad request errors
-- Be aware of 429 rate limiting errors when the service receives too many requests - implement batching or use "Retry on
-Fail" feature
-- Refresh expired tokens, verify API keys, and ensure correct permissions to avoid authentication failures
-
-### SerpAPI (@n8n/n8n-nodes-langchain.toolSerpApi)
-
-Purpose: Give an agent the ability to search for research materials and fact-checking results that have been retrieved
-from other sources.
-
-### Perplexity (n8n-nodes-base.perplexityTool)
-
-Purpose: Give an agent the ability to search utilising Perplexity, a powerful tool for finding sources/material for
-generating reports and information.
-
-### HTML Extract (n8n-nodes-base.htmlExtract)
-
-Purpose: Parses HTML and extracts data using CSS selectors for web scraping
-
-Pitfalls:
-
-- Some sites use JavaScript to render content, which may not be accessible via simple HTTP requests. Consider using
-browser automation tools or APIs if the HTML appears empty
-- Validate that the CSS selectors match the actual page structure to avoid extraction failures
-
-### Split Out (n8n-nodes-base.splitOut)
-
-Purpose: Processes lists of items one by one for sequential operations
-
-Pitfalls:
-- Can cause performance issues with very large datasets - consider using Split In Batches instead
-
-### Loop Over Items (Split in Batches) (n8n-nodes-base.splitInBatches)
-
-Purpose: Processes lists of items in batches to manage memory and performance
-
-Pitfalls:
-- Ensure proper loop configuration to avoid infinite loops or skipped data. The index 0
-(first connection) of the loop is treated as the done state, while the index 1 (second connection)
-is the connection that loops.
-- Use appropriate batch sizes (e.g., 200 rows) to balance memory usage and performance
-
-### Edit Fields (Set) (n8n-nodes-base.set)
-
-Purpose: Manipulates data, sets variables for loop control and state management
-
-### Code (n8n-nodes-base.code)
-
-Purpose: Implements custom logic for complex data transformations or pagination
-
-Pitfalls:
-
-- Prefer built-in nodes over custom code to reduce memory usage and improve maintainability
-- Avoid processing very large datasets in a single code execution - use batching
-
-### If (n8n-nodes-base.if)
-
-Purpose: Adds conditional logic for error handling, loop control, or data filtering
-
-Pitfalls:
-- Validate expressions carefully to avoid unexpected branching behavior
-
-### Wait (n8n-nodes-base.wait)
-
-Purpose: Introduces delays to respect rate limits and avoid overloading servers
-
-### Data Tables (n8n-nodes-base.dataTable)
-
-Purpose: Stores scraped data in n8n's built-in persistent data storage
-
-### Google Sheets (n8n-nodes-base.googleSheets)
-
-Purpose: Stores scraped data in spreadsheets for easy access and sharing
-
-### Microsoft Excel 365 (n8n-nodes-base.microsoftExcel)
-
-Purpose: Stores scraped data in Excel files for offline analysis
-
-### Airtable (n8n-nodes-base.airtable)
-
-Purpose: Saves structured data to a database with rich data types and relationships
-
-### AI Agent (@n8n/n8n-nodes-langchain.agent)
-
-Purpose: For research, summarization, and advanced data extraction. AI agents can autonomously gather information
-from websites, analyze content, and organize findings into structured formats, integrating tools for web scraping,
-content analysis, and database storage
-
-### Scraping Nodes
-
-- Phantombuster (n8n-nodes-base.phantombuster)
-- Apify (use HTTP Request or community node)
-- BrightData (use HTTP Request or community node)
-
-Purpose: If the user wishes to scrap data from sites like LinkedIn, Facebook, Instagram, Twitter/X, Indeed, Glassdoor
-or any other service similar to these large providers it is better to use a node designed for this. The scraping
-nodes provide access to these datasets while avoiding issues like rate limiting or breaking terms of service for
-sites like these.
-
-## Common Pitfalls to Avoid
-
-Bad Request Errors: Double-check URL formatting, query parameters, and ensure all required fields are present to
-avoid 400 errors when making HTTP requests.
-
-Rate Limits: Use batching and Wait nodes to avoid 429 errors. When the service receives too many requests, implement
-batching to reduce request frequency or use the "Retry on Fail" feature.
-
-Memory Issues: Avoid processing very large datasets in a single run; use batching and increase server resources if
-needed. Use Split In Batches node to process 200 rows at a time, leverage built-in nodes instead of custom code, and
-increase execution timeouts via environment variables.
-
-Empty or Unexpected Data: Some sites use JavaScript to render content, which may not be accessible via simple HTTP
-requests. Standard HTTP and HTML parsing nodes fail because sites load data asynchronously via JavaScript, leaving the
-initial HTML empty of actual content. Web scraping nodes can be used to avoid this.
-`;
-    getDocumentation() {
-        return this.documentation;
-    }
-}
-exports.ScrapingAndResearchBestPractices = ScrapingAndResearchBestPractices;
-//# sourceMappingURL=scraping-and-research.js.map

package/dist/tools/best-practices/scraping-and-research.js.map

@@ -1 +0,0 @@
-{"version":3,"file":"scraping-and-research.js","sourceRoot":"","sources":["../../../src/tools/best-practices/scraping-and-research.ts"],"names":[],"mappings":";;;AACA,2DAA2D;AAE3D,MAAa,gCAAgC;IACnC,SAAS,GAAG,kCAAiB,CAAC,qBAAqB,CAAC;IACpD,OAAO,GAAG,OAAO,CAAC;IAEV,aAAa,GAAG;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;CAgJjC,CAAC;IAED,gBAAgB;QACf,OAAO,IAAI,CAAC,aAAa,CAAC;IAC3B,CAAC;CACD;AAzJD,4EAyJC"}

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

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

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

@@ -1,149 +0,0 @@
-"use strict";
-Object.defineProperty(exports, "__esModule", { value: true });
-exports.TriageBestPractices = void 0;
-const categorization_1 = require("../../types/categorization");
-class TriageBestPractices {
-    technique = categorization_1.WorkflowTechnique.TRIAGE;
-    version = '1.0.0';
-    documentation = `# Best Practices: Triage Workflows
-
-## Workflow Design
-
-Triage workflows automatically classify incoming data and route it based on priority or category. Common use cases include sorting support tickets by urgency, categorizing emails for follow-up, or scoring leads for sales routing.
-
-Define clear categories and outcomes before building. Design in logical stages:
-
-1. **Trigger & Input**: Capture incoming items (webhook, email trigger, form submission, schedule)
-2. **Preprocessing**: Fetch additional data if needed (CRM lookup, field normalization)
-3. **Classification**: Assign categories via rules or AI
-4. **Routing**: Direct items to appropriate branches using Switch node or Text Classifier Node
-5. **Actions**: Execute category-specific tasks (create tasks, send alerts, update records)
-6. **Logging**: Track outcomes for monitoring and analysis
-
-Include a default/fallback path to catch unclassified items so data is tracked rather than dropped silently.
-
-## Classification Strategies
-
-### Rule-Based Classification
-Use IF/Switch nodes for keyword detection, sender addresses, or numeric thresholds. Chain multiple conditions or use Switch for multi-way branching.
-
-Example: IF email contains "urgent" → High Priority branch
-
-### AI-Powered Classification
-For unstructured text or nuanced decisions, use AI nodes with clear prompts and defined output labels.
-
-Example prompt: "Classify this email as INTERESTED, NOT_INTERESTED, or QUESTION"
-
-Best practices:
-- Use structured output format (JSON with specific fields)
-- Set low temperature parameter of the model (0-0.2) for consistency
-- Include few-shot examples of input + classification
-- Implement error handling for unexpected outputs
-
-#### Text Classifier Node
-Use the Text Classifier node (@n8n/n8n-nodes-langchain.textClassifier) for straightforward text classification tasks. Configure with predefined category labels and descriptions for accurate results.
-
-Example workflow pattern:
-\`\`\`mermaid
-flowchart LR
-    A[Webhook Trigger] --> B[Set: Normalize Data]
-    B --> C[Text Classifier]
-    C --> D{Switch: Route by Category}
-    D -->|High Priority| E[Slack: Alert Team]
-    D -->|Medium Priority| F[Create Task]
-    D -->|Low Priority| G[Log to Sheet]
-    D -->|Default| H[Manual Review]
-\`\`\`
-
-### Combined Approach
-For robust triage, combine rule-based and AI classification. Use AI Agent node with structured output to assign categories, scores, or tags, then route with Switch nodes.
-When using AI with structured output, always add reasoning field alongside category or score to aid debugging.
-
-Example workflow pattern:
-\`\`\`mermaid
-flowchart LR
-    A[Email Trigger] --> B[Set: Extract Fields]
-    B --> C{IF: Contains Keywords}
-    C -->|Yes| D[Set: Rule-based Category]
-    C -->|No| E[AI Agent: Classify with Structured Output]
-    D --> F[Merge]
-    E --> F
-    F --> G{Switch: Route by Category}
-    G -->|Category A| H[Action A]
-    G -->|Category B| I[Action B]
-    G -->|Default| J[Manual Review]
-\`\`\`
-
-**Structured Output Schema Example:**
-\`\`\`json
-{
-  "category": "INTERESTED | NOT_INTERESTED | QUESTION",
-  "confidence": 0.95,
-  "reasoning": "Customer asked about pricing and availability"
-}
-\`\`\`
-
-## Routing & Branching
-
-Use Switch node as primary traffic controller:
-- Configure cases for each classification value
-- Always define Default case for unexpected values
-- Each item follows exactly one branch
-
-Avoid parallel IF nodes that could match multiple conditions - use Switch node.
-
-## Recommended Nodes
-
-**IF** (n8n-nodes-base.if):
-- Purpose: Simple binary decisions
-- Use when: Two-way branching based on conditions
-- Example: Check if priority field equals "high"
-
-**Switch** (n8n-nodes-base.switch):
-- Purpose: Multi-way branching based on field values
-- Use when: Multiple categories (3+ outcomes)
-- Configure Default output for unmatched items
-
-**Merge** (n8n-nodes-base.merge):
-- Purpose: Consolidate branches for unified logging
-- Use after: Category-specific actions before final logging step
-
-**Text Classifier** (@n8n/n8n-nodes-langchain.textClassifier):
-- Purpose: AI-powered text classification with predefined labels
-- Use when: Need to assign categories to unstructured text
-- Configure "When No Clear Match" option to output items to "Other" branch
-
-**AI Agent** (@n8n/n8n-nodes-langchain.agent):
-- Purpose: Complex classification or scoring requiring multiple steps or tool use
-- Use when: Classification needs context lookup, multi-step reasoning with tools, numerical scoring or other complex outputs
-- Use structured output format (JSON schema)
-
-For all AI nodes (Text Classifier, AI Agent):
-	- Set low temperature of the model (0-0.2) for consistency
-	- Include few-shot examples in prompts
-
-## Common Pitfalls to Avoid
-
-### No Default Path
-**Problem**: Every Switch must have a Default output. Unmatched items should go to manual review or logging, never drop silently.
-
-**Solution**: Always configure Default case to route unclassified items to a fallback action (e.g., manual review queue, admin notification)
-
-### No "Other" Branch in Text Classifier
-**Problem**: Items that don't match any category get dropped if "When No Clear Match" isn't set.
-
-**Solution**: In Text Classifier node, set "When No Clear Match" to "Output on Extra, 'Other' Branch" to capture unmatched items.
-
-### Overlapping Conditions
-**Problem**: Categories must be mutually exclusive. Items matching multiple conditions cause unpredictable routing.
-
-**Solution**:
-- Order checks from most specific to general
-- Use Switch with distinct values instead of multiple IF nodes
-`;
-    getDocumentation() {
-        return this.documentation;
-    }
-}
-exports.TriageBestPractices = TriageBestPractices;
-//# sourceMappingURL=triage.js.map

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

@@ -1 +0,0 @@
-{"version":3,"file":"triage.js","sourceRoot":"","sources":["../../../src/tools/best-practices/triage.ts"],"names":[],"mappings":";;;AACA,2DAA2D;AAE3D,MAAa,mBAAmB;IACtB,SAAS,GAAG,kCAAiB,CAAC,MAAM,CAAC;IACrC,OAAO,GAAG,OAAO,CAAC;IAEV,aAAa,GAAG;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;CAuIjC,CAAC;IAED,gBAAgB;QACf,OAAO,IAAI,CAAC,aAAa,CAAC;IAC3B,CAAC;CACD;AAhJD,kDAgJC"}