@robertying/thu-learn-lib 5.0.0 → 6.0.0

package/src/index.ts

@@ -11,38 +11,45 @@ import * as questionnaires from './questionnaires.ts';
 import { Session } from './request.ts';
 import type {
   AllContentsOptions,
+  Credential,
   AllContentsResult,
   CalendarOptions,
   CalendarResult,
-  CourseListOptions,
-  ExcellentHomework,
-  HomeworkListOptions,
-  IHomeworkDetail,
-  NotificationListOptions,
-  RemoteFile,
   CommentItem,
+  ContentType,
+  CourseFile,
   CourseInfo,
+  CourseListOptions,
+  CourseNotification,
   Discussion,
+  ExcellentHomework,
   FavoriteItem,
-  File,
   FileCategory,
   HelperConfig,
   Homework,
+  HomeworkDetail,
+  HomeworkListOptions,
+  HomeworkSubmitAttachment,
+  HomeworkSubmitRequest,
   HomeworkTA,
-  IHomeworkSubmitAttachment,
   Language,
-  Notification,
+  NotificationListOptions,
   Question,
   Questionnaire,
+  QuestionnaireDetail,
+  QuestionnaireListOptions,
+  RemoteFile,
   SemesterInfo,
   UserInfo,
-  ContentType,
 } from './types.ts';
-import { CourseType } from './types.ts';
+import { CourseType, FailReason } from './types.ts';
+import { apiError } from './utils.ts';
 import * as URLS from './urls.ts';
 import * as user from './user.ts';
 
-export { addCSRFTokenToUrl } from './request.ts';
+export { addCSRFTokenToUrl, isConnectionError } from './request.ts';
+export { checkHomeworkSubmitResponse, homeworkContentHtml } from './homework.ts';
+export { CLASS_PERIOD_TIMES, parseCourseMeeting, parseWeeks, semesterWeek } from './timetable.ts';
 export * from './types.ts';
 
 /** the main helper class */
