@n8n/workflow-sdk 0.9.0 → 0.11.0

package/dist/prompts/best-practices/guides/form-input.js

@@ -0,0 +1,175 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.FormInputBestPractices = void 0;
+const types_1 = require("../types");
+class FormInputBestPractices {
+    constructor() {
+        this.technique = types_1.WorkflowTechnique.FORM_INPUT;
+        this.version = '1.0.0';
+        this.documentation = `# Best Practices: Form Input Workflows
+
+## Workflow Design
+
+### Critical: Always Store Raw Form Data
+
+ALWAYS store raw form responses to a persistent data storage destination even if the primary purpose of the workflow is
+to trigger another action (like sending to an API or triggering a notification). This allows users to monitor
+form responses as part of the administration of their workflow.
+
+Required storage destinations include:
+- Google Sheets node
+- Airtable node
+- n8n Data Tables
+- PostgreSQL/MySQL/MongoDB nodes
+- Any other database or spreadsheet service
+
+IMPORTANT: Simply using Set or Merge nodes is NOT sufficient. These nodes only transform data in memory - they do not
+persist data. You must use an actual storage node (like Google Sheets, Airtable, or Data Tables) to write the data.
+
+Storage Requirements:
+- Store the un-edited user input immediately after the form steps are complete
+- Do not store only a summary or edited version of the user's inputs - store the raw data
+- For single-step forms: store immediately after the form trigger
+- For multi-step forms: store immediately after aggregating all steps with Set/Merge nodes
+- The storage node should appear in the workflow right after data collection/aggregation
+
+## Message Attribution
+
+n8n forms attach the attribution "n8n workflow" to messages by default - you must disable this setting which will
+often be called "Append n8n Attribution" for the n8n form nodes, add this setting and set it to false.
+
+## Multi-Step Forms
+
+Build multi-step forms by chaining multiple Form nodes together. Each Form node represents a page or step in your form
+sequence. Use the n8n Form Trigger node to start the workflow and display the first form page to the user.
+
+## Data Collection & Aggregation
+
+Collect and merge all user responses from each form step before writing to your destination (e.g., Data Table). Use
+Set or Merge nodes to combine data as needed. Make sure your JSON keys match the column names in your destination for
+automatic mapping.
+
+## Conditional Logic & Branching
+
+Use IF or Switch nodes to direct users to different form pages based on their previous answers. This enables dynamic
+form flows where the path changes based on user input, creating personalized form experiences.
+
+## Dynamic Form Fields
+
+For forms that require dynamic options (e.g., dropdowns populated from an API or previous step), generate the form
+definition in a Code node and pass it to the Form node as JSON. You can define forms using JSON for dynamic or
+conditional fields, and even generate form fields dynamically using a Code node if needed.
+
+## Input Validation
+
+Validate user input between steps to ensure data quality. If input is invalid, loop back to the relevant form step with
+an error message to guide the user to correct their submission. This prevents bad data from entering your system.
+
+## Recommended Nodes
+
+### n8n Form Trigger (n8n-nodes-base.formTrigger)
+
+Purpose: Starts the workflow and displays the first form page to the user
+
+Pitfalls:
+
+- Use the Production URL for live forms; the Test URL is for development and debugging only
+- Ensure the form trigger is properly configured before sharing URLs with users
+
+### n8n Form (n8n-nodes-base.form)
+
+Purpose: Displays form pages in multi-step form sequences
+
+Pitfalls:
+
+- Each Form node represents one page/step in your form
+- You can define forms using JSON for dynamic or conditional fields
+- Generate form fields dynamically using a Code node if needed for complex scenarios
+
+### Storage Nodes
+
+Purpose: Persist raw form data to a storage destination, preference should be for built-in n8n tables
+but use the most applicable node depending on the user's request.
+
+Required nodes (use at least one):
+- Data table (n8n-nodes-base.dataTable): Built-in n8n storage for quick setup - preferred
+- Google Sheets (n8n-nodes-base.googleSheets): Best for simple spreadsheet storage
+- Airtable (n8n-nodes-base.airtable): Best for structured database with relationships
+- Postgres (n8n-nodes-base.postgres) / MySQL (n8n-nodes-base.mySql) / MongoDB (n8n-nodes-base.mongoDb): For production database storage
+
+Pitfalls:
+
+- Every form workflow MUST include a storage node that actually writes data to a destination
+- Set and Merge nodes alone are NOT sufficient - they only transform data in memory
+- The storage node should be placed immediately after the form trigger (single-step) or after data aggregation (multi-step)
+
+### Code (n8n-nodes-base.code)
+
+Purpose: Processes form data, generates dynamic form definitions, or implements custom validation logic
+
+### Edit Fields (Set) (n8n-nodes-base.set)
+
+Purpose: Aggregates and transforms form data between steps (NOT for storage - use a storage node)
+
+### Merge (n8n-nodes-base.merge)
+
+Purpose: Combines data from multiple form steps into a single dataset (NOT for storage - use a storage node)
+
+Pitfalls:
+
+- Ensure data from all form steps is properly merged before writing to destination
+- Use appropriate merge modes (append, merge by key, etc.) for your use case
+- Remember: Merge prepares data but does not store it - add a storage node after Merge
+
+### If (n8n-nodes-base.if)
+
+Purpose: Routes users to different form pages based on their previous answers
+
+### Switch (n8n-nodes-base.switch)
+
+Purpose: Implements multi-path conditional routing in complex forms
+
+Pitfalls:
+
+- Include a default case to handle unexpected input values
+- Keep routing logic clear and maintainable
+
+## Common Pitfalls to Avoid
+
+### Missing Raw Form Response Storage
+
+When building n8n forms it is recommended to always store the raw form response to some form of data storage (Googlesheets, Airtable, etc)
+for administration later. It is CRITICAL if you create a n8n form node that you store the raw output with a storage node.
+
+### Data Loss in Multi-Step Forms
+
+Aggregate all form step data using Set/Merge nodes before writing to your destination. Failing to merge data from multiple steps
+can result in incomplete form submissions being stored. After merging, ensure you write the complete dataset to a storage node.
+
+### Poor User Experience
+
+Use the Form Ending page type to show a completion message or redirect users after submission.
+Without a proper ending, users may be confused about whether their submission was successful.
+
+### Invalid Data
+
+Implement validation between form steps to catch errors early. Without validation, invalid data can
+propagate through your workflow and corrupt your destination data.
+
+### Complex Field Generation
+
+When generating dynamic form fields, ensure the JSON structure exactly matches what the Form
+node expects. Test thoroughly with the Test URL before going live.
+
+### Mapping Errors
+
+When writing to Google Sheets or other destinations, ensure field names match exactly. Mismatched names
+will cause data to be written to wrong columns or fail entirely.
+`;
+    }
+    getDocumentation() {
+        return this.documentation;
+    }
+}
+exports.FormInputBestPractices = FormInputBestPractices;
+//# sourceMappingURL=form-input.js.map

