### Example API Response Headers

Source: https://github.com/maelgangloff/scolengo-api/wiki/Fonctionnement-du-serveur-API

This snippet showcases typical response headers received from the Scolengo API. These headers provide information about content type, ENT version, security policies, and KrakenD processing status.

```http
content-type: application/vnd.api+json;charset=utf-8
version-ent: 4.12.19.4
x-content-type-options: nosniff
x-frame-options: SAMEORIGIN
x-krakend: Version undefined
x-krakend-completed: false
```

--------------------------------

### Example X-Skolengo-Ems-Code Header

Source: https://github.com/maelgangloff/scolengo-api/wiki/Fonctionnement-du-serveur-API

This code snippet demonstrates the format of the 'X-Skolengo-Ems-Code' header used to specify the target ENT for API requests. This header is mandatory when interacting with the Scolengo API gateway.

```http
X-Skolengo-Ems-Code: gdest
```

--------------------------------

### Get Detailed Lesson Information (JavaScript)

Source: https://context7.com/maelgangloff/scolengo-api/llms.txt

Fetches and displays detailed information about a specific lesson, including its title, subject, timing, location, teachers, content, and attachments. Relies on the 'scolengo-api' library.

```javascript
const { Skolengo } = require('scolengo-api')

Skolengo.fromConfigObject(config).then(async user => {
  const studentId = 'ESKO-P-12345678-1234-1234-1234-123456789abc'
  const lessonId = 'lesson-12345'

  const lesson = await user.getLesson(studentId, lessonId)

  console.log(`Lesson: ${lesson.title}`)
  console.log(`Subject: ${lesson.subject.label}`)
  console.log(`Start: ${new Date(lesson.startDateTime).toLocaleString()}`)
  console.log(`End: ${new Date(lesson.endDateTime).toLocaleString()}`)
  console.log(`Location: ${lesson.location || 'Not specified'}`)
  console.log(`Canceled: ${lesson.canceled ? 'Yes' : 'No'}`)

  if (lesson.teachers && lesson.teachers.length > 0) {
    console.log(`\nTeachers:`)
    lesson.teachers.forEach(teacher => {
      console.log(`  - ${teacher.title || ''} ${teacher.firstName} ${teacher.lastName}`)
    })
  }

  if (lesson.contents && lesson.contents.length > 0) {
    console.log('\nLesson Content:')
    lesson.contents.forEach(content => {
      console.log(`  ${content.title}`)
      if (content.attachments && content.attachments.length > 0) {
        console.log(`  Attachments: ${content.attachments.length}`)
      }
    })
  }

  if (lesson.toDoForTheLesson && lesson.toDoForTheLesson.length > 0) {
    console.log(`\nTo do before: ${lesson.toDoForTheLesson.length} assignments`)
  }

  if (lesson.toDoAfterTheLesson && lesson.toDoAfterTheLesson.length > 0) {
    console.log(`To do after: ${lesson.toDoAfterTheLesson.length} assignments`)
  }
})
```

--------------------------------

### GET /app/config

Source: https://context7.com/maelgangloff/scolengo-api/llms.txt

Retrieves the current configuration for the Skolengo mobile application, including version information and maintenance messages.

```APIDOC
## Get Application Configuration

### Description
Retrieve current Skolengo mobile application version information.

### Method
GET

### Endpoint
/app/config

### Parameters
None

### Request Example
```javascript
const { Skolengo } = require('scolengo-api')

Skolengo.getAppCurrentConfig().then(config => {
  console.log(config)
})
```

### Response
#### Success Response (200)
- **latestDeployedSkoAppVersion** (string) - The latest version of the Skolengo app that has been deployed.
- **latestSupportedSkoAppVersion** (string) - The latest version of the Skolengo app that is currently supported.
- **minSupportedSkoAppVersion** (string) - The minimum version of the Skolengo app that is required.
- **maintenanceMessage** (string) - An optional message to display to users regarding maintenance or important updates.

#### Response Example
```json
{
  "latestDeployedSkoAppVersion": "2.5.0",
  "latestSupportedSkoAppVersion": "2.6.0",
  "minSupportedSkoAppVersion": "2.3.0",
  "maintenanceMessage": "Scheduled maintenance tonight from 10 PM to 11 PM UTC."
}
```
```

--------------------------------

### Get Application Configuration with Scolengo API

Source: https://context7.com/maelgangloff/scolengo-api/llms.txt

Retrieves the current Skolengo mobile application configuration details. This includes the latest deployed, supported, and minimum required app versions. It also displays any maintenance messages if present.

```javascript
const { Skolengo } = require('scolengo-api')

Skolengo.getAppCurrentConfig().then(config => {
  console.log('Skolengo Application Configuration:')
  console.log(`Latest Deployed Version: ${config.latestDeployedSkoAppVersion}`)
  console.log(`Latest Supported Version: ${config.latestSupportedSkoAppVersion}`)
  console.log(`Minimum Required Version: ${config.minSupportedSkoAppVersion}`)

  if (config.maintenanceMessage) {
    console.log(`\nMaintenance Message: ${config.maintenanceMessage}`)
  }
})
```

--------------------------------

