@d34dman/flowdrop 0.0.15 → 0.0.17

package/dist/types/auth.js

@@ -0,0 +1,244 @@
+/**
+ * Authentication Provider Types for FlowDrop
+ *
+ * Provides interfaces and implementations for authentication in FlowDrop.
+ * AuthProvider is passed at mount time and cannot be changed without remounting.
+ *
+ * @module types/auth
+ */
+/**
+ * Static authentication provider
+ *
+ * Provides authentication using static credentials configured at instantiation.
+ * Suitable for simple use cases where tokens don't change during the session.
+ * Also used internally for backward compatibility with existing endpointConfig.auth.
+ *
+ * @example
+ * ```typescript
+ * // Bearer token authentication
+ * const authProvider = new StaticAuthProvider({
+ *   type: "bearer",
+ *   token: "your-jwt-token"
+ * });
+ *
+ * // API key authentication
+ * const authProvider = new StaticAuthProvider({
+ *   type: "api_key",
+ *   apiKey: "your-api-key"
+ * });
+ *
+ * // Custom headers
+ * const authProvider = new StaticAuthProvider({
+ *   type: "custom",
+ *   headers: {
+ *     "X-Custom-Auth": "value",
+ *     "X-Tenant-ID": "tenant123"
+ *   }
+ * });
+ * ```
+ */
+export class StaticAuthProvider {
+    /** Cached authentication headers */
+    headers;
+    /**
+     * Create a new StaticAuthProvider
+     *
+     * @param config - Static authentication configuration
+     */
+    constructor(config) {
+        this.headers = {};
+        switch (config.type) {
+            case 'bearer':
+                if (config.token) {
+                    this.headers['Authorization'] = `Bearer ${config.token}`;
+                }
+                break;
+            case 'api_key':
+                if (config.apiKey) {
+                    this.headers['X-API-Key'] = config.apiKey;
+                }
+                break;
+            case 'custom':
+                if (config.headers) {
+                    this.headers = { ...config.headers };
+                }
+                break;
+            case 'none':
+            default:
+                // No headers needed
+                break;
+        }
+    }
+    /**
+     * Get authentication headers
+     *
+     * Returns the statically configured headers.
+     *
+     * @returns Promise resolving to authentication headers
+     */
+    async getAuthHeaders() {
+        return this.headers;
+    }
+    /**
+     * Check if authenticated
+     *
+     * Returns true if any auth headers are configured.
+     *
+     * @returns true if headers are configured
+     */
+    isAuthenticated() {
+        return Object.keys(this.headers).length > 0;
+    }
+    /**
+     * Handle unauthorized response
+     *
+     * Static provider cannot refresh tokens, so always returns false.
+     *
+     * @returns Promise resolving to false (cannot refresh)
+     */
+    async onUnauthorized() {
+        // Static provider cannot refresh tokens
+        return false;
+    }
+    /**
+     * Handle forbidden response
+     *
+     * Static provider has no special handling for 403.
+     */
+    async onForbidden() {
+        // No special handling for static provider
+    }
+}
+/**
+ * Callback-based authentication provider
+ *
+ * Provides authentication using callback functions for dynamic token retrieval.
+ * Ideal for enterprise integrations where the parent application manages auth.
+ *
+ * @example
+ * ```typescript
+ * const authProvider = new CallbackAuthProvider({
+ *   getToken: async () => {
+ *     return authService.getAccessToken();
+ *   },
+ *   onUnauthorized: async () => {
+ *     const refreshed = await authService.refreshToken();
+ *     return refreshed;
+ *   },
+ *   onForbidden: async () => {
+ *     showError("You don't have permission to access this resource");
+ *   }
+ * });
+ * ```
+ */
+export class CallbackAuthProvider {
+    /** Function to get the current token */
+    getToken;
+    /** Optional unauthorized callback */
+    onUnauthorizedCallback;
+    /** Optional forbidden callback */
+    onForbiddenCallback;
+    /**
+     * Create a new CallbackAuthProvider
+     *
+     * @param config - Callback authentication configuration
+     */
+    constructor(config) {
+        this.getToken = config.getToken;
+        this.onUnauthorizedCallback = config.onUnauthorized;
+        this.onForbiddenCallback = config.onForbidden;
+    }
+    /**
+     * Get authentication headers
+     *
+     * Calls the getToken callback to retrieve the current token.
+     *
+     * @returns Promise resolving to authentication headers
+     */
+    async getAuthHeaders() {
+        const token = await this.getToken();
+        if (token) {
+            return { Authorization: `Bearer ${token}` };
+        }
+        return {};
+    }
+    /**
+     * Check if authenticated
+     *
+     * For callback-based auth, we assume authenticated if getToken exists.
+     * The actual token validity is checked when making requests.
+     *
+     * @returns true (assumes authenticated, actual check happens on request)
+     */
+    isAuthenticated() {
+        // For callback-based auth, we assume authenticated if getToken exists
+        // The actual token validity is checked when making requests
+        return true;
+    }
+    /**
+     * Handle unauthorized response
+     *
+     * Calls the onUnauthorized callback if provided.
+     *
+     * @returns Promise resolving to true if auth was refreshed
+     */
+    async onUnauthorized() {
+        if (this.onUnauthorizedCallback) {
+            return this.onUnauthorizedCallback();
+        }
+        return false;
+    }
+    /**
+     * Handle forbidden response
+     *
+     * Calls the onForbidden callback if provided.
+     */
+    async onForbidden() {
+        if (this.onForbiddenCallback) {
+            await this.onForbiddenCallback();
+        }
+    }
+}
+/**
+ * No-op authentication provider
+ *
+ * Used when no authentication is required.
+ * Provides empty headers and always returns not authenticated.
+ */
+export class NoAuthProvider {
+    /**
+     * Get authentication headers
+     *
+     * Returns empty headers (no auth).
+     *
+     * @returns Promise resolving to empty object
+     */
+    async getAuthHeaders() {
+        return {};
+    }
+    /**
+     * Check if authenticated
+     *
+     * Always returns false (no auth configured).
+     *
+     * @returns false
+     */
+    isAuthenticated() {
+        return false;
+    }
+}
+/**
+ * Create an AuthProvider from legacy endpointConfig.auth configuration
+ *
+ * Used internally for backward compatibility with existing code that uses
+ * the old auth configuration format in EndpointConfig.
+ *
+ * @param authConfig - Legacy auth configuration from EndpointConfig
+ * @returns AuthProvider instance
+ */
+export function createAuthProviderFromLegacyConfig(authConfig) {
+    if (!authConfig || authConfig.type === 'none') {
+        return new NoAuthProvider();
+    }
+    return new StaticAuthProvider(authConfig);
+}

