<?php

declare(strict_types=1);

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

namespace KTXF\Mail\Service;

use KTXF\Mail\Entity\EntityMutableInterface;
use KTXF\Mail\Object\AddressInterface;
use KTXF\Mail\Object\MessagePropertiesMutableInterface;
use KTXF\Mail\Submission\EntitySubmitResult;
use KTXF\Resource\Identifier\EntityIdentifierInterface;

/**
 * Mail Service Submit Interface
 *
 * Interface for mail services capable of outbound submission.
 * Supports submission of fresh in-memory messages and already-existing
 * provider-backed drafts through a single provider-agnostic contract.
 *
 * @since 2026.06.07
 */
interface ServiceEntitySubmitInterface {

    public const CAPABILITY_ENTITY_SUBMIT_FRESH = 'EntitySubmitFresh';
    public const CAPABILITY_ENTITY_SUBMIT_DRAFT = 'EntitySubmitDraft';

    /**
     * Creates a fresh entity instance for composition
     *
     * @since 2025.05.01
     *
     * @return EntityMutableInterface Fresh entity object
     */
    public function entityFresh(): EntityMutableInterface;

    /**
     * Submits an outbound message.
     *
     * @since 2026.06.07
     *
     * @param AddressInterface $sender Sender address
     * @param EntityIdentifierInterface|null $source Source entity identifier
     * @param MessagePropertiesMutableInterface|null $message Message properties
     *
     * @return EntitySubmitResult Normalized submission result
     */
    public function entitySubmit(AddressInterface $sender, EntityIdentifierInterface|null $source = null, MessagePropertiesMutableInterface|null $message = null): EntitySubmitResult;

}