### Get Mail Settings and Folders with Scolengo API

Source: https://context7.com/maelgangloff/scolengo-api/llms.txt

Retrieves messaging configuration, including maximum characters for subjects and messages, email signatures, and a list of available folders. It depends on the 'scolengo-api' library.

```javascript
const { Skolengo } = require('scolengo-api')

Skolengo.fromConfigObject(config).then(async user => {
  const mailSettings = await user.getUsersMailSettings()

  console.log(`Max Characters in Subject: ${mailSettings.maxCharsInCommunicationSubject}`)
  console.log(`Max Characters in Message: ${mailSettings.maxCharsInParticipationContent}`)

  if (mailSettings.signature) {
    console.log(`\nEmail Signature:\n${mailSettings.signature.content}`)
  }

  console.log('\nFolders:')
  mailSettings.folders.forEach(folder => {
    console.log(`  - ${folder.name} (${folder.type})`)
    console.log(`    Folder ID: ${folder.id}`)
  })

  if (mailSettings.contacts && mailSettings.contacts.length > 0) {
    console.log(`\nContacts: ${mailSettings.contacts.length}`)
    mailSettings.contacts.slice(0, 5).forEach(contact => {
      if (contact.person) {
        console.log(`  - ${contact.person.firstName} ${contact.person.lastName}`)
      }
    })
  }
})
```

--------------------------------

### Get Evaluation Settings and Periods using Scolengo API

Source: https://context7.com/maelgangloff/scolengo-api/llms.txt

Retrieves evaluation configuration, including grading periods and skill settings, for a given student. Requires 'scolengo-api' library and a configuration object. Outputs service ID, periodic report status, skill status, and details about each grading period.

```javascript
const { Skolengo } = require('scolengo-api')

Skolengo.fromConfigObject(config).then(async user => {
  const studentId = 'ESKO-P-12345678-1234-1234-1234-123456789abc'
  const evalSettings = await user.getEvaluationSettings(studentId)

  evalSettings.forEach(setting => {
    console.log(`Service ID: ${setting.id}`)
    console.log(`Periodic Reports Enabled: ${setting.periodicReportsEnabled}`)
    console.log(`Skills Enabled: ${setting.skillsEnabled}`)
    console.log(`Evaluation Details Available: ${setting.evaluationsDetailsAvailable}`)

    console.log('\nGrading Periods:')
    setting.periods.forEach(period => {
      console.log(`  - ${period.label}`)
      console.log(`    Period ID: ${period.id}`)
      console.log(`    From: ${period.startDate} to ${period.endDate}`)
    })
  })
})
```

--------------------------------

### Get All School News

Source: https://context7.com/maelgangloff/scolengo-api/llms.txt

Retrieve a list of all school announcements and news items. The output includes titles, publication dates, author information, attachment counts, and content previews. Requires an authenticated user object.

```javascript
const { Skolengo } = require('scolengo-api')

Skolengo.fromConfigObject(config).then(async user => {
  const schoolNews = await user.getSchoolInfos()

  console.log(`Found ${schoolNews.length} news items:\n`)

  schoolNews.forEach(news => {
    console.log(`Title: ${news.title}`)
    console.log(`Published: ${new Date(news.publicationDateTime).toLocaleString()}`)
    console.log(`Author: ${news.author?.person?.firstName} ${news.author?.person?.lastName}`)

    if (news.attachments && news.attachments.length > 0) {
      console.log(`Attachments: ${news.attachments.length}`)
    }

    console.log(`Content preview: ${news.content.substring(0, 100)}...`)
    console.log('---')
  })
})
```

--------------------------------

### Get Detailed Homework Assignment (JavaScript)

Source: https://context7.com/maelgangloff/scolengo-api/llms.txt

Fetches and displays detailed information for a specific homework assignment, including its title, subject, due date, completion status, teacher, instructions (HTML), and attachments. Uses the 'scolengo-api' library.

```javascript
const { Skolengo } = require('scolengo-api')

Skolengo.fromConfigObject(config).then(async user => {
  const studentId = user.getTokenClaims().sub
  const homeworkId = '123456'

  const homework = await user.getHomeworkAssignment(studentId, homeworkId)

  console.log(`Title: ${homework.title}`)
  console.log(`Subject: ${homework.subject.label}`)
  console.log(`Due: ${new Date(homework.dueDateTime).toLocaleString()}`)
  console.log(`Status: ${homework.done ? 'Completed' : 'Not completed'}`)

  if (homework.teacher) {
    console.log(`Teacher: ${homework.teacher.person.firstName} ${homework.teacher.person.lastName}`)
  }

  console.log('\nInstructions:')
  console.log(homework.html)

  if (homework.attachments && homework.attachments.length > 0) {
    console.log('\nAttachments:')
    homework.attachments.forEach(attachment => {
      console.log(`  - ${attachment.name} (${attachment.mimeTypeLabel})`)
    })
  }
})
```

--------------------------------

### Get Specific School News Item with Details

Source: https://context7.com/maelgangloff/scolengo-api/llms.txt

Fetch detailed information for a specific school announcement, including its full content and a list of attachments. This requires fetching all news items first to get an ID, then requesting the details of a single item.

