@robertying/thu-learn-lib 5.0.0 → 6.0.0

package/src/request.ts

@@ -1,22 +1,13 @@
-import * as cheerio from 'cheerio';
-import type { Element } from 'cheerio';
 import fetchCookie from 'fetch-cookie';
 import { fetch } from 'node-fetch-native';
 import { CookieJar } from 'tough-cookie';
 
 import type { ApiError, CredentialProvider, Fetch, HelperConfig } from './types.ts';
 import { FailReason, Language } from './types.ts';
-
-const CHEERIO_CONFIG: cheerio.CheerioOptions = { xml: true };
-
-export const $ = (html: string | Element | Element[]): cheerio.CheerioAPI => {
-  return cheerio.load(html, CHEERIO_CONFIG);
-};
+import { apiError, looksLikeLoginPage, urlOf } from './utils.ts';
 
 export const noLogin = (res: Response) => res.url.includes('login_timeout') || res.status === 403;
 
-export const YES = '是';
-
 /** default for `HelperConfig.maxConcurrentRequests` */
 export const DEFAULT_MAX_CONCURRENT_REQUESTS = 6;
 /** default for `HelperConfig.requestTimeout`, in milliseconds */
@@ -33,14 +24,11 @@ function makeFetch(jar?: CookieJar): typeof fetch {
   return fetchCookie(fetch, jar);
 }
 
-const urlOf = (input: Parameters<Fetch>[0]): string =>
-  typeof input === 'string' ? input : input instanceof URL ? input.href : input.url;
-
 /**
  * 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,56 +45,88 @@ 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 },
-        } as ApiError;
+        throw apiError(FailReason.REQUEST_TIMEOUT, { url: urlOf(input), timeout });
       }
       throw err;
     } finally {
       clearTimeout(timer);
-      outer?.removeEventListener('abort', forward);
     }
   };
 }
 
+/**
+ * Reject a call of `inner` that fails without any response (the fetch implementation's own error: `TypeError: fetch
+ * failed` in Node, `Network request failed` in React Native) with `FailReason.NETWORK_ERROR`, keeping the error in
+ * `extra`. An `ApiError` (such as `REQUEST_TIMEOUT`) and the caller's own abort pass through unchanged.
+ */
+export function withNetworkError(inner: TimedFetch): TimedFetch {
+  return async (input, init) => {
+    try {
+      return await inner(input, init);
+    } catch (err) {
+      if ((err as ApiError | undefined)?.reason !== undefined || init?.signal?.aborted) throw err;
+      throw apiError(FailReason.NETWORK_ERROR, err);
+    }
+  };
+}
+
+/** whether an error means the server was not reached: `NETWORK_ERROR`, or `REQUEST_TIMEOUT` (no answer in time) */
+export const isConnectionError = (err: unknown): boolean => {
+  const reason = (err as ApiError | undefined)?.reason;
+  return reason === FailReason.NETWORK_ERROR || reason === FailReason.REQUEST_TIMEOUT;
+};
+
 /** free the connection of a response we won't read */
