<?php
/**
 * Reward type interface for implementing reward types.
 *
 * @package Awesomemotive\Rewardswp\Interfaces
 * @since 1.0.0
 */

namespace Awesomemotive\Rewardswp\Interfaces;

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

use Awesomemotive\Rewardswp\Helpers\IconHelper;
use Awesomemotive\Rewardswp\Models\Referral;
use Awesomemotive\Rewardswp\Models\Reward;

/**
 * RewardType interface.
 *
 * @since 1.0.0
 */
interface RewardTypeInterface {
	/**
	 * Must return the unique reward name.
	 * It should use snake_case format.
	 *
	 * The class must use the same name but using CamelCase.
	 *
	 * @since 1.0.0
	 *
	 * @return string
	 */
	public function get_type(): string;

	/**
	 * Must return the name used in admin screens.
	 *
	 * @since 1.0.0
	 *
	 * @return string
	 */
	public function get_admin_title(): string;

	/**
	 * Must return the title used in the front-end panel.
	 *
	 * @since 1.0.0
	 *
	 * @return string
	 */
	public function get_panel_title(): string;

	/**
	 * Must return the subtitle used in the front-end panel.
	 *
	 * @since 1.0.0
	 *
	 * @return string
	 */
	public function get_panel_subtitle(): string;

	/**
	 * Must return the instructions to be used in the front-end panel.
	 *
	 * @since 1.0.0
	 *
	 * @return string
	 */
	public function get_panel_instructions(): string;

	/**
	 * Must return the icon name. Used in both admin and front-end.
	 *
	 * @see IconHelper For the list of icon names.
	 *
	 * @since 1.0.0
	 *
	 * @return string
	 */
	public function get_icon_name(): string;

	/**
	 * A method to return the reward formatted amount.
	 *
	 * To use a custom currency symbol, call set_currency_symbol() before this method.
	 *
	 * @since 1.0.0
	 *
	 * @param float  $amount The reward amount.
	 * @param string $format Optional. Output format. Default 'default'.
	 *
	 * @return string
	 */
	public function get_reward_formatted_amount( float $amount = 0, string $format = 'default' ): string;

	/**
	 * Must return an array with the integration supported by this reward type.
	 *
	 * @see IntegrationInterface implementations to find the integration names available.
	 *
	 * @since 1.0.0
	 *
	 * @return array
	 */
	public function available_for(): array;

	/**
	 * Must implement a way to return the default values.
	 *
	 * @since 1.0.0
	 *
	 * @return array
	 */
	public function get_defaults(): array;

	/**
	 * Must implement a way to return the title for the advocate admin component.
	 *
	 * @since 1.0.0
	 *
	 * @return string
	 */
	public function get_admin_advocate_title(): string;

	/**
	 * Must implement a way to return the title for the friend admin component.
	 *
	 * @since 1.0.0
	 *
	 * @return string
	 */
	public function get_admin_friend_title(): string;

	/**
	 * Must implement a way to a claim_reward.
	 *
	 * Rewards can be only claimed by a friend.
	 *
	 * @since 1.0.0
	 *
	 * @param array $args Arguments for claiming the reward.
	 *
	 * @return Reward|null
	 */
	public function claim_reward( array $args = [] ): ?Reward;

	/**
	 * Must implement a way to issue a reward.
	 *
	 * This can be called in different situations, like after a referral is created during a purchase or
	 * during the friend's redeem process.
	 *
	 * @since 1.0.0
	 *
	 * @param Referral $referral       The referral object.
	 * @param string   $recipient_type Can be either advocate or friend.
	 * @param array    $args           Additional arguments.
	 *
	 * @return Reward|null
	 */
	public function issue_reward( Referral $referral, string $recipient_type, array $args = [] ): ?Reward;

	/**
	 * Must implement a way to process friend and advocate rewards.
	 *
	 * @since 1.0.0
	 *
	 * @param Reward $reward The reward object.
	 * @param array  $args   Additional arguments.
	 *
	 * @return bool|null
	 */
	public function redeem_reward( Reward $reward, array $args = [] ): ?bool;

	/**
	 * Must implement a way to return the rewards HTML to render into the panel.
	 *
	 * The method should get the advocate rewards and return the array with the HTML to be output in the advocate's panel.
	 *
	 * @param Reward[] $rewards Array of reward objects.
	 * @param array    $args    Additional arguments.
	 *
	 * @return array
	 */
	public function prepare_rewards_objects_for_view( array $rewards, array $args = [] ): array;

	/**
	 * Must return the content when no rewards are available.
	 *
	 * @since 1.0.0
	 *
	 * @return string
	 */
	public function get_empty_rewards_content(): string;

	/**
	 * Must return the content to display the claiming panel.
	 *
	 * @since 1.0.0
	 *
	 * @param array $args Additional arguments.
	 *
	 * @return string
	 */
	public function get_claim_panel_content( array $args = [] ): string;
}
