vku-sdk 1.0.0

package/README.md

@@ -0,0 +1,38 @@
+# VKU SDK 
+Ứng dụng này là một SDK không chính thức dành cho nền tảng VKU (Trang đào tạo trường VKU). Mục tiêu của SDK này là cung cấp các công cụ và phương thức để tương tác với nền tảng VKU một cách dễ dàng và hiệu quả.
+
+## Tính năng chính
+- Quản lý tín chỉ gồm: Đăng ký, xóa, lấy danh sách tín chỉ, tín chỉ đã đăng ký.
+
+## Cài đặt
+```bash
+npm install vku-sdk
+```
+## Sử dụng ví dụ
+```typescript
+import { FileCache,  AccountFactory, AccountHost, CourseSection, VkuSDK } from "./"
+
+
+async function main() {
+    const account = AccountFactory.createAccount({
+        session: "<your_cookie_or_session_here>",
+        host: AccountHost.DAOTAO // or AccountHost.DK1, AccountHost.DK2
+    })
+
+    const client = new VkuSDK(account, {
+        cache: new FileCache(__dirname + "/.cache") // Optional: Enable caching to improve performance
+    })
+
+    const registeredClasses = await client.enrollment.getRegisteredClasses() // Fetch registered classes
+    const scanClasses = await client.enrollment.scanSubjectClasses(1, 1000) // 1 to 1000 will covers the entire subject of VKU 
+    
+    const courseToRegister = new CourseSection(1, 2, 3) // Replace with actual SubjectClass.enrollmentParams
+    await client.enrollment.registerSubjectClass(courseToRegister) // Register for a class
+    
+    console.log("Registered Classes:", registeredClasses)
+    console.log("Scanned Classes:", scanClasses)
+
+}
+
+main()
+```

package/package.json

@@ -0,0 +1,36 @@
+{
+  "name": "vku-sdk",
+  "version": "1.0.0",
+  "description": "",
+  "main": "dist/index.js",
+  "types": "dist/index.d.ts",
+  "scripts": {
+    "test": "echo \"Error: no test specified\" && exit 1",
+    "build": "tsc && tsc-alias",
+    "rm:dist": "rimraf dist"
+  },
+  "keywords": [],
+  "author": "",
+  "license": "ISC",
+  "packageManager": "pnpm@10.26.2+sha512.0e308ff2005fc7410366f154f625f6631ab2b16b1d2e70238444dd6ae9d630a8482d92a451144debc492416896ed16f7b114a86ec68b8404b2443869e68ffda6",
+  "devDependencies": {
+    "@types/chrome-remote-interface": "^0.33.0",
+    "@types/node": "^25.0.3",
+    "chrome-launcher": "^1.2.1",
+    "chrome-remote-interface": "^0.33.3",
+    "rimraf": "^6.1.2",
+    "tsc-alias": "^1.8.16",
+    "tsx": "^4.21.0",
+    "typescript": "^5.9.3"
+  },
+  "dependencies": {
+    "axios": "^1.13.2",
+    "cheerio": "^1.1.2",
+    "domhandler": "^5.0.3",
+    "node-cache": "^5.1.2"
+  },
+  "peerDependencies": {
+    "chrome-launcher": "^1.2.1",
+    "chrome-remote-interface": "^0.33.3"
+  }
+}

package/pnpm-workspace.yaml

@@ -0,0 +1,2 @@
+onlyBuiltDependencies:
+  - esbuild

package/src/VkuSDK.ts

