<?php

declare(strict_types=1);

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

namespace KTXF\Mail\Object;

use DateTimeImmutable;
use KTXF\Resource\Provider\Node\NodePropertiesMutableInterface;

/**
 * Message Properties Mutable Interface
 * 
 * @since 2025.05.01
 */
interface MessagePropertiesMutableInterface extends MessagePropertiesBaseInterface, NodePropertiesMutableInterface {

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

    /**
     * Sets a specific header value
     *
     * @since 2025.05.01
     *
     * @param string $name Header name
     * @param string|array<int,string> $value Header value(s)
     *
     * @return self
     */
    public function setHeader(string $name, string|array $value): static;

    /**
     * Sets the universal resource identifier (URN)
     *
     * @since 2025.05.01
     *
     * @param string|null $value
     *
     * @return self
     */
    public function setUrid(?string $value): static;

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

    /**
     * Sets the received date
     *
     * @since 2025.05.01
     *
     * @param DateTimeImmutable|null $value
     *
     * @return self
     */
    public function setReceived(?DateTimeImmutable $value): static;

    /**
     * Sets the message size in bytes
     *
     * @since 2025.05.01
     *
     * @param int|null $value
     *
     * @return self
     */
    public function setSize(?int $value): static;

    /**
     * Sets the sender address (actual sender, may differ from From)
     *
     * @since 2025.05.01
     *
     * @param AddressInterface|null $value
     *
     * @return self
     */
    public function setSender(?AddressInterface $value): static;

    /**
     * Sets the sender address
     *
     * @since 2025.05.01
     *
     * @param AddressInterface $value
     *
     * @return self
     */
    public function setFrom(AddressInterface $value): static;

    /**
     * Sets the reply-to addresses
     *
     * @since 2025.05.01
     *
     * @param AddressInterface ...$value
     *
     * @return self
     */
    public function setReplyTo(AddressInterface ...$value): static;

    /**
     * Sets the primary recipients (To)
     *
     * @since 2025.05.01
     *
     * @param AddressInterface ...$value
     *
     * @return self
     */
    public function setTo(AddressInterface ...$value): static;

    /**
     * Sets the carbon copy recipients (CC)
     *
     * @since 2025.05.01
     *
     * @param AddressInterface ...$value
     *
     * @return self
     */
    public function setCc(AddressInterface ...$value): static;

    /**
     * Sets the blind carbon copy recipients (BCC)
     *
     * @since 2025.05.01
     *
     * @param AddressInterface ...$value
     *
     * @return self
     */
    public function setBcc(AddressInterface ...$value): static;

    /**
     * Sets the message ID this is replying to
     *
     * @since 2025.05.01
     *
     * @param string|null $value
     *
     * @return self
     */
    public function setInReplyTo(?string $value): static;

    /**
     * Sets the references (message IDs in thread)
     *
     * @since 2025.05.01
     *
     * @param string ...$value
     *
     * @return self
     */
    public function setReferences(string ...$value): static;

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

    /**
     * Sets the message snippet/preview
     *
     * @since 2025.05.01
     *
     * @param string|null $value
     *
     * @return self
     */
    public function setSnippet(?string $value): static;

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

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

    /**
     * Sets the attachments
     *
     * @since 2025.05.01
     *
     * @param AttachmentInterface ...$value
     *
     * @return self
     */
    public function setAttachments(AttachmentInterface ...$value): static;

    /**
     * Adds an attachment
     *
     * @since 2025.05.01
     *
     * @param AttachmentInterface $value
     *
     * @return self
     */
    public function addAttachment(AttachmentInterface $value): static;
    /**
     * Sets message tags
     *
     * @since 2025.05.01
     *
     * @param array{read: bool, starred: bool, important: bool, answered: bool, forwarded: bool, draft: bool, deleted: bool, flagged: bool} $value
     *
     * @return self
     */
    public function setFlag(string $label, bool $value): static;

}