145 lines
3.6 KiB
Markdown
145 lines
3.6 KiB
Markdown
# Quick Start Guide
|
|
|
|
## Installation
|
|
|
|
1. **Dependencies already installed:**
|
|
- `ynab` (2.1.0) - YNAB API SDK
|
|
- `pyyaml` (6.0.3) - YAML parsing
|
|
|
|
2. **Virtual environment active** in `.venv/`
|
|
|
|
## Configuration
|
|
|
|
Update `ynab.yml` with your YNAB credentials:
|
|
|
|
```yaml
|
|
ynab:
|
|
- token: "your_actual_ynab_api_token"
|
|
plan_id: "your_budget_plan_id"
|
|
accounts:
|
|
- name: "Credit Card"
|
|
id: "account_uuid"
|
|
```
|
|
|
|
Get your credentials from: https://app.youneedabudget.com/settings/developer
|
|
|
|
## Quick Examples
|
|
|
|
### Extract Wells Fargo Transactions
|
|
|
|
```bash
|
|
# Display in console
|
|
python main.py --input posted.dat
|
|
|
|
# Save to file
|
|
python main.py --input posted.dat --output extracted.json
|
|
|
|
# Process and save transactions
|
|
python example_usage.py
|
|
```
|
|
|
|
**Output:** `processed_transactions.json` with 179 sample transactions
|
|
|
|
### Fetch YNAB Transactions
|
|
|
|
```bash
|
|
python ynab_example.py
|
|
```
|
|
|
|
**Output:** `ynab_transactions.json` with transactions from past 30 days
|
|
|
|
### Reconcile Both Sources
|
|
|
|
```bash
|
|
python reconcile.py
|
|
```
|
|
|
|
**Output:** `reconciliation_report.json` comparing both datasets
|
|
|
|
## Module Quick Reference
|
|
|
|
| Task | Module | Method |
|
|
|------|--------|--------|
|
|
| Extract WF payload | `wf_debit_extractor.py` | `WellsFargoPayloadExtractor().extract_from_file()` |
|
|
| Process WF transactions | `transaction_processor.py` | `TransactionProcessor().extract_transactions()` |
|
|
| Fetch YNAB transactions | `ynab_client.py` | `YNABClient().get_transactions_for_days()` |
|
|
| Reconcile both | `reconcile.py` | `reconcile_transactions()` |
|
|
|
|
## Common Code Patterns
|
|
|
|
### Get Wells Fargo Transactions
|
|
```python
|
|
from wf_debit_extractor import WellsFargoPayloadExtractor
|
|
from transaction_processor import TransactionProcessor
|
|
|
|
extractor = WellsFargoPayloadExtractor()
|
|
payloads = extractor.extract_from_file("posted.dat")
|
|
|
|
processor = TransactionProcessor()
|
|
transactions = processor.extract_transactions(payloads)
|
|
|
|
for txn in transactions:
|
|
print(f"{txn['id']}: ${txn['transaction_amount_cents']/100:.2f}")
|
|
```
|
|
|
|
### Get YNAB Transactions
|
|
```python
|
|
from ynab_client import YNABClient
|
|
|
|
client = YNABClient("ynab.yml")
|
|
transactions = client.get_transactions_for_days(days=30)
|
|
|
|
for txn in transactions:
|
|
print(f"{txn['date']}: {txn['payee_name']} ${txn['amount_milliCurrency']/1000:.2f}")
|
|
```
|
|
|
|
### Full Reconciliation
|
|
```python
|
|
from reconcile import reconcile_transactions
|
|
|
|
report = reconcile_transactions()
|
|
print(f"WF: {report['transaction_count_wf']} transactions")
|
|
print(f"YNAB: {report['transaction_count_ynab']} transactions")
|
|
```
|
|
|
|
## File Locations
|
|
|
|
- **Input:** `posted.dat` (Wells Fargo HAR export)
|
|
- **Config:** `ynab.yml` (YNAB credentials)
|
|
- **Output:**
|
|
- `extracted.json` - Raw WF payloads
|
|
- `processed_transactions.json` - Processed WF transactions
|
|
- `ynab_transactions.json` - YNAB transactions
|
|
- `reconciliation_report.json` - Comparison report
|
|
|
|
## Troubleshooting
|
|
|
|
**YNAB Authorization Error:**
|
|
- Verify token in `ynab.yml` is correct
|
|
- Check token hasn't expired
|
|
- Ensure token has budget access
|
|
|
|
**Wells Fargo Extraction Returns 0 Objects:**
|
|
- Verify `posted.dat` contains `/*WellFargoProprietary%...%WellFargoProprietary*/`
|
|
- Check file is valid JSON
|
|
|
|
**Import Errors:**
|
|
- Activate venv: `.venv\Scripts\Activate.ps1`
|
|
- Reinstall deps: `pip install ynab pyyaml`
|
|
|
|
## Documentation
|
|
|
|
See detailed docs in:
|
|
- `README.md` - Full project documentation
|
|
- `PROJECT_SUMMARY.md` - Module reference
|
|
- `YNAB_MODULE.md` - YNAB client details
|
|
- Module docstrings - Inline documentation
|
|
|
|
## Next Steps
|
|
|
|
1. Update `ynab.yml` with real credentials
|
|
2. Run `python example_usage.py` to test WF extraction
|
|
3. Run `python ynab_example.py` to test YNAB connection
|
|
4. Run `python reconcile.py` to generate comparison report
|
|
|