@@ -0,0 +1,184 @@
+import {
+  AxiosHttpClient,
+  HttpAccountDecorator,
+  HttpCacheDecorator,
+  HttpLoggerDecorator,
+  HttpRetryDecorator,
+  IHttpClient,
+  ISessionProvider,
+  RequestExecutor,
+} from "./core";
+import { ICache } from "./core/cache";
+import {
+  CourseSection,
+  GetRegisteredSubjectClassRequest,
+  GetSubjectClassesRequest,
+  RegisterSubjectClassRequest,
+  SubjectClass,
+  UnregisterSubjectClassRequest,
+} from "./modules";
+
+export interface ClientOptions {
+  httpLogging?: boolean;
+  cache?: ICache | null;
+  retry?: {
+    maxRetries: number;
+    retryDelay: number;
+  } | null;
+}
+
+export default class VkuSDK {
+  private executor: RequestExecutor;
+  private client: IHttpClient;
+  private options: Required<ClientOptions> = {
+    httpLogging: false,
+    cache: null,
+    retry: null,
+  };
+  private cacheDecorator?: HttpCacheDecorator;
+
+  constructor(sessionProvider: ISessionProvider, options?: ClientOptions);
+  constructor(
+    account: ISessionProvider,
+    httpClient: IHttpClient,
+    options?: ClientOptions,
+  );
+  constructor(
+    account: ISessionProvider,
+    httpClient?: IHttpClient | ClientOptions,
+    options?: ClientOptions,
+  ) {
+    this.options = {
+      ...this.options,
+      ...(isClientOptions(httpClient) ? httpClient : options || {}),
+    };
+
+    const client =
+      httpClient && !isClientOptions(httpClient)
+        ? httpClient
+        : new AxiosHttpClient(account.getHost());
+
+    let decoratedClient: IHttpClient = new HttpAccountDecorator(
+      client,
+      account,
+    );
+
+    if (this.options.cache) {
+      this.cacheDecorator = new HttpCacheDecorator(
+        decoratedClient,
+        this.options.cache,
+      );
+      decoratedClient = this.cacheDecorator;
+    }
+
+    if (this.options.retry) {
+      decoratedClient = new HttpRetryDecorator(
+        decoratedClient,
+        this.options.retry.maxRetries,
+        this.options.retry.retryDelay,
+      );
+    }
+
+    if (this.options.httpLogging) {
+      decoratedClient = new HttpLoggerDecorator(decoratedClient);
+    }
+
+    this.client = decoratedClient;
+    this.executor = new RequestExecutor(this.client);
+  }
+
+  readonly enrollment = {
+    getSubjectClasses: async (subjectId: number) => {
+      const result = await this.executor.execute(
+        new GetSubjectClassesRequest(subjectId),
+      );
+
+      return result.map((subjectClass) =>
+        subjectClass.clone({
+          id: subjectId.toString(),
+        }),
+      );
+    },
+
+    registerSubjectClass: async (courseSection: CourseSection) => {
+      return this.executor.execute(
+        new RegisterSubjectClassRequest(courseSection),
+        true
+      );
+    },
+
+    unregisterSubjectClass: async (subjectRegisteredId: number) => {
+      return this.executor.execute(
+        new UnregisterSubjectClassRequest(subjectRegisteredId),
+      );
+    },
+
+    getRegisteredClasses: async (focusRefresh: boolean = false) => {
+      return this.executor.execute(
+        new GetRegisteredSubjectClassRequest(),
+        focusRefresh,
+      );
+    },
+
+    scanSubjectClasses: async (
+      minId: number = 1,
+      maxId: number = 800,
+      refreshCourses: Array<string | number> = [],
+    ) => {
+      const batch = 20;
+      const foundClasses: SubjectClass[] = [];
+
+      for (let i = minId; i <= maxId; i += batch) {
+        const promises: Promise<SubjectClass[]>[] = [];
+        for (let j = i; j < i + batch && j <= maxId; j++) {
+          const needRefresh = this.neededRefreshCacheForSubjectClass(
+            j,
+            refreshCourses,
+          );
+
+          promises.push(
+            this.executor
+              .execute(new GetSubjectClassesRequest(j), needRefresh)
+              .then((classes) =>
+                classes.map((c) =>
+                  c.clone({
+                    id: j.toString(),
+                  }),
+                ),
+              )
+              .catch(() => []),
+          );
+        }
+
+        const results = await Promise.all(promises);
+        for (const classes of results) {
+          foundClasses.push(...classes);
+        }
+      }
+
+      return foundClasses;
+    },
+  };
+
+  private neededRefreshCacheForSubjectClass(
+    subjectClassId: string | number,
+    refreshCourses: Array<string | number>,
+  ): boolean {
+    if (refreshCourses.length === 1 && refreshCourses[0] === "*") return true;
+    return refreshCourses.includes(subjectClassId);
+  }
+
+  enableCache(): void {
+    this.cacheDecorator?.enableCache();
+  }
+
+  disableCache(): void {
+    this.cacheDecorator?.disableCache();
+  }
+}
+
+function isClientOptions(object: unknown): object is ClientOptions {
+  if (typeof object !== "object" || object === null) return false;
+  const obj = object as ClientOptions;
+  return obj.httpLogging === undefined || typeof obj.httpLogging === "boolean";
+}

