maelgangloff / scolengo-api

Unofficial Node.js API client of Skolengo EMS v2

scolengo-api

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.

Tip

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

Disclaimer

Warning

• Il est clairement mentionné que cette librairie n'est pas officiellement éditée par la société éditrice du logiciel Skolengo.
• 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 et imposé par le serveur API.
• 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 et approuvé 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 et compris l'entièreté du code de ce projet avant toute utilisation.
• L'auteur de ce projet n'agit pas en tant qu'intermédiaire de traitement des données au sens du RGPD. Les utilisateurs sont responsables de leur propre conformité au RGPD lors de l'utilisation de cette librairie. Ils doivent s'assurer que leur utilisation de cette librairie est conforme aux exigences du RGPD et de toute autre législation applicable en matière de protection des données.
• Eu égard l'ensemble de ces remarques, les contributeurs et a fortiori l'auteur du projet ne peuvent être tenus responsables de tout dommage potentiel.

Liste des ENT utilisant Skolengo :

Nom usuel de l'ENT	Code ENT	URL OpenID Connect Discovery
Mon Bureau Numérique	gdest	https://sso.monbureaunumerique.fr/oidc/.well-known
Mon ENT Occitanie	entmip	https://sso.mon-ent-occitanie.fr/oidc/.well-known
Arsène 76	cg76	https://sso.arsene76.fr/oidc/.well-known
ENT27	cg27	https://sso.ent27.fr/oidc/.well-known
ENT Creuse	cg23	https://sso.entcreuse.fr/oidc/.well-known
ENT Auvergne-Rhône-Alpes	rra	https://sso.ent.auvergnerhonealpes.fr/oidc/.well-known
Agora 06	cg06	https://sso.agora06.fr/oidc/.well-known
CyberCollèges 42	cg42	https://sso.cybercolleges42.fr/oidc/.well-known
eCollège 31 Haute-Garonne	cg31	https://sso.ecollege.haute-garonne.fr/oidc/.well-known
Mon collège en Val d'Oise	cg95	https://sso.moncollege.valdoise.fr/oidc/.well-known
Webcollège Seine-Saint-Denis	cg93	https://sso.webcollege.seinesaintdenis.fr/oidc/.well-known
Eclat-BFC	bfc	https://sso.eclat-bfc.fr/oidc/.well-known
@ucollège84	cg84	https://sso.aucollege84.vaucluse.fr/oidc/.well-known
ENT Val de Marne	cg94	https://sso.moncollege.valdemarne.fr/oidc/.well-known
Skolengo-Écoles primaires	metab1d	https://sso.skolengo.com/oidc/.well-known
Skolengo-Collèges et Lycées	mpdl	https://sso.pdl.kosmoseducation.com/oidc/.well-known
AEFE	metab	https://sso1.skolengo.com/oidc/.well-known
AEFE Amérique - Pacifique	metabam	https://sso2.skolengo.com/oidc/.well-known
Schulportal Ostbelgien	cgb	https://sso.schulen.be/oidc/.well-known

Un wiki est disponible, celui-ci rassemble davantage d'informations sur le fonctionnement de l'API. Ce wiki est disponible ici.

Skolengo

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)
    • .refreshToken(triggerListener)
    • .getTokenClaims()
  • static
    • .revokeToken(oidClient, token)
    • .getAppCurrentConfig(httpConfig)
    • .searchSchool(filter, limit, offset, httpConfig)
    • .getOIDClient(school, redirectUri)
    • .fromConfigObject(config, skolengoConfig)

new Skolengo(oidClient, school, tokenSet, config)

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	TokenSetParameters	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} = require('scolengo-api')
const {TokenSet} = require('openid-client')

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}`)
})

skolengo.getUserInfo(userId, params, includes)

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

skolengo.downloadAttachment(attachment)

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.

Caution

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

skolengo.getSchoolInfos(params, includes)

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

skolengo.getSchoolInfo(schoolInfoId, params, includes)

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

skolengo.getEvaluationSettings(studentId, limit, offset, params, includes)

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

skolengo.getEvaluation(studentId, periodId, limit, offset, params, includes)

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

skolengo.getEvaluationDetail(studentId, evaluationId, params, includes)

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

skolengo.getPeriodicReportsFiles(studentId, limit, offset, params, includes)

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

skolengo.getAgenda(studentId, startDate, endDate, limit, offset, params, includes)

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())
})

skolengo.getLesson(studentId, lessonId, params, includes)

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

skolengo.getHomeworkAssignments(studentId, startDate, endDate, limit, offset, params, includes)

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.getTokenClaims().sub, startDate, endDate)

  console.log("Voici les exercices à faire pour les 2 prochaines semaines :", homework)
})

skolengo.getHomeworkAssignment(studentId, homeworkId, params, includes)

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.getTokenClaims().sub, "123456").then(e => {
    console.log(`Pour le ${new Date(e.dueDateTime).toLocaleString()} :`)
    console.log(`> ${e.title} (${e.subject.label})`)
    console.log(e.html)
})

skolengo.patchHomeworkAssignment(studentId, homeworkId, attributes, params, includes)

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'}.`)
})

