@atom8n/ai-workflow-builder 1.4.3 → 1.5.1

package/dist/tools/get-documentation.tool.js

@@ -0,0 +1,163 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.GET_DOCUMENTATION_TOOL = exports.DocumentationType = void 0;
+exports.createGetDocumentationTool = createGetDocumentationTool;
+const tools_1 = require("@langchain/core/tools");
+const zod_1 = require("zod");
+const errors_1 = require("../errors");
+const builder_1 = require("../prompts/builder");
+const node_recommendations_1 = require("../prompts/shared/node-recommendations");
+const best_practices_1 = require("../tools/best-practices");
+const progress_1 = require("../tools/helpers/progress");
+const response_1 = require("../tools/helpers/response");
+const categorization_1 = require("../types/categorization");
+const node_recommendations_2 = require("../types/node-recommendations");
+exports.DocumentationType = {
+    BEST_PRACTICES: 'best_practices',
+    NODE_RECOMMENDATIONS: 'node_recommendations',
+};
+const bestPracticesRequestSchema = zod_1.z.object({
+    type: zod_1.z.literal(exports.DocumentationType.BEST_PRACTICES),
+    techniques: zod_1.z
+        .array(zod_1.z.nativeEnum(categorization_1.WorkflowTechnique))
+        .min(1)
+        .describe('Workflow techniques to get best practices for'),
+});
+const nodeRecommendationsRequestSchema = zod_1.z.object({
+    type: zod_1.z.literal(exports.DocumentationType.NODE_RECOMMENDATIONS),
+    categories: zod_1.z
+        .array(zod_1.z.nativeEnum(node_recommendations_2.RecommendationCategory))
+        .min(1)
+        .describe('Task categories to get node recommendations for'),
+});
+const getDocumentationSchema = zod_1.z.object({
+    requests: zod_1.z
+        .array(zod_1.z.union([bestPracticesRequestSchema, nodeRecommendationsRequestSchema]))
+        .min(1)
+        .describe('Array of documentation requests to retrieve'),
+});
+function formatBestPractices(techniques) {
+    const foundDocs = [];
+    for (const technique of techniques) {
+        const doc = best_practices_1.documentation[technique];
+        if (doc) {
+            foundDocs.push(doc.getDocumentation());
+        }
+    }
+    if (foundDocs.length === 0) {
+        return '';
+    }
+    return (0, builder_1.prompt)().section('best_practices', foundDocs.join('\n---\n')).build();
+}
+function formatCategory(category, content) {
+    return (0, builder_1.prompt)().section(category, content).build();
+}
+function formatNodeRecommendations(categories) {
+    const foundRecs = [];
+    for (const category of categories) {
+        const rec = node_recommendations_1.recommendations[category];
+        if (rec) {
+            foundRecs.push(formatCategory(category, (0, node_recommendations_1.formatRecommendation)(rec.recommendation)));
+        }
+    }
+    if (foundRecs.length === 0) {
+        return '';
+    }
+    return (0, builder_1.prompt)().section('node_recommendations', foundRecs.join('\n')).build();
+}
+exports.GET_DOCUMENTATION_TOOL = {
+    toolName: 'get_documentation',
+    displayTitle: 'Getting documentation',
+};
+function createGetDocumentationTool() {
+    const dynamicTool = (0, tools_1.tool)((input, config) => {
+        const reporter = (0, progress_1.createProgressReporter)(config, exports.GET_DOCUMENTATION_TOOL.toolName, exports.GET_DOCUMENTATION_TOOL.displayTitle);
+        try {
+            const validatedInput = getDocumentationSchema.parse(input);
+            const { requests } = validatedInput;
+            reporter.start(validatedInput);
+            reporter.progress(`Processing ${requests.length} documentation request(s)...`);
+            const results = [];
+            let bestPracticesContent;
+            const allTechniques = [];
+            for (const request of requests) {
+                if (request.type === exports.DocumentationType.BEST_PRACTICES) {
+                    const { techniques } = request;
+                    const availableDocs = techniques.filter((t) => best_practices_1.documentation[t]);
+                    if (availableDocs.length > 0) {
+                        const content = formatBestPractices(techniques);
+                        results.push(content);
+                        bestPracticesContent = content;
+                        allTechniques.push(...techniques);
+                    }
+                }
+                else {
+                    const { categories } = request;
+                    const availableRecs = categories.filter((c) => node_recommendations_1.recommendations[c]);
+                    if (availableRecs.length > 0) {
+                        results.push(formatNodeRecommendations(categories));
+                    }
+                }
+            }
+            if (results.length === 0) {
+                const message = 'No documentation available for the requested items.';
+                reporter.complete({ requests: requests.length, found: 0 });
+                return (0, response_1.createSuccessResponse)(config, message);
+            }
+            const message = results.join('\n\n');
+            reporter.complete({ requests: requests.length, found: results.length });
+            const stateUpdates = {};
+            if (bestPracticesContent) {
+                stateUpdates.bestPractices = bestPracticesContent;
+                stateUpdates.techniqueCategories = allTechniques;
+            }
+            return (0, response_1.createSuccessResponse)(config, message, Object.keys(stateUpdates).length > 0 ? stateUpdates : undefined);
+        }
+        catch (error) {
+            if (error instanceof zod_1.z.ZodError) {
+                const validationError = new errors_1.ValidationError('Invalid input parameters', {
+                    extra: { errors: error.errors },
+                });
+                reporter.error(validationError);
+                return (0, response_1.createErrorResponse)(config, validationError);
+            }
+            const toolError = new errors_1.ToolExecutionError(error instanceof Error ? error.message : 'Unknown error occurred', {
+                toolName: exports.GET_DOCUMENTATION_TOOL.toolName,
+                cause: error instanceof Error ? error : undefined,
+            });
+            reporter.error(toolError);
+            return (0, response_1.createErrorResponse)(config, toolError);
+        }
+    }, {
+        name: exports.GET_DOCUMENTATION_TOOL.toolName,
+        description: `Retrieve documentation to guide workflow building.
+
+TYPE: best_practices
+Use when you need guidance on workflow patterns and implementation.
+Requires: techniques array (workflow techniques to get practices for)
+Returns: Best practices including recommended nodes, common pitfalls, performance tips.
+
+TYPE: node_recommendations
+Use when user wants AI capabilities but doesn't specify exact nodes/providers.
+Requires: categories array (task categories to get recommendations for)
+Returns: Default node recommendations with alternatives.
+
+Do NOT use node_recommendations when:
+- User explicitly names a provider (e.g., "use Claude", "with OpenAI", "using Gemini")
+- User specifies exact node names
+
+Available techniques for best_practices:
+- trigger, loop, branch, subroutine, pagination, parallel_execution, error_handling, scheduling, rate_limiting, batch_processing, ai_agent, ai_chain, rag, data_transformation, http_request
+
+Available categories for node_recommendations:
+- text_manipulation: summarization, analysis, extraction, classification, chat
+- image_generation: generate, analyze, edit images
+- video_generation: create videos from text/images
+- audio_generation: text-to-speech, transcription, translation`,
+        schema: getDocumentationSchema,
+    });
+    return {
+        tool: dynamicTool,
+        ...exports.GET_DOCUMENTATION_TOOL,
+    };
+}

