Papillon ED Core - Documentation

papillon-ed-core est le module qui permet la connexion entre Ecoledirecte et Papillon. Il contient des morceaux de code réutilisable qui permettent de récupérer les données scolaires. C'est l'intermédiaire entre Ecoledirecte et IndexDataInstance, qui permet l'affichage des données dans Papillon.

Github

Le répo du module est disponible sur Github .

EcoleDirecte est une marque déposée de la société Aplim . Papillon n'est pas affilié à EcoleDirecte et à Aplim.

Guide de l'utilisateur

Ce guide vous permet de comprendre comment fonctionne ce module et comment vous pouvez l'utiliser.

Ce projet est développé en Typescript, il est compatible avec toutes les technologies Javascript et fonctionne avec npm 18 !

Installation

Node Package Manager

Le module est disponible sur npmjs.com sous le nom de @papillonapp/ed-core.

npm i @papillonapp/ed-core

Utilisation

Ce module utilise des fonctions asynchrones pour fonctionner.

1. Importer le module

import { EDCore } from "@papillonapp/ed-core";

2. Initialiser le module

const ED = new EDCore()

3. S'authentifier

Merci de vous référer à la section authentification.

await ED.auth.login("username", "password", "uuidv4")

[TIP] Pour générer un UUIDv4, vous pouvez utiliser le module uuid, par défaut installé:
import { v4 as uuidv4 } from 'uuid';
const uuid = uuidv4()
await ED.auth.login("username", "password", uuid)

4. Visitez la documentation

Désormais connecté, il vous faudra lire la documentation des références pour comprendre et utiliser chaque fonctionnalité.

Des exemples sont aussi écrits dans examples/. Ajoutez vos identifiants dans examples/login.ts et tester les fonctionnalités avec ts-node examples/<fichier>.ts

Il existe aussi des documentations plus précises sur certaines fonctionnalités : - Commandes - Téléchargements

Authentification

Cette section est dédiée à l'authentification, et vous permettra de comprendre plus précisément les différents modes d'authentification et leurs différences...

L'authentification est accessible ainsi :

ED.auth

Vous pouvez vous authentifier de plusieurs manières : - ~~Classique; équivalent à une connexion depuis un navigateur.~~ (abandonné) - Mobile ou permanante; équivalent à une authentification depuis l'application mobile Ecoledirecte. - Token; déconseillée, vous vous connectez avec un token Ecoledirecte, vous devez donc assurer le renouvellement de celui-ci vous-même.

[!CAUTION] Authentification à facteurs ! Depuis Avril 2024, Ecoledirecte a mis en place une authentification à facteurs, avec un QCM pour sécuriser les connexions... Veuillez lire À double facteurs

Permanante

Depuis la version 0.2.7, la connexion permanante, permettant de renouveler le token est utilisée par défaut par ed-core.

Elle correspond à une authentification depuis l'application Ecoledirecte mobile. Vous aurez besoin de générer un UUIDv4, qui sera l'identifiant unique de votre "session" et permettra le renouvellement du token.

import { v4 as uuidv4 } from 'uuid';
import { EDCore } from "@papillonapp/ed-core";

const uuid = uuidv4()
await ED.auth.login("username", "password", uuid)

Quand une erreur de code 12 apparait, c'est que la double authentification est nécessaire.

Token

L'authentification par token permet de se connecter à Ecoledirecte avec un token généré par vos soins.

const userId = 0000
ED.setToken('token', userId)

L'identifiant de l'utilisateur est nécessaire.

À double facteurs

Quand une erreur de code 12 est renvoyée, vous devez répondre à des questions pour vous authentifier...

Il est conseillé de lire examples/login.ts pour voir une implémentation de cette double authentification

Récupérer le jeton de la double authentification

const token = await ED.auth.get2FAToken("username", "password")

Récupérer le questionnaire

const QCM = await ED.auth.get2FA(token)
QCM.question // La question
QCM.propositions // Les réponses possibles

Envoyer la réponse

const authFactors = await ED.auth.resolve2FA("La réponse") // Renvoie un objet utilisé pour s'authentifier

S'authentifier avec les facteurs

await ED.auth.login("username", "password", "uuid", authFactors)

Commandes

[!WARNING] Le module de commande est encore instable !

Ce module est accessible ainsi :

