core/src/Checkout/Services/CheckoutService.php

<?php

namespace Modules\Core\Checkout\Services;

use Lunar\Exceptions\FingerprintMismatchException;
use Lunar\Exceptions\Carts\CartException;
use Illuminate\Support\Collection;
use Illuminate\Support\Facades\Event;
use Lunar\Base\Addressable;
use Lunar\DataTypes\ShippingOption;
use Lunar\Facades\ShippingManifest;
use Lunar\Models\Cart;
use Modules\Core\Cart\Services\CartService;
use Modules\Core\Checkout\Events\BillingAddressSet;
use Modules\Core\Checkout\Events\PaymentMethodSelected;
use Modules\Core\Checkout\Events\ShippingAddressSet;
use Modules\Core\Checkout\Events\ShippingOptionSelected;
use Modules\Core\Checkout\Exceptions\InvalidShippingOptionException;
use Modules\Core\Checkout\Exceptions\UnknownPaymentTypeException;
use Modules\Core\Payment\DTOs\PaymentResult;
use Modules\Core\Payment\Models\PaymentMethod;
use Modules\Core\Payment\Services\PaymentDriverResolver;

/**
 * Storefront-facing checkout operations, mirroring
 * Modules\Core\Cart\Services\CartService's shape — one boboko-owned API a
 * storefront calls, keeping Lunar's own Cart/ShippingManifest primitives an
 * implementation detail. See docs/checkout.md for the full design —
 * Checkout is the middle of a three-stage lifecycle (Cart → Checkout →
 * Order): it owns the placement moment itself (address, shipping selection,
 * ensuring a draft Order exists) and hands off to Payment the instant that
 * draft exists — see initiatePayment(). What happens to that Order
 * afterward (status transitions, fulfillment) is deliberately out of
 * scope here — see docs/payments.md and Checkout\Events\OrderPlaced's
 * docblock for where that now lives.
 *
 * Depends on CartService for cart access rather than reaching into
 * Lunar\Facades\CartSession directly a second time, so Checkout stays
 * layered on top of Cart's own service boundary instead of duplicating it.
 */
class CheckoutService
{
    public function __construct(
        private readonly CartService $cart,
        private readonly PaymentDriverResolver $paymentDrivers,
    ) {}

    public function setShippingAddress(array|Addressable $address): Cart
    {
        $cart = $this->cart->currentOrCreate()->setShippingAddress($address);

        Event::dispatch(new ShippingAddressSet($cart, $address));

        return $cart;
    }

    public function setBillingAddress(array|Addressable $address): Cart
    {
        $cart = $this->cart->currentOrCreate()->setBillingAddress($address);

        Event::dispatch(new BillingAddressSet($cart, $address));

        return $cart;
    }

    /**
     * Every shipping option currently available for the cart — already
     * fully backed by the merged Shipping-Carriers work: this runs every
     * registered Lunar\Shipping\Interfaces\ShippingRateInterface driver
     * (ACS/Box Now live-rate quoting alongside table-rate-shipping's own
     * flat-rate/free-shipping/collection drivers) through
     * ShippingManifest's pipeline. No rate-resolution logic lives here —
     * this is a thin pass-through.
     *
     * @return Collection<int, ShippingOption>
     */
    public function getShippingOptions(): Collection
    {
        return ShippingManifest::getOptions($this->cart->currentOrCreate());
    }

    /**
     * @throws InvalidShippingOptionException if $identifier doesn't resolve
     *   to a real, currently-available option for the cart
     */
    public function selectShippingOption(string $identifier): Cart
    {
        $cartBefore = $this->cart->currentOrCreate();
        $option = ShippingManifest::getOption($cartBefore, $identifier);

        if ($option === null) {
            throw new InvalidShippingOptionException($identifier);
        }

        $cart = $cartBefore->setShippingOption($option);

        Event::dispatch(new ShippingOptionSelected($cart, $option));

        return $cart;
    }

    /**
     * Every payment type currently offered to the storefront — every key
     * in config('lunar.payments.types') that is BOTH administratively
     * enabled (Modules\Core\Payment\Models\PaymentMethod::enabled) AND
     * whose registered driver reports itself usable right now
     * (Configurable::isConfigured() — e.g. Stripe with no API key set is
     * never offered, regardless of the enabled toggle). A type with no
     * PaymentMethod row at all (never seeded) is treated as not offered,
     * same as disabled — nothing here creates one; see
     * InstallLunarCommand::seedPaymentMethods().
     *
     * @return array<string>
     */
    public function getPaymentMethods(): array
    {
        return PaymentMethod::where('enabled', true)
            ->pluck('type')
            ->filter(fn (string $type) => $this->paymentDrivers->resolve($type)?->isConfigured() ?? false)
            ->values()
            ->all();
    }

