@robertying/thu-learn-lib 5.0.0 → 6.0.0

package/src/homework.ts

@@ -1,37 +1,54 @@
 // 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.
  * 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[]>;
 
@@ -43,77 +60,70 @@ export async function getHomeworkList(
   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();
-    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[]> {
-  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,
-    });
-  }
+  status: HomeworkStatus,
+): Promise<HomeworkBase[]> {
+  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[];
 
@@ -125,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,
   );
 }
 
@@ -149,18 +158,11 @@ 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();
-  if (json.result !== 'success') {
-    return Promise.reject({
-      reason: FailReason.INVALID_RESPONSE,
-      extra: json,
-    });
-  }
+  const json = await s.fetchJsonWithToken(URLS.LEARN_HOMEWORK_LIST_EXCELLENT, {
+    method: 'POST',
+    body: URLS.LEARN_PAGE_LIST_FORM_DATA(courseID),
+  });
+  expectSuccess(json, FailReason.INVALID_RESPONSE);
 
   const result = (json.object?.aaData ?? []) as any[];
 
@@ -178,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]) {
@@ -189,9 +191,8 @@ async function getExcellentHomeworkListByHomework(
     }, {});
 }
 
-async function parseHomeworkAtUrl(s: Session, url: string): Promise<IHomeworkDetail> {
-  const response = await s.fetchWithToken(url);
-  const result = $(await response.text());
+async function parseHomeworkAtUrl(s: Session, url: string): Promise<HomeworkDetail> {
+  const result = $(await s.fetchTextWithToken(url));
 
   const fileDivs = result('div.list.fujian.clearfix');
 
@@ -212,47 +213,41 @@ 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> {
-  const json = await (
-    await s.fetchWithToken(URLS.LEARN_HOMEWORK_DETAIL, {
-      method: 'POST',
-      body: URLS.LEARN_HOMEWORK_DETAIL_FORM_DATA(baseId),
-    })
-  ).json();
-  if (json.result !== 'success') {
-    throw {
-      reason: FailReason.INVALID_RESPONSE,
-      extra: json,
-    } as ApiError;
-  }
+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),
+  });
+  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];
-  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;
-    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 }).data,
+      name: (fileNode.children[0] as { data?: string } | undefined)?.data ?? '',
       downloadUrl,
       previewUrl: URLS.LEARN_FILE_PREVIEW(ContentType.HOMEWORK, attachmentId, CourseType.STUDENT, s.previewFirstPage),
       size,
@@ -266,19 +261,96 @@ export async function submitHomework(
   s: Session,
   id: string,
   content = '',
-  attachment?: IHomeworkSubmitAttachment,
+  attachment?: HomeworkSubmitAttachment,
   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();
-  if (json.result !== 'success') {
-    return Promise.reject({
-      reason: FailReason.OPERATION_FAILED,
-      extra: json,
-    });
+  const json = await s.fetchJsonWithToken(URLS.LEARN_HOMEWORK_SUBMIT, {
+    method: 'POST',
+    body: homeworkSubmitForm(id, content, attachment, removeAttachment),
+    // the response only starts after the whole upload, which can take longer than `requestTimeout`
+    timeout: attachment ? 0 : undefined,
+  });
+  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('');
 }