first commit

QUICKSTART.md

@@ -0,0 +1,144 @@
+# 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
+