Merge pull request #15 from micromagicman/develop

v2.1.0
micromagicman · May 26, 2024 · 9454396 · 9454396
2 parents dfd8f09 + 5a4caa2
commit 9454396
Show file tree

Hide file tree

Showing 18 changed files with 458 additions and 55 deletions.
diff --git a/README.md b/README.md
@@ -34,13 +34,14 @@ php artisan vendor:publish --provider="Micromagicman\TelegramWebApp\TelegramWebA
 
 All package configuration available in `config/telegram-webapp.php` file after `publish` command execution:
 
-| Config name            | Description                                                                  | Environment                               | Default value                                 |
-|------------------------|------------------------------------------------------------------------------|-------------------------------------------|-----------------------------------------------|
-| `enabled`              | Telegram MiniApp data validation switch                                      | `TELEGRAM_WEBAPP_DATA_VALIDATION_ENABLED` | `true`                                        |
-| `webAppScriptLocation` | Path to script (.js) which initializes Telegram MiniApp on your frontend app | -                                         | `https://telegram.org/js/telegram-web-app.js` |
-| `botToken`             | Your Telegram bot token                                                      | `TELEGRAM_BOT_TOKEN`                      | -                                             |
-| `error.status`         | HTTP status code when Telegram MiniApp data validation fails                 | -                                         | 403 (Forbidden)                               |
-| `error.message`        | HTTP status code when Telegram MiniApp data validation fails                 | -                                         | 403 (Forbidden)                               |
+| Config name               | Description                                                                                                                                                                                                                                                                                                                                                         | Environment                               | Default value                                 |
+|---------------------------|---------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------|-------------------------------------------|-----------------------------------------------|
+| `enabled`                 | Telegram MiniApp data validation switch                                                                                                                                                                                                                                                                                                                             | `TELEGRAM_WEBAPP_DATA_VALIDATION_ENABLED` | `true`                                        |
+| `webAppScriptLocation`    | Path to script (.js) which initializes Telegram MiniApp on your frontend app                                                                                                                                                                                                                                                                                        | -                                         | `https://telegram.org/js/telegram-web-app.js` |
+| `botToken`                | Your Telegram bot token                                                                                                                                                                                                                                                                                                                                             | `TELEGRAM_BOT_TOKEN`                      | -                                             |
+| `error.status`            | HTTP status code when Telegram MiniApp data validation fails                                                                                                                                                                                                                                                                                                        | -                                         | 403 (Forbidden)                               |
+| `error.message`           | Error message returned when Telegram MiniApp data validation fails                                                                                                                                                                                                                                                                                                  | -                                         | 403 (Forbidden)                               |
+| `authDateLifetimeSeconds` | The lifetime of the Telegram initData auth_date parameter in seconds. The request to the server must be made within this interval, otherwise the data transmitted from Telegram will be considered invalid. The values of the parameter <= 0 imply that there is no verification of the lifetime of data from telegram and the auth_date parameter is not validated | -                                         | 0                                             |
 
 Example in code:
 
@@ -68,4 +69,29 @@ Example:
         // My spa content
     </div>
 @endsection
