@d34dman/flowdrop 0.0.1 → 0.0.2

package/README.md

@@ -1,293 +1,385 @@
-# FlowDrop
+# FlowDrop - Drupal Workflow Editor
 
-A powerful Svelte Flow-based library for building workflows with a drag-and-drop interface. Inspired by tools like n8n, Langflow, and Flowise.
+A powerful visual workflow editor for Drupal that enables drag-and-drop creation of complex workflows with AI integration, data processing, and automation capabilities.
 
-## Features
+## 🚀 Features
 
-- 🎯 **Node-based Workflow Editor** - Drag and drop interface for building workflows
-- 🔌 **HTTP API Integration** - Fetch node definitions and manage workflows via REST API
-- 🎨 **Modern UI** - Built with DaisyUI and Tailwind CSS for a beautiful, responsive interface
-- 📱 **Responsive Design** - Works seamlessly on desktop and mobile devices
-- 🔧 **TypeScript Support** - Full TypeScript support with comprehensive type definitions
-- 🚀 **SvelteKit Ready** - Built for SvelteKit applications
-- 📦 **Modular Architecture** - Easy to extend and customize
+- **Visual Workflow Editor**: Drag-and-drop interface for building complex workflows
+- **AI Integration**: OpenAI, Anthropic, and other AI model integrations
+- **Data Processing**: Advanced data manipulation and transformation nodes
+- **HTTP Integration**: Webhook and API request capabilities
+- **File Operations**: Upload, download, and file processing
+- **Conditional Logic**: Advanced branching and decision-making nodes
+- **Real-time Execution**: Live workflow execution with status monitoring
+- **Drupal Native**: Built specifically for Drupal 10/11
 
-## Installation
+## 📁 Project Structure
 
-```bash
-npm install flowdrop
+```
+flowdrop/
+├── src/                          # Core PHP classes
+│   ├── Service/NodeRuntime/      # Node execution engine
+│   ├── Plugin/FlowDropNodeProcessor/  # 25+ node processors
+│   ├── Attribute/                # Plugin discovery attributes
+│   └── Exception/                # Custom exception classes
+├── modules/                      # Drupal sub-modules
+│   ├── flowdrop_workflow/        # Workflow entity management
+│   ├── flowdrop_ui/             # Svelte frontend application
+│   ├── flowdrop_node_type/      # Node type definitions
+│   ├── flowdrop_node_category/  # Node categorization
+│   ├── flowdrop_pipeline/       # Pipeline management
+│   ├── flowdrop_job/           # Job execution system
+│   ├── flowdrop_runner/        # Workflow execution engine
+│   └── flowdrop_ai/            # AI integration features
+├── js/                         # Drupal JavaScript integration
+└── config/                     # Drupal configuration
 ```
 
-## Quick Start
+## 🏗️ Architecture
 
-### 1. Basic Setup
+### Core Components
 
-```svelte
-<script lang="ts">
-  import { WorkflowEditor } from "flowdrop";
-  import type { FlowDropConfig } from "flowdrop";
+1. **Plugin System**: Attribute-based discovery of node processors
+2. **Node Runtime**: Execution engine for workflow nodes
+3. **Workflow Engine**: Drupal entity-based workflow management
+4. **Frontend**: Svelte-based visual editor
+5. **API Layer**: RESTful API for workflow operations
 
-  const config: FlowDropConfig = {
-    apiBaseUrl: "https://your-api.com",
-    theme: "auto",
-    enableDebug: true
-  };
-</script>
+### Node Categories
 
-<WorkflowEditor {config} />
-```
+- **AI Models**: OpenAI Chat, Embeddings, HuggingFace
+- **Data Processing**: Calculator, Dataframe Operations, Data Operations
+- **Input/Output**: Text Input, Chat Output, File Upload
+- **HTTP Operations**: URL Fetch, HTTP Request, Webhook
+- **Conditional Logic**: Conditional nodes, Loop operations
+- **Utility**: DateTime, Regex Extractor, Split Text
+- **Storage**: Save to File, Chroma Vector Store
 
-### 2. With Sample Data
+## 🛠️ Installation
 
-```svelte
-<script lang="ts">
-  import { WorkflowEditor, sampleWorkflow } from "flowdrop";
-  import type { FlowDropConfig } from "flowdrop";
+### Prerequisites
 
