HSA Reimbursement CLI

HSA Reimbursement CLI is a command-line tool designed to help users manage healthcare receipts of Health Savings Account. The app enables tracking reimbursements efficiently. It allows users to analyze receipts, request reimbursements, back up data, restore from backups, and generate reports, all through an intuitive command-line interface.

All transactions are stored in a local SQLite database.

---

Features

• Receipt Management:
  • Scan directories for healthcare receipts with automatic parsing of file metadata.
  • Validate receipt file naming conventions.
• Reimbursement Tracking:
  • Request optimal reimbursement amounts based on available receipts.
  • Track reimbursed and remaining amounts.
• Backup and Restore:
  • Backup reimbursement data to JSON files.
  • Restore data from backups.
• Reporting:
  • Generate detailed reimbursement reports.
  • Export reports to CSV or JSON formats.
• User-Friendly Commands:
  • Easy-to-use commands with a consistent interface.
  • Version tracking for updates and compatibility.

---

Table of Contents

• Installation
• Usage
• Commands
• File Naming Convention
• Development Notes
• Local Testing
• Releasing to Pypi
• License

---

Installation

1. Clone the repository:

   git clone https://github.com/radian21/hsa_reimburse.git
   cd hsa_reimburse

2. Install the package locally:

   pip install .

3. Verify installation:

   hsa --version

---

Assumptions

This app assumes that the user is already saving their medical expense receipts. The app supports receipt files with any file extension because the app only parses the file names, not the file contents.

Filenames are assumed to meet the following condition:

YYYYMMDD_#.##_anyDescription

• YYYYMMDD is the date the receipt occurred on.
• #.## is a decimal number representing the value of the receipt in a currency.
• anyDescription is an optional string that can be included as desired.

Each of these parts are expected to be delimited by the _ (underscore) character. By using the metadata from this format, the app can track reimbursement amounts and correlate files to those amounts.

---

Usage

Run the hsa command with a subcommand:

hsa <command> [options]

Examples:

• Scan receipts in a directory:

  hsa init --path "C:\Receipts"

  The default path to the receipts will be used if no path is provided. Run hsa config to see file paths.

• Request a reimbursement:

  hsa request 1000

• Generate a summary:

  hsa summary

• Generate a report for tracability:

  hsa report

  Export a report to json:

  hsa report --export json
  

  Export a report to csv:

  hsa report --export csv
  

---

Commands

init

Scan a directory for receipts and add them to the database creating the database if necessary. It is safe to run this repeatedly as the database will not get re-created if it already exists and historical transactions will be preserved.

hsa init <path>

Example:

`hsa init --path "C:\HSA Receipts"`

• Options:
  • <path>: Path to the directory containing receipt files.

---

request

Request a reimbursement for a specific amount. The tool will select optimal receipts that sum up to or just below the requested amount.

hsa request <amount>

• Options:
  • <amount>: The reimbursement amount requested.

---

reset

Reset all reimbursement transactions after creating a backup. This does NOT rescan the receipts source directory. Run hsa init to rescan receipt files.

hsa reset

• Prompts for confirmation before proceeding.
• Saves a JSON backup of all reimbursement transactions before resetting the database. This backup is stored in ~/Documents/hsa-reimburse/backups and can be used to restore the database as desired.

---

restore

Restore reimbursement data from a backup file.

hsa restore <backup_file>

• Options:
  • <backup_file>: Path to the JSON backup file.

The default backup location is ~/Documents/hsa-reimburse/backups

---

summary

Show a summary of total reimbursed and available amounts.

hsa summary

---

config

Display current application configuration. The hsa_config.json file is stored in the program directory.

hsa config

---

report

Generate a detailed report of all reimbursements.

hsa report [--export <format>]

• Options:
  • --export <format>: Export report to csv or json.

---

Exported report files are saved to: ~/Documents/hsa-reimburse/exports

check-invalid

Check for receipt files that do not match the expected naming convention.

hsa check-invalid [--path <path>]

• Options:
  • --path <path>: Directory to check. Defaults to the receipts directory.

---

File Naming Convention

Receipt files must follow this format:

YYYYMMDD_DollarAmount_OptionalNote.extension

