<?php

declare(strict_types=1);

namespace App\Module\Mail\Domain\Repository;

use App\Module\Mail\Domain\Entity\MailFolder;
use App\Module\Mail\Domain\Entity\MailMessage;

interface MailMessageRepositoryInterface
{
    public function findById(int $id): ?MailMessage;

    /**
     * @return list<MailMessage>
     */
    public function findAll(): array;

    public function findByMessageId(string $messageId): ?MailMessage;

    public function findByFolderAndUid(MailFolder $folder, int $uid): ?MailMessage;

    /**
     * @return list<MailMessage>
     */
    public function findByFolderPaginated(MailFolder $folder, int $limit, int $offset): array;

    public function countUnreadByFolder(MailFolder $folder): int;

    public function findMaxUidInFolder(MailFolder $folder): int;

    /**
     * @return list<MailMessage>
     */
    public function findLastNByFolder(MailFolder $folder, int $limit): array;

    /**
     * @return list<int>
     */
    public function findAllUidsByFolder(MailFolder $folder): array;

    /**
     * Pagination cursor : retourne $limit messages apres le cursor (sentAt DESC, id DESC).
     * Cursor format : base64url(sentAt_iso8601:id) - null pour la premiere page.
     *
     * @return array{messages: list<MailMessage>, nextCursor: ?string}
     */
    public function findByFolderCursor(MailFolder $folder, int $limit, ?string $cursor): array;
}