-  const config: FlowDropConfig = {
-    apiBaseUrl: "https://your-api.com",
-    theme: "auto"
-  };
-</script>
+- Drupal 10 or 11
+- PHP 8.1+
+- Node.js 18+ (for frontend development)
 
-<WorkflowEditor {config} workflow={sampleWorkflow} />
-```
+### Installation Steps
 
-### 3. Custom API Client
+1. **Install the module**:
 
-```svelte
-<script lang="ts">
-  import { WorkflowEditor, FlowDropApiClient } from "flowdrop";
-  import type { FlowDropConfig } from "flowdrop";
+   ```bash
+   # Copy to your Drupal modules directory
+   cp -r flowdrop /path/to/drupal/web/modules/custom/
+   ```
 
-  const config: FlowDropConfig = {
-    apiBaseUrl: "https://your-api.com",
-    apiKey: "your-api-key"
-  };
+2. **Enable the module**:
 
-  const apiClient = new FlowDropApiClient(config.apiBaseUrl, config.apiKey);
-</script>
+   ```bash
+   ddev drush en flowdrop flowdrop_workflow flowdrop_ui
+   ```
 
-<WorkflowEditor {config} />
-```
+3. **Build the frontend**:
 
-## API Reference
+   ```bash
+   cd modules/flowdrop_ui/app/flowdrop
+   npm install
+   npm run build:iife
+   ```
 
-### Configuration
+4. **Clear Drupal cache**:
+   ```bash
+   ddev drush cr
+   ```
 
-```typescript
-interface FlowDropConfig {
-  apiBaseUrl: string;           // Your API endpoint
-  theme?: "light" | "dark" | "auto";
-  enableDebug?: boolean;
-  autoSave?: boolean;
-  autoSaveInterval?: number;    // milliseconds
-  maxUndoSteps?: number;
-  nodeSpacing?: number;
-  gridSize?: number;
-}
-```
+## 🎯 Usage
 
-### Node Types
-
-The library supports various node categories:
-
-- **Models** - OpenAI, Anthropic, and other model providers
-- **Input/Output** - Text input, file upload, display output
-- **Processing** - Text transformation, data processing
-- **Conditional** - Logic gates, conditional flows
-- **Utility** - Helper functions, data manipulation
-- **Integration** - External service connections
-
-### Node Metadata Structure
-
-```typescript
-interface NodeMetadata {
-  id: string;
-  name: string;
-  description: string;
-  category: NodeCategory;
-  icon?: string;
-  color?: string;
-  inputs: NodePort[];
-  outputs: NodePort[];
-  configSchema?: Record<string, unknown>;
-  tags?: string[];
-}
-```
+### Accessing the Workflow Editor
 
-### API Endpoints
+1. Navigate to `/admin/structure/flowdrop-workflow`
+2. Create a new workflow or edit an existing one
+3. Use the visual editor to build your workflow
 
-The library expects the following API endpoints:
+### Creating Workflows
 
-- `GET /api/nodes` - Fetch available node types
-- `GET /api/nodes?category={category}` - Fetch nodes by category
-- `GET /api/nodes/{id}` - Fetch specific node metadata
-- `POST /api/workflows` - Save workflow
-- `PUT /api/workflows/{id}` - Update workflow
-- `GET /api/workflows/{id}` - Load workflow
-- `GET /api/workflows` - List workflows
-- `DELETE /api/workflows/{id}` - Delete workflow
-- `POST /api/workflows/{id}/execute` - Execute workflow
-- `GET /api/executions/{id}` - Get execution status
-- `POST /api/executions/{id}/cancel` - Cancel execution
+1. **Add Nodes**: Drag nodes from the palette to the canvas
+2. **Configure Nodes**: Set parameters and configuration for each node
+3. **Connect Nodes**: Create connections between node inputs and outputs
+4. **Test Execution**: Use the execution panel to test your workflow
+5. **Save & Deploy**: Save your workflow for production use
 
-## Components
+### Available Node Types
 
-### WorkflowEditor
+#### AI Models
 
-The main component that provides the complete workflow editing experience.
+- **OpenAI Chat**: GPT model integration
+- **OpenAI Embeddings**: Text embedding generation
+- **HuggingFace Embeddings**: Alternative embedding models
+- **Simple Agent**: Basic AI agent implementation
 
-```svelte
-<WorkflowEditor
-  config={config}
-  workflow={workflow}
-  apiKey="optional-api-key"
-/>
-```
+#### Data Processing
 
-### NodeSidebar
+- **Calculator**: Mathematical operations
+- **Dataframe Operations**: Advanced data manipulation
+- **Data Operations**: General data processing
+- **Data to Dataframe**: Data format conversion
 
-A sidebar component that displays available nodes organized by category.
+#### Input/Output
 
-```svelte
-<NodeSidebar
-  nodes={availableNodes}
-  loading={false}
-  on:nodeSelected={handleNodeSelected}
-  on:categoryChanged={handleCategoryChanged}
-  on:searchChanged={handleSearchChanged}
-/>
-```
+- **Text Input**: User input collection
+- **Text Output**: Display text results
+- **Chat Output**: Chat interface output
+- **File Upload**: File upload handling
 
-### WorkflowNode
+#### HTTP & Integration
 
-A customizable node component for displaying workflow nodes.
+- **URL Fetch**: HTTP GET requests
+- **HTTP Request**: Full HTTP client
+- **Webhook**: Webhook endpoint handling
 
-```svelte
-<WorkflowNode
-  data={nodeData}
-  selected={false}
-  on:configChanged={handleConfigChange}
-  on:nodeSelected={handleNodeSelect}
-/>
-```
+#### Logic & Control
 
-## Events
+- **Conditional**: If/else logic branching
+- **Loop**: Iterative operations
+- **Split Text**: Text segmentation
 
-The library dispatches various events for integration:
+#### Utility
 
-```typescript
-// Node events
-nodeSelected: { node: NodeMetadata }
-nodeAdded: { node: WorkflowNode }
-nodeRemoved: { nodeId: string }
-nodeUpdated: { node: WorkflowNode }
+- **DateTime**: Date/time operations
+- **Regex Extractor**: Pattern matching
+- **Conversation Buffer**: Chat history management
+- **Structured Output**: Formatted output generation
 
