@flowuent-org/diagramming-core 1.0.5

package/packages/diagrams/GOOGLE_SHEETS_IMPLEMENTATION.md

@@ -0,0 +1,233 @@
+# Google Sheets Automation Node Implementation
+
+This document explains the frontend-only Google Sheets Output Node. It supports Google Sheets export (cloud), Excel download (local), and email compose.
+
+## Features
+
+### ✅ Implemented
+
+1. **Google Sheets Export (Cloud)**
+   - OAuth via Google Identity Services (GIS) in the browser
+   - Creates a new spreadsheet when `spreadsheetId` is empty
+   - Ensures the target sheet exists and writes mapped values
+
+2. **Excel Download (Local)**
+   - Uses `xlsx` to build a workbook and `file-saver` to download
+   - Optional headers row
+
+3. **Email Output (Compose)**
+   - Opens Gmail compose in a new tab with pre-filled to/subject/body
+   - Falls back to `mailto:` handler if the popup is blocked
+   - Optionally includes a spreadsheet link in the message
+
+4. **Data Mapping & Formatting**
+   - Flexible column mapping with nested field support (dot notation)
+   - String/number/date/boolean formatting
+   - Append/overwrite controls via configuration
+
+5. **Export Modes**
+   - `sheets` (cloud)
+   - `excel` (local)
+   - `both` (cloud + local)
+
+6. **Error Handling & Logging**
+   - Config validation, structured logs, execution results per node
+
+## Dependencies
+
+Browser loads GIS from `https://accounts.google.com/gsi/client`. No server SDK required.
+
+Project packages used:
+
+```json
+{
+  "xlsx": "^0.18.5",
+  "file-saver": "^2.0.5",
+  "@types/file-saver": "^2.0.7"
+}
+```
+
+## Configuration Structure
+
+### Google Sheets Configuration
+```typescript
+sheetsConfig: {
+  spreadsheetId: string;
+  sheetName: string;
+  range: string;
+  credentials: {
+    type: 'oauth' | 'service-account' | 'api-key';
+    // Frontend OAuth (GIS)
+    clientId?: string;
+    scopes?: string[]; // default: ['https://www.googleapis.com/auth/spreadsheets']
+    oauthToken?: string; // optional pre-provided token
+    // Server-side options (not used in frontend-only mode)
+    serviceAccountKey?: string;
+    clientEmail?: string;
+    privateKey?: string;
+    apiKey?: string;
+  };
+}
+```
+
+### Export Options
+```typescript
+exportOptions: {
+  emailRecipients: string[];
+  fileName: string;
+  exportFormat: 'sheets' | 'excel' | 'both';
+  includeHeaders: boolean;
+  sendEmailNotification: boolean;
+  // Email compose options (optional)
+  emailSendEnabled?: boolean;
+  emailSender?: string;
+  emailSubject?: string;
+  emailMessage?: string;
+  includeSpreadsheetLink?: boolean;
+  attachExcel?: boolean; // requires Gmail API for real attachments
+}
+```
+
+### Data Mapping
+```typescript
+dataMapping: {
+  headers: Array<{
+    column: string;
+    sourceField: string;
+    dataType: 'string' | 'number' | 'date' | 'boolean';
+  }>;
+  appendMode: boolean;
+  clearSheet: boolean;
+}
+```
+
+## Usage Examples
+
+### Basic Google Sheets Export
+```typescript
+const sheetsService = new GoogleSheetsService();
+await sheetsService.initialize(sheetsConfig);
+
+const response = await sheetsService.exportToSheets(
+  data,
+  sheetsConfig,
+  dataMapping,
+  {
+    emailRecipients: ['user@example.com'],
+    fileName: 'report.xlsx',
+    exportFormat: 'sheets',
+    includeHeaders: true
+  }
+);
+```
+
+### Excel File Generation
+```typescript
+const excelResponse = await sheetsService.exportToExcel(
+  data,
+  dataMapping,
+  {
+    emailRecipients: ['user@example.com'],
+    fileName: 'data_export.xlsx',
+    includeHeaders: true
+  }
+);
+```
+
+### Both + Email Compose
+```typescript
+const response = await sheetsService.exportToSheets(
+  data,
+  sheetsConfig,
+  dataMapping,
+  {
+    emailRecipients: ['recipient@example.com'],
+    fileName: 'news_analysis_report',
+    exportFormat: 'both',
+    includeHeaders: true,
+    // email compose
+    emailSendEnabled: true,
+    emailSender: 'sender@example.com',
+    emailSubject: 'News Analysis Results',
+    emailMessage: 'Please find the latest output.',
+    includeSpreadsheetLink: true,
+  }
+);
+```
+
+## Authentication Setup (Frontend OAuth)
+
+1. Google Cloud Console → APIs & Services → Credentials → Create OAuth client ID → Application type: Web application.
+2. Authorized JavaScript origins: add your dev URLs (e.g., `http://localhost:5200`, `http://localhost:5300`).
+3. Enable the "Google Sheets API" for your project.
+4. OAuth consent screen: configure and Publish (or add test users).
+5. Put the client ID in `sheetsConfig.credentials.clientId`.
+6. Scopes: `['https://www.googleapis.com/auth/spreadsheets']` (default). For sending emails programmatically later, add `https://www.googleapis.com/auth/gmail.send`.
+7. Allow pop-ups for your dev origin so Gmail compose can open in a new tab.
+
+## Error Handling
+
+Includes:
+
+- Configuration validation
+- OAuth and API error messages with details
+- Range sizing that accounts for header rows
+- Logging and `executionResult` on each node
+
+## Security Considerations
+
+1. **Credentials Storage**: Store service account keys securely
+2. **API Key Restrictions**: Limit API key scope and usage
+3. **Sheet Permissions**: Use minimal required permissions
+4. **Data Privacy**: Ensure sensitive data is handled appropriately
+
+## Testing
+
+The implementation includes:
+- Configuration validation tests
+- Mock API responses for development
+- Error scenario handling
+- Data format validation
+
+## Future Enhancements
+
+1. Gmail API send with attachments (requires `gmail.send` scope and MIME building)
+2. Predefined Google Sheets templates and formatting
+3. Batch operations and partial updates
+4. Live progress UI during export
+
+### Potential Improvements
+1. **Caching**: Cache authentication tokens
+2. **Rate Limiting**: Handle API rate limits
+3. **Progress Tracking**: Real-time export progress
+4. **Data Validation**: Enhanced data type validation
+5. **Custom Formatting**: Cell formatting options
+
+## Troubleshooting
+
+### Common Issues
+1. **OAuth 400**: Ensure Authorized JavaScript origins match your dev URL and the consent screen is published.
+2. **No Gmail compose**: Enable pop-ups or try again; we open Gmail in a new tab.
+3. **Range errors**: Increase range or rely on auto-sizing; headers add one row.
+4. **Empty writes**: Verify the previous node outputs the fields referenced by `dataMapping.headers`.
+
+### Debug Mode
+Enable debug logging to see detailed execution information:
+```typescript
+// Debug logs are automatically included in execution results
+console.log('Execution result:', response);
+```
+
+## Contributing
+
+When contributing to this implementation:
+1. Follow TypeScript best practices
+2. Include comprehensive error handling
+3. Add appropriate tests
+4. Update documentation
+5. Consider security implications
+
+## License
+
+This implementation follows the same license as the parent project.
+

