feat: support taxes receipts

.eslintrc.cjs

@@ -1,7 +1,7 @@
 const { builtinModules } = require("node:module");
 
 module.exports = {
-	ignorePatterns: ["dist/", "*.cjs", "_test.ts"],
+	ignorePatterns: ["dist/", "*.cjs", "_test.ts", "tsup.config.ts"],
 	env: {
 		node: true,
 	},

package.json

@@ -11,7 +11,7 @@
 		"prepare": "npm test",
 		"prettier": "prettier --write src/**/*.ts",
 		"start": "npm run build && node --trace-warnings --enable-source-maps .",
-		"test": "eslint src && tsc --noEmit && tsup _test.ts && node dist/_test",
+		"test": "eslint src && tsc --noEmit && tsup _test.ts --format esm && node dist/_test.mjs",
 		"postinstall": "npm run build"
 	},
 	"repository": {

src/Client.ts

@@ -29,6 +29,7 @@ import {
 	getPCTOData,
 	getProfilo,
 	getRicevimenti,
+	getRicevutaTelematica,
 	getStoricoBacheca,
 	getStoricoBachecaAlunno,
 	getTasse,
@@ -222,7 +223,7 @@ export class Client {
 	 * @returns I dati
 	 */
 	async getDettagliProfilo<T extends DettagliProfilo>(old?: T) {
-		if (!this.isReady()) throw new Error("Client is not logged in!");
+		this.checkReady();
 		return getDettagliProfilo(this, {
 			old,
 		});
@@ -238,7 +239,7 @@ export class Client {
 		month?: number;
 		day?: number;
 	}) {
-		if (!this.isReady()) throw new Error("Client is not logged in!");
+		this.checkReady();
 		return getOrarioGiornaliero(this, {
 			day: date?.day,
 			month: date?.month,
@@ -252,7 +253,7 @@ export class Client {
 	 * @returns L'url
 	 */
 	async getLinkAllegato(id: string) {
-		if (!this.isReady()) throw new Error("Client is not logged in!");
+		this.checkReady();
 		return downloadAllegato(this, {
 			id,
 		});
@@ -264,7 +265,7 @@ export class Client {
 	 * @param file - Il percorso dove salvare il file
 	 */
 	async downloadAllegato(id: string, file: string) {
-		if (!this.isReady()) throw new Error("Client is not logged in!");
+		this.checkReady();
 		const { body } = await request(await this.getLinkAllegato(id));
 
 		await writeFile(file, body);
@@ -277,7 +278,7 @@ export class Client {
 	 * @returns L'url
 	 */
 	async getLinkAllegatoStudente(id: string, profileId?: string) {
-		if (!this.isReady()) throw new Error("Client is not logged in!");
+		this.checkReady();
 		return downloadAllegatoStudente(this, {
 			id,
 			profileId: profileId ?? this.profile.id,
@@ -291,20 +292,43 @@ export class Client {
 	 * @param profileId - L'id del profilo
 	 */
 	async downloadAllegatoStudente(id: string, file: string, profileId?: string) {
-		if (!this.isReady()) throw new Error("Client is not logged in!");
+		this.checkReady();
 		const { body } = await request(
 			await this.getLinkAllegatoStudente(id, profileId)
 		);
 
 		await writeFile(file, body);
 	}
 
+	/**
+	 * Ottieni i dati di una ricevuta telematica.
+	 * @param iuv - L'iuv del pagamento
+	 * @returns La ricevuta
+	 */
+	async getRicevuta(iuv: string) {
+		this.checkReady();
+		return getRicevutaTelematica(this, { iuv });
+	}
+
+	/**
+	 * Scarica la ricevuta di un pagamento.
+	 * @param iuv - L'iuv del pagamento
+	 * @param file - Il percorso dove salvare il file
+	 */
+	async downloadRicevuta(iuv: string, file: string) {
+		this.checkReady();
+		const ricevuta = await this.getRicevuta(iuv);
+		const { body } = await request(ricevuta.url);
+
+		await writeFile(file, body);
+	}
+
 	/**
 	 * Ottieni i voti dello scrutinio dello studente.
 	 * @returns I dati
 	 */
 	async getVotiScrutinio() {
-		if (!this.isReady()) throw new Error("Client is not logged in!");
+		this.checkReady();
 		return getVotiScrutinio(this);
 	}
 
@@ -313,7 +337,7 @@ export class Client {
 	 * @returns I dati
 	 */
 	async getRicevimenti<T extends Ricevimenti>(old?: T) {
-		if (!this.isReady()) throw new Error("Client is not logged in!");
+		this.checkReady();
 		return getRicevimenti(this, { old });
 	}
 
@@ -323,7 +347,7 @@ export class Client {
 	 * @returns I dati
 	 */
 	async getTasse(profileId?: string) {
-		if (!this.isReady()) throw new Error("Client is not logged in!");
+		this.checkReady();
 		return getTasse(this, {
 			profileId: profileId ?? this.profile.id,
 		});
@@ -335,7 +359,7 @@ export class Client {
 	 * @returns I dati
 	 */
 	async getPCTOData(profileId?: string) {
-		if (!this.isReady()) throw new Error("Client is not logged in!");
+		this.checkReady();
 		return getPCTOData(this, {
 			profileId: profileId ?? this.profile.id,
 		});
@@ -347,7 +371,7 @@ export class Client {
 	 * @returns I dati
 	 */
 	async getCorsiRecupero<T extends CorsiRecupero>(profileId?: string, old?: T) {
-		if (!this.isReady()) throw new Error("Client is not logged in!");
+		this.checkReady();
 		return getCorsiRecupero(this, {
 			profileId: profileId ?? this.profile.id,
 			old,
@@ -360,7 +384,7 @@ export class Client {
 	 * @returns I dati
 	 */
 	async getCurriculum(profileId?: string) {
-		if (!this.isReady()) throw new Error("Client is not logged in!");
+		this.checkReady();
 		return getCurriculum(this, {
 			profileId: profileId ?? this.profile.id,
 		});
@@ -372,7 +396,7 @@ export class Client {
 	 * @returns I dati
 	 */
 	async getStoricoBacheca(profileId: string) {
-		if (!this.isReady()) throw new Error("Client is not logged in!");
+		this.checkReady();
 		return getStoricoBacheca(this, {
 			profileId,
 		});
@@ -384,7 +408,7 @@ export class Client {
 	 * @returns I dati
 	 */
 	async getStoricoBachecaAlunno(profileId: string) {
-		if (!this.isReady()) throw new Error("Client is not logged in!");
+		this.checkReady();
 		return getStoricoBachecaAlunno(this, {
 			profileId,
 		});
@@ -395,10 +419,14 @@ export class Client {
 	 * @returns La dashboard
 	 */
 	private async getDashboard() {
-		if (!this.isReady()) throw new Error("Client is not logged in!");
+		this.checkReady();
 		return getDashboard(this, {
 			lastUpdate:
 				this.dashboard?.dataAggiornamento ?? this.profile.anno.dataInizio,
 		});
 	}
+
+	private checkReady(): asserts this is ReadyClient {
+		if (!this.isReady()) throw new Error("Client is not logged in!");
+	}
 }

src/api/getRicevutaTelematica.ts

@@ -0,0 +1,29 @@
+import type { APIRicevutaTelematica, Client } from "..";
+import { Ricevuta, apiRequest } from "..";
+
+/**
+ * Ottieni i dati di una ricevuta telematica.
+ * @param client - Il client
+ * @param options - Altre opzioni della richiesta
+ * @returns I dati
+ */
+export const getRicevutaTelematica = async (
+	client: Client,
+	options: {
+		iuv: string;
+	}
+) => {
+	const { body } = await apiRequest<APIRicevutaTelematica>(
+		"ricevutatelematica",
+		client,
+		{
+			method: "POST",
+			body: {
+				iuv: options.iuv,
+			},
+		}
+	);
+
+	if (!body.success) throw new Error(body.msg);
+	return new Ricevuta(body, client);
+};

src/api/index.ts

@@ -10,6 +10,7 @@ export * from "./getOrarioGiornaliero";
 export * from "./getPCTOData";
 export * from "./getProfilo";
 export * from "./getRicevimenti";
+export * from "./getRicevutaTelematica";
 export * from "./getStoricoBacheca";
 export * from "./getStoricoBachecaAlunno";
 export * from "./getTasse";

src/structures/Ricevuta.ts

@@ -0,0 +1,30 @@
+import type { APIRicevutaTelematica, Client, Jsonify } from "..";
+import { Base } from "..";
+
+type RicevutaData = APIRicevutaTelematica;
+type Data = Jsonify<Ricevuta> | RicevutaData;
+
+/**
+ * Rappresenta i dati di una ricevuta
+ */
+export class Ricevuta extends Base<RicevutaData> {
+	nomeFile!: string;
+	url!: string;
+
+	/**
+	 * @param data - I dati ricevuti tramite l'API
+	 */
+	constructor(data: Data, client: Client) {
+		super(client);
+		this.patch(data);
+	}
+
+	patch(data: Data) {
+		if (this.isJson(data)) this.handleJson(data);
+		else {
+			this.nomeFile = data.fileName;
+			this.url = data.url;
+		}
+		return this;
+	}
+}

src/structures/Tassa.ts

@@ -38,6 +38,10 @@ export class Tassa extends Base<TassaData> {
 		this.patch(data);
 	}
 
+	get pagato() {
+		return this.stato.toLowerCase() === "pagato";
+	}
+
 	private static resolveNumber(n: string) {
 		return Number(n.replace(",", "."));
 	}
@@ -76,4 +80,30 @@ export class Tassa extends Base<TassaData> {
 		}
 		return this;
 	}
+
+	/**
+	 * Scarica la ricevuta telematica del pagamento.
+	 * @param file - Il percorso dove salvare il file
+	 */
+	async download(file: string) {
+		if (typeof this.iuv === "undefined")
+			throw new TypeError("Cannot download receipt without an iuv");
+		if (!this.pagato)
+			throw new TypeError(
+				"Cannot download receipt for a tax that was not payed"
+			);
+		return this.client.downloadRicevuta(this.iuv, file);
+	}
+
+	/**
+	 * Ottieni la ricevuta telematica del pagamento.
+	 * @returns La ricevuta
+	 */
+	async getRicevuta() {
+		if (typeof this.iuv === "undefined")
+			throw new TypeError("Cannot get receipt without an iuv");
+		if (!this.pagato)
+			throw new TypeError("Cannot get receipt for a tax that was not payed");
+		return this.client.getRicevuta(this.iuv);
+	}
 }

src/structures/index.ts

@@ -1,6 +1,7 @@
 export * from "./Allegato";
 export * from "./Alunno";
 export * from "./Base";
+export * from "./BaseProfilo";
 export * from "./CorsiRecupero";
 export * from "./Curriculum";
 export * from "./Dashboard";
@@ -25,8 +26,8 @@ export * from "./Prenotazione";
 export * from "./Profilo";
 export * from "./Promemoria";
 export * from "./Ricevimenti";
+export * from "./Ricevuta";
 export * from "./Scrutinio";
-export * from "./BaseProfilo";
 export * from "./Tassa";
 export * from "./Token";
 export * from "./Voto";

src/types/apiTypes.ts

@@ -578,6 +578,12 @@ export type APICurriculum = APIResponse<{
 		ordineScuola: string;
 	}[];
 }>;
+export type APIRicevutaTelematica = {
+	success: boolean;
+	fileName: string;
+	msg?: string;
+	url: string;
+};
 export type APIBacheca = APIResponse<
 	Pick<APIDashboard["data"]["dati"][number], "bacheca">
 >;

tsup.config.ts

@@ -4,7 +4,7 @@ const options: Options = {
 	clean: true,
 	entry: ["src/index.ts"],
 	// format: ["esm"],
-	external: ["tsup"],
+	external: ["dotenv"],
 	platform: "node",
 	target: "esnext",
 	minify: true,