@robertying/thu-learn-lib 5.1.0 → 6.0.0

package/src/notices.ts

@@ -3,11 +3,19 @@
 import { Base64 } from 'js-base64';
 
 import type { Session } from './request.ts';
-import { $, YES } from './request.ts';
-import type { INotification, Notification, NotificationListOptions, RemoteFile } from './types.ts';
+import type { CourseNotification, CourseNotificationBase, NotificationListOptions, RemoteFile } from './types.ts';
 import { ContentType, CourseType, FailReason } from './types.ts';
 import * as URLS from './urls.ts';
-import { decodeHTML, isSelected, trimAndDefine } from './utils.ts';
+import {
+  $,
+  YES,
+  decodeHTML,
+  expectSuccess,
+  isSelected,
+  toRequiredServerTime,
+  toServerTime,
+  trimAndDefine,
+} from './utils.ts';
 
 /**
  * Get all notifications （课程公告） of the specified course: current and expired lists.
@@ -18,13 +26,13 @@ export async function getNotificationList(
   courseID: string,
   courseType: CourseType = CourseType.STUDENT,
   options: NotificationListOptions = {},
-): Promise<Notification[]> {
+): Promise<CourseNotification[]> {
   const lists = await Promise.all([
     getNotificationListKind(s, courseID, courseType, false),
     getNotificationListKind(s, courseID, courseType, true),
   ]);
   return Promise.all(
-    lists.flat().map(async (n): Promise<Notification> => {
+    lists.flat().map(async (n): Promise<CourseNotification> => {
       if (!n.attachmentName || !isSelected(options.attachments, n)) return n;
       return { ...n, attachment: await getNotificationAttachment(s, n, courseType) };
     }),
@@ -36,17 +44,12 @@ async function getNotificationListKind(
   courseID: string,
   courseType: CourseType,
   expired: boolean,
-): Promise<INotification[]> {
+): Promise<CourseNotificationBase[]> {
   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,
-      extra: json,
-    });
-  }
+  expectSuccess(json, FailReason.INVALID_RESPONSE);
 
   const result = (json.object?.aaData ?? json.object?.resultsList ?? []) as any[];
 
@@ -60,12 +63,12 @@ async function getNotificationListKind(
       publisher: n.fbrxm,
       hasRead: n.sfyd === YES,
       markedImportant: Number(n.sfqd) === 1, // n.sfqd could be string '1' (teacher mode) or number 1 (student mode)
-      publishTime: n.fbsj && typeof n.fbsj === 'string' ? n.fbsj : n.fbsjStr,
-      expireTime: n.jzsj ?? undefined,
+      publishTime: toRequiredServerTime(n.fbsj && typeof n.fbsj === 'string' ? n.fbsj : n.fbsjStr),
+      expireTime: toServerTime(n.jzsj),
       isFavorite: n.sfsc === YES,
       comment: n.bznr ?? undefined,
       attachmentName: typeof attachmentName === 'string' && attachmentName ? attachmentName : undefined,
-    } satisfies INotification;
+    } satisfies CourseNotificationBase;
   });
 }
 
@@ -75,20 +78,10 @@ async function getNotificationListKind(
  */
 export async function getNotificationAttachment(
   s: Session,
-  notification: Pick<INotification, 'url' | 'attachmentName'>,
+  notification: Pick<CourseNotificationBase, 'url' | 'attachmentName'>,
   courseType: CourseType = CourseType.STUDENT,
 ): Promise<RemoteFile | undefined> {
   if (!notification.attachmentName) return undefined;
-  /// from JSON (backup, currently not used)
-  // const postParams = new FormData();
-  // postParams.append('id', id);
-  // postParams.append('wlkcid', courseID);
-  // const metadata = await s.fetchJsonWithToken(URL.LEARN_NOTIFICATION_EDIT(courseType), {
-  //   'method': 'POST',
-  //   'body': postParams,
-  // });
-  // const attachmentId = metadata.ggfjid as string;
-  /// parsed from HTML
   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)

package/src/questionnaires.ts

@@ -1,11 +1,19 @@
 // Questionnaires (课程问卷).
 
 import type { Session } from './request.ts';
-import { YES } from './request.ts';
-import type { ApiError, Questionnaire, QuestionnaireDetail, QuestionnaireListOptions } from './types.ts';
+import type { Questionnaire, QuestionnaireDetail, QuestionnaireListOptions } from './types.ts';
 import { FailReason, QuestionnaireType } from './types.ts';
 import * as URLS from './urls.ts';