skolengo.getUsersMailSettings(userId, params, includes)

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

skolengo.getCommunicationsFolder(folderId, limit, offset, params, includes)

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

skolengo.getCommunication(communicationId, params)

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

skolengo.getCommunicationParticipations(communicationId, params, includes)

Récupérer les participations d'un fil de discussion (communication) Marque la communication comme lue.

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

skolengo.getCommunicationParticipants(communicationId, fromGroup, params, includes)

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

skolengo.patchCommunicationFolders(communicationId, folders, userId, params)

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

skolengo.postCommunication(newCommunication, params)

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

skolengo.postParticipation(participation, params)

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

skolengo.getAbsenceFiles(studentId, limit, offset, params, includes)

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())
})

skolengo.getAbsenceFile(folderId, params, includes)

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

skolengo.postAbsenceFileState(folderId, reasonId, comment, params)

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

skolengo.getAbsenceReasons(limit, offset, params)

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(';')}`)
  })
})

skolengo.refreshToken(triggerListener)

Demande un renouvellement du jeu de jeton (tokenSet)

Kind: instance method of Skolengo

Param	Type	Default	Description
triggerListener	boolean	true	Si oui, appeler la fonction onTokenRefresh

skolengo.getTokenClaims()

Récupérer les données contenues dans le payload JWT du token ID

Kind: instance method of Skolengo

Skolengo.revokeToken(oidClient, token)

Révoquer un jeton

Kind: static method of Skolengo

Param	Type	Description
oidClient	Client	Un client OpenID Connect
token	string	Un jeton

Skolengo.getAppCurrentConfig(httpConfig)

Configuration actuelle de l'application mobile (dernière version déployée, dernière version supportée, ...)

Kind: static method of Skolengo

Param	Type	Description
httpConfig	AxiosRequestConfig | undefined	Configuration facultative du client HTTP

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}`)
})

Skolengo.searchSchool(filter, limit, offset, httpConfig)

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
httpConfig	AxiosRequestConfig | undefined		Configuration facultative du client HTTP

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

Skolengo.getOIDClient(school, redirectUri)

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}`)
})

Skolengo.fromConfigObject(config, skolengoConfig)

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. Le callback optionnel onTokenRefresh est appellé lors du rafraichissement du jeton (pour éventuellement stocker en mémoire le nouveau tokenSet). La callback optionnel tokenRefresh permet d'outrepasser l'utilisation de la librairie openid-client pour le rafraîchissement des jetons. La délégation de cette tâche permet l'utilisation de cette librairie dans des environnements externes à Node.js.

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}`)
})

Note

Liens utiles

• Wiki
• Serveur Discord
• JSON:API Specification
• OpenID Connect Specification

scolengo-api's Issues

Permettre de déplacer une communication

Implémenter la récupération des retards/absences

Implémenter le téléchargement des bilans périodiques (bulletins)

Implémenter la route permettant de récupérer la liste des bulletins et permettre à l'utilisateur de les télécharger.

Exporter les absences au format CSV

Participation au projet

Bonjour,
Je serais éventuellement intéressé pour participer au projet.
J'ai rejoins le serveur discord mais je n'ai aucune permission pour lire ou participer.
@maelgangloff es ce que tu peut faire quelque chose?

Merci

Permettre de marquer un devoir comme terminé

Implémenter la route correspondante et ajouter le test unitaire.

Erreur "PRONOTE_RESOURCES_NOT_READY" lors de la récupération des évaluations

Lorsque je souhaite utiliser la fonction getEvaluation(), de la façon suivante :

Skolengo.fromConfigObject(config).then(async user => {
  const infoUser = await user.getUserInfo()
  const studentId = infoUser.id;
  const periodId = '1'; 

  const limit = 20; 
  const offset = 0;
  const notes = await user.getEvaluation(studentId, periodId, limit, offset);
  console.log('Voici les notes :', notes);
}).catch((error) => {
  console.error('Une erreur s\'est produite :', error);
});

