🥗 Diet Bot

Bot Telegram per gestire dieta e spesa, multi-persona.

Storage su file JSON · nessun database · pensato per girare H24 su un Raspberry Pi Zero 2W.

✨ Funzioni

| | Funzione | Descrizione | |---|---|---| | ⏰ | Promemoria a fasce orarie | Notifiche per ricordare cosa mangiare e — in anticipo — cosa cucinare, configurabili per persona. | | 🛒 | Lista della spesa settimanale | /spesa aggrega gli alimenti della settimana in un'unica checklist con spunte; ogni voce mostra quantità totale, dose per porzione e quante volte a settimana. | | 🧾 | Ingredienti di oggi | /oggispesa consolida i primary di tutti i pasti odierni (tutti i profili) in un'unica lista con le quantità totali. |

Perché così leggero? Il target è un Pi Zero 2W (quad-core Cortex-A53, 512 MB RAM): da qui le scelte di stack — long polling (niente webhook/HTTPS), nessun database, footprint RAM contenuto (heap limitata a 256 MB).

📑 Indice

• Requisiti
• Installazione da npm
• Configurazione · guida completa
• Comandi
• Aggiornamento
• Release & publishing
• Note tecniche
• Licenza

📋 Requisiti

• Node.js ≥ 20 (vedi .node-version) — su OS a 32 bit installalo via nvm, così i pacchetti globali finiscono in una cartella scrivibile dall'utente (niente sudo).
• Un token bot da @BotFather
• PM2 per la gestione del processo

📦 Installazione da npm

Il bot è pubblicato su npm come diet-handler-tgbot: si installa con un solo comando, senza clonare il repo né compilare nulla sul Raspberry Pi.

npm install -g diet-handler-tgbot

Questo aggiunge il comando diet-handler-bot.

Il pacchetto include il bot compilato, la specifica del formato dieta e users.example.json, ma non i dati personali. Tieni config e dati in una cartella dedicata e fai puntare lì DATA_DIR:

mkdir -p ~/diet-bot/data/diets && cd ~/diet-bot

nano .env                       # BOT_TOKEN=... e DATA_DIR=/home/<utente>/diet-bot/data
nano data/users.json            # i tuoi profili (vedi users.example.json)
nano data/diets/<dietId>.json   # la/le tua/e dieta/e, secondo formato-dieta.md

⚠️ DATA_DIR è la causa più comune di "non funziona". Con l'install globale, il default dei dati è la cartella dentro il pacchetto in node_modules (che contiene solo users.example.json), non la tua. Imposta sempre DATA_DIR su un percorso assoluto alla cartella data/ che hai creato. In alternativa puoi usare ./data (relativo), ma allora devi avviare PM2 con --cwd ~/diet-bot.

Avvia il bot sotto PM2 (heap limitata a 256 MB per contenere la RAM):

pm2 start "$(which diet-handler-bot)" --name diet-bot --cwd ~/diet-bot \
  --node-args="--max-old-space-size=256"

pm2 save              # salva la lista processi
pm2 startup           # stampa un comando `sudo ...` — eseguilo così com'è

Dopo aver eseguito il comando sudo stampato, lancia di nuovo pm2 save.

Comandi PM2 utili

pm2 status               # elenco processi
pm2 logs diet-bot        # log in tempo reale (utile per il debug)
pm2 restart diet-bot     # riavvia
pm2 stop diet-bot        # ferma
pm2 delete diet-bot      # rimuove dalla lista

⚙️ Configurazione

📖 Guida completa passo-passo: CONFIGURAZIONE.md — struttura della cartella, users.json campo per campo, errori comuni.

In breve:

• Diete — un file per dieta in data/diets/<dietId>.json (formato v1.0, vedi formato-dieta.md). Il dietId del profilo è il nome del file senza .json.
• Utenti/profili — data/users.json (con la s: un file user.json viene ignorato). Ogni utente Telegram può avere più profili (persone), ognuno con la propria dieta e le proprie fasce orarie. Recupera il tuo ID Telegram (es. con @userinfobot) e usalo come chiave e come chatId.
• DATA_DIR — cartella dati (diete, utenti, stato runtime). Con l'install da npm va impostata su un percorso assoluto alla tua cartella data/, fuori da node_modules (vedi Installazione).

Fasce orarie (schedule)

Per ogni pasto: at = orario del promemoria "mangia"; prepBefore (opzionale, minuti) = anticipo per il promemoria "cucina".

💬 Comandi

| Comando | Azione | |---|---| | /start | Registra la chat e mostra l'aiuto | | /oggi | Piano alimentare completo di oggi | | /pasto | Prossimo pasto | | /oggispesa | Ingredienti di oggi: lista consolidata con quantità totali | | /spesa | Lista spesa settimanale (checklist, con dose per porzione e volte/settimana) | | /promemoria on\|off | Attiva/disattiva le notifiche |

🔄 Aggiornamento

npm update -g diet-handler-tgbot
pm2 restart diet-bot

I tuoi .env, data/users.json e lo stato runtime stanno nella tua cartella data/ e non vengono toccati dall'aggiornamento. Per aggiungere o modificare una dieta basta editare data/diets/<dietId>.json e fare pm2 restart diet-bot (nessuna ricompilazione).

📦 Release & publishing

Il workflow .github/workflows/release.yml si attiva al push di un tag vX.Y.Z (annotato) e:

1. compila il TypeScript e produce un bundle a singolo file, allegandolo a una GitHub Release (note prese dal messaggio del tag);
2. pubblica il pacchetto su npm (nome non scoped) — richiede il secret NPM_TOKEN; se assente, questo passo viene saltato;
3. ripubblica su GitHub Packages sotto lo scope @owner (usa il GITHUB_TOKEN integrato).

Tieni allineata la version in package.json con il tag:

npm version patch            # aggiorna package.json e crea il tag
git push --follow-tags

🔧 Note tecniche

• Sorgenti in src/*.ts, compilati in CommonJS in dist/ (tsconfig.json).
• Scheduler: node-cron con tick al minuto (* * * * *), confronto orario per fuso dell'utente via API Intl (nessuna libreria timezone esterna).
• Invio notifiche fuori dagli handler: bot.api.sendMessage(chatId, ...).
• Stato anti-duplicato in data/notify-state.json; spunte spesa in data/shopping/<chatId>.json. Scritture atomiche (tmp + rename).

📄 Licenza

MPL-2.0