268 lines
8.7 KiB
Markdown
268 lines
8.7 KiB
Markdown
# kDrive n8n Node Implementation Summary
|
|
|
|
## Overview
|
|
|
|
This implementation provides a comprehensive n8n node for interacting with the Infomaniak kDrive API. The node supports the most common file management operations including drive management, file operations, and directory operations.
|
|
|
|
## Architecture
|
|
|
|
### Files Structure
|
|
|
|
```
|
|
n8n-nodes-kdrive/
|
|
├── package.json # Node package configuration
|
|
├── src/
|
|
│ ├── index.ts # Main export file
|
|
│ └── nodes/
|
|
│ └── KDrive/
|
|
│ ├── KDrive.node.ts # Main node implementation
|
|
│ ├── GenericFunctions.ts # API helper functions
|
|
│ ├── KDriveCredentials.api.ts # Credentials definition
|
|
│ └── kdrive.svg # Node icon
|
|
├── README.md # User documentation
|
|
└── IMPLEMENTATION_SUMMARY.md # This file
|
|
```
|
|
|
|
### Key Components
|
|
|
|
#### 1. KDrive.node.ts
|
|
|
|
The main node implementation with:
|
|
|
|
- **Node Definition**: Display name, icon, group, version, and description
|
|
- **Authentication**: API key authentication method
|
|
- **Resource Types**: Drive, File, Directory
|
|
- **Operations**: Comprehensive set of operations for each resource type
|
|
- **Parameter Handling**: Dynamic parameter display based on selected operation
|
|
- **Execution Logic**: Main execute() method that handles all operations
|
|
|
|
#### 2. GenericFunctions.ts
|
|
|
|
API helper functions:
|
|
|
|
- **kdriveApiRequest()**: Generic API request handler
|
|
- Handles different HTTP methods (GET, POST, DELETE, etc.)
|
|
- Manages authentication headers
|
|
- Processes query parameters and form data
|
|
- Error handling
|
|
|
|
- **handleApiError()**: Error processing and formatting
|
|
|
|
#### 3. KDriveCredentials.api.ts
|
|
|
|
Credentials management:
|
|
- API key credential type
|
|
- Secure storage of API keys
|
|
- Integration with n8n credentials system
|
|
|
|
#### 4. kdrive.svg
|
|
|
|
Custom icon for the node in the n8n UI
|
|
|
|
## Supported Operations
|
|
|
|
### Drive Operations
|
|
|
|
1. **List Drives** (`/2/drive` - GET)
|
|
- Lists all accessible drives for the authenticated user
|
|
- Returns drive IDs, names, and basic information
|
|
|
|
2. **Get Drive Info** (`/2/drive/{drive_id}/settings` - GET)
|
|
- Gets detailed information about a specific drive
|
|
- Includes drive settings and configuration
|
|
|
|
### File Operations
|
|
|
|
1. **List Files** (`/3/drive/{drive_id}/files/{file_id}/files` - GET)
|
|
- Lists files in a specific directory
|
|
- Supports pagination and filtering
|
|
- Can list root directory or any subdirectory
|
|
|
|
2. **Get File Info** (`/3/drive/{drive_id}/files/{file_id}` - GET)
|
|
- Gets detailed metadata about a file
|
|
- Includes size, type, creation/modification dates, etc.
|
|
|
|
3. **Upload File** (`/3/drive/{drive_id}/upload` - POST)
|
|
- Uploads a file to kDrive
|
|
- Supports base64 encoded file data
|
|
- Can specify target directory
|
|
|
|
4. **Download File** (`/2/drive/{drive_id}/files/{file_id}/download` - GET)
|
|
- Downloads a file from kDrive
|
|
- Returns binary data for file download
|
|
|
|
5. **Delete File** (`/2/drive/{drive_id}/files/{file_id}` - DELETE)
|
|
- Moves a file to trash (soft delete)
|
|
- File can be restored from trash
|
|
|
|
6. **Search Files** (`/3/drive/{drive_id}/files/search` - GET)
|
|
- Searches for files by name or content
|
|
- Supports searching in trash
|
|
- Advanced filtering options
|
|
|
|
7. **Get File Versions** (`/3/drive/{drive_id}/files/{file_id}/versions` - GET)
|
|
- Gets version history of a file
|
|
- Shows previous versions and restoration points
|
|
|
|
### Directory Operations
|
|
|
|
1. **Create Directory** (`/3/drive/{drive_id}/files/{file_id}/directory` - POST)
|
|
- Creates a new directory
|
|
- Can be created in root or any subdirectory
|
|
- Returns the new directory ID
|
|
|
|
2. **Create File** (`/3/drive/{drive_id}/files/{file_id}/file` - POST)
|
|
- Creates a new file with content
|
|
- Supports text content
|
|
- Can be created in any directory
|
|
|
|
## API Version Strategy
|
|
|
|
The implementation uses a mixed approach with API versions:
|
|
|
|
- **v2 endpoints**: Used for core operations that are stable
|
|
- `/2/drive` - Drive listing
|
|
- `/2/drive/{drive_id}/files/{file_id}/download` - File download
|
|
- `/2/drive/{drive_id}/files/{file_id}` - File deletion
|
|
|
|
- **v3 endpoints**: Used for more advanced operations
|
|
- `/3/drive/{drive_id}/files/{file_id}/files` - File listing
|
|
- `/3/drive/{drive_id}/files/{file_id}` - File info
|
|
- `/3/drive/{drive_id}/upload` - File upload
|
|
- `/3/drive/{drive_id}/files/search` - File search
|
|
|
|
This approach ensures compatibility while taking advantage of newer features.
|
|
|
|
## Authentication
|
|
|
|
The node uses Bearer Token authentication:
|
|
|
|
- **API Key**: Required for all operations
|
|
- **Authentication Header**: `Authorization: Bearer {api_key}`
|
|
- **Secure Storage**: API key is stored securely in n8n credentials
|
|
|
|
## Error Handling
|
|
|
|
Comprehensive error handling is implemented:
|
|
|
|
- **Network Errors**: Handles connection issues and timeouts
|
|
- **API Errors**: Processes HTTP status codes and error messages
|
|
- **Authentication Errors**: Detects and reports invalid credentials
|
|
- **Validation Errors**: Validates input parameters before API calls
|
|
- **Continue on Fail**: Supports n8n's continue-on-fail functionality
|
|
|
|
## Parameter Handling
|
|
|
|
The node uses dynamic parameter display:
|
|
|
|
- **Conditional Display**: Parameters show/hide based on selected operation
|
|
- **Required Fields**: Enforces required parameters for each operation
|
|
- **Default Values**: Provides sensible defaults (e.g., "root" for parent directory)
|
|
- **Data Types**: Uses appropriate input types (string, boolean, etc.)
|
|
|
|
## Response Handling
|
|
|
|
Different response types are supported:
|
|
|
|
- **JSON Responses**: For most operations (drive info, file listing, etc.)
|
|
- **Binary Responses**: For file downloads
|
|
- **Error Responses**: Formatted error messages
|
|
|
|
## Usage Examples
|
|
|
|
### Basic Workflow: Upload and List Files
|
|
|
|
1. **List Drives**: Get available drives
|
|
2. **List Files**: List files in root directory
|
|
3. **Upload File**: Upload a new file
|
|
4. **List Files Again**: Verify the file was uploaded
|
|
|
|
### Advanced Workflow: File Management
|
|
|
|
1. **Search Files**: Find files matching criteria
|
|
2. **Get File Info**: Get details about specific files
|
|
3. **Create Directory**: Organize files
|
|
4. **Move Files**: (Would require additional implementation)
|
|
5. **Delete Files**: Clean up old files
|
|
|
|
## Limitations and Future Enhancements
|
|
|
|
### Current Limitations
|
|
|
|
1. **No File Moving**: Cannot move files between directories
|
|
2. **No File Copying**: Cannot copy files
|
|
3. **No File Sharing**: Cannot manage file sharing permissions
|
|
4. **No Batch Operations**: Operations are performed one at a time
|
|
5. **No Webhooks**: No real-time event handling
|
|
|
|
### Potential Future Enhancements
|
|
|
|
1. **File Moving/Copying**: Add operations to move/copy files
|
|
2. **Sharing Management**: Add sharing and permission operations
|
|
3. **Batch Operations**: Support for bulk operations
|
|
4. **Webhook Support**: Real-time event handling
|
|
5. **Advanced Search**: More search filters and options
|
|
6. **Trash Management**: Restore from trash, permanent delete
|
|
7. **File Preview**: Generate file previews
|
|
8. **File Conversion**: Convert between file formats
|
|
|
|
## Testing
|
|
|
|
The node includes basic structure testing:
|
|
|
|
- **File Existence Check**: Verifies all required files are present
|
|
- **JSON Validation**: Ensures package.json is valid
|
|
- **TypeScript Syntax**: Basic syntax checking
|
|
|
|
## Build Process
|
|
|
|
```bash
|
|
# Install dependencies
|
|
npm install
|
|
|
|
# Build the node
|
|
npm run build
|
|
|
|
# The built files will be in the dist/ directory
|
|
```
|
|
|
|
## Installation in n8n
|
|
|
|
1. **Copy the built files** to your n8n custom nodes directory
|
|
2. **Restart n8n** to load the new node
|
|
3. **Configure credentials** with your kDrive API key
|
|
4. **Start using** the kDrive node in your workflows
|
|
|
|
## Dependencies
|
|
|
|
- **n8n-workflow**: Core n8n workflow types and interfaces
|
|
- **request**: HTTP request library (included in n8n)
|
|
- **TypeScript**: For type-safe development
|
|
|
|
## Compatibility
|
|
|
|
- **n8n Version**: Compatible with recent n8n versions
|
|
- **kDrive API**: Uses both v2 and v3 API endpoints
|
|
- **Browser Support**: Works in n8n's browser-based environment
|
|
|
|
## Security Considerations
|
|
|
|
- **API Key Security**: API keys are stored securely
|
|
- **HTTPS**: All API calls use HTTPS
|
|
- **Input Validation**: Basic input validation is implemented
|
|
- **Error Handling**: Sensitive error details are not exposed
|
|
|
|
## Performance Considerations
|
|
|
|
- **Pagination**: Large file listings should use pagination
|
|
- **Batch Processing**: For many files, consider batch processing
|
|
- **Rate Limiting**: Be aware of API rate limits
|
|
- **File Size**: Large file uploads/downloads may take time
|
|
|
|
## License
|
|
|
|
This project is licensed under the LGPL-3.0 License.
|
|
|
|
## Conclusion
|
|
|
|
This implementation provides a solid foundation for kDrive integration in n8n. It covers the most common use cases and provides a clean, well-structured codebase that can be easily extended with additional functionality as needed. |