<?php

declare(strict_types=1);

/**
 * SPDX-FileCopyrightText: Sebastian Krupinski <krupinski01@gmail.com>
 * SPDX-License-Identifier: AGPL-3.0-or-later
 */

namespace KTXF\Mail\Entity;

use DateTimeImmutable;

/**
 * Mail Message Mutable Interface
 * 
 * Interface for composing and modifying mail messages with fluent setters.
 * 
 * @since 2025.05.01
 */
interface IMessageMutable extends IMessageBase {

    /**
     * Sets the message identifier
     *
     * @since 2025.05.01
     *
     * @param string|null $id
     *
     * @return self
     */
    public function setId(?string $id): self;

    /**
     * Sets the message subject
     *
     * @since 2025.05.01
     *
     * @param string $subject
     *
     * @return self
     */
    public function setSubject(string $subject): self;

    /**
     * Sets the sender address
     *
     * @since 2025.05.01
     *
     * @param IAddress|null $from
     *
     * @return self
     */
    public function setFrom(?IAddress $from): self;

    /**
     * Sets the reply-to address
     *
     * @since 2025.05.01
     *
     * @param IAddress|null $replyTo
     *
     * @return self
     */
    public function setReplyTo(?IAddress $replyTo): self;

    /**
     * Sets the primary recipients (To)
     *
     * @since 2025.05.01
     *
     * @param array<int, IAddress> $to
     *
     * @return self
     */
    public function setTo(array $to): self;

    /**
     * Adds a primary recipient (To)
     *
     * @since 2025.05.01
     *
     * @param IAddress $address
     *
     * @return self
     */
    public function addTo(IAddress $address): self;

    /**
     * Sets the carbon copy recipients (CC)
     *
     * @since 2025.05.01
     *
     * @param array<int, IAddress> $cc
     *
     * @return self
     */
    public function setCc(array $cc): self;

    /**
     * Adds a carbon copy recipient (CC)
     *
     * @since 2025.05.01
     *
     * @param IAddress $address
     *
     * @return self
     */
    public function addCc(IAddress $address): self;

    /**
     * Sets the blind carbon copy recipients (BCC)
     *
     * @since 2025.05.01
     *
     * @param array<int, IAddress> $bcc
     *
     * @return self
     */
    public function setBcc(array $bcc): self;

    /**
     * Adds a blind carbon copy recipient (BCC)
     *
     * @since 2025.05.01
     *
     * @param IAddress $address
     *
     * @return self
     */
    public function addBcc(IAddress $address): self;

    /**
     * Sets the message date
     *
     * @since 2025.05.01
     *
     * @param DateTimeImmutable|null $date
     *
     * @return self
     */
    public function setDate(?DateTimeImmutable $date): self;

    /**
     * Sets the plain text body
     *
     * @since 2025.05.01
     *
     * @param string|null $text
     *
     * @return self
     */
    public function setBodyText(?string $text): self;

    /**
     * Sets the HTML body
     *
     * @since 2025.05.01
     *
     * @param string|null $html
     *
     * @return self
     */
    public function setBodyHtml(?string $html): self;

    /**
     * Sets the attachments
     *
     * @since 2025.05.01
     *
     * @param array<int, IAttachment> $attachments
     *
     * @return self
     */
    public function setAttachments(array $attachments): self;

    /**
     * Adds an attachment
     *
     * @since 2025.05.01
     *
     * @param IAttachment $attachment
     *
     * @return self
     */
    public function addAttachment(IAttachment $attachment): self;

    /**
     * Sets custom headers
     *
     * @since 2025.05.01
     *
     * @param array<string, string> $headers Header name => value
     *
     * @return self
     */
    public function setHeaders(array $headers): self;

    /**
     * Sets a specific header value
     *
     * @since 2025.05.01
     *
     * @param string $name Header name
     * @param string $value Header value
     *
     * @return self
     */
    public function setHeader(string $name, string $value): self;

}