-const discard = (res: Response) => {
+export 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');
+
 /**
  * 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,24 +135,37 @@ 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;
   #pendingLogin?: Promise<void>;
+  /**
+   * The `BAD_CREDENTIAL` of the last failed `CredentialProvider` login. Automatic logins (an expired session, no CSRF
+   * token yet) reject with it instead of trying the same credentials again, which could lock the account; an explicit
+   * `login`, or a new CSRF token, clears it.
+   */
+  #badCredential?: ApiError;
   lang = Language.ZH;
   previewFirstPage: boolean;
+  /**
+   * The device fingerprints of the last SSO login. id.tsinghua.edu.cn asks for them again when another site (WebVPN,
+   * for the registrar) signs in with the same id.tsinghua.edu.cn session.
+   */
+  fingerprints?: { fingerPrint: string; fingerGenPrint: string; fingerGenPrint3: string };
 
-  /** `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;
     this.cookieJar = config?.cookieJar ?? new CookieJar();
     this.rawFetch = limitConcurrency(
-      withTimeout(config?.fetch ?? makeFetch(this.cookieJar), config?.requestTimeout ?? DEFAULT_REQUEST_TIMEOUT),
+      withNetworkError(
+        withTimeout(config?.fetch ?? makeFetch(this.cookieJar), config?.requestTimeout ?? DEFAULT_REQUEST_TIMEOUT),
+      ),
       config?.maxConcurrentRequests ?? DEFAULT_MAX_CONCURRENT_REQUESTS,
     );
   }
@@ -144,71 +177,161 @@ export class Session {
   set csrfToken(token: string) {
     this.#csrfToken = token;
     this.#generation += 1;
+    this.#badCredential = undefined;
   }
 
   /**
-   * 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. Called by `login()`, so it tries again after a `BAD_CREDENTIAL`.
+   */
+  relogin(): Promise<void> {
+    this.#badCredential = undefined;
+    return this.autoRelogin();
+  }
+
+  /**
+   * `relogin` for a login nobody asked for (an expired session, no CSRF token yet, the registrar wanting a new
+   * id.tsinghua.edu.cn session), unless the last provider login was turned down with `BAD_CREDENTIAL`: then reject with
+   * that again
+   */
+  autoRelogin(): Promise<void> {
+    return this.#badCredential
+      ? Promise.reject(this.#badCredential)
+      : (this.#pendingLogin ?? this.runLogin(this.#providerLogin));
+  }
+
+  #providerLogin = async (): Promise<void> => {
+    try {
+      await this.loginWithProvider();
+    } catch (err) {
+      if ((err as ApiError | undefined)?.reason === FailReason.BAD_CREDENTIAL) this.#badCredential = err as ApiError;
+      throw err;
+    }
+  };
+
+  /**
+   * 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.
+   * session) and retries once. After a provider login failed with `BAD_CREDENTIAL` it rejects with that instead, until
+   * the next explicit `login`.
    */
-  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;
+      throw apiError(FailReason.NOT_LOGGED_IN);
     }
     if (this.#generation === generation) {
-      await this.relogin();
+      await this.autoRelogin();
     }
-    const retry = await this.rawFetch(makeUrl(), init);
-    if (noLogin(retry)) {
-      discard(retry);
-      throw { reason: FailReason.NOT_LOGGED_IN } as ApiError;
+    const second = await attempt(true);
+    if (second === EXPIRED) {
+      throw apiError(FailReason.NOT_LOGGED_IN);
     }
-    if (retry.status !== 200) {
-      discard(retry);
-      throw {
-        reason: FailReason.UNEXPECTED_STATUS,
-        extra: { code: retry.status, text: retry.statusText },
-      } as ApiError;
-    }
-    return retry;
+    return second;
   }
 
-  /** fetch with a login check (see `#send`) */
-  readonly fetch: Fetch = (input, init) => this.#send(() => urlOf(input), init);
+  /** 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 apiError(FailReason.UNEXPECTED_STATUS, { code: res.status, text: res.statusText });
+    }
+    return res;
+  };
 
-  /** 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 parsed JSON body (after a re-login only from a response with status 200); the login page with status 200
+   * instead means the session has expired.
+   */
+  static readonly #json = async (res: Response, retry: boolean): Promise<any> => {
+    await Session.#response(res, retry);
+    const text = await res.text();
+    try {
+      return JSON.parse(text);
+    } catch {
+      if (res.status === 200 && looksLikeLoginPage(text)) return EXPIRED;
+      throw apiError(res.status === 200 ? FailReason.INVALID_RESPONSE : FailReason.UNEXPECTED_STATUS, {
+        code: res.status,
+        text: text.slice(0, 200),
+      });
+    }
+  };
+
+  /** 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();
+      await this.autoRelogin();
     }
     const url = urlOf(input);
-    return this.#send(() => addCSRFTokenToUrl(url, this.#csrfToken), init);
+    return () => addCSRFTokenToUrl(url, this.#csrfToken);
   };
 
+  /** fetch with a login check (see `#send`); logs in first if there is no CSRF token yet and adds it 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. The short login page with status 200 instead of JSON
+   * counts as an expired session (log in again and retry once, as for a 403); any other page is `INVALID_RESPONSE`.
+   */
+  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();
+      await this.autoRelogin();
       return;
     }
-    discard(await this.fetchWithToken(probeUrl));
+    const json = await this.fetchJsonWithToken(probeUrl);
+    if (json?.message !== 'success') {
+      throw apiError(FailReason.INVALID_RESPONSE, json);
+    }
   }
 }

package/src/timetable.ts

