<?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\Collection\ICollectionBase;
use KTXF\Mail\Collection\ICollectionMutable;

/**
 * Mail Service Collection Mutable Interface
 * 
 * Optional interface for services that support collection CRUD operations.
 * Provides mailbox/folder creation, modification, deletion, and moving.
 * 
 * @since 2025.05.01
 */
interface ServiceCollectionMutableInterface extends ServiceBaseInterface {

    public const CAPABILITY_COLLECTION_CREATE = 'CollectionCreate';
    public const CAPABILITY_COLLECTION_MODIFY = 'CollectionModify';
    public const CAPABILITY_COLLECTION_DESTROY = 'CollectionDestroy';
    public const CAPABILITY_COLLECTION_MOVE = 'CollectionMove';

    /**
     * Creates a fresh collection instance for configuration
     *
     * @since 2025.05.01
     *
     * @return ICollectionMutable Fresh collection object
     */
    public function collectionFresh(): ICollectionMutable;

    /**
     * Creates a new collection
     *
     * @since 2025.05.01
     *
     * @param string|int|null $location Parent collection ID (null for root)
     * @param ICollectionMutable $collection Collection to create
     * @param array $options Protocol-specific options
     *
     * @return ICollectionBase Created collection with assigned ID
     */
    public function collectionCreate(string|int|null $location, ICollectionMutable $collection, array $options = []): ICollectionBase;

    /**
     * Modifies an existing collection
     *
     * @since 2025.05.01
     *
     * @param string|int $identifier Collection ID
     * @param ICollectionMutable $collection Updated collection data
     *
     * @return ICollectionBase Modified collection
     */
    public function collectionModify(string|int $identifier, ICollectionMutable $collection): ICollectionBase;

    /**
     * Destroys a collection
     *
     * @since 2025.05.01
     *
     * @param string|int $identifier Collection ID
     * @param bool $recursive Destroy child collections too
     *
     * @return bool True if destroyed
     */
    public function collectionDestroy(string|int $identifier, bool $recursive = false): bool;

    /**
     * Moves a collection to a new parent
     *
     * @since 2025.05.01
     *
     * @param string|int $identifier Collection ID
     * @param string|int|null $targetLocation New parent ID (null for root)
     *
     * @return ICollectionBase Moved collection
     */
    public function collectionMove(string|int $identifier, string|int|null $targetLocation): ICollectionBase;

}