<?php
/**
 * Integration with coupon interface for implementing coupon creation and management.
 *
 * @package Awesomemotive\Rewardswp\Interfaces
 * @since 1.0.0
 */

namespace Awesomemotive\Rewardswp\Interfaces;

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

use WP_Error;

interface IntegrationWithCouponInterface {
	/**
	 * Classes must implement a method to create the coupon.
	 *
	 * @since 1.0.0
	 *
	 * @param array $data The coupon data.
	 *
	 * @return int|WP_Error The coupon ID or WP_Error on failure.
	 */
	public function create_coupon( array $data );

	/**
	 * A method to automatically apply the coupon to the cart.
	 *
	 * @param string $coupon_code The coupon code to apply.
	 *
	 * @return true|WP_Error|null True in case of success, WP_Error in case the coupon doesn't exist or integration is not active,
	 *                            null if the discount was already applied.
	 */
	public function apply_coupon( string $coupon_code );

	/**
	 * A method to remove a coupon from the cart.
	 *
	 * If no coupon is supplied, should remove all coupons.
	 *
	 * @param string $coupon_code The coupon code to remove.
	 *
	 * @return bool Whether the coupon was removed or not.
	 */
	public function remove_coupon( string $coupon_code = '' ): bool;

	/**
	 * A method to check if a coupon has been applied to the cart.
	 *
	 * @param string $coupon_code The coupon code to check.
	 *
	 * @return bool Whether the coupon is applied or not.
	 */
	public function is_coupon_applied( string $coupon_code ): bool;

	/**
	 * A method to map the reward array to an array that it can be used to create the coupon.
	 *
	 * Since every integration has its own set of parameters to create coupons, this method
	 * shall be responsible to convert the original parameters provided by the reward to the final parameters.
	 *
	 * @since 1.0.0
	 *
	 * @param array $data The original parameters.
	 *
	 * @return array The data with the expected integration parameters.
	 */
	public function map_coupon_data( array $data ): array;

	/**
	 * A method to return products by ID.
	 *
	 * @since 1.0.0
	 *
	 * @param int $product_id The product ID.
	 *
	 * @return array An array with the `id` and `name` properties.
	 */
	public function get_product( int $product_id ): array;

	/**
	 * A method to return products by a search string.
	 *
	 * @since 1.0.0
	 *
	 * @param string $substring The search string.
	 *
	 * @return array An array with the `id` and `name` properties.
	 */
	public function search_products( string $substring ): array;

	/**
	 * A method to return the order total as a float number.
	 *
	 * @since 1.0.0
	 *
	 * @param int $order_id The order ID.
	 *
	 * @return float The order total as a float number.
	 */
	public function get_order_total( int $order_id ): float;

	/**
	 * A method to return the order total formatted with the currency used at the moment of the purchase.
	 *
	 * @since 1.0.0
	 *
	 * @param int $order_id The order ID.
	 *
	 * @return string The formatted order total.
	 */
	public function get_order_total_formatted( int $order_id ): string;

	/**
	 * Get the link to view the order in the admin panel.
	 *
	 * @param int $order_id The order ID.
	 * @return string The link to the order.
	 */
	public function get_order_link( int $order_id ): string;

	/**
	 * Get the URL to the store/shop page where customers can browse and purchase products.
	 *
	 * @since 1.1.0
	 *
	 * @return string The store/shop URL.
	 */
	public function get_store_url(): string;

	/**
	 * Check if a product is in stock and available for purchase.
	 *
	 * For WooCommerce: checks stock status and purchasability.
	 * For EDD: downloads are typically always available (digital products).
	 *
	 * @since 1.2.0
	 *
	 * @param int|string $product_id The product ID (int) or "download_id:price_id" string for EDD.
	 *
	 * @return bool True if the product is in stock and purchasable, false otherwise.
	 */
	public function is_product_in_stock( $product_id ): bool;
}
