<?php // phpcs:ignore WordPress.Files.FileName.NotHyphenatedLowercase, WordPress.Files.FileName.InvalidClassFileName
/**
 * Interface for the Snooze options provider.
 *
 * @package Autoship\Services\Snooze\Interfaces
 * @since   2.13.0
 */

namespace Autoship\Services\Snooze\Interfaces;

/**
 * Provides snooze duration options to the subscriber-facing UI.
 *
 * The provider resolves the duration list from the configured source
 * (QMC merchant settings or plugin defaults), with a fallback chain so
 * the front-end never renders an empty picker.
 *
 * Each option in the returned array uses PascalCase keys for internal
 * consistency: Duration, DurationType, IsDefault, Enabled, Order. Plugin
 * defaults additionally carry an optional Label key.
 */
interface SnoozeOptionsProviderInterface {

	/**
	 * Resolve the snooze options for the current site.
	 *
	 * Precedence (when source = "qmc"):
	 *   1. Cached QMC frequencies (transient).
	 *   2. Live QMC fetch via the QPilot API.
	 *   3. Plugin default frequencies (fallback).
	 *
	 * When source = "plugin", returns plugin defaults directly without
	 * consulting QMC or the cache.
	 *
	 * @param bool $refresh Force a fresh fetch, bypassing the cache.
	 *
	 * @return array<int, array<string, mixed>> Ordered list of options.
	 */
	public function get_options( bool $refresh = false ): array;

	/**
	 * Plugin default frequency list.
	 *
	 * Reads merchant-configured rows from `autoship_snooze_plugin_frequencies`
	 * and maps them to the PascalCase shape. Falls back to a hard-coded
	 * 5-row list when nothing is saved.
	 *
	 * @return array<int, array<string, mixed>> Plugin default options.
	 */
	public function get_default_options(): array;

	/**
	 * Invalidate the cached QMC frequencies for the current site.
	 *
	 * @return void
	 */
	public function clear_cache(): void;
}
