Merge pull request 'feat: mail entity download' (#32) from feat/mail-entity-download into main

Reviewed-on: #32

lib/Client/Client.php

@@ -6,8 +6,8 @@ namespace KTXM\ProviderImap\Client;
 
 use KTXM\ProviderImap\Client\Command\CapabilityCommand;
 use KTXM\ProviderImap\Client\Command\CommandInterface;
+use KTXM\ProviderImap\Client\FetchTarget;
 use KTXM\ProviderImap\Client\Command\LoginCommand;
-use KTXM\ProviderImap\Client\Command\StatusCommand;
 use KTXM\ProviderImap\Client\Command\StartTlsCommand;
 use KTXM\ProviderImap\Client\Protocol\CommandExecutor;
 use KTXM\ProviderImap\Client\Protocol\ProtocolReader;
@@ -87,6 +87,15 @@ final class Client implements ClientInterface
         return $this->executor->perform($command, $this->session);
     }
 
+    public function download(FetchTarget $target, string $section, int $chunkSize = 8192): \Generator
+    {
+        if ($this->session === null || $this->executor === null) {
+            throw new ImapException('IMAP client is not connected.');
+        }
+
+        return $this->executor->download($target, $section, $chunkSize, $this->session);
+    }
+
     public function session(): SessionContext
     {
         if ($this->session === null) {

lib/Client/ClientInterface.php

@@ -5,6 +5,7 @@ declare(strict_types=1);
 namespace KTXM\ProviderImap\Client;
 
 use KTXM\ProviderImap\Client\Command\CommandInterface;
+use KTXM\ProviderImap\Client\FetchTarget;
 
 interface ClientInterface
 {
@@ -21,4 +22,11 @@ interface ClientInterface
      * @return TResult
      */
     public function perform(CommandInterface $command): mixed;
+
+    /**
+     * Stream the raw bytes of a single IMAP BODY section without buffering.
+     *
+     * @return \Generator<string>  raw (transfer-encoded) bytes from the socket
+     */
+    public function download(FetchTarget $target, string $section, int $chunkSize = 8192): \Generator;
 }

lib/Client/Command/StoreCommand.php

@@ -28,9 +28,9 @@ final class StoreCommand implements CommandInterface
      */
     public function __construct(
         FetchTarget|string|SequenceSet|null $target = null,
-        private readonly array $flags = [],
-        private readonly string $action = '',
-        private readonly bool $silent = true,
+        private array $flags = [],
+        private string $action = '',
+        private bool $silent = true,
     ) {
         $resolvedTarget = match (true) {
             $target instanceof FetchTarget => $target,

lib/Client/FetchOptions.php

@@ -89,6 +89,11 @@ final class FetchOptions
         return $this->with('BODY[TEXT]');
     }
 
+    public function withBody(): self
+    {
+        return $this->with('BODY[]');
+    }
+
     public function withBodySection(string $section): self
     {
         $section = strtoupper(trim($section));

lib/Client/Message.php

@@ -156,6 +156,11 @@ final class Message
         return $this->bodySections;
     }
 
+    public function bodyRaw(): ?string
+    {
+        return $this->bodySections[''] ?? null;
+    }
+
     /**
      * @param array<string, string> $bodySections
      */

lib/Client/MessageParser.php

@@ -524,9 +524,6 @@ final class MessageParser
             }
 
             $section = strtoupper(trim($matches[1]));
-            if ($section === '') {
-                continue;
-            }
 
              if (preg_match('/^(\d+(?:\.\d+)*)\.TEXT$/', $section, $partMatches) === 1) {
                 $section = $partMatches[1];

lib/Client/MessagePart.php

@@ -167,8 +167,9 @@ final class MessagePart
     {
         $data = [
             'partId' => $this->partId,
+            'blobId' => $this->partId,
+            'cId' => $this->contentId,
             'type' => $this->mimeType,
-            'blobId' => $this->contentId,
             'charset' => $this->parameters['charset'] ?? null,
             'name' => $this->parameters['name'] ?? $this->dispositionParameters['filename'] ?? null,
             'encoding' => $this->encoding,

lib/Client/Protocol/CommandExecutor.php

@@ -6,9 +6,11 @@ namespace KTXM\ProviderImap\Client\Protocol;
 
 use Generator;
 use KTXM\ProviderImap\Client\Command\CommandInterface;
+use KTXM\ProviderImap\Client\FetchTarget;
 use KTXM\ProviderImap\Client\ImapException;
 use KTXM\ProviderImap\Client\Protocol\Response\TaggedResponse;
 use KTXM\ProviderImap\Client\Protocol\Response\UntaggedResponse;
+use KTXM\ProviderImap\Client\Protocol\RequestFrame;
 use KTXM\ProviderImap\Client\SessionContext;
 use KTXM\ProviderImap\Client\SessionState;
 use Psr\Log\LoggerInterface;
@@ -41,10 +43,42 @@ final class CommandExecutor
         $this->writer->write($tag, $frame);
 
         return $command->handle(new ResponseStream(function () use ($tag, $context): Generator {
-            yield from $this->responsesUntilCompletion($tag, $context);
+            yield from $this->processPerform($tag, $context);
         }), $context);
     }
 
+    /**
+     * Stream the raw bytes of a single IMAP BODY section without buffering.
+     *
+     * Sends a UID FETCH for the given section and yields the literal bytes
+     * directly from the socket in chunks, never assembling a full string.
+     * The caller MUST fully exhaust the returned Generator before issuing
+     * any further IMAP commands.
+     *
+     * @return \Generator<string>  raw (transfer-encoded) bytes from the socket
+     */
+    public function download(FetchTarget $target, string $section, int $chunkSize, SessionContext $context): \Generator
+    {
+        $this->assertState([SessionState::Selected], $context->state(), 'FETCH (download)');
+
+        $tag = $this->tags->next();
+        $this->writer->write($tag, new RequestFrame(sprintf(
+            'UID FETCH %s (UID BODY[%s])',
+            $target->sequenceSet()->toCommand(),
+            $section,
+        )));
+
+        $result = $this->reader->readUntilFetchLiteral($tag);
+
+        if ($result === null) {
+            return; // UID not found or empty FETCH result
+        }
+
+        yield from $this->reader->streamLiteral($result['literalLength'], $chunkSize);
+
+        $this->reader->readToEnd($tag);
+    }
+
     /**
      * @param list<SessionState> $allowedStates
      */
@@ -63,7 +97,7 @@ final class CommandExecutor
         ));
     }
 
-    private function responsesUntilCompletion(string $tag, SessionContext $context): Generator
+    private function processPerform(string $tag, SessionContext $context): Generator
     {
         while (true) {
             $response = $this->reader->readResponse();

lib/Client/Protocol/ProtocolReader.php

@@ -42,7 +42,14 @@ final class ProtocolReader
 
     public function readResponse(): ResponseInterface
     {
-        $raw = $this->readRawResponse();
+        $raw = $this->connection->readLine();
+
+        while (($literalLength = $this->trailingLiteralLength($raw)) !== null) {
+            $raw .= $this->connection->readBytes($literalLength);
+            $raw .= $this->connection->readLine();
+        }
+
+        $raw = $this->trimTrailingLineEnding($raw);
 
         if ($raw === '') {
             throw new ImapException('Received empty IMAP response line.');
@@ -85,16 +92,72 @@ final class ProtocolReader
         return new TaggedResponse($parts[0], $status, $parts[2] ?? '', $raw);
     }
 
-    private function readRawResponse(): string
+    /**
+     * Read responses until an untagged FETCH response containing a literal marker is found,
+     * returning the literal byte count WITHOUT consuming the literal bytes from the socket.
+     * Returns null if the tagged OK/NO/BAD for $tag arrives before any literal is detected.
+     *
+     * ⚠️ After a non-null return the literal bytes MUST be consumed (via streamLiteral())
+     * before any further reads are made on this reader.
+     *
+     * @return array{literalLength: int, prefixLine: string}|null
+     */
+    public function readUntilFetchLiteral(string $tag): ?array
     {
-        $raw = $this->connection->readLine();
+        while (true) {
+            $line = $this->connection->readLine();
+            $trimmed = $this->trimTrailingLineEnding($line);
 
-        while (($literalLength = $this->trailingLiteralLength($raw)) !== null) {
-            $raw .= $this->connection->readBytes($literalLength);
-            $raw .= $this->connection->readLine();
+            // Literal marker at the end of the line — stop before consuming the bytes
+            $literalLength = $this->trailingLiteralLength($line);
+            if ($literalLength !== null) {
+                return ['literalLength' => $literalLength, 'prefixLine' => $trimmed];
+            }
+
+            // Tagged completion for our command
+            if (str_starts_with($trimmed, $tag . ' ')) {
+                $parts = preg_split('/\s+/', $trimmed, 3) ?: [];
+                $status = strtoupper($parts[1] ?? '');
+                if ($status === 'NO' || $status === 'BAD') {
+                    throw new ImapException(sprintf('FETCH command failed: %s', $trimmed));
+                }
+                return null; // Tagged OK without ever finding a literal → UID not found
+            }
+
+            // Any other untagged response — discard and continue
         }
+    }
 
-        return $this->trimTrailingLineEnding($raw);
+    public function readToEnd(string $tag): TaggedResponse
+    {
+        while (true) {
+            $response = $this->readResponse();
+
+            if ($response instanceof TaggedResponse && $response->tag() === $tag) {
+                if (!$response->isOk()) {
+                    throw new ImapException(sprintf('FETCH failed: %s', $response->text()));
+                }
+                return $response;
+            }
+        }
+    }
+
+    /**
+     * Yield the literal bytes already waiting in the socket as chunks.
+     * After the generator is fully exhausted this method reads the one trailing
+     * line that closes the FETCH parenthesised response (e.g. ")\r\n").
+     *
+     * Contract: the caller MUST exhaust this generator before issuing any further
+     * reads on this reader.
+     *
+     * @return \Generator<string>
+     */
+    public function streamLiteral(int $length, int $chunkSize = 8192): \Generator
+    {
+        yield from $this->connection->readBytesChunked($length, $chunkSize);
+
+        // Consume the closing portion of the FETCH parenthesised list (e.g. ")\r\n")
+        $this->connection->readLine();
     }
 
     private function trailingLiteralLength(string $raw): ?int

lib/Client/Transport/ConnectionInterface.php

@@ -20,5 +20,13 @@ interface ConnectionInterface
 
     public function readBytes(int $length): string;
 
+    /**
+     * Yield the literal payload in chunks without buffering the full content.
+     * Reads exactly $length bytes from the socket, never crossing the literal boundary.
+     *
+     * @return \Generator<string>
+     */
+    public function readBytesChunked(int $length, int $chunkSize = 8192): \Generator;
+
     public function upgradeToTls(): void;
 }

lib/Client/Transport/SocketConnection.php

@@ -135,6 +135,26 @@ final class SocketConnection implements ConnectionInterface
         return $buffer;
     }
 
+    public function readBytesChunked(int $length, int $chunkSize = 8192): \Generator
+    {
+        if ($length < 0) {
+            throw new ImapException('IMAP socket cannot read a negative number of bytes.');
+        }
+
+        $remaining = $length;
+
+        while ($remaining > 0) {
+            $chunk = fread($this->stream(), min($chunkSize, $remaining));
+
+            if ($chunk === false || $chunk === '') {
+                throw new ImapException('Failed to read literal payload from IMAP socket.');
+            }
+
+            $remaining -= strlen($chunk);
+            yield $chunk;
+        }
+    }
+
     public function upgradeToTls(): void
     {
         $stream = $this->stream();

lib/Providers/MessageAttachment.php

@@ -9,12 +9,14 @@ declare(strict_types=1);
 
 namespace KTXM\ProviderImap\Providers;
 
+use KTXF\Mail\Object\MessagePartInterface;
+
 /**
  * Mail Attachment Object
  *
  * @since 1.0.0
  */
-class MessageAttachment implements \KTXF\Mail\Object\MessagePartInterface {
+class MessageAttachment implements MessagePartInterface {
 
     protected MessagePart $_meta;
     protected ?string $_contents = null;

lib/Providers/MessagePart.php

@@ -9,10 +9,8 @@ declare(strict_types=1);
 
 namespace KTXM\ProviderImap\Providers;
 
-use Gricob\IMAP\Protocol\Response\Line\Data\Fetch\BodyStructure\MultiPart;
-use Gricob\IMAP\Protocol\Response\Line\Data\Fetch\BodyStructure\Part;
-use Gricob\IMAP\Protocol\Response\Line\Data\Fetch\BodyStructure\SinglePart;
 use KTXF\Mail\Object\MessagePartMutableAbstract;
+use KTXM\ProviderImap\Client\MessagePart as ImapMessagePart;
 
 /**
  * Mail Message Part Implementation
@@ -25,7 +23,7 @@ class MessagePart extends MessagePartMutableAbstract {
      * @param Part $part gricob BodyStructure Part (SinglePart or MultiPart)
      * @param string $partId numeric part identifier (e.g. "1", "1.1", "2")
      */
-    public function fromImap(Part $part, string $partId = '1'): static {
+    public function fromImap(ImapMessagePart $part, string $partId = '1'): static {
 
         $this->data['partId'] = $partId;
 
@@ -104,82 +102,4 @@ class MessagePart extends MessagePartMutableAbstract {
         return $this;
     }
 
-    /**
-     * Convert message part to store array
-     */
-    public function toStore(): array {
-        $data = $this->data;
-        if (count($this->parts) > 0) {
-            $data['subParts'] = [];
-            foreach ($this->parts as $subPart) {
-                if ($subPart instanceof MessagePart) {
-                    $data['subParts'][] = $subPart->toStore();
-                }
-            }
-        } else {
-            $data['subParts'] = null;
-        }
-        return $data;
-    }
-
-    /**
-     * Hydrate message part from store array
-     */
-    public function fromStore(array $data): static {
-        if (isset($data['subParts']) && is_array($data['subParts'])) {
-            foreach ($data['subParts'] as $subPart) {
-                $this->parts[] = (new MessagePart())->fromStore($subPart);
-            }
-            unset($data['subParts']);
-        }
-        $this->data = $data;
-        return $this;
-    }
-
-    /**
-     * Inject decoded body content from a map of IMAP section-ID → raw encoded text.
-     *
-     * Walks the MessagePart tree recursively. For each text/* leaf part whose
-     * partId is present in $sectionMap the raw text is decoded according to the
-     * part's Content-Transfer-Encoding and converted to UTF-8 before being
-     * stored in 'content'. Binary parts (images, PDFs, …) are skipped.
-     *
-     * @param array<string,string> $sectionMap  Keys: IMAP section IDs (e.g. "1", "1.2");
-     *                                           Values: raw (transfer-encoded) body text
-     */
-    public function injectSections(array $sectionMap): void
-    {
-        // MultiPart: recurse into children
-        if (!empty($this->parts)) {
-            foreach ($this->parts as $childPart) {
-                if ($childPart instanceof MessagePart) {
-                    $childPart->injectSections($sectionMap);
-                }
-            }
-            return;
-        }
-
-        // SinglePart: only inject decoded content for text/* MIME types
-        $type = strtolower($this->data['type'] ?? '');
-        if (!str_starts_with($type, 'text/')) {
-            return;
-        }
-
-        $partId = $this->data['partId'] ?? null;
-        if ($partId === null || !array_key_exists($partId, $sectionMap)) {
-            return;
-        }
-
-        $raw = $sectionMap[$partId];
-        $encoding = strtolower($this->data['encoding'] ?? '7bit');
-        $decoded = match ($encoding) {
-            'quoted-printable' => quoted_printable_decode($raw),
-            'base64'           => base64_decode($raw, strict: false),
-            default            => $raw, // 7bit, 8bit, binary
-        };
-
-        $charset = $this->data['charset'] ?? 'us-ascii';
-        $this->data['content'] = MessageProperties::toUtf8($decoded, $charset);
-    }
-
 }

lib/Providers/Provider.php

@@ -27,7 +27,6 @@ use KTXM\ProviderImap\Stores\ServiceStore;
 class Provider implements ProviderBaseInterface, ProviderServiceMutateInterface, ProviderServiceDiscoverInterface, ProviderServiceTestInterface
 {
 
-    public const JSON_TYPE = ProviderBaseInterface::JSON_TYPE;
     protected const PROVIDER_IDENTIFIER  = 'imap';
     protected const PROVIDER_LABEL       = 'IMAP Mail Provider';
     protected const PROVIDER_DESCRIPTION = 'Provides mail services via the IMAP protocol';
@@ -195,7 +194,7 @@ class Provider implements ProviderBaseInterface, ProviderServiceMutateInterface,
             // Attempt to authenticate and list mailboxes as a connectivity check
             $client  = RemoteService::freshClient($service);
             $service = RemoteService::mailService($service, $client);
-            $mailboxes = $service->collectionList();
+            $mailboxes = iterator_to_array($service->collectionList());
 
             $latency = (int) round((microtime(true) - $startTime) * 1000);
 
@@ -206,36 +205,9 @@ class Provider implements ProviderBaseInterface, ProviderServiceMutateInterface,
                     . ' (Latency: ' . $latency . ' ms)',
             ];
         } catch (\Throwable $e) {
-            $latency = (int) round((microtime(true) - $startTime) * 1000);
-
-            $location = ($service instanceof Service) ? $service->getLocation() : null;
-            $target   = $location
-                ? $location->getEncryption() . '://' . $location->getHost() . ':' . $location->getPort()
-                : 'unknown host';
-
-            // stream_socket_client errors are suppressed with @ in gricob — recover them
-            $phpError = error_get_last();
-            $detail   = $e->getMessage() !== '' ? $e->getMessage() : ($phpError['message'] ?? '');
-
-            if ($detail === '' && $location !== null) {
-                $host = $location->getHost();
-                if ($host !== '' && gethostbyname($host) === $host) {
-                    $detail = "hostname '{$host}' could not be resolved";
-                } else {
-                    $detail = 'connection refused or timed out — check port and encryption settings';
-                }
-            } elseif ($detail === '') {
-                $detail = 'no details — check host, port, and encryption settings';
-            }
-
             return [
                 'success' => false,
-                'message' => sprintf(
-                    'Connection to %s failed (%s): %s',
-                    $target,
-                    (new \ReflectionClass($e))->getShortName(),
-                    $detail,
-                ),
+                'message' => 'Test failed: ' . $e->getMessage(),
             ];
         }
     }

lib/Providers/Service.php

@@ -11,7 +11,6 @@ namespace KTXM\ProviderImap\Providers;
 
 use Generator;
 use KTXF\Mail\Collection\CollectionBaseInterface;
-use KTXF\Mail\Collection\CollectionMutableInterface;
 use KTXF\Mail\Collection\CollectionPropertiesBaseInterface;
 use KTXF\Mail\Object\Address;
 use KTXF\Mail\Object\AddressInterface;
@@ -20,6 +19,7 @@ use KTXF\Mail\Service\ServiceCollectionMutableInterface;
 use KTXF\Mail\Service\ServiceEntityMutableInterface;
 use KTXF\Mail\Service\ServiceConfigurableInterface;
 use KTXF\Mail\Service\ServiceMutableInterface;
+use KTXF\Resource\BinaryResource;
 use KTXF\Resource\Provider\ResourceServiceIdentityInterface;
 use KTXF\Resource\Provider\ResourceServiceLocationInterface;
 use KTXF\Resource\Delta\Delta;
@@ -40,8 +40,9 @@ use KTXM\ProviderImap\Service\Remote\RemoteService;
 use KTXM\ProviderImap\Providers\CollectionResource;
 use KTXF\Mail\Collection\CollectionRoles;
 use KTXF\Mail\Object\MessagePropertiesMutableInterface;
-use KTXF\Mail\Service\ServiceEntityMutableInterface;
+use KTXF\Resource\Identifier\EntityIdentifierInterface;
 use KTXM\ProviderImap\Providers\EntityResource;
+use KTXM\ProviderImap\Client\Mailbox;
 
 /**
  * IMAP Mail Service
@@ -62,20 +63,23 @@ class Service implements ServiceBaseInterface, ServiceMutableInterface, ServiceC
     private array $auxiliary = [];
 
     private array $serviceAbilities = [
-        self::CAPABILITY_COLLECTION_LIST   => true,
+        self::CAPABILITY_COLLECTION_LIST => true,
         self::CAPABILITY_COLLECTION_LIST_FILTER => [
             self::CAPABILITY_COLLECTION_FILTER_LABEL => 's:128:256:256',
             self::CAPABILITY_COLLECTION_FILTER_ROLE => 's:32:1:1',
             self::CAPABILITY_COLLECTION_FILTER_SUBSCRIBED => 'b:0:1:1',
         ],
-        self::CAPABILITY_COLLECTION_LIST_SORT   => [],
-        self::CAPABILITY_COLLECTION_EXTANT => true,
+        self::CAPABILITY_COLLECTION_LIST_SORT => [
+            self::CAPABILITY_COLLECTION_SORT_LABEL,
+            self::CAPABILITY_COLLECTION_SORT_RANK,
+        ],
         self::CAPABILITY_COLLECTION_FETCH  => true,
+        self::CAPABILITY_COLLECTION_EXTANT => true,
         self::CAPABILITY_COLLECTION_CREATE => true,
         self::CAPABILITY_COLLECTION_UPDATE => true,
         self::CAPABILITY_COLLECTION_DELETE => true,
-        self::CAPABILITY_COLLECTION_MOVE   => true,
-        self::CAPABILITY_ENTITY_LIST       => true,
+        self::CAPABILITY_COLLECTION_MOVE => true,
+        self::CAPABILITY_ENTITY_LIST => true,
         self::CAPABILITY_ENTITY_LIST_FILTER => [
             self::CAPABILITY_ENTITY_FILTER_FROM => 's:100:256:256',
             self::CAPABILITY_ENTITY_FILTER_TO => 's:100:256:256',
@@ -86,56 +90,62 @@ class Service implements ServiceBaseInterface, ServiceMutableInterface, ServiceC
             self::CAPABILITY_ENTITY_FILTER_SIZE_MIN => 'i:0:16:16',
             self::CAPABILITY_ENTITY_FILTER_SIZE_MAX => 'i:0:32:32',
         ],
-        self::CAPABILITY_ENTITY_LIST_SORT   => [],
-        self::CAPABILITY_ENTITY_LIST_RANGE  => ['tally' => ['absolute', 'relative']],
-        self::CAPABILITY_ENTITY_EXTANT     => true,
-        self::CAPABILITY_ENTITY_FETCH      => true,
-        self::CAPABILITY_ENTITY_CREATE     => false,
-        self::CAPABILITY_ENTITY_MODIFY     => false,
-        self::CAPABILITY_ENTITY_DELETE     => true,
-        self::CAPABILITY_ENTITY_MOVE       => true,
-        self::CAPABILITY_ENTITY_COPY       => false,
+        self::CAPABILITY_ENTITY_LIST_SORT => [
+            self::CAPABILITY_ENTITY_SORT_FROM,
+            self::CAPABILITY_ENTITY_SORT_TO,
+            self::CAPABILITY_ENTITY_SORT_SUBJECT,
+            self::CAPABILITY_ENTITY_SORT_DATE_RECEIVED,
+            self::CAPABILITY_ENTITY_SORT_DATE_SENT,
+            self::CAPABILITY_ENTITY_SORT_SIZE,
+        ],
+        self::CAPABILITY_ENTITY_LIST_RANGE  => [
+            'tally' => ['absolute', 'relative']
+        ],
+        self::CAPABILITY_ENTITY_FETCH => true,
+        self::CAPABILITY_ENTITY_EXTANT => true,
+        self::CAPABILITY_ENTITY_CREATE => false,
+        self::CAPABILITY_ENTITY_MODIFY => false,
+        self::CAPABILITY_ENTITY_PATCH => true,
+        self::CAPABILITY_ENTITY_DELETE => true,
+        self::CAPABILITY_ENTITY_MOVE => true,
+        self::CAPABILITY_ENTITY_COPY => false,
     ];
 
-    private RemoteMailService $mailService;
+    private RemoteMailService $remoteService;
 
     public function __construct() {}
 
-    // ── Lazy initialisation ───────────────────────────────────────────────────
-
     private function initialize(): void
     {
-        if (!isset($this->mailService)) {
+        if (!isset($this->remoteService)) {
             $wrapper = RemoteService::freshClient($this);
-            $this->mailService = RemoteService::mailService($this, $wrapper);
+            $this->remoteService = RemoteService::mailService($this, $wrapper);
         }
     }
 
-    // ── Store (MongoDB persistence) ───────────────────────────────────────────
-
     public function toStore(): array
     {
         return array_filter([
-            'tid'               => $this->serviceTenantId,
-            'uid'               => $this->serviceUserId,
-            'sid'               => $this->serviceIdentifier,
-            'label'             => $this->serviceLabel,
-            'enabled'           => $this->serviceEnabled,
-            'primaryAddress'    => $this->primaryAddress,
+            'tid' => $this->serviceTenantId,
+            'uid' => $this->serviceUserId,
+            'sid' => $this->serviceIdentifier,
+            'enabled' => $this->serviceEnabled,
+            'label' => $this->serviceLabel,
+            'primaryAddress' => $this->primaryAddress,
             'secondaryAddresses'=> $this->secondaryAddresses,
-            'location'          => $this->location?->toStore(),
-            'identity'          => $this->identity?->toStore(),
-            'auxiliary'         => $this->auxiliary,
+            'location' => $this->location?->toStore(),
+            'identity' => $this->identity?->toStore(),
+            'auxiliary' => $this->auxiliary,
         ], fn($v) => $v !== null);
     }
 
     public function fromStore(array $data): static
     {
-        $this->serviceTenantId   = $data['tid'] ?? null;
-        $this->serviceUserId     = $data['uid'] ?? null;
+        $this->serviceTenantId = $data['tid'] ?? null;
+        $this->serviceUserId = $data['uid'] ?? null;
         $this->serviceIdentifier = $data['sid'] ?? null;
-        $this->serviceLabel      = $data['label'] ?? '';
-        $this->serviceEnabled    = $data['enabled'] ?? false;
+        $this->serviceLabel = $data['label'] ?? '';
+        $this->serviceEnabled = $data['enabled'] ?? false;
 
         if (isset($data['primaryAddress'])) {
             $this->primaryAddress = $data['primaryAddress'];
@@ -156,22 +166,20 @@ class Service implements ServiceBaseInterface, ServiceMutableInterface, ServiceC
         return $this;
     }
 
-    // ── JSON ──────────────────────────────────────────────────────────────────
-
     public function jsonSerialize(): array
     {
         return array_filter([
-            self::JSON_PROPERTY_TYPE             => self::JSON_TYPE,
-            self::JSON_PROPERTY_PROVIDER         => self::PROVIDER_IDENTIFIER,
-            self::JSON_PROPERTY_IDENTIFIER       => $this->serviceIdentifier,
-            self::JSON_PROPERTY_LABEL            => $this->serviceLabel,
-            self::JSON_PROPERTY_ENABLED          => $this->serviceEnabled,
-            self::JSON_PROPERTY_CAPABILITIES     => $this->serviceAbilities,
+            self::JSON_PROPERTY_TYPE => self::JSON_TYPE,
+            self::JSON_PROPERTY_PROVIDER => self::PROVIDER_IDENTIFIER,
+            self::JSON_PROPERTY_IDENTIFIER => $this->serviceIdentifier,
+            self::JSON_PROPERTY_LABEL => $this->serviceLabel,
+            self::JSON_PROPERTY_ENABLED => $this->serviceEnabled,
+            self::JSON_PROPERTY_CAPABILITIES => $this->serviceAbilities,
             self::JSON_PROPERTY_PRIMARY_ADDRESS  => $this->primaryAddress,
             self::JSON_PROPERTY_SECONDARY_ADDRESSES => $this->secondaryAddresses,
-            self::JSON_PROPERTY_LOCATION         => $this->location?->jsonSerialize(),
-            self::JSON_PROPERTY_IDENTITY         => $this->identity?->jsonSerialize(),
-            self::JSON_PROPERTY_AUXILIARY        => $this->auxiliary,
+            self::JSON_PROPERTY_LOCATION => $this->location?->jsonSerialize(),
+            self::JSON_PROPERTY_IDENTITY => $this->identity?->jsonSerialize(),
+            self::JSON_PROPERTY_AUXILIARY => $this->auxiliary,
         ], fn($v) => $v !== null);
     }
 
@@ -181,12 +189,12 @@ class Service implements ServiceBaseInterface, ServiceMutableInterface, ServiceC
             $data = json_decode($data, true, 512, JSON_THROW_ON_ERROR);
         }
 
-        if (isset($data[self::JSON_PROPERTY_LABEL])) {
-            $this->setLabel($data[self::JSON_PROPERTY_LABEL]);
-        }
         if (isset($data[self::JSON_PROPERTY_ENABLED])) {
             $this->setEnabled($data[self::JSON_PROPERTY_ENABLED]);
         }
+        if (isset($data[self::JSON_PROPERTY_LABEL])) {
+            $this->setLabel($data[self::JSON_PROPERTY_LABEL]);
+        }
         if (isset($data[self::JSON_PROPERTY_LOCATION])) {
             $this->setLocation($this->freshLocation(null, $data[self::JSON_PROPERTY_LOCATION]));
         }
@@ -209,8 +217,6 @@ class Service implements ServiceBaseInterface, ServiceMutableInterface, ServiceC
         return $this;
     }
 
-    // ── ServiceBaseInterface ──────────────────────────────────────────────────
-
     public function capable(string $value): bool
     {
         return isset($this->serviceAbilities[$value]);
@@ -231,8 +237,6 @@ class Service implements ServiceBaseInterface, ServiceMutableInterface, ServiceC
         return $this->serviceIdentifier;
     }
 
-    // ── ServiceMutableInterface ───────────────────────────────────────────────
-
     public function getLabel(): ?string
     {
         return $this->serviceLabel;
@@ -295,8 +299,6 @@ class Service implements ServiceBaseInterface, ServiceMutableInterface, ServiceC
         
     }
 
-    // ── ServiceConfigurableInterface ──────────────────────────────────────────
-
     public function getLocation(): ServiceLocation
     {
         return $this->location;
@@ -355,15 +357,13 @@ class Service implements ServiceBaseInterface, ServiceMutableInterface, ServiceC
         return $this;
     }
 
-    // ── Collection operations ─────────────────────────────────────────────────
-
     public function collectionList(string|int|null $location, ?IFilter $filter = null, ?ISort $sort = null): array
     {
         $this->initialize();
         
         $list = [];
         
-        foreach ($this->mailService->collectionList($location, $filter, $sort) as $mailbox) {
+        foreach ($this->remoteService->collectionList($location, $filter, $sort) as $mailbox) {
             $resource = $this->collectionFresh();
             $resource->fromImap($mailbox);
             $list[$mailbox->name()] = $resource;
@@ -390,7 +390,7 @@ class Service implements ServiceBaseInterface, ServiceMutableInterface, ServiceC
 
         foreach ($identifiers as $identifier) {
             $key = (string) $identifier;
-            $result = $this->mailService->collectionFetch($key);
+            $result = $this->remoteService->collectionFetch($key);
 
             $list[$key] = $result !== false;
         }
@@ -398,11 +398,11 @@ class Service implements ServiceBaseInterface, ServiceMutableInterface, ServiceC
         return $list;
     }
 
-    public function collectionFetch(string|int $identifier): ?CollectionBaseInterface
+    public function collectionFetch(string|int $identifier): ?CollectionResource
     {
         $this->initialize();
         
-        $mailbox = $this->mailService->collectionFetch((string) $identifier);
+        $mailbox = $this->remoteService->collectionFetch((string) $identifier);
         if ($mailbox === null) {
             return null;
         }
@@ -431,13 +431,13 @@ class Service implements ServiceBaseInterface, ServiceMutableInterface, ServiceC
         if ($target !== null) {
             $path = $target->collection();
             // Determine the hierarchy delimiter from an existing mailbox, default to '/'
-            $mailboxes = iterator_to_array($this->mailService->collectionList(null, null, null, ''));
+            $mailboxes = iterator_to_array($this->remoteService->collectionList(null, null, null, ''));
             $rootMailbox = $mailboxes === [] ? null : reset($mailboxes);
             $delimiter = $rootMailbox === false ? '/' : ($rootMailbox?->delimiter() ?? '/');
             $label = rtrim((string) $path, $delimiter) . $delimiter . ltrim($label, $delimiter);
         }
 
-        $mailbox = $this->mailService->collectionCreate($label);
+        $mailbox = $this->remoteService->collectionCreate($label);
 
         $collection = $this->collectionFresh();
         $collection->fromImap($mailbox, ['delimiter' => $delimiter ?? null]);
@@ -457,7 +457,7 @@ class Service implements ServiceBaseInterface, ServiceMutableInterface, ServiceC
         // In IMAP, "update" = rename to the new label
         $oldPath = (string) $target->collection();
         $newName = $properties->getLabel();
-        $mailbox = $this->mailService->collectionRename($oldPath, $newName);
+        $mailbox = $this->remoteService->collectionRename($oldPath, $newName);
 
         $collection = $this->collectionFresh();
         $collection->fromImap($mailbox);
@@ -477,14 +477,14 @@ class Service implements ServiceBaseInterface, ServiceMutableInterface, ServiceC
 
         // Move to target collection (e.g. Trash) instead of deleting
         if ($deleteMode === 'soft' && $deleteTarget !== null) {
-            return $this->collectionMove($target, new CollectionIdentifier($target->provider(), $target->service(), $deleteTarget));
+            return $this->collectionMove(new CollectionIdentifier($target->provider(), $target->service(), $deleteTarget), $target);
         }
 
         if ($deleteMode === 'soft' && $deleteTarget === null) {
             $filter = $this->collectionListFilter();
             $filter->condition('role', CollectionRoles::Trash->value);
 
-            $mailboxes = iterator_to_array($this->mailService->collectionList(null, $filter, null));
+            $mailboxes = iterator_to_array($this->remoteService->collectionList(null, $filter, null));
             if (empty($mailboxes)) {
                 throw new \RuntimeException('No Trash collection configured or found for deletion');
             }
@@ -499,8 +499,8 @@ class Service implements ServiceBaseInterface, ServiceMutableInterface, ServiceC
         }
 
         $result = match ($deleteMode) {
-            'soft' => $this->collectionMove($target, new CollectionIdentifier($target->provider(), $target->service(), $deleteTarget)),
-            'hard' => $this->mailService->collectionDestroy((string) $target->collection()),
+            'soft' => $this->collectionMove(new CollectionIdentifier($target->provider(), $target->service(), $deleteTarget), $target),
+            'hard' => $this->remoteService->collectionDestroy((string) $target->collection()),
         };
         return $result;
     }
@@ -509,8 +509,8 @@ class Service implements ServiceBaseInterface, ServiceMutableInterface, ServiceC
     {
         $this->initialize();
         
-        $sourceMailbox = $this->mailService->collectionFetch((string) $source->collection());
-        $targetMailbox = $this->mailService->collectionFetch((string) $target->collection());
+        $sourceMailbox = $this->remoteService->collectionFetch((string) $source->collection());
+        $targetMailbox = $this->remoteService->collectionFetch((string) $target->collection());
         if ($sourceMailbox === null) {
              throw new \RuntimeException('Source collection not found for move operation');
         }
@@ -521,29 +521,31 @@ class Service implements ServiceBaseInterface, ServiceMutableInterface, ServiceC
         $sourceDelimiter = $sourceMailbox->delimiter() ?? '/';
         $targetDelimiter = $targetMailbox->delimiter() ?? '/';
 
-        $targetPath = rtrim($targetMailbox->name(), $targetDelimiter) . $targetDelimiter . end(explode($sourceDelimiter, $sourceMailbox->name()));
-        $mutatedMailbox = $this->mailService->collectionRename($sourceMailbox->name(), $targetPath);
+        $extantPath = $sourceMailbox->name();
+        $extantPathLeafs = explode($sourceDelimiter, rtrim($extantPath, $sourceDelimiter));
+
+        $freshPath = rtrim($targetMailbox->name(), $targetDelimiter) . $targetDelimiter . end($extantPathLeafs);
+
+        $mutatedMailbox = $this->remoteService->collectionRename($extantPath, $freshPath);
 
         $collection = $this->collectionFresh();
         $collection->fromImap($mutatedMailbox, ['delimiter' => $targetDelimiter]);
         return $collection;
     }
 
-    // ── Entity operations ─────────────────────────────────────────────────────
-
-    public function entityList(string|int $collection, ?IFilter $filter = null, ?ISort $sort = null, ?IRange $range = null, ?array $properties = null): array
+    public function entityListBulk(string|int $collection, ?IFilter $filter = null, ?ISort $sort = null, ?IRange $range = null, ?array $properties = null): array
     {
-        return iterator_to_array($this->entityList((string) $collection, $filter, $sort, $range), true);
+        return iterator_to_array($this->entityListStream((string) $collection, $filter, $sort, $range), true);
     }
 
     public function entityListStream(string|int $collection, ?IFilter $filter = null, ?ISort $sort = null, ?IRange $range = null, ?array $properties = null): Generator
     {
         $this->initialize();
 
-        foreach ($this->mailService->entityList((string) $collection, $filter, $sort, $range) as $identifier => $message) {
+        foreach ($this->remoteService->entityList((string) $collection, $filter, $sort, $range) as $identifier => $message) {
             $resource = $this->entityFresh();
             $resource->fromImap($message, $collection);
-            yield $identifier => $resource;
+            yield $resource->urn() => $resource;
         }
     }
 
@@ -565,12 +567,35 @@ class Service implements ServiceBaseInterface, ServiceMutableInterface, ServiceC
         };
     }
     
-    public function entityFetch(string|int $collection, string|int ...$identifiers): array 
+    public function entityFetchBulk(EntityIdentifierInterface ...$identifiers): array
+    {
+        return iterator_to_array($this->entityFetchStream(...$identifiers), true);
+    }
+
+    public function entityFetchStream(EntityIdentifierInterface ...$identifiers): Generator
     {
         $this->initialize();
 
-        $uids = array_map('intval', $identifiers);
-        return $this->mailService->entityFetch((string) $collection, ...$uids);
+        $identifiers = $this->groupEntitiesByCollection(...$identifiers);
+
+        foreach ($identifiers as $collection => $entities) {
+            $uids = array_keys($entities);
+            foreach ($this->remoteService->entityFetch((string) $collection, ...$uids) as $uid => $message) {
+                $resource = $this->entityFresh();
+                $resource->fromImap($message, $collection);
+                yield $resource->urn() => $resource;
+            }
+        }
+    }
+
+    public function entityDownload(EntityIdentifierInterface $target, array|null $part): BinaryResource {
+        $this->initialize();
+
+        $collection = $target->collection();
+        $uid        = (int) $target->entity();
+        $partId     = isset($part['partId']) ? (string) $part['partId'] : null;
+
+        return $this->remoteService->entityDownload($collection, $uid, $partId);
     }
 
     public function entityDelta(string|int $collection, string $signature, string $detail = 'ids'): Delta
@@ -582,7 +607,7 @@ class Service implements ServiceBaseInterface, ServiceMutableInterface, ServiceC
     {
         $this->initialize();
 
-        $allUids = $this->mailService->entityList((string) $collection);
+        $allUids = $this->remoteService->entityList((string) $collection);
         $uidSet  = array_flip($allUids);  // int[] → [uid => index]
         $extant  = [];
         foreach ($identifiers as $id) {
@@ -606,6 +631,39 @@ class Service implements ServiceBaseInterface, ServiceMutableInterface, ServiceC
         throw new \RuntimeException('Entity modification is not supported in this service');
     }
 
+    public function entityPatch(MessagePropertiesMutableInterface $properties, EntityIdentifier ...$targets): array
+    {
+        // validate identifiers and group by collection
+        $targets = $this->groupEntitiesByCollection(...$targets);
+
+         // move entities on remote store and construct result map
+        $this->initialize();
+        
+        $list = [];
+
+        foreach ($targets as $targetCollection => $targetIdentifiers) {
+            $uids = array_keys($targetIdentifiers);
+            $flagsAdd = [];
+            $flagsRemove = [];
+
+            foreach ($properties->getFlags() as $flag => $value) {
+                if ($value === true) {
+                    $flagsAdd[] = $flag;
+                } elseif ($value === false) {
+                    $flagsRemove[] = $flag;
+                }
+            }
+
+            $mutations = $this->remoteService->entityPatch($targetCollection, $flagsAdd, $flagsRemove, ...$uids);
+
+            foreach ($uids as $uid) {
+                $list[(string)$targetIdentifiers[$uid]] = ['disposition' => 'patched'];
+            }
+        }
+
+        return $list;
+    }
+
     public function entityDelete(EntityIdentifier ...$targets): array
     {
         // validate identifiers and group by collection
@@ -627,23 +685,29 @@ class Service implements ServiceBaseInterface, ServiceMutableInterface, ServiceC
             $filter = $this->collectionListFilter();
             $filter->condition('role', CollectionRoles::Trash->value);
 
-            $mailboxes = iterator_to_array($this->mailService->collectionList(null, $filter, null));
+            /** @var Mailbox[] $mailboxes */
+            $mailboxes = iterator_to_array($this->remoteService->collectionList(null, $filter, null));
             if (empty($mailboxes)) {
                 throw new \RuntimeException('No Trash collection configured or found for deletion');
             }
 
-            $rootMailbox = reset($mailboxes);
-            if ($rootMailbox === false) {
+            $targetMailbox = reset($mailboxes);
+            if ($targetMailbox === false) {
                 throw new \RuntimeException('No Trash collection configured or found for deletion');
             }
 
-            $deleteTargetNative = $rootMailbox->name();
+            $deleteTargetNative = $targetMailbox->name();
             $deleteTargetIdentifier = new CollectionIdentifier($this->provider(), (string) $this->identifier(), $deleteTargetNative);
         } else {
             $deleteTargetNative = $deleteTarget;
             $deleteTargetIdentifier = new CollectionIdentifier($this->provider(), (string) $this->identifier(), $deleteTargetNative);
         }
 
+        // if all targets are already in the delete target collection, we should hard delete instead of moving to avoid duplicates in the trash
+        if (array_keys($targets) === [$deleteTargetNative]) {
+            $deleteMode = 'hard';
+        }
+
         // entities need to be moved or deleted by collection
         $list = [];
         foreach ($targets as $sourceCollection => $sourceEntities) {
@@ -654,77 +718,16 @@ class Service implements ServiceBaseInterface, ServiceMutableInterface, ServiceC
             $uids = array_keys($sourceEntities);
 
             $mutations = match ($deleteMode) {
-                'soft' => $this->mailService->entityMove($deleteTargetNative, $sourceCollection, ...$uids),
-                'hard' => $this->mailService->entityDestroy($sourceCollection, ...$uids),
+                'soft' => $this->remoteService->entityMove($deleteTargetNative, $sourceCollection, ...$uids),
+                'hard' => $this->remoteService->entityDestroy($sourceCollection, ...$uids),
             };
 
             foreach ($uids as $uid) {
-                $mutatedUid = $mutations[$uid] ?? null;
+                $mutatedUid = !isset($mutations[$uid]) || $mutations[$uid] === true ? null : $mutations[$uid];
                 $list[(string)$sourceEntities[$uid]] = [
                     'disposition' => $deleteMode === 'soft' ? 'moved' : 'deleted',
                     'destination' => $deleteMode === 'soft' ? $deleteTargetIdentifier : null,
-                    'mutation' => $mutatedUid !== null ? new EntityIdentifier($this->provider(), $this->identifier(), $deleteTargetIdentifier->collection(), $mutatedUid) : null,
-                ];
-            }
-        }
-
-        return $list;
-    }
-
-    public function entityPatch(MessagePropertiesMutableInterface $properties, EntityIdentifier ...$targets): array
-    {
-        throw new \RuntimeException('Entity patching is not supported in this service');
-    }
-
-    public function entityPatch(MessagePropertiesMutableInterface $properties, EntityIdentifier ...$targets): array
-    {
-        // validate identifiers and group by collection
-        $targets = $this->groupEntitiesByCollection(...$targets);
-
-         // move entities on remote store and construct result map
-        $this->initialize();
-        
-        $list = [];
-
-        foreach ($targets as $targetCollection => $targetIdentifiers) {
-            $uids = array_keys($targetIdentifiers);
-
-            $mutations = $this->mailService->entityPatch($targetCollection, $properties, ...$uids);
-
-            foreach ($uids as $uid) {
-                $list[(string)$targetIdentifiers[$uid]] = ['disposition' => 'patched'];
-            }
-        }
-
-        return $list;
-    }
-
-    public function entityCopy(CollectionIdentifier $target, EntityIdentifier ...$sources): array
-    {
-        // validate target belongs to this service
-        if ($target->provider() !== $this->provider() || $target->service() !== $this->identifier()) {
-            throw new \InvalidArgumentException('Target collection does not belong to this service: ' . $target);
-        }
-
-        // validate identifiers and group by collection
-        $sources = $this->groupEntitiesByCollection(...$sources);
-
-        // copy entities on remote store and construct result map
-        $this->initialize();
-
-        $list = [];
-        
-        foreach ($sources as $sourceCollection => $sourceEntities) {
-            $uids = array_keys($sourceEntities);
-
-            $mutations = $this->mailService->entityCopy($target->collection(), $sourceCollection, ...$uids);
-
-            foreach ($uids as $uid) {
-                $mutatedUid = $mutations[$uid] ?? null;
-                $list[(string)$sourceEntities[$uid]] = [
-                    'disposition' => $mutatedUid !== null ? 'copied' : 'error',
-                    'destination' => $target,
-                    'mutation' => $mutatedUid !== null ? new EntityIdentifier($this->provider(), $this->identifier(), $target->collection(), $mutatedUid) : null,
+                    'mutation' => $deleteMode === 'soft' && $mutatedUid !== null ? new EntityIdentifier($this->provider(), $this->identifier(), $deleteTargetIdentifier->collection(), $mutatedUid) : null,
                 ];
             }
         }
@@ -750,7 +753,7 @@ class Service implements ServiceBaseInterface, ServiceMutableInterface, ServiceC
         foreach ($sources as $sourceCollection => $sourceEntities) {
             $uids = array_keys($sourceEntities);
 
-            $mutations = $this->mailService->entityMove($target->collection(), $sourceCollection, ...$uids);
+            $mutations = $this->remoteService->entityMove($target->collection(), $sourceCollection, ...$uids);
 
             foreach ($uids as $uid) {
                 $mutatedUid = $mutations[$uid] ?? null;
@@ -759,15 +762,44 @@ class Service implements ServiceBaseInterface, ServiceMutableInterface, ServiceC
                     'destination' => $target,
                     'mutation' => $mutatedUid !== null ? new EntityIdentifier($this->provider(), $this->identifier(), $target->collection(), $mutatedUid) : null,
                 ];
+                unset($sourceEntities[$uid]);
             }
         }
 
         return $list;
     }
 
-    public function entityCopy(CollectionIdentifier $target, EntityIdentifier ...$sources): array 
+    public function entityCopy(CollectionIdentifier $target, EntityIdentifier ...$sources): array
     {
-        throw new \RuntimeException('Entity copying is not supported in this service');
+        // validate target belongs to this service
+        if ($target->provider() !== $this->provider() || $target->service() !== $this->identifier()) {
+            throw new \InvalidArgumentException('Target collection does not belong to this service: ' . $target);
+        }
+
+        // validate identifiers and group by collection
+        $sources = $this->groupEntitiesByCollection(...$sources);
+
+        // copy entities on remote store and construct result map
+        $this->initialize();
+
+        $list = [];
+        
+        foreach ($sources as $sourceCollection => $sourceEntities) {
+            $uids = array_keys($sourceEntities);
+
+            $mutations = $this->remoteService->entityCopy($target->collection(), $sourceCollection, ...$uids);
+
+            foreach ($uids as $uid) {
+                $mutatedUid = $mutations[$uid] ?? null;
+                $list[(string)$sourceEntities[$uid]] = [
+                    'disposition' => $mutatedUid !== null ? 'copied' : 'error',
+                    'destination' => $target,
+                    'mutation' => $mutatedUid !== null ? new EntityIdentifier($this->provider(), $this->identifier(), $target->collection(), $mutatedUid) : null,
+                ];
+            }
+        }
+
+        return $list;
     }
 
     private function groupEntitiesByCollection(EntityIdentifier ...$identifiers): array

lib/Service/Remote/RemoteMailService.php

@@ -13,6 +13,7 @@ use DateTimeImmutable;
 use Generator;
 use KTXM\ProviderImap\Client\Client;
 use KTXM\ProviderImap\Client\Command\FetchManyCommand;
+use KTXM\ProviderImap\Client\Command\FetchOneCommand;
 use KTXM\ProviderImap\Client\Command\ExpungeCommand;
 use KTXM\ProviderImap\Client\Command\ListCommand;
 use KTXM\ProviderImap\Client\Command\SearchCommand;
@@ -45,8 +46,7 @@ use KTXF\Resource\Range\IRangeTally;
 use KTXF\Resource\Range\RangeAnchorType;
 use KTXF\Resource\Range\RangeTally;
 use KTXF\Resource\Sort\ISort;
-use KTXM\ProviderImap\Providers\CollectionResource;
-use KTXM\ProviderImap\Providers\EntityResource;
+use KTXF\Resource\BinaryResource;
 
 /**
  * IMAP Remote Mail Service
@@ -295,6 +295,116 @@ class RemoteMailService
         }
     }
 
+    /**
+     * Stream the raw bytes of a message or a specific MIME part without buffering.
+     *
+     * When $partId is given, first fetches BODYSTRUCTURE to determine the
+     * correct filename and MIME type, then starts the streaming body fetch.
+     *
+     * @param string      $collection  Mailbox name
+     * @param int         $uid         Message UID
+     * @param string|null $partId      MIME section (e.g. '1', '1.2'); null = full RFC 822
+     */
+    public function entityDownload(string $collection, int $uid, ?string $partId = null): BinaryResource
+    {
+        $this->client->perform(new SelectCommand($collection, true));
+
+        $encoding = null;
+
+        if ($partId === null) {
+            $filename = 'message.eml';
+            $mimeType = 'message/rfc822';
+        } else {
+            // Fetch BODYSTRUCTURE first to determine metadata (no body bytes transferred)
+            $message = $this->client->perform(new FetchOneCommand(
+                FetchTarget::uid(SequenceSet::items($uid)),
+                FetchOptions::of('BODYSTRUCTURE'),
+            ));
+            $bodyStructure = $message->bodyStructure();
+            $part          = $bodyStructure !== null ? $this->findBodyPart($bodyStructure, $partId) : null;
+            $mimeType      = $part?->mimeType() ?? 'application/octet-stream';
+            $partData      = $part?->toArray() ?? [];
+            $filename      = isset($partData['name']) && $partData['name'] !== ''
+                ? $partData['name']
+                : "attachment-{$partId}";
+            $encoding      = $part?->encoding();
+        }
+
+        // Start download stream
+        $stream = $this->decodeStream(
+            $this->client->download(FetchTarget::uid(SequenceSet::items($uid)), $partId ?? ''),
+            $encoding
+        );
+
+        return new BinaryResource($filename, $mimeType, $stream);
+    }
+
+    private function findBodyPart(MessagePart $root, string $partId): ?MessagePart
+    {
+        if ($root->partId() === $partId) {
+            return $root;
+        }
+        foreach ($root->parts() as $child) {
+            $found = $this->findBodyPart($child, $partId);
+            if ($found !== null) {
+                return $found;
+            }
+        }
+        return null;
+    }
+
+    /**
+     * Wraps a raw IMAP body stream with a transfer-encoding decoder.
+     *
+     * IMAP BODY[n] literals are delivered in the transfer encoding declared
+     * by BODYSTRUCTURE (typically base64 or quoted-printable for attachments).
+     * 7bit / 8bit / binary sections pass through unchanged.
+     */
+    private function decodeStream(\Generator $stream, ?string $encoding): \Generator
+    {
+        return match (strtolower($encoding ?? '')) {
+            'base64'           => $this->decodeBase64Stream($stream),
+            'quoted-printable' => $this->decodeQpStream($stream),
+            default            => $stream,
+        };
+    }
+
+    private function decodeBase64Stream(\Generator $source): \Generator
+    {
+        $buffer = '';
+        foreach ($source as $chunk) {
+            // IMAP folds base64 at 76 chars with CRLF — strip all whitespace
+            $buffer .= preg_replace('/\s+/', '', $chunk);
+            // Decode complete 4-character groups; keep any partial tail
+            $remainder = strlen($buffer) % 4;
+            $complete  = strlen($buffer) - $remainder;
+            if ($complete > 0) {
+                yield base64_decode(substr($buffer, 0, $complete), true);
+                $buffer = substr($buffer, $complete);
+            }
+        }
+        // Flush remainder (handles padded or stripped trailing '=')
+        if ($buffer !== '') {
+            yield base64_decode($buffer, true);
+        }
+    }
+
+    private function decodeQpStream(\Generator $source): \Generator
+    {
+        // Buffer until we have complete lines so soft-line-breaks are intact
+        $buffer = '';
+        foreach ($source as $chunk) {
+            $buffer .= $chunk;
+            while (($pos = strpos($buffer, "\n")) !== false) {
+                yield quoted_printable_decode(substr($buffer, 0, $pos + 1));
+                $buffer = substr($buffer, $pos + 1);
+            }
+        }
+        if ($buffer !== '') {
+            yield quoted_printable_decode($buffer);
+        }
+    }
+
     /**
      * Append a raw RFC 822 message to a mailbox and return the assigned UID.
      *
@@ -353,6 +463,9 @@ class RemoteMailService
 
         $this->client->perform(new SelectCommand($collection, false));
 
+        $flagsToAdd = $this->normalizeFlags($flagsToAdd);
+        $flagsToRemove = $this->normalizeFlags($flagsToRemove);
+
         if (!empty($flagsToAdd)) {
             $this->client->perform(new StoreCommand(
                 FetchTarget::uid(SequenceSet::items(...array_values($uids))),
@@ -422,6 +535,36 @@ class RemoteMailService
 
     }
 
+    public function entityCopy(string $targetCollection, string $sourceCollection, int ...$uids): array
+    {
+        if (empty($uids)) {
+            return [];
+        }
+
+        $this->client->perform(new SelectCommand($sourceCollection, false));
+        $response = $this->client->perform(new CopyCommand(
+            FetchTarget::uid(SequenceSet::items(...array_values($uids))),
+            $targetCollection,
+        ));
+
+        if (!$response->isOk()) {
+            throw new ImapException('Failed to copy messages: ' . implode(', ', $response->responseCodes()));
+        }
+
+        // construct operation result as a map of source UID to boolean or destination UID, depending on server support
+        $map = $response->copyUidMap();
+        if ($map === []) {
+            $result = array_fill_keys(array_map('strval', $uids), true);
+        } else {
+            $result = array_fill_keys(array_map('strval', $uids), false);
+            foreach ($uids as $uid) {
+                $result[$uid] = $map[$uid] ?? false;
+            }
+        }
+
+        return $result;
+    }
+
     private function buildEntitySearchCriteria(?IFilter $filter): SearchCriteriaBuilder
     {
         if ($filter === null || $filter->conditions() === []) {
@@ -869,4 +1012,23 @@ class RemoteMailService
 
         return CollectionRoles::None->value;
     }
+
+    private function normalizeFlags(array $flags): array
+    {
+        $map = [
+            'read' => '\\Seen',
+            'answered' => '\\Answered',
+            'flagged' => '\\Flagged',
+            'deleted' => '\\Deleted',
+            'draft' => '\\Draft',
+        ];
+        $normalized = [];
+        foreach ($flags as $flag) {
+            $flag = strtolower(trim($flag));
+            if (isset($map[$flag])) {
+                $normalized[] = $map[$flag];
+            }
+        }
+        return $normalized;
+    }
 }

package.json

@@ -22,8 +22,8 @@
   "devDependencies": {
     "@vitejs/plugin-vue": "^6.0.1",
     "@vue/tsconfig": "^0.9.0",
-    "typescript": "~5.8.3",
-    "vite": "^7.1.2",
+    "typescript": "~6.0.0",
+    "vite": "^8.0.0",
     "vue-tsc": "^3.0.5"
   }
 }