🚀 Overview

wrapDirecte is a powerful, modern, and type-safe TypeScript wrapper for the EcoleDirecte API. It provides a clean interface to access grades, homework, messaging, timetable, and more, with built-in support for 2FA and multi-account management.

📦 Install

npm install wrapdirecte

⚡ Quick Start

import { WrapDirecte } from 'wrapdirecte';

const client = new WrapDirecte();

// 1. Authenticate
const loginResult = await client.login('USERNAME', 'PASSWORD');

// 2. Handle 2FA if required
if (loginResult.status === '2FA_REQUIRED') {
  console.log('Question:', loginResult.challenge?.question);
  // In a real app, prompt the user for the answer
  await client.submit2FA('THE_ANSWER');
}

// 3. Access your data
const account = client.getAccount();
console.log(`Hello, ${account?.firstName}!`);

// 4. Use modules
const homework = await client.homework?.getHomework('2026-04-08');
const grades = await client.grades?.getGrades('2025-2026');

[!TIP] The user-agent is automatically generated from your package.json. You can customize it: new WrapDirecte({ appName: 'MyGreatApp', appVersion: '2.0.0' })

🛠️ Documentation

Core Methods

| Method | Description | | :--- | :--- | | login(user, pass, uuid?, preferredId?) | Primary authentication method | | submit2FA(answer, uuid?) | Submit answer for 2FA challenges | | directLogin(user, pass, proof, uuid?) | Bypass 2FA if you have a valid faProof | | relogin(user, pass, uuid) | Refresh an existing session | | selectAccount(accountId) | Switch between student accounts | | logout() | Clear session and tokens | | getAccount() | Get the currently selected account | | isAuthenticated | Returns true if logged in and account selected |

🧩 Available Modules

After a successful login, these modules are accessible via client.<module>:

• homework: Fetch, mark as done, add comments.
• grades: Access grades, periods, and averages.
• messaging: Send/receive messages, manage folders, contacts.
• timetable: Weekly schedules and iCal integration.
• absences: Track absences, delays, and sanctions.
• timeline: School news and personal event feed.
• documents: Download invoices, reports, and certificates.
• cloud: Full file management (upload, download, move, delete).
• settings: Manage account profile and preferences.

[!NOTE] All module methods accept an optional options parameter. Use { raw: true } to bypass cleaning and get the original API response.

📖 Module Deep Dive

Homework (client.homework)

• getHomework(date): Returns CleanHomework[].
• markAsDone(homeworkId, status): Update completion status.
• addComment(homeworkId, text): Post a comment on a task.

Grades (client.grades)

• getGrades(year): Returns grades, periods, and settings.

Messaging (client.messaging)

• getMessages(year): Returns inbox, sent, drafts, and archives.
• getMessageContent(id, year): Get full body and attachments.
• sendMessage(params): Compose and send new messages.
• getContacts(type): Fetch available recipients.

Timetable (client.timetable)

• getTimetable(start, end): Get courses for a date range.
• getIcalUrl(): Generate a subscription link for external calendars.

Cloud (client.cloud)

• getCloudFiles(depth?): List files and folders.
• uploadFile(path, data, name): Upload files to the cloud.
• downloadFile(params): Download any file from the system.
• deleteNodes(nodes) / moveNodes(...): File operations.

📊 Data Types (Cleaned)

The wrapper transforms complex API responses into clean, predictable interfaces.

interface CleanHomework {
  id: number;
  date: Date | null;
  subject: string;
  subjectCode: string;
  teacherName: string;
  isInterrogation: boolean;
  isDone: boolean;
  content: string;
  files: CleanFile[];
  comments: CleanComment[];
  sessionContent: {
    content: string;
    files: CleanFile[];
    comments: CleanComment[];
  };
}

interface CleanMessage {
  id: number;
  subject: string;
  date: Date | null;
  from: CleanContact;
  to: CleanContact[];
  content?: string;
  isRead: boolean;
  hasAttachments: boolean;
  attachments: CleanAttachment[];
  type: 'received' | 'sent' | 'draft' | 'archived' | 'classeur';
}

🧪 Testing & Development

The project uses ts-node for testing and tsup for building.

Setup

1. Clone the repo and npm install.
2. Create a .env file from .env.example with your credentials.

Run Tests

npm run test-login      # Test authentication
npm run test-homework   # Test homework module
npm run test            # Run all enabled tests in all.test.ts

Build

npm run build           # Bundle with tsup

📜 License & Legal

License: LGPL 3.0.

Legal Notice: This project is not affiliated with EcoleDirecte. Use it responsibly. YOU are responsible for your usage of this wrapper. Don't use it with accounts you don't have permission to access.