@robertying/thu-learn-lib 5.0.0 → 6.0.0

package/src/auth.ts

@@ -3,39 +3,35 @@
 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 { discard, isConnectionError } from './request.ts';
+import type { Credential } from './types.ts';
+import { CourseType, FailReason, Language } from './types.ts';
 import * as URLS from './urls.ts';
+import { $, apiError } from './utils.ts';
+
+/** a `Credential` with everything an SSO login needs */
+export type CompleteCredential = Credential & { username: string; password: string; fingerPrint: string };
+
+/** whether `credential` has a username, a password and a fingerprint */
+export const isComplete = (credential: Credential | undefined): credential is CompleteCredential =>
+  !!credential?.username && !!credential.password && !!credential.fingerPrint;
 
 /**
  * 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.
+export async function getRoamingTicket(s: Session, credential: CompleteCredential): Promise<string> {
+  const { username, password, fingerPrint, fingerGenPrint = '', fingerGenPrint3 = '' } = credential;
+  // start from the login form without an id.tsinghua.edu.cn session: one left in the cookies may be another user's
   try {
     await s.cookieJar.setCookie('JSESSIONID=; path=/; HttpOnly', URLS.ID_PREFIX);
   } catch (err) {
-    throw {
-      reason: FailReason.ERROR_SETTING_COOKIES,
-      extra: err,
-    } as ApiError;
+    throw apiError(FailReason.ERROR_SETTING_COOKIES, err);
   }
 
+  let page: string;
   try {
-    const loginForm = await s.rawFetch(URLS.ID_LOGIN());
+    const loginForm = await s.rawFetch(URLS.ID_LOGIN);
     const body = $(await loginForm.text());
     const sm2publicKey = body('#sm2publicKey').text().trim();
 
@@ -44,78 +40,84 @@ export async function getRoamingTicket(
     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('fingerGenPrint', fingerGenPrint);
+    formData.append('fingerGenPrint3', fingerGenPrint3);
     formData.append('i_captcha', '');
-    const checkResponse = await s.rawFetch(URLS.ID_LOGIN_CHECK(), {
+    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;
+    if (!checkResponse.ok) {
+      throw { code: checkResponse.status, text: checkResponse.statusText };
+    }
+    page = await checkResponse.text();
   } catch (err) {
-    throw {
-      reason: FailReason.ERROR_FETCH_FROM_ID,
-      extra: err,
-    } as ApiError;
+    // no answer at all: the device is offline or id.tsinghua.edu.cn is unreachable, not a refused login
+    if (isConnectionError(err)) throw err;
+    throw apiError(FailReason.ERROR_FETCH_FROM_ID, err);
   }
+
+  // id.tsinghua.edu.cn answers with a page whose only link is the roaming URL (with the ticket), or with the login form
+  // again (with its links to the password reset, guides, phone and mail) for a wrong password
+  const body = $(page);
+  const ticket = ticketOf(body('a[href*="ticket="]').attr('href'));
+  if (ticket) return ticket;
+  if (body('#theform, form[action*="/auth/login/check"]').length > 0 && body('#i_pass').length > 0) {
+    throw apiError(FailReason.BAD_CREDENTIAL, textOf(body('#msg_note, .alert-danger')) || undefined);
+  }
+  // something else, e.g. a second factor, a locked account or maintenance: not a wrong password
+  throw apiError(
+    FailReason.ERROR_FETCH_FROM_ID,
+    textOf(body('body').clone().find('script, style').remove().end()).slice(0, 200),
+  );
 }
 
-/** 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,
-      });
-    }
+const textOf = (el: { text(): string }) => el.text().replace(/\s+/g, ' ').trim();
+
+const ticketOf = (href: string | undefined): string | undefined => {
+  if (!href) return undefined;
+  try {
+    return new URL(href, URLS.ID_PREFIX).searchParams.get('ticket') || undefined;
+  } catch {
+    return undefined;
   }
+};
+
+/** log in with the `CredentialProvider`; `NO_CREDENTIAL` without one, or when it gives an incomplete credential */
+export async function loginWithProvider(s: Session): Promise<void> {
+  const credential = await s.provider?.();
+  if (!isComplete(credential)) throw apiError(FailReason.NO_CREDENTIAL);
+  return login(s, credential);
+}
 
