BotFire

1. L'inizio

   Una community e un creator, entrambi poco serviti

   Faccio live su Twitch, e Il Bonfire è il server Discord della mia community, il punto d'incontro dei miei follower, i viandanti. Due incombenze mi rubavano tempo: i suggerimenti di giochi sparsi nella chat, senza un modo ufficiale per raccoglierli, e tenere allineato il calendario di Twitch con Google Calendar, cosa che la sincronizzazione di Twitch fa in modo mezzo rotto. Nessun bot già pronto faceva nessuna delle due come volevo, e preferisco costruire uno strumento su misura piuttosto che piegare il mio modo di lavorare a uno generico.

2. L'obiettivo

   Un bot, due pubblici

   BotFire doveva essere un punto di ritrovo per i viandanti e un pannello di controllo privato per me. Per la community: un modo ufficiale e fatto bene per suggerire giochi, abbastanza furbo da capire le saghe e se un gioco gira su PC, più un modo semplice per sapere quando è la prossima live. Per me: creare, vedere e rimuovere all'istante le live dal calendario di Twitch direttamente da Discord, con Google Calendar che segue in modo affidabile.

3. L'avventura

   Quattro servizi dietro un bot Discord

   Ho iniziato il 16 settembre 2025 e in circa un mese avevo la prima versione completa. BotFire gira su Discord.js v14 con moduli ES e usa i nuovissimi Components V2 di Discord per messaggi interattivi senza embed. Dietro ci sono quattro servizi: IGDB per il database dei giochi, l'API Helix di Twitch per il calendario, Google Calendar per la sincronizzazione e Firestore per suggerimenti e voti. Una cache in memoria con scadenza ed eliminazione dei dati usati meno di recente lo tiene veloce senza martellare nessuno di questi servizi.

   VideoSuggerire un gioco con /suggerisci-gioco

   0:00 / 0:00

4. Le difficoltà

   Saghe, calendari, limiti e fusi orari

   Trovare ogni gioco ufficiale e canonico di una serie ha richiesto query su IGDB molto più complesse di una ricerca: escludere remaster, port e spin-off, poi verificare la disponibilità su PC gioco per gioco. Tenere coerenti due calendari voleva dire collegare ogni evento al suo segmento Twitch e non lasciare mai che un errore del calendario bloccasse Twitch. Discord limita un messaggio a circa 40 componenti, quindi un mese pieno andava diviso su più messaggi. E ogni data doveva sopravvivere a fusi orari e ora legale nel suo viaggio verso due API diverse.

5. La fine

   In uso ogni giorno, e ancora in crescita

   BotFire fa parte di come gestisco il canale ogni giorno. /prossima-live e /suggerisci-gioco sono i comandi più usati dalla community, e il calendario arriva su Google Calendar in modo più affidabile della sincronizzazione ufficiale di Twitch. Non tutti ne sfruttano tutto il potenziale, perché c'è chi ha timore dei bot Discord anche quando sono semplici, ma le funzioni principali sono entrate nella routine del server. È un progetto in corso: continuo ad aggiungere strumenti, a correggere e migliorare quelli esistenti, e aggiorno questa pagina ogni volta che cambia in modo importante.

Cosa aggiungerei

• Un calendario più comodo

  Renderei il calendario ancora più semplice da usare, nei limiti di quello che permettono i Components di Discord. I form di Discord sono ancora limitati, e spero che diventino più potenti.

• Da Calendar a Twitch

  L'infrastruttura per sincronizzare da Google Calendar verso Twitch c'è già; il prossimo passo è la logica che crea i segmenti Twitch partendo dagli eventi del calendario.

• Suggerimenti che capiscono le saghe

  Ricerca basata su IGDB con copertine, riconoscimento delle saghe, controllo PC e niente doppioni.

• Il calendario di Twitch da Discord

  Crea, guarda e rimuovi le live all'istante, in un'interfaccia con navigazione per mese e azioni per ogni live.

• Sincronizzazione con Google Calendar

  Ogni live in programma arriva su Google Calendar, anche quelle ricorrenti, in modo più affidabile della sincronizzazione di Twitch.

• Comandi per la community

  La prossima live, i giochi suggeriti con i loro voti e le informazioni del server, per tutti.

