# CLAUDE.md

This file provides guidance to Claude Code when working with code in this repository.

## Project Overview

BTGO Scraper - Playwright automation for extracting account balances and transaction CSVs from Banca Transilvania George (btgo.ro).

**Security Context**: Authorized personal banking automation tool for educational purposes.

**⚠️ CRITICAL**: Docker/headless mode is **BLOCKED by WAF**. ONLY works locally with `HEADLESS=false`.

## Running the Scraper

```powershell
# Windows setup
deployment\windows\scripts\setup_dev.ps1

# Run scraper (browser visible)
deployment\windows\scripts\run_scraper.ps1

# Run Telegram bot (manual)
deployment\windows\scripts\run_telegram_bot_manual.ps1

# Interactive menu (all options)
deployment\windows\scripts\menu.ps1
```

## Architecture

### Core Flow
```
login() → handle_2fa_wait() → read_accounts() → download_transactions() → save_results()
```

### Critical Implementation Details

#### 1. Login with Popup (lines ~140-200)
- Main page → Click "LOGIN" → **Opens popup window**
- Use `page.expect_popup()` to capture popup reference
- All operations happen in `self.login_page` (the popup)

#### 2. 2FA Auto-Detection (lines ~202-240)
- URL monitoring: `login.bancatransilvania.ro` → `goapp.bancatransilvania.ro`
- Poll for `#accountsBtn` element every 2 seconds
- After 2FA: `self.page = self.login_page` (switch page reference)

#### 3. Account Reading (lines ~242-310)
- Elements: `fba-account-details-card`, `#accountsBtn`
- Each card: `h4` (name), `span.text-grayscale-label` (IBAN), `strong.sold` (balance)
- Balance format: `"7,223.26 RON"` → parse to float + currency

#### 4. Transaction Download Modal (lines ~312-420)

**State Machine:**
```
Account 1: Expand card → Click "Tranzacții" → Download → Back → Modal
Account 2+: Select from modal → [ALREADY on page] → Download → Back
```

**Critical**: After modal selection, you're ALREADY on transactions page. Don't expand/click again.

**Modal selectors:**
- Modal: `.modal-content`
- Account buttons: `#accountC14RONCRT{last_10_iban_digits}`
- Example: IBAN `...0637236701` → `#accountC14RONCRT0637236701`

### Key Selectors

- Login: `get_by_placeholder("ID de logare")`, `get_by_placeholder("Parola")`
- Post-login: `#accountsBtn`, `goapp.bancatransilvania.ro` domain
- Accounts: `fba-account-details-card`, `.collapse-account-btn`, `.account-transactions-btn`
- Modal: `.modal-content`, `#accountC14RONCRT{iban_digits}`
- CSV: `get_by_role("button", name="CSV")`

**Update selectors:** `playwright codegen https://btgo.ro --target python`

## Docker Limitation

**Docker DOES NOT WORK** - Akamai WAF blocks with "Access Denied".

**Symptoms:**
- "Access Denied" page
- 0 links detected
- Screenshot: `data/debug_before_login_*.png` shows error

**Solution:** Use Windows local mode with `HEADLESS=false`.

## Common Issues

### Access Denied (Docker)
- **Cause**: WAF blocking
- **Fix**: Run locally with `HEADLESS=false`

### Transaction Download Timeout
- Modal not detected: Check `.modal-content` selector
- Account ID mismatch: Verify IBAN mapping `#accountC14RONCRT{last_10_digits}`
- For idx > 1: Already on page, don't expand/click

### 2FA Timeout
- Increase `TIMEOUT_2FA_SECONDS` in `.env`
- Verify URL redirect to `goapp.bancatransilvania.ro`

### "Nu exista card la pozitia X"
- Trying to access cards in modal context
- First account needs expand, subsequent accounts don't

## Exit Codes

- `0`: Success
- `1`: General error
- `4`: Config error (.env invalid)
- `99`: Unexpected error