```javascript
const { Skolengo } = require('scolengo-api')

Skolengo.fromConfigObject(config).then(async user => {
  const allNews = await user.getSchoolInfos()

  if (allNews.length === 0) {
    console.log('No news available')
    return
  }

  const newsId = allNews[0].id
  const newsDetail = await user.getSchoolInfo(newsId)

  console.log(`Title: ${newsDetail.title}`)
  console.log(`Published on: ${new Date(newsDetail.publicationDateTime).toLocaleString()}`)
  console.log(`\nFull content:\n${newsDetail.content}`)

  if (newsDetail.attachments && newsDetail.attachments.length > 0) {
    console.log('\nAttachments:')
    newsDetail.attachments.forEach(attachment => {
      console.log(`  - ${attachment.name} (${attachment.mimeTypeLabel}, ${attachment.size} bytes)`)
    })
  }
})
```

--------------------------------

### Get Student Schedule as iCalendar (JavaScript)

Source: https://context7.com/maelgangloff/scolengo-api/llms.txt

Retrieves a student's schedule for a specified date range and exports it to iCalendar format. Requires the 'scolengo-api' library and Node.js 'fs' module. Outputs the schedule to 'schedule.ics'.

```javascript
const { Skolengo } = require('scolengo-api')
const { writeFileSync } = require('node:fs')

Skolengo.fromConfigObject(config).then(async user => {
  const studentId = 'ESKO-P-12345678-1234-1234-1234-123456789abc'
  const startDate = '2023-05-01'
  const endDate = '2023-05-30'

  const agenda = await user.getAgenda(studentId, startDate, endDate)

  console.log(`Retrieved schedule from ${startDate} to ${endDate}`)
  console.log(`Total days: ${agenda.length}`)

  let totalLessons = 0
  agenda.forEach(day => {
    totalLessons += day.lessons.length
    console.log(`${day.date}: ${day.lessons.length} lessons, ${day.homeworkAssignments.length} homework`)
  })

  console.log(`\nTotal lessons: ${totalLessons}`)

  const icalContent = agenda.toICalendar(new Date(), 'My School Schedule')
  writeFileSync('schedule.ics', icalContent)
  console.log('\nSchedule exported to schedule.ics')
})
```

--------------------------------

### GET /absence-reasons

Source: https://context7.com/maelgangloff/scolengo-api/llms.txt

Retrieves the list of valid absence reasons that can be used for justifying absences. This is useful for understanding the available options before submitting a justification.

```APIDOC
## Get Available Absence Reasons

### Description
Retrieve the list of valid absence reasons for justification.

### Method
GET

### Endpoint
/absence-reasons

### Parameters
#### Query Parameters
None

### Request Example
```javascript
const { Skolengo } = require('scolengo-api')

Skolengo.fromConfigObject(config).then(async user => {
  const reasons = await user.getAbsenceReasons()
  console.log(reasons)
})
```

### Response
#### Success Response (200)
- **reasons** (array) - An array of absence reason objects. Each object contains:
  - **longLabel** (string) - The full description of the absence reason.
  - **shortLabel** (string) - A shorter label for the absence reason.
  - **id** (string) - The unique identifier for the absence reason.
  - **justified** (boolean) - Indicates if the reason requires justification.

#### Response Example
```json
[
  {
    "longLabel": "Maladie",
    "shortLabel": "Maladie",
    "id": "reason-id-1",
    "justified": true
  },
  {
    "longLabel": "Absence justifiée par les parents",
    "shortLabel": "Justifié Parents",
    "id": "reason-id-2",
    "justified": false
  }
]
```
```

--------------------------------

### Get Available Absence Reasons with Scolengo API

Source: https://context7.com/maelgangloff/scolengo-api/llms.txt

Retrieves and displays a list of available absence reasons from the Scolengo API. It requires a configuration object for authentication and outputs the long label, short label, ID, and justification status for each reason.

```javascript
const { Skolengo } = require('scolengo-api')

Skolengo.fromConfigObject(config).then(async user => {
  const reasons = await user.getAbsenceReasons()

  console.log(`Available absence reasons (${reasons.length}):\n`)

  reasons.forEach((reason, index) => {
    console.log(`${index + 1}. ${reason.longLabel}`)
    console.log(`   Short: ${reason.shortLabel}`)
    console.log(`   Reason ID: ${reason.id}`)
    console.log(`   Justified: ${reason.justified ? 'Yes' : 'No'}`)
  })
})
```

--------------------------------

### Manually Refresh Access Token with Scolengo API

Source: https://context7.com/maelgangloff/scolengo-api/llms.txt

Forces a refresh of the Scolengo API access token before it expires. It demonstrates setting up an `onTokenRefresh` callback for persistent storage and manually calling `refreshToken()`. The example logs the token expiry before and after the refresh and verifies authentication with `getUserInfo`.

