🚀 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' })

🛠️ Complete API Reference

Here is the exhaustive documentation for all callable functions, parameters, and properties available in wrapDirecte.

🧭 Core Client (WrapDirecte)

The core WrapDirecte class manages session credentials, student accounts, and initialization of specific modules.

• new WrapDirecte(options?: WrapDirecteOptions)

  • Description: Initializes a new client instance.
  • Parameters:
    • options?: WrapDirecteOptions (optional):
      • appName?: string: The name of your application. Used to build a custom User-Agent header.
      • 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.

• client.isAuthenticated (getter)

  • Description: Indicates whether the client is authenticated with an active session token and has a student account currently selected.
  • Return Type: boolean

• client.accounts (getter)

  • Description: Returns all student accounts associated with the authenticated user credentials.
  • Return Type: CleanAccount[]

• login(username, password, uuid?, preferredAccountId?)

  • 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

• submit2FA(answer, uuid?)

  • 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)

• directLogin(username, password, faProof, uuid?)

  • 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

• selectAccount(accountId)

  • 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")

• logout()

  • Description: Clears all session tokens, user credentials, lists of accounts, and uninitializes all active module instances.
  • Return Type: void

• initModules(account?)

  • Description: Initializes or re-initializes all modules.
  • Parameters:
    • account?: RawAccount (optional): A raw account object. Defaults to the currently selected account.
  • Return Type: void

• getAccount()

  • Description: Retrieves the currently selected student account details.
  • Return Type: CleanAccount | null

• getRawAccount()

  • Description: Retrieves the raw account details of the currently selected account.
  • Return Type: RawAccount | null

• setToken(token)

  • Description: Manually overrides the session token.
  • Parameters:
    • token: string | null: The token string to set.
  • Return Type: void

🧩 Modules Reference

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.

📚 Homework (client.homework)

• getHomework(date, options?)

  • Description: Retrieves homework for a specific date.
  • Parameters:
    • date: string: The date in format YYYY-MM-DD.
    • options?: BaseModuleOptions: { raw?: boolean }.
  • Return Type: Promise<CleanHomework[] | any>

• markAsDone(homeworkId, isDone?)

  • 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 to true.
  • Return Type: Promise<void>

• addComment(homeworkId, message)

  • 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.

📊 Grades (client.grades)

• getGrades(year?, options?)

  • 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>

✉️ Messaging (client.messaging)

• getMessages(year, options?)

  • 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 messages are: received, sent, draft, and archived.

• getMessagesByFolder(folderId, options?)

  • Description: Retrieves messages in a specific custom message folder.
  • Parameters:
    • folderId: number: The folder ID.
    • options?: BaseModuleOptions: { raw?: boolean }.
  • Return Type: Promise<CleanMessage[] | any>

• getMessageContent(messageId, year, options?)

  • 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>

• sendMessage(params)

  • 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.

• getContacts(type)

  • Description: Fetches the list of contacts for composing messages.
  • Parameters:
    • type: 'professeurs' | 'personnels' | 'entreprises': The contact group to fetch.
  • Return Type: Promise<any[]>

• markAsRead(ids, year)

  • Description: Marks messages as read.
  • Parameters:
    • ids: number[]: Array of message IDs.
    • year: string: The messages school year.
  • Return Type: Promise<void>

• markAsUnread(ids, year)

  • Description: Marks messages as unread.
  • Parameters:
    • ids: number[]: Array of message IDs.
    • year: string: The messages school year.
  • Return Type: Promise<void>

• archiveMessages(ids, year)

  • Description: Archives messages.
  • Parameters:
    • ids: number[]: Array of message IDs.
    • year: string: The messages school year.
  • Return Type: Promise<void>

• unarchiveMessages(ids, year)

  • Description: Unarchives messages.
  • Parameters:
    • ids: number[]: Array of message IDs.
    • year: string: The messages school year.
  • Return Type: Promise<void>

