Script Creation

Generate a new bank script by combining the output of Teach with an LLM.

Workflow

Run beanscrape teach <bank-id> to capture bank website details. Output: ./prompts/<bank-id>.md.
Open the prompt file and the script generation guide (bundled with Beanscrape, also at docs/new-script.md in the source repo).
Paste both into an LLM (Claude, ChatGPT, etc.).
The LLM generates a .csx script.
Save the script as <bank-id>.csx.
Test: beanscrape run ./<bank-id>.csx --debug.
Iterate with the LLM if the script needs adjustments.

Script structure

A bank script is a C# script (.csx) that uses Beanscrape’s runtime API:

// Required: bank metadata
BankId = "mybank";
BankName = "My Bank";
BankUrl = "https://www.mybank.com";

// Required: scrape function
Scrape = async (page) =>
{
    // 1. Navigate to login page
    await NavigateAsync(page, "https://www.mybank.com/login");

    // 2. Enter credentials
    await FillAsync(page.Locator("#username"), Env("MYBANK_USERID"));
    await FillAsync(page.Locator("#password"), Env("MYBANK_PASSWORD"));
    await ClickAsync(page.Locator("#login-button"));

    // 3. Navigate to transactions
    await NavigateAsync(page, "https://www.mybank.com/transactions");

    // 4. Extract transactions
    var rows = await page.Locator(".transaction-row").AllAsync();
    foreach (var row in rows)
    {
        AddTransaction(new Transaction
        {
            Date = ParseDate(await row.Locator(".date").TextContentAsync()),
            Payee = await row.Locator(".payee").TextContentAsync(),
            Outflow = ParseAmount(await row.Locator(".amount").TextContentAsync()),
        });
    }
};

Available API

Environment & logging

Method	Description
`Env(name)`	Read environment variable or credential
`Log(message)`	Write to debug log

Browser helpers

Method	Description
`NavigateAsync(page, url)`	Navigate with retries
`ClickAsync(locator)`	Click with human-like delay
`FillAsync(locator, value)`	Type text with human-like delay
`HumanDelayAsync(min, max)`	Random wait (default 500–1500ms)
`WaitForSelectorAsync(page, selector)`	Wait for element
`IsElementVisibleAsync(page, selector)`	Check element visibility

Parsing helpers

Method	Description
`ParseDate(string)`	Parse various date formats to `DateOnly`
`ParseAmount(string)`	Parse currency string to `decimal`
`ParseAmountAccounting(string)`	Parse accounting format (parentheses = negative)

File parsing

Method	Description
`ParseQfx(filePath)`	Parse OFX/QFX file to transactions
`ParseQfxContent(content)`	Parse OFX/QFX string content

Available libraries

Scripts have access to:

Playwright: browser automation
CsvHelper: CSV parsing
QFXparser: OFX/QFX parsing
System.Text.Json: JSON handling
Standard .NET libraries (Linq, Regex, IO, Collections)

Tips

Use --debug when testing to see detailed logs.
Use --keep-open to inspect the browser state after a scrape.
Some banks serve different content based on viewport size. The default viewport works for most.
For banks that offer CSV/OFX download, prefer downloading the file and parsing it rather than scraping the DOM. It’s more reliable.

Keyboard shortcuts

Surebeans Guide