The ULTIMATE wrapper for EcoleDirecte's private API.
Version 🌸 Flower 0.2.0 (🌱 Seedling)
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.
npm install wrapdirecteimport { 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' })
Here is the exhaustive documentation for all callable functions, parameters, and properties available in wrapDirecte.
The core WrapDirecte class manages session credentials, student accounts, and initialization of specific modules.
-
- Description: Initializes a new client instance.
- Parameters:
options?: WrapDirecteOptions(optional):appName?: string: The name of your application. Used to build a customUser-Agentheader.appVersion?: string: The version of your application (defaults to'1.0.0').
- Details: If no options are specified, it attempts to load the name and version from your project's local
package.json. If that fails, it falls back to a default user-agent.
-
- Description: Indicates whether the client is authenticated with an active session token and has a student account currently selected.
- Return Type:
boolean
-
- Description: Returns all student accounts associated with the authenticated user credentials.
- Return Type:
CleanAccount[]
-
- Description: Begins the authentication process with EcoleDirecte.
- Parameters:
username: string: User's login username.password: string: User's login password.uuid?: string(optional): Unique device identifier. Defaults to empty string.preferredAccountId?: number(optional): Target student account ID to select automatically on success. Defaults to the first student account found.
- Return Type:
Promise<LoginResult> - Throws:
EcoleDirecteAPIError,EcoleDirecteError,EcoleDirecteAccountTypeError
-
- Description: Submits the response to a 2FA challenge.
- Parameters:
answer: string: The chosen answer to the 2FA question.uuid?: string(optional): Unique device identifier. Defaults to empty string.
- Return Type:
Promise<LoginResult> - Throws:
EcoleDirecteError(if called without a preceding login flow)
-
- Description: Bypasses the 2FA challenge using a previously saved proof token (
faProof). - Parameters:
username: string: User's login username.password: string: User's login password.faProof: string: Base64 encoded 2FA proof (cn:cv) obtained from a prior successful 2FA login.uuid?: string(optional): Unique device identifier. Defaults to empty string.
- Return Type:
Promise<LoginResult> - Throws:
EcoleDirecteAPIError,EcoleDirecteAccountTypeError
- Description: Bypasses the 2FA challenge using a previously saved proof token (
-
- Description: Switches the active session to another student account.
- Parameters:
accountId: number: The student account ID.
- Return Type:
Promise<CleanAccount> - Throws:
EcoleDirecteAccountTypeError(if the account is not found or is not a student account type "E")
-
- Description: Clears all session tokens, user credentials, lists of accounts, and uninitializes all active module instances.
- Return Type:
void
-
- Description: Initializes or re-initializes all modules.
- Parameters:
account?: RawAccount(optional): A raw account object. Defaults to the currently selected account.
- Return Type:
void
-
- Description: Retrieves the currently selected student account details.
- Return Type:
CleanAccount | null
-
- Description: Retrieves the raw account details of the currently selected account.
- Return Type:
RawAccount | null
-
- Description: Manually overrides the session token.
- Parameters:
token: string | null: The token string to set.
- Return Type:
void
All modules are instantiated on the client property (e.g. client.homework) upon successful login/account selection. They all accept an optional options parameter that defaults to {}. If { raw: true } is passed, the module will return the raw API response instead of cleaning it.
-
- Description: Retrieves homework for a specific date.
- Parameters:
date: string: The date in formatYYYY-MM-DD.options?: BaseModuleOptions:{ raw?: boolean }.
- Return Type:
Promise<CleanHomework[] | any>
-
- Description: Updates the completion status of a homework task.
- Parameters:
homeworkId: number: The ID of the homework task.isDone?: boolean(optional): Whether the task is done. Defaults totrue.
- Return Type:
Promise<void>
-
- Description: Adds a comment to a homework task.
- Parameters:
homeworkId: number: The ID of the homework task.message: string: The content of the comment.
- Return Type:
Promise<number>: The ID of the created comment.
-
- Description: Retrieves grades, periods, grading settings, and competencies.
- Parameters:
year?: string(optional): The school year (e.g.,'2025-2026'). If omitted, retrieves grades for the current active year.options?: BaseModuleOptions:{ raw?: boolean }.
- Return Type:
Promise<CleanGradesResponse | any>
-
- Description: Fetches messages and folders structure.
- Parameters:
year: string: The messages school year.options?: BaseModuleOptions:{ raw?: boolean }.
- Return Type:
Promise<{ messages: Record<string, CleanMessage[]>, folders: CleanFolder[] } | any>- Message keys under
messagesare:received,sent,draft, andarchived.
- Message keys under
-
- Description: Retrieves messages in a specific custom message folder.
- Parameters:
folderId: number: The folder ID.options?: BaseModuleOptions:{ raw?: boolean }.
- Return Type:
Promise<CleanMessage[] | any>
-
- Description: Fetches the full content of a message (including body and attachments).
- Parameters:
messageId: number: The message ID.year: string: The messages school year.options?: BaseModuleOptions & { markAsUnread?: boolean }:markAsUnread?: boolean(optional): If true, marks the message back as unread.
- Return Type:
Promise<CleanMessage | any>
-
- Description: Composes and sends a message.
- Parameters:
params:subject: string: Subject of the email.content: string: Message body.recipients: any[]: Array of recipient contacts.year: string: School year of the messages.
- Return Type:
Promise<number>: The ID of the sent message.
-
- Description: Fetches the list of contacts for composing messages.
- Parameters:
type: 'professeurs' | 'personnels' | 'entreprises': The contact group to fetch.
- Return Type:
Promise<any[]>
-
- Description: Marks messages as read.
- Parameters:
ids: number[]: Array of message IDs.year: string: The messages school year.
- Return Type:
Promise<void>
-
- Description: Marks messages as unread.
- Parameters:
ids: number[]: Array of message IDs.year: string: The messages school year.
- Return Type:
Promise<void>
-
- Description: Archives messages.
- Parameters:
ids: number[]: Array of message IDs.year: string: The messages school year.
- Return Type:
Promise<void>
-
- Description: Unarchives messages.
- Parameters:
ids: number[]: Array of message IDs.year: string: The messages school year.
- Return Type:
Promise<void>
-
- Description: Moves messages to a folder.
- Parameters:
ids: number[]: Array of message IDs.folderId: number: The target folder ID (use0for the Inbox).
- Return Type:
Promise<void>
-
- Description: Creates a new message folder.
- Parameters:
name: string: Name of the new folder.
- Return Type:
Promise<number>: The ID of the created folder.
-
- Description: Deletes a folder.
- Parameters:
folderId: number: The folder ID to delete.
- Return Type:
Promise<void>
-
- Description: Retrieves timetable courses between two dates.
- Parameters:
startDate: string: Start date in formatYYYY-MM-DD.endDate: string: End date in formatYYYY-MM-DD.options?: BaseModuleOptions:{ raw?: boolean }.
- Return Type:
Promise<CleanCourse[] | any>
-
- Description: Generates an iCal calendar link for syncing tables.
- Return Type:
Promise<string>
-
- Description: Fetches school life data (absences, delays, sanctions, etc.).
- Parameters:
options?: BaseModuleOptions:{ raw?: boolean }.
- Return Type:
Promise<CleanAbsence[] | any>
-
- Description: Retrieves timeline events, grades releases, and news items.
- Parameters:
options?: BaseModuleOptions:{ raw?: boolean }.
- Return Type:
Promise<CleanTimelineEvent[] | any>
-
- Description: Fetches the homepage's common feed containing notifications (post-its) and events.
- Parameters:
options?: BaseModuleOptions:{ raw?: boolean }.
- Return Type:
Promise<{ events: CleanTimelineEvent[], postits: CleanPostIt[] } | any>
-
- Description: Fetches documents categorized by type.
- Parameters:
options?: BaseModuleOptions:{ raw?: boolean }.
- Return Type:
Promise<Record<string, CleanDocument[]> | any>- Available categories are:
factures,notes,viescolaire,administratifs,inscriptions, andentreprises.
- Available categories are:
-
- Description: Retrieves cloud folders and files.
- Parameters:
depth?: number(optional): Max folder traversal depth. Defaults to3.options?: BaseModuleOptions:{ raw?: boolean }.
- Return Type:
Promise<CleanCloudNode[] | any>
-
- Description: Creates a new subdirectory.
- Parameters:
parentPath: string: Path of the parent directory.folderName: string: Name of the new folder.
- Return Type:
Promise<any>
-
- Description: Copies files/folders.
- Parameters:
parentPath: string: Path of the destination directory.nodes: any[]: Array of nodes{ id: string, type: 'file' | 'folder' }to copy.
- Return Type:
Promise<any>
-
- Description: Soft deletes specified files or folders.
- Parameters:
nodes: any[]: Array of nodes to delete.
- Return Type:
Promise<any>
-
- Description: Restores deleted nodes from recycle bin.
- Parameters:
nodes: any[]: Array of nodes to restore.
- Return Type:
Promise<any>
-
- Description: Moves nodes into a directory.
- Parameters:
parentPath: string: Destination folder path.nodes: any[]: Array of nodes to move.
- Return Type:
Promise<any>
-
- Description: Exports an attachment or document from homework / messages directly into Cloud storage.
- Parameters:
fileId: number: ID of the file.module: 'CAHIER_DE_TEXTES' | 'MESSAGERIE': Source module type.
- Return Type:
Promise<any>
-
- Description: Uploads a file to the Cloud.
- Parameters:
destPath: string: Target folder path.fileData: Blob | Buffer: The binary payload of the file.fileName: string: Name of the file.
- Return Type:
Promise<any>
-
- Description: Downloads a file from the server.
- Parameters:
params:type: 'CLOUD' | 'FICHIER_CDT' | 'PIECE_JOINTE' | string: File type category.fileId: string: ID identifier of the file.year?: string: Message school year (mandatory for message attachments).
- Return Type:
Promise<Blob>
-
- Description: Updates visual accessibility preferences.
- Parameters:
value: string: State value.
- Return Type:
Promise<void>
-
- Description: Updates user profile parameters (username, password, secret questions, phone number, email).
- Parameters:
data:identifiant: string: Username.nouveauMotDePasse: string: New password.confirmationMotDePasse: string: Confirmation of the password.email: string: E-mail address.portable: string: Mobile phone number.questionSecrete: string: Secret question.reponse: string: Secret response.uuid?: string: Device identifier.
- Return Type:
Promise<any>
-
- Description: Retrieves the profile settings.
- Parameters:
idLogin?: number(optional): The login ID of the user. If omitted, uses the current login ID.
- Return Type:
Promise<any>
The library exports custom error classes to handle different failure cases properly:
import {
EcoleDirecteError,
EcoleDirecteAuthError,
EcoleDirecteAPIError,
EcoleDirecteAccountTypeError
} from 'wrapdirecte';| Error Class | Triggered When | Properties |
|---|---|---|
EcoleDirecteError |
Generic error in client flow. | code?: number |
EcoleDirecteAuthError |
Authentication logic/credentials errors. | code?: number |
EcoleDirecteAPIError |
The HTTP request fails or the API returns a error code other than 200/250. | code?: number, host?: string |
EcoleDirecteAccountTypeError |
The logged-in user does not contain a student (type 'E') account. |
code: 505 |
The wrapper transforms complex API responses into clean, predictable interfaces.
Click to see WrapDirecte Interfaces (WrapDirecteOptions & LoginResult)
interface WrapDirecteOptions {
appName?: string;
appVersion?: string;
}
interface LoginResult {
status: 'SUCCESS' | '2FA_REQUIRED';
token: string;
accounts?: CleanAccount[];
faProof?: string;
challenge?: {
question: string;
proposals: string[];
};
}Click to see CleanAccount & Profile Interfaces
interface CleanAccount {
loginId: number;
id: number;
uid: string;
username: string;
accountType: 'E' | 'P' | 'A' | 'F';
ogecCode: string;
isMain: boolean;
lastConnection: Date | string;
civility: string;
firstName: string;
particule: string;
lastName: string;
email: string;
isPrimary: boolean;
establishmentName: string;
establishmentLogo: string;
establishmentAgendaColor: string;
hasOnlineDictionary: boolean;
socketToken: string;
modules: CleanModule[];
individualParams: CleanIndividualParams;
profile: CleanProfile;
}
interface CleanModule {
code: string;
isEnabled: boolean;
order: number;
badgeCount: number;
params: Record<string, string>;
}
interface CleanIndividualParams {
[key: string]: any;
hasQrCode: boolean;
visualAccessibility: boolean;
pageZoom: boolean;
secureAuthCheck: boolean;
}
interface CleanProfile {
gender: 'M' | 'F';
timetableInfo: string;
establishmentName: string;
establishmentId: string;
establishmentRne: string;
mobilePhone: string;
realEstablishmentId: string;
photoUrl: string;
photoB64?: string | null;
isLearner: boolean;
class: {
id: number;
code: string;
name: string;
isGraded: boolean;
};
}Click to see CleanHomework, CleanFile & CleanComment 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 CleanFile {
id: number;
name: string;
date: Date | null;
size: number;
type: string;
}
interface CleanComment {
id: number;
authorId: number;
authorProfile: string;
authorName: string;
date: Date | null;
message: string;
}Click to see Grades & Competency Interfaces
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;
}
interface CleanPeriod {
id: number | string;
code: string;
name: string;
startDate: Date | null;
endDate: Date | null;
isClosed: boolean;
}
interface CleanSettings {
evaluationLabels: Record<string, string>;
evaluationColors: Record<string, string>;
displayAverage: boolean;
displayGrades: boolean;
}
interface CleanCompetence {
id: number | string;
competenceId: number | string;
knowledgeId: number | string;
elementProgramId: number | string;
title: string;
description: string;
subjectCode: string;
subjectLabel: string;
date: Date | null;
value: string;
outOf: string;
coefficient: number;
isLetter: boolean;
isSignificant: boolean;
comment: string;
periodCode: string;
noteId?: number | string;
noteTitle?: string;
noteDate?: Date | null;
noteValue?: string;
noteOutOf?: string;
noteCoefficient?: number;
}
interface CleanGradesResponse {
grades: CleanGrade[];
periods: CleanPeriod[];
settings: CleanSettings;
competencies: CleanCompetence[];
}Click to see Messaging Interfaces
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';
folderId?: number;
}
interface CleanFolder {
id: number;
name: string;
}
interface CleanContact {
id: number;
firstName: string;
lastName: string;
civility: string;
role: string;
}
interface CleanAttachment {
id: number;
name: string;
date: Date | null;
type: string;
}Click to see Timetable Interfaces
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;
}Click to see Absence Interface
interface CleanAbsence {
id: number;
type: 'Absence' | 'Retard' | string;
date: Date | null;
displayDate: string;
label: string;
reason: string;
isJustified: boolean;
comment: string;
}Click to see Document Interface
interface CleanDocument {
id: number;
name: string;
date: Date | null;
type: string;
studentId: number;
}Click to see Timeline & PostIt Interfaces
interface CleanTimelineEvent {
date: Date | null;
type: string;
id: number;
title: string;
subtitle: string;
content: string;
}
interface CleanPostIt {
id: number;
type: string;
content: string;
creationDate: Date | null;
startDate: Date | null;
endDate: Date | null;
author: {
firstName: string;
lastName: string;
civility: string;
id: string;
};
}Click to see Cloud Storage Interface
interface CleanCloudNode {
type: 'file' | 'folder';
name: string;
date: Date | null;
size: number;
id: string;
children?: CleanCloudNode[];
}The project uses ts-node for testing and tsup for building.
- Clone the repo and
npm install. - Create a
.envfile from.env.examplewith your credentials.
npm run test-login # Test authentication
npm run test-homework # Test homework module
npm run test # Run all enabled tests in all.test.tsnpm run build # Bundle with tsupLicense: 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.
Made with ❤️ by the Scool team