```javascript
const { Skolengo } = require('scolengo-api')

Skolengo.fromConfigObject(config, {
  onTokenRefresh: (newTokenSet) => {
    console.log('Token refreshed at:', new Date().toISOString())
    console.log('New access token expires at:', new Date(newTokenSet.expires_at * 1000).toISOString())
    // Save newTokenSet to persistent storage
  }
}).then(async user => {
  console.log('Current token expiry:', new Date(user.tokenSet.expires_at * 1000).toISOString())

  const newTokenSet = await user.refreshToken()

  console.log('Token manually refreshed')
  console.log('New expiry:', new Date(newTokenSet.expires_at * 1000).toISOString())

  // Continue using the client with refreshed token
  const userInfo = await user.getUserInfo()
  console.log(`Still authenticated as: ${userInfo.firstName} ${userInfo.lastName}`)
})
```

--------------------------------

### Reply to Existing Message Thread using Scolengo API

Source: https://context7.com/maelgangloff/scolengo-api/llms.txt

This code example shows how to add a participation (reply) to an existing communication thread via the Scolengo API. It utilizes the 'scolengo-api' library and requires a valid communication ID and the reply content. The function returns the details of the sent participation.

```javascript
const { Skolengo } = require('scolengo-api')

Skolengo.fromConfigObject(config).then(async user => {
  const communicationId = 'comm-12345'

  const newParticipation = {
    type: 'participation',
    attributes: {
      content: 'Thank you for your response. That clarifies my question.'
    },
    relationships: {
      communication: {
        data: { type: 'communication', id: communicationId }
      }
    }
  }

  const sentParticipation = await user.postParticipation(newParticipation)

  console.log('Reply sent successfully!')
  console.log(`Participation ID: ${sentParticipation.id}`)
  console.log(`Sent at: ${new Date(sentParticipation.dateTime).toLocaleString()}`)
})
```

--------------------------------

### Get Current User Information

Source: https://context7.com/maelgangloff/scolengo-api/llms.txt

Retrieve detailed information about the currently authenticated user. This includes personal details, permissions, and associated students. It requires an authenticated user object obtained via OAuth.

```javascript
const { Skolengo } = require('scolengo-api')

Skolengo.fromConfigObject(config).then(async user => {
  const userInfo = await user.getUserInfo()

  console.log(`Name: ${userInfo.firstName} ${userInfo.lastName}`)
  console.log(`Email: ${userInfo.externalMail}`)
  console.log(`Phone: ${userInfo.mobilephone}`)
  console.log(`School: ${userInfo.school.name}`)
  console.log(`Timezone: ${userInfo.school.timeZone}`)

  if (userInfo.students && userInfo.students.length > 0) {
    console.log('\nStudents:')
    userInfo.students.forEach(student => {
      console.log(`  - ${student.firstName} ${student.lastName} (${student.className})`)
      console.log(`    Student ID: ${student.id}`)
      console.log(`    Date of Birth: ${student.dateOfBirth}`)
    })
  }

  console.log('\nPermissions:', userInfo.permissions)
})
```

--------------------------------

### Get Homework Assignments for Date Range (JavaScript)

Source: https://context7.com/maelgangloff/scolengo-api/llms.txt

Retrieves all homework assignments for a student within a specified date range (defaulting to the next 15 days). Organizes and displays homework by subject, indicating completion status. Requires the 'scolengo-api' library.

```javascript
const { Skolengo } = require('scolengo-api')

Skolengo.fromConfigObject(config).then(async user => {
  const studentId = user.getTokenClaims().sub
  const startDate = new Date().toISOString().split('T')[0]
  const endDate = new Date(Date.now() + 15 * 24 * 60 * 60 * 1000).toISOString().split('T')[0]

  const homework = await user.getHomeworkAssignments(studentId, startDate, endDate)

  console.log(`Homework for the next 15 days (${startDate} to ${endDate}):\n`)

  const bySubject = {}
  homework.forEach(hw => {
    const subject = hw.subject.label
    if (!bySubject[subject]) bySubject[subject] = []
    bySubject[subject].push(hw)
  })

  Object.keys(bySubject).forEach(subject => {
    console.log(`\n${subject}:`)
    bySubject[subject].forEach(hw => {
      const dueDate = new Date(hw.dueDateTime).toLocaleDateString()
      const status = hw.done ? '✓' : '○'
      console.log(`  ${status} [${dueDate}] ${hw.title}`)
    })
  })

  const completed = homework.filter(hw => hw.done).length
  console.log(`\n${completed}/${homework.length} assignments completed`)
})
```

--------------------------------

### Get Messages from Folder with Scolengo API

Source: https://context7.com/maelgangloff/scolengo-api/llms.txt

Fetches communications from a specified folder (e.g., inbox, sent) using the 'scolengo-api' library. It requires the folder ID and allows specifying the number of messages and an offset. Outputs include sender, date, read status, and message ID.

```javascript
const { Skolengo } = require('scolengo-api')

Skolengo.fromConfigObject(config).then(async user => {
  const mailSettings = await user.getUsersMailSettings()

  const inboxFolder = mailSettings.folders.find(f => f.type === 'INBOX')
  if (!inboxFolder) {
    console.log('Inbox folder not found')
    return
  }

  const messages = await user.getCommunicationsFolder(inboxFolder.id, 20, 0)

  console.log(`Messages in Inbox (${messages.length}):\n`)

  messages.forEach(message => {
    const lastParticipation = message.lastParticipation
    const sender = lastParticipation?.sender?.person

    console.log(`Subject: ${message.subject}`)
    console.log(`From: ${sender ? `${sender.firstName} ${sender.lastName}` : 'Unknown'}`)
    console.log(`Date: ${new Date(message.lastParticipationDateTime).toLocaleString()}`)
    console.log(`Read: ${message.read ? 'Yes' : 'No'}`)
    console.log(`Message ID: ${message.id}`)
    console.log('---')
  })
})
```

