jjkiers/banks2ff
1
0
Fork 0
Code Issues Pull Requests Actions Packages Releases Activity

Implement encrypted transaction caching for GoCardless adapter

Browse Source 
- 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
This commit is contained in:
Jacob Kiers
2025-11-21 21:16:11 +01:00
parent 1dd251c379
commit c67378ff25
11 changed files with 1318 additions and 54 deletions
Download Patch File Download Diff File Expand all files Collapse all files

21
README.md
View File

@@ -5,6 +5,7 @@ A robust command-line tool to synchronize bank transactions from GoCardless (for
## ✨ 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
@@ -21,10 +22,11 @@ A robust command-line tool to synchronize bank transactions from GoCardless (for
### 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
- `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
@@ -47,6 +49,17 @@ Banks2FF automatically:
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