https://github.com/joshjohanning/hsa-expense-analyzer
🩺 🧾 📊 A simple JavaScript utility to tally up and chart HSA expenses by year based on a directory of receipts
https://github.com/joshjohanning/hsa-expense-analyzer
analyzer chartscii hsa javascript node personal-finance
Last synced: 3 months ago
JSON representation
🩺 🧾 📊 A simple JavaScript utility to tally up and chart HSA expenses by year based on a directory of receipts
- Host: GitHub
- URL: https://github.com/joshjohanning/hsa-expense-analyzer
- Owner: joshjohanning
- License: mit
- Created: 2024-05-29T03:14:19.000Z (over 1 year ago)
- Default Branch: main
- Last Pushed: 2025-06-02T22:59:23.000Z (4 months ago)
- Last Synced: 2025-07-06T21:43:30.294Z (3 months ago)
- Topics: analyzer, chartscii, hsa, javascript, node, personal-finance
- Language: JavaScript
- Homepage:
- Size: 46.9 KB
- Stars: 5
- Watchers: 1
- Forks: 0
- Open Issues: 0
-
Metadata Files:
- Readme: README.md
- License: LICENSE
Awesome Lists containing this project
README
# hsa-expense-analyzer
🩺 🧾 📊 Analyzes HSA expense totals by year from a folder of receipts.
## File Structure
Expects receipts to be in single folder with the following naming convention:
- Expenses:
` - - $.pdf|png|jpg|whatever`
- Reimbursed expenses:
` - - $.reimbursed.pdf|png|jpg|whatever`
> [!TIP]
> When you receive a reimbursement from your HSA provider, rename the receipt to include `.reimbursed.` before the extension. This will help track which expenses have been reimbursed and which expenses can still be submitted.
Example file structure:
```text
/
├── 2021-01-01 - doctor - $45.00.pdf # Expense
├── 2021-02-15 - pharmacy - $30.00.reimbursed.pdf # Reimbursed expense
├── 2022-02-01 - doctor - $50.00.reimbursed.pdf # Reimbursed expense
├── 2022-03-15 - dentist - $150.00.png # Expense
├── 2022-11-01 - glasses - $50.00.reimbursed.jpg # Reimbursed expense
├── 2023-05-01 - doctor - $45.00.pdf # Expense
├── 2023-06-01 - doctor - $55.00.reimbursed.pdf # Reimbursed expense
├── 2024-07-15 - doctor - $50.00.pdf # Expense
└── 2025-01-15 - doctor - $125.00.pdf # Expense
```
> [!NOTE]
>
> - Any file extension for receipts is fine; only the date and $ amount are used
> - The script detects reimbursements by looking for `.reimbursed.` anywhere in the filename.
## Running
```bash
npm install
npm run start -- --dirPath="/path/to/receipts"
```
## Example Output
```text
2021:
expenses: $75.00
reimbursements: $30.00
receipts: 2
2022:
expenses: $250.00
reimbursements: $100.00
receipts: 3
2023:
expenses: $100.00
reimbursements: $55.00
receipts: 2
2024:
expenses: $50.00
reimbursements: $0.00
receipts: 1
2025:
expenses: $125.00
reimbursements: $0.00
receipts: 1
Expenses by year
2021 ╢██████░░░░░░░░░░░░░░ $75.00
2022 ╢████████████████████ $250.00
2023 ╢████████░░░░░░░░░░░░ $100.00
2024 ╢████░░░░░░░░░░░░░░░░ $50.00
2025 ╢██████████░░░░░░░░░░ $125.00
╚════════════════════
Reimbursements by year
2021 ╢██████░░░░░░░░░░░░░░ $30.00
2022 ╢████████████████████ $100.00
2023 ╢███████████░░░░░░░░░ $55.00
2024 ╢░░░░░░░░░░░░░░░░░░░░ $0.00
2025 ╢░░░░░░░░░░░░░░░░░░░░ $0.00
╚════════════════════
Comparison by year:
2021 Expenses ╢██████░░░░░░░░░░░░░░ $75.00
2021 Reimbursements ╢██░░░░░░░░░░░░░░░░░░ $30.00
2022 Expenses ╢████████████████████ $250.00
2022 Reimbursements ╢████████░░░░░░░░░░░░ $100.00
2023 Expenses ╢████████░░░░░░░░░░░░ $100.00
2023 Reimbursements ╢████░░░░░░░░░░░░░░░░ $55.00
2024 Expenses ╢████░░░░░░░░░░░░░░░░ $50.00
2024 Reimbursements ╢░░░░░░░░░░░░░░░░░░░░ $0.00
2025 Expenses ╢██████████░░░░░░░░░░ $125.00
2025 Reimbursements ╢░░░░░░░░░░░░░░░░░░░░ $0.00
╚════════════════════
```