@flowdrop/flowdrop 1.0.0

package/dist/svelte-app.js

@@ -0,0 +1,295 @@
+/**
+ * Svelte App Wrapper for Framework Integration
+ *
+ * Provides mount/unmount functions for integrating FlowDrop into any web application.
+ * Particularly useful for integration with vanilla JS, Drupal, WordPress, or other frameworks.
+ *
+ * @module svelte-app
+ */
+import { mount, unmount } from 'svelte';
+import WorkflowEditor from './components/WorkflowEditor.svelte';
+import App from './components/App.svelte';
+import { workflowFormatRegistry } from './registry/workflowFormatRegistry.js';
+import './registry/builtinFormats.js';
+import { initializePortCompatibility } from './utils/connections.js';
+import { DEFAULT_PORT_CONFIG } from './config/defaultPortConfig.js';
+import { fetchPortConfig } from './services/portConfigApi.js';
+import { fetchCategories } from './services/categoriesApi.js';
+import { initializeCategories } from './stores/categoriesStore.svelte.js';
+import { isDirty, markAsSaved, getWorkflow as getWorkflowFromStore, setOnDirtyStateChange, setOnWorkflowChange } from './stores/workflowStore.svelte.js';
+import { DraftAutoSaveManager, getDraftStorageKey } from './services/draftStorage.js';
+import { mergeFeatures } from './types/events.js';
+import { initializeSettings } from './stores/settingsStore.svelte.js';
+import { logger } from './utils/logger.js';
+import { globalSaveWorkflow, globalExportWorkflow } from './services/globalSave.js';
+/**
+ * Mount the full FlowDrop App with navbar, sidebars, and workflow editor
+ *
+ * Use this for a complete workflow editing experience with all UI components.
+ *
+ * @param container - DOM element to mount the app into
+ * @param options - Configuration options for the app
+ * @returns Promise resolving to a MountedFlowDropApp instance
+ *
+ * @example
+ * ```typescript
+ * const app = await mountFlowDropApp(document.getElementById("editor"), {
+ *   workflow: myWorkflow,
+ *   endpointConfig: createEndpointConfig("/api/flowdrop"),
+ *   authProvider: new CallbackAuthProvider({
+ *     getToken: () => authService.getAccessToken()
+ *   }),
+ *   eventHandlers: {
+ *     onDirtyStateChange: (isDirty) => updateSaveButton(isDirty),
+ *     onAfterSave: () => showSuccess("Saved!")
+ *   }
+ * });
+ * ```
+ */
+export async function mountFlowDropApp(container, options = {}) {
+    const { workflow, nodes, endpointConfig, portConfig, categories, height = '100vh', width = '100%', showNavbar = false, disableSidebar, lockWorkflow, readOnly, nodeStatuses, pipelineId, navbarTitle, navbarActions, showSettings, authProvider, eventHandlers, features: userFeatures, settings: initialSettings, draftStorageKey: customDraftKey, formatAdapters } = options;
+    // Register custom format adapters before mounting
+    if (formatAdapters) {
+        for (const adapter of formatAdapters) {
+            workflowFormatRegistry.register(adapter);
+        }
+    }
+    // Merge features with defaults
+    const features = mergeFeatures(userFeatures);
+    // Apply initial settings overrides and initialize theme
+    await initializeSettings({
+        defaults: initialSettings
+    });
+    // Create endpoint configuration
+    let config;
+    if (endpointConfig) {
+        // Merge with default configuration to ensure all required endpoints are present
+        const { defaultEndpointConfig } = await import('./config/endpoints.js');
+        config = {
+            ...defaultEndpointConfig,
+            ...endpointConfig,
+            endpoints: {
+                ...defaultEndpointConfig.endpoints,
+                ...endpointConfig.endpoints
+            }
+        };
+    }
+    else {
+        // Use default configuration if none provided
+        const { defaultEndpointConfig } = await import('./config/endpoints.js');
+        config = defaultEndpointConfig;
+    }
+    // Initialize port configuration
+    let finalPortConfig = portConfig;
+    if (!finalPortConfig && config) {
+        // Try to fetch port configuration from API
+        try {
+            finalPortConfig = await fetchPortConfig(config);
+        }
+        catch (error) {
+            logger.warn('Failed to fetch port config from API, using default:', error);
+            finalPortConfig = DEFAULT_PORT_CONFIG;
+        }
+    }
+    else if (!finalPortConfig) {
+        finalPortConfig = DEFAULT_PORT_CONFIG;
+    }
+    initializePortCompatibility(finalPortConfig);
+    // Initialize categories
+    if (categories) {
+        initializeCategories(categories);
+    }
+    else if (config) {
+        try {
+            const fetchedCategories = await fetchCategories(config);
+            initializeCategories(fetchedCategories);
+        }
+        catch (error) {
+            logger.warn('Failed to fetch categories from API, using defaults:', error);
+        }
+    }
+    // Set up event handler callbacks in the store
+    if (eventHandlers?.onDirtyStateChange) {
+        setOnDirtyStateChange(eventHandlers.onDirtyStateChange);
+    }
+    if (eventHandlers?.onWorkflowChange) {
+        setOnWorkflowChange(eventHandlers.onWorkflowChange);
+    }
+    // Create the Svelte App component with configuration
+    const svelteApp = mount(App, {
+        target: container,
+        props: {
+            workflow,
+            nodes,
+            height,
+            width,
+            showNavbar,
+            disableSidebar,
+            lockWorkflow,
+            readOnly,
+            nodeStatuses,
+            pipelineId,
+            navbarTitle,
+            navbarActions,
+            showSettings,
+            endpointConfig: config,
+            authProvider,
+            eventHandlers,
+            features
+        }
+    });
+    // Set up draft auto-save manager
+    let draftManager = null;
+    if (features.autoSaveDraft) {
+        const storageKey = getDraftStorageKey(workflow?.id, customDraftKey);
+        draftManager = new DraftAutoSaveManager({
+            storageKey,
+            interval: features.autoSaveDraftInterval,
+            enabled: features.autoSaveDraft,
+            getWorkflow: getWorkflowFromStore,
+            isDirty
+        });
+        draftManager.start();
+    }
+    // Store state for cleanup
+    const state = {
+        svelteApp,
+        draftManager,
+        eventHandlers: eventHandlers ?? null
+    };
+    // Create the mounted app interface
+    const mountedApp = {
+        destroy: () => {
+            // Call onBeforeUnmount if provided
+            if (state.eventHandlers?.onBeforeUnmount) {
+                const currentWorkflow = getWorkflowFromStore();
+                if (currentWorkflow) {
+                    state.eventHandlers.onBeforeUnmount(currentWorkflow, isDirty());
+                }
+            }
+            // Stop draft manager
+            if (state.draftManager) {
+                // Save one final draft if dirty
+                if (isDirty()) {
+                    state.draftManager.forceSave();
+                }
+                state.draftManager.stop();
+            }
+            // Clear event callbacks
+            setOnDirtyStateChange(null);
+            setOnWorkflowChange(null);
+            // Unmount Svelte app
+            unmount(state.svelteApp);
+        },
+        isDirty: () => isDirty(),
+        markAsSaved: () => {
+            markAsSaved();
+            // Also update draft manager
+            if (state.draftManager) {
+                state.draftManager.markAsSaved();
+            }
+        },
+        getWorkflow: () => getWorkflowFromStore(),
+        save: async () => {
+            await globalSaveWorkflow();
+        },
+        export: () => {
+            globalExportWorkflow();
+        }
+    };
+    return mountedApp;
+}
+/**
+ * Mount the WorkflowEditor component in a container
+ *
+ * Simpler alternative to mountFlowDropApp - only mounts the editor without navbar.
+ *
+ * @param container - DOM element to mount the editor into
+ * @param options - Configuration options
+ * @returns Promise resolving to a MountedFlowDropApp instance
+ */
+export async function mountWorkflowEditor(container, options = {}) {
+    const { nodes = [], endpointConfig, portConfig, categories } = options;
+    // Create endpoint configuration
+    let config;
+    if (endpointConfig) {
+        // Merge with default configuration to ensure all required endpoints are present
+        const { defaultEndpointConfig } = await import('./config/endpoints.js');
+        config = {
+            ...defaultEndpointConfig,
+            ...endpointConfig,
+            endpoints: {
+                ...defaultEndpointConfig.endpoints,
+                ...endpointConfig.endpoints
+            }
+        };
+    }
+    else {
+        // Use default configuration if none provided
+        const { defaultEndpointConfig } = await import('./config/endpoints.js');
+        config = defaultEndpointConfig;
+    }
+    // Initialize port configuration
+    let finalPortConfig = portConfig;
+    if (!finalPortConfig && config) {
+        // Try to fetch port configuration from API
+        try {
+            finalPortConfig = await fetchPortConfig(config);
+        }
+        catch (error) {
+            logger.warn('Failed to fetch port config from API, using default:', error);
+            finalPortConfig = DEFAULT_PORT_CONFIG;
+        }
+    }
+    else if (!finalPortConfig) {
+        finalPortConfig = DEFAULT_PORT_CONFIG;
+    }
+    initializePortCompatibility(finalPortConfig);
+    // Initialize categories
+    if (categories) {
+        initializeCategories(categories);
+    }
+    else if (config) {
+        try {
+            const fetchedCategories = await fetchCategories(config);
+            initializeCategories(fetchedCategories);
+        }
+        catch (error) {
+            logger.warn('Failed to fetch categories from API, using defaults:', error);
+        }
+    }
+    // Create the Svelte component
+    const svelteApp = mount(WorkflowEditor, {
+        target: container,
+        props: {
+            nodes,
+            endpointConfig: config
+        }
+    });
+    // Create the mounted app interface (simpler version)
+    const mountedApp = {
+        destroy: () => {
+            unmount(svelteApp);
+        },
+        isDirty: () => isDirty(),
+        markAsSaved: () => markAsSaved(),
+        getWorkflow: () => getWorkflowFromStore(),
+        save: async () => {
+            await globalSaveWorkflow();
+        },
+        export: () => {
+            globalExportWorkflow();
+        }
+    };
+    return mountedApp;
+}
+/**
+ * Unmount a FlowDrop app
+ *
+ * @param app - The mounted app to unmount
+ */
+export function unmountFlowDropApp(app) {
+    if (app && typeof app.destroy === 'function') {
+        app.destroy();
+    }
+}

