@flowuent-org/diagramming-core 1.3.10 → 1.4.1

package/packages/diagrams/GOOGLE_SHEETS_IMPLEMENTATION.md

@@ -1,233 +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.
-
+# 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.
+