matcha-alert

Matcha Restock Alert es un pequeño proyecto de automatización que supervisa todos los productos de matcha de la tienda internacional de Marukyu-Koyamaen y envía un correo cuando un artículo pasa de agotado a disponible. Como la tienda repone existencias de forma aleatoria y sin anunciar un calendario, el proyecto se ejecuta en la nube las 24 horas para que tu propio equipo pueda estar apagado. Funcionamiento: un servicio externo gratuito de ping (cron-job.org) llama al workflow de GitHub Actions cada cinco minutos mediante la API workflow_dispatch. El workflow ejecuta matcha_monitor.py, que visita cada página de producto y busca el mensaje propio de la tienda «currently out of stock and unavailable»; si no aparece el mensaje, el artículo puede comprarse. El script guarda el último estado de cada producto en state.json, que se vuelve a confirmar en el repositorio tras cada ejecución, y solo envía correos cuando algo se repone por primera vez, evitando correos repetidos. Si falla el envío, la alerta se reintenta en la siguiente ejecución. Para ser respetuoso con la tienda, cada ejecución de cinco minutos solo vuelve a comprobar los artículos agotados en ese momento, con un barrido completo una vez por hora para detectar nuevos agotamientos. Las solicitudes se espacian dos segundos y usan una identidad de navegador normal. El script también escanea el catálogo en busca de productos de matcha totalmente nuevos, los supervisa automáticamente y envía un correo cuando aparecen. La propia programación cron */30 del workflow se mantiene solo como respaldo porque, en la práctica, el cron de GitHub está muy limitado. La configuración requiere una contraseña de aplicación de Gmail, secretos del repositorio para el usuario SMTP, la contraseña y el destinatario, y un token de GitHub de grano fino vinculado al repositorio con permiso de lectura/escritura de Actions, configurado en cron-job.org como un trabajo POST con cuerpo JSON. Una ejecución de prueba que devuelve 204 confirma que funciona, y una activación del workflow test-email verifica la entrega. La lista de supervisión está en products.json, con unos 50 productos de matcha; los artículos pueden añadirse, eliminarse o pausarse con "watch": false. Los productos detectados automáticamente se guardan en state.json y pueden pausarse de la misma forma. Los archivos principales son matcha_monitor.py (el comprobador y remitente de correos, que también puede ejecutarse localmente con --force), products.json, state.json y el archivo del workflow de GitHub Actions. Notas: la tienda desaconseja el rastreo agresivo y su protección contra bots puede bloquear solicitudes. El script detecta páginas de bloqueo o desafío y nunca las confunde con el estado de disponible; las comprobaciones bloqueadas simplemente se reintentan en la siguiente ejecución. El matcha está limitado a cinco artículos por pedido, y la tienda rechaza los pedidos que considera destinados a reventa.