n8n-nodes-pronote 0.1.2

package/README.md

@@ -0,0 +1,24 @@
+## n8n PRONOTE nodes
+
+Custom n8n nodes and small agent helpers that talk to PRONOTE using the same Pawnote flow as the mobile app (mobile user-agent, device UUID, `loginCredentials` / `loginToken` + `createSessionHandle`).
+
+### Available resources
+- Timetable: fetches the week for a reference date (defaults to today) and groups classes by day.
+- Tasks: homework for the week of a reference date, with an `onlyPending` toggle.
+- Grades: list available periods or pull an overview (student/class averages plus detailed grades per subject).
+
+### Installation
+1) `cd n8n-node-pronote`
+2) Install deps: `npm install`
+3) Build: `npm run build`
+4) Copy/symlink the `dist` folder into your n8n custom nodes directory, or publish the package to a registry and install it in n8n.
+
+### Credentials
+Configure the **PRONOTE API** credentials in n8n:
+- Authentication mode: `Username and Password` or `Existing Mobile Token` (the `mdp` token from a prior mobile login).
+- Instance URL: full PRONOTE base URL (the node normalizes it with Pawnote `cleanURL`).
+- Device UUID: optional but recommended so the instance does not ask to re-validate a new device every run.
+- Account kind: Student/Parent/Teacher (defaults to Student).
+
+### Agent helpers
+See `agent-tools/pronoteTools.ts` for a thin wrapper you can drop into LLM agent stacks. It reuses the same login and fetch functions as the node.

package/dist/agent-tools/pronoteTools.d.ts

@@ -0,0 +1,8 @@
+import { type GradeOverviewResponse, type GradePeriodInfo, type HomeworkItem, type PronoteLoginOptions, type TimetableDay } from "../shared/pawnoteClient";
+export interface PronoteAgentTools {
+    getTimetable: (referenceDate?: Date | string) => Promise<TimetableDay[]>;
+    getTasks: (referenceDate?: Date | string) => Promise<HomeworkItem[]>;
+    getGrades: (periodName?: string) => Promise<GradeOverviewResponse>;
+    getGradePeriods: () => Promise<GradePeriodInfo[]>;
+}
+export declare function createPronoteAgent(options: PronoteLoginOptions): Promise<PronoteAgentTools>;

package/dist/agent-tools/pronoteTools.js

@@ -0,0 +1,23 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.createPronoteAgent = createPronoteAgent;
+const pawnoteClient_1 = require("../shared/pawnoteClient");
+async function createPronoteAgent(options) {
+    const auth = await (0, pawnoteClient_1.createPronoteSession)(options);
+    return {
+        getTimetable: (referenceDate) => (0, pawnoteClient_1.fetchTimetable)(auth.session, normalizeDate(referenceDate)),
+        getTasks: (referenceDate) => (0, pawnoteClient_1.fetchAssignments)(auth.session, normalizeDate(referenceDate)),
+        getGrades: (periodName) => (0, pawnoteClient_1.fetchGrades)(auth.session, periodName),
+        getGradePeriods: () => (0, pawnoteClient_1.fetchGradePeriods)(auth.session),
+    };
+}
+function normalizeDate(referenceDate) {
+    if (!referenceDate) {
+        return new Date();
+    }
+    const date = typeof referenceDate === "string" ? new Date(referenceDate) : referenceDate;
+    if (Number.isNaN(date.getTime())) {
+        throw new Error(`Invalid reference date: ${referenceDate}`);
+    }
+    return date;
+}

package/dist/credentials/PronoteApi.credentials.d.ts

@@ -0,0 +1,7 @@
+import type { ICredentialType, INodeProperties } from "n8n-workflow";
+export declare class PronoteApi implements ICredentialType {
+    name: string;
+    displayName: string;
+    documentationUrl: string;
+    properties: INodeProperties[];
+}

package/dist/credentials/PronoteApi.credentials.js

