Skip to content

README.md

Latest commit

 

History

History
141 lines (105 loc) · 3.54 KB

README.md

File metadata and controls

141 lines (105 loc) · 3.54 KB
Raw

Telegram Expense Tracker

A personal finance application that provides a CLI-like interface through Telegram for recording and managing expenses with automatic Google Sheets synchronization.

Features

  • 💬 Record expenses through Telegram commands
  • 📊 Automatic synchronization to Google Sheets
  • 🏷️ Custom category management with inline keyboard selection
  • 💾 Local persistence with sync retry logic
  • 🔒 Single-user authorization
  • 📱 Quick expense entry without leaving Telegram

Project Structure

telegram-expense-tracker/
├── src/                    # Source code
│   ├── models.py          # Data models (Expense, Category, UserConfig)
│   ├── storage.py         # Local storage implementation
│   ├── core.py            # Business logic (ExpenseTrackerCore)
│   ├── sync.py            # Google Sheets sync service
│   └── bot.py             # Telegram bot handler
├── tests/
│   ├── unit/              # Unit tests
│   ├── property/          # Property-based tests
│   └── integration/       # Integration tests
├── requirements.txt       # Python dependencies
├── .env.example          # Environment variables template
└── main.py               # Application entry point

Setup Instructions

1. Create Virtual Environment

# Create virtual environment
python -m venv venv

# Activate virtual environment
# On Windows:
venv\Scripts\activate
# On macOS/Linux:
source venv/bin/activate

2. Install Dependencies

pip install -r requirements.txt

3. Configure Environment

# Copy the example environment file
cp .env.example .env

# Edit .env and add your configuration:
# - TELEGRAM_BOT_TOKEN: Get from @BotFather on Telegram
# - GOOGLE_CREDENTIALS_PATH: Path to your Google service account JSON
# - AUTHORIZED_USER_ID: Your Telegram user ID

4. Set Up Google Sheets API

  1. Go to Google Cloud Console
  2. Create a new project or select existing one
  3. Enable Google Sheets API
  4. Create a service account and download credentials JSON
  5. Save credentials as credentials.json in project root
  6. Share your Google Sheet with the service account email

5. Run the Bot

python main.py

Usage

Available Commands

  • /expense <amount> <description> [category] or /e - Add new expense
  • /addcat <category_name> or /ac - Add new category
  • /categories or /cats - List all categories
  • /delcat <category_name> or /dc - Delete category
  • /list - Show recent expenses (last 10)
  • /list <YYYY-MM-DD> - Show expenses for specific date
  • /delete <expense_id> or /del - Delete expense
  • /config <sheet_link> - Configure Google Sheet
  • /help or /start - Show help message

Examples

/e 25.50 Lunch Food
/expense 100 Groceries
/ac Transportation
/list
/list 2024-01-15
/del expense-id-123

Development

Running Tests

# Run all tests
pytest

# Run unit tests only
pytest tests/unit/

# Run property-based tests only
pytest tests/property/

# Run with coverage
pytest --cov=src --cov-report=html

Running Property-Based Tests

Property-based tests use Hypothesis and run 100 iterations by default:

pytest tests/property/ -v

Requirements

  • Python 3.8+
  • Telegram Bot Token
  • Google Sheets API credentials
  • Active internet connection for sync

License

MIT License