Initial version

.github/workflows/build-docs.yml

@@ -0,0 +1,107 @@
+name: Build documentation
+
+on:
+  push:
+    branches: ["main"]
+  workflow_dispatch:
+
+permissions:
+  id-token: write
+  pages: write
+
+env:
+  INSTANCE: 'Writerside/telegram-bots'
+  ARTIFACT: 'webHelpTELEGRAM-BOTS2-all.zip'
+  DOCKER_VERSION: '233.14389'
+  ALGOLIA_ARTIFACT: 'algolia-indexes-TELEGRAM-BOTS.zip'
+  ALGOLIA_APP_NAME: 'MU5QJD4JVP'
+  ALGOLIA_INDEX_NAME: 'TelegramBotsDocumentation'
+  ALGOLIA_KEY: '${{ secrets.ALGOLIA_KEY }}'
+  CONFIG_JSON_PRODUCT: 'TelegramBots'
+  CONFIG_JSON_VERSION: '1.0'
+
+jobs:
+  build:
+    runs-on: ubuntu-latest
+    steps:
+      - name: Checkout repository
+        uses: actions/checkout@v4
+
+      - name: Build docs using Writerside Docker builder
+        uses: JetBrains/writerside-github-action@v4
+        with:
+          instance: ${{ env.INSTANCE }}
+          artifact: ${{ env.ARTIFACT }}
+          docker-version: ${{ env.DOCKER_VERSION }}
+
+      - name: Save artifact with build results
+        uses: actions/upload-artifact@v3
+        with:
+          name: docs
+          path: |
+            artifacts/${{ env.ARTIFACT }}
+            artifacts/report.json
+            artifacts/${{ env.ALGOLIA_ARTIFACT }}
+          retention-days: 7
+  test:
+    needs: build
+    runs-on: ubuntu-latest
+    steps:
+      - name: Download artifacts
+        uses: actions/download-artifact@v3
+        with:
+          name: docs
+          path: artifacts
+
+      - name: Test documentation
+        uses: JetBrains/writerside-checker-action@v1
+        with:
+          instance: ${{ env.INSTANCE }}
+  deploy:
+    environment:
+      name: github-pages
+      url: ${{ steps.deployment.outputs.page_url }}
+    needs: [build, test]
+    runs-on: ubuntu-latest
+    steps:
+      - name: Download artifacts
+        uses: actions/download-artifact@v3
+        with:
+          name: docs
+
+      - name: Unzip artifact
+        run: unzip -O UTF-8 -qq '${{ env.ARTIFACT }}' -d dir
+
+      - name: Setup Pages
+        uses: actions/configure-pages@v4
+
+      - name: Package and upload Pages artifact
+        uses: actions/upload-pages-artifact@v3
+        with:
+          path: dir
+
+      - name: Deploy to GitHub Pages
+        id: deployment
+        uses: actions/deploy-pages@v4
+  publish-indexes:
+    if: false
+    needs: [ build, test, deploy ]
+    runs-on: ubuntu-latest
+    container:
+      image: registry.jetbrains.team/p/writerside/builder/algolia-publisher:2.0.32-2
+    steps:
+      - name: Download artifact
+        uses: actions/download-artifact@v3
+        with:
+          name: docs
+      - name: Unzip artifact
+        run: |
+          unzip -O UTF-8 -qq '${{ env.ALGOLIA_ARTIFACT }}' -d algolia-indexes
+          env algolia-key='${{env.ALGOLIA_KEY}}' java -jar /opt/builder/help-publication-agent.jar \
+          update-index \
+          --application-name '${{env.ALGOLIA_APP_NAME}}' \
+          --index-name '${{env.ALGOLIA_INDEX_NAME}}' \
+          --product '${{env.CONFIG_JSON_PRODUCT}}' \
+          --version '${{env.CONFIG_JSON_VERSION}}' \
+          --index-directory algolia-indexes/ \
+          2>&1 | tee algolia-update-index-log.txt

.gitignore

@@ -0,0 +1 @@
+.idea/

README.md

@@ -0,0 +1,38 @@
+# Telegram Bot Java Library Documentation
+
+This project holds the documentation for https://github.com/rubenlagus/TelegramBots java library that is available on at https://rubenlagus.github.io/TelegramBotsDocumentation/
+
+## Contributions
+Feel free to fork this project, work on it and then make a pull request.
+I will accept them if they add something valuable documentation.
+
+Please, **DO NOT PUSH ANY TOKEN OR API KEY**, I will never accept a pull request with that content.
+
+## Powered by Jetbrains and Algolia
+<p align="center">
+   <a href="https://www.jetbrains.com/?from=TelegramBots"><img src="Writerside/images/jetbrains.png" width="75"></a>
+    <a href="https://algolia.com/?from=TelegramBots"><img src="Writerside/images/Algolia-mark-blue.png" width="75"></a>
+</p>
+
+## License
+MIT License
+
+Copyright (c) 2024 Ruben Bermudez
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

Writerside/c.list

