<?php
/**
 * SEO fix strategy contract.
 *
 * @package SmartyPress_AI_Engine
 * @since 1.0.0
 */

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

/**
 * Describes a single AI-assisted SEO assessment fix.
 */
interface SmartyPress_AI_SEO_Strategy_Interface {

	/**
	 * Get the SEO test identifier handled by this strategy.
	 *
	 * @return string
	 */
	public function get_test_id();

	/**
	 * Get the machine-readable reason for generated operations.
	 *
	 * @return string
	 */
	public function get_reason();

	/**
	 * Get a user-facing operation label.
	 *
	 * @return string
	 */
	public function get_label();

	/**
	 * Check whether the strategy can run for the current context.
	 *
	 * @param array $context  Cached SEO context.
	 * @param array $analysis Full-context SEO analysis.
	 * @return bool
	 */
	public function is_applicable( $context, $analysis );

	/**
	 * Get desired context scope.
	 *
	 * @return string local|expanded|full
	 */
	public function get_context_scope();

	/**
	 * Select the payload sent to the AI provider.
	 *
	 * @param array $context  Cached SEO context.
	 * @param array $analysis Full-context SEO analysis.
	 * @return array
	 */
	public function select_context( $context, $analysis );

	/**
	 * Get a JSON schema for the AI response.
	 *
	 * @return array
	 */
	public function get_response_schema();

	/**
	 * Validate and normalize an AI response.
	 *
	 * @param array $response Raw AI response.
	 * @param array $context  Cached SEO context.
	 * @param array $analysis Full-context SEO analysis.
	 * @return array
	 */
	public function validate_response( $response, $context, $analysis );
}
