kushdab/mpesa-ledger-cli-20260624

A command-line utility for Kenyan small businesses to parse transaction statements and calculate net profits after tax and fees. # mpesa-ledger-cli A command-line utility for Kenyan small businesses to parse M-Pesa transaction statements and calculate net profits after tax and fees. ## Description `mpesa-ledger-cli` helps small and medium business owners in Kenya quickly understand their true net earnings by accounting for M-Pesa transaction fees, VAT (16%), and Excise Duty (20% on fees) applied to every financial transaction. ## Features - Parse CSV-format M-Pesa transaction exports - Automatically calculate M-Pesa transaction fees using official Safaricom fee tiers - Apply Kenyan VAT (16%) and Excise Duty (20%) on transaction fees - Compute gross and net profit per statement period - Display per-transaction breakdown with `--all` flag - Export full report to JSON for integration with other tools - Generate sample CSV for quick demo/testing ## Installation ```bash git clone github.com cd mpesa-ledger-cli pip install -r requirements.txt ``` No external dependencies are required — the tool uses Python's standard library only. ## Usage ### Basic usage ```bash python main.py transactions.csv ``` ### Show full transaction details ```bash python main.py transactions.csv --all ``` ### Export report to JSON ```bash python main.py transactions.csv --export report.json ``` ### Generate a sample CSV to get started ```bash python main.py --sample sample_transactions.csv python main.py sample_transactions.csv --all ``` ## CSV Format Your input CSV must include the following columns (case-insensitive): | Column | Description | Example | |---|---|---| | `date` | Transaction date | 2026-06-01 | | `description` | Short description | Sale - Customer A | | `amount` | Transaction amount in KES | 5000 | | `type` | Transaction type (see below) | credit | | `reference` | Optional transaction code | QJK123ABC | ### Supported Transaction Types | Type | Category | |---|---| | `credit`, `received`, `income`, `paybill_in`, `till_in` | Income | | `debit`, `sent …