@flowdrop/flowdrop/core (or the main @flowdrop/flowdrop entry point).
Workflow
interface Workflow {
id: string;
name: string;
description?: string;
nodes: WorkflowNode[];
edges: WorkflowEdge[];
metadata: {
/** Workflow schema format version — identifies the document format, not the workflow's own revision. */
schemaVersion: string;
createdAt: string;
updatedAt: string;
author?: string;
tags?: string[];
versionId?: string;
updateNumber?: number;
/** Workflow format. Determines sidebar filtering and export behavior. */
format?: WorkflowFormat;
};
/** Custom workflow-level configuration values, populated via workflowSettingsSchema. */
config?: Record<string, unknown>;
}
metadata is required. The format-version field lives at metadata.schemaVersion and identifies the document format — it is not the workflow’s own revision number.
WorkflowNode
interface WorkflowNode {
id: string;
type: string;
position: { x: number; y: number };
data: {
label: string;
config?: Record<string, unknown>;
metadata?: NodeMetadata;
branches?: Branch[];
};
}
WorkflowEdge
interface WorkflowEdge {
id: string;
source: string;
sourceHandle?: string;
target: string;
targetHandle?: string;
data?: {
label?: string;
condition?: string;
metadata?: {
edgeType?: EdgeCategory;
sourcePortDataType?: string;
};
};
}
NodeMetadata
interface NodeMetadata {
id: string;
name: string;
description?: string;
type: string;
supportedTypes?: string[];
category?: string;
version?: string;
icon?: string;
color?: string;
badge?: string;
inputs?: NodePort[];
outputs?: NodePort[];
config?: Record<string, unknown>;
configSchema?: ConfigSchema;
uiSchema?: UISchemaElement;
configEdit?: ConfigEditOptions;
tags?: string[];
extensions?: NodeExtensions;
}
NodePort
interface NodePort {
id: string;
name: string;
type: 'input' | 'output' | 'metadata';
dataType: string;
required?: boolean;
description?: string;
defaultValue?: unknown;
schema?: OutputSchema | InputSchema;
}
ConfigSchema
Standard JSON Schema with FlowDrop extensions:interface ConfigSchema {
type: 'object';
properties?: Record<string, FieldSchema>;
required?: string[];
}
FieldSchema
interface FieldSchema {
type: FieldType | string;
title?: string;
description?: string;
default?: unknown;
format?: string;
enum?: unknown[];
oneOf?: Array<{ const: any; title: string }>;
multiple?: boolean;
minimum?: number;
maximum?: number;
minLength?: number;
maxLength?: number;
pattern?: string;
readOnly?: boolean;
items?: FieldSchema;
properties?: Record<string, FieldSchema>;
autocomplete?: AutocompleteConfig;
variables?: TemplateVariablesConfig;
'x-display-order'?: number;
[key: string]: unknown;
}
UISchema types
type UISchemaElement = UISchemaControl | UISchemaVerticalLayout | UISchemaGroup;
interface UISchemaControl {
type: 'Control';
scope: string; // JSON Pointer: "#/properties/fieldName"
label?: string;
hidden?: boolean;
}
interface UISchemaVerticalLayout {
type: 'VerticalLayout';
elements: UISchemaElement[];
}
interface UISchemaGroup {
type: 'Group';
label?: string;
description?: string;
collapsible?: boolean;
defaultOpen?: boolean;
elements: UISchemaElement[];
}
Authentication
interface AuthProvider {
getHeaders(): Promise<Record<string, string>>;
onUnauthorized?(): Promise<void>;
}
class StaticAuthProvider implements AuthProvider {
constructor(token: string);
}
class CallbackAuthProvider implements AuthProvider {
constructor(options: {
getToken: () => string | Promise<string>;
onUnauthorized?: () => void | Promise<void>;
});
}
class NoAuthProvider implements AuthProvider {}
AuthProvider passed as the authProvider mount option — not via the endpoint config.
EndpointConfig
interface EndpointConfig {
baseUrl: string;
endpoints: {
nodes: { list: string; get: string; byCategory: string; metadata: string };
portConfig: string;
categories: string;
workflows: {
list: string;
get: string;
create: string;
update: string;
delete: string;
validate: string;
export: string;
import: string;
};
executions: { execute: string; status: string; cancel: string; logs: string; history: string };
// ... pipelines, playground, interrupts, chat, templates, users, system
};
agentSpec?: AgentSpecEndpointConfig;
timeout?: number;
/** Transform applied to workflow objects before they are sent to the backend */
transformWorkflowPayload?: (workflow: Record<string, unknown>) => Record<string, unknown>;
}
function createEndpointConfig(baseUrlOrConfig: string | Partial<EndpointConfig>): EndpointConfig;
EndpointConfig carries no authentication field. Use the authProvider mount option for credentials.
WorkflowChangeType
type WorkflowChangeType =
| 'node_add'
| 'node_remove'
| 'node_move'
| 'node_config'
| 'edge_add'
| 'edge_remove'
| 'metadata'
| 'name'
| 'description';
Event handlers
Event handlers for lifecycle integration. See Event System for usage examples.interface FlowDropEventHandlers {
/** Called on any workflow modification */
onWorkflowChange?: (workflow: Workflow, changeType: WorkflowChangeType) => void;
/** Called when dirty state changes (saved ↔ unsaved) */
onDirtyStateChange?: (isDirty: boolean) => void;
/** Called before save — return false to cancel */
onBeforeSave?: (workflow: Workflow) => Promise<boolean | void>;
/** Called after successful save */
onAfterSave?: (workflow: Workflow) => Promise<void>;
/** Called when save fails */
onSaveError?: (error: Error, workflow: Workflow) => Promise<void>;
/** Called after a workflow is loaded */
onWorkflowLoad?: (workflow: Workflow) => void;
/** Called before FlowDrop is destroyed */
onBeforeUnmount?: (workflow: Workflow, isDirty: boolean) => void;
/** Called on any API error — return true to suppress default toast */
onApiError?: (error: Error, operation: string) => boolean | void;
/** Called before a node swap — return false to cancel */
onBeforeSwap?: (context: SwapEventContext) => boolean | void | Promise<boolean | void>;
/** Called after a node swap is applied */
onAfterSwap?: (result: SwapResult, oldNode: WorkflowNode, newNodeId: string) => void;
/** Called when Agent Spec execution starts */
onAgentSpecExecutionStarted?: (executionId: string) => void;
/** Called when Agent Spec execution completes */
onAgentSpecExecutionCompleted?: (executionId: string, results: Record<string, unknown>) => void;
/** Called when Agent Spec execution fails */
onAgentSpecExecutionFailed?: (executionId: string, error: Error) => void;
/** Called when a node's execution status updates during Agent Spec execution */
onAgentSpecNodeStatusUpdate?: (nodeId: string, status: NodeExecutionInfo) => void;
}
Features
interface FlowDropFeatures {
/** Save drafts to localStorage automatically @default true */
autoSaveDraft?: boolean;
/** Auto-save interval in ms @default 30000 */
autoSaveDraftInterval?: number;
/** Show toast notifications @default true */
showToasts?: boolean;
}
Port configuration
interface PortConfig {
dataTypes: PortDataTypeConfig[];
compatibilityRules: PortCompatibilityRule[];
defaultDataType: string;
version?: string;
}
interface PortDataTypeConfig {
id: string;
name: string;
description?: string;
color: string;
category?: string;
aliases?: string[];
enabled?: boolean;
}
interface PortCompatibilityRule {
from: string;
to: string;
description?: string;
}
Playground types
interface PlaygroundSession {
id: string;
workflowId: string;
name: string;
status: PlaygroundSessionStatus;
createdAt: string;
updatedAt: string;
}
interface PlaygroundMessage {
id: string;
sessionId: string;
role: 'user' | 'assistant' | 'system';
content: string;
status?: string;
sequenceNumber?: number;
metadata?: Record<string, unknown>;
timestamp: string;
}
Interrupt types
interface Interrupt {
id: string;
type: InterruptType;
status: InterruptStatus;
config: InterruptConfig;
responseValue?: unknown;
}
type InterruptType = 'confirmation' | 'choice' | 'text_input' | 'form' | 'review';
type InterruptStatus = 'pending' | 'resolved' | 'cancelled' | 'expired';