<?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 KTXF\Json\JsonSerializable;

/**
 * Address Interface
 * 
 * Represents an email address with optional display name.
 * 
 * @since 2025.05.01
 */
interface AddressInterface extends JsonSerializable {

    public const JSON_PROPERTY_ADDRESS = 'address';
    public const JSON_PROPERTY_LABEL = 'label';

    /**
     * Gets the email address
     *
     * @since 2025.05.01
     */
    public function getAddress(): string;

    /**
     * Sets the email address
     *
     * @since 2025.05.01
     */
    public function setAddress(string $value): static;

    /**
     * Gets the display name
     *
     * @since 2025.05.01
     */
    public function getLabel(): ?string;

    /**
     * Sets the display name
     *
     * @since 2025.05.01
     */
    public function setLabel(?string $value): static;

    /**
     * Gets the formatted address string
     *
     * @since 2025.05.01
     *
     * @return string Formatted as "Name <address>" or just "address" if no name
     */
    public function toString(): string;

}