n8n-nodes-pronote 0.1.2 → 0.2.1

package/README.md

@@ -1,14 +1,16 @@
 ## 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`).
+Custom n8n nodes and small agent helpers that talk to PRONOTE using the Pawnote (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).
+- **PRONOTE Tool (AI Agents)**: an `ai_tool` node that exposes timetable, tasks, grades, and grade-period listing to AI Agent nodes. The model can set `action`, `referenceDate` (ISO), `periodName`, `onlyPendingTasks`, and `includeGrades`.
+- **PRONOTE Auth Helper**: prepares the mobile validation flow (InfoMobileApp + device UUID for Lycée Connecté/CAS) and validates `mdp` mobile tokens into a usable session/token. Also supports direct username/password login when CAS is not needed.
 
 ### Installation
-1) `cd n8n-node-pronote`
+1) `cd n8n-nodes-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.
@@ -21,4 +23,9 @@ Configure the **PRONOTE API** credentials in n8n:
 - 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.
+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. For no-code agent flows, drop the **PRONOTE Tool** node into an AI Agent graph and wire it to your agent; the model will decide which action to call and can set the reference date or period dynamically.
+
+### Auth helper flow (Lycée Connecté / CAS)
+1) Run **PRONOTE Auth Helper** with operation “Prepare Mobile Validation” and your instance URL. It returns a `deviceUUID` and the `InfoMobileApp.json` URL.
+2) Open that URL in a browser, approve the device in your CAS portal (e.g., Lycée Connecté). Capture the returned `login` and `mdp` (token).
+3) Run **PRONOTE Auth Helper** with operation “Validate Mobile Token”, providing the `instanceUrl`, `login`, `mdp`, and the same `deviceUUID`. The node outputs a verified token plus user details—use these in the PRONOTE credentials.

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

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

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

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

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

@@ -0,0 +1,233 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.PronoteAuthHelper = void 0;
+const crypto_1 = require("crypto");
+const pawnote_1 = require("pawnote");
+const n8n_workflow_1 = require("n8n-workflow");
+const pawnoteClient_1 = require("../../shared/pawnoteClient");
+class PronoteAuthHelper {
+    constructor() {
+        this.description = {
+            displayName: "PRONOTE Auth Helper",
+            name: "pronoteAuthHelper",
+            icon: "file:pronote.svg",
+            group: ["transform"],
+            version: 1,
+            description: "Assist with PRONOTE mobile/CAS token retrieval and validation",
+            subtitle: "={{ $parameter[\"operation\"] }}",
+            defaults: {
+                name: "PRONOTE Auth Helper",
+            },
+            inputs: [n8n_workflow_1.NodeConnectionTypes.Main],
+            outputs: [n8n_workflow_1.NodeConnectionTypes.Main],
+            outputNames: ["Result"],
+            properties: [
+                {
+                    displayName: "Operation",
+                    name: "operation",
+                    type: "options",
+                    options: [
+                        {
+                            name: "Prepare Mobile Validation",
+                            value: "prepare",
+                            description: "Generate device UUID and InfoMobileApp URL to start the mobile validation flow (Lycée Connecté/CAS)",
+                            action: "Prepare mobile validation",
+                        },
+                        {
+                            name: "Validate Mobile Token",
+                            value: "validate",
+                            description: "Validate an mdp/token obtained after mobile validation and return session details",
+                            action: "Validate mobile token",
+                        },
+                        {
+                            name: "Login with Credentials",
+                            value: "loginCredentials",
+                            description: "Direct username/password login (for instances without external SSO)",
+                            action: "Login with credentials",
+                        },
+                    ],
+                    default: "prepare",
+                },
+                {
+                    displayName: "Instance URL",
+                    name: "instanceUrl",
+                    type: "string",
+                    default: "",
+                    placeholder: "https://example.index-education.net/pronote",
+                    description: "Base URL of the PRONOTE instance",
+                },
+                {
+                    displayName: "Device UUID",
+                    name: "deviceUUID",
+                    type: "string",
+                    default: "",
+                    description: "Optional persistent device UUID. Leave blank to auto-generate.",
+                    displayOptions: {
+                        show: {
+                            operation: ["prepare", "validate", "loginCredentials"],
+                        },
+                    },
+                },
+                {
+                    displayName: "Username",
+                    name: "username",
+                    type: "string",
+                    default: "",
+                    description: "PRONOTE username (or returned login from CAS). Required for validate/login.",
+                    displayOptions: {
+                        show: {
+                            operation: ["validate", "loginCredentials"],
+                        },
+                    },
+                },
+                {
+                    displayName: "Password",
+                    name: "password",
+                    type: "string",
+                    typeOptions: {
+                        password: true,
+                    },
+                    default: "",
+                    description: "PRONOTE password (not used for CAS mobile tokens).",
+                    displayOptions: {
+                        show: {
+                            operation: ["loginCredentials"],
+                        },
+                    },
+                },
+                {
+                    displayName: "Mobile Token (mdp)",
+                    name: "token",
+                    type: "string",
+                    typeOptions: {
+                        password: true,
+                    },
+                    default: "",
+                    description: "The mobile token (mdp) returned after CAS/mobile validation.",
+                    displayOptions: {
+                        show: {
+                            operation: ["validate"],
+                        },
+                    },
+                },
+                {
+                    displayName: "Account Kind",
+                    name: "kind",
+                    type: "options",
+                    default: "STUDENT",
+                    options: [
+                        { name: "Student", value: "STUDENT" },
+                        { name: "Parent", value: "PARENT" },
+                        { name: "Teacher", value: "TEACHER" },
+                    ],
+                    description: "Account type for the session",
+                    displayOptions: {
+                        show: {
+                            operation: ["validate", "loginCredentials"],
+                        },
+                    },
+                },
+            ],
+        };
+    }
+    async execute() {
+        const items = this.getInputData();
+        const returnData = [];
+        for (let i = 0; i < items.length; i++) {
+            const operation = this.getNodeParameter("operation", i);
+            const rawInstance = this.getNodeParameter("instanceUrl", i);
+            const instanceUrl = (0, pawnote_1.cleanURL)(rawInstance);
+            if (!instanceUrl) {
+                throw new n8n_workflow_1.NodeOperationError(this.getNode(), "Instance URL is required.");
+            }
+            if (operation === "prepare") {
+                const deviceUUID = this.getNodeParameter("deviceUUID", i).trim() || (0, crypto_1.randomUUID)();
+                const infoMobileUrl = `${instanceUrl}/InfoMobileApp.json?id=0D264427-EEFC-4810-A9E9-346942A862A4`;
+                const mobileWebviewUrl = `${instanceUrl}/mobile.eleve.html?fd=1`;
+                returnData.push({
+                    json: {
+                        instanceUrl,
+                        deviceUUID,
+                        infoMobileUrl,
+                        mobileWebviewUrl,
+                        instructions: "Open InfoMobileApp.json in a browser, approve the device in the portal (e.g., Lycée Connecté/CAS). " +
+                            "After validation, capture the returned login (username) and mdp (token), then run Validate Mobile Token.",
+                    },
+                });
+                continue;
+            }
+            if (operation === "validate") {
+                const username = this.getNodeParameter("username", i).trim();
+                const token = this.getNodeParameter("token", i).trim();
+                const kindRaw = this.getNodeParameter("kind", i) || "STUDENT";
+                const deviceUUID = this.getNodeParameter("deviceUUID", i).trim() || (0, crypto_1.randomUUID)();
+                if (!username || !token) {
+                    throw new n8n_workflow_1.NodeOperationError(this.getNode(), "Username and mobile token are required.");
+                }
+                const kind = normalizeKind(kindRaw);
+                const auth = await (0, pawnoteClient_1.createPronoteSession)({
+                    instanceUrl,
+                    username,
+                    token,
+                    deviceUUID,
+                    kind,
+                    authMode: "token",
+                });
+                returnData.push({
+                    json: {
+                        instanceUrl: auth.url,
+                        deviceUUID: auth.deviceUUID,
+                        username: auth.username,
+                        token: auth.token,
+                        kind: auth.kind,
+                        userDisplayName: auth.session.user.name,
+                        establishment: auth.session.user.resources[0]?.establishmentName,
+                        className: auth.session.user.resources[0]?.className,
+                    },
+                });
+                continue;
+            }
+            if (operation === "loginCredentials") {
+                const username = this.getNodeParameter("username", i).trim();
+                const password = this.getNodeParameter("password", i).trim();
+                const kindRaw = this.getNodeParameter("kind", i) || "STUDENT";
+                const deviceUUID = this.getNodeParameter("deviceUUID", i).trim() || (0, crypto_1.randomUUID)();
+                if (!username || !password) {
+                    throw new n8n_workflow_1.NodeOperationError(this.getNode(), "Username and password are required.");
+                }
+                const kind = normalizeKind(kindRaw);
+                const auth = await (0, pawnoteClient_1.createPronoteSession)({
+                    instanceUrl,
+                    username,
+                    password,
+                    deviceUUID,
+                    kind,
+                    authMode: "credentials",
+                });
+                returnData.push({
+                    json: {
+                        instanceUrl: auth.url,
+                        deviceUUID: auth.deviceUUID,
+                        username: auth.username,
+                        token: auth.token,
+                        kind: auth.kind,
+                        userDisplayName: auth.session.user.name,
+                        establishment: auth.session.user.resources[0]?.establishmentName,
+                        className: auth.session.user.resources[0]?.className,
+                    },
+                });
+                continue;
+            }
+            throw new n8n_workflow_1.NodeOperationError(this.getNode(), `Unsupported operation "${operation}".`);
+        }
+        return [returnData];
+    }
+}
+exports.PronoteAuthHelper = PronoteAuthHelper;
+function normalizeKind(kind) {
+    if (typeof kind === "number") {
+        return kind;
+    }
+    const key = kind.toUpperCase();
+    return pawnote_1.AccountKind[key] ?? pawnote_1.AccountKind.STUDENT;
+}

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

@@ -0,0 +1,5 @@
+import { type INodeType, type INodeTypeDescription, type ISupplyDataFunctions, type SupplyData } from "n8n-workflow";
+export declare class PronoteTool implements INodeType {
+    description: INodeTypeDescription;
+    supplyData(this: ISupplyDataFunctions): Promise<SupplyData>;
+}

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

@@ -0,0 +1,133 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.PronoteTool = void 0;
+const tools_1 = require("@langchain/core/tools");
+const zod_1 = require("zod");
+const n8n_workflow_1 = require("n8n-workflow");
+const pawnoteClient_1 = require("../../shared/pawnoteClient");
+const GenericFunctions_1 = require("./GenericFunctions");
+class PronoteTool {
+    constructor() {
+        this.description = {
+            displayName: "PRONOTE Tool",
+            name: "pronoteTool",
+            icon: "file:pronote.svg",
+            group: ["transform"],
+            version: 1,
+            description: "Expose PRONOTE timetable, tasks, and grades to AI Agents",
+            subtitle: "={{ $parameter[\"toolDescription\"] || \"PRONOTE tool\" }}",
+            defaults: {
+                name: "PRONOTE Tool",
+            },
+            inputs: [],
+            outputs: [n8n_workflow_1.NodeConnectionTypes.AiTool],
+            outputNames: ["Tool"],
+            credentials: [
+                {
+                    name: "pronoteApi",
+                    required: true,
+                },
+            ],
+            properties: [
+                {
+                    displayName: "Tool Description",
+                    name: "toolDescription",
+                    type: "string",
+                    default: "Use this tool to read timetable, homework/tasks, or grade information from PRONOTE. " +
+                        "Provide action: timetable, tasks, grades, or gradePeriods. " +
+                        "Use referenceDate (ISO) for timetable/tasks; periodName for grades.",
+                    description: "Optional guidance shown to the model about how to use this tool.",
+                    typeOptions: {
+                        rows: 3,
+                    },
+                },
+            ],
+        };
+    }
+    async supplyData() {
+        try {
+            const { session } = await (0, GenericFunctions_1.getPronoteAuth)(this);
+            const tool = new tools_1.DynamicStructuredTool({
+                name: "pronote",
+                description: this.getNodeParameter("toolDescription", 0) ||
+                    "Fetch timetable, homework/tasks, or grade information from PRONOTE. " +
+                        "Actions: timetable, tasks, grades, gradePeriods. " +
+                        "Use referenceDate (ISO date) to target a week for timetable/tasks. " +
+                        "When action=grades, provide periodName (ID or label).",
+                schema: zod_1.z.object({
+                    action: zod_1.z
+                        .enum(["timetable", "tasks", "grades", "gradePeriods"])
+                        .describe("What to retrieve from PRONOTE."),
+                    referenceDate: zod_1.z
+                        .string()
+                        .optional()
+                        .describe("ISO date (e.g. 2024-09-01). Used for timetable and tasks to select the week; defaults to today."),
+                    periodName: zod_1.z
+                        .string()
+                        .optional()
+                        .describe("Grade period name or ID. Used when action=grades."),
+                    onlyPendingTasks: zod_1.z
+                        .boolean()
+                        .optional()
+                        .describe("When action=tasks, if true only return undone tasks."),
+                    includeGrades: zod_1.z
+                        .boolean()
+                        .optional()
+                        .describe("When action=grades, if false only averages are returned."),
+                }),
+                func: async (input) => {
+                    const safeStringify = (data) => JSON.stringify(data, null, 2);
+                    switch (input.action) {
+                        case "timetable": {
+                            const referenceDate = (0, GenericFunctions_1.resolveReferenceDate)(input.referenceDate);
+                            const timetable = await (0, pawnoteClient_1.fetchTimetable)(session, referenceDate);
+                            return safeStringify(timetable);
+                        }
+                        case "tasks": {
+                            const referenceDate = (0, GenericFunctions_1.resolveReferenceDate)(input.referenceDate);
+                            const assignments = await (0, pawnoteClient_1.fetchAssignments)(session, referenceDate);
+                            const filtered = input.onlyPendingTasks
+                                ? assignments.filter((a) => !a.isDone)
+                                : assignments;
+                            return safeStringify(filtered);
+                        }
+                        case "gradePeriods": {
+                            const periods = await (0, pawnoteClient_1.fetchGradePeriods)(session);
+                            return safeStringify(periods);
+                        }
+                        case "grades": {
+                            const includeGrades = input.includeGrades !== false;
+                            const overview = await (0, pawnoteClient_1.fetchGrades)(session, input.periodName);
+                            if (!includeGrades) {
+                                return safeStringify({
+                                    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,
+                                    })),
+                                });
+                            }
+                            return safeStringify(overview);
+                        }
+                        default:
+                            throw new Error(`Unsupported action: ${input["action"]}`);
+                    }
+                },
+            });
+            return {
+                response: tool,
+            };
+        }
+        catch (error) {
+            throw new n8n_workflow_1.NodeOperationError(this.getNode(), error.message);
+        }
+    }
+}
+exports.PronoteTool = PronoteTool;

package/package.json

@@ -1,10 +1,11 @@
 {
   "name": "n8n-nodes-pronote",
-  "version": "0.1.2",
+  "version": "0.2.1",
   "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",
+  "keywords": ["n8n-community-node-package", "n8n", "n8n-nodes", "pronote", "pawnote", "langchain"],
   "scripts": {
     "build": "tsc -p .",
     "clean": "rimraf dist"
@@ -13,7 +14,9 @@
     "dist"
   ],
   "dependencies": {
-    "pawnote": "^1.6.2"
+    "@langchain/core": "^0.2.29",
+    "pawnote": "^1.6.2",
+    "zod": "^3.23.8"
   },
   "peerDependencies": {
     "n8n-core": "^1.0.0",
@@ -28,7 +31,9 @@
   },
   "n8n": {
     "nodes": [
-      "dist/nodes/Pronote/Pronote.node.js"
+      "dist/nodes/Pronote/Pronote.node.js",
+      "dist/nodes/Pronote/PronoteTool.node.js",
+      "dist/nodes/Pronote/PronoteAuthHelper.node.js"
     ],
     "credentials": [
       "dist/credentials/PronoteApi.credentials.js"