package/dist/tools/rename-node.tool.d.ts

@@ -0,0 +1,15 @@
+import type { Logger } from '@n8n/backend-common';
+import { z } from 'zod';
+import type { BuilderTool, BuilderToolBase } from '../utils/stream-processor';
+export declare const renameNodeSchema: z.ZodObject<{
+    nodeId: z.ZodString;
+    newName: z.ZodString;
+}, "strip", z.ZodTypeAny, {
+    nodeId: string;
+    newName: string;
+}, {
+    nodeId: string;
+    newName: string;
+}>;
+export declare const RENAME_NODE_TOOL: BuilderToolBase;
+export declare function createRenameNodeTool(logger?: Logger): BuilderTool;

package/dist/tools/rename-node.tool.js

@@ -0,0 +1,140 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.RENAME_NODE_TOOL = exports.renameNodeSchema = void 0;
+exports.createRenameNodeTool = createRenameNodeTool;
+const tools_1 = require("@langchain/core/tools");
+const zod_1 = require("zod");
+const errors_1 = require("../errors");
+const progress_1 = require("./helpers/progress");
+const response_1 = require("./helpers/response");
+const state_1 = require("./helpers/state");
+const validation_1 = require("./helpers/validation");
+exports.renameNodeSchema = zod_1.z.object({
+    nodeId: zod_1.z.string().describe('The UUID of the node to rename'),
+    newName: zod_1.z.string().min(1).describe('The new name for the node'),
+});
+exports.RENAME_NODE_TOOL = {
+    toolName: 'rename_node',
+    displayTitle: 'Renaming node',
+};
+function buildResponseMessage(oldName, newName) {
+    return `Successfully renamed node from "${oldName}" to "${newName}"`;
+}
+function createRenameNodeTool(logger) {
+    const dynamicTool = (0, tools_1.tool)((input, config) => {
+        const reporter = (0, progress_1.createProgressReporter)(config, exports.RENAME_NODE_TOOL.toolName, exports.RENAME_NODE_TOOL.displayTitle);
+        try {
+            const validatedInput = exports.renameNodeSchema.parse(input);
+            reporter.start(validatedInput);
+            const state = (0, state_1.getWorkflowState)();
+            const workflow = (0, state_1.getCurrentWorkflow)(state);
+            (0, progress_1.reportProgress)(reporter, 'Finding node to rename...');
+            const node = (0, validation_1.validateNodeExists)(validatedInput.nodeId, workflow.nodes);
+            if (!node) {
+                const error = (0, validation_1.createNodeNotFoundError)(validatedInput.nodeId);
+                reporter.error(error);
+                return (0, response_1.createErrorResponse)(config, error);
+            }
+            const oldName = node.name;
+            const newName = validatedInput.newName;
+            if (oldName === newName) {
+                const validationError = new errors_1.ValidationError(`Node "${oldName}" already has this name`, {
+                    field: 'newName',
+                    value: newName,
+                });
+                const error = {
+                    message: validationError.message,
+                    code: 'SAME_NAME',
+                    details: {
+                        nodeId: validatedInput.nodeId,
+                        currentName: oldName,
+                        newName,
+                    },
+                };
+                reporter.error(error);
+                return (0, response_1.createErrorResponse)(config, error);
+            }
+            const existingNode = workflow.nodes.find((n) => n.name === newName && n.id !== validatedInput.nodeId);
+            if (existingNode) {
+                const validationError = new errors_1.ValidationError(`A node with the name "${newName}" already exists`, {
+                    field: 'newName',
+                    value: newName,
+                });
+                const error = {
+                    message: validationError.message,
+                    code: 'NAME_CONFLICT',
+                    details: {
+                        nodeId: validatedInput.nodeId,
+                        newName,
+                        conflictingNodeId: existingNode.id,
+                    },
+                };
+                reporter.error(error);
+                return (0, response_1.createErrorResponse)(config, error);
+            }
+            logger?.debug('\n=== Rename Node Tool ===');
+            logger?.debug(`Renaming node: "${oldName}" -> "${newName}"`);
+            (0, progress_1.reportProgress)(reporter, `Renaming "${oldName}" to "${newName}"...`);
+            const message = buildResponseMessage(oldName, newName);
+            logger?.debug('Node will be renamed');
+            const output = {
+                nodeId: validatedInput.nodeId,
+                oldName,
+                newName,
+                message,
+            };
+            const stateUpdates = (0, state_1.renameNodeInWorkflow)(validatedInput.nodeId, oldName, newName);
+            reporter.complete(output);
+            return (0, response_1.createSuccessResponse)(config, message, stateUpdates);
+        }
+        catch (error) {
+            let toolError;
+            if (error instanceof zod_1.z.ZodError) {
+                const validationError = new errors_1.ValidationError('Invalid rename node parameters', {
+                    field: error.errors[0]?.path.join('.'),
+                    value: error.errors[0]?.message,
+                });
+                toolError = {
+                    message: validationError.message,
+                    code: 'VALIDATION_ERROR',
+                    details: error.errors,
+                };
+            }
+            else {
+                toolError = {
+                    message: error instanceof Error ? error.message : 'Unknown error occurred',
+                    code: 'EXECUTION_ERROR',
+                };
+            }
+            reporter.error(toolError);
+            return (0, response_1.createErrorResponse)(config, toolError);
+        }
+    }, {
+        name: exports.RENAME_NODE_TOOL.toolName,
+        description: `Rename a node in the workflow. This updates the node's display name and automatically updates all connection references.
+
+USAGE:
+Use this tool when you need to give a node a more descriptive or meaningful name.
+
+PARAMETERS:
+- nodeId: The UUID of the node to rename
+- newName: The new name for the node (must be unique in the workflow)
+
+EXAMPLES:
+1. Rename a generic node:
+   nodeId: "abc-123", newName: "Process Customer Data"
+
+2. Rename after duplicating:
+   nodeId: "def-456", newName: "Send Welcome Email"
+
+NOTES:
+- The node must exist in the workflow
+- The new name must not conflict with any other node name in the workflow
+- All connections to/from this node will be automatically updated`,
+        schema: exports.renameNodeSchema,
+    });
+    return {
+        tool: dynamicTool,
+        ...exports.RENAME_NODE_TOOL,
+    };
+}