-  // check response from id.tsinghua.edu.cn
-  const ticket = await getRoamingTicket(s, username, password, fingerPrint, fingerGenPrint, fingerGenPrint3);
+/** log in through id.tsinghua.edu.cn, then read the CSRF token and the website language from the homepage */
+export async function login(s: Session, credential: CompleteCredential): Promise<void> {
+  const ticket = await getRoamingTicket(s, credential);
+  const { fingerPrint, fingerGenPrint = '', fingerGenPrint3 = '' } = credential;
+  s.fingerprints = { fingerPrint, fingerGenPrint, fingerGenPrint3 };
 
   const loginResponse = await s.rawFetch(URLS.LEARN_AUTH_ROAM(ticket));
+  // only the status matters
+  discard(loginResponse);
   if (!loginResponse.ok) {
-    return Promise.reject({
-      reason: FailReason.ERROR_ROAMING,
-    });
+    throw apiError(FailReason.ERROR_ROAMING);
   }
-  const courseListPageSource: string = await (await s.rawFetch(URLS.LEARN_STUDENT_COURSE_LIST_PAGE())).text();
+  const courseListPageSource: string = await (await s.rawFetch(URLS.LEARN_HOMEPAGE(CourseType.STUDENT))).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',
-    });
+    throw apiError(FailReason.INVALID_RESPONSE, 'cannot fetch CSRF token from source');
   }
   s.csrfToken = tokenMatches[0][1];
-  const langRegex = /<script src="\/f\/wlxt\/common\/languagejs\?lang=(zh|en)"><\/script>/g;
+  // the homepage loads e.g. `/f/wlxt/common/languagejs?lang=zh_CN&v=845`
+  const langRegex = /\/f\/wlxt\/common\/languagejs\?lang=(zh|en)/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) */
+/**  logout (to make everyone happy); the CSRF token is cleared, so the next request logs in again */
 export async function logout(s: Session): Promise<void> {
-  await s.rawFetch(URLS.LEARN_LOGOUT(), { method: 'POST' });
+  discard(await s.rawFetch(URLS.LEARN_LOGOUT, { method: 'POST' }));
+  s.csrfToken = '';
 }

package/src/calendar.ts

@@ -1,21 +1,30 @@
-// Course calendar from the registrar (academic.tsinghua.edu.cn).
+// Course calendar from the registrar (zhjw.cic.tsinghua.edu.cn).
 
 import type { Session } from './request.ts';