package/src/core/auth/index.ts

@@ -0,0 +1 @@
+export * from "./session-provider.interface";

package/src/core/auth/session-provider.interface.ts

@@ -0,0 +1,5 @@
+export interface ISessionProvider {
+  getAuthHeader(): Promise<Record<string, string>>;
+  getHost(): string;
+  isAuthenticated(): boolean;
+}

package/src/core/cache/cache.interface.ts

@@ -0,0 +1,6 @@
+export interface ICache {
+  get<T>(key: string): Promise<T | null>;
+  set<T>(key: string, value: T, ttl?: number | string): Promise<boolean>;
+  delete(key: string): Promise<number>;
+  clear(): Promise<void>;
+}

package/src/core/cache/index.ts

@@ -0,0 +1,2 @@
+export * from "./cache.interface";
+export * from "./infra";

package/src/core/cache/infra/file-cache.ts

@@ -0,0 +1,82 @@
+import fs from "fs/promises";
+import path from "path";
+import crypto from "crypto";
+import { ICache } from "../cache.interface";
+
+interface CachePacket<T> {
+  data: T;
+  expiry: number;
+}
+
+export class FileCache implements ICache {
+  private cacheDir: string;
+
+  constructor(baseDir: string = "./.cache_data") {
+    this.cacheDir = path.resolve(baseDir);
+    this.ensureDir();
+  }
+
+  private async ensureDir() {
+    try {
+      await fs.access(this.cacheDir);
+    } catch {
+      await fs.mkdir(this.cacheDir, { recursive: true });
+    }
+  }
+
+  private getFileName(key: string): string {
+    const hash = crypto.createHash("md5").update(key).digest("hex");
+    return path.join(this.cacheDir, `${hash}.json`);
+  }
+
+  async get<T>(key: string): Promise<T | null> {
+    const filePath = this.getFileName(key);
+
+    try {
+      const raw = await fs.readFile(filePath, "utf-8");
+      const packet: CachePacket<T> = JSON.parse(raw);
+
+      if (Date.now() > packet.expiry) {
+        await this.delete(key);
+        return null;
+      }
+
+      return packet.data;
+    } catch (error) {
+      return null;
+    }
+  }
+
+  async set<T>(key: string, value: T, ttl: number): Promise<boolean> {
+    const filePath = this.getFileName(key);
+    const packet: CachePacket<T> = {
+      data: value,
+      expiry: Date.now() + ttl * 1000,
+    };
+
+    await fs.writeFile(filePath, JSON.stringify(packet), "utf-8");
+
+    return true;
+  }
+
+  async delete(key: string): Promise<number> {
+    const filePath = this.getFileName(key);
+    try {
+      await fs.unlink(filePath);
+      return 1;
+    } catch {
+      return 0;
+    }
+  }
+
+  async clear(): Promise<void> {
+    try {
+      const files = await fs.readdir(this.cacheDir);
+      for (const file of files) {
+        await fs.unlink(path.join(this.cacheDir, file));
+      }
+    } catch (e) {
+      // Ignore errors
+    }
+  }
+}

package/src/core/cache/infra/index.ts

@@ -0,0 +1,3 @@
+export * from "./memory-cache";
+export * from "./storage-cache";
+export * from "./file-cache";

package/src/core/cache/infra/memory-cache.ts

