@robertying/thu-learn-lib 5.1.0 → 6.0.0

package/src/favorites.ts

@@ -1,23 +1,25 @@
 // Favorites (收藏) and comments (备注).
 
 import type { Session } from './request.ts';
-import { YES } from './request.ts';
 import type { CommentItem, FavoriteItem } from './types.ts';
 import { ContentType, FailReason } from './types.ts';
 import * as URLS from './urls.ts';
-import { CONTENT_TYPE_MAP_REVERSE, decodeHTML } from './utils.ts';
+import {
+  CONTENT_TYPE_MAP_REVERSE,
+  YES,
+  decodeHTML,
+  expectSuccess,
+  toRequiredServerTime,
+  toServerTime,
+} from './utils.ts';
 
 /**
  * Add an item to favorites. (收藏)
+ * Success is `result: 'success'`; the message is in the website's language ("收藏成功", "Added successfully.").
  */
 export async function addToFavorites(s: Session, type: ContentType, id: string): Promise<void> {
   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,
-      extra: json,
-    });
-  }
+  expectSuccess(json, FailReason.OPERATION_FAILED);
 }
 
 /**
@@ -25,12 +27,7 @@ export async function addToFavorites(s: Session, type: ContentType, id: string):
  */
 export async function removeFromFavorites(s: Session, id: string): Promise<void> {
   const json = await s.fetchJsonWithToken(URLS.LEARN_FAVORITE_REMOVE(id));
-  if (json.result !== 'success' || !json.msg?.endsWith?.('成功')) {
-    return Promise.reject({
-      reason: FailReason.OPERATION_FAILED,
-      extra: json,
-    });
-  }
+  expectSuccess(json, FailReason.OPERATION_FAILED);
 }
 
 /**
@@ -42,12 +39,7 @@ export async function getFavorites(s: Session, courseID?: string, type?: Content
     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[];
   return result
     .map((e): FavoriteItem | undefined => {
@@ -57,15 +49,17 @@ export async function getFavorites(s: Session, courseID?: string, type?: Content
         id: e.ywid,
         type: itemType,
         title: decodeHTML(e.ywbt),
-        time: itemType === ContentType.DISCUSSION || itemType === ContentType.QUESTION ? e.tlsj : e.ywsj,
+        time: toRequiredServerTime(
+          itemType === ContentType.DISCUSSION || itemType === ContentType.QUESTION ? e.tlsj : e.ywsj,
+        ),
         state: e.ywzt,
         extra: e.ywbz ?? undefined,
         semesterId: e.xnxq,
         courseId: e.wlkcid,
         pinned: e.sfzd === YES,
-        pinnedTime: e.zdsj === null ? undefined : e.zdsj, // Note: this field is originally unix timestamp instead of string
+        pinnedTime: toServerTime(e.zdsj),
         comment: e.bznr ?? undefined,
-        addedTime: e.scsj,
+        addedTime: toRequiredServerTime(e.scsj),
         itemId: e.id,
       } satisfies FavoriteItem;
     })
@@ -80,12 +74,7 @@ export async function pinFavoriteItem(s: Session, id: string): Promise<void> {
     method: 'POST',
     body: URLS.LEARN_FAVORITE_PIN_UNPIN_FORM_DATA(id),
   });
-  if (json.result !== 'success') {
-    return Promise.reject({
-      reason: FailReason.OPERATION_FAILED,
-      extra: json,
-    });
-  }
+  expectSuccess(json, FailReason.OPERATION_FAILED);
 }
 
 /**
@@ -96,12 +85,7 @@ export async function unpinFavoriteItem(s: Session, id: string): Promise<void> {
     method: 'POST',
     body: URLS.LEARN_FAVORITE_PIN_UNPIN_FORM_DATA(id),
   });
-  if (json.result !== 'success') {
-    return Promise.reject({
-      reason: FailReason.OPERATION_FAILED,
-      extra: json,
-    });
-  }
+  expectSuccess(json, FailReason.OPERATION_FAILED);
 }
 
 /**
@@ -113,12 +97,7 @@ export async function setComment(s: Session, type: ContentType, id: string, cont
     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,
-      extra: json,
-    });
-  }
+  expectSuccess(json, FailReason.OPERATION_FAILED);
 }
 
 /**
@@ -130,12 +109,7 @@ export async function getComments(s: Session, courseID?: string, type?: ContentT
     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[];
   return result
     .map((e): CommentItem | undefined => {
@@ -149,7 +123,7 @@ export async function getComments(s: Session, courseID?: string, type?: ContentT
         title: decodeHTML(e.ywbt),
         semesterId: e.xnxq,
         courseId: e.wlkcid,
-        commentTime: e.cjsj,
+        commentTime: toRequiredServerTime(e.cjsj),
         itemId: e.id,
       } satisfies CommentItem;
     })

package/src/files.ts

@@ -1,24 +1,23 @@
 // Course files (课程文件) and file categories.
 
 import type { Session } from './request.ts';
-import type { File, FileCategory } from './types.ts';
+import type { CourseFile, FileCategory } from './types.ts';
 import { ContentType, CourseType, FailReason } from './types.ts';
 import * as URLS from './urls.ts';
-import { decodeHTML, formatFileSize } from './utils.ts';
+import { YES, decodeHTML, expectSuccess, formatFileSize, toRequiredServerTime } from './utils.ts';
 
 /** 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 s.fetchJsonWithToken(URLS.LEARN_FILE_LIST(courseID, courseType));
-  if (json.result !== 'success') {
-    return Promise.reject({
-      reason: FailReason.INVALID_RESPONSE,
-      extra: json,
-    });
-  }
+): Promise<CourseFile[]> {
+  // categories only fill `category`; don't fail the whole list when they can't be fetched
+  const [json, categoryList] = await Promise.all([
+    s.fetchJsonWithToken(URLS.LEARN_FILE_LIST(courseID, courseType)),
+    getFileCategoryList(s, courseID, courseType).catch((): FileCategory[] => []),
+  ]);
+  expectSuccess(json, FailReason.INVALID_RESPONSE);
 
   let result: any[] = [];
   if (Array.isArray(json.object?.resultsList)) {
@@ -29,42 +28,47 @@ export async function getFileList(
     result = json.object;
   }
 
-  // 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) => ({ ...parseFile(s, f, courseType), category: categories.get(f.kjflid) }));
+}
 
-  return result.map((f) => {
-    const title = decodeHTML(f.bt);
-    const fileId = f.wjid;
-    const uploadTime = f.scsj;
-    const downloadUrl = URLS.LEARN_FILE_DOWNLOAD(fileId, courseType);
-    const previewUrl = URLS.LEARN_FILE_PREVIEW(ContentType.FILE, fileId, courseType, s.previewFirstPage);
-    return {
-      id: f.kjxxid,
-      fileId,
-      category: categories.get(f.kjflid),
-      title,
-      description: decodeHTML(f.ms),
-      rawSize: f.wjdx,
-      size: f.fileSize,
-      uploadTime,
-      publishTime: uploadTime,
+/** a 0 / 1 flag, which the server sends as a number, a string or (in older answers) a boolean */
+const isSet = (flag: unknown): boolean => flag === true || Number(flag) === 1;
+
+/** a count or size, which the server sends as a number or a string */
+const toNumber = (value: unknown): number => Number(value ?? 0) || 0;
+
+/** a file of the object-shaped lists (`getFileList`, and `getFileListByCategory` for a teacher) */
+function parseFile(s: Session, f: any, courseType: CourseType): CourseFile {
+  const title = decodeHTML(f.bt);
+  const fileId = f.wjid;
+  const uploadTime = toRequiredServerTime(f.scsj);
+  const downloadUrl = URLS.LEARN_FILE_DOWNLOAD(fileId, courseType);
+  const previewUrl = URLS.LEARN_FILE_PREVIEW(ContentType.FILE, fileId, courseType, s.previewFirstPage);
+  return {
+    id: f.kjxxid,
+    fileId,
+    title,
+    description: decodeHTML(f.ms),
+    rawSize: toNumber(f.wjdx),
+    size: f.fileSize,
+    uploadTime,
+    publishTime: uploadTime,
+    downloadUrl,
+    previewUrl,
+    isNew: isSet(f.isNew), // 1 / 0 for a student
+    markedImportant: isSet(f.sfqd), // string '1' for a teacher, number 1 for a student
+    visitCount: toNumber(f.xsllcs ?? f.llcs),
+    downloadCount: toNumber(f.xzcs),
+    fileType: f.wjlx,
+    remoteFile: {
+      id: fileId,
+      name: title,
       downloadUrl,
       previewUrl,
-      isNew: f.isNew ?? false,
-      markedImportant: f.sfqd === 1,
-      visitCount: f.xsllcs ?? f.llcs ?? 0,
-      downloadCount: f.xzcs ?? 0,
-      fileType: f.wjlx,
-      remoteFile: {
-        id: fileId,
-        name: title,
-        downloadUrl,
-        previewUrl,
-        size: f.fileSize,
-      },
-    } satisfies File;
-  });
+      size: f.fileSize,
+    },
+  };
 }
 
 /** Get file categories of the specified course. */