package/dist/prompts/best-practices/guides/form-input.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"form-input.js","sourceRoot":"","sources":["../../../../src/prompts/best-practices/guides/form-input.ts"],"names":[],"mappings":";;;AACA,oCAA6C;AAE7C,MAAa,sBAAsB;IAAnC;QACU,cAAS,GAAG,yBAAiB,CAAC,UAAU,CAAC;QACzC,YAAO,GAAG,OAAO,CAAC;QAEV,kBAAa,GAAG;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;CA+JjC,CAAC;IAKF,CAAC;IAHA,gBAAgB;QACf,OAAO,IAAI,CAAC,aAAa,CAAC;IAC3B,CAAC;CACD;AAxKD,wDAwKC"}

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

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

package/dist/prompts/best-practices/guides/human-in-the-loop.js

@@ -0,0 +1,270 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.HumanInTheLoopBestPractices = void 0;
+const types_1 = require("../types");
+class HumanInTheLoopBestPractices {
+    constructor() {
+        this.technique = types_1.WorkflowTechnique.HUMAN_IN_THE_LOOP;
+        this.version = '1.0.0';
+        this.documentation = `# Best Practices: Human-in-the-Loop Workflows
+
+## Workflow Design
+
+Structure workflows in three stages: Automation → Human Decision → Resume Processing. The Wait node is the core component for implementing pauses.
+
+Break the workflow into clear stages:
+1. **Initial Automation**: Execute automated steps leading to the decision point (data extraction, AI content generation, etc.)
+2. **Human Notification**: Send notification with resume URL via preferred channel (Email, Slack, Telegram)
+3. **Wait for Response**: Configure Wait node with appropriate resume condition
+4. **Process Decision**: Use IF/Switch nodes to branch based on human input
+
+Example pattern:
+- Trigger → Generate Content → Email (with resume URLs) → Wait Node → IF (decision) → Publish/Reject
+- HTTP Request (fetch data) → Filter → Email Manager → Wait (On Webhook) → Switch (approval status) → Database Update
+
+CRITICAL: Always include the $execution.resumeUrl in notification messages. This unique URL resumes the specific workflow execution when accessed.
+
+## Wait Node Configuration
+
+The Wait node supports four resume conditions:
+- **After Time Interval**: Resume after fixed delay (not for human decisions)
+- **At Specified Time**: Resume at specific date/time (not for human decisions)
+- **On Webhook Call**: Resume when URL is accessed (ideal for link-based approvals)
+- **On Form Submitted**: Resume when user submits n8n-hosted form (best for structured input)
+
+For human-in-the-loop, use "On Webhook Call" or "On Form Submitted" modes.
+
+### Webhook Configuration
+- Set HTTP method (GET for simple links, POST for data)
+- Configure authentication if needed (None for private URLs, Basic/Token for security)
+- Enable "Ignore Bots" to prevent email scanners/chat bots from triggering
+- Use Webhook Suffix for multiple wait points in same workflow
+
+### Form Configuration
+- Design form fields directly in Wait node
+- Specify field types, labels, validation
+- Form automatically hosts at resume URL
+- Submitted data merges with workflow context
+
+## Timeout Management
+
+Always configure "Limit Wait Time" to prevent infinite waits:
+- Set maximum wait duration (e.g., 48 hours)
+- Or specify absolute deadline date
+- Handle timeout case in workflow logic
+- Check if resumed by timeout (no webhook/form data present)
+
+## Communication Patterns
+
+### Direct Link Method
+Include $execution.resumeUrl directly in messages:
+
+Email: Click to [Approve]({{$execution.resumeUrl}}?decision=approve) or [Reject]({{$execution.resumeUrl}}?decision=reject)
+Slack: Please review and click: {{$execution.resumeUrl}}
+
+### Platform Response Method
+For responses within platform (Slack reply, email response):
+- Use separate trigger workflow to catch responses
+- Correlate to correct execution via ID
+- Call resume URL programmatically
+- More complex but keeps interaction native
+
+## Data Handling
+
+The Wait node preserves all prior workflow data when resuming:
+- Original context remains available
+- New input data (form/webhook) adds to context
+- Access webhook data via $json after Wait node
+- Query parameters available in $json.query
+- Form fields merge directly into JSON output
+
+## Recommended Nodes
+
+### Wait (n8n-nodes-base.wait)
+
+**Purpose**: Core node for pausing workflow execution until human input
+
+**Key Settings**:
+- Resume: "On Webhook Call" or "On Form Submitted"
+- Authentication: Configure based on security needs
+- Ignore Bots: Enable to prevent accidental triggers
+- Limit Wait Time: Set timeout to prevent infinite waits
+
+**Use Cases**:
+- Approval workflows
+- Data collection from humans
+- Multi-step verification processes
+
+**Best Practices**:
+- Always include timeout handling
+- Use unique webhook suffixes for multiple waits
+- Test resume URLs during development
+
+### Email (n8n-nodes-base.emailSend)
+
+**Purpose**: Send notifications with resume links to users
+
+**Use Cases**:
+- Approval request emails
+- Data verification requests
+- Task assignment notifications
+
+**Best Practices**:
+- Include clear call-to-action buttons
+- Embed resume URL as hyperlinks
+- Provide context about the decision needed
+
+### Slack (n8n-nodes-base.slack)
+
+**Purpose**: Send notifications via Slack with resume links
+
+**Best Practices**:
+- Wrap URLs in <> to prevent unfurling
+- Use clear message formatting
+- Consider using blocks for rich formatting
+
+### Telegram (n8n-nodes-base.telegram)
+
+**Purpose**: Send notifications via Telegram
+
+**Best Practices**:
+- Enable "Ignore Bots" in Wait node
+- Use inline keyboards for better UX
+- Keep messages concise
+
+### IF (n8n-nodes-base.if)
+
+**Purpose**: Branch workflow based on human decision
+
+**Use Cases**:
+- Route approved vs rejected items
+- Check if response was received (vs timeout)
+- Validate input data
+
+**Best Practices**:
+- Handle all possible decision values
+- Include default/timeout branch
+- Use clear condition names
+
+### Switch (n8n-nodes-base.switch)
+
+**Purpose**: Multi-way branching for complex decisions
+
+**Use Cases**:
+- Multiple approval levels
+- Various response options
+- Status-based routing
+
+### HTTP Request (n8n-nodes-base.httpRequest)
+
+**Purpose**: Call external APIs after human decision
+
+**Use Cases**:
+- Update external systems
+- Trigger downstream processes
+- Log decisions to external services
+
+### Database Nodes
+
+**MySQL** (n8n-nodes-base.mySql), **Postgres** (n8n-nodes-base.postgres), **MongoDB** (n8n-nodes-base.mongoDb):
+- Store approval history
+- Update record status after decision
+- Log human inputs for audit
+
+### Google Sheets (n8n-nodes-base.googleSheets)
+
+**Purpose**: Track decisions and maintain approval logs
+
+**Use Cases**:
+- Approval tracking spreadsheets
+- Decision audit logs
+- User response collection
+
+## Common Pitfalls to Avoid
+
+### Accidental Resume Triggers
+
+**Problem**: Email clients or chat apps preview links and trigger resume unintentionally.
+
+**Solution**:
+- Enable "Ignore Bots" option in Wait node
+- Wrap Slack URLs in <> to prevent unfurling
+- Use authentication for sensitive workflows
+- Educate users to click only when ready
+
+### Missing Timeouts
+
+**Problem**: Workflow waits forever if human never responds.
+
+**Solution**:
+- Always set "Limit Wait Time" (e.g., 3 days)
+- Handle timeout scenario in workflow logic
+- Send reminder before deadline
+- Escalate to another person if timeout occurs
+
+### Lost Context After Wait
+
+**Problem**: Assuming data is lost after Wait node resumes.
+
+**Solution**:
+- Wait node preserves all prior data automatically
+- New input merges with existing context
+- Test data structure after resume
+- Use expressions to access both old and new data
+
+### Security Issues with Resume URLs
+
+**Problem**: Resume URLs exposed to unauthorized users.
+
+**Solution**:
+- Treat resume URLs as secrets
+- Use authentication options for sensitive workflows
+- Send only through private channels
+- Consider IP whitelisting if needed
+
+### Multiple Wait Node Confusion
+
+**Problem**: Using same webhook URL for different wait points.
+
+**Solution**:
+- Use unique Webhook Suffix for each Wait node
+- Generate fresh $execution.resumeUrl for each wait
+- Label wait points clearly
+- Document which URL corresponds to which decision
+
+### Not Handling All Response Types
+
+**Problem**: Only handling expected responses, not edge cases.
+
+**Solution**:
+- Handle timeout case explicitly
+- Provide default action for unexpected inputs
+- Validate form data before processing
+- Log all decisions for debugging
+
+### Workflow State Persistence
+
+**Problem**: Worrying about resource consumption during wait.
+
+**Solution**:
+- Waiting executions are saved to database, not running
+- No worker threads consumed during wait
+- Can have hundreds of paused workflows
+- Survives n8n restarts (state in database)
+
+### Complex Parallel Approvals
+
+**Problem**: Need multiple people to approve before continuing.
+
+**Solution**:
+- Use separate Wait node per approver
+- Or create sub-workflow per approver
+- Use Merge node to synchronize branches
+- Consider approval tracking in database`;
+    }
+    getDocumentation() {
+        return this.documentation;
+    }
+}
+exports.HumanInTheLoopBestPractices = HumanInTheLoopBestPractices;
+//# sourceMappingURL=human-in-the-loop.js.map

package/dist/prompts/best-practices/guides/human-in-the-loop.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"human-in-the-loop.js","sourceRoot":"","sources":["../../../../src/prompts/best-practices/guides/human-in-the-loop.ts"],"names":[],"mappings":";;;AACA,oCAA6C;AAE7C,MAAa,2BAA2B;IAAxC;QACU,cAAS,GAAG,yBAAiB,CAAC,iBAAiB,CAAC;QAChD,YAAO,GAAG,OAAO,CAAC;QAEV,kBAAa,GAAG;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;yCA8PO,CAAC;IAK1C,CAAC;IAHA,gBAAgB;QACf,OAAO,IAAI,CAAC,aAAa,CAAC;IAC3B,CAAC;CACD;AAvQD,kEAuQC"}

package/dist/prompts/best-practices/guides/knowledge-base.d.ts

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