Matrix Expense Tracking Bot

A Matrix bot for tracking personal expenses with Chinese language support. The bot allows users to record expenses in a simple format and provides statistical summaries.

Features

• 📝 Simple Expense Recording: Record expenses using format 项目 金额 分类 (item amount category)
• 📊 Statistics Export: View spending summaries by category with !导出
• 🗑️ Data Management: Clear all records with !清除
• 📌 Auto-pinned Instructions: Automatically pins usage instructions in the room
• 💾 Persistent Storage: Saves data in JSON files for persistence
• 🔐 Session Management: Handles Matrix authentication and session persistence

Commands

• Record Expense: 午餐 20 餐饮 (lunch 20 food)
• Export Statistics: !导出
• Clear All Data: !清除
• Update Instructions: !更新说明 (admin only)

Quick Start

Environment Setup

1. Clone the repository:

git clone <repository-url>
cd matrix-bot

2. Create a virtual environment:

python3 -m venv .venv
source ./.venv/bin/activate  # On Windows: .venv\Scripts\activate

3. Install dependencies:

pip install -r requirements.txt

4. Create a .env file with your Matrix credentials:

MATRIX_HOMESERVER=https://matrix.org
MATRIX_USER_ID=@yourusername:matrix.org
MATRIX_PASSWORD=your_password
MATRIX_ROOM_ID=!roomid:matrix.org

5. Run the bot:

python bot.py

Docker Setup

Build and Run

docker build -t matrix-bot .
docker run --rm --env-file .env matrix-bot

Docker Compose

docker-compose up -d

Configuration

Create a .env file in the project root with the following variables:

MATRIX_HOMESERVER=https://your-matrix-server.org
MATRIX_USER_ID=@your-bot-username:your-matrix-server.org
MATRIX_PASSWORD=your_bot_password
MATRIX_ROOM_ID=!your-room-id:your-matrix-server.org

Data Storage

The bot creates and manages several JSON files:

• expenses.json: Stores all expense records
• session.json: Matrix session data for authentication persistence
• sync_token.json: Matrix sync token for message synchronization
• manual.json: Stores the pinned instruction message details

Dependencies

• matrix-nio[e2e]>=0.22.0: Matrix client library with end-to-end encryption support
• aiohttp>=3.8.1: Async HTTP client library
• python-dotenv>=1.0.0: Environment variable loading

Usage Example

1. Start the bot in your Matrix room
2. The bot will automatically pin usage instructions
3. Send messages like:
   • 咖啡 25 餐饮 (coffee 25 food)
   • 打车 15 出行 (taxi 15 transportation)
   • 电影票 45 娱乐 (movie ticket 45 entertainment)
4. Export statistics: !导出
5. Clear data when needed: !清除

Development

Project Structure

matrix-bot/
├── bot.py              # Main bot logic
├── requirements.txt    # Python dependencies
├── Dockerfile         # Docker configuration
├── docker-compose.yml # Docker Compose setup
├── .env.example       # Environment variables template
├── .gitignore         # Git ignore rules
└── README.md          # This file

Contributing

1. Fork the repository
2. Create a feature branch
3. Make your changes
4. Test thoroughly
5. Submit a pull request

License

This project is licensed under the MIT License - see the LICENSE file for details.

Support

If you encounter any issues or have questions, please open an issue on GitHub.