feat(session): implement userResource to start #61

can be mutated using the `pronote.use(session, value)` helper method

examples/account.ts

@@ -12,9 +12,9 @@ void async function main () {
   });
 
   // Basic account data that we can access without doing any requests.
-  console.log("Logged into", session.user.name, "studying at", session.user.resources[0].establishmentName, "in", session.user.resources[0].className);
-  if (session.user.resources[0].profilePicture) {
-    console.log("-> Profile Picture URL:", session.user.resources[0].profilePicture.url);
+  console.log("Logged into", session.user.name, "studying at", session.userResource.establishmentName, "in", session.userResource.className);
+  if (session.userResource.profilePicture) {
+    console.log("-> Profile Picture URL:", session.userResource.profilePicture.url);
   }
 
   console.log(); // Break line.

examples/discussions/create.ts

@@ -14,8 +14,7 @@ void async function main () {
   if (!session.user.authorizations.canDiscuss)
     throw new Error("This account can't discuss, review the permissions.");
 
-  const user = session.user.resources[0];
-  const teachers = await pronote.newDiscussionRecipients(session, user, pronote.EntityKind.Teacher);
+  const teachers = await pronote.newDiscussionRecipients(session, pronote.EntityKind.Teacher);
   console.info("Sending a message to every teachers:", teachers.map((teacher) => teacher.name).join(", "));
 
   await pronote.newDiscussion(

examples/discussions/creation-recipients.ts

@@ -37,14 +37,11 @@ void async function main () {
     kinds.push(pronote.EntityKind.Student);
   }
 
-  const user = session.user.resources[0]; // we'll use the first user (for students this is the student itself)
-  const recipients = await pronote.newDiscussionRecipients(session, user, pronote.EntityKind.Teacher);
-  // const recipients = await Promise.all(kinds.map((type) => pronote.newDiscussionRecipients(session, user, type)));
-
+  const recipients = await Promise.all(kinds.map((kind) => pronote.newDiscussionRecipients(session, kind)));
   const people = recipients.flat();
 
   for (const person of people) {
-    console.info();
+    console.info(); // New line.
     let typeName = "unknown";
 
     if (person.kind === pronote.EntityKind.Personal) typeName = "staff";

examples/evaluations.ts

@@ -11,10 +11,7 @@ void async function main () {
     deviceUUID: credentials.deviceUUID
   });
 
-  // Read the user resources to find the tab's periods.
-  const user = session.user.resources[0];
-
-  const tab = user.tabs.get(pronote.TabLocation.Evaluations);
+  const tab = session.userResource.tabs.get(pronote.TabLocation.Evaluations);
   if (!tab) throw new Error("Cannot retrieve periods for the evaluations tab, you maybe don't have access to it.");
   const selectedPeriod = tab.periods.find((period) => period.name === "Trimestre 1")!;
 

examples/gradebook-url.ts

@@ -11,10 +11,7 @@ void async function main () {
     deviceUUID: credentials.deviceUUID
   });
 
-  // Read the user resources to find the tab's periods.
-  const user = session.user.resources[0];
-
-  const tab = user.tabs.get(pronote.TabLocation.Gradebook);
+  const tab = session.userResource.tabs.get(pronote.TabLocation.Gradebook);
   if (!tab) throw new Error("Cannot retrieve periods for the gradebook tab, you maybe don't have access to it.");
   const selectedPeriod = tab.periods.find((period) => period.name === "Trimestre 1")!;
 

examples/grades-overview.ts

@@ -37,10 +37,7 @@ void async function main () {
     deviceUUID: credentials.deviceUUID
   });
 
-  // Read the user resources to find the tab's periods.
-  const user = session.user.resources[0];
-
-  const tab = user.tabs.get(pronote.TabLocation.Grades);
+  const tab = session.userResource.tabs.get(pronote.TabLocation.Grades);
   if (!tab) throw new Error("Cannot retrieve periods for the grades tab, you maybe don't have access to it.");
   const selectedPeriod = tab.defaultPeriod!;
 

examples/notebook.ts

@@ -11,10 +11,7 @@ void async function main () {
     deviceUUID: credentials.deviceUUID
   });
 
-  // Read the user resources to find the tab's periods.
-  const user = session.user.resources[0];
-
-  const tab = user.tabs.get(pronote.TabLocation.Notebook);
+  const tab = session.userResource.tabs.get(pronote.TabLocation.Notebook);
   if (!tab) throw new Error("Cannot retrieve periods for the notebook tab, you maybe don't have access to it.");
   const selectedPeriod = tab.defaultPeriod!;
 

examples/periods.ts

