From f80680e8744aa51991d8764af167f493738b26f0 Mon Sep 17 00:00:00 2001
From: matthieu <matthieu@yuno.malio.fr>
Date: Tue, 19 May 2026 23:20:58 +0200
Subject: [PATCH] feat(mail) : MailProviderInterface + MailProviderException

---
 src/Mail/Exception/MailProviderException.php | 20 ++++++
 src/Mail/MailProviderInterface.php           | 66 ++++++++++++++++++++
 2 files changed, 86 insertions(+)
 create mode 100644 src/Mail/Exception/MailProviderException.php
 create mode 100644 src/Mail/MailProviderInterface.php

diff --git a/src/Mail/Exception/MailProviderException.php b/src/Mail/Exception/MailProviderException.php
new file mode 100644
index 0000000..af4e6da
--- /dev/null
+++ b/src/Mail/Exception/MailProviderException.php
@@ -0,0 +1,20 @@
+<?php
+
+declare(strict_types=1);
+
+namespace App\Mail\Exception;
+
+use RuntimeException;
+
+final class MailProviderException extends RuntimeException
+{
+    public static function connectionFailed(string $reason): self
+    {
+        return new self(sprintf('Mail provider connection failed: %s', $reason));
+    }
+
+    public static function operationFailed(string $operation, string $reason): self
+    {
+        return new self(sprintf('Mail provider operation "%s" failed: %s', $operation, $reason));
+    }
+}
diff --git a/src/Mail/MailProviderInterface.php b/src/Mail/MailProviderInterface.php
new file mode 100644
index 0000000..1de7da3
--- /dev/null
+++ b/src/Mail/MailProviderInterface.php
@@ -0,0 +1,66 @@
+<?php
+
+declare(strict_types=1);
+
+namespace App\Mail;
+
+use App\Mail\Dto\MailFolderDto;
+use App\Mail\Dto\MailMessageDetailDto;
+use App\Mail\Dto\MailMessageHeaderDto;
+use App\Mail\Exception\MailProviderException;
+
+interface MailProviderInterface
+{
+    /**
+     * Returns the full folder tree of the configured mailbox.
+     *
+     * @return list<MailFolderDto>
+     *
+     * @throws MailProviderException
+     */
+    public function listFolders(): array;
+
+    /**
+     * Returns a paginated list of message headers for the given folder.
+     *
+     * @return list<MailMessageHeaderDto>
+     *
+     * @throws MailProviderException
+     */
+    public function listMessages(string $folderPath, int $limit, int $offset): array;
+
+    /**
+     * Fetches the full message (headers + body + attachments list) by UID.
+     *
+     * @throws MailProviderException
+     */
+    public function fetchMessage(string $folderPath, int $uid): MailMessageDetailDto;
+
+    /**
+     * Marks a message as read or unread on the IMAP server.
+     *
+     * @throws MailProviderException
+     */
+    public function markRead(string $folderPath, int $uid, bool $read): void;
+
+    /**
+     * Marks a message as flagged (starred) or unflagged on the IMAP server.
+     *
+     * @throws MailProviderException
+     */
+    public function markFlagged(string $folderPath, int $uid, bool $flagged): void;
+
+    /**
+     * Moves a message from one folder to another on the IMAP server.
+     *
+     * @throws MailProviderException
+     */
+    public function moveMessage(string $folderPath, int $uid, string $targetFolder): void;
+
+    /**
+     * Fetches the raw binary content of an attachment by its MIME part number.
+     *
+     * @throws MailProviderException
+     */
+    public function fetchAttachment(string $folderPath, int $uid, string $partNumber): string;
+}