@@ -0,0 +1,121 @@
+// Reading a course's time and location (`Course.timeAndLocation`) and counting teaching weeks, for working out a
+// timetable without the registrar's calendar.
+
+import type { CourseMeeting } from './types.ts';
+
+/**
+ * The start and end (Beijing time, HH:mm) of each class period (大节), which is what a course's time and location
+ * counts in.
+ */
+export const CLASS_PERIOD_TIMES: Readonly<Record<number, readonly [string, string]>> = {
+  1: ['08:00', '09:35'],
+  2: ['09:50', '12:15'],
+  3: ['13:30', '15:05'],
+  4: ['15:20', '16:55'],
+  5: ['17:05', '18:40'],
+  6: ['19:20', '21:45'],
+};
+
+/** weeks in a regular term, for "every other week", "last eight weeks" and the like */
+const TERM_WEEKS = 16;
+
+const range = (from: number, to: number, step = 1): number[] => {
+  const weeks: number[] = [];
+  for (let w = from; w <= to; w += step) weeks.push(w);
+  return weeks;
+};
+
+const WEEKDAYS: Record<string, number> = { 一: 1, 二: 2, 三: 3, 四: 4, 五: 5, 六: 6, 日: 7, 天: 7 };
+
+/** English weekdays by their first three letters (the server writes `Mon`, `Tues`, `Thur`, …) */
+const ENGLISH_WEEKDAYS: Record<string, number> = { mon: 1, tue: 2, wed: 3, thu: 4, fri: 5, sat: 6, sun: 7 };
+
+/** week specs that aren't a list of weeks, in Chinese and in English (spaces removed, lower case) */
+const NAMED_WEEKS: Record<string, () => number[] | null> = {
+  全周: () => null,
+  all: () => null,
+  every: () => null,
+  full: () => null,
+  前八周: () => range(1, 8),
+  first8: () => range(1, 8),
+  firsteight: () => range(1, 8),
+  后八周: () => range(9, TERM_WEEKS),
+  last8: () => range(9, TERM_WEEKS),
+  lasteight: () => range(9, TERM_WEEKS),
+  单周: () => range(1, TERM_WEEKS, 2),
+  odd: () => range(1, TERM_WEEKS, 2),
+  双周: () => range(2, TERM_WEEKS, 2),
+  even: () => range(2, TERM_WEEKS, 2),
+};
+
+/**
+ * The teaching weeks a meeting happens in, from the part of its time and location in parentheses: `全周`, `1-8周`,
+ * `9,11周`, `单周`, or in English `Week all`, `Week 1-8`, `Odd weeks`. `null` means every week, also for text it
+ * doesn't know.
+ */
+export function parseWeeks(text: string): number[] | null {
+  const spec = text
+    .replace(/\s/g, '')
+    .toLowerCase()
+    .replace(/^(?:第|weeks?|wks?)/, '')
+    .replace(/(?:周|weeks?|wks?)$/, '');
+  const named = NAMED_WEEKS[spec] ?? NAMED_WEEKS[`${spec}周`];
+  if (named) return named();
+  const weeks: number[] = [];
+  for (const part of spec.split(/[,，、;；]/)) {
+    const match = /^(\d+)(?:[-~～–—](\d+))?$/.exec(part);
+    if (!match) return null;
+    const from = Number(match[1]);
+    weeks.push(...range(from, match[2] ? Number(match[2]) : from));
+  }
+  return weeks;
+}
+
+const toMeeting = (weekday: number | undefined, period: number, weeks: string, location: string) =>
+  weekday && CLASS_PERIOD_TIMES[period]
+    ? { weekday, period, weeks: parseWeeks(weeks), location: location.trim() }
+    : null;
+
+/**
+ * Read one entry of a course's time and location (`Course.timeAndLocation`): `星期六第1节(9,11周)，六教6A414`, or
+ * `Section 1 of Sat (Week 9,11 ), 六教6A414` when the website is in English. Entries without a day or a known period
+ * (`星期第0节(全周)，`, `Section 0  (Week all ), `) give `null`.
+ */
+export function parseCourseMeeting(text: string): CourseMeeting | null {
+  const chinese = /星期([一二三四五六日天])第(\d+)节\s*[(（]([^)）]*)[)）]\s*[，,]?\s*(.*)$/.exec(text);
+  if (chinese) return toMeeting(WEEKDAYS[chinese[1]], Number(chinese[2]), chinese[3], chinese[4]);
+  const english = /section\s*(\d+)\s*(?:of\s*([a-z]+)\.?)?\s*[(（]([^)）]*)[)）]\s*[，,]?\s*(.*)$/i.exec(text);
+  if (english) {
+    const day = english[2]?.slice(0, 3).toLowerCase();
+    return toMeeting(day ? ENGLISH_WEEKDAYS[day] : undefined, Number(english[1]), english[3], english[4]);
+  }
+  return null;
+}
+
+const DAY_MS = 24 * 60 * 60 * 1000;
+
+/** a YYYY-MM-DD date (anything after it, like a time, is ignored) as days since the epoch */
+const dayNumber = (date: string): number => {
+  const match = /^(\d{4})-(\d{2})-(\d{2})/.exec(date);
+  const time = match ? Date.UTC(Number(match[1]), Number(match[2]) - 1, Number(match[3])) : NaN;
+  if (Number.isNaN(time) || new Date(time).toISOString().slice(0, 10) !== date.slice(0, 10)) {
+    throw new RangeError(`invalid date ${date}, expected YYYY-MM-DD`);
+  }
+  return time / DAY_MS;
+};
+
+/** days since the epoch of the Monday of the week of `day` (days since the epoch; day 0 was a Thursday) */
+const mondayOf = (day: number) => day - ((day + 3) % 7);
+
+/**
+ * The teaching week `date` falls in, from 1 (0 or less before the term), for a term whose first day
+ * (`SemesterInfo.startDate`) is `semesterStartDate`. Both are YYYY-MM-DD Beijing dates. Week 1 starts on the Monday
+ * of the first day, or on the Monday after it when the first day is a weekend (fall 2026 starts on Saturday Sep 12;
+ * week 1 is Sep 14–20). Throws a `RangeError` for a date that isn't YYYY-MM-DD.
+ */
+export function semesterWeek(semesterStartDate: string, date: string): number {
+  const start = dayNumber(semesterStartDate);
+  const weekday = (start + 3) % 7; // 0 Monday … 6 Sunday
+  const firstMonday = weekday >= 5 ? start + 7 - weekday : start - weekday;
+  return (mondayOf(dayNumber(date)) - firstMonday) / 7 + 1;
+}