<?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\NodePropertiesBaseInterface;

/**
 * Message Properties Base Interface
 * 
 * @since 2025.05.01
 */
interface MessagePropertiesBaseInterface extends NodePropertiesBaseInterface {

    public const JSON_TYPE = 'mail.message';
    public const JSON_PROPERTY_HEADERS = 'headers';
    public const JSON_PROPERTY_URID = 'urid';
    public const JSON_PROPERTY_DATE = 'date';
    public const JSON_PROPERTY_RECEIVED = 'received';
    public const JSON_PROPERTY_SIZE = 'size';
    public const JSON_PROPERTY_SENDER = 'sender';
    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_IN_REPLY_TO = 'inReplyTo';
    public const JSON_PROPERTY_REFERENCES = 'references';
    public const JSON_PROPERTY_SUBJECT = 'subject';
    public const JSON_PROPERTY_SNIPPET = 'snippet';
    public const JSON_PROPERTY_BODY = 'body';
    public const JSON_PROPERTY_ATTACHMENTS = 'attachments';
    public const JSON_PROPERTY_TAGS = 'tags';

    /**
     * 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|array<int,string>|null Header value(s) or null if not set
     */
    public function getHeader(string $name): string|array|null;

    /**
     * Gets the universal resource identifier (URN)
     *
     * @since 2025.05.01
     *
     * @return string|null
     */
    public function getUrid(): ?string;

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

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

    /**
     * Gets the message size in bytes
     *
     * @since 2025.05.01
     *
     * @return int|null
     */
    public function getSize(): ?int;

    /**
     * Gets the sender address (actual sender, may differ from From)
     *
     * @since 2025.05.01
     *
     * @return AddressInterface|null
     */
    public function getSender(): ?AddressInterface;

    /**
     * Gets the sender address
     *
     * @since 2025.05.01
     *
     * @return AddressInterface|null
     */
    public function getFrom(): ?AddressInterface;
    /**
     * Gets the reply-to addresses
     *
     * @since 2025.05.01
     *
     * @return array<int,AddressInterface>
     */
    public function getReplyTo(): array;

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

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

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

    /**
     * Gets the message ID this is replying to
     *
     * @since 2025.05.01
     *
     * @return string|null
     */
    public function getInReplyTo(): ?string;

    /**
     * Gets the references (message IDs in thread)
     *
     * @since 2025.05.01
     *
     * @return array<int,string>
     */
    public function getReferences(): array;

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

    /**
     * Gets the message snippet/preview
     *
     * @since 2025.05.01
     *
     * @return string|null
     */
    public function getSnippet(): ?string;

    /**
     * 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;

    /**
     * Gets the message body structure
     *
     * @since 2025.05.01
     *
     * @return MessagePartInterface|null The body structure or null if no body
     */
    public function getBody(): ?MessagePartInterface;

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

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

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

    /**
     * Gets message flags
     *
     * @since 2025.05.01
     *
     * @return array{read:bool,starred:bool,important:bool,answered:bool,forwarded:bool,draft:bool,deleted:bool,flagged:bool}
     */
    public function getFlags(): array;

    /**
     * Gets a specific flag value
     *
     * @since 2025.05.01
     *
     * @param string $name Flag name (read, starred, important, answered, forwarded, draft, deleted, flagged)
     *
     * @return bool
     */
    public function getFlag(string $name): bool;

}