-// Edge events
-edgeAdded: { edge: WorkflowEdge }
-edgeRemoved: { edgeId: string }
+## 🔧 Development
 
-// Workflow events
-workflowSaved: { workflow: Workflow }
-workflowLoaded: { workflow: Workflow }
+### Adding New Node Types
 
-// Execution events
-executionStarted: { workflowId: string }
-executionCompleted: { result: ExecutionResult }
-executionFailed: { error: string }
-```
+1. **Create Node Class**:
 
-## Customization
+   ```php
+   <?php
 
-### Custom Node Types
+   namespace Drupal\flowdrop\Plugin\FlowDropNodeProcessor;
 
-You can create custom node types by extending the base components:
+   use Drupal\flowdrop\Attribute\FlowDropNodeProcessor;
 
-```svelte
-<script lang="ts">
-  import WorkflowNode from "flowdrop/WorkflowNode.svelte";
-  
-  // Custom node logic here
-</script>
+   #[FlowDropNodeProcessor(
+     id: "my_custom_node",
+     label: new \Drupal\Core\StringTranslation\TranslatableMarkup("My Custom Node")
+   )]
+   class MyCustomNode extends AbstractFlowDropNodeProcessor {
 
-<div class="custom-node">
-  <!-- Your custom node UI -->
-</div>
-```
+     public function execute(array $inputs, array $config): array {
+       // Your node logic here
+       return ['result' => 'processed data'];
+     }
 
