inovar-client

A TypeScript client for the Inovar SIGE API — the student information system used by Portuguese schools.

⚠️ This project is not affiliated with Inovar or inovarmais.com in any way.
Built by reverse engineering for the Papillon project 🦋

📦 Installation

npm install inovar-client

Compatible with Node.js 18+, React Native and any environment that supports the Fetch API.

🚀 Quick Start

import { InovarClient } from "inovar-client";

const client = new InovarClient();

// Login with your school subdomain, student number and password
await client.auth.login("aeviso", "8275", "mypassword");

// Get grades
const grades = await client.grades.getAll();
console.log(grades[0].subject); // "Português"
console.log(grades[0].p1);      // "3"

// Get absences
const absences = await client.absences.getAll();
console.log(absences[0].subject);    // "História"
console.log(absences[0].isJustified); // true

// Get upcoming tests from teachers
const events = await client.schedule.getTeacherEvents();
console.log(events[0].subject);     // "Matemática"
console.log(events[0].description); // "Teste de Matemática..."

// Get profile photo (data URI, ready for <Image>)
const photo = await client.student.getPhoto();
// "data:image/jpeg;base64,/9j/4AAQ..."

// Logout
client.auth.logout();

📚 API Reference

client.auth

| Method | Description | |--------|-------------| | login(escola, username, password) | Authenticates the user. Returns SessionData. | | logout() | Logs out and clears all stored data. | | refreshToken() | Manually refreshes the JWT token. | | isAuthenticated() | Returns true if the user is logged in. | | getSession() | Returns the current SessionData or null. |

client.grades

| Method | Description | |--------|-------------| | getAll() | Returns all subjects with grades for all periods. |

client.absences

| Method | Description | |--------|-------------| | getAll(startDate?, count?) | Returns absences from startDate (default: Sep 1st). |

client.schedule

| Method | Description | |--------|-------------| | getTeacherEvents(count?) | Returns upcoming tests/events set by teachers. | | getPersonalAgenda() | Returns the personal agenda (raw, more endpoints TBD). |

client.student

| Method | Description | |--------|-------------| | getPhoto() | Returns the student's profile photo as a data URI. | | getMenus() | Returns available meal menus. | | hasBilling() | Returns true if the school has billing enabled. | | hasNotices() | Returns true if there are school notices for the class. |

🔄 Token Refresh

The JWT token expires after 1 hour. The client handles this automatically — before every API call, it checks if the token is about to expire and re-logs in transparently.

You can also trigger a manual refresh (e.g. on app foreground):

await client.auth.refreshToken();

❌ Error Handling

import { InovarClient, AuthError, NetworkError } from "inovar-client";

try {
  await client.auth.login("aeviso", "8275", "wrongpassword");
} catch (err) {
  if (err instanceof AuthError) {
    console.log("Authentication failed:", err.message);
  } else if (err instanceof NetworkError) {
    console.log("Network error:", err.message);
  }
}

🏗️ Project Structure

src/
├── clients/        # InovarClient (main entry point)
├── errors/         # AuthError, NetworkError, InovarError
├── managers/       # RequestManager, TokenManager, EscolaContext
├── modules/        # AuthModule, GradesModule, AbsencesModule, ScheduleModule, StudentModule
├── structures/     # Grade, Absence, ScheduleEvent, Session
├── types/          # Raw API response types
└── utils/          # Encoding helpers (Base64, UUID)

📝 Notes

• The server runs ASP.NET 4.0 on IIS behind Cloudflare
• Each school has its own subdomain under inovarmais.com
• The API was discovered by reverse engineering the Angular web app
• More endpoints will be added as they are discovered

Part of the Papillon open source school app project 🦋