<?php

namespace App\Services\Mail;

/**
 * The mailbox customers write to, as this application needs to read it.
 *
 * Deliberately tiny: fetch what has not been fetched, and say which messages
 * have been dealt with. Everything else a mail server can do — moving,
 * deleting, flagging for other clients — is somebody else's mail and not ours
 * to rearrange.
 */
interface InboundMailbox
{
    /** Is a mailbox configured at all? */
    public function isConfigured(): bool;

    /**
     * Reach the mailbox now and say what happened.
     *
     * For the button in the console: an operator who has just typed a host, a
     * user and a password should not have to wait for the next scheduled run to
     * find out whether any of it was right — and "the inbox is empty" is not an
     * answer to that question.
     *
     * Never throws. A failed check IS the answer.
     *
     * @return array{ok: bool, message: string, unseen: int|null}
     */
    public function check(): array;

    /**
     * Messages that have arrived, oldest first.
     *
     * @param  int  $limit  how many to take in one run
     * @return array<int, FetchedMail>
     */
    public function fetch(int $limit = 50): array;

    /**
     * Mark a message as seen on the SERVER, so the next run skips it.
     *
     * Seen, never deleted. The copy on the mail server is not ours to remove —
     * an application that empties somebody's mailbox is one nobody hands a
     * password to, and the original is the only place an attachment still
     * exists once this application has refused to store it.
     */
    public function markSeen(string $uid): void;
}