Merge branch 'master' of https://github.com/loumadev/EdupageAPI

lib/CookieJar.js

@@ -19,7 +19,7 @@ class CookieJar {
 
 	/**
 	 * Adds cookie to the Jar
-	 * @param {string|CookieJar.Cookie|http.ServerResponse|http.IncomingMessage|fetch.Response} cookie Cookie name (requires second parameter), Cookie String, CookieJar.Cookie object, ServerResponseLike object
+	 * @param {string | CookieJar.Cookie | http.ServerResponse | http.IncomingMessage | fetch.Response} cookie Cookie name (requires second parameter), Cookie String, CookieJar.Cookie object, ServerResponseLike object
 	 * @param {string} [value=undefined]
 	 * @param {Object<string, any>} [options={}]
 	 * @return {CookieJar} 
@@ -98,7 +98,7 @@ class CookieJar {
 
 	/**
 	 * Removes cookie from the Jar
-	 * @param {string|CookieJar.Cookie} cookie
+	 * @param {string | CookieJar.Cookie} cookie
 	 * @return {CookieJar.Cookie} Deleted cookie
 	 * @memberof CookieJar
 	 */
@@ -206,7 +206,7 @@ class Cookie {
 		this.props = {};
 
 		/**
-		 * @type {Array<"Secure"|"HttpOnly">}
+		 * @type {Array<"Secure" | "HttpOnly">}
 		 */
 		this.flags = [];
 	}

lib/ResponseTypings.js

@@ -0,0 +1,80 @@
+/**
+ * @typedef {Object} MAppData
+ * @prop {string} loggedUser
+ * @prop {number} loggedChild
+ * @prop {string} loggedUserName
+ * @prop {string} lang
+ * @prop {string} edupage
+ * @prop {string} school_type
+ * @prop {number} timezonediff
+ * @prop {string} school_country
+ * @prop {string} schoolyear_turnover
+ * @prop {number} firstDayOfWeek
+ * @prop {string} sort_name_col
+ * @prop {number} selectedYear
+ * @prop {number} autoYear
+ * @prop {string} year_turnover
+ * @prop {boolean[]} vyucovacieDni
+ * @prop {string} server
+ * @prop {number} syncIntervalMultiplier
+ * @prop {any} ascspl
+ * @prop {boolean} jePro
+ * @prop {boolean} jeZUS
+ * @prop {boolean} rtl
+ * @prop {boolean} rtlAvailable
+ * @prop {string} uidsgn
+ * @prop {boolean} webpageadmin
+ * @prop {EduRequestProps} edurequestProps
+ * @prop {string} gsechash
+ * @prop {string} email
+ * @prop {any[]} userrights
+ * @prop {boolean} isAdult
+ */
+
+/**
+ * @typedef {Object} EduRequestProps
+ * @prop {string} edupage
+ * @prop {string} lang
+ * @prop {string} school_name
+ * @prop {string} school_country
+ * @prop {string} school_state
+ * @prop {string} schoolyear_turnover
+ * @prop {any[]} custom_turnover
+ * @prop {number} firstDayOfWeek
+ * @prop {number[]} weekendDays
+ * @prop {string} timezone
+ * @prop {string} sort_name_col
+ * @prop {{date: string, time: string}} dtFormats
+ * @prop {string} jsmodulemode
+ * @prop {string} loggedUser
+ * @prop {any[]} loggedUserRights
+ * @prop {boolean} isAsc
+ * @prop {boolean} isAgenda
+ */
+
+/**
+ * @typedef {Object} MAuthUser
+ * @prop {string} userid
+ * @prop {string} typ
+ * @prop {string} edupage
+ * @prop {string} edumeno
+ * @prop {string} eduheslo
+ * @prop {string} firstname
+ * @prop {string} lastname
+ * @prop {string} esid
+ * @prop {MAppData} appdata
+ * @prop {string} portal_userid
+ * @prop {string} portal_email
+ * @prop {"1" | null} need2fa
+ */
+
+/**
+ * @typedef {Object} MAuthResponse
+ * @prop {MAuthUser[]} users
+ * @prop {boolean} needEdupage
+ * @prop {string} edid
+ * @prop {any | undefined} [t2fasec=undefined]
+ */
+
+//Required to enable type checking
+module.exports = undefined;

src/ASC.js

@@ -21,7 +21,7 @@ class ASC extends RawData {
 		super(data);
 
 		/**
-		 * @type {Edupage|string}
+		 * @type {Edupage | string}
 		 */
 		this.edupage = edupage;
 

src/Assignment.js

@@ -51,7 +51,7 @@ class Assignment extends RawData {
 		this.superId = data.e_superid;
 
 		/**
-		 * @type {User|Teacher}
+		 * @type {User | Teacher}
 		 */
 		this.owner = null;
 
@@ -153,7 +153,7 @@ class Assignment extends RawData {
 		this.stateUpdatedDate = data.studentStav?.timestamp ? new Date(data.studentStav?.timestamp) : null;
 
 		/**
-		 * @type {User|Teacher}
+		 * @type {User | Teacher}
 		 */
 		this.stateUpdatedBy = null;
 
@@ -219,7 +219,7 @@ class Assignment extends RawData {
 	 * @static
 	 * @param {RawDataObject} [data={}]
 	 * @param {Edupage} [edupage=null]
-	 * @return {Assignment|Homework|Test}
+	 * @return {Assignment | Homework | Test}
 	 * @memberof Assignment
 	 */
 	static from(data = {}, edupage = null) {

src/Attachment.js

@@ -17,17 +17,19 @@ class Attachment extends RawData {
 		super(data);
 
 		/**
-		 * Edupage instance
+		 * Edupage instance associated to this object
 		 * @type {Edupage} 
 		 */
 		this.edupage = edupage;
 
 		/**
+		 * Name of the attachment file
 		 * @type {string}
 		 */
 		this.name = data.name;
 
 		/**
+		 * Absolute URL path to the attachment file uploaded on Edupage cloud server
 		 * @type {string}
 		 */
 		this.src = null;
@@ -46,6 +48,11 @@ class Attachment extends RawData {
 		this.src = `https://${this.edupage.user.origin}.edupage.org` + (this._data.file || this._data.src);
 	}
 
+	/**
+	 * Converts the `Attachment` object to JSON object
+	 * @return {Object<string, string>} JSON object contianing the attachment name as key and the attachment URL as value
+	 * @memberof Attachment
+	 */
 	toJSON() {
 		return {[this._data.file]: this.name};
 	}

src/Class.js

@@ -18,43 +18,50 @@ class Class extends RawData {
 		super(data);
 
 		/**
-		 * Edupage instance
+		 * Edupage instance associated to this object
 		 * @type {Edupage} 
 		 */
 		this.edupage = edupage;
 
 
 		/**
+		 * Grade of the class
 		 * @type {number}
 		 */
 		this.grade = +data.grade ?? null;
 
 		/**
+		 * ID of the class
 		 * @type {string}
 		 */
 		this.id = data.id;
 
 		/**
+		 * Name of the class
 		 * @type {string}
 		 */
 		this.name = data.name;
 
 		/**
+		 * Short name of the class
 		 * @type {string}
 		 */
 		this.short = data.short;
 
 		/**
+		 * Classroom associated to this class
 		 * @type {Classroom}
 		 */
 		this.classroom = null;
 
 		/**
+		 * Teacher associated to this class
 		 * @type {Teacher}
 		 */
 		this.teacher = null;
 
 		/**
+		 * Teacher 2 associated to this class
 		 * @type {Teacher}
 		 */
 		this.teacher2 = null;

src/Classroom.js

@@ -16,7 +16,7 @@ class Classroom extends RawData {
 		super(data);
 
 		/**
-		 * Edupage instance
+		 * Edupage instance associated to this object
 		 * @type {Edupage} 
 		 */
 		this.edupage = edupage;

src/Edupage.js

@@ -49,7 +49,7 @@ class Edupage extends RawData {
 		super();
 
 		/**
-		 * @type {User|Teacher|Student}
+		 * @type {User | Teacher | Student}
 		 */
 		this.user = null;
 
@@ -157,18 +157,23 @@ class Edupage extends RawData {
 		});
 	}
 
+	/**
+	 * @typedef {import("./User").LoginOptions} LoginOptions
+	 */
+
 	/**
 	 * Logs user in for this instance
 	 *
-	 * @param {string} [username=this.user.credentials.username]
-	 * @param {string} [password=this.user.credentials.password]
-	 * @return {Promise<User|Teacher|Student>} 
+	 * @param {string} [username=this.user.credentials.username] Username of the user
+	 * @param {string} [password=this.user.credentials.password] Password of the user
+	 * @param {LoginOptions} [options] Login options
+	 * @return {Promise<User | Teacher | Student>} Returns a promise that resolves with the `User` object if successful. If the 2FA is requested by the Edupage, the promise will resolve with `null`. 
 	 * @memberof Edupage
 	 */
-	async login(username = this.user.credentials.username, password = this.user.credentials.password) {
+	async login(username = this.user.credentials.username, password = this.user.credentials.password, options) {
 		return new Promise((resolve, reject) => {
 			const temp = new User();
-			temp.login(username, password).then(async user => {
+			temp.login(username, password, options).then(async user => {
 				//Assign properties
 				this.user = temp;
 				this.baseUrl = `https://${this.user.origin}.edupage.org`;
@@ -385,7 +390,7 @@ class Edupage extends RawData {
 	/**
 	 *
 	 * @param {string} id
-	 * @return {User|Teacher|Student|Parent|undefined} 
+	 * @return {User | Teacher | Student | Parent | undefined} 
 	 * @memberof Edupage
 	 */
 	getUserById(id) {
@@ -405,7 +410,7 @@ class Edupage extends RawData {
 	/**
 	 *
 	 * @param {string} userString
-	 * @return {User|Teacher|Student|Parent|undefined} 
+	 * @return {User | Teacher | Student | Parent | undefined} 
 	 * @memberof Edupage
 	 */
 	getUserByUserString(userString) {
@@ -425,7 +430,7 @@ class Edupage extends RawData {
 	/**
 	 *
 	 * @param {Date} date
-	 * @return {Promise<Timetable|undefined>} 
+	 * @return {Promise<Timetable | undefined>} 
 	 * @memberof Edupage
 	 */
 	async getTimetableForDate(date) {
@@ -536,12 +541,12 @@ class Edupage extends RawData {
 
 	/**
 	 * @typedef {Object} APIOptions
-	 * @prop {string|ENDPOINT} url
-	 * @prop {Object<string, any>|stream.Readable|Buffer|string} [data={}]
+	 * @prop {string | ENDPOINT} url
+	 * @prop {Object<string, any> | stream.Readable | Buffer | string} [data={}]
 	 * @prop {Object<string, any>} [headers={}]
 	 * @prop {string} [method="POST"]
 	 * @prop {boolean} [encodeBody=true]
-	 * @prop {"json"|"text"} [type="json"]
+	 * @prop {"json" | "text"} [type="json"]
 	 * @prop {boolean} [autoLogin=true]
 	 */
 
@@ -755,8 +760,8 @@ class Edupage extends RawData {
 
 	/**
 	 *
-	 * @param {Date|number|string} date1
-	 * @param {Date|number|string} date2
+	 * @param {Date | number | string} date1
+	 * @param {Date | number | string} date2
 	 * @return {boolean} true if day of the dates is same, otherwise false
 	 * @memberof Edupage
 	 */

src/Lesson.js

@@ -27,7 +27,7 @@ class Lesson extends RawData {
 		super(data);
 
 		/**
-		 * Edupage instance
+		 * Edupage instance associated to this object
 		 * @type {Edupage} 
 		 */
 		this.edupage = edupage;

src/Message.js

@@ -148,30 +148,30 @@ class Message extends RawData {
 
 		/**
 		 * ! WARNING: This property is only accessible after calling `message.refresh()`!
-		 * @type {(User|Teacher|Student|Parent)[]}
+		 * @type {(User | Teacher | Student | Parent)[]}
 		 */
 		this.participants = [];
 
 		/**
 		 * ! WARNING: This property is only accessible after calling `message.refresh()`!
-		 * @type {({user: User|Teacher|Student|Parent, date: Date})[]}
+		 * @type {({user: User | Teacher | Student | Parent, date: Date})[]}
 		 */
 		this.likedBy = [];
 
 		/**
 		 * ! WARNING: This property is only accessible after calling `message.refresh()`!
-		 * @type {({user: User|Teacher|Student|Parent, date: Date})[]}
+		 * @type {({user: User | Teacher | Student | Parent, date: Date})[]}
 		 */
 		this.seenBy = [];
 
 
 		/**
-		 * @type {User|Teacher|Student|Parent}
+		 * @type {User | Teacher | Student | Parent}
 		 */
 		this.owner = null;
 
 		/**
-		 * @type {User|Teacher|Student|Parent|Plan|Class}
+		 * @type {User | Teacher | Student | Parent | Plan | Class}
 		 */
 		this.recipient = null;
 
@@ -322,7 +322,7 @@ class Message extends RawData {
 	/**
 	 * @typedef {Object} MessageReplyOptions
 	 * @prop {string} text
-	 * @prop {User|Teacher|Student|Parent} [recipient=null]
+	 * @prop {User | Teacher | Student | Parent} [recipient=null]
 	 * @prop {boolean} [parents=false]
 	 * @prop {Attachment[]} [attachments=[]]
 	 */

src/Parent.js

@@ -17,7 +17,7 @@ class Parent extends User {
 		super(data, edupage);
 
 		/**
-		 * Edupage instance
+		 * Edupage instance associated to this object
 		 * @type {Edupage} 
 		 */
 		this.edupage = edupage;