UOEL Student Portal SDK

An unofficial, strongly-typed TypeScript SDK for programmatic access to the University of Education, Lahore (UOEL) Student Portal.

This SDK abstracts away the complexities of the portal's authentication flow, CSRF token management, and session handling, providing clean and structured data for a student's profile, grades, and semester records.

Features

• Robust Authentication: Handles the multi-step login process, including CSRF token extraction and HTTP 403 bypass.
• Auto-Reauthentication: Automatically detects expired sessions (HTTP 419/401) and re-authenticates behind the scenes.
• Session Management: Transparently manages session cookies (XSRF-TOKEN, ums_ue_student_portal_session) using an in-memory cookie jar.
• Structured Data Extraction:
  • Student Profile: Extracts comprehensive details including personal info, academic standing (CGPA, required credits, probation limits), and previous academic history.
  • Semester Data: Retrieves detailed course-wise breakdowns (Mid, Practical, Sessional, Final, Total Score, Grade, Grade Point) along with the semester summary (GPA, Credits Earned, Status).
• Strongly Typed: Built with TypeScript, providing full intellisense and interface definitions for all scraped data.

Installation

Currently, this SDK is intended to be used locally or compiled as part of a larger project. Ensure you have Node.js and dependencies installed.

npm install
# or
yarn install

Quick Start

import { UOELStudentPortal } from './src/client';
import { SemesterBatchCode } from './src/types';

async function main() {
  const portal = new UOELStudentPortal();

  try {
    // 1. Authenticate with your portal credentials
    console.log('Logging in...');
    await portal.login({
      username: 'your-username', // e.g. bsf...
      password: 'your-password'
    });
    console.log('Login successful!');

    // 2. Fetch the authenticated student's profile
    console.log('Fetching profile...');
    const profile = await portal.getStudentProfile();
    console.log(`Welcome, ${profile.name}! (CGPA: ${profile.cgpa})`);
    console.log('Profile Details:', profile);

    // 3. Fetch data for a specific semester
    console.log('Fetching semester data for Fall 2023...');
    const semesterData = await portal.getSemesterData('2304');
    console.log(`Semester: ${semesterData.semesterName}`);
    console.log(`GPA: ${semesterData.summary.gpa}`);
    console.log('Courses:', semesterData.courses);

  } catch (error) {
    console.error('Error occurred:', error);
  }
}

main();

API Reference

UOELStudentPortal

The main class orchestrating communication with the portal.

login(credentials: LoginCredentials): Promise<void>

Authenticates the user, extracts necessary CSRF tokens, and establishes an active session. Stores credentials internally to allow auto-reauthentication if the session expires during subsequent requests.

getStudentProfile(): Promise<StudentProfile>

Fetches the student profile from /student-profile and parses it into a strongly typed StudentProfile object, including academic history.

getSemesterData(semBatch: SemesterBatchCode): Promise<SemesterDataResponse>

Retrieves course grades and summary information for a given semester batch (e.g., '2304' for Fall 2023).

Data Types (Highlights)

StudentProfile

Contains personal info, ID numbers, CGPA, total credits, required GPA for probation, program details, and an array of AcademicRecord (previous degrees like Matriculation/Intermediate).

SemesterDataResponse

Includes the semesterName (e.g. "Fall 2023"), a summary object (GPA, total courses, credits earned, status), and an array of courses detailing marks breakdown (mid, practical, sessional, final, score, grade, gradePoint).

SemesterBatchCode

A union of supported batch codes corresponding to specific semesters (e.g., '2304' for Fall 2023, '2402' for Spring 2024, etc.).

Error Handling

The SDK exposes specific error classes to help you handle different failure modes gracefully:

• AuthenticationError: Thrown when invalid credentials are provided.
• SessionExpiredError: Thrown when the session expires and auto-reauth cannot proceed (e.g., missing stored credentials).
• ParseError: Thrown when the SDK fails to extract required data from the HTML payload (e.g., if the portal's markup changes).

Disclaimer

This is an unofficial SDK. It relies on web scraping and intercepting XHR requests from the UOEL Student Portal. Changes to the portal's underlying HTML structure or authentication flow may break this SDK. Please use responsibly.