@@ -74,12 +78,7 @@ export async function getFileCategoryList(
   courseType: CourseType = CourseType.STUDENT,
 ): Promise<FileCategory[]> {
   const json = await s.fetchJsonWithToken(URLS.LEARN_FILE_CATEGORY_LIST(courseID, courseType));
-  if (json.result !== 'success') {
-    return Promise.reject({
-      reason: FailReason.INVALID_RESPONSE,
-      extra: json,
-    });
-  }
+  expectSuccess(json, FailReason.INVALID_RESPONSE);
 
   const result = (json.object?.rows ?? []) as any[];
 
@@ -88,7 +87,7 @@ export async function getFileCategoryList(
       ({
         id: c.kjflid,
         title: decodeHTML(c.bt),
-        creationTime: c.czsj,
+        creationTime: toRequiredServerTime(c.czsj),
       }) satisfies FileCategory,
   );
 }
@@ -102,96 +101,79 @@ export async function getFileListByCategory(
   courseID: string,
   categoryId: string,
   courseType: CourseType = CourseType.STUDENT,
-): Promise<File[]> {
-  if (courseType === CourseType.STUDENT) {
-    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,
-        extra: json,
-      });
-    }
-
-    const result = (json.object ?? []) as any[];
-
-    return result.map((f) => {
-      const fileId = f[7];
-      const title = decodeHTML(f[1]);
-      const rawSize = f[9];
-      const size = formatFileSize(rawSize);
-      const downloadUrl = URLS.LEARN_FILE_DOWNLOAD(fileId, courseType);
-      const previewUrl = URLS.LEARN_FILE_PREVIEW(ContentType.FILE, fileId, courseType, s.previewFirstPage);
-      return {
-        id: f[0],
-        fileId,
-        title,
-        description: decodeHTML(f[5]),
-        rawSize,
-        size,
-        uploadTime: f[6],
-        publishTime: f[10],
-        downloadUrl,
-        previewUrl,
-        isNew: f[8] === 1,
-        markedImportant: f[2] === 1,
-        visitCount: 0,
-        downloadCount: 0,
-        fileType: f[13],
-        remoteFile: {
-          id: fileId,
-          name: title,
-          downloadUrl,
-          previewUrl,
-          size,
-        },
-        isFavorite: f[11],
-        comment: f[14] ?? undefined,
-      } satisfies File;
-    });
-  } else {
-    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,
-        extra: json,
-      });
-    }
-
-    const result = (json.object?.aaData ?? []) as any[];
-
-    return result.map((f) => {
-      const title = decodeHTML(f.bt);
-      const fileId = f.wjid;
-      const uploadTime = f.scsj;
-      const downloadUrl = URLS.LEARN_FILE_DOWNLOAD(fileId, courseType);
-      const previewUrl = URLS.LEARN_FILE_PREVIEW(ContentType.FILE, fileId, courseType, s.previewFirstPage);
-      return {
-        id: f.kjxxid,
-        fileId,
-        title,
-        description: decodeHTML(f.ms),
-        rawSize: f.wjdx,
-        size: f.fileSize,
-        uploadTime,
-        publishTime: uploadTime,
+): Promise<CourseFile[]> {
+  return courseType === CourseType.STUDENT
+    ? getStudentFileListByCategory(s, courseID, categoryId)
+    : getTeacherFileListByCategory(s, courseID, categoryId);
+}
+
+/** the columns of a row of the student's file list of a category, which is an array instead of an object */
+const COLUMN = {
+  ID: 0,
+  TITLE: 1,
+  MARKED_IMPORTANT: 2,
+  DESCRIPTION: 5,
+  UPLOAD_TIME: 6,
+  FILE_ID: 7,
+  IS_NEW: 8,
+  RAW_SIZE: 9,
+  PUBLISH_TIME: 10,
+  IS_FAVORITE: 11,
+  FILE_TYPE: 13,
+  COMMENT: 14,
+} as const;
+
+async function getStudentFileListByCategory(s: Session, courseID: string, categoryId: string): Promise<CourseFile[]> {
+  const json = await s.fetchJsonWithToken(URLS.LEARN_FILE_LIST_BY_CATEGORY_STUDENT(courseID, categoryId));
+  expectSuccess(json, FailReason.INVALID_RESPONSE);
+
+  const result = (json.object ?? []) as any[][];
+
+  return result.map((f) => {
+    const fileId = f[COLUMN.FILE_ID];
+    const title = decodeHTML(f[COLUMN.TITLE]);
+    const rawSize = toNumber(f[COLUMN.RAW_SIZE]);
+    const size = formatFileSize(rawSize);
+    const downloadUrl = URLS.LEARN_FILE_DOWNLOAD(fileId, CourseType.STUDENT);
+    const previewUrl = URLS.LEARN_FILE_PREVIEW(ContentType.FILE, fileId, CourseType.STUDENT, s.previewFirstPage);
+    return {
+      id: f[COLUMN.ID],
+      fileId,
+      title,
+      description: decodeHTML(f[COLUMN.DESCRIPTION]),
+      rawSize,
+      size,
+      uploadTime: toRequiredServerTime(f[COLUMN.UPLOAD_TIME]),
+      publishTime: toRequiredServerTime(f[COLUMN.PUBLISH_TIME]),
+      downloadUrl,
+      previewUrl,
+      isNew: isSet(f[COLUMN.IS_NEW]),
+      markedImportant: isSet(f[COLUMN.MARKED_IMPORTANT]),
+      // not in this list
+      visitCount: 0,
+      downloadCount: 0,
+      fileType: f[COLUMN.FILE_TYPE],
+      remoteFile: {
+        id: fileId,
+        name: title,
         downloadUrl,
         previewUrl,
-        isNew: f.isNew ?? false,
-        markedImportant: f.sfqd === 1,
-        visitCount: f.xsllcs ?? f.llcs ?? 0,
-        downloadCount: f.xzcs ?? 0,
-        fileType: f.wjlx,
-        remoteFile: {
-          id: fileId,
-          name: title,
-          downloadUrl,
-          previewUrl,
-          size: f.fileSize,
-        },
-      } satisfies File;
-    });
-  }
+        size,
+      },
+      isFavorite: f[COLUMN.IS_FAVORITE] === YES, // '是' / '否' like the other lists
+      comment: f[COLUMN.COMMENT] ?? undefined,
+    } satisfies CourseFile;
+  });
+}
+
+async function getTeacherFileListByCategory(s: Session, courseID: string, categoryId: string): Promise<CourseFile[]> {
+  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),
+  });
+  expectSuccess(json, FailReason.INVALID_RESPONSE);
+
+  const result = (json.object?.aaData ?? []) as any[];
+
+  return result.map((f) => parseFile(s, f, CourseType.TEACHER));
 }