J'obtiens l'erreur suivante (chemins d'accès modifiés, ils sont à la base absolus) :

PRONOTE_RESOURCES_NOT_READY: Pronote resources are not yet ready, please try again in 500 ms
    at Skolengo.request (./node_modules/scolengo-api/dist/index.js:926:23)
    at process.processTicksAndRejections (node:internal/process/task_queues:95:5)
    at async Skolengo.getEvaluation (./node_modules/scolengo-api/dist/index.js:349:52)
    at async ./main.js:38:17 {
  status: '503',
  detail: 'Pronote resources are not yet ready, please try again in 500 ms'
}

Pour reproduire le problème :
Le code que j'ai testé est :

Skolengo.fromConfigObject(config).then(async user => {
  const infoUser = await user.getUserInfo()
  const studentId = infoUser.id;
  const periodId = '1'; 

  const limit = 20; 
  const offset = 0;
  const notes = await user.getEvaluation(studentId, periodId, limit, offset);
  console.log('Voici les notes :', notes);
}).catch((error) => {
  console.error('Une erreur s\'est produite :', error);
});

Résultat attendu
La liste des notes, en fonction des arguments passés à la fonction

Contexte additionnel
Version de la librairie : 1.2.0

Implémenter l'envoi de message via le service de communication

Implémenter la route correspondante et ajouter les tests unitaires associés.

Permettre l'envoi d'un message sur un fil de discussion

Actuellement, il n'est pas possible d'ajouter une réponse à un fil de discussion. Il est seulement possible de créer un nouveau fil.

Rédiger une définition OpenAPI

Rédiger un fichier de définition OpenAPI. Cette spécification permettra d'en comprendre davantage son fonctionnement et aidera à son implémentation dans d'autres projets.

Permettre le téléchargement d'une pièce jointe à une communication

Implémenter la récupération de l'agenda personnel de l'étudiant

Implémenter la route correspondante pour récupérer l'agenda personnel et ajouter les tests unitaires associés.

New scrapped API changes to includes

• homework-assignments: specifying fields[homework]=title,done,dueDateTime&fields[subject]=label,color is mandatory, unless the API fails with an NPE
• homework-assignments/:homeworkId: include teacher.person was removed. I don't think keeping it is an issue?
• users-mail-settings/:userId: includes 'contacts', 'contacts.person', 'contacts.personContacts' were removed. Might be an issue?
• schools-info: include attachments was removed. Might not be an issue?

Note that the following endpoints were untested:

• POST communications
• GET absence-files/:folderId

Exporter l'agenda au format iCalendar

Permettre de télécharger l'agenda au format iCalendar (Type MIME: text/calendar).
Ce format est standardisé (proposé par la RFC 5545) et permet l'importation de calendrier dans de nombreux logiciels (Google Agenda par exemple).

Erreur de type pour les contact d'une nouvelle communication

Les destinataires doivent être des personContact ou groupContact et pas du type user.

Mettre à jour la documentation

Ajouter les exemples JS qui manquent dans le README

Ajouter des tests unitaires

Ajouter des tests unitaires pour s'assurer que les types des réponses sont corrects.

Gérer les erreurs HTTP

Certaines requêtes génèrent des erreurs. Dans ces cas, il est d'usage de retourner un message explicite d'erreur en fonction des cas possibles.

Par exemple, l'endpoint concernant les absences peut retourner une erreur si l'établissement de l'utilisateur utilise Pronote pour la gestion des absences. Cette erreur l'invite à réessayer la requête après un certain temps.

Exemple d'erreur Pronote lors d'une demande de la liste des absences :

{
    "errors": [
        {
            "status": "503",
            "title": "PRONOTE_RESOURCES_NOT_READY",
            "detail": "Pronote resources are not yet ready, please try again in 500 ms"
        }
    ]
}

Merci à @mateo08c d'avoir partagé ce message d'erreur.

Voir les détails d'une absence

Rechercher un établissement avec coordonnées GPS

Permettre la recherche des établissements autour de soi (en fournissant des coordonnées GPS).

Implémenter la récupération des participants d'une communication

Unauthorized 403

Is your feature request related to a problem? Please describe.
Authentication

Describe the solution you'd like
After 2 years without any problem of authentication, currently, i received 403 http code and it's not possible to use its api anymore.
I have not migrate to new api but I have tried using scolengo and the same 403.

Describe alternatives you've considered
no workaround possible

Any ideas?