--------------------------------

### Get Detailed Evaluation Information using Scolengo API

Source: https://context7.com/maelgangloff/scolengo-api/llms.txt

Retrieves comprehensive details for a specific grade, including comments, sub-skills, and associated subject information. Requires 'scolengo-api', student ID, and evaluation ID. Outputs title, topic, date, subject, coefficient, scale, student grade, and optional comments or sub-skill assessments.

```javascript
const { Skolengo } = require('scolengo-api')

Skolengo.fromConfigObject(config).then(async user => {
  const studentId = 'ESKO-P-12345678-1234-1234-1234-123456789abc'
  const evaluationId = '123456'

  const evalDetail = await user.getEvaluationDetail(studentId, evaluationId)

  console.log(`Title: ${evalDetail.title}`)
  console.log(`Topic: ${evalDetail.topic}`)
  console.log(`Date: ${new Date(evalDetail.dateTime).toLocaleString()}`)
  console.log(`Subject: ${evalDetail.evaluationService.subject.label}`)
  console.log(`Coefficient: ${evalDetail.coefficient}`)
  console.log(`Scale: Min ${evalDetail.min} - Max ${evalDetail.max} (Average: ${evalDetail.average})`)

  if (evalDetail.evaluationResult) {
    const result = evalDetail.evaluationResult
    console.log(`\nStudent Grade: ${result.mark}`)

    if (result.comment) {
      console.log(`Teacher Comment: ${result.comment}`)
    }

    if (result.subSkillsEvaluationResults && result.subSkillsEvaluationResults.length > 0) {
      console.log('\nSub-Skills Assessment:')
      result.subSkillsEvaluationResults.forEach(subSkill => {
        console.log(`  - ${subSkill.subSkill.shortLabel}: Level ${subSkill.level}`)
      })
    }
  }
})
```

--------------------------------

### Get Student Grades for a Period using Scolengo API

Source: https://context7.com/maelgangloff/scolengo-api/llms.txt

Fetches all grades and evaluations for a specific grading period for a student. It first retrieves evaluation settings to determine the period ID, then fetches the evaluations. Outputs subject, averages, coefficient, and individual grades with optional titles and teacher information. Requires 'scolengo-api'.

```javascript
const { Skolengo } = require('scolengo-api')

Skolengo.fromConfigObject(config).then(async user => {
  const studentId = 'ESKO-P-12345678-1234-1234-1234-123456789abc'

  const evalSettings = await user.getEvaluationSettings(studentId)
  const periodId = evalSettings[0].periods[0].id

  const evaluations = await user.getEvaluation(studentId, periodId)

  evaluations.forEach(evalService => {
    console.log(`\nSubject: ${evalService.subject.label}`)
    console.log(`Student Average: ${evalService.studentAverage}/${evalService.scale}`)
    console.log(`Class Average: ${evalService.average}/${evalService.scale}`)
    console.log(`Coefficient: ${evalService.coefficient}`)

    console.log('\nIndividual Grades:')
    evalService.evaluations.forEach(evaluation => {
      const result = evaluation.evaluationResult
      if (result && result.mark !== null) {
        console.log(`  - ${new Date(evaluation.dateTime).toLocaleDateString()}: ${result.mark}/${evaluation.scale}`)
        if (evaluation.title) console.log(`    Title: ${evaluation.title}`)
      }
    })

    if (evalService.teachers && evalService.teachers.length > 0) {
      console.log(`Teachers: ${evalService.teachers.map(t => `${t.firstName} ${t.lastName}`).join(', ')}`)
    }
  })
})
```

--------------------------------

### Get Token Claims and User ID

Source: https://context7.com/maelgangloff/scolengo-api/llms.txt

Extract JWT token claims to obtain the current user's subject identifier ('sub'), issue time ('iat'), and expiration time ('exp'). This information can be used for API calls, such as fetching homework assignments.

```javascript
const { Skolengo } = require('scolengo-api')

Skolengo.fromConfigObject(config).then(async user => {
  const claims = user.getTokenClaims()

  console.log(`User Subject ID: ${claims.sub}`)
  console.log(`Token Issued At: ${new Date(claims.iat * 1000).toLocaleString()}`)
  console.log(`Token Expires At: ${new Date(claims.exp * 1000).toLocaleString()}`)

  // Use the subject ID for API calls
  const homework = await user.getHomeworkAssignments(claims.sub, '2023-05-01', '2023-05-30')
  console.log(`Found ${homework.length} homework assignments`)
})
```

--------------------------------

### Get Student Absences and Export to CSV using Scolengo API

Source: https://context7.com/maelgangloff/scolengo-api/llms.txt

