AkahuSync/README.md

# AkahuSync
This is my attempt to use NZ's open banking, along with some web scraping, to try and make sense of my financial position over time  
My intention is to gather daily, weekly, and monthly snapshots of my networth, to the end that some visibilty will help steer me in the right direction  
I also have some enhancements planned, such as writing transactional data to Firefly, where I will categorize and report on purchases  


make sure to install playwright (pip install playwright), then run:
```
playwright install --with-deps
```
to get the correct drivers and dependencies for the host system

## Runtime flags
These env vars let you split Akahu vs Emoney runs (useful for separate k8s cron jobs):

- RUN_AKAHU (default true)
- RUN_EMONEY (default true)
- RUN_NORMALIZE (default true)
- RUN_FIREFLY (default false)

Example:
```
RUN_AKAHU=true RUN_EMONEY=false RUN_NORMALIZE=true python main.py
```

## Container notes
- The Docker image uses Playwright's Python base image.
- The Emoney scraper runs headless by default.

## Env vars
Required:
- AKAHU_API_TOKEN
- AKAHU_APP_ID
- DB_HOST
- DB_NAME
- DB_USER
- DB_PASSWORD
- SCRAPER_URL
- SCRAPER_USERNAME
- SCRAPER_PASSWORD
- FIREFLY_BASE_URL
- FIREFLY_API_TOKEN

Optional:
- EMONEY_USE_CACHE (true/false, default false)
- EMONEY_CACHE_PATH (default emoney_cache.json)
- RUN_AKAHU (default true)
- RUN_EMONEY (default true)
- RUN_NORMALIZE (default true)
- RUN_FIREFLY (default false)
- FIREFLY_CURRENCY_CODE (default NZD)
- FIREFLY_DEFAULT_ACCOUNT_TYPE (default asset)
- FIREFLY_LIABILITY_TYPE (default loan)
- FIREFLY_LIABILITY_DIRECTION (default debit)
- FIREFLY_LIABILITY_INTEREST_PERIOD (default yearly)
- FIREFLY_LIABILITY_INTEREST (default 0)
- FIREFLY_ASSET_ACCOUNT_ROLE (default defaultAsset)
- FIREFLY_ACCOUNT_TYPE_OVERRIDES (JSON mapping of account name/number to Firefly account type)
- FIREFLY_BALANCE_ACCOUNTS (comma-separated account names to adjust by balance)
- FIREFLY_ADJUSTMENT_ACCOUNT_NAME (default Balance Adjustment)
- FIREFLY_REVENUE_ACCOUNT_NAME (default Income)
- FIREFLY_ERROR_IF_DUPLICATE_HASH (default true)

## Build and test the Docker image
Build:
```
docker build -t akahusync:local .
```

Run (example, pass env vars):
```
docker run --rm \
	-e AKAHU_API_TOKEN=... \
	-e AKAHU_APP_ID=... \
	-e DB_HOST=... \
	-e DB_NAME=... \
	-e DB_USER=... \
	-e DB_PASSWORD=... \
	-e SCRAPER_URL=... \
	-e SCRAPER_USERNAME=... \
	-e SCRAPER_PASSWORD=... \
	-e RUN_AKAHU=true \
	-e RUN_EMONEY=false \
	-e RUN_NORMALIZE=true \
	akahusync:local
```

## Normalization gotchas
- Akahu org is derived from the connection name (BNZ/Sharesies), not the source name.
- Emoney transactions are hardcoded to vendor "Finance Now".
- Akahu descriptions with "INTERNET XFR" are rewritten to include the counterparty info and meta fields.