@robertying/thu-learn-lib 5.0.0 → 5.1.0

package/src/auth.ts

@@ -34,6 +34,7 @@ export async function getRoamingTicket(
     } as ApiError;
   }
 
+  let page: string;
   try {
     const loginForm = await s.rawFetch(URLS.ID_LOGIN());
     const body = $(await loginForm.text());
@@ -52,16 +53,27 @@ export async function getRoamingTicket(
       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;
   }
+
+  // id.tsinghua.edu.cn answers with a link to the roaming URL (with the ticket), or with the form and an error
+  const body = $(page);
+  const redirectUrl = body('a').attr('href');
+  if (!redirectUrl) {
+    throw {
+      reason: FailReason.BAD_CREDENTIAL,
+      extra: body.root().text().replace(/\s+/g, ' ').trim().slice(0, 200),
+    } as ApiError;
+  }
+  return redirectUrl.split('=').slice(-1)[0];
 }
 
 /** login is necessary if you do not provide a `CredentialProvider` */
@@ -115,7 +127,8 @@ export async function login(
   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' });
+  s.csrfToken = '';
 }

package/src/calendar.ts

@@ -1,7 +1,7 @@
 // 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 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';
@@ -11,11 +11,16 @@ 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;
 };
@@ -60,10 +65,12 @@ 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.
  */
 export async function getCalendar(
   s: Session,
@@ -75,12 +82,10 @@ export async function getCalendar(
   const ranges = splitCalendarRange(startDate, endDate);
   if (ranges.length === 0) return { events: [], failedRanges: [] };
 
-  const ticketResponse = await s.fetchWithToken(URLS.REGISTRAR_TICKET(), {
+  let ticket = await s.fetchTextWithToken(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));
@@ -88,12 +93,25 @@ export async function getCalendar(
   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

@@ -29,6 +29,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)`
+          return Promise.reject({
+            reason: FailReason.NOT_IMPLEMENTED,
+            extra: '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,7 +44,9 @@ 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,

package/src/courses.ts

@@ -7,7 +7,7 @@ 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();
+  const json = await s.fetchJsonWithToken(URLS.LEARN_SEMESTER_LIST());
   if (!Array.isArray(json)) {
     return Promise.reject({
       reason: FailReason.INVALID_RESPONSE,
@@ -20,7 +20,7 @@ export async function getSemesterIdList(s: Session): Promise<string[]> {
 }
 
 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,
@@ -46,7 +46,7 @@ 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,
@@ -85,7 +85,7 @@ 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;
   }
@@ -93,15 +93,13 @@ export async function getCourseTimeAndLocation(s: Session, courseID: string): Pr
 }
 
 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();
+  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',
+    },
+  });
   if (json.result !== 'success') {
     return Promise.reject({
       reason: FailReason.OPERATION_FAILED,

package/src/discussions.ts

@@ -15,7 +15,7 @@ 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();
+  const json = await s.fetchJsonWithToken(URLS.LEARN_DISCUSSION_LIST(courseID, courseType));
   if (json.result !== 'success') {
     return Promise.reject({
       reason: FailReason.INVALID_RESPONSE,
@@ -44,7 +44,7 @@ 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();
+  const json = await s.fetchJsonWithToken(URLS.LEARN_QUESTION_LIST_ANSWERED(courseID, courseType));
   if (json.result !== 'success') {
     return Promise.reject({
       reason: FailReason.INVALID_RESPONSE,

package/src/favorites.ts

@@ -11,7 +11,7 @@ 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();
+  const json = await s.fetchJsonWithToken(URLS.LEARN_FAVORITE_ADD(type, id));
   if (json.result !== 'success' || !json.msg?.endsWith?.('成功')) {
     return Promise.reject({
       reason: FailReason.OPERATION_FAILED,
@@ -24,7 +24,7 @@ export async function addToFavorites(s: Session, type: ContentType, id: string):
  * 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();
+  const json = await s.fetchJsonWithToken(URLS.LEARN_FAVORITE_REMOVE(id));
   if (json.result !== 'success' || !json.msg?.endsWith?.('成功')) {
     return Promise.reject({
       reason: FailReason.OPERATION_FAILED,
@@ -38,12 +38,10 @@ export async function removeFromFavorites(s: Session, id: string): Promise<void>
  * 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();
+  const json = await s.fetchJsonWithToken(URLS.LEARN_FAVORITE_LIST(type), {
+    method: 'POST',
+    body: URLS.LEARN_PAGE_LIST_FORM_DATA(courseID),
+  });
   if (json.result !== 'success') {
     return Promise.reject({
       reason: FailReason.INVALID_RESPONSE,
@@ -78,12 +76,10 @@ export async function getFavorites(s: Session, courseID?: string, type?: Content
  * 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();
+  const json = await s.fetchJsonWithToken(URLS.LEARN_FAVORITE_PIN, {
+    method: 'POST',
+    body: URLS.LEARN_FAVORITE_PIN_UNPIN_FORM_DATA(id),
+  });
   if (json.result !== 'success') {
     return Promise.reject({
       reason: FailReason.OPERATION_FAILED,
@@ -96,12 +92,10 @@ export async function pinFavoriteItem(s: Session, id: string): Promise<void> {
  * 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();
+  const json = await s.fetchJsonWithToken(URLS.LEARN_FAVORITE_UNPIN, {
+    method: 'POST',
+    body: URLS.LEARN_FAVORITE_PIN_UNPIN_FORM_DATA(id),
+  });
   if (json.result !== 'success') {
     return Promise.reject({
       reason: FailReason.OPERATION_FAILED,
@@ -115,12 +109,10 @@ export async function unpinFavoriteItem(s: Session, id: string): Promise<void> {
  * 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();
+  const json = await s.fetchJsonWithToken(URLS.LEARN_COMMENT_SET, {
+    method: 'POST',
+    body: URLS.LEARN_COMMENT_SET_FORM_DATA(type, id, content),
+  });
   if (json.result !== 'success' || !json.msg?.endsWith?.('成功')) {
     return Promise.reject({
       reason: FailReason.OPERATION_FAILED,
@@ -134,12 +126,10 @@ export async function setComment(s: Session, type: ContentType, id: string, cont
  * 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();
+  const json = await s.fetchJsonWithToken(URLS.LEARN_COMMENT_LIST(type), {
+    method: 'POST',
+    body: URLS.LEARN_PAGE_LIST_FORM_DATA(courseID),
+  });
   if (json.result !== 'success') {
     return Promise.reject({
       reason: FailReason.INVALID_RESPONSE,

package/src/files.ts

@@ -6,13 +6,13 @@ import { ContentType, CourseType, FailReason } from './types.ts';
 import * as URLS from './urls.ts';
 import { decodeHTML, formatFileSize } from './utils.ts';
 
-/** Get all files （课程文件） of the specified course. */
+/** Get all files （课程文件） of the specified course; `category` is left out if the categories can't be fetched. */
 export async function getFileList(
   s: Session,
   courseID: string,
   courseType: CourseType = CourseType.STUDENT,
 ): Promise<File[]> {
-  const json = await (await s.fetchWithToken(URLS.LEARN_FILE_LIST(courseID, courseType))).json();
+  const json = await s.fetchJsonWithToken(URLS.LEARN_FILE_LIST(courseID, courseType));
   if (json.result !== 'success') {
     return Promise.reject({
       reason: FailReason.INVALID_RESPONSE,
@@ -29,7 +29,9 @@ export async function getFileList(
     result = json.object;
   }
 
-  const categories = new Map((await getFileCategoryList(s, courseID, courseType)).map((c) => [c.id, c]));
+  // categories only fill `category`; don't fail the whole list when they can't be fetched
+  const categoryList = await getFileCategoryList(s, courseID, courseType).catch(() => []);
+  const categories = new Map(categoryList.map((c) => [c.id, c]));
 
   return result.map((f) => {
     const title = decodeHTML(f.bt);
@@ -71,7 +73,7 @@ export async function getFileCategoryList(
   courseID: string,
   courseType: CourseType = CourseType.STUDENT,
 ): Promise<FileCategory[]> {
-  const json = await (await s.fetchWithToken(URLS.LEARN_FILE_CATEGORY_LIST(courseID, courseType))).json();
+  const json = await s.fetchJsonWithToken(URLS.LEARN_FILE_CATEGORY_LIST(courseID, courseType));
   if (json.result !== 'success') {
     return Promise.reject({
       reason: FailReason.INVALID_RESPONSE,
@@ -102,7 +104,7 @@ export async function getFileListByCategory(
   courseType: CourseType = CourseType.STUDENT,
 ): Promise<File[]> {
   if (courseType === CourseType.STUDENT) {
-    const json = await (await s.fetchWithToken(URLS.LEARN_FILE_LIST_BY_CATEGORY_STUDENT(courseID, categoryId))).json();
+    const json = await s.fetchJsonWithToken(URLS.LEARN_FILE_LIST_BY_CATEGORY_STUDENT(courseID, categoryId));
     if (json.result !== 'success') {
       return Promise.reject({
         reason: FailReason.INVALID_RESPONSE,
@@ -147,12 +149,10 @@ export async function getFileListByCategory(
       } satisfies File;
     });
   } else {
-    const json = await (
-      await s.fetchWithToken(URLS.LEARN_FILE_LIST_BY_CATEGORY_TEACHER, {
-        method: 'POST',
-        body: URLS.LEARN_FILE_LIST_BY_CATEGORY_TEACHER_FORM_DATA(courseID, categoryId),
-      })
-    ).json();
+    const json = await s.fetchJsonWithToken(URLS.LEARN_FILE_LIST_BY_CATEGORY_TEACHER, {
+      method: 'POST',
+      body: URLS.LEARN_FILE_LIST_BY_CATEGORY_TEACHER_FORM_DATA(courseID, categoryId),
+    });
     if (json.result !== 'success') {
       return Promise.reject({
         reason: FailReason.INVALID_RESPONSE,
@@ -160,7 +160,7 @@ export async function getFileListByCategory(
       });
     }
 
-    const result = (json.object.aaData ?? []) as any[];
+    const result = (json.object?.aaData ?? []) as any[];
 
     return result.map((f) => {
       const title = decodeHTML(f.bt);

package/src/homework.ts

@@ -26,12 +26,10 @@ import { GRADE_LEVEL_MAP, decodeHTML, isSelected, trimAndDefine } from './utils.
  * Get all homeworks （课程作业） of the specified course: 3 status lists and the excellent homework list.
  * Details (page + description) only for the homework `options.details` selects.
  */
-export function getHomeworkList(s: Session, courseID: string): Promise<Homework[]>;
-
 export function getHomeworkList(
   s: Session,
   courseID: string,
-  courseType: CourseType.STUDENT,
+  courseType?: CourseType.STUDENT,
   options?: HomeworkListOptions,
 ): Promise<Homework[]>;
 
@@ -44,12 +42,10 @@ export async function getHomeworkList(
   options: HomeworkListOptions = {},
 ): Promise<Homework[] | HomeworkTA[]> {
   if (courseType === CourseType.TEACHER) {
-    const json = await (
-      await s.fetchWithToken(URLS.LEARN_HOMEWORK_LIST_TEACHER, {
-        method: 'POST',
-        body: URLS.LEARN_PAGE_LIST_FORM_DATA(courseID),
-      })
-    ).json();
+    const json = await s.fetchJsonWithToken(URLS.LEARN_HOMEWORK_LIST_TEACHER, {
+      method: 'POST',
+      body: URLS.LEARN_PAGE_LIST_FORM_DATA(courseID),
+    });
     if (json.result !== 'success') {
       return Promise.reject({
         reason: FailReason.INVALID_RESPONSE,
@@ -102,12 +98,10 @@ async function getHomeworkListAtUrl(
   url: string,
   status: IHomeworkStatus,
 ): Promise<IHomework[]> {
-  const json = await (
-    await s.fetchWithToken(url, {
-      method: 'POST',
-      body: URLS.LEARN_PAGE_LIST_FORM_DATA(courseID),
-    })
-  ).json();
+  const json = await s.fetchJsonWithToken(url, {
+    method: 'POST',
+    body: URLS.LEARN_PAGE_LIST_FORM_DATA(courseID),
+  });
   if (json.result !== 'success') {
     return Promise.reject({
       reason: FailReason.INVALID_RESPONSE,
@@ -149,12 +143,10 @@ async function getExcellentHomeworkListByHomework(
   s: Session,
   courseID: string,
 ): Promise<{ [id: string]: ExcellentHomework[] }> {
-  const json = await (
-    await s.fetchWithToken(URLS.LEARN_HOMEWORK_LIST_EXCELLENT, {
-      method: 'POST',
-      body: URLS.LEARN_PAGE_LIST_FORM_DATA(courseID),
-    })
-  ).json();
+  const json = await s.fetchJsonWithToken(URLS.LEARN_HOMEWORK_LIST_EXCELLENT, {
+    method: 'POST',
+    body: URLS.LEARN_PAGE_LIST_FORM_DATA(courseID),
+  });
   if (json.result !== 'success') {
     return Promise.reject({
       reason: FailReason.INVALID_RESPONSE,
@@ -190,8 +182,7 @@ async function getExcellentHomeworkListByHomework(
 }
 
 async function parseHomeworkAtUrl(s: Session, url: string): Promise<IHomeworkDetail> {
-  const response = await s.fetchWithToken(url);
-  const result = $(await response.text());
+  const result = $(await s.fetchTextWithToken(url));
 
   const fileDivs = result('div.list.fujian.clearfix');
 
@@ -222,12 +213,10 @@ export async function getHomeworkDetail(
 }
 
 async function getHomeworkDescription(s: Session, baseId: string): Promise<IHomeworkDetail> {
-  const json = await (
-    await s.fetchWithToken(URLS.LEARN_HOMEWORK_DETAIL, {
-      method: 'POST',
-      body: URLS.LEARN_HOMEWORK_DETAIL_FORM_DATA(baseId),
-    })
-  ).json();
+  const json = await s.fetchJsonWithToken(URLS.LEARN_HOMEWORK_DETAIL, {
+    method: 'POST',
+    body: URLS.LEARN_HOMEWORK_DETAIL_FORM_DATA(baseId),
+  });
   if (json.result !== 'success') {
     throw {
       reason: FailReason.INVALID_RESPONSE,
@@ -241,18 +230,19 @@ async function getHomeworkDescription(s: Session, baseId: string): Promise<IHome
 
 function parseHomeworkFile(s: Session, fileDiv: Element): RemoteFile | undefined {
   const fileNode = $(fileDiv)('.ftitle').children('a')[0] ?? $(fileDiv)('.fl').children('a')[0];
-  if (fileNode !== undefined) {
-    const size = trimAndDefine($(fileDiv)('.fl > span[class^="color"]').first().text())!;
-    const params = new URLSearchParams(fileNode.attribs.href.split('?').slice(-1)[0]);
+  const href = fileNode?.attribs.href;
+  if (fileNode !== undefined && href) {
+    const size = trimAndDefine($(fileDiv)('.fl > span[class^="color"]').first().text()) ?? '';
+    const params = new URLSearchParams(href.split('?').slice(-1)[0]);
     const attachmentId = params.get('fileId')!;
     // so dirty here...
-    let downloadUrl = URLS.LEARN_PREFIX + fileNode.attribs.href;
+    let downloadUrl = URLS.LEARN_PREFIX + href;
     if (params.has('downloadUrl')) {
       downloadUrl = URLS.LEARN_PREFIX + params.get('downloadUrl')!;
     }
     return {
       id: attachmentId,
-      name: (fileNode.children[0] as { data: string }).data,
+      name: (fileNode.children[0] as { data?: string } | undefined)?.data ?? '',
       downloadUrl,
       previewUrl: URLS.LEARN_FILE_PREVIEW(ContentType.HOMEWORK, attachmentId, CourseType.STUDENT, s.previewFirstPage),
       size,
@@ -269,12 +259,12 @@ export async function submitHomework(
   attachment?: IHomeworkSubmitAttachment,
   removeAttachment = false,
 ): Promise<void> {
-  const json = await (
-    await s.fetchWithToken(URLS.LEARN_HOMEWORK_SUBMIT(), {
-      method: 'POST',
-      body: URLS.LEARN_HOMEWORK_SUBMIT_FORM_DATA(id, content, attachment, removeAttachment),
-    })
-  ).json();
+  const json = await s.fetchJsonWithToken(URLS.LEARN_HOMEWORK_SUBMIT(), {
+    method: 'POST',
+    body: URLS.LEARN_HOMEWORK_SUBMIT_FORM_DATA(id, content, attachment, removeAttachment),
+    // the response only starts after the whole upload, which can take longer than `requestTimeout`
+    timeout: attachment ? 0 : undefined,
+  });
   if (json.result !== 'success') {
     return Promise.reject({
       reason: FailReason.OPERATION_FAILED,

package/src/index.ts

@@ -34,6 +34,8 @@ import type {
   Notification,
   Question,
   Questionnaire,
+  QuestionnaireDetail,
+  QuestionnaireListOptions,
   SemesterInfo,
   UserInfo,
   ContentType,
@@ -89,7 +91,8 @@ export class Learn2018Helper {
 
   /**
    * Login is necessary if you do not provide a `CredentialProvider`.
-   * Without credentials it uses the provider, and concurrent calls share one SSO login.
+   * Without credentials it uses the provider, and concurrent calls share one SSO login. Logins never overlap: one with
+   * credentials waits for a login in progress, and requests that find the session expired meanwhile wait for it.
    */
   public async login(
     username?: string,
@@ -99,7 +102,9 @@ export class Learn2018Helper {
     fingerGenPrint3?: string,
   ): Promise<void> {
     if (!username || !password || !fingerPrint) return this.#session.relogin();
-    return auth.login(this.#session, username, password, fingerPrint, fingerGenPrint, fingerGenPrint3);
+    return this.#session.runLogin(() =>
+      auth.login(this.#session, username, password, fingerPrint, fingerGenPrint, fingerGenPrint3),
+    );
   }
 
   /**
@@ -124,7 +129,8 @@ export class Learn2018Helper {
   /**
    * 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`).
+   * `failedRanges`. Rejects only when every window fails (usually with `FailReason.INVALID_RESPONSE`), or with a
+   * `RangeError` for a date that is not a valid yyyymmdd.
    */
   public async getCalendar(startDate: string, endDate: string, options?: CalendarOptions): Promise<CalendarResult> {
     return calendar.getCalendar(this.#session, startDate, endDate, options);
@@ -220,10 +226,9 @@ export class Learn2018Helper {
    * 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,
+    courseType?: CourseType.STUDENT,
     options?: HomeworkListOptions,
   ): Promise<Homework[]>;
   public async getHomeworkList(courseID: string, courseType: CourseType.TEACHER): Promise<HomeworkTA[]>;
@@ -265,9 +270,16 @@ export class Learn2018Helper {
 
   /**
    * Get all questionnaires （课程问卷/QNR） of the specified course.
+   * Questions (`detail`, one request per questionnaire) for the questionnaires `options.details` selects, by default
+   * all; use `getQuestionnaireDetail` for the others.
    */
-  public async getQuestionnaireList(courseID: string): Promise<Questionnaire[]> {
-    return questionnaires.getQuestionnaireList(this.#session, courseID);
+  public async getQuestionnaireList(courseID: string, options?: QuestionnaireListOptions): Promise<Questionnaire[]> {
+    return questionnaires.getQuestionnaireList(this.#session, courseID, options);
+  }
+
+  /** Get the questions of one questionnaire (one request). */
+  public async getQuestionnaireDetail(courseID: string, questionnaireID: string): Promise<QuestionnaireDetail[]> {
+    return questionnaires.getQuestionnaireDetail(this.#session, courseID, questionnaireID);
   }
 
   /**