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

package/src/auth.ts

@@ -0,0 +1,121 @@
+// Login to Web Learning through id.tsinghua.edu.cn (SSO) and logout.
+
+import { sm2 } from 'sm-crypto';
+
+import type { Session } from './request.ts';
+import { $ } from './request.ts';
+import type { ApiError } from './types.ts';
+import { FailReason, Language } from './types.ts';
+import * as URLS from './urls.ts';
+
+/**
+ * If using alternative cookie management systems,
+ * be sure to clear id.tsinghua.edu.cn cookies before calling this function
+ */
+export async function getRoamingTicket(
+  s: Session,
+  username: string,
+  password: string,
+  fingerPrint: string,
+  fingerGenPrint: string = '',
+  fingerGenPrint3: string = '',
+) {
+  // Make sure we always start with the form page
+  // More code is needed to handle the case where the user is already logged in (i.e. cookies are set)
+  // It won't be a problem if it is always the same user,
+  // but if the current cookies are from a different user than the one trying to log in,
+  // it will cause problems.
+  try {
+    await s.cookieJar.setCookie('JSESSIONID=; path=/; HttpOnly', URLS.ID_PREFIX);
+  } catch (err) {
+    throw {
+      reason: FailReason.ERROR_SETTING_COOKIES,
+      extra: err,
+    } as ApiError;
+  }
+
+  try {
+    const loginForm = await s.rawFetch(URLS.ID_LOGIN());
+    const body = $(await loginForm.text());
+    const sm2publicKey = body('#sm2publicKey').text().trim();
+
+    const formData = new FormData();
+    formData.append('i_user', username);
+    formData.append('i_pass', '04' + sm2.doEncrypt(password, sm2publicKey));
+    formData.append('singleLogin', 'on');
+    formData.append('fingerPrint', fingerPrint);
+    formData.append('fingerGenPrint', fingerGenPrint ?? '');
+    formData.append('fingerGenPrint3', fingerGenPrint3 ?? '');
+    formData.append('i_captcha', '');
+    const checkResponse = await s.rawFetch(URLS.ID_LOGIN_CHECK(), {
+      method: 'POST',
+      body: formData,
+    });
+
+    const anchor = $(await checkResponse.text())('a');
+    const redirectUrl = anchor.attr('href') as string;
+    const ticket = redirectUrl.split('=').slice(-1)[0];
+    return ticket;
+  } catch (err) {
+    throw {
+      reason: FailReason.ERROR_FETCH_FROM_ID,
+      extra: err,
+    } as ApiError;
+  }
+}
+
+/** login is necessary if you do not provide a `CredentialProvider` */
+export async function login(
+  s: Session,
+  username?: string,
+  password?: string,
+  fingerPrint?: string,
+  fingerGenPrint?: string,
+  fingerGenPrint3?: string,
+): Promise<void> {
+  if (!username || !password || !fingerPrint) {
+    if (!s.provider)
+      return Promise.reject({
+        reason: FailReason.NO_CREDENTIAL,
+      });
+    const credential = await s.provider();
+    username = credential.username;
+    password = credential.password;
+    fingerPrint = credential.fingerPrint;
+    fingerGenPrint = credential.fingerGenPrint;
+    fingerGenPrint3 = credential.fingerGenPrint3;
+    if (!username || !password || !fingerPrint) {
+      return Promise.reject({
+        reason: FailReason.NO_CREDENTIAL,
+      });
+    }
+  }
+
+  // check response from id.tsinghua.edu.cn
+  const ticket = await getRoamingTicket(s, username, password, fingerPrint, fingerGenPrint, fingerGenPrint3);
+
+  const loginResponse = await s.rawFetch(URLS.LEARN_AUTH_ROAM(ticket));
+  if (!loginResponse.ok) {
+    return Promise.reject({
+      reason: FailReason.ERROR_ROAMING,
+    });
+  }
+  const courseListPageSource: string = await (await s.rawFetch(URLS.LEARN_STUDENT_COURSE_LIST_PAGE())).text();
+  const tokenRegex = /^.*&_csrf=(\S*)".*$/gm;
+  const tokenMatches = [...courseListPageSource.matchAll(tokenRegex)];
+  if (tokenMatches.length === 0) {
+    return Promise.reject({
+      reason: FailReason.INVALID_RESPONSE,
+      extra: 'cannot fetch CSRF token from source',
+    });
+  }
+  s.csrfToken = tokenMatches[0][1];
+  const langRegex = /<script src="\/f\/wlxt\/common\/languagejs\?lang=(zh|en)"><\/script>/g;
+  const langMatches = [...courseListPageSource.matchAll(langRegex)];
+  if (langMatches.length !== 0) s.lang = langMatches[0][1] === 'en' ? Language.EN : Language.ZH;
+}
+
+/**  logout (to make everyone happy) */
+export async function logout(s: Session): Promise<void> {
+  await s.rawFetch(URLS.LEARN_LOGOUT(), { method: 'POST' });
+}

