@robertying/thu-learn-lib 5.1.0 → 6.0.1

package/src/homework.ts

@@ -1,26 +1,45 @@
 // Homework (课程作业), excellent homework and homework submission.
 
-import type { Element } from 'cheerio';
 import { Base64 } from 'js-base64';
 
 import type { Session } from './request.ts';
-import { $, YES } from './request.ts';
+import { addCSRFTokenToUrl } from './request.ts';
 import type {
-  ApiError,
   ExcellentHomework,
+  ExcellentHomeworkBase,
   Homework,
+  HomeworkBase,
+  HomeworkDetail,
   HomeworkListOptions,
+  HomeworkStatus,
+  HomeworkSubmitAttachment,
+  HomeworkSubmitRequest,
   HomeworkTA,
-  IExcellentHomework,
-  IHomework,
-  IHomeworkDetail,
-  IHomeworkStatus,
-  IHomeworkSubmitAttachment,
   RemoteFile,
 } from './types.ts';
 import { ContentType, CourseType, FailReason } from './types.ts';
 import * as URLS from './urls.ts';
-import { GRADE_LEVEL_MAP, decodeHTML, isSelected, trimAndDefine } from './utils.ts';
+import {
+  $,
+  GRADE_LEVEL_MAP,
+  YES,
+  apiError,
+  decodeHTML,
+  expectSuccess,
+  isSelected,
+  looksLikeLoginPage,
+  toRequiredServerTime,
+  toServerTime,
+  trimAndDefine,
+} from './utils.ts';
+import type { Element } from './utils.ts';
+
+/** the student homework lists, by submission status */
+export const HOMEWORK_LIST_SOURCES: readonly { url: string; status: HomeworkStatus }[] = [
+  { url: URLS.LEARN_HOMEWORK_LIST_NEW, status: { submitted: false, graded: false } },
+  { url: URLS.LEARN_HOMEWORK_LIST_SUBMITTED, status: { submitted: true, graded: false } },
+  { url: URLS.LEARN_HOMEWORK_LIST_GRADED, status: { submitted: true, graded: true } },
+];
 
 /**
  * Get all homeworks （课程作业） of the specified course: 3 status lists and the excellent homework list.
@@ -41,73 +60,70 @@ export async function getHomeworkList(
   courseType: CourseType = CourseType.STUDENT,
   options: HomeworkListOptions = {},
 ): Promise<Homework[] | HomeworkTA[]> {
-  if (courseType === CourseType.TEACHER) {
-    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,
-        extra: json,
-      });
-    }
+  return courseType === CourseType.TEACHER
+    ? getTeacherHomeworkList(s, courseID)
+    : getStudentHomeworkList(s, courseID, options);
+}
 
-    const result = (json.object?.aaData ?? []) as any[];
+async function getTeacherHomeworkList(s: Session, courseID: string): Promise<HomeworkTA[]> {
+  const json = await s.fetchJsonWithToken(URLS.LEARN_HOMEWORK_LIST_TEACHER, {
+    method: 'POST',
+    body: URLS.LEARN_PAGE_LIST_FORM_DATA(courseID),
+  });
+  expectSuccess(json, FailReason.INVALID_RESPONSE);
 
-    return result.map(
-      (d) =>
-        ({
-          id: d.zyid,
-          index: d.wz,
-          title: decodeHTML(d.bt),
-          description: decodeHTML(Base64.decode(d.nr)),
-          publisherId: d.fbr,
-          publishTime: d.fbsj,
-          startTime: d.kssj,
-          deadline: d.jzsj,
-          lateSubmissionDeadline: d.bjjzsj ?? undefined,
-          url: URLS.LEARN_HOMEWORK_DETAIL_TEACHER(courseID, d.zyid),
-          completionType: d.zywcfs,
-          submissionType: d.zytjfs,
-          gradedCount: d.ypys,
-          submittedCount: d.yjs,
-          unsubmittedCount: d.wjs,
-        }) 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(
-      lists.flat().map(async (h) => {
-        const homework: Homework = { ...h, excellentHomeworkList: excellentHomeworkListByHomework[h.baseId] };
-        return isSelected(options.details, homework) ? { ...homework, ...(await getHomeworkDetail(s, h)) } : homework;
-      }),
-    );
-  }
+  const result = (json.object?.aaData ?? []) as any[];
+
+  return result.map(
+    (d) =>
+      ({
+        id: d.zyid,
+        index: d.wz,
+        title: decodeHTML(d.bt),
+        description: decodeHTML(Base64.decode(d.nr ?? '')),
+        publisherId: d.fbr,
+        publishTime: toRequiredServerTime(d.fbsj),
+        startTime: toRequiredServerTime(d.kssj),
+        deadline: toRequiredServerTime(d.jzsj),
+        lateSubmissionDeadline: toServerTime(d.bjjzsj),
+        url: URLS.LEARN_HOMEWORK_DETAIL_TEACHER(courseID, d.zyid),
+        completionType: d.zywcfs,
+        submissionType: d.zytjfs,
+        gradedCount: d.ypys,
+        submittedCount: d.yjs,
+        unsubmittedCount: d.wjs,
+      }) satisfies HomeworkTA,
+  );
+}
+
+async function getStudentHomeworkList(s: Session, courseID: string, options: HomeworkListOptions): Promise<Homework[]> {
+  const [lists, excellentHomeworkListByHomework] = await Promise.all([
+    Promise.all(HOMEWORK_LIST_SOURCES.map((source) => getHomeworkListAtUrl(s, courseID, source.url, source.status))),
+    // a failed excellent homework list doesn't fail the homework list: its items get `excellentHomeworkList: undefined`
+    getExcellentHomeworkListByHomework(s, courseID).catch(() => undefined),
+  ]);
+  return Promise.all(
+    lists.flat().map(async (h) => {
+      const homework: Homework = {
+        ...h,
+        excellentHomeworkList: excellentHomeworkListByHomework && (excellentHomeworkListByHomework[h.baseId] ?? []),
+      };
+      return isSelected(options.details, homework) ? { ...homework, ...(await getHomeworkDetail(s, h)) } : homework;
+    }),
+  );
 }
 
 async function getHomeworkListAtUrl(
   s: Session,
   courseID: string,
   url: string,
-  status: IHomeworkStatus,
-): Promise<IHomework[]> {
+  status: HomeworkStatus,
+): Promise<HomeworkBase[]> {
   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,
-      extra: json,
-    });
-  }
+  expectSuccess(json, FailReason.INVALID_RESPONSE);
 
   const result = (json.object?.aaData ?? []) as any[];
 
@@ -119,23 +135,22 @@ async function getHomeworkListAtUrl(
         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,
+        deadline: toRequiredServerTime(h.jzsj),
+        lateSubmissionDeadline: toServerTime(h.bjjzsj),
         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,
+        submitTime: toServerTime(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,
+        gradeTime: toServerTime(h.pysj),
         isFavorite: h.sfsc === YES,
-        favoriteTime: h.scsj === null || h.sfsc !== YES ? undefined : h.scsj,
         comment: h.bznr ?? undefined,
         ...status,
-      }) satisfies IHomework,
+      }) satisfies HomeworkBase,
   );
 }
 
@@ -147,12 +162,7 @@ async function getExcellentHomeworkListByHomework(
     method: 'POST',
     body: URLS.LEARN_PAGE_LIST_FORM_DATA(courseID),
   });
-  if (json.result !== 'success') {
-    return Promise.reject({
-      reason: FailReason.INVALID_RESPONSE,
-      extra: json,
-    });
-  }
+  expectSuccess(json, FailReason.INVALID_RESPONSE);
 
   const result = (json.object?.aaData ?? []) as any[];
 
@@ -170,7 +180,7 @@ async function getExcellentHomeworkListByHomework(
             name: h.cy?.split(' ')?.[1],
             anonymous: h.sfzm === YES,
           },
-        }) satisfies IExcellentHomework,
+        }) satisfies ExcellentHomeworkBase,
     )
     .reduce<{ [id: string]: ExcellentHomework[] }>((acc, cur) => {
       if (!acc[cur.baseId]) {
@@ -181,7 +191,7 @@ async function getExcellentHomeworkListByHomework(
     }, {});
 }
 
-async function parseHomeworkAtUrl(s: Session, url: string): Promise<IHomeworkDetail> {
+async function parseHomeworkAtUrl(s: Session, url: string): Promise<HomeworkDetail> {
   const result = $(await s.fetchTextWithToken(url));
 
   const fileDivs = result('div.list.fujian.clearfix');
@@ -203,43 +213,38 @@ async function parseHomeworkAtUrl(s: Session, url: string): Promise<IHomeworkDet
  */
 export async function getHomeworkDetail(
   s: Session,
-  homework: Pick<IHomework | IExcellentHomework, 'url' | 'baseId'>,
-): Promise<IHomeworkDetail> {
+  homework: Pick<HomeworkBase | ExcellentHomeworkBase, 'url' | 'baseId'>,
+): Promise<HomeworkDetail> {
   const [page, description] = await Promise.all([
     parseHomeworkAtUrl(s, homework.url),
     getHomeworkDescription(s, homework.baseId),
   ]);
-  return { ...page, ...description };
+  // the description JSON wins, but an empty one falls back to the page
+  return { ...page, description: description.description ?? page.description };
 }
 
