<?php
/**
 * Copyright © Magento, Inc. All rights reserved.
 * See COPYING.txt for license details.
 */
namespace Magento\Framework\Oauth;

/**
 * TokenProviderInterface provides token manipulation, such as creating a request token and getting an access token
 * as well as methods for performing certain validations on tokens and token requests. Consumer methods are also
 * provided to help clients manipulating tokens validate and acquire the associated token consumer.
 *
 * @api
 * @since 100.0.2
 */
interface TokenProviderInterface
{
    /**
     * Validate the consumer.
     *
     * @param ConsumerInterface $consumer The consumer.
     * @return bool True if the consumer is valid.
     * @throws \Magento\Framework\Oauth\Exception Validation errors.
     */
    public function validateConsumer($consumer);

    /**
     * Create a request token for the specified consumer.
     * Example:
     * <pre>
     *     array(
     *         'oauth_token' => 'gshsjkndtyhwjhdbutfgbsnhtrequikf,
     *         'oauth_token_secret' => 'gshsjkndtyhwjhdbutfgbsnhtrequikf'
     *     )
     * </pre>
     *
     * @param ConsumerInterface $consumer
     * @return array The request token and secret.
     * @throws \Magento\Framework\Oauth\Exception Validation errors.
     */
    public function createRequestToken($consumer);

    /**
     * Validates the request token and verifier. Verifies the request token is associated with the consumer.
     *
     * @param string $requestToken The 'oauth_token' request token value.
     * @param ConsumerInterface $consumer The consumer given the 'oauth_consumer_key'.
     * @param string $oauthVerifier The 'oauth_verifier' value.
     * @return string The request token secret (i.e. 'oauth_token_secret').
     * @throws \Magento\Framework\Oauth\Exception Validation errors.
     */
    public function validateRequestToken($requestToken, $consumer, $oauthVerifier);

    /**
     * Retrieve access token for the specified consumer given the consumer key.
     * Example:
     * <pre>
     *     array(
     *         'oauth_token' => 'gshsjkndtyhwjhdbutfgbsnhtrequikf,
     *         'oauth_token_secret' => 'gshsjkndtyhwjhdbutfgbsnhtrequikf'
     *     )
     * </pre>
     *
     * @param ConsumerInterface $consumer The consumer given the 'oauth_consumer_key'.
     * @return array The access token and secret.
     * @throws \Magento\Framework\Oauth\Exception Validation errors.
     */
    public function getAccessToken($consumer);

    /**
     * Validates the Oauth token type and verifies that it's associated with the consumer.
     *
     * @param string $accessToken The 'oauth_token' access token value.
     * @param ConsumerInterface $consumer The consumer given the 'oauth_consumer_key'.
     * @return string The access token secret.
     * @throws \Magento\Framework\Oauth\Exception Validation errors.
     */
    public function validateAccessTokenRequest($accessToken, $consumer);

    /**
     * Validate an access token string.
     *
     * @param string $accessToken The 'oauth_token' access token string.
     * @return int Consumer ID if the access token is valid.
     * @throws \Magento\Framework\Oauth\Exception Validation errors.
     */
    public function validateAccessToken($accessToken);

    /**
     * Perform basic validation of an Oauth token, of any type (e.g. request, access, etc.).
     *
     * @param string $oauthToken The token string.
     * @return bool True if the Oauth token passes basic validation.
     */
    public function validateOauthToken($oauthToken);

    /**
     * Retrieve a consumer given the consumer's key.
     *
     * @param string $consumerKey The 'oauth_consumer_key' value.
     * @return ConsumerInterface
     * @throws \Magento\Framework\Oauth\Exception
     */
    public function getConsumerByKey($consumerKey);
}