<?php

/**
 * Copyright 2024-2025 Simply.IN Sp. z o.o.
 *
 * NOTICE OF LICENSE
 *
 * Licensed under the EUPL-1.2 or later.
 * You may not use this work except in compliance with the Licence.
 *
 * Copy of the Licence is available at:
 * https://joinup.ec.europa.eu/software/page/eupl
 * It is bundled with this package in the file LICENSE.txt
 *
 * Unless required by applicable law or agreed to in writing,
 * software distributed under the Licence is distributed on an as is basis,
 * without warranties or conditions of any kind, either express or implied.
 * Check the Licence for the specific language governing permissions
 * and limitations under the License.
 *
 * @author   Simply.IN Sp. z o.o.
 * @copyright 2024-2025 Simply.IN Sp. z o.o.
 * @license   https://joinup.ec.europa.eu/software/page/eupl
 */

declare(strict_types=1);

namespace SimplyIn\Payment;

use Cart;
use Order;

if (!defined('_PS_VERSION_')) {
    exit;
}

interface PaymentRecorderInterface
{
    public function newPaymentId(Order $order): string;

    /**
     * Open an attempt with a not-yet-known outcome, BEFORE the payment is requested.
     *
     * The ordering is the point, not an implementation detail. From the instant the request leaves,
     * a payment may exist - so the record of it has to exist first. Recording afterwards leaves a
     * window in which a payment is live and nothing knows: every guard that decides whether the
     * order may be paid again reads these rows, so an unrecorded payment is an invisible one, and
     * the next decision is taken as though it never happened.
     *
     * The outcome is written by {@see settle()} once it is known.
     */
    public function record(
        Cart $cart,
        string $type,
        string $status,
        string $paymentId,
        string $paymentProvider,
        string $cardProvider,
        string $providerImage,
        string $image,
    ): void;

    /**
     * Record the outcome of an attempt already opened by {@see record()}.
     *
     * @param string $rejectReason an already-sanitized {@see PaymentProviderErrorReason} member, or
     *                             '' when none was reported (or none survived sanitization) - never
     *                             stored in that case
     *
     * @return bool whether the outcome was actually stored against that attempt; false means the
     *              attempt could not be found, and the caller must not assume the write happened
     */
    public function settle(string $paymentId, string $status, string $rejectReason = ''): bool;
}
