Implement service desk attachments API

src/Pagination/PaginatedQuery.php

@@ -34,19 +34,29 @@ class PaginatedQuery implements PaginatedQueryInterface
      */
     protected $parseItemCallback;
 
+    /**
+     * @var PaginatedQueryResultInterface<T>|null
+     */
+    protected $firstPageResult;
+
     /**
      * @param callable(array):object $queryCallback
      * The function performing the query and returning parsed result,
      * accepts the current pagination query parameters (can be passed to e.g. http_build_query).
      * @param callable(object):T $parseItemCallback
      * The function parsing the items,
      * accepts the item data and returns the object of type T.
+     * @param object|null $initialResponse The response with the results of the first page, if available.
      */
-    public function __construct(callable $queryCallback, callable $parseItemCallback)
+    public function __construct(callable $queryCallback, callable $parseItemCallback, $initialResponse = null)
     {
         $this->start = $this->initialIndex();
         $this->queryCallback = $queryCallback;
         $this->parseItemCallback = $parseItemCallback;
+
+        if ($initialResponse) {
+            $this->firstPageResult = $this->parseResponse($initialResponse);
+        }
     }
 
     public function getStart(): int
@@ -84,15 +94,9 @@ public function withLimit(int $limit)
      */
     public function execute(): PaginatedQueryResultInterface
     {
-        $response = (array) ($this->queryCallback)($this->getQueryParameters());
+        $response = ($this->queryCallback)($this->getQueryParameters());
 
-        return new PaginatedQueryResult(
-            $response['start'],
-            $response['limit'],
-            $response['size'],
-            $response['isLastPage'],
-            array_map($this->parseItemCallback, $response['values'])
-        );
+        return $this->parseResponse($response);
     }
 
     /**
@@ -101,7 +105,17 @@ public function execute(): PaginatedQueryResultInterface
      */
     public function allPages(): Generator
     {
-        $query = $this->withStart($this->initialIndex());
+        if ($this->firstPageResult) {
+            if ($this->firstPageResult->getSize() !== 0) {
+                yield $this->firstPageResult;
+            }
+
+            if ($this->firstPageResult->isLastPage()) {
+                return;
+            }
+        }
+
+        $query = $this->withStart($this->initialIndex() + ($this->firstPageResult ? $this->firstPageResult->getSize() : 0));
 
         while (true) {
             $result = $query->execute();
@@ -116,7 +130,7 @@ public function allPages(): Generator
                 break;
             }
 
-            $query = $query->withStart($query->getStart() + $this->getLimit());
+            $query = $query->withStart($query->getStart() + $result->getSize());
         }
     }
 
@@ -128,6 +142,22 @@ protected function getQueryParameters(): array
         ];
     }
 
