Merge pull request #26 from ch3p4ll3/v2

V2

.all-contributorsrc

@@ -0,0 +1,29 @@
+{
+  "files": [
+    "README.md"
+  ],
+  "imageSize": 100,
+  "commit": false,
+  "commitType": "docs",
+  "commitConvention": "angular",
+  "contributors": [
+    {
+      "login": "bushig",
+      "name": "Bogdan",
+      "avatar_url": "https://avatars.githubusercontent.com/u/2815779?v=4",
+      "profile": "https://github.com/bushig",
+      "contributions": [
+        "code"
+      ]
+    }
+  ],
+  "contributorsPerLine": 7,
+  "skipCi": true,
+  "repoType": "github",
+  "repoHost": "https://github.com",
+  "projectName": "QBittorrentBot",
+  "projectOwner": "ch3p4ll3"
+}
+  "projectName": "QBittorrentBot",
+  "projectOwner": "ch3p4ll3"
+}

.github/workflows/deploy_retype.yml

@@ -0,0 +1,26 @@
+name: Publish Retype powered website to GitHub Pages
+on:
+  workflow_dispatch:
+  push:
+    branches:
+      - main
+
+jobs:
+  publish:
+    name: Publish to retype branch
+
+    runs-on: ubuntu-latest
+
+    permissions:
+      contents: write
+
+    steps:
+      - uses: actions/checkout@v2
+
+      - uses: retypeapp/action-build@latest
+        with:
+          config: docs/retype.yml
+
+      - uses: retypeapp/action-github-pages@latest
+        with:
+          update-branch: true

.github/workflows/docker-image.yml

@@ -13,6 +13,11 @@ jobs:
     runs-on: ubuntu-latest
 
     steps:
+      - name: "Set current date as env variable"
+        run: |
+          echo "builddate=$(date +'%Y-%m-%d')" >> $GITHUB_OUTPUT
+        id: version  # this is used on variable path
+
       - name: Checkout 
         uses: actions/checkout@v3
       -
@@ -36,4 +41,6 @@ jobs:
           context: .
           file: ./Dockerfile
           push: true
-          tags: ${{ secrets.DOCKER_HUB_USERNAME }}/qbittorrent-bot:latest
+          tags: |
+            ${{ secrets.DOCKER_HUB_USERNAME }}/qbittorrent-bot:${{ steps.version.outputs.builddate }}
+            ${{ secrets.DOCKER_HUB_USERNAME }}/qbittorrent-bot:latest

.gitignore

@@ -165,4 +165,5 @@ config.json
 *.session
 *.session-journal
 
-*.sqlite
+*.sqlite
+/docker_folder

README.md

