moodle-auto-client

🚀 Automate Moodle login, session extraction, and API data capture — powered by Playwright.

📦 Installation

npm install moodle-auto-client

or using yarn:

yarn add moodle-auto-client

Prerequisites: Make sure you have Playwright browsers installed:

npx playwright install

⚙️ Features

• 🔐 Automated Login - Secure Moodle authentication
• 📊 API Data Capture - Automatically intercepts and saves Moodle API responses
• 💾 Structured Storage - Saves data to organized JSON files
• 🕵️ Session Management - Extracts cookies and session tokens
• 🚀 Headless Operation - Runs silently without browser UI
• 📁 Modular Architecture - Easy to extend and customize
• 🎯 NIE Student Portal Integration - Automated attendance and grade extraction
• 📅 Course Management - Extract course details, timetables, and schedules

Captured Data:

• 📚 Enrolled Courses
• 📅 Calendar Events & Monthly Views
• 🔔 Notifications
• 🕐 Recent Courses
• 🍪 Session Data & Cookies
• 👨‍🎓 Student Information & Profiles
• 📊 Attendance Records & Statistics
• 📝 Course Registration Details
• 🎓 CIE (Continuous Internal Evaluation) Marks
• 👨‍🏫 Proctor Information

🚀 Quick Start

1. Setup Environment

# Copy environment template
cp .env.sample .env

# Edit .env with your credentials
[email protected]
PASS=your_password
NIE_USERNAME=your_nie_username
NIE_PASSWORD=your_nie_password
NIE_DOB=DD/MM/YYYY

2. Basic Usage

import { moodle, parentsNie } from 'moodle-auto-client';

// Run Moodle automation
(async () => {
    await moodle('https://your-moodle-instance.edu');
})();

// Run NIE Student Portal automation
(async () => {
    await parentsNie();
})();

3. Advanced Usage

import { 
    loginToMoodle, 
    extractSessionData, 
    saveDataToFiles,
    loginToNIEStudentPortal,
    extractDashboardData
} from 'moodle-auto-client/utils/';

// Custom Moodle implementation
(async () => {
    const session = await loginToMoodle('https://your-moodle-url.edu');
    const data = await extractSessionData(session);
    await saveDataToFiles(data);
})();

// Custom NIE implementation
(async () => {
    const { page, browser } = await loginToNIEStudentPortal();
    const data = await extractDashboardData(page);
    await saveDataToFiles(data, 'nie_student_data');
    await browser.close();
})();

📂 Project Structure

moodle-auto-client/
│
├── 📄 package.json              # Dependencies and scripts
├── 📄 package-lock.json         # Lock file
├── 📄 README.md                 # This file
├── 📄 LICENSE.txt               # MIT License
├── 📄 .gitignore                # Git ignore rules
├── 📄 .env.sample               # Environment template
├── 📄 playwright.config.js      # Playwright configuration
│
├── 📁 src/
│   └── 📄 index.js              # Main entry point that orchestrates the automation
│
├── 📁 utils/
│   ├── 📁 Moodle/
│   │   ├── 📄 loginToMoodle.js          # Core login automation
│   │   ├── 📄 setupRequestInterception.js # API response capturing
│   │   ├── 📄 checkLoginStatus.js       # Login verification
│   │   ├── 📄 extractSessionData.js     # Session/cookie extraction
│   │   └── 📄 saveDataToFiles.js        # Data storage utilities
│   │
│   └── 📁 ParentsNie/
│       ├── 📄 loginToNIEStudentPortal.js    # NIE portal login automation
│       ├── 📄 extractDashboardData.js       # Dashboard data extraction
│       ├── 📄 extractStudentInfo.js         # Student profile extraction
│       ├── 📄 extractCoursesData.js         # Course details extraction
│       ├── 📄 extractAttendanceData.js      # Attendance data extraction
│       ├── 📄 extractProctorDetails.js      # Proctor information extraction
│       └── 📄 saveDataToFiles.js           # NIE-specific data storage
│
└── 📄 index.js                  # Package exports

🧩 API Reference

Main Exports

import { moodle, parentsNie } from 'moodle-auto-client';

/**
 * Moodle automation function
 * @param {string} url - Moodle instance URL
 */
await moodle('https://moodle.yourschool.edu');

/**
 * NIE Student Portal automation
 */
await parentsNie();

Utility Functions

import { 
    // Moodle utilities
    loginToMoodle,
    setupRequestInterception,
    checkLoginStatus,
    extractSessionData,
    saveDataToFiles,
    
    // NIE utilities
    loginToNIEStudentPortal,
    extractDashboardData,
    extractStudentInfo,
    extractCoursesData,
    extractAttendanceData,
    extractProctorDetails
} from 'moodle-auto-client/utils/';

// Individual component usage
const page = await loginToMoodle(url);
await setupRequestInterception(page);
const status = await checkLoginStatus(page);
const session = await extractSessionData(context);
await saveDataToFiles(capturedData);

📊 Output

Moodle Data (moodle_data/)

moodle_data/
├── 📄 courses_2024-01-15T10-30-45Z.json
├── 📄 events_2024-01-15T10-30-45Z.json
├── 📄 notifications_2024-01-15T10-30-45Z.json
├── 📄 recent_courses_2024-01-15T10-30-45Z.json
├── 📄 calendar_2024-01-15T10-30-45Z.json
└── 📄 all_data_2024-01-15T10-30-45Z.json