@@ -51,7 +58,7 @@ export class Learn2018Helper {
 
   /** you can provide a CookieJar and / or CredentialProvider in the configuration */
   constructor(config?: HelperConfig) {
-    this.#session = new Session(config, () => auth.login(this.#session));
+    this.#session = new Session(config, () => auth.loginWithProvider(this.#session));
   }
 
   /** whether preview URLs open the first page only (`HelperConfig.generatePreviewUrlForFirstPage`) */
@@ -74,32 +81,25 @@ export class Learn2018Helper {
   }
 
   /**
-   * If using alternative cookie management systems,
-   * be sure to clear id.tsinghua.edu.cn cookies before calling this function
+   * Sign in to id.tsinghua.edu.cn and return the Web Learning roaming ticket, without logging in to Web Learning.
+   * Rejects with `NO_CREDENTIAL` unless `credential` has a username, a password and a fingerprint. If using
+   * alternative cookie management systems, be sure to clear id.tsinghua.edu.cn cookies before calling this function.
    */
-  public async getRoamingTicket(
-    username: string,
-    password: string,
-    fingerPrint: string,
-    fingerGenPrint: string = '',
-    fingerGenPrint3: string = '',
-  ): Promise<string> {
-    return auth.getRoamingTicket(this.#session, username, password, fingerPrint, fingerGenPrint, fingerGenPrint3);
+  public async getRoamingTicket(credential: Credential): Promise<string> {
+    if (!auth.isComplete(credential)) throw apiError(FailReason.NO_CREDENTIAL);
+    return auth.getRoamingTicket(this.#session, credential);
   }
 
   /**
    * Login is necessary if you do not provide a `CredentialProvider`.
-   * Without credentials it uses the provider, and concurrent calls share one SSO login.
+   * Without a credential it uses the provider, and concurrent calls share one SSO login; a credential without a
+   * username, a password and a fingerprint rejects with `NO_CREDENTIAL`. Logins never overlap: one with a credential
+   * waits for a login in progress, and requests that find the session expired meanwhile wait for it.
    */
-  public async login(
-    username?: string,
-    password?: string,
-    fingerPrint?: string,
-    fingerGenPrint?: string,
-    fingerGenPrint3?: string,
-  ): Promise<void> {
-    if (!username || !password || !fingerPrint) return this.#session.relogin();
-    return auth.login(this.#session, username, password, fingerPrint, fingerGenPrint, fingerGenPrint3);
+  public async login(credential?: Credential): Promise<void> {
+    if (credential === undefined) return this.#session.relogin();
+    if (!auth.isComplete(credential)) throw apiError(FailReason.NO_CREDENTIAL);
+    return this.#session.runLogin(() => auth.login(this.#session, credential));
   }
 
   /**
@@ -108,7 +108,7 @@ export class Learn2018Helper {
    * Use it when resuming an app instead of `login()`.
    */
   public async ensureSession(): Promise<void> {
-    return this.#session.ensureSession(URLS.LEARN_CURRENT_SEMESTER());
+    return this.#session.ensureSession(URLS.LEARN_CURRENT_SEMESTER);
   }
 
   /**  logout (to make everyone happy) */
@@ -123,8 +123,11 @@ 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`).
+   * Ranges longer than 28 days are fetched in windows and merged; windows that still fail are listed in `failedRanges`
+   * (a timed-out window is not retried). Rejects when every window fails (usually with `FailReason.INVALID_RESPONSE`),
+   * with `FailReason.ERROR_REGISTRAR_AUTH` when signing in to the registrar fails, or with a `RangeError` for a date
+   * that is not a valid yyyymmdd. With a `CredentialProvider`, a sign-in that id.tsinghua.edu.cn turns down (its session
+   * from the last login expired) logs in again and is tried once more.
    */
   public async getCalendar(startDate: string, endDate: string, options?: CalendarOptions): Promise<CalendarResult> {
     return calendar.getCalendar(this.#session, startDate, endDate, options);
@@ -140,7 +143,8 @@ export class Learn2018Helper {
 
   /**
    * Get all courses in the specified semester.
-   * `timeAndLocation` is only fetched (one request per course) with `options.timeAndLocation`.
+   * `timeAndLocation` is only fetched (one request per course) with `options.timeAndLocation`, and left out for a
+   * course whose request failed.
    */
   public async getCourseList(
     semesterID: string,
@@ -178,20 +182,20 @@ export class Learn2018Helper {
     courseID: string,
     courseType: CourseType = CourseType.STUDENT,
     options?: NotificationListOptions,
-  ): Promise<Notification[]> {
+  ): Promise<CourseNotification[]> {
     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'>,
+    notification: Pick<CourseNotification, 'url' | 'attachmentName'>,
     courseType: CourseType = CourseType.STUDENT,
   ): Promise<RemoteFile | undefined> {
     return notices.getNotificationAttachment(this.#session, notification, courseType);
   }
 
   /** Get all files （课程文件） of the specified course. */
-  public async getFileList(courseID: string, courseType: CourseType = CourseType.STUDENT): Promise<File[]> {
+  public async getFileList(courseID: string, courseType: CourseType = CourseType.STUDENT): Promise<CourseFile[]> {
     return files.getFileList(this.#session, courseID, courseType);
   }
 
@@ -211,7 +215,7 @@ export class Learn2018Helper {
     courseID: string,
     categoryId: string,
     courseType: CourseType = CourseType.STUDENT,
-  ): Promise<File[]> {
+  ): Promise<CourseFile[]> {
     return files.getFileListByCategory(this.#session, courseID, categoryId, courseType);
   }
 
@@ -220,10 +224,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[]>;
@@ -238,12 +241,12 @@ export class Learn2018Helper {
   }
 
   /** Get the detail (page content, attachments and description) of one homework. */
-  public async getHomeworkDetail(item: Pick<Homework, 'url' | 'baseId'>): Promise<IHomeworkDetail> {
+  public async getHomeworkDetail(item: Pick<Homework, 'url' | 'baseId'>): Promise<HomeworkDetail> {
     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> {
+  public async getExcellentHomeworkDetail(item: Pick<ExcellentHomework, 'url' | 'baseId'>): Promise<HomeworkDetail> {
     return homework.getHomeworkDetail(this.#session, item);
   }
 
@@ -265,9 +268,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);
   }
 
   /**
@@ -326,15 +336,36 @@ export class Learn2018Helper {
     return courses.sortCourses(this.#session, courseIDs);
   }
 
+  /**
+   * Submit homework `id` (the `studentHomeworkId`), the way the website's submit page does. `content` is the whole
+   * answer as HTML (the website sends its editor's HTML) and replaces the submitted one, so pass the current answer
+   * when only changing the attachment (`homeworkContentHtml` turns plain text into the editor's HTML). With no
+   * `attachment` the existing one is kept, unless `removeAttachment`: that only deletes the attachment, and `content` is
+   * ignored. In React Native, pass the attachment's `content` as `{ uri, type }`.
+   */
   public async submitHomework(
     id: string,
     content = '',
-    attachment?: IHomeworkSubmitAttachment,
+    attachment?: HomeworkSubmitAttachment,
     removeAttachment = false,
   ): Promise<void> {
     return homework.submitHomework(this.#session, id, content, attachment, removeAttachment);
   }
 
+  /**
+   * The request `submitHomework` would send, for sending with another HTTP client (e.g. to show upload progress, which
+   * `fetch` can't): POST `body` to `url`, then pass the answer (parsed JSON or text) to `checkHomeworkSubmitResponse`.
+   * It checks the session first (`ensureSession`), since that request doesn't log in again and retry.
+   */
+  public async getHomeworkSubmitRequest(
+    id: string,
+    content = '',
+    attachment?: HomeworkSubmitAttachment,
+    removeAttachment = false,
+  ): Promise<HomeworkSubmitRequest> {
+    return homework.getHomeworkSubmitRequest(this.#session, id, content, attachment, removeAttachment);
+  }
+
   public async setLanguage(lang: Language): Promise<void> {
     return user.setLanguage(this.#session, lang);
   }

package/src/notices.ts

@@ -3,11 +3,19 @@
 import { Base64 } from 'js-base64';
 
 import type { Session } from './request.ts';
-import { $, YES } from './request.ts';
-import type { INotification, Notification, NotificationListOptions, RemoteFile } from './types.ts';
+import type { CourseNotification, CourseNotificationBase, NotificationListOptions, RemoteFile } from './types.ts';
 import { ContentType, CourseType, FailReason } from './types.ts';
 import * as URLS from './urls.ts';
-import { decodeHTML, isSelected, trimAndDefine } from './utils.ts';
+import {
+  $,
+  YES,
+  decodeHTML,
+  expectSuccess,
+  isSelected,
+  toRequiredServerTime,
+  toServerTime,
+  trimAndDefine,
+} from './utils.ts';
 
 /**
  * Get all notifications （课程公告） of the specified course: current and expired lists.
@@ -18,13 +26,13 @@ export async function getNotificationList(
   courseID: string,
   courseType: CourseType = CourseType.STUDENT,
   options: NotificationListOptions = {},
-): Promise<Notification[]> {
+): Promise<CourseNotification[]> {
   const lists = await Promise.all([
     getNotificationListKind(s, courseID, courseType, false),
     getNotificationListKind(s, courseID, courseType, true),
   ]);
   return Promise.all(
-    lists.flat().map(async (n): Promise<Notification> => {
+    lists.flat().map(async (n): Promise<CourseNotification> => {
       if (!n.attachmentName || !isSelected(options.attachments, n)) return n;
       return { ...n, attachment: await getNotificationAttachment(s, n, courseType) };
     }),
@@ -36,19 +44,12 @@ async function getNotificationListKind(
   courseID: string,
   courseType: CourseType,
   expired: boolean,
-): Promise<INotification[]> {
-  const json = await (
-    await s.fetchWithToken(URLS.LEARN_NOTIFICATION_LIST(courseType, expired), {
-      method: 'POST',
-      body: URLS.LEARN_PAGE_LIST_FORM_DATA(courseID),
-    })
-  ).json();
-  if (json.result !== 'success') {
-    return Promise.reject({
-      reason: FailReason.INVALID_RESPONSE,
-      extra: json,
-    });
-  }
+): Promise<CourseNotificationBase[]> {
+  const json = await s.fetchJsonWithToken(URLS.LEARN_NOTIFICATION_LIST(courseType, expired), {
+    method: 'POST',
+    body: URLS.LEARN_PAGE_LIST_FORM_DATA(courseID),
+  });
+  expectSuccess(json, FailReason.INVALID_RESPONSE);
 
   const result = (json.object?.aaData ?? json.object?.resultsList ?? []) as any[];
 
@@ -62,44 +63,30 @@ async function getNotificationListKind(
       publisher: n.fbrxm,
       hasRead: n.sfyd === YES,
       markedImportant: Number(n.sfqd) === 1, // n.sfqd could be string '1' (teacher mode) or number 1 (student mode)
-      publishTime: n.fbsj && typeof n.fbsj === 'string' ? n.fbsj : n.fbsjStr,
-      expireTime: n.jzsj ?? undefined,
+      publishTime: toRequiredServerTime(n.fbsj && typeof n.fbsj === 'string' ? n.fbsj : n.fbsjStr),
+      expireTime: toServerTime(n.jzsj),
       isFavorite: n.sfsc === YES,
       comment: n.bznr ?? undefined,
       attachmentName: typeof attachmentName === 'string' && attachmentName ? attachmentName : undefined,
-    } satisfies INotification;
+    } satisfies CourseNotificationBase;
   });
 }
 
 /**
  * Get the attachment of a notice from its detail page (1 request), or `undefined` without a request if
- * `attachmentName` says it has none.
+ * `attachmentName` says it has none, or if the page has no attachment link.
  */
 export async function getNotificationAttachment(
   s: Session,
-  notification: Pick<INotification, 'url' | 'attachmentName'>,
+  notification: Pick<CourseNotificationBase, 'url' | 'attachmentName'>,
   courseType: CourseType = CourseType.STUDENT,
 ): Promise<RemoteFile | undefined> {
   if (!notification.attachmentName) return undefined;
-  /// from JSON (backup, currently not used)
-  // const postParams = new FormData();
-  // postParams.append('id', id);
-  // postParams.append('wlkcid', courseID);
-  // const metadata = await (await s.fetchWithToken(URL.LEARN_NOTIFICATION_EDIT(courseType), {
-  //   'method': 'POST',
-  //   'body': postParams,
-  // })).json();
-  // const attachmentId = metadata.ggfjid as string;
-  /// parsed from HTML
-  const response = await s.fetchWithToken(notification.url);
-  const result = $(await response.text());
-  let path = '';
-  if (courseType === CourseType.STUDENT) {
-    path = result('.ml-10').attr('href')!;
-  } else {
-    path = result('#wjid').attr('href')!;
-  }
-  const size = trimAndDefine(result('div#attachment > div.fl > span[class^="color"]').first().text())!;
+  const result = $(await s.fetchTextWithToken(notification.url));
+  let path = (courseType === CourseType.STUDENT ? result('.ml-10') : result('#wjid')).attr('href');
+  // the page has no attachment link (removed since the list was fetched, or the page changed)
+  if (!path) return undefined;
+  const size = trimAndDefine(result('div#attachment > div.fl > span[class^="color"]').first().text()) ?? '';
   const params = new URLSearchParams(path.split('?').slice(-1)[0]);
   const attachmentId = params.get('wjid')!;
   if (!path.startsWith(URLS.LEARN_PREFIX)) {

package/src/questionnaires.ts

@@ -1,63 +1,80 @@
 // Questionnaires (课程问卷).
 
 import type { Session } from './request.ts';
-import { YES } from './request.ts';
-import type { Questionnaire, QuestionnaireDetail } from './types.ts';
+import type { Questionnaire, QuestionnaireDetail, QuestionnaireListOptions } from './types.ts';
 import { FailReason, QuestionnaireType } from './types.ts';
 import * as URLS from './urls.ts';
-import { QNR_TYPE_MAP, decodeHTML } from './utils.ts';
+import {
+  QNR_TYPE_MAP,
+  YES,
+  apiError,
+  decodeHTML,
+  expectSuccess,
+  isSelected,
+  toRequiredServerTime,
+  toServerTime,
+} from './utils.ts';
 
 /**
- * Get all questionnaires （课程问卷/QNR） of the specified course.
+ * Get all questionnaires （课程问卷/QNR） of the specified course: ongoing and ended lists.
+ * Questions (`detail`, 1 request each) only for the questionnaires `options.details` selects (default `'all'`).
  */
-export async function getQuestionnaireList(s: Session, courseID: string): Promise<Questionnaire[]> {
-  return Promise.all([
+export async function getQuestionnaireList(
+  s: Session,
+  courseID: string,
+  options: QuestionnaireListOptions = {},
+): Promise<Questionnaire[]> {
+  const details = options.details ?? 'all';
+  const lists = await Promise.all([
     getQuestionnaireListAtUrl(s, courseID, URLS.LEARN_QNR_LIST_ONGOING),
     getQuestionnaireListAtUrl(s, courseID, URLS.LEARN_QNR_LIST_ENDED),
-  ]).then((r) => r.flat());
+  ]);
+  return Promise.all(
+    lists
+      .flat()
+      .map(async (q) =>
+        isSelected(details, q) ? { ...q, detail: await getQuestionnaireDetail(s, courseID, q.id) } : q,
+      ),
+  );
 }
 
 async function getQuestionnaireListAtUrl(s: Session, courseID: string, url: string): Promise<Questionnaire[]> {
-  const json = await (
-    await s.fetchWithToken(url, { 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 json = await s.fetchJsonWithToken(url, { method: 'POST', body: URLS.LEARN_PAGE_LIST_FORM_DATA(courseID) });
+  expectSuccess(json, FailReason.INVALID_RESPONSE);
   const result = (json.object?.aaData ?? []) as any[];
-  return Promise.all(
-    result.map(async (e) => {
-      const type = QNR_TYPE_MAP.get(e.wjlx) ?? QuestionnaireType.SURVEY;
-      return {
-        id: e.wjid,
-        type,
-        title: decodeHTML(e.wjbt),
-        startTime: e.kssj,
-        endTime: e.jssj,
-        uploadTime: e.scsj,
-        uploaderId: e.scr,
-        uploaderName: e.scrxm,
-        submitTime: e.tjsj ? e.tjsj : undefined,
-        isFavorite: e.sfsc === YES,
-        comment: e.bznr ?? undefined,
-        url: URLS.LEARN_QNR_SUBMIT_PAGE(e.wlkcid, e.wjid, type),
-        detail: await getQuestionnaireDetail(s, courseID, e.wjid),
-      } satisfies Questionnaire;
-    }),
-  );
+  return result.map((e) => {
+    const type = QNR_TYPE_MAP.get(e.wjlx) ?? QuestionnaireType.SURVEY;
+    return {
+      id: e.wjid,
+      type,
+      title: decodeHTML(e.wjbt),
+      startTime: toRequiredServerTime(e.kssj),
+      endTime: toRequiredServerTime(e.jssj),
+      uploadTime: toRequiredServerTime(e.scsj),
+      uploaderId: e.scr,
+      uploaderName: e.scrxm,
+      submitTime: toServerTime(e.tjsj),
+      isFavorite: e.sfsc === YES,
+      comment: e.bznr ?? undefined,
+      url: URLS.LEARN_QNR_SUBMIT_PAGE(e.wlkcid, e.wjid, type),
+    } satisfies Questionnaire;
+  });
 }
 
-async function getQuestionnaireDetail(s: Session, courseID: string, qnrID: string): Promise<QuestionnaireDetail[]> {
-  const json = await (
-    await s.fetchWithToken(URLS.LEARN_QNR_DETAIL, {
-      method: 'POST',
-      body: URLS.LEARN_QNR_DETAIL_FORM(courseID, qnrID),
-    })
-  ).json();
-  return (json as any[]).map(
+/** Get the questions of one questionnaire (1 request). */
+export async function getQuestionnaireDetail(
+  s: Session,
+  courseID: string,
+  qnrID: string,
+): Promise<QuestionnaireDetail[]> {
+  const json = await s.fetchJsonWithToken(URLS.LEARN_QNR_DETAIL, {
+    method: 'POST',
+    body: URLS.LEARN_QNR_DETAIL_FORM(courseID, qnrID),
+  });
+  if (!Array.isArray(json)) {
+    throw apiError(FailReason.INVALID_RESPONSE, json);
+  }
+  return json.map(
     (e) =>
       ({
         id: e.wtid,
@@ -65,7 +82,7 @@ async function getQuestionnaireDetail(s: Session, courseID: string, qnrID: strin
         type: e.type,
         required: e.require === YES,
         title: decodeHTML(e.wtbt),
-        score: e.wtfz ? Number(e.wtfz) : undefined, // unsure about original type
+        score: e.wtfz ? Number(e.wtfz) : undefined, // a number or a string of digits; none when missing or 0
         options: (e.list as any[])?.map((o) => ({
           id: o.xxid,
           index: Number(o.xxbh),