Added resumable upload

src/Api.php

@@ -75,6 +75,8 @@ class Api
     private const string ACTION_ANSWERS = '/answers';
     private const string ACTION_VIDEO_DETAILS = '/videos/%s';
 
+    private const int RESUMABLE_UPLOAD_THRESHOLD_BYTES = 10 * 1024 * 1024; // 10 MB
+
     private readonly ClientApiInterface $client;
 
     private readonly ModelFactory $modelFactory;
@@ -443,6 +445,33 @@ class Api
         );
     }
 
+    /**
+     * @param string $uploadUrl The target URL for the upload.
+     * @param resource $fileHandle A stream resource pointing to the file.
+     * @param string $fileName The desired file name for the upload.
+     *
+     * @return string The body of the final response from the server.
+     * @throws ClientApiException
+     * @throws NetworkException
+     * @throws SerializationException
+     * @throws RuntimeException
+     */
+    public function uploadFile(string $uploadUrl, mixed $fileHandle, string $fileName): string
+    {
+        $stat = fstat($fileHandle);
+        if (!is_array($stat)) {
+            throw new RuntimeException('File handle is not a valid resource.');
+        }
+
+        rewind($fileHandle);
+
+        if ($stat['size'] < self::RESUMABLE_UPLOAD_THRESHOLD_BYTES) {
+            return $this->client->multipartUpload($uploadUrl, $fileHandle, $fileName);
+        }
+
+        return $this->client->resumableUpload($uploadUrl, $fileHandle, $fileName, $stat['size']);
+    }
+
     /**
      * A simplified method for uploading a file and getting the resulting attachment object.
      *
@@ -479,7 +508,8 @@ class Api
                     "API did not return a pre-upload token for type '$type->value'."
                 );
             }
-            $this->client->upload($uploadEndpoint->url, $fileHandle, basename($filePath));
+
+            $this->uploadFile($uploadEndpoint->url, $fileHandle, basename($filePath));
             fclose($fileHandle);
 
             return match ($type) {
@@ -489,7 +519,7 @@ class Api
         }
 
         // For images and files, the token is in the response *after* the upload.
-        $responseBody = $this->client->upload($uploadEndpoint->url, $fileHandle, basename($filePath));
+        $responseBody = $this->uploadFile($uploadEndpoint->url, $fileHandle, basename($filePath));
         fclose($fileHandle);
 
         try {

src/Client.php

@@ -21,6 +21,7 @@ use Psr\Http\Message\ResponseInterface;
 use Psr\Http\Message\StreamFactoryInterface;
 use Psr\Log\LoggerInterface;
 use Psr\Log\NullLogger;
+use RuntimeException;
 
 /**
  * The low-level HTTP client responsible for communicating with the Max Bot API.
@@ -122,7 +123,7 @@ final readonly class Client implements ClientApiInterface
     /**
      * @inheritDoc
      */
-    public function upload(string $uri, mixed $fileContents, string $fileName): string
+    public function multipartUpload(string $uri, mixed $fileContents, string $fileName): string
     {
         $boundary = '--------------------------' . microtime(true);
         $bodyStream = $this->streamFactory->createStream();
@@ -155,6 +156,67 @@ final readonly class Client implements ClientApiInterface
         return (string)$response->getBody();
     }
 
+    /**
+     * @inheritDoc
+     */
+    public function resumableUpload(
+        string $uploadUrl,
+        mixed $fileResource,
+        string $fileName,
+        int $fileSize,
+        int $chunkSize = 1048576,
+    ): string {
+        if (!is_resource($fileResource) || get_resource_type($fileResource) !== 'stream') {
+            throw new InvalidArgumentException('fileResource must be a valid stream resource.');
+        }
+
+        // @phpstan-ignore-next-line
+        if ($fileSize <= 0) {
+            throw new InvalidArgumentException('File size must be greater than 0.');
+        }
+
+        $startByte = 0;
+        $finalResponseBody = '';
+
+        while (!feof($fileResource)) {
+            $chunk = fread($fileResource, $chunkSize);
+            if ($chunk === false) {
+                throw new RuntimeException('Failed to read chunk from file stream.');
+            }
+
+            $chunkLength = strlen($chunk);
+            if ($chunkLength === 0) {
+                break;
+            }
+
+            $endByte = $startByte + $chunkLength - 1;
+
+            $chunkStream = $this->streamFactory->createStream($chunk);
+            $request = $this->requestFactory->createRequest('POST', $uploadUrl)
+                ->withBody($chunkStream)
+                ->withHeader('Content-Type', 'application/octet-stream')
+                ->withHeader('Content-Disposition', 'attachment; filename="' . $fileName . '"')
+                ->withHeader('Content-Range', "bytes {$startByte}-{$endByte}/{$fileSize}");
+
+            try {
+                $response = $this->httpClient->sendRequest($request);
+            } catch (ClientExceptionInterface $e) {
+                throw new NetworkException($e->getMessage(), $e->getCode(), $e);
+            }
+
+            $this->handleErrorResponse($response);
+
+            // The final response might contain the retval
+            $finalResponseBody = (string)$response->getBody();
+
+            $startByte += $chunkLength;
+        }
+
+        // According to docs, for video/audio the token is sent separately,
+        // and the upload response contains 'retval'. We return the body of the last response.
+        return $finalResponseBody;
+    }
+
     /**
      * Checks the response for an error status code and throws a corresponding typed exception.
      *

src/ClientApiInterface.php

@@ -7,6 +7,7 @@ namespace BushlanovDev\MaxMessengerBot;
 use BushlanovDev\MaxMessengerBot\Exceptions\ClientApiException;
 use BushlanovDev\MaxMessengerBot\Exceptions\NetworkException;
 use BushlanovDev\MaxMessengerBot\Exceptions\SerializationException;
+use RuntimeException;
 
 interface ClientApiInterface
 {
@@ -37,5 +38,28 @@ interface ClientApiInterface
      * @throws NetworkException
      * @throws SerializationException
      */
-    public function upload(string $uri, mixed $fileContents, string $fileName): string;
+    public function multipartUpload(string $uri, mixed $fileContents, string $fileName): string;
+
+    /**
+     * Uploads a file in chunks using the resumable upload method.
+     * The caller is responsible for opening and closing the file resource.
+     *
+     * @param string $uploadUrl The target URL for the upload.
+     * @param resource $fileResource A stream resource pointing to the file.
+     * @param string $fileName The desired file name for the upload.
+     * @param int<1, max> $fileSize The total size of the file in bytes.
+     * @param int<1, max> $chunkSize The size of each chunk in bytes.
+     *
+     * @return string The body of the final response from the server.
+     * @throws NetworkException
+     * @throws ClientApiException
+     * @throws RuntimeException
+     */
+    public function resumableUpload(
+        string $uploadUrl,
+        $fileResource,
+        string $fileName,
+        int $fileSize,
+        int $chunkSize = 1048576,
+    ): string;
 }