<?php
/**
 * DemoPSP Connector
 *
 * A zero-configuration payment connector that immediately marks donations as
 * completed without involving any real payment gateway. Intended for
 * first-run testing via the setup wizard and as a reusable test mode from the
 * Payments settings tab.
 *
 * When active, the donation form skips the external checkout redirect and goes
 * straight to the post-payment confirmation page.
 *
 * @package AmbassadorHub\Connectors\Free
 */

declare( strict_types=1 );

namespace AmbassadorHub\Connectors\Free;

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

use AmbassadorHub\Connectors\AbstractPspConnector;
use AmbassadorHub\Connectors\ConnectorResult;
use AmbassadorHub\Donations\DonationsModule;

/**
 * DemoPSP connector.
 *
 * Registered under the 'psp' slot.  Has no settings UI and no webhook endpoint.
 * Switching to a real PSP from Settings overrides the active connector option.
 */
final class FreePspConnector extends AbstractPspConnector {

	// -------------------------------------------------------------------------
	// Identity
	// -------------------------------------------------------------------------

	public const ID   = 'free';
	public const TYPE = 'psp';
	public const LOGO = AMBASSADOR_HUB_URL . 'src/Connectors/Free/assets/ambh_logo.svg';

	public static function get_label(): string {
		return esc_html__( 'Test payments', 'ambassadorhub' );
	}

	public static function get_description(): string {
		return esc_html__( 'Instantly confirms donations without a real payment gateway. Use for testing only.', 'ambassadorhub' );
	}

	// -------------------------------------------------------------------------
	// Availability
	// -------------------------------------------------------------------------

	/**
	 * Always available — no credentials required.
	 */
	public static function is_available(): bool {
		return true;
	}

	// -------------------------------------------------------------------------
	// Payment initiation
	// -------------------------------------------------------------------------

	/**
	 * Immediately marks the donation as completed and redirects to the
	 * confirmation page — no external checkout involved.
	 *
	 * @param array $donation_data Payment data passed by the donation form.
	 * @return ConnectorResult
	 */
	public static function initiate_payment( array $donation_data ): ConnectorResult {
		$donation_id    = (int) ( $donation_data['donation_id'] ?? 0 );
		$transaction_id = 'free-' . $donation_id;

		DonationsModule::update(
			$donation_id,
			array(
				'status'         => 'completed',
				'transaction_id' => $transaction_id,
			)
		);

		return ConnectorResult::ok(
			transaction_id: $transaction_id,
			redirect_url:   $donation_data['redirect_url'] ?? null,
		);
	}

	// -------------------------------------------------------------------------
	// Registration — no settings UI, no webhook endpoint needed
	// -------------------------------------------------------------------------

	/**
	 * {@inheritdoc}
	 *
	 * No-op: the free connector has no settings fields.
	 */
	public static function register(): void {}

	/**
	 * {@inheritdoc}
	 *
	 * No-op: no webhook route to register.
	 */
	public static function on_registration(): void {}
}
