* SPDX-License-Identifier: AGPL-3.0-or-later */ namespace KTXF\Chrono\Service; use KTXF\Chrono\Collection\CollectionBaseInterface; use KTXF\Resource\Delta\Delta; use KTXF\Resource\Filter\IFilter; use KTXF\Resource\Provider\ResourceServiceBaseInterface; use KTXF\Resource\Range\IRange; use KTXF\Resource\Range\RangeType; use KTXF\Resource\Sort\ISort; /** * Chrono Service Base Interface * * @since 2025.05.01 */ interface ServiceBaseInterface extends ResourceServiceBaseInterface { // 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'; // Collection Filter public const CAPABILITY_COLLECTION_FILTER_LABEL = 'label'; public const CAPABILITY_COLLECTION_FILTER_CONTENTS = 'contents'; // Collection Sort public const CAPABILITY_COLLECTION_SORT_LABEL = 'label'; public const CAPABILITY_COLLECTION_SORT_RANK = 'rank'; // 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'; // Filter capabilities public const CAPABILITY_ENTITY_FILTER_ALL = '*'; public const CAPABILITY_ENTITY_FILTER_ID = 'id'; public const CAPABILITY_ENTITY_FILTER_URID = 'urid'; public const CAPABILITY_ENTITY_FILTER_LABEL = 'label'; // Sort capabilities public const CAPABILITY_ENTITY_SORT_ID = 'id'; public const CAPABILITY_ENTITY_SORT_URID = 'urid'; public const CAPABILITY_ENTITY_SORT_LABEL = 'label'; public const CAPABILITY_ENTITY_SORT_PRIORITY = 'priority'; // Range capabilities public const CAPABILITY_ENTITY_RANGE_TALLY = 'tally'; public const CAPABILITY_ENTITY_RANGE_TALLY_ABSOLUTE = 'absolute'; public const CAPABILITY_ENTITY_RANGE_TALLY_RELATIVE = 'relative'; public const CAPABILITY_ENTITY_RANGE_DATE = 'date'; public const JSON_TYPE = 'chrono.service'; /** * Lists all collections in this service * * @since 2025.05.01 * * @param IFilter|null $filter Optional filter criteria * @param ISort|null $sort Optional sort order * * @return array Collections indexed by ID */ public function collectionList(string|int $location, ?IFilter $filter = null, ?ISort $sort = null): array; /** * Creates a filter builder for collections * * @since 2025.05.01 * * @return IFilter */ public function collectionListFilter(): IFilter; /** * Creates a sort builder for collections * * @since 2025.05.01 * * @return ISort */ public function collectionListSort(): ISort; /** * Checks if collections exist * * @since 2025.05.01 * * @param string|int ...$identifiers Collection IDs to check * * @return array Map of ID => exists */ public function collectionExtant(string|int $location, string|int ...$identifiers): array; /** * Fetches a single collection * * @since 2025.05.01 * * @param string|int $identifier Collection ID * * @return CollectionBaseInterface|null Collection or null if not found */ public function collectionFetch(string|int $identifier): ?CollectionBaseInterface; /** * Lists messages in a collection * * @since 2025.05.01 * * @param string|int $collection Collection ID * @param IFilter|null $filter Optional filter criteria * @param ISort|null $sort Optional sort order * @param IRange|null $range Optional pagination * @param array|null $properties Optional message properties to fetch * * @return array Messages indexed by ID */ public function entityList(string|int $collection, ?IFilter $filter = null, ?ISort $sort = null, ?IRange $range = null, ?array $properties = null): array; /** * Creates a filter builder for messages * * @since 2025.05.01 * * @return IFilter */ public function entityListFilter(): IFilter; /** * Creates a sort builder for messages * * @since 2025.05.01 * * @return ISort */ public function entityListSort(): ISort; /** * Creates a range builder for messages * * @since 2025.05.01 * * @param RangeType $type Range type (offset, cursor, etc.) * * @return IRange */ public function entityListRange(RangeType $type): IRange; /** * Gets incremental changes since last sync * * @since 2025.05.01 * * @param string|int $collection Collection ID * @param string $signature Sync token from previous sync * @param string $detail Detail level: 'ids', 'minimal', 'full' * * @return array ['signature' => string, 'added' => array, 'modified' => array, 'removed' => array] */ public function entityDelta(string|int $collection, string $signature, string $detail = 'ids'): Delta; /** * Checks if messages exist * * @since 2025.05.01 * * @param string|int $collection Collection ID * @param string|int ...$identifiers Message IDs to check * * @return array Map of ID => exists */ public function entityExtant(string|int $collection, string|int ...$identifiers): array; /** * Fetches one or more entities * * @since 2025.05.01 * * @param string|int $collection Collection ID * @param string|int ...$identifiers Message IDs to fetch * * @return array Messages indexed by ID */ public function entityFetch(string|int $collection, string|int ...$identifiers): array; }