<?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;
use JsonSerializable;

/**
 * Mail Message Base Interface
 * 
 * Read-only interface for mail message entities.
 * 
 * @since 2025.05.01
 */
interface IMessageBase extends JsonSerializable {

    public const JSON_TYPE = 'mail.message';
    public const JSON_PROPERTY_TYPE = '@type';
    public const JSON_PROPERTY_ID = 'id';
    public const JSON_PROPERTY_SUBJECT = 'subject';
    public const JSON_PROPERTY_FROM = 'from';
    public const JSON_PROPERTY_REPLY_TO = 'replyTo';
    public const JSON_PROPERTY_TO = 'to';
    public const JSON_PROPERTY_CC = 'cc';
    public const JSON_PROPERTY_BCC = 'bcc';
    public const JSON_PROPERTY_DATE = 'date';
    public const JSON_PROPERTY_BODY_TEXT = 'bodyText';
    public const JSON_PROPERTY_BODY_HTML = 'bodyHtml';
    public const JSON_PROPERTY_ATTACHMENTS = 'attachments';
    public const JSON_PROPERTY_HEADERS = 'headers';

    /**
     * Gets the message identifier
     *
     * @since 2025.05.01
     *
     * @return string|null Message ID or null for unsent messages
     */
    public function getId(): ?string;

    /**
     * Gets the message subject
     *
     * @since 2025.05.01
     *
     * @return string
     */
    public function getSubject(): string;

    /**
     * Gets the sender address
     *
     * @since 2025.05.01
     *
     * @return IAddress|null
     */
    public function getFrom(): ?IAddress;

    /**
     * Gets the reply-to address
     *
     * @since 2025.05.01
     *
     * @return IAddress|null
     */
    public function getReplyTo(): ?IAddress;

    /**
     * Gets the primary recipients (To)
     *
     * @since 2025.05.01
     *
     * @return array<int, IAddress>
     */
    public function getTo(): array;

    /**
     * Gets the carbon copy recipients (CC)
     *
     * @since 2025.05.01
     *
     * @return array<int, IAddress>
     */
    public function getCc(): array;

    /**
     * Gets the blind carbon copy recipients (BCC)
     *
     * @since 2025.05.01
     *
     * @return array<int, IAddress>
     */
    public function getBcc(): array;

    /**
     * Gets the message date
     *
     * @since 2025.05.01
     *
     * @return DateTimeImmutable|null
     */
    public function getDate(): ?DateTimeImmutable;

    /**
     * Gets the plain text body
     *
     * @since 2025.05.01
     *
     * @return string|null
     */
    public function getBodyText(): ?string;

    /**
     * Gets the HTML body
     *
     * @since 2025.05.01
     *
     * @return string|null
     */
    public function getBodyHtml(): ?string;

    /**
     * Gets the attachments
     *
     * @since 2025.05.01
     *
     * @return array<int, IAttachment>
     */
    public function getAttachments(): array;

    /**
     * Gets custom headers
     *
     * @since 2025.05.01
     *
     * @return array<string, string> Header name => value
     */
    public function getHeaders(): array;

    /**
     * Gets a specific header value
     *
     * @since 2025.05.01
     *
     * @param string $name Header name
     *
     * @return string|null Header value or null if not set
     */
    public function getHeader(string $name): ?string;

    /**
     * Checks if the message has any recipients
     *
     * @since 2025.05.01
     *
     * @return bool True if To, CC, or BCC has at least one recipient
     */
    public function hasRecipients(): bool;

    /**
     * Checks if the message has any body content
     *
     * @since 2025.05.01
     *
     * @return bool True if text or HTML body is set
     */
    public function hasBody(): bool;

}