@flowdrop/flowdrop 1.0.0

package/dist/services/api.js

@@ -0,0 +1,214 @@
+/**
+ * Client-side API service for FlowDrop
+ * Provides methods to interact with the backend APIs using configurable endpoints
+ */
+import { buildEndpointUrl, getEndpointMethod, getEndpointHeaders } from '../config/endpoints.js';
+let endpointConfig = null;
+/**
+ * Set the endpoint configuration at runtime
+ */
+export function setEndpointConfig(config) {
+    endpointConfig = config;
+}
+/**
+ * Get the current endpoint configuration
+ */
+export function getEndpointConfig() {
+    return endpointConfig;
+}
+/**
+ * Generic API request helper with endpoint configuration
+ */
+async function apiRequest(endpointKey, endpointPath, params, options = {}) {
+    if (!endpointConfig) {
+        throw new Error('Endpoint configuration not set. Call setEndpointConfig() first.');
+    }
+    const url = buildEndpointUrl(endpointConfig, endpointPath, params);
+    const method = getEndpointMethod(endpointConfig, endpointKey);
+    const headers = getEndpointHeaders(endpointConfig, endpointKey);
+    const response = await fetch(url, {
+        method,
+        headers,
+        ...options
+    });
+    // Check if response is JSON
+    const contentType = response.headers.get('content-type');
+    const isJson = contentType?.includes('application/json');
+    if (!response.ok) {
+        // Try to get error details
+        let errorMessage = `HTTP ${response.status}: ${response.statusText}`;
+        if (isJson) {
+            try {
+                const data = await response.json();
+                errorMessage = data.error || data.message || errorMessage;
+            }
+            catch {
+                // Failed to parse JSON, use default error message
+            }
+        }
+        else {
+            // Response is not JSON (probably HTML error page)
+            try {
+                const text = await response.text();
+                // Extract first 200 characters for debugging
+                const preview = text.substring(0, 200).trim();
+                errorMessage = `${errorMessage}. Server returned: ${preview}...`;
+            }
+            catch {
+                // Failed to read response text
+            }
+        }
+        throw new Error(errorMessage);
+    }
+    // Parse successful response
+    const data = await response.json();
+    return data;
+}
+/**
+ * Node API methods
+ */
+export const nodeApi = {
+    /**
+     * Get all node types with optional filtering
+     */
+    async getNodes(options) {
+        if (!endpointConfig) {
+            throw new Error('Endpoint configuration not set');
+        }
+        const params = new URLSearchParams();
+        if (options?.category)
+            params.append('category', options.category);
+        if (options?.search)
+            params.append('search', options.search);
+        if (options?.limit)
+            params.append('limit', options.limit.toString());
+        if (options?.offset)
+            params.append('offset', options.offset.toString());
+        const response = await apiRequest('nodes.list', endpointConfig.endpoints.nodes.list + '?' + params.toString());
+        return response.data || [];
+    },
+    /**
+     * Get a specific node type by ID
+     */
+    async getNode(id) {
+        if (!endpointConfig) {
+            throw new Error('Endpoint configuration not set');
+        }
+        const response = await apiRequest('nodes.get', endpointConfig.endpoints.nodes.get, { id });
+        if (!response.data) {
+            throw new Error('Node not found');
+        }
+        return response.data;
+    }
+};
+/**
+ * Workflow API methods
+ */
+export const workflowApi = {
+    /**
+     * Get all workflows with optional filtering
+     */
+    async getWorkflows(options) {
+        if (!endpointConfig) {
+            throw new Error('Endpoint configuration not set');
+        }
+        const params = new URLSearchParams();
+        if (options?.search)
+            params.append('search', options.search);
+        if (options?.limit)
+            params.append('limit', options.limit.toString());
+        if (options?.offset)
+            params.append('offset', options.offset.toString());
+        const response = await apiRequest('workflows.list', endpointConfig.endpoints.workflows.list + '?' + params.toString());
+        return response.data || [];
+    },
+    /**
+     * Get a specific workflow by ID
+     */
+    async getWorkflow(id) {
+        if (!endpointConfig) {
+            throw new Error('Endpoint configuration not set');
+        }
+        const response = await apiRequest('workflows.get', endpointConfig.endpoints.workflows.get, { id });
+        if (!response.data) {
+            throw new Error('Workflow not found');
+        }
+        return response.data;
+    },
+    /**
+     * Create a new workflow
+     */
+    async createWorkflow(workflow) {
+        if (!endpointConfig) {
+            throw new Error('Endpoint configuration not set');
+        }
+        // Apply the consumer-provided payload transform (e.g. Drupal's label mapping).
+        // The default is the identity function — no CMS-specific logic in the core library.
+        const transform = endpointConfig.transformWorkflowPayload ?? ((w) => w);
+        const body = transform(workflow);
+        const response = await apiRequest('workflows.create', endpointConfig.endpoints.workflows.create, undefined, {
+            method: 'POST',
+            body: JSON.stringify(body)
+        });
+        if (!response.data) {
+            throw new Error('Failed to create workflow');
+        }
+        return response.data;
+    },
+    /**
+     * Update an existing workflow
+     */
+    async updateWorkflow(id, workflow) {
+        if (!endpointConfig) {
+            throw new Error('Endpoint configuration not set');
+        }
+        // Apply the consumer-provided payload transform (e.g. Drupal's label mapping).
+        // The default is the identity function — no CMS-specific logic in the core library.
+        const transform = endpointConfig.transformWorkflowPayload ?? ((w) => w);
+        const body = transform(workflow);
+        const response = await apiRequest('workflows.update', endpointConfig.endpoints.workflows.update, { id }, {
+            method: 'PUT',
+            body: JSON.stringify(body)
+        });
+        if (!response.data) {
+            throw new Error('Failed to update workflow');
+        }
+        return response.data;
+    },
+    /**
+     * Delete a workflow
+     */
+    async deleteWorkflow(id) {
+        if (!endpointConfig) {
+            throw new Error('Endpoint configuration not set');
+        }
+        await apiRequest('workflows.delete', endpointConfig.endpoints.workflows.delete, { id }, { method: 'DELETE' });
+    },
+    /**
+     * Save workflow (create or update)
+     */
+    async saveWorkflow(workflow) {
+        // Check if this is an existing workflow by looking for a valid ID
+        // Valid IDs should not be a UUID (which indicates a new workflow)
+        const isExistingWorkflow = workflow.id &&
+            workflow.id.length > 0 &&
+            !workflow.id.match(/^[0-9a-f]{8}-[0-9a-f]{4}-[0-9a-f]{4}-[0-9a-f]{4}-[0-9a-f]{12}$/i);
+        if (isExistingWorkflow) {
+            // Update existing workflow
+            return this.updateWorkflow(workflow.id, workflow);
+        }
+        else {
+            // Create new workflow
+            // eslint-disable-next-line @typescript-eslint/no-unused-vars
+            const { id, ...workflowData } = workflow;
+            return this.createWorkflow(workflowData);
+        }
+    }
+};
+/**
+ * Export the API service
+ */
+export const api = {
+    nodes: nodeApi,
+    workflows: workflowApi
+};

