<?php
/**
 * Wizard State
 *
 * Centralised option key constants and helpers for tracking the setup wizard's
 * progress so no other file hard-codes option names.
 *
 * @package AmbassadorHub\Admin\Wizard
 */

namespace AmbassadorHub\Admin\Wizard;

if ( ! defined( 'ABSPATH' ) ) {
	exit;
}

/**
 * Manages the setup wizard's persistent state via WordPress options and transients.
 */
final class WizardState {

	/** Option: whether the wizard has been completed or explicitly skipped. */
	public const OPTION_COMPLETED = 'ambh_wizard_completed';

	/** Option: the current step index (0-based) the user is on. */
	public const OPTION_STEP = 'ambh_wizard_step';

	/** Transient: set on activation to trigger the first-run redirect. */
	public const TRANSIENT_REDIRECT = 'ambh_wizard_redirect';

	/**
	 * Schedule the first-run redirect by setting a short-lived transient.
	 *
	 * Called during plugin activation. Expires in 60 seconds so it only fires
	 * on the very next admin page load after activation.
	 *
	 * @return void
	 */
	public static function schedule_redirect(): void {
		self::set_step( 0 );
		set_transient( self::TRANSIENT_REDIRECT, '1', 60 );
	}

	/**
	 * Whether the wizard has been completed or fully skipped.
	 *
	 * @return bool
	 */
	public static function is_completed(): bool {
		return (bool) get_option( self::OPTION_COMPLETED, false );
	}

	/**
	 * Mark the wizard as completed / skipped and clean up step state.
	 *
	 * @return void
	 */
	public static function mark_completed(): void {
		update_option( self::OPTION_COMPLETED, '1', false );
		delete_option( self::OPTION_STEP );
	}

	/**
	 * Get the current wizard step index (0-based).
	 *
	 * @return int
	 */
	public static function get_step(): int {
		return (int) get_option( self::OPTION_STEP, 0 );
	}

	/**
	 * Persist the current wizard step index.
	 *
	 * @param int $step Step index.
	 * @return void
	 */
	public static function set_step( int $step ): void {
		update_option( self::OPTION_STEP, $step, false );
	}
}
