@flowdrop/flowdrop 1.0.0

package/dist/adapters/agentspec/validator.js

@@ -0,0 +1,169 @@
+/**
+ * Agent Spec Validator
+ *
+ * Validates workflows against Agent Spec constraints for export,
+ * and validates imported Agent Spec documents for correctness.
+ */
+/**
+ * Validate a FlowDrop StandardWorkflow for Agent Spec export compatibility.
+ *
+ * Checks:
+ * - Must have exactly 1 start node (terminal/triggers)
+ * - Must have at least 1 end node (terminal/outputs)
+ * - Gateway nodes must have branches defined
+ */
+export function validateForAgentSpecExport(workflow) {
+    const errors = [];
+    const warnings = [];
+    if (workflow.nodes.length === 0) {
+        errors.push('Workflow has no nodes');
+        return { valid: false, errors, warnings };
+    }
+    // Check for start nodes
+    const startNodes = workflow.nodes.filter((n) => {
+        const ext = n.data.metadata.extensions?.['agentspec:component_type'];
+        if (ext === 'start_node')
+            return true;
+        return n.data.metadata.type === 'terminal' && n.data.metadata.category === 'triggers';
+    });
+    if (startNodes.length === 0) {
+        errors.push('Agent Spec requires exactly one StartNode. No start node found (terminal node with triggers category).');
+    }
+    else if (startNodes.length > 1) {
+        errors.push(`Agent Spec requires exactly one StartNode. Found ${startNodes.length}: ${startNodes.map((n) => n.id).join(', ')}`);
+    }
+    // Check for end nodes
+    const endNodes = workflow.nodes.filter((n) => {
+        const ext = n.data.metadata.extensions?.['agentspec:component_type'];
+        if (ext === 'end_node')
+            return true;
+        return n.data.metadata.type === 'terminal' && n.data.metadata.category === 'outputs';
+    });
+    if (endNodes.length === 0) {
+        errors.push('Agent Spec requires at least one EndNode. No end node found (terminal node with outputs category).');
+    }
+    // Check gateway nodes have branches
+    const gatewayNodes = workflow.nodes.filter((n) => {
+        const ext = n.data.metadata.extensions?.['agentspec:component_type'];
+        return ext === 'branching_node' || n.data.metadata.type === 'gateway';
+    });
+    for (const gw of gatewayNodes) {
+        const branches = gw.data.config?.branches;
+        if (!branches || !Array.isArray(branches) || branches.length === 0) {
+            warnings.push(`Gateway node "${gw.data.label || gw.id}" has no branches defined. Agent Spec BranchingNode requires at least one branch.`);
+        }
+    }
+    // Check for disconnected nodes
+    const connectedNodes = new Set();
+    for (const edge of workflow.edges) {
+        connectedNodes.add(edge.source);
+        connectedNodes.add(edge.target);
+    }
+    const disconnected = workflow.nodes.filter((n) => !connectedNodes.has(n.id));
+    if (disconnected.length > 0) {
+        warnings.push(`${disconnected.length} node(s) are not connected to any edges: ${disconnected.map((n) => n.data.label || n.id).join(', ')}`);
+    }
+    return { valid: errors.length === 0, errors, warnings };
+}
+/**
+ * Validate an imported Agent Spec Flow document.
+ *
+ * Checks:
+ * - Has a start_node reference that exists
+ * - At least one end_node exists
+ * - All edge references point to existing nodes
+ * - BranchingNode has branches
+ * - Data flow edges reference valid properties
+ */
+export function validateAgentSpecFlow(flow) {
+    const errors = [];
+    const warnings = [];
+    if (!flow.nodes || flow.nodes.length === 0) {
+        errors.push('Flow has no nodes');
+        return { valid: false, errors, warnings };
+    }
+    // Build node name set
+    const nodeNames = new Set(flow.nodes.map((n) => n.name));
+    // Check start_node exists
+    if (!flow.start_node) {
+        errors.push('Flow is missing start_node reference');
+    }
+    else if (!nodeNames.has(flow.start_node)) {
+        errors.push(`start_node "${flow.start_node}" does not match any node name`);
+    }
+    // Check start_node is actually a start_node type
+    const startNode = flow.nodes.find((n) => n.name === flow.start_node);
+    if (startNode && startNode.component_type !== 'start_node') {
+        warnings.push(`start_node "${flow.start_node}" has component_type "${startNode.component_type}" instead of "start_node"`);
+    }
+    // Check for end nodes
+    const endNodes = flow.nodes.filter((n) => n.component_type === 'end_node');
+    if (endNodes.length === 0) {
+        warnings.push('Flow has no EndNode. Consider adding one for clarity.');
+    }
+    // Check for duplicate node names
+    const nameCount = new Map();
+    for (const node of flow.nodes) {
+        nameCount.set(node.name, (nameCount.get(node.name) || 0) + 1);
+    }
+    for (const [name, count] of nameCount) {
+        if (count > 1) {
+            errors.push(`Duplicate node name: "${name}" appears ${count} times`);
+        }
+    }
+    // Validate control-flow edges
+    for (const edge of flow.control_flow_connections) {
+        if (!nodeNames.has(edge.from_node)) {
+            errors.push(`Control flow edge "${edge.name}" references non-existent from_node "${edge.from_node}"`);
+        }
+        if (!nodeNames.has(edge.to_node)) {
+            errors.push(`Control flow edge "${edge.name}" references non-existent to_node "${edge.to_node}"`);
+        }
+        // Validate from_branch references
+        if (edge.from_branch) {
+            const fromNode = flow.nodes.find((n) => n.name === edge.from_node);
+            if (fromNode && fromNode.component_type === 'branching_node') {
+                const branchingNode = fromNode;
+                if (!branchingNode.branches?.some((b) => b.name === edge.from_branch)) {
+                    errors.push(`Control flow edge "${edge.name}" references branch "${edge.from_branch}" which doesn't exist on node "${edge.from_node}"`);
+                }
+            }
+        }
+    }
+    // Validate data-flow edges
+    if (flow.data_flow_connections) {
+        for (const edge of flow.data_flow_connections) {
+            if (!nodeNames.has(edge.source_node)) {
+                errors.push(`Data flow edge "${edge.name}" references non-existent source_node "${edge.source_node}"`);
+            }
+            if (!nodeNames.has(edge.destination_node)) {
+                errors.push(`Data flow edge "${edge.name}" references non-existent destination_node "${edge.destination_node}"`);
+            }
+            // Check that output/input properties exist on the nodes
+            const sourceNode = flow.nodes.find((n) => n.name === edge.source_node);
+            if (sourceNode?.outputs) {
+                const hasOutput = sourceNode.outputs.some((o) => o.title === edge.source_output);
+                if (!hasOutput) {
+                    warnings.push(`Data flow edge "${edge.name}": source node "${edge.source_node}" has no output named "${edge.source_output}"`);
+                }
+            }
+            const destNode = flow.nodes.find((n) => n.name === edge.destination_node);
+            if (destNode?.inputs) {
+                const hasInput = destNode.inputs.some((i) => i.title === edge.destination_input);
+                if (!hasInput) {
+                    warnings.push(`Data flow edge "${edge.name}": destination node "${edge.destination_node}" has no input named "${edge.destination_input}"`);
+                }
+            }
+        }
+    }
+    // Validate branching nodes have branches
+    for (const node of flow.nodes) {
+        if (node.component_type === 'branching_node') {
+            const bn = node;
+            if (!bn.branches || bn.branches.length === 0) {
+                warnings.push(`BranchingNode "${node.name}" has no branches defined`);
+            }
+        }
+    }
+    return { valid: errors.length === 0, errors, warnings };
+}

