<?php
/**
 * Payment Gateway Interface.
 *
 * Every TitanCart payment gateway — built-in or third-party — must implement
 * this interface. It defines the three operations the payments system needs
 * from a gateway: process a charge, issue a refund, and describe its own
 * settings fields (so the admin UI can render a settings form dynamically).
 *
 * GATEWAY REGISTRATION
 * --------------------
 * Gateways register themselves on the `titancart_register_gateways` action:
 *
 *   add_action( 'titancart_register_gateways', function ( GatewayRegistry $registry ) {
 *       $registry->register( 'my_gateway', MyGateway::class );
 *   } );
 *
 * PROCESS PAYMENT RETURN VALUE
 * ----------------------------
 * `process_payment()` must return an array with these keys:
 *
 *   success         bool    — true if charge succeeded or is pending (e.g. redirect).
 *   transaction_id  string  — gateway-assigned ID for this charge ('pending' if async).
 *   message         string  — human-readable status message.
 *   payment_data    array   — extra data sent to the JS frontend. Required keys vary:
 *     Stripe:   [ 'client_secret' => '...', 'publishable_key' => '...' ]
 *     PayPal:   [ 'redirect_url'  => 'https://paypal.com/...' ]
 *     COD:      []
 *
 * @package TitanCart\Modules\Payments
 */

namespace TitanCart\Modules\Payments;

defined( 'ABSPATH' ) || exit;

interface PaymentGatewayInterface {

    /**
     * Attempt to process the payment for a given order.
     *
     * Called immediately after the order record is created.
     * Must NOT throw — return a failure result instead.
     *
     * @param  int   $order_id  Primary key from tc_orders.
     * @param  array $order     Full order row (totals, currency, billing address, etc.).
     * @param  array $settings  Gateway settings decrypted from payment_methods.settings.
     * @return array{
     *   success: bool,
     *   transaction_id: string,
     *   message: string,
     *   payment_data: array
     * }
     */
    public function process_payment( int $order_id, array $order, array $settings ): array;

    /**
     * Issue a (partial or full) refund for a previously charged transaction.
     *
     * @param  int    $order_id       Primary key from tc_orders.
     * @param  string $transaction_id The gateway transaction ID to refund.
     * @param  float  $amount         Amount to refund in the order's currency.
     * @param  array  $settings       Gateway settings.
     * @return array{
     *   success: bool,
     *   refund_id: string,
     *   message: string
     * }
     */
    public function refund( int $order_id, string $transaction_id, float $amount, array $settings ): array;

    /**
     * Return the list of admin settings fields for this gateway.
     *
     * Each field descriptor:
     *   [ 'key' => string, 'label' => string, 'type' => 'text'|'password'|'checkbox'|'select', 'default' => mixed ]
     *
     * The React admin UI reads this and renders the appropriate inputs.
     *
     * @return array<int, array<string, mixed>>
     */
    public function get_settings_fields(): array;

    /**
     * Return the human-readable display name of this gateway.
     * Used in admin lists and checkout dropdown.
     *
     * @return string
     */
    public function get_label(): string;
}
