@d34dman/flowdrop 0.0.15 → 0.0.16

package/README.md

@@ -371,7 +371,6 @@ node build
 ```
 
 For detailed deployment instructions, see:
-- [DEPLOYMENT.md](./DEPLOYMENT.md) - Complete deployment guide
 - [DOCKER.md](./DOCKER.md) - Docker quick start
 
 ---

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

@@ -1,44 +1,160 @@
 /**
  * Enhanced API Client for FlowDrop
- * Uses configurable endpoints for all API actions
+ *
+ * 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 { 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);
+ *
+ * // Backward compatible (uses config.auth)
+ * const client = new EnhancedFlowDropApiClient(config);
+ * ```
  */
 export declare class EnhancedFlowDropApiClient {
     private config;
-    constructor(config: EndpointConfig);
+    private authProvider;
     /**
-     * Make HTTP request with error handling and retry logic
+     * Create a new EnhancedFlowDropApiClient
+     *
+     * @param config - Endpoint configuration
+     * @param authProvider - Optional authentication provider (if not provided, uses config.auth)
+     */
+    constructor(config: EndpointConfig, authProvider?: AuthProvider);
+    /**
+     * Make HTTP request with error handling, retry logic, and auth support
+     *
+     * @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;

package/dist/api/enhanced-client.js

@@ -1,24 +1,80 @@
 /**
  * Enhanced API Client for FlowDrop
- * Uses configurable endpoints for all API actions
+ *
+ * Uses configurable endpoints and supports pluggable authentication providers.
+ *
+ * @module api/enhanced-client
  */
-import { buildEndpointUrl, getEndpointMethod, getEndpointHeaders } from '../config/endpoints.js';
+import { buildEndpointUrl, getEndpointMethod, getEndpointHeaders } from "../config/endpoints.js";
+import { createAuthProviderFromLegacyConfig } from "../types/auth.js";
+/**
+ * API error with additional context
+ */
+export class ApiError extends Error {
+    /** HTTP status code */
+    status;
+    /** Original error data from API */
+    errorData;
+    /** Operation that was being performed */
+    operation;
+    constructor(message, status, operation, errorData = {}) {
+        super(message);
+        this.name = "ApiError";
+        this.status = status;
+        this.operation = operation;
+        this.errorData = errorData;
+    }
+}
 /**
  * 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);
+ *
+ * // Backward compatible (uses config.auth)
+ * const client = new EnhancedFlowDropApiClient(config);
+ * ```
  */
 export class EnhancedFlowDropApiClient {
     config;
-    constructor(config) {
+    authProvider;
+    /**
+     * Create a new EnhancedFlowDropApiClient
+     *
+     * @param config - Endpoint configuration
+     * @param authProvider - Optional authentication provider (if not provided, uses config.auth)
+     */
+    constructor(config, authProvider) {
         this.config = config;
+        // Use provided AuthProvider or create one from legacy config
+        this.authProvider = authProvider ?? createAuthProviderFromLegacyConfig(config.auth);
     }
     /**
-     * Make HTTP request with error handling and retry logic
+     * Make HTTP request with error handling, retry logic, and auth support
+     *
+     * @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)
      */
-    async request(endpointKey, endpointPath, params, options = {}) {
+    async request(endpointKey, endpointPath, params, options = {}, operation = "API request") {
         const url = buildEndpointUrl(this.config, endpointPath, params);
-        const method = getEndpointMethod(this.config, endpointKey);
-        const headers = getEndpointHeaders(this.config, endpointKey);
-        const config = {
+        const method = options.method ?? getEndpointMethod(this.config, endpointKey);
+        const configHeaders = getEndpointHeaders(this.config, endpointKey);
+        // Get auth headers from provider
+        const authHeaders = await this.authProvider.getAuthHeaders();
+        // Merge headers: config headers < auth headers < request-specific headers
+        const headers = {
+            ...configHeaders,
+            ...authHeaders,
+            ...options.headers
+        };
+        const fetchConfig = {
             method,
             headers,
             ...options
@@ -27,184 +83,307 @@ export class EnhancedFlowDropApiClient {
         const maxAttempts = this.config.retry?.enabled ? this.config.retry.maxAttempts : 1;
         for (let attempt = 1; attempt <= maxAttempts; attempt++) {
             try {
-                const response = await fetch(url, config);
+                const response = await fetch(url, fetchConfig);
+                // Handle 401 Unauthorized
+                if (response.status === 401) {
+                    if (this.authProvider.onUnauthorized) {
+                        const refreshed = await this.authProvider.onUnauthorized();
+                        if (refreshed && attempt < maxAttempts) {
+                            // Get new auth headers and retry
+                            const newAuthHeaders = await this.authProvider.getAuthHeaders();
+                            fetchConfig.headers = {
+                                ...configHeaders,
+                                ...newAuthHeaders,
+                                ...options.headers
+                            };
+                            continue; // Retry with new headers
+                        }
+                    }
+                    throw new ApiError("Unauthorized", 401, operation, {});
+                }
+                // Handle 403 Forbidden
+                if (response.status === 403) {
+                    if (this.authProvider.onForbidden) {
+                        await this.authProvider.onForbidden();
+                    }
+                    throw new ApiError("Forbidden", 403, operation, {});
+                }
+                // Handle other errors
                 if (!response.ok) {
                     const errorData = await response.json().catch(() => ({}));
-                    throw new Error(errorData.error || `HTTP ${response.status}: ${response.statusText}`);
+                    throw new ApiError(errorData.error ?? `HTTP ${response.status}: ${response.statusText}`, response.status, operation, errorData);
                 }
                 const data = await response.json();
                 return data;
             }
             catch (error) {
-                lastError = error instanceof Error ? error : new Error(String(error));
-                // Don't retry on last attempt
-                if (attempt === maxAttempts) {
-                    console.error(`API request failed after ${maxAttempts} attempts:`, lastError);
+                // If it's already an ApiError, preserve it
+                if (error instanceof ApiError) {
+                    lastError = error;
+                }
+                else {
+                    lastError = error instanceof Error ? error : new Error(String(error));
+                }
+                // Don't retry on auth errors (401, 403) or last attempt
+                if ((lastError instanceof ApiError &&
+                    (lastError.status === 401 || lastError.status === 403)) ||
+                    attempt === maxAttempts) {
+                    console.error(`API request failed after ${attempt} attempts:`, lastError);
                     throw lastError;
                 }
                 // Wait before retry
-                const delay = this.config.retry?.delay || 1000;
-                const backoffDelay = this.config.retry?.backoff === 'exponential' ? delay * Math.pow(2, attempt - 1) : delay;
+                const delay = this.config.retry?.delay ?? 1000;
+                const backoffDelay = this.config.retry?.backoff === "exponential" ? delay * Math.pow(2, attempt - 1) : delay;
                 await new Promise((resolve) => setTimeout(resolve, backoffDelay));
             }
         }
         throw lastError;
     }
+    /**
+     * 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) {
+        this.authProvider = authProvider;
+    }
+    /**
+     * Get current auth provider
+     *
+     * @returns The current AuthProvider instance
+     */
+    getAuthProvider() {
+        return this.authProvider;
+    }
+    // =========================================================================
     // Node API Methods
+    // =========================================================================
+    /**
+     * Fetch all available node types
+     */
     async getAvailableNodes() {
-        const response = await this.request('nodes.list', this.config.endpoints.nodes.list);
+        const response = await this.request("nodes.list", this.config.endpoints.nodes.list, undefined, {}, "fetch available nodes");
         if (!response.success || !response.data) {
-            throw new Error(response.error || 'Failed to fetch available nodes');
+            throw new Error(response.error ?? "Failed to fetch available nodes");
         }
         return response.data;
     }
+    /**
+     * Fetch nodes filtered by category
+     */
     async getNodesByCategory(category) {
-        const response = await this.request('nodes.byCategory', this.config.endpoints.nodes.byCategory, { category });
+        const response = await this.request("nodes.byCategory", this.config.endpoints.nodes.byCategory, { category }, {}, "fetch nodes by category");
         if (!response.success || !response.data) {
-            throw new Error(response.error || 'Failed to fetch nodes by category');
+            throw new Error(response.error ?? "Failed to fetch nodes by category");
         }
         return response.data;
     }
+    /**
+     * Fetch metadata for a specific node type
+     */
     async getNodeMetadata(nodeId) {
-        const response = await this.request('nodes.metadata', this.config.endpoints.nodes.metadata, { id: nodeId });
+        const response = await this.request("nodes.metadata", this.config.endpoints.nodes.metadata, { id: nodeId }, {}, "fetch node metadata");
         if (!response.success || !response.data) {
-            throw new Error(response.error || 'Failed to fetch node metadata');
+            throw new Error(response.error ?? "Failed to fetch node metadata");
         }
         return response.data;
     }
+    // =========================================================================
     // Workflow API Methods
+    // =========================================================================
+    /**
+     * Save a new workflow
+     */
     async saveWorkflow(workflow) {
-        const response = await this.request('workflows.create', this.config.endpoints.workflows.create, undefined, {
-            method: 'POST',
+        const response = await this.request("workflows.create", this.config.endpoints.workflows.create, undefined, {
+            method: "POST",
             body: JSON.stringify(workflow)
-        });
+        }, "save workflow");
         if (!response.success || !response.data) {
-            throw new Error(response.error || 'Failed to save workflow');
+            throw new Error(response.error ?? "Failed to save workflow");
         }
         return response.data;
     }
+    /**
+     * Update an existing workflow
+     */
     async updateWorkflow(workflowId, workflow) {
-        const response = await this.request('workflows.update', this.config.endpoints.workflows.update, { id: workflowId }, {
-            method: 'PUT',
+        const response = await this.request("workflows.update", this.config.endpoints.workflows.update, { id: workflowId }, {
+            method: "PUT",
             body: JSON.stringify(workflow)
-        });
+        }, "update workflow");
         if (!response.success || !response.data) {
-            throw new Error(response.error || 'Failed to update workflow');
+            throw new Error(response.error ?? "Failed to update workflow");
         }
         return response.data;
     }
+    /**
+     * Load a workflow by ID
+     */
     async loadWorkflow(workflowId) {
-        const response = await this.request('workflows.get', this.config.endpoints.workflows.get, { id: workflowId });
+        const response = await this.request("workflows.get", this.config.endpoints.workflows.get, { id: workflowId }, {}, "load workflow");
         if (!response.success || !response.data) {
-            throw new Error(response.error || 'Failed to load workflow');
+            throw new Error(response.error ?? "Failed to load workflow");
         }
         return response.data;
     }
+    /**
+     * List all workflows
+     */
     async listWorkflows() {
-        const response = await this.request('workflows.list', this.config.endpoints.workflows.list);
+        const response = await this.request("workflows.list", this.config.endpoints.workflows.list, undefined, {}, "list workflows");
         if (!response.success || !response.data) {
-            throw new Error(response.error || 'Failed to list workflows');
+            throw new Error(response.error ?? "Failed to list workflows");
         }
         return response.data;
     }
+    /**
+     * Delete a workflow
+     */
     async deleteWorkflow(workflowId) {
-        const response = await this.request('workflows.delete', this.config.endpoints.workflows.delete, { id: workflowId }, { method: 'DELETE' });
+        const response = await this.request("workflows.delete", this.config.endpoints.workflows.delete, { id: workflowId }, { method: "DELETE" }, "delete workflow");
         if (!response.success) {
-            throw new Error(response.error || 'Failed to delete workflow');
+            throw new Error(response.error ?? "Failed to delete workflow");
         }
     }
+    /**
+     * Validate a workflow
+     */
     async validateWorkflow(workflow) {
-        const response = await this.request('workflows.validate', this.config.endpoints.workflows.validate, undefined, {
-            method: 'POST',
+        const response = await this.request("workflows.validate", this.config.endpoints.workflows.validate, undefined, {
+            method: "POST",
             body: JSON.stringify(workflow)
-        });
+        }, "validate workflow");
         if (!response.success || !response.data) {
-            throw new Error(response.error || 'Failed to validate workflow');
+            throw new Error(response.error ?? "Failed to validate workflow");
         }
         return response.data;
     }
+    /**
+     * Export a workflow as JSON string
+     */
     async exportWorkflow(workflowId) {
-        const response = await this.request('workflows.export', this.config.endpoints.workflows.export, { id: workflowId });
+        const response = await this.request("workflows.export", this.config.endpoints.workflows.export, { id: workflowId }, {}, "export workflow");
         if (!response.success || !response.data) {
-            throw new Error(response.error || 'Failed to export workflow');
+            throw new Error(response.error ?? "Failed to export workflow");
         }
         return response.data;
     }
+    /**
+     * Import a workflow from JSON
+     */
     async importWorkflow(workflowJson) {
-        const response = await this.request('workflows.import', this.config.endpoints.workflows.import, undefined, {
-            method: 'POST',
+        const response = await this.request("workflows.import", this.config.endpoints.workflows.import, undefined, {
+            method: "POST",
             body: JSON.stringify({ workflow: workflowJson })
-        });
+        }, "import workflow");
         if (!response.success || !response.data) {
-            throw new Error(response.error || 'Failed to import workflow');
+            throw new Error(response.error ?? "Failed to import workflow");
         }
         return response.data;
     }
+    // =========================================================================
     // Execution API Methods
+    // =========================================================================
+    /**
+     * Execute a workflow
+     */
     async executeWorkflow(workflowId, inputs) {
-        const response = await this.request('executions.execute', this.config.endpoints.executions.execute, { id: workflowId }, {
-            method: 'POST',
+        const response = await this.request("executions.execute", this.config.endpoints.executions.execute, { id: workflowId }, {
+            method: "POST",
             body: JSON.stringify({ inputs })
-        });
+        }, "execute workflow");
         if (!response.success || !response.data) {
-            throw new Error(response.error || 'Failed to execute workflow');
+            throw new Error(response.error ?? "Failed to execute workflow");
         }
         return response.data;
     }
+    /**
+     * Get execution status
+     */
     async getExecutionStatus(executionId) {
-        const response = await this.request('executions.status', this.config.endpoints.executions.status, { id: executionId });
+        const response = await this.request("executions.status", this.config.endpoints.executions.status, { id: executionId }, {}, "get execution status");
         if (!response.success || !response.data) {
-            throw new Error(response.error || 'Failed to get execution status');
+            throw new Error(response.error ?? "Failed to get execution status");
         }
         return response.data;
     }
+    /**
+     * Cancel a running execution
+     */
     async cancelExecution(executionId) {
-        const response = await this.request('executions.cancel', this.config.endpoints.executions.cancel, { id: executionId }, { method: 'POST' });
+        const response = await this.request("executions.cancel", this.config.endpoints.executions.cancel, { id: executionId }, { method: "POST" }, "cancel execution");
         if (!response.success) {
-            throw new Error(response.error || 'Failed to cancel execution');
+            throw new Error(response.error ?? "Failed to cancel execution");
         }
     }
+    /**
+     * Get execution logs
+     */
     async getExecutionLogs(executionId) {
-        const response = await this.request('executions.logs', this.config.endpoints.executions.logs, { id: executionId });
+        const response = await this.request("executions.logs", this.config.endpoints.executions.logs, { id: executionId }, {}, "get execution logs");
         if (!response.success || !response.data) {
-            throw new Error(response.error || 'Failed to get execution logs');
+            throw new Error(response.error ?? "Failed to get execution logs");
         }
         return response.data;
     }
+    // =========================================================================
     // Template API Methods
+    // =========================================================================
+    /**
+     * List available templates
+     */
     async listTemplates() {
-        const response = await this.request('templates.list', this.config.endpoints.templates.list);
+        const response = await this.request("templates.list", this.config.endpoints.templates.list, undefined, {}, "list templates");
         if (!response.success || !response.data) {
-            throw new Error(response.error || 'Failed to list templates');
+            throw new Error(response.error ?? "Failed to list templates");
         }
         return response.data;
     }
+    /**
+     * Get a template by ID
+     */
     async getTemplate(templateId) {
-        const response = await this.request('templates.get', this.config.endpoints.templates.get, { id: templateId });
+        const response = await this.request("templates.get", this.config.endpoints.templates.get, { id: templateId }, {}, "get template");
         if (!response.success || !response.data) {
-            throw new Error(response.error || 'Failed to get template');
+            throw new Error(response.error ?? "Failed to get template");
         }
         return response.data;
     }
+    // =========================================================================
     // System API Methods
+    // =========================================================================
+    /**
+     * Get system health status
+     */
     async getSystemHealth() {
-        const response = await this.request('system.health', this.config.endpoints.system.health);
+        const response = await this.request("system.health", this.config.endpoints.system.health, undefined, {}, "get system health");
         if (!response.success || !response.data) {
-            throw new Error(response.error || 'Failed to get system health');
+            throw new Error(response.error ?? "Failed to get system health");
         }
         return response.data;
     }
+    /**
+     * Get system configuration
+     */
     async getSystemConfig() {
-        const response = await this.request('system.config', this.config.endpoints.system.config);
+        const response = await this.request("system.config", this.config.endpoints.system.config, undefined, {}, "get system config");
         if (!response.success || !response.data) {
-            throw new Error(response.error || 'Failed to get system config');
+            throw new Error(response.error ?? "Failed to get system config");
         }
         return response.data;
     }
+    /**
+     * Get system version information
+     */
     async getSystemVersion() {
-        const response = await this.request('system.version', this.config.endpoints.system.version);
+        const response = await this.request("system.version", this.config.endpoints.system.version, undefined, {}, "get system version");
         if (!response.success || !response.data) {
-            throw new Error(response.error || 'Failed to get system version');
+            throw new Error(response.error ?? "Failed to get system version");
         }
         return response.data;
     }