<?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\Entity\IEntityBase;
use KTXF\People\Entity\IEntityMutable;

interface IServiceEntityMutable extends IServiceBase {

	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 of the specified type
	 *
	 * @since 2025.05.01
	 *
	 * @return IEntityMutable
	 */
	public function entityFresh(): IEntityMutable;

	/**
	 * Creates a new entity in the specified collection
	 *
	 * @since 2025.05.01
	 *
	 * @param string|int $collection The collection to create this entity in
	 * @param IEntityMutable $entity The entity to create
	 * @param array $options Additional options for the entity creation
	 *
	 * @return IEntityMutable
	 *
	 * @throws \KTXF\Resource\Exceptions\InvalidArgumentException
	 * @throws \KTXF\Resource\Exceptions\UnsupportedException
	 * @throws \KTXF\Resource\Exceptions\UnauthorizedException
	 */
	public function entityCreate(string|int $collection, IEntityMutable $entity, array $options): IEntityMutable;

	/**
	 * Modifies an existing entity in the specified collection
	 *
	 * @since 2025.05.01
	 *
	 * @param string|int $collection The collection containing the entity to modify
	 * @param string|int $identifier The ID of the entity to modify
	 * @param IEntityMutable $entity The entity with modifications
	 *
	 * @return IEntityMutable
	 *
	 * @throws \KTXF\Resource\Exceptions\InvalidArgumentException
	 * @throws \KTXF\Resource\Exceptions\UnsupportedException
	 * @throws \KTXF\Resource\Exceptions\UnauthorizedException
	 */
	public function entityModify(string|int $collection, string|int $identifier, IEntityMutable $entity): IEntityMutable;

	/**
	 * Destroys an existing entity in the specified collection
	 *
	 * @since 2025.05.01
	 *
	 * @param string|int $collection The collection containing the entity to destroy
	 * @param string|int $identifier The ID of the entity to destroy
	 *
	 * @return bool
	 *
	 * @throws \KTXF\Resource\Exceptions\InvalidArgumentException
	 * @throws \KTXF\Resource\Exceptions\UnsupportedException
	 * @throws \KTXF\Resource\Exceptions\UnauthorizedException
	 */
	public function entityDestroy(string|int $collection, string|int $identifier): IEntityBase;

}