Skip to content

Latest commit

 

History

History
577 lines (407 loc) · 43.3 KB

DOCUMENTATION.md

File metadata and controls

577 lines (407 loc) · 43.3 KB

Papillon ED Core - Documentation

Sommaire

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. Fonctionne avec npm 18 !

Installation

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és, 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 :

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

  1. Récupérer le jeton de la double authentification
const token = await ED.auth.get2FAToken("username", "password")
  1. Récupérer le questionnaire
const QCM = await ED.auth.get2FA(token)
QCM.question // La question
QCM.propositions // Les réponses possibles
  1. Envoyer la réponse
const authFactors = await ED.auth.resolve2FA("La réponse") // Renvoie un objet utilisé pour s'authentifier
  1. 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 envoie 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és à 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 joint (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 jout 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 jour 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 évenements do 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 trasnfé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 trasnfé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 trasnfé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 trasnfé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