@@ -0,0 +1,101 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.PronoteApi = void 0;
+class PronoteApi {
+    constructor() {
+        this.name = "pronoteApi";
+        this.displayName = "PRONOTE API";
+        this.documentationUrl = "https://pawnote.docs.literate.ink/";
+        this.properties = [
+            {
+                displayName: "Authentication Mode",
+                name: "authMode",
+                type: "options",
+                default: "credentials",
+                options: [
+                    {
+                        name: "Username and Password",
+                        value: "credentials",
+                    },
+                    {
+                        name: "Existing Mobile Token",
+                        value: "token",
+                    },
+                ],
+            },
+            {
+                displayName: "Instance URL",
+                name: "instanceUrl",
+                type: "string",
+                default: "",
+                placeholder: "https://example.index-education.net/pronote",
+                description: "Base URL of the PRONOTE instance",
+            },
+            {
+                displayName: "Username",
+                name: "username",
+                type: "string",
+                default: "",
+                description: "PRONOTE username",
+            },
+            {
+                displayName: "Password",
+                name: "password",
+                type: "string",
+                typeOptions: {
+                    password: true,
+                },
+                default: "",
+                description: "PRONOTE password",
+                displayOptions: {
+                    show: {
+                        authMode: ["credentials"],
+                    },
+                },
+            },
+            {
+                displayName: "Mobile Token",
+                name: "token",
+                type: "string",
+                typeOptions: {
+                    password: true,
+                },
+                default: "",
+                description: "Mobile token (mdp) obtained from a prior mobile login",
+                displayOptions: {
+                    show: {
+                        authMode: ["token"],
+                    },
+                },
+            },
+            {
+                displayName: "Device UUID",
+                name: "deviceUUID",
+                type: "string",
+                default: "",
+                description: "Optional persistent device UUID to reuse across logins",
+            },
+            {
+                displayName: "Account Kind",
+                name: "kind",
+                type: "options",
+                default: "STUDENT",
+                options: [
+                    {
+                        name: "Student",
+                        value: "STUDENT",
+                    },
+                    {
+                        name: "Parent",
+                        value: "PARENT",
+                    },
+                    {
+                        name: "Teacher",
+                        value: "TEACHER",
+                    },
+                ],
+            },
+        ];
+    }
+}
+exports.PronoteApi = PronoteApi;

package/dist/nodes/Pronote/GenericFunctions.d.ts

@@ -0,0 +1,6 @@
+import type { IExecuteFunctions, ILoadOptionsFunctions } from "n8n-workflow";
+import { type PronoteAuthContext } from "../../shared/pawnoteClient";
+type Context = IExecuteFunctions | ILoadOptionsFunctions;
+export declare function getPronoteAuth(context: Context, itemIndex?: number): Promise<PronoteAuthContext>;
+export declare function resolveReferenceDate(raw?: string): Date;
+export {};

package/dist/nodes/Pronote/GenericFunctions.js

@@ -0,0 +1,30 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.getPronoteAuth = getPronoteAuth;
+exports.resolveReferenceDate = resolveReferenceDate;
+const pawnoteClient_1 = require("../../shared/pawnoteClient");
+async function getPronoteAuth(context, itemIndex = 0) {
+    const credentials = (await context.getCredentials("pronoteApi"));
+    if (!credentials) {
+        throw new Error("Pronote credentials are missing. Please configure the Pronote API credentials.");
+    }
+    return (0, pawnoteClient_1.createPronoteSession)({
+        instanceUrl: credentials.instanceUrl,
+        username: credentials.username,
+        password: credentials.password,
+        token: credentials.token,
+        deviceUUID: credentials.deviceUUID,
+        kind: credentials.kind,
+        authMode: credentials.authMode,
+    });
+}
+function resolveReferenceDate(raw) {
+    if (!raw) {
+        return new Date();
+    }
+    const date = new Date(raw);
+    if (Number.isNaN(date.getTime())) {
+        throw new Error(`Invalid date provided: ${raw}`);
+    }
+    return date;
+}

