chore(deps): update dependency vite to v8.0.16

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

@@ -15,42 +15,21 @@ final class FetchOptions
 
     public static function default(): self
     {
-        return self::message();
-    }
-
-    public static function summary(): self
-    {
-        return new self([
-            'UID',
-            'FLAGS',
-            'INTERNALDATE',
-            'RFC822.SIZE',
-        ]);
+        return (new self([]))
+            ->withUid()
+            ->withFlags()
+            ->withInternalDate()
+            ->withSize();
     }
 
     public static function message(): self
     {
-        return self::summary()
+        return self::default()
+            ->withHeaders()
             ->withEnvelope()
             ->withBodyStructure();
     }
 
-    public static function fullMessage(): self
-    {
-        return self::message()->withBodyText();
-    }
-
-    public function withBodySection(string $section): self
-    {
-        $section = strtoupper(trim($section));
-
-        if ($section === '') {
-            return $this;
-        }
-
-        return $this->with(sprintf('BODY[%s]', $section));
-    }
-
     public static function of(string ...$items): self
     {
         return new self(self::normalize($items));
@@ -76,6 +55,25 @@ final class FetchOptions
         return $this->with('RFC822.SIZE');
     }
 
+    public function withHeaders(): self
+    {
+        return $this->with('BODY[HEADER]');
+    }
+
+    public function withHeader(string ...$fields): self
+    {
+        $fields = array_values(array_filter(array_map(
+            static fn (string $field): string => strtoupper(trim($field)),
+            $fields,
+        ), static fn (string $field): bool => $field !== ''));
+
+        if ($fields === []) {
+            return $this;
+        }
+
+        return $this->with(sprintf('BODY.PEEK[HEADER.FIELDS (%s)]', implode(' ', $fields)));
+    }
+
     public function withEnvelope(): self
     {
         return $this->with('ENVELOPE');
@@ -88,21 +86,23 @@ final class FetchOptions
 
     public function withBodyText(): self
     {
-        return $this->withBodySection('TEXT');
+        return $this->with('BODY[TEXT]');
     }
 
-    public function withHeaderFields(string ...$fields): self
+    public function withBody(): self
     {
-        $fields = array_values(array_filter(array_map(
-            static fn (string $field): string => strtoupper(trim($field)),
-            $fields,
-        ), static fn (string $field): bool => $field !== ''));
+        return $this->with('BODY[]');
+    }
 
-        if ($fields === []) {
+    public function withBodySection(string $section): self
+    {
+        $section = strtoupper(trim($section));
+
+        if ($section === '') {
             return $this;
         }
 
-        return $this->with(sprintf('BODY.PEEK[HEADER.FIELDS (%s)]', implode(' ', $fields)));
+        return $this->with(sprintf('BODY[%s]', $section));
     }
 
     public function with(string $item): self

lib/Client/Message.php

@@ -21,6 +21,7 @@ final class Message
         private readonly int $uid,
         private readonly int $size,
         private readonly ?string $internalDate,
+        private readonly ?string $receivedAt,
         private readonly array $flags,
         private readonly ?string $subject,
         private readonly ?string $sentAt,
@@ -56,6 +57,11 @@ final class Message
         return $this->internalDate;
     }
 
+    public function receivedAt(): ?string
+    {
+        return $this->receivedAt;
+    }
+
     /**
      * @return list<string>
      */
@@ -139,7 +145,7 @@ final class Message
 
     public function bodyText(): ?string
     {
-        return $this->bodyText;
+        return $this->bodySections['TEXT'] ?? null;
     }
 
     /**
@@ -150,6 +156,11 @@ final class Message
         return $this->bodySections;
     }
 
+    public function bodyRaw(): ?string
+    {
+        return $this->bodySections[''] ?? null;
+    }
+
     /**
      * @param array<string, string> $bodySections
      */
@@ -160,6 +171,7 @@ final class Message
             $this->uid,
             $this->size,
             $this->internalDate,
+            $this->receivedAt,
             $this->flags,
             $this->subject,
             $this->sentAt,

lib/Client/MessageParser.php

@@ -4,6 +4,8 @@ declare(strict_types=1);
 
 namespace KTXM\ProviderImap\Client;
 
+use DateTimeInterface;
+
 final class MessageParser
 {
     public static function isFetchMessage(string $payload): bool
@@ -23,12 +25,14 @@ final class MessageParser
         $envelope = is_array($attributes['ENVELOPE'] ?? null) ? $attributes['ENVELOPE'] : null;
         $bodyStructure = isset($attributes['BODYSTRUCTURE']) ? self::parseBodyPart($attributes['BODYSTRUCTURE'], '') : null;
         $bodySections = self::parseBodySections($attributes, $bodyStructure);
+        $headers = self::parseFetchedHeaders($attributes);
 
         return new Message(
             $sequence,
             $uid,
             self::toOptionalInt($attributes['RFC822.SIZE'] ?? null) ?? 0,
             self::toNullableString($attributes['INTERNALDATE'] ?? null),
+            self::extractReceivedAt($headers),
             self::parseFlags($attributes['FLAGS'] ?? null),
             self::decodeMimeHeader(self::envelopeString($envelope, 1)),
             self::envelopeString($envelope, 0),
@@ -258,6 +262,127 @@ final class MessageParser
         return is_string($value) && $value !== '' ? $value : null;
     }
 
+    /**
+     * @param array<string, mixed> $attributes
+     * @return array<string, list<string>>
+     */
+    private static function parseFetchedHeaders(array $attributes): array
+    {
+        $headers = [];
+
+        foreach ($attributes as $name => $value) {
+            if (!is_string($value)) {
+                continue;
+            }
+
+            if (!preg_match('/^BODY(?:\.PEEK)?\[(.+)\]$/i', $name, $matches)) {
+                continue;
+            }
+
+            $section = strtoupper(trim($matches[1]));
+            if (!str_starts_with($section, 'HEADER')) {
+                continue;
+            }
+
+            foreach (self::parseHeaderBlock($value) as $headerName => $headerValues) {
+                $normalized = strtolower($headerName);
+                $headers[$normalized] ??= [];
+                array_push($headers[$normalized], ...$headerValues);
+            }
+        }
+
+        return $headers;
+    }
+
+    /**
+     * @return array<string, list<string>>
+     */
+    private static function parseHeaderBlock(string $headers): array
+    {
+        $parsed = [];
+        $currentName = null;
+        $currentValue = '';
+
+        foreach (preg_split("/\r\n|\n|\r/", $headers) ?: [] as $line) {
+            if ($line === '') {
+                break;
+            }
+
+            if (($line[0] === ' ' || $line[0] === "\t") && $currentName !== null) {
+                $currentValue .= ' ' . trim($line);
+                continue;
+            }
+
+            if ($currentName !== null) {
+                $parsed[$currentName] ??= [];
+                $parsed[$currentName][] = trim($currentValue);
+            }
+
+            $separator = strpos($line, ':');
+            if ($separator === false) {
+                $currentName = null;
+                $currentValue = '';
+                continue;
+            }
+
+            $currentName = substr($line, 0, $separator);
+            $currentValue = substr($line, $separator + 1);
+        }
+
+        if ($currentName !== null) {
+            $parsed[$currentName] ??= [];
+            $parsed[$currentName][] = trim($currentValue);
+        }
+
+        return $parsed;
+    }
+
+    /**
+     * @param array<string, list<string>> $headers
+     */
+    private static function extractReceivedAt(array $headers): ?string
+    {
+        foreach ($headers['delivery-date'] ?? [] as $value) {
+            $date = self::parseHeaderDate($value);
+            if ($date !== null) {
+                return $date;
+            }
+        }
+
+        foreach ($headers['received'] ?? [] as $value) {
+            $date = self::parseHeaderDateFromReceived($value);
+            if ($date !== null) {
+                return $date;
+            }
+        }
+
+        return null;
+    }
+
+    private static function parseHeaderDate(?string $value): ?string
+    {
+        $value = self::toNullableString($value);
+        if ($value === null) {
+            return null;
+        }
+
+        try {
+            return (new \DateTimeImmutable($value))->format(DateTimeInterface::ATOM);
+        } catch (\Exception) {
+            return null;
+        }
+    }
+
+    private static function parseHeaderDateFromReceived(string $value): ?string
+    {
+        $separator = strrpos($value, ';');
+        if ($separator === false) {
+            return self::parseHeaderDate($value);
+        }
+
+        return self::parseHeaderDate(substr($value, $separator + 1));
+    }
+
     private static function envelopeString(?array $envelope, int $index): ?string
     {
         if ($envelope === null) {
@@ -399,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/CollectionResource.php

@@ -91,12 +91,4 @@ class CollectionResource extends CollectionMutableAbstract
         return $this->properties;
     }
 
-    // ── JSON ─────────────────────────────────────────────────────────────────
-
-    public function jsonSerialize(): array
-    {
-        $data                      = $this->data;
-        $data['properties']        = $this->getProperties()->jsonSerialize();
-        return $data;
-    }
 }

lib/Providers/EntityResource.php

@@ -9,7 +9,6 @@ declare(strict_types=1);
 
 namespace KTXM\ProviderImap\Providers;
 
-use DateTimeInterface;
 use KTXM\ProviderImap\Client\Message;
 use KTXF\Mail\Entity\EntityMutableAbstract;
 
@@ -43,27 +42,6 @@ class EntityResource extends EntityMutableAbstract {
         return $this;
     }
 
-    /**
-     * Convert mail entity object to store array
-     */
-    public function toStore(): array {
-        return array_merge(
-            $this->data,
-            ['properties' => $this->getProperties()->toStore()]
-        );
-    }
-
-    /**
-     * Hydrate mail entity object from store array
-     */
-    public function fromStore(array $data): static {
-        $properties = $data['properties'] ?? [];
-        unset($data['properties']);
-        $this->data = $data;
-        $this->getProperties()->fromStore($properties);
-        return $this;
-    }
-
     /**
      * @inheritDoc
      */

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/MessageProperties.php

@@ -25,71 +25,74 @@ class MessageProperties extends MessagePropertiesMutableAbstract {
      */
     public function fromImap(Message $message): static
     {
-        $this->data['size'] = $message->size();
-
-        $this->data['flags'] = [];
-        foreach ($message->flags() as $flag) {
-            $flag = ltrim($flag, '\\');
-            $normalized = match (strtolower($flag)) {
-                'seen' => 'read',
-                'flagged' => 'flagged',
-                'answered' => 'answered',
-                'draft' => 'draft',
-                'deleted' => 'deleted',
-                default => strtolower($flag),
-            };
-            $this->data['flags'][$normalized] = true;
-        }
+        $this->data[static::PROPERTY_SIZE] = $message->size();
 
         if ($message->messageId() !== null) {
-            $this->data['urid'] = $message->messageId();
+            $this->data[static::PROPERTY_URID] = $message->messageId();
         }
 
-        if ($message->subject() !== null) {
-            $this->data['subject'] = $message->subject();
+        if ($message->inReplyTo() !== null) {
+            $this->data[static::PROPERTY_IN_REPLY_TO] = $message->inReplyTo();
+        }
+
+        //if ($message->references() !== []) {
+        //    $this->data[static::PROPERTY_REFERENCES] = $message->references();
+        //}
+
+        $receivedAt = $message->receivedAt() ?? $message->internalDate();
+        if ($receivedAt !== null) {
+            $date = new DateTimeImmutable($receivedAt);
+            $this->data[static::PROPERTY_RECEIVED] = $date->format(DateTimeInterface::ATOM);
         }
 
         if ($message->sentAt() !== null) {
             $date = new DateTimeImmutable($message->sentAt());
-            $this->data['date'] = $date->format(DateTimeInterface::ATOM);
-        }
-
-        if ($message->inReplyTo() !== null) {
-            $this->data['inReplyTo'] = $message->inReplyTo();
-        }
-
-        if ($message->from() !== []) {
-            $this->data['from'] = $message->from()[0]->toArray();
+            $this->data[static::PROPERTY_SENT] = $date->format(DateTimeInterface::ATOM);
         }
 
         if ($message->sender() !== []) {
-            $this->data['sender'] = $message->sender()[0]->toArray();
+            $this->data[static::PROPERTY_SENDER] = $message->sender()[0]->toArray();
         }
 
-        foreach (['to', 'cc', 'bcc', 'replyTo'] as $field) {
+        if ($message->from() !== []) {
+            $this->data[static::PROPERTY_FROM] = $message->from()[0]->toArray();
+        }
+
+        $addressProperties = [
+            'to' => static::PROPERTY_TO,
+            'cc' => static::PROPERTY_CC,
+            'bcc' => static::PROPERTY_BCC,
+            'replyTo' => static::PROPERTY_REPLY_TO,
+        ];
+
+        foreach ($addressProperties as $field => $property) {
             $addresses = $message->{$field}();
             if ($addresses === []) {
                 continue;
             }
 
-            $this->data[$field] = array_map(
+            $this->data[$property] = array_map(
                 static fn ($address): array => $address->toArray(),
                 $addresses,
             );
         }
 
+        if ($message->subject() !== null) {
+            $this->data[static::PROPERTY_SUBJECT] = $message->subject();
+        }
+
         if ($message->bodyStructure() !== null) {
-            $this->data['body'] = $message->bodyStructure()->toArray();
+            $this->data[static::PROPERTY_BODY] = $message->bodyStructure()->toArray();
 
             $attachments = [];
-            self::collectAttachments($message->bodyStructure(), $attachments);
+            $this->collectAttachments($message->bodyStructure(), $attachments);
             if ($attachments !== []) {
-                $this->data['attachments'] = $attachments;
+                $this->data[static::PROPERTY_ATTACHMENTS] = $attachments;
             }
         }
 
         if ($message->bodyStructure() !== null) {
-            $this->data['body'] = $message->bodyStructure()->toArray();
+            $this->data[static::PROPERTY_BODY] = $message->bodyStructure()->toArray();
 			// Recursively add content from bodyValues to matching parts
 			if (is_array($message->bodySections())) {
 				$addContentToParts = function(&$structure, $bodyValues) use (&$addContentToParts) {
@@ -105,77 +108,36 @@ class MessageProperties extends MessagePropertiesMutableAbstract {
 					}
 				};
 				
-				$addContentToParts($this->data['body'], $message->bodySections());
+				$addContentToParts($this->data[static::PROPERTY_BODY], $message->bodySections());
 			}
 		}
 
+        $this->data[static::PROPERTY_FLAGS] = [];
+        foreach ($message->flags() as $flag) {
+            $flag = ltrim($flag, '\\');
+            $normalized = match (strtolower($flag)) {
+                'seen' => 'read',
+                'flagged' => 'flagged',
+                'answered' => 'answered',
+                'draft' => 'draft',
+                'deleted' => 'deleted',
+                default => strtolower($flag),
+            };
+            $this->data[static::PROPERTY_FLAGS][$normalized] = true;
+        }
+
         return $this;
     }
 
-    public function toImap(): array
-    {
-        $message = [];
-
-        if (isset($this->data['flags'])) {
-            $message['flags'] = $this->data['flags'];
-        }
-
-        return $message;
-    }
-
-    /**
-     * Hydrate from store array
-     */
-    public function fromStore(array $data): static {
-        $this->data = $data;
-        return $this;
-    }
-
-    /**
-     * Serialize to store array
-     */
-    public function toStore(): array {
-        return $this->data;
-    }
-
-
-    /**
-     * Convert a string to UTF-8 from the given charset.
-     *
-     * Tries mb_convert_encoding first; falls back to iconv when mbstring does
-     * not recognise the charset name (e.g. "windows-1250").
-     */
-    public static function toUtf8(string $content, string $charset): string
-    {
-        if ($charset === '' || in_array(strtolower($charset), ['utf-8', 'utf8'], true)) {
-            // Content claims to be UTF-8 but may still have invalid sequences; scrub to be safe.
-            return mb_convert_encoding($content, 'UTF-8', 'UTF-8');
-        }
-        // Try mbstring first
-        try {
-            $converted = mb_convert_encoding($content, 'UTF-8', $charset);
-            if ($converted !== false) {
-                return $converted;
-            }
-        } catch (\ValueError) {
-            // charset not recognised by mbstring — fall through to iconv
-        }
-        // iconv fallback (handles Windows-125x, ISO-8859-*, etc.)
-        $converted = @iconv($charset, 'UTF-8//TRANSLIT//IGNORE', $content);
-        $content = ($converted !== false) ? $converted : $content;
-        // Final scrub: strip any residual invalid UTF-8 bytes so json_encode never fails.
-        return mb_convert_encoding($content, 'UTF-8', 'UTF-8');
-    }
-
     /**
      * Recursively collect attachment parts from body structure
      */
-    private static function collectAttachments(ClientMessagePart $part, array &$attachments): void
+    private function collectAttachments(ClientMessagePart $part, array &$attachments): void
     {
         $children = $part->parts();
         if ($children !== []) {
             foreach ($children as $childPart) {
-                self::collectAttachments($childPart, $attachments);
+                $this->collectAttachments($childPart, $attachments);
             }
             return;
         }

lib/Providers/Provider.php

@@ -14,6 +14,7 @@ use KTXF\Mail\Provider\ProviderServiceDiscoverInterface;
 use KTXF\Mail\Provider\ProviderServiceMutateInterface;
 use KTXF\Mail\Provider\ProviderServiceTestInterface;
 use KTXF\Mail\Service\ServiceBaseInterface;
+use KTXF\Mail\Service\ServiceMutableInterface;
 use KTXF\Resource\Provider\ResourceServiceLocationInterface;
 use KTXF\Resource\Provider\ResourceServiceMutateInterface;
 use KTXM\ProviderImap\Service\Discovery;
@@ -23,10 +24,9 @@ use KTXM\ProviderImap\Stores\ServiceStore;
 /**
  * IMAP Mail Provider
  */
-class Provider implements ProviderServiceMutateInterface, ProviderServiceDiscoverInterface, ProviderServiceTestInterface
+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';
@@ -180,7 +180,7 @@ class Provider implements ProviderServiceMutateInterface, ProviderServiceDiscove
         return $discovery->discover($identity, $location, $secret, $verifySSL);
     }
 
-    public function serviceTest(ServiceBaseInterface $service, array $options = []): array
+    public function serviceTest(ServiceBaseInterface|ServiceMutableInterface $service, array $options = []): array
     {
         $startTime = microtime(true);
 
@@ -194,7 +194,7 @@ class Provider implements ProviderServiceMutateInterface, ProviderServiceDiscove
             // 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);
 
@@ -205,36 +205,9 @@ class Provider implements ProviderServiceMutateInterface, ProviderServiceDiscove
                     . ' (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,9 +11,7 @@ namespace KTXM\ProviderImap\Providers;
 
 use Generator;
 use KTXF\Mail\Collection\CollectionBaseInterface;
-use KTXF\Mail\Collection\CollectionMutableInterface;
-use KTXF\Mail\Entity\EntityBaseInterface;
-use KTXF\Mail\Entity\EntityMutableInterface;
+use KTXF\Mail\Collection\CollectionPropertiesBaseInterface;
 use KTXF\Mail\Object\Address;
 use KTXF\Mail\Object\AddressInterface;
 use KTXF\Mail\Service\ServiceBaseInterface;
@@ -21,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;
@@ -41,15 +40,15 @@ use KTXM\ProviderImap\Service\Remote\RemoteService;
 use KTXM\ProviderImap\Providers\CollectionResource;
 use KTXF\Mail\Collection\CollectionRoles;
 use KTXF\Mail\Object\MessagePropertiesMutableInterface;
+use KTXF\Resource\Identifier\EntityIdentifierInterface;
 use KTXM\ProviderImap\Providers\EntityResource;
+use KTXM\ProviderImap\Client\Mailbox;
 
 /**
  * IMAP Mail Service
  */
 class Service implements ServiceBaseInterface, ServiceMutableInterface, ServiceConfigurableInterface, ServiceCollectionMutableInterface, ServiceEntityMutableInterface
 {
-    public const JSON_TYPE = ServiceBaseInterface::JSON_TYPE;
-
     private const PROVIDER_IDENTIFIER = 'imap';
 
     private ?string $serviceTenantId   = null;
@@ -64,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',
@@ -88,51 +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_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'];
@@ -153,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);
     }
 
@@ -178,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]));
         }
@@ -206,8 +217,6 @@ class Service implements ServiceBaseInterface, ServiceMutableInterface, ServiceC
         return $this;
     }
 
-    // ── ServiceBaseInterface ──────────────────────────────────────────────────
-
     public function capable(string $value): bool
     {
         return isset($this->serviceAbilities[$value]);
@@ -228,8 +237,6 @@ class Service implements ServiceBaseInterface, ServiceMutableInterface, ServiceC
         return $this->serviceIdentifier;
     }
 
-    // ── ServiceMutableInterface ───────────────────────────────────────────────
-
     public function getLabel(): ?string
     {
         return $this->serviceLabel;
@@ -292,8 +299,6 @@ class Service implements ServiceBaseInterface, ServiceMutableInterface, ServiceC
         
     }
 
-    // ── ServiceConfigurableInterface ──────────────────────────────────────────
-
     public function getLocation(): ServiceLocation
     {
         return $this->location;
@@ -352,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;
@@ -383,19 +386,23 @@ class Service implements ServiceBaseInterface, ServiceMutableInterface, ServiceC
     {
         $this->initialize();
 
-        $mailboxes = $this->collectionList(null);
-        $extant   = [];
-        foreach ($identifiers as $id) {
-            $extant[(string) $id] = isset($mailboxes[(string) $id]);
+        $list = [];
+
+        foreach ($identifiers as $identifier) {
+            $key = (string) $identifier;
+            $result = $this->remoteService->collectionFetch($key);
+
+            $list[$key] = $result !== false;
         }
-        return $extant;
+
+        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;
         }
@@ -411,20 +418,26 @@ class Service implements ServiceBaseInterface, ServiceMutableInterface, ServiceC
         return new CollectionResource($this->provider(), $this->identifier());
     }
 
-    public function collectionCreate(string|int|null $location, CollectionMutableInterface $collection, array $options = []): CollectionBaseInterface 
+    public function collectionCreate(CollectionIdentifier|null $target, CollectionPropertiesBaseInterface $properties, array $options = []): CollectionBaseInterface
     {
         $this->initialize();
 
+        if (!$properties->getLabel()) {
+            throw new \InvalidArgumentException('Collection label is required property');
+        }
+        $label = $properties->getLabel();
+
         // Resolve the full name: if a parent location is given, prepend it
-        $label = $collection->getProperties()->getLabel() ?? '';
-        if ($location !== null && $location !== '') {
+        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, ''));
-            $delimiter = $mailboxes ? reset($mailboxes)->delimiter() ?? '/' : '/';
-            $label = rtrim((string) $location, $delimiter) . $delimiter . ltrim($label, $delimiter);
+            $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]);
@@ -432,20 +445,26 @@ class Service implements ServiceBaseInterface, ServiceMutableInterface, ServiceC
         return $collection;
     }
 