package/dist/types/events.d.ts

@@ -0,0 +1,163 @@
+/**
+ * Event Handler Types for FlowDrop
+ *
+ * Defines high-level event handlers for enterprise integration.
+ * These events allow parent applications to react to workflow lifecycle events.
+ *
+ * @module types/events
+ */
+import type { Workflow } from './index.js';
+/**
+ * Types of workflow changes
+ *
+ * Used to identify what kind of change triggered the onWorkflowChange event.
+ */
+export type WorkflowChangeType = 'node_add' | 'node_remove' | 'node_move' | 'node_config' | 'edge_add' | 'edge_remove' | 'metadata' | 'name' | 'description';
+/**
+ * High-level event handlers for enterprise integration
+ *
+ * These event handlers allow parent applications to hook into FlowDrop's
+ * workflow lifecycle. All handlers are optional.
+ *
+ * @example
+ * ```typescript
+ * const eventHandlers: FlowDropEventHandlers = {
+ *   onWorkflowChange: (workflow, changeType) => {
+ *     console.log(`Workflow changed: ${changeType}`);
+ *   },
+ *   onDirtyStateChange: (isDirty) => {
+ *     updateSaveButtonState(isDirty);
+ *   },
+ *   onAfterSave: async (workflow) => {
+ *     showSuccess("Workflow saved!");
+ *   }
+ * };
+ * ```
+ */
+export interface FlowDropEventHandlers {
+    /**
+     * Called when workflow changes (any modification)
+     *
+     * Triggered after nodes are added/removed/moved, edges are added/removed,
+     * or node configurations are changed.
+     *
+     * @param workflow - The updated workflow
+     * @param changeType - The type of change that occurred
+     */
+    onWorkflowChange?: (workflow: Workflow, changeType: WorkflowChangeType) => void;
+    /**
+     * Called when dirty state changes
+     *
+     * Triggered when the workflow transitions between saved and unsaved states.
+     * Useful for updating UI indicators or enabling/disabling save buttons.
+     *
+     * @param isDirty - true if there are unsaved changes
+     */
+    onDirtyStateChange?: (isDirty: boolean) => void;
+    /**
+     * Called before save - return false to cancel
+     *
+     * Allows the parent application to validate or confirm before saving.
+     * If this returns false, the save operation is cancelled.
+     *
+     * @param workflow - The workflow about to be saved
+     * @returns Promise resolving to false to cancel, true/void to proceed
+     */
+    onBeforeSave?: (workflow: Workflow) => Promise<boolean | void>;
+    /**
+     * Called after successful save
+     *
+     * Triggered after the workflow has been successfully saved to the backend.
+     * Useful for showing success notifications or clearing draft storage.
+     *
+     * @param workflow - The saved workflow (may include server-assigned IDs)
+     */
+    onAfterSave?: (workflow: Workflow) => Promise<void>;
+    /**
+     * Called when save fails
+     *
+     * Triggered when the save operation fails due to API error.
+     * Useful for showing error notifications or logging.
+     *
+     * @param error - The error that occurred
+     * @param workflow - The workflow that failed to save
+     */
+    onSaveError?: (error: Error, workflow: Workflow) => Promise<void>;
+    /**
+     * Called when workflow is loaded
+     *
+     * Triggered after a workflow is loaded and initialized.
+     * This includes both initial load and subsequent loads.
+     *
+     * @param workflow - The loaded workflow
+     */
+    onWorkflowLoad?: (workflow: Workflow) => void;
+    /**
+     * Called before unmount
+     *
+     * Triggered before FlowDrop is destroyed/unmounted.
+     * Allows parent application to save drafts or perform cleanup.
+     *
+     * @param workflow - The current workflow state
+     * @param isDirty - true if there are unsaved changes
+     */
+    onBeforeUnmount?: (workflow: Workflow, isDirty: boolean) => void;
+    /**
+     * Called on any API error
+     *
+     * Triggered when any API request fails.
+     * Return true to suppress FlowDrop's default error toast.
+     *
+     * @param error - The error that occurred
+     * @param operation - Description of the operation that failed (e.g., "save", "load", "fetchNodes")
+     * @returns true to suppress default error handling, false/void to show default toast
+     */
+    onApiError?: (error: Error, operation: string) => boolean | void;
+}
+/**
+ * Feature flags for FlowDrop
+ *
+ * Controls optional features and behaviors.
+ * All features have sensible defaults.
+ */
+export interface FlowDropFeatures {
+    /**
+     * Save drafts to localStorage automatically
+     *
+     * When enabled, FlowDrop will periodically save the current workflow
+     * to localStorage as a draft. This helps prevent data loss.
+     *
+     * @default true
+     */
+    autoSaveDraft?: boolean;
+    /**
+     * Auto-save interval in milliseconds
+     *
+     * How often to save drafts to localStorage when autoSaveDraft is enabled.
+     *
+     * @default 30000 (30 seconds)
+     */
+    autoSaveDraftInterval?: number;
+    /**
+     * Show toast notifications
+     *
+     * When enabled, FlowDrop will show toast notifications for
+     * success, error, and loading states.
+     *
+     * @default true
+     */
+    showToasts?: boolean;
+}
+/**
+ * Default feature values
+ *
+ * Used when features are not explicitly configured.
+ */
+export declare const DEFAULT_FEATURES: Required<FlowDropFeatures>;
+/**
+ * Merge user-provided features with defaults
+ *
+ * @param features - User-provided feature configuration
+ * @returns Complete feature configuration with defaults applied
+ */
+export declare function mergeFeatures(features?: FlowDropFeatures): Required<FlowDropFeatures>;

