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

package/src/index.ts

@@ -0,0 +1,345 @@
+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 {
+  AllContentsOptions,
+  AllContentsResult,
+  CalendarOptions,
+  CalendarResult,
+  CourseListOptions,
+  ExcellentHomework,
+  HomeworkListOptions,
+  IHomeworkDetail,
+  NotificationListOptions,
+  RemoteFile,
+  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 URLS from './urls.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, () => auth.login(this.#session));
+  }
+
+  /** 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`.
+   * Without credentials it uses the provider, and concurrent calls share one SSO login.
+   */
+  public async login(
+    username?: string,
+    password?: string,
+    fingerPrint?: string,
+    fingerGenPrint?: string,
+    fingerGenPrint3?: string,
+  ): Promise<void> {
+    if (!username || !password || !fingerPrint) return this.#session.relogin();
+    return auth.login(this.#session, username, password, fingerPrint, fingerGenPrint, fingerGenPrint3);
+  }
+
+  /**
+   * Make sure the session is usable without a full SSO login when possible: with a CSRF token (from an earlier login
+   * or `setCSRFToken`), make one cheap request and log in again only if the session has expired; without one, log in.
+   * Use it when resuming an app instead of `login()`.
+   */
+  public async ensureSession(): Promise<void> {
+    return this.#session.ensureSession(URLS.LEARN_CURRENT_SEMESTER());
+  }
+
+  /**  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.
+   * `timeAndLocation` is only fetched (one request per course) with `options.timeAndLocation`.
+   */
+  public async getCourseList(
+    semesterID: string,
+    courseType: CourseType = CourseType.STUDENT,
+    lang: Language = this.#session.lang,
+    options?: CourseListOptions,
+  ): Promise<CourseInfo[]> {
+    return courses.getCourseList(this.#session, semesterID, courseType, lang, options);
+  }
+
+  /** Get the time and location of one course. */
+  public async getCourseTimeAndLocation(courseID: string): Promise<string[]> {
+    return courses.getCourseTimeAndLocation(this.#session, courseID);
+  }
+
+  /**
+   * Get certain type of content of all specified courses.
+   * It wraps around the `getXXX` list functions; a course that fails is reported in `errors` instead of failing
+   * the rest. `options.details` is passed on as homework `details` or notification `attachments`.
+   */
+  public async getAllContents<T extends ContentType>(
+    courseIDs: string[],
+    type: T,
+    options?: AllContentsOptions<T>,
+  ): Promise<AllContentsResult<T>> {
+    return contents.getAllContents(this.#session, courseIDs, type, options);
+  }
+
+  /**
+   * Get all notifications （课程公告） of the specified course.
+   * Attachments are only fetched (one request per notice) for the notices `options.attachments` selects;
+   * use `getNotificationAttachment` for the others.
+   */
+  public async getNotificationList(
+    courseID: string,
+    courseType: CourseType = CourseType.STUDENT,
+    options?: NotificationListOptions,
+  ): Promise<Notification[]> {
+    return notices.getNotificationList(this.#session, courseID, courseType, options);
+  }
+
+  /** Get the attachment of a notice (one request), `undefined` if it has none. */
+  public async getNotificationAttachment(
+    notification: Pick<Notification, 'url' | 'attachmentName'>,
+    courseType: CourseType = CourseType.STUDENT,
+  ): Promise<RemoteFile | undefined> {
+    return notices.getNotificationAttachment(this.#session, notification, 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, with the excellent homework list (without details).
+   * Details (page + description, two requests per homework) are only fetched for the homework `options.details`
+   * selects; use `getHomeworkDetail` for the others.
+   */
+  public async getHomeworkList(courseID: string): Promise<Homework[]>;
+  public async getHomeworkList(
+    courseID: string,
+    courseType: CourseType.STUDENT,
+    options?: HomeworkListOptions,
+  ): Promise<Homework[]>;
+  public async getHomeworkList(courseID: string, courseType: CourseType.TEACHER): Promise<HomeworkTA[]>;
+  public async getHomeworkList(
+    courseID: string,
+    courseType: CourseType = CourseType.STUDENT,
+    options?: HomeworkListOptions,
+  ): Promise<Homework[] | HomeworkTA[]> {
+    return courseType === CourseType.TEACHER
+      ? homework.getHomeworkList(this.#session, courseID, CourseType.TEACHER)
+      : homework.getHomeworkList(this.#session, courseID, CourseType.STUDENT, options);
+  }
+
+  /** Get the detail (page content, attachments and description) of one homework. */
+  public async getHomeworkDetail(item: Pick<Homework, 'url' | 'baseId'>): Promise<IHomeworkDetail> {
+    return homework.getHomeworkDetail(this.#session, item);
+  }
+
+  /** Get the detail (page content, attachments and description) of one excellent homework. */
+  public async getExcellentHomeworkDetail(item: Pick<ExcellentHomework, 'url' | 'baseId'>): Promise<IHomeworkDetail> {
+    return homework.getHomeworkDetail(this.#session, item);
+  }
+
+  /** 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,115 @@
+// Course notifications (课程公告).
+
+import { Base64 } from 'js-base64';
+
+import type { Session } from './request.ts';
+import { $, YES } from './request.ts';
+import type { INotification, Notification, NotificationListOptions, RemoteFile } from './types.ts';
+import { ContentType, CourseType, FailReason } from './types.ts';
+import * as URLS from './urls.ts';
+import { decodeHTML, isSelected, trimAndDefine } from './utils.ts';
+
+/**
+ * Get all notifications （课程公告） of the specified course: current and expired lists.
+ * Attachments only for the notices `options.attachments` selects.
+ */
+export async function getNotificationList(
+  s: Session,
+  courseID: string,
+  courseType: CourseType = CourseType.STUDENT,
+  options: NotificationListOptions = {},
+): Promise<Notification[]> {
+  const lists = await Promise.all([
+    getNotificationListKind(s, courseID, courseType, false),
+    getNotificationListKind(s, courseID, courseType, true),
+  ]);
+  return Promise.all(
+    lists.flat().map(async (n): Promise<Notification> => {
+      if (!n.attachmentName || !isSelected(options.attachments, n)) return n;
+      return { ...n, attachment: await getNotificationAttachment(s, n, courseType) };
+    }),
+  );
+}
+
+async function getNotificationListKind(
+  s: Session,
+  courseID: string,
+  courseType: CourseType,
+  expired: boolean,
+): Promise<INotification[]> {
+  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 result.map((n) => {
+    const attachmentName: unknown = courseType === CourseType.STUDENT ? n.fjmc : n.fjbt;
+    return {
+      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,
+      attachmentName: typeof attachmentName === 'string' && attachmentName ? attachmentName : undefined,
+    } satisfies INotification;
+  });
+}
+
+/**
+ * Get the attachment of a notice from its detail page (1 request), or `undefined` without a request if
+ * `attachmentName` says it has none.
+ */
+export async function getNotificationAttachment(
+  s: Session,
+  notification: Pick<INotification, 'url' | 'attachmentName'>,
+  courseType: CourseType = CourseType.STUDENT,
+): Promise<RemoteFile | undefined> {
+  if (!notification.attachmentName) return undefined;
+  /// 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(notification.url);
+  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 {
+    name: notification.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,
+  );
+}