<?php

declare(strict_types=1);

namespace App\Module\Mail\Domain\Provider;

use App\Module\Mail\Application\Dto\MailFolderDto;
use App\Module\Mail\Application\Dto\MailMessageDetailDto;
use App\Module\Mail\Application\Dto\MailMessageHeaderDto;
use App\Module\Mail\Domain\Exception\MailProviderException;

interface MailProviderInterface
{
    /**
     * Opens a connection using the stored configuration and returns the number
     * of folders found. Used by the admin "test connection" endpoint, so it
     * MUST work even when the configuration is not yet enabled.
     *
     * @throws MailProviderException
     */
    public function testConnection(): int;

    /**
     * Releases any reused network connection held by the provider.
     * Safe to call multiple times; a no-op if nothing is open.
     */
    public function closeConnection(): void;

    /**
     * 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;
}
