<?php

namespace Modules\Core\Order\Services;

use Lunar\Models\Order;
use Lunar\Models\Transaction;
use Modules\Core\Payment\DTOs\PaymentResult;
use Modules\Core\Payment\Enums\PaymentResultStatus;

/**
 * Writes the Transaction row a Payment operation's PaymentResult becomes —
 * the one place that translates Payment's gateway-agnostic result into
 * Lunar's own transactions table, in the same shape lunarphp/stripe's own
 * StoreCharges already writes (type, success, amount, reference, driver).
 * Lives in Order, not Payment — Transaction.order_id is required, and
 * Payment never writes to another module's models (see docs/payments.md);
 * this is the "read the event, do the write" half of that boundary, same
 * shape as Modules\Core\Order\Listeners\ApplyResolvedPaymentStatus.
 *
 * Kept as its own class (not inlined into the listener that calls it) so a
 * future admin action (a manually-triggered capture/refund from Filament)
 * can write a row the same way, without going through an event at all.
 */
class TransactionRecorder
{
    /**
     * $type is Lunar's own transaction type string — 'intent' (an
     * authorize()-produced hold), 'capture' (settled funds, whether via
     * pay() directly or capture() settling a prior intent), 'refund',
     * 'void' is NOT one of Lunar's three built-in types (Order::
     * paymentStatus() only ever reads 'intent'/'capture'/'refund' — see
     * Modules\Core\Order\Support\OrderStatus::payment()) — a void never
     * moved money, so it's still recorded for audit but $success reflects
     * whether the RELEASE succeeded, not a captured amount.
     *
     * $driver is the payment type key (e.g. 'stripe', 'cash-on-delivery'),
     * not a class name — matches the $type PaymentCaptured/etc. events
     * themselves carry, and what Transaction.driver already means
     * elsewhere in this codebase (see the old, now-removed
     * TransactionRecorder this replaces).
     */
    public function record(Order $order, string $type, string $driver, PaymentResult $result): Transaction
    {
        return $order->transactions()->create([
            'success' => $result->status === PaymentResultStatus::Succeeded,
            'type' => $type,
            'driver' => $driver,
            'amount' => $result->amount->value,
            'reference' => $result->reference,
            'status' => $result->status->name,
            'notes' => $result->failureReason,
            'card_type' => $result->meta['card_type'] ?? null,
            'last_four' => $result->meta['last_four'] ?? null,
            'meta' => $result->meta,
        ]);
    }
}