package/dist/types/events.js

@@ -0,0 +1,30 @@
+/**
+ * Event Handler Types for FlowDrop
+ *
+ * Defines high-level event handlers for enterprise integration.
+ * These events allow parent applications to react to workflow lifecycle events.
+ *
+ * @module types/events
+ */
+/**
+ * Default feature values
+ *
+ * Used when features are not explicitly configured.
+ */
+export const DEFAULT_FEATURES = {
+    autoSaveDraft: true,
+    autoSaveDraftInterval: 30000,
+    showToasts: true
+};
+/**
+ * Merge user-provided features with defaults
+ *
+ * @param features - User-provided feature configuration
+ * @returns Complete feature configuration with defaults applied
+ */
+export function mergeFeatures(features) {
+    return {
+        ...DEFAULT_FEATURES,
+        ...features
+    };
+}

package/dist/types/index.d.ts

@@ -71,9 +71,27 @@ export interface NodePort {
     defaultValue?: unknown;
 }
 /**
- * Node types for explicit component rendering
- */
-export type NodeType = 'note' | 'simple' | 'square' | 'tool' | 'gateway' | 'default';
+ * Built-in node types for explicit component rendering.
+ * These are the node types that ship with FlowDrop.
+ */
+export type BuiltinNodeType = 'note' | 'simple' | 'square' | 'tool' | 'gateway' | 'default';
+/**
+ * Node type for component rendering.
+ * Includes built-in types and allows custom registered types.
+ *
+ * Built-in types: note, simple, square, tool, gateway, default
+ * Custom types: Any string registered via nodeComponentRegistry
+ *
+ * @example
+ * ```typescript
+ * // Built-in type
+ * const type: NodeType = "simple";
+ *
+ * // Custom registered type
+ * const customType: NodeType = "mylib:fancy";
+ * ```
+ */
+export type NodeType = BuiltinNodeType | (string & Record<never, never>);
 /**
  * Node configuration metadata
  */
