The ULTIMATE wrapper for EcoleDirecte's private API.

Version 🌸 Flower 1.0 (🌱 Seedling)

Install

npm install wrapdirecte

Quick Start

import { WrapDirecte } from 'wrapdirecte';

const client = new WrapDirecte();
const loginResult = await client.login('USERNAME', 'PASSWORD');

if (loginResult.status === '2FA_REQUIRED') {
  console.log(loginResult.challenge?.question);
  const answer = '...';
  await client.submit2FA(answer);
}

const account = client.getAccount();
console.log(account?.firstName, account?.lastName);

const homework = await client.homework?.getHomework('2026-04-08');
console.log(homework);

Important

The user-agent uses, by default, the name and version of your project from package.json. You can also manually override this when doing new WrapDirecte like this : new WrapDirecte({ appName: 'MyApp', appVersion: '1.2.3' })

Documentation

Authentication Methods

• new WrapDirecte() - Create a new client instance
• login(username, password, uuid?, preferredAccountId?) - Login with credentials
• relogin(username, password, uuid) - Re-login with existing session
• directLogin(username, password, cn, cv, uuid?) - Direct login with 2FA tokens
• submit2FA(answer, uuid?) - Submit 2FA answer
• selectAccount(accountId) - Select a specific student account
• logout() - Logout and clear session
• getAccount() / getRawAccount() - Get current account info
• isAuthenticated - Check if authenticated
• accounts - Get all available student accounts

Modules Available After Login

After successful authentication, the following modules become available:

• client.homework - Homework management
• client.grades - Grades and periods
• client.messaging - Messaging system
• client.timetable - Timetable and calendar
• client.absences - Absences and delays
• client.timeline - Timeline events
• client.documents - Administrative documents
• client.cloud - Cloud file storage
• client.settings - Account settings

All module methods accept an optional options parameter with {raw: true} to return raw API data instead of cleaned data.

Authentication

Login Flow

const client = new WrapDirecte();

// Basic login
const result = await client.login('username', 'password');

// If 2FA is required
if (result.status === '2FA_REQUIRED') {
  console.log(result.challenge.question); // Display question
  console.log(result.challenge.proposals); // Display proposals
  const answer = 'user_answer';
  await client.submit2FA(answer);
}

// Direct login with 2FA tokens (if you have cn/cv)
const result = await client.directLogin('username', 'password', 'cn', 'cv');

// Re-login (for session refresh)
const result = await client.relogin('username', 'password', 'uuid');

// Select account (if multiple students)
await client.selectAccount(accountId);

// Check authentication
console.log(client.isAuthenticated); // true/false
console.log(client.accounts); // Array of available accounts

Homework Module (client.homework)

Get Homework for a Date

const homework = await client.homework.getHomework('2026-04-08');
// Returns: CleanHomework[]

Mark Homework as Done/Not Done

await client.homework.markAsDone(homeworkId, true); // Mark as done
await client.homework.markAsDone(homeworkId, false); // Mark as not done

Add Comment to Homework

const commentId = await client.homework.addComment(homeworkId, 'My comment');

Grades Module (client.grades)

Get Grades and Periods

const { grades, periods, settings } = await client.grades.getGrades('2025-2026');
// grades: CleanGrade[]
// periods: CleanPeriod[]
// settings: GradeSettings

Messaging Module (client.messaging)

Get Messages by Year

const messages = await client.messaging.getMessages('2025-2026');
// Returns: { received: CleanMessage[], sent: CleanMessage[], draft: CleanMessage[], archived: CleanMessage[] }

Get Messages by Folder

const folderMessages = await client.messaging.getMessagesByFolder(folderId);
// Returns: CleanMessage[]

Get Full Message Content

const messageContent = await client.messaging.getMessageContent(messageId, '2025-2026');
// Returns: CleanMessage with content property

Send a Message

const messageId = await client.messaging.sendMessage({
  subject: 'Subject',
  content: 'Message content',
  recipients: [{ id: 123, type: 'P' }], // Teacher recipients
  year: '2025-2026'
});

Get Contacts

const teachers = await client.messaging.getContacts('professeurs');
const staff = await client.messaging.getContacts('personnels');
const companies = await client.messaging.getContacts('entreprises');
// Returns: Contact[]

Timetable Module (client.timetable)

Get Timetable for Date Range

const timetable = await client.timetable.getTimetable('2026-04-01', '2026-04-07');
// Returns: CleanCourse[]

Get iCal URL

const icalUrl = await client.timetable.getIcalUrl();
// Returns: string (full URL for calendar subscription)

Absences Module (client.absences)

Get Absences and Delays

const absences = await client.absences.getAbsences();
// Returns: CleanAbsence[]

