Airtable — base "Attività e Progetti"

Questa skill mi permette di leggere e modificare la base di lavoro di Ettore su Airtable
tramite l'API REST ufficiale. Il token sta nella variabile d'ambiente AIRTABLE_TOKEN
(mai scriverlo nei messaggi né nei file).

Regola d'oro (come in AGENTS.md)

• Lettura: libera. Posso interrogare la base quando serve per farmi il contesto.
• Scrittura (create / update / delete): solo con conferma. Prima dico a Ettore cosa voglio scrivere, in quale tabella e perché, e aspetto l'OK. Poi eseguo.

Base e tabelle

Base ID: app5EU480jgD2WuJ9

Note utili: i campi link (es. Attività, Progetti, Sotto-Attività) contengono ID di record
(rec...), non testo. Priorità/Stato/Tipo sono singleSelect: usare esattamente i valori già
esistenti nella base (in caso di dubbio, prima leggo i valori presenti).

La base cambia nel tempo — verifico la struttura dal vivo

La tabella qui sopra è una fotografia del 25/06/2026. Gli ID non cambiano se Ettore
rinomina tabelle o campi, quindi le chiamate restano valide. Ma se aggiunge o toglie tabelle/campi,
la mappa può diventare vecchia. Perciò: **se qualcosa non torna (errore 422, campo che non esiste,
nuova tabella), o prima di una scrittura importante, chiedo ad Airtable la struttura aggiornata**
invece di fidarmi solo della fotografia:

curl.exe -s "https://api.airtable.com/v0/meta/bases/app5EU480jgD2WuJ9/tables" `
  -H "Authorization: Bearer $env:AIRTABLE_TOKEN"

Questo restituisce tabelle e campi correnti (ID + nomi + tipi). Richiede che il token abbia lo
scope schema.bases:read. In pratica: la fotografia mi fa partire veloce, l'endpoint meta mi
tiene allineato quando la base evolve.

Come chiamo l'API (Windows / PowerShell)

• Endpoint base: https://api.airtable.com/v0/app5EU480jgD2WuJ9/<TABLE_ID>
• Uso gli ID tabella (sopra), così evito problemi con spazi/accenti nei nomi.
• Header di autenticazione: Authorization: Bearer $env:AIRTABLE_TOKEN
• Importante su Windows: uso curl.exe (non curl, che in PowerShell è un alias di Invoke-WebRequest). In alternativa va benissimo Invoke-RestMethod.

Leggere record (GET)

curl.exe -s "https://api.airtable.com/v0/app5EU480jgD2WuJ9/tblBxG70UIBAldYWr?pageSize=20" `
  -H "Authorization: Bearer $env:AIRTABLE_TOKEN"

Filtri: aggiungere filterByFormula URL-encoded, es. solo attività con Stato "In corso":
?filterByFormula= + encode di {Stato}="In corso". Ordino con
sort[0][field]=Priorità&sort[0][direction]=asc.

Creare un record (POST) — solo dopo OK

curl.exe -s -X POST "https://api.airtable.com/v0/app5EU480jgD2WuJ9/tblBxG70UIBAldYWr" `
  -H "Authorization: Bearer $env:AIRTABLE_TOKEN" -H "Content-Type: application/json" `
  -d '{ "records": [ { "fields": { "Nome": "Esempio", "Stato": "Da iniziare" } } ] }'

Aggiornare un record (PATCH) — solo dopo OK

curl.exe -s -X PATCH "https://api.airtable.com/v0/app5EU480jgD2WuJ9/tblBxG70UIBAldYWr" `
  -H "Authorization: Bearer $env:AIRTABLE_TOKEN" -H "Content-Type: application/json" `
  -d '{ "records": [ { "id": "recXXXXXXXXXXXXXX", "fields": { "Stato": "Completato" } } ] }'

Cancellare (DELETE) — solo dopo OK esplicito

DELETE https://api.airtable.com/v0/app5EU480jgD2WuJ9/tblBxG70UIBAldYWr?records[]=recXXXX

Pattern d'uso tipico

1. Ettore chiede qualcosa sui progetti/attività → leggo la tabella giusta e rispondo.
2. Per scrivere → preparo il JSON, mostro cosa farei (tabella, campi, valori) e chiedo conferma.
3. Dopo l'OK, eseguo la chiamata e confermo l'esito (con l'ID del record creato/aggiornato).
4. Se un valore singleSelect non esiste ancora, lo segnalo invece di inventarlo.

Errori comuni

• 401 Unauthorized → token assente/sbagliato: controllare AIRTABLE_TOKEN e i suoi permessi.
• 403 → il token non ha accesso a questa base o manca lo scope (serve read e/o write).
• 422 → nome campo o valore singleSelect non valido.