package/src/calendar.ts

@@ -0,0 +1,102 @@
+// Course calendar from the registrar (academic.tsinghua.edu.cn).
+
+import type { Session } from './request.ts';
+import type { CalendarEvent, CalendarOptions, CalendarRange, CalendarResult } from './types.ts';
+import { FailReason } from './types.ts';
+import * as URLS from './urls.ts';
+import { JSONP_EXTRACTOR_NAME, extractJSONPResult } from './utils.ts';
+
+/** The registrar often fails for ranges longer than about a month, so longer ranges are fetched in windows of this many days. */
+export const CALENDAR_WINDOW_DAYS = 28;
+
+const DAY_MS = 24 * 60 * 60 * 1000;
+
+const parseDate = (date: string): number => {
+  const match = /^(\d{4})(\d{2})(\d{2})$/.exec(date);
+  const time = match ? Date.UTC(Number(match[1]), Number(match[2]) - 1, Number(match[3])) : NaN;
+  if (Number.isNaN(time) || formatDate(time) !== date) {
+    throw { reason: FailReason.INVALID_RESPONSE, extra: `invalid date ${date}, expected yyyymmdd` };
+  }
+  return time;
+};
+
+const formatDate = (time: number): string => new Date(time).toISOString().slice(0, 10).replaceAll('-', '');
+
+/** Split an inclusive yyyymmdd range into consecutive inclusive windows of at most `days` days. */
+export function splitCalendarRange(startDate: string, endDate: string, days = CALENDAR_WINDOW_DAYS): CalendarRange[] {
+  const start = parseDate(startDate);
+  const end = parseDate(endDate);
+  const ranges: CalendarRange[] = [];
+  for (let from = start; from <= end; from += days * DAY_MS) {
+    const to = Math.min(from + (days - 1) * DAY_MS, end);
+    ranges.push({ startDate: formatDate(from), endDate: formatDate(to) });
+  }
+  return ranges;
+}
+
+async function fetchWindow(s: Session, range: CalendarRange, graduate: boolean): Promise<CalendarEvent[]> {
+  const response = await s.fetchWithToken(
+    URLS.REGISTRAR_CALENDAR(range.startDate, range.endDate, graduate, JSONP_EXTRACTOR_NAME),
+  );
+
+  if (!response.ok) {
+    return Promise.reject({
+      reason: FailReason.INVALID_RESPONSE,
+    });
+  }
+
+  const result = extractJSONPResult(await response.text()) as any[];
+
+  return result.map<CalendarEvent>((i) => ({
+    location: i.dd,
+    status: i.fl,
+    startTime: i.kssj,
+    endTime: i.jssj,
+    date: i.nq,
+    courseName: i.nr,
+  }));
+}
+
+/**
+ * Get calendar items during the specified period (in yyyymmdd format, both inclusive).
+ *
+ * Ranges longer than `CALENDAR_WINDOW_DAYS` are fetched in consecutive windows (one at a time, each retried once) and
+ * merged in date order. Windows that still fail are listed in `failedRanges`, so callers can show partial data and
+ * retry only those. If every window fails, this rejects with the last error instead (usually
+ * `FailReason.INVALID_RESPONSE`). The result might be empty if the period is too far away from now.
+ */
+export async function getCalendar(
+  s: Session,
+  startDate: string,
+  endDate: string,
+  options: CalendarOptions = {},
+): Promise<CalendarResult> {
+  const graduate = options.graduate ?? false;
+  const ranges = splitCalendarRange(startDate, endDate);
+  if (ranges.length === 0) return { events: [], failedRanges: [] };
+
+  const ticketResponse = await s.fetchWithToken(URLS.REGISTRAR_TICKET(), {
+    method: 'POST',
+    body: URLS.REGISTRAR_TICKET_FORM_DATA(),
+  });
+
+  let ticket = await ticketResponse.text();
+  ticket = ticket.substring(1, ticket.length - 1);
+
+  await s.fetch(URLS.REGISTRAR_AUTH(ticket));
+
+  const events: CalendarEvent[] = [];
+  const failedRanges: CalendarRange[] = [];
+  let lastError: unknown;
+  for (const range of ranges) {
+    try {
+      events.push(...(await fetchWindow(s, range, graduate).catch(() => fetchWindow(s, range, graduate))));
+    } catch (e) {
+      lastError = e;
+      failedRanges.push(range);
+    }
+  }
+
+  if (failedRanges.length === ranges.length) throw lastError;
+  return { events, failedRanges };
+}

