From aee76966d19d9c2a8b53f60322c034dc224ec0b1 Mon Sep 17 00:00:00 2001
From: Luna <git@l4.pm>
Date: Tue, 22 Jul 2025 00:35:56 -0300
Subject: [PATCH] add CLAUDE.md

---
 CLAUDE.md | 58 +++++++++++++++++++++++++++++++++++++++++++++++++++++++
 1 file changed, 58 insertions(+)
 create mode 100644 CLAUDE.md

diff --git a/CLAUDE.md b/CLAUDE.md
new file mode 100644
index 0000000..6a0664a
--- /dev/null
+++ b/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
\ No newline at end of file