package/dist/types/node-guidance.d.ts

@@ -0,0 +1,7 @@
+export interface NodeGuidance {
+    nodeType: string;
+    usage: string;
+    connections: string;
+    configuration: string;
+    recommendation?: string;
+}

package/dist/types/node-guidance.js

@@ -0,0 +1,2 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });

package/dist/types/node-recommendations.d.ts

@@ -0,0 +1,26 @@
+import type { NodeConnectionType } from 'n8n-workflow';
+export declare const RecommendationCategory: {
+    readonly TEXT_MANIPULATION: "text_manipulation";
+    readonly IMAGE_GENERATION: "image_generation";
+    readonly VIDEO_GENERATION: "video_generation";
+    readonly AUDIO_GENERATION: "audio_generation";
+};
+export type RecommendationCategoryType = (typeof RecommendationCategory)[keyof typeof RecommendationCategory];
+export declare const RecommendationCategoryDescription: Record<RecommendationCategoryType, string>;
+export interface ConnectedNodeRecommendation {
+    nodeType: string;
+    connectionType: NodeConnectionType;
+    description?: string;
+}
+export interface NodeRecommendation {
+    defaultNode: string;
+    operations: string[];
+    reasoning: string;
+    connectedNodes?: ConnectedNodeRecommendation[];
+    note?: string;
+}
+export interface NodeRecommendationDocument {
+    readonly category: RecommendationCategoryType;
+    readonly version: string;
+    readonly recommendation: NodeRecommendation;
+}