package/dist/services/apiVariableService.d.ts

@@ -0,0 +1,114 @@
+/**
+ * API Variable Service
+ * Handles fetching template variable schemas from REST endpoints at runtime.
+ * Enables dynamic variable suggestions from backend APIs for template editors.
+ *
+ * @module services/apiVariableService
+ */
+import type { VariableSchema, ApiVariablesConfig, AuthProvider } from '../types/index.js';
+/**
+ * Context for variable API requests
+ */
+interface VariableContext {
+    /** Workflow ID */
+    workflowId?: string;
+    /** Node instance ID */
+    nodeId: string;
+}
+/**
+ * Result of a variable schema fetch operation
+ */
+export interface ApiVariableResult {
+    /** Whether the fetch was successful */
+    success: boolean;
+    /** The fetched variable schema (if successful) */
+    schema?: VariableSchema;
+    /** Error message (if failed) */
+    error?: string;
+    /** Whether the schema was loaded from cache */
+    fromCache?: boolean;
+}
+/** Default cache TTL for variable data */
+export declare const DEFAULT_VARIABLE_CACHE_TTL: number;
+/**
+ * Replaces {workflowId} and {nodeId} placeholders in URL template.
+ *
+ * @param template - The URL template string
+ * @param context - The variable context with workflowId and nodeId
+ * @returns The resolved URL with placeholders replaced
+ *
+ * @example
+ * ```typescript
+ * const url = "/api/variables/{workflowId}/{nodeId}";
+ * const context = { workflowId: "wf-123", nodeId: "node-456" };
+ * resolveEndpointUrl(url, context);
+ * // Returns "/api/variables/wf-123/node-456"
+ * ```
+ */
+export declare function resolveEndpointUrl(template: string, context: VariableContext): string;
+/**
+ * Fetches variable schema from a backend API endpoint.
+ *
+ * @param workflowId - The workflow ID (optional)
+ * @param nodeId - The node instance ID
+ * @param config - The API variables configuration
+ * @param authProvider - Optional auth provider for auth headers
+ * @returns A promise that resolves to the variable schema result
+ *
+ * @example
+ * ```typescript
+ * const config: ApiVariablesConfig = {
+ *   endpoint: {
+ *     url: "/api/variables/{workflowId}/{nodeId}",
+ *     method: "GET"
+ *   },
+ *   cacheTtl: 300000
+ * };
+ *
+ * const result = await fetchVariableSchema("wf-123", "node-456", config);
+ * if (result.success && result.schema) {
+ *   // Use the fetched variable schema
+ * }
+ * ```
+ */
+export declare function fetchVariableSchema(workflowId: string | undefined, nodeId: string, config: ApiVariablesConfig, authProvider?: AuthProvider): Promise<ApiVariableResult>;
+/**
+ * Clears the variable schema cache.
+ * Can optionally clear only entries matching a specific pattern.
+ *
+ * @param pattern - Optional pattern to match cache keys (e.g., workflow ID or node ID)
+ *
+ * @example
+ * ```typescript
+ * // Clear all cache
+ * clearVariableCache();
+ *
+ * // Clear cache for a specific workflow
+ * clearVariableCache("wf-123");
+ *
+ * // Clear cache for a specific node
+ * clearVariableCache("node-456");
+ * ```
+ */
+export declare function clearVariableCache(pattern?: string): void;
+/**
+ * Invalidates a specific variable cache entry.
+ *
+ * @param workflowId - The workflow ID (optional)
+ * @param nodeId - The node instance ID
+ */
+export declare function invalidateVariableCache(workflowId: string | undefined, nodeId: string): void;
+/**
+ * Gets the current cache size (number of entries).
+ *
+ * @returns The number of cached variable schemas
+ */
+export declare function getVariableCacheSize(): number;
+/**
+ * Gets all cache keys currently stored.
+ * Useful for debugging and monitoring.
+ *
+ * @returns Array of cache keys
+ */
+export declare function getVariableCacheKeys(): string[];
+export {};

