Package Exports

This package does not declare an exports field, so the exports above have been automatically detected and optimized by JSPM instead. If any package subpath is missing, it is recommended to post an issue to the original package (classeviva-api-wrapper) to support the "exports" field. If that is not possible, create a JSPM override to customize the exports field for this package.

Readme

Classeviva.js

Wrapper JavaScript/Node.js per l'API di Classeviva - Registro elettronico di Spaggiari

📖 Descrizione

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.

✨ Caratteristiche

🔄 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

🚀 Installazione

npm install classeviva-js

📋 Requisiti

Node.js ≥ 16.0.0
npm o yarn

🔧 Utilizzo Base

Import

// Named imports (raccomandato)
import { Utente, ListaUtenti } from 'classeviva-js';

// Default import
import Classeviva from 'classeviva-js';
const utente = new Classeviva.Utente('S1234567', 'password');

// Import specifici
import { PasswordNonValida, validaDate } from 'classeviva-js';

Singolo Utente

import { Utente } from 'classeviva-js';

async function main() {
    // Crea utente
    const utente = new Utente('S1234567', '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();

Lista Utenti (Operazioni Batch)

import { Utente, ListaUtenti } from 'classeviva-js';

async function gestisciClasse() {
    // Crea lista studenti
    const studenti = new ListaUtenti([
        new Utente('S1111111', 'password1'),
        new Utente('S2222222', 'password2'),
        new Utente('S3333333', '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();

📚 API Documentazione

Classe `Utente`

Metodi Principali

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à

Proprietà	Descrizione	Tipo
`connesso`	Stato connessione	`boolean`
`dati`	Dati utente essenziali	`Object`
`token`	Token di autenticazione	`string`

Classe `ListaUtenti`

Metodi Principali

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>`

🎯 Esempi Avanzati

Gestione Date

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');

Gestione Errori

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);
    }
}

Download File

// 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);

🔒 Sicurezza

⚠️ IMPORTANTE: Non salvare mai le credenziali nel codice! Usa variabili d'ambiente:

// .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
);

🛠️ Sviluppo

# 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 dev

📁 Struttura Progetto

src/
├── 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

🤝 Contributi

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

📄 Licenza

Questo progetto è sotto licenza MIT. Vedi il file LICENSE per dettagli.

🙏 Crediti

Libreria Python originale: Classeviva-Wrapper-API
API Endpoints: Documentazione ufficiale
Conversione JavaScript: Filippo Berti

❓ Supporto

Per problemi o domande:

Apri una Issue
Consulta la Documentazione API

⭐ Se questa libreria ti è utile, lascia una stella su GitHub! ⭐

classeviva-api-wrapper

Package Exports

Readme

Classeviva.js

📖 Descrizione

✨ Caratteristiche

🚀 Installazione

📋 Requisiti

🔧 Utilizzo Base

Import

Singolo Utente

Lista Utenti (Operazioni Batch)

📚 API Documentazione

Classe Utente

Metodi Principali

Proprietà

Classe ListaUtenti

Metodi Principali

🎯 Esempi Avanzati

Gestione Date

Gestione Errori

Download File

🔒 Sicurezza

🛠️ Sviluppo

📁 Struttura Progetto

🤝 Contributi

📄 Licenza

🙏 Crediti

❓ Supporto

Classe `Utente`

Classe `ListaUtenti`