add CLAUDE.md

CLAUDE.md

@@ -0,0 +1,58 @@
+# CLAUDE.md
+
+This file provides guidance to Claude Code (claude.ai/code) when working with code in this repository.
+
+## Project Overview
+
+This is a Mullvad VPN account expiry monitor that scrapes account information and sends Discord webhook notifications when the account is close to expiring. The project consists of a single Python script with intelligent caching and duplicate notification prevention.
+
+## Core Architecture
+
+- **Single-file application**: `mullvad_check.py` contains all logic
+- **Web scraping workflow**: POST login → GET account page → parse HTML with BeautifulSoup
+- **JSON-based caching**: Uses `mullvad_cache.json` to store expiry data and notification state
+- **Session-based authentication**: Maintains cookies between login and account page requests
+
+## Environment Configuration
+
+Required environment variables:
+- `MULLVAD_ACCOUNT_NUMBER`: Your Mullvad account number
+- `DISCORD_WEBHOOK_URL`: Discord webhook URL for notifications
+- `MULLVAD_WARNING_DAYS`: Days before expiry to warn (default: 5, configurable for testing)
+
+## Development Commands
+
+```bash
+# Setup
+python3 -m venv env
+env/bin/pip install -Ur requirements.txt
+
+# Run
+env/bin/python3 ./mullvad_check.py
+
+# Test with different warning periods
+MULLVAD_WARNING_DAYS=60 env/bin/python3 ./mullvad_check.py
+```
+
+## Key Implementation Details
+
+- **Cache expiry**: 10 days (`CACHE_EXPIRY_DAYS`)
+- **Target HTML element**: `<time data-cy="account-expiry">` with `datetime` attribute
+- **Notification idempotency**: Tracks `notification_sent_for_expiry` to prevent duplicate alerts
+- **Headers**: Full browser-like headers required to avoid 403 responses, including `x-sveltekit-action: true`
+
+## Cache Structure
+
+The `mullvad_cache.json` file stores:
+- `account_expiry`: ISO datetime string
+- `last_scrape`: Unix timestamp
+- `last_notification_sent`: Unix timestamp (optional)
+- `notification_sent_for_expiry`: Expiry datetime for which notification was sent (optional)
+
+## Typical Workflow
+
+1. Check cache validity (10-day expiry)
+2. If cache valid, calculate days remaining and check notification requirements
+3. If cache expired, perform login flow and scrape fresh data
+4. Send Discord notification only if within warning period and not previously notified for this expiry date
+5. Update cache with new data and notification state