+```
+
+## Telegram bot API
+
+### answerWebAppQuery
+
+Set the result of an interaction with a Web App and send a corresponding message on behalf of the user to the chat 
+from which the query originated. On success, an `Illuminate\Http\Client\Response` object is returned.
+
+#### Parameters
+
+`$result` - one of [InlineQueryResult](https://core.telegram.org/bots/api#inlinequeryresult) variations (php array)
+
+```php
+
+use Micromagicman\TelegramWebApp\Api\TelegramBotApi;
+
+private TelegramBotApi $botApi;
+
+$response = $botApi->answerWebpAppQuery([
+    'type' => 'document'
+    // ...
+    // one of InlineQueryResult variations
+    // ...
+]);
 ```
diff --git a/composer.lock b/composer.lock
diff --git a/config/telegram-webapp.php b/config/telegram-webapp.php
@@ -23,6 +23,16 @@
     */
     'botToken' => env( 'TELEGRAM_BOT_TOKEN', '' ),
 
+    /*
+    |--------------------------------------------------------------------------
+    | The lifetime of the {@link https://core.telegram.org/bots/webapps#webappinitdata Telegram initData} auth_date parameter in seconds.
+    | The request to the server must be made within this interval, otherwise the data transmitted from Telegram
+    | will be considered invalid. The values of the parameter <= 0 imply that there is no verification of the lifetime
+    | of data from telegram and the auth_date parameter is not validated.
+    |--------------------------------------------------------------------------
+    */
+    'authDateLifetimeSeconds' => 0,
+
     /*
     |--------------------------------------------------------------------------
     | HTTP error response format options

diff --git a/src/Api/TelegramApi.php b/src/Api/TelegramApi.php
@@ -0,0 +1,20 @@
+<?php
+
+namespace Micromagicman\TelegramWebApp\Api;
+
+/**
+ * Abstract Telegram API
+ * Possible implementations:
+ * <ul>
+ *  <li>{@link https://core.telegram.org/#getting-started Telegram API}</li>
+ *  <li>{@link https://core.telegram.org/bots/api Telegram Telegram Bot API}</li>
+ * </ul>
+ */
+interface TelegramApi
+{
+
+    /**
+     * Execution of API method
+     */
+    public function execute( TelegramApiMethod $apiMethod ): mixed;
+}
diff --git a/src/Api/TelegramApiMethod.php b/src/Api/TelegramApiMethod.php
@@ -0,0 +1,32 @@
+<?php
+
+namespace Micromagicman\TelegramWebApp\Api;
+
+use UnexpectedValueException;
+
+/**
+ * Abstract Telegram API method
+ */
+abstract class TelegramApiMethod
+{
+
+    /**
+     * Method name
+     * By default, it's class name in lowerUpperCase
+     */
+    public function methodName(): string
+    {
+        $fullClassName = get_called_class();
+        $lastBackslashIndex = strrpos( $fullClassName, '\\' );
+        if ( -1 === $lastBackslashIndex ) {
+            throw new UnexpectedValueException( "Cannot resolve method name from it\'s class ($fullClassName)" );
+        }
+        $className = substr( $fullClassName, $lastBackslashIndex + 1 );
+        return strtolower( $className[ 0 ] ) . substr( $className, 1 );
+    }
+
+    /**
+     * Request body for API method
+     */
+    public abstract function body(): array;
+}
diff --git a/src/Api/TelegramBotApi.php b/src/Api/TelegramBotApi.php
@@ -0,0 +1,51 @@
+<?php
+
+namespace Micromagicman\TelegramWebApp\Api;
+
+use Illuminate\Http\Client\Response;
+use Illuminate\Support\Facades\Http;
+use Micromagicman\TelegramWebApp\Api\WebApp\AnswerWebAppQuery;
+
+class TelegramBotApi implements TelegramApi
+{
+
+    /**
+     * Root endpoint for Telegram Bot API
+     */
+    private const TELEGRAM_API_ROOT = 'https://api.telegram.org';
+
+    /**
+     * Root endpoint with current bot token
+     */
+    private string $apiBotRoot;
+
+    public function __construct()
+    {
+        $this->apiBotRoot = self::TELEGRAM_API_ROOT . '/bot' . telegramToken();
+    }
+
+    /**
+     * Set the result of an interaction with a Web App and send a corresponding message on behalf of the user to the chat
+     * from which the query originated. On success, an Illuminate\Http\Client\Response object is returned.
+     */
+    public function answerWebAppQuery( mixed $result ): Response
+    {
+        return $this->execute( new AnswerWebAppQuery( $result ) );
+    }
+
+    /**
+     * Telegram Bot API method execution
+     */
+    public function execute( TelegramApiMethod $apiMethod ): Response
+    {
+        return Http::post( $this->prepareUrl( $apiMethod ), $apiMethod->body() );
+    }
+
+    /**
+     * Create endpoint for Telegram Bot API
+     */
+    private function prepareUrl( TelegramApiMethod $apiMethod ): string
+    {
+        return "$this->apiBotRoot/{$apiMethod->methodName()}";
+    }
+}
diff --git a/src/Api/WebApp/AnswerWebAppQuery.php b/src/Api/WebApp/AnswerWebAppQuery.php
@@ -0,0 +1,33 @@
+<?php
+
+namespace Micromagicman\TelegramWebApp\Api\WebApp;
+
+use Micromagicman\TelegramWebApp\Api\TelegramApiMethod;
+
+/**
+ * Set the result of an interaction with a Web App and send a corresponding message on behalf of the user
+ * to the chat from which the query originated.
+ *
+ * @see {@link https://core.telegram.org/bots/api#answerwebappquery}
+ */
+class AnswerWebAppQuery extends TelegramApiMethod
+{
+
+    /**
+     * A JSON-serialized object describing the message to be sent
+     */
+    private mixed $result;
+
+    public function __construct( mixed $result )
+    {
+        $this->result = $result;
+    }
+
+    public function body(): array
+    {
+        return [
+            'web_app_query_id' => webAppQueryId(),
+            'result' => json_encode( $this->result )
+        ];
+    }
+}