package/dist/nodes/Pronote/Pronote.node.d.ts

@@ -0,0 +1,5 @@
+import type { IExecuteFunctions, INodeExecutionData, INodeType, INodeTypeDescription } from "n8n-workflow";
+export declare class Pronote implements INodeType {
+    description: INodeTypeDescription;
+    execute(this: IExecuteFunctions): Promise<INodeExecutionData[][]>;
+}

package/dist/nodes/Pronote/Pronote.node.js

@@ -0,0 +1,265 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.Pronote = void 0;
+const pawnoteClient_1 = require("../../shared/pawnoteClient");
+const GenericFunctions_1 = require("./GenericFunctions");
+class Pronote {
+    constructor() {
+        this.description = {
+            displayName: "PRONOTE",
+            name: "pronote",
+            group: ["transform"],
+            icon: "file:pronote.svg",
+            version: 1,
+            subtitle: "={{ $parameter[\"operation\"] + \": \" + $parameter[\"resource\"] }}",
+            description: "Interact with PRONOTE using the Pawnote client",
+            defaults: {
+                name: "PRONOTE",
+            },
+            inputs: ["main"],
+            outputs: ["main"],
+            credentials: [
+                {
+                    name: "pronoteApi",
+                    required: true,
+                },
+            ],
+            properties: [
+                {
+                    displayName: "Resource",
+                    name: "resource",
+                    type: "options",
+                    options: [
+                        {
+                            name: "Timetable",
+                            value: "timetable",
+                        },
+                        {
+                            name: "Tasks",
+                            value: "tasks",
+                        },
+                        {
+                            name: "Grades",
+                            value: "grades",
+                        },
+                    ],
+                    default: "timetable",
+                },
+                {
+                    displayName: "Operation",
+                    name: "operation",
+                    type: "options",
+                    displayOptions: {
+                        show: {
+                            resource: ["timetable"],
+                        },
+                    },
+                    options: [
+                        {
+                            name: "Get Week",
+                            value: "get",
+                            description: "Fetch the timetable for the week of a reference date",
+                            action: "Get timetable",
+                        },
+                    ],
+                    default: "get",
+                },
+                {
+                    displayName: "Reference Date",
+                    name: "referenceDate",
+                    type: "string",
+                    placeholder: "2024-09-01",
+                    default: "",
+                    description: "Date used to compute the PRONOTE week (ISO 8601). Defaults to today.",
+                    displayOptions: {
+                        show: {
+                            resource: ["timetable"],
+                            operation: ["get"],
+                        },
+                    },
+                },
+                {
+                    displayName: "Operation",
+                    name: "operation",
+                    type: "options",
+                    displayOptions: {
+                        show: {
+                            resource: ["tasks"],
+                        },
+                    },
+                    options: [
+                        {
+                            name: "Get Week",
+                            value: "get",
+                            description: "Fetch homework/tasks for the week of a reference date",
+                            action: "Get tasks",
+                        },
+                    ],
+                    default: "get",
+                },
+                {
+                    displayName: "Reference Date",
+                    name: "referenceDate",
+                    type: "string",
+                    placeholder: "2024-09-01",
+                    default: "",
+                    description: "Date used to compute the PRONOTE week (ISO 8601). Defaults to today.",
+                    displayOptions: {
+                        show: {
+                            resource: ["tasks"],
+                            operation: ["get"],
+                        },
+                    },
+                },
+                {
+                    displayName: "Only Pending",
+                    name: "onlyPending",
+                    type: "boolean",
+                    default: false,
+                    description: "If enabled, completed tasks are filtered out",
+                    displayOptions: {
+                        show: {
+                            resource: ["tasks"],
+                            operation: ["get"],
+                        },
+                    },
+                },
+                {
+                    displayName: "Operation",
+                    name: "operation",
+                    type: "options",
+                    displayOptions: {
+                        show: {
+                            resource: ["grades"],
+                        },
+                    },
+                    options: [
+                        {
+                            name: "Get Overview",
+                            value: "get",
+                            description: "Fetch averages and detailed grades for a period",
+                            action: "Get grades",
+                        },
+                        {
+                            name: "List Periods",
+                            value: "listPeriods",
+                            description: "List all available grade periods",
+                            action: "List grade periods",
+                        },
+                    ],
+                    default: "get",
+                },
+                {
+                    displayName: "Period Name or ID",
+                    name: "periodName",
+                    type: "string",
+                    default: "",
+                    description: "Name or ID of the grade period. Defaults to the first available period.",
+                    displayOptions: {
+                        show: {
+                            resource: ["grades"],
+                            operation: ["get"],
+                        },
+                    },
+                },
+                {
+                    displayName: "Include Individual Grades",
+                    name: "includeGrades",
+                    type: "boolean",
+                    default: true,
+                    description: "Return individual grade entries along with averages",
+                    displayOptions: {
+                        show: {
+                            resource: ["grades"],
+                            operation: ["get"],
+                        },
+                    },
+                },
+            ],
+        };
+    }
+    async execute() {
+        const items = this.getInputData();
+        const returnData = [];
+        let auth = null;
+        const ensureAuth = async () => {
+            if (!auth) {
+                auth = await (0, GenericFunctions_1.getPronoteAuth)(this);
+            }
+            return auth;
+        };
+        for (let i = 0; i < items.length; i++) {
+            const resource = this.getNodeParameter("resource", i);
+            const operation = this.getNodeParameter("operation", i);
+            const { session } = await ensureAuth();
+            if (resource === "timetable") {
+                if (operation !== "get") {
+                    throw new Error(`Unsupported operation ${operation} for timetable resource.`);
+                }
+                const dateInput = this.getNodeParameter("referenceDate", i);
+                const referenceDate = (0, GenericFunctions_1.resolveReferenceDate)(dateInput);
+                const timetable = await (0, pawnoteClient_1.fetchTimetable)(session, referenceDate);
+                for (const day of timetable) {
+                    returnData.push({ json: day });
+                }
+                continue;
+            }
+            if (resource === "tasks") {
+                if (operation !== "get") {
+                    throw new Error(`Unsupported operation ${operation} for tasks resource.`);
+                }
+                const dateInput = this.getNodeParameter("referenceDate", i);
+                const onlyPending = this.getNodeParameter("onlyPending", i);
+                const referenceDate = (0, GenericFunctions_1.resolveReferenceDate)(dateInput);
+                const assignments = await (0, pawnoteClient_1.fetchAssignments)(session, referenceDate);
+                for (const assignment of assignments) {
+                    if (onlyPending && assignment.isDone) {
+                        continue;
+                    }
+                    returnData.push({ json: assignment });
+                }
+                continue;
+            }
+            if (resource === "grades") {
+                if (operation === "listPeriods") {
+                    const periods = await (0, pawnoteClient_1.fetchGradePeriods)(session);
+                    for (const period of periods) {
+                        returnData.push({ json: period });
+                    }
+                    continue;
+                }
+                if (operation === "get") {
+                    const periodName = this.getNodeParameter("periodName", i).trim() || undefined;
+                    const includeGrades = this.getNodeParameter("includeGrades", i);
+                    const overview = await (0, pawnoteClient_1.fetchGrades)(session, periodName);
+                    if (!includeGrades) {
+                        returnData.push({
+                            json: {
+                                period: overview.period,
+                                studentOverall: overview.studentOverall,
+                                classAverage: overview.classAverage,
+                                subjects: overview.subjects.map((subject) => ({
+                                    id: subject.id,
+                                    name: subject.name,
+                                    studentAverage: subject.studentAverage,
+                                    classAverage: subject.classAverage,
+                                    maximum: subject.maximum,
+                                    minimum: subject.minimum,
+                                    outOf: subject.outOf,
+                                })),
+                            },
+                        });
+                    }
+                    else {
+                        returnData.push({ json: overview });
+                    }
+                    continue;
+                }
+                throw new Error(`Unsupported operation ${operation} for grades resource.`);
+            }
+            throw new Error(`Unknown resource ${resource}.`);
+        }
+        return [returnData];
+    }
+}
+exports.Pronote = Pronote;

