herel/kdrive-n8n
1
0
Fork 0
Code Issues Pull Requests Actions Packages Projects Releases Wiki Activity
Files
main
kdrive-n8n/IMPLEMENTATION_SUMMARY.md
Rene Luria c609d6c1ee LGPL-3.0
2025-12-22 18:01:50 +01:00

8.7 KiB
Raw Permalink Blame History

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

# 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.

Reference in New Issue View Git Blame Copy Permalink