• moveMessages(ids, folderId)

  • Description: Moves messages to a folder.
  • Parameters:
    • ids: number[]: Array of message IDs.
    • folderId: number: The target folder ID (use 0 for the Inbox).
  • Return Type: Promise<void>

• createFolder(name)

  • Description: Creates a new message folder.
  • Parameters:
    • name: string: Name of the new folder.
  • Return Type: Promise<number>: The ID of the created folder.

• deleteFolder(folderId)

  • Description: Deletes a folder.
  • Parameters:
    • folderId: number: The folder ID to delete.
  • Return Type: Promise<void>

📅 Timetable (client.timetable)

• getTimetable(startDate, endDate, options?)

  • Description: Retrieves timetable courses between two dates.
  • Parameters:
    • startDate: string: Start date in format YYYY-MM-DD.
    • endDate: string: End date in format YYYY-MM-DD.
    • options?: BaseModuleOptions: { raw?: boolean }.
  • Return Type: Promise<CleanCourse[] | any>

• getIcalUrl()

  • Description: Generates an iCal calendar link for syncing tables.
  • Return Type: Promise<string>

🚷 Absences (client.absences)

• getAbsences(options?)

  • Description: Fetches school life data (absences, delays, sanctions, etc.).
  • Parameters:
    • options?: BaseModuleOptions: { raw?: boolean }.
  • Return Type: Promise<CleanAbsence[] | any>

📰 Timeline (client.timeline)

• getStudentTimeline(options?)

  • Description: Retrieves timeline events, grades releases, and news items.
  • Parameters:
    • options?: BaseModuleOptions: { raw?: boolean }.
  • Return Type: Promise<CleanTimelineEvent[] | any>

• getCommonTimeline(options?)

  • 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>

📁 Documents (client.documents)

• getDocuments(options?)

  • 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, and entreprises.

☁️ Cloud (client.cloud)

• getCloudFiles(depth?, options?)

  • Description: Retrieves cloud folders and files.
  • Parameters:
    • depth?: number (optional): Max folder traversal depth. Defaults to 3.
    • options?: BaseModuleOptions: { raw?: boolean }.
  • Return Type: Promise<CleanCloudNode[] | any>

• createFolder(parentPath, folderName)

  • Description: Creates a new subdirectory.
  • Parameters:
    • parentPath: string: Path of the parent directory.
    • folderName: string: Name of the new folder.
  • Return Type: Promise<any>

• copyNodes(parentPath, nodes)

  • 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>

• deleteNodes(nodes)

  • Description: Soft deletes specified files or folders.
  • Parameters:
    • nodes: any[]: Array of nodes to delete.
  • Return Type: Promise<any>

• restoreNodes(nodes)

  • Description: Restores deleted nodes from recycle bin.
  • Parameters:
    • nodes: any[]: Array of nodes to restore.
  • Return Type: Promise<any>

• moveNodes(parentPath, nodes)

  • Description: Moves nodes into a directory.
  • Parameters:
    • parentPath: string: Destination folder path.
    • nodes: any[]: Array of nodes to move.
  • Return Type: Promise<any>

• exportToCloud(fileId, module)

  • 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>

• uploadFile(destPath, fileData, fileName)

  • 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>

• downloadFile(params)

  • 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>

⚙️ Settings (client.settings)

• updateIndividualParam(value)

  • Description: Updates visual accessibility preferences.
  • Parameters:
    • value: string: State value.
  • Return Type: Promise<void>

• updateAccountSettings(data)

  • 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>

• getAccountSettings(idLogin?)

  • 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>

⚠️ Error Handling

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 |

📊 Data Types (Cleaned)

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

interface WrapDirecteOptions {
  appName?: string;
  appVersion?: string;
}

interface LoginResult {
  status: 'SUCCESS' | '2FA_REQUIRED';
  token: string;
  accounts?: CleanAccount[];
  faProof?: string;
  challenge?: {
    question: string;
    proposals: string[];
  };
}

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

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

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

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

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

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

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

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

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

🧪 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.