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 (go.bancatransilvania.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 (lines ~529-732)

Flow (2024+ version):

Account 1: Expand card -> Click tranzactii icon -> Select "CSV" -> "Genereaza" -> Download from fba-document-item
Account 2+: Click #selectAccountBtn -> Select by heading name -> "Genereaza" -> Download

Key methods:

• _download_first_account(): Handles first account (expand + select CSV format)
• _download_subsequent_account(): Handles accounts 2+ (dropdown selection)
• _wait_and_download(): Waits for fba-document-item and downloads

Account selection strategies (in order):

1. get_by_role("heading", name=account_name)
2. locator("fba-account-details").filter(has_text=account_name)
3. get_by_text(account_name, exact=True)

Key Selectors

Cookie consent:

• New (2024+): get_by_role("button", name="Accept toate")
• One-time consent: get_by_text("Am inteles")

Login page:

• URL: https://go.bancatransilvania.ro/
• Login link: get_by_role("link", name="Login")
• Username: get_by_placeholder("ID logare") (intelligent fallback in _find_username_field)
• Password: get_by_placeholder("Parola") or input[type='password']
• Submit: get_by_role("button", name="Autentifica-te") (intelligent fallback in _find_submit_button)

Post-login:

• 2FA success indicator: #accountsBtn visible and enabled
• Domain: goapp.bancatransilvania.ro

Accounts:

• Cards: fba-account-details-card
• Expand icon: .mx-auto .mat-icon svg, .collapse-account-btn
• Transactions button: fba-account-buttons svg, .account-transactions-btn

Transaction download:

• Account selector: #selectAccountBtn svg
• Account in dropdown: get_by_role("heading", name=account_name)
• CSV format: get_by_text("CSV", exact=True)
• Generate button: get_by_role("button", name="Genereaza")
• Download item: fba-document-item svg, fba-document-item path

Update selectors: playwright codegen https://go.bancatransilvania.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

• Check fba-document-item selector (wait for document generation)
• Verify #selectAccountBtn for account dropdown
• Account selection: verify heading name matches exactly

2FA Timeout

• Increase TIMEOUT_2FA_SECONDS in .env
• Verify URL redirect to goapp.bancatransilvania.ro
• Check for "Am inteles" consent dialog blocking

Account Selection Failed

• Account name might have changed - verify exact match
• Try running playwright codegen to see current UI structure
• Check if dropdown opened (#selectAccountBtn)

Exit Codes

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