@robertying/thu-learn-lib 4.1.0 → 5.1.0

package/src/notices.ts

@@ -4,21 +4,31 @@ import { Base64 } from 'js-base64';
 
 import type { Session } from './request.ts';
 import { $, YES } from './request.ts';
-import type { INotification, INotificationDetail, Notification } from './types.ts';
+import type { INotification, Notification, NotificationListOptions, RemoteFile } from './types.ts';
 import { ContentType, CourseType, FailReason } from './types.ts';
 import * as URLS from './urls.ts';
-import { decodeHTML, trimAndDefine } from './utils.ts';
+import { decodeHTML, isSelected, trimAndDefine } from './utils.ts';
 
-/** Get all notifications （课程公告） of the specified course. */
+/**
+ * Get all notifications （课程公告） of the specified course: current and expired lists.
+ * Attachments only for the notices `options.attachments` selects.
+ */
 export async function getNotificationList(
   s: Session,
   courseID: string,
   courseType: CourseType = CourseType.STUDENT,
+  options: NotificationListOptions = {},
 ): Promise<Notification[]> {
-  return Promise.all([
+  const lists = await Promise.all([
     getNotificationListKind(s, courseID, courseType, false),
     getNotificationListKind(s, courseID, courseType, true),
-  ]).then((r) => r.flat());
+  ]);
+  return Promise.all(
+    lists.flat().map(async (n): Promise<Notification> => {
+      if (!n.attachmentName || !isSelected(options.attachments, n)) return n;
+      return { ...n, attachment: await getNotificationAttachment(s, n, courseType) };
+    }),
+  );
 }
 
 async function getNotificationListKind(
@@ -26,13 +36,11 @@ async function getNotificationListKind(
   courseID: string,
   courseType: CourseType,
   expired: boolean,
-): Promise<Notification[]> {
-  const json = await (
-    await s.fetchWithToken(URLS.LEARN_NOTIFICATION_LIST(courseType, expired), {
-      method: 'POST',
-      body: URLS.LEARN_PAGE_LIST_FORM_DATA(courseID),
-    })
-  ).json();
+): Promise<INotification[]> {
+  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,
@@ -42,69 +50,60 @@ async function getNotificationListKind(
 
   const result = (json.object?.aaData ?? json.object?.resultsList ?? []) as any[];
 
-  return Promise.all(
-    result.map(async (n) => {
-      const notification: INotification = {
-        id: n.ggid,
-        content: Base64.decode(n.ggnr ?? ''),
-        title: decodeHTML(n.bt),
-        url: URLS.LEARN_NOTIFICATION_DETAIL(courseID, n.ggid, courseType),
-        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,
-        isFavorite: n.sfsc === YES,
-        comment: n.bznr ?? undefined,
-      };
-      let detail: INotificationDetail = {};
-      const attachmentName = courseType === CourseType.STUDENT ? n.fjmc : n.fjbt;
-      if (attachmentName) {
-        detail = await parseNotificationDetail(s, courseID, notification.id, courseType, attachmentName);
-      }
-      return { ...notification, ...detail } satisfies Notification;
-    }),
-  );
+  return result.map((n) => {
+    const attachmentName: unknown = courseType === CourseType.STUDENT ? n.fjmc : n.fjbt;
+    return {
+      id: n.ggid,
+      content: Base64.decode(n.ggnr ?? ''),
+      title: decodeHTML(n.bt),
+      url: URLS.LEARN_NOTIFICATION_DETAIL(courseID, n.ggid, courseType),
+      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,
+      isFavorite: n.sfsc === YES,
+      comment: n.bznr ?? undefined,
+      attachmentName: typeof attachmentName === 'string' && attachmentName ? attachmentName : undefined,
+    } satisfies INotification;
+  });
 }
 
-async function parseNotificationDetail(
+/**
+ * Get the attachment of a notice from its detail page (1 request), or `undefined` without a request if
+ * `attachmentName` says it has none, or if the page has no attachment link.
+ */
+export async function getNotificationAttachment(
   s: Session,
-  courseID: string,
-  id: string,
-  courseType: CourseType,
-  attachmentName: string,
-): Promise<INotificationDetail> {
+  notification: Pick<INotification, '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 (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(URLS.LEARN_NOTIFICATION_DETAIL(courseID, id, courseType));
-  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)) {
     path = URLS.LEARN_PREFIX + path;
   }
   return {
-    attachment: {
-      name: attachmentName,
-      id: attachmentId,
-      downloadUrl: path,
-      previewUrl: URLS.LEARN_FILE_PREVIEW(ContentType.NOTIFICATION, attachmentId, courseType, s.previewFirstPage),
-      size,
-    },
+    name: notification.attachmentName,
+    id: attachmentId,
+    downloadUrl: path,
+    previewUrl: URLS.LEARN_FILE_PREVIEW(ContentType.NOTIFICATION, attachmentId, courseType, s.previewFirstPage),
+    size,
   };
 }

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

@@ -4,7 +4,7 @@ import fetchCookie from 'fetch-cookie';
 import { fetch } from 'node-fetch-native';
 import { CookieJar } from 'tough-cookie';
 
-import type { CredentialProvider, Fetch, HelperConfig } from './types.ts';
+import type { ApiError, CredentialProvider, Fetch, HelperConfig } from './types.ts';
 import { FailReason, Language } from './types.ts';
 
 const CHEERIO_CONFIG: cheerio.CheerioOptions = { xml: true };
@@ -17,6 +17,11 @@ export const noLogin = (res: Response) => res.url.includes('login_timeout') || r
 
 export const YES = '是';
 
+/** default for `HelperConfig.maxConcurrentRequests` */
+export const DEFAULT_MAX_CONCURRENT_REQUESTS = 6;
+/** default for `HelperConfig.requestTimeout`, in milliseconds */
+export const DEFAULT_REQUEST_TIMEOUT = 60_000;
+
 /** add CSRF token to any request URL as parameters */
 export const addCSRFTokenToUrl = (url: string, token: string): string => {
   const newUrl = new URL(url);
@@ -28,32 +33,110 @@ function makeFetch(jar?: CookieJar): typeof fetch {
   return fetchCookie(fetch, jar);
 }
 
-function withReAuth(rawFetch: Fetch, login: () => Promise<void>): Fetch {
-  return async function wrappedFetch(...args) {
-    const retryAfterLogin = async () => {
-      await login();
-      return await rawFetch(...args).then((res: Response) => {
-        if (noLogin(res)) {
-          return Promise.reject({
-            reason: FailReason.NOT_LOGGED_IN,
-          });
-        } else if (res.status !== 200) {
-          return Promise.reject({
-            reason: FailReason.UNEXPECTED_STATUS,
-            extra: {
-              code: res.status,
-              text: res.statusText,
-            },
-          });
-        } else {
-          return res;
-        }
-      });
-    };
-    return await rawFetch(...args).then((res: Response) => (noLogin(res) ? retryAfterLogin() : res));
+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<F extends (...args: any[]) => Promise<Response>>(inner: F, max: number): F {
+  if (!(max >= 1) || max === Infinity) return inner;
+  let active = 0;
+  const waiting: (() => void)[] = [];
+  const acquire = (): Promise<void> => {
+    if (active < max) {
+      active += 1;
+      return Promise.resolve();
+    }
+    return new Promise((resolve) => waiting.push(resolve));
+  };
+  const release = () => {
+    const next = waiting.shift();
+    // hand the slot straight to the next caller, so `active` stays the same
+    if (next) next();
+    else active -= 1;
+  };
+  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 (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): 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 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();
+    }, 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 },
+        } as ApiError;
+      }
+      throw err;
+    } finally {
+      clearTimeout(timer);
+    }
   };
 }
 