This JavaScript code retrieves all absence records for a given student and exports them to a CSV file. It utilizes the 'scolengo-api' library and Node.js 'fs' module for file writing. The function fetches absence data, logs summary information, and saves the data as 'absences.csv'.

```javascript
const { Skolengo } = require('scolengo-api')
const { writeFileSync } = require('node:fs')

Skolengo.fromConfigObject(config).then(async user => {
  const studentId = 'ESKO-P-12345678-1234-1234-1234-123456789abc'
  const absenceFiles = await user.getAbsenceFiles(studentId)

  console.log(`Found ${absenceFiles.length} absence records:\n`)

  absenceFiles.forEach(absence => {
    console.log(`Type: ${absence.type}`)
    console.log(`Date: ${new Date(absence.createdDateTime).toLocaleDateString()}`)

    if (absence.currentState) {
      const state = absence.currentState
      console.log(`Status: ${state.status}`)

      if (state.absenceReason) {
        console.log(`Reason: ${state.absenceReason.longLabel}`)
      }

      if (state.comment) {
        console.log(`Comment: ${state.comment}`)
      }
    }
    console.log('---')
  })

  const csvContent = absenceFiles.toCSV()
  writeFileSync('absences.csv', csvContent)
  console.log('\nAbsences exported to absences.csv')
})
```

--------------------------------

### Get Detailed Absence Information using Scolengo API

Source: https://context7.com/maelgangloff/scolengo-api/llms.txt

This snippet retrieves detailed information about a specific absence, including its history, using the Scolengo API. It requires the 'scolengo-api' library and the absence ID. The function fetches and logs various details such as absence type, creation date, status, reason, and history entries.

```javascript
const { Skolengo } = require('scolengo-api')

Skolengo.fromConfigObject(config).then(async user => {
  const absenceId = 'absence-file-12345'

  const absenceDetail = await user.getAbsenceFile(absenceId)

  console.log(`Absence Type: ${absenceDetail.type}`)
  console.log(`Created: ${new Date(absenceDetail.createdDateTime).toLocaleString()}`)
  console.log(`Resolved: ${absenceDetail.resolved ? 'Yes' : 'No'}`)

  if (absenceDetail.currentState) {
    const state = absenceDetail.currentState
    console.log(`\nCurrent Status: ${state.status}`)

    if (state.absenceReason) {
      console.log(`Reason: ${state.absenceReason.longLabel}`)
    }

    if (state.absenceRecurrence) {
      console.log(`Start: ${state.absenceRecurrence.startDateTime}`)
      console.log(`End: ${state.absenceRecurrence.endDateTime}`)
    }
  }

  if (absenceDetail.history && absenceDetail.history.length > 0) {
    console.log('\nHistory:')
    absenceDetail.history.forEach((entry, index) => {
      console.log(`  ${index + 1}. ${entry.status} - ${new Date(entry.createdDateTime).toLocaleString()}`)
      if (entry.creator) {
        console.log(`     By: ${entry.creator.firstName} ${entry.creator.lastName}`)
      }
    })
  }
})
```

--------------------------------

### Complete OAuth Flow with Authorization Code

Source: https://context7.com/maelgangloff/scolengo-api/llms.txt

This snippet demonstrates the full OAuth 2.0 Authorization Code flow. It exchanges an authorization code for access tokens, creates an authenticated client, and retrieves user information. Requires the 'scolengo-api' library.

```javascript
const { Skolengo } = require('scolengo-api')

Skolengo.searchSchool({ text: 'Lycée Louise Weiss' }).then(async schools => {
  if (!schools.length) throw new Error('No school found')

  const school = schools[0]
  const oidClient = await Skolengo.getOIDClient(school, 'skoapp-prod://sign-in-callback')

  const callbackUrl = 'skoapp-prod://sign-in-callback?code=OC-9999-xxxxxxxxxxxxxxxxxxxxxxxxxxxxxx-X'
  const params = oidClient.callbackParams(callbackUrl)
  const tokenSet = await oidClient.callback('skoapp-prod://sign-in-callback', params)

  const user = new Skolengo(oidClient, school, tokenSet)
  const userInfo = await user.getUserInfo()
  console.log(`Successfully authenticated: ${userInfo.firstName} ${userInfo.lastName}`)

  // Save tokenSet and school info for future use
  const configToSave = {
    tokenSet: tokenSet,
    school: school
  }
  console.log('Save this config:', JSON.stringify(configToSave, null, 2))
})
```

--------------------------------

### Authenticate with Scolengo API from Config Object

Source: https://context7.com/maelgangloff/scolengo-api/llms.txt

Initializes a Skolengo client using a pre-configured object containing OAuth 2.0 tokens and school details. It supports custom HTTP clients and token refresh callbacks.