package/dist/types/agentspec.d.ts

@@ -0,0 +1,318 @@
+/**
+ * Open Agent Specification (Agent Spec) TypeScript Types
+ *
+ * Type definitions mirroring Oracle's Open Agent Spec format.
+ * Used for bidirectional conversion between FlowDrop and Agent Spec.
+ *
+ * @see https://github.com/oracle/agent-spec
+ * @see https://oracle.github.io/agent-spec/
+ */
+/** Agent Spec node component_type discriminator values */
+export type AgentSpecNodeComponentType = 'start_node' | 'end_node' | 'llm_node' | 'api_node' | 'agent_node' | 'flow_node' | 'map_node' | 'branching_node' | 'tool_node';
+/** Agent Spec tool component_type discriminator values */
+export type AgentSpecToolComponentType = 'server_tool' | 'client_tool' | 'remote_tool';
+/** All Agent Spec component_type values */
+export type AgentSpecComponentType = 'agent' | 'flow' | AgentSpecNodeComponentType | AgentSpecToolComponentType | 'llm_config';
+/**
+ * Agent Spec Property — JSON Schema-based input/output definition.
+ *
+ * Uses JSON Schema types and structure for describing data shape.
+ * Placeholder syntax `{{variable_name}}` generates implicit input properties.
+ */
+export interface AgentSpecProperty {
+    /** Property name (used as identifier in edges and templates) */
+    title: string;
+    /** JSON Schema type */
+    type: string;
+    /** Human-readable description */
+    description?: string;
+    /** Default value */
+    default?: unknown;
+    /** Allowed values (JSON Schema enum) */
+    enum?: unknown[];
+    /** Array item schema */
+    items?: AgentSpecProperty;
+    /** Object property schemas */
+    properties?: Record<string, AgentSpecProperty>;
+    /** Required properties (for object types) */
+    required?: string[];
+    /** Additional JSON Schema fields */
+    [key: string]: unknown;
+}
+/** Base interface for all Agent Spec nodes */
+export interface AgentSpecNodeBase {
+    /** Discriminator for node type */
+    component_type: AgentSpecNodeComponentType;
+    /** Node name (used as identifier in edges) */
+    name: string;
+    /** Human-readable description */
+    description?: string;
+    /** Input properties */
+    inputs?: AgentSpecProperty[];
+    /** Output properties */
+    outputs?: AgentSpecProperty[];
+    /** Extension metadata (includes FlowDrop-specific data for round-trip) */
+    metadata?: Record<string, unknown>;
+}
+/** Graph entry point */
+export interface AgentSpecStartNode extends AgentSpecNodeBase {
+    component_type: 'start_node';
+}
+/** Graph exit point */
+export interface AgentSpecEndNode extends AgentSpecNodeBase {
+    component_type: 'end_node';
+}
+/** LLM text generation node */
+export interface AgentSpecLLMNode extends AgentSpecNodeBase {
+    component_type: 'llm_node';
+    /** LLM configuration (inline or $component_ref string) */
+    llm_config?: AgentSpecLLMConfig | string;
+    /** System prompt template (supports {{variable}} syntax) */
+    system_prompt?: string;
+    /** User prompt template (supports {{variable}} syntax) */
+    prompt_template?: string;
+    /** Output JSON Schema for structured output */
+    output_schema?: Record<string, unknown>;
+}
+/** API call node */
+export interface AgentSpecAPINode extends AgentSpecNodeBase {
+    component_type: 'api_node';
+    /** API endpoint URL */
+    endpoint?: string;
+    /** HTTP method */
+    method?: string;
+    /** Request headers */
+    headers?: Record<string, string>;
+    /** Request body template */
+    body?: Record<string, unknown>;
+}
+/** Multi-round agent conversation node */
+export interface AgentSpecAgentNode extends AgentSpecNodeBase {
+    component_type: 'agent_node';
+    /** Agent reference ($component_ref or inline) */
+    agent?: AgentSpecAgent | string;
+}
+/** Nested flow execution node */
+export interface AgentSpecFlowNode extends AgentSpecNodeBase {
+    component_type: 'flow_node';
+    /** Flow reference ($component_ref or inline) */
+    flow?: AgentSpecFlow | string;
+}
+/** Map-reduce operation node */
+export interface AgentSpecMapNode extends AgentSpecNodeBase {
+    component_type: 'map_node';
+    /** Input collection property name */
+    input_collection?: string;
+    /** Output collection property name */
+    output_collection?: string;
+    /** Flow or node to execute per item ($component_ref or inline) */
+    map_flow?: AgentSpecFlow | string;
+}
+/** Conditional routing node */
+export interface AgentSpecBranchingNode extends AgentSpecNodeBase {
+    component_type: 'branching_node';
+    /** Branch definitions with conditions */
+    branches: AgentSpecBranch[];
+}
+/** Tool execution node */
+export interface AgentSpecToolNode extends AgentSpecNodeBase {
+    component_type: 'tool_node';
+    /** Tool reference ($component_ref or inline) */
+    tool?: AgentSpecTool | string;
+}
+/** Union of all Agent Spec node types */
+export type AgentSpecNode = AgentSpecStartNode | AgentSpecEndNode | AgentSpecLLMNode | AgentSpecAPINode | AgentSpecAgentNode | AgentSpecFlowNode | AgentSpecMapNode | AgentSpecBranchingNode | AgentSpecToolNode;
+/** Branch definition for BranchingNode */
+export interface AgentSpecBranch {
+    /** Branch name (used as from_branch in ControlFlowEdge) */
+    name: string;
+    /** Condition expression for this branch */
+    condition?: string;
+    /** Human-readable description */
+    description?: string;
+}
+/**
+ * Control Flow Edge — defines execution order between nodes.
+ *
+ * Multiple control flow connections from the same branch are prohibited.
+ */
+export interface AgentSpecControlFlowEdge {
+    /** Edge name (identifier) */
+    name: string;
+    /** Source node name */
+    from_node: string;
+    /** Target node name */
+    to_node: string;
+    /** Source branch name (null/undefined = default "next" branch) */
+    from_branch?: string | null;
+}
+/**
+ * Data Flow Edge — routes data between node outputs and inputs.
+ *
+ * Maps a specific output property of a source node to a specific
+ * input property of a destination node.
+ */
+export interface AgentSpecDataFlowEdge {
+    /** Edge name (identifier) */
+    name: string;
+    /** Source node name */
+    source_node: string;
+    /** Source output property title */
+    source_output: string;
+    /** Destination node name */
+    destination_node: string;
+    /** Destination input property title */
+    destination_input: string;
+}
+/**
+ * Agent Spec Flow — a directed, potentially cyclic graph of nodes.
+ *
+ * Flows function as "subroutines" encapsulating repeatable processes.
+ * They separate control-flow (execution order) from data-flow (data routing).
+ */
+export interface AgentSpecFlow {
+    component_type: 'flow';
+    /** Flow name */
+    name: string;
+    /** Human-readable description */
+    description?: string;
+    /** Reference to the StartNode name */
+    start_node: string;
+    /** All nodes in the flow */
+    nodes: AgentSpecNode[];
+    /** Execution order edges */
+    control_flow_connections: AgentSpecControlFlowEdge[];
+    /**
+     * Data routing edges.
+     * When null, data flows by matching input/output property names
+     * across connected nodes (name-based variable access).
+     */
+    data_flow_connections?: AgentSpecDataFlowEdge[] | null;
+    /** Extension metadata */
+    metadata?: Record<string, unknown>;
+}
+/** Base interface for Agent Spec tools */
+export interface AgentSpecToolBase {
+    component_type: AgentSpecToolComponentType;
+    /** Tool name */
+    name: string;
+    /** Human-readable description */
+    description?: string;
+    /** Input parameters */
+    inputs?: AgentSpecProperty[];
+    /** Output parameters */
+    outputs?: AgentSpecProperty[];
+    /** Extension metadata */
+    metadata?: Record<string, unknown>;
+}
+/** Tool executed in the same runtime environment */
+export interface AgentSpecServerTool extends AgentSpecToolBase {
+    component_type: 'server_tool';
+    /** Function name or module path */
+    function_name?: string;
+}
+/** Tool executed by the client, results returned to runtime */
+export interface AgentSpecClientTool extends AgentSpecToolBase {
+    component_type: 'client_tool';
+}
+/** Tool triggered via RPC/REST calls */
+export interface AgentSpecRemoteTool extends AgentSpecToolBase {
+    component_type: 'remote_tool';
+    /** Remote endpoint URL */
+    endpoint?: string;
+    /** HTTP method */
+    method?: string;
+    /** Request headers */
+    headers?: Record<string, string>;
+}
+/** Union of all Agent Spec tool types */
+export type AgentSpecTool = AgentSpecServerTool | AgentSpecClientTool | AgentSpecRemoteTool;
+/** LLM model configuration */
+export interface AgentSpecLLMConfig {
+    component_type: 'llm_config';
+    /** Configuration name */
+    name: string;
+    /** Model identifier (e.g., "gpt-4o", "claude-sonnet-4-5-20250929") */
+    model_id: string;
+    /** Provider name (e.g., "openai", "anthropic") */
+    provider?: string;
+    /** API endpoint URL */
+    url?: string;
+    /** Generation parameters (temperature, max_tokens, etc.) */
+    parameters?: Record<string, unknown>;
+    /** Extension metadata */
+    metadata?: Record<string, unknown>;
+}
+/**
+ * Agent Spec Agent — top-level conversational AI system.
+ *
+ * Serves as the entry point and holds shared resources like
+ * tools, memory, and LLM configuration.
+ */
+export interface AgentSpecAgent {
+    component_type: 'agent';
+    /** Agent name */
+    name: string;
+    /** Human-readable description */
+    description?: string;
+    /** Agent inputs */
+    inputs?: AgentSpecProperty[];
+    /** Agent outputs */
+    outputs?: AgentSpecProperty[];
+    /** Available tools (inline or $component_ref strings) */
+    tools?: (AgentSpecTool | string)[];
+    /** LLM configuration (inline or $component_ref string) */
+    llm_config?: AgentSpecLLMConfig | string;
+    /** System prompt template */
+    system_prompt?: string;
+    /** Extension metadata */
+    metadata?: Record<string, unknown>;
+}
+/**
+ * Top-level Agent Spec document.
+ *
+ * Contains a flow and/or agent definition along with shared
+ * tool and LLM configuration declarations.
+ */
+export interface AgentSpecDocument {
+    /** Agent definition */
+    agent?: AgentSpecAgent;
+    /** Flow definition */
+    flow?: AgentSpecFlow;
+    /** Shared tool declarations */
+    tools?: AgentSpecTool[];
+    /** Shared LLM configurations */
+    llm_configs?: AgentSpecLLMConfig[];
+    /** Document-level metadata */
+    metadata?: Record<string, unknown>;
+}
+/** Prefix for component references in Agent Spec */
+export declare const COMPONENT_REF_PREFIX = "$component_ref:";
+/**
+ * Check if a value is a component reference string.
+ *
+ * @example
+ * ```typescript
+ * isComponentRef("$component_ref:my_tool") // true
+ * isComponentRef("just a string") // false
+ * ```
+ */
+export declare function isComponentRef(value: unknown): value is string;
+/**
+ * Extract the component ID from a component reference string.
+ *
+ * @example
+ * ```typescript
+ * extractComponentRefId("$component_ref:my_tool") // "my_tool"
+ * ```
+ */
+export declare function extractComponentRefId(ref: string): string;
+/**
+ * Create a component reference string.
+ *
+ * @example
+ * ```typescript
+ * createComponentRef("my_tool") // "$component_ref:my_tool"
+ * ```
+ */
+export declare function createComponentRef(componentId: string): string;

