finki-auth 1.2.1 → 1.3.0

package/README.md

@@ -1,15 +1,34 @@
 # FINKI Auth
 
-This is an NPM package for managing authentication and sessions for FCSE CAS and the other services. Currently supported:
+NPM (Node) package for managing authentication and sessions for FCSE CAS and the other services. Uses an HTTP client under the hood, and not a full browser (such as Puppeteer).
 
-- CAS
-- Courses
-- Diplomas
+## Features
+
+Currently supports the following services:
+
+- [CAS](https://cas.finki.ukim.mk/)
+- [Courses](https://courses.finki.ukim.mk/)
+- [Diplomas](https://diplomski.finki.ukim.mk/)
 
 ## Installation
 
-`npm i finki-auth`
+You can add the package to your NPM project by running `npm i finki-auth`.
+
+## Example
+
+```ts
+import { CasAuthentication, Service } from "finki-auth";
+
+const auth = new CasAuthentication(credentials.username, credentials.password);
+const rawCookies = await auth.authenticate(Service.COURSES);
+
+const cookies: Record<string, string> = {};
+
+for (const { key, value } of rawCookies) {
+  cookies[key] = value;
+}
+```
 
 ## License
 
-This project is licensed under the MIT license.
+This project is licensed under the terms of the MIT license.

package/dist/auth.d.ts

@@ -0,0 +1,10 @@
+import { Service } from './lib/Service.js';
+export declare class CasAuthentication {
+    private readonly password;
+    private readonly session;
+    private readonly username;
+    constructor(username: string, password: string);
+    authenticate: (service: Service) => Promise<import("tough-cookie").Cookie[]>;
+    private readonly getCookies;
+    private readonly getFormData;
+}

package/dist/auth.js

@@ -0,0 +1,56 @@
+import axios from 'axios';
+import { wrapper } from 'axios-cookiejar-support';
+import { JSDOM } from 'jsdom';
+import { CookieJar } from 'tough-cookie';
+import { z } from 'zod';
+import { SERVICE_LOGIN_URLS } from './constants.js';
+import { Service } from './lib/Service.js';
+export class CasAuthentication {
+    password;
+    session;
+    username;
+    constructor(username, password) {
+        this.username = username;
+        this.password = password;
+        const cookieJar = new CookieJar();
+        const client = axios.create({
+            jar: cookieJar,
+            validateStatus: (status) => status >= 200 && status < 400,
+        });
+        this.session = wrapper(client);
+    }
+    authenticate = async (service) => {
+        const fullUrl = `${SERVICE_LOGIN_URLS[Service.CAS]}?service=${encodeURIComponent(SERVICE_LOGIN_URLS[service])}`;
+        const initialRequest = await this.session.get(fullUrl);
+        const { data } = z.string().safeParse(initialRequest.data);
+        if (!data) {
+            throw new Error('Failed to parse initial request data');
+        }
+        const { window } = new JSDOM(data);
+        const hiddenInputs = window.document.querySelectorAll('input[type="hidden"]');
+        const urlSearchParams = this.getFormData(hiddenInputs);
+        await this.session.post(fullUrl, urlSearchParams);
+        return this.getCookies(service);
+    };
+    getCookies = async (service) => {
+        const casCookies = (await this.session.defaults.jar?.getCookies(SERVICE_LOGIN_URLS[Service.CAS])) ?? [];
+        const serviceCookies = service
+            ? ((await this.session.defaults.jar?.getCookies(SERVICE_LOGIN_URLS[service])) ?? [])
+            : [];
+        return [...casCookies, ...serviceCookies];
+    };
+    getFormData = (inputs) => {
+        const urlSearchParams = new URLSearchParams();
+        for (const input of inputs) {
+            const name = input.getAttribute('name');
+            const value = input.getAttribute('value');
+            if (name) {
+                urlSearchParams.append(name, value ?? '');
+            }
+        }
+        urlSearchParams.append('username', this.username);
+        urlSearchParams.append('password', this.password);
+        urlSearchParams.append('submit', 'LOGIN');
+        return urlSearchParams;
+    };
+}

package/dist/constants.d.ts

@@ -1,5 +1,15 @@
 export declare const SERVICE_URLS: {
+    readonly cas: "https://cas.finki.ukim.mk";
+    readonly courses: "https://courses.finki.ukim.mk";
+    readonly diplomas: "http://diplomski.finki.ukim.mk";
+};
+export declare const SERVICE_LOGIN_URLS: {
     readonly cas: "https://cas.finki.ukim.mk/cas/login";
     readonly courses: "https://courses.finki.ukim.mk/login/index.php";
     readonly diplomas: "http://diplomski.finki.ukim.mk/Account/LoginCAS";
 };
+export declare const SERVICE_USER_ELEMENT_SELECTORS: {
+    readonly cas: "";
+    readonly courses: "span.usertext.mr-1";
+    readonly diplomas: "#logoutForm > ul > li:nth-child(1) > a";
+};

package/dist/constants.js

@@ -1,6 +1,16 @@
 import { Service } from './lib/Service.js';
 export const SERVICE_URLS = {
+    [Service.CAS]: 'https://cas.finki.ukim.mk',
+    [Service.COURSES]: 'https://courses.finki.ukim.mk',
+    [Service.DIPLOMAS]: 'http://diplomski.finki.ukim.mk',
+};
+export const SERVICE_LOGIN_URLS = {
     [Service.CAS]: 'https://cas.finki.ukim.mk/cas/login',
     [Service.COURSES]: 'https://courses.finki.ukim.mk/login/index.php',
     [Service.DIPLOMAS]: 'http://diplomski.finki.ukim.mk/Account/LoginCAS',
 };
+export const SERVICE_USER_ELEMENT_SELECTORS = {
+    [Service.CAS]: '',
+    [Service.COURSES]: 'span.usertext.mr-1',
+    [Service.DIPLOMAS]: '#logoutForm > ul > li:nth-child(1) > a',
+};

package/dist/index.d.ts

@@ -1,10 +1,3 @@
-import { Service } from './lib/Service.js';
-export declare class CasAuthentication {
-    private readonly password;
-    private readonly session;
-    private readonly username;
-    constructor(username: string, password: string);
-    authenticate: (service: Service) => Promise<import("tough-cookie").Cookie[]>;
-    private readonly getCookies;
-    private readonly getFormData;
-}
+export { CasAuthentication } from './auth.js';
+export { Service } from './lib/Service.js';
+export { isCookieValid } from './session.js';

package/dist/index.js

@@ -1,58 +1,3 @@
-import axios from 'axios';
-import { wrapper } from 'axios-cookiejar-support';
-import { JSDOM } from 'jsdom';
-import { CookieJar } from 'tough-cookie';
-import { z } from 'zod';
-import { SERVICE_URLS } from './constants.js';
-import { Service } from './lib/Service.js';
-export class CasAuthentication {
-    password;
-    session;
-    username;
-    constructor(username, password) {
-        this.username = username;
-        this.password = password;
-        const cookieJar = new CookieJar();
-        const client = axios.create({
-            jar: cookieJar,
-            validateStatus: (status) => status >= 200 && status < 400,
-        });
-        // @ts-expect-error axios-cookiejar-support has old typings. This used to be an issue in all axios related packages
-        this.session = wrapper(client);
-    }
-    authenticate = async (service) => {
-        const fullUrl = `${SERVICE_URLS[Service.CAS]}?service=${encodeURIComponent(SERVICE_URLS[service])}`;
-        const initialRequest = await this.session.get(fullUrl);
-        const { data } = z.string().safeParse(initialRequest.data);
-        if (!data) {
-            throw new Error('Failed to parse initial request data');
-        }
-        const { window } = new JSDOM(data);
-        const hiddenInputs = window.document.querySelectorAll('input[type="hidden"]');
-        const urlSearchParams = this.getFormData(hiddenInputs);
-        await this.session.post(fullUrl, urlSearchParams);
-        return this.getCookies(service);
-    };
-    getCookies = async (service) => {
-        const casCookies = (await this.session.defaults.jar?.getCookies(SERVICE_URLS[Service.CAS])) ?? [];
-        const serviceCookies = service
-            ? ((await this.session.defaults.jar?.getCookies(SERVICE_URLS[service])) ??
-                [])
-            : [];
-        return [...casCookies, ...serviceCookies];
-    };
-    getFormData = (inputs) => {
-        const urlSearchParams = new URLSearchParams();
-        for (const input of inputs) {
-            const name = input.getAttribute('name');
-            const value = input.getAttribute('value');
-            if (name) {
-                urlSearchParams.append(name, value ?? '');
-            }
-        }
-        urlSearchParams.append('username', this.username);
-        urlSearchParams.append('password', this.password);
-        urlSearchParams.append('submit', 'LOGIN');
-        return urlSearchParams;
-    };
-}
+export { CasAuthentication } from './auth.js';
+export { Service } from './lib/Service.js';
+export { isCookieValid } from './session.js';

package/dist/session.d.ts

@@ -0,0 +1,2 @@
+import type { Service } from './lib/Service.js';
+export declare const isCookieValid: (service: Service, cookies: string) => Promise<boolean>;

package/dist/session.js

@@ -0,0 +1,16 @@
+import axios from 'axios';
+import { JSDOM } from 'jsdom';
+import { z } from 'zod';
+import { SERVICE_URLS, SERVICE_USER_ELEMENT_SELECTORS } from './constants.js';
+export const isCookieValid = async (service, cookies) => {
+    const url = SERVICE_URLS[service];
+    const userElement = SERVICE_USER_ELEMENT_SELECTORS[service];
+    const response = await axios.get(url, {
+        headers: {
+            Cookie: cookies,
+        },
+    });
+    const html = z.string().parse(response.data);
+    const { window } = new JSDOM(html);
+    return window.document.querySelector(userElement) !== null;
+};

package/package.json

@@ -17,12 +17,12 @@
     "axios-cookiejar-support": "^6.0.0",
     "jsdom": "^26.0.0",
     "tough-cookie": "^5.1.2",
-    "zod": "^3.24.2"
+    "zod": "^3.25.31"
   },
   "description": "Authentication for FCSE services",
   "devDependencies": {
     "@commitlint/cli": "^19.8.0",
-    "@commitlint/config-conventional": "^19.8.0",
+    "@commitlint/config-conventional": "^19.8.1",
     "@semantic-release/changelog": "^6.0.3",
     "@semantic-release/git": "^10.0.1",
     "@types/jsdom": "^21.1.7",
@@ -39,12 +39,12 @@
     "vitest": "^3.1.1"
   },
   "engines": {
-    "node": "^20 || ^22"
+    "node": "^20 || ^22 || ^24"
   },
   "files": [
     "dist",
     "!**/*.test.*",
-    "!test"
+    "!**/tests"
   ],
   "homepage": "https://github.com/finki-hub/finki-auth",
   "keywords": [
@@ -67,11 +67,11 @@
     "lint": "eslint . --ignore-pattern \"**/test/*\" --no-warn-ignored --cache",
     "prepare": "husky",
     "package": "npm run build && npm pack",
-    "release": "semantic-release",
+    "release": "npm run build && semantic-release",
     "release:dry": "npm run release -- --dry-run",
     "test": "vitest run --exclude dist"
   },
   "type": "module",
   "types": "dist/index.d.ts",
-  "version": "1.2.1"
+  "version": "1.3.0"
 }

package/dist/tests/utils.d.ts

@@ -1,5 +0,0 @@
-import 'dotenv/config';
-export declare const getCredentials: () => {
-    password: string;
-    username: string;
-};

package/dist/tests/utils.js

@@ -1,13 +0,0 @@
-/* eslint-disable n/no-process-env */
-import 'dotenv/config';
-import assert from 'node:assert';
-export const getCredentials = () => {
-    const username = process.env['CAS_USERNAME'];
-    const password = process.env['CAS_PASSWORD'];
-    assert(username);
-    assert(password);
-    return {
-        password,
-        username,
-    };
-};