package/src/contents.ts

@@ -0,0 +1,67 @@
+// One kind of content for many courses at once.
+
+import type { Session } from './request.ts';
+import type { ContentTypeMap, CourseContent } from './types.ts';
+import { ContentType, CourseType, FailReason } from './types.ts';
+import { getAnsweredQuestionList, getDiscussionList } from './discussions.ts';
+import { getFileList } from './files.ts';
+import { getHomeworkList } from './homework.ts';
+import { getNotificationList } from './notices.ts';
+import { getQuestionnaireList } from './questionnaires.ts';
+
+/**
+ * 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.
+ */
+export async function getAllContents<T extends ContentType>(
+  s: Session,
+  courseIDs: string[],
+  type: T,
+  courseType: CourseType = CourseType.STUDENT,
+  allowFailure = false,
+) {
+  const fetchContentForCourse = (id: string) => {
+    switch (type) {
+      case ContentType.NOTIFICATION:
+        return getNotificationList(s, id, courseType) as Promise<ContentTypeMap[T][]>;
+      case ContentType.FILE:
+        return getFileList(s, id, courseType) as Promise<ContentTypeMap[T][]>;
+      case ContentType.HOMEWORK:
+        return getHomeworkList(s, id) as Promise<ContentTypeMap[T][]>;
+      case ContentType.DISCUSSION:
+        return getDiscussionList(s, id, courseType) as Promise<ContentTypeMap[T][]>;
+      case ContentType.QUESTION:
+        return getAnsweredQuestionList(s, id, courseType) as Promise<ContentTypeMap[T][]>;
+      case ContentType.QUESTIONNAIRE:
+        return getQuestionnaireList(s, id) as Promise<ContentTypeMap[T][]>;
+      default:
+        return Promise.reject({
+          reason: FailReason.NOT_IMPLEMENTED,
+          extra: 'Unknown content type',
+        });
+    }
+  };
+
+  const contents: CourseContent<T> = {};
+
+  const results = await Promise.allSettled(
+    courseIDs.map(async (id) => {
+      contents[id] = await fetchContentForCourse(id);
+    }),
+  );
+
+  if (!allowFailure) {
+    for (const r of results) {
+      if (r.status === 'rejected') {
+        return Promise.reject({
+          reason: FailReason.INVALID_RESPONSE,
+          extra: {
+            reason: r.reason,
+          },
+        });
+      }
+    }
+  }
+
+  return contents;
+}

package/src/courses.ts

