Add or Improve Transaction Importers

[ShichengRao]

Add or Improve Transaction Importers

DeskBooks supports importing local transaction exports from banks, credit cards, brokerages, and similar financial institutions. We would like to gradually expand importer coverage so more people can use the app with their own exported files.

This is an ongoing starter issue. Contributors are welcome to reply with PRs that add support for one additional CSV/XLSX export format, improve detection for an existing format, or add missing test coverage for an importer.

Please do not include real financial data in PRs.

Why This Is A Good First Issue

Each importer is small, testable, and mostly isolated from the rest of the app. It is a good way to learn DeskBooks’ transaction model without needing to understand the full frontend or analytics system.

Useful files:

• backend/app/importers/base.py
• backend/app/importers/chase_credit.py
• backend/app/importers/wells_fargo_checking.py
• backend/app/importers/amex.py
• backend/app/importers/us_banks.py
• backend/tests/test_importers.py
• samples/

What A Good PR Includes

A good importer PR usually includes:

• A parser for one transaction export format.
• Header sniffing via can_handle(...), so DeskBooks can recognize the file.
• Normalization into DeskBooks transaction drafts:
  • transaction date
  • optional post date
  • raw description
  • normalized description
  • signed amount
  • raw source columns
  • optional suggested kind, such as income, refund, transfer, or credit card payment
• Synthetic test rows in backend/tests/test_importers.py.
• Optional synthetic sample file under samples/ if useful.

Privacy Rules

Use only synthetic data.

Do not commit:

• real bank exports
• real account numbers
• real merchant history
• real balances
• names, addresses, emails, or other personal details

Amounts, dates, and merchant names in tests should be fake.

Example synthetic row:

06/01/2026,NEIGHBORHOOD COFFEE,-6.75

Sign Conventions

DeskBooks generally normalizes everyday spending as negative and income/payments as positive.

Examples:

• Coffee purchase: -6.75
• Payroll deposit: 2500.00
• Refund: usually positive
• Credit card payment: usually positive

Some institutions export credit card charges as positive numbers. Existing importers may flip those to DeskBooks’ outflow-negative convention. Please add tests that make the intended behavior obvious.

Suggested PR Shape

A small importer PR might:

1. Add or update an importer class in backend/app/importers/.
2. Register it with the importer registry if adding a new class.
3. Add one or more tests to backend/tests/test_importers.py.
4. Optionally add a synthetic sample file under samples/.
5. Run backend tests.

Verification command:

cd backend && uv run pytest

Frontend changes are usually not needed for importer-only PRs.

Acceptance Criteria

A PR is ready for review when:

• The importer recognizes the intended file headers.
• It parses realistic synthetic rows correctly.
• It handles dates and amounts consistently.
• It preserves source columns in the raw transaction data where appropriate.
• It does not include private financial data.
• Backend tests pass with uv run pytest.

Helpful Edge Cases To Cover

Importer tests are especially useful when they cover:

• purchases/spending
• income/deposits
• refunds/returns
• credit card payments
• transfers
• pending vs posted rows, if the export includes status
• separate debit/credit columns
• running balance columns that should be ignored
• odd header names or extra columns
• quoted descriptions containing commas

Claiming Work

Multiple contributors can work from this issue. To avoid duplicate effort, please comment with the format you plan to support before opening a PR.

Suggested comment format:

I’m working on importer support for:
<institution or export shape>

File type:
CSV or XLSX

Headers:
Date, Description, Amount, ...

Notes:
Any sign convention, status, or parsing details worth mentioning.

When your PR is ready, reply here with:

Added importer support for:
<institution or export shape>

PR:
#123