<?php
/**
 * Operation contract.
 *
 * @package Recast\WCS
 */

namespace Recast\WCS\Operation;

use Recast\WCS\Diff\DiffSet;
use Recast\WCS\Run\RunItem;

defined( 'ABSPATH' ) || exit;

/**
 * A change that can be previewed (purely) and applied (through setters + save()) per subscription.
 */
interface OperationInterface {

	/**
	 * Unique id such as 'price.set'.
	 *
	 * @return string
	 */
	public function id();

	/**
	 * Descriptor for the UI and the registry.
	 *
	 * @return OperationDescriptor
	 */
	public function describe();

	/**
	 * Validates and normalises run-level params.
	 *
	 * @param array<string, mixed> $params Raw params.
	 * @return ValidationResult
	 */
	public function validate( array $params );

	/**
	 * State fields this operation may write for the given params (patterns like 'item:*:total' allowed).
	 *
	 * @param array<string, mixed> $params Normalised params.
	 * @return string[]
	 */
	public function touched_fields( array $params );

	/**
	 * Predicts the change WITHOUT mutating the subscription (no setters, no save()).
	 *
	 * @param \WC_Subscription     $subscription Subscription.
	 * @param array<string, mixed> $params       Normalised params.
	 * @return DiffSet
	 */
	public function compute_diff( \WC_Subscription $subscription, array $params );


	/**
	 * Warnings or blocks for undoing a previously applied item.
	 *
	 * @param RunItem          $item    Applied item (with before/after state).
	 * @param \WC_Subscription $current Current subscription.
	 * @return array<int, array{code: string, message: string, blocking: bool}>
	 */
	public function undo_constraints( RunItem $item, \WC_Subscription $current );
}