<?php

declare(strict_types=1);

namespace KTXF\Resource\Provider;

use KTXF\Json\JsonSerializable;

/**
 * Resource Provider Interface
 */
interface ResourceProviderBaseInterface extends ProviderInterface, JsonSerializable
{
	public const CAPABILITY_SERVICE_LIST = 'ServiceList';
	public const CAPABILITY_SERVICE_FETCH = 'ServiceFetch';
	public const CAPABILITY_SERVICE_EXTANT = 'ServiceExtant';
	public const CAPABILITY_SERVICE_CREATE = 'ServiceCreate';
	public const CAPABILITY_SERVICE_MODIFY = 'ServiceModify';
	public const CAPABILITY_SERVICE_DESTROY = 'ServiceDestroy';
	public const CAPABILITY_SERVICE_DISCOVER = 'ServiceDiscover';
	public const CAPABILITY_SERVICE_TEST = 'ServiceTest';

	public const JSON_TYPE = 'resource.provider';
	public const JSON_PROPERTY_TYPE = '@type';
	public const JSON_PROPERTY_IDENTIFIER = 'identifier';
	public const JSON_PROPERTY_LABEL = 'label';
	public const JSON_PROPERTY_CAPABILITIES = 'capabilities';

	/**
	 * Confirms if specific capability is supported (e.g. 'ServiceList')
	 *
	 * @since 2025.11.01
	 */
	public function capable(string $value): bool;

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

    /**
	 * Retrieve collection of services for a specific user
	 *
	 * @since 2025.11.01
	 *
	 * @param string $tenantId tenant identifier
	 * @param string $userId user identifier
	 * @param array $filter filter criteria
	 *
	 * @return array<string,ResourceServiceBaseInterface> collection of service objects
	 */
	public function serviceList(string $tenantId, string $userId, array $filter): array;

	/**
	 * Determine if any services are configured for a specific user
	 *
	 * @since 2025.11.01
	 *
	 * @param string $tenantId tenant identifier
	 * @param string $userId user identifier
	 * @param int|string ...$identifiers variadic collection of service identifiers
	 * 
	 * @return array<string,bool> collection of service identifiers with boolean values indicating if the service is available
	 */
	public function serviceExtant(string $tenantId, string $userId, int|string ...$identifiers): array;

	/**
	 * Retrieve a service with a specific identifier
	 *
	 * @since 2025.11.01
	 *
	 * @param string $tenantId tenant identifier
	 * @param string $userId user identifier
	 * @param string|int $identifier service identifier
	 *
	 * @return ResourceServiceBaseInterface|null returns service object or null if non found
	 */
	public function serviceFetch(string $tenantId, string $userId, string|int $identifier): ?ResourceServiceBaseInterface;

}