package/dist/api/enhanced-client.d.ts

@@ -0,0 +1,183 @@
+/**
+ * Enhanced API Client for FlowDrop
+ *
+ * Uses configurable endpoints and supports pluggable authentication providers.
+ *
+ * @module api/enhanced-client
+ */
+import type { NodeMetadata, Workflow, ExecutionResult } from '../types/index.js';
+import type { EndpointConfig } from '../config/endpoints.js';
+import type { AuthProvider } from '../types/auth.js';
+/**
+ * API error with additional context
+ */
+export declare class ApiError extends Error {
+    /** HTTP status code */
+    readonly status: number;
+    /** Original error data from API */
+    readonly errorData: Record<string, unknown>;
+    /** Operation that was being performed */
+    readonly operation: string;
+    constructor(message: string, status: number, operation: string, errorData?: Record<string, unknown>);
+}
+/**
+ * Enhanced HTTP API client for FlowDrop with configurable endpoints
+ *
+ * Supports pluggable authentication via AuthProvider interface.
+ *
+ * @example
+ * ```typescript
+ * // With AuthProvider
+ * const client = new EnhancedFlowDropApiClient(config, authProvider);
+ *
+ * // Without authentication
+ * const client = new EnhancedFlowDropApiClient(config);
+ * ```
+ */
+export declare class EnhancedFlowDropApiClient {
+    private config;
+    private authProvider;
+    /**
+     * Create a new EnhancedFlowDropApiClient
+     *
+     * @param config - Endpoint configuration
+     * @param authProvider - Optional authentication provider (defaults to NoAuthProvider)
+     */
+    constructor(config: EndpointConfig, authProvider?: AuthProvider);
+    /**
+     * Make HTTP request with error handling, retry logic, timeout, and auth support
+     *
+     * Uses apiSettings for timeout and retry configuration, falling back to EndpointConfig values.
+     *
+     * @param endpointKey - Key identifying the endpoint (for method/header lookup)
+     * @param endpointPath - The endpoint path template
+     * @param params - URL parameters to substitute
+     * @param options - Additional fetch options
+     * @param operation - Description of the operation (for error messages)
+     */
+    private request;
+    /**
+     * Update the auth provider
+     *
+     * Useful for updating auth after token refresh in parent application.
+     * Note: Per specification, this should rarely be needed as auth is typically
+     * set at mount time and requires remount to change.
+     *
+     * @param authProvider - New authentication provider
+     */
+    setAuthProvider(authProvider: AuthProvider): void;
+    /**
+     * Get current auth provider
+     *
+     * @returns The current AuthProvider instance
+     */
+    getAuthProvider(): AuthProvider;
+    /**
+     * Fetch all available node types
+     */
+    getAvailableNodes(): Promise<NodeMetadata[]>;
+    /**
+     * Fetch nodes filtered by category
+     */
+    getNodesByCategory(category: string): Promise<NodeMetadata[]>;
+    /**
+     * Fetch metadata for a specific node type
+     */
+    getNodeMetadata(nodeId: string): Promise<NodeMetadata>;
+    /**
+     * Save a new workflow
+     */
+    saveWorkflow(workflow: Workflow): Promise<Workflow>;
+    /**
+     * Update an existing workflow
+     */
+    updateWorkflow(workflowId: string, workflow: Partial<Workflow>): Promise<Workflow>;
+    /**
+     * Load a workflow by ID
+     */
+    loadWorkflow(workflowId: string): Promise<Workflow>;
+    /**
+     * List all workflows
+     */
+    listWorkflows(): Promise<Workflow[]>;
+    /**
+     * Delete a workflow
+     */
+    deleteWorkflow(workflowId: string): Promise<void>;
+    /**
+     * Validate a workflow
+     */
+    validateWorkflow(workflow: Workflow): Promise<{
+        valid: boolean;
+        errors: string[];
+    }>;
+    /**
+     * Export a workflow as JSON string
+     */
+    exportWorkflow(workflowId: string): Promise<string>;
+    /**
+     * Import a workflow from JSON
+     */
+    importWorkflow(workflowJson: string): Promise<Workflow>;
+    /**
+     * Execute a workflow
+     */
+    executeWorkflow(workflowId: string, inputs?: Record<string, unknown>): Promise<ExecutionResult>;
+    /**
+     * Get execution status
+     */
+    getExecutionStatus(executionId: string): Promise<ExecutionResult>;
+    /**
+     * Cancel a running execution
+     */
+    cancelExecution(executionId: string): Promise<void>;
+    /**
+     * Get execution logs
+     */
+    getExecutionLogs(executionId: string): Promise<string[]>;
+    /**
+     * List available templates
+     */
+    listTemplates(): Promise<Workflow[]>;
+    /**
+     * Get a template by ID
+     */
+    getTemplate(templateId: string): Promise<Workflow>;
+    /**
+     * Get system health status
+     */
+    getSystemHealth(): Promise<{
+        status: string;
+        timestamp: number;
+    }>;
+    /**
+     * Get system configuration
+     */
+    getSystemConfig(): Promise<Record<string, unknown>>;
+    /**
+     * Get system version information
+     */
+    getSystemVersion(): Promise<{
+        version: string;
+        build: string;
+    }>;
+    /**
+     * Fetch pipeline data including job information and status
+     */
+    getPipelineData(pipelineId: string): Promise<{
+        status: string;
+        jobs: Array<Record<string, unknown>>;
+        node_statuses: Record<string, {
+            status: string;
+            [key: string]: unknown;
+        }>;
+        job_status_summary: {
+            total: number;
+            pending: number;
+            running: number;
+            completed: number;
+            failed: number;
+            cancelled: number;
+        };
+    }>;
+}