ED.orders

Une commande s'effectue ainsi: 1. Séléction du point de passage 2. Séléction des articles et envoi de la commande

Pour récupérer les anciennes commandes et les "points de passage" (lieux ; cafétéria, food truck);
```
ED.orders.fetchOrders()
```
Renvoie ordersResData
Pour initier une commande (correspond séléction d'un point de passage);
```
ED.orders.startOrder(1, "2024-01-01")
```
Renvoie startOrderResData

Pour envoyer, passer une commande;

const articles = [
  {
    code: "BEI-POM",
    libelle: "Beignet Pomme",
    description: "string;",
    estFormule: false,
    etat: 0,
    img: "",
    montant: 1.5,
    quantite: 1,
    quantiteMax: 3,
    estObligatoire: false,
    ordre: 1
  }
]
ED.orders.order(articles, "12:00", "2024-01-01", 1)

Renvoie orderPlacedResData

Pour supprimer une commande;
```
ED.orders.deleteOrder(100)
```
Renvoie une réponse vide

Téléchargements

À plusieurs endroits vous pourrez être amené à devoir télécharger des documents (exemple: documents administratifs renvoyés par ED.documents).

Le module ED.downloads vous permet donc de récupérer des objets de ces documents:

ED.downloads.getFileBlob(1235, "ADMINISTRATIF")

Ceci renvoie le blob du document administratif à l'identifiant 1235

Exemple avec une année:

ED.downloads.getFileBlob(1235, "ADMINISTRATIF", "2022-2023")

Ceci renvoie le blob du document administratif de l'année 2022-2023 à l'identifiant 1235

Exemple avec base64:

ED.downloads.getFileBase64(1235, "ADMINISTRATIF", "2022-2023")

Ceci renvoie le fichier sous format base64 (pour le técharger par exemple)

Voici tous les types de documents supportés:

type fileType = "CLOUD" | "FICHIER_CDT" | "PIECE_JOINTE" | "FICHIER_MENU_RESTAURATION" | "ADMINISTRATIF";

- "CLOUD"; l'argument fileId sera le chemin complet du document dans le cloud. - "FICHIER_CDT"; télécharger un fichier du Cahier De Texte. - "PIECE_JOINTE"; télécharger une pièce jointe (si le message provient d'une année antérieur, l'argument year devra contenir l'année). - "FICHIER_MENU_RESTAURATION"; télécharger un menu (voir Menu dans getCantine.ts). - "ADMINISTRATIF"; télécharger un fichier administratif (si le document provient d'une année antérieur, l'argument year devra contenir l'année).

Références

[!NOTE] Des exemples sont disponibles dans exemples/

Les références sont données ainsi:

Propriété	Type	Commentaire
nom	`undefined \\| string`

Certains types ont des liens hypertextes vers la référence du type.
Certains liens renvoient vers le fichier de définition du type.
Le signe ? désigne que la valeur peut être non-définie !
Si la propriété est une fonction, le type est (arg: type) => type.
Si la fonction est async, elle renvoie une Promise<type>

EDCore

La classe principale du module.

Propriété	Type	Commentaire
homeworks	`GetHomeworks`	Gestion des devoirs
grades	`GetGrades`	Gestion des notes
timetable	`GetTimetable`	Gestion de l'EDT
schoolLife	`GetSchoolLife`	Gestion de la vie scolaire
cantine	`GetCantine`	Gestion de la cantine
digitalManuals	`GetDigitalManuals`	Gestion des manuels numériques
messaging	`GetMessaging`	Gestion des messages
timeline	`GetTimeline`	Gestion des timeline
documents	`GetDocuments`	Gestion des document administratifs
forms	`GetForms`	Gestion des formulaires
workspaces	`GetWorkspaces`	Gestion des espaces de travail
communicationBook	`GetCommunicationBook`	Gestion du carnet de correspondance
cloud	`GetCloud`	Gestion du cloud
orders	`GetOrders`	Gestion des commandes
esidoc	`GetOrders`	Gestion du module Esidoc
downloads	`GetDownloads`	Gestion des téléchargements

auth	`Auth`	Gestion de l'authentification
request	`Request`	Gestion du requêtage

_token	`string` \| `undefined`	Token
isLoggedIn	`boolean`	L'utilisateur est-il connecté
settings?	`accountParameters` \| `undefined`	Paramètres de l'utilisateur
student	`account` \| `BlankAccount`	Profil de l'utilisateur
school?	`EstablishmentInfo`	Informations de l'établissement
modules?	`Array<accountModule`)`>`	Modules activés

