From a7c948dd95c53b42288a8823552d8aa6321d0e1b Mon Sep 17 00:00:00 2001
From: Alex <alex@bushlanov.dev>
Date: Tue, 15 Jul 2025 19:12:42 +0300
Subject: [PATCH] Added attachment CallbackButton

---
 src/Api.php                                   | 12 ++-
 src/Enums/AttachmentType.php                  | 18 +++++
 src/Enums/ButtonType.php                      | 15 ++++
 src/Enums/Intent.php                          | 12 +++
 .../Attachments/Buttons/AbstractButton.php    | 17 ++++
 .../Attachments/Buttons/CallbackButton.php    | 22 +++++
 .../Payloads/AbstractAttachmentPayload.php    | 11 +++
 .../Payloads/InlineKeyboardPayload.php        | 18 +++++
 .../Requests/AbstractAttachmentRequest.php    | 21 +++++
 .../InlineKeyboardAttachmentRequest.php       | 23 ++++++
 tests/ApiTest.php                             | 81 +++++++++++++++++++
 .../Buttons/CallbackButtonTest.php            | 33 ++++++++
 12 files changed, 280 insertions(+), 3 deletions(-)
 create mode 100644 src/Enums/AttachmentType.php
 create mode 100644 src/Enums/ButtonType.php
 create mode 100644 src/Enums/Intent.php
 create mode 100644 src/Models/Attachments/Buttons/AbstractButton.php
 create mode 100644 src/Models/Attachments/Buttons/CallbackButton.php
 create mode 100644 src/Models/Attachments/Payloads/AbstractAttachmentPayload.php
 create mode 100644 src/Models/Attachments/Payloads/InlineKeyboardPayload.php
 create mode 100644 src/Models/Attachments/Requests/AbstractAttachmentRequest.php
 create mode 100644 src/Models/Attachments/Requests/InlineKeyboardAttachmentRequest.php
 create mode 100644 tests/Models/Attachments/Buttons/CallbackButtonTest.php

diff --git a/src/Api.php b/src/Api.php
index 56d27ad..4f3dd6c 100644
--- a/src/Api.php
+++ b/src/Api.php
@@ -9,6 +9,8 @@ use BushlanovDev\MaxMessengerBot\Enums\UpdateType;
 use BushlanovDev\MaxMessengerBot\Exceptions\ClientApiException;
 use BushlanovDev\MaxMessengerBot\Exceptions\NetworkException;
 use BushlanovDev\MaxMessengerBot\Exceptions\SerializationException;
+use BushlanovDev\MaxMessengerBot\Models\AbstractModel;
+use BushlanovDev\MaxMessengerBot\Models\Attachments\Requests\AbstractAttachmentRequest;
 use BushlanovDev\MaxMessengerBot\Models\BotInfo;
 use BushlanovDev\MaxMessengerBot\Models\Message;
 use BushlanovDev\MaxMessengerBot\Models\Result;
@@ -155,20 +157,20 @@ class Api
      * @param int|null $userId Fill this parameter if you want to send message to user.
      * @param int|null $chatId Fill this if you send message to chat.
      * @param string|null $text Message text.
+     * @param AbstractAttachmentRequest[]|null $attachments Message attachments.
+     * @param MessageFormat|null $format
      * @param bool $notify If false, chat participants would not be notified.
      * @param bool $disableLinkPreview If false, server will not generate media preview for links in text.
      *
      * @return Message
      *
