Lectful n8n Node

A custom n8n node for integrating with the Lectful API.

Features

• User Management: Get user information and list users
• Course Management: Get course details and list courses
• Authentication: Secure API key and base URL configuration
• Central API Integration: Full access to Lectful Central API for admin operations
  • Tenant Management (list tenants, generate tokens)
  • Blog Management (CRUD operations for blog posts)
  • Image Management (upload images)
  • BuilderX AI Integration (AI manifests and templates)
  • Form Submissions (with webhook support)
  • Health Checks (startup, liveness, readiness)

Installation

For Production Use

npm install n8n-nodes-lectful

For Local Development/Testing

1. Clone this repository:

   git clone <your-repo-url>
   cd LectfulTenantn8n

2. Install dependencies:

   npm install

3. Build the project:

   npm run build

4. Start n8n with Docker Desktop:

   docker-compose up -d

5. Access n8n:

   • Open your browser and go to http://localhost:5678
   • Login with:
     • Username: admin
     • Password: password

6. Install your custom node (Choose one method):

   Method 1: Using Community Nodes (Recommended)

   • In n8n, go to Settings → Community Nodes
   • Click "Install a community node"
   • Search for "n8n-nodes-lectful" and install it
   • If not found, use Method 2 or 3

   Method 2: Using npm link (Local Development)

   # In your project directory
   npm link
      
   # In the n8n container
   docker exec -it n8n npm link n8n-nodes-lectful

   Method 3: Direct folder installation

   • Copy the nodes/Lectful folder to the n8n custom nodes directory
   • The folder is already mounted at /home/node/.n8n/custom in the container
   • Restart n8n: docker-compose restart

   Method 4: Using n8n CLI (if available)

   docker exec -it n8n n8n-node-dev install /home/node/.n8n/custom/Lectful

Configuration

Credentials