    /**
     * Records which payment type the shopper picked (Cart::meta
     * ['payment_method']) — read by e.g. Modules\Core\Payment\Pipelines\
     * Cart\ApplyCashOnDeliveryFee to add that type's own cart-total
     * adjustments before recalculation.
     *
     * Also snapshots Cart::fingerprint() into meta, *after* saving the
     * chosen type — the fingerprint has to reflect the final total
     * including any payment-type-specific adjustment (e.g. a COD
     * surcharge), which only exists once payment_method is set and the
     * cart recalculates. Captured here, server-side, rather than asked of
     * the storefront: this is the last moment before initiatePayment() that
     * the shopper's reviewed total is known, and initiatePayment() reads it
     * back internally instead of taking a fingerprint parameter — a
     * storefront should never need to know Cart::fingerprint() exists.
     *
     * Does not itself call a payment driver — selecting a method and
     * initiating payment against it are deliberately separate steps, same
     * as selecting a shipping option happens before placing the order.
     *
     * @throws UnknownPaymentTypeException if $type isn't currently offered
     *   — see getPaymentMethods() for what that means (registered,
     *   administratively enabled, and its driver reports itself usable)
     */
    public function selectPaymentMethod(string $type): Cart
    {
        if (! in_array($type, $this->getPaymentMethods(), true)) {
            throw new UnknownPaymentTypeException($type);
        }

        $cart = $this->cart->currentOrCreate();
        $cart->meta = [...$cart->meta->toArray(), 'payment_method' => $type];
        $cart->save();

        $cart = $cart->calculate();
        $cart->meta = [...$cart->meta->toArray(), 'checkout_fingerprint' => $cart->fingerprint()];
        $cart->save();

        Event::dispatch(new PaymentMethodSelected($cart, $type));

        return $cart;
    }

    /**
     * The one storefront-facing "place this order and pay for it" call —
     * the point where Checkout hands off to Payment. Ensures a draft
     * Order exists (Cart::createOrder() — confirmed idempotent against a
     * cart's own pre-existing, not-yet-placed-at draft; see
     * vendor/lunarphp/core/src/Actions/Carts/CreateOrder.php), then
     * resolves the payment type selected by selectPaymentMethod() and
     * calls pay() or authorize() on its driver, per that type's
     * config('lunar.payments.types.{type}.capture_mode') — boboko-core's
     * own types (config/payment.php) are merged into that same Lunar
     * config key by PaymentServiceProvider::boot().
     *
     * Returns the driver's own PaymentResult UNCHANGED — this method does
     * not wait for or resolve anything past what pay()/authorize() itself
     * returns synchronously. A Pending result (an async gateway like
     * Stripe requiring 3-D Secure/a redirect) is a normal, expected
     * outcome, not an error — the caller (a storefront controller) is
     * responsible for whatever the gateway needs next.
     *
     * KNOWN GAP, explicitly out of scope for now: PaymentResult alone does
     * not carry gateway-specific continuation data (e.g. Stripe's
     * PaymentIntent client_secret for a Pending result needing frontend
     * confirmation) — that concept existed on the deleted PaymentInitiation
     * DTO and was intentionally removed from Payment's abstraction layer.
     * Nothing here re-introduces it; only OfflinePaymentDriver's
     * always-Immediate-Succeeded path is fully wired end-to-end today.
     *
     * The draft order's own $order->total (not the Cart's) is what gets
     * passed as $amount — Order::$total is Lunar's own Price-cast
     * attribute, already resolving the correct Currency via the order's
     * own currency_code, and is the authoritative total once the draft
     * row exists.
     *
     * $context passed to the driver is {cart_id, order_id} — the exact
     * keys Modules\Core\Payment\Drivers\StripePaymentDriver::
     * rememberIntent() already reads.
     *
     * Same fingerprint precondition the old placeOrder() had: mandatory,
     * not optional, checked before the draft is created.
     *
     * @param  array<string, mixed>  $data  passed through untouched to
     *   the driver's pay()/authorize() — e.g. Stripe's payment_method
     *   token.
     *
     * @throws UnknownPaymentTypeException if the cart's selected
     *   payment_method (from selectPaymentMethod()) is no longer offered
     *   — re-checked here, not just at selection time, since a type could
     *   be disabled in between
     * @throws FingerprintMismatchException
     * @throws CartException
     */
    public function initiatePayment(string $fingerprint, array $data = []): PaymentResult
    {
        $cart = $this->cart->currentOrCreate();
        $cart->checkFingerprint($fingerprint);

        $type = $cart->meta['payment_method'] ?? null;

        if ($type === null || ! in_array($type, $this->getPaymentMethods(), true)) {
            throw new UnknownPaymentTypeException((string) $type);
        }

        $order = $cart->createOrder();

        $driver = $this->paymentDrivers->resolve($type);
        $captureMode = config("lunar.payments.types.{$type}.capture_mode", 'pay');

        $context = ['cart_id' => $cart->id, 'order_id' => $order->id];

        return $captureMode === 'authorize'
            ? $driver->authorize($type, $order->total, $data, $context)
            : $driver->pay($type, $order->total, $data, $context);
    }
}