Ouvrir src/session.ts

GetHomeworks

La classe de gestion des devoirs.

Propriété	Type	Commentaire
fetch()	`async () =>textbookResData`	Récupérer les devoirs
getByDay()	`async (day: string, removeHTMLTags: boolean) =>textbookResDateData`	Récupérer les devoirs du jour `day` (day est formaté `YYYY-MM-DD`). `removeHTMLTags` permet de renvoyer le contenu des devoirs sans balises HTML.

Ouvrir src/fetch/getHomeworks.ts

GetGrades

La classe de gestion des notes.

Propriété	Type	Commentaire
fetch()	`async () =>gradesResData`	Récupérer les notes

Ouvrir src/fetch/getGrades.ts

GetTimetable

La classe de gestion de l'EDT. Les jours sont formatés YYYY-MM-DD.

Propriété	Type	Commentaire
fetchByDay()	`async (day: string) =>timetableCourseList`	Récupérer l'EDT du jour `day`
fetchByDate()	`async (starteDate: string, endDate: string) =>timetableCourseList`	Récupérer l'EDT des jours `startDate` à `endDate`

Ouvrir src/fetch/getTimetable.ts

GetSchoolLife

La classe de gestion de la vie scolaire

Propriété	Type	Commentaire
fetch()	`async () =>schoolLifeRes`	Récupérer tous les évenements de vie scolaire

Ouvrir src/fetch/getSchoolLife.ts

GetCantine

La classe de gestion des modules de cantine.

Propriété	Type	Commentaire
getBarcode()	`() => string`	Renvoie la valeur du code-barre du badge
getReservations()	`() =>` `modStudReservations.params`	Renvoie les paramètres module de réservation
fetchSchoolMenu()	`() => Array<Menu>`	Renvoie la liste des menus

Ouvrir src/fetch/getCantine.ts

GetDigitalManuals

La classe de gestion des manuels scolaires.

Propriété	Type	Commentaire
fetch()	`async () =>` `manualsRes`	Récupérer les manuels scolaires

Ouvrir src/fetch/getDigitalManuals.ts

GetMessaging

La classe de gestion de la messagerie.

Propriété	Type	Commentaire
fetchReceivedMessages()	`async () =>` `mailboxResData`	Récupérer les messages reçus (`data.messages.received` sera rempli, les autres vides)
fetchSentMessages()	`async () =>` `mailboxResData`	Récupérer les messages envoyés (`data.messages.sent` sera rempli, les autres vides)

Ouvrir src/fetch/getMessaging.ts

GetTimeline

La classe de gestion des timeline.

Propriété	Type	Commentaire
fetch()	`async () => Array<studTlElem>`	Récupérer la timeline personnelle.
fetchCommonTimeline()	`async () =>` `studCommonTlResData`	Récupérer la timeline commune

Ouvrir src/fetch/getTimeline.ts

GetDocuments

La classe de gestion des documents administratifs.

[!CAUTION] Non testé, si vous pouvez tester, merci de nous contacter

Propriété	Type	Commentaire
fetch()	`async (archive: string) =>studentDocsResData`	Récupérer les documents administratifs. `archive` est une année scolaire `YYYY-YYY` (eg. `2023-2024`).

Ouvrir src/fetch/getDocuments.ts

GetForms

La classe de gestion des formulaires.

[!CAUTION] Non testé, si vous pouvez tester, merci de nous contacter

Propriété	Type	Commentaire
fetch()	`async (annee: string) => Array<form>`	Récupérer les formulaires de l'année. `annee` est une année scolaire `YYYY-YYY` (eg. `2023-2024`).

Ouvrir src/fetch/getForms.ts

GetWorkspaces

La classe de gestion des espaces de travail.

[!CAUTION] Non testé, si vous pouvez tester, merci de nous contacter

