feat: mail entity download

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

shared/lib/Mail/Service/ServiceBaseInterface.php

@@ -12,6 +12,7 @@ namespace KTXF\Mail\Service;
 use Generator;
 use KTXF\Mail\Collection\CollectionBaseInterface;
 use KTXF\Mail\Object\AddressInterface;
+use KTXF\Resource\BinaryResource;
 use KTXF\Resource\Delta\Delta;
 use KTXF\Resource\Filter\IFilter;
 use KTXF\Resource\Identifier\EntityIdentifierInterface;
@@ -262,4 +263,16 @@ interface ServiceBaseInterface extends ResourceServiceBaseInterface {
      */
     public function entityFetchStream(EntityIdentifierInterface ...$identifiers): Generator;
 
+
+    /**
+     * Downloads a message or part of a message
+     *
+     * @since 2025.05.01
+     *
+     * @param EntityIdentifierInterface $target Message identifier
+     * @param array|null $part Optional part to download
+     *
+     * @return BinaryResource
+     */
+    public function entityDownload(EntityIdentifierInterface $target, array|null $part): BinaryResource;
 }

shared/lib/Resource/BinaryResource.php

@@ -0,0 +1,37 @@
+<?php
+
+declare(strict_types=1);
+
+/**
+ * SPDX-FileCopyrightText: Sebastian Krupinski <krupinski01@gmail.com>
+ * SPDX-License-Identifier: AGPL-3.0-or-later
+ */
+
+namespace KTXF\Resource;
+
+/**
+ * Carries file-like binary content metadata and a byte stream.
+ */
+final class BinaryResource
+{
+    public function __construct(
+        private readonly string $filename,
+        private readonly string $mimeType,
+        private readonly \Generator $stream,
+    ) {}
+
+    public function filename(): string
+    {
+        return $this->filename;
+    }
+
+    public function mimeType(): string
+    {
+        return $this->mimeType;
+    }
+
+    public function stream(): \Generator
+    {
+        return $this->stream;
+    }
+}