@robertying/thu-learn-lib 4.1.0 → 5.1.0

package/src/homework.ts

@@ -9,6 +9,7 @@ import type {
   ApiError,
   ExcellentHomework,
   Homework,
+  HomeworkListOptions,
   HomeworkTA,
   IExcellentHomework,
   IHomework,
@@ -19,12 +20,18 @@ import type {
 } from './types.ts';
 import { ContentType, CourseType, FailReason } from './types.ts';
 import * as URLS from './urls.ts';
-import { GRADE_LEVEL_MAP, decodeHTML, trimAndDefine } from './utils.ts';
+import { GRADE_LEVEL_MAP, decodeHTML, isSelected, trimAndDefine } from './utils.ts';
 
-/** Get all homeworks （课程作业） of the specified course. */
-export function getHomeworkList(s: Session, courseID: string): Promise<Homework[]>;
-
-export function getHomeworkList(s: Session, courseID: string, courseType: CourseType.STUDENT): Promise<Homework[]>;
+/**
+ * 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,
+  courseType?: CourseType.STUDENT,
+  options?: HomeworkListOptions,
+): Promise<Homework[]>;
 
 export function getHomeworkList(s: Session, courseID: string, courseType: CourseType.TEACHER): Promise<HomeworkTA[]>;
 
@@ -32,14 +39,13 @@ export async function getHomeworkList(
   s: Session,
   courseID: string,
   courseType: CourseType = CourseType.STUDENT,
+  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,
@@ -70,9 +76,19 @@ export async function getHomeworkList(
         }) satisfies HomeworkTA,
     );
   } else {
+    const [lists, excellentHomeworkListByHomework] = await Promise.all([
+      Promise.all(
+        URLS.LEARN_HOMEWORK_LIST_SOURCE.map((source) => getHomeworkListAtUrl(s, courseID, source.url, source.status)),
+      ),
+      // Don't block the whole process if excellent homework list cannot be fetched
+      getExcellentHomeworkListByHomework(s, courseID).catch((): { [id: string]: ExcellentHomework[] } => ({})),
+    ]);
     return Promise.all(
-      URLS.LEARN_HOMEWORK_LIST_SOURCE.map((source) => getHomeworkListAtUrl(s, courseID, source.url, source.status)),
-    ).then((r) => r.flat());
+      lists.flat().map(async (h) => {
+        const homework: Homework = { ...h, excellentHomeworkList: excellentHomeworkListByHomework[h.baseId] };
+        return isSelected(options.details, homework) ? { ...homework, ...(await getHomeworkDetail(s, h)) } : homework;
+      }),
+    );
   }
 }
 
@@ -81,13 +97,11 @@ async function getHomeworkListAtUrl(
   courseID: string,
   url: string,
   status: IHomeworkStatus,
-): Promise<Homework[]> {
-  const json = await (
-    await s.fetchWithToken(url, {
-      method: 'POST',
-      body: URLS.LEARN_PAGE_LIST_FORM_DATA(courseID),
-    })
-  ).json();
+): Promise<IHomework[]> {
+  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,
@@ -97,50 +111,31 @@ async function getHomeworkListAtUrl(
 
   const result = (json.object?.aaData ?? []) as any[];
 
-  let excellentHomeworkListByHomework: { [id: string]: ExcellentHomework[] } = {};
-  try {
-    excellentHomeworkListByHomework = await getExcellentHomeworkListByHomework(s, courseID);
-  } catch (e) {
-    // Don't block the whole process if excellent homework list cannot be fetched
-  }
-
-  return Promise.all(
-    result
-      .map(
-        (h) =>
-          ({
-            id: h.xszyid,
-            studentHomeworkId: h.xszyid,
-            baseId: h.zyid,
-            title: decodeHTML(h.bt),
-            url: URLS.LEARN_HOMEWORK_PAGE(h.wlkcid, h.xszyid),
-            deadline: h.jzsj,
-            lateSubmissionDeadline: h.bjjzsj ? h.bjjzsj : undefined,
-            isLateSubmission: h.sfbj === YES,
-            completionType: h.zywcfs,
-            submissionType: h.zytjfs,
-            submitUrl: URLS.LEARN_HOMEWORK_SUBMIT_PAGE(h.wlkcid, h.xszyid),
-            submitTime: h.scsj === null ? undefined : h.scsj,
-            grade: h.cj === null ? undefined : h.cj,
-            gradeLevel: GRADE_LEVEL_MAP.get(h.cj),
-            graderName: trimAndDefine(h.jsm),
-            gradeContent: trimAndDefine(h.pynr),
-            gradeTime: h.pysj === null ? undefined : h.pysj,
-            isFavorite: h.sfsc === YES,
-            favoriteTime: h.scsj === null || h.sfsc !== YES ? undefined : h.scsj,
-            comment: h.bznr ?? undefined,
-            excellentHomeworkList: excellentHomeworkListByHomework[h.zyid],
-            ...status,
-          }) satisfies IHomework,
-      )
-      .map(
-        async (h) =>
-          ({
-            ...h,
-            ...(await parseHomeworkAtUrl(s, h.url)),
-            ...(await getHomeworkDetail(s, h.baseId)),
-          }) satisfies Homework,
-      ),
+  return result.map(
+    (h) =>
+      ({
+        id: h.xszyid,
+        studentHomeworkId: h.xszyid,
+        baseId: h.zyid,
+        title: decodeHTML(h.bt),
+        url: URLS.LEARN_HOMEWORK_PAGE(h.wlkcid, h.xszyid),
+        deadline: h.jzsj,
+        lateSubmissionDeadline: h.bjjzsj ? h.bjjzsj : undefined,
+        isLateSubmission: h.sfbj === YES,
+        completionType: h.zywcfs,
+        submissionType: h.zytjfs,
+        submitUrl: URLS.LEARN_HOMEWORK_SUBMIT_PAGE(h.wlkcid, h.xszyid),
+        submitTime: h.scsj === null ? undefined : h.scsj,
+        grade: h.cj === null ? undefined : h.cj,
+        gradeLevel: GRADE_LEVEL_MAP.get(h.cj),
+        graderName: trimAndDefine(h.jsm),
+        gradeContent: trimAndDefine(h.pynr),
+        gradeTime: h.pysj === null ? undefined : h.pysj,
+        isFavorite: h.sfsc === YES,
+        favoriteTime: h.scsj === null || h.sfsc !== YES ? undefined : h.scsj,
+        comment: h.bznr ?? undefined,
+        ...status,
+      }) satisfies IHomework,
   );
 }
 
@@ -148,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,
@@ -163,45 +156,33 @@ async function getExcellentHomeworkListByHomework(
 
   const result = (json.object?.aaData ?? []) as any[];
 
-  return (
-    await Promise.all(
-      result
-        .map(
-          (h) =>
-            ({
-              id: h.xszyid,
-              baseId: h.zyid,
-              title: decodeHTML(h.bt),
-              url: URLS.LEARN_HOMEWORK_EXCELLENT_PAGE(h.wlkcid, h.xszyid),
-              completionType: h.zywcfs,
-              author: {
-                id: h.cy?.split(' ')?.[0],
-                name: h.cy?.split(' ')?.[1],
-                anonymous: h.sfzm === YES,
-              },
-            }) satisfies IExcellentHomework,
-        )
-        .map(
-          async (h) =>
-            ({
-              ...h,
-              ...(await parseHomeworkAtUrl(s, h.url)),
-              ...(await getHomeworkDetail(s, h.baseId)),
-            }) satisfies ExcellentHomework,
-        ),
+  return result
+    .map(
+      (h) =>
+        ({
+          id: h.xszyid,
+          baseId: h.zyid,
+          title: decodeHTML(h.bt),
+          url: URLS.LEARN_HOMEWORK_EXCELLENT_PAGE(h.wlkcid, h.xszyid),
+          completionType: h.zywcfs,
+          author: {
+            id: h.cy?.split(' ')?.[0],
+            name: h.cy?.split(' ')?.[1],
+            anonymous: h.sfzm === YES,
+          },
+        }) satisfies IExcellentHomework,
     )
-  ).reduce<{ [id: string]: ExcellentHomework[] }>((acc, cur) => {
-    if (!acc[cur.baseId]) {
-      acc[cur.baseId] = [];
-    }
-    acc[cur.baseId].push(cur);
-    return acc;
-  }, {});
+    .reduce<{ [id: string]: ExcellentHomework[] }>((acc, cur) => {
+      if (!acc[cur.baseId]) {
+        acc[cur.baseId] = [];
+      }
+      acc[cur.baseId].push(cur);
+      return acc;
+    }, {});
 }
 
 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');
 
@@ -216,13 +197,26 @@ async function parseHomeworkAtUrl(s: Session, url: string): Promise<IHomeworkDet
   };
 }
 
-async function getHomeworkDetail(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();
+/**
+ * Get the detail of one homework or excellent homework: its page (answer, submitted content, attachments) and the
+ * description JSON (which wins for `description`). 2 requests.
+ */
+export async function getHomeworkDetail(
+  s: Session,
+  homework: Pick<IHomework | IExcellentHomework, 'url' | 'baseId'>,
+): Promise<IHomeworkDetail> {
+  const [page, description] = await Promise.all([
+    parseHomeworkAtUrl(s, homework.url),
+    getHomeworkDescription(s, homework.baseId),
+  ]);
+  return { ...page, ...description };
+}
+
+async function getHomeworkDescription(s: Session, baseId: string): Promise<IHomeworkDetail> {
+  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,
@@ -236,18 +230,19 @@ async function getHomeworkDetail(s: Session, baseId: string): Promise<IHomeworkD
 
 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,
@@ -264,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

@@ -10,8 +10,16 @@ import * as notices from './notices.ts';
 import * as questionnaires from './questionnaires.ts';
 import { Session } from './request.ts';
 import type {
+  AllContentsOptions,
+  AllContentsResult,
   CalendarOptions,
   CalendarResult,
+  CourseListOptions,
+  ExcellentHomework,
+  HomeworkListOptions,
+  IHomeworkDetail,
+  NotificationListOptions,
+  RemoteFile,
   CommentItem,
   CourseInfo,
   Discussion,
@@ -26,11 +34,14 @@ import type {
   Notification,
   Question,
   Questionnaire,
+  QuestionnaireDetail,
+  QuestionnaireListOptions,
   SemesterInfo,
   UserInfo,
   ContentType,
 } from './types.ts';
 import { CourseType } from './types.ts';
+import * as URLS from './urls.ts';
 import * as user from './user.ts';
 
 export { addCSRFTokenToUrl } from './request.ts';
@@ -42,7 +53,7 @@ export class Learn2018Helper {
 
   /** you can provide a CookieJar and / or CredentialProvider in the configuration */
   constructor(config?: HelperConfig) {
-    this.#session = new Session(config, () => this.login());
+    this.#session = new Session(config, () => auth.login(this.#session));
   }
 
   /** whether preview URLs open the first page only (`HelperConfig.generatePreviewUrlForFirstPage`) */
@@ -78,7 +89,11 @@ export class Learn2018Helper {
     return auth.getRoamingTicket(this.#session, username, password, fingerPrint, fingerGenPrint, fingerGenPrint3);
   }
 
-  /** login is necessary if you do not provide a `CredentialProvider` */
+  /**
+   * Login is necessary if you do not provide a `CredentialProvider`.
+   * 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,
     password?: string,
@@ -86,7 +101,19 @@ export class Learn2018Helper {
     fingerGenPrint?: string,
     fingerGenPrint3?: string,
   ): Promise<void> {
-    return auth.login(this.#session, username, password, fingerPrint, fingerGenPrint, fingerGenPrint3);
+    if (!username || !password || !fingerPrint) return this.#session.relogin();
+    return this.#session.runLogin(() =>
+      auth.login(this.#session, username, password, fingerPrint, fingerGenPrint, fingerGenPrint3),
+    );
+  }
+
+  /**
+   * Make sure the session is usable without a full SSO login when possible: with a CSRF token (from an earlier login
+   * or `setCSRFToken`), make one cheap request and log in again only if the session has expired; without one, log in.
+   * Use it when resuming an app instead of `login()`.
+   */
+  public async ensureSession(): Promise<void> {
+    return this.#session.ensureSession(URLS.LEARN_CURRENT_SEMESTER());
   }
 
   /**  logout (to make everyone happy) */
@@ -102,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);
@@ -116,34 +144,56 @@ export class Learn2018Helper {
     return courses.getCurrentSemester(this.#session);
   }
 
-  /** get all courses in the specified semester */
+  /**
+   * Get all courses in the specified semester.
+   * `timeAndLocation` is only fetched (one request per course) with `options.timeAndLocation`.
+   */
   public async getCourseList(
     semesterID: string,
     courseType: CourseType = CourseType.STUDENT,
     lang: Language = this.#session.lang,
+    options?: CourseListOptions,
   ): Promise<CourseInfo[]> {
-    return courses.getCourseList(this.#session, semesterID, courseType, lang);
+    return courses.getCourseList(this.#session, semesterID, courseType, lang, options);
+  }
+
+  /** Get the time and location of one course. */
+  public async getCourseTimeAndLocation(courseID: string): Promise<string[]> {
+    return courses.getCourseTimeAndLocation(this.#session, courseID);
   }
 
   /**
    * Get certain type of content of all specified courses.
-   * It actually wraps around other `getXXX` functions. You can ignore the failure caused by certain courses.
+   * It wraps around the `getXXX` list functions; a course that fails is reported in `errors` instead of failing
+   * the rest. `options.details` is passed on as homework `details` or notification `attachments`.
    */
   public async getAllContents<T extends ContentType>(
     courseIDs: string[],
     type: T,
-    courseType: CourseType = CourseType.STUDENT,
-    allowFailure = false,
-  ) {
-    return contents.getAllContents(this.#session, courseIDs, type, courseType, allowFailure);
+    options?: AllContentsOptions<T>,
+  ): Promise<AllContentsResult<T>> {
+    return contents.getAllContents(this.#session, courseIDs, type, options);
   }
 
-  /** Get all notifications （课程公告） of the specified course. */
+  /**
+   * Get all notifications （课程公告） of the specified course.
+   * Attachments are only fetched (one request per notice) for the notices `options.attachments` selects;
+   * use `getNotificationAttachment` for the others.
+   */
   public async getNotificationList(
     courseID: string,
     courseType: CourseType = CourseType.STUDENT,
+    options?: NotificationListOptions,
   ): Promise<Notification[]> {
-    return notices.getNotificationList(this.#session, courseID, courseType);
+    return notices.getNotificationList(this.#session, courseID, courseType, options);
+  }
+
+  /** Get the attachment of a notice (one request), `undefined` if it has none. */
+  public async getNotificationAttachment(
+    notification: Pick<Notification, 'url' | 'attachmentName'>,
+    courseType: CourseType = CourseType.STUDENT,
+  ): Promise<RemoteFile | undefined> {
+    return notices.getNotificationAttachment(this.#session, notification, courseType);
   }
 
   /** Get all files （课程文件） of the specified course. */
@@ -171,17 +221,35 @@ export class Learn2018Helper {
     return files.getFileListByCategory(this.#session, courseID, categoryId, courseType);
   }
 
-  /** Get all homeworks （课程作业） of the specified course. */
-  public async getHomeworkList(courseID: string): Promise<Homework[]>;
-  public async getHomeworkList(courseID: string, courseType: CourseType.STUDENT): Promise<Homework[]>;
+  /**
+   * Get all homeworks （课程作业） of the specified course, with the excellent homework list (without details).
+   * Details (page + description, two requests per homework) are only fetched for the homework `options.details`
+   * selects; use `getHomeworkDetail` for the others.
+   */
+  public async getHomeworkList(
+    courseID: string,
+    courseType?: CourseType.STUDENT,
+    options?: HomeworkListOptions,
+  ): Promise<Homework[]>;
   public async getHomeworkList(courseID: string, courseType: CourseType.TEACHER): Promise<HomeworkTA[]>;
   public async getHomeworkList(
     courseID: string,
     courseType: CourseType = CourseType.STUDENT,
+    options?: HomeworkListOptions,
   ): Promise<Homework[] | HomeworkTA[]> {
     return courseType === CourseType.TEACHER
       ? homework.getHomeworkList(this.#session, courseID, CourseType.TEACHER)
-      : homework.getHomeworkList(this.#session, courseID, CourseType.STUDENT);
+      : homework.getHomeworkList(this.#session, courseID, CourseType.STUDENT, options);
+  }
+
+  /** Get the detail (page content, attachments and description) of one homework. */
+  public async getHomeworkDetail(item: Pick<Homework, 'url' | 'baseId'>): Promise<IHomeworkDetail> {
+    return homework.getHomeworkDetail(this.#session, item);
+  }
+
+  /** Get the detail (page content, attachments and description) of one excellent homework. */
+  public async getExcellentHomeworkDetail(item: Pick<ExcellentHomework, 'url' | 'baseId'>): Promise<IHomeworkDetail> {
+    return homework.getHomeworkDetail(this.#session, item);
   }
 
   /** Get all discussions （课程讨论） of the specified course. */
@@ -202,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);
   }
 
   /**