<?php // phpcs:ignore WordPress.Files.FileName.NotHyphenatedLowercase, WordPress.Files.FileName.InvalidClassFileName
/**
 * Interface for Snooze-aware QPilot feature flag checks.
 *
 * @package Autoship\Services\Snooze\Interfaces
 * @since   2.13.0
 */

namespace Autoship\Services\Snooze\Interfaces;

/**
 * Snooze-specific helpers around the QPilot remote feature flag list.
 *
 * Wraps the unified `Plugin::fetch_qpilot_feature_flags()` cache so the
 * snooze feature can ask its own questions ("is the flag definitely
 * off?") without re-fetching or duplicating the cache.
 */
interface SnoozeFeatureFlagsInterface {

	/**
	 * Whether the QPilot 'enable-snooze' flag is enabled.
	 *
	 * Permissive: returns true when the remote flag list could not be
	 * fetched, so transient API issues do not block merchants from
	 * configuring the feature.
	 *
	 * @return bool
	 */
	public function is_snooze_flag_enabled(): bool;

	/**
	 * Whether the 'enable-snooze' flag is *definitively* absent.
	 *
	 * Returns true only when we successfully fetched a non-empty flag
	 * list AND `enable-snooze` is missing. Use this for surfaces that
	 * should only display a warning when the situation is certain
	 * (e.g., the WP-Admin warning banner).
	 *
	 * @return bool
	 */
	public function is_snooze_flag_definitively_off(): bool;

	/**
	 * The resolved remote feature flag list (merged global + site).
	 *
	 * @return array<string>
	 */
	public function get_flags(): array;
}