@@ -85,6 +103,7 @@ export interface NodeMetadata {
      * Array of supported node types that this node can be rendered as.
      * If not specified, defaults to the single 'type' field or 'default'.
      * This allows nodes to support multiple rendering modes (e.g., both 'simple' and 'default').
+     * Can include both built-in types and custom registered types.
      */
     supportedTypes?: NodeType[];
     description: string;
@@ -252,6 +271,14 @@ export interface WorkflowNode extends Node {
         executionInfo?: NodeExecutionInfo;
     };
 }
+/**
+ * Edge category types based on source port data type
+ * Used for visual styling of edges on the canvas
+ * - trigger: For control flow connections (dataType: "trigger")
+ * - tool: Dashed amber line for tool connections (dataType: "tool")
+ * - data: Normal gray line for all other data connections
+ */
+export type EdgeCategory = 'trigger' | 'tool' | 'data';
 /**
  * Extended edge type for workflows
  */
@@ -267,6 +294,14 @@ export interface WorkflowEdge extends Edge {
     data?: {
         label?: string;
         condition?: string;
+        /** Edge metadata for API and persistence */
+        metadata?: {
+            /** Edge type for styling ("tool" or "data") */
+            edgeType?: EdgeCategory;
+            /** Data type of the source output port (e.g., "tool", "string", "number") */
+            sourcePortDataType?: string;
+        };
+        /** @deprecated Use metadata.edgeType instead - kept for backward compatibility */
         isToolConnection?: boolean;
         targetNodeType?: string;
         targetCategory?: string;

package/dist/utils/nodeTypes.d.ts

@@ -1,57 +1,112 @@
 /**
  * Node type utilities for FlowDrop
- * Handles dynamic node type resolution based on NodeMetadata
+ * Handles dynamic node type resolution based on NodeMetadata.
+ *
+ * This module provides utilities for:
+ * - Resolving which node type to use based on metadata and config
+ * - Getting available node types for a given metadata
+ * - Creating config schema properties for node type selection
+ *
+ * Works with both built-in types and custom registered types.
  */
 import type { NodeType, NodeMetadata } from '../types/index.js';
 /**
- * Gets the SvelteFlow component name for a given NodeType
+ * Gets the SvelteFlow component name for a given NodeType.
+ * Supports both built-in types and registered custom types.
+ *
+ * @param nodeType - The node type identifier
+ * @returns The component name to use
  */
-export declare function getComponentNameForNodeType(nodeType: NodeType): string;
+export declare function getComponentNameForNodeType(nodeType: NodeType | string): string;
 /**
- * Gets the available node types for a given NodeMetadata
+ * Gets the available node types for a given NodeMetadata.
  * Priority: supportedTypes > type > "default"
+ *
+ * @param metadata - The node metadata
+ * @returns Array of available node type identifiers
  */
-export declare function getAvailableNodeTypes(metadata: NodeMetadata): NodeType[];
+export declare function getAvailableNodeTypes(metadata: NodeMetadata): (NodeType | string)[];
 /**
- * Gets the primary (default) node type for a given NodeMetadata
- * This is used when no specific type is configured by the user
+ * Gets the primary (default) node type for a given NodeMetadata.
+ * This is used when no specific type is configured by the user.
+ *
+ * @param metadata - The node metadata
+ * @returns The primary node type
  */
-export declare function getPrimaryNodeType(metadata: NodeMetadata): NodeType;
+export declare function getPrimaryNodeType(metadata: NodeMetadata): NodeType | string;
 /**
- * Determines the appropriate node type based on configuration and metadata
+ * Determines the appropriate node type based on configuration and metadata.
+ *
  * Priority:
  * 1. configNodeType (if valid for this metadata)
  * 2. metadata.type (if valid)
  * 3. First supportedType
  * 4. "default"
+ *
+ * @param metadata - The node metadata
+ * @param configNodeType - Optional type from user config
+ * @returns The resolved node type
  */
-export declare function resolveNodeType(metadata: NodeMetadata, configNodeType?: string): NodeType;
+export declare function resolveNodeType(metadata: NodeMetadata, configNodeType?: string): NodeType | string;
 /**
- * Gets the SvelteFlow component name for resolved node type
- * This replaces the old mapNodeType function
+ * Gets the SvelteFlow component name for resolved node type.
+ * This is the main function used by UniversalNode to determine which component to render.
+ *
+ * @param metadata - The node metadata
+ * @param configNodeType - Optional type from user config
+ * @returns The component name to use
  */
 export declare function resolveComponentName(metadata: NodeMetadata, configNodeType?: string): string;
 /**
- * Validates if a node type is supported by the given metadata
+ * Validates if a node type is supported by the given metadata.
+ *
+ * @param metadata - The node metadata
+ * @param nodeType - The type to check
+ * @returns true if the type is supported
  */
-export declare function isNodeTypeSupported(metadata: NodeMetadata, nodeType: NodeType): boolean;
+export declare function isNodeTypeSupported(metadata: NodeMetadata, nodeType: NodeType | string): boolean;
 /**
- * Gets enum options for node type configuration
- * Used in config schemas to show available options
+ * Gets enum options for node type configuration.
+ * Used in config schemas to show available options.
+ *
+ * This function combines:
+ * - Types specified in metadata.supportedTypes
+ * - Registered custom types (optionally filtered)
+ *
+ * @param metadata - The node metadata
+ * @param includeCustomTypes - Whether to include registered custom types
+ * @returns Object with enum values and display names
  */
-export declare function getNodeTypeEnumOptions(metadata: NodeMetadata): {
+export declare function getNodeTypeEnumOptions(metadata: NodeMetadata, includeCustomTypes?: boolean): {
     enum: string[];
     enumNames: string[];
 };
 /**
- * Creates a nodeType config property that respects supportedTypes
- * This replaces hardcoded enum values in config schemas
+ * Creates a nodeType config property that respects supportedTypes.
+ * This replaces hardcoded enum values in config schemas.
+ *
+ * @param metadata - The node metadata
+ * @param defaultType - Optional default type override
+ * @returns Config schema property object
  */
-export declare function createNodeTypeConfigProperty(metadata: NodeMetadata, defaultType?: NodeType): {
+export declare function createNodeTypeConfigProperty(metadata: NodeMetadata, defaultType?: NodeType | string): {
     type: "string";
     title: string;
     description: string;
-    default: NodeType;
+    default: string;
     enum: string[];
     enumNames: string[];
 };
+/**
+ * Check if a type string represents a valid registered or built-in type.
+ *
+ * @param type - The type to check
+ * @returns true if the type is valid
+ */
+export declare function isValidNodeType(type: string): boolean;
+/**
+ * Get all available node types (built-in + registered).
+ *
+ * @returns Array of all valid node type identifiers
+ */
+export declare function getAllNodeTypes(): string[];