<?php // phpcs:ignore WordPress.Files.FileName.NotHyphenatedLowercase, WordPress.Files.FileName.InvalidClassFileName
/**
 * Interface for wholesale pricing operations.
 *
 * @package Autoship\Modules\WholesalePricing\Services
 * @since   2.13.0
 */

namespace Autoship\Modules\WholesalePricing\Services;

use Autoship\Domain\WholesalePricing\WholesaleValidationResult;

/**
 * Interface for wholesale pricing operations.
 *
 * Single entry point for all wholesale pricing validation and price adjustments.
 *
 * @package Autoship\Modules\WholesalePricing\Services
 * @since   2.13.0
 */
interface WholesalePricingServiceInterface {

	/**
	 * Validate wholesale requirements for a given user/role/product.
	 *
	 * @param array    $user_wholesale_role The user's wholesale role.
	 * @param int      $qty                Actual item quantity.
	 * @param float    $total              Actual item total price.
	 * @param int|bool $product_id         The product ID.
	 *
	 * @return WholesaleValidationResult
	 */
	public function validate( array $user_wholesale_role, int $qty, float $total, $product_id = false ): WholesaleValidationResult;

	/**
	 * Adjust the wholesale price for a product.
	 *
	 * @param int           $product_id          The product ID.
	 * @param float|null    $base_wholesale_price The base wholesale price.
	 * @param float|null    $regular_price        The regular price.
	 * @param \WP_User|null $wp_user              The user. Defaults to current user.
	 *
	 * @return float|null The adjusted wholesale price, or null.
	 */
	public function adjust_price( int $product_id, ?float $base_wholesale_price = null, ?float $regular_price = null, $wp_user = null ): ?float;

	/**
	 * Get the user's wholesale role.
	 *
	 * @param \WP_User|null $wp_user The user. Defaults to current user.
	 *
	 * @return array The user's wholesale role.
	 */
	public function get_user_role( $wp_user = null ): array;

	/**
	 * Retrieve the wholesale base price for a product.
	 *
	 * @param int           $product_id The product ID.
	 * @param \WP_User|null $wp_user    The user. Defaults to current user.
	 *
	 * @return float|null The wholesale base price, or null.
	 */
	public function retrieve_base_price( int $product_id, $wp_user = null ): ?float;

	/**
	 * Get the scheduled discount percentage for a product.
	 *
	 * @param int    $product_id          The product ID.
	 * @param string $user_wholesale_role The user's wholesale role.
	 *
	 * @return float The discount as a decimal (e.g., 0.10 for 10%).
	 */
	public function get_scheduled_discount_percentage( int $product_id, $user_wholesale_role ): float;
}