```javascript
const { Skolengo } = require('scolengo-api')

const config = {
  "tokenSet": {
    "access_token": "eyJhbGciOiJSUzI1NiIsInR5cCI6IkpXVCJ9...",
    "id_token": "eyJhbGciOiJSUzI1NiIsInR5cCI6IkpXVCJ9...",
    "refresh_token": "RT-12345-abcdefghijklmnopqrstuvwxyz",
    "token_type": "bearer",
    "expires_at": 1234567890,
    "scope": "openid"
  },
  "school": {
    "id": "SKO-E-12345678-1234-1234-1234-123456789abc",
    "name": "Lycée Louise Weiss",
    "addressLine1": "1 Rue Example",
    "addressLine2": null,
    "addressLine3": null,
    "zipCode": "67000",
    "city": "Strasbourg",
    "country": "France",
    "homePageUrl": "https://cas.monbureaunumerique.fr/login",
    "emsCode": "gdest",
    "emsOIDCWellKnownUrl": "https://sso.monbureaunumerique.fr/oidc/.well-known"
  }
}

Skolengo.fromConfigObject(config, {
  handlePronoteError: true,
  onTokenRefresh: (newTokenSet) => {
    console.log('Token refreshed, save it for future use')
    // Save newTokenSet to file or database
  }
}).then(async user => {
  const userInfo = await user.getUserInfo()
  console.log(`Authenticated as: ${userInfo.firstName} ${userInfo.lastName}`)
  console.log(`User ID: ${userInfo.id}`)
})
```

--------------------------------

### Lesson API

Source: https://github.com/maelgangloff/scolengo-api/blob/master/README.md

Endpoint for retrieving details of a specific lesson.

```APIDOC
## GET /students/{studentId}/lessons/{lessonId}

### Description
Retrieves details for a specific lesson of a student.

### Method
GET

### Endpoint
/students/{studentId}/lessons/{lessonId}

### Parameters
#### Path Parameters
- **studentId** (string) - Required - The ID of the student.
- **lessonId** (string) - Required - The ID of the lesson.

#### Query Parameters
- **params** (object) - Optional - Additional parameters for the request.
- **includes** (array) - Optional - Specifies related data to include in the response.

### Request Example
```json
{
  "params": {},
  "includes": []
}
```

### Response
#### Success Response (200)
- **lesson** (object) - Details of the lesson.

#### Response Example
```json
{
  "lesson": {
    "id": "lesson123",
    "subject": "Physics",
    "teacher": "Dr. Smith"
  }
}
```
```

--------------------------------

### Communications API

Source: https://github.com/maelgangloff/scolengo-api/blob/master/README.md

Endpoints for managing communications and folders.

```APIDOC
## GET /communications/folders/{folderId}

### Description
Retrieves communications within a specified folder.

### Method
GET

### Endpoint
/communications/folders/{folderId}

### Parameters
#### Path Parameters
- **folderId** (string) - Required - The ID of the folder.

#### Query Parameters
- **limit** (integer) - Optional - The maximum number of results to return.
- **offset** (integer) - Optional - The number of results to skip.
- **params** (object) - Optional - Additional parameters for the request.
- **includes** (array) - Optional - Specifies related data to include in the response.

### Request Example
```json
{
  "limit": 10,
  "offset": 0,
  "params": {},
  "includes": []
}
```

### Response
#### Success Response (200)
- **communications** (array) - A list of communications in the folder.

#### Response Example
```json
{
  "communications": [
    {
      "id": "comm1",
      "subject": "Meeting Reminder"
    }
  ]
}
```

## GET /communications/{communicationId}

### Description
Retrieves details of a specific communication.

### Method
GET

### Endpoint
/communications/{communicationId}

### Parameters
#### Path Parameters
- **communicationId** (string) - Required - The ID of the communication.

#### Query Parameters
- **params** (object) - Optional - Additional parameters for the request.

### Request Example
```json
{
  "params": {}
}
```

### Response
#### Success Response (200)
- **communication** (object) - Details of the communication.

#### Response Example
```json
{
  "communication": {
    "id": "comm1",
    "subject": "Meeting Reminder",
    "body": "Please attend the meeting at 3 PM."
  }
}
```

## GET /communications/{communicationId}/participations

### Description
Retrieves participations for a specific communication.

### Method
GET

### Endpoint
/communications/{communicationId}/participations

### Parameters
#### Path Parameters
- **communicationId** (string) - Required - The ID of the communication.

#### Query Parameters
- **params** (object) - Optional - Additional parameters for the request.
- **includes** (array) - Optional - Specifies related data to include in the response.

### Request Example
```json
{
  "params": {},
  "includes": []
}
```

### Response
#### Success Response (200)
- **participations** (array) - A list of participations.

#### Response Example
```json
{
  "participations": [
    {
      "userId": "user1",
      "status": "accepted"
    }
  ]
}
```

## GET /communications/{communicationId}/participants

### Description
Retrieves participants for a specific communication, optionally filtering by group.

### Method
GET

### Endpoint
/communications/{communicationId}/participants

### Parameters
#### Path Parameters
- **communicationId** (string) - Required - The ID of the communication.

#### Query Parameters
- **fromGroup** (boolean) - Optional - If true, filters participants by group.
- **params** (object) - Optional - Additional parameters for the request.
- **includes** (array) - Optional - Specifies related data to include in the response.

### Request Example
```json
{
  "fromGroup": false,
  "params": {},
  "includes": []
}
```

### Response
#### Success Response (200)
- **participants** (array) - A list of participants.

#### Response Example
```json
{
  "participants": [
    {
      "userId": "user2",
      "name": "Jane Smith"
    }
  ]
}
```

## PATCH /communications/{communicationId}/folders

### Description
Updates the folder for a communication.

### Method
PATCH

### Endpoint
/communications/{communicationId}/folders

### Parameters
#### Path Parameters
- **communicationId** (string) - Required - The ID of the communication.

#### Query Parameters
- **params** (object) - Optional - Additional parameters for the request.

#### Request Body
- **folders** (array) - Required - The list of folder IDs to associate the communication with.
- **userId** (string) - Required - The ID of the user performing the action.

### Request Example
```json
{
  "folders": ["folderA", "folderB"],
  "userId": "user3",
  "params": {}
}
```

### Response
#### Success Response (200)
- **updateStatus** (string) - Confirmation of the update.

#### Response Example
```json
{
  "updateStatus": "success"
}
```

## POST /communications

### Description
Creates a new communication.

### Method
POST

### Endpoint
/communications

### Parameters
#### Query Parameters
- **params** (object) - Optional - Additional parameters for the request.

#### Request Body
- **newCommunication** (object) - Required - The details of the new communication.

### Request Example
```json
{
  "newCommunication": {
    "subject": "New Announcement",
    "body": "Important update regarding school policies."
  },
  "params": {}
}
```

### Response
#### Success Response (200)
- **createdCommunication** (object) - Details of the newly created communication.

#### Response Example
```json
{
  "createdCommunication": {
    "id": "comm5",
    "subject": "New Announcement"
  }
}
```

## POST /participations

### Description
Adds a participation to a communication.

### Method
POST

### Endpoint
/participations

### Parameters
#### Query Parameters
- **params** (object) - Optional - Additional parameters for the request.

#### Request Body
- **participation** (object) - Required - The participation details.

### Request Example
```json
{
  "participation": {
    "communicationId": "comm5",
    "userId": "user4",
    "status": "pending"
  },
  "params": {}
}
```

### Response
#### Success Response (200)
- **participationStatus** (string) - Confirmation of the participation addition.

#### Response Example
```json
{
  "participationStatus": "added"
}
```
```