package/dist/services/apiVariableService.js

@@ -0,0 +1,338 @@
+/**
+ * API Variable Service
+ * Handles fetching template variable schemas from REST endpoints at runtime.
+ * Enables dynamic variable suggestions from backend APIs for template editors.
+ *
+ * @module services/apiVariableService
+ */
+import { getEndpointConfig } from './api.js';
+import { logger } from '../utils/logger.js';
+import { DEFAULT_CACHE_TTL_MS } from '../config/constants.js';
+/**
+ * Variable schema cache with TTL support
+ * Key format: `variables:{workflowId}:{nodeId}`
+ */
+const variableCache = new Map();
+/** Default cache TTL for variable data */
+export const DEFAULT_VARIABLE_CACHE_TTL = DEFAULT_CACHE_TTL_MS;
+/**
+ * Replaces {workflowId} and {nodeId} placeholders in URL template.
+ *
+ * @param template - The URL template string
+ * @param context - The variable context with workflowId and nodeId
+ * @returns The resolved URL with placeholders replaced
+ *
+ * @example
+ * ```typescript
+ * const url = "/api/variables/{workflowId}/{nodeId}";
+ * const context = { workflowId: "wf-123", nodeId: "node-456" };
+ * resolveEndpointUrl(url, context);
+ * // Returns "/api/variables/wf-123/node-456"
+ * ```
+ */
+export function resolveEndpointUrl(template, context) {
+    let resolved = template;
+    // Replace {workflowId}
+    if (context.workflowId) {
+        resolved = resolved.replace(/\{workflowId\}/g, encodeURIComponent(context.workflowId));
+    }
+    // Replace {nodeId}
+    resolved = resolved.replace(/\{nodeId\}/g, encodeURIComponent(context.nodeId));
+    return resolved;
+}
+/**
+ * Generates a cache key for a variable schema based on the context.
+ *
+ * @param workflowId - The workflow ID (optional)
+ * @param nodeId - The node instance ID
+ * @returns A unique cache key string
+ */
+function generateVariableCacheKey(workflowId, nodeId) {
+    return `variables:${workflowId || 'unknown'}:${nodeId}`;
+}
+/**
+ * Checks if a cached variable schema is still valid (not expired).
+ *
+ * @param entry - The cache entry to check
+ * @param ttl - Time-to-live in milliseconds
+ * @returns True if the cache entry is still valid
+ */
+function isCacheValid(entry, ttl = DEFAULT_VARIABLE_CACHE_TTL) {
+    return Date.now() - entry.cachedAt < ttl;
+}
+/**
+ * Resolves template variables in request body.
+ * Recursively processes nested objects and arrays.
+ *
+ * @param body - The request body object
+ * @param context - The variable context
+ * @returns The body with template variables resolved
+ */
+function resolveBodyTemplates(body, context) {
+    const resolved = {};
+    for (const [key, value] of Object.entries(body)) {
+        if (typeof value === 'string') {
+            // Resolve template variables in string values
+            let resolvedValue = value;
+            if (context.workflowId) {
+                resolvedValue = resolvedValue.replace(/\{workflowId\}/g, encodeURIComponent(context.workflowId));
+            }
+            resolvedValue = resolvedValue.replace(/\{nodeId\}/g, encodeURIComponent(context.nodeId));
+            resolved[key] = resolvedValue;
+        }
+        else if (typeof value === 'object' && value !== null && !Array.isArray(value)) {
+            // Recursively resolve nested objects
+            resolved[key] = resolveBodyTemplates(value, context);
+        }
+        else {
+            // Pass through other values as-is
+            resolved[key] = value;
+        }
+    }
+    return resolved;
+}
+/**
+ * Fetches variable schema from a backend API endpoint.
+ *
+ * @param workflowId - The workflow ID (optional)
+ * @param nodeId - The node instance ID
+ * @param config - The API variables configuration
+ * @param authProvider - Optional auth provider for auth headers
+ * @returns A promise that resolves to the variable schema result
+ *
+ * @example
+ * ```typescript
+ * const config: ApiVariablesConfig = {
+ *   endpoint: {
+ *     url: "/api/variables/{workflowId}/{nodeId}",
+ *     method: "GET"
+ *   },
+ *   cacheTtl: 300000
+ * };
+ *
+ * const result = await fetchVariableSchema("wf-123", "node-456", config);
+ * if (result.success && result.schema) {
+ *   // Use the fetched variable schema
+ * }
+ * ```
+ */
+export async function fetchVariableSchema(workflowId, nodeId, config, authProvider) {
+    const endpoint = config.endpoint;
+    const context = { workflowId, nodeId };
+    // Generate cache key
+    const cacheKey = generateVariableCacheKey(workflowId, nodeId);
+    // Check cache first (if caching is enabled)
+    if (endpoint.cacheEnabled !== false) {
+        const cached = variableCache.get(cacheKey);
+        const ttl = config.cacheTtl ?? DEFAULT_VARIABLE_CACHE_TTL;
+        if (cached && isCacheValid(cached, ttl)) {
+            return {
+                success: true,
+                schema: cached.schema,
+                fromCache: true
+            };
+        }
+    }
+    // Resolve the URL with template variables
+    let url = resolveEndpointUrl(endpoint.url, context);
+    // If URL is relative, prepend base URL from endpoint config
+    if (url.startsWith('/')) {
+        const currentConfig = getEndpointConfig();
+        if (currentConfig?.baseUrl) {
+            const baseUrl = currentConfig.baseUrl.replace(/\/$/, '');
+            url = `${baseUrl}${url}`;
+        }
+    }
+    // Prepare request options
+    const method = endpoint.method ?? 'GET';
+    const timeout = endpoint.timeout ?? 30000;
+    const headers = {
+        Accept: 'application/json',
+        'Content-Type': 'application/json',
+        ...endpoint.headers
+    };
+    // Add auth headers from AuthProvider if available
+    if (authProvider) {
+        try {
+            const authHeaders = await authProvider.getAuthHeaders();
+            Object.assign(headers, authHeaders);
+        }
+        catch (error) {
+            logger.warn('Failed to get auth headers:', error);
+        }
+    }
+    // Add auth headers from endpoint config as fallback
+    const currentConfig = getEndpointConfig();
+    if (currentConfig?.auth) {
+        if (currentConfig.auth.type === 'bearer' && currentConfig.auth.token) {
+            headers['Authorization'] = headers['Authorization'] ?? `Bearer ${currentConfig.auth.token}`;
+        }
+        else if (currentConfig.auth.type === 'api_key' && currentConfig.auth.apiKey) {
+            headers['X-API-Key'] = headers['X-API-Key'] ?? currentConfig.auth.apiKey;
+        }
+        else if (currentConfig.auth.type === 'custom' && currentConfig.auth.headers) {
+            Object.assign(headers, currentConfig.auth.headers);
+        }
+    }
+    // Prepare fetch options
+    const fetchOptions = {
+        method,
+        headers,
+        signal: AbortSignal.timeout(timeout)
+    };
+    // Add body for non-GET requests
+    if (method !== 'GET' && endpoint.body) {
+        const resolvedBody = resolveBodyTemplates(endpoint.body, context);
+        fetchOptions.body = JSON.stringify(resolvedBody);
+    }
+    try {
+        const response = await fetch(url, fetchOptions);
+        // Handle 404 as "no variables available"
+        if (response.status === 404) {
+            return {
+                success: true,
+                schema: { variables: {} },
+                fromCache: false
+            };
+        }
+        if (!response.ok) {
+            // Handle authentication errors
+            if (response.status === 401 || response.status === 403) {
+                if (authProvider?.onUnauthorized) {
+                    const refreshed = await authProvider.onUnauthorized();
+                    if (refreshed) {
+                        // Retry with refreshed auth
+                        return fetchVariableSchema(workflowId, nodeId, config, authProvider);
+                    }
+                }
+                return {
+                    success: false,
+                    error: 'Authentication failed'
+                };
+            }
+            const errorText = await response.text();
+            return {
+                success: false,
+                error: `HTTP ${response.status}: ${errorText || response.statusText}`
+            };
+        }
+        const data = await response.json();
+        // The response could be:
+        // 1. Direct VariableSchema: { variables: {...} }
+        // 2. Wrapped in { data: { variables: {...} } }
+        // 3. Wrapped in { schema: { variables: {...} } }
+        // 4. Wrapped in { success: true, data: { variables: {...} } }
+        let schema;
+        if (data.variables && typeof data.variables === 'object') {
+            // Direct VariableSchema
+            schema = data;
+        }
+        else if (data.data?.variables && typeof data.data.variables === 'object') {
+            // Wrapped in { data: ... }
+            schema = data.data;
+        }
+        else if (data.schema?.variables && typeof data.schema.variables === 'object') {
+            // Wrapped in { schema: ... }
+            schema = data.schema;
+        }
+        else if (data.success && data.data?.variables) {
+            // Wrapped in { success: true, data: ... }
+            schema = data.data;
+        }
+        if (!schema) {
+            return {
+                success: false,
+                error: 'Invalid variable schema format received from endpoint'
+            };
+        }
+        // Cache the schema (if caching is enabled)
+        if (endpoint.cacheEnabled !== false) {
+            variableCache.set(cacheKey, {
+                schema,
+                cachedAt: Date.now(),
+                cacheKey
+            });
+        }
+        return {
+            success: true,
+            schema,
+            fromCache: false
+        };
+    }
+    catch (error) {
+        // Handle specific error types
+        if (error instanceof Error) {
+            if (error.name === 'AbortError' || error.name === 'TimeoutError') {
+                return {
+                    success: false,
+                    error: `Request timed out after ${timeout}ms`
+                };
+            }
+            return {
+                success: false,
+                error: error.message
+            };
+        }
+        return {
+            success: false,
+            error: 'Unknown error occurred while fetching variable schema'
+        };
+    }
+}
+/**
+ * Clears the variable schema cache.
+ * Can optionally clear only entries matching a specific pattern.
+ *
+ * @param pattern - Optional pattern to match cache keys (e.g., workflow ID or node ID)
+ *
+ * @example
+ * ```typescript
+ * // Clear all cache
+ * clearVariableCache();
+ *
+ * // Clear cache for a specific workflow
+ * clearVariableCache("wf-123");
+ *
+ * // Clear cache for a specific node
+ * clearVariableCache("node-456");
+ * ```
+ */
+export function clearVariableCache(pattern) {
+    if (!pattern) {
+        variableCache.clear();
+        return;
+    }
+    // Clear matching entries
+    for (const key of variableCache.keys()) {
+        if (key.includes(pattern)) {
+            variableCache.delete(key);
+        }
+    }
+}
+/**
+ * Invalidates a specific variable cache entry.
+ *
+ * @param workflowId - The workflow ID (optional)
+ * @param nodeId - The node instance ID
+ */
+export function invalidateVariableCache(workflowId, nodeId) {
+    const cacheKey = generateVariableCacheKey(workflowId, nodeId);
+    variableCache.delete(cacheKey);
+}
+/**
+ * Gets the current cache size (number of entries).
+ *
+ * @returns The number of cached variable schemas
+ */
+export function getVariableCacheSize() {
+    return variableCache.size;
+}
+/**
+ * Gets all cache keys currently stored.
+ * Useful for debugging and monitoring.
+ *
+ * @returns Array of cache keys
+ */
+export function getVariableCacheKeys() {
+    return Array.from(variableCache.keys());
+}