Propriété	Type	Commentaire
fetch()	`async () => Array<workspace>`	Récupérer les espaces de travail.
get()	`async (id: string) =>workspace`	Récupérer l'espace de travail avec l'identifiant `id`.
getDiary()	`async (espaceId: string) =>diaryResData`	Récupérer l'agenda (les évènements) de l'espace de travail avec l'identifiant `espaceId`.
getTopics()	`async (espaceId: string) =>topicsResData`	Récupérer les discussions de l'espace de travail avec l'identifiant `espaceId`.
getMembers()	`async (espaceId: string) =>workspace`	Récupérer les membres de l'espace de travail avec l'identifiant `espaceId`.
join()	`async (espace:workspace) =>membersResData`	Rejoindre l'espace de travail `espace`.
leave()	`async (espace: number) =>emptyRes`	Quitter l'espace de travail avec l'identifiant `id`.

Ouvrir src/fetch/getWorkspaces.ts

GetCommunicationBook

La classe de gestion du carnet de liaison.

[!CAUTION] Non testé, si vous pouvez tester, merci de nous contacter

Propriété	Type	Commentaire
fetch()	`async () => Array<communicationBookResData>`	Récupérer les événements du carnet de liaison.

Ouvrir src/fetch/getCommunicationBook.ts

GetCloud

La classe de gestion du cloud.

[!CAUTION] Non testé, si vous pouvez tester, merci de nous contacter

Propriété	Type	Commentaire
fetch()	`async () => Array<cloudResFolder>`	Récupérer les fichiers du cloud.

Ouvrir src/fetch/getCloud.ts

GetOrders

La classe de gestion des commandes.

[!WARNING] Module instable.

Point de passage signifie le lieux où la commande est passée (cafétéria par exemple). Il possède un id.

Propriété	Type	Commentaire
isEnabled()	`() => boolean`	Permet de savoir si le module est activé.
fetchOrders()	`async () =>ordersResData\\| undefined`	Récupérer les points de passages et commandes passées.
startOrder()	`async (placeId: number, date: string) =>startOrderResData`	Récupérer les informations du point de passage `placeId` à la date `date`.
order()	`async (articles: Array<detailedArticle>, hour: string, date: string, placeId: number) =>orderPlacedResData`	Passe une commande des article `articles`, pour `date`, `heure` au point de passage `placeId`.
deleteOrder()	`async (orderId: number) =>emptyRes`	Annule la commande à l'identifiant `orderId`.

Ouvrir src/fetch/getOrders.ts

GetEsidoc

La classe de gestion du module Esidoc.

Propriété	Type	Commentaire
isEnabled()	`() => boolean`	Permet de savoir si le module est activé.
getParams()	`async () =>modStudEsidoc.params.tabParams\\| undefined`	Récupérer les paramètres d'Esidoc.

Ouvrir src/fetch/getEsidoc.ts

GetDownloads

La classe de gestion des téléchargements.

fileType

type fileType = "CLOUD" | "FICHIER_CDT" | "PIECE_JOINTE" | "FICHIER_MENU_RESTAURATION" | "ADMINISTRATIF";

Propriété	Type	Commentaire
getFileBlob()	`async (fileId: number \\| string, fileType:fileType) => Blob`	Récupère le blob du fichier `fileId` (voir Télécharger des fichiers).
getFileBase64()	`async (fileId: number \\| string, fileType:fileType) => string`	Récupère le fichier `fileId` (voir Télécharger des fichiers) sous forme base64.

Ouvrir src/fetch/getDownloads.ts

Auth

La classe de gestion de l'authentification et de l'utilisateur.

Voir s'authentifier avec ed-core

Propriété	Type	Commentaire
login()	`async (username: string, password: string, uuid: string, fa?: object) => void`	Se connecte à Ecoledirecte avec des identifiants. `uuid` est un UUIDv4 utilisé pour reconnaitre l'appareil et regénérger un token. Lisez le guide pour savoir comment le générer. `fa` est l'objet contenant les facteurs d'authentification de `resolve2FA()`
renewToken()	`async (username: string, uuid: string, accessToken: string) => void`	Régénère un token à l'aide du nom d'utilisateur, de l'`uuid` et de l'`accessToken` et remplace automatiquement le token actuel.
setToken()	`(token: string, id: number) => boolean`	Se connecte à Ecoledirecte avec un token.
get2FAToken()	`async (username: string, password: string) => string`	Renvoie le jeton nécessaire à la récupération du QCM 2FA.
get2FA()	`async (token: string) =>doubleauthResData`	Récupère le questionnaire 2FA avec le token de `get2FAToken()`.
resolve2FA()	`async (answer: string) =>doubleauthValidationResData`	Renvoie les facteurs permettant l'uthentification.

