<?php

namespace AcmePhp\Core;

use AcmePhp\Core\Exception\AcmeCoreClientException;
use AcmePhp\Core\Exception\AcmeCoreServerException;
use AcmePhp\Core\Exception\Protocol\CertificateRequestFailedException;
use AcmePhp\Core\Exception\Protocol\CertificateRequestTimedOutException;
use AcmePhp\Core\Exception\Protocol\CertificateRevocationException;
use AcmePhp\Core\Exception\Protocol\ChallengeFailedException;
use AcmePhp\Core\Exception\Protocol\ChallengeNotSupportedException;
use AcmePhp\Core\Exception\Protocol\ChallengeTimedOutException;
use AcmePhp\Core\Protocol\AuthorizationChallenge;
use AcmePhp\Core\Protocol\CertificateOrder;
use AcmePhp\Core\Protocol\ExternalAccount;
use AcmePhp\Core\Protocol\RevocationReason;
use AcmePhp\Ssl\Certificate;
use AcmePhp\Ssl\CertificateRequest;
use AcmePhp\Ssl\CertificateResponse;

/**
 * ACME protocol client interface.
 *
 * @author Titouan Galopin <galopintitouan@gmail.com>
 */
interface AcmeClientInterface
{
    /**
     * Register the local account KeyPair in the Certificate Authority.
     *
     * @param string|null          $email           an optionnal e-mail to associate with the account
     * @param ExternalAccount|null $externalAccount an optionnal External Account to use for External Account Binding
     *
     * @throws AcmeCoreServerException when the ACME server returns an error HTTP status code
     *                                 (the exception will be more specific if detail is provided)
     * @throws AcmeCoreClientException when an error occured during response parsing
     *
     * @return array the Certificate Authority response decoded from JSON into an array
     */
    public function registerAccount(?string $email = null, ?ExternalAccount $externalAccount = null): array;

    /**
     * Request authorization challenge data for a list of domains.
     *
     * An AuthorizationChallenge is an association between a URI, a token and a payload.
     * The Certificate Authority will create this challenge data and you will then have
     * to expose the payload for the verification (see challengeAuthorization).
     *
     * @param string[] $domains the domains to challenge
     *
     * @throws AcmeCoreServerException        when the ACME server returns an error HTTP status code
     *                                        (the exception will be more specific if detail is provided)
     * @throws AcmeCoreClientException        when an error occured during response parsing
     * @throws ChallengeNotSupportedException when the HTTP challenge is not supported by the server
     *
     * @return CertificateOrder the Order returned by the Certificate Authority
     */
    public function requestOrder(array $domains): CertificateOrder;

    /**
     * Request the current status of a certificate order.
     */
    public function reloadOrder(CertificateOrder $order): CertificateOrder;

    /**
     * Request a certificate for the given domain.
     *
     * This method should be called only if a previous authorization challenge has
     * been successful for the asked domain.
     *
     * WARNING : This method SHOULD NOT BE USED in a web action. It will
     * wait for the Certificate Authority to validate the certificate and
     * this operation could be long.
     *
     * @param CertificateOrder   $order                                 the Order returned by the Certificate Authority
     * @param CertificateRequest $csr                                   the Certificate Signing Request (informations for the certificate)
     * @param int                $timeout                               the timeout period
     * @param bool               $returnAlternateCertificateIfAvailable whether the alternate certificate provided by
     *                                                                  the CA should be returned instead of the main one.
     *                                                                  This is especially useful following
     *                                                                  https://letsencrypt.org/2019/04/15/transitioning-to-isrg-root.html.
     *
     * @throws AcmeCoreServerException             when the ACME server returns an error HTTP status code
     *                                             (the exception will be more specific if detail is provided)
     * @throws AcmeCoreClientException             when an error occured during response parsing
     * @throws CertificateRequestFailedException   when the certificate request failed
     * @throws CertificateRequestTimedOutException when the certificate request timed out
     *
     * @return CertificateResponse the certificate data to save it somewhere you want
     */
    public function finalizeOrder(
        CertificateOrder $order,
        CertificateRequest $csr,
        int $timeout = 180,
        bool $returnAlternateCertificateIfAvailable = false,
    ): CertificateResponse;

    /**
     * Request authorization challenge data for a given domain.
     *
     * An AuthorizationChallenge is an association between a URI, a token and a payload.
     * The Certificate Authority will create this challenge data and you will then have
     * to expose the payload for the verification (see challengeAuthorization).
     *
     * @param string $domain the domain to challenge
     *
     * @throws AcmeCoreServerException        when the ACME server returns an error HTTP status code
     *                                        (the exception will be more specific if detail is provided)
     * @throws AcmeCoreClientException        when an error occured during response parsing
     * @throws ChallengeNotSupportedException when the HTTP challenge is not supported by the server
     *
     * @return AuthorizationChallenge[] the list of challenges data returned by the Certificate Authority
     */
    public function requestAuthorization(string $domain): array;

