207 lines
6.8 KiB
Markdown
207 lines
6.8 KiB
Markdown
# YNAB Amazon Helper
|
|
|
|
Automatically link your YNAB transactions to Amazon orders and categorize them using AI.
|
|
|
|
## Features
|
|
|
|
- **Unapproved Transaction Workflow**: Automatically fetch and match only unapproved YNAB transactions (no date range needed!)
|
|
- **Automated Matching**: Matches YNAB transactions with Amazon orders based on amount and date proximity
|
|
- **Web Scraping**: Scrapes your Amazon order history using Puppeteer (no Amazon API keys required)
|
|
- **AI-Powered Categorization**: Uses OpenAI to suggest appropriate YNAB categories based on product descriptions
|
|
- **Visual Review Interface**: Web UI to review, approve, and modify matches before applying
|
|
- **Batch Updates**: Apply approved matches to YNAB with one click, automatically marking them as approved
|
|
|
|
## Prerequisites
|
|
|
|
- [Bun](https://bun.sh) runtime installed
|
|
- YNAB account with API access
|
|
- Amazon account
|
|
- OpenAI API key
|
|
|
|
## Setup
|
|
|
|
### 1. Install Dependencies
|
|
|
|
```bash
|
|
bun install
|
|
```
|
|
|
|
### 2. Configure Environment Variables
|
|
|
|
Copy the example environment file:
|
|
|
|
```bash
|
|
cp .env.example .env
|
|
```
|
|
|
|
Edit `.env` and fill in your credentials:
|
|
|
|
```env
|
|
# YNAB API Configuration
|
|
YNAB_API_TOKEN=your_ynab_personal_access_token
|
|
YNAB_BUDGET_ID=your_budget_id
|
|
|
|
# OpenAI API Configuration
|
|
OPENAI_API_KEY=your_openai_api_key
|
|
|
|
# Server Configuration
|
|
PORT=3000
|
|
NODE_ENV=development
|
|
```
|
|
|
|
**Note:** Amazon credentials are NOT required. You'll log in manually through the browser when scraping.
|
|
|
|
### 3. Get Your YNAB API Token
|
|
|
|
1. Go to [YNAB Account Settings](https://app.ynab.com/settings)
|
|
2. Navigate to "Developer Settings"
|
|
3. Click "New Token" and copy the personal access token
|
|
4. To find your Budget ID, you can use the YNAB API or check the URL when viewing your budget
|
|
|
|
### 4. Get Your OpenAI API Key
|
|
|
|
1. Go to [OpenAI API Keys](https://platform.openai.com/api-keys)
|
|
2. Create a new secret key
|
|
3. Copy the key (you won't be able to see it again)
|
|
|
|
## Usage
|
|
|
|
### Start the Server
|
|
|
|
```bash
|
|
bun --hot server.ts
|
|
```
|
|
|
|
The server will start at `http://localhost:3000`
|
|
|
|
### Using the Application
|
|
|
|
1. **Open the Web Interface**: Navigate to `http://localhost:3000` in your browser
|
|
|
|
2. **Choose Transaction Mode**:
|
|
- **Unapproved Transactions (Recommended)**: Automatically fetches all unapproved transactions from YNAB
|
|
- **Date Range**: Manually specify start and end dates for transactions to match
|
|
|
|
3. **Fetch Matches**: Click "Fetch & Match Transactions"
|
|
- The app will fetch YNAB transactions (unapproved or by date range)
|
|
- Scrape Amazon orders from the relevant time period (opens a browser window)
|
|
- Match transactions using date/amount proximity
|
|
- Suggest categories using AI
|
|
|
|
4. **Review Matches**:
|
|
- Each match shows the YNAB transaction and corresponding Amazon order
|
|
- Confidence scores help identify quality matches
|
|
- Review AI-suggested categories and modify if needed
|
|
- Approve or reject each match
|
|
|
|
5. **Apply Changes**: Click "Apply Approved Matches" to update YNAB
|
|
- Amazon order links will be added to transaction memos
|
|
- Categories will be updated if changed
|
|
- Transactions will be marked as approved
|
|
|
|
## How It Works
|
|
|
|
### Transaction Matching Algorithm
|
|
|
|
The matcher uses a scoring system based on:
|
|
- **Amount Matching (50% weight)**: Compares transaction amount with order total
|
|
- **Date Proximity (30% weight)**: Considers orders within ±3 days of transaction
|
|
- **Payee Name (20% weight)**: Boosts score for Amazon-related payees
|
|
|
|
Default tolerances:
|
|
- Date: ±3 days
|
|
- Amount: ±$0.50
|
|
|
|
### AI Categorization
|
|
|
|
OpenAI analyzes product descriptions and suggests categories from your YNAB budget:
|
|
- Uses GPT-4o-mini for cost efficiency
|
|
- Considers all items in multi-item orders
|
|
- Maps products to your existing category structure
|
|
|
|
### Amazon Scraping
|
|
|
|
The scraper:
|
|
- Uses Puppeteer to automate browser interactions
|
|
- Navigates to Amazon transactions page (`https://www.amazon.com/cpe/yourpayments/transactions`)
|
|
- Automatically logs into your Amazon account if needed
|
|
- Extracts transaction details, dates, and amounts
|
|
- Caches session data to avoid repeated logins
|
|
- Takes debug screenshots for troubleshooting
|
|
|
|
**Important Notes**:
|
|
- A browser window will open and navigate to the Amazon transactions page
|
|
- **You'll need to log in manually** - the app waits 45 seconds for you to complete login
|
|
- Once logged in, the session is cached in `.puppeteer_cache/` for future runs
|
|
- If you're already logged in (from a previous session), scraping will start automatically
|
|
- Debug screenshots are saved to `debug-transactions-page.png` for troubleshooting
|
|
|
|
## Project Structure
|
|
|
|
```
|
|
├── server.ts # Bun.serve backend API
|
|
├── index.html # Main HTML page
|
|
├── frontend.tsx # Frontend TypeScript/React
|
|
├── types.ts # TypeScript type definitions
|
|
├── amazon-scraper.ts # Amazon order scraping logic
|
|
├── ynab-client.ts # YNAB API integration
|
|
├── matcher.ts # Transaction matching algorithm
|
|
├── category-suggester.ts # OpenAI category suggestions
|
|
└── .env # Environment configuration (not in git)
|
|
```
|
|
|
|
## API Endpoints
|
|
|
|
- `GET /` - Serve web interface
|
|
- `POST /api/fetch-matches` - Fetch and match transactions
|
|
- `GET /api/matches/:sessionId` - Get matches for a session
|
|
- `PATCH /api/matches/:sessionId/:matchIndex` - Update match status
|
|
- `POST /api/approve-matches/:sessionId` - Apply approved matches to YNAB
|
|
- `GET /api/categories` - Get YNAB categories
|
|
|
|
## Troubleshooting
|
|
|
|
### Amazon Login Issues
|
|
|
|
- **2FA Required**: Complete 2FA manually when the browser opens
|
|
- **CAPTCHA**: Solve any CAPTCHA challenges that appear
|
|
- **Session Expired**: Delete `.puppeteer_cache/` and try again
|
|
|
|
### YNAB API Issues
|
|
|
|
- **Invalid Token**: Regenerate your personal access token
|
|
- **Budget Not Found**: Verify your budget ID is correct
|
|
- **Rate Limits**: The app respects YNAB rate limits automatically
|
|
|
|
### OpenAI Issues
|
|
|
|
- **Rate Limits**: Categories are suggested in batches with delays
|
|
- **Cost Concerns**: Uses gpt-4o-mini (~$0.15 per 1M tokens)
|
|
- **Poor Suggestions**: Review and manually select correct categories
|
|
|
|
## Security Considerations
|
|
|
|
- Never commit `.env` file to version control
|
|
- Amazon credentials are stored locally only
|
|
- YNAB token has read/write access to your budget
|
|
- Puppeteer cache may contain session cookies
|
|
|
|
## Future Enhancements
|
|
|
|
- [ ] Support for multiple budgets
|
|
- [ ] Database for persistent match storage
|
|
- [ ] Manual order entry (for non-Amazon purchases)
|
|
- [ ] Improved scraping with stealth plugins
|
|
- [ ] Export/import match history
|
|
- [ ] Category learning from past matches
|
|
|
|
## License
|
|
|
|
MIT
|
|
|
|
## Built With
|
|
|
|
- [Bun](https://bun.sh) - Fast JavaScript runtime
|
|
- [Puppeteer](https://pptr.dev) - Headless browser automation
|
|
- [YNAB API](https://api.ynab.com) - Budget data integration
|
|
- [OpenAI API](https://platform.openai.com) - AI categorization
|