@atom8n/ai-workflow-builder 1.2.0

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

@@ -0,0 +1,229 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.NotificationBestPractices = void 0;
+const categorization_1 = require("../../types/categorization");
+class NotificationBestPractices {
+    technique = categorization_1.WorkflowTechnique.NOTIFICATION;
+    version = '1.0.0';
+    documentation = `# Best Practices: Notification Workflows
+
+## Workflow Design
+
+Structure notification workflows in a clear sequence: Trigger → Data Retrieval/Processing → Condition Check → Notification Action → Post-Notification (logging/tracking). Keep each part modular with nodes dedicated to specific purposes.
+
+Choose between event-based triggers (webhooks, form submissions, CRM events) for immediate notifications or scheduled triggers (Cron) for periodic condition monitoring. Test Cron triggers in manual mode first to avoid unintended executions.
+
+CRITICAL: Multi-channel notifications should branch from a single condition check to multiple notification nodes in parallel, not duplicate the entire workflow. This enables easy extension and maintenance.
+
+Example pattern:
+- Webhook/Schedule Trigger → Fetch Data → IF (threshold exceeded) → [Email + Slack + SMS nodes in parallel]
+- Result: Single workflow handles all channels efficiently with consistent logic
+
+## Condition Logic & Filtering
+
+Use IF nodes for simple threshold checks without code. For complex conditions (multiple fields, array filtering), use Function nodes to script the logic and filter items that need alerts.
+
+Always include empty notification prevention - check that alert-worthy items exist (items.length > 0) before proceeding to notification nodes. Route the false branch to end the workflow or log "no alert needed".
+
+Store threshold values in environment variables or external sources (Google Sheets, database) rather than hardcoding. This enables adjustment without workflow modification.
+
+## Message Construction
+
+Use expressions to inject dynamic data into messages. The expression \`{{ $json.fieldName }}\` pulls data from input items. For email subjects and bodies, include key details like metric names, values, and timestamps.
+
+Format messages appropriately for each channel:
+- Email: Support HTML or plain text, use clear subject lines
+- Slack: Use markdown-like formatting, \\n for newlines
+- SMS: Keep concise due to character limits, plain text only
+
+## Authentication & Permissions
+
+Configure proper credentials for each service:
+- Email: SMTP settings with correct host/port/auth (use App Passwords for Gmail)
+- Slack: Bot token with chat:write scope, bot must be invited to target channel
+- SMS (Twilio): Account SID, Auth Token, verified phone numbers
+
+Store sensitive information in n8n credentials system or environment variables, never hardcode in workflows.
+
+## Alert Management
+
+Implement cooldown mechanisms to prevent notification floods. Record last alert time and check before sending duplicates. Consider alert aggregation - send one message listing multiple items rather than individual alerts.
+
+Add logging nodes to track sent notifications for audit trails and duplicate prevention. Consider using error handling paths with Continue on Fail settings for redundancy.
+
+## Recommended Nodes
+
+### Trigger Nodes
+
+**Webhook** (n8n-nodes-base.webhook):
+- Purpose: Event-based notifications triggered by external systems
+- Use cases: Form submissions, CRM events, API webhooks
+- Best practice: Validate incoming data before processing
+
+**Schedule Trigger** (n8n-nodes-base.scheduleTrigger):
+- Purpose: Periodic monitoring and batch notifications
+- Use cases: Daily reports, threshold monitoring, scheduled alerts
+- Best practice: Test in manual mode first to avoid unintended executions
+
+**Email Trigger IMAP** (n8n-nodes-base.emailReadImap):
+- Purpose: Email-triggered alerts and auto-responses
+- Use cases: Support ticket creation, email monitoring
+- Best practice: Use filters to avoid processing every email
+
+### Notification Nodes
+
+**Send Email** (n8n-nodes-base.emailSend):
+- Purpose: Detailed alerts with attachments and HTML formatting
+- Use cases: Reports, detailed notifications, formal communications
+- Configuration: SMTP settings, use App Passwords for Gmail
+- Best practice: Use clear subject lines with key information
+
+**Slack** (n8n-nodes-base.slack):
+- Purpose: Team notifications in channels or direct messages
+- Use cases: Team alerts, status updates, incident notifications
+- Configuration: Bot token with chat:write scope, bot must be invited to channel
+- Best practice: Use markdown formatting, channel IDs (starting with C) not names
+
+**Telegram** (n8n-nodes-base.telegram):
+- Purpose: Instant messaging alerts to individuals or groups
+- Use cases: Personal notifications, bot interactions
+- Configuration: Bot token from BotFather
+- Best practice: Use chat ID for direct messages
+
+**Twilio** (n8n-nodes-base.twilio):
+- Purpose: SMS/WhatsApp critical alerts
+- Use cases: High-priority alerts, two-factor authentication, critical incidents
+- Configuration: Account SID, Auth Token, verified phone numbers
+- Best practice: Keep messages concise, use international format (+1234567890)
+
+**HTTP Request** (n8n-nodes-base.httpRequest):
+- Purpose: Custom webhooks (Microsoft Teams, Discord, custom APIs)
+- Use cases: Integration with services without dedicated nodes
+- Best practice: Test webhook URLs before production
+
+### Logic & Processing
+
+**IF** (n8n-nodes-base.if):
+- Purpose: Simple threshold checks and condition routing
+- Use cases: Check if metric exceeds threshold, validate data
+- Best practice: Include empty notification prevention (items.length > 0)
+
+**Switch** (n8n-nodes-base.switch):
+- Purpose: Route notifications based on severity/type
+- Use cases: Different channels for different alert levels
+- Best practice: Always define Default case for unexpected values
+
+**Function** (n8n-nodes-base.function):
+- Purpose: Complex filtering and data transformation
+- Use cases: Array filtering, complex conditions, message formatting
+- Best practice: Keep logic focused and well-documented
+
+**Merge** (n8n-nodes-base.merge):
+- Purpose: Combine parallel notification branches
+- Use cases: Track all notification attempts, consolidate logs
+- Best practice: Use after parallel notification nodes
+
+### Data Sources
+
+**Database Nodes**:
+- Postgres (n8n-nodes-base.postgres)
+- MySQL (n8n-nodes-base.mySql)
+- MongoDB (n8n-nodes-base.mongoDb)
+
+Purpose: Fetch metrics, thresholds, and historical data
+Best practice: Use queries with proper indexing for performance
+
+**Google Sheets** (n8n-nodes-base.googleSheets):
+- Purpose: Configuration storage and logging
+- Use cases: Store thresholds, log notifications, track cooldowns
+- Best practice: Use for non-critical configurations that need easy updates
+
+**HTTP Request** (n8n-nodes-base.httpRequest):
+- Purpose: API data retrieval
+- Use cases: Fetch metrics from monitoring APIs, get user preferences
+- Best practice: Handle API errors gracefully
+
+### Utility Nodes
+
+**Set** (n8n-nodes-base.set):
+- Purpose: Prepare alert messages and structure data
+- Use cases: Format notification content, add metadata
+- Best practice: Use to centralize message construction logic
+
+**Wait** (n8n-nodes-base.wait):
+- Purpose: Delays between notifications
+- Use cases: Rate limiting, cooldown periods, retry logic
+- Best practice: Use for preventing notification floods
+
+**Split In Batches** (n8n-nodes-base.splitInBatches):
+- Purpose: Handle large datasets without overwhelming recipients
+- Use cases: Bulk notifications with rate limiting
+- Best practice: Combine with Wait node for controlled sending
+
+## Common Pitfalls to Avoid
+
+### Authentication Failures
+**Problem**: Invalid or expired credentials are the most common cause of failed notifications.
+
+**Solution**:
+- Regularly verify API keys, OAuth tokens, and SMTP passwords
+- Ensure bots have proper permissions (Slack bots need channel membership)
+- Use n8n credentials system, never hardcode sensitive data
+- Test authentication in isolation before deploying
+
+### Notification Floods
+**Problem**: Without proper controls, a threshold breach can trigger hundreds of identical alerts.
+
+**Solution**:
+- Implement cooldown periods using Wait node or tracking last alert time
+- Use alert aggregation - send one message listing multiple items
+- Use deduplication logic to prevent identical alerts
+- Consider exponential backoff for repeated alerts
+- Store last notification timestamp in database/sheets
+
+### Incorrect Channel Configuration
+**Problem**: Notifications fail due to misconfigured channels.
+
+**Solution**:
+- Slack requires channel IDs (starting with C) not names
+- Email requires verified sender addresses
+- SMS needs international format (+1234567890)
+- Test each channel with sample data before production
+- Validate configuration in node settings
+
+### Data Type Mismatches
+**Problem**: String-to-number comparisons fail silently ("5" > "10" is lexicographically true).
+
+**Solution**:
+- Always convert data types before comparisons
+- Use Number() or parseInt() for numeric comparisons
+- Escape special characters in messages to prevent formatting breaks
+- Validate data types early in the workflow
+
+### Missing Error Handling
+**Problem**: A single failed notification can stop the entire workflow.
+
+**Solution**:
+- Configure error workflows using Error Trigger node
+- Use "Continue on Fail" setting for redundancy
+- Implement fallback channels (if Slack fails, send email)
+- Log failed notification attempts for debugging
+- Add retry logic with exponential backoff
+
+### Rate Limit Violations
+**Problem**: External services have posting limits that can block notifications.
+
+**Solution**:
+- Add delays between bulk sends using Wait node
+- Monitor API quotas and adjust trigger frequency
+- Use BCC for bulk emails when appropriate
+- Implement batch processing with Split In Batches
+- Check service documentation for rate limits
+- Use webhook aggregation where possible
+`;
+    getDocumentation() {
+        return this.documentation;
+    }
+}
+exports.NotificationBestPractices = NotificationBestPractices;
+//# sourceMappingURL=notification.js.map

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

