KFUPM Course Scraper

A TypeScript CLI tool to scrape course offerings from KFUPM's registrar website.

Installation

Local Development

1. Clone or download the repository
2. Install dependencies:

npm install

3. Install Playwright browsers:

npx playwright install chromium

Global Installation

Once published to npm:

npm i -g @mmogib/kfupm-courses

This will also install the Chromium browser used by Playwright.

For local linking during development (no npm publish needed):

npm run setup

This installs dependencies, installs Playwright Chromium, builds, and links the CLI globally.

Usage

List Available Departments

kfupm-courses list-departments
# or
kfupm-courses list
# or
kfupm-courses depts

Scrape Courses

There are multiple ways to scrape courses:

Option 1: Using explicit flags

kfupm-courses scrape --term 251 --dept "Mathematics"
kfupm-courses scrape -t 252 -d "Math"

Option 2: Using positional arguments

kfupm-courses 251 "Math"
kfupm-courses 252 "Computer Science"

Option 3: Specify custom output directory

kfupm-courses scrape -t 251 -d "Math" -o "/path/to/output"
kfupm-courses 252 "ICS" --output "C:\MyFolder"

Department Shortcuts

You can use department shortcuts instead of full names:

• Math or Mathematics → Mathematics
• CS or ICS → Information & Computer Science
• ME or Mechanical → Mechanical Engineering
• EE or Electrical → Electrical Engineering
• PE or Petroleum → Petroleum Engineering
• And many more...

Use kfupm-courses list to see all available departments and their shortcuts.

Examples

# Scrape Math courses for term 251
kfupm-courses 251 "Math"

# Scrape Computer Science courses for term 252
kfupm-courses scrape -t 252 -d "CS"

# Scrape Electrical Engineering with custom output
kfupm-courses 253 "EE" -o "D:\Courses"

# List all departments
kfupm-courses list-departments

Output

CSV files are saved with the following format:

term{TERM}_{DEPT}_{TIMESTAMP}.csv

Example: term251_mathematics_2024-12-07T15-30-45.csv

Default output directory: the current working directory

Development

Available Scripts

# One-command setup (install, build, link)
npm run setup

# Build and link globally
npm run build-link

# Build only
npm run build

# Development mode (no build required)
npm run dev -- scrape -t 251 -d "Math"

# Test run (builds first)
npm start -- 251 "Math"

CSV Format

The output CSV includes the following columns:

• Course-Sec
• Activity
• CRN
• Course Name
• Instructor
• Day
• Time
• Location
• Instructional Method

Error Handling

The tool provides clear error messages for:

• Invalid term numbers
• Invalid department names
• Network errors
• Missing data

Requirements

• Node.js >= 16
• npm >= 7
• Internet connection

License

MIT