Skip to content

Latest commit

 

History

History
265 lines (225 loc) · 9.03 KB

README.md

File metadata and controls

265 lines (225 loc) · 9.03 KB
Raw

Housematee Telegram Bot

Housematee is a Telegram bot designed to make your life with housemates easier and more organized. It allows you to manage home bills, set reminders for housework, and more, all within the convenience of Telegram.

Commands Housework Split bill
Commands Housework Split bill

Features

  • Bill Sharing: Easily split and manage home bills among your housemates.
  • Housework Reminders: Set reminders for housework tasks and keep your living space clean and organized.
  • Customization: Customize Housematee to suit your preferences.
  • Feedback: Share your feedback and suggestions with us to improve Housematee.

Installation

  1. Clone the repository:
git clone https://github.com/your-username/housematee-tgbot.git

Usage

  • Start a chat with Housematee bot on Telegram.
  • Use the available commands to manage bills, set reminders, and more.
  • Supported commands:
    • /splitbill - Easily split expenses with your housemates and keep track of who owes what.
    • /splitbill_add - Add a new expenses quickly and easily.
    • /housework - Organize and delegate house chores among housemates with reminders and schedules.
    • /hello - A greeting command to initiate interaction with the bot.
    • /gsheets - Manage and interact with your Google Sheets data directly from the bot.
    • /settings - Adjust bot settings, such as language, notification preferences, and more.
    • /feedback - Provide feedback about the bot or report issues for continuous improvement.
    • /help - Get a list of available commands and learn how to use the bot effectively.
  • The sample spreadsheet: here

Project structure

housematee-tgbot/
│
├── config/
│   ├── config.go
│   └── config.sample.json
│
├── commands/
│   ├── splitbill/
│   │   ├── splitbill.go
│   ├── housework/
│   │   ├── housework.go
│   ├── settings/
│   │   ├── settings.go
│   └── start.go
│
├── handlers/
│   ├── splitbill_handler.go
│   ├── housework_handler.go
│   ├── settings_handler.go
│   └── start_handler.go
│
├── models/
│   ├── bill/
│   │   ├── bill.go
│   │   └── bill_helper.go
│   ├── housework/
│   │   ├── housework.go
│   │   └── housework_helper.go
│   └── user.go
│
├── services/
│   ├── gsheets/
│   │   ├── gsheets.go
│   │   └── gsheets_helper.go
│   └── utilities/
│       └── utilities.go
│
├── cmd/
│   └── main.go
│
└── README.md

Explanation:

  1. commands/:

    • This directory now has sub-directories for each major feature like splitbill, housework, etc. Each sub-directory contains the main go file and a _helper.go file for helper functions related to that command.

  2. models/:

    • Similar to commands/, it now has sub-directories for each major data model like bill and housework. Each sub-directory contains the main go file and a _helper.go file for helper functions.

  3. services/:

    • This is a new directory aimed at hosting services that can be used across the application. For example, Google Sheets API logic can go under gsheets/.

  4. utilities/:

    • This sub-directory under services/ can contain utility functions that can be used throughout the application.

TODO List

Telegram chatbot

  • Configure supported commands: /hello, gsheets, /splitbill, /housework, /settings, /feedback, /help, ...
  • Add bot into group
  • Configure API token

Google sheets

  • Configure Google Sheets API
  • Configure Google Sheets credentials

Requirements

Handle all commands when received

  • reply to user if command is supported
  • reply to user if command is not supported

Command: /hello handler

  • Greet user

Command: /splitbill handler

  • show the list of buttons for bill management: add, view, update, delete, report
    • handle add button:
      • user input: each on a new line: name, amount, date, payer 
        [expense name]: default: name - current date
[amount]: support parse "k" -> thousand, "m" -> million
[date]: default: current date
[payer]: default: current user
      • add new record to Google Sheets
      • reply to user: 
            Status: <status>
    --- <show data as a row of table> ---
    ID: <id> 
    Expense name: <name>
    Amount: <amount>
    Date: <date>
    Payer: <payer>
    • handle view button:
      • show last 5 records as table 
              | ID | Expense name | Amount | Date | Payer |
      |:---|:-------------|:-------|:-----|:------|
      | 1  | ...          | ...    | ...  | ...   |
      | 2  | ...          | ...    | ...  | ...   |
      • show buttons: next, previous, back (optional)
    • handle report button:
      • show a report as table 
          |                               | Amount    | ***        |
  |:------------------------------|:----------|:-----------|
  | living expenses               | 5.000.000 | 2.500.000  |
  | person1 paid                  | 1.000.000 | 1.500.000  |
  | person2 paid                  | 4.000.000 | -1.500.000 |
  | rent                          | 4.500.000 | 2.250.000  |
  | total                         | 9.500.000 | 4.750.000  |
  | gap= (total)/2-[person2 paid] | 3.250.000 |            |

Command: /housework handler

  • Show the list of buttons for housework management: list, add, update, delete
    • handle list button:
      • show the list of housework tasks as table 
          | ID | Task name | Frequency | Last done | Next due | Next assignee |
  |:---|:----------|:----------|:----------|:---------|:--------------|
  | 1  | ...       | ...       | ...       | ...      |...            |
  | 2  | ...       | ...       | ...       | ...      |...            |
      • show buttons: each task as a button, back (optional)
      • handle task selected button
        • show task details 
              ID: <id> 
    Task name: <name>
    Frequency: <frequency>
    Last done: <last done>
    Next due: <next due>
    Next assignee: <next assignee>
      • show buttons: mark as done, remind housemates, back (optional)
    • handle add button:
      • user input: each on a new line: name, frequency, last done 
        [task name]: default: name - current date
[frequency]: default: 1 week
[next due]: default: current date
[next assignee]: default: current user
      • add new record to Google Sheets
      • reply to user: 
            Status: <status>
    --- <show data as a row of table> ---
    ID: <id> 
    Task name: <name>
    Frequency: <frequency>
    Last done: <last done>
    Next due: <next due>
    Next assignee: <next assignee>

Command: /sgheets handler

  • show buttons: list, create, select main sheet, back (optional)
  • handle list button:
    • show the list of sheets as table 
        | ID | Sheet name | Sheet ID |
  |:---|:-----------|:---------|
  | 1  | ...        | ...      |
  | 2  | ...        | ...      |
    • show buttons: select main sheet, back (optional)
  • handle create button:
    • create a new sheet with name: Housematee - <current month>/<current year>
    • add new record to Google Sheets
    • reply to user: 
          Status: <status>
    --- <show data as a row of table> ---
    ID: <id> 
    Sheet name: <name>
    Sheet ID: <sheet id>
  • handle select main sheet button:

Command: /help handler

  • show the list of buttons for help: /hello, gsheets, /splitbill, /housework, /settings, /feedback, /help, ...

Contributing

Contributions to this project are welcome! Feel free to open issues, submit pull requests, or provide feedback.

License

This project is licensed under the MIT License.