package/dist/types/node-recommendations.js

@@ -0,0 +1,15 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.RecommendationCategoryDescription = exports.RecommendationCategory = void 0;
+exports.RecommendationCategory = {
+    TEXT_MANIPULATION: 'text_manipulation',
+    IMAGE_GENERATION: 'image_generation',
+    VIDEO_GENERATION: 'video_generation',
+    AUDIO_GENERATION: 'audio_generation',
+};
+exports.RecommendationCategoryDescription = {
+    [exports.RecommendationCategory.TEXT_MANIPULATION]: 'AI text tasks: summarization, analysis, extraction, classification, chat',
+    [exports.RecommendationCategory.IMAGE_GENERATION]: 'AI image tasks: generate, analyze, edit images',
+    [exports.RecommendationCategory.VIDEO_GENERATION]: 'AI video tasks: generate video from text/images',
+    [exports.RecommendationCategory.AUDIO_GENERATION]: 'AI audio tasks: generate speech, transcribe, translate audio',
+};

package/dist/utils/resource-operation-extractor.d.ts

@@ -0,0 +1,16 @@
+import { type INodeTypeDescription, type Logger } from 'n8n-workflow';
+export interface OperationInfo {
+    value: string;
+    displayName: string;
+}
+export interface ResourceInfo {
+    value: string;
+    displayName: string;
+    operations: OperationInfo[];
+}
+export interface ResourceOperationInfo {
+    resources: ResourceInfo[];
+}
+export declare function extractResourceOperations(nodeType: INodeTypeDescription, nodeVersion: number, logger?: Logger): ResourceOperationInfo | null;
+export declare function createResourceCacheKey(nodeName: string, version: number): string;
+export declare function formatResourceOperationsForPrompt(info: ResourceOperationInfo): string;

package/dist/utils/resource-operation-extractor.js

