<?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\EntityBaseInterface;
use KTXF\Mail\Entity\EntityMutableInterface;

/**
 * Mail Service Entity Mutable Interface
 * 
 * Optional interface for services that support entity CRUD operations.
 * Provides entity creation, modification, deletion, copying, moving, and flag management.
 * 
 * @since 2025.05.01
 */
interface ServiceEntityMutableInterface extends ServiceBaseInterface {

    public const CAPABILITY_ENTITY_CREATE = 'EntityCreate';
    public const CAPABILITY_ENTITY_MODIFY = 'EntityModify';
    public const CAPABILITY_ENTITY_DESTROY = 'EntityDestroy';
    public const CAPABILITY_ENTITY_COPY = 'EntityCopy';
    public const CAPABILITY_ENTITY_MOVE = 'EntityMove';

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

    /**
     * Creates/imports an entity into a collection
     *
     * @since 2025.05.01
     *
     * @param string|int $collection collection identifier
     * @param EntityMutableInterface $entity Entity data
     * @param array $options additional options
     *
     * @return EntityBaseInterface Created entity
     */
    public function entityCreate(string|int $collection, EntityMutableInterface $entity, array $options = []): EntityBaseInterface;

    /**
     * Modifies an existing entity
     *
     * @since 2025.05.01
     *
     * @param string|int $collection Collection identifier
     * @param string|int $identifier Entity identifier
     * @param EntityMutableInterface $entity Entity data
     *
     * @return EntityBaseInterface Modified entity
     */
    public function entityModify(string|int $collection, string|int $identifier, EntityMutableInterface $entity): EntityBaseInterface;
    /**
     * Destroys one or more entities
     *
     * @since 2025.05.01
     *
     * @param string|int $collection Collection identifier
     * @param string|int ...$identifiers Entity identifiers to destroy
     *
     * @return array<string|int,bool> List of destroyed entity identifiers
     */
    public function entityDestroy(string|int $collection, string|int ...$identifiers): array;

    /**
     * Copies entities to another collection
     *
     * @since 2025.05.01
     *
     * @param string|int $sourceCollection Source collection identifier
     * @param string|int $targetCollection Target collection identifier
     * @param string|int ...$identifiers Entity identifiers to copy
     *
     * @return array<string|int,string|int> Map of source identifier => new identifier
     */
    public function entityCopy(string|int $sourceCollection, string|int $targetCollection, string|int ...$identifiers): array;

    /**
     * Moves entities to another collection
     *
     * @since 2025.05.01
     *
     * @param string|int $sourceCollection Source collection identifier
     * @param string|int $targetCollection Target collection identifier
     * @param string|int ...$identifiers Entity identifiers to move
     *
     * @return array<string|int,bool> List of moved entity identifiers
     */
    public function entityMove(string|int $sourceCollection, string|int $targetCollection, string|int ...$identifiers): array;

}