Core types

Key TypeScript types exported by FlowDrop.

All types are exported from @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 {}

Authentication is supplied through an 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';