package/dist/types/agentspec.js

@@ -0,0 +1,48 @@
+/**
+ * Open Agent Specification (Agent Spec) TypeScript Types
+ *
+ * Type definitions mirroring Oracle's Open Agent Spec format.
+ * Used for bidirectional conversion between FlowDrop and Agent Spec.
+ *
+ * @see https://github.com/oracle/agent-spec
+ * @see https://oracle.github.io/agent-spec/
+ */
+// ============================================================================
+// Component Reference
+// ============================================================================
+/** Prefix for component references in Agent Spec */
+export const COMPONENT_REF_PREFIX = '$component_ref:';
+/**
+ * Check if a value is a component reference string.
+ *
+ * @example
+ * ```typescript
+ * isComponentRef("$component_ref:my_tool") // true
+ * isComponentRef("just a string") // false
+ * ```
+ */
+export function isComponentRef(value) {
+    return typeof value === 'string' && value.startsWith(COMPONENT_REF_PREFIX);
+}
+/**
+ * Extract the component ID from a component reference string.
+ *
+ * @example
+ * ```typescript
+ * extractComponentRefId("$component_ref:my_tool") // "my_tool"
+ * ```
+ */
+export function extractComponentRefId(ref) {
+    return ref.slice(COMPONENT_REF_PREFIX.length);
+}
+/**
+ * Create a component reference string.
+ *
+ * @example
+ * ```typescript
+ * createComponentRef("my_tool") // "$component_ref:my_tool"
+ * ```
+ */
+export function createComponentRef(componentId) {
+    return `${COMPONENT_REF_PREFIX}${componentId}`;
+}