Enrich Lunch Money Transactions with Regex Rules

Applies regex extraction rules to your Lunch Money transactions to pull structured data out of raw payee names and Plaid metadata. Useful for extracting booking codes, reference numbers, or other patterns that Lunch Money doesn't parse on its own.

Installation

Run the CLI with uvx; it downloads the package automatically when needed.

Set your API key:

export LUNCH_MONEY_API_KEY=your_token_here

Usage

Run manually

uvx lunchmoney-transaction-enhancer

Dry run (no writes)

uvx lunchmoney-transaction-enhancer --dry-run

Run via cron

# Ensure HEARTBEAT_URL is set in your environment
uvx lunchmoney-transaction-enhancer --cron

Options

• --lookback N — days to look back, overriding persisted state (default: 180 if no state exists)
• --dry-run — log what would be updated without making any changes
• --cron — wait for internet connectivity before running, send heartbeat on success

Features

• Define regex rules against any transaction field (payee, notes, original_name) or Plaid metadata (plaid_name)
• Extract named capture groups and format them into a target field using a template string
• Skips updates when the target field already contains the correct value
• Preserves existing transaction notes and logs a warning when a note enhancement is skipped
• Persists a last-checked timestamp so each run only processes new transactions
• Cron mode waits up to 8 hours for internet connectivity via exponential backoff, then pings a heartbeat URL (compatible with Healthchecks.io, Better Stack, etc.)

Supported Services

Note enhancements are applied only when the transaction does not already have a note. Other enhancements, such as Capital One Travel payee normalization, can still be applied independently.

Configuring Rules

Rules are defined in lunchmoney_transaction_enhancer/config.py:

ExtractionRule(
    name="Airbnb Code",
    source_field="plaid_name",  # field to match against
    pattern=r"AIRBNB \* (?P<code>[A-Z0-9]{10})",
    target_field="notes",  # field to write to
    template="Airbnb Code: {code}",  # use named capture groups as variables
)

Privacy & Data Handling

• Account data fetched: Only transaction objects (payee, notes, amount, date, original name, and Plaid metadata) within the lookback window are retrieved via the Lunch Money API. Account balances, credentials, and other non-transaction data are never requested.
• Local data retention: Only a single timestamp (data/last_checked.txt) is persisted locally to track state between runs. No transactions or financial details are stored on disk.
• Logging: Transaction update logs include transaction IDs, payee names, and modified fields. Payee names and note contents may be visible in standard output or centralized log aggregators.

MIT License

This project was created from iloveitaly/python-package-template