-### Custom Styling
+     public function getConfigSchema(): array {
+       return [
+         'type' => 'object',
+         'properties' => [
+           'mySetting' => ['type' => 'string'],
+         ],
+       ];
+     }
+   }
+   ```
 
-The library uses DaisyUI and Tailwind CSS. You can customize the appearance by:
+2. **Implement Required Methods**:
+   - `execute()`: Main node logic
+   - `getConfigSchema()`: Configuration schema
+   - `getInputSchema()`: Input validation schema
+   - `getOutputSchema()`: Output schema
+   - `validateInputs()`: Input validation
 
-1. Overriding CSS variables
-2. Using DaisyUI themes
-3. Adding custom CSS classes
+### Frontend Development
 
-```css
-:root {
-  --primary: 220 14% 96%;
-  --primary-content: 220 9% 46%;
-  --secondary: 220 14% 96%;
-  --secondary-content: 220 9% 46%;
-  /* ... more variables */
-}
+The frontend is a Svelte application located in `modules/flowdrop_ui/app/flowdrop/`.
+
+```bash
+cd modules/flowdrop_ui/app/flowdrop
+npm run dev          # Development server
+npm run build:iife   # Build for Drupal integration
+npm run test         # Run tests
 ```
 
-## Development
+## 📚 API Documentation
 
-### Prerequisites
+### IIFE Integration API
 
-- Node.js 18+
-- npm or yarn
+The FlowDrop library can be integrated into Drupal using the IIFE (Immediately Invoked Function Expression) build. The library provides two main mounting functions:
 
-### Setup
+#### Mounting Functions
 
-```bash
-git clone https://github.com/your-repo/flowdrop.git
-cd flowdrop
-npm install
+```javascript
+// Mount the full FlowDrop App
+window.FlowDrop.mountFlowDropApp(container, options);
+
+// Mount just the WorkflowEditor component
+window.FlowDrop.mountWorkflowEditor(container, options);
 ```
 
-### Development Server
+#### Configuration Options
+
+```javascript
+// Basic usage with default configuration
+window.FlowDrop.mountWorkflowEditor(container, {
+	workflow: myWorkflow,
+	nodes: availableNodes
+});
+
+// Advanced usage with custom endpoint configuration
+window.FlowDrop.mountWorkflowEditor(container, {
+	workflow: myWorkflow,
+	nodes: availableNodes,
+	endpointConfig: {
+		baseUrl: '/api/flowdrop',
+		endpoints: {
+			nodes: {
+				list: '/nodes',
+				get: '/nodes/{id}',
+				byCategory: '/nodes?category={category}',
+				metadata: '/nodes/{id}/metadata'
+			},
+			workflows: {
+				list: '/workflows',
+				get: '/workflows/{id}',
+				create: '/workflows',
+				update: '/workflows/{id}',
+				delete: '/workflows/{id}',
+				validate: '/workflows/validate',
+				export: '/workflows/{id}/export',
+				import: '/workflows/import'
+			},
+			executions: {
+				execute: '/workflows/{id}/execute',
+				status: '/executions/{id}',
+				cancel: '/executions/{id}/cancel',
+				logs: '/executions/{id}/logs',
+				history: '/executions'
+			}
+		},
+		timeout: 30000,
+		retry: {
+			enabled: true,
+			maxAttempts: 3,
+			delay: 1000,
+			backoff: 'exponential'
+		},
+		auth: {
+			type: 'bearer',
+			token: 'your-auth-token'
+		}
+	}
+});
+```
 
-```bash
-npm run dev
+#### Drupal Integration Example
+
+```javascript
+// Drupal behavior for FlowDrop integration
+Drupal.behaviors.flowdropWorkflowEditor = {
+	attach: function (context, settings) {
+		const container = context.querySelector('.flowdrop-workflow-editor');
+		if (container && window.FlowDrop) {
+			window.FlowDrop.mountWorkflowEditor(container, {
+				endpointConfig: settings.flowdrop.endpointConfig,
+				workflow: settings.flowdrop.workflow,
+				nodes: settings.flowdrop.nodes
+			});
+		}
+	}
+};
+```
+
+### REST API Endpoints
+
+#### Workflows
+
+- `GET /api/flowdrop/workflows` - List workflows
+- `POST /api/flowdrop/workflows` - Create workflow
+- `GET /api/flowdrop/workflows/{id}` - Get workflow
+- `PUT /api/flowdrop/workflows/{id}` - Update workflow
+- `DELETE /api/flowdrop/workflows/{id}` - Delete workflow
+- `POST /api/flowdrop/workflows/{id}/execute` - Execute workflow
+
+#### Nodes
+
+- `GET /api/flowdrop/nodes` - List available nodes
+- `GET /api/flowdrop/nodes/{id}` - Get node metadata
+- `GET /api/flowdrop/nodes?category={category}` - Filter by category
+
+#### Executions
+
+- `GET /api/flowdrop/executions/active` - Active executions
+- `GET /api/flowdrop/executions/{id}/state` - Execution status
+
+### Node Configuration Schema
+
+Each node type defines its configuration schema:
+
+```json
+{
+	"type": "object",
+	"properties": {
+		"setting1": {
+			"type": "string",
+			"title": "Setting 1",
+			"description": "Description of setting"
+		},
+		"setting2": {
+			"type": "number",
+			"default": 0
+		}
+	}
+}
 ```
 
