juno-erp-client 1.0.0

package/LICENSE

@@ -0,0 +1,19 @@
+Copyright (c) 2026 Danish
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

package/README.md

@@ -0,0 +1,99 @@
+# Juno ERP Client
+
+[![npm version](https://img.shields.io/npm/v/juno-erp-client.svg)](https://www.npmjs.com/package/juno-erp-client)
+[![License: MIT](https://img.shields.io/badge/License-MIT-yellow.svg)](https://opensource.org/licenses/MIT)
+
+A high-level TypeScript API wrapper for the **JUNO Campus ERP** system (MGM University). This library simplifies programmatic access to student information, academic details, attendance, results, and fees.
+
+## Features
+
+- 🔐 **Automated Authentication**: Handles the multi-step Juno login process (including JSESSIONID acquisition and session priming).
+- 💾 **Session Persistence**: Built-in support for saving and loading cookies to/from a local file or external storage.
+- 📘 **Type Safe**: Fully written in TypeScript with comprehensive interfaces for all API responses.
+- ⚡ **Easy to Use**: Simplified methods for common tasks like checking attendance, results, and timetables.
+
+## Installation
+
+```bash
+npm install juno-erp-client
+```
+
+## Quick Start
+
+### Basic Login
+```typescript
+import { JunoClient } from 'juno-erp-client';
+
+const client = new JunoClient({ debug: true });
+
+const success = await client.login('your_username', 'your_password');
+if (success) {
+    const profile = await client.getStudentProfile();
+    console.log(`LoggedIn as: ${profile[0].firstName} ${profile[0].lastName}`);
+}
+```
+
+### Session Persistence (File-based)
+Automatically save and reuse your session to avoid logging in every time.
+
+```typescript
+const client = new JunoClient({
+    sessionPath: './.session/cookies.json', // Path to save cookies
+    autoSave: true // Default: true if sessionPath is provided
+});
+
+// Check if we have an active session
+if (!(await client.isLoggedIn())) {
+    await client.login(username, password);
+}
+
+// Now you're ready to make API calls!
+const results = await client.getStudentResults({
+    examScheduleId: '...',
+    examSemesterId: '...',
+    universitySyllabusId: 0
+});
+```
+
+### Manual Session Export/Import
+Useful for serverless environments (e.g., storing session in Redis or a DB).
+
+```typescript
+// Export
+const sessionData = client.exportSession();
+
+// Import on a new instance
+const newClient = new JunoClient();
+newClient.importSession(sessionData);
+
+if (await newClient.isLoggedIn()) {
+    console.log("Re-authenticated using exported session!");
+}
+```
+
+## API Documentation
+
+The client provides methods for:
+
+- **Student Information**: `getStudentProfile`, `getPersonalInformation`, `getAcademicInfo`, `getAdmissionDetails`.
+- **Attendance**: `getAttendanceDetails`, `getAttendanceGraph`.
+- **Academics**: `getCourses`, `getStudentResults`, `getExamDetails`.
+- **Finance**: `getFeesDetails`, `getStudentReceivable`.
+- **Schedule**: `getTodaySchedule`, `getTimetableBetweenDates`.
+- **Utils**: `search`, `getStudentIdFromSession`.
+
+All methods return strongly typed promises. Refer to the TypeScript definitions for detailed response structures.
+
+## Troubleshooting
+
+### Connectivity
+If you encounter `ECONNREFUSED` or `ETIMEDOUT`, ensure that:
+1. The MGM University ERP (erp.mgmu.ac.in) is online.
+2. You are not blocked by a firewall or VPN.
+
+### Empty Responses
+Some endpoints require specific session "priming". The library handles this during `login()`. If you are using session persistence, ensure the session has not expired on the server.
+
+## License
+
+MIT © [Denizuh](mailto:danishs2007@gmail.com)

package/dist/index.d.ts

@@ -0,0 +1,198 @@
+import { JunoConfig, StudentProfile, PersonalInfo, AcademicInfo, AdmissionDetail, Course, AttendanceDetails, AttendanceGraph, ResultDetail, ExamDetails, FeesDetails, StudentReceivable, TodaySchedule, DetailedTimetableEntry, SearchResult, Caste, Country, TransferDetail, TransferDetailsOfStudent } from './types';
+/**
+ * JunoClient is a high-level API wrapper for the Juno ERP system.
+ * It handles session management, cookie persistence, and provides
+ * type-safe methods to access student data.
+ */
+export declare class JunoClient {
+    private api;
+    private jar;
+    private debug;
+    private sessionPath?;
+    private autoSave;
+    /**
+     * Creates a new instance of the Juno API client.
+     * @param config - Configuration options for the client.
+     */
+    constructor(config?: JunoConfig);
+    /**
+     * Internal utility for logging debug information.
+     * @param method - The name of the method being logged.
+     * @param data - The data to log.
+     */
+    private logDebug;
+    /**
+     * Saves the current session cookies to the configured sessionPath.
+     */
+    saveSessionToFile(): void;
+    /**
+     * Loads session cookies from the configured sessionPath and re-initializes the API instance.
+     */
+    loadSessionFromFile(): void;
+    /**
+     * Exports the current session data as a JSON-serializable object.
+     * Use this for manual session management (e.g., storing in a database).
+     * @returns The serialized session object.
+     */
+    exportSession(): any;
+    /**
+     * Imports session data from a previously exported session object.
+     * @param data - The serialized session object.
+     */
+    importSession(data: any): void;
+    /**
+     * Checks if the client is currently logged in and has a valid session.
+     * This method verifies the session by attempting to fetch the student ID.
+     * @returns A promise that resolves to true if logged in, false otherwise.
+     */
+    isLoggedIn(): Promise<boolean>;
+    /**
+     * Performs a multi-step login process to authenticate with the Juno ERP system.
+     * The process involves:
+     * 1. Acquiring an initial JSESSIONID from the login page.
+     * 2. Posting credentials to the security check endpoint.
+     * 3. Following redirects to activate the session.
+     * 4. Visiting the dashboard to prime the server-side context.
+     *
+     * @param username - The Juno ERP username.
+     * @param password - The Juno ERP password.
+     * @returns A promise that resolves to true if login was successful, false otherwise.
+     */
+    login(username: string, password: string): Promise<boolean>;
+    /**
+     * Fetches the student's basic profile information.
+     * @returns A promise that resolves to an array containing the student profile.
+     */
+    getStudentProfile(): Promise<StudentProfile[]>;
+    /**
+     * Fetches detailed personal contact and address information.
+     * @returns A promise resolving to an object containing PersonalInfo.
+     */
+    getPersonalInformation(): Promise<{
+        hasUserLogin: boolean;
+        PersonalInfo: PersonalInfo;
+        hasPersonalInfo: boolean;
+    }>;
+    /**
+     * Fetches academic enrollment details like course, department, and semester.
+     * @returns A promise resolving to an array of AcademicInfo objects.
+     */
+    getAcademicInfo(): Promise<AcademicInfo[]>;
+    /**
+     * Fetches admission-related details and document submission status.
+     * @returns A promise resolving to an object containing AdmissionDetail.
+     */
+    getAdmissionDetails(): Promise<{
+        hasAdmissionDetail: boolean;
+        AdmissionInfo: AdmissionDetail;
+    }>;
+    /**
+     * Fetches a list of all available castes from the system.
+     * @returns A promise resolving to an array of Caste objects.
+     */
+    getAllCastes(): Promise<Caste[]>;
+    /**
+     * Fetches a list of all countries for nationality selection.
+     * @returns A promise resolving to an array of Country objects.
+     */
+    getCountryList(): Promise<Country[]>;
+    /**
+     * Fetches the list of courses for a given term (semester).
+     * @param termId - The internal ID for the term.
+     * @param params - Optional search and filtering parameters.
+     * @returns A promise resolving to an array of Course objects.
+     */
+    getCourses(termId: number, params?: {
+        refreshData?: number;
+        subjectwisestudentids?: string;
+        subejctwiseBatchIds?: string;
+        batchsemestercapacity?: number;
+    }): Promise<Course[]>;
+    /**
+     * Fetches high-level attendance summary statistics.
+     * @returns A promise resolving to AttendanceDetails.
+     */
+    getAttendanceDetails(): Promise<AttendanceDetails>;
+    /**
+     * Fetches attendance distribution data for visualization/graphing.
+     * @param termId - The term to filter by. Defaults to 'All'.
+     * @returns A promise resolving to an array of AttendanceGraph data points.
+     */
+    getAttendanceGraph(termId?: string): Promise<AttendanceGraph[]>;
+    /**
+     * Fetches detailed marks and results for a specific examination.
+     * @param params - Parameters defining the specific exam schedule and syllabus.
+     * @returns A promise resolving to an array of ResultDetail objects.
+     */
+    getStudentResults(params: {
+        examScheduleId: string;
+        examSemesterId: string;
+        universitySyllabusId: number;
+    }): Promise<ResultDetail[]>;
+    /**
+     * Fetches overall examination performance and marks statistics.
+     * @returns A promise resolving to ExamDetails.
+     */
+    getExamDetails(): Promise<ExamDetails>;
+    /**
+     * Fetches the current fee invoice and structure summary.
+     * @returns A promise resolving to FeesDetails.
+     */
+    getFeesDetails(): Promise<FeesDetails>;
+    /**
+     * Fetches the detailed fee break-up for the current student.
+     * @returns A promise resolving to an array of fee items.
+     */
+    getFeeStructureByStudentId(): Promise<any[]>;
+    /**
+     * Alternative method to fetch fee structure from the student-side view.
+     * @returns A promise resolving to an array of fee items.
+     */
+    getFeeStructureByStudentIdOfStudentSide(): Promise<any[]>;
+    /**
+     * Fetches the total receivables, including academic, hostel, and miscellaneous fees.
+     * @returns A promise resolving to StudentReceivable details.
+     */
+    getStudentReceivable(): Promise<StudentReceivable>;
+    /**
+     * Fetches the student's schedule for a specific date.
+     * @param date - The date to fetch for (standard format).
+     * @returns A promise resolving to an array of TodaySchedule objects.
+     */
+    getTodaySchedule(date: string): Promise<TodaySchedule[]>;
+    /**
+     * Fetches the timetable entries between two dates.
+     * @param params - Date range and optional term filter.
+     * @returns A promise resolving to an array of DetailedTimetableEntry objects.
+     */
+    getTimetableBetweenDates(params: {
+        startDate: string;
+        endDate: string;
+        termId?: number;
+    }): Promise<DetailedTimetableEntry[]>;
+    /**
+     * Performs a global search across student and faculty records.
+     * @param query - The search string (e.g., name or ID).
+     * @returns A promise resolving to an array of SearchResult objects.
+     */
+    search(query: string): Promise<SearchResult[]>;
+    /**
+     * Retrieves the internal student ID from the current active session.
+     * @returns A promise resolving to the student ID.
+     */
+    getStudentIdFromSession(): Promise<number>;
+    /**
+     * Fetches details of any course transfer requests made by the student.
+     * @returns A promise resolving to an object with transfer details.
+     */
+    getTransferDetails(): Promise<{
+        hasTransferRequest: boolean;
+        studentTransferDetails: TransferDetail[];
+    }>;
+    /**
+     * Fetches the historical transfer record of the student.
+     * @returns A promise resolving to an array of TransferDetailsOfStudent objects.
+     */
+    getTransferDetailsOfStudent(): Promise<TransferDetailsOfStudent[]>;
+}
+export * from './types';