@flowdrop/flowdrop 1.0.0

package/dist/helpers/proximityConnect.d.ts

@@ -0,0 +1,94 @@
+/**
+ * Proximity Connect Helper
+ *
+ * Provides type-aware proximity connect logic for the workflow editor.
+ * When a node is dragged near another node, this helper finds the best
+ * compatible port pair and creates a preview/permanent edge.
+ */
+import type { WorkflowNode as WorkflowNodeType, WorkflowEdge, NodePort, PortCoordinateMap } from '../types/index.js';
+/** A candidate proximity edge before it is finalized */
+export interface ProximityEdgeCandidate {
+    id: string;
+    source: string;
+    target: string;
+    sourceHandle: string;
+    targetHandle: string;
+    sourcePortDataType: string;
+    targetPortDataType: string;
+}
+export declare class ProximityConnectHelper {
+    /**
+     * Get ALL ports (static + dynamic + gateway branches) for a node.
+     */
+    static getAllPorts(node: WorkflowNodeType, direction: 'input' | 'output'): NodePort[];
+    /**
+     * Build handle ID in the standard format.
+     */
+    static buildHandleId(nodeId: string, direction: 'input' | 'output', portId: string): string;
+    /**
+     * Calculate center-to-center distance between two nodes.
+     */
+    static getNodeDistance(nodeA: {
+        position: {
+            x: number;
+            y: number;
+        };
+        measured?: {
+            width?: number;
+            height?: number;
+        };
+    }, nodeB: {
+        position: {
+            x: number;
+            y: number;
+        };
+        measured?: {
+            width?: number;
+            height?: number;
+        };
+    }): number;
+    /**
+     * Find the single best compatible edge between a dragged node and nearby nodes.
+     *
+     * Algorithm:
+     * 1. Find the closest node within minDistance (edge-to-edge)
+     * 2. Check both directions (dragged->nearby and nearby->dragged)
+     * 3. Return the first exact-type match, or first compatible match
+     * 4. Skip pairs where an edge already exists
+     *
+     * @returns Array with at most ONE ProximityEdgeCandidate
+     */
+    static findCompatibleEdges(draggedNode: WorkflowNodeType, allNodes: WorkflowNodeType[], existingEdges: WorkflowEdge[], minDistance: number): ProximityEdgeCandidate[];
+    /**
+     * Find the single best compatible edge using port-to-port distance.
+     *
+     * Unlike findCompatibleEdges() which uses node center distance,
+     * this method compares actual handle positions from the port coordinate store.
+     * This is more accurate for large nodes or nodes with many ports.
+     *
+     * Algorithm:
+     * 1. Partition ports by owner (dragged vs other) and direction (input vs output)
+     * 2. Group other-node ports by dataType for O(1) lookup of compatible groups
+     * 3. For each dragged port, only iterate compatible dataType groups
+     * 4. Return the closest compatible pair (exact type match preferred)
+     *
+     * @returns Array with at most ONE ProximityEdgeCandidate
+     */
+    static findCompatibleEdgesByPortCoordinates(draggedNodeId: string, portCoordinates: PortCoordinateMap, existingEdges: WorkflowEdge[], maxDistance: number): ProximityEdgeCandidate[];
+    /**
+     * Convert candidates to temporary (preview) WorkflowEdge objects with dashed styling.
+     */
+    static createPreviewEdges(candidates: ProximityEdgeCandidate[]): WorkflowEdge[];
+    /**
+     * Convert candidates to permanent WorkflowEdge objects.
+     */
+    static createPermanentEdges(candidates: ProximityEdgeCandidate[]): WorkflowEdge[];
+    /**
+     * Check if an edge is a temporary proximity preview edge.
+     */
+    static isProximityPreviewEdge(edge: WorkflowEdge): boolean;
+    /**
+     * Remove all proximity preview edges from an edge array.
+     */
+    static removePreviewEdges(edges: WorkflowEdge[]): WorkflowEdge[];
+}

package/dist/helpers/proximityConnect.js