Timeline Module (client.timeline)

Get Student Timeline

const timeline = await client.timeline.getStudentTimeline();
// Returns: CleanTimelineEvent[]

Get Common Timeline (School-wide)

const { events, postits } = await client.timeline.getCommonTimeline();
// events: CleanTimelineEvent[]
// postits: CleanPostIt[]

Documents Module (client.documents)

Get Administrative Documents

const documents = await client.documents.getDocuments();
// Returns: { factures: CleanDocument[], notes: CleanDocument[], ... }

Cloud Module (client.cloud)

Get Cloud Files

const files = await client.cloud.getCloudFiles(3); // depth 3
// Returns: CleanCloudNode[]

Create Folder

await client.cloud.createFolder('parent/path', 'newFolder');

Upload File

await client.cloud.uploadFile('destination/path', fileBuffer, 'filename.txt');

Download File

const blob = await client.cloud.downloadFile({
  type: 'CLOUD',
  fileId: 'fileId',
  year: '2025-2026' // optional
});

File Operations

// Copy nodes
await client.cloud.copyNodes('destination/path', [node1, node2]);

// Move nodes
await client.cloud.moveNodes('destination/path', [node1, node2]);

// Delete nodes
await client.cloud.deleteNodes([node1, node2]);

// Restore nodes
await client.cloud.restoreNodes([node1, node2]);

Export to Cloud

await client.cloud.exportToCloud(fileId, 'CAHIER_DE_TEXTES'); // or 'MESSAGERIE'

Settings Module (client.settings)

Update Individual Parameter

await client.settings.updateIndividualParam('value');

Update Account Settings

await client.settings.updateAccountSettings({
  identifiant: 'newUsername',
  nouveauMotDePasse: 'newPassword',
  confirmationMotDePasse: 'newPassword',
  email: 'new@email.com',
  portable: '0612345678',
  questionSecrete: 'Secret question',
  reponse: 'Answer',
  uuid: 'optional-uuid'
});

Get Account Settings

const settings = await client.settings.getAccountSettings();
// or with specific login ID
const settings = await client.settings.getAccountSettings(loginId);

Data Types

CleanHomework

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[];
  };
}

CleanGrade

interface CleanGrade {
  id: number;
  title: string;
  subjectCode: string;
  subjectLabel: string;
  date: Date | null;
  value: string;
  outOf: string;
  coefficient: number;
  isLetter: boolean;
  isSignificant: boolean;
  comment: string;
  periodCode: string;
}

CleanMessage

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';
}

CleanCourse

interface CleanCourse {
  id: number;
  subject: string;
  subjectCode: string;
  type: string;
  startDate: Date | null;
  endDate: Date | null;
  color: string;
  teacher: string;
  room: string;
  group: string;
  groupCode: string;
  isModified: boolean;
  isCancelled: boolean;
  hasSessionContent: boolean;
  hasHomework: boolean;
}

CleanAbsence

interface CleanAbsence {
  id: number;
  type: 'Absence' | 'Retard' | string;
  date: Date | null;
  displayDate: string;
  label: string;
  reason: string;
  isJustified: boolean;
  comment: string;
}

CleanTimelineEvent

interface CleanTimelineEvent {
  date: Date | null;
  type: string;
  id: number;
  title: string;
  subtitle: string;
  content: string;
}

CleanDocument

interface CleanDocument {
  id: number;
  name: string;
  date: Date | null;
  type: string;
  studentId: number;
}

CleanCloudNode

interface CleanCloudNode {
  type: 'file' | 'folder';
  name: string;
  date: Date | null;
  size: number;
  id: string;
  children?: CleanCloudNode[];
}

Testing

The project includes comprehensive integration tests for all functionalities.

Setup

1. Copy .env.example to .env and fill in your EcoleDirecte credentials.
2. Run individual tests: npm run test-[functionality] (e.g., npm run test-login)
3. Run all tests: Uncomment desired tests in tests/all.test.ts, then npm run test

Available test scripts:

• npm run test-login
• npm run test-relogin
• npm run test-selectAccount
• npm run test-homework
• npm run test-grades
• npm run test-messaging
• npm run test-timetable
• npm run test-absences
• npm run test-timeline
• npm run test-documents
• npm run test-cloud
• npm run test-settings
• npm run test (all, with uncommented tests)

Documentation

See the project wiki.

License

wrapDirecte is licensed under the LGPL 3.0, allowing you to use, modify, and distribute it for both commercial and non-commercial purposes, provided that the license terms are respected. See the LICENSE file for more details.

Legal notice

YOU are responsible for everything you made wrapDirecte process. Don't use wrapDirecte with accounts you don't have the permission to use.