@@ -0,0 +1,97 @@
+// Semesters and courses.
+
+import type { Session } from './request.ts';
+import type { CourseInfo, SemesterInfo } from './types.ts';
+import { CourseType, FailReason } from './types.ts';
+import * as URLS from './urls.ts';
+import { decodeHTML, parseSemesterType } from './utils.ts';
+
+export async function getSemesterIdList(s: Session): Promise<string[]> {
+  const json = await (await s.fetchWithToken(URLS.LEARN_SEMESTER_LIST())).json();
+  if (!Array.isArray(json)) {
+    return Promise.reject({
+      reason: FailReason.INVALID_RESPONSE,
+      extra: json,
+    });
+  }
+  const semesters = json as string[];
+  // sometimes web learning returns null, so confusing...
+  return semesters.filter((semester) => semester != null);
+}
+
+export async function getCurrentSemester(s: Session): Promise<SemesterInfo> {
+  const json = await (await s.fetchWithToken(URLS.LEARN_CURRENT_SEMESTER())).json();
+  if (json.message !== 'success') {
+    return Promise.reject({
+      reason: FailReason.INVALID_RESPONSE,
+      extra: json,
+    });
+  }
+  const result = json.result;
+  return {
+    id: result.id,
+    startDate: result.kssj,
+    endDate: result.jssj,
+    startYear: Number(result.xnxq.slice(0, 4)),
+    endYear: Number(result.xnxq.slice(5, 9)),
+    type: parseSemesterType(Number(result.xnxq.slice(10, 11))),
+  };
+}
+
+/** get all courses in the specified semester */
+export async function getCourseList(
+  s: Session,
+  semesterID: string,
+  courseType: CourseType = CourseType.STUDENT,
+  lang = s.lang,
+): Promise<CourseInfo[]> {
+  const json = await (await s.fetchWithToken(URLS.LEARN_COURSE_LIST(semesterID, courseType, lang))).json();
+  if (json.message !== 'success' || !Array.isArray(json.resultList)) {
+    return Promise.reject({
+      reason: FailReason.INVALID_RESPONSE,
+      extra: json,
+    });
+  }
+  const result = (json.resultList ?? []) as any[];
+
+  return Promise.all(
+    result.map(async (c) => {
+      let timeAndLocation: string[] = [];
+      try {
+        // see https://github.com/Harry-Chen/Learn-Helper/issues/145
+        timeAndLocation = await (await s.fetchWithToken(URLS.LEARN_COURSE_TIME_LOCATION(c.wlkcid))).json();
+      } catch (e) {}
+      return {
+        id: c.wlkcid,
+        name: decodeHTML(c.zywkcm),
+        chineseName: decodeHTML(c.kcm),
+        englishName: decodeHTML(c.ywkcm),
+        timeAndLocation,
+        url: URLS.LEARN_COURSE_PAGE(c.wlkcid, courseType),
+        teacherName: c.jsm ?? '', // teacher can not fetch this
+        teacherNumber: c.jsh,
+        courseNumber: c.kch,
+        courseIndex: Number(c.kxh), // c.kxh could be string (teacher mode) or number (student mode)
+        courseType,
+      } satisfies CourseInfo;
+    }),
+  );
+}
+
+export async function sortCourses(s: Session, courseIDs: string[]): Promise<void> {
+  const json = await (
+    await s.fetchWithToken(URLS.LEARN_SORT_COURSES, {
+      method: 'POST',
+      body: JSON.stringify(courseIDs.map((id, index) => ({ wlkcid: id, xh: index + 1 }))),
+      headers: {
+        'Content-Type': 'application/json',
+      },
+    })
+  ).json();
+  if (json.result !== 'success') {
+    return Promise.reject({
+      reason: FailReason.OPERATION_FAILED,
+      extra: json,
+    });
+  }
+}

package/src/discussions.ts