-    public function collectionUpdate(string|int $identifier, CollectionMutableInterface $collection): CollectionBaseInterface
+    public function collectionUpdate(CollectionIdentifier $target, CollectionPropertiesBaseInterface $properties): CollectionBaseInterface
     {
         $this->initialize();
 
+        if (!$properties->getLabel()) {
+            throw new \InvalidArgumentException('Collection label is a required property');
+        }
+        $label = $properties->getLabel();
+
         // In IMAP, "update" = rename to the new label
-        $newName = $collection->getProperties()->getLabel() ?? (string) $identifier;
-        $mailbox = $this->mailService->collectionRename((string) $identifier, $newName);
+        $oldPath = (string) $target->collection();
+        $newName = $properties->getLabel();
+        $mailbox = $this->remoteService->collectionRename($oldPath, $newName);
 
         $collection = $this->collectionFresh();
         $collection->fromImap($mailbox);
         return  $collection;
     }
 
-    public function collectionDelete(string|int $identifier, bool $force = false): CollectionBaseInterface | true
+    public function collectionDelete(CollectionIdentifier $target, bool $force = false): CollectionBaseInterface | true
     {
         $this->initialize();
 
@@ -458,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((string) $identifier, (string) $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');
             }
@@ -474,24 +493,24 @@ class Service implements ServiceBaseInterface, ServiceMutableInterface, ServiceC
         }
 
         // we need to determine if the folder being deleted is already in the trash
