Pawnote - A purrfect API wrapper for Pronote

A simple wrapper around Index-Education's Pronote internal API.

Supported

Versions

Note about versions before 2022 : This package wasn't tested concerning those, so not sure if it works but it should since not a lot of breaking changes were made.

• 2022
• Latest, 2023

Sessions

• Encrypted
• Compressed

Accounts

• élève (student)
• parent

A support for other accounts will be added in the future.

Authentication

• By username and password (no ENT)
• By username and token
• By QR Code
• By injecting ENT cookies (see below)

ENT native support is not and will never be supported by Pawnote, for the simple reason that implementing all of them with all of their specificities requires a lot of time and effort. It's simply a pain to implement and track, as a matter of fact, most of the issues on pronotepy - a similar project - are related to ENTs.

Even though, if you want to, you can code your own ENT solution and feed the cookies to Pawnote in the authenticateFromENTCookies (not done yet) function. That'll authenticate you using the ENT cookies you provided and will give you back a Pronote instance with a nextTimeToken that you can use to authenticate next time, just like every other authentication methods.

Note about demonstration servers

Credentials authentication works, but token authentication won't work. This is because demo servers doesn't save next-time tokens, even if it's able to generate them.

You can know if a server is a demo or not by getting the isDemo property on a Pronote instance. It returns a boolean that is true when the server is a demo.

Features

• Timetable (per week and from/to dates)
  • parser: StudentTimetableLesson
  • parser: StudentSubject
  • client: .requestTimetableForWeek(weekNumber)
  • client: .requestLessonsForInterval(from[, to])
• Homework (per week and from/to dates)
  • client: .getHomeworkForInterval(from[, to])
  • client: .getHomeworkForWeek(weekNumber)
  • client: all homework for a specific lesson .getLessonHomework(lessonResourceId)
  • parser: StudentHomework
  • parser: parse attachments using StudentAttachment
• Update homework status
  • client: .patchHomeworkStatus(homeworkID, done)
  • parser: StudentHomework.setDone(done)
• Attachment
  • parser: StudentAttachment
  • parser: able to get/build attachment's URL
• Resources (per week and from/to dates)
  • client: .getResourcesForInterval(from[, to])
  • client: .getResourcesForWeek(weekNumber)
  • client: .getLessonResource(lessonResourceId)
  • parser: StudentLessonResource
• Find Pronote instances with longitude and latitude
  • findPronoteInstances(fetcher, { longitude, latitude })
• Get information about an instance from its URL
  • getPronoteInstanceInformation(fetcher, { pronoteURL })
• Periods
  • client: .periods (property)
  • parser: Period
• Grades & Averages
  • client: .getGradesOverviewForPeriod(period)
  • parser: Period.getGradesOverview()
  • parser: StudentGrade
  • parser: StudentAverage
• Evaluations and Skills (= Acquisition)
  • client: .getEvaluationsForPeriod(period)
  • parser: Period.getEvaluations()
  • parser: StudentEvaluation
  • parser: StudentSkill
• Personal Information on Student Account
  • client: .getPersonalInformation()
  • parser: StudentPersonalInformation
• Custom fetcher to call the API with another API than fetch
• Sends Presence requests to keep alive the connection
  • client: .startPresenceRequests()
  • client: .stopPresenceRequests()
• Error handlers
  • PawnoteNetworkFail
  • PawnoteBadCredentials
  • ... (more to come)

Installation

Use your favorite package manager to install Pawnote from NPM.

# pnpm
pnpm add pawnote

# Yarn
yarn add pawnote

# npm
npm install pawnote

Usage

You can see multiple examples in the examples folder.

Tauri

Since Pawnote uses fetch as default fetcher, you need to use a custom fetcher to make it work with the Tauri HTTP API.

Here's an example fetcher made to work with Tauri (v1) :

import { type PawnoteFetcher } from "pawnote";
import { Body, ResponseType, getClient } from "@tauri-apps/api/http";

const tauriPawnoteFetcher: PawnoteFetcher = async (url, options) => {
  const client = await getClient(options.redirect === "manual" ? {
    maxRedirections: 0
  }: void 0);

  const response = await client.request<string>({
    url,
    method: options.method,
    headers: options.headers,
    body: options.method !== "GET" && options.body ? Body.text(options.body) : void 0,
    responseType: ResponseType.Text
  });

  return {
    headers: response.headers,
    text: async () => response.data,
    json: async <T>() => JSON.parse(response.data) as T
  }
};

export default tauriPawnoteFetcher;

API

Documentation is not yet available, for now you'll have to use intellisense. Most of the methods are self-explanatory and well commented.

We'll see if we can generate a documentation website using comments from the source code in the future.

Resources

Without these very useful resources, I wouldn't be able to write this whole client by myself.

• Pronote Protocol written by developers of pronotepy.
• pronote-api's (forked/archived) source code.
• pronotepy's source code.
• Pronote QR Code API
• Read encrypted/compressed responses from Pronote