@robertying/thu-learn-lib 5.0.0 → 5.1.0

package/src/notices.ts

@@ -37,12 +37,10 @@ async function getNotificationListKind(
   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();
+  const json = await s.fetchJsonWithToken(URLS.LEARN_NOTIFICATION_LIST(courseType, expired), {
+    method: 'POST',
+    body: URLS.LEARN_PAGE_LIST_FORM_DATA(courseID),
+  });
   if (json.result !== 'success') {
     return Promise.reject({
       reason: FailReason.INVALID_RESPONSE,
@@ -73,7 +71,7 @@ async function getNotificationListKind(
 
 /**
  * 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,
@@ -85,21 +83,17 @@ export async function getNotificationAttachment(
   // const postParams = new FormData();
   // postParams.append('id', id);
   // postParams.append('wlkcid', courseID);
-  // const metadata = await (await s.fetchWithToken(URL.LEARN_NOTIFICATION_EDIT(courseType), {
+  // const metadata = await s.fetchJsonWithToken(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

@@ -2,25 +2,36 @@
 
 import type { Session } from './request.ts';
 import { YES } from './request.ts';
-import type { Questionnaire, QuestionnaireDetail } from './types.ts';
+import type { ApiError, 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, decodeHTML, isSelected } 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();
+  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,
@@ -28,36 +39,39 @@ async function getQuestionnaireListAtUrl(s: Session, courseID: string, url: stri
     });
   }
   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: 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),
+    } 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 { reason: FailReason.INVALID_RESPONSE, extra: json } as ApiError;
+  }
+  return json.map(
     (e) =>
       ({
         id: e.wtid,

package/src/request.ts

@@ -40,7 +40,7 @@ const urlOf = (input: Parameters<Fetch>[0]): string =>
  * Let at most `max` calls of `inner` run at once; the rest wait in FIFO order. A slot is freed when the response
  * headers arrive (or the call fails), so reading a body does not hold one.
  */
-export function limitConcurrency(inner: Fetch, max: number): Fetch {
+export function limitConcurrency<F extends (...args: any[]) => Promise<Response>>(inner: F, max: number): F {
   if (!(max >= 1) || max === Infinity) return inner;
   let active = 0;
   const waiting: (() => void)[] = [];
@@ -57,47 +57,57 @@ export function limitConcurrency(inner: Fetch, max: number): Fetch {
     if (next) next();
     else active -= 1;
   };
-  return async (...args) => {
+  return (async (...args: Parameters<F>) => {
     await acquire();
     try {
       return await inner(...args);
     } finally {
       release();
     }
-  };
+  }) as F;
 }
 
+/** `RequestInit` plus a per-request `timeout` (milliseconds; 0 or `Infinity` for none) */
+export type RequestOptions = RequestInit & { timeout?: number };
+
+/** a `Fetch` whose `init` can also carry a per-request `timeout` */
+export type TimedFetch = (input: Parameters<Fetch>[0], init?: RequestOptions) => Promise<Response>;
+
 /**
- * Abort a call of `inner` that has no response headers after `ms` milliseconds and reject it with
- * `FailReason.REQUEST_TIMEOUT`. A caller's own `signal` still works. Uses only `AbortController` and `setTimeout`,
- * which React Native has (unlike `AbortSignal.timeout` / `AbortSignal.any`).
+ * Abort a call of `inner` that has no response headers after `ms` milliseconds (or `init.timeout`, which overrides it
+ * for one request) and reject it with `FailReason.REQUEST_TIMEOUT`. A caller's own `signal` still works, also while
+ * the body is read. Uses only `AbortController` and `setTimeout`, which React Native has (unlike
+ * `AbortSignal.timeout` / `AbortSignal.any`). Note that React Native's fetch resolves only after the whole body has
+ * arrived, so there the timeout covers the download too.
  */
-export function withTimeout(inner: Fetch, ms: number): Fetch {
-  if (!(ms > 0) || ms === Infinity) return inner;
-  return async (input, init) => {
+export function withTimeout(inner: Fetch, ms: number): TimedFetch {
+  return async (input, options) => {
+    const { timeout = ms, ...init } = options ?? {};
+    if (!(timeout > 0) || timeout === Infinity) return inner(input, init);
     const controller = new AbortController();
-    const outer = init?.signal ?? undefined;
+    const outer = init.signal ?? undefined;
     const forward = () => controller.abort(outer?.reason);
     if (outer?.aborted) forward();
+    // kept after the headers arrive, so the caller can still cancel reading the body
     else outer?.addEventListener('abort', forward, { once: true });
     let timedOut = false;
     const timer = setTimeout(() => {
       timedOut = true;
       controller.abort();
-    }, ms);
+    }, timeout);
     try {
       return await inner(input, { ...init, signal: controller.signal });
     } catch (err) {
+      outer?.removeEventListener('abort', forward);
       if (timedOut) {
         throw {
           reason: FailReason.REQUEST_TIMEOUT,
-          extra: { url: urlOf(input), timeout: ms },
+          extra: { url: urlOf(input), timeout },
         } as ApiError;
       }
       throw err;
     } finally {
       clearTimeout(timer);
-      outer?.removeEventListener('abort', forward);
     }
   };
 }
@@ -107,6 +117,26 @@ const discard = (res: Response) => {
   res.body?.cancel().catch(() => {});
 };
 
+/** returned by a read step when the response turned out to be from an expired session */
+const EXPIRED = Symbol('expired');
+
+/**
+ * Whether a 200 body that should have been JSON is an HTML page instead. Web Learning answers some requests of an
+ * expired session with a login or redirect page and status 200, not with a 403 or a `login_timeout` redirect.
+ */
+const looksLikeHtml = (text: string) => text.trimStart().startsWith('<');
+
+/** pages longer than this are taken as real pages, never as the short login / redirect page of an expired session */
+const MAX_LOGIN_PAGE_LENGTH = 4096;
+
+/**
+ * Whether a 200 page is the short login or redirect page of an expired session rather than the page asked for. A
+ * heuristic (not verified against the real server): short, and pointing at the login timeout page or the SSO login.
+ */
+export const looksLikeLoginPage = (text: string) =>
+  text.length < MAX_LOGIN_PAGE_LENGTH &&
+  /login_timeout|id\.tsinghua\.edu\.cn\/do\/off\/ui\/auth\/login|j_spring_security_thauth_roaming_entry/.test(text);
+
 /**
  * State shared by every request a `Learn2018Helper` makes: cookies, CSRF token, language and the fetch wrappers.
  * Internal; the helper keeps it in a private field.
@@ -115,7 +145,7 @@ export class Session {
   readonly provider?: CredentialProvider;
   readonly cookieJar: CookieJar;
   /** fetch with cookies, the concurrency cap and the timeout, but no login check */
-  readonly rawFetch: Fetch;
+  readonly rawFetch: TimedFetch;
   #csrfToken = '';
   /** bumped whenever the session changes (login, `csrfToken` set), so late failures from an old session don't log in again */
   #generation = 0;
@@ -123,10 +153,10 @@ export class Session {
   lang = Language.ZH;
   previewFirstPage: boolean;
 
-  /** `login` signs in through SSO with the `CredentialProvider`; the session calls it at most once at a time */
+  /** `loginWithProvider` signs in through SSO with the `CredentialProvider` */
   constructor(
     config: HelperConfig | undefined,
-    readonly login: () => Promise<void>,
+    readonly loginWithProvider: () => Promise<void>,
   ) {
     this.previewFirstPage = config?.generatePreviewUrlForFirstPage ?? true;
     this.provider = config?.provider;
@@ -147,68 +177,137 @@ export class Session {
   }
 
   /**
-   * Log in with the `CredentialProvider`. Concurrent callers share one SSO login instead of starting one each.
+   * Run one login (`login`) at a time. It starts after a login already in progress has settled, and requests that
+   * find the session expired meanwhile wait for it instead of starting their own (two SSO logins at once reset each
+   * other's id.tsinghua.edu.cn cookie).
    */
-  relogin(): Promise<void> {
-    this.#pendingLogin ??= this.login().finally(() => {
-      this.#pendingLogin = undefined;
+  runLogin(login: () => Promise<void>): Promise<void> {
+    const previous = this.#pendingLogin?.catch(() => {}) ?? Promise.resolve();
+    const current: Promise<void> = previous.then(login).finally(() => {
+      if (this.#pendingLogin === current) this.#pendingLogin = undefined;
     });
-    return this.#pendingLogin;
+    this.#pendingLogin = current;
+    return current;
   }
 
   /**
-   * Send a request built by `makeUrl` (called again for the retry, so it can pick up a new CSRF token).
+   * Log in with the `CredentialProvider`, or wait for the login already in progress (also one with explicit
+   * credentials) instead of starting another.
+   */
+  relogin(): Promise<void> {
+    return this.#pendingLogin ?? this.runLogin(this.loginWithProvider);
+  }
+
+  /**
+   * Send a request built by `makeUrl` (called again for the retry, so it can pick up a new CSRF token) and read it
+   * with `read`, which returns `EXPIRED` for a body that shows the session has expired.
    * When the session has expired, it rejects with `NOT_LOGGED_IN` if there is no `CredentialProvider`; otherwise it
    * logs in again (sharing a login already in progress, or skipping it if another request already renewed the
    * session) and retries once.
    */
-  async #send(makeUrl: () => string, init?: RequestInit): Promise<Response> {
+  async #send<T>(
+    makeUrl: () => string,
+    init: RequestOptions | undefined,
+    read: (res: Response, retry: boolean) => Promise<T | typeof EXPIRED>,
+  ): Promise<T> {
+    const attempt = async (retry: boolean): Promise<T | typeof EXPIRED> => {
+      const res = await this.rawFetch(makeUrl(), init);
+      if (noLogin(res)) {
+        discard(res);
+        return EXPIRED;
+      }
+      return read(res, retry);
+    };
     const generation = this.#generation;
-    const res = await this.rawFetch(makeUrl(), init);
-    if (!noLogin(res)) return res;
-    discard(res);
+    const first = await attempt(false);
+    if (first !== EXPIRED) return first;
     if (!this.provider) {
       throw { reason: FailReason.NOT_LOGGED_IN } as ApiError;
     }
     if (this.#generation === generation) {
       await this.relogin();
     }
-    const retry = await this.rawFetch(makeUrl(), init);
-    if (noLogin(retry)) {
-      discard(retry);
+    const second = await attempt(true);
+    if (second === EXPIRED) {
       throw { reason: FailReason.NOT_LOGGED_IN } as ApiError;
     }
-    if (retry.status !== 200) {
-      discard(retry);
+    return second;
+  }
+
+  /** the response, but after a re-login only one with status 200 */
+  static readonly #response = async (res: Response, retry: boolean): Promise<Response> => {
+    if (retry && res.status !== 200) {
+      discard(res);
       throw {
         reason: FailReason.UNEXPECTED_STATUS,
-        extra: { code: retry.status, text: retry.statusText },
+        extra: { code: res.status, text: res.statusText },
       } as ApiError;
     }
-    return retry;
-  }
+    return res;
+  };
 
-  /** fetch with a login check (see `#send`) */
-  readonly fetch: Fetch = (input, init) => this.#send(() => urlOf(input), init);
+  /** the parsed JSON body; an HTML page with status 200 means the session has expired */
+  static readonly #json = async (res: Response): Promise<any> => {
+    const text = await res.text();
+    try {
+      return JSON.parse(text);
+    } catch {
+      if (res.status === 200 && looksLikeHtml(text)) return EXPIRED;
+      throw {
+        reason: res.status === 200 ? FailReason.INVALID_RESPONSE : FailReason.UNEXPECTED_STATUS,
+        extra: { code: res.status, text: text.slice(0, 200) },
+      } as ApiError;
+    }
+  };
 
-  /** like `fetch`, but logs in first if there is no CSRF token yet and adds the current token to the URL */
-  readonly fetchWithToken: Fetch = async (input, init) => {
+  /** the text body; a short login / redirect page with status 200 means the session has expired */
+  static readonly #text = async (res: Response, retry: boolean): Promise<string | typeof EXPIRED> => {
+    await Session.#response(res, retry);
+    const text = await res.text();
+    return res.status === 200 && looksLikeLoginPage(text) ? EXPIRED : text;
+  };
+
+  #withToken = async (input: Parameters<Fetch>[0]): Promise<() => string> => {
     if (this.#csrfToken === '') {
       await this.relogin();
     }
     const url = urlOf(input);
-    return this.#send(() => addCSRFTokenToUrl(url, this.#csrfToken), init);
+    return () => addCSRFTokenToUrl(url, this.#csrfToken);
   };
 
+  /** fetch with a login check (see `#send`) */
+  readonly fetch: TimedFetch = (input, init) => this.#send(() => urlOf(input), init, Session.#response);
+
+  /** like `fetch`, but logs in first if there is no CSRF token yet and adds the current token to the URL */
+  readonly fetchWithToken: TimedFetch = async (input, init) =>
+    this.#send(await this.#withToken(input), init, Session.#response);
+
   /**
-   * Make sure the session works: if there is a CSRF token, make one cheap authenticated request (`probeUrl`) and log
-   * in only if it fails; otherwise log in.
+   * Like `fetchWithToken`, but returns the parsed JSON body. A 200 HTML page instead of JSON counts as an expired
+   * session (log in again and retry once, as for a 403).
+   */
+  readonly fetchJsonWithToken = async (input: Parameters<Fetch>[0], init?: RequestOptions): Promise<any> =>
+    this.#send(await this.#withToken(input), init, Session.#json);
+
+  /**
+   * Like `fetchWithToken`, but returns the text body (an HTML page). A short login or redirect page with status 200
+   * counts as an expired session (log in again and retry once, as for a 403).
+   */
+  readonly fetchTextWithToken = async (input: Parameters<Fetch>[0], init?: RequestOptions): Promise<string> =>
+    this.#send(await this.#withToken(input), init, Session.#text);
+
+  /**
+   * Make sure the session works: if there is a CSRF token, fetch the current semester (`probeUrl`) and log in only if
+   * the session has expired; otherwise log in.
    */
   async ensureSession(probeUrl: string): Promise<void> {
     if (this.#csrfToken === '') {
       await this.relogin();
       return;
     }
-    discard(await this.fetchWithToken(probeUrl));
+    const json = await this.fetchJsonWithToken(probeUrl);
+    if (json?.message !== 'success') {
+      throw { reason: FailReason.INVALID_RESPONSE, extra: json } as ApiError;
+    }
   }
 }

package/src/types.ts

@@ -365,7 +365,8 @@ 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;
@@ -394,14 +395,24 @@ export interface NotificationListOptions {
   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 `details` or notification `attachments`, passed to each course's list */
+  /** 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>
-      : never;
+      : T extends ContentType.QUESTIONNAIRE
+        ? DetailSelector<IQuestionnaire>
+        : never;
 }
 
 export interface AllContentsResult<T extends ContentType> {

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,6 +1,6 @@
 import { decodeHTML as _decodeHTML } from 'entities';
 
-import type { DetailSelector } from './types.ts';
+import type { ApiError, DetailSelector } from './types.ts';
 import { ContentType, FailReason, HomeworkGradeLevel, QuestionnaireType, SemesterType } from './types.ts';
 
 export function parseSemesterType(n: number): SemesterType {
@@ -78,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 {