<?php

declare(strict_types=1);

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

namespace KTXF\Chrono\Service;

use JsonSerializable;
use KTXF\Chrono\Collection\ICollectionBase;
use KTXF\Resource\Filter\IFilter;
use KTXF\Resource\Range\IRange;
use KTXF\Resource\Range\RangeType;
use KTXF\Resource\Sort\ISort;

interface IServiceBase extends JsonSerializable {

	public const CAPABILITY_COLLECTION_LIST = 'CollectionList';
	public const CAPABILITY_COLLECTION_LIST_FILTER = 'CollectionListFilter';
	public const CAPABILITY_COLLECTION_LIST_SORT = 'CollectionListSort';
	public const CAPABILITY_COLLECTION_EXTANT = 'CollectionExtant';
	public const CAPABILITY_COLLECTION_FETCH = 'CollectionFetch';

	public const CAPABILITY_ENTITY_LIST = 'EntityList';
	public const CAPABILITY_ENTITY_LIST_FILTER = 'EntityListFilter';
	public const CAPABILITY_ENTITY_LIST_SORT = 'EntityListSort';
	public const CAPABILITY_ENTITY_LIST_RANGE = 'EntityListRange';
	public const CAPABILITY_ENTITY_DELTA = 'EntityDelta';
	public const CAPABILITY_ENTITY_EXTANT = 'EntityExtant';
	public const CAPABILITY_ENTITY_FETCH = 'EntityFetch';

    public const CAPABILITY_FILTER_ANY = '*';
    public const CAPABILITY_FILTER_ID = 'id';
    public const CAPABILITY_FILTER_URID = 'urid';
    public const CAPABILITY_FILTER_LABEL = 'label';
    public const CAPABILITY_FILTER_DESCRIPTION = 'description';

    public const CAPABILITY_SORT_ID = 'id';
    public const CAPABILITY_SORT_URID = 'urid';
    public const CAPABILITY_SORT_LABEL = 'label';
    public const CAPABILITY_SORT_PRIORITY = 'priority';

    public const CAPABILITY_RANGE_TALLY = 'tally';
    public const CAPABILITY_RANGE_TALLY_ABSOLUTE = 'absolute';
    public const CAPABILITY_RANGE_TALLY_RELATIVE = 'relative';
    public const CAPABILITY_RANGE_DATE = 'date';

	public const JSON_TYPE = 'chrono.service';
	public const JSON_PROPERTY_TYPE = '@type';
	public const JSON_PROPERTY_PROVIDER = 'provider';
	public const JSON_PROPERTY_ID = 'id';
	public const JSON_PROPERTY_LABEL = 'label';
	public const JSON_PROPERTY_CAPABILITIES = 'capabilities';
	public const JSON_PROPERTY_ENABLED = 'enabled';

	/**
	 * Confirms if specific capability is supported
	 *
	 * @since 2025.05.01
	 *
	 * @param string $value required ability e.g. 'EntityList'
	 *
	 * @return bool
	 */
	public function capable(string $value): bool;

	/**
	 * Lists all supported capabilities
	 *
	 * @since 2025.05.01
	 *
	 * @return array<string,bool>
	 */
	public function capabilities(): array;

	/**
	 * Unique identifier of the provider this service belongs to
	 *
	 * @since 2025.05.01
	 */
	public function in(): string;

	/**
	 * Unique arbitrary text string identifying this service (e.g. 1 or service1 or anything else)
	 *
	 * @since 2025.05.01
	 */
	public function id(): string|int;

	/**
	 * Gets the localized human friendly name of this service (e.g. ACME Company Calendar Service)
	 *
	 * @since 2025.05.01
	 */
	public function getLabel(): string;

	/**
	 * Gets the active status of this service
	 *
	 * @since 2025.05.01
	 */
	public function getEnabled(): bool;

	/**
	 * Retrieve collection of collections for this service
	 *
	 * @since 2025.05.01
	 */
	public function collectionList(?IFilter $filter = null, ?ISort $sort = null): array;

	/**
	 * Retrieve filter object for collection list
	 *
	 * @since 2025.05.01
	 */
	public function collectionListFilter(): IFilter;

	/**
	 * Retrieve sort object for collection list
	 *
	 * @since 2025.05.01
	 */
	public function collectionListSort(): ISort;

	/**
	 * Determine if a collection exists
	 *
	 * @since 2025.05.01
	 */
	public function collectionExtant(string|int $identifier): bool;

	/**
	 * Retrieve a specific collection
	 *
	 * @since 2025.05.01
	 */
	public function collectionFetch(string|int $identifier): ?ICollectionBase;

	/**
	 * Retrieve collection of entities from a specific collection
	 *
	 * @since 2025.05.01
	 */
	public function entityList(string|int $collection, ?IFilter $filter = null, ?ISort $sort = null, ?IRange $range = null, ?array $elements = null): array;

	/**
	 * Retrieve filter object for entity list
	 *
	 * @since 2025.05.01
	 */
	public function entityListFilter(): IFilter;

	/**
	 * Retrieve sort object for entity list
	 *
	 * @since 2025.05.01
	 */
	public function entityListSort(): ISort;

	/**
	 * Retrieve range object for entity list
	 *
	 * @since 2025.05.01
	 */
	public function entityListRange(RangeType $type): IRange;

	/**
	 * Retrieve collection of entities that have changed since a given signature
	 *
	 * @since 2025.05.01
	 *
	 * @param string|int $collection collection identifier
	 * @param string $signature signature to compare against
	 * @param string $detail level of detail to return (ids, full, etc)
	 *
	 * @return array collection of entities or entity identifiers
	 */
	public function entityDelta(string|int $collection, string $signature, string $detail = 'ids'): array;

	/**
	 * Determine if entities exist in a specific collection
	 *
	 * @since 2025.05.01
	 */
	public function entityExtant(string|int $collection, string|int ...$identifiers): array;

	/**
	 * Retrieve specific entities from a specific collection
	 *
	 * @since 2025.05.01
	 */
	public function entityFetch(string|int $collection, string|int ...$identifiers): array;

}