Files

Jacob Kiers c67378ff25 Implement encrypted transaction caching for GoCardless adapter

- Reduces GoCardless API calls by up to 99% through intelligent caching of transaction data
- Secure AES-GCM encryption with PBKDF2 key derivation (200k iterations) for at-rest storage
- Automatic range merging and transaction deduplication to minimize storage and API usage
- Cache-first approach with automatic fetching of uncovered date ranges
- Comprehensive test suite with 30 unit tests covering all cache operations and edge cases
- Thread-safe implementation with in-memory caching and encrypted disk persistence

2025-11-22 15:16:39 +00:00

2.8 KiB

Raw Blame History

Banks2FF

A robust command-line tool to synchronize bank transactions from GoCardless (formerly Nordigen) to Firefly III.

✨ Key Benefits

Automatic Transaction Sync: Keep your Firefly III finances up-to-date with your bank accounts
Intelligent Caching: Reduces GoCardless API calls by up to 99% through encrypted local storage
Multi-Currency Support: Handles international transactions and foreign currencies correctly
Smart Duplicate Detection: Avoids double-counting transactions automatically
Reliable Operation: Continues working even when some accounts need attention
Safe Preview Mode: Test changes before applying them to your finances
Rate Limit Aware: Works within API limits to ensure consistent access

🚀 Quick Start

Prerequisites

Rust (latest stable)
GoCardless Bank Account Data account
Running Firefly III instance

Setup

Copy environment template: cp env.example .env
Fill in your credentials in .env:
- GOCARDLESS_ID: Your GoCardless Secret ID
- GOCARDLESS_KEY: Your GoCardless Secret Key
- FIREFLY_III_URL: Your Firefly instance URL
- FIREFLY_III_API_KEY: Your Personal Access Token
- BANKS2FF_CACHE_KEY: Required encryption key for secure transaction caching

Usage

# Sync all accounts (automatic date range)
cargo run -p banks2ff

# Preview changes without saving
cargo run -p banks2ff -- --dry-run

# Sync specific date range
cargo run -p banks2ff -- --start 2023-01-01 --end 2023-01-31

📋 What It Does

Banks2FF automatically:

Connects to your bank accounts via GoCardless
Finds matching accounts in your Firefly III instance
Downloads new transactions since your last sync
Adds them to Firefly III (avoiding duplicates)
Handles errors gracefully - keeps working even if some accounts have issues

🔐 Secure Transaction Caching

Banks2FF automatically caches your transaction data to make future syncs much faster:

Faster Syncs: Reuses previously downloaded data instead of re-fetching from the bank
API Efficiency: Dramatically reduces the number of calls made to GoCardless
Secure Storage: Your financial data is safely encrypted on your local machine
Automatic Management: The cache works transparently in the background

The cache requires BANKS2FF_CACHE_KEY to be set in your .env file for secure encryption (see env.example for key generation instructions).

🔧 Troubleshooting

Account not syncing? Check that the IBAN matches between GoCardless and Firefly III
Missing transactions? The tool syncs from the last transaction date forward
Rate limited? The tool automatically handles API limits and retries appropriately

For technical details, see docs/architecture.md

2.8 KiB Raw Blame History