@robertying/thu-learn-lib 4.1.0 → 5.1.0

package/src/types.ts

@@ -14,6 +14,10 @@ export type HelperConfig = {
   fetch?: Fetch;
   cookieJar?: CookieJar;
   generatePreviewUrlForFirstPage?: boolean;
+  /** at most this many requests in flight at once, including login (default 6; `Infinity` for no limit) */
+  maxConcurrentRequests?: number;
+  /** milliseconds to wait for a response before rejecting with `FailReason.REQUEST_TIMEOUT` (default 60000; 0 for none) */
+  requestTimeout?: number;
 };
 
 export enum FailReason {
@@ -27,6 +31,7 @@ export enum FailReason {
   UNEXPECTED_STATUS = 'unexpected status',
   OPERATION_FAILED = 'operation failed',
   ERROR_SETTING_COOKIES = 'could not set cookies',
+  REQUEST_TIMEOUT = 'request timed out',
 }
 
 export interface ApiError {
@@ -78,7 +83,8 @@ interface ICourseInfo {
   name: string;
   chineseName: string;
   englishName: string;
-  timeAndLocation: string[];
+  /** only with `getCourseList(..., { timeAndLocation: true })`; see `getCourseTimeAndLocation` */
+  timeAndLocation?: string[];
   url: string;
   teacherName: string;
   teacherNumber: string;
@@ -111,6 +117,8 @@ export interface INotification {
   expireTime?: string;
   isFavorite: boolean;
   comment?: string;
+  /** name of the attachment, if the notice has one; fetch it with `getNotificationAttachment` */
+  attachmentName?: string;
 }
 
 export interface INotificationDetail {
@@ -357,11 +365,63 @@ export interface IQuestionnaire {
   isFavorite: boolean;
   comment?: string;
   url: string;
-  detail: QuestionnaireDetail[];
+  /** the questions; only for the questionnaires `getQuestionnaireList`'s `details` selects (by default all) */
+  detail?: QuestionnaireDetail[];
 }
 
 export type Questionnaire = IQuestionnaire;
 
+/** which items get their extra per-item requests: none (default), all, or those the predicate accepts */
+export type DetailSelector<T> = 'none' | 'all' | ((item: T) => boolean);
+
+export interface CourseListOptions {
+  /** fetch each course's time and location (one request per course; default false) */
+  timeAndLocation?: boolean;
+}
+
+export interface HomeworkListOptions {
+  /**
+   * Which homework gets its detail (page + description JSON, 2 requests each); default `'none'`.
+   * The same as calling `getHomeworkDetail` for those items.
+   */
+  details?: DetailSelector<IHomework>;
+}
+
+export interface NotificationListOptions {
+  /**
+   * Which notices with an attachment get it (1 request each); default `'none'`.
+   * The same as calling `getNotificationAttachment` for those items.
+   */
+  attachments?: DetailSelector<INotification>;
+}
+
+export interface QuestionnaireListOptions {
+  /**
+   * Which questionnaires get their questions (`detail`, 1 request each); default `'all'` (unlike the other lists, for
+   * compatibility). The same as calling `getQuestionnaireDetail` for those items.
+   */
+  details?: DetailSelector<IQuestionnaire>;
+}
+
+export interface AllContentsOptions<T extends ContentType> {
+  courseType?: CourseType;
+  /** homework or questionnaire `details`, or notification `attachments`, passed to each course's list */
+  details?: T extends ContentType.HOMEWORK
+    ? DetailSelector<IHomework>
+    : T extends ContentType.NOTIFICATION
+      ? DetailSelector<INotification>
+      : T extends ContentType.QUESTIONNAIRE
+        ? DetailSelector<IQuestionnaire>
+        : never;
+}
+
+export interface AllContentsResult<T extends ContentType> {
+  /** content of each course that succeeded */
+  contents: CourseContent<T>;
+  /** the error of each course that failed */
+  errors: { [courseID: string]: unknown };
+}
+
 export type ContentTypeMap = {
   [ContentType.NOTIFICATION]: Notification;
   [ContentType.FILE]: File;

package/src/user.ts

@@ -8,7 +8,7 @@ import * as URLS from './urls.ts';
 
 /** get user's name and department */
 export async function getUserInfo(s: Session, courseType = CourseType.STUDENT): Promise<UserInfo> {
-  const content = await (await s.fetchWithToken(URLS.LEARN_HOMEPAGE(courseType))).text();
+  const content = await s.fetchTextWithToken(URLS.LEARN_HOMEPAGE(courseType));
 
   const dom = $(content);
   const name = dom('a.user-log').text().trim();

package/src/utils.ts

@@ -1,5 +1,6 @@
 import { decodeHTML as _decodeHTML } from 'entities';
 
+import type { ApiError, DetailSelector } from './types.ts';
 import { ContentType, FailReason, HomeworkGradeLevel, QuestionnaireType, SemesterType } from './types.ts';
 
 export function parseSemesterType(n: number): SemesterType {
@@ -77,14 +78,20 @@ export const GRADE_LEVEL_MAP = new Map([
 
 export const JSONP_EXTRACTOR_NAME = 'thu_learn_lib_jsonp_extractor';
 
+const invalidJSONP = (extra: unknown): ApiError => ({ reason: FailReason.INVALID_RESPONSE, extra });
+
 export function extractJSONPResult(jsonp: string): any {
   // check jsonp format
   if (!jsonp.startsWith(JSONP_EXTRACTOR_NAME)) {
-    throw FailReason.INVALID_RESPONSE;
+    throw invalidJSONP(jsonp.slice(0, 200));
   }
   // evaluate the result
-  // oxlint-disable-next-line typescript/no-implied-eval -- JSONP from the registrar is a JS expression, not JSON
-  return Function(`"use strict";const ${JSONP_EXTRACTOR_NAME}=(s)=>s;return ${jsonp};`)();
+  try {
+    // oxlint-disable-next-line typescript/no-implied-eval -- JSONP from the registrar is a JS expression, not JSON
+    return Function(`"use strict";const ${JSONP_EXTRACTOR_NAME}=(s)=>s;return ${jsonp};`)();
+  } catch (err) {
+    throw invalidJSONP(err);
+  }
 }
 
 export function formatFileSize(size: number): string {
@@ -118,3 +125,7 @@ export const QNR_TYPE_MAP = new Map([
   ['填表', QuestionnaireType.FORM],
   ['问卷', QuestionnaireType.SURVEY],
 ]);
+
+/** whether `item` is selected by a `DetailSelector` (`undefined` means `'none'`) */
+export const isSelected = <T>(selector: DetailSelector<T> | undefined, item: T): boolean =>
+  selector === 'all' || (typeof selector === 'function' && selector(item));