thu-learn-lib

npm size npm downloads

This is a JavaScript library aimed to provide a program-friendly interface of web Learning of Tsinghua University.

This project is licensed under MIT License.

Compatibility

The library uses node-fetch-cookie-native, which is a simple wrapper for node-fetch-native and fetch-cookie, providing cookie and redirection support in both browsers and Node.

In case of any syntax problems, just upgrade your browser / Node, or use any corresponding polyfills.

Installation

Node / Bundler

yarn add thu-learn-lib

Browser (IIFE)

The library is exposed under window.LearnLib.

Browser (ESM)

Build

yarn run build

You can find the bundled library in lib/.

index.js: ES module entry
index.d.ts: definition file for TypeScript
index.global.js{,.map}: IIFE for use in browser (with source map for debugging)

Development in browser

yarn run dev

This will open a dev browser with a testing extension. Click the t icon in extension bar, then execute anything you want in the Console of Chrome Developer Tool. The library is exposed under window.LearnLib.

Use yarn run dev:build to build the extension that can be installed to your chrome browser manually.

Usage

Authentication related (important changes since v1.2.0)

import { Learn2018Helper } from 'thu-learn-lib';

// There are three ways of logging in:

// 1. provide a cookie jar with existing cookies (see `tough-cookie`)
const helper = new Learn2018Helper({ cookieJar });
// 2. provide nothing, but invoking login with username and password
const helper = new Learn2018Helper();
// 3. provide a CredentialProvider function, which can be async
const helper = new Learn2018Helper({
  provider: () =&gt; ({ username, password }),
});

// Note that by using the following two methods you may encounter problems like login time out.
// But if you provide a credential provider, the library will retry logging in when failing, automatically resolving the cookie expiry problem.
// So we strongly recommend using this method.

// If you do not provide a cookie jar or CredentialProvider, you must log in manually. Otherwise you do not need to call login explicitly.
try {
  await helper.login(username, password);
} catch (e) {
  // e is a FailReason
}

// You can also take out cookies (e.g. for file download), which will not work in browsers.
console.log(helper.cookieJar);

// Logout if you want, but the cookie jar will not be cleared.
await helper.logout();

Content related

We currently support both student and teacher (or TA) version of web learning. To keep backwards compatibility, the default behavior of all APIs is to use the student version. The following APIs needs CourseType.TEACHER as the last (optional) parameter to access the teacher version. You should use them when you are the teacher / TA of one course, for you will get nothing from the student version in that case.

We do not maintain a global type in Learn2018Helper class, for there can be the situation that one can be a student and teacher of the same course simultaneously, on which by using different CourseType you can get different results.

getCourseList
getNotificationList/getFileList/getHomeworkList/getDiscussionList/getAnsweredQuestionList
getAllContents

Note that currently fetching homework information from teacher version is partially implemented.

import { ContentType, ApiError } from 'thu-learn-lib';

// get ids of all semesters that current account has access to
const semesters = await helper.getSemesterIdList();

// get get semester info
const semester = await helper.getCurrentSemester();

// get courses of this semester
const courses = await helper.getCourseList(semester.id);
const course = courses[0];

// get detail information about the course
const discussions = await helper.getDiscussionList(course.id);
const notifications = await helper.getNotificationList(course.id);
const files = await helper.getFileList(course.id);
const homework = await helper.getHomeworkList(course.id);
const questions = await helper.getAnsweredQuestionList(course.id);

// get content from bunches of courses
// the return type will be { [id: string]: Content }
// where Content = Notification | File | Homework | Discussion | Question
const homeworks = await helper.getAllContents([1, 2, 3], ContentType.HOMEWORK);

// get course calendar in a period
try {
  const calendar = await helper.getCalendar('20191001', '20191201');
} catch (e) {
  const error = e as ApiError;
  // check e.reason and e.extra for information
  // you might want to check your date format or shrink the range (currently we observe a limit of 29 days)
}

According to security strategies (CORS, CORB) of browsers, you might need to run the code in the page context of https://learn.tsinghua.edu.cn and https://id.tsinghua.edu.cn. The simplest way is to run the code in Node.js or in browser extension.

Typing

See src/types.ts for type definitions. Note that ApiError represents the type that will be used in rejected Promises.

Testing

Run yarn test for testing. It requires your personal credential since we don't have mocks for these APIs. To do this, you must touch a .env similar to template.env under /test folder.

It's ok if you meet Timeout * Async callback was not invoked within the 5000ms timeout... error when running tests, rerun tests may resolve this problem. If you hate this, just add the third argument timeout to every testcase it("should...", async () => void, timeout) and make sure it's greater than 5000.

Changelog

Projects using this library

Most popular functions for thu-learn-lib

To help you get started, we’ve selected a few thu-learn-lib examples, based on popular ways it is used in public projects.

thu-learn-lib.Learn2018Helper