-     * @throws ClientApiException
-     * @throws NetworkException
-     * @throws SerializationException
      * @throws ReflectionException
      */
     public function sendMessage(
         ?int $userId = null,
         ?int $chatId = null,
         ?string $text = null,
+        ?array $attachments = null,
         ?MessageFormat $format = null,
         bool $notify = true,
         bool $disableLinkPreview = false,
@@ -183,6 +185,10 @@ class Api
             'text' => $text,
             'format' => $format?->value,
             'notify' => $notify,
+            'attachments' => $attachments !== null ? array_map(
+                fn(AbstractModel $attachment) => $attachment->toArray(),
+                $attachments,
+            ) : null,
         ];
 
         $response = $this->client->request(
diff --git a/src/Enums/AttachmentType.php b/src/Enums/AttachmentType.php
new file mode 100644
index 0000000..b6448cf
--- /dev/null
+++ b/src/Enums/AttachmentType.php
@@ -0,0 +1,18 @@
+<?php
+
+declare(strict_types=1);
+
+namespace BushlanovDev\MaxMessengerBot\Enums;
+
+enum  AttachmentType: string
+{
+    case Image = 'image';
+    case Video = 'video';
+    case Audio = 'audio';
+    case File = 'file';
+    case Sticker = 'sticker';
+    case Contract = 'contract';
+    case InlineKeyboard = 'inline_keyboard';
+    case Location = 'location';
+    case Share = 'share';
+}
diff --git a/src/Enums/ButtonType.php b/src/Enums/ButtonType.php
new file mode 100644
index 0000000..7521458
--- /dev/null
+++ b/src/Enums/ButtonType.php
@@ -0,0 +1,15 @@
+<?php
+
+declare(strict_types=1);
+
+namespace BushlanovDev\MaxMessengerBot\Enums;
+
+enum ButtonType: string
+{
+    case Callback = 'callback';
+    case Link = 'link';
+    case RequestGeoLocation = 'request_geo_location';
+    case RequestContact = 'request_contact';
+    case OpenApp = 'open_app';
+    case Message = 'message';
+}
diff --git a/src/Enums/Intent.php b/src/Enums/Intent.php
new file mode 100644
index 0000000..3645ced
--- /dev/null
+++ b/src/Enums/Intent.php
@@ -0,0 +1,12 @@
+<?php
+
+declare(strict_types=1);
+
+namespace BushlanovDev\MaxMessengerBot\Enums;
+
+enum Intent: string
+{
+    case Positive = 'positive';
+    case Negative = 'negative';
+    case Default = 'default';
+}
diff --git a/src/Models/Attachments/Buttons/AbstractButton.php b/src/Models/Attachments/Buttons/AbstractButton.php
new file mode 100644
index 0000000..155f52f
--- /dev/null
+++ b/src/Models/Attachments/Buttons/AbstractButton.php
@@ -0,0 +1,17 @@
+<?php
+
+declare(strict_types=1);
+
+namespace BushlanovDev\MaxMessengerBot\Models\Attachments\Buttons;
+
+use BushlanovDev\MaxMessengerBot\Enums\ButtonType;
+use BushlanovDev\MaxMessengerBot\Models\AbstractModel;
+
+abstract readonly class AbstractButton extends AbstractModel
+{
+    public function __construct(
+        public ButtonType $type,
+        public string $text,
+    ) {
+    }
+}
diff --git a/src/Models/Attachments/Buttons/CallbackButton.php b/src/Models/Attachments/Buttons/CallbackButton.php
new file mode 100644
index 0000000..7183dca
--- /dev/null
+++ b/src/Models/Attachments/Buttons/CallbackButton.php
@@ -0,0 +1,22 @@
+<?php
+
+declare(strict_types=1);
+
+namespace BushlanovDev\MaxMessengerBot\Models\Attachments\Buttons;
+
+use BushlanovDev\MaxMessengerBot\Enums\ButtonType;
+use BushlanovDev\MaxMessengerBot\Enums\Intent;
+
+final readonly class CallbackButton extends AbstractButton
+{
+    public string $payload;
+    public ?Intent $intent;
+
+    public function __construct(string $text, string $payload, ?Intent $intent = null)
+    {
+        parent::__construct(ButtonType::Callback, $text);
+
+        $this->payload = $payload;
+        $this->intent = $intent;
+    }
+}
diff --git a/src/Models/Attachments/Payloads/AbstractAttachmentPayload.php b/src/Models/Attachments/Payloads/AbstractAttachmentPayload.php
new file mode 100644
index 0000000..eb9c5b1
--- /dev/null
+++ b/src/Models/Attachments/Payloads/AbstractAttachmentPayload.php
@@ -0,0 +1,11 @@
+<?php
+
+declare(strict_types=1);
+
+namespace BushlanovDev\MaxMessengerBot\Models\Attachments\Payloads;
+
+use BushlanovDev\MaxMessengerBot\Models\AbstractModel;
+
+abstract readonly class AbstractAttachmentPayload extends AbstractModel
+{
+}
diff --git a/src/Models/Attachments/Payloads/InlineKeyboardPayload.php b/src/Models/Attachments/Payloads/InlineKeyboardPayload.php
new file mode 100644
index 0000000..2a6a341
--- /dev/null
+++ b/src/Models/Attachments/Payloads/InlineKeyboardPayload.php
@@ -0,0 +1,18 @@
+<?php
+
+declare(strict_types=1);
+
+namespace BushlanovDev\MaxMessengerBot\Models\Attachments\Payloads;
+
+use BushlanovDev\MaxMessengerBot\Models\Attachments\Buttons\AbstractButton;
+
+final readonly class InlineKeyboardPayload extends AbstractAttachmentPayload
+{
+    /**
+     * @param AbstractButton[][] $buttons
+     */
+    public function __construct(
+        public array $buttons,
+    ) {
+    }
+}
diff --git a/src/Models/Attachments/Requests/AbstractAttachmentRequest.php b/src/Models/Attachments/Requests/AbstractAttachmentRequest.php
new file mode 100644
index 0000000..c21aa64
--- /dev/null
+++ b/src/Models/Attachments/Requests/AbstractAttachmentRequest.php
@@ -0,0 +1,21 @@
+<?php
+
+declare(strict_types=1);
+
+namespace BushlanovDev\MaxMessengerBot\Models\Attachments\Requests;
+
+use BushlanovDev\MaxMessengerBot\Enums\AttachmentType;
+use BushlanovDev\MaxMessengerBot\Models\AbstractModel;
+use BushlanovDev\MaxMessengerBot\Models\Attachments\Payloads\AbstractAttachmentPayload;
+
+/**
+ * Message attachments.
+ */
+abstract readonly class AbstractAttachmentRequest extends AbstractModel
+{
+    public function __construct(
+        public AttachmentType $type,
+        public AbstractAttachmentPayload $payload,
+    ) {
+    }
+}
diff --git a/src/Models/Attachments/Requests/InlineKeyboardAttachmentRequest.php b/src/Models/Attachments/Requests/InlineKeyboardAttachmentRequest.php
new file mode 100644
index 0000000..2cb4738
--- /dev/null
+++ b/src/Models/Attachments/Requests/InlineKeyboardAttachmentRequest.php
@@ -0,0 +1,23 @@
+<?php
+
+declare(strict_types=1);
+
+namespace BushlanovDev\MaxMessengerBot\Models\Attachments\Requests;
+
+use BushlanovDev\MaxMessengerBot\Enums\AttachmentType;
+use BushlanovDev\MaxMessengerBot\Models\Attachments\Buttons\AbstractButton;
+use BushlanovDev\MaxMessengerBot\Models\Attachments\Payloads\InlineKeyboardPayload;
+
+final readonly class InlineKeyboardAttachmentRequest extends AbstractAttachmentRequest
+{
+    /**
+     * @param AbstractButton[][] $buttons
+     */
+    public function __construct(array $buttons)
+    {
+        parent::__construct(
+            AttachmentType::InlineKeyboard,
+            new InlineKeyboardPayload($buttons)
+        );
+    }
+}
diff --git a/tests/ApiTest.php b/tests/ApiTest.php
index 22e3c90..08f15d4 100644
--- a/tests/ApiTest.php
+++ b/tests/ApiTest.php
@@ -7,9 +7,14 @@ namespace BushlanovDev\MaxMessengerBot\Tests;
 use BushlanovDev\MaxMessengerBot\Api;
 use BushlanovDev\MaxMessengerBot\Client;
 use BushlanovDev\MaxMessengerBot\ClientApiInterface;
+use BushlanovDev\MaxMessengerBot\Enums\AttachmentType;
+use BushlanovDev\MaxMessengerBot\Enums\ButtonType;
 use BushlanovDev\MaxMessengerBot\Enums\MessageFormat;
 use BushlanovDev\MaxMessengerBot\Enums\UpdateType;
 use BushlanovDev\MaxMessengerBot\ModelFactory;
+use BushlanovDev\MaxMessengerBot\Models\Attachments\Buttons\CallbackButton;
+use BushlanovDev\MaxMessengerBot\Models\Attachments\Payloads\InlineKeyboardPayload;
+use BushlanovDev\MaxMessengerBot\Models\Attachments\Requests\InlineKeyboardAttachmentRequest;
 use BushlanovDev\MaxMessengerBot\Models\BotInfo;
 use BushlanovDev\MaxMessengerBot\Models\Message;
 use BushlanovDev\MaxMessengerBot\Models\MessageBody;
@@ -34,6 +39,9 @@ use ReflectionClass;
 #[UsesClass(MessageBody::class)]
 #[UsesClass(Recipient::class)]
 #[UsesClass(Sender::class)]
+#[UsesClass(CallbackButton::class)]
+#[UsesClass(InlineKeyboardPayload::class)]
+#[UsesClass(InlineKeyboardAttachmentRequest::class)]
 final class ApiTest extends TestCase
 {
     private MockObject&ClientApiInterface $clientMock;
@@ -279,6 +287,7 @@ final class ApiTest extends TestCase
             null,
             $chatId,
             $text,
+            null,
             $format,
             $notify,
             $disableLinkPreview,
@@ -286,4 +295,76 @@ final class ApiTest extends TestCase
 
         $this->assertSame($expectedMessageObject, $result);
     }
+
+    #[Test]
+    public function sendMessageWithAttachmentsBuildsCorrectRequest(): void
+    {
+        $chatId = 123456;
+        $text = 'Test message with a keyboard';
+        $disableLinkPreview = true;
+        $button = new CallbackButton('Press Me', 'payload_123');
+        $keyboard = new InlineKeyboardAttachmentRequest([[$button]]);
+
+        $expectedAttachmentsJson = [
+            [
+                'type' => AttachmentType::InlineKeyboard->value,
+                'payload' => [
+                    'buttons' => [
+                        [
+                            [
+                                'type' => ButtonType::Callback->value,
+                                'text' => 'Press Me',
+                                'payload' => 'payload_123',
+                                'intent' => null,
+                            ]
+                        ]
+                    ]
+                ]
+            ]
+        ];
+
+        $expectedBody = [
+            'text' => $text,
+            'attachments' => $expectedAttachmentsJson,
+            'notify' => true,
+        ];
+
+        $expectedQuery = ['chat_id' => $chatId, 'disable_link_preview' => $disableLinkPreview];
+
+        $apiResponse = [
+            'message' => [
+                'timestamp' => time(),
+                'body' => ['mid' => 'mid.test.123', 'seq' => 1, 'text' => $text],
+                'recipient' => ['chat_type' => 'dialog', 'user_id' => 123, 'chat_id' => null],
+            ]
+        ];
+
+        $expectedMessageObject = Message::fromArray($apiResponse['message']);
+
+        $this->clientMock
+            ->expects($this->once())
+            ->method('request')
+            ->with(
+                'POST',
+                '/messages',
+                $expectedQuery,
+                $expectedBody,
+            )
+            ->willReturn($apiResponse);
+
+        $this->modelFactoryMock
+            ->expects($this->once())
+            ->method('createMessage')
+            ->with($apiResponse['message'])
+            ->willReturn($expectedMessageObject);
+
+        $result = $this->api->sendMessage(
+            chatId: $chatId,
+            text: $text,
+            attachments: [$keyboard],
+            disableLinkPreview: $disableLinkPreview,
+        );
+
+        $this->assertSame($expectedMessageObject, $result);
+    }
 }