@@ -0,0 +1,5 @@
+<?xml version="1.0" encoding="UTF-8"?>
+<!DOCTYPE categories
+        SYSTEM "https://resources.jetbrains.com/writerside/1.0/categories.dtd">
+<categories>
+</categories>

Writerside/cfg/buildprofiles.xml

@@ -0,0 +1,24 @@
+<buildprofiles xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance"
+               xsi:noNamespaceSchemaLocation="https://resources.jetbrains.com/writerside/1.0/build-profiles.xsd">
+    <variables>
+        <primary-color>aqua</primary-color>
+        <product-web-url>https://github.com/rubenlagus/TelegramBots</product-web-url>
+        <download-title>Github</download-title>
+        <download-page>https://github.com/rubenlagus/TelegramBots</download-page>
+        <showDownloadButton>true</showDownloadButton>
+        <algolia-id>MU5QJD4JVP</algolia-id>
+        <algolia-index>TelegramBotsDocumentation</algolia-index>
+        <algolia-api-key>426f9e87b8714e3864942ac0df30bc8d</algolia-api-key>
+        <web-root>https://rubenlagus.github.io/TelegramBotsDocumentation</web-root>
+    </variables>
+    <build-profile instance="telegram-bots">
+        <variables>
+            <noindex-content>false</noindex-content>
+        </variables>
+    </build-profile>
+    <footer>
+        <link href="https://github.com/rubenlagus/TelegramBots/issues">Issue Tracker</link>
+        <link href="https://telegram.me/JavaBotsApi">Telegram Chat</link>
+        <copyright>Ruben Bermudez 2016</copyright>
+    </footer>
+</buildprofiles>

Writerside/redirection-rules.xml

@@ -0,0 +1,9 @@
+<?xml version="1.0" encoding="UTF-8"?>
+<!DOCTYPE rules SYSTEM "https://resources.jetbrains.com/writerside/1.0/redirection-rules.dtd">
+<rules>
+
+    <rule id="5af9978a">
+        <description>Created after removal of "Using HTTP proxy" from Telegram Bots</description>
+        <accepts>Using-HTTP-proxy.html</accepts>
+    </rule>
+</rules>

Writerside/telegram-bots.tree

@@ -0,0 +1,28 @@
+<?xml version="1.0" encoding="UTF-8"?>
+<!DOCTYPE instance-profile
+        SYSTEM "https://resources.jetbrains.com/writerside/1.0/product-profile.dtd">
+
+<instance-profile id="telegram-bots"
+                 name="Telegram Bots"
+                 start-page="Telegram-Bots.topic">
+
+    <toc-element topic="Telegram-Bots.topic"/>
+    <toc-element topic="Getting-Started.md"/>
+    <toc-element topic="FAQ.md"/>
+    <toc-element topic="Handling-Bot-Tokens.md"/>
+    <toc-element topic="Abilities.md">
+        <toc-element topic="Simple-Example.md"/>
+        <toc-element topic="Using-Replies.md"/>
+        <toc-element topic="Ability-Toggle.md"/>
+        <toc-element topic="State-Machines.md"/>
+        <toc-element topic="Database-Handling.md"/>
+        <toc-element topic="Ability-Extensions.md"/>
+        <toc-element topic="Bot-Testing.md"/>
+        <toc-element topic="Bot-Recovery.md"/>
+        <toc-element topic="Advanced.md"/>
+        <toc-element topic="Additional-Examples.md"/>
+    </toc-element>
+    <toc-element topic="Changelog.md">
+        <toc-element topic="How-To-Update.md"/>
+    </toc-element>
+</instance-profile>

Writerside/topics/Abilities.md