1. In n8n, go to Credentials
2. Add new "Lectful API" credentials
3. Configure:
   • API Key: Your Lectful API key
   • Base URL: Your Lectful API base URL (e.g., https://mooc.vipay.tn)

Usage

1. Create a new workflow
2. Add either the "Lectful" node (for tenant operations) or "Lectful Central" node (for admin operations)
3. Configure authentication:
   • Authentication Mode: Choose between:
     • Use Stored Credentials: Use credentials configured in n8n (recommended for static configurations)
     • Manual Configuration: Provide base URL and API key manually (useful for dynamic configurations)
   • Base URL Override: Required when using Manual Configuration mode
   • API Key Override: Required when using Manual Configuration mode
4. Select a resource and operation, then configure the operation parameters
5. Test the connection

Node Types

Lectful Node (Tenant API)

• Purpose: Interact with tenant-specific APIs
• Use Case: Operations that require tenant context (user management, course management)
• Base URL: Automatically appends /api/v1 to your base URL

Lectful Central Node (Central API)

• Purpose: Interact with the central admin API
• Use Case: Administrative operations, cross-tenant management, system-wide operations
• Base URL: Automatically appends /api/v1 to your base URL (except for health checks and form submissions)

Central API Resources

The Lectful Central node provides access to the following resources:

Authentication

• Admin Login: Authenticate admin users and receive Sanctum API tokens

Tenant Management

• List Tenants: Retrieve paginated list of all tenants with search and pagination
• Generate Tenant Token: Generate authentication tokens for specific tenants

Blog Management

• List Posts: Get all blog posts with pagination
• Get Post by ID/Slug: Retrieve specific blog posts
• Create Post: Create new blog posts
• Update Post: Modify existing blog posts

Image Management

• Upload Image: Upload images to the central system (JPEG, PNG, JPG, GIF, max 10MB)

BuilderX AI Integration

• Get All AI Manifests: Retrieve available AI manifests for BuilderX widgets
• Get AI Manifest Batch: Get manifests for specific widgets
• Apply AI Template: Apply AI-generated templates to create new pages

Form Submissions

• Submit Form: Submit forms with optional webhook notifications

Health Checks

• Startup: Check if the application is starting up
• Liveness: Check if the application is alive and running
• Readiness: Check if the application is ready to serve requests

Authentication Modes

The node supports two authentication modes:

Use Stored Credentials (Default)

• Uses credentials configured in n8n Credentials section
• Recommended for static configurations
• No additional parameters required

Manual Configuration

• Provides base URL and API key manually
• Useful for dynamic configurations
• Note: You can leave the credentials field empty when using this mode
• Both Base URL Override and API Key Override are required

This is useful when you need to:

• Connect to different environments (dev, staging, prod) dynamically
• Use different API keys for different operations
• Pass credentials from previous nodes in the workflow
• Test different API endpoints without storing credentials

Visual Interface

The node provides clear visual guidance:

• Manual Configuration mode: Shows a "Credentials Note" explaining that credentials can be left empty
• Parameter visibility: Override parameters only appear when Manual Configuration is selected

Development

Building

npm run build

Linting

npm run lint

Publishing

npm run publish

Troubleshooting

Node Not Appearing in n8n

• Ensure you've installed the node correctly using one of the methods above
• Check that the node is built (npm run build)
• Restart n8n after installation: docker-compose restart
• Check n8n logs: docker-compose logs n8n

Credential Connection Issues ("Couldn't connect with these settings")

This is a common issue with custom nodes. Here are several solutions:

Solution 1: Use Manual Configuration Mode

• Switch to "Manual Configuration" mode in the node
• Leave the credentials field empty
• Provide your base URL and API key directly in the node parameters
• This bypasses n8n's credential validation system

Solution 2: Test Credentials Outside n8n

Use the provided test script to verify your credentials work:

# Install axios if not already installed
npm install axios

# Edit test-credentials.js with your actual credentials
# Then run:
node test-credentials.js

Solution 3: Check Base URL Format

• Ensure your base URL doesn't have trailing slashes
• Use format: https://yourdomain.com (not https://yourdomain.com/)
• The node automatically appends /api/v1 where needed

Solution 4: Verify API Endpoints

• Check if your base URL is accessible: curl https://yourdomain.com/
• Verify health check endpoint: curl https://yourdomain.com/api/health-check/liveness
• Ensure your API key has proper permissions

Solution 5: Credential Test Endpoint

The credential test uses the root endpoint (/) to verify basic connectivity. If this fails:

• Check if your server responds to root requests
• Verify firewall/network settings
• Check if the domain resolves correctly

Invalid URL Error

• Make sure your base URL doesn't have trailing slashes
• The node automatically strips trailing slashes from the base URL
• Check the browser console for debug logs

Docker Issues

• Ensure Docker Desktop is running
• Check if port 5678 is available
• Use docker-compose logs n8n to view logs
• Restart the container: docker-compose restart

Installation Issues

• If "Install from folder" is not available, use Method 2 (npm link) or Method 3 (direct copy)
• Make sure the node folder is properly mounted in the container
• Check file permissions in the mounted volume

API Documentation

For detailed API documentation, visit: http://lectful.test/developers/api-docs

License

This project is licensed under the MIT License.

Support

For support, please refer to:

• Lectful API Documentation
• n8n Community Nodes Documentation
• n8n Community Forum

Changelog

1.0.11

• Added Authentication Mode toggle (Use Stored Credentials / Manual Configuration)
• Added optional Base URL and API Key override parameters
• Support for dynamic credential configuration on the fly
• Improved flexibility for multi-environment workflows
• Enhanced user experience with conditional parameter display

1.0.0

• Initial release
• Support for User and Course resources
• Basic CRUD operations (Get, Get All)

Examples

Basic Tenant Operations

See examples/authentication-modes-workflow.json for examples of using the Lectful node with different authentication modes.

Central API Operations

See examples/central-api-workflow.json for examples of using the Lectful Central node for various admin operations.

Dynamic Credentials

See examples/dynamic-credentials-workflow.json for examples of using dynamic credential configuration.