A node library that provides a programmatic API for GUC students, implementing the functionality of the admin system (currently for students).
The library uses puppeteer, a chromium headless browser. Since the GUC has no API (as of the time of writing this), this solution might not be the fastest, but it is the best that can be done for now.
The implementation covers the perspective of a student, if any staff members would like to contribute to include their own functionalities, please check the contribution section.
IMPORTANT: If you're experiencing unexpected errors (errors that are not defined by the package), you might want to launch your browser in a non-headless mode as described. Mostly it's due to a system error, which is to be implemented.
- Full transcript of the student in a relatively fast time (without having to wait a minute between requests)
- Current semester's grades (Course work & Midterms)
- Current semester schedule
- Reports specific errors when the GUC system is down, course evaluation is required, etc.
Requires Node 8.9.0+ due to puppeteer's requirements.
npm i guc-clientNote: When you install the package, it installs Puppeteer, which in turn downloads a recent version of Chromium (~170MB Mac, ~282MB Linux, ~280MB Win) that is guaranteed to work with the API. To skip the download, please check Skipping Chromium Download.
First require the client class, and set the credentials object
const { GucClient, errors } = require('guc-client');
const credentials = { username: 'john.doe', password: '123' };The following is a basic example for fetching the grades, while catching an error if the authentication failed.
The implementation is based on promises, it is recommended to use async/await for easier syntax
(async () => {
try {
const client = await GucClient.create(credentials);
const grades = await client.getGrades();
console.log(grades);
await client.terminate();
} catch (error) {
if (error instanceof errors.InvalidCredentialsError) {
console.log('Invalid username or password!');
}
}
})();Or using normal then/catch syntax as so
GucClient.create(credentials)
.then(instance => {
instance.getGrades().then(grades => {
console.log(grades);
instance.terminate();
});
})
.catch(error => {
if (error instanceof errors.InvalidCredentialsError) {
console.log('Invalid username or password!');
}
});- The
GucClient.createis asynchronous, and it can throw an error, mainly for invalid credentials, but also if the GUC system is down. You should always handle such errors as described in the errors-section. - You must call the
.terminate()function after your code is no longer using the client, andawaitit, or else the application process won't stop (the spawned browser process won't be closed otherwise).
Since the library is written in TypeScript, the typing will be skipped in the docs as they can be inferred (use an editor with Intellisense for easier development)
A factory function that asynchronously creates a client instance (given the user's login information), it tests the system by logging in with the provided credentials, and can throw any of the following system errors:
InvalidCredentialsErrorSystemErrorUnknownSystemError
Returns the full transcript (an array of years) for the logged in student. The function may throw EvaluationRequiredError if the GUC system is requiring evaluation before showing the transcript.
Example return value, tap to expand
An array of years as the following
[
{
"year": "2015-2016",
"semesters": [
{
"name": "Winter 2015",
"gpa": 1.09,
"courses": [
{
"name": "Maths",
"grade": {
"numeric": 1.3,
"letter": "A-"
},
"creditHours": 8
}
// other courses ...
]
}
// other semesters ...
]
}
]Returns the logged in user's semester grades: both the coursework of all current courses, as well as the midterm grades if any.
Example return value, tap to expand
Containing two keys, the midterms, and the courseWork. Note that the coursework is grouped by elements (think one quiz with 2 questions) as shown below
{
"courseWork": [
{
"name": "CSEN1066 Selected Topics in Modern Networks",
"courseWork": [
{
"name": "Project",
"elements": [
{
"name": "M1",
"grade": 10,
"maxGrade": 10,
"professor": "Amr Hussien Elmougy"
},
{
"name": "M2",
"grade": 20,
"maxGrade": 20,
"professor": "Amr Hussien Elmougy"
}
]
}
// other course work ...
]
}
],
"midterms": [
{
"courseName": "Selected Topics in Modern Networks CSEN1066",
"grade": 92
}
// other midterms ...
]
}Returns the logged in user's current semester schedule.
Example return value, tap to expand
An array of day objects (day & slots array for each day). Free slots are denoted with a null. Therefore a day off will have 5 null values for the slots.
[
{
"day": "Saturday",
"slots": [
null,
null,
null,
{
"period": 4,
"type": "LAB",
"course": "CSEN 903",
"group": "P10",
"location": "C7.203",
"rawName": "9CSEN P10\tC7.203\tCSEN 903 Lab"
},
null
]
}
// other days ...
]When running npm install, you can skip the download of the chromium binaries by setting the following environment variable:
export PUPPETEER_SKIP_CHROMIUM_DOWNLOAD=trueHowever you must provide an executable path to a chromium binary (which is done via the CHROMIUM_EXECUTABLE_PATH environment variable). In the following example, it's assumed the default path to google-chrome, on an Ubuntu machine.
export CHROMIUM_EXECUTABLE_PATH=/usr/bin/google-chromeThis can be done via a .env file for easier configuration.
When creating a client instance, you can provide an optional puppeteer browser instance, this will allow you to set any options you would like to the browser instance (and this can be used to specify the executable path without the use of env as mentioned above).
So for example, if you would like to run the library in a non-headless mode (see the browser interaction being rendered), you can run the following:
const { GucClient } = require('guc-client');
const puppeteer = require('puppeteer');
const customOptions = {
headless: false
// any other options ...
};
(async () => {
const browser = await puppeteer.launch(customOptions);
const client = GucClient.create({ username: 'john.doe', password: '123' }, browser);
// Use the client instance regularly ...
})();The following errors can be thrown, you should try your best to handle each of them, and be as specific as possible:
Thrown when the provided credentials fail to login. No further data is associated with the error.
Thrown whenever the system faces a handled error (for instance, trying to access a page you are not authorized to).
The error object has the following properties:
message: A string containing the title displayed on the error pagedetails: A string containing further details displayed on the error page
The error gets thrown whenever the system raises an exception that was not handled (500 on the GUC server basically).
The error object doesn't contain any further metadata, for the sake of privacy, since such errors dump the stacktrace (as of the time of writing this).
The error is thrown only from the getTranscript function. Whenever course evaluation is required before accessing the transcript page.
It contains a details object in the following format:
{
"evaluationUrl": "url/to/evaluation",
"courses": ["list", "of", "strings"]
}For any feedback or issues, feel free to open an issue, make sure to keep it as detailed as possible.
If you would like to contribute, feel free to fork the repo, and open a PR. However, please create an issue first with the feature/bug-fix you would like to implement, since it might be in-work already.
The library is open source under the MIT License.
DISCLAIMER: This library is in no way legally associated with the GUC. It is simply a personal project for automating day-to-day tasks involving the GUC system.