+    /**
+     * @param array|object $response
+     * @return PaginatedQueryResultInterface<T>
+     */
+    protected function parseResponse($response): PaginatedQueryResultInterface {
+        $response = (array) $response;
+
+        return new PaginatedQueryResult(
+            $response['start'],
+            $response['limit'],
+            $response['size'],
+            $response['isLastPage'],
+            array_map($this->parseItemCallback, $response['values'])
+        );
+    }
+
     protected function initialIndex(): int
     {
         return 0;

src/ServiceDesk/Attachment/Attachment.php

@@ -0,0 +1,77 @@
+<?php
+
+namespace JiraRestApi\ServiceDesk\Attachment;
+
+use JiraRestApi\ServiceDesk\Date\DateInterface;
+use JiraRestApi\ServiceDesk\User\UserInterface;
+
+/**
+ * Attachment in a customer request. AttachmentDTO from the JIRA Service Desk API.
+ */
+class Attachment implements AttachmentInterface
+{
+    /** @var string */
+    protected $fileName;
+
+    /** @var UserInterface */
+    protected $author;
+
+    /** @var DateInterface */
+    protected $created;
+
+    /** @var int */
+    protected $size;
+
+    /** @var string */
+    protected $mimeType;
+
+    public function getFileName(): string
+    {
+        return $this->fileName;
+    }
+
+    public function setFilename(string $fileName): void
+    {
+        $this->fileName = $fileName;
+    }
+
+    public function getAuthor(): UserInterface
+    {
+        return $this->author;
+    }
+
+    public function setAuthor(UserInterface $author): void
+    {
+        $this->author = $author;
+    }
+
+    public function getCreated(): DateInterface
+    {
+        return $this->created;
+    }
+
+    public function setCreated(DateInterface $created): void
+    {
+        $this->created = $created;
+    }
+
+    public function getSize(): int
+    {
+        return $this->size;
+    }
+
+    public function setSize(int $size): void
+    {
+        $this->size = $size;
+    }
+
+    public function getMimeType(): string
+    {
+        return $this->mimeType;
+    }
+
+    public function setMimeType(string $mimeType): void
+    {
+        $this->mimeType = $mimeType;
+    }
+}

src/ServiceDesk/Attachment/AttachmentCreationResult.php

@@ -0,0 +1,42 @@
+<?php
+
+namespace JiraRestApi\ServiceDesk\Attachment;
+
+use JiraRestApi\Pagination\PaginatedQueryInterface;
+use JiraRestApi\ServiceDesk\Comment\CommentInterface;
+
+/**
+ * Info about a comment with attachments. AttachmentCreateResultDTO from the JIRA Service Desk API.
+ */
+class AttachmentCreationResult implements AttachmentCreationResultInterface
+{
+    /** @var CommentInterface */
+    protected $comment;
+
+    /** @var PaginatedQueryInterface<AttachmentInterface> */
+    protected $attachmentsQuery;
+
+    /**
+     * @param CommentInterface $comment
+     * @param PaginatedQueryInterface<AttachmentInterface> $attachmentsQuery
+     */
+    public function __construct(CommentInterface $comment, PaginatedQueryInterface $attachmentsQuery)
+    {
+        $this->comment = $comment;
+        $this->attachmentsQuery = $attachmentsQuery;
+    }
+
+    public function getComment(): CommentInterface
+    {
+        return $this->comment;
+    }
+
+    /**
+     * @inheritDoc
+     * @return PaginatedQueryInterface<AttachmentInterface>
+     */
+    public function getAttachmentsQuery(): PaginatedQueryInterface
+    {
+        return $this->attachmentsQuery;
+    }
+}

src/ServiceDesk/Attachment/AttachmentCreationResultInterface.php

@@ -0,0 +1,24 @@
+<?php
+
+namespace JiraRestApi\ServiceDesk\Attachment;
+
+use JiraRestApi\Pagination\PaginatedQueryInterface;
+use JiraRestApi\ServiceDesk\Comment\CommentInterface;
+
+/**
+ * Info about a comment with attachments. AttachmentCreateResultDTO from the JIRA Service Desk API.
+ */
+interface AttachmentCreationResultInterface
+{
+    /**
+     * Returns the comment included with the attachments.
+     * @return CommentInterface
+     */
+    public function getComment(): CommentInterface;
+
+    /**
+     * Returns paginated query allowing to retrieve info about all attachments.
+     * @return PaginatedQueryInterface<AttachmentInterface>
+     */
+    public function getAttachmentsQuery(): PaginatedQueryInterface;
+}

src/ServiceDesk/Attachment/AttachmentInterface.php

@@ -0,0 +1,40 @@
+<?php
+
+namespace JiraRestApi\ServiceDesk\Attachment;
+
+use JiraRestApi\ServiceDesk\Date\DateInterface;
+use JiraRestApi\ServiceDesk\User\UserInterface;
+
+/**
+ * Attachment in a customer request. AttachmentDTO from the JIRA Service Desk API.
+ */
+interface AttachmentInterface
+{
+    /**
+     * @return string
+     */
+    public function getFileName(): string;
+
+    /**
+     * @return UserInterface
+     */
+    public function getAuthor(): UserInterface;
+
+    /**
+     * Returns date the attachment was added.
+     * @return DateInterface
+     */
+    public function getCreated(): DateInterface;
+
+    /**
+     * Returns size of the attachment in bytes.
+     * @return int
+     */
+    public function getSize(): int;
+
+    /**
+     * Returns MIME type of the attachment.
+     * @return string
+     */
+    public function getMimeType(): string;
+}

src/ServiceDesk/Attachment/TemporaryFile.php

@@ -0,0 +1,38 @@
+<?php
+
+namespace JiraRestApi\ServiceDesk\Attachment;
+
+use JiraRestApi\ServiceDesk\Date\DateInterface;
+use JiraRestApi\ServiceDesk\User\UserInterface;
+
+/**
+ * Temporary file that was uploaded and can be used for attachments.
+ */
+class TemporaryFile implements TemporaryFileInterface
+{
+    /** @var string */
+    protected $temporaryAttachmentId;
+
+    /** @var string */
+    protected $fileName;
+
+    public function getTemporaryAttachmentId(): string
+    {
+        return $this->temporaryAttachmentId;
+    }
+
+    public function setTemporaryAttachmentId(string $temporaryAttachmentId): void
+    {
+        $this->temporaryAttachmentId = $temporaryAttachmentId;
+    }
+
+    public function getFileName(): string
+    {
+        return $this->fileName;
+    }
+
+    public function setFileName(string $fileName): void
+    {
+        $this->fileName = $fileName;
+    }
+}

src/ServiceDesk/Attachment/TemporaryFileInterface.php

@@ -0,0 +1,13 @@
+<?php
+
+namespace JiraRestApi\ServiceDesk\Attachment;
+
+/**
+ * Temporary file that was uploaded and can be used for attachments.
+ */
+interface TemporaryFileInterface
+{
+    public function getTemporaryAttachmentId(): string;
+
+    public function getFileName(): string;
+}

src/ServiceDesk/RequestService.php

@@ -4,6 +4,11 @@
 
 use JiraRestApi\Configuration\ConfigurationInterface;
 use JiraRestApi\JiraClient;
+use JiraRestApi\Pagination\PaginatedQuery;
+use JiraRestApi\ServiceDesk\Attachment\Attachment;
+use JiraRestApi\ServiceDesk\Attachment\AttachmentCreationResult;
+use JiraRestApi\ServiceDesk\Attachment\AttachmentCreationResultInterface;
+use JiraRestApi\ServiceDesk\Attachment\AttachmentInterface;
 use JiraRestApi\ServiceDesk\Comment\Comment;
 use JiraRestApi\ServiceDesk\Comment\CommentInterface;
 use JiraRestApi\ServiceDesk\Date\Date;
@@ -101,6 +106,42 @@ public function createComment($issueIdOrKey, string $body, bool $public): Commen
         );
     }
 