diff --git a/tests/Models/Attachments/Buttons/CallbackButtonTest.php b/tests/Models/Attachments/Buttons/CallbackButtonTest.php
new file mode 100644
index 0000000..eda8f99
--- /dev/null
+++ b/tests/Models/Attachments/Buttons/CallbackButtonTest.php
@@ -0,0 +1,33 @@
+<?php
+
+declare(strict_types=1);
+
+namespace BushlanovDev\MaxMessengerBot\Tests\Models\Attachments\Buttons;
+
+use BushlanovDev\MaxMessengerBot\Enums\ButtonType;
+use BushlanovDev\MaxMessengerBot\Enums\Intent;
+use BushlanovDev\MaxMessengerBot\Models\Attachments\Buttons\CallbackButton;
+use PHPUnit\Framework\Attributes\CoversClass;
+use PHPUnit\Framework\Attributes\Test;
+use PHPUnit\Framework\TestCase;
+
+#[CoversClass(CallbackButton::class)]
+final class CallbackButtonTest extends TestCase
+{
+    #[Test]
+    public function toArraySerializesCorrectly(): void
+    {
+        $button = new CallbackButton('Test Button', 'test_payload', Intent::Default);
+
+        $expectedArray = [
+            'payload' => 'test_payload',
+            'intent' => Intent::Default->value,
+            'type' => ButtonType::Callback->value,
+            'text' => 'Test Button',
+        ];
+
+        $resultArray = $button->toArray();
+
+        $this->assertSame($expectedArray, $resultArray);
+    }
+}