<?php
/**
 * Contract for a single product fix.
 *
 * @package AgentReadyForWooCommerce
 */

defined( 'ABSPATH' ) || exit;

/**
 * Interface ARWC_Fix
 *
 * A fix is the write-side counterpart to an {@see ARWC_Check}. Each fix inspects
 * one dimension of a product and proposes concrete, reviewable changes (a
 * before -> after diff). Nothing is written until apply() is called, which the
 * admin layer only does after an explicit, nonce-protected approval click.
 *
 * Implement this (or extend {@see ARWC_Abstract_Fix}) and register it on the
 * `arwc_fixes` filter to add a fix without touching the fixer.
 */
interface ARWC_Fix {

	/**
	 * Stable machine ID for this fix (e.g. "attributes"). Should mirror the
	 * related check ID where one exists.
	 *
	 * @return string
	 */
	public function get_id();

	/**
	 * Human-readable label.
	 *
	 * @return string
	 */
	public function get_label();

	/**
	 * Short description of what this fix changes.
	 *
	 * @return string
	 */
	public function get_description();

	/**
	 * Whether this fix belongs to the Pro tier (AI-backed).
	 *
	 * @return bool
	 */
	public function is_pro();

	/**
	 * Inspect a product and return the proposed changes for it.
	 *
	 * Must NOT write anything. Returns an array of proposal arrays, each shaped:
	 *  [
	 *    'field'       => string,  // machine field id within this fix
	 *    'label'       => string,  // human label for the field
	 *    'before'      => string,  // current value (display)
	 *    'after'       => string,  // proposed value (display); '' if input needed
	 *    'needs_input' => bool,    // true => merchant must type a value (e.g. GTIN)
	 *    'auto'        => bool,    // true => can be applied without merchant input
	 *    'note'        => string,  // optional guidance shown in the UI
	 *  ]
	 *
	 * An empty array means "nothing to fix here".
	 *
	 * @param WC_Product $product Product to inspect.
	 * @return array<int,array<string,mixed>>
	 */
	public function preview( WC_Product $product );

	/**
	 * Apply the fix to a product.
	 *
	 * Writes via WooCommerce CRUD only. The caller (the fixer) takes a snapshot
	 * BEFORE calling this so the change can be undone. Implementations should
	 * return an ARWC_Fix_Result describing what changed, or a WP_Error.
	 *
	 * @param WC_Product $product Product to modify.
	 * @param array      $input   Sanitized merchant input keyed by field id
	 *                            (e.g. [ 'gtin' => '0123456789012' ]).
	 * @return ARWC_Fix_Result|WP_Error
	 */
	public function apply( WC_Product $product, array $input );
}