<?php

declare(strict_types=1);

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

namespace KTXF\Files\Service;

use KTXF\Files\Node\INodeCollectionBase;
use KTXF\Files\Node\INodeCollectionMutable;

interface IServiceCollectionMutable extends IServiceBase {

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

	/**
	 * Creates a new, empty collection node
	 *
	 * @since 2025.11.01
	 */
	public function collectionFresh(): INodeCollectionMutable;

	/**
	 * Creates a new collection at the specified location
	 *
	 * @since 2025.11.01
	 *
	 * @param string|int|null $location Parent collection, null for root
	 * @param INodeCollectionMutable $collection The collection to create
	 * @param array $options Additional options
	 *
	 * @throws \KTXF\Resource\Exceptions\InvalidArgumentException
	 * @throws \KTXF\Resource\Exceptions\UnsupportedException
	 * @throws \KTXF\Resource\Exceptions\UnauthorizedException
	 */
	public function collectionCreate(string|int|null $location, INodeCollectionMutable $collection, array $options = []): INodeCollectionBase;

	/**
	 * Modifies an existing collection
	 *
	 * @since 2025.11.01
	 *
	 * @param string|int $identifier Collection identifier
	 * @param INodeCollectionMutable $collection The collection with modifications
	 *
	 * @throws \KTXF\Resource\Exceptions\InvalidArgumentException
	 * @throws \KTXF\Resource\Exceptions\UnsupportedException
	 * @throws \KTXF\Resource\Exceptions\UnauthorizedException
	 */
	public function collectionModify(string|int $identifier, INodeCollectionMutable $collection): INodeCollectionBase;

	/**
	 * Destroys an existing collection
	 *
	 * @since 2025.11.01
	 *
	 * @param string|int $identifier Collection identifier
	 *
	 * @throws \KTXF\Resource\Exceptions\InvalidArgumentException
	 * @throws \KTXF\Resource\Exceptions\UnsupportedException
	 * @throws \KTXF\Resource\Exceptions\UnauthorizedException
	 */
	public function collectionDestroy(string|int $identifier): bool;

	/**
	 * Copies an existing collection to a new location
	 *
	 * @since 2025.11.01
	 *
	 * @param string|int $identifier Collection identifier
	 * @param string|int|null $location Destination parent collection, null for root
	 *
	 * @throws \KTXF\Resource\Exceptions\InvalidArgumentException
	 * @throws \KTXF\Resource\Exceptions\UnsupportedException
	 * @throws \KTXF\Resource\Exceptions\UnauthorizedException
	 */
	public function collectionCopy(string|int $identifier, string|int|null $location): INodeCollectionBase;

	/**
	 * Moves an existing collection to a new location
	 *
	 * @since 2025.11.01
	 *
	 * @param string|int $identifier Collection identifier
	 * @param string|int|null $location Destination parent collection, null for root
	 *
	 * @throws \KTXF\Resource\Exceptions\InvalidArgumentException
	 * @throws \KTXF\Resource\Exceptions\UnsupportedException
	 * @throws \KTXF\Resource\Exceptions\UnauthorizedException
	 */
	public function collectionMove(string|int $identifier, string|int|null $location): INodeCollectionBase;

}