+    public function createAttachment(
+        $issueIdOrKey,
+        array $temporaryAttachmentIds,
+        bool $public,
+        string $additionalComment = null
+    ): AttachmentCreationResultInterface
+    {
+        $data = ['temporaryAttachmentIds' => $temporaryAttachmentIds, 'public' => $public];
+        if ($additionalComment) {
+            $data['additionalComment'] = ['body' => $additionalComment];
+        }
+
+        $ret = $this->exec($this->issueUri($issueIdOrKey) . '/attachment', json_encode($data));
+
+        $result = json_decode($ret);
+
+        $this->json_mapper->classMap[UserInterface::class] = User::class;
+        $this->json_mapper->classMap[DateInterface::class] = Date::class;
+
+        /** @var Comment $comment */
+        $comment = $this->json_mapper->map($result->comment, new Comment());
+
+        return new AttachmentCreationResult(
+            $comment,
+            new PaginatedQuery(function (array $paginationQuery) use ($issueIdOrKey, $comment) {
+                $this->allowExperimentalApi();
+
+                $response = $this->exec($this->issueUri($issueIdOrKey) . '/comment/' . $comment->getId() . '/attachment'
+                    . '?' . http_build_query($paginationQuery));
+                return json_decode($response);
+            }, function ($itemData): AttachmentInterface {
+                return $this->json_mapper->map($itemData, new Attachment());
+            }, $result->attachments)
+        );
+    }
+
     protected function issueUri(string $id): string {
         return $this->uri . "/$id";
     }