@@ -1,4 +1,7 @@
 [![Codacy Badge](https://api.codacy.com/project/badge/Grade/259099080ca24e029a910e3249d32041)](https://app.codacy.com/gh/ch3p4ll3/QBittorrentBot?utm_source=github.com&utm_medium=referral&utm_content=ch3p4ll3/QBittorrentBot&utm_campaign=Badge_Grade)
+<!-- ALL-CONTRIBUTORS-BADGE:START - Do not remove or modify this section -->
+[![All Contributors](https://img.shields.io/badge/all_contributors-1-orange.svg?style=flat-square)](#contributors-)
+<!-- ALL-CONTRIBUTORS-BADGE:END -->
 
 # QBittorrentBot
 
@@ -10,6 +13,9 @@ magnet:?xt=...
 ```
 You can also pause, resume, delete and add/remove and modify categories.
 
+## Warning!
+Since version V2, the mapping of the configuration file has been changed. Make sure you have modified it correctly before starting the bot
+
 ## Configuration
 ### Retrieve Telegram API ID and API HASH
 With the change of library to [pyrogram](https://docs.pyrogram.org/) you will need the API_ID and API_HASH. Check [here](https://docs.pyrogram.org/intro/quickstart) to find out how to recover them.
@@ -19,8 +25,9 @@ The config file is stored in the mounted /app/config/ volume
 
 ```
 {
-    "qbittorrent": {
-        "ip": "192.168.178.102",
+    "client": {
+        "type": "qbittorrent",
+        "host": "192.168.178.102",
         "port": 8080,
         "user": "admin",
         "password": "admin"
@@ -34,11 +41,13 @@ The config file is stored in the mounted /app/config/ volume
     "users": [
         {
             "user_id": 123456,
-            "notify": false
+            "notify": false,
+            "role": "administrator"
         },
         {
             "user_id": 12345678,
-            "notify": true
+            "notify": true,
+            "role": "manager"
         }
     ]
 }
@@ -58,7 +67,6 @@ Pull and run the image with: `docker run -d -v /home/user/docker/QBittorrentBot:
 - Move in the project directory
 - Install dependencies with `pip3 install -r requirements.txt`
 - Create a config.json file
-- Edit in the file /src/config.py the location of the file 'config.json'
 - Start the bot with `python3 main.py`
 
 ## How to enable the qBittorrent Web UI
@@ -71,3 +79,24 @@ You can activate it by going on the menu bar, go to **Tools > Options** qBittorr
 - Set username and password (by default username: admin / password: adminadmin)
 
 Click on Ok to save settings.
+
+## Contributors ✨
+
+Thanks goes to these wonderful people ([emoji key](https://allcontributors.org/docs/en/emoji-key)):
+
+<!-- ALL-CONTRIBUTORS-LIST:START - Do not remove or modify this section -->
+<!-- prettier-ignore-start -->
+<!-- markdownlint-disable -->
+<table>
+  <tbody>
+    <tr>
+      <td align="center" valign="top" width="14.28%"><a href="https://github.com/bushig"><img src="https://avatars.githubusercontent.com/u/2815779?v=4?s=100" width="100px;" alt="Bogdan"/><br /><sub><b>Bogdan</b></sub></a><br /><a href="https://github.com/ch3p4ll3/QBittorrentBot/commits?author=bushig" title="Code">💻</a></td>
+    </tr>
+  </tbody>
+</table>
+
+<!-- markdownlint-restore -->
+<!-- prettier-ignore-end -->
+<!-- ALL-CONTRIBUTORS-LIST:END -->
+
+This project follows the [all-contributors](https://github.com/all-contributors/all-contributors) specification. Contributions of any kind welcome!

config.json.template

@@ -1,6 +1,7 @@
 {
-    "qbittorrent": {
-        "ip": "192.168.178.102",
+    "client": {
+        "type": "qbittorrent",
+        "host": "192.168.178.102",
         "port": 8080,
         "user": "admin",
         "password": "admin"
@@ -14,7 +15,8 @@
     "users": [
         {
             "user_id": 123456,
-            "notify": false
+            "notify": false,
+            "role": "administrator"
         }
     ]
 }

docs/advanced/add_entries_configuration.md

@@ -0,0 +1,35 @@
+---
+order: -10
+---
+# Add new entries in configuration file
+
+Adding a new entry to the QBittorrentBot configuration file involves several steps:
+
+- **Clone the repository**: `git clone https://github.com/ch3p4ll3/QBittorrentBot.git`
+
+- **Navigate to the folder**: `src/configs`
+
+- **Modify the pydantic class**:
+        Identify the pydantic class where the new entry should be added.
+        Add a new attribute to the class to represent the new entry.
+
+- **Create a validation function (if necessary)**:
+        If the new entry requires additional validation beyond the type provided by pydantic, create a validation function.
+        The validation function should inspect the value of the new entry and check for any constraints or rules that need to be enforced.
+
+- **Add the new entry to the config file**:
+        Open the configuration file (usually `config.json`).
+        Add a new property to the configuration object for the new entry.
+        Set the value of the new property to the desired initial value.
+
+- **Update the convert_type_from_string function (if necessary)**:
+        If the new entry type requires a custom conversion from a string representation, add the conversion function to the `utils` file.
+        The function should take a string representation of the new entry type and return the corresponding data type.
+
+- **Update the bot code (if necessary)**:
+        If the new entry is being used by the bot code, update the relevant parts of the code to handle the new entry type and its values.
+
+- Build the docker image
+- Start the docker container
+
+You can now use the bot with the new entry, have fun🥳

docs/advanced/add_new_client_manager.md

@@ -0,0 +1,78 @@
+---
+order: 0
+---
+# Add new client manager
+
+Adding a new client manager to QBittorrentBot involves creating a new class that implements the `ClientManager` interface. This interface defines the methods that the bot uses to interact with the client, such as adding, removing, pausing, and resuming torrents.
+
+To do this you need to follow a couple of steps:
+
+- Clone the repository locally using the command: `git clone https://github.com/ch3p4ll3/QBittorrentBot.git`
+- Navigate to the folder `src/client_manager`
+- Create a new file for your client manager class. Name the file something like `<client>_manager.py`. For example, if you are writing a manager for utorrent the name will be `utorrent_manager.py`
+- Define your client manager class. The class should inherit from the `ClientManager` class and implement all of its methods. For example, the `utorrent_manager.py` file might look like this:
+```python
+from typing import Union, List
+from .client_manager import ClientManager
+
+
+class UtorrentManager(ClientManager):
+    @classmethod
+    def add_magnet(cls, magnet_link: Union[str, List[str]], category: str = None) -> None:
+        # Implement your code to add a magnet to the utorrent client
+        pass
+
+    @classmethod
+    def add_torrent(cls, file_name: str, category: str = None) -> None:
+        # Implement your code to add a torrent to the utorrent client
+        pass
+...
+```
+- Navigate to the `src/configs/` folder and edit the `enums.py` file by adding to the `ClientTypeEnum` class an enum for your client. For example, if we wanted to add a manager for utorrent the class would become like this:
+```python
+class ClientTypeEnum(str, Enum):
+    QBittorrent = 'qbittorrent'
+    Utorrent = 'utorrent'
+```
+- Return to the `src/client_manager` folder and edit the `client_repo.py` file by adding to the dictionary named `repositories` an entry associating the newly created enum with the new manager. Example:
+```python
+from ..configs.enums import ClientTypeEnum
+from .qbittorrent_manager import QbittorrentManager, ClientManager
+
+
+class ClientRepo:
+    repositories = {
+        ClientTypeEnum.QBittorrent: QbittorrentManager,
+        ClientTypeEnum.Utorrent: UtorrentManager
+    }
+...
+```
+- Register your client manager in the config file. The config file is a JSON file that defines the configuration for the QBittorrentBot. You can add your new client manager to the client section of the config file. For example, the config file might look like this:
+```json
+{
+    "client": {
+        "type": "utorrent",
+        "host": "192.168.178.102",
+        "port": 8080,
+        "user": "admin",
+        "password": "admin"
+    },
+    "telegram": {
+        "bot_token": "1111111:AAAAAAAA-BBBBBBBBB",
+        "api_id": 1111,
+        "api_hash": "aaaaaaaa"
+    },
+
+    "users": [
+        {
+            "user_id": 123456,
+            "notify": false,
+            "role": "administrator"
+        }
+    ]
+}
+```
+- Build the docker image
+- Start the docker container
+
+You can now use the bot with the new client, have fun:partying_face:

docs/advanced/index.md

@@ -0,0 +1,3 @@
+# Advanced
+
+This section will speigate the advanced functions of the bot, such as creating new client managers, and managing user roles

docs/advanced/index.yml

@@ -0,0 +1 @@
+order: -10

docs/advanced/manager_user_roles.md

@@ -0,0 +1,20 @@
+---
+order: -20
+---
+# Managing users roles
+
+QBittorrentBot provides a user role management system to control access to different actions and functionalities within the bot. The system defines three roles: Reader, Manager, and Admin, each with increasing permissions and capabilities.
+
+## Reader
+
+The Reader role grants basic access to view the list of active torrents and inspect the details of individual torrents. Users with the Reader role can view the torrent name, download speed, upload speed, progress, and file size. They can also view the category to which each torrent belongs.
+
+## Manager
+
+The Manager role extends the Reader role with additional permissions, allowing users to perform actions beyond mere observation. Manager-level users can download new torrents by sending magnet links or torrent files to the bot. They can also add or edit categories to organize their torrents effectively. Additionally, Manager users can set torrent priorities, enabling them to manage the download order and prioritize specific torrents. Moreover, they can pause or resume ongoing downloads, providing flexibility in managing their torrent activity.
+
+## Admin
+
+The Admin role, the most privileged, grants the user full control over the bot's functionalities. In addition to the capabilities of the Manager role, Admin users can remove torrents from their download lists, eliminating unwanted downloads. They can also remove categories, streamlining their torrent organization structure. And, as the highest-level role, Admin users have the authority to edit the bot's configuration files, modifying its settings and behavior.
+
+This role management system ensures that users are granted access appropriate to their needs and responsibilities. Readers can observe and manage their torrent activity, Managers can perform more extensive actions, and Admins have full control over the bot's operation. This structure enhances security and prevents unauthorized users from modifying configuration files or deleting torrents.

docs/faq.md

@@ -0,0 +1,64 @@
+---
+order: -20
+---
+# FAQ
+
+### What is QBittorrentBot?
+
+QBittorrentBot is a Telegram bot that allows you to control your qBittorrent downloads from within the Telegram app. It can add torrents, manage your torrent list, and much more.
+
+### What are the benefits of using QBittorrentBot?
+
+There are several benefits to using QBittorrentBot, including:
+
+* **Convenience:** You can control your torrents from anywhere, without having to open the qBittorrent app.
+* **Efficiency:** You can manage your torrents without switching between apps.
+* **Organization:** You can categorize your torrents for better organization and accessibility.
+* **Docker Support:** You can deploy and manage the bot seamlessly using Docker containers.
+
+### How do I add QBittorrentBot to my Telegram account?
+
+Follow this guide to start using QBittorrentBot
+[!ref Getting Started](getting_started)
+
+### How do I edit the configuration for the QBittorrentBot?
+
+The QBittorrentBot configuration file is located at config.json. This file stores the bot's settings, such as the connection details for the qBittorrent client, the API IDs and hashes, and the list of authorized users. To edit the configuration file, you can open it in a text editor and make the necessary changes.
+
+### How do I check the status of my torrents?
+
+You can check the status of your torrents by using the list torrents button. This command will display a list of all your active torrents, including their name, status, progress, and download/upload speed.
+
+### What is the difference between a magnet link and a torrent file?
+
+A magnet link is a URI scheme that allows you to download a torrent without having to download the entire torrent file. A torrent file is a file that contains metadata about the torrent, such as the filename, file size, and number of pieces.
+
+### What are the different user roles available in QBittorrentBot?
+
+QBittorrentBot supports three user roles: Reader, Manager, and Admin. Each role has different permissions, as follows:
+
+* **Reader:** Can view lists of active torrents and view individual torrent details.
+* **Manager:** Can perform all Reader actions, plus add/edit categories, set torrent priorities, and pause/resume downloads.
+* **Admin:** Can perform all Manager actions, plus remove torrents, remove categories, and edit configs.
+
+### How do I change the user role for a user?
+
+You can change the user role for a user by editing the `config.json` file. Open the file and find the user's entry. Change the `role` field to the desired role (e.g., "reader", "manager", or "admin"). Save the file and restart the bot or, if you are an admin you can reload the configuration from the bot.
+
+### How do I install QBittorrentBot on my server?
+
+You can install QBittorrentBot on your server using Docker. First, install Docker on your server. Then, create a Docker image from the QBittorrentBot Dockerfile. Finally, run the Docker image to start the bot.
+
+### How do I add a new manager to my QBittorrentBot?
+
+Please follow this guide
+[!ref Add new client manager](advanced/add_new_client_manager)
+
+### How do I add a new entry to the QBittorrentBot configuration file?
+
+Please follow this guide
+[!ref Add new entries in configuration file](advanced/add_entries_configuration)
+
+### How do I contribute to the development of QBittorrentBot?
+
+QBittorrentBot is an open-source project. You can contribute to the development by reporting bugs, suggesting improvements, or submitting pull requests. The project's code is hosted on [GitHub](https://github.com/ch3p4ll3/QBittorrentBot).