@@ -0,0 +1,32 @@
+import { ICache } from "../cache.interface";
+
+export class MemoryCache implements ICache {
+  constructor(private defaultTTL: number = 300) {}
+  private store: Map<string, { value: any; expiresAt: number | null }> =
+    new Map();
+  async get<T>(key: string): Promise<T | null> {
+    const entry = this.store.get(key);
+    if (!entry) return null;
+
+    if (entry.expiresAt && Date.now() > entry.expiresAt) {
+      this.store.delete(key);
+      return null;
+    }
+
+    return entry.value as T;
+  }
+  async set<T>(key: string, value: T, ttl?: number): Promise<boolean> {
+    const expiresAt = Date.now() + (ttl ?? this.defaultTTL) * 1000;
+
+    this.store.set(key, { value, expiresAt });
+
+    return true;
+  }
+  async delete(key: string): Promise<number> {
+    return this.store.delete(key) ? 1 : 0;
+  }
+
+  async clear(): Promise<void> {
+    this.store.clear();
+  }
+}

package/src/core/cache/infra/storage-cache.ts

@@ -0,0 +1,24 @@
+import { ICache } from "../cache.interface";
+import NodeCache from "node-cache";
+
+export class StorageCache implements ICache {
+  private cache: NodeCache;
+  constructor(
+    private options: NodeCache.Options = { stdTTL: 300, checkperiod: 600 },
+  ) {
+    this.cache = new NodeCache(this.options);
+  }
+  async get<T>(key: string): Promise<T | null> {
+    return this.cache.get<T>(key) ?? null;
+  }
+  async set<T>(key: string, value: T, ttl?: number | string): Promise<boolean> {
+    if (ttl) return this.cache.set(key, value, ttl);
+    return this.cache.set(key, value);
+  }
+  async delete(key: string): Promise<number> {
+    return this.cache.del(key);
+  }
+  async clear(): Promise<void> {
+    this.cache.flushAll();
+  }
+}

package/src/core/executor/index.ts

@@ -0,0 +1 @@
+export * from "./request-executor";

package/src/core/executor/request-executor.ts

@@ -0,0 +1,20 @@
+import { BaseRequest } from "../http/base-request";
+import { IHttpClient } from "../http/http-client.interface";
+import { HtmlDetect } from "../utils";
+
+export class RequestExecutor {
+  constructor(private client: IHttpClient) {}
+
+  async execute<T>(request: BaseRequest<T>, focusRefresh: boolean = false) {
+    const httpRequest = request.buildRequest();
+    if (focusRefresh) httpRequest.disableCache();
+
+    const response = await this.client.send(httpRequest);
+
+    if (httpRequest.isAuthRequired() && HtmlDetect.isLoginPage(response))
+      throw new Error("Authentication required but session is invalid.");
+
+    const parser = request.getParser();
+    return parser.parse(response);
+  }
+}

package/src/core/http/adapters/axios-http-client.ts

@@ -0,0 +1,25 @@
+import { AxiosInstance } from "axios";
+import { HttpRequest } from "../base-request";
+import { IHttpClient } from "../http-client.interface";
+import axios from "axios";
+
+export class AxiosHttpClient implements IHttpClient {
+  private instance: AxiosInstance;
+  constructor(baseURL?: string) {
+    this.instance = axios.create({
+      baseURL: baseURL,
+    });
+  }
+
+  async send(request: HttpRequest): Promise<string> {
+    const { data } = await this.instance.request<string>({
+      url: request.getUrl(),
+      method: request.getMethod(),
+      headers: request.getHeaders(),
+      params: request.getParams(),
+      data: request.getBody(),
+    });
+
+    return data;
+  }
+}

package/src/core/http/adapters/http-account.decorator.ts

@@ -0,0 +1,19 @@
+import { ISessionProvider } from "../../auth/session-provider.interface";
+import { HttpRequest } from "../base-request";
+import { IHttpClient } from "../http-client.interface";
+
+export class HttpAccountDecorator implements IHttpClient {
+  constructor(
+    private delegate: IHttpClient,
+    private sessionProvider: ISessionProvider,
+  ) {}
+  async send(request: HttpRequest): Promise<string> {
+    if (request.isAuthRequired() && !this.sessionProvider.isAuthenticated())
+      throw new Error("Authentication required but no session available.");
+    const header = await this.sessionProvider.getAuthHeader();
+    request.mergeHeaders(header);
+    request.setHost(this.sessionProvider.getHost());
+
+    return this.delegate.send(request);
+  }
+}

package/src/core/http/adapters/http-cache.decorator.ts