@@ -0,0 +1 @@
+{"version":3,"file":"notification.js","sourceRoot":"","sources":["../../../src/tools/best-practices/notification.ts"],"names":[],"mappings":";;;AACA,2DAA2D;AAE3D,MAAa,yBAAyB;IAC5B,SAAS,GAAG,kCAAiB,CAAC,YAAY,CAAC;IAC3C,OAAO,GAAG,OAAO,CAAC;IAEV,aAAa,GAAG;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;CAuNjC,CAAC;IAED,gBAAgB;QACf,OAAO,IAAI,CAAC,aAAa,CAAC;IAC3B,CAAC;CACD;AAhOD,8DAgOC"}

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

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

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

@@ -0,0 +1,281 @@
+"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. Use modular sub-workflows via Execute Workflow node for complex operations (database cleanup, report generation) to isolate failures and improve maintainability.
+
+For recurring tasks, use Schedule Trigger node with clear naming (e.g., "Daily 08:00 Trigger", "Every 6h Cron"). Document schedule purpose in workflow description.
+
+Prevent overlapping executions by ensuring worst-case execution time < schedule interval. For frequent schedules, implement mutex/lock mechanisms using external systems if needed.
+
+CRITICAL: Always save and activate workflows with Schedule Trigger nodes - scheduled workflows only run in active mode. Manual execution works during development but activation is required for automatic runs.
+
+## 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 one-time future runs, use cron expression with exact date/time (e.g., \`0 12 22 10 *\` for Oct 22 at 12:00).
+IMPORTANT: Deactivate workflow after execution to prevent yearly recurrence.
+
+For event-relative scheduling, use Wait node to pause workflow until specified time/date. Workflow state persists across n8n restarts.
+
+### Conditional Scheduling
+
+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 or based on external data
+- Route different tasks based on conditions
+
+Better than complex cron expressions and provides flexibility for dynamic requirements.
+
+## Time Zone Configuration
+
+CRITICAL: Explicitly set timezone to avoid scheduling confusion.
+
+By default n8n will:
+- Attempts to detect local timezone at signup, defaults to GMT if unsure
+- Set instance timezone via Admin Panel
+- Override per-workflow as needed
+
+Schedule Trigger uses workflow timezone if set, otherwise instance timezone. Cron schedules automatically adjust for DST when using region timezones (Europe/London, America/New_York).
+
+WARNING: Wait node uses server system time, ignoring workflow timezone settings. Account for this when using Wait with specific clock times.
+
+## Error Handling & Monitoring
+
+Build robust error handling for unattended execution:
+- Use Error Trigger for global error workflow
+- Implement retry logic with Wait node for transient failures
+- Add email/Slack notifications for failures
+- Log timestamps with Console node to detect timing issues
+
+Monitor Executions list regularly for:
+- Expected trigger times
+- Duplicates or gaps
+- Failed executions
+- Long-running workflows
+
+## Recommended Nodes
+
+### Schedule Trigger (n8n-nodes-base.scheduleTrigger)
+
+Purpose: Primary node for running workflows on schedule
+
+Modes:
+- Interval: Simple recurring schedules via UI
+- Cron: Complex patterns via expressions
+
+Best Practices:
+- Activate workflow for schedule to work
+- Use descriptive names including schedule
+- Test with manual execution during development
+- Consider DST impacts for region timezones
+
+### Wait (n8n-nodes-base.wait)
+
+Purpose: Pause workflow execution until specified time
+
+Use Cases:
+- Delay actions relative to events
+- One-off timers per data item
+- Follow-up actions after specific duration
+
+Best Practices:
+- Use external database (PostgreSQL) for long waits
+- Avoid extremely long wait times
+- Remember Wait uses server time, not workflow timezone
+- State persists across n8n restarts
+
+### IF (n8n-nodes-base.if)
+
+Purpose: Add conditional logic to scheduled workflows
+
+Use Cases:
+- Check date conditions (last day of month)
+- Skip execution based on external data
+- Route to different actions conditionally
+
+Best Practices:
+- Enable "Convert types where required" for comparisons
+- Document condition logic clearly
+- Prefer IF nodes over complex cron expressions
+
+### Switch (n8n-nodes-base.switch)
+
+Purpose: Multiple conditional branches for complex routing
+
+Use Cases:
+- Different actions based on day of week
+- Time-based routing within workflow
+- Multi-path conditional execution
+
+### Error Trigger (n8n-nodes-base.errorTrigger)
+
+Purpose: Global error handling for failed scheduled executions
+
+Use Cases:
+- Send notifications on workflow failure
+- Log errors to external systems
+- Implement global retry logic
+
+Best Practices:
+- Create dedicated error workflow
+- Include workflow name and timestamp in notifications
+- Consider severity levels for different failures
+
+### Execute Workflow (n8n-nodes-base.executeWorkflow)
+
+Purpose: Call sub-workflows for modular scheduling
+
+Use Cases:
+- Break complex scheduled tasks into modules
+- Reuse common scheduled operations
+- Isolate failures to specific components
+
+Best Practices:
+- Pass parameters for configuration
+- Handle sub-workflow errors appropriately
+- Use for maintainable, focused workflows
+
+### Database Nodes
+
+Purpose: Check pending tasks or store execution history
+
+- MySQL (n8n-nodes-base.mySql)
+- Postgres (n8n-nodes-base.postgres)
+- MongoDB (n8n-nodes-base.mongoDb)
+
+Use Cases:
+- Store list of pending one-time tasks
+- Log execution history
+- Implement custom scheduling queue
+
+Best Practices:
+- Query efficiently with proper indexes
+- Clean up old execution logs periodically
+- Use for dynamic scheduling requirements
+
+### HTTP Request (n8n-nodes-base.httpRequest)
+
+Purpose: Call external APIs or monitoring services
+
+Use Cases:
+- Send heartbeat to monitoring service
+- Check external conditions before execution
+- Trigger external scheduled jobs
+
+### Email/Slack
+
+- Email (n8n-nodes-base.emailSend)
+- Slack (n8n-nodes-base.slack)
+
+Purpose: Send notifications for scheduled workflow events
+
+Use Cases:
+- Daily report delivery
+- Failure notifications
+- Completion confirmations
+
+## Common Pitfalls to Avoid
+
+### Time Zone Mismatch
+
+**Problem**: Workflows run at wrong time due to incorrect timezone configuration. Schedule set for 08:00 runs at 07:00 or 09:00.
+
+**Solution**:
+- Explicitly set workflow or instance timezone
+- Verify timezone after DST changes
+- Use UTC for consistency if timezone complexity is problematic
+- Remember self-hosted defaults to America/New_York
+
+### Daylight Saving Time Issues
+
+**Problem**: Missed or duplicate executions during DST transitions. Jobs may not run or run twice when clocks change.
+
+**Solution**:
+- Use region timezones for automatic DST handling
+- Test critical schedules around DST dates
+- Consider fixed-offset timezone for year-round consistency
+- Update n8n version for latest timezone database
+
+### Duplicate Trigger Executions
+
+**Problem**: Workflows triggering multiple times at scheduled time, especially in multi-instance setups.
+
+**Solution**:
+- Upgrade to n8n ≥1.107.0 (fixes duplicate cron registrations)
+- Configure N8N_MULTI_MAIN_PROCESS=true for multi-instance setups
+- Disable and re-enable workflow if duplicates persist
+- Restart n8n process if issues occur after editing
+
+### Missed Schedules During Downtime
+
+**Problem**: Scheduled runs missed when n8n instance is down. No automatic catch-up for missed triggers.
+
+**Solution**:
+- Ensure high availability for critical schedules
+- Design idempotent workflows that check for missed work
+- Use daily check pattern instead of exact timing when possible
+- Implement external monitoring for uptime
+
+### 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 database or external system
+- Add execution check at workflow start
+- Configure single worker for workflow in queue mode
+
+### 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 UTC timestamps for clarity
+- Run server in target timezone if 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**:
+- Plan activation timing carefully
+- Use manual execution for immediate first run
+- Understand that schedule recalculates from activation moment
+- Document expected first run time
+
+### Cron Syntax Errors
+
+**Problem**: Invalid cron expression prevents trigger activation. Missing fields or incorrect format causes silent failures.
+
+**Solution**:
+- Use crontab.guru to validate expressions
+- Remember n8n supports 5 or 6 field 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 * * * *\`)
+- Use interval mode for simple schedules
+`;
+    getDocumentation() {
+        return this.documentation;
+    }
+}
+exports.SchedulingBestPractices = SchedulingBestPractices;
+//# sourceMappingURL=scheduling.js.map

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

@@ -0,0 +1 @@
+{"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;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;CA2QjC,CAAC;IAED,gBAAgB;QACf,OAAO,IAAI,CAAC,aAAa,CAAC;IAC3B,CAAC;CACD;AApRD,0DAoRC"}

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

@@ -0,0 +1,7 @@
+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;
+}