@@ -0,0 +1,147 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.extractResourceOperations = extractResourceOperations;
+exports.createResourceCacheKey = createResourceCacheKey;
+exports.formatResourceOperationsForPrompt = formatResourceOperationsForPrompt;
+const n8n_workflow_1 = require("n8n-workflow");
+function isPropertyVisibleForVersion(property, nodeVersion) {
+    const displayOptions = property.displayOptions;
+    if (!displayOptions) {
+        return true;
+    }
+    const showVersion = displayOptions.show?.['@version'];
+    if (showVersion && !(0, n8n_workflow_1.checkConditions)(showVersion, [nodeVersion])) {
+        return false;
+    }
+    const hideVersion = displayOptions.hide?.['@version'];
+    if (hideVersion && (0, n8n_workflow_1.checkConditions)(hideVersion, [nodeVersion])) {
+        return false;
+    }
+    return true;
+}
+function findResourceProperty(properties, nodeVersion) {
+    return properties.find((prop) => prop.name === 'resource' &&
+        prop.type === 'options' &&
+        isPropertyVisibleForVersion(prop, nodeVersion));
+}
+function isOperationVisibleForResource(prop, resourceValue) {
+    const displayOptions = prop.displayOptions;
+    if (!displayOptions) {
+        return true;
+    }
+    const showResource = displayOptions.show?.resource;
+    if (showResource && !(0, n8n_workflow_1.checkConditions)(showResource, [resourceValue])) {
+        return false;
+    }
+    const hideResource = displayOptions.hide?.resource;
+    if (hideResource && (0, n8n_workflow_1.checkConditions)(hideResource, [resourceValue])) {
+        return false;
+    }
+    return true;
+}
+function findOperationProperties(properties, resourceValue, nodeVersion) {
+    return properties.filter((prop) => {
+        if (prop.name !== 'operation' || prop.type !== 'options') {
+            return false;
+        }
+        if (!isPropertyVisibleForVersion(prop, nodeVersion)) {
+            return false;
+        }
+        return isOperationVisibleForResource(prop, resourceValue);
+    });
+}
+function extractOptions(property, logger) {
+    if (!property.options || !Array.isArray(property.options)) {
+        return [];
+    }
+    return property.options
+        .filter((opt) => {
+        if (typeof opt !== 'object' || opt === null || !('name' in opt) || !('value' in opt)) {
+            return false;
+        }
+        const optName = opt.name;
+        const optValue = opt.value;
+        if (typeof optValue !== 'string') {
+            logger?.debug('Skipping non-string option value in resource/operation extraction', {
+                propertyName: property.name,
+                optionName: optName,
+                valueType: typeof optValue,
+            });
+            return false;
+        }
+        return true;
+    })
+        .map((opt) => ({
+        value: opt.value,
+        displayName: opt.name,
+    }));
+}
+function extractResourceOperations(nodeType, nodeVersion, logger) {
+    const properties = nodeType.properties;
+    if (!properties || properties.length === 0) {
+        logger?.debug('extractResourceOperations: No properties found', {
+            nodeType: nodeType.name,
+            nodeVersion,
+        });
+        return null;
+    }
+    const resourceProperty = findResourceProperty(properties, nodeVersion);
+    if (!resourceProperty) {
+        return null;
+    }
+    const resourceOptions = extractOptions(resourceProperty, logger);
+    if (resourceOptions.length === 0) {
+        logger?.warn('extractResourceOperations: Resource property found but no string options', {
+            nodeType: nodeType.name,
+            nodeVersion,
+            propertyDefault: resourceProperty.default,
+        });
+        return null;
+    }
+    const resources = resourceOptions.map((resource) => {
+        const operationProperties = findOperationProperties(properties, resource.value, nodeVersion);
+        const allOperations = [];
+        const seenValues = new Set();
+        for (const opProp of operationProperties) {
+            const ops = extractOptions(opProp, logger);
+            for (const op of ops) {
+                if (!seenValues.has(op.value)) {
+                    seenValues.add(op.value);
+                    allOperations.push({
+                        value: op.value,
+                        displayName: op.displayName,
+                    });
+                }
+            }
+        }
+        return {
+            value: resource.value,
+            displayName: resource.displayName,
+            operations: allOperations,
+        };
+    });
+    return { resources };
+}
+function createResourceCacheKey(nodeName, version) {
+    return `${nodeName}:${version}`;
+}
+function formatResourceOperationsForPrompt(info) {
+    const parts = ['<available_resources_and_operations>'];
+    for (const resource of info.resources) {
+        if (resource.value === '__CUSTOM_API_CALL__')
+            continue;
+        parts.push(`  Resource: ${resource.displayName} (value: "${resource.value}")`);
+        const filteredOps = resource.operations.filter((op) => op.value !== '__CUSTOM_API_CALL__');
+        if (filteredOps.length > 0) {
+            parts.push('    Operations:');
+            for (const op of filteredOps) {
+                parts.push(`      - ${op.displayName} (value: "${op.value}")`);
+            }
+        }
+        else {
+            parts.push('    Operations: none defined');
+        }
+    }
+    parts.push('</available_resources_and_operations>');
+    return parts.join('\n');
+}

package/dist/validation/auto-fix/auto-fix-connections.d.ts

@@ -0,0 +1,21 @@
+import type { INodeTypeDescription, NodeConnectionType, IConnections } from 'n8n-workflow';
+import type { SimpleWorkflow } from '../../types';
+import type { ProgrammaticViolation } from '../types';
+export interface AutoFixResult {
+    fixed: AutoFixedConnection[];
+    unfixable: UnfixableConnection[];
+    updatedConnections: IConnections;
+}
+export interface AutoFixedConnection {
+    sourceNodeName: string;
+    targetNodeName: string;
+    connectionType: NodeConnectionType;
+    reason: string;
+}
+export interface UnfixableConnection {
+    nodeName: string;
+    missingInputType: NodeConnectionType;
+    reason: string;
+    candidateCount: number;
+}
+export declare function autoFixConnections(workflow: SimpleWorkflow, nodeTypes: INodeTypeDescription[], violations: ProgrammaticViolation[]): AutoFixResult;