<?php

namespace Modules\Core\Payment\Contracts;

use Lunar\DataTypes\Price;
use Modules\Core\Payment\DTOs\PaymentResult;

/**
 * A driver's hold-only operation (Mastercard's "Authorize", Nexi's
 * ActionType::PREAUTH(), Stripe's capture_method=manual) — places a hold
 * on the customer's payment method without moving any funds. Only a
 * driver that also implements SupportsCaptures/SupportsVoids can do
 * anything with the resulting hold afterward; implementing this alone
 * with neither of those would leave the hold to simply expire
 * (typically ~7 days, gateway-dependent) with no way to settle or release
 * it early.
 *
 * A driver capable of both authorize-then-settle AND an atomic charge
 * (most card gateways) implements this alongside SupportsPay — which one
 * gets called for a given payment attempt is the CALLER's choice (a
 * policy decision), not something this driver decides for itself.
 *
 * Dispatches Modules\Core\Payment\Events\PaymentAuthorized or
 * PaymentAuthorizationFailed based on the returned PaymentResult's status,
 * unless $result->status is Pending — see SupportsPay's docblock for the
 * same async-resolution note.
 */
interface SupportsAuthorization
{
    /**
     * Same $type/$amount/$data/$context reasoning as SupportsPay::pay().
     *
     * @param  array<string, mixed>  $data
     * @param  array<string, mixed>  $context
     */
    public function authorize(string $type, Price $amount, array $data = [], array $context = []): PaymentResult;
}