--------------------------------

### Generate Scolengo API Authorization URL

Source: https://context7.com/maelgangloff/scolengo-api/llms.txt

Creates an OAuth authorization URL for manual authentication. It first searches for a school and then generates a URL that initiates the OpenID Connect authentication flow.

```javascript
const { Skolengo } = require('scolengo-api')

Skolengo.searchSchool({ text: 'Lycée Louise Weiss' }).then(async schools => {
  if (!schools.length) throw new Error('No school found')

  const school = schools[0]
  const oidClient = await Skolengo.getOIDClient(school, 'skoapp-prod://sign-in-callback')

  const authUrl = oidClient.authorizationUrl({
    scope: 'openid',
    response_type: 'code'
  })

  console.log('Visit this URL to authenticate:')
  console.log(authUrl)
  console.log('
After authentication, you will be redirected with a code parameter')
})
```

--------------------------------

### Authentication API

Source: https://github.com/maelgangloff/scolengo-api/blob/master/README.md

Endpoints related to token management and authentication.

```APIDOC
## POST /auth/refresh_token

### Description
Refreshes the authentication token.

### Method
POST

### Endpoint
/auth/refresh_token

### Parameters
#### Request Body
- **triggerListener** (boolean) - Required - Whether to trigger a listener upon token refresh.

### Request Example
```json
{
  "triggerListener": true
}
```

### Response
#### Success Response (200)
- **newToken** (string) - The new authentication token.

#### Response Example
```json
{
  "newToken": "eyJhbGciOiJIUzI1NiIsInR5cCI6IkpXVCJ9..."
}
```

## GET /auth/token_claims

### Description
Retrieves the claims associated with the current authentication token.

### Method
GET

### Endpoint
/auth/token_claims

### Parameters
None

### Response
#### Success Response (200)
- **claims** (object) - The claims of the token.

#### Response Example
```json
{
  "claims": {
    "userId": "user123",
    "exp": 1700000000
  }
}
```

## POST /auth/revoke_token

### Description
(Static Method) Revokes an authentication token.

### Method
POST

### Endpoint
/auth/revoke_token

### Parameters
#### Request Body
- **oidClient** (object) - Required - The OID client details.
- **token** (string) - Required - The token to
```

--------------------------------

### User Information API

Source: https://github.com/maelgangloff/scolengo-api/blob/master/README.md

Endpoints for retrieving user-specific information.

```APIDOC
## GET /users/{userId}/info

### Description
Retrieves information for a specific user.

### Method
GET

### Endpoint
/users/{userId}/info

### Parameters
#### Path Parameters
- **userId** (string) - Required - The ID of the user.

#### Query Parameters
- **params** (object) - Optional - Additional parameters for the request.
- **includes** (array) - Optional - Specifies related data to include in the response.

### Request Example
```json
{
  "params": {},
  "includes": []
}
```

### Response
#### Success Response (200)
- **userInfo** (object) - Information about the user.

#### Response Example
```json
{
  "userInfo": {
    "id": "user123",
    "name": "John Doe"
  }
}
```
```