• YYYYMMDD: Date of the receipt.
• DollarAmount: Reimbursable amount in decimal format.
• OptionalNote: Additional details (optional).
• Supported Extensions:
  • .pdf
  • .jpg
  • .png
  • All other ignored

Valid Examples:

• 20240101_150.00_PrescriptionReceipt.pdf
• 20240215_200.50.png
• 20240305_1056_CVS.jpg

---

Development Notes

Global Variables

• Database File: hsa_reimburse.db
• Backup Directory: ~/Documents/.hsa_reimburse/backups
• Export Directory: ~/Documents/.hsa_reimburse/exports
• Receipts Directory: Configurable via RECEIPTS_DIR.

Key Python Libraries

• sqlite3: Database for storing receipt and reimbursement data.
• argparse: Command-line argument parsing.
• json: Data serialization for backups and exports.
• csv: Exporting data to CSV format.
• os: File and path handling.

Code Structure

• Commands are implemented as separate functions for modularity.
• SQL queries are used for database operations.
• Errors are handled gracefully with informative messages.

---

Local Testing

Uninstall, Rebuild, and Reinstall Locally

To test changes to the project locally, follow these steps to uninstall the current version, rebuild the package, and reinstall the updated version.

1. Uninstall the Existing Package

Before installing a new version, uninstall the previous version to avoid conflicts.

pip uninstall hsa-reimburse -y

Verify that the package has been removed by running:

pip list | grep hsa-reimburse  # On Linux/MacOS
pip list | findstr hsa-reimburse  # On Windows

2. Clean Previous Build Files

Remove any previously generated build artifacts to ensure a clean build.

Linux/MacOS:

rm -rf dist/ build/ *.egg-info

Windows PowerShell:

Remove-Item -Recurse -Force dist, build, *.egg-info

3. Rebuild the Package

Rebuild the package using the build module:

python -m build

Upon successful build, check the dist/ folder for files like:

dist/
  hsa_reimburse-0.1.0-py3-none-any.whl
  hsa_reimburse-0.1.0.tar.gz

4. Reinstall the Package Locally

Install the newly built package using pip:

pip install dist/hsa_reimburse-0.1.0-py3-none-any.whl

5. Verify Installation

Check if the package was installed correctly:

hsa --version

Expected output:

hsa 0.2.0

---

Releasing to Pypi

Incrementing the Version Number and Preparing for a New Release

Before publishing a new version to PyPI, you need to update the version number across all relevant files.

1. Update the Version Number

Update the following files:

src/hsa_reimburse_package_radian21/__init__.py

__version__ = "0.2.0"  # Update to the new version

setup.py (if not dynamically fetching version)

setup(
    name="hsa-reimburse",
    version="0.2.0",
    packages=find_packages(where="src"),
)

pyproject.toml

[project]
name = "hsa-reimburse"
version = "0.2.0"

README.md (if version is mentioned) Update any references to the version number:

# HSA Reimburse CLI - Version 0.2.0

2. Commit the Changes

After updating the version, commit the changes:

git add .
git commit -m "Bump version to 0.2.0"
git push origin main

3. Build the New Release

Run the build process to package the updated version:

python -m build

Confirm that the new version files are in the dist/ directory.

4. Upload to PyPI

Ensure you have the twine tool installed:

pip install twine

Upload the new package to PyPI:

twine upload dist/*

When prompted, enter your PyPI username and password.

5. Verify on PyPI

After successful upload, verify that the new version is available on PyPI.

6. Install the Package from PyPI

To ensure the new version works correctly, install it from PyPI:

pip install hsa-reimburse --upgrade

Verify the installation:

hsa --version

7. Prepare for the Next Development Cycle

Once the new version is published, increment the version number for development purposes (e.g., 0.3.0-dev).

Update init.py with a development version:

__version__ = "0.3.0-dev"

Commit the change:

git commit -am "Prepare for next development cycle 0.3.0-dev"
git push origin main

8. Automate Version Bumping (Optional)

You can use tools like bumpver to automate versioning:

pip install bumpver
bumpver update --minor  # Increment minor version

---

License

This project is licensed under the MIT License.

---