+/** free the connection of a response we won't read */
+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.
@@ -61,41 +144,170 @@ function withReAuth(rawFetch: Fetch, login: () => Promise<void>): Fetch {
 export class Session {
   readonly provider?: CredentialProvider;
   readonly cookieJar: CookieJar;
-  /** plain fetch with cookies, no login check */
-  readonly rawFetch: Fetch;
-  /** rejects with `NOT_LOGGED_IN`, or logs in again and retries once when a `CredentialProvider` is set */
-  readonly fetch: Fetch;
-  csrfToken = '';
+  /** fetch with cookies, the concurrency cap and the timeout, but no login check */
+  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>;
   lang = Language.ZH;
   previewFirstPage: boolean;
 
-  /** `login` is called with no arguments when a request needs a (new) session */
+  /** `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 = config?.fetch ?? makeFetch(this.cookieJar);
-    this.fetch = this.provider
-      ? withReAuth(this.rawFetch, login)
-      : async (...args) => {
-          const result = await this.rawFetch(...args);
-          if (noLogin(result))
-            return Promise.reject({
-              reason: FailReason.NOT_LOGGED_IN,
-            });
-          return result;
-        };
+    this.rawFetch = limitConcurrency(
+      withTimeout(config?.fetch ?? makeFetch(this.cookieJar), config?.requestTimeout ?? DEFAULT_REQUEST_TIMEOUT),
+      config?.maxConcurrentRequests ?? DEFAULT_MAX_CONCURRENT_REQUESTS,
+    );
+  }
+
+  get csrfToken(): string {
+    return this.#csrfToken;
   }
 
-  /** like `fetch`, but logs in first if there is no CSRF token yet and adds the token to the URL */
-  readonly fetchWithToken: Fetch = async (...args) => {
-    if (this.csrfToken === '') {
-      await this.login();
+  set csrfToken(token: string) {
+    this.#csrfToken = token;
+    this.#generation += 1;
+  }
+
+  /**
+   * 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).
+   */
+  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;
+    });
+    this.#pendingLogin = current;
+    return current;
+  }
+
+  /**
+   * 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<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 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 second = await attempt(true);
+    if (second === EXPIRED) {
+      throw { reason: FailReason.NOT_LOGGED_IN } as ApiError;
+    }
+    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: res.status, text: res.statusText },
+      } as ApiError;
+    }
+    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> => {
+    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;
     }
-    const [url, ...remaining] = args;
-    return this.fetch(addCSRFTokenToUrl(url as string, this.csrfToken), ...remaining);
   };
+
+  /** 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 () => 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);
+
+  /**
+   * 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;
+    }
+    const json = await this.fetchJsonWithToken(probeUrl);
+    if (json?.message !== 'success') {
+      throw { reason: FailReason.INVALID_RESPONSE, extra: json } as ApiError;
+    }
+  }
 }