<?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;

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

/**
 * The closed vocabulary SIN.CORE normalizes a provider's decline into, mirrored here as a plain
 * allowlist - this plugin has no generated client of its own to import it from.
 *
 * An external payload (the payment-creation response, the webhook) offers this value as a plain
 * string with no guarantee it is one this plugin recognizes: a future member neither side has
 * shipped yet, a transport hiccup, a field that simply is not there. {@see sanitize()} is the one
 * gate every such value passes through before it is ever persisted - discarding what it does not
 * recognize rather than guessing at it or failing the payment path over a spelling this plugin
 * does not control.
 */
final class PaymentProviderErrorReason
{
    /**
     * @var list<string>
     */
    private const VALUES = [
        'INVALID_CONFIGURATION',
        'TRANSACTION_TIMEOUT',
        'AMOUNT_LIMIT_EXCEEDED',
        'INVALID_AMOUNT',
        'BLIK_INVALID_CODE',
        'CARD_THREE_DS_FAILED',
        'DCB_UNSUPPORTED_OPERATOR',
        'DCB_DISABLED_PREMIUM_SERVICES',
        'DCB_UNSUPPORTED_BILLING_MODEL',
        'DCB_INVALID_PHONE_NUMBER',
        'DCB_INVALID_PIN',
        'UNSUPPORTED',
        'PROVIDER_INTERNAL_ERROR',
        'UNKNOWN',
    ];

    /**
     * @param mixed $value whatever an external payload offered under this field - never assumed to
     *                      already be a string
     *
     * @return string the value itself when it is a known member; '' otherwise - absent, null,
     *                 empty, non-string and unrecognized all degrade the same way, to nothing
     *                 stored
     */
    public static function sanitize($value): string
    {
        if (!is_string($value) || $value === '') {
            return '';
        }

        return in_array($value, self::VALUES, true) ? $value : '';
    }
}