@@ -0,0 +1,314 @@
+/**
+ * Proximity Connect Helper
+ *
+ * Provides type-aware proximity connect logic for the workflow editor.
+ * When a node is dragged near another node, this helper finds the best
+ * compatible port pair and creates a preview/permanent edge.
+ */
+import { dynamicPortToNodePort } from '../types/index.js';
+import { getPortCompatibilityChecker } from '../utils/connections.js';
+import { v4 as uuidv4 } from 'uuid';
+/** CSS class applied to proximity preview edges */
+const PROXIMITY_EDGE_CLASS = 'flowdrop--edge--proximity-preview';
+export class ProximityConnectHelper {
+    /**
+     * Get ALL ports (static + dynamic + gateway branches) for a node.
+     */
+    static getAllPorts(node, direction) {
+        // Static ports from metadata
+        const staticPorts = direction === 'output'
+            ? (node.data?.metadata?.outputs ?? [])
+            : (node.data?.metadata?.inputs ?? []);
+        // Dynamic ports from config
+        const dynamicKey = direction === 'output' ? 'dynamicOutputs' : 'dynamicInputs';
+        const rawDynamic = node.data?.config?.[dynamicKey] ?? [];
+        const dynamicPorts = rawDynamic.map((p) => dynamicPortToNodePort(p, direction));
+        // Gateway branches (output only, dataType = 'trigger')
+        if (direction === 'output') {
+            const branches = node.data?.config?.branches;
+            const nodeType = node.data?.metadata?.type || node.type;
+            if (nodeType === 'gateway' && branches?.length) {
+                const branchPorts = branches
+                    .filter((b) => !staticPorts.some((sp) => sp.id === b.name))
+                    .map((b) => ({
+                    id: b.name,
+                    name: b.name,
+                    type: 'output',
+                    dataType: 'trigger'
+                }));
+                return [...staticPorts, ...dynamicPorts, ...branchPorts];
+            }
+        }
+        return [...staticPorts, ...dynamicPorts];
+    }
+    /**
+     * Build handle ID in the standard format.
+     */
+    static buildHandleId(nodeId, direction, portId) {
+        return `${nodeId}-${direction}-${portId}`;
+    }
+    /**
+     * Calculate center-to-center distance between two nodes.
+     */
+    static getNodeDistance(nodeA, nodeB) {
+        const aCenterX = nodeA.position.x + (nodeA.measured?.width ?? 0) / 2;
+        const aCenterY = nodeA.position.y + (nodeA.measured?.height ?? 0) / 2;
+        const bCenterX = nodeB.position.x + (nodeB.measured?.width ?? 0) / 2;
+        const bCenterY = nodeB.position.y + (nodeB.measured?.height ?? 0) / 2;
+        const dx = aCenterX - bCenterX;
+        const dy = aCenterY - bCenterY;
+        return Math.sqrt(dx * dx + dy * dy);
+    }
+    /**
+     * Find the single best compatible edge between a dragged node and nearby nodes.
+     *
+     * Algorithm:
+     * 1. Find the closest node within minDistance (edge-to-edge)
+     * 2. Check both directions (dragged->nearby and nearby->dragged)
+     * 3. Return the first exact-type match, or first compatible match
+     * 4. Skip pairs where an edge already exists
+     *
+     * @returns Array with at most ONE ProximityEdgeCandidate
+     */
+    static findCompatibleEdges(draggedNode, allNodes, existingEdges, minDistance) {
+        const checker = getPortCompatibilityChecker();
+        // Build lookup set for O(1) duplicate checks
+        const existingEdgeSet = new Set(existingEdges.map((e) => `${e.source}:${e.sourceHandle}->${e.target}:${e.targetHandle}`));
+        // Find the closest node within distance
+        let closestNode = null;
+        let closestDistance = Infinity;
+        for (const node of allNodes) {
+            if (node.id === draggedNode.id)
+                continue;
+            const dist = this.getNodeDistance(draggedNode, node);
+            if (dist < minDistance && dist < closestDistance) {
+                closestDistance = dist;
+                closestNode = node;
+            }
+        }
+        if (!closestNode)
+            return [];
+        const draggedOutputs = this.getAllPorts(draggedNode, 'output');
+        const draggedInputs = this.getAllPorts(draggedNode, 'input');
+        const nearbyInputs = this.getAllPorts(closestNode, 'input');
+        const nearbyOutputs = this.getAllPorts(closestNode, 'output');
+        // Collect all compatible pairs, then pick the best one
+        let exactMatch = null;
+        let compatibleMatch = null;
+        // Direction A: dragged (source) -> nearby (target)
+        for (const outPort of draggedOutputs) {
+            for (const inPort of nearbyInputs) {
+                if (!checker.areDataTypesCompatible(outPort.dataType, inPort.dataType))
+                    continue;
+                const sourceHandle = this.buildHandleId(draggedNode.id, 'output', outPort.id);
+                const targetHandle = this.buildHandleId(closestNode.id, 'input', inPort.id);
+                const edgeKey = `${draggedNode.id}:${sourceHandle}->${closestNode.id}:${targetHandle}`;
+                if (existingEdgeSet.has(edgeKey))
+                    continue;
+                const candidate = {
+                    id: `proximity-${uuidv4()}`,
+                    source: draggedNode.id,
+                    target: closestNode.id,
+                    sourceHandle,
+                    targetHandle,
+                    sourcePortDataType: outPort.dataType,
+                    targetPortDataType: inPort.dataType
+                };
+                if (outPort.dataType === inPort.dataType) {
+                    if (!exactMatch)
+                        exactMatch = candidate;
+                }
+                else {
+                    if (!compatibleMatch)
+                        compatibleMatch = candidate;
+                }
+                // Early exit if we found an exact match
+                if (exactMatch)
+                    break;
+            }
+            if (exactMatch)
+                break;
+        }
+        // Direction B: nearby (source) -> dragged (target)
+        if (!exactMatch) {
+            for (const outPort of nearbyOutputs) {
+                for (const inPort of draggedInputs) {
+                    if (!checker.areDataTypesCompatible(outPort.dataType, inPort.dataType))
+                        continue;
+                    const sourceHandle = this.buildHandleId(closestNode.id, 'output', outPort.id);
+                    const targetHandle = this.buildHandleId(draggedNode.id, 'input', inPort.id);
+                    const edgeKey = `${closestNode.id}:${sourceHandle}->${draggedNode.id}:${targetHandle}`;
+                    if (existingEdgeSet.has(edgeKey))
+                        continue;
+                    const candidate = {
+                        id: `proximity-${uuidv4()}`,
+                        source: closestNode.id,
+                        target: draggedNode.id,
+                        sourceHandle,
+                        targetHandle,
+                        sourcePortDataType: outPort.dataType,
+                        targetPortDataType: inPort.dataType
+                    };
+                    if (outPort.dataType === inPort.dataType) {
+                        if (!exactMatch)
+                            exactMatch = candidate;
+                    }
+                    else {
+                        if (!compatibleMatch)
+                            compatibleMatch = candidate;
+                    }
+                    if (exactMatch)
+                        break;
+                }
+                if (exactMatch)
+                    break;
+            }
+        }
+        const best = exactMatch ?? compatibleMatch;
+        return best ? [best] : [];
+    }
+    /**
+     * Find the single best compatible edge using port-to-port distance.
+     *
+     * Unlike findCompatibleEdges() which uses node center distance,
+     * this method compares actual handle positions from the port coordinate store.
+     * This is more accurate for large nodes or nodes with many ports.
+     *
+     * Algorithm:
+     * 1. Partition ports by owner (dragged vs other) and direction (input vs output)
+     * 2. Group other-node ports by dataType for O(1) lookup of compatible groups
+     * 3. For each dragged port, only iterate compatible dataType groups
+     * 4. Return the closest compatible pair (exact type match preferred)
+     *
+     * @returns Array with at most ONE ProximityEdgeCandidate
+     */
+    static findCompatibleEdgesByPortCoordinates(draggedNodeId, portCoordinates, existingEdges, maxDistance) {
+        const checker = getPortCompatibilityChecker();
+        // Build lookup set for O(1) duplicate checks
+        const existingEdgeSet = new Set(existingEdges.map((e) => `${e.source}:${e.sourceHandle}->${e.target}:${e.targetHandle}`));
+        // Partition ports by owner and direction, group other-node ports by dataType
+        const draggedOutputs = [];
+        const draggedInputs = [];
+        const otherInputsByType = new Map();
+        const otherOutputsByType = new Map();
+        for (const coord of portCoordinates.values()) {
+            if (coord.nodeId === draggedNodeId) {
+                if (coord.direction === 'output')
+                    draggedOutputs.push(coord);
+                else
+                    draggedInputs.push(coord);
+            }
+            else {
+                const groupMap = coord.direction === 'input' ? otherInputsByType : otherOutputsByType;
+                let group = groupMap.get(coord.dataType);
+                if (!group) {
+                    group = [];
+                    groupMap.set(coord.dataType, group);
+                }
+                group.push(coord);
+            }
+        }
+        let bestCandidate = null;
+        let bestDistance = Infinity;
+        let bestIsExact = false;
+        const evaluatePair = (sourceCoord, targetCoord) => {
+            // Check for existing edge
+            const edgeKey = `${sourceCoord.nodeId}:${sourceCoord.handleId}->${targetCoord.nodeId}:${targetCoord.handleId}`;
+            if (existingEdgeSet.has(edgeKey))
+                return;
+            // Calculate port-to-port distance
+            const dx = sourceCoord.x - targetCoord.x;
+            const dy = sourceCoord.y - targetCoord.y;
+            const dist = Math.sqrt(dx * dx + dy * dy);
+            if (dist > maxDistance)
+                return;
+            const isExact = sourceCoord.dataType === targetCoord.dataType;
+            // Prefer exact match, then closest distance
+            if ((isExact && !bestIsExact) || (isExact === bestIsExact && dist < bestDistance)) {
+                bestCandidate = {
+                    id: `proximity-${uuidv4()}`,
+                    source: sourceCoord.nodeId,
+                    target: targetCoord.nodeId,
+                    sourceHandle: sourceCoord.handleId,
+                    targetHandle: targetCoord.handleId,
+                    sourcePortDataType: sourceCoord.dataType,
+                    targetPortDataType: targetCoord.dataType
+                };
+                bestDistance = dist;
+                bestIsExact = isExact;
+            }
+        };
+        // Direction A: dragged outputs → other inputs (only compatible types)
+        for (const srcPort of draggedOutputs) {
+            const compatibleTypes = checker.getCompatibleTypes(srcPort.dataType);
+            for (const targetType of compatibleTypes) {
+                const targets = otherInputsByType.get(targetType);
+                if (!targets)
+                    continue;
+                for (const tgtPort of targets) {
+                    evaluatePair(srcPort, tgtPort);
+                }
+            }
+        }
+        // Direction B: other outputs → dragged inputs (only compatible types)
+        for (const tgtPort of draggedInputs) {
+            for (const [srcType, sources] of otherOutputsByType) {
+                if (!checker.areDataTypesCompatible(srcType, tgtPort.dataType))
+                    continue;
+                for (const srcPort of sources) {
+                    evaluatePair(srcPort, tgtPort);
+                }
+            }
+        }
+        return bestCandidate ? [bestCandidate] : [];
+    }
+    /**
+     * Convert candidates to temporary (preview) WorkflowEdge objects with dashed styling.
+     */
+    static createPreviewEdges(candidates) {
+        return candidates.map((c) => ({
+            id: c.id,
+            source: c.source,
+            target: c.target,
+            sourceHandle: c.sourceHandle,
+            targetHandle: c.targetHandle,
+            class: PROXIMITY_EDGE_CLASS,
+            style: 'stroke-dasharray: 5 5; opacity: 0.6;',
+            animated: true,
+            selectable: false,
+            deletable: false,
+            data: {
+                metadata: {
+                    edgeType: 'data',
+                    sourcePortDataType: c.sourcePortDataType,
+                    isProximityPreview: true
+                }
+            }
+        }));
+    }
+    /**
+     * Convert candidates to permanent WorkflowEdge objects.
+     */
+    static createPermanentEdges(candidates) {
+        return candidates.map((c) => ({
+            id: uuidv4(),
+            source: c.source,
+            target: c.target,
+            sourceHandle: c.sourceHandle,
+            targetHandle: c.targetHandle
+        }));
+    }
+    /**
+     * Check if an edge is a temporary proximity preview edge.
+     */
+    static isProximityPreviewEdge(edge) {
+        return (edge.id.startsWith('proximity-') ||
+            edge.data?.metadata?.isProximityPreview === true);
+    }
+    /**
+     * Remove all proximity preview edges from an edge array.
+     */
+    static removePreviewEdges(edges) {
+        return edges.filter((e) => !this.isProximityPreviewEdge(e));
+    }
+}

