<?php

declare(strict_types=1);

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

namespace KTXF\People\Service;

use KTXF\People\Collection\CollectionBaseInterface;
use KTXF\People\Collection\CollectionMutableInterface;
use KTXF\People\Collection\CollectionPropertiesBaseInterface;
use KTXF\Resource\Identifier\CollectionIdentifierInterface;

/**
 * People Service Collection Mutable Interface
 * 
 * Optional interface for services that support collection CRUD operations.
 * 
 * @since 2025.05.01
 */
interface ServiceCollectionMutableInterface {

    public const CAPABILITY_COLLECTION_CREATE = 'CollectionCreate';
    public const CAPABILITY_COLLECTION_UPDATE = 'CollectionUpdate';
    public const CAPABILITY_COLLECTION_DELETE = 'CollectionDelete';

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

    /**
     * Creates a new collection
     *
     * @since 2025.05.01
     *
     * @param CollectionIdentifierInterface|null $target Target collection identifier (parent)
     * @param CollectionPropertiesBaseInterface $properties Collection properties
     * @param array $options Protocol-specific options
     *
     * @return CollectionBaseInterface Created collection with assigned ID
     */
    public function collectionCreate(CollectionIdentifierInterface|null $target, CollectionPropertiesBaseInterface $properties, array $options = []): CollectionBaseInterface;

    /**
     * Updates an existing collection
     *
     * @since 2025.05.01
     *
     * @param CollectionIdentifierInterface $target Target collection identifier
     * @param CollectionPropertiesBaseInterface $properties Updated collection data
     *
     * @return CollectionBaseInterface Updated collection
     */
    public function collectionUpdate(CollectionIdentifierInterface $target, CollectionPropertiesBaseInterface $properties): CollectionBaseInterface;

    /**
     * Deletes a collection
     *
     * @since 2025.05.01
     *
     * @param CollectionIdentifierInterface $target Target collection identifier
     * @param bool $force Force deletion even if not empty
     *
     * @return CollectionBaseInterface|true Collection object on soft delete, true on hard delete
     */
    public function collectionDelete(CollectionIdentifierInterface $target, bool $force = false): CollectionBaseInterface | true;

}