From 812a6680a8c090cdb8c2f498a3ff659a3ca505c0 Mon Sep 17 00:00:00 2001
From: Sebastian Krupinski <krupinski01@gmail.com>
Date: Thu, 28 May 2026 23:02:37 -0400
Subject: [PATCH] feat: mail entity download

Signed-off-by: Sebastian Krupinski <krupinski01@gmail.com>
---
 .../lib/Mail/Service/ServiceBaseInterface.php | 15 +++++++-
 shared/lib/Resource/BinaryResource.php        | 37 +++++++++++++++++++
 2 files changed, 51 insertions(+), 1 deletion(-)
 create mode 100644 shared/lib/Resource/BinaryResource.php

diff --git a/shared/lib/Mail/Service/ServiceBaseInterface.php b/shared/lib/Mail/Service/ServiceBaseInterface.php
index 966489e..aaee2d4 100644
--- a/shared/lib/Mail/Service/ServiceBaseInterface.php
+++ b/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;
@@ -251,7 +252,7 @@ interface ServiceBaseInterface extends ResourceServiceBaseInterface {
      */
     public function entityFetchBulk(EntityIdentifierInterface ...$identifiers): array;
 
-        /**
+    /**
      * Fetches one or more entities
      *
      * @since 2025.05.01
@@ -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;
 }
diff --git a/shared/lib/Resource/BinaryResource.php b/shared/lib/Resource/BinaryResource.php
new file mode 100644
index 0000000..c5c6eb9
--- /dev/null
+++ b/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;
+    }
+}
\ No newline at end of file