<?php

namespace Modules\Core\Payment\Contracts;

use Lunar\Exceptions\FingerprintMismatchException;
use Lunar\Exceptions\Carts\CartException;
use Lunar\Models\Cart;

/**
 * A boboko-owned payment driver — wraps a payment gateway's own confirmation
 * mechanics (Stripe's synchronous authorize() call, a redirect-based
 * provider's async callback/webhook, anything else) behind one uniform
 * moment: "payment is confirmed."
 *
 * confirm() is the only thing a driver is required to do: once it has,
 * by whatever mechanism is native to that gateway, independently decided
 * the payment succeeded, it dispatches Modules\Core\Checkout\Events\
 * PaymentConfirmed — no driver ever calls CheckoutService::placeOrder() or
 * Lunar\Models\Cart::createOrder() directly. CheckoutService itself listens
 * for PaymentConfirmed and places the order from there; a driver that needs
 * to do something to the placed Order afterward (status mapping, syncing
 * gateway state) listens for the resulting OrderPlaced itself, matching it
 * via $order->meta['payment_method'] — see PaymentConfirmed's docblock for
 * why. This split is what makes an async/webhook-driven gateway (payment
 * confirmed in a request that has no synchronous caller waiting for an
 * Order at all) and a synchronous one (Stripe) work through the exact same
 * contract. See docs/checkout.md / docs/payments.md.
 */
interface PaymentDriver
{
    /**
     * Whether this driver can actually be used right now — e.g. Stripe
     * checking its own API key is present, an offline-style driver always
     * returning true since it has no external dependency. Independent of
     * Modules\Core\Payment\Models\PaymentMethod::enabled (the admin
     * on/off toggle) — CheckoutService::getPaymentMethods() combines both:
     * a type is only offered to the storefront if it's administratively
     * enabled AND its driver reports itself configured.
     */
    public function isConfigured(): bool;

    /**
     * $type is the payment type key being confirmed (e.g. 'cash-in-hand',
     * 'cash-on-delivery', 'stripe') — passed through even though most
     * drivers only ever serve one type, because a driver shared across
     * several types (e.g. one "no real confirmation" offline driver behind
     * both cash-in-hand and cash-on-delivery) needs it to look up that
     * type's own config (e.g. its 'authorized' status) rather than another
     * type's.
     *
     * $data carries whatever the gateway needs to confirm this specific
     * payment (Stripe: ['payment_intent' => $id], a redirect-based
     * provider: its callback payload) — passed explicitly by the caller
     * (a controller, a webhook job) rather than a driver reaching into the
     * global request(), so confirm() works the same whether it's called
     * from a synchronous HTTP request or an async webhook/job with no
     * active request at all.
     *
     * @param  array<string, mixed>  $data
     *
     * @throws FingerprintMismatchException
     * @throws CartException
     */
    public function confirm(Cart $cart, string $type, string $fingerprint, array $data): void;
}