@lime1/esprit-ts 1.0.0 → 1.1.0

package/README.md

@@ -2,6 +2,23 @@
 
 A TypeScript client library for the ESPRIT student portal. Scrape grades, absences, credits, schedules, and student information with full type safety.
 
+## Features
+
+- 🔐 **Authentication**: Secure login/logout with session management
+- 📊 **Academic Data**:
+  - Regular grades (incremental release during semester)
+  - Principal session results (final verdict)
+  - Rattrapage grades (retake session incremental)
+  - Rattrapage session results (retake final verdict)
+  - Historical ranking across multiple years
+  - Language proficiency levels (French & English)
+- 📅 **Attendance**: Absence tracking
+- 🎓 **Credits**: Academic credit history
+- 📋 **Schedules**: Class schedules with download links
+- 👤 **Student Info**: Name and class information
+- 🔄 **ASP.NET Support**: Full handling of complex ASP.NET postback mechanisms
+- 📦 **Type Safety**: Complete TypeScript definitions
+
 ## Installation
 
 ```bash
@@ -14,56 +31,117 @@ yarn add @lime1/esprit-ts
 
 ## Usage
 
+### Basic Example
+
 ```typescript
 import { EspritClient } from '@lime1/esprit-ts';
 
-
 async function main() {
-  // Create client (optionally enable debug mode)
   const client = new EspritClient({ debug: false });
 
-  // Login with your ESPRIT credentials
+  // Login
   const result = await client.login('your-student-id', 'your-password');
-
   if (!result.success) {
     console.error('Login failed:', result.message);
     return;
   }
 
-  console.log('Login successful!');
-
   // Get student info
   const info = await client.getStudentInfo();
-  console.log(`Name: ${info.name}`);
-  console.log(`Class: ${info.className}`);
-
-  // Get grades
-  const grades = await client.getGrades();
-  console.log('Grades:', grades);
+  console.log(`${info.name} - ${info.className}`);
+
+  // Get regular grades (released during semester)
+  const regularGrades = await client.getRegularGrades();
+  if (regularGrades) {
+    const [headers, ...rows] = regularGrades;
+    console.log('Headers:', headers);
+    console.log('Grades:', rows);
+  }
 
-  // Get grades with calculated averages
-  const summary = await client.getGradesWithAverage();
-  if (summary) {
-    console.log(`Total Average: ${summary.totalAverage?.toFixed(2)}`);
+  // Get principal session result (final verdict)
+  const principalResult = await client.getPrincipalResult();
+  if (principalResult) {
+    console.log(`Average: ${principalResult.moyenneGeneral}`);
+    console.log(`Decision: ${principalResult.decision}`);
   }
 
-  // Get absences
+  await client.logout();
+}
+
+main().catch(console.error);
+```
+
+### Comprehensive Example
+
+```typescript
+import { EspritClient } from '@lime1/esprit-ts';
+
+async function fetchAllData() {
+  const client = new EspritClient({ debug: true });
+
+  const login = await client.login('your-id', 'your-password');
+  if (!login.success) return;
+
+  console.log('=== Student Info ===');
+  const info = await client.getStudentInfo();
+  console.log(info);
+
+  console.log('\n=== Regular Grades ===');
+  const regularGrades = await client.getRegularGrades();
+  console.log(regularGrades);
+
+  console.log('\n=== Principal Result ===');
+  const principalResult = await client.getPrincipalResult();
+  console.log(principalResult);
+
+  console.log('\n=== Rattrapage Grades ===');
+  const rattrapageGrades = await client.getRattrapageGrades();
+  console.log(rattrapageGrades);
+
+  console.log('\n=== Rattrapage Result ===');
+  const rattrapageResult = await client.getRattrapageResult();
+  console.log(rattrapageResult);
+
+  console.log('\n=== Language Levels ===');
+  const languageLevels = await client.getLanguageLevels();
+  console.log(languageLevels);
+
+  console.log('\n=== Ranking ===');
+  const ranking = await client.getRanking();
+  console.log(ranking);
+
+  console.log('\n=== Absences ===');
   const absences = await client.getAbsences();
-  console.log('Absences:', absences);
+  console.log(absences);
 
-  // Get credit history
+  console.log('\n=== Credits ===');
   const credits = await client.getCredits();
-  console.log('Credits:', credits);
+  console.log(credits);
 
-  // Get schedules
+  console.log('\n=== Schedules ===');
   const schedules = await client.getSchedules();
-  console.log('Schedules:', schedules);
+  console.log(schedules);
 
-  // Logout when done
   await client.logout();
 }
 
-main().catch(console.error);
+fetchAllData().catch(console.error);
+```
+
+### Legacy Grade Format with Averages
+
+```typescript
+// For backward compatibility, the old getGrades() method still works
+// but returns parsed Grade objects instead of raw data
+const grades = await client.getGrades(); // deprecated
+const summary = await client.getGradesWithAverage();
+
+if (summary) {
+  console.log(`Total Average: ${summary.totalAverage?.toFixed(2)}`);
+  summary.grades.forEach(grade => {
+    console.log(`${grade.designation}: ${grade.moyenne?.toFixed(2)}`);
+  });
+}
 ```
 
 ## API Reference
@@ -76,31 +154,47 @@ main().catch(console.error);
 new EspritClient(config?: EspritClientConfig)
 ```
 
-| Option | Type | Default | Description |
-|--------|------|---------|-------------|
-| `debug` | `boolean` | `false` | Enable debug logging |
-| `userAgent` | `string` | Chrome UA | Custom user agent string |
-| `timeout` | `number` | `30000` | Request timeout in ms |
+| Option      | Type      | Default   | Description              |
+| ----------- | --------- | --------- | ------------------------ |
+| `debug`     | `boolean` | `false`   | Enable debug logging     |
+| `userAgent` | `string`  | Chrome UA | Custom user agent string |
+| `timeout`   | `number`  | `30000`   | Request timeout in ms    |
 
 #### Methods
 
-| Method | Returns | Description |
-|--------|---------|-------------|
-| `login(id, password)` | `Promise<LoginResult>` | Login to the portal |
-| `logout()` | `Promise<boolean>` | Logout from the portal |
-| `getGrades()` | `Promise<Grade[] \| null>` | Get student grades |
-| `getGradesWithAverage()` | `Promise<GradeSummary \| null>` | Get grades with calculated averages |
-| `getAbsences()` | `Promise<Absence[] \| null>` | Get student absences |
-| `getCredits()` | `Promise<Credit[] \| null>` | Get credit history |
-| `getSchedules()` | `Promise<Schedule[] \| null>` | Get available schedules |
-| `getStudentName()` | `Promise<string \| null>` | Get student name |
-| `getStudentClass()` | `Promise<string \| null>` | Get student class |
-| `getStudentInfo()` | `Promise<StudentInfo>` | Get name and class |
-| `getCookies()` | `Promise<Cookie[]>` | Get session cookies |
+##### Authentication
+| Method                | Returns                | Description            |
+| --------------------- | ---------------------- | ---------------------- |
+| `login(id, password)` | `Promise<LoginResult>` | Login to the portal    |
+| `logout()`            | `Promise<boolean>`     | Logout from the portal |
+| `getCookies()`        | `Promise<Cookie[]>`    | Get session cookies    |
+
+##### Grades & Results
+| Method                   | Returns                             | Description                                              |
+| ------------------------ | ----------------------------------- | -------------------------------------------------------- |
+| `getRegularGrades()`     | `Promise<RegularGrade \| null>`     | Get grades released during semester (Session Principale) |
+| `getPrincipalResult()`   | `Promise<PrincipalResult \| null>`  | Get final verdict of principal session                   |
+| `getRattrapageGrades()`  | `Promise<RattrapageGrade \| null>`  | Get retake exam grades (incremental)                     |
+| `getRattrapageResult()`  | `Promise<RattrapageResult \| null>` | Get final verdict of rattrapage session                  |
+| `getLanguageLevels()`    | `Promise<LanguageLevel \| null>`    | Get French and English proficiency levels                |
+| `getRanking()`           | `Promise<RankingEntry[] \| null>`   | Get historical academic ranking                          |
+| `getGrades()`            | `Promise<Grade[] \| null>`          | **DEPRECATED:** Use `getRegularGrades()` instead         |
+| `getGradesWithAverage()` | `Promise<GradeSummary \| null>`     | Get parsed grades with calculated averages               |
+
+##### Other Data
+| Method              | Returns                       | Description                 |
+| ------------------- | ----------------------------- | --------------------------- |
+| `getAbsences()`     | `Promise<Absence[] \| null>`  | Get student absences        |
+| `getCredits()`      | `Promise<Credit[] \| null>`   | Get credit history          |
+| `getSchedules()`    | `Promise<Schedule[] \| null>` | Get available schedules     |
+| `getStudentName()`  | `Promise<string \| null>`     | Get student name            |
+| `getStudentClass()` | `Promise<string \| null>`     | Get student class           |
+| `getStudentInfo()`  | `Promise<StudentInfo>`        | Get name and class together |
 
 ### Types
 
 ```typescript
+// Legacy parsed grade format (used by getGrades())
 interface Grade {
   designation: string;
   coefficient: number | null;
@@ -115,6 +209,32 @@ interface GradeSummary {
   totalCoefficient: number;
 }
 
+// New grade formats (raw table data)
+type RegularGrade = string[][]; // First row is headers
+type RattrapageGrade = string[][]; // First row is headers
+
+interface PrincipalResult {
+  moyenneGeneral: string | null;
+  decision: string | null;
+}
+
+interface RattrapageResult {
+  moyenneGeneral: string | null;
+  decision: string | null;
+}
+
+interface LanguageLevel {
+  francais: string | null;
+  anglais: string | null;
+}
+
+interface RankingEntry {
+  anneeUniversitaire: string | null;
+  classe: string | null;
+  moyenne: string | null;
+  rang: string | null;
+}
+
 interface LoginResult {
   success: boolean;
   cookies: Cookie[];

package/dist/index.cjs

@@ -173,6 +173,13 @@ var EspritClient = class {
   ABSENCES_URL = "https://esprit-tn.com/ESPOnline/Etudiants/absenceetud.aspx";
   CREDITS_URL = "https://esprit-tn.com/ESPOnline/Etudiants/Historique_Cr%C3%A9dit.aspx";
   SCHEDULES_URL = "https://esprit-tn.com/ESPOnline/Etudiants/Emplois.aspx";
+  // New grade endpoints
+  REGULAR_GRADES_URL = "https://esprit-tn.com/ESPOnline/Etudiants/Resultat2021.aspx";
+  PRINCIPAL_RESULT_URL = "https://esprit-tn.com/ESPOnline/Etudiants/ResultatPrincipale2021.aspx";
+  RATTRAPAGE_GRADES_URL = "https://esprit-tn.com/ESPOnline/Etudiants/noterat.aspx";
+  RATTRAPAGE_RESULT_URL = "https://esprit-tn.com/ESPOnline/Etudiants/ResultatRattrapage2021.aspx";
+  LANGUAGE_LEVELS_URL = "https://esprit-tn.com/ESPOnline/Etudiants/LANG2.aspx";
+  RANKING_URL = "https://esprit-tn.com/ESPOnline/Etudiants/ranking.aspx";
   LOGOUT_URLS = [
     "https://esprit-tn.com/esponline/Etudiants/Deconnexion.aspx",
     "https://esprit-tn.com/esponline/online/Deconnexion.aspx"
@@ -408,6 +415,7 @@ var EspritClient = class {
   /**
    * Get student grades.
    * 
+   * @deprecated Use getRegularGrades() for more accurate naming. This method will be removed in a future version.
    * @returns Array of Grade objects or null if page cannot be loaded
    */
   async getGrades() {
@@ -685,6 +693,292 @@ var EspritClient = class {
       return { name: null, className: null };
     }
   }
+  /**
+   * Get regular grades (grades released incrementally during the semester - Session Principale).
+   * 
+   * This replaces the old getGrades() method with more accurate naming.
+   * Fetches data from Resultat2021.aspx which displays module grades as they're released.
+   * 
+   * @returns Array of string arrays where first row is headers, or null if unavailable
+   */
+  async getRegularGrades() {
+    try {
+      const response = await this.client.get(this.REGULAR_GRADES_URL, { maxRedirects: 5 });
+      if (isLoginPage(response.request?.res?.responseUrl ?? "")) {
+        this.log("Session expired - redirected to login");
+        return null;
+      }
+      if (response.data.includes("aucune note!")) {
+        this.log("No grades available yet");
+        return null;
+      }
+      const $ = cheerio2.load(response.data);
+      const h1Tag = $("h1").filter((_, el) => {
+        const text = $(el).text();
+        return text.includes("Notes Des Modules");
+      });
+      if (h1Tag.length === 0) {
+        this.log("Page does not contain expected content");
+        return null;
+      }
+      const table = $("#ContentPlaceHolder1_GridView1");
+      if (table.length === 0) {
+        this.log("Grades table not found");
+        return null;
+      }
+      const { headers, rows } = parseTable($, table);
+      return [headers, ...rows];
+    } catch (error) {
+      this.log("Error getting regular grades:", error);
+      return null;
+    }
+  }
+  /**
+   * Get the final verdict/decision at the end of the principal session.
+   * 
+   * Fetches data from ResultatPrincipale2021.aspx showing the overall average and pass/fail decision.
+   * 
+   * @returns PrincipalResult with moyenneGeneral and decision, or null if unavailable
+   */
+  async getPrincipalResult() {
+    try {
+      const response = await this.client.get(this.PRINCIPAL_RESULT_URL, { maxRedirects: 5 });
+      if (isLoginPage(response.request?.res?.responseUrl ?? "")) {
+        this.log("Session expired - redirected to login");
+        return null;
+      }
+      const $ = cheerio2.load(response.data);
+      const h1Tag = $("h1").filter((_, el) => {
+        const text = $(el).text();
+        return text.includes("Resultat Session Principale");
+      });
+      if (h1Tag.length === 0) {
+        this.log("Page does not contain expected content");
+        return null;
+      }
+      const table = $("#ContentPlaceHolder1_GridView3");
+      if (table.length === 0) {
+        this.log("Result table not found");
+        return null;
+      }
+      const { headers, rows } = parseTable($, table);
+      if (rows.length === 0) {
+        this.log("No result data found");
+        return null;
+      }
+      const headerLower = headers.map((h) => h.toLowerCase());
+      const moyenneIdx = headerLower.findIndex((h) => h.includes("moyenne"));
+      const decisionIdx = headerLower.findIndex((h) => h.includes("decision"));
+      return {
+        moyenneGeneral: moyenneIdx >= 0 ? rows[0][moyenneIdx] ?? null : null,
+        decision: decisionIdx >= 0 ? rows[0][decisionIdx] ?? null : null
+      };
+    } catch (error) {
+      this.log("Error getting principal result:", error);
+      return null;
+    }
+  }
+  /**
+   * Get rattrapage (retake) grades released incrementally during the retake session.
+   * 
+   * Similar to regular grades but for the retake session, fetched from noterat.aspx.
+   * 
+   * @returns Array of string arrays where first row is headers, or null if unavailable
+   */
+  async getRattrapageGrades() {
+    try {
+      const response = await this.client.get(this.RATTRAPAGE_GRADES_URL, { maxRedirects: 5 });
+      if (isLoginPage(response.request?.res?.responseUrl ?? "")) {
+        this.log("Session expired - redirected to login");
+        return null;
+      }
+      if (response.data.includes("aucune note!")) {
+        this.log("No rattrapage grades available yet");
+        return null;
+      }
+      const $ = cheerio2.load(response.data);
+      const h1Tag = $("h1").filter((_, el) => {
+        const text = $(el).text();
+        return text.includes("Notes Des Modules session Rattrapage");
+      });
+      if (h1Tag.length === 0) {
+        this.log("Page does not contain expected content");
+        return null;
+      }
+      const table = $("#ContentPlaceHolder1_GridView1");
+      if (table.length === 0) {
+        this.log("Rattrapage grades table not found");
+        return null;
+      }
+      const { headers, rows } = parseTable($, table);
+      return [headers, ...rows];
+    } catch (error) {
+      this.log("Error getting rattrapage grades:", error);
+      return null;
+    }
+  }
+  /**
+   * Get the final verdict/decision of the rattrapage (retake) session.
+   * 
+   * Fetches data from ResultatRattrapage2021.aspx showing the overall average and pass/fail decision.
+   * 
+   * @returns RattrapageResult with moyenneGeneral and decision, or null if unavailable
+   */
+  async getRattrapageResult() {
+    try {
+      const response = await this.client.get(this.RATTRAPAGE_RESULT_URL, { maxRedirects: 5 });
+      if (isLoginPage(response.request?.res?.responseUrl ?? "")) {
+        this.log("Session expired - redirected to login");
+        return null;
+      }
+      const $ = cheerio2.load(response.data);
+      const h1Tag = $("h1").filter((_, el) => {
+        const text = $(el).text();
+        return text.includes("Resultat");
+      });
+      const spanTag = $("#ContentPlaceHolder1_Label18").filter((_, el) => {
+        const text = $(el).text();
+        return text.includes("Resultat");
+      });
+      if (h1Tag.length === 0 && spanTag.length === 0) {
+        this.log("Page does not contain expected content");
+        return null;
+      }
+      const table = $("#ContentPlaceHolder1_GridView3");
+      if (table.length === 0) {
+        this.log("Rattrapage result table not found");
+        return null;
+      }
+      const { headers, rows } = parseTable($, table);
+      if (rows.length === 0) {
+        this.log("No rattrapage result data found");
+        return null;
+      }
+      const headerLower = headers.map((h) => h.toLowerCase());
+      const moyenneIdx = headerLower.findIndex((h) => h.includes("moyenne"));
+      const decisionIdx = headerLower.findIndex((h) => h.includes("decision"));
+      return {
+        moyenneGeneral: moyenneIdx >= 0 ? rows[0][moyenneIdx] ?? null : null,
+        decision: decisionIdx >= 0 ? rows[0][decisionIdx] ?? null : null
+      };
+    } catch (error) {
+      this.log("Error getting rattrapage result:", error);
+      return null;
+    }
+  }
+  /**
+   * Get language proficiency levels (French and English).
+   * 
+   * Fetches data from LANG2.aspx showing language levels like 'B1', 'B2', etc.
+   * 
+   * @returns LanguageLevel with francais and anglais levels, or null if unavailable
+   */
+  async getLanguageLevels() {
+    try {
+      const response = await this.client.get(this.LANGUAGE_LEVELS_URL, { maxRedirects: 5 });
+      if (isLoginPage(response.request?.res?.responseUrl ?? "")) {
+        this.log("Session expired - redirected to login");
+        return null;
+      }
+      const $ = cheerio2.load(response.data);
+      const h1Tag = $("h1").filter((_, el) => {
+        const text = $(el).text();
+        return text.includes("NIVEAU LANGUES");
+      });
+      if (h1Tag.length === 0) {
+        this.log("Page does not contain expected content");
+        return null;
+      }
+      const table = $("#ContentPlaceHolder1_GridView2");
+      if (table.length === 0) {
+        this.log("Language levels table not found");
+        return null;
+      }
+      const { headers, rows } = parseTable($, table);
+      if (rows.length === 0) {
+        this.log("No language level data found");
+        return null;
+      }
+      const headerLower = headers.map((h) => h.toLowerCase());
+      const francaisIdx = headerLower.findIndex((h) => h.includes("francais"));
+      const anglaisIdx = headerLower.findIndex((h) => h.includes("anglais"));
+      return {
+        francais: francaisIdx >= 0 ? rows[0][francaisIdx] ?? null : null,
+        anglais: anglaisIdx >= 0 ? rows[0][anglaisIdx] ?? null : null
+      };
+    } catch (error) {
+      this.log("Error getting language levels:", error);
+      return null;
+    }
+  }
+  /**
+   * Get historical academic ranking data across multiple years.
+   * 
+   * Fetches data from ranking.aspx showing the student's rank, average, and class for each academic year.
+   * The table ID can vary, so multiple IDs are tried with a fallback to structure-based detection.
+   * 
+   * @returns Array of RankingEntry objects, or null if unavailable
+   */
+  async getRanking() {
+    try {
+      const response = await this.client.get(this.RANKING_URL, { maxRedirects: 5 });
+      if (isLoginPage(response.request?.res?.responseUrl ?? "")) {
+        this.log("Session expired - redirected to login");
+        return null;
+      }
+      const $ = cheerio2.load(response.data);
+      let table = $();
+      const possibleIds = [
+        "ContentPlaceHolder1_GridView1_5",
+        "ContentPlaceHolder1_GridView1_4",
+        "ContentPlaceHolder1_GridView1_3",
+        "ContentPlaceHolder1_GridView1_2",
+        "ContentPlaceHolder1_GridView1"
+      ];
+      for (const id of possibleIds) {
+        table = $(`#${id}`);
+        if (table.length > 0) {
+          this.log("Found ranking table with ID:", id);
+          break;
+        }
+      }
+      if (table.length === 0) {
+        this.log("Trying fallback table detection");
+        $("table").each((_, el) => {
+          const firstRow = $(el).find("tr").first();
+          const headers2 = firstRow.find("th").map((_2, th) => $(th).text().trim().toLowerCase()).get();
+          if (headers2.some((h) => h.includes("a.u") || h.includes("rang"))) {
+            table = $(el);
+            this.log("Found ranking table by structure");
+            return false;
+          }
+        });
+      }
+      if (table.length === 0) {
+        this.log("Ranking table not found");
+        return null;
+      }
+      const { headers, rows } = parseTable($, table);
+      if (rows.length === 0) {
+        this.log("No ranking data found");
+        return null;
+      }
+      const headerLower = headers.map((h) => h.toLowerCase());
+      const auIdx = headerLower.findIndex((h) => h.includes("a.u") || h.includes("ann\xE9e"));
+      const classeIdx = headerLower.findIndex((h) => h.includes("classe"));
+      const moyenneIdx = headerLower.findIndex((h) => h.includes("moyenne"));
+      const rangIdx = headerLower.findIndex((h) => h.includes("rang"));
+      return rows.map((row) => ({
+        anneeUniversitaire: auIdx >= 0 ? row[auIdx] ?? null : null,
+        classe: classeIdx >= 0 ? row[classeIdx] ?? null : null,
+        moyenne: moyenneIdx >= 0 ? row[moyenneIdx] ?? null : null,
+        rang: rangIdx >= 0 ? row[rangIdx] ?? null : null
+      }));
+    } catch (error) {
+      this.log("Error getting ranking:", error);
+      return null;
+    }
+  }
 };
 var index_default = EspritClient;
 // Annotate the CommonJS export names for ESM import in node: