@d34dman/flowdrop 0.0.15 → 0.0.17

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 { 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 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',
             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',
             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',
             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',
             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',
             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;
     }