<?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 JsonSerializable;
use KTXF\Files\Node\INodeBase;
use KTXF\Files\Node\INodeCollectionBase;
use KTXF\Files\Node\INodeEntityBase;
use KTXF\Resource\Filter\IFilter;
use KTXF\Resource\Range\IRange;
use KTXF\Resource\Range\RangeType;
use KTXF\Resource\Sort\ISort;

interface IServiceBase extends JsonSerializable {

	// Collection Capabilities
	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';

	// Entity Capabilities
	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_ENTITY_READ = 'EntityRead';
	public const CAPABILITY_ENTITY_READ_STREAM = 'EntityReadStream';
	public const CAPABILITY_ENTITY_READ_CHUNK = 'EntityReadChunk';

	// Node Capabilities (recursive/unified)
	public const CAPABILITY_NODE_LIST = 'NodeList';
	public const CAPABILITY_NODE_LIST_FILTER = 'NodeListFilter';
	public const CAPABILITY_NODE_LIST_SORT = 'NodeListSort';
	public const CAPABILITY_NODE_LIST_RANGE = 'NodeListRange';
	public const CAPABILITY_NODE_DELTA = 'NodeDelta';

	// JSON Constants
	public const JSON_TYPE = 'files.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.11.01
	 *
	 * @param string $value required ability e.g. 'EntityList'
	 *
	 * @return bool
	 */
	public function capable(string $value): bool;

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

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

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

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

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

	// ==================== Collection Methods ====================

	/**
	 * List of accessible collections at a specific location
	 *
	 * @since 2025.11.01
	 *
	 * @param string|int|null $location Parent collection identifier, null for root
	 *
	 * @return array<string|int,INodeCollectionBase>
	 */
	public function collectionList(string|int|null $location = null, ?IFilter $filter = null, ?ISort $sort = null): array;

	/**
	 * Fresh filter for collection list
	 *
	 * @since 2025.11.01
	 */
	public function collectionListFilter(): IFilter;

	/**
	 * Fresh sort for collection list
	 *
	 * @since 2025.11.01
	 */
	public function collectionListSort(): ISort;

	/**
	 * Confirms if specific collection exists
	 *
	 * @since 2025.11.01
	 *
	 * @param string|int|null $identifier Collection identifier
	 */
	public function collectionExtant(string|int|null $identifier): bool;

	/**
	 * Fetches details about a specific collection
	 *
	 * @since 2025.11.01
	 *
	 * @param string|int|null $identifier Collection identifier
	 */
	public function collectionFetch(string|int|null $identifier): ?INodeCollectionBase;

	// ==================== Entity Methods ====================

	/**
	 * Lists all entities in a specific collection
	 *
	 * @since 2025.11.01
	 *
	 * @param string|int|null $collection Collection identifier
	 *
	 * @return array<string|int,INodeEntityBase>
	 */
	public function entityList(string|int|null $collection, ?IFilter $filter = null, ?ISort $sort = null, ?IRange $range = null): array;

	/**
	 * Fresh filter for entity list
	 *
	 * @since 2025.11.01
	 */
	public function entityListFilter(): IFilter;

	/**
	 * Fresh sort for entity list
	 *
	 * @since 2025.11.01
	 */
	public function entityListSort(): ISort;

	/**
	 * Fresh range for entity list
	 *
	 * @since 2025.11.01
	 */
	public function entityListRange(RangeType $type): IRange;

	/**
	 * Lists all changes from a specific signature
	 *
	 * @since 2025.11.01
	 *
	 * @param string|int|null $collection Collection identifier
	 * @param string $signature Sync token signature
	 * @param string $detail Detail level: ids | meta | full
	 *
	 * @return array{
	 *     added: array<string|int>,
	 *     updated: array<string|int>,
	 *     deleted: array<string|int>,
	 *     signature: string
	 * }
	 */
	public function entityDelta(string|int|null $collection, string $signature, string $detail = 'ids'): array;

	/**
	 * Confirms if specific entities exist in a collection
	 *
	 * @since 2025.11.01
	 *
	 * @param string|int|null $collection Collection identifier
	 * @param string|int ...$identifiers Entity identifiers
	 *
	 * @return array<string|int,bool>
	 */
	public function entityExtant(string|int|null $collection, string|int ...$identifiers): array;

