@robertying/thu-learn-lib 0.0.0-stage → 5.0.0

package/src/request.ts

@@ -0,0 +1,214 @@
+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);
+};
+
+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 */
+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);
+  newUrl.searchParams.set('_csrf', token);
+  return newUrl.toString();
+};
+
+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 {
+  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) => {
+    await acquire();
+    try {
+      return await inner(...args);
+    } finally {
+      release();
+    }
+  };
+}
+
+/**
+ * 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`).
+ */
+export function withTimeout(inner: Fetch, ms: number): Fetch {
+  if (!(ms > 0) || ms === Infinity) return inner;
+  return async (input, init) => {
+    const controller = new AbortController();
+    const outer = init?.signal ?? undefined;
+    const forward = () => controller.abort(outer?.reason);
+    if (outer?.aborted) forward();
+    else outer?.addEventListener('abort', forward, { once: true });
+    let timedOut = false;
+    const timer = setTimeout(() => {
+      timedOut = true;
+      controller.abort();
+    }, ms);
+    try {
+      return await inner(input, { ...init, signal: controller.signal });
+    } catch (err) {
+      if (timedOut) {
+        throw {
+          reason: FailReason.REQUEST_TIMEOUT,
+          extra: { url: urlOf(input), timeout: ms },
+        } as ApiError;
+      }
+      throw err;
+    } finally {
+      clearTimeout(timer);
+      outer?.removeEventListener('abort', forward);
+    }
+  };
+}
+
+/** free the connection of a response we won't read */
+const discard = (res: Response) => {
+  res.body?.cancel().catch(() => {});
+};
+
+/**
+ * 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.
+ */
+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;
+  #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` signs in through SSO with the `CredentialProvider`; the session calls it at most once at a time */
+  constructor(
+    config: HelperConfig | undefined,
+    readonly login: () => 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),
+      config?.maxConcurrentRequests ?? DEFAULT_MAX_CONCURRENT_REQUESTS,
+    );
+  }
+
+  get csrfToken(): string {
+    return this.#csrfToken;
+  }
+
+  set csrfToken(token: string) {
+    this.#csrfToken = token;
+    this.#generation += 1;
+  }
+
+  /**
+   * Log in with the `CredentialProvider`. Concurrent callers share one SSO login instead of starting one each.
+   */
+  relogin(): Promise<void> {
+    this.#pendingLogin ??= this.login().finally(() => {
+      this.#pendingLogin = undefined;
+    });
+    return this.#pendingLogin;
+  }
+
+  /**
+   * Send a request built by `makeUrl` (called again for the retry, so it can pick up a new CSRF token).
+   * 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> {
+    const generation = this.#generation;
+    const res = await this.rawFetch(makeUrl(), init);
+    if (!noLogin(res)) return res;
+    discard(res);
+    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);
+      throw { reason: FailReason.NOT_LOGGED_IN } as ApiError;
+    }
+    if (retry.status !== 200) {
+      discard(retry);
+      throw {
+        reason: FailReason.UNEXPECTED_STATUS,
+        extra: { code: retry.status, text: retry.statusText },
+      } as ApiError;
+    }
+    return retry;
+  }
+
+  /** fetch with a login check (see `#send`) */
+  readonly fetch: Fetch = (input, init) => this.#send(() => urlOf(input), init);
+
+  /** 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) => {
+    if (this.#csrfToken === '') {
+      await this.relogin();
+    }
+    const url = urlOf(input);
+    return this.#send(() => addCSRFTokenToUrl(url, this.#csrfToken), init);
+  };
+
+  /**
+   * 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.
+   */
+  async ensureSession(probeUrl: string): Promise<void> {
+    if (this.#csrfToken === '') {
+      await this.relogin();
+      return;
+    }
+    discard(await this.fetchWithToken(probeUrl));
+  }
+}

package/src/types.ts

