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

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,63 @@
+// One kind of content for many courses at once.
+
+import type { Session } from './request.ts';
+import type { AllContentsOptions, AllContentsResult, 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 wraps around the `getXXX` list functions; one course failing doesn't fail the others: its error is in `errors`.
+ */
+export async function getAllContents<T extends ContentType>(
+  s: Session,
+  courseIDs: string[],
+  type: T,
+  options: AllContentsOptions<T> = {},
+): Promise<AllContentsResult<T>> {
+  const courseType = options.courseType ?? CourseType.STUDENT;
+  const fetchContentForCourse = (id: string): Promise<ContentTypeMap[T][]> => {
+    switch (type) {
+      case ContentType.NOTIFICATION:
+        return getNotificationList(s, id, courseType, {
+          attachments: (options as AllContentsOptions<ContentType.NOTIFICATION>).details,
+        }) as Promise<ContentTypeMap[T][]>;
+      case ContentType.FILE:
+        return getFileList(s, id, courseType) as Promise<ContentTypeMap[T][]>;
+      case ContentType.HOMEWORK:
+        return getHomeworkList(s, id, CourseType.STUDENT, {
+          details: (options as AllContentsOptions<ContentType.HOMEWORK>).details,
+        }) 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 errors: AllContentsResult<T>['errors'] = {};
+
+  await Promise.all(
+    courseIDs.map(async (id) => {
+      try {
+        contents[id] = await fetchContentForCourse(id);
+      } catch (err) {
+        errors[id] = err;
+      }
+    }),
+  );
+
+  return { contents, errors };
+}

package/src/courses.ts

@@ -0,0 +1,111 @@
+// Semesters and courses.
+
+import type { Session } from './request.ts';
+import type { ApiError, CourseInfo, CourseListOptions, 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; time and location only with `options.timeAndLocation` */
+export async function getCourseList(
+  s: Session,
+  semesterID: string,
+  courseType: CourseType = CourseType.STUDENT,
+  lang = s.lang,
+  options: CourseListOptions = {},
+): 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[] | undefined;
+      if (options.timeAndLocation) {
+        try {
+          timeAndLocation = await getCourseTimeAndLocation(s, c.wlkcid);
+        } catch {
+          timeAndLocation = [];
+        }
+      }
+      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;
+    }),
+  );
+}
+
+/** get the time and location of one course (1 request) */
+export async function getCourseTimeAndLocation(s: Session, courseID: string): Promise<string[]> {
+  // see https://github.com/Harry-Chen/Learn-Helper/issues/145
+  const json = await (await s.fetchWithToken(URLS.LEARN_COURSE_TIME_LOCATION(courseID))).json();
+  if (!Array.isArray(json)) {
+    throw { reason: FailReason.INVALID_RESPONSE, extra: json } as ApiError;
+  }
+  return json as string[];
+}
+
+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);
+}