Bill Reminder 🔔

A Python CLI app that checks your unpaid bills and sends Telegram notifications for bills due within the next 4 days. Built to replace an n8n workflow using clean architecture principles.

Features

• Reads bills from a CSV file
• Filters unpaid bills due within a configurable number of days
• Sends Telegram notifications via the Telegram Bot API
• Clean architecture: models, repository pattern, service layer

Project Structure

bill-reminder/
├── app/
│   ├── models/
│   │   ├── bill.py
│   │   └── bill_type.py
│   ├── repositories/
│   │   └── bill_repository.py
│   └── services/
│       └── telegram_notification_service.py
├── data/
│   └── bills.csv
├── tests/
├── main.py
├── .env
├── requirements.txt
└── README.md

Setup

1. Clone the repository

   git clone https://github.com/your-username/bill-reminder.git
   cd bill-reminder

2. Create a virtual environment and install dependencies

   python -m venv venv
   source venv/bin/activate  # On Windows: venv\Scripts\activate
   pip install -r requirements.txt

3. Configure environment variables

   Create a .env file at the root:

   TELEGRAM_BOT_TOKEN=your_bot_token_here
   TELEGRAM_CHAT_ID=your_chat_id_here
   

4. Prepare your CSV file

   Create data/bills.csv with the following format:

   id,title,description,amount,due_date,is_payed,is_notification_enabled,bill_type
   1,Internet,Monthly internet bill,50.00,28/02/2026,false,true,subscription
   

Usage

python main.py

CSV Format

Column	Type	Format	Example
id	int	—	1
title	str	—	Internet
description	str	—	Monthly bill
amount	float	—	50.00
due_date	date	dd/mm/yyyy	28/02/2026
is_payed	bool	true/false	false
is_notification_enabled	bool	true/false	true
bill_type	str	bill/subscription	subscription

Getting your Telegram Chat ID

1. Create a bot via @BotFather and get your token
2. Send a message to your bot
3. Visit https://api.telegram.org/bot<YOUR_TOKEN>/getUpdates
4. Copy the chat_id from the response

Tech Stack

• Python 3.10+
• requests — HTTP calls to Telegram API
• python-dotenv — environment variable management
• pytest — testing

License

MIT