-async function getHomeworkDescription(s: Session, baseId: string): Promise<IHomeworkDetail> {
+async function getHomeworkDescription(s: Session, baseId: string): Promise<HomeworkDetail> {
   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,
-      extra: json,
-    } as ApiError;
-  }
+  expectSuccess(json, FailReason.INVALID_RESPONSE);
   return {
     description: trimAndDefine(json.msg),
   };
 }
 
-function parseHomeworkFile(s: Session, fileDiv: Element): RemoteFile | undefined {
+/** the attachment in one `div.list.fujian` block; `undefined` if the block is missing or has no link */
+function parseHomeworkFile(s: Session, fileDiv: Element | undefined): RemoteFile | undefined {
+  if (!fileDiv) return undefined;
   const fileNode = $(fileDiv)('.ftitle').children('a')[0] ?? $(fileDiv)('.fl').children('a')[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 + href;
-    if (params.has('downloadUrl')) {
-      downloadUrl = URLS.LEARN_PREFIX + params.get('downloadUrl')!;
-    }
+    // a link to the file viewer carries the download path in its `downloadUrl` parameter
+    const downloadUrl = URLS.LEARN_PREFIX + (params.get('downloadUrl') ?? href);
     return {
       id: attachmentId,
       name: (fileNode.children[0] as { data?: string } | undefined)?.data ?? '',
@@ -256,19 +261,96 @@ export async function submitHomework(
   s: Session,
   id: string,
   content = '',
-  attachment?: IHomeworkSubmitAttachment,
+  attachment?: HomeworkSubmitAttachment,
   removeAttachment = false,
 ): Promise<void> {
-  const json = await s.fetchJsonWithToken(URLS.LEARN_HOMEWORK_SUBMIT(), {
+  const json = await s.fetchJsonWithToken(URLS.LEARN_HOMEWORK_SUBMIT, {
     method: 'POST',
-    body: URLS.LEARN_HOMEWORK_SUBMIT_FORM_DATA(id, content, attachment, removeAttachment),
+    body: homeworkSubmitForm(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,
-      extra: json,
-    });
+  checkHomeworkSubmitResponse(json);
+}
+
+/**
+ * The request `submitHomework` would send, for sending it with another HTTP client (e.g. one that reports upload
+ * progress). Checks the session first (`ensureSession`: one request, and a login only if it has expired), as the
+ * request is sent without the helper's re-login and retry. Read the answer with `checkHomeworkSubmitResponse`.
+ */
+export async function getHomeworkSubmitRequest(
+  s: Session,
+  id: string,
+  content = '',
+  attachment?: HomeworkSubmitAttachment,
+  removeAttachment = false,
+): Promise<HomeworkSubmitRequest> {
+  await s.ensureSession(URLS.LEARN_CURRENT_SEMESTER);
+  return {
+    url: addCSRFTokenToUrl(URLS.LEARN_HOMEWORK_SUBMIT, s.csrfToken),
+    body: homeworkSubmitForm(id, content, attachment, removeAttachment),
+  };
+}
+
+/**
+ * Check the server's answer to a homework submission: its parsed JSON, or the body as text. Rejects with
+ * `NOT_LOGGED_IN` for the login page of an expired session (which the server sends with status 200),
+ * `INVALID_RESPONSE` for any other text that isn't JSON, and `OPERATION_FAILED` (with the answer in `extra`) unless
+ * `result` is `'success'`.
+ */
+export function checkHomeworkSubmitResponse(body: unknown): void {
+  let json = body;
+  if (typeof body === 'string') {
+    try {
+      json = JSON.parse(body);
+    } catch {
+      throw apiError(
+        looksLikeLoginPage(body) ? FailReason.NOT_LOGGED_IN : FailReason.INVALID_RESPONSE,
+        body.slice(0, 200),
+      );
+    }
   }
+  expectSuccess(json, FailReason.OPERATION_FAILED);
+}
+
+/**
+ * The form the website's submit page sends (`fileUploadProgress` in `/res/js/common/myApp.js`): `fileupload` is the
+ * picked file, or the text "undefined" when none is picked (it appends `files[0]` as is); `zynr` is the whole current
+ * answer as HTML from its editor, sent every time (also when only the attachment changes); `isDeleted` is "1" when the
+ * existing attachment is deleted, and then the server ignores `zynr` (the submitted answer stays).
+ */
+export const homeworkSubmitForm = (
+  id: string,
+  content = '',
+  attachment?: HomeworkSubmitAttachment,
+  removeAttachment = false,
+) => {
+  const form = new FormData();
+  form.append('xszyid', id);
+  form.append('zynr', content ?? '');
+  if (!attachment) form.append('fileupload', 'undefined');
+  else if (attachment.content instanceof Blob) form.append('fileupload', attachment.content, attachment.filename);
+  else {
+    // React Native's FormData reads a file from an object with its uri, name and type
+    const { uri, type } = attachment.content;
+    form.append('fileupload', { uri, name: attachment.filename, type: type || 'application/octet-stream' } as any);
+  }
+  if (removeAttachment) form.append('isDeleted', '1');
+  else form.append('isDeleted', '0');
+  return form;
+};
+
+const HTML_ESCAPES: Record<string, string> = { '&': '&amp;', '<': '&lt;', '>': '&gt;', '"': '&quot;', "'": '&#39;' };
+
+/**
+ * Plain text as the website's answer editor sends it: one `<p>` per line, with `&nbsp;` for an empty line, and `''`
+ * for text that is only whitespace. The server replaces the submitted answer with what is sent, so send its HTML
+ * as it is when the answer wasn't edited, to keep its formatting.
+ */
+export function homeworkContentHtml(text: string): string {
+  if (!text.trim()) return '';
+  return text
+    .split(/\r?\n/)
+    .map((line) => `<p>${line.trim() ? line.replace(/[&<>"']/g, (c) => HTML_ESCAPES[c]) : '&nbsp;'}</p>`)
+    .join('');
 }

package/src/index.ts

@@ -11,40 +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 */
@@ -53,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`) */
@@ -76,35 +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. Logins never overlap: one with
-   * credentials waits for a login in progress, and requests that find the session expired meanwhile wait for it.
+   * 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 this.#session.runLogin(() =>
-      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));
   }
 
   /**
@@ -113,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) */
@@ -128,9 +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`), or with a
-   * `RangeError` for a date that is not a valid yyyymmdd.
+   * 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);
@@ -146,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,
@@ -184,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);
   }
 
@@ -217,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);
   }
 
@@ -243,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);
   }
 
@@ -338,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);
   }