@@ -0,0 +1,55 @@
+import { ICache } from "../../cache";
+import { HtmlDetect } from "../../utils";
+import { HttpMethod, HttpRequest } from "../base-request";
+import { IHttpClient } from "../http-client.interface";
+
+export class HttpCacheDecorator implements IHttpClient {
+  private isEnabledCache: boolean = true;
+  constructor(
+    private delegate: IHttpClient,
+    private cache: ICache,
+    private defaultTTL: number = 120
+  ) {}
+  async send(request: HttpRequest): Promise<string> {
+    if (
+      request.getMethod() !== HttpMethod.GET ||
+      !this.isEnabledCache ||
+      request.isNoCache()
+    ) {
+      return this.delegate.send(request);
+    }
+
+    const cacheKey = this.generateCacheKey(request);
+
+    const cachedResponse = await this.cache.get<string>(cacheKey);
+    if (cachedResponse) {
+      return cachedResponse;
+    }
+
+    const response = await this.delegate.send(request);
+
+    if (!HtmlDetect.isLoginPage(response)) {
+      await this.cache.set<string>(cacheKey, response, this.defaultTTL);
+    }
+
+    return response;
+  }
+
+  private generateCacheKey(request: HttpRequest): string {
+    const url = request.getUrl();
+    const params = request.getParams();
+    const paramString = Object.keys(params)
+      .sort()
+      .map((key) => `${key}=${params[key]}`)
+      .join("&");
+    return paramString ? `${url}?${paramString}` : url;
+  }
+
+  enableCache(): void {
+    this.isEnabledCache = true;
+  }
+
+  disableCache(): void {
+    this.isEnabledCache = false;
+  }
+}

package/src/core/http/adapters/http-logger.decorator.ts

@@ -0,0 +1,29 @@
+import { HttpRequest } from "../base-request";
+import { IHttpClient } from "../http-client.interface";
+
+export interface IHttpLoggerDecoratorOptions {}
+
+export class HttpLoggerDecorator implements IHttpClient {
+  constructor(
+    private delegate: IHttpClient,
+    options: IHttpLoggerDecoratorOptions = {},
+  ) {}
+  async send(request: HttpRequest): Promise<string> {
+    const startTime = Date.now();
+    try {
+      const response = await this.delegate.send(request);
+      const duration = Date.now() - startTime;
+      console.log(
+        `[HttpLoggerDecorator]: ${request.getMethod()} ${request.getUrl()} success - ${duration}ms\n\n`,
+        response.slice(0, 500) + "\n",
+      );
+      return response;
+    } catch (error) {
+      const duration = Date.now() - startTime;
+      console.log(
+        `[HttpLoggerDecorator]: ${request.getMethod()} ${request.getUrl()} - Failed after ${duration}ms: ${(error as any).message}`,
+      );
+      throw error;
+    }
+  }
+}

package/src/core/http/adapters/http-retry.decorator.ts

@@ -0,0 +1,34 @@
+import { HttpRequest } from "../base-request";
+import { IHttpClient } from "../http-client.interface";
+
+export class HttpRetryDecorator implements IHttpClient {
+  constructor(
+    private delegate: IHttpClient,
+    private maxRetries: number = 3,
+    private retryDelay: number = 300,
+  ) {}
+
+  async send(request: HttpRequest): Promise<string> {
+    let attempt = 0;
+    let lastError: any;
+
+    while (attempt < this.maxRetries) {
+      try {
+        return await this.delegate.send(request);
+      } catch (error) {
+        lastError = error;
+        attempt++;
+        console.warn(
+          `[HttpRetryDecorator]: Attempt ${attempt} failed. Retrying in ${this.retryDelay}ms...`,
+        );
+        await new Promise((resolve) => setTimeout(resolve, this.retryDelay));
+      }
+    }
+
+    console.error(
+      `[HttpRetryDecorator]: All ${this.maxRetries} attempts failed.`,
+    );
+
+    throw lastError;
+  }
+}

package/src/core/http/adapters/index.ts

@@ -0,0 +1,5 @@
+export * from "./axios-http-client";
+export * from "./http-account.decorator";
+export * from "./http-cache.decorator";
+export * from "./http-retry.decorator";
+export * from "./http-logger.decorator";