-import { QNR_TYPE_MAP, decodeHTML, isSelected } from './utils.ts';
+import {
+  QNR_TYPE_MAP,
+  YES,
+  apiError,
+  decodeHTML,
+  expectSuccess,
+  isSelected,
+  toRequiredServerTime,
+  toServerTime,
+} from './utils.ts';
 
 /**
  * Get all questionnaires （课程问卷/QNR） of the specified course: ongoing and ended lists.
@@ -32,12 +40,7 @@ export async function getQuestionnaireList(
 
 async function getQuestionnaireListAtUrl(s: Session, courseID: string, url: string): Promise<Questionnaire[]> {
   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,
-      extra: json,
-    });
-  }
+  expectSuccess(json, FailReason.INVALID_RESPONSE);
   const result = (json.object?.aaData ?? []) as any[];
   return result.map((e) => {
     const type = QNR_TYPE_MAP.get(e.wjlx) ?? QuestionnaireType.SURVEY;
@@ -45,12 +48,12 @@ async function getQuestionnaireListAtUrl(s: Session, courseID: string, url: stri
       id: e.wjid,
       type,
       title: decodeHTML(e.wjbt),
-      startTime: e.kssj,
-      endTime: e.jssj,
-      uploadTime: e.scsj,
+      startTime: toRequiredServerTime(e.kssj),
+      endTime: toRequiredServerTime(e.jssj),
+      uploadTime: toRequiredServerTime(e.scsj),
       uploaderId: e.scr,
       uploaderName: e.scrxm,
-      submitTime: e.tjsj ? e.tjsj : undefined,
+      submitTime: toServerTime(e.tjsj),
       isFavorite: e.sfsc === YES,
       comment: e.bznr ?? undefined,
       url: URLS.LEARN_QNR_SUBMIT_PAGE(e.wlkcid, e.wjid, type),
@@ -69,7 +72,7 @@ export async function getQuestionnaireDetail(
     body: URLS.LEARN_QNR_DETAIL_FORM(courseID, qnrID),
   });
   if (!Array.isArray(json)) {
-    throw { reason: FailReason.INVALID_RESPONSE, extra: json } as ApiError;
+    throw apiError(FailReason.INVALID_RESPONSE, json);
   }
   return json.map(
     (e) =>
@@ -79,7 +82,7 @@ export async function getQuestionnaireDetail(
         type: e.type,
         required: e.require === YES,
         title: decodeHTML(e.wtbt),
-        score: e.wtfz ? Number(e.wtfz) : undefined, // unsure about original type
+        score: e.wtfz ? Number(e.wtfz) : undefined, // a number or a string of digits; none when missing or 0
         options: (e.list as any[])?.map((o) => ({
           id: o.xxid,
           index: Number(o.xxbh),

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,9 +24,6 @@ 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.
@@ -100,10 +88,7 @@ export function withTimeout(inner: Fetch, ms: number): TimedFetch {
     } catch (err) {
       outer?.removeEventListener('abort', forward);
       if (timedOut) {
-        throw {
-          reason: FailReason.REQUEST_TIMEOUT,
-          extra: { url: urlOf(input), timeout },
-        } as ApiError;
+        throw apiError(FailReason.REQUEST_TIMEOUT, { url: urlOf(input), timeout });
       }
       throw err;
     } finally {
@@ -112,31 +97,36 @@ export function withTimeout(inner: Fetch, ms: number): TimedFetch {
   };
 }
 
+/**
+ * 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');
 
-/**
- * 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.
@@ -150,8 +140,19 @@ export class Session {
   /** 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 };
 
   /** `loginWithProvider` signs in through SSO with the `CredentialProvider` */
   constructor(
@@ -162,7 +163,9 @@ export class Session {
     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,
     );
   }
@@ -174,6 +177,7 @@ export class Session {
   set csrfToken(token: string) {
     this.#csrfToken = token;
     this.#generation += 1;
+    this.#badCredential = undefined;
   }
 
   /**
@@ -192,18 +196,40 @@ export class Session {
 
   /**
    * Log in with the `CredentialProvider`, or wait for the login already in progress (also one with explicit
-   * credentials) instead of starting another.
+   * credentials) instead of starting another. Called by `login()`, so it tries again after a `BAD_CREDENTIAL`.
    */
   relogin(): Promise<void> {
-    return this.#pendingLogin ?? this.runLogin(this.loginWithProvider);
+    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<T>(
     makeUrl: () => string,
@@ -222,14 +248,14 @@ export class Session {
     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 second = await attempt(true);
     if (second === EXPIRED) {
-      throw { reason: FailReason.NOT_LOGGED_IN } as ApiError;
+      throw apiError(FailReason.NOT_LOGGED_IN);
     }
     return second;
   }
@@ -238,25 +264,26 @@ export class Session {
   static readonly #response = async (res: Response, retry: boolean): Promise<Response> => {
     if (retry && res.status !== 200) {
       discard(res);
-      throw {
-        reason: FailReason.UNEXPECTED_STATUS,
-        extra: { code: res.status, text: res.statusText },
-      } as ApiError;
+      throw apiError(FailReason.UNEXPECTED_STATUS, { code: res.status, text: res.statusText });
     }
     return res;
   };
 
-  /** the parsed JSON body; an HTML page with status 200 means the session has expired */
-  static readonly #json = async (res: Response): Promise<any> => {
+  /**
+   * 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 && 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;
+      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),
+      });
     }
   };
 
@@ -269,22 +296,19 @@ export class Session {
 
   #withToken = async (input: Parameters<Fetch>[0]): Promise<() => string> => {
     if (this.#csrfToken === '') {
-      await this.relogin();
+      await this.autoRelogin();
     }
     const url = urlOf(input);
     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 */
+  /** 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);
 
   /**
-   * 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).
+   * 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);
@@ -302,12 +326,12 @@ export class Session {
    */
   async ensureSession(probeUrl: string): Promise<void> {
     if (this.#csrfToken === '') {
-      await this.relogin();
+      await this.autoRelogin();
       return;
     }
     const json = await this.fetchJsonWithToken(probeUrl);
     if (json?.message !== 'success') {
-      throw { reason: FailReason.INVALID_RESPONSE, extra: json } as ApiError;
+      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;
+}