feat: Add CommandFailedException for COPY/MOVE and APPEND, exposing command name, status, server text, and parsed completion code.

Signed-off-by: Sebastian Krupinski <krupinski01@gmail.com>

lib/Client/CommandFailedException.php

@@ -0,0 +1,48 @@
+<?php
+
+declare(strict_types=1);
+
+namespace KTXM\ProviderImap\Client;
+
+/**
+ * A server-reported unsuccessful tagged command completion.
+ */
+final class CommandFailedException extends ImapException
+{
+    /**
+     * @param ?array{name:string, arguments:list<string>, text:string} $responseCode
+     */
+    public function __construct(
+        private readonly string $command,
+        private readonly string $status,
+        private readonly string $text,
+        private readonly ?array $responseCode = null,
+    ) {
+        parent::__construct($command . ' failed: ' . $text);
+    }
+
+    public function command(): string
+    {
+        return $this->command;
+    }
+
+    public function status(): string
+    {
+        return $this->status;
+    }
+
+    public function text(): string
+    {
+        return $this->text;
+    }
+
+    /**
+     * The code from the tagged completion, if present.
+     *
+     * @return ?array{name:string, arguments:list<string>, text:string}
+     */
+    public function responseCode(): ?array
+    {
+        return $this->responseCode;
+    }
+}

lib/Client/Protocol/Command/AppendCommand.php

@@ -7,6 +7,7 @@ namespace KTXM\ProviderImap\Client\Protocol\Command;
 use KTXM\ProviderImap\Client\Protocol\Parser\ResponseCodeParser;
 use KTXM\ProviderImap\Client\Protocol\StringEncoder;
 use KTXM\ProviderImap\Client\ImapException;
+use KTXM\ProviderImap\Client\CommandFailedException;
 use KTXM\ProviderImap\Client\Protocol\RequestFrame;
 use KTXM\ProviderImap\Client\Protocol\Response\ContinuationResponse;
 use KTXM\ProviderImap\Client\Protocol\Response\TaggedResponse;
@@ -81,7 +82,12 @@ final class AppendCommand implements CommandInterface
 
             if ($response instanceof TaggedResponse) {
                 if (!$response->isOk()) {
-                    throw new ImapException('APPEND failed: ' . $response->text());
+                    throw new CommandFailedException(
+                        'APPEND',
+                        $response->status(),
+                        $response->text(),
+                        $this->responseCodeParser->parse($response->text()),
+                    );
                 }
 
                 return $this->parseAppendUid($response->text());

lib/Client/Protocol/Command/MessageTransferCommand.php

@@ -10,6 +10,7 @@ use KTXM\ProviderImap\Client\Result\MessageTransferResult;
 use KTXM\ProviderImap\Client\Protocol\Command\Argument\MessageTarget;
 use KTXM\ProviderImap\Client\Protocol\IdentifierMode;
 use KTXM\ProviderImap\Client\ImapException;
+use KTXM\ProviderImap\Client\CommandFailedException;
 use KTXM\ProviderImap\Client\Protocol\RequestFrame;
 use KTXM\ProviderImap\Client\Protocol\Response\TaggedResponse;
 use KTXM\ProviderImap\Client\Protocol\Response\UntaggedResponse;
@@ -113,7 +114,16 @@ final class MessageTransferCommand implements CommandInterface
                     $highestModSeq,
                 );
 
-                $result = new MessageTransferResult(
+                if (!$response->isOk()) {
+                    throw new CommandFailedException(
+                        $this->operation,
+                        $response->status(),
+                        $response->text(),
+                        $this->responseCodeParser->parse($response->text()),
+                    );
+                }
+
+                return new MessageTransferResult(
                     $response->status(),
                     $response->text(),
                     $responseCodes,
@@ -123,12 +133,6 @@ final class MessageTransferCommand implements CommandInterface
                     $expunged,
                     $vanished,
                 );
-
-                if (!$response->isOk()) {
-                    throw new ImapException($this->operation . ' failed: ' . $response->text());
-                }
-
-                return $result;
             }
         }