<?php
/**
 * PSP Connector Interface
 *
 * Contract for payment service provider connectors.
 *
 * @package AmbassadorHub\Connectors
 */

namespace AmbassadorHub\Connectors;

/**
 * Interface for payment service provider (PSP) connectors.
 *
 * Unlike CRM and marketing connectors, PSPs have a synchronous phase: the donor's
 * browser must be redirected to the hosted checkout page immediately during the
 * form-submission request. This cannot go through the automations engine (which
 * runs deferred). PSPs therefore expose a direct initiate_payment() method that
 * the fundraiser calls explicitly on form submission.
 *
 * Two-phase execution model:
 *
 *   Phase 1 — synchronous (form submission request):
 *     fundraiser form submitted
 *       → donation row created with status 'pending'
 *         → ConnectorRegistry::get_active_psp()->initiate_payment( $donation_data )
 *           → ConnectorResult { redirect_url, transaction_id }
 *             → donor redirected to PSP hosted checkout
 *
 *   Phase 2 — async (PSP webhook callback):
 *     PSP posts webhook
 *       → PSP connector verifies signature, updates donation status
 *         → do_action( 'ambh_donation_status_changed', $donation_id, $new_status )
 *           → automations engine fires 'donation_status_changed' trigger
 *             → rules execute: CRM sync, email, etc.
 *
 * Only one PSP connector may be active at a time. The active connector is
 * selected on the Integrations settings tab and stored in wp_options. The
 * ConnectorRegistry enforces this single-active-PSP constraint.
 */
interface PspConnectorInterface extends ConnectorInterface {

	/**
	 * Initiate a payment with the PSP and return a result.
	 *
	 * Called synchronously during the donation form submission request.
	 * On success, ConnectorResult::$redirect_url contains the hosted
	 * checkout URL to send the donor to. On failure, ConnectorResult::$success
	 * is false and ConnectorResult::$error_message describes the problem.
	 *
	 * @param array<string, mixed> $donation_data {
	 *     Normalised donation data assembled by the fundraiser plugin.
	 *
	 *     @type int    $donation_id   ID of the freshly created donation row.
	 *     @type float  $amount        Donation amount in major currency units.
	 *     @type string $currency      ISO 4217 currency code (e.g. 'EUR').
	 *     @type string $description   Payment description shown in the PSP dashboard.
	 *     @type string $redirect_url  URL to return the donor to after checkout.
	 *     @type string $webhook_url   URL the PSP should POST status updates to.
	 *     @type array  $donor         Donor details: name, email, address, etc.
	 * }
	 * @return ConnectorResult
	 */
	public static function initiate_payment( array $donation_data ): ConnectorResult;
}