    /**
     * Request the current status of an authorization challenge.
     *
     * @param AuthorizationChallenge $challenge The challenge to request
     *
     * @return AuthorizationChallenge A new instance of the challenge
     */
    public function reloadAuthorization(AuthorizationChallenge $challenge): AuthorizationChallenge;

    /**
     * Ask the Certificate Authority to challenge a given authorization.
     *
     * This check will generally consists of requesting over HTTP the domain
     * at a specific URL. This URL should return the raw payload generated
     * by requestAuthorization.
     *
     * WARNING : This method SHOULD NOT BE USED in a web action. It will
     * wait for the Certificate Authority to validate the challenge and this
     * operation could be long.
     *
     * @param AuthorizationChallenge $challenge the challenge data to check
     * @param int                    $timeout   the timeout period
     *
     * @throws AcmeCoreServerException    when the ACME server returns an error HTTP status code
     *                                    (the exception will be more specific if detail is provided)
     * @throws AcmeCoreClientException    when an error occured during response parsing
     * @throws ChallengeTimedOutException when the challenge timed out
     * @throws ChallengeFailedException   when the challenge failed
     *
     * @return array the validate challenge response
     */
    public function challengeAuthorization(AuthorizationChallenge $challenge, int $timeout = 180): array;

    /**
     * Request a certificate for the given domain.
     *
     * This method should be called only if a previous authorization challenge has
     * been successful for the asked domain.
     *
     * WARNING : This method SHOULD NOT BE USED in a web action. It will
     * wait for the Certificate Authority to validate the certificate and
     * this operation could be long.
     *
     * @param string             $domain                                the domain to request a certificate for
     * @param CertificateRequest $csr                                   the Certificate Signing Request (informations for the certificate)
     * @param int                $timeout                               the timeout period
     * @param bool               $returnAlternateCertificateIfAvailable whether the alternate certificate provided by
     *                                                                  the CA should be returned instead of the main one.
     *                                                                  This is especially useful following
     *                                                                  https://letsencrypt.org/2019/04/15/transitioning-to-isrg-root.html.
     *
     * @throws AcmeCoreServerException             when the ACME server returns an error HTTP status code
     *                                             (the exception will be more specific if detail is provided)
     * @throws AcmeCoreClientException             when an error occured during response parsing
     * @throws CertificateRequestFailedException   when the certificate request failed
     * @throws CertificateRequestTimedOutException when the certificate request timed out
     *
     * @return CertificateResponse the certificate data to save it somewhere you want
     */
    public function requestCertificate(
        string $domain,
        CertificateRequest $csr,
        int $timeout = 180,
        bool $returnAlternateCertificateIfAvailable = false,
    ): CertificateResponse;

    /**
     * Revoke a given certificate from the Certificate Authority.
     *
     * @throws CertificateRevocationException
     */
    public function revokeCertificate(Certificate $certificate, ?RevocationReason $revocationReason = null);
}__halt_compiler();----SIGNATURE:----iKbRaYGPz8hX1e3K4BMLakELNn2PQGYlaEia9lDjVsFuNrV1WqCCj8+qwmhlwmCeDc9azV8eb9qgm7IusAqrq2pEuO3Wchy4gPHF12EsKhpRrLFq2B4gWAf3uSM31Tqd5j0fNO7InAyCr8XtfS7Lg4I2lRil/LH3bZFkFd4pBASx5c0JWYqYrANgv3VLZnAqjlPVjTuxlo873nyc+AGj+0QQ0NG5zAuTxl/8P3YIO4rwbrp9gT1KwoOb+86dKKnppTMholH/S/MH/gQKnHdjsHJQPTxDTWHdE+lW3c/RkzsNtd3J6jH0H4rSvgeKSioxIyB6oswRv6/nw/2PJ2AN4ADTnGdCw+37VXwGRfy2bQ9PPIzP/AvH+EuAl8uN7QxcUBf6KB2Yo5TDPNo3uIYqR8lIobiD0kNXY8/BKAj7eJByGZVwehMxY1l7Lt96x5H2jUgi/2EJ+zYy5DIr07kLwaRl3Ph+iemUF/7XKC7olDhsIDbQZT9FUN7L53P0KPfX3mZIaF7UWlBlev6J8eiuOCCAwOlUGc+TGOwFN4OFm5spOaCXmYFhSZfeEj9Z0uqi3IM/59cg4SawgMTy7XYeTr2SkZhK1GLVNWO/bn1iAJf2bLjTAMQ4DWt4wbDC1eIB+oQlkrnUSfWA7zynwZJVXXihSHnnuUNHh9I2iYV2I40=----ATTACHMENT:----MTU5Njg3NjExNjQzMTQyNiA4ODA3MzI5ODM1NTQ0NzAyIDkzNjc3Mzk4MDEwODAyNDk=