<?php

declare(strict_types=1);

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

namespace KTXF\People\Collection;

use DateTimeImmutable;
use JsonSerializable;

interface ICollectionBase extends JsonSerializable {

	public const JSON_TYPE = 'people.collection';
	public const JSON_PROPERTY_TYPE = '@type';
	public const JSON_PROPERTY_PROVIDER = 'provider';
	public const JSON_PROPERTY_SERVICE = 'service';
	public const JSON_PROPERTY_IN = 'in';
	public const JSON_PROPERTY_ID = 'id';
	public const JSON_PROPERTY_LABEL = 'label';
	public const JSON_PROPERTY_DESCRIPTION = 'description';
	public const JSON_PROPERTY_PRIORITY = 'priority';
	public const JSON_PROPERTY_VISIBILITY = 'visibility';
	public const JSON_PROPERTY_COLOR = 'color';
	public const JSON_PROPERTY_CREATED = 'created';
	public const JSON_PROPERTY_MODIFIED = 'modified';
	public const JSON_PROPERTY_ENABLED = 'enabled';
	public const JSON_PROPERTY_SIGNATURE = 'signature';
	public const JSON_PROPERTY_PERMISSIONS = 'permissions';
	public const JSON_PROPERTY_ROLES = 'roles';
	public const JSON_PROPERTY_CONTENTS = 'contents';

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

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

	/**
	 * Gets the creation date of this collection
	 */
	public function created(): ?DateTimeImmutable;
	
	/**
	 * Gets the modification date of this collection
	 */
	public function modified(): ?DateTimeImmutable;

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

	/**
	 * Gets the signature of this collection
	 *
	 * @since 2025.05.01
	 */
	public function signature(): ?string;

	/**
	 * Gets the role(s) of this collection
	 *
	 * @since 2025.05.01
	 */
	public function roles(): array;

	/**
	 * Checks if this collection supports the given role
	 *
	 * @since 2025.05.01
	 */
	public function role(CollectionRoles $value): bool;

	/**
	 * Gets the content types of this collection
	 *
	 * @since 2025.05.01
	 */
	public function contents(): array;

	/**
	 * Checks if this collection contains the given content type
	 *
	 * @since 2025.05.01
	 */
	public function contains(CollectionContent $value): bool;

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

	/**
	 * Gets the active status of this collection
	 *
	 * @since 2025.05.01
	 */
	public function getPermissions(): array;

	/**
	 * Checks if this collection has the given permission
	 *
	 * @since 2025.05.01
	 */
	public function hasPermission(CollectionPermissions $permission): bool;

	/**
	 * Gets the human friendly name of this collection (e.g. Personal Contacts)
	 *
	 * @since 2025.05.01
	 */
	public function getLabel(): ?string;

	/**
	 * Gets the human friendly description of this collection
	 *
	 * @since 2025.05.01
	 */
	public function getDescription(): ?string;

	/**
	 * Gets the priority of this collection
	 *
	 * @since 2025.05.01
	 */
	public function getPriority(): ?int;

	/**
	 * Gets the visibility of this collection
	 *
	 * @since 2025.05.01
	 */
	public function getVisibility(): ?bool;

	/**
	 * Gets the color of this collection
	 *
	 * @since 2025.05.01
	 */
	public function getColor(): ?string;

}