<?php
/**
 * Payment interface.
 */

declare(strict_types=1);
namespace FeData\FastEvents\Payment;

defined( 'ABSPATH' ) || exit;

use FeData\FastEvents\Helpers\EventsHelper;
use stdClass;
use WP_Error;
use WP_REST_Request;
use WP_User;

interface PaymentInterface {

	/**
	 * Installation activities of the payment provider. It can be called multiple times!
	 *
	 * @since 3.0.0
	 *
	 * @return bool|WP_Error Returns true if the installation was successful.
	 */
	public function install(): bool|WP_Error;

	/**
	 * Uninstallation activities of the payment provider.
	 *
	 * @since 3.0.0
	 */
	public function uninstall(): void;

	/**
	 * Retrieve the payment provider name.
	 *
	 * @since 3.0.0
	 *
	 * @return string The name of the payment provider.
	 */
	public function get_provider_name(): string;

	/**
	 * Create a payment.
	 *
	 * @since 3.0.0
	 *
	 * @param EventsHelper $events_helper The events helper.
	 *                                    It contains all the methods to set up a payment.
	 * @param bool         $test          Use test mode or not (default: false).
	 * @return array|WP_Error     Returns an array with the payment details ('id' and 'url').
	 */
	public function create_payment( EventsHelper $events_helper, bool $test = false ): array|WP_Error;

	/**
	 * Retrieve the unique order uid and id from the webhook request parameters.
	 *
	 * @since 3.0.0
	 *
	 * @param WP_REST_Request $data   The WP_REST_Request request.
	 * @return array|WP_Error Returns an array with the payment details ('id' and 'uid').
	 */
	public function get_uid( WP_REST_Request $data ): array|WP_Error;

	/**
	 * Retrieve a single payment object by its payment ID.
	 *
	 * @since 3.0.0
	 *
	 * @param string   $payment_id The unique ID of the payment.
	 * @param int      $user_id    The ID of the user.
	 * @param stdClass $order      The order object.
	 * @param bool     $test       Use test mode or not (default: false).
	 * @return array|WP_Error    Returns an array with the payment details.
	 */
	public function get_payment( string $payment_id, int $user_id, stdClass $order, bool $test = false ): array|WP_Error;

	/**
	 * Capture the payment.
	 *
	 * @since 3.0.0
	 *
	 * @param string   $payment_id The unique ID of the payment.
	 * @param int      $user_id    The ID of the user.
	 * @param stdClass $order      The order object.
	 * @param bool     $test       Use test mode or not (default: false).
	 * @return array|WP_Error      Returns an array with the payment details.
	 */
	public function capture_payment( string $payment_id, int $user_id, stdClass $order, bool $test = false ): array|WP_Error;

	/**
	 * Cancel the payment.
	 *
	 * @since 3.0.0
	 *
	 * @param string $payment_id The unique ID of the payment.
	 * @param int    $user_id    The ID of the user.
	 * @param bool   $test       Use test mode or not (default: false).
	 * @return array|WP_Error    Returns an array with the payment details.
	 */
	public function cancel_payment( string $payment_id, int $user_id, bool $test = false ): array|WP_Error;


	/**
	 * Refund a payment.
	 *
	 * @since 3.0.0
	 *
	 * @param stdClass $order       The order object.
	 * @param string   $description The description of the payment.
	 * @param float    $amount      The amount of the payment.
	 * @param array    $metadata    Any metadata you want to store with the payment.
	 * @param int      $user_id     The ID of the user.
	 * @param bool     $test        Use test mode or not (default: false).
	 * @return array|WP_Error       Returns an array with the payment details ('id' and 'url').
	 */
	public function refund( stdClass $order, string $description, float $amount, array $metadata, int $user_id, bool $test = false ): array|WP_Error;

	/**
	 * Generate the authorization URL (OAuth url) for the payment provider.
	 *
	 * @since 3.0.0
	 *
	 * @param WP_User $user The user object.
	 * @return string The authorization URL.
	 */
	public function get_oauth_url( WP_User $user ): string;

	/**
	 * Get an access token from auth code.
	 *
	 * @since 3.0.0
	 *
	 * @param int    $user_id The ID of the user.
	 * @param string $state The state (nonce) parameter from the webhook request.
	 * @param array  $params  The parameters in the webhook request.
	 * @return WP_Error|string The authorization URL.
	 */
	public function get_access_token_from_auth_token( int $user_id, string $state, array $params ): WP_Error|string;

	/**
	 * Get an access token to access the endpoints on behalf of the sub-merchant.
	 *
	 * @since 3.0.0
	 *
	 * @param int $user_id The ID of the user.
	 * @return string The access token.
	 */
	public function get_access_token( int $user_id ): string;

	/**
	 * Revoke SaaS authorization.
	 *
	 * @since 3.0.0
	 *
	 * @param int $user_id The ID of the user.
	 * @return WP_Error|string The authorization URL.
	 */
	public function revoke_authorization( int $user_id ): WP_Error|string;
}