@@ -0,0 +1,149 @@
+# Abilities
+
+<p align="center">
+<img src="API BOT-03.png" alt="abilities" />
+</p>
+
+The AbilityBot abstraction defines a new object, named Ability. An ability combines conditions, flags, action, post-action and replies.
+
+## Usage
+
+<tabs group="depencency">
+    <tab title="Maven" group-key="Maven">
+        <code-block lang="xml">
+            <![CDATA[
+            <dependency>
+              <groupId>org.telegram</groupId>
+              <artifactId>telegrambots-abilities</artifactId>
+              <version>%version%</version>
+            </dependency>
+            ]]>
+        </code-block>
+    </tab>
+    <tab title="Gradle" group-key="Gradle">
+        <code-block lang="gradle">
+            <![CDATA[implementation 'org.telegram:telegrambots-abilities:%version%']]></code-block>
+    </tab>
+    <tab title="JitPack" group-key="JitPack">
+        If you don´t like standard <b>Maven Central Repository</b>, see Jitpack steps <a href="https://jitpack.io/#rubenlagus/TelegramBots">here</a>
+    </tab>  
+    <tab title="Manual Jar" group-key="Manual">
+        Import the library <b>.jar</b> direclty to your project. You can find it <a href="https://github.com/rubenlagus/TelegramBots/releases">here</a>, don't forget to fetch the latest version, it usually is a good idea. 
+        <p></p>
+        Depending on the IDE you are using, the process to add a library is different, here is a video that may help with <a href="https://www.youtube.com/watch?v=NZaH4tjwMYg">Intellij</a>
+    </tab>
+</tabs>
+
+## Motivation
+
+Ever since I've started programming bots for Telegram, I've been using the Telegram Bot Java API. It's a basic and nicely done API that is a 1-to-1 translation of the HTTP API exposed by Telegram.
+
+Dealing with a basic API has its advantages and disadvantages. Obviously, there's nothing hidden. If it's there on Telegram, it's here in the Java API.
+When you want to implement a feature in your bot, you start asking these questions:
+
+* The **WHO**?
+    * Who is going to use this feature? Should they be allowed to use all the features?
+* The **WHAT**?
+    * Under what conditions should I allow this feature?
+    * Should the message have a photo? A document? Oh, maybe a callback query?
+* The **HOW**?
+    * If my bot crashes, how can I resume my operation?
+    * Should I utilize a DB?
+    * How can I separate logic execution of different features?
+    * How can I unit-test my feature outside of Telegram?
+
+Every time you write a command or a feature, you will need to answer these questions and ensure that your feature logic works.
+
+## Ability Bot Abstraction
+
+After implementing my fifth bot using that API, I had had it with the amount of **boilerplate code** that was needed for every added feature. Methods were getting overly-complex and readability became subpar.
+That is where the notion of another layer of abstraction (AbilityBot) began taking shape.
+
+The AbilityBot abstraction defines a new object, named **Ability**. An ability combines conditions, flags, action, post-action and replies.
+As an example, here is a code-snippet of an ability that creates a ***/hello*** command:
+
+```java
+public Ability sayHelloWorld() {
+    return Ability
+              .builder()
+              .name("hello")
+              .info("says hello world!")
+              .input(0)
+              .locality(USER)
+              .privacy(ADMIN)
+              .action(ctx -> sender.send("Hello world!", ctx.chatId()))
+              .post(ctx -> sender.send("Bye world!", ctx.chatId()))
+              .build();
+}
+```
+Here is a breakdown of the above code snippet:
+* *.name()* - the name of the ability (essentially, this is the command)
+* *.info()* - provides information for the command
+    * More on this later, but it basically centralizes command information in-code.
+* *.input()* - the number of input arguments needed, 0 is for do-not-care
+* *.locality()* - this answers where you want the ability to be available
+    * In GROUP, USER private chats or ALL (both)
+* *.privacy()* - this answers who you want to access your ability
+    * CREATOR, ADMIN, or everyone as PUBLIC
+* *.action()* - the feature logic resides here (a lambda function that takes a *MessageContext*)
+    * *MessageContext* provides fast accessors for the **chatId**, **user** and the underlying **update**. It also conforms to the specifications of the basic API.
+* *.post()* - the logic executed **after** your main action finishes execution
+
+The following is a snippet of how this would look like with the plain basic API.
+
+```java
+   @Override
+   public void onUpdateReceived(Update update) {
+       // Global checks...
+       // Switch, if, logic to route to hello world method
+       // Execute method
+   }
+
+   public void sayHelloWorld(Update update) {
+       if (!update.hasMessage() || !update.getMessage().isUserMessage() || !update.getMessage().hasText() || update.getMessage.getText().isEmpty())
+           return;
+       User maybeAdmin = update.getMessage().getFrom();
+       /* Query DB for if the user is an admin, can be SQL, Reddis, Ignite, etc...
+          If user is not an admin, then return here.
+       */
+
+       SendMessage snd = new SendMessage();
+       snd.setChatId(update.getMessage().getChatId());
+       snd.setText("Hello world!");
+
+       try {
+           sendMessage(snd);
+       } catch (TelegramApiException e) {
+           BotLogger.error("Could not send message", TAG, e);
+       }
+   }
+```
+
+I will leave you the choice to decide between the two snippets as to which is more **readable**, **writable** and **testable**.
+
+***You can do so much more with abilities, besides plain commands. Head over to our [examples](#examples) to check out all of its features!***
+
+## Objective
+
+The AbilityBot abstraction intends to provide the following:
+* New feature is a new **Ability**, a new method - no fuss, zero overhead, no cross-code with other features
+* Argument length on a command is as easy as changing a single integer
+* Privacy settings per Ability - access levels to Abilities! User | Admin | Creator
+* Embedded database - available for every declared ability
+* Proxy sender interface - enhances testability; accurate results pre-release
+
+Alongside these exciting core features of the AbilityBot, the following have been introduced:
+* The bot automatically maintains an up-to-date set of all the users who have contacted the bot
+    * up-to-date: if a user changes their Username, First Name or Last Name, the bot updates the respective field in the embedded-DB
+* Backup and recovery for the DB
+    * Default implementation relies on JSON/Jackson
+* Ban and unban users from accessing your bots
+    * The bot will execute the shortest path to discard the update the next time they try to spam
+* Promote and demote users as bot administrators
+    * Allows admins to execute admin abilities
+
+# Examples
+-------------------
+* [Example Bots](https://github.com/addo37/ExampleBots)
+
+Do you have a project that uses **AbilityBots**? Let us know!