Wrapper JavaScript/Node.js per l'API di Classeviva - Registro elettronico di Spaggiari
Libreria JavaScript per interagire con il sistema Classeviva di Spaggiari, il registro elettronico utilizzato nelle scuole italiane. Conversione della libreria Python originale con supporto completo per Node.js e JavaScript moderno.
- 🔄 API completamente async/await
- 🏫 Copertura completa API Classeviva (voti, assenze, agenda, documenti, etc.)
- 👥 Gestione batch utenti con
ListaUtenti - 🛡️ Gestione errori robusta con eccezioni tipizzate
- 📅 Validazione automatica date
- 🔐 Gestione sessioni e token automatica
- 📦 Import ES6 moderni
- 🇮🇹 Documentazione e messaggi in italiano
npm install classeviva-js- Node.js ≥ 16.0.0
- npm o yarn
// Named imports (raccomandato)
import { Utente, ListaUtenti } from 'classeviva-js';
// Default import
import Classeviva from 'classeviva-js';
const utente = new Classeviva.Utente('utente', 'password');
// Import specifici
import { PasswordNonValida, validaDate } from 'classeviva-js';import { Utente } from 'classeviva-js';
async function main() {
// Crea utente
const utente = new Utente('utente', 'tua_password');
try {
// Effettua l'accesso
await utente.accedi();
console.log('✅ Accesso effettuato!');
// Ottieni informazioni utente
console.log('Dati utente:', utente.dati);
// Ottieni i voti
const voti = await utente.voti();
console.log('Voti:', voti);
// Ottieni le assenze
const assenze = await utente.assenze();
console.log('Assenze:', assenze);
// Ottieni l'agenda
const agenda = await utente.agenda();
console.log('Agenda:', agenda);
} catch (error) {
console.error('Errore:', error.message);
}
}
main();import { Utente, ListaUtenti } from 'classeviva-js';
async function gestisciClasse() {
// Crea lista studenti
const studenti = new ListaUtenti([
new Utente('utente1', 'password1'),
new Utente('utente2', 'password2'),
new Utente('utente3', 'password3')
]);
try {
// Effettua l'accesso per tutti
await studenti.accedi();
console.log('✅ Tutti gli studenti connessi!');
// Ottieni i voti di tutti
const votiTutti = await studenti.votiTutti();
console.log('Voti classe:', votiTutti);
// Ottieni statistiche
console.log('Statistiche:', studenti.statistiche);
} catch (error) {
console.error('Errore batch:', error.message);
}
}
gestisciClasse();| Metodo | Descrizione | Ritorno |
|---|---|---|
accedi() |
Effettua l'accesso | Promise<void> |
voti() |
Ottiene i voti | Promise<Array> |
assenze() |
Ottiene le assenze | Promise<Array> |
materie() |
Ottiene le materie | Promise<Array> |
agenda() |
Ottiene l'agenda | Promise<Array> |
note() |
Ottiene le note | Promise<Object> |
pagelle() |
Ottiene le pagelle | Promise<Array> |
bacheca() |
Ottiene la bacheca | Promise<Array> |
carta() |
Ottiene carta studente | Promise<Object> |
libri() |
Ottiene libri di testo | Promise<Object> |
| Proprietà | Descrizione | Tipo |
|---|---|---|
connesso |
Stato connessione | boolean |
dati |
Dati utente essenziali | Object |
token |
Token di autenticazione | string |
| Metodo | Descrizione | Ritorno |
|---|---|---|
accedi() |
Accesso per tutti gli utenti | Promise<void> |
votiTutti() |
Voti di tutti gli utenti | Promise<Array> |
assenzeTutti() |
Assenze di tutti gli utenti | Promise<Array> |
aggiungi(utente) |
Aggiunge utente (no duplicati) | boolean |
applicaTutti(metodo, ...args) |
Applica metodo a tutti | Promise<Array> |
import { validaDate, formattaDataPerAPI } from 'classeviva-js';
// Ottieni assenze in un periodo
const assenzePeriodo = await utente.assenzeDaA('2024-01-01', '2024-03-31');
// Ottieni agenda specifica
const agendaMarzo = await utente.agendaDaA('2024-03-01', '2024-03-31');import { PasswordNonValida, TokenScaduto, DataFuoriGamma } from 'classeviva-js';
try {
await utente.accedi();
} catch (error) {
if (error instanceof PasswordNonValida) {
console.error('Credenziali non valide');
} else if (error instanceof TokenScaduto) {
console.error('Sessione scaduta, riaccedi');
} else if (error instanceof DataFuoriGamma) {
console.error('Data fuori range anno scolastico');
} else {
console.error('Errore generico:', error.message);
}
}// Ottieni avatar
const avatarBuffer = await utente.avatar();
// Salva su file
import fs from 'fs';
fs.writeFileSync('avatar.jpg', avatarBuffer);
// Ottieni documenti
const documenti = await utente.documenti();
console.log('Pagelle disponibili:', documenti.schoolReports);// .env file
CLASSEVIVA_USER=S1234567
CLASSEVIVA_PASSWORD=tua_password_sicura
// Nel codice
import 'dotenv/config';
const utente = new Utente(
process.env.CLASSEVIVA_USER,
process.env.CLASSEVIVA_PASSWORD
);# Clona repository
git clone https://github.com/tu-username/classeviva-js.git
# Installa dipendenze
npm install
# Esegui esempi
npm run test
# Sviluppo con watch
npm run devsrc/
├── lib/
│ ├── Utente.js # Classe principale utente
│ ├── ListaUtenti.js # Gestione batch utenti
│ ├── collegamenti.js # URL endpoints API
│ ├── eccezioni.js # Eccezioni personalizzate
│ └── variabili.js # Costanti e utility
├── index.js # Entry point principale
examples/
├── esempio-base.js # Esempi di utilizzo
test/
└── test.js # Test base
I contributi sono benvenuti! Per favore:
- Fai un fork del progetto
- Crea un branch per la tua feature (
git checkout -b feature/AmazingFeature) - Commit le modifiche (
git commit -m 'Add some AmazingFeature') - Push al branch (
git push origin feature/AmazingFeature) - Apri una Pull Request
Questo progetto è sotto licenza MIT. Vedi il file LICENSE per dettagli.
- Libreria Python originale: Classeviva-Wrapper-API
- API Endpoints: Documentazione ufficiale
- Conversione JavaScript: Filippo Berti
Per problemi o domande:
- Apri una Issue
- Consulta la Documentazione API
⭐ Se questa libreria ti è utile, lascia una stella su GitHub! ⭐