	/**
	 * Fetches details about specific entities in a collection
	 *
	 * @since 2025.11.01
	 *
	 * @param string|int|null $collection Collection identifier
	 * @param string|int ...$identifiers Entity identifiers
	 *
	 * @return array<string|int,INodeEntityBase>
	 */
	public function entityFetch(string|int|null $collection, string|int ...$identifiers): array;

	/**
	 * Reads the entire content of an entity as a string
	 *
	 * @since 2025.11.01
	 *
	 * @param string|int|null $collection Collection identifier
	 * @param string|int $identifier Entity identifier
	 *
	 * @return string|null File content or null if not found
	 *
	 * @throws \KTXF\Resource\Exceptions\InvalidArgumentException
	 * @throws \KTXF\Resource\Exceptions\UnsupportedException
	 * @throws \KTXF\Resource\Exceptions\UnauthorizedException
	 */
	public function entityRead(string|int|null $collection, string|int $identifier): ?string;

	/**
	 * Opens a stream to read the content of an entity
	 *
	 * @since 2025.11.01
	 *
	 * @param string|int|null $collection Collection identifier
	 * @param string|int $identifier Entity identifier
	 *
	 * @return resource|null Stream resource or null if not found
	 *
	 * @throws \KTXF\Resource\Exceptions\InvalidArgumentException
	 * @throws \KTXF\Resource\Exceptions\UnsupportedException
	 * @throws \KTXF\Resource\Exceptions\UnauthorizedException
	 */
	public function entityReadStream(string|int|null $collection, string|int $identifier);

	/**
	 * Reads a chunk of content from an entity
	 *
	 * @since 2025.11.01
	 *
	 * @param string|int|null $collection Collection identifier
	 * @param string|int $identifier Entity identifier
	 * @param int $offset Starting byte position (0-indexed)
	 * @param int $length Number of bytes to read
	 *
	 * @return string|null Chunk content or null if not found
	 *
	 * @throws \KTXF\Resource\Exceptions\InvalidArgumentException
	 * @throws \KTXF\Resource\Exceptions\UnsupportedException
	 * @throws \KTXF\Resource\Exceptions\UnauthorizedException
	 */
	public function entityReadChunk(string|int|null $collection, string|int $identifier, int $offset, int $length): ?string;

	// ==================== Node Methods (Recursive/Unified) ====================

	/**
	 * Lists all nodes (collections and entities) at a location, optionally recursive
	 * Returns a flat list with parent references via in()
	 *
	 * @since 2025.11.01
	 *
	 * @param string|int|null $location Starting location, null for root
	 * @param bool $recursive Whether to list recursively
	 *
	 * @return array<string|int,INodeBase>
	 */
	public function nodeList(string|int|null $location = null, bool $recursive = false, ?IFilter $filter = null, ?ISort $sort = null, ?IRange $range = null): array;

	/**
	 * Fresh filter for node list
	 *
	 * @since 2025.11.01
	 */
	public function nodeListFilter(): IFilter;

	/**
	 * Fresh sort for node list
	 *
	 * @since 2025.11.01
	 */
	public function nodeListSort(): ISort;

	/**
	 * Fresh range for node list
	 *
	 * @since 2025.11.01
	 */
	public function nodeListRange(RangeType $type): IRange;

	/**
	 * Lists all node changes from a specific signature, optionally recursive
	 * Returns flat list with parent references
	 *
	 * @since 2025.11.01
	 *
	 * @param string|int|null $location Starting location, null for root
	 * @param string $signature Sync token signature
	 * @param bool $recursive Whether to include recursive changes
	 * @param string $detail Detail level: ids | meta | full
	 *
	 * @return array{
	 *     added: array<string|int,INodeBase>|array<string|int>,
	 *     updated: array<string|int,INodeBase>|array<string|int>,
	 *     deleted: array<string|int>,
	 *     signature: string
	 * }
	 */
	public function nodeDelta(string|int|null $location, string $signature, bool $recursive = false, string $detail = 'ids'): array;

}