NIE Student Data (nie_student_data/)

nie_student_data/
├── 📄 student_info_2024-01-15T10-30-45Z.json
├── 📄 courses_2024-01-15T10-30-45Z.json
├── 📄 attendance_2024-01-15T10-30-45Z.json
├── 📄 proctor_details_2024-01-15T10-30-45Z.json
└── 📄 combined_data_2024-01-15T10-30-45Z.json

Data Structure Examples:

Student Information:

{
  "name": "RAHUL",
  "usn": "4NI22IS064",
  "details": "B.E-IS, SEM 05, SEC B",
  "lastUpdated": "Last Updated On: 31/10/2025"
}

Course Attendance:

{
  "courseCode": "BIS501",
  "courseName": "Software Engineering & Project Management",
  "percentage": 95,
  "status": "Good",
  "detailedData": {
    "presentCount": 18,
    "absentCount": 1,
    "remainingClasses": 23,
    "present": [...],
    "absent": [...],
    "faculty": "Rajesh D"
  }
}

Proctor Details:

{
  "name": "Mr. Raj",
  "contact": "9845716829"
}

⚙️ Configuration

Environment Variables (.env)

# Moodle Credentials
[email protected]
PASS=your_password

# NIE Student Portal Credentials
NIE_USERNAME=your_username
NIE_PASSWORD=your_password
NIE_DOB=05/12/2006

# Optional: Customize output directories
MOODLE_DATA_DIR=custom_moodle_data
NIE_DATA_DIR=custom_nie_data

Playwright Config (playwright.config.js)

// Default configuration
module.exports = {
    timeout: 60000,
    headless: true,
    slowMo: 100,
    viewport: { width: 1280, height: 720 }
};

🎯 NIE Student Portal Features

Automated Data Extraction:

• ✅ Student Profile: Name, USN, Program, Semester, Section
• ✅ Course Registration: All registered courses with details
• ✅ Attendance Records: Detailed class-wise attendance with percentages
• ✅ CIE Marks: Continuous Internal Evaluation scores
• ✅ Proctor Information: Proctor name and contact details
• ✅ Academic Calendar: Events and important dates
• ✅ Timetable: Class schedules and timings

Smart Navigation:

• 🔄 Tab-based Processing: Uses multiple tabs for concurrent data extraction
• 🎯 Stale Element Handling: Automatic recovery from navigation issues
• ⚡ Batch Processing: Processes courses in batches for optimal performance
• 🔒 Session Management: Maintains secure login sessions

🔧 Extending Functionality

Adding New API Endpoints (Moodle)

// In setupRequestInterception.js
if (url.includes('your_new_endpoint')) {
    const data = await response.json();
    capturedData.newData = data;
}

Adding New Data Extractors (NIE)

// Create new extractor in utils/ParentsNie/
export async function extractNewData(page, capturedData) {
    // Your extraction logic here
    const newData = await page.evaluate(() => {
        // Extract data from page
        return { /* extracted data */ };
    });
    
    capturedData.newData = newData;
}

⚠️ Important Notes

• 🔒 Security: Credentials are stored in .env file, never in code
• 📵 Compliance: Use in accordance with your institution's policies
• 🛡️ 2FA: Currently doesn't support two-factor authentication
• 🔍 CAPTCHA: May not work with CAPTCHA-protected login forms
• ⏱️ Rate Limiting: Includes delays to avoid overwhelming servers
• 📊 Data Accuracy: Extracted data should be verified with official sources
• 🔄 Session Timeouts: NIE portal sessions may timeout during long operations

🐛 Troubleshooting

Common Issues:

1. Browser not installed:

   npx playwright install

2. Login fails:

   • Verify credentials in .env
   • Check if URLs are accessible
   • Ensure date format matches NIE requirements (DD/MM/YYYY)

3. No data captured:

   • Increase wait times in configuration
   • Check network connectivity
   • Verify element selectors match current portal structure

4. Stale element errors:

   • The tab-based approach should handle this automatically
   • Check for portal layout changes

5. NIE Date of Birth issues:

   • Ensure DOB format is exactly DD/MM/YYYY
   • Verify the DOB matches your registered records

🚀 Performance Tips

1. Use Headless Mode: Faster execution without UI
2. Batch Processing: NIE automation processes courses in batches
3. Concurrent Tabs: Multiple tabs for parallel data extraction
4. Smart Waiting: Adaptive wait times based on network conditions
5. Error Recovery: Automatic retry mechanisms for failed operations

🤝 Contributing

Areas for Contribution:

• ✅ Two-factor authentication support
• ✅ CAPTCHA handling
• ✅ Additional API endpoints
• ✅ More export formats (CSV, Excel)
• ✅ Better error handling
• ✅ Additional educational portals
• ✅ Mobile app integration
• ✅ Real-time notifications

Development Setup:

git clone https://github.com/kaushal-Prakash/moodle-auto-client.git
cd moodle-auto-client
npm install
cp .env.sample .env
# Edit .env with your credentials
npm test

🪪 License

MIT License - see LICENSE.txt for details.

Built with ❤️ for students and developers automating their educational workflows.