@robertying/thu-learn-lib 0.0.0-stage → 4.1.0

package/src/index.ts

@@ -0,0 +1,282 @@
+import * as auth from './auth.ts';
+import * as calendar from './calendar.ts';
+import * as contents from './contents.ts';
+import * as courses from './courses.ts';
+import * as discussions from './discussions.ts';
+import * as favorites from './favorites.ts';
+import * as files from './files.ts';
+import * as homework from './homework.ts';
+import * as notices from './notices.ts';
+import * as questionnaires from './questionnaires.ts';
+import { Session } from './request.ts';
+import type {
+  CalendarOptions,
+  CalendarResult,
+  CommentItem,
+  CourseInfo,
+  Discussion,
+  FavoriteItem,
+  File,
+  FileCategory,
+  HelperConfig,
+  Homework,
+  HomeworkTA,
+  IHomeworkSubmitAttachment,
+  Language,
+  Notification,
+  Question,
+  Questionnaire,
+  SemesterInfo,
+  UserInfo,
+  ContentType,
+} from './types.ts';
+import { CourseType } from './types.ts';
+import * as user from './user.ts';
+
+export { addCSRFTokenToUrl } from './request.ts';
+export * from './types.ts';
+
+/** the main helper class */
+export class Learn2018Helper {
+  readonly #session: Session;
+
+  /** you can provide a CookieJar and / or CredentialProvider in the configuration */
+  constructor(config?: HelperConfig) {
+    this.#session = new Session(config, () => this.login());
+  }
+
+  /** whether preview URLs open the first page only (`HelperConfig.generatePreviewUrlForFirstPage`) */
+  public get previewFirstPage(): boolean {
+    return this.#session.previewFirstPage;
+  }
+
+  public set previewFirstPage(value: boolean) {
+    this.#session.previewFirstPage = value;
+  }
+
+  /** fetch CSRF token from helper (invalid after login / re-login), might be '' if not logged in */
+  public getCSRFToken(): string {
+    return this.#session.csrfToken;
+  }
+
+  /** manually set CSRF token (useful when you want to reuse previous token) */
+  public setCSRFToken(csrfToken: string): void {
+    this.#session.csrfToken = csrfToken;
+  }
+
+  /**
+   * If using alternative cookie management systems,
+   * be sure to clear id.tsinghua.edu.cn cookies before calling this function
+   */
+  public async getRoamingTicket(
+    username: string,
+    password: string,
+    fingerPrint: string,
+    fingerGenPrint: string = '',
+    fingerGenPrint3: string = '',
+  ): Promise<string> {
+    return auth.getRoamingTicket(this.#session, username, password, fingerPrint, fingerGenPrint, fingerGenPrint3);
+  }
+
+  /** login is necessary if you do not provide a `CredentialProvider` */
+  public async login(
+    username?: string,
+    password?: string,
+    fingerPrint?: string,
+    fingerGenPrint?: string,
+    fingerGenPrint3?: string,
+  ): Promise<void> {
+    return auth.login(this.#session, username, password, fingerPrint, fingerGenPrint, fingerGenPrint3);
+  }
+
+  /**  logout (to make everyone happy) */
+  public async logout(): Promise<void> {
+    return auth.logout(this.#session);
+  }
+
+  /** get user's name and department */
+  public async getUserInfo(courseType = CourseType.STUDENT): Promise<UserInfo> {
+    return user.getUserInfo(this.#session, courseType);
+  }
+
+  /**
+   * Get calendar items during the specified period (in yyyymmdd format, both inclusive).
+   * Ranges longer than 28 days are fetched in windows and merged; windows that fail even after a retry are listed in
+   * `failedRanges`. Rejects only when every window fails (usually with `FailReason.INVALID_RESPONSE`).
+   */
+  public async getCalendar(startDate: string, endDate: string, options?: CalendarOptions): Promise<CalendarResult> {
+    return calendar.getCalendar(this.#session, startDate, endDate, options);
+  }
+
+  public async getSemesterIdList(): Promise<string[]> {
+    return courses.getSemesterIdList(this.#session);
+  }
+
+  public async getCurrentSemester(): Promise<SemesterInfo> {
+    return courses.getCurrentSemester(this.#session);
+  }
+
+  /** get all courses in the specified semester */
+  public async getCourseList(
+    semesterID: string,
+    courseType: CourseType = CourseType.STUDENT,
+    lang: Language = this.#session.lang,
+  ): Promise<CourseInfo[]> {
+    return courses.getCourseList(this.#session, semesterID, courseType, lang);
+  }
+
+  /**
+   * Get certain type of content of all specified courses.
+   * It actually wraps around other `getXXX` functions. You can ignore the failure caused by certain courses.
+   */
+  public async getAllContents<T extends ContentType>(
+    courseIDs: string[],
+    type: T,
+    courseType: CourseType = CourseType.STUDENT,
+    allowFailure = false,
+  ) {
+    return contents.getAllContents(this.#session, courseIDs, type, courseType, allowFailure);
+  }
+
+  /** Get all notifications （课程公告） of the specified course. */
+  public async getNotificationList(
+    courseID: string,
+    courseType: CourseType = CourseType.STUDENT,
+  ): Promise<Notification[]> {
+    return notices.getNotificationList(this.#session, courseID, courseType);
+  }
+
+  /** Get all files （课程文件） of the specified course. */
+  public async getFileList(courseID: string, courseType: CourseType = CourseType.STUDENT): Promise<File[]> {
+    return files.getFileList(this.#session, courseID, courseType);
+  }
+
+  /** Get file categories of the specified course. */
+  public async getFileCategoryList(
+    courseID: string,
+    courseType: CourseType = CourseType.STUDENT,
+  ): Promise<FileCategory[]> {
+    return files.getFileCategoryList(this.#session, courseID, courseType);
+  }
+
+  /**
+   * Get all files of the specified category of the specified course.
+   * Note: this cannot get correct `visitCount` and `downloadCount` for student
+   */
+  public async getFileListByCategory(
+    courseID: string,
+    categoryId: string,
+    courseType: CourseType = CourseType.STUDENT,
+  ): Promise<File[]> {
+    return files.getFileListByCategory(this.#session, courseID, categoryId, courseType);
+  }
+
+  /** Get all homeworks （课程作业） of the specified course. */
+  public async getHomeworkList(courseID: string): Promise<Homework[]>;
+  public async getHomeworkList(courseID: string, courseType: CourseType.STUDENT): Promise<Homework[]>;
+  public async getHomeworkList(courseID: string, courseType: CourseType.TEACHER): Promise<HomeworkTA[]>;
+  public async getHomeworkList(
+    courseID: string,
+    courseType: CourseType = CourseType.STUDENT,
+  ): Promise<Homework[] | HomeworkTA[]> {
+    return courseType === CourseType.TEACHER
+      ? homework.getHomeworkList(this.#session, courseID, CourseType.TEACHER)
+      : homework.getHomeworkList(this.#session, courseID, CourseType.STUDENT);
+  }
+
+  /** Get all discussions （课程讨论） of the specified course. */
+  public async getDiscussionList(courseID: string, courseType: CourseType = CourseType.STUDENT): Promise<Discussion[]> {
+    return discussions.getDiscussionList(this.#session, courseID, courseType);
+  }
+
+  /**
+   * Get all notifications （课程答疑） of the specified course.
+   * The student version supports only answered questions, while the teacher version supports all questions.
+   */
+  public async getAnsweredQuestionList(
+    courseID: string,
+    courseType: CourseType = CourseType.STUDENT,
+  ): Promise<Question[]> {
+    return discussions.getAnsweredQuestionList(this.#session, courseID, courseType);
+  }
+
+  /**
+   * Get all questionnaires （课程问卷/QNR） of the specified course.
+   */
+  public async getQuestionnaireList(courseID: string): Promise<Questionnaire[]> {
+    return questionnaires.getQuestionnaireList(this.#session, courseID);
+  }
+
+  /**
+   * Add an item to favorites. (收藏)
+   */
+  public async addToFavorites(type: ContentType, id: string): Promise<void> {
+    return favorites.addToFavorites(this.#session, type, id);
+  }
+
+  /**
+   * Remove an item from favorites. (取消收藏)
+   */
+  public async removeFromFavorites(id: string): Promise<void> {
+    return favorites.removeFromFavorites(this.#session, id);
+  }
+
+  /**
+   * Get favorites. (我的收藏)
+   * If `courseID` or `type` is specified, only return favorites of that course or type.
+   */
+  public async getFavorites(courseID?: string, type?: ContentType): Promise<FavoriteItem[]> {
+    return favorites.getFavorites(this.#session, courseID, type);
+  }
+
+  /**
+   * Pin a favorite item. (置顶)
+   */
+  public async pinFavoriteItem(id: string): Promise<void> {
+    return favorites.pinFavoriteItem(this.#session, id);
+  }
+
+  /**
+   * Unpin a favorite item. (取消置顶)
+   */
+  public async unpinFavoriteItem(id: string): Promise<void> {
+    return favorites.unpinFavoriteItem(this.#session, id);
+  }
+
+  /**
+   * Set a comment. (备注)
+   * Set an empty string to remove the comment.
+   */
+  public async setComment(type: ContentType, id: string, content: string): Promise<void> {
+    return favorites.setComment(this.#session, type, id, content);
+  }
+
+  /**
+   * Get comments. (我的备注)
+   * If `courseID` or `type` is specified, only return favorites of that course or type.
+   */
+  public async getComments(courseID?: string, type?: ContentType): Promise<CommentItem[]> {
+    return favorites.getComments(this.#session, courseID, type);
+  }
+
+  public async sortCourses(courseIDs: string[]): Promise<void> {
+    return courses.sortCourses(this.#session, courseIDs);
+  }
+
+  public async submitHomework(
+    id: string,
+    content = '',
+    attachment?: IHomeworkSubmitAttachment,
+    removeAttachment = false,
+  ): Promise<void> {
+    return homework.submitHomework(this.#session, id, content, attachment, removeAttachment);
+  }
+
+  public async setLanguage(lang: Language): Promise<void> {
+    return user.setLanguage(this.#session, lang);
+  }
+
+  public getCurrentLanguage(): Language {
+    return this.#session.lang;
+  }
+}

package/src/notices.ts

@@ -0,0 +1,110 @@
+// Course notifications (课程公告).
+
+import { Base64 } from 'js-base64';
+
+import type { Session } from './request.ts';
+import { $, YES } from './request.ts';
+import type { INotification, INotificationDetail, Notification } from './types.ts';
+import { ContentType, CourseType, FailReason } from './types.ts';
+import * as URLS from './urls.ts';
+import { decodeHTML, trimAndDefine } from './utils.ts';
+
+/** Get all notifications （课程公告） of the specified course. */
+export async function getNotificationList(
+  s: Session,
+  courseID: string,
+  courseType: CourseType = CourseType.STUDENT,
+): Promise<Notification[]> {
+  return Promise.all([
+    getNotificationListKind(s, courseID, courseType, false),
+    getNotificationListKind(s, courseID, courseType, true),
+  ]).then((r) => r.flat());
+}
+
+async function getNotificationListKind(
+  s: Session,
+  courseID: string,
+  courseType: CourseType,
+  expired: boolean,
+): Promise<Notification[]> {
+  const json = await (
+    await s.fetchWithToken(URLS.LEARN_NOTIFICATION_LIST(courseType, expired), {
+      method: 'POST',
+      body: URLS.LEARN_PAGE_LIST_FORM_DATA(courseID),
+    })
+  ).json();
+  if (json.result !== 'success') {
+    return Promise.reject({
+      reason: FailReason.INVALID_RESPONSE,
+      extra: json,
+    });
+  }
+
+  const result = (json.object?.aaData ?? json.object?.resultsList ?? []) as any[];
+
+  return Promise.all(
+    result.map(async (n) => {
+      const notification: INotification = {
+        id: n.ggid,
+        content: Base64.decode(n.ggnr ?? ''),
+        title: decodeHTML(n.bt),
+        url: URLS.LEARN_NOTIFICATION_DETAIL(courseID, n.ggid, courseType),
+        publisher: n.fbrxm,
+        hasRead: n.sfyd === YES,
+        markedImportant: Number(n.sfqd) === 1, // n.sfqd could be string '1' (teacher mode) or number 1 (student mode)
+        publishTime: n.fbsj && typeof n.fbsj === 'string' ? n.fbsj : n.fbsjStr,
+        expireTime: n.jzsj ?? undefined,
+        isFavorite: n.sfsc === YES,
+        comment: n.bznr ?? undefined,
+      };
+      let detail: INotificationDetail = {};
+      const attachmentName = courseType === CourseType.STUDENT ? n.fjmc : n.fjbt;
+      if (attachmentName) {
+        detail = await parseNotificationDetail(s, courseID, notification.id, courseType, attachmentName);
+      }
+      return { ...notification, ...detail } satisfies Notification;
+    }),
+  );
+}
+
+async function parseNotificationDetail(
+  s: Session,
+  courseID: string,
+  id: string,
+  courseType: CourseType,
+  attachmentName: string,
+): Promise<INotificationDetail> {
+  /// from JSON (backup, currently not used)
+  // const postParams = new FormData();
+  // postParams.append('id', id);
+  // postParams.append('wlkcid', courseID);
+  // const metadata = await (await s.fetchWithToken(URL.LEARN_NOTIFICATION_EDIT(courseType), {
+  //   'method': 'POST',
+  //   'body': postParams,
+  // })).json();
+  // const attachmentId = metadata.ggfjid as string;
+  /// parsed from HTML
+  const response = await s.fetchWithToken(URLS.LEARN_NOTIFICATION_DETAIL(courseID, id, courseType));
+  const result = $(await response.text());
+  let path = '';
+  if (courseType === CourseType.STUDENT) {
+    path = result('.ml-10').attr('href')!;
+  } else {
+    path = result('#wjid').attr('href')!;
+  }
+  const size = trimAndDefine(result('div#attachment > div.fl > span[class^="color"]').first().text())!;
+  const params = new URLSearchParams(path.split('?').slice(-1)[0]);
+  const attachmentId = params.get('wjid')!;
+  if (!path.startsWith(URLS.LEARN_PREFIX)) {
+    path = URLS.LEARN_PREFIX + path;
+  }
+  return {
+    attachment: {
+      name: attachmentName,
+      id: attachmentId,
+      downloadUrl: path,
+      previewUrl: URLS.LEARN_FILE_PREVIEW(ContentType.NOTIFICATION, attachmentId, courseType, s.previewFirstPage),
+      size,
+    },
+  };
+}

package/src/questionnaires.ts

@@ -0,0 +1,76 @@
+// Questionnaires (课程问卷).
+
+import type { Session } from './request.ts';
+import { YES } from './request.ts';
+import type { Questionnaire, QuestionnaireDetail } from './types.ts';
+import { FailReason, QuestionnaireType } from './types.ts';
+import * as URLS from './urls.ts';
+import { QNR_TYPE_MAP, decodeHTML } from './utils.ts';
+
+/**
+ * Get all questionnaires （课程问卷/QNR） of the specified course.
+ */
+export async function getQuestionnaireList(s: Session, courseID: string): Promise<Questionnaire[]> {
+  return Promise.all([
+    getQuestionnaireListAtUrl(s, courseID, URLS.LEARN_QNR_LIST_ONGOING),
+    getQuestionnaireListAtUrl(s, courseID, URLS.LEARN_QNR_LIST_ENDED),
+  ]).then((r) => r.flat());
+}
+
+async function getQuestionnaireListAtUrl(s: Session, courseID: string, url: string): Promise<Questionnaire[]> {
+  const json = await (
+    await s.fetchWithToken(url, { method: 'POST', body: URLS.LEARN_PAGE_LIST_FORM_DATA(courseID) })
+  ).json();
+  if (json.result !== 'success') {
+    return Promise.reject({
+      reason: FailReason.INVALID_RESPONSE,
+      extra: json,
+    });
+  }
+  const result = (json.object?.aaData ?? []) as any[];
+  return Promise.all(
+    result.map(async (e) => {
+      const type = QNR_TYPE_MAP.get(e.wjlx) ?? QuestionnaireType.SURVEY;
+      return {
+        id: e.wjid,
+        type,
+        title: decodeHTML(e.wjbt),
+        startTime: e.kssj,
+        endTime: e.jssj,
+        uploadTime: e.scsj,
+        uploaderId: e.scr,
+        uploaderName: e.scrxm,
+        submitTime: e.tjsj ? e.tjsj : undefined,
+        isFavorite: e.sfsc === YES,
+        comment: e.bznr ?? undefined,
+        url: URLS.LEARN_QNR_SUBMIT_PAGE(e.wlkcid, e.wjid, type),
+        detail: await getQuestionnaireDetail(s, courseID, e.wjid),
+      } satisfies Questionnaire;
+    }),
+  );
+}
+
+async function getQuestionnaireDetail(s: Session, courseID: string, qnrID: string): Promise<QuestionnaireDetail[]> {
+  const json = await (
+    await s.fetchWithToken(URLS.LEARN_QNR_DETAIL, {
+      method: 'POST',
+      body: URLS.LEARN_QNR_DETAIL_FORM(courseID, qnrID),
+    })
+  ).json();
+  return (json as any[]).map(
+    (e) =>
+      ({
+        id: e.wtid,
+        index: Number(e.wtbh),
+        type: e.type,
+        required: e.require === YES,
+        title: decodeHTML(e.wtbt),
+        score: e.wtfz ? Number(e.wtfz) : undefined, // unsure about original type
+        options: (e.list as any[])?.map((o) => ({
+          id: o.xxid,
+          index: Number(o.xxbh),
+          title: decodeHTML(o.xxbt),
+        })),
+      }) satisfies QuestionnaireDetail,
+  );
+}

package/src/request.ts

@@ -0,0 +1,101 @@
+import * as cheerio from 'cheerio';
+import type { Element } from 'cheerio';
+import fetchCookie from 'fetch-cookie';
+import { fetch } from 'node-fetch-native';
+import { CookieJar } from 'tough-cookie';
+
+import type { CredentialProvider, Fetch, HelperConfig } from './types.ts';
+import { FailReason, Language } from './types.ts';
+
+const CHEERIO_CONFIG: cheerio.CheerioOptions = { xml: true };
+
+export const $ = (html: string | Element | Element[]): cheerio.CheerioAPI => {
+  return cheerio.load(html, CHEERIO_CONFIG);
+};
+
+export const noLogin = (res: Response) => res.url.includes('login_timeout') || res.status === 403;
+
+export const YES = '是';
+
+/** add CSRF token to any request URL as parameters */
+export const addCSRFTokenToUrl = (url: string, token: string): string => {
+  const newUrl = new URL(url);
+  newUrl.searchParams.set('_csrf', token);
+  return newUrl.toString();
+};
+
+function makeFetch(jar?: CookieJar): typeof fetch {
+  return fetchCookie(fetch, jar);
+}
+
+function withReAuth(rawFetch: Fetch, login: () => Promise<void>): Fetch {
+  return async function wrappedFetch(...args) {
+    const retryAfterLogin = async () => {
+      await login();
+      return await rawFetch(...args).then((res: Response) => {
+        if (noLogin(res)) {
+          return Promise.reject({
+            reason: FailReason.NOT_LOGGED_IN,
+          });
+        } else if (res.status !== 200) {
+          return Promise.reject({
+            reason: FailReason.UNEXPECTED_STATUS,
+            extra: {
+              code: res.status,
+              text: res.statusText,
+            },
+          });
+        } else {
+          return res;
+        }
+      });
+    };
+    return await rawFetch(...args).then((res: Response) => (noLogin(res) ? retryAfterLogin() : res));
+  };
+}
+
+/**
+ * State shared by every request a `Learn2018Helper` makes: cookies, CSRF token, language and the fetch wrappers.
+ * Internal; the helper keeps it in a private field.
+ */
+export class Session {
+  readonly provider?: CredentialProvider;
+  readonly cookieJar: CookieJar;
+  /** plain fetch with cookies, no login check */
+  readonly rawFetch: Fetch;
+  /** rejects with `NOT_LOGGED_IN`, or logs in again and retries once when a `CredentialProvider` is set */
+  readonly fetch: Fetch;
+  csrfToken = '';
+  lang = Language.ZH;
+  previewFirstPage: boolean;
+
+  /** `login` is called with no arguments when a request needs a (new) session */
+  constructor(
+    config: HelperConfig | undefined,
+    readonly login: () => Promise<void>,
+  ) {
+    this.previewFirstPage = config?.generatePreviewUrlForFirstPage ?? true;
+    this.provider = config?.provider;
+    this.cookieJar = config?.cookieJar ?? new CookieJar();
+    this.rawFetch = config?.fetch ?? makeFetch(this.cookieJar);
+    this.fetch = this.provider
+      ? withReAuth(this.rawFetch, login)
+      : async (...args) => {
+          const result = await this.rawFetch(...args);
+          if (noLogin(result))
+            return Promise.reject({
+              reason: FailReason.NOT_LOGGED_IN,
+            });
+          return result;
+        };
+  }
+
+  /** like `fetch`, but logs in first if there is no CSRF token yet and adds the token to the URL */
+  readonly fetchWithToken: Fetch = async (...args) => {
+    if (this.csrfToken === '') {
+      await this.login();
+    }
+    const [url, ...remaining] = args;
+    return this.fetch(addCSRFTokenToUrl(url as string, this.csrfToken), ...remaining);
+  };
+}