• Cinque livelli di permesso

  Tutti, Membro, Moderatore, Admin e Proprietario, riconosciuti dai ruoli e modificabili con un comando.

• Interfaccia Components V2

  Messaggi senza embed, con pulsanti, modali e menu a tendina, costruiti sui nuovi componenti di Discord.

Suggerimenti di giochi

/suggerisci-gioco cerca su IGDB mentre scrivi e capisce che un gioco può far parte di una saga più grande.

• Riconoscimento delle saghe

  Quando un gioco appartiene a un franchise, BotFire passa all'intera collezione ed elenca ogni capitolo principale.

• Controllo PC

  Faccio live da PC, quindi per i giochi singoli si verifica l'uscita su PC, e per le saghe si calcola la percentuale di compatibilità.

• Niente doppioni

  La stessa persona non può suggerire due volte lo stesso gioco o la stessa saga.

• Ricerca mentre scrivi

  Ricerca su IGDB in tempo reale con copertine e dettagli, dal terzo carattere.

• Voti

  Ogni suggerimento conta come un voto, così i giochi e le saghe più richiesti salgono in cima.

• Filtri intelligenti

  Remaster, port e spin-off restano fuori, così una saga mostra solo i suoi giochi canonici.

Suggerimenti e voti si possono sfogliare per gioco o per saga, con una classifica di chi suggerisce di più.

Il calendario di Twitch

I comandi del calendario sono miei: trasformano Discord nel posto dove pianifico le live.

• Modifiche istantanee

  Aggiungi, guarda e rimuovi le live direttamente da Discord, senza passare dalla dashboard di Twitch.

• Google Calendar, in automatico

  Gli spettatori possono aggiungere le live ai propri calendari, con promemoria e notifiche.

• Categorie con copertina

  Completamento automatico sulle categorie di gioco di Twitch, con le miniature.

• Live ricorrenti

  Un appuntamento settimanale è una sola voce, riportata nel calendario come vero evento ricorrente.

• Fusi orari

  Supporto completo ai fusi orari, ora legale compresa.

• Navigazione veloce

  Mese per mese, con una cache intelligente e i mesi precedente e successivo caricati in anticipo.

Per i viandanti, /prossima-live mostra quando è la prossima live e di cosa parla. Il messaggio si cancella da solo dopo 15 secondi, con un'attesa di 20 secondi tra un uso e l'altro così non può intasare la chat.

Chi può fare cosa

Cinque livelli, dal più ampio al più ristretto. I comandi per suggerire e per la prossima live sono aperti a tutti; la gestione del calendario è riservata al proprietario, e /permission-set può cambiare qualsiasi impostazione.

• Tutti

  Tutti gli utenti, anche senza ruoli.

• Membro

  Utenti con almeno un ruolo oltre a @everyone.

• Moderatore

  Utenti con ruoli o permessi di moderazione.

• Admin

  Utenti con ruoli di amministrazione, e il proprietario del server.

• Proprietario

  Solo il proprietario del bot.

Architettura

BotFire sta tra Discord e tre servizi esterni. Twitch è la fonte di verità per il calendario, Google Calendar lo segue, e Firestore lavora per conto suo per i suggerimenti di giochi.

• API di Twitch (Helix)

  Principale

  Il calendario vive qui. I token a livello di app leggono i dati pubblici; un token utente autorizza le modifiche al calendario.

• API di Google Calendar

  Secondario

  Sincronizzato da Twitch, tramite un account di servizio. Ogni evento conserva l'ID del suo segmento Twitch.

• Firebase Firestore

  Indipendente

  Suggerimenti, voti e dati degli utenti, tramite le credenziali di un account di servizio.

• API di IGDB

  Database dei giochi

  Ricerca, collezioni e piattaforme, autenticata con le stesse credenziali OAuth2 di Twitch.

Ogni azione sul calendario segue lo stesso percorso: comando Discord, validazione, API di Twitch, API di Google Calendar, risposta. Un errore del calendario viene registrato e non blocca mai Twitch.

Sotto il cofano: i suggerimenti

1. Ricerca

   Dal terzo carattere vengono presi fino a 50 risultati da IGDB e mostrati i 25 con il titolo più corto, i più pertinenti.