-import type { CalendarEvent, CalendarOptions, CalendarRange, CalendarResult } from './types.ts';
+import { discard } from './request.ts';
+import type { ApiError, 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';
+import { $, JSONP_EXTRACTOR_NAME, apiError, 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. */
+/**
+ * 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;
 
+/** after this many windows in a row time out, `getCalendar` gives up on the rest (they go to `failedRanges`) */
+const MAX_CONSECUTIVE_TIMEOUTS = 2;
+
+const isTimeout = (err: unknown) => (err as ApiError | undefined)?.reason === FailReason.REQUEST_TIMEOUT;
+
 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` };
+    throw new RangeError(`invalid date ${date}, expected yyyymmdd`);
   }
   return time;
 };
@@ -34,18 +43,112 @@ export function splitCalendarRange(startDate: string, endDate: string, days = CA
   return ranges;
 }
 
+const FINGERPRINT_FIELDS = ['fingerPrint', 'fingerGenPrint', 'fingerGenPrint3'] as const;
+const isFingerprintField = (name: string): name is (typeof FINGERPRINT_FIELDS)[number] =>
+  (FINGERPRINT_FIELDS as readonly string[]).includes(name);
+
+/** `extra.step` of an `ERROR_REGISTRAR_AUTH` that id.tsinghua.edu.cn turned down (rather than the registrar failing) */
+const ID_STEP = 'id.tsinghua.edu.cn';
+
+const isIdRefusal = (err: unknown) =>
+  (err as ApiError | undefined)?.reason === FailReason.ERROR_REGISTRAR_AUTH &&
+  ((err as ApiError).extra as { step?: string } | undefined)?.step === ID_STEP;
+
+/** an id.tsinghua.edu.cn login form (`/do/off/ui/auth/login/check`, `.../checkSingle`) */
+const isIdLoginPage = (res: Response, page: string) =>
+  res.url.startsWith(URLS.ID_PREFIX) || /action="[^"]*\/do\/off\/ui\/auth\/login\//.test(page);
+
+/**
+ * The body of a sign-in step, or '' when there is no text. The registrar's own pages are GBK, which React Native's
+ * fetch can't decode: its `text()` then gives `undefined` instead of a string. Only id.tsinghua.edu.cn pages (UTF-8)
+ * are looked into here, so an undecodable registrar page is as good as an empty one.
+ */
+const readText = async (res: Response): Promise<string> => {
+  const text: unknown = await res.text();
+  return typeof text === 'string' ? text : '';
+};
+
+/**
+ * Sign in to the registrar with a Web Learning ticket.
+ *
+ * Registrar requests use `rawFetch`, without the Web Learning login check: a 403 or login page from the registrar says
+ * nothing about the Web Learning session, and logging in there again wouldn't renew the registrar ticket. They don't
+ * carry Web Learning's CSRF token either: the registrar (and WebVPN in front of it off campus) has no use for it.
+ *
+ * Off campus the registrar is only reachable through WebVPN (webvpn.tsinghua.edu.cn): the auth URL redirects there,
+ * and WebVPN signs in through id.tsinghua.edu.cn OAuth. As the id.tsinghua.edu.cn session of the Web Learning login is
+ * still there, id.tsinghua.edu.cn answers with a form (`#logined`) that a browser submits right away with its device
+ * fingerprints. Submitting it answers with a page that links (by script) to the OAuth callback, which signs in to WebVPN
+ * and redirects back to the auth URL, so following the link ends on the registrar.
+ */
+async function authenticateRegistrar(s: Session, ticket: string): Promise<void> {
+  let res = await s.rawFetch(URLS.REGISTRAR_AUTH(ticket));
+  let page = await readText(res);
+
+  const form = $(page)('form#logined');
+  if (form.length > 0) {
+    const fingerprints = s.fingerprints ?? (await s.provider?.());
+    const data = new FormData();
+    form.find('input[name]').each((_, input) => {
+      const name = input.attribs.name;
+      const known = isFingerprintField(name) ? fingerprints?.[name] : undefined;
+      data.append(name, known ?? input.attribs.value ?? '');
+    });
+    const action = new URL(form.attr('action') ?? '', res.url || URLS.ID_PREFIX).href;
+    const check = await s.rawFetch(action, { method: 'POST', body: data });
+    const link = check.ok ? $(await readText(check))('a').attr('href') : undefined;
+    if (!link) {
+      discard(check);
+      throw apiError(FailReason.ERROR_REGISTRAR_AUTH, { step: ID_STEP, code: check.status });
+    }
+    res = await s.rawFetch(new URL(link, check.url || action).href);
+    page = await readText(res);
+  }
+
+  if (isIdLoginPage(res, page)) {
+    throw apiError(FailReason.ERROR_REGISTRAR_AUTH, { step: ID_STEP, code: res.status, url: res.url.split('?')[0] });
+  }
+  if (!res.ok) {
+    throw apiError(FailReason.ERROR_REGISTRAR_AUTH, { code: res.status, url: res.url.split('?')[0] });
+  }
+}
+
+/**
+ * Get a registrar ticket and sign in to the registrar with it. When id.tsinghua.edu.cn turns the sign-in down (its
+ * session from the last login has expired, e.g. in a session resumed from saved cookies) and there is a
+ * `CredentialProvider`, log in to Web Learning again (a new id.tsinghua.edu.cn session) and try once more.
+ */
+async function signInToRegistrar(s: Session): Promise<void> {
+  const signIn = async () => {
+    const ticket = await s.fetchTextWithToken(URLS.REGISTRAR_TICKET, {
+      method: 'POST',
+      body: URLS.REGISTRAR_TICKET_FORM_DATA(),
+    });
+    await authenticateRegistrar(s, ticket.substring(1, ticket.length - 1));
+  };
+  try {
+    await signIn();
+  } catch (err) {
+    if (!s.provider || !isIdRefusal(err)) throw err;
+    await s.autoRelogin();
+    await signIn();
+  }
+}
+
 async function fetchWindow(s: Session, range: CalendarRange, graduate: boolean): Promise<CalendarEvent[]> {
-  const response = await s.fetchWithToken(
+  const response = await s.rawFetch(
     URLS.REGISTRAR_CALENDAR(range.startDate, range.endDate, graduate, JSONP_EXTRACTOR_NAME),
   );
 
   if (!response.ok) {
-    return Promise.reject({
-      reason: FailReason.INVALID_RESPONSE,
-    });
+    discard(response);
+    throw apiError(FailReason.INVALID_RESPONSE, { code: response.status, text: response.statusText });
   }
 
-  const result = extractJSONPResult(await response.text()) as any[];
+  const result: unknown = extractJSONPResult(await response.text());
+  if (!Array.isArray(result)) {
+    throw apiError(FailReason.INVALID_RESPONSE, result);
+  }
 
   return result.map<CalendarEvent>((i) => ({
     location: i.dd,
@@ -60,10 +163,14 @@ async function fetchWindow(s: Session, range: CalendarRange, graduate: boolean):
 /**
  * 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.
+ * Ranges longer than `CALENDAR_WINDOW_DAYS` are fetched in consecutive windows (one at a time, each retried once
+ * unless it timed out) and merged in date order. Windows that still fail are listed in `failedRanges`, so callers can
+ * show partial data and retry only those; after two windows in a row time out, the rest are listed there without a
+ * request. 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. Throws a `RangeError` for a date that is not a
+ * valid yyyymmdd, and rejects with `FailReason.ERROR_REGISTRAR_AUTH` if signing in to the registrar fails. Off campus
+ * this goes through WebVPN and needs the id.tsinghua.edu.cn session of the last `login`; when that has expired, a
+ * helper with a `CredentialProvider` logs in again and tries once more.
  */
 export async function getCalendar(
   s: Session,
@@ -75,25 +182,30 @@ export async function getCalendar(
   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));
+  await signInToRegistrar(s);
 
   const events: CalendarEvent[] = [];
   const failedRanges: CalendarRange[] = [];
   let lastError: unknown;
+  let timeouts = 0;
   for (const range of ranges) {
+    // after this many timed-out windows in a row the registrar is taken as down, and the rest are not tried
+    if (timeouts >= MAX_CONSECUTIVE_TIMEOUTS) {
+      failedRanges.push(range);
+      continue;
+    }
     try {
-      events.push(...(await fetchWindow(s, range, graduate).catch(() => fetchWindow(s, range, graduate))));
+      // a timed-out window is not retried: the registrar is slow, not flaky, and each try takes `requestTimeout`
+      events.push(
+        ...(await fetchWindow(s, range, graduate).catch((err: unknown) =>
+          isTimeout(err) ? Promise.reject(err) : fetchWindow(s, range, graduate),
+        )),
+      );
+      timeouts = 0;
     } catch (e) {
       lastError = e;
       failedRanges.push(range);
+      timeouts = isTimeout(e) ? timeouts + 1 : 0;
     }
   }
 

package/src/contents.ts

@@ -2,6 +2,7 @@
 
 import type { Session } from './request.ts';
 import type { AllContentsOptions, AllContentsResult, ContentTypeMap, CourseContent } from './types.ts';
+import { apiError } from './utils.ts';
 import { ContentType, CourseType, FailReason } from './types.ts';
 import { getAnsweredQuestionList, getDiscussionList } from './discussions.ts';
 import { getFileList } from './files.ts';
@@ -20,7 +21,7 @@ export async function getAllContents<T extends ContentType>(
   options: AllContentsOptions<T> = {},
 ): Promise<AllContentsResult<T>> {
   const courseType = options.courseType ?? CourseType.STUDENT;
-  const fetchContentForCourse = (id: string): Promise<ContentTypeMap[T][]> => {
+  const fetchContentForCourse = async (id: string): Promise<ContentTypeMap[T][]> => {
     switch (type) {
       case ContentType.NOTIFICATION:
         return getNotificationList(s, id, courseType, {
@@ -29,6 +30,13 @@ export async function getAllContents<T extends ContentType>(
       case ContentType.FILE:
         return getFileList(s, id, courseType) as Promise<ContentTypeMap[T][]>;
       case ContentType.HOMEWORK:
+        if (courseType === CourseType.TEACHER) {
+          // the teacher list has another shape (`HomeworkTA`); use `getHomeworkList(id, CourseType.TEACHER)`
+          throw apiError(
+            FailReason.NOT_IMPLEMENTED,
+            'homework of a teacher course; use getHomeworkList(courseID, CourseType.TEACHER)',
+          );
+        }
         return getHomeworkList(s, id, CourseType.STUDENT, {
           details: (options as AllContentsOptions<ContentType.HOMEWORK>).details,
         }) as Promise<ContentTypeMap[T][]>;
@@ -37,12 +45,11 @@ export async function getAllContents<T extends ContentType>(
       case ContentType.QUESTION:
         return getAnsweredQuestionList(s, id, courseType) as Promise<ContentTypeMap[T][]>;
       case ContentType.QUESTIONNAIRE:
-        return getQuestionnaireList(s, id) as Promise<ContentTypeMap[T][]>;
+        return getQuestionnaireList(s, id, {
+          details: (options as AllContentsOptions<ContentType.QUESTIONNAIRE>).details,
+        }) as Promise<ContentTypeMap[T][]>;
       default:
-        return Promise.reject({
-          reason: FailReason.NOT_IMPLEMENTED,
-          extra: 'Unknown content type',
-        });
+        throw apiError(FailReason.NOT_IMPLEMENTED, 'Unknown content type');
     }
   };
 

package/src/courses.ts

@@ -1,31 +1,25 @@
 // Semesters and courses.
 
 import type { Session } from './request.ts';
-import type { ApiError, CourseInfo, CourseListOptions, SemesterInfo } from './types.ts';
+import type { CourseInfo, CourseListOptions, SemesterInfo } from './types.ts';
 import { CourseType, FailReason } from './types.ts';
 import * as URLS from './urls.ts';
-import { decodeHTML, parseSemesterType } from './utils.ts';
+import { apiError, decodeHTML, expectSuccess, parseSemesterType } from './utils.ts';
 
 export async function getSemesterIdList(s: Session): Promise<string[]> {
-  const json = await (await s.fetchWithToken(URLS.LEARN_SEMESTER_LIST())).json();
+  const json = await s.fetchJsonWithToken(URLS.LEARN_SEMESTER_LIST);
   if (!Array.isArray(json)) {
-    return Promise.reject({
-      reason: FailReason.INVALID_RESPONSE,
-      extra: json,
-    });
+    throw apiError(FailReason.INVALID_RESPONSE, json);
   }
   const semesters = json as string[];
-  // sometimes web learning returns null, so confusing...
+  // the list can contain null entries
   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();
+  const json = await s.fetchJsonWithToken(URLS.LEARN_CURRENT_SEMESTER);
   if (json.message !== 'success') {
-    return Promise.reject({
-      reason: FailReason.INVALID_RESPONSE,
-      extra: json,
-    });
+    throw apiError(FailReason.INVALID_RESPONSE, json);
   }
   const result = json.result;
   return {
@@ -46,14 +40,11 @@ export async function getCourseList(
   lang = s.lang,
   options: CourseListOptions = {},
 ): Promise<CourseInfo[]> {
-  const json = await (await s.fetchWithToken(URLS.LEARN_COURSE_LIST(semesterID, courseType, lang))).json();
+  const json = await s.fetchJsonWithToken(URLS.LEARN_COURSE_LIST(semesterID, courseType, lang));
   if (json.message !== 'success' || !Array.isArray(json.resultList)) {
-    return Promise.reject({
-      reason: FailReason.INVALID_RESPONSE,
-      extra: json,
-    });
+    throw apiError(FailReason.INVALID_RESPONSE, json);
   }
-  const result = (json.resultList ?? []) as any[];
+  const result = json.resultList as any[];
 
   return Promise.all(
     result.map(async (c) => {
@@ -62,7 +53,7 @@ export async function getCourseList(
         try {
           timeAndLocation = await getCourseTimeAndLocation(s, c.wlkcid);
         } catch {
-          timeAndLocation = [];
+          // left out, so a failure doesn't look like a course without a schedule; see `getCourseTimeAndLocation`
         }
       }
       return {
@@ -85,27 +76,20 @@ export async function getCourseList(
 /** 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();
+  const json = await s.fetchJsonWithToken(URLS.LEARN_COURSE_TIME_LOCATION(courseID));
   if (!Array.isArray(json)) {
-    throw { reason: FailReason.INVALID_RESPONSE, extra: json } as ApiError;
+    throw apiError(FailReason.INVALID_RESPONSE, json);
   }
   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,
-    });
-  }
+  const json = await s.fetchJsonWithToken(URLS.LEARN_SORT_COURSES, {
+    method: 'POST',
+    body: JSON.stringify(courseIDs.map((id, index) => ({ wlkcid: id, xh: index + 1 }))),
+    headers: {
+      'Content-Type': 'application/json',
+    },
+  });
+  expectSuccess(json, FailReason.OPERATION_FAILED);
 }

package/src/discussions.ts

@@ -3,11 +3,10 @@
 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 type { Discussion, DiscussionBase, Question } from './types.ts';
 import { CourseType, FailReason } from './types.ts';
 import * as URLS from './urls.ts';
-import { decodeHTML } from './utils.ts';
+import { YES, decodeHTML, expectSuccess, toRequiredServerTime } from './utils.ts';
 
 /** Get all discussions （课程讨论） of the specified course. */
 export async function getDiscussionList(
@@ -15,13 +14,8 @@ export async function getDiscussionList(
   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 json = await s.fetchJsonWithToken(URLS.LEARN_DISCUSSION_LIST(courseID, courseType));
+  expectSuccess(json, FailReason.INVALID_RESPONSE);
 
   const result = (json.object?.resultsList ?? []) as any[];
 
@@ -44,13 +38,8 @@ export async function getAnsweredQuestionList(
   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 json = await s.fetchJsonWithToken(URLS.LEARN_QUESTION_LIST_ANSWERED(courseID, courseType));
+  expectSuccess(json, FailReason.INVALID_RESPONSE);
 
   const result = (json.object?.resultsList ?? []) as any[];
 
@@ -58,19 +47,19 @@ export async function getAnsweredQuestionList(
     (q) =>
       ({
         ...parseDiscussionBase(q),
-        question: Base64.decode(q.wtnr),
+        question: Base64.decode(q.wtnr ?? ''),
         url: URLS.LEARN_QUESTION_DETAIL(q.wlkcid, q.id, courseType),
       }) satisfies Question,
   );
 }
 
-function parseDiscussionBase(d: any): IDiscussionBase {
+function parseDiscussionBase(d: any): DiscussionBase {
   return {
     id: d.id,
     title: decodeHTML(d.bt),
     publisherName: d.fbrxm,
-    publishTime: d.fbsj,
-    lastReplyTime: d.zhhfsj,
+    publishTime: toRequiredServerTime(d.fbsj),
+    lastReplyTime: toRequiredServerTime(d.zhhfsj),
     lastReplierName: d.zhhfrxm,
     visitCount: d.djs ?? 0, // teacher cannot fetch this
     replyCount: d.hfcs,