<?php
/**
 * Entitlement provider contract.
 *
 * Implementors validate production entitlements against their channel (WooCommerce.com/marketplace).
 * An adapter between the Free plugin entitlement service and the official WooCommerce.com/marketplace contract.
 *
 * This interface defines a single source of truth for Pro execution capability, respecting the
 * channel contract documented in the MarginBeacon PRD and ADR. It MUST NOT rely on undocumented
 * WC_Helper fields, invent product IDs, API keys, URLs, credentials, or marketplace responses.
 *
 * States mapped to public presentation:
 *  - Free missing -> STATE_FREE_ONLY
 *  - Free incompatible -> STATE_FREE_ONLY
 *  - Pro inactive -> STATE_PRO_INSTALLED_INACTIVE
 *  - marketplace signal unavailable -> STATE_PRO_ACTIVE_NOT_ENTITLED
 *  - entitlement invalid/expired -> STATE_PRO_ACTIVE_NOT_ENTITLED
 *  - entitlement valid -> STATE_PRO_ACTIVE
 *  - temporary provider failure -> STATE_PRO_ACTIVE_NOT_ENTITLED
 *
 * @package Kayvandra\MarginBeacon\Application\Entitlement\Providers
 */

declare(strict_types=1);

namespace Kayvandra\MarginBeacon\Application\Entitlement\Providers;

/**
 * Contract for entitlement providers that implement the WooCommerce Marketplace integration.
 */
interface EntitlementProvider {

	/**
	 * Whether Pro execution is currently enabled for this site (entitlement contract satisfied).
	 *
	 * Returns true only when the official WooCommerce.com subscription signal indicates a
	 * valid entitlement for the site URL and product. Must NOT elevate based on local
	 * activation alone (dev bootstrap only for local/staging).
	 *
	 * @return bool True if Pro capabilities may be rendered.
	 */
	public function allows_pro_execution(): bool;

	/**
	 * Whether the provider itself is healthy and able to respond.
	 *
	 * Reflects that the channel integration contract is in place (e.g., Marketplace URL configured).
	 * When false, public UI must not display purchase/upgrade CTAs that reference an unavailable channel.
	 *
	 * @return bool True if the provider is ready for production use.
	 */
	public function is_available(): bool;

	/**
	 * Whether the provider is temporarily unavailable (network, cache stale, etc.).
	 *
	 * This is distinct from a permanent missing marketplace signal (is_available() === false).
	 * When true, the UI should present a deferred state (e.g., "Pro active but entitlement is being retrieved")
	 * but never a Safe financial result.
	 *
	 * @return bool True if the provider is currently unable to deliver an entitlement decision.
	 */
	public function is_unavailable(): bool;

	/**
	 * Refresh internal provider state (e.g., fetch subscription status, clear stale cache).
	 *
	 * Callable from admin_init, scheduled jobs, or manual actions. The provider must respect
	 * caching contracts and fail-closed when the channel is unreachable.
	 */
	public function refresh(): void;
}