Calendario
Libre WebUI include un calendario personale. Ogni utente autenticato dispone di viste mensili e settimanali con eventi singoli e ricorrenti; anche le prossime occorrenze e la cronologia delle automazioni pianificate vengono proiettate sulla stessa griglia.
Eventi
Un evento ha un titolo, note facoltative, un'ora di inizio, un'ora di fine facoltativa, un indicatore per l'intera giornata e una regola di ricorrenza facoltativa. Titoli e note vengono cifrati a riposo con lo stesso envelope usato per chat e note.
La ricorrenza usa il modello di trigger condiviso:
| Tipo | Campi | Significato |
|---|---|---|
once | at | Una singola occorrenza |
hourly | minute, startHour?, endHour? | Ogni ora all'interno di una finestra |
daily | hour, minute | Ogni giorno a un'ora locale |
weekly | dayOfWeek, hour, minute | Ogni settimana nel giorno scelto |
monthly | dayOfMonth, hour, minute | Ogni mese nel giorno scelto |
yearly | month, dayOfMonth, hour, minute | Ogni anno nella data scelta |
Gli eventi ricorrenti vengono memorizzati una sola volta. Le query per intervallo li espandono sul server: ogni occorrenza proiettata contiene un baseEventId che punta all'evento di origine, quindi modificando l'origine si aggiornano tutte le occorrenze future. Un dayOfMonth successivo alla fine del mese viene limitato all'ultimo giorno di quel mese. Tutti i calcoli di ricorrenza usano il fuso orario locale del server.
Calendari con nome e condivisione
Oltre all'ambito personale predefinito, un utente può creare fino a 20 calendari con nome, ciascuno con un colore di visualizzazione facoltativo. Gli eventi hanno un calendarId facoltativo; quelli che ne sono privi restano nell'ambito predefinito, che rimane privato.
I calendari con nome vengono condivisi tramite il modello di autorizzazioni comune: un'autorizzazione read consente al destinatario di vedere il calendario e i relativi eventi insieme ai propri; un'autorizzazione write permette inoltre di creare e modificare eventi. Gli eventi creati da un collaboratore sono memorizzati nell'account del proprietario del calendario, quindi quote, eliminazione e archivio portabile restano nell'ambito del proprietario. L'accesso viene nuovamente autorizzato a ogni richiesta; la revoca nasconde il calendario alla lettura successiva. Eliminando un calendario, i suoi eventi tornano all'ambito predefinito del proprietario e le autorizzazioni vengono rimosse.
Promemoria
Un evento può avere un anticipo per il promemoria (reminderMinutes, fino a 14 giorni). Il tick con lease del pianificatore delle automazioni cerca i promemoria scaduti e pubblica una notifica calendar-reminder nella casella del proprietario dell'evento; un compare-and-set per occorrenza garantisce che la stessa occorrenza non venga mai notificata di nuovo, anche per gli eventi ricorrenti.
Importazione ed esportazione ICS
GET /api/calendar/export?calendarId= scarica un calendario, o l'ambito predefinito, come file .ics RFC 5545: timestamp UTC, testo con escape, regole RRULE di base derivate dai tipi di ricorrenza nativi e blocchi VALARM per i promemoria. POST /api/calendar/import accetta un payload ICS (fino a 2 MB / 1.000 eventi) in un ambito di calendario scrivibile. L'importatore gestisce UTC e orari mobili, valori DATE per l'intera giornata e semplici regole FREQ. Le regole che non può rappresentare fedelmente (INTERVAL, COUNT, UNTIL, EXDATE) importano l'evento senza ricorrenza e vengono conteggiate nella risposta come regole scartate, invece di provocare spostamenti silenziosi.
Accesso dei modelli
Tre strumenti di chat integrati forniscono ai modelli accesso al calendario con l'identità dell'utente che li invoca: list_calendar_events è di sola lettura; create_calendar_event e delete_calendar_event producono effetti e sono quindi soggetti al flusso standard di approvazione degli strumenti.
API
Tutti gli endpoint richiedono autenticazione. Le letture degli eventi coprono gli eventi dell'utente e i calendari condivisi con lui; le scritture richiedono la proprietà o un'autorizzazione di scrittura sul calendario di destinazione.
| Metodo | Percorso | Scopo |
|---|---|---|
GET | /api/calendar/events?from=&to= | Eventi nell'intervallo, ricorrenze espanse |
POST | /api/calendar/events | Creare un evento |
PUT | /api/calendar/events/:eventId | Aggiornare un evento |
DELETE | /api/calendar/events/:eventId | Eliminare un evento |
GET | /api/calendar/calendars | Calendari con nome propri e condivisi |
POST | /api/calendar/calendars | Creare un calendario con nome |
PUT | /api/calendar/calendars/:id | Rinominare o cambiare colore a un calendario |
DELETE | /api/calendar/calendars/:id | Eliminare un calendario (gli eventi si staccano) |
GET | /api/calendar/export | Esportazione ICS |
POST | /api/calendar/import | Importazione ICS |
Le query per intervallo accettano limiti from/to in millisecondi Unix e coprono al massimo 13 mesi per richiesta. Un utente può memorizzare fino a 2000 eventi; i titoli sono limitati a 200 caratteri e le note a 10.000.