<?php

namespace Modules\Core\Payment\Contracts;

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

/**
 * A driver's atomic charge — authorize and capture in one gateway call
 * (Mastercard's own "Pay" operation, Nexi's ActionType::PAY(), Stripe's
 * capture_method=automatic, or an offline driver with no gateway at all).
 * Distinct from SupportsAuthorization: a driver that only ever settles in
 * one step implements this and nothing else — there is no separate hold
 * to later capture() or void().
 *
 * Dispatches Modules\Core\Payment\Events\PaymentCaptured or
 * PaymentCaptureFailed based on the returned PaymentResult's status,
 * unless $result->status is Pending (an async gateway that hasn't
 * resolved yet — see HandlesPaymentCallback for how that gets resolved
 * later, from a separate call this method's return value does not wait
 * on).
 */
interface SupportsPay
{
    /**
     * $type is the payment type key being charged (e.g. 'cash-on-delivery',
     * 'stripe') — passed through even though most drivers only ever serve
     * one type, because a driver shared across several types needs it to
     * look up that type's own config.
     *
     * $amount is required, not optional data a caller might omit — there
     * is no way to process a payment without knowing what to charge.
     * Lunar's own Price (bundling its own currency) — the same money
     * representation every other Payment contract method takes/returns,
     * see PaymentResult's own docblock.
     *
     * $data carries whatever ELSE the gateway needs (customer details, a
     * payment method token) — the caller's responsibility to assemble,
     * since a driver has no notion of a cart or order to pull them from
     * itself.
     *
     * $context is opaque to the driver — carried through untouched into
     * whichever Payment event this call (or a later handleCallback()
     * resolving it) produces, so the caller can correlate the result back
     * to whatever it needs, without Payment ever needing to know what
     * that is.
     *
     * @param  array<string, mixed>  $data
     * @param  array<string, mixed>  $context
     */
    public function pay(string $type, Price $amount, array $data = [], array $context = []): PaymentResult;
}