package/packages/diagrams/NODE_DATA_UPDATE_API.md

@@ -0,0 +1,430 @@
+# Node Data Update API Documentation
+
+## Overview
+
+The diagramming library provides comprehensive node data management functionality that allows external applications to read and update node configurations dynamically. This is particularly useful for automation diagrams where nodes contain configuration data like API endpoints, AI model settings, authentication keys, and other execution parameters.
+
+## How Node Data Management Works
+
+### Internal Implementation
+
+1. **Node Data Storage**: Each node contains a `data` property that holds its configuration
+2. **State Management**: Node data is managed through the Zustand store
+3. **Real-time Updates**: Changes are immediately reflected in the diagram
+4. **History Tracking**: Node data changes are tracked in the undo/redo system
+
+### Key Components
+
+- **DiagrammingPageRef**: Exposes node data management methods
+- **Node Data Types**: Structured interfaces for different node types
+- **Update Methods**: Functions to modify node data externally
+
+## External Node Data Control
+
+### Method 1: Using Ref-based API (Recommended)
+
+The `DiagrammingPage` component exposes node data management through a ref:
+
+```typescript
+import React, { useRef, useState, useEffect } from 'react';
+import { DiagrammingPage, DiagrammingPageRef } from '@flowuent-org/diagrams';
+
+const MyComponent = () => {
+  const diagramRef = useRef<DiagrammingPageRef>(null);
+  const [selectedNodeId, setSelectedNodeId] = useState<string | null>(null);
+  const [nodeData, setNodeData] = useState<any>(null);
+
+  // Monitor node selection changes
+  useEffect(() => {
+    const interval = setInterval(() => {
+      if (diagramRef.current) {
+        const currentSelected = diagramRef.current.getSelectedNode();
+        if (currentSelected !== selectedNodeId) {
+          setSelectedNodeId(currentSelected);
+          if (currentSelected) {
+            const data = diagramRef.current.getNodeData(currentSelected);
+            setNodeData(data);
+          }
+        }
+      }
+    }, 100);
+
+    return () => clearInterval(interval);
+  }, [selectedNodeId]);
+
+  const handleUpdateNode = (newData: any) => {
+    if (selectedNodeId && diagramRef.current) {
+      const success = diagramRef.current.updateNodeData(selectedNodeId, newData);
+      if (success) {
+        console.log('Node updated successfully');
+      }
+    }
+  };
+
+  return (
+    <div>
+      {/* Your external configuration panel */}
+      <YourConfigurationPanel 
+        nodeData={nodeData}
+        onUpdate={handleUpdateNode}
+      />
+
+      {/* The diagram */}
+      <DiagrammingPage
+        ref={diagramRef}
+        diagramType="automation"
+        defaultNodes={nodes}
+        defaultEdges={edges}
+        availableFunctions={[]}
+        id={1}
+      />
+    </div>
+  );
+};
+```
+
+### Available Methods
+
+The `DiagrammingPageRef` interface provides these node data management methods:
+
+```typescript
+interface DiagrammingPageRef {
+  // Undo/Redo methods (from previous API)
+  undo: () => void;
+  redo: () => void;
+  canUndo: () => boolean;
+  canRedo: () => boolean;
+  reset: () => void;
+  getHistoryLength: () => number;
+  getHistoryIndex: () => number;
+  
+  // Node data management methods
+  getNodeData: (nodeId: string) => any | null;        // Get node data by ID
+  updateNodeData: (nodeId: string, data: any) => boolean; // Update node data
+  getSelectedNode: () => string | null;               // Get currently selected node ID
+  getNodes: () => any[];                              // Get all nodes
+  getEdges: () => any[];                              // Get all edges
+}
+```
+
+## Node Data Structure Examples
+
+### Automation API Node
+```typescript
+interface AutomationApiNodeData {
+  label: string;
+  description: string;
+  method: 'GET' | 'POST' | 'PUT' | 'DELETE';
+  url: string;
+  headers: Array<{
+    key: string;
+    value: string;
+    enabled: boolean;
+  }>;
+  queryParams: Array<{
+    key: string;
+    value: string;
+    enabled: boolean;
+  }>;
+  body?: string;
+  timeout: number;
+  retryCount: number;
+  // ... other API-specific fields
+}
+```
+
+### Automation AI Formatting Node
+```typescript
+interface AutomationFormattingNodeData {
+  label: string;
+  description: string;
+  formattingType: 'basic' | 'ai-powered' | 'template';
+  aiConfig?: {
+    apiUrl: string;
+    apiKey: string;
+    model: string;           // e.g., "GPT-5 Thinking mini"
+    instruction: string;
+    temperature: number;     // e.g., 0.95
+    maxTokens?: number;      // e.g., 2048
+    systemPrompt?: string;
+  };
+  outputVariable: string;
+  outputDataType: 'String' | 'Object' | 'Array';
+  // ... other formatting-specific fields
+}
+```
+
+### Automation Start Node
+```typescript
+interface AutomationStartNodeData {
+  label: string;
+  description: string;
+  triggerType: 'manual' | 'scheduled' | 'event';
+  scheduleConfig?: {
+    frequency: 'hourly' | 'daily' | 'weekly' | 'monthly';
+    time?: string;
+    cron?: string;
+    timezone?: string;
+  };
+  eventConfig?: {
+    webhookUrl?: string;
+    eventType?: string;
+    filters?: Array<{
+      key: string;
+      value: string;
+      operator: 'equals' | 'contains' | 'startsWith' | 'endsWith';
+    }>;
+  };
+  // ... other start-specific fields
+}
+```
+
+## Complete Example: AI Model Configuration Panel
+
+Here's a complete example showing how to create an external configuration panel for AI model settings:
+
+```typescript
+import React, { useRef, useState, useEffect } from 'react';
+import { 
+  Box, 
+  Typography, 
+  TextField, 
+  Button, 
+  Card, 
+  CardContent, 
+  Grid, 
+  Select, 
+  MenuItem, 
+  FormControl, 
+  InputLabel,
+  Chip,
+  Alert
+} from '@mui/material';
+import { DiagrammingPage, DiagrammingPageRef } from '@flowuent-org/diagrams';
+
+const AIModelConfigurationPanel: React.FC = () => {
+  const diagramRef = useRef<DiagrammingPageRef>(null);
+  const [selectedNodeId, setSelectedNodeId] = useState<string | null>(null);
+  const [nodeData, setNodeData] = useState<any>(null);
+  const [formData, setFormData] = useState<any>({});
+  const [updateStatus, setUpdateStatus] = useState<'idle' | 'success' | 'error'>('idle');
+
+  // Monitor node selection changes
+  useEffect(() => {
+    const interval = setInterval(() => {
+      if (diagramRef.current) {
+        const currentSelected = diagramRef.current.getSelectedNode();
+        if (currentSelected !== selectedNodeId) {
+          setSelectedNodeId(currentSelected);
+          if (currentSelected) {
+            const data = diagramRef.current.getNodeData(currentSelected);
+            setNodeData(data);
+            setFormData(data || {});
+          }
+        }
+      }
+    }, 100);
+
+    return () => clearInterval(interval);
+  }, [selectedNodeId]);
+
+  const handleFormChange = (field: string, value: any) => {
+    setFormData(prev => ({
+      ...prev,
+      [field]: value
+    }));
+  };
+
+  const handleUpdateNode = () => {
+    if (!selectedNodeId || !diagramRef.current) return;
+
+    const success = diagramRef.current.updateNodeData(selectedNodeId, formData);
+    if (success) {
+      setUpdateStatus('success');
+      setTimeout(() => setUpdateStatus('idle'), 2000);
+    } else {
+      setUpdateStatus('error');
+      setTimeout(() => setUpdateStatus('idle'), 2000);
+    }
+  };
+
+  const renderAIConfiguration = () => {
+    if (!selectedNodeId || !nodeData) {
+      return (
+        <Card>
+          <CardContent>
+            <Typography variant="h6" color="text.secondary">
+              Select an AI Formatting node to configure
+            </Typography>
+          </CardContent>
+        </Card>
+      );
+    }
+
+    return (
+      <Card>
+        <CardContent>
+          <Typography variant="h6" gutterBottom>
+            AI Model Configuration
+          </Typography>
+          
+          <Chip 
+            label={`Node ID: ${selectedNodeId}`} 
+            size="small" 
+            sx={{ mb: 2 }} 
+          />
+
+          {updateStatus === 'success' && (
+            <Alert severity="success" sx={{ mb: 2 }}>
+              Configuration updated successfully!
+            </Alert>
+          )}
+
+          <Grid container spacing={2}>
+            <Grid item xs={12}>
+              <TextField
+                fullWidth
+                label="Model"
+                value={formData.aiConfig?.model || ''}
+                onChange={(e) => handleFormChange('aiConfig', {
+                  ...formData.aiConfig,
+                  model: e.target.value
+                })}
+              />
+            </Grid>
+
+            <Grid item xs={6}>
+              <TextField
+                fullWidth
+                label="Max Tokens"
+                type="number"
+                value={formData.aiConfig?.maxTokens || 2048}
+                onChange={(e) => handleFormChange('aiConfig', {
+                  ...formData.aiConfig,
+                  maxTokens: parseInt(e.target.value)
+                })}
+              />
+            </Grid>
+
+            <Grid item xs={6}>
+              <TextField
+                fullWidth
+                label="Temperature"
+                type="number"
+                step="0.1"
+                value={formData.aiConfig?.temperature || 0.95}
+                onChange={(e) => handleFormChange('aiConfig', {
+                  ...formData.aiConfig,
+                  temperature: parseFloat(e.target.value)
+                })}
+              />
+            </Grid>
+
+            <Grid item xs={12}>
+              <TextField
+                fullWidth
+                label="Instruction"
+                multiline
+                rows={3}
+                value={formData.aiConfig?.instruction || ''}
+                onChange={(e) => handleFormChange('aiConfig', {
+                  ...formData.aiConfig,
+                  instruction: e.target.value
+                })}
+              />
+            </Grid>
+
+            <Grid item xs={12}>
+              <TextField
+                fullWidth
+                label="API Key"
+                type="password"
+                value={formData.aiConfig?.apiKey || ''}
+                onChange={(e) => handleFormChange('aiConfig', {
+                  ...formData.aiConfig,
+                  apiKey: e.target.value
+                })}
+              />
+            </Grid>
+          </Grid>
+
+          <Box sx={{ mt: 3 }}>
+            <Button
+              variant="contained"
+              onClick={handleUpdateNode}
+              fullWidth
+            >
+              Update Configuration
+            </Button>
+          </Box>
+        </CardContent>
+      </Card>
+    );
+  };
+
+  return (
+    <Box sx={{ height: '100vh', display: 'flex' }}>
+      {/* Configuration Panel */}
+      <Box sx={{ 
+        width: 400, 
+        borderRight: '1px solid #ddd',
+        bgcolor: '#fafafa',
+        overflow: 'auto'
+      }}>
+        {renderAIConfiguration()}
+      </Box>
+
+      {/* Diagram */}
+      <Box sx={{ flex: 1 }}>
+        <DiagrammingPage
+          ref={diagramRef}
+          diagramType="automation"
+          defaultNodes={nodes}
+          defaultEdges={edges}
+          availableFunctions={[]}
+          id={1}
+        />
+      </Box>
+    </Box>
+  );
+};
+
+export default AIModelConfigurationPanel;
+```
+
+## Integration Steps for Your Team Member
+
+1. **Install the updated library** with the new node data management API
+2. **Create a ref** to the DiagrammingPage component
+3. **Monitor node selection** to detect when a node is selected
+4. **Read node data** using `getNodeData(nodeId)` method
+5. **Create configuration UI** based on the node type and data structure
+6. **Update node data** using `updateNodeData(nodeId, newData)` method
+7. **Handle success/error states** appropriately
+
+## Key Benefits
+
+- **Real-time Updates**: Changes are immediately reflected in the diagram
+- **Type Safety**: Structured data interfaces for different node types
+- **Flexible Configuration**: Support for any node data structure
+- **History Integration**: Node data changes are tracked in undo/redo
+- **Selection Awareness**: Know which node is currently selected
+- **Error Handling**: Methods return success/failure status
+
+## Common Use Cases
+
+1. **AI Model Configuration**: Update model, tokens, temperature, instructions
+2. **API Configuration**: Modify endpoints, headers, authentication
+3. **Workflow Settings**: Change trigger types, schedules, conditions
+4. **Data Formatting**: Update formatting rules, templates, variables
+5. **Authentication**: Manage API keys, tokens, credentials
+6. **Execution Parameters**: Modify timeouts, retry counts, error handling
+
+## Notes
+
+- Node data updates are immediately reflected in the diagram
+- Changes are tracked in the undo/redo history
+- The API supports partial updates (only changed fields need to be provided)
+- Node selection changes are detected automatically
+- The system handles invalid node IDs gracefully
+- All node types are supported with their specific data structures

package/packages/diagrams/README.md

@@ -0,0 +1,7 @@
+# common
+
+This library was generated with [Nx](https://nx.dev).
+
+## Running unit tests
+
+Run `nx test common` to execute the unit tests via [Jest](https://jestjs.io).