2. Dettagli

   Il gioco scelto viene caricato per intero, collezioni comprese.

3. Saga

   Se ne fa parte, una multiquery carica in parallelo i giochi e le appartenenze della saga.

4. Controllo PC

   Disponibilità su PC per ogni gioco, e una percentuale per la saga.

5. Conferma e salvataggio

   Una conferma, il controllo dei doppioni, poi Firestore.

La multiquery della saga

Una sola richiesta all'endpoint multiquery di IGDB esegue due query in parallelo. La prima carica ogni gioco della collezione con copertina, date di uscita, piattaforme e gioco principale. La seconda carica le appartenenze alla collezione, così il bot tiene solo i giochi principali (appartenenza type.id === 1) e scarta gli spin-off. I giochi sono ordinati per data di uscita, usando parent_game.first_release_date quando c'è. Il gioco suggerito in origine riceve un indicatore nella lista, i giochi PC una spunta e gli altri un avviso.

I filtri tengono solo:

• Giochi principali (game_type = 0) che non siano remake, remaster o port.
• DLC (game_type = 4) solo su PC, ed espansioni (game_type = 8, 9) ed espansioni standalone (game_type = 10), filtrate allo stesso modo.
• Giochi usciti (game_status = 0 o assente) che hanno un anno di uscita.
• Piattaforme moderne: PC, PlayStation 3, 4 e 5, Xbox 360, One e Series X|S, e Switch.

Compatibilità PC

Per un gioco singolo si cerca un'uscita su PC (Microsoft Windows); se non c'è, la conferma diventa dorata (0xFFD700) con un avviso. Per una saga si controlla la piattaforma 6 (PC) di ogni gioco, e sotto il 75% di compatibilità la community riceve un avviso.

Salvataggio e doppioni

Ogni suggerimento è un documento Firestore il cui ID codifica tipo, obiettivo e utente:

{type}_{targetId}_{userId}

0_1942_123456789   un gioco singolo
1_123_123456789    una collezione

Così lo stesso utente non può suggerire due volte la stessa cosa, tutti i suggerimenti per un gioco sono a una query di distanza, e lo stesso vale per tutti i suggerimenti di un utente. Ogni documento conserva anche il nome dell'obiettivo, il nome dell'utente, un timestamp e i campi di audit (createdAt, updatedAt, createdBy, updatedBy).

• Autenticazione

  OAuth2 di Twitch

  Flusso client credentials; il token resta in memoria e viene rinnovato quando scade, dopo un'ora.

• Prestazioni

  Cache

  Query Firestore in cache per 5 minuti con eliminazione LRU, al massimo 1.000 voci; la multiquery risparmia chiamate.

• Errori

  Resilienza

  Errori di IGDB, del completamento automatico, di Firestore e i timeout sono tutti gestiti, registrati con il contesto e spiegati agli utenti in italiano.

Sotto il cofano: il calendario

Aggiungere una live

1. Form

   Un modale chiede titolo (140 caratteri, il limite di Twitch), data, ora, durata e se si ripete.

2. Validazione

   Formati, date reali, nel futuro ma entro un anno, da 30 minuti a 23 ore, categoria e fuso orario.

3. Fuso orario

   L'ora locale diventa una stringa ISO 8601 con lo scostamento giusto per quella data.

4. Conferma

   Un riepilogo con Conferma e Annulla, che scade dopo 30 secondi.

5. Twitch

   POST /helix/schedule/segment; le live sovrapposte ricevono un errore chiaro.

6. Calendario

   L'evento viene creato e collegato al suo segmento Twitch.

I fusi orari sono il punto dove i calendari di solito si rompono. L'input viene letto come ora locale nel fuso scelto, e lo scostamento viene calcolato per quella data specifica con Intl.DateTimeFormat, così l'ora legale è sempre corretta:

19/09/2025 19:00, Europe/Rome  →  2025-09-19T19:00:00+02:00

L'evento del calendario riceve titolo, descrizione, inizio e fine con il fuso orario e un link al canale. Conserva twitchSegmentId e broadcasterId nelle proprietà estese, e una live ricorrente diventa una RRULE, come RRULE:FREQ=WEEKLY;BYDAY=FR per ogni venerdì.