@@ -0,0 +1,80 @@
+// Discussions (课程讨论) and answered questions (课程答疑).
+
+import { Base64 } from 'js-base64';
+
+import type { Session } from './request.ts';
+import { YES } from './request.ts';
+import type { Discussion, IDiscussionBase, Question } from './types.ts';
+import { CourseType, FailReason } from './types.ts';
+import * as URLS from './urls.ts';
+import { decodeHTML } from './utils.ts';
+
+/** Get all discussions （课程讨论） of the specified course. */
+export async function getDiscussionList(
+  s: Session,
+  courseID: string,
+  courseType: CourseType = CourseType.STUDENT,
+): Promise<Discussion[]> {
+  const json = await (await s.fetchWithToken(URLS.LEARN_DISCUSSION_LIST(courseID, courseType))).json();
+  if (json.result !== 'success') {
+    return Promise.reject({
+      reason: FailReason.INVALID_RESPONSE,
+      extra: json,
+    });
+  }
+
+  const result = (json.object?.resultsList ?? []) as any[];
+
+  return result.map(
+    (d) =>
+      ({
+        ...parseDiscussionBase(d),
+        boardId: d.bqid,
+        url: URLS.LEARN_DISCUSSION_DETAIL(d.wlkcid, d.bqid, d.id, courseType),
+      }) satisfies Discussion,
+  );
+}
+
+/**
+ * Get all notifications （课程答疑） of the specified course.
+ * The student version supports only answered questions, while the teacher version supports all questions.
+ */
+export async function getAnsweredQuestionList(
+  s: Session,
+  courseID: string,
+  courseType: CourseType = CourseType.STUDENT,
+): Promise<Question[]> {
+  const json = await (await s.fetchWithToken(URLS.LEARN_QUESTION_LIST_ANSWERED(courseID, courseType))).json();
+  if (json.result !== 'success') {
+    return Promise.reject({
+      reason: FailReason.INVALID_RESPONSE,
+      extra: json,
+    });
+  }
+
+  const result = (json.object?.resultsList ?? []) as any[];
+
+  return result.map(
+    (q) =>
+      ({
+        ...parseDiscussionBase(q),
+        question: Base64.decode(q.wtnr),
+        url: URLS.LEARN_QUESTION_DETAIL(q.wlkcid, q.id, courseType),
+      }) satisfies Question,
+  );
+}
+
+function parseDiscussionBase(d: any): IDiscussionBase {
+  return {
+    id: d.id,
+    title: decodeHTML(d.bt),
+    publisherName: d.fbrxm,
+    publishTime: d.fbsj,
+    lastReplyTime: d.zhhfsj,
+    lastReplierName: d.zhhfrxm,
+    visitCount: d.djs ?? 0, // teacher cannot fetch this
+    replyCount: d.hfcs,
+    isFavorite: d.sfsc === YES,
+    comment: d.bznr ?? undefined,
+  };
+}

package/src/favorites.ts