package/dist/shared/pawnoteClient.d.ts

@@ -0,0 +1,109 @@
+import { AccountKind, type SessionHandle } from "pawnote";
+export declare const pronoteUserAgent = "Mozilla/5.0 (iPhone; CPU iPhone OS 19_0 like Mac OS X) AppleWebKit/605.1.15 (KHTML, like Gecko) Mobile/15E148 PRONOTE Mobile APP Version/2.0.11";
+export type PronoteAuthMode = "credentials" | "token";
+export interface PronoteLoginOptions {
+    instanceUrl: string;
+    username: string;
+    password?: string;
+    token?: string;
+    deviceUUID?: string;
+    kind?: AccountKind | keyof typeof AccountKind;
+    authMode?: PronoteAuthMode;
+}
+export interface PronoteAuthContext {
+    session: SessionHandle;
+    token: string;
+    username: string;
+    kind: AccountKind;
+    url: string;
+    deviceUUID: string;
+}
+export interface TimetableCourse {
+    id: string;
+    type: "lesson" | "detention" | "activity";
+    subject?: string;
+    title?: string;
+    room?: string;
+    teacher?: string;
+    group?: string;
+    status?: string;
+    from: string;
+    to: string;
+    notes?: string;
+    resourceId?: string;
+    backgroundColor?: string;
+    [key: string]: unknown;
+}
+export interface TimetableDay {
+    date: string;
+    courses: TimetableCourse[];
+    [key: string]: unknown;
+}
+export interface HomeworkAttachment {
+    name: string;
+    url: string;
+    type: string | number;
+    [key: string]: unknown;
+}
+export interface HomeworkItem {
+    id: string;
+    subject: string;
+    description: string;
+    dueDate: string;
+    isDone: boolean;
+    returnKind: string;
+    attachments: HomeworkAttachment[];
+    [key: string]: unknown;
+}
+export interface GradePeriodInfo {
+    id: string;
+    name: string;
+    start: string;
+    end: string;
+    [key: string]: unknown;
+}
+export interface GradeScore {
+    value: number;
+    disabled?: boolean;
+    status?: string;
+    [key: string]: unknown;
+}
+export interface GradeEntry {
+    id: string;
+    subjectId: string;
+    subjectName: string;
+    description?: string;
+    givenAt: string;
+    bonus: boolean;
+    optional: boolean;
+    outOf: GradeScore;
+    coefficient?: number;
+    studentScore: GradeScore;
+    averageScore: GradeScore;
+    minScore: GradeScore;
+    maxScore: GradeScore;
+    [key: string]: unknown;
+}
+export interface SubjectGrades {
+    id: string;
+    name: string;
+    studentAverage: GradeScore;
+    classAverage: GradeScore;
+    maximum: GradeScore;
+    minimum: GradeScore;
+    outOf: GradeScore;
+    grades: GradeEntry[];
+    [key: string]: unknown;
+}
+export interface GradeOverviewResponse {
+    period: GradePeriodInfo;
+    studentOverall: GradeScore;
+    classAverage: GradeScore;
+    subjects: SubjectGrades[];
+    [key: string]: unknown;
+}
+export declare function createPronoteSession(options: PronoteLoginOptions): Promise<PronoteAuthContext>;
+export declare function fetchTimetable(session: SessionHandle, referenceDate: Date): Promise<TimetableDay[]>;
+export declare function fetchAssignments(session: SessionHandle, referenceDate: Date): Promise<HomeworkItem[]>;
+export declare function fetchGradePeriods(session: SessionHandle): Promise<GradePeriodInfo[]>;
+export declare function fetchGrades(session: SessionHandle, periodName?: string): Promise<GradeOverviewResponse>;

