<?php
/**
 * File Path: includes/payment/interface-mbs-payment-processor.php
 *
 * MBS_Payment_Processor Interface
 *
 * Defines the contract that every payment processor adapter must implement.
 * Each adapter (Stripe, PayPal, future processors) registers its own REST
 * webhook endpoint, verifies the incoming event signature using its own
 * processor-specific method, and delegates license provisioning through
 * the shared provision() method.
 *
 * Usage (from MBS_Plugin or a registration hook):
 *   add_action( 'rest_api_init', array( 'MBS_Stripe_Adapter', 'register_webhook' ) );
 *   add_action( 'rest_api_init', array( 'MBS_PayPal_Adapter', 'register_webhook' ) );
 *
 * Data contract for provision():
 *   $data must contain:
 *     'email'     string  Customer email — used to deliver the license key.
 *     'tier'      string  'pro' or 'pub' — determines license type.
 *     'tx_id'     string  Processor transaction ID — for idempotency + audit.
 *     'amount'    float   Payment amount in the transaction currency.
 *     'currency'  string  ISO 4217 currency code (e.g. 'USD').
 *     'processor' string  'stripe' or 'paypal' — logged on the server.
 *
 * Security contract:
 *   - verify_signature() MUST return false on any doubt — never fail open.
 *   - provision() MUST be called only after verify_signature() returns true.
 *   - Webhook secrets MUST be read from encrypted wp_options (GP-SEC-1).
 *     Never hardcode or log secrets.
 *   - Amazon PA-API credentials are NEVER involved in payment flows (arch rule).
 *
 * @package MyBookShowroom
 * @since   1.0.0
 */

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

interface MBS_Payment_Processor {

	/**
	 * Register the REST API webhook endpoint for this processor.
	 *
	 * Called on rest_api_init. Each adapter registers its own route under
	 * the mbs/v1 namespace:
	 *   POST /wp-json/mbs/v1/webhook/{processor-slug}
	 *
	 * The permission_callback must be __return_true — signature verification
	 * is handled inside the callback, not at the REST permission layer.
	 */
	public static function register_webhook(): void;

	/**
	 * Verify the incoming webhook event signature.
	 *
	 * Each processor uses a different verification mechanism:
	 *   Stripe  — HMAC-SHA256 of timestamp.payload using the endpoint secret.
	 *   PayPal  — POST-back IPN verification to PayPal's verification endpoint.
	 *
	 * @return bool True if the event is authentic; false otherwise.
	 */
	public static function verify_signature( WP_REST_Request $request ): bool;

	/**
	 * Extract normalized payment data from a verified event.
	 *
	 * Returns an array with the keys defined in the data contract above,
	 * or null if the event type is not a completed payment (e.g. refunds,
	 * disputes, test events) and should be silently ignored.
	 *
	 * @return array{
	 *   email: string,
	 *   tier: string,
	 *   tx_id: string,
	 *   amount: float,
	 *   currency: string,
	 *   processor: string
	 * }|null Normalized data or null to skip processing.
	 */
	public static function extract_payment_data( WP_REST_Request $request ): ?array;

	/**
	 * Provision a license after a confirmed payment.
	 *
	 * Sends the normalized payment data to the API server's
	 * POST /license/provision endpoint, which creates the paid license row,
	 * logs the transaction, and emails the license key to the customer.
	 *
	 * This method is the same for all processors — it is defined on the
	 * interface so each adapter can call it, but the implementation lives
	 * in the abstract helper MBS_Payment_Processor_Base (Sprint 9+) or
	 * can be duplicated across adapters for Sprint 8 simplicity.
	 *
	 * @param array $data Normalized payment data from extract_payment_data().
	 * @return bool True if provisioning succeeded; false on failure.
	 */
	public static function provision( array $data ): bool;
}