@@ -0,0 +1,167 @@
+// Favorites (收藏) and comments (备注).
+
+import type { Session } from './request.ts';
+import { YES } from './request.ts';
+import type { CommentItem, FavoriteItem } from './types.ts';
+import { ContentType, FailReason } from './types.ts';
+import * as URLS from './urls.ts';
+import { CONTENT_TYPE_MAP_REVERSE, decodeHTML } from './utils.ts';
+
+/**
+ * Add an item to favorites. (收藏)
+ */
+export async function addToFavorites(s: Session, type: ContentType, id: string): Promise<void> {
+  const json = await (await s.fetchWithToken(URLS.LEARN_FAVORITE_ADD(type, id))).json();
+  if (json.result !== 'success' || !json.msg?.endsWith?.('成功')) {
+    return Promise.reject({
+      reason: FailReason.OPERATION_FAILED,
+      extra: json,
+    });
+  }
+}
+
+/**
+ * Remove an item from favorites. (取消收藏)
+ */
+export async function removeFromFavorites(s: Session, id: string): Promise<void> {
+  const json = await (await s.fetchWithToken(URLS.LEARN_FAVORITE_REMOVE(id))).json();
+  if (json.result !== 'success' || !json.msg?.endsWith?.('成功')) {
+    return Promise.reject({
+      reason: FailReason.OPERATION_FAILED,
+      extra: json,
+    });
+  }
+}
+
+/**
+ * Get favorites. (我的收藏)
+ * If `courseID` or `type` is specified, only return favorites of that course or type.
+ */
+export async function getFavorites(s: Session, courseID?: string, type?: ContentType): Promise<FavoriteItem[]> {
+  const json = await (
+    await s.fetchWithToken(URLS.LEARN_FAVORITE_LIST(type), {
+      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 result
+    .map((e): FavoriteItem | undefined => {
+      const itemType = CONTENT_TYPE_MAP_REVERSE.get(e.ywlx);
+      if (!itemType) return undefined; // ignore unknown type
+      return {
+        id: e.ywid,
+        type: itemType,
+        title: decodeHTML(e.ywbt),
+        time: itemType === ContentType.DISCUSSION || itemType === ContentType.QUESTION ? e.tlsj : e.ywsj,
+        state: e.ywzt,
+        extra: e.ywbz ?? undefined,
+        semesterId: e.xnxq,
+        courseId: e.wlkcid,
+        pinned: e.sfzd === YES,
+        pinnedTime: e.zdsj === null ? undefined : e.zdsj, // Note: this field is originally unix timestamp instead of string
+        comment: e.bznr ?? undefined,
+        addedTime: e.scsj,
+        itemId: e.id,
+      } satisfies FavoriteItem;
+    })
+    .filter((x) => !!x);
+}
+
+/**
+ * Pin a favorite item. (置顶)
+ */
+export async function pinFavoriteItem(s: Session, id: string): Promise<void> {
+  const json = await (
+    await s.fetchWithToken(URLS.LEARN_FAVORITE_PIN, {
+      method: 'POST',
+      body: URLS.LEARN_FAVORITE_PIN_UNPIN_FORM_DATA(id),
+    })
+  ).json();
+  if (json.result !== 'success') {
+    return Promise.reject({
+      reason: FailReason.OPERATION_FAILED,
+      extra: json,
+    });
+  }
+}
+
+/**
+ * Unpin a favorite item. (取消置顶)
+ */
+export async function unpinFavoriteItem(s: Session, id: string): Promise<void> {
+  const json = await (
+    await s.fetchWithToken(URLS.LEARN_FAVORITE_UNPIN, {
+      method: 'POST',
+      body: URLS.LEARN_FAVORITE_PIN_UNPIN_FORM_DATA(id),
+    })
+  ).json();
+  if (json.result !== 'success') {
+    return Promise.reject({
+      reason: FailReason.OPERATION_FAILED,
+      extra: json,
+    });
+  }
+}
+
+/**
+ * Set a comment. (备注)
+ * Set an empty string to remove the comment.
+ */
+export async function setComment(s: Session, type: ContentType, id: string, content: string): Promise<void> {
+  const json = await (
+    await s.fetchWithToken(URLS.LEARN_COMMENT_SET, {
+      method: 'POST',
+      body: URLS.LEARN_COMMENT_SET_FORM_DATA(type, id, content),
+    })
+  ).json();
+  if (json.result !== 'success' || !json.msg?.endsWith?.('成功')) {
+    return Promise.reject({
+      reason: FailReason.OPERATION_FAILED,
+      extra: json,
+    });
+  }
+}
+
+/**
+ * Get comments. (我的备注)
+ * If `courseID` or `type` is specified, only return favorites of that course or type.
+ */
+export async function getComments(s: Session, courseID?: string, type?: ContentType): Promise<CommentItem[]> {
+  const json = await (
+    await s.fetchWithToken(URLS.LEARN_COMMENT_LIST(type), {
+      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 result
+    .map((e): CommentItem | undefined => {
+      const itemType = CONTENT_TYPE_MAP_REVERSE.get(e.ywlx);
+      if (!itemType) return undefined; // ignore unknown type
+      return {
+        id: e.ywid,
+        type: itemType,
+        content: e.bt,
+        contentHTML: decodeHTML(e.bznrstring),
+        title: decodeHTML(e.ywbt),
+        semesterId: e.xnxq,
+        courseId: e.wlkcid,
+        commentTime: e.cjsj,
+        itemId: e.id,
+      } satisfies CommentItem;
+    })
+    .filter((x) => !!x);
+}