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

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

/**
 * Outcome of a backend handshake (webhook-secret sync, RSA registration), classified so the admin
 * UI can tell an actually-wrong API key apart from a transient/technical problem instead of showing
 * one conflated "check your API key" message for both.
 */
enum ConnectionOutcome
{
    case SUCCESS;
    /**
     * Either the backend explicitly rejected the request as unauthenticated/unauthorized
     * (401/403-class), or there was no API key to even attempt a request with.
     */
    case AUTH_REJECTED;
    /**
     * RSA registration only: the API key is valid, but the backend already has an RSA public key
     * registered for it from a previous session — distinct from AUTH_REJECTED so the admin UI does
     * not tell the merchant their (valid) key is wrong.
     */
    case ALREADY_REGISTERED;
    /** Anything else: network error, timeout, 5xx, malformed response. */
    case TECHNICAL_FAILURE;

    /**
     * Classify an HTTP status code from a response the plugin could not otherwise treat as success
     * (non-2xx, or a 2xx with a malformed/empty/error-shaped body).
     */
    public static function fromStatusCode(?int $statusCode): self
    {
        return $statusCode === 401 || $statusCode === 403 ? self::AUTH_REJECTED : self::TECHNICAL_FAILURE;
    }
}
