Support non officiel de l'API Skolengo. Il s'agit de l'API utilisée par la nouvelle application mobile éponyme. Ce module permet de récupérer les données de l'ENT de manière automatique. De plus, certaines fonctions implémentées permettent de prétraiter les données (conversion de l'emploi du temps au format iCalendar par exemple).
Ce module est destiné à devenir le successeur de kdecole-api dans l'éventualité où l'accès à l'ancienne API serait définitivement clos. Pour utiliser cette librairie, il est nécessaire de s'authentifier auprès des serveurs de Skolengo. Pour obtenir des jetons de connexion, vous pouvez utiliser scolengo-token.
Pour participer et se tenir informé, rejoins le serveur Discord: https://discord.gg/9u69mxsFT6
- Il est clairement mentionné que cette librairie est n'est pas officielle.
- Ce module n'est pas une contrefaçon car il n'existe pas de module similaire édité officiellement.
- Les utilisateurs ne peuvent accéder qu'à leurs propres données. Ils sont soumis au même processus d'authentification que celui implémenté dans l'application.
- Les données des utilisateurs ne sont pas davantage exposées puisqu'un utilisateur ne peut accéder qu'à ses propres données. Personne n'a le contrôle sur cette limitation qui est inhérente au fonctionnement de l'API des serveurs de Skolengo.
- Cette librairie ne se suffit pas à elle-même pour fonctionner. Il est nécessaire de l'importer dans un projet et l'utilisateur est le seul responsable de son code et des éventuelles conséquences.
- Tout utilisateur de cette librairie a a priori lu l'entièreté du fichier de licence GPLv3 disponible publiquement LICENSE ainsi que de ce présent fichier de présentation.
- Tout utilisateur de cette librairie a a priori lu l'entièreté du code de ce projet avant toute utilisation.
- Eu égard l'ensemble de ces remarques, les contributeurs et a fortiori l'auteur du projet ne peuvent être tenus comme responsables de tout dommage potentiel.
Un wiki est disponible, celui-ci rassemble davantage d'informations sur le fonctionnement de l'API. Ce wiki est disponible ici.
Kind: global class
- Skolengo
- new Skolengo(oidClient, school, tokenSet, config)
- instance
- .getUserInfo(userId, params, includes)
- .downloadAttachment(attachment)
- .getSchoolInfos(params, includes)
- .getSchoolInfo(schoolInfoId, params, includes)
- .getEvaluationSettings(studentId, limit, offset, params, includes)
- .getEvaluation(studentId, periodId, limit, offset, params, includes)
- .getEvaluationDetail(studentId, evaluationId, params, includes)
- .getPeriodicReportsFiles(studentId, limit, offset, params, includes)
- .getAgenda(studentId, startDate, endDate, limit, offset, params, includes)
- .getLesson(studentId, lessonId, params, includes)
- .getHomeworkAssignments(studentId, startDate, endDate, limit, offset, params, includes)
- .getHomeworkAssignment(studentId, homeworkId, params, includes)
- .patchHomeworkAssignment(studentId, homeworkId, attributes, params, includes)
- .getUsersMailSettings(userId, params, includes)
- .getCommunicationsFolder(folderId, limit, offset, params, includes)
- .getCommunication(communicationId, params)
- .getCommunicationParticipations(communicationId, params, includes)
- .getCommunicationParticipants(communicationId, fromGroup, params, includes)
- .patchCommunicationFolders(communicationId, folders, userId, params)
- .postCommunication(newCommunication, params)
- .postParticipation(participation, params)
- .getAbsenceFiles(studentId, limit, offset, params, includes)
- .getAbsenceFile(folderId, params, includes)
- .postAbsenceFileState(folderId, reasonId, comment, params)
- .getAbsenceReasons(limit, offset, params)
- static
Il est possible de s'authentifier en possédant au prélable des jetons OAuth 2.0
Param | Type | Description |
---|---|---|
oidClient | Client |
Un client OpenID Connect |
school | School |
Etablissement |
tokenSet | TokenSet |
Jetons d'authentification OpenID Connect |
config | SkolengoConfig |
Configuration optionnelle (stockage du jeton renouvellé, client HTTP personnalisé, gestion des erreurs Pronote, ...) |
Example
const {Skolengo} = require('scolengo-api')
// 🚨 ATTENTION: Ne communiquez jamais vos jetons à un tiers. Ils vous sont strictement personnels. Si vous pensez que vos jetons ont été dérobés, révoquez-les immédiatement.
// L'objet de configuration ci-dessous peut être généré à partir de l'utilitaire scolengo-token (https://github.com/maelgangloff/scolengo-token)
const config = {
"tokenSet": {
"access_token": "<access_token_here>",
"id_token": "<id_token_here>",
"refresh_token": "RT-<refresh_token_here>",
"token_type": "bearer",
"expires_at": 1234567890,
"scope": "openid"
},
"school": {
"id": "SKO-E-<school_id>",
"name": "<school_name>",
"addressLine1": "<school_address>",
"addressLine2": null,
"addressLine3": null,
"zipCode": "<school_zip_code>",
"city": "<school_city>",
"country": "France",
"homePageUrl": "<cas_login_url>",
"emsCode": "<school_ems_code>",
"emsOIDCWellKnownUrl": "<school_ems_oidc_well_known_url>"
}
}
Skolengo.fromConfigObject(config).then(async user => {
const infoUser = await user.getUserInfo()
console.log(`Correctement authentifié sous l'identifiant ${infoUser.id}`)
})
const {Skolengo, TokenSet} = require('scolengo-api')
Skolengo.searchSchool({ text: 'Lycée Louise Weiss' }).then(async schools => {
if(!schools.length) throw new Error('Aucun établissement n\'a été trouvé.')
const school = schools[0]
const oidClient = await Skolengo.getOIDClient(school)
// 🚨 ATTENTION: Ne communiquez jamais vos jetons à un tiers. Ils vous sont strictement personnels. Si vous pensez que vos jetons ont été dérobés, révoquez-les immédiatement.
const tokenSet = new TokenSet({
access_token: 'ACCESS_TOKEN',
id_token: 'ID_TOKEN',
refresh_token: 'REFRESH_TOKEN',
token_type: 'bearer',
expires_at: 1681486899,
scope: 'openid'
})
const user = new Skolengo(oidClient, school, tokenSet)
const infoUser = await user.getUserInfo()
console.log(`Correctement authentifié sous l'identifiant ${infoUser.id}`)
})
Informations sur l'utilisateur actuellement authentifié (nom, prénom, date de naissance, adresse postale, courriel, téléphone, permissions, ...)
Kind: instance method of Skolengo
Param | Type | Description |
---|---|---|
userId | string | undefined |
Identifiant de l'utilisateur |
params | object |
Modifier les paramètres de la requête |
includes | Array.<string> |
Ressources JSON:API à inclure |
Télécharger une pièce jointe.
Une pièce jointe peut être un fichier inclu dans un courriel, une actualité de l'établissement ou un bulletin périodique.
🚨 ATTENTION: Dans cette requête, votre jeton est envoyé à l'URL du fichier. Assurez-vous que celle-ci provient bien de votre établissement.
Kind: instance method of Skolengo
Param | Type | Description |
---|---|---|
attachment | Attachment |
La pièce jointe |
Example
const {createWriteStream} = require('node:fs')
const {Skolengo} = require('scolengo-api')
Skolengo.fromConfigObject(config).then(async user => {
const student = 'ESKO-P-b2c86113-1062-427e-bc7f-0618cbd5d5ec'
const bulletins = await user.getPeriodicReportsFiles(student)
for(const bulletin of bulletins) {
console.log(bulletin.name)
(await user.downloadAttachment(bulletin)).pipe(createWriteStream(bulletin.name));
}
})
Récupérer toutes les actualités de l'établissement
Kind: instance method of Skolengo
Param | Type | Description |
---|---|---|
params | object |
Modifier les paramètres de la requête |
includes | Array.<string> |
Ressources JSON:API à inclure |
Récupérer une actualité de l'établissement
Kind: instance method of Skolengo
Param | Type | Description |
---|---|---|
schoolInfoId | string |
Identifiant d'une actualité |
params | object |
Modifier les paramètres de la requête |
includes | Array.<string> |
Ressources JSON:API à inclure |
Statut des services d'évaluation (identifiant des périodes, ...)
Kind: instance method of Skolengo
Param | Type | Default | Description |
---|---|---|---|
studentId | string |
Identifiant d'un étudiant | |
limit | number |
20 |
Limite |
offset | number |
0 |
Offset |
params | object |
Modifier les paramètres de la requête | |
includes | Array.<string> |
Ressources JSON:API à inclure |
Récupérer les notes d'un étudiant sur une période
Kind: instance method of Skolengo
Param | Type | Default | Description |
---|---|---|---|
studentId | string |
Identifiant d'un étudiant | |
periodId | string |
Identifiant de la période de notation | |
limit | number |
20 |
Limite |
offset | number |
0 |
Offset |
params | object |
Modifier les paramètres de la requête | |
includes | Array.<string> |
Ressources JSON:API à inclure |
Récupérer le détail d'une note d'un étudiant
Kind: instance method of Skolengo
Param | Type | Description |
---|---|---|
studentId | string |
Identifiant d'un étudiant |
evaluationId | string |
Identifiant de la note |
params | object |
Modifier les paramètres de la requête |
includes | Array.<string> |
Ressources JSON:API à inclure |
Récupérer la liste des bilans périodiques disponibles pour un étudiant. Pour chaque bulletin, une adresse est disponible pour le téléchargement.
Kind: instance method of Skolengo
Param | Type | Default | Description |
---|---|---|---|
studentId | string |
Identifiant d'un étudiant | |
limit | number |
20 |
Limite |
offset | number |
0 |
Offset |
params | object |
Modifier les paramètres de la requête | |
includes | Array.<string> |
Ressources JSON:API à inclure |
Example
const {Skolengo} = require('scolengo-api')
Skolengo.fromConfigObject(config).then(async user => {
const bulletins = await getPeriodicReportsFiles('ESKO-P-xxxxxxxx-xxxx-xxxx-xxxx-xxxxxxxxxxx');
console.log(bulletins)
})
Récupérer l'agenda d'un étudiant. Il est possible de le convertir au format iCalendar.
Kind: instance method of Skolengo
Param | Type | Default | Description |
---|---|---|---|
studentId | string |
Identifiant d'un étudiant | |
startDate | string |
Date de début - Format : YYYY-MM-DD | |
endDate | string |
Date de fin - Format : YYYY-MM-DD | |
limit | number |
20 |
Limite |
offset | number |
0 |
Offset |
params | object |
Modifier les paramètres de la requête | |
includes | Array.<string> |
Ressources JSON:API à inclure |
Example
const { writeFileSync } = require('node:fs')
const { Skolengo } = require('scolengo-api')
Skolengo.fromConfigObject(config).then(async user => {
const studentId = 'ESKO-P-xxxxxxxx-xxxx-xxxx-xxxx-xxxxxxxxxxxx'
const agenda = await user.getAgenda(studentId, '2023-05-01', '2023-05-30')
writeFileSync('export.ics', agenda.toICalendar())
})
Récupérer les données d'un cours/leçon
Kind: instance method of Skolengo
Param | Type | Description |
---|---|---|
studentId | string |
Identifiant d'un étudiant |
lessonId | string |
Identifiant d'un cours/leçon |
params | object |
Modifier les paramètres de la requête |
includes | Array.<string> |
Ressources JSON:API à inclure |
Récupérer les devoirs d'un étudiant
Kind: instance method of Skolengo
Param | Type | Default | Description |
---|---|---|---|
studentId | string |
Identifiant d'un étudiant | |
startDate | string |
Date de début - Format : YYYY-MM-DD | |
endDate | string |
Date de fin - Format : YYYY-MM-DD | |
limit | number |
20 |
Limite |
offset | number |
0 |
Offset |
params | object |
Modifier les paramètres de la requête | |
includes | Array.<string> |
Ressources JSON:API à inclure |
Example
const {Skolengo} = require('scolengo-api')
Skolengo.fromConfigObject(config).then(async user => {
const startDate = new Date().toISOString().split('T')[0] // Aujourd'hui
const endDate = new Date(Date.now() + 15 * 24 * 60 * 60 * 1e3).toISOString().split('T')[0] // Aujourd'hui + 15 jours
const homework = await user.getHomeworkAssignments(user.tokenSet.claims().sub, startDate, endDate)
console.log("Voici les exercices à faire pour les 2 prochaines semaines :", homework)
})
Récupérer les données d'un devoir
Kind: instance method of Skolengo
Param | Type | Description |
---|---|---|
studentId | string |
Identifiant d'un étudiant |
homeworkId | string |
Identifiant du devoir |
params | object |
Modifier les paramètres de la requête |
includes | Array.<string> |
Ressources JSON:API à inclure |
Example
const {Skolengo} = require('scolengo-api')
const user = await Skolengo.fromConfigObject(config)
user.getHomeworkAssignment(user.tokenSet.claims().sub, "123456").then(e => {
console.log(`Pour le ${new Date(e.dueDateTime).toLocaleString()} :`)
console.log(`> ${e.title} (${e.subject.label})`)
console.log(e.html)
})
Modifier le statut d'un travail à faire
Kind: instance method of Skolengo
Param | Type | Description |
---|---|---|
studentId | string |
Identifiant d'un étudiant |
homeworkId | string |
Identifiant d'un devoir à modifier |
attributes | Partial.<HomeworkAssignment> |
Devoir modifié |
params | object |
Modifier les paramètres de la requête |
includes | Array.<string> |
Ressources JSON:API à inclure |
Example
const {Skolengo} = require('scolengo-api')
const user = await Skolengo.fromConfigObject(config)
user.patchHomeworkAssignment('ESKO-P-xxxxxxxx-xxxx-xxxx-xxxx-xxxxxxxxxxxx', '123456', { done: true }).then(hmw => {
console.log(`Le travail "${hmw.title}" a été marqué ${hmw.done ? 'fait' : 'à faire'}.`)
})
Récupérer les informations du service de communication (identifiants des dossiers, ...)
Kind: instance method of Skolengo
Param | Type | Description |
---|---|---|
userId | string | undefined |
Identifiant d'un utilisateur |
params | object |
Modifier les paramètres de la requête |
includes | Array.<string> |
Ressources JSON:API à inclure |
Récupérer les communication d'un dossier
Kind: instance method of Skolengo
Param | Type | Default | Description |
---|---|---|---|
folderId | string |
Identifiant d'un dossier | |
limit | number |
10 |
Limite |
offset | number |
0 |
Offset |
params | object |
Modifier les paramètres de la requête | |
includes | Array.<string> |
Ressources JSON:API à inclure |
Récupérer une communication à partir de son identifiant
Kind: instance method of Skolengo
Param | Type | Description |
---|---|---|
communicationId | string |
Identifiant d'une communication |
params | object |
Modifier les paramètres de la requête |
Récupérer les participations d'un fil de discussion (communication)
Kind: instance method of Skolengo
Param | Type | Description |
---|---|---|
communicationId | string |
Identifiant d'une communication |
params | object |
Modifier les paramètres de la requête |
includes | Array.<string> |
Ressources JSON:API à inclure |
Récupérer tous les participants d'un fil de discussion (communication)
Kind: instance method of Skolengo
Param | Type | Default | Description |
---|---|---|---|
communicationId | string |
Identifiant d'une communication | |
fromGroup | boolean |
true |
Afficher le détail des groupes |
params | object |
Modifier les paramètres de la requête | |
includes | Array.<string> |
Ressources JSON:API à inclure |
Déplacer une communication dans un dossier
Kind: instance method of Skolengo
Param | Type | Description |
---|---|---|
communicationId | string |
Identifiant d'une communication |
folders | Liste contenant l'identifiant du dossier | |
userId | string | undefined |
Identifiant de l'utilisateur |
params | object |
Modifier les paramètres de la requête |
Envoyer un message dans un nouveau fil de discussion
Kind: instance method of Skolengo
Param | Type | Description |
---|---|---|
newCommunication | Partial.<Communication> |
La nouvelle communication |
params | object |
Modifier les paramètres de la requête |
Envoyer un message dans un fil de discussion existant
Kind: instance method of Skolengo
Param | Type | Description |
---|---|---|
participation | Partial.<Participation> |
La nouvelle participation |
params | object |
Modifier les paramètres de la requête |
Récupérer les absences et retards d'un étudiant. Il est possible d'exporter les absences au format CSV.
Kind: instance method of Skolengo
Param | Type | Default | Description |
---|---|---|---|
studentId | string |
Identifiant d'un étudiant | |
limit | number |
20 |
Limite |
offset | offset |
0 |
Offset |
params | object |
Modifier les paramètres de la requête | |
includes | Array.<string> |
Ressources JSON:API à inclure |
Example
const { writeFileSync } = require('node:fs')
const { Skolengo } = require('scolengo-api')
Skolengo.fromConfigObject(config).then(async user => {
const studentId = 'ESKO-P-xxxxxxxx-xxxx-xxxx-xxxx-xxxxxxxxxxxx'
const absenceFiles = await user.getAbsenceFiles(studentId)
writeFileSync('export.csv', agenda.toCSV())
})
Récupérer les détails d'une absence
Kind: instance method of Skolengo
Param | Type | Description |
---|---|---|
folderId | string |
Identifiant d'un dossier |
params | object |
Modifier les paramètres de la requête |
includes | Array.<string> |
Ressources JSON:API à inclure |
Justifier une absence avec motif et commentaire. PS: La requête n'a pas été testée.
Kind: instance method of Skolengo
Param | Type | Description |
---|---|---|
folderId | string |
Identifiant d'un dossier |
reasonId | string |
Identifiant d'un motif |
comment | string |
Commentaire |
params | object |
Modifier les paramètres de la requête |
Récupérer la liste des motifs possibles d'absence. Cette liste peut être différente pour chaque établissement.
Kind: instance method of Skolengo
Param | Type | Default | Description |
---|---|---|---|
limit | number |
20 |
Limite |
offset | number |
0 |
Offset |
params | object |
Modifier les paramètres de la requête |
Example
const {Skolengo} = require('scolengo-api')
Skolengo.fromConfigObject(config).then(async user => {
user.getAbsenceReasons().then(response => {
console.log(`Liste des motifs: ${response.map(r => r.longLabel).join(';')}`)
})
})
Révoquer un jeton
Kind: static method of Skolengo
Param | Type | Description |
---|---|---|
oidClient | Client |
Un client OpenID Connect |
token | string |
Un jeton |
Configuration actuelle de l'application mobile (dernière version déployée, dernière version supportée, ...)
Kind: static method of Skolengo
Example
const {Skolengo} = require('scolengo-api')
Skolengo.getAppCurrentConfig().then(config => {
console.log(`Dernière version déployée: ${config.latestDeployedSkoAppVersion}`)
console.log(`Dernière version supportée: ${config.latestSupportedSkoAppVersion}`)
})
Rechercher un établissement scolaire
Kind: static method of Skolengo
Param | Type | Default | Description |
---|---|---|---|
filter | SchoolFilter |
Le filtre de recherche | |
limit | number |
10 |
Limite |
offset | number |
0 |
Offset |
Example
const {Skolengo} = require('scolengo-api')
Skolengo.searchSchool({ text: 'Lycée Louise Weiss' }).then(schools => {
console.log(schools)
})
Example
const {Skolengo} = require('scolengo-api')
Skolengo.searchSchool({ lat: 48.0, lon: 7.0 }).then(schools => {
console.log(schools)
})
Créer un client OpenID Connect permettant l'obtention des jetons (refresh token et access token)
Kind: static method of Skolengo
Param | Type | Default | Description |
---|---|---|---|
school | School |
L'établissement scolaire | |
redirectUri | string | undefined |
"skoapp-prod://sign-in-callback" |
Callback |
Example
const {Skolengo} = require('scolengo-api')
Skolengo.searchSchool({ text: 'Lycée Louise Weiss' }).then(async schools => {
if(!schools.length) throw new Error('Aucun établissement n\'a été trouvé.')
const school = schools[0]
const oidClient = await Skolengo.getOIDClient(school, 'skoapp-prod://sign-in-callback')
console.log(oidClient.authorizationUrl())
// Lorsque l'authentification est effectuée, le CAS redirige vers le callback indiqué avec le code. Ce code permet d'obtenir les refresh token et access token (cf. mécanismes OAuth 2.0 et OID Connect)
})
const {Skolengo} = require('scolengo-api')
Skolengo.searchSchool({ text: 'Lycée Louise Weiss' }).then(async schools => {
if(!schools.length) throw new Error('Aucun établissement n\'a été trouvé.')
const school = schools[0]
const oidClient = await Skolengo.getOIDClient(school, 'skoapp-prod://sign-in-callback')
const params = oidClient.callbackParams('skoapp-prod://sign-in-callback?code=OC-9999-xxxxxxxxxxxxxxxxxxxxxxxxxxxxxx-X')
const tokenSet = await oidClient.callback('skoapp-prod://sign-in-callback', params)
// 🚨 ATTENTION: Ne communiquez jamais vos jetons à un tiers. Ils vous sont strictement personnels. Si vous pensez que vos jetons ont été dérobés, révoquez-les immédiatement.
const user = new Skolengo(oidClient, school, tokenSet)
const infoUser = await user.getUserInfo()
console.log(`Correctement authentifié sous l'identifiant ${infoUser.id}`)
})
Créer un client Scolengo à partir d'un objet contenant les informations d'authentification.
Cet objet de configuration peut être généré à partir de l'utilitaire scolengo-token.
La fonction onTokenRefresh
est appellée lors du rafraichissement du jeton (pour éventuellement stocker en mémoire le nouveau tokenSet).
Kind: static method of Skolengo
Param | Type | Description |
---|---|---|
config | AuthConfig |
Informations d'authentification |
skolengoConfig | SkolengoConfig |
Configuration optionnelle (stockage du jeton renouvellé, client HTTP personnalisé, gestion des erreurs Pronote, ...) |
Example
const {Skolengo} = require('scolengo-api')
const config = require('./config.json')
const user = await Skolengo.fromConfigObject(config)
const {Skolengo} = require('scolengo-api')
// 🚨 ATTENTION: Ne communiquez jamais vos jetons à un tiers. Ils vous sont strictement personnels. Si vous pensez que vos jetons ont été dérobés, révoquez-les immédiatement.
const config = {
"tokenSet": {
"access_token": "<access_token_here>",
"id_token": "<id_token_here>",
"refresh_token": "RT-<refresh_token_here>",
"token_type": "bearer",
"expires_at": 1234567890,
"scope": "openid"
},
"school": {
"id": "SKO-E-<school_id>",
"name": "<school_name>",
"addressLine1": "<school_address>",
"addressLine2": null,
"addressLine3": null,
"zipCode": "<school_zip_code>",
"city": "<school_city>",
"country": "France",
"homePageUrl": "<cas_login_url>",
"emsCode": "<school_ems_code>",
"emsOIDCWellKnownUrl": "<school_ems_oidc_well_known_url>"
}
}
Skolengo.fromConfigObject(config).then(async user => {
const infoUser = await user.getUserInfo()
console.log(`Correctement authentifié sous l'identifiant ${infoUser.id}`)
})