package/dist/helpers/workflowEditorHelper.d.ts

@@ -0,0 +1,183 @@
+/**
+ * Workflow Editor Helper
+ * Contains business logic for workflow operations
+ */
+import type { WorkflowNode as WorkflowNodeType, NodeMetadata, Workflow, WorkflowEdge, NodeExecutionInfo } from '../types/index.js';
+import type { EndpointConfig } from '../config/endpoints.js';
+/**
+ * Generate a unique node ID based on node type and existing nodes
+ * Format: <node_type>.<number>
+ * Example: boolean_gateway.1, calculator.2
+ */
+export declare function generateNodeId(nodeTypeId: string, existingNodes: WorkflowNodeType[]): string;
+/**
+ * Edge category type for styling purposes
+ * - trigger: For control flow connections (dataType: "trigger")
+ * - tool: Dashed amber line for tool connections (dataType: "tool")
+ * - loopback: Dashed gray line for loop iteration connections (targets loop_back port)
+ * - data: Normal gray line for all other data connections
+ */
+export type EdgeCategory = 'trigger' | 'tool' | 'loopback' | 'data';
+/**
+ * Edge styling configuration based on source port data type
+ */
+export declare class EdgeStylingHelper {
+    /**
+     * Extract the port ID from a handle ID
+     * @param handleId - The handle ID string (e.g., "sample-node.1-output-trigger" or "trigger")
+     * @returns The port ID (e.g., "trigger") or the handleId itself for short format
+     */
+    static extractPortIdFromHandle(handleId: string | undefined): string | null;
+    /**
+     * Check if a port ID matches a dynamic branch in a Gateway node
+     * Gateway nodes store branches in config.branches array
+     * @param node - The workflow node to check
+     * @param portId - The port ID to look up
+     * @returns true if the portId matches a gateway branch
+     */
+    static isGatewayBranch(node: WorkflowNodeType, portId: string): boolean;
+    /**
+     * Get the data type of a port from a node's metadata
+     * Also handles dynamic ports like Gateway branches
+     * @param node - The workflow node containing the port
+     * @param portId - The port ID to look up
+     * @param portType - Whether to look in "inputs" or "outputs"
+     * @returns The port's dataType or null if not found
+     */
+    static getPortDataType(node: WorkflowNodeType, portId: string, portType: 'input' | 'output'): string | null;
+    /**
+     * Determine the edge category based on source port data type
+     * Note: This method does not check for loopback edges.
+     * Use getEdgeCategoryWithLoopback() for full edge categorization.
+     *
+     * @param sourcePortDataType - The data type of the source output port
+     * @returns The edge category for styling
+     */
+    static getEdgeCategory(sourcePortDataType: string | null): EdgeCategory;
+    /**
+     * Determine the full edge category including loopback detection
+     * Loopback edges take precedence over source port data type
+     *
+     * @param edge - The edge to categorize
+     * @param sourcePortDataType - The data type of the source output port
+     * @returns The edge category for styling
+     */
+    static getEdgeCategoryWithLoopback(edge: WorkflowEdge, sourcePortDataType: string | null): EdgeCategory;
+    /**
+     * Apply custom styling to connection edges based on edge type:
+     * - Loopback: Dashed gray line for loop iteration (targets loop_back port)
+     * - Trigger ports: Solid black line with arrow
+     * - Tool ports: Dashed amber line with arrow
+     * - Data ports: Normal gray line with arrow
+     */
+    static applyConnectionStyling(edge: WorkflowEdge, sourceNode: WorkflowNodeType, targetNode: WorkflowNodeType): void;
+    /**
+     * Update existing edges with custom styling rules
+     */
+    static updateEdgeStyles(edges: WorkflowEdge[], nodes: WorkflowNodeType[]): WorkflowEdge[];
+}
+/**
+ * Node operations helper
+ */
+export declare class NodeOperationsHelper {
+    /**
+     * Load nodes from API
+     */
+    static loadNodesFromApi(providedNodes?: NodeMetadata[]): Promise<NodeMetadata[]>;
+    /**
+     * Load node execution information for all nodes in the workflow
+     */
+    static loadNodeExecutionInfo(workflow: Workflow | null, pipelineId?: string): Promise<Record<string, NodeExecutionInfo>>;
+    /**
+     * Create a new node from dropped data
+     */
+    static createNodeFromDrop(nodeTypeData: string, position: {
+        x: number;
+        y: number;
+    }, existingNodes?: WorkflowNodeType[]): WorkflowNodeType | null;
+}
+/**
+ * Workflow operations helper
+ */
+export declare class WorkflowOperationsHelper {
+    /**
+     * Generate workflow metadata for updates
+     */
+    static generateMetadata(existingMetadata?: Workflow['metadata']): Workflow['metadata'];
+    /**
+     * Update workflow with new nodes/edges and generate new metadata
+     */
+    static updateWorkflow(workflow: Workflow, nodes: WorkflowNodeType[], edges: WorkflowEdge[]): Workflow;
+    /**
+     * Clear workflow (remove all nodes and edges)
+     */
+    static clearWorkflow(workflow: Workflow): Workflow;
+    /**
+     * Update node configuration
+     */
+    static updateNodeConfig(workflow: Workflow, nodeId: string, newConfig: Record<string, unknown>): Workflow;
+    /**
+     * Add a new node to the workflow
+     */
+    static addNode(workflow: Workflow, node: WorkflowNodeType): Workflow;
+    /**
+     * Save workflow to backend
+     */
+    static saveWorkflow(workflow: Workflow | null): Promise<Workflow | null>;
+    /**
+     * Export workflow as JSON file
+     */
+    static exportWorkflow(workflow: Workflow | null): void;
+    /**
+     * Export workflow as Agent Spec JSON file.
+     *
+     * Converts the FlowDrop workflow to Agent Spec format and triggers a download.
+     * Validates the workflow for Agent Spec compatibility first.
+     *
+     * @param workflow - The FlowDrop workflow to export
+     * @returns Validation result (check .valid before assuming success)
+     */
+    static exportAsAgentSpec(workflow: Workflow | null): {
+        valid: boolean;
+        errors: string[];
+        warnings: string[];
+    };
+    /**
+     * Import a workflow from an Agent Spec JSON or YAML file.
+     *
+     * Reads the file, detects format, converts to FlowDrop format,
+     * and returns a Workflow ready for the editor.
+     *
+     * @param file - The file to import (JSON or YAML)
+     * @returns Promise resolving to the imported FlowDrop Workflow
+     */
+    static importFromAgentSpec(file: File): Promise<Workflow>;
+    /**
+     * Check if workflow has invalid cycles (excludes valid loopback cycles)
+     * Valid loopback cycles are used for ForEach node iteration and should not
+     * trigger a warning.
+     *
+     * @param nodes - Array of workflow nodes
+     * @param edges - Array of workflow edges
+     * @returns True if there are invalid (non-loopback) cycles
+     */
+    static checkWorkflowCycles(nodes: WorkflowNodeType[], edges: WorkflowEdge[]): boolean;
+    /**
+     * Check if workflow has any cycles (including valid loopback cycles)
+     * Use this when you need to detect ALL cycles regardless of type.
+     *
+     * @param nodes - Array of workflow nodes
+     * @param edges - Array of workflow edges
+     * @returns True if any cycle exists
+     */
+    static checkWorkflowHasAnyCycles(nodes: WorkflowNodeType[], edges: WorkflowEdge[]): boolean;
+}
+/**
+ * Configuration helper
+ */
+export declare class ConfigurationHelper {
+    /**
+     * Configure API endpoints
+     */
+    static configureEndpoints(config: EndpointConfig): void;
+}