-### Build
+## 🔒 Security
+
+- All API endpoints require appropriate Drupal permissions
+- Input validation on all node processors
+- Exception handling for failed executions
+- Logging of all workflow operations
+
+## 🧪 Testing
+
+### Backend Testing
 
 ```bash
-npm run build
+ddev drush test:run flowdrop
 ```
 
-### Testing
+### Frontend Testing
 
 ```bash
-npm run test
+cd modules/flowdrop_ui/app/flowdrop
+npm run test:unit
+npm run test:e2e
 ```
 
-## Contributing
+## 📝 Logging
+
+Workflow execution is logged through Drupal's logging system:
+
+```php
+$this->loggerFactory->get('flowdrop')->info('Workflow executed', [
+  'workflow_id' => $workflowId,
+  'execution_time' => $executionTime,
+]);
+```
 
-1. Fork the repository
-2. Create a feature branch
-3. Make your changes
-4. Add tests if applicable
-5. Submit a pull request
+## 🤝 Contributing
 
-## License
+Not accepting Contribution until the module stabilizes. Stay tuned.
 
-MIT License - see [LICENSE](LICENSE) file for details.
+## 🆘 Support
 
-## Support
+For issues and questions:
 
-- 📚 [Documentation](https://flowdrop.dev)
-- 🐛 [Issue Tracker](https://github.com/your-repo/flowdrop/issues)
-- 💬 [Discussions](https://github.com/your-repo/flowdrop/discussions)
+- Check the API documentation in `modules/flowdrop_ui/app/flowdrop/API.md`
+- Review the security guidelines in `modules/flowdrop_ui/app/flowdrop/SECURITY.md`
+- Create an issue in the project repository
 
-## Acknowledgments
+---
 
-- [Svelte Flow](https://github.com/xyflow/xyflow) - The underlying flow library
-- [DaisyUI](https://daisyui.com/) - Beautiful UI components
-- [Tailwind CSS](https://tailwindcss.com/) - Utility-first CSS framework
-- [SvelteKit](https://kit.svelte.dev/) - The web framework
+**FlowDrop** - Empowering Drupal with visual workflow automation.

package/dist/adapters/WorkflowAdapter.d.ts

@@ -13,7 +13,7 @@
  * - External applications that want to integrate with FlowDrop
  * - Systems that need to generate or modify workflows programmatically
  */
-import type { Workflow, NodeMetadata } from "../types/index.js";
+import type { Workflow, NodeMetadata } from '../types/index.js';
 /**
  * Standard workflow node interface (SvelteFlow-agnostic)
  */