matcha-alert

Matcha Restock Alert is a small automation project that watches every matcha product on the Marukyu-Koyamaen international shop and sends an email when an item goes from sold out back to in stock. Because the shop restocks randomly without announcing a schedule, the project runs in the cloud around the clock so your own computer can be off. How it works: an external free pinger (cron-job.org) calls the GitHub Actions workflow every five minutes via the workflow_dispatch API. The workflow runs matcha_monitor.py, which visits each product page and looks for the shop's own "currently out of stock and unavailable" message; no message means the item is buyable. The script stores each product's last status in state.json, which is committed back to the repository after each run, and only emails when something newly restocks, avoiding repeat spam. If an email fails to send, the alert is retried on the next run. To be polite to the shop, each five-minute run only re-checks items currently sold out, with a full sweep once an hour to catch new sell-outs. Requests are spaced two seconds apart and use a normal browser identity. The script also scans the catalog for brand-new matcha products, auto-watches them, and emails when they appear. The workflow's own */30 cron schedule is kept only as a backup because GitHub's cron is heavily throttled in practice. Setup requires a Gmail app password, repository secrets for SMTP user, password and recipient, and a fine-grained GitHub token scoped to the repo with Actions read/write permission configured on cron-job.org as a POST job with a JSON body. A test run returning 204 confirms it works, and a test-email workflow dispatch verifies delivery. The watch list lives in products.json with roughly 50 matcha products; items can be added, removed, or paused with "watch": false. Auto-discovered products are stored in state.json and can be paused the same way. The main files are matcha_monitor.py (the checker and emailer, also runnable locally with --force), products.json, state.json, and the GitHub Actions workflow file. Notes: the shop discourages aggressive scraping and its bot protection may block requests. The script detects block or challenge pages and never mistakes them for in-stock status; blocked checks are simply retried next run. Matcha is limited to five items per order, and the shop declines orders it believes are for resale.