Vedere il calendario

/schedule è costruito con i Components V2: mese precedente e successivo, un aggiornamento che svuota la cache e un pulsante per chiudere. Ogni live mostra la copertina del gioco, il titolo (con un indicatore per quelle ricorrenti), data e tempo relativo, durata e categoria, più un menu per rimuoverla o copiarne l'ID.

• Budget di componenti

  Limiti di Discord

  Un messaggio contiene 5 righe di azioni e circa 40 componenti. Una live ne costa circa 8, quindi il mese viene diviso: il primo messaggio ne tiene 34 per la navigazione, i successivi hanno tutti i 40.

• Cache

  TTL

  Dati utente per 10 minuti, calendari per 1 minuto, categorie per 1 ora.

• Precaricamento

  Velocità

  I mesi prima e dopo quello sullo schermo si caricano in background, così la navigazione sembra istantanea.

Rimuovere una live

/schedule-remove pulisce prima il calendario: cerca l'evento tramite twitchSegmentId oppure, in alternativa, carica il segmento da Twitch e cerca nel calendario per orario e titolo. Poi chiama DELETE /helix/schedule/segment. Se Twitch non ha più il segmento ma il calendario è stato pulito, segnala comunque il successo; se il calendario fallisce, la cancellazione su Twitch va avanti. Niente si blocca, tutto viene registrato.

Tenere allineati due calendari

Ogni evento del calendario conserva l'ID del suo segmento Twitch in extendedProperties.private.twitchSegmentId. Per trovare un evento, il bot cerca prima per quell'ID, che è veloce, esatto e restituisce l'evento principale di una serie ricorrente. Se non basta, cerca entro 60 minuti dall'orario della live e confronta il titolo. Una serie ricorrente tiene l'ID sull'evento principale, le singole occorrenze lo ereditano, e rimuovere la live rimuove l'intera serie.

/schedule-sync ripara qualsiasi disallineamento:

• Da Twitch a Calendar crea gli eventi mancanti, senza doppioni, e riporta i conteggi. Per la prima configurazione, dopo problemi al calendario o per le live create fuori dal bot.
• Da Calendar a Twitch è in programma: l'infrastruttura c'è, la logica che crea i segmenti Twitch dagli eventi del calendario deve ancora arrivare.
• Sincronizzazione completa esegue entrambe e riporta tutto.

Le operazioni non sono atomiche tra i due servizi, per scelta: Twitch è il principale, il calendario lo segue, e una sincronizzazione manuale può sempre riparare un'incoerenza.

Lo stack

• Discord.js

  14.14.1

  Comandi slash, completamento automatico e Components V2.

• Node.js

  16.9+ con moduli ES

  Il runtime, con import ed export moderni.

• API di Twitch

  Helix, OAuth2

  Gestione del calendario, con token di app e di utente.

• API di IGDB

  OAuth2 di Twitch

  Ricerca dei giochi, collezioni e piattaforme.

• API di Google Calendar

  Account di servizio

  CRUD degli eventi e ricorrenze RRULE.

• Firebase Firestore

  NoSQL

  Voti e persistenza, con cache e campi di audit.

Sfide

Competenze acquisite

• Discord.js v14 e Components V2

  Bot Discord moderni

  Messaggi senza embed, componenti interattivi, modali, comandi slash, completamento automatico e il modello di interazione di Discord.

• IGDB

  Query complesse sui giochi

  Sintassi delle multiquery, collezioni, filtri sulle piattaforme e la logica per distinguere i giochi canonici dal resto.

• Twitch Helix

  Gestione del calendario

  OAuth2 di app e di utente, CRUD dei segmenti, ricerca delle categorie, fusi orari e limiti di richieste.

• Google Calendar

  Sincronizzazione

  Account di servizio, CRUD degli eventi, ricorrenze RRULE, proprietà estese per i collegamenti e fusi orari con l'ora legale.

• Firestore

  NoSQL e cache

  CRUD dei documenti, progettazione delle query, ID personalizzati, campi di audit e cache in memoria con TTL ed eliminazione LRU.

• Architettura di integrazione

  Sincronizzazione tra servizi

  Schemi principale e secondario, collegamenti nei due sensi, gestione degli errori tra servizi e dati coerenti.