package/dist/shared/pawnoteClient.js

@@ -0,0 +1,280 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.pronoteUserAgent = void 0;
+exports.createPronoteSession = createPronoteSession;
+exports.fetchTimetable = fetchTimetable;
+exports.fetchAssignments = fetchAssignments;
+exports.fetchGradePeriods = fetchGradePeriods;
+exports.fetchGrades = fetchGrades;
+const crypto_1 = require("crypto");
+const pawnote_1 = require("pawnote");
+exports.pronoteUserAgent = "Mozilla/5.0 (iPhone; CPU iPhone OS 19_0 like Mac OS X) AppleWebKit/605.1.15 (KHTML, like Gecko) Mobile/15E148 PRONOTE Mobile APP Version/2.0.11";
+const pawnoteFetcher = async (options) => {
+    const response = await fetch(options.url, {
+        method: options.method,
+        headers: {
+            ...options.headers,
+            "User-Agent": exports.pronoteUserAgent,
+        },
+        body: options.method !== "GET" ? options.content : undefined,
+        redirect: options.redirect,
+    });
+    const content = await response.text();
+    return {
+        content,
+        status: response.status,
+        get headers() {
+            return response.headers;
+        },
+    };
+};
+async function createPronoteSession(options) {
+    const url = (0, pawnote_1.cleanURL)(options.instanceUrl);
+    const authMode = options.authMode ?? "credentials";
+    const deviceUUID = ensureDeviceUUID(options.deviceUUID);
+    const kind = normalizeKind(options.kind);
+    const session = (0, pawnote_1.createSessionHandle)(pawnoteFetcher);
+    if (authMode === "token") {
+        if (!options.token) {
+            throw new Error("Missing PRONOTE token for token-based login.");
+        }
+        const auth = await (0, pawnote_1.loginToken)(session, {
+            url,
+            kind,
+            username: options.username,
+            token: options.token,
+            deviceUUID,
+        });
+        return {
+            session,
+            token: auth.token,
+            username: auth.username,
+            kind: auth.kind,
+            url: auth.url,
+            deviceUUID,
+        };
+    }
+    if (!options.password) {
+        throw new Error("Missing password for credential-based login.");
+    }
+    const auth = await (0, pawnote_1.loginCredentials)(session, {
+        url,
+        kind,
+        username: options.username,
+        password: options.password,
+        deviceUUID,
+    });
+    return {
+        session,
+        token: auth.token,
+        username: auth.username,
+        kind: auth.kind,
+        url: auth.url,
+        deviceUUID,
+    };
+}
+async function fetchTimetable(session, referenceDate) {
+    const weekNumber = (0, pawnote_1.translateToWeekNumber)(referenceDate, session.instance.firstMonday);
+    const timetable = await (0, pawnote_1.timetableFromWeek)(session, weekNumber);
+    (0, pawnote_1.parseTimetable)(session, timetable, {
+        withSuperposedCanceledClasses: false,
+        withCanceledClasses: true,
+        withPlannedClasses: true,
+    });
+    const mappedCourses = timetable.classes.map(mapCourse);
+    const grouped = {};
+    for (const course of mappedCourses) {
+        const dayKey = course.from.split("T")[0];
+        if (!grouped[dayKey]) {
+            grouped[dayKey] = [];
+        }
+        grouped[dayKey].push(course);
+    }
+    return Object.entries(grouped)
+        .sort(([a], [b]) => new Date(a).getTime() - new Date(b).getTime())
+        .map(([date, courses]) => ({
+        date,
+        courses: courses.sort((a, b) => new Date(a.from).getTime() - new Date(b.from).getTime()),
+    }));
+}
+async function fetchAssignments(session, referenceDate) {
+    const weekNumber = (0, pawnote_1.translateToWeekNumber)(referenceDate, session.instance.firstMonday);
+    const assignments = await (0, pawnote_1.assignmentsFromWeek)(session, weekNumber);
+    return assignments.map((assignment) => ({
+        id: assignment.id,
+        subject: assignment.subject.name,
+        description: assignment.description,
+        dueDate: serializeDate(assignment.deadline),
+        isDone: assignment.done,
+        returnKind: assignment.return.kind === 1 ? "paper" : "upload",
+        attachments: assignment.attachments.map((attachment) => ({
+            type: attachment.kind,
+            name: attachment.name,
+            url: attachment.url,
+        })),
+    }));
+}
+async function fetchGradePeriods(session) {
+    const gradeTab = session.user.resources[0].tabs.get(pawnote_1.TabLocation.Grades);
+    if (!gradeTab) {
+        throw new Error("Grades tab not available for this account.");
+    }
+    return gradeTab.periods.map((period) => ({
+        id: period.id,
+        name: period.name,
+        start: serializeDate(period.startDate),
+        end: serializeDate(period.endDate),
+    }));
+}
+async function fetchGrades(session, periodName) {
+    const gradeTab = session.user.resources[0].tabs.get(pawnote_1.TabLocation.Grades);
+    if (!gradeTab) {
+        throw new Error("Grades tab not available for this account.");
+    }
+    const period = pickPeriod(gradeTab.periods, periodName);
+    const overview = await (0, pawnote_1.gradesOverview)(session, period);
+    return {
+        period: {
+            id: period.id,
+            name: period.name,
+            start: serializeDate(period.startDate),
+            end: serializeDate(period.endDate),
+        },
+        studentOverall: mapGradeValueToScore(overview.overallAverage),
+        classAverage: mapGradeValueToScore(overview.classAverage),
+        subjects: mapSubjects(overview),
+    };
+}
+function normalizeKind(kind) {
+    if (typeof kind === "number") {
+        return kind;
+    }
+    if (typeof kind === "string") {
+        const key = kind.toUpperCase();
+        if (pawnote_1.AccountKind[key]) {
+            return pawnote_1.AccountKind[key];
+        }
+    }
+    return pawnote_1.AccountKind.STUDENT;
+}
+function ensureDeviceUUID(deviceUUID) {
+    if (deviceUUID && deviceUUID.trim().length > 0) {
+        return deviceUUID.trim();
+    }
+    try {
+        return (0, crypto_1.randomUUID)();
+    }
+    catch {
+        return Math.random().toString(16).slice(2);
+    }
+}
+function serializeDate(date) {
+    return date.toISOString();
+}
+function mapCourse(course) {
+    const base = {
+        id: course.id,
+        from: serializeDate(course.startDate),
+        to: serializeDate(course.endDate),
+        notes: course.notes,
+        backgroundColor: course.backgroundColor,
+    };
+    if (course.is === "lesson") {
+        return {
+            ...base,
+            type: "lesson",
+            subject: course.subject?.name,
+            room: course.classrooms.join(", "),
+            teacher: course.teacherNames.join(", "),
+            group: course.groupNames.join(", "),
+            status: course.status,
+            resourceId: course.lessonResourceID,
+        };
+    }
+    if (course.is === "detention") {
+        return {
+            ...base,
+            type: "detention",
+            title: course.title ?? "Detention",
+            room: course.classrooms.join(", "),
+        };
+    }
+    return {
+        ...base,
+        type: "activity",
+        title: course.title,
+    };
+}
+function mapSubjects(overview) {
+    const grades = overview.grades.map((grade) => mapGrade(grade));
+    const subjects = [];
+    for (const subjectAverage of overview.subjectsAverages) {
+        const subjectGrades = grades.filter((g) => g.subjectId === subjectAverage.subject.id);
+        subjects.push({
+            id: subjectAverage.subject.id,
+            name: subjectAverage.subject.name,
+            studentAverage: mapGradeValueToScore(subjectAverage.student),
+            classAverage: mapGradeValueToScore(subjectAverage.class_average),
+            maximum: mapGradeValueToScore(subjectAverage.max),
+            minimum: mapGradeValueToScore(subjectAverage.min),
+            outOf: mapGradeValueToScore(subjectAverage.outOf),
+            grades: subjectGrades,
+        });
+    }
+    return subjects;
+}
+function mapGrade(grade) {
+    return {
+        id: grade.id,
+        subjectId: grade.subject.id,
+        subjectName: grade.subject.name,
+        description: grade.comment,
+        givenAt: serializeDate(grade.date),
+        bonus: grade.isBonus ?? false,
+        optional: grade.isOptional ?? false,
+        outOf: mapGradeValueToScore(grade.outOf),
+        coefficient: grade.coefficient,
+        studentScore: mapGradeValueToScore(grade.value),
+        averageScore: mapGradeValueToScore(grade.average),
+        minScore: mapGradeValueToScore(grade.min),
+        maxScore: mapGradeValueToScore(grade.max),
+    };
+}
+function mapGradeValueToScore(grade) {
+    if (typeof grade === "undefined") {
+        return { value: 0, disabled: true, status: "unknown" };
+    }
+    switch (grade.kind) {
+        case pawnote_1.GradeKind.Grade:
+            return { value: grade.points ?? 0 };
+        case pawnote_1.GradeKind.NotGraded:
+            return { value: 0, disabled: true, status: "not graded" };
+        case pawnote_1.GradeKind.Absent:
+            return { value: 0, disabled: true, status: "absent" };
+        case pawnote_1.GradeKind.AbsentZero:
+            return { value: 0, disabled: false, status: "absent zero" };
+        case pawnote_1.GradeKind.Exempted:
+            return { value: 0, disabled: true, status: "exempted" };
+        case pawnote_1.GradeKind.Unfit:
+            return { value: 0, disabled: true, status: "unfit" };
+        case pawnote_1.GradeKind.Unreturned:
+            return { value: 0, disabled: true, status: "not returned" };
+        case pawnote_1.GradeKind.UnreturnedZero:
+            return { value: 0, disabled: false, status: "not returned zero" };
+        default:
+            return { value: 0, disabled: true, status: "unknown" };
+    }
+}
+function pickPeriod(periods, periodName) {
+    if (!periods.length) {
+        throw new Error("No grade periods are available for this account.");
+    }
+    if (!periodName) {
+        return periods[0];
+    }
+    const period = periods.find((p) => p.name.toLowerCase() === periodName.toLowerCase() || p.id === periodName);
+    if (!period) {
+        throw new Error(`Grade period "${periodName}" was not found.`);
+    }
+    return period;
+}

package/package.json

@@ -0,0 +1,37 @@
+{
+  "name": "n8n-nodes-pronote",
+  "version": "0.1.2",
+  "description": "n8n custom nodes and agent utilities to talk to PRONOTE via the Pawnote library.",
+  "license": "MIT",
+  "main": "dist/nodes/Pronote/Pronote.node.js",
+  "types": "dist/nodes/Pronote/Pronote.node.d.ts",
+  "scripts": {
+    "build": "tsc -p .",
+    "clean": "rimraf dist"
+  },
+  "files": [
+    "dist"
+  ],
+  "dependencies": {
+    "pawnote": "^1.6.2"
+  },
+  "peerDependencies": {
+    "n8n-core": "^1.0.0",
+    "n8n-workflow": "^1.0.0"
+  },
+  "devDependencies": {
+    "@types/node": "^22.7.4",
+    "n8n-core": "^1.0.0",
+    "n8n-workflow": "^1.0.0",
+    "rimraf": "^6.0.1",
+    "typescript": "^5.6.2"
+  },
+  "n8n": {
+    "nodes": [
+      "dist/nodes/Pronote/Pronote.node.js"
+    ],
+    "credentials": [
+      "dist/credentials/PronoteApi.credentials.js"
+    ]
+  }
+}