@runtypelabs/react-flow 0.1.0

package/src/types/index.ts

@@ -0,0 +1,332 @@
+import type { Node, Edge, NodeProps } from '@xyflow/react'
+import type { FlowStepType, PromptStepMode } from '@travrse/shared'
+import type { RuntypeClient } from '@runtypelabs/sdk'
+
+// ============================================================================
+// Flow Step Types (matching Runtype API)
+// ============================================================================
+
+/**
+ * Core FlowStep interface matching the Runtype API structure
+ */
+export interface FlowStep {
+  id: string
+  type: FlowStepType
+  name: string
+  order: number
+  enabled: boolean
+  config: FlowStepConfig
+}
+
+/**
+ * Union type for all step configurations
+ */
+export type FlowStepConfig =
+  | PromptStepConfig
+  | FetchUrlStepConfig
+  | TransformDataStepConfig
+  | ConditionalStepConfig
+  | SendEmailStepConfig
+  | GenericStepConfig
+
+/**
+ * Prompt step configuration
+ */
+export interface PromptStepConfig {
+  mode?: PromptStepMode
+  model: string
+  systemPrompt?: string
+  userPrompt: string
+  previousMessages?: string
+  responseFormat?: 'json' | 'markdown' | 'text' | 'html' | 'xml'
+  temperature?: number
+  maxTokens?: number
+  outputVariable: string
+  tools?: {
+    toolIds: string[]
+  }
+}
+
+/**
+ * Fetch URL step configuration
+ */
+export interface FetchUrlStepConfig {
+  http: {
+    url: string
+    method?: 'GET' | 'POST' | 'PUT' | 'DELETE' | 'PATCH'
+    headers?: Record<string, string>
+    body?: string
+    timeout?: number
+  }
+  auth?: {
+    type: 'none' | 'bearer' | 'basic' | 'api-key'
+    token?: string
+    username?: string
+    password?: string
+    apiKey?: string
+    headerName?: string
+  }
+  responseType?: 'json' | 'text' | 'xml'
+  outputVariable: string
+  errorHandling?: 'fail' | 'continue' | 'default'
+  defaultValue?: unknown
+}
+
+/**
+ * Transform data (code) step configuration
+ */
+export interface TransformDataStepConfig {
+  script: string
+  outputVariable: string
+  sandboxProvider?: 'quickjs' | 'daytona'
+  language?: 'javascript' | 'typescript' | 'python'
+  errorHandling?: 'fail' | 'continue' | 'default'
+  defaultValue?: unknown
+}
+
+/**
+ * Conditional step configuration
+ */
+export interface ConditionalStepConfig {
+  condition: string
+  trueSteps: FlowStep[]
+  falseSteps?: FlowStep[]
+}
+
+/**
+ * Send email step configuration
+ */
+export interface SendEmailStepConfig {
+  from: string
+  to: string
+  subject: string
+  replyTo?: string
+  cc?: string
+  bcc?: string
+  html?: string
+  text?: string
+  attachments?: Array<{
+    filename: string
+    content: string
+    contentType?: string
+  }>
+  outputVariable: string
+  errorHandling?: 'fail' | 'continue' | 'default'
+  defaultValue?: unknown
+}
+
+/**
+ * Generic step config for extensibility
+ */
+export interface GenericStepConfig {
+  [key: string]: unknown
+  outputVariable?: string
+}
+
+// ============================================================================
+// React Flow Node Types
+// ============================================================================
+
+/**
+ * Base data structure for all Runtype nodes
+ * Uses index signature to satisfy React Flow's Record<string, unknown> constraint
+ */
+export interface RuntypeNodeData extends Record<string, unknown> {
+  step: FlowStep
+  label: string
+  onChange?: (stepId: string, updates: Partial<FlowStep>) => void
+  onDelete?: (stepId: string) => void
+}
+
+/**
+ * Runtype node extending React Flow's Node type
+ */
+export type RuntypeNode = Node<RuntypeNodeData, FlowStepType>
+
+/**
+ * Runtype edge type
+ */
+export type RuntypeEdge = Edge<{ stepOrder?: number }>
+
+/**
+ * Props for node components
+ */
+export type RuntypeNodeProps = NodeProps
+
+// ============================================================================
+// Node Type Registry
+// ============================================================================
+
+/**
+ * Supported node types that have custom components
+ */
+export const SUPPORTED_NODE_TYPES = [
+  'prompt',
+  'fetch-url',
+  'transform-data',
+  'conditional',
+  'send-email',
+] as const
+
+export type SupportedNodeType = typeof SUPPORTED_NODE_TYPES[number]
+
+/**
+ * Check if a step type has a custom node component
+ */
+export function isSupportedNodeType(type: FlowStepType): type is SupportedNodeType {
+  return SUPPORTED_NODE_TYPES.includes(type as SupportedNodeType)
+}
+
+// ============================================================================
+// Editor Configuration
+// ============================================================================
+
+/**
+ * Configuration for the RuntypeFlowEditor component
+ */
+export interface RuntypeFlowEditorProps {
+  /** Runtype API client instance */
+  client: RuntypeClient
+  /** ID of an existing flow to load */
+  flowId?: string
+  /** Initial flow name (for new flows) */
+  initialName?: string
+  /** Initial flow description */
+  initialDescription?: string
+  /** Initial steps to populate the editor */
+  initialSteps?: FlowStep[]
+  /** Callback when flow is saved */
+  onSave?: (flow: SavedFlow) => void
+  /** Callback when flow changes */
+  onChange?: (nodes: RuntypeNode[], edges: RuntypeEdge[]) => void
+  /** Callback when a step is selected */
+  onStepSelect?: (step: FlowStep | null) => void
+  /** Whether to show the toolbar */
+  showToolbar?: boolean
+  /** Whether the editor is read-only */
+  readOnly?: boolean
+  /** Custom class name for the editor container */
+  className?: string
+  /** Available models for prompt steps */
+  availableModels?: ModelOption[]
+}
+
+/**
+ * Model option for prompt step configuration
+ */
+export interface ModelOption {
+  id: string
+  name: string
+  provider: string
+}
+
+/**
+ * Saved flow data returned after save operations
+ */
+export interface SavedFlow {
+  id: string
+  name: string
+  description?: string
+  steps: FlowStep[]
+  createdAt?: string
+  updatedAt?: string
+}
+
+// ============================================================================
+// Hook Types
+// ============================================================================
+
+/**
+ * Return type for useRuntypeFlow hook
+ */
+export interface UseRuntypeFlowReturn {
+  /** Current React Flow nodes */
+  nodes: RuntypeNode[]
+  /** Current React Flow edges */
+  edges: RuntypeEdge[]
+  /** Handler for node changes */
+  onNodesChange: (changes: unknown) => void
+  /** Handler for edge changes */
+  onEdgesChange: (changes: unknown) => void
+  /** Handler for new connections */
+  onConnect: (connection: unknown) => void
+  /** Flow metadata */
+  flowName: string
+  flowDescription: string
+  flowId: string | null
+  /** Set flow name */
+  setFlowName: (name: string) => void
+  /** Set flow description */
+  setFlowDescription: (description: string) => void
+  /** Load a flow by ID */
+  loadFlow: (flowId: string) => Promise<void>
+  /** Save the current flow */
+  saveFlow: () => Promise<SavedFlow>
+  /** Create a new flow */
+  createFlow: (name: string, description?: string) => Promise<SavedFlow>
+  /** Delete a step */
+  deleteStep: (stepId: string) => void
+  /** Update a step's configuration */
+  updateStep: (stepId: string, updates: Partial<FlowStep>) => void
+  /** Add a new step */
+  addStep: (type: FlowStepType, position?: { x: number; y: number }) => void
+  /** Loading state */
+  isLoading: boolean
+  /** Saving state */
+  isSaving: boolean
+  /** Error state */
+  error: Error | null
+  /** Whether there are unsaved changes */
+  hasUnsavedChanges: boolean
+}
+
+/**
+ * Validation result for a flow
+ */
+export interface FlowValidationResult {
+  isValid: boolean
+  errors: ValidationError[]
+  warnings: ValidationWarning[]
+}
+
+export interface ValidationError {
+  stepId: string
+  field?: string
+  message: string
+}
+
+export interface ValidationWarning {
+  stepId: string
+  field?: string
+  message: string
+}
+
+// ============================================================================
+// Event Types
+// ============================================================================
+
+/**
+ * Event emitted when a step is updated
+ */
+export interface StepUpdateEvent {
+  stepId: string
+  updates: Partial<FlowStep>
+  previousValue: FlowStep
+}
+
+/**
+ * Event emitted when a step is deleted
+ */
+export interface StepDeleteEvent {
+  stepId: string
+  step: FlowStep
+}
+
+/**
+ * Event emitted when a step is added
+ */
+export interface StepAddEvent {
+  step: FlowStep
+  position: { x: number; y: number }
+}
+