Ouvrir src/auth.ts

Request

La classe de gestion des requêtes.

Propriété	Type	Commentaire
post()	`async (url: string, body: string, params?: string, ignoreErrors: boolean = false) => object`	Exécute la requête à l'API ecoledirect (path: `url`, body: `body`, les données utiles transférées à Ecoledirecte , paramètres d'url `params` et pour obtenir tout les réponses, même les erreurs Ecoledirecte, passer `ignoreErrors` à `true`) avec comme paramètre verbe=get. Renvoie la réponse sous forme d'un object JSON
get()	`async (url: string, body: string, params?: string, ignoreErrors: boolean = false) => object`	Exécute la requête à l'API ecoledirect (path: `url`, body: `body`, les données utiles transférées à Ecoledirecte , paramètres d'url `params` et pour obtenir tout les réponses, même les erreurs Ecoledirecte, passer `ignoreErrors` à `true`) avec comme paramètre verbe=post. Renvoie la réponse sous forme d'un object JSON
delete()	`async (url: string, body: string, params?: string, ignoreErrors: boolean = false) => object`	Exécute la requête à l'API ecoledirect (path: `url`, body: `body`, les données utiles transférées à Ecoledirecte , paramètres d'url `params` et pour obtenir tout les réponses, même les erreurs Ecoledirecte, passer `ignoreErrors` à `true`) avec comme paramètre verbe=delete. Renvoie la réponse sous forme d'un object JSON
put()	`async (url: string, body: string, params?: string, ignoreErrors: boolean = false) => object`	Exécute la requête à l'API ecoledirect (path: `url`, body: `body`, les données utiles transférées à Ecoledirecte , paramètres d'url `params` et pour obtenir tout les réponses, même les erreurs Ecoledirecte, passer `ignoreErrors` à `true`) avec comme paramètre verbe=put. Renvoie la réponse sous forme d'un object JSON
request()	`async (url: string, body: string, ignoreErrors: boolean = false) => object`	Exécute une requête (url: `url`, body: `body` et pour obtenir tout les réponses, même les erreurs Ecoledirecte, passer `ignoreErrors` à `true`). Renvoie la réponse sous forme d'un object JSON
blob()	`async (url: string, body: string, completeUrl: boolean = false, method: "GET" \\| "POST" = "GET") => Blob`	Exécute la requête et renvoie un objet Blob. `completeUrl` sur `true` indiquera que `url` est la cible complète, pas un chemin de `https://api.ecoledirecte.com`

Ouvrir src/Request.ts

Guide du développeur

Ce guide vous permet de comprendre comment ce module est développé et donc d'y contribuer !

Ce projet est développé en Typescript. Vous devez maitriser ce languages ainsi que le développement de modules NodeJs pour commencer.

Installation

[!NOTE] Si vous souhaitez contribuer ou modifier le code, veuillez fork le dépot et cloner votre copie de celui-ci.

1. Cloner ce dépôt

git clone https://github.com/PapillonApp/Papillon-ED-Core

2. Installer les dépendances

npm install

3. Récupérer les submodules

git submodule update --init --recursive

[!NOTE] Pour mettre à jour le submodule, exécutez
cd src/types && git pull

Et voilà, vous êtes prêts !

Structure

Le module est structuré de la manière suivante : - src/fetch : Contient les fonctions de récupération des données de l'API d'EcoleDirecte - src/session.ts : Contient les fonctions de gestion de la session - src/auth.ts : Contient les fonctions d'authentification - src/errors.ts : Contient les erreurs pouvant être retournées par le module. Les erreurs doivent suivre la même structure pour chaque module. - src/types: Submodule git des types des réponses ED. (réadaptation de Armand CAMPONOVO, travail original ab2r) - src/utils/types: Contient les types des data requêtes, et des types utiles à ce module.

Scripts

Linter: eslint

npm run lint

Vous pouvez aussi exécuter npm run lint:fix pour régler les problèmes de formatage automatiquement.

Build: tsc

Les fichiers transpilés sont généré à leur emplacement. Ce script lint et build la base de code.

npm run build