@@ -23,7 +23,7 @@ void async function main () {
 
   for (const tabID of session.user.authorizations.tabs) {
     // We're on a student account, there's only one resource.
-    const tab = session.user.resources[0].tabs.get(tabID);
+    const tab = session.userResource.tabs.get(tabID);
     if (!tab) {
       console.warn(`Skipping tab ${tabID} since no period is required there.`);
       continue;

src/api/helpers/login.ts

@@ -8,6 +8,7 @@ import { AES } from "../private/aes";
 import { authenticate } from "../private/authenticate";
 import { userParameters } from "../private/user-parameters";
 import { decodeAuthenticationQr } from "~/decoders/authentication-qr";
+import { use } from "./use";
 
 /**
  * base parameters for `sessionInformation` call.
@@ -249,6 +250,7 @@ const hasSecurityModal = (authentication: any): boolean => Boolean(authenticatio
 
 export const finishLoginManually = async (session: SessionHandle, authentication: any, identity: any, initialUsername?: string): Promise<RefreshInformation> => {
   session.user = await userParameters(session);
+  use(session, 0); // default to first resource.
 
   return {
     token: authentication.jetonConnexionAppliMobile,

src/api/helpers/use.ts

@@ -0,0 +1,9 @@
+import type { SessionHandle, UserResource } from "~/models";
+
+function use (session: SessionHandle, index: number): void;
+function use (session: SessionHandle, resource: UserResource): void;
+function use (session: SessionHandle, value: any): void {
+  session.userResource = typeof value === "number" ? session.user.resources[value] : value;
+}
+
+export { use };

src/api/index.ts

@@ -6,6 +6,7 @@ export * from "./helpers/news-question-local-mutate";
 export * from "./helpers/parse-timetable";
 export * from "./helpers/presence-interval";
 export * from "./helpers/session-handle";
+export * from "./helpers/use";
 export * from "./helpers/week-number";
 
 export * from "./account";

src/api/new-discussion-recipients.ts

@@ -1,7 +1,6 @@
 import { RequestFN } from "~/core/request-function";
 import { decodeNewDiscussionRecipient } from "~/decoders/new-discussion-recipient";
-import { SessionHandle, TabLocation, UserResource, EntityKind } from "~/models";
-import { NewDiscussionRecipient } from "~/models/new-discussion-recipient";
+import { type SessionHandle, TabLocation, type EntityKind, type NewDiscussionRecipient } from "~/models";
 
 /**
  * Returns a list of possible recipients when creating a discussion.
@@ -11,7 +10,9 @@ import { NewDiscussionRecipient } from "~/models/new-discussion-recipient";
  *
  * @param kind The kind of entity to create a discussion with. Only `Teacher`, `Student` and `Personal` are allowed.
  */
-export const newDiscussionRecipients = async (session: SessionHandle, user: UserResource, kind: EntityKind): Promise<Array<NewDiscussionRecipient>> => {
+export const newDiscussionRecipients = async (session: SessionHandle, kind: EntityKind): Promise<Array<NewDiscussionRecipient>> => {
+  const user = session.userResource;
+
   // TODO: use `ListePublics` for teachers.
   const request = new RequestFN(session, "ListeRessourcesPourCommunication", {
     _Signature_: { onglet: TabLocation.Discussions },

src/api/timetable.ts

@@ -5,7 +5,7 @@ import { encodeUserResource } from "~/encoders/user-resource";
 import { decodeTimetable } from "~/decoders/timetable";
 import { encodePronoteDate } from "~/encoders/pronote-date";
 
-const timetable = async (session: SessionHandle, index: number, additional = {}): Promise<Timetable> => {
+const timetable = async (session: SessionHandle, additional = {}): Promise<Timetable> => {
   const request = new RequestFN(session, "PageEmploiDuTemps", {
     _Signature_: { onglet: TabLocation.Timetable },
 
@@ -25,7 +25,7 @@ const timetable = async (session: SessionHandle, index: number, additional = {})
 
       edt: { G: 16, L: "Emploi du temps" },
 
-      ...propertyCaseInsensitive("ressource", encodeUserResource(session.user.resources[index])),
+      ...propertyCaseInsensitive("ressource", encodeUserResource(session.userResource)),
       ...additional
     }
   });
@@ -34,12 +34,12 @@ const timetable = async (session: SessionHandle, index: number, additional = {})
   return decodeTimetable(response.data.donnees, session);
 };
 
-export const timetableFromWeek = async (session: SessionHandle, weekNumber: number, index = 0): Promise<Timetable> => {
-  return timetable(session, index, propertyCaseInsensitive("numeroSemaine", weekNumber));
+export const timetableFromWeek = async (session: SessionHandle, weekNumber: number): Promise<Timetable> => {
+  return timetable(session, propertyCaseInsensitive("numeroSemaine", weekNumber));
 };
 
-export const timetableFromIntervals = async (session: SessionHandle, startDate: Date, endDate?: Date, index = 0): Promise<Timetable> => {
-  return timetable(session, index, {
+export const timetableFromIntervals = async (session: SessionHandle, startDate: Date, endDate?: Date): Promise<Timetable> => {
+  return timetable(session, {
     ...propertyCaseInsensitive("dateDebut", {
       _T: 7,
       V: encodePronoteDate(startDate)

src/models/session-handle.ts

@@ -3,8 +3,9 @@ import type { Queue } from "~/api/private/queue";
 import type { SessionInformation } from "./session-information";
 import type { UserParameters } from "./user-parameters";
 import type { InstanceParameters } from "./instance-parameters";
+import { UserResource } from "./user-resource";
 
-export interface SessionHandle {
+export type SessionHandle = {
   /**
    * Equivalent of a PRONOTE session.
    * Contains metadata, AES keys, RSA modulus, and more.
@@ -13,8 +14,14 @@ export interface SessionHandle {
   instance: InstanceParameters
   user: UserParameters
 
+  /**
+   * Can be updated with the `pronote.use(number | UserResource)` method.
+   * @default user.resources[0] // first resource from the user
+   */
+  userResource: UserResource
+
   readonly queue: Queue
   readonly fetcher: Fetcher
 
   presence: null | ReturnType<typeof setInterval>
-}
+};