{"id":19610020,"url":"https://github.com/nikitoskey/alcounting_bot","last_synced_at":"2025-04-04T17:07:29.514Z","repository":{"id":226896090,"uuid":"769619573","full_name":"NikitosKey/alcounting_bot","owner":"NikitosKey","description":"Telegram bot for me and my friends, which helps us to order cocktails and other things at our parties.","archived":false,"fork":false,"pushed_at":"2025-01-24T02:21:10.000Z","size":2198,"stargazers_count":188,"open_issues_count":5,"forks_count":6,"subscribers_count":2,"default_branch":"main","last_synced_at":"2025-03-28T16:07:03.308Z","etag":null,"topics":["ptb","python","python-telegram-bot","telegram-bot","telegram-bot-api"],"latest_commit_sha":null,"homepage":"","language":"Python","has_issues":true,"has_wiki":null,"has_pages":null,"mirror_url":null,"source_name":null,"license":"mit","status":null,"scm":"git","pull_requests_enabled":true,"icon_url":"https://github.com/NikitosKey.png","metadata":{"files":{"readme":"README.md","changelog":null,"contributing":null,"funding":null,"license":"LICENSE","code_of_conduct":null,"threat_model":null,"audit":null,"citation":null,"codeowners":null,"security":null,"support":null,"governance":null,"roadmap":null,"authors":null,"dei":null,"publiccode":null,"codemeta":null}},"created_at":"2024-03-09T15:34:34.000Z","updated_at":"2025-03-22T04:25:21.000Z","dependencies_parsed_at":"2024-11-11T10:30:16.509Z","dependency_job_id":"7eab69e5-e6e1-4f3b-9618-a78a0bd8e097","html_url":"https://github.com/NikitosKey/alcounting_bot","commit_stats":null,"previous_names":["nikitoskey/alcounting_bot"],"tags_count":2,"template":false,"template_full_name":null,"repository_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/NikitosKey%2Falcounting_bot","tags_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/NikitosKey%2Falcounting_bot/tags","releases_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/NikitosKey%2Falcounting_bot/releases","manifests_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/NikitosKey%2Falcounting_bot/manifests","owner_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners/NikitosKey","download_url":"https://codeload.github.com/NikitosKey/alcounting_bot/tar.gz/refs/heads/main","host":{"name":"GitHub","url":"https://github.com","kind":"github","repositories_count":247217183,"owners_count":20903009,"icon_url":"https://github.com/github.png","version":null,"created_at":"2022-05-30T11:31:42.601Z","updated_at":"2022-07-04T15:15:14.044Z","host_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub","repositories_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories","repository_names_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repository_names","owners_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners"}},"keywords":["ptb","python","python-telegram-bot","telegram-bot","telegram-bot-api"],"created_at":"2024-11-11T10:26:27.246Z","updated_at":"2025-04-04T17:07:29.496Z","avatar_url":"https://github.com/NikitosKey.png","language":"Python","funding_links":[],"categories":[],"sub_categories":[],"readme":"[![code-quality](https://github.com/NikitosKey/alcounting_bot/actions/workflows/python-poetry-code-quality.yml/badge.svg)](https://github.com/NikitosKey/alcounting_bot/actions/workflows/python-poetry-code-quality.yml)\n\n# Alcounting Telegram Bot\n\nA bot designed to help manage parties and prevent organizers from going into the red.\n\n## Table of Contents\n\n- [Description](#description)\n- [Guide](#Guide)\n- [Documentation](#documentation)\n- [Contributing](#contributing)\n\n## Description\n\nThis bot is written in Python using the `python-telegram-bot` library.  \nIt offers a simple interface with buttons and a few commands.\nKey features include:\n- Ordering drinks, viewing the menu, and checking order statuses.\n- Role-based access levels: Administrator, Bartender, and Customer.\n- SQLite3 database integration.\n\n## Guide\n### How to install and run\n#### Step 1: Create a Telegram Bot and Get the Token from @BotFather\n\n1. Open the Telegram app and search for `@BotFather`.\n2. Start a chat with `@BotFather` by clicking the \"Start\" button.\n3. Use the command `/newbot` to create a new bot.\n4. Follow the instructions to choose a name and username for your bot.\n5. After successfully creating the bot, `@BotFather` will provide you with a token. This token is required to authenticate your bot and should be kept secure.\n\nExample of the token provided by `@BotFather`:\n```\n123456789:ABCdefGhIJKlmNoPQRstuVWXyz\n```\n\nSave this token as you will need it to configure your bot in the next steps.\n\n\u003e **Note:** The token is sensitive information and should not be shared publicly.\n#### Step 2: Set Up the Bot\nFirst, you need to get repository on your local machine. You can do it by cloning the repository or downloading the zip file.\n```shell\n# Clone the repository\n\n\n# Install Git from https://git-scm.com/downloads if you haven't already.\ngit clone git@github.com:NikitosKey/alcounting_bot.git\ncd alcounting_bot\n```\nAnd get a token from the `@BotFather` in Telegram.\n\nTODO: Add the instruction how to get the token.\n\n##### Local Installation Native Method\n\n```shell\n# Install Python 3.13 if you haven't already.\n# Visit https://www.python.org/downloads/ to download the latest version of Python.\n# Or use your package manager to install it:\n\n# Ubuntu\nsudo apt-get install python3.13 \n\n# macOS\n# Install Homebrew from https://brew.sh/ if you haven't already.\nbrew install python3.13\n\n# Windows\n# Install Chocolatey from https://chocolatey.org/ if you haven't already.\nchoco install python3.13\n\n# Install SQLite3 if you haven't already from https://www.sqlite.org/download.html or use your package manager:\n# Ubuntu\nsudo apt-get install sqlite3\n\n# macOS\nbrew install sqlite3\n\n# Windows\nchoco install sqlite3\n\n# Install Poetry\n# install pip if you haven't already from https://pip.pypa.io/en/stable/installation/.\npip install poetry\n# This is sufficient to install dependencies, but for contributions,\n# it's recommended to visit https://python-poetry.org/docs/ and follow their setup instructions.\n\n# Install dependencies using Poetry (recommended for contributors)\npoetry install\n\n# Install dependencies using pip (alternative to Poetry)\n# Create a virtual environment\npython3.13 -m venv venv\n# Activate the virtual environment\nsource venv/bin/activate\npip install -r requirements.txt\n\n# Create an environment variable BOT_TOKEN and set it to your bot's token.\nexport BOT_TOKEN=your_token\n\n# Run the bot\npoetry run python -m bot.__main__\n\n# For convenience, you can use screen or tmux to keep the bot running in the background:\n\n# Using screen\nscreen -S alcounting_bot\npoetry run python -m bot.__main__\n\n# Using tmux\ntmux new -s alcounting_bot\npoetry run python -m bot.__main__ \n```\n\nThat's it!  \nThe bot will now run in the background, processing user requests.  \nTo stop the bot, press `Ctrl+C`.\n\n\n##### Local Installation Docker Method\nFirstly, you need to create `.env` file. You can find example in `.env.example`.\n\n```shell\n# Install Docker and Docker Compose from https://docs.docker.com/get-docker/ and https://docs.docker.com/compose/install/ if you haven't already.\ndocker-compose up --build\n```\n\n\u003e To host the bot remotely instead of running it locally, you'll need to set up a hosting environment.\n\n### How to use \n#### Step 1: Start the Bot\n1. Open the Telegram app.\n2. Search for your bot by its username.\n3. Start a chat with the bot by clicking the \"Start\" button.\n\nAfter receiving `/start` bot creates a database and sends a welcome message and your automatically get the role of the \ncustomer.\n\nTo use all the features of the bot, you need to change your role to administrator. To do this your need to install the \nSQLite browser and change the role in the database.\n\n#### Step 2: Use the Bot\nThe bot supports the following commands:\n1. `/start` - restart the bot.\n2. `/help` - Display the help message.\n3. `/menu` - Display the menu.\n\nMenu consists of the following buttons:\n\nTODO: Add the photos and the description of the buttons.\n\n## Documentation\n\n### Project Structure\n\n- `bot/` - Bot folder\n  - `handlers/` - Command handlers\n  - `database/` - Database interactions\n  - `users/` - User management\n  - `__main__.py` - Bot entry point\n- `data/` - Folder for the database\n- `logs/` - Folder for logs\n- `res/` - Folder for resources\n- `startup_script/` - Scripts for starting the bot\n- `tests/` - Folder for tests\n- `.gitignore` - Ignored files\n- `poetry.lock` - Poetry dependency lock file\n- `pyproject.toml` - Poetry project configuration file\n- `requirements.txt` - Dependencies for pip\n- `README.md` - Project description\n\n---\n\n### Access Levels (+ Checklist)\n\n#### **Customer**\nBasic functionalities:\n- [x] View the menu\n- [x] Place orders\n- [x] View their own orders\n- [ ] Statistics\n\n#### **Bartender**\nIncludes all Customer functionalities plus:\n- [x] View the order queue\n- [x] Confirm orders\n\n#### **Administrator**\nIncludes all Bartender functionalities plus:\n- [ ] Assign roles (Customer or Bartender)\n- [ ] View logs\n- [ ] Access various statistics\n- [ ] Modify and edit the database\n- [ ] Manage users\n\n---\n\n### Database\n\nThe database is located in `data/database.db` (git-ignored to prevent user data leaks) and is stored locally on the host.  \n\nIt uses SQLite and is managed through the `database.py` file.  \n\nThe database contains the following tables:\n1. **Users**: Tracks user information and roles.\n2. **Menu**: Contains bar items and pricing.\n3. **Orders**: Tracks customer orders (used to generate the bartender's queue).\n\n---\n\n#### **Order Data**\nTable structure:\n- Order number (optional; currently using date and time instead)\n- Product name (from the menu)\n- Customer ID\n- Bartender ID\n- Order status\n- Status change timestamps (optional, as there are only two statuses for now)\n\n#### **Menu**\nTable structure:\n- Item name\n- Description\n- Price\n- Tags (optional, for categorization if the menu becomes too large)\n\n#### **User Data**\nTable structure:\n- User ID\n- Username\n- Access level (role)\n- ...\n\n---\n\n### Party Management System (+ Checklist)\n\nThis feature will be implemented later. It is expected to include:\n- [ ] Creating parties\n- [ ] Inviting users\n- [ ] Managing access to parties\n- [ ] Joining an existing party\n\n## Contributing\nYou can contribute to this project by creating a pull request or opening an issue. \nAlso you can fork this repository and make your own version of the bot.\n\n\nAll contributions are welcome!\n","project_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fnikitoskey%2Falcounting_bot","html_url":"https://awesome.ecosyste.ms/projects/github.com%2Fnikitoskey%2Falcounting_bot","lists_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fnikitoskey%2Falcounting_bot/lists"}