@@ -0,0 +1,494 @@
+import type { CookieJar } from 'tough-cookie';
+
+export type Fetch = typeof globalThis.fetch;
+export type Credential = {
+  username?: string;
+  password?: string;
+  fingerPrint?: string;
+  fingerGenPrint?: string;
+  fingerGenPrint3?: string;
+};
+export type CredentialProvider = () => Credential | Promise<Credential>;
+export type HelperConfig = {
+  provider?: CredentialProvider;
+  fetch?: Fetch;
+  cookieJar?: CookieJar;
+  generatePreviewUrlForFirstPage?: boolean;
+  /** at most this many requests in flight at once, including login (default 6; `Infinity` for no limit) */
+  maxConcurrentRequests?: number;
+  /** milliseconds to wait for a response before rejecting with `FailReason.REQUEST_TIMEOUT` (default 60000; 0 for none) */
+  requestTimeout?: number;
+};
+
+export enum FailReason {
+  NO_CREDENTIAL = 'no credential provided',
+  ERROR_FETCH_FROM_ID = 'could not fetch ticket from id.tsinghua.edu.cn',
+  BAD_CREDENTIAL = 'bad credential',
+  ERROR_ROAMING = 'could not roam to learn.tsinghua.edu.cn',
+  NOT_LOGGED_IN = 'not logged in or login timeout',
+  NOT_IMPLEMENTED = 'not implemented',
+  INVALID_RESPONSE = 'invalid response',
+  UNEXPECTED_STATUS = 'unexpected status',
+  OPERATION_FAILED = 'operation failed',
+  ERROR_SETTING_COOKIES = 'could not set cookies',
+  REQUEST_TIMEOUT = 'request timed out',
+}
+
+export interface ApiError {
+  reason: FailReason;
+  extra?: unknown;
+}
+
+export enum SemesterType {
+  FALL = 'fall',
+  SPRING = 'spring',
+  SUMMER = 'summer',
+  UNKNOWN = '',
+}
+
+export enum ContentType {
+  NOTIFICATION = 'notification',
+  FILE = 'file',
+  HOMEWORK = 'homework',
+  DISCUSSION = 'discussion',
+  QUESTION = 'question',
+  QUESTIONNAIRE = 'questionnaire',
+}
+
+interface IUserInfo {
+  name: string;
+  department: string;
+}
+
+export type UserInfo = IUserInfo;
+
+interface ISemesterInfo {
+  id: string;
+  startDate: string;
+  endDate: string;
+  startYear: number;
+  endYear: number;
+  type: SemesterType;
+}
+
+export type SemesterInfo = ISemesterInfo;
+
+export enum CourseType {
+  STUDENT = 'student',
+  TEACHER = 'teacher',
+}
+
+interface ICourseInfo {
+  id: string;
+  name: string;
+  chineseName: string;
+  englishName: string;
+  /** only with `getCourseList(..., { timeAndLocation: true })`; see `getCourseTimeAndLocation` */
+  timeAndLocation?: string[];
+  url: string;
+  teacherName: string;
+  teacherNumber: string;
+  courseNumber: string;
+  courseIndex: number;
+  courseType: CourseType;
+}
+
+export type CourseInfo = ICourseInfo;
+
+interface IRemoteFile {
+  id: string;
+  name: string;
+  downloadUrl: string;
+  previewUrl: string;
+  size: string;
+}
+
+export type RemoteFile = IRemoteFile;
+
+export interface INotification {
+  id: string;
+  title: string;
+  content: string;
+  hasRead: boolean;
+  url: string;
+  markedImportant: boolean;
+  publishTime: string;
+  publisher: string;
+  expireTime?: string;
+  isFavorite: boolean;
+  comment?: string;
+  /** name of the attachment, if the notice has one; fetch it with `getNotificationAttachment` */
+  attachmentName?: string;
+}
+
+export interface INotificationDetail {
+  attachment?: RemoteFile;
+}
+
+export type Notification = INotification & INotificationDetail;
+
+interface IFileCategory {
+  id: string;
+  title: string;
+  creationTime: Date;
+}
+
+export type FileCategory = IFileCategory;
+
+interface IFile {
+  /** previously `id2` */
+  id: string;
+  /** previously `id` */
+  fileId: string;
+  /** note: will be unset when calling `getFileListByCategory` */
+  category?: FileCategory;
+  /** size in byte */
+  rawSize: number;
+  /** inaccurate size description (like '1M') */
+  size: string;
+  title: string;
+  description: string;
+  uploadTime: string;
+  publishTime: string;
+  downloadUrl: string;
+  /** preview is not supported on all types of files, check before use */
+  previewUrl: string;
+  isNew: boolean;
+  markedImportant: boolean;
+  visitCount: number;
+  downloadCount: number;
+  fileType: string;
+  /** for compatibility */
+  remoteFile: RemoteFile;
+  /** could not get favorite or comment info when using `getFileList` or in TA mode */
+  isFavorite?: boolean;
+  comment?: string;
+}
+
+export type File = IFile;
+
+export interface IHomeworkStatus {
+  submitted: boolean;
+  graded: boolean;
+}
+
+export enum HomeworkGradeLevel {
+  /** 已阅 */
+  CHECKED = 'checked',
+  A_PLUS = 'A+',
+  A = 'A',
+  A_MINUS = 'A-',
+  B_PLUS = 'B+',
+  /** 优秀 */
+  DISTINCTION = 'distinction',
+  B = 'B',
+  B_MINUS = 'B-',
+  C_PLUS = 'C+',
+  C = 'C',
+  C_MINUS = 'C-',
+  G = 'G',
+  D_PLUS = 'D+',
+  D = 'D',
+  /** 免课 */
+  EXEMPTED_COURSE = 'exempted course',
+  P = 'P',
+  EX = 'EX',
+  /** 免修 */
+  EXEMPTION = 'exemption',
+  /** 通过 */
+  PASS = 'pass',
+  /** 不通过 */
+  FAILURE = 'failure',
+  W = 'W',
+  I = 'I',
+  /** 缓考 */
+  INCOMPLETE = 'incomplete',
+  NA = 'NA',
+  F = 'F',
+}
+
+export interface IHomework extends IHomeworkStatus {
+  id: string;
+  /** @deprecated use `id` */
+  studentHomeworkId: string;
+  baseId: string;
+  title: string;
+  deadline: string;
+  lateSubmissionDeadline?: string;
+  url: string;
+  completionType: HomeworkCompletionType;
+  submissionType: HomeworkSubmissionType;
+  submitUrl: string;
+  submitTime?: string;
+  isLateSubmission: boolean;
+  grade?: number;
+  /** some homework has levels but not grades, like A/B/.../F */
+  gradeLevel?: HomeworkGradeLevel;
+  gradeTime?: string;
+  graderName?: string;
+  gradeContent?: string;
+  isFavorite: boolean;
+  favoriteTime?: string;
+  comment?: string;
+  excellentHomeworkList?: ExcellentHomework[];
+}
+
+export interface IHomeworkDetail {
+  description?: string;
+  /** attachment from teacher */
+  attachment?: RemoteFile;
+  /** answer from teacher */
+  answerContent?: string;
+  answerAttachment?: RemoteFile;
+  /** submitted content from student */
+  submittedContent?: string;
+  submittedAttachment?: RemoteFile;
+  /** grade from teacher */
+  gradeAttachment?: RemoteFile;
+}
+
+export type Homework = IHomework & IHomeworkDetail;
+
+export enum HomeworkCompletionType {
+  INDIVIDUAL = 1,
+  GROUP = 2,
+}
+
+export enum HomeworkSubmissionType {
+  WEB_LEARNING = 2,
+  OFFLINE = 0,
+}
+
+export interface IExcellentHomework {
+  id: string;
+  baseId: string;
+  title: string;
+  url: string;
+  completionType: HomeworkCompletionType;
+  author: {
+    id: string;
+    name: string;
+    anonymous: boolean;
+  };
+}
+
+export type ExcellentHomework = IExcellentHomework & IHomeworkDetail;
+
+export interface IHomeworkTA {
+  id: string;
+  index: number;
+  title: string;
+  description: string;
+  publisherId: string;
+  publishTime: string;
+  startTime: string;
+  deadline: string;
+  lateSubmissionDeadline?: string;
+  url: string;
+  completionType: HomeworkCompletionType;
+  submissionType: HomeworkSubmissionType;
+  gradedCount: number;
+  submittedCount: number;
+  unsubmittedCount: number;
+}
+
+export type HomeworkTA = IHomeworkTA;
+
+export interface IHomeworkSubmitAttachment {
+  filename: string;
+  content: Blob;
+}
+
+export interface IDiscussionBase {
+  id: string;
+  title: string;
+  publisherName: string;
+  publishTime: string;
+  lastReplierName: string;
+  lastReplyTime: string;
+  visitCount: number;
+  replyCount: number;
+  isFavorite: boolean;
+  comment?: string;
+}
+
+interface IDiscussion extends IDiscussionBase {
+  url: string;
+  boardId: string;
+}
+
+export type Discussion = IDiscussion;
+
+interface IQuestion extends IDiscussionBase {
+  url: string;
+  question: string;
+}
+
+export type Question = IQuestion;
+
+export enum QuestionnaireDetailType {
+  SINGLE = 'dnx',
+  MULTI = 'dox',
+  TEXT = 'wd',
+}
+
+export interface QuestionnaireDetail {
+  id: string;
+  index: number;
+  type: QuestionnaireDetailType;
+  required: boolean;
+  title: string;
+  score?: number;
+  options?: {
+    id: string;
+    index: number;
+    title: string;
+  }[];
+}
+
+export enum QuestionnaireType {
+  VOTE = 'tp',
+  FORM = 'tb',
+  SURVEY = 'wj',
+}
+
+export interface IQuestionnaire {
+  id: string;
+  type: QuestionnaireType;
+  title: string;
+  startTime: string;
+  endTime: string;
+  uploadTime: string;
+  uploaderId: string;
+  uploaderName: string;
+  submitTime?: string;
+  isFavorite: boolean;
+  comment?: string;
+  url: string;
+  detail: QuestionnaireDetail[];
+}
+
+export type Questionnaire = IQuestionnaire;
+
+/** which items get their extra per-item requests: none (default), all, or those the predicate accepts */
+export type DetailSelector<T> = 'none' | 'all' | ((item: T) => boolean);
+
+export interface CourseListOptions {
+  /** fetch each course's time and location (one request per course; default false) */
+  timeAndLocation?: boolean;
+}
+
+export interface HomeworkListOptions {
+  /**
+   * Which homework gets its detail (page + description JSON, 2 requests each); default `'none'`.
+   * The same as calling `getHomeworkDetail` for those items.
+   */
+  details?: DetailSelector<IHomework>;
+}
+
+export interface NotificationListOptions {
+  /**
+   * Which notices with an attachment get it (1 request each); default `'none'`.
+   * The same as calling `getNotificationAttachment` for those items.
+   */
+  attachments?: DetailSelector<INotification>;
+}
+
+export interface AllContentsOptions<T extends ContentType> {
+  courseType?: CourseType;
+  /** homework `details` or notification `attachments`, passed to each course's list */
+  details?: T extends ContentType.HOMEWORK
+    ? DetailSelector<IHomework>
+    : T extends ContentType.NOTIFICATION
+      ? DetailSelector<INotification>
+      : never;
+}
+
+export interface AllContentsResult<T extends ContentType> {
+  /** content of each course that succeeded */
+  contents: CourseContent<T>;
+  /** the error of each course that failed */
+  errors: { [courseID: string]: unknown };
+}
+
+export type ContentTypeMap = {
+  [ContentType.NOTIFICATION]: Notification;
+  [ContentType.FILE]: File;
+  [ContentType.HOMEWORK]: Homework;
+  [ContentType.DISCUSSION]: Discussion;
+  [ContentType.QUESTION]: Question;
+  [ContentType.QUESTIONNAIRE]: Questionnaire;
+};
+
+interface ICourseContent<T extends ContentType> {
+  [id: string]: ContentTypeMap[T][];
+}
+
+export type CourseContent<T extends ContentType = ContentType> = ICourseContent<T>;
+
+interface IFavoriteItem {
+  id: string;
+  type: ContentType;
+  title: string;
+  time: string;
+  state: string;
+  /** extra message. For homework, this will be deadline (plus score if graded). It's too flexible and hard to parse so we leave it as is. */
+  extra?: string;
+  semesterId: string;
+  courseId: string;
+  pinned: boolean;
+  pinnedTime?: string;
+  comment?: string;
+  addedTime: string;
+  /** for reference */
+  itemId: string;
+}
+
+export type FavoriteItem = IFavoriteItem;
+
+interface ICommentItem {
+  id: string;
+  type: ContentType;
+  content: string;
+  contentHTML: string;
+  title: string;
+  semesterId: string;
+  courseId: string;
+  commentTime: string;
+  /** for reference */
+  itemId: string;
+}
+
+export type CommentItem = ICommentItem;
+
+export interface CalendarEvent {
+  location: string;
+  status: string;
+  startTime: string;
+  endTime: string;
+  date: string;
+  courseName: string;
+}
+
+export interface CalendarOptions {
+  /** use the graduate calendar instead of the undergraduate one */
+  graduate?: boolean;
+}
+
+/** an inclusive date range, in yyyymmdd format */
+export interface CalendarRange {
+  startDate: string;
+  endDate: string;
+}
+
+export interface CalendarResult {
+  /** events of every window that succeeded, in date order */
+  events: CalendarEvent[];
+  /** windows that failed even after a retry; empty when the whole range was fetched */
+  failedRanges: CalendarRange[];
+}
+
+export enum Language {
+  ZH = 'zh',
+  EN = 'en',
+}