-        if (str_starts_with((string) $identifier, (string) $deleteTarget)) {
+        if (str_starts_with((string) $target->collection(), (string) $deleteTarget)) {
             // if so, we should hard delete instead of moving to avoid duplicates in the trash
             $deleteMode = 'hard';
         }
 
         $result = match ($deleteMode) {
-            'soft' => $this->collectionMove((string) $identifier, (string) $deleteTarget),
-            'hard' => $this->mailService->collectionDestroy((string) $identifier)
+            'soft' => $this->collectionMove(new CollectionIdentifier($target->provider(), $target->service(), $deleteTarget), $target),
+            'hard' => $this->remoteService->collectionDestroy((string) $target->collection()),
         };
         return $result;
     }
 
-    public function collectionMove(string|int $identifier, string|int|null $target): CollectionBaseInterface
+    public function collectionMove(CollectionIdentifier $target, CollectionIdentifier $source): CollectionBaseInterface
     {
         $this->initialize();
         
-        $sourceMailbox = $this->mailService->collectionFetch((string) $identifier);
-        $targetMailbox = $this->mailService->collectionFetch((string) $target);
+        $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');
         }
@@ -502,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 itterator_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;
         }
     }
 
@@ -546,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
@@ -563,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) {
@@ -579,12 +623,45 @@ class Service implements ServiceBaseInterface, ServiceMutableInterface, ServiceC
 
     public function entityCreate(CollectionIdentifier $target, MessagePropertiesMutableInterface $properties, array $options = []): EntityResource
     {
-        return $this->entityFresh();
+        throw new \RuntimeException('Entity creation is not supported in this service');
     }
 
     public function entityModify(EntityIdentifier $target, MessagePropertiesMutableInterface $properties): EntityResource
     {
-        return $this->entityFresh();
+        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
@@ -608,18 +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');
             }
 
-            $deleteTargetNative = reset($mailboxes)->name();
+            $targetMailbox = reset($mailboxes);
+            if ($targetMailbox === false) {
+                throw new \RuntimeException('No Trash collection configured or found for deletion');
+            }
+
+            $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) {
@@ -630,72 +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;
-                $results[(string)$sourceEntities[$uid]] = [
+                $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 $results;
-    }
-
-    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,
                 ];
             }
         }
