Jacob Kiers
68dafe9225
- 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
72 lines
2.8 KiB
Markdown
72 lines
2.8 KiB
Markdown
# 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
|
|
1. Copy environment template: `cp env.example .env`
|
|
2. 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
|
|
```bash
|
|
# 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:
|
|
1. Connects to your bank accounts via GoCardless
|
|
2. Finds matching accounts in your Firefly III instance
|
|
3. Downloads new transactions since your last sync
|
|
4. Adds them to Firefly III (avoiding duplicates)
|
|
5. 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](docs/architecture.md)*
|