<?php

namespace Modules\Core\Payment\Contracts;

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

/**
 * Settles a PRIOR SupportsAuthorization::authorize() hold — only ever
 * valid against a reference that call (or a HandlesPaymentCallback
 * resolving it) produced, never called standalone. A driver with no
 * authorize-then-settle model at all (most redirect/wallet gateways, any
 * offline driver) never implements this — it settles everything through
 * SupportsPay::pay() in one step instead.
 *
 * Dispatches Modules\Core\Payment\Events\PaymentCaptured or
 * PaymentCaptureFailed — the same terminal events SupportsPay::pay()
 * produces, since "money has been captured" is the same business fact
 * regardless of which path reached it.
 */
interface SupportsCaptures
{
    /**
     * $reference is the identifier SupportsAuthorization::authorize()
     * returned (PaymentResult::$reference) for the hold being settled.
     *
     * $amount is Lunar's own Price (never a gateway's own minor-unit
     * scale — see PaymentResult's docblock), and lets a driver capture
     * less than the full authorized amount (e.g. shipping less than
     * ordered) — up to the driver/gateway whether a partial capture also
     * releases the remainder or leaves it capturable again later
     * (multicapture-style gateways). Required explicitly, not derived by
     * the driver from a live gateway lookup — the caller (whatever placed
     * the original authorize() call) already knows it.
     *
     * @param  array<string, mixed>  $context
     */
    public function capture(string $reference, Price $amount, array $context = []): PaymentResult;
}