btgo-playwright/CLAUDE.md

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.

Coding Guidelines

NO EMOJIS: Do not use emojis in user-facing messages (Telegram, email, notifications). Use plain text only.

Running the Scraper

# 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