matcha-alert

O Matcha Restock Alert é um pequeno projeto de automação que monitora todos os produtos de matchá na loja internacional da Marukyu-Koyamaen e envia um e-mail quando um item passa de esgotado para disponível. Como a loja reabastece aleatoriamente, sem anunciar cronograma, o projeto é executado na nuvem 24 horas por dia para que seu próprio computador possa ficar desligado. Como funciona: um pinger externo gratuito (cron-job.org) chama o workflow do GitHub Actions a cada cinco minutos por meio da API workflow_dispatch. O workflow executa matcha_monitor.py, que visita cada página de produto e procura a mensagem da própria loja "currently out of stock and unavailable"; a ausência da mensagem significa que o item pode ser comprado. O script armazena o último status de cada produto em state.json, que é commitado de volta ao repositório após cada execução, e só envia e-mail quando algo é reabastecido recentemente, evitando spam repetido. Se o envio de um e-mail falhar, o alerta é tentado novamente na próxima execução. Para ser educado com a loja, cada execução de cinco minutos apenas reverifica os itens atualmente esgotados, com uma varredura completa uma vez por hora para capturar novos esgotamentos. As solicitações são espaçadas em dois segundos e usam uma identidade normal de navegador. O script também varre o catálogo em busca de produtos de matchá totalmente novos, monitora-os automaticamente e envia um e-mail quando eles aparecem. A própria programação cron */30 do workflow é mantida apenas como backup porque, na prática, o cron do GitHub é fortemente limitado por throttling. A configuração exige uma senha de app do Gmail, segredos do repositório para usuário SMTP, senha e destinatário, e um token GitHub refinado, restrito ao repositório, com permissão de leitura/gravação no Actions, configurado no cron-job.org como um job POST com corpo JSON. Uma execução de teste que retorna 204 confirma que funciona, e um dispatch do workflow test-email verifica a entrega. A lista de monitoramento fica em products.json, com cerca de 50 produtos de matchá; itens podem ser adicionados, removidos ou pausados com "watch": false. Produtos descobertos automaticamente são armazenados em state.json e podem ser pausados da mesma forma. Os arquivos principais são matcha_monitor.py (o verificador e remetente de e-mail, também executável localmente com --force), products.json, state.json e o arquivo de workflow do GitHub Actions. Observações: a loja desencoraja scraping agressivo e sua proteção contra bots pode bloquear solicitações. O script detecta páginas de bloqueio ou desafio e nunca as confunde com status de disponível; verificações bloqueadas são simplesmente repetidas na próxima execução. O matchá é limitado a cinco itens por pedido, e a loja recusa pedidos que acredita serem para revenda.