@@ -721,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;
@@ -730,6 +762,40 @@ 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
+    {
+        // 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,
+                ];
             }
         }
 

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
@@ -106,7 +106,7 @@ class RemoteMailService
                 }
                 try {
                     $status = $this->client->perform(new StatusCommand($mailbox->name(), self::DEFAULT_MAILBOX_STATUS_ITEMS));
-                    $mailbox->fromStatus($status);
+                    $mailbox = $mailbox->fromStatus($status);
                 } catch (ImapException) {
                     // do nothing
                 }
@@ -132,7 +132,7 @@ class RemoteMailService
         $mailbox = reset($mailbox);
         // enrich with STATUS
         $status = $this->client->perform(new StatusCommand($mailbox->name(), self::DEFAULT_MAILBOX_STATUS_ITEMS));
-        $mailbox->fromStatus($status);
+        $mailbox = $mailbox->fromStatus($status);
         
         return $mailbox;
     }
@@ -241,14 +241,31 @@ class RemoteMailService
      */
     public function entityList(string $collection, ?IFilter $filter = null, ?ISort $sort = null, ?IRange $range = null): Generator
     {
+        $options = FetchOptions::message()->withBodyText();
+
+        // fast path: fetch all messages without filtering, sorting or pagination
+        if ($filter === null && $sort === null && $range === null) {
+            $mailbox = $this->client->perform(new SelectCommand($collection, true));
+
+            if ($mailbox === null) {
+                return [];
+            }
+
+            yield from $this->client->perform(new FetchManyCommand(
+                FetchTarget::all(),
+                $options,
+            ));
+
+            return;
+        }
+
         // find all the UIDs matching the filter
         $uids = $this->entityFind($collection, $filter, $sort, $range);
+        
         if (empty($uids)) {
             return [];
         }
 
-        $options = FetchOptions::default()->withBodyText();
-
         yield from $this->entityFetch($collection, $options, ...$uids);
     }
 
@@ -264,7 +281,7 @@ class RemoteMailService
             return [];
         }
 
-        $options ??= FetchOptions::default();
+        $options ??= FetchOptions::message()->withBodyText();
         $this->client->perform(new SelectCommand($collection, true));
 
         $request = new FetchManyCommand(
@@ -278,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.
      *
@@ -336,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))),
@@ -405,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() === []) {
@@ -599,7 +759,7 @@ class RemoteMailService
      */
     private function entitySortClientSide(array $uids, ISort $sort): array
     {
-        $options = FetchOptions::summary();
+        $options = FetchOptions::default();
         foreach ($sort->conditions() as $condition) {
             if (in_array($condition['attribute'] ?? '', ['from', 'to', 'subject', 'sent'], true)) {
                 $options = $options->withEnvelope();
@@ -636,7 +796,7 @@ class RemoteMailService
             'from' => $this->entityPrimaryAddressValue($left->from()) <=> $this->entityPrimaryAddressValue($right->from()),
             'to' => $this->entityPrimaryAddressValue($left->to()) <=> $this->entityPrimaryAddressValue($right->to()),
             'subject' => $this->entityScalarValue($left->subject()) <=> $this->entityScalarValue($right->subject()),
-            'received' => $this->entityTimestampValue($left->internalDate()) <=> $this->entityTimestampValue($right->internalDate()),
+            'received' => $this->entityTimestampValue($left->receivedAt() ?? $left->internalDate()) <=> $this->entityTimestampValue($right->receivedAt() ?? $right->internalDate()),
             'sent' => $this->entityTimestampValue($left->sentAt()) <=> $this->entityTimestampValue($right->sentAt()),
             'size' => $left->size() <=> $right->size(),
             default => 0,
@@ -852,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

@@ -14,16 +14,16 @@
     "lint": "eslint . --ext .vue,.js,.jsx,.cjs,.mjs,.ts,.tsx,.cts,.mts --fix --ignore-path .gitignore"
   },
   "dependencies": {
-    "pinia": "^2.3.1",
+    "pinia": "^3.0.0",
     "vue": "^3.5.18",
-    "vue-router": "^4.5.1",
-    "vuetify": "^3.10.2"
+    "vue-router": "^5.0.0",
+    "vuetify": "^4.0.0"
   },
   "devDependencies": {
     "@vitejs/plugin-vue": "^6.0.1",
-    "@vue/tsconfig": "^0.7.0",
-    "typescript": "~5.8.3",
-    "vite": "^7.1.2",
+    "@vue/tsconfig": "^0.9.0",
+    "typescript": "~6.0.0",
+    "vite": "^8.0.0",
     "vue-tsc": "^3.0.5"
   }
 }