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

/**
 * OauthInterface provides methods consistent with implementing a 2-legged OAuth authentication mechanism. Methods
 * include creating a request token, getting an access token, and performing certain validations on tokens and
 * token requests. A method is also included for generating an OAuth header that can be used in an HTTP request.
 *
 * @api
 * @since 100.0.2
 */
interface OauthInterface
{
    /**#@+
     * OAuth result statuses
     */
    const ERR_OK = 0;

    const ERR_VERSION_REJECTED = 1;

    const ERR_PARAMETER_ABSENT = 2;

    const ERR_PARAMETER_REJECTED = 3;

    const ERR_TIMESTAMP_REFUSED = 4;

    const ERR_NONCE_USED = 5;

    const ERR_SIGNATURE_METHOD_REJECTED = 6;

    const ERR_SIGNATURE_INVALID = 7;

    const ERR_CONSUMER_KEY_REJECTED = 8;

    const ERR_TOKEN_USED = 9;

    const ERR_TOKEN_EXPIRED = 10;

    const ERR_TOKEN_REVOKED = 11;

    const ERR_TOKEN_REJECTED = 12;

    const ERR_VERIFIER_INVALID = 13;

    const ERR_PERMISSION_UNKNOWN = 14;

    const ERR_PERMISSION_DENIED = 15;

    const ERR_METHOD_NOT_ALLOWED = 16;

    const ERR_CONSUMER_KEY_INVALID = 17;

    /**#@-*/

    /**#@+
     * Signature Methods
     */
    const SIGNATURE_SHA1 = 'HMAC-SHA1';

    const SIGNATURE_SHA256 = 'HMAC-SHA256';

    /**#@-*/

    /**
     * Issue a pre-authorization request token to the caller.
     *
     * @param array $params - Array containing parameters necessary for requesting Request Token.
     * <pre>
     * array (
     *         'oauth_version' => '1.0',
     *         'oauth_signature_method' => 'HMAC-SHA1',
     *         'oauth_nonce' => 'rI7PSWxTZRHWU3R',
     *         'oauth_timestamp' => '1377183099',
     *         'oauth_consumer_key' => 'a6aa81cc3e65e2960a4879392445e718',
     *         'oauth_signature' => 'VNg4mhFlXk7%2FvsxMqqUd5DWIj9s%3D'
     * )
     * </pre>
     * @param string $requestUrl - The request Url.
     * @param string $httpMethod - (default: 'POST')
     * @return array - The request token/secret pair.
     * <pre>
     * array (
     *         'oauth_token' => 'gshsjkndtyhwjhdbutfgbsnhtrequikf',
     *         'oauth_token_secret' => 'gshsjkndtyhwjhdbutfgbsnhtrequikf'
     * )
     * </pre>
     * @throws \Magento\Framework\Oauth\Exception - Validation errors.
     */
    public function getRequestToken($params, $requestUrl, $httpMethod = 'POST');

    /**
     * Get access token for a pre-authorized request token.
     *
     * @param array $params - Array containing parameters necessary for requesting Access Token.
     * <pre>
     * array (
     *         'oauth_version' => '1.0',
     *         'oauth_signature_method' => 'HMAC-SHA1',
     *         'oauth_token' => 'a6aa81cc3e65e2960a487939244sssss',
     *         'oauth_nonce' => 'rI7PSWxTZRHWU3R',
     *         'oauth_timestamp' => '1377183099',
     *         'oauth_consumer_key' => 'a6aa81cc3e65e2960a4879392445e718',
     *         'oauth_signature' => 'VNg4mhFlXk7%2FvsxMqqUd5DWIj9s%3D',
     *         'oauth_verifier' => 'a6aa81cc3e65e2960a487939244vvvvv'
     * )
     * </pre>
     * @param string $requestUrl - The request Url.
     * @param string $httpMethod - (default: 'POST')
     * @return array - The access token/secret pair.
     * <pre>
     * array (
     *         'oauth_token' => 'gshsjkndtyhwjhdbutfgbsnhtrequikf',
     *         'oauth_token_secret' => 'gshsjkndtyhwjhdbutfgbsnhtrequikf'
     * )
     * </pre>
     * @throws \Magento\Framework\Oauth\Exception
     */
    public function getAccessToken($params, $requestUrl, $httpMethod = 'POST');

    /**
     * Validate an access token request.
     *
     * @param array $params - Array containing parameters necessary for validating Access Token.
     * <pre>
     * array (
     *         'oauth_version' => '1.0',
     *         'oauth_signature_method' => 'HMAC-SHA1',
     *         'oauth_token' => 'a6aa81cc3e65e2960a487939244sssss',
     *         'oauth_nonce' => 'rI7PSWxTZRHWU3R',
     *         'oauth_timestamp' => '1377183099',
     *         'oauth_consumer_key' => 'a6aa81cc3e65e2960a4879392445e718',
     *         'oauth_signature' => 'VNg4mhFlXk7%2FvsxMqqUd5DWIj9s%3D'
     * )
     * </pre>
     * @param string $requestUrl - The request Url.
     * @param string $httpMethod - (default: 'POST')
     * @return int Consumer ID.
     * @throws \Magento\Framework\Oauth\Exception - Validation errors.
     */
    public function validateAccessTokenRequest($params, $requestUrl, $httpMethod = 'POST');

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

    /**
     * Build the Oauth authorization header for an authenticated API request
     *
     * @param array $params - Array containing parameters to build the Oauth HTTP Authorization header
     * <pre>
     *  array (
     *      'oauth_consumer_key' => 'edf957ef88492f0a32eb7e1731e85d',
     *      'oauth_consumer_secret' => 'asdawwewefrtyh2f0a32eb7e1731e85d',
     *      'oauth_token' => '7c0709f789e1f38a17aa4b9a28e1b06c',
     *      'oauth_secret' => 'a6agsfrsfgsrjjjjyy487939244ssggg',
     *      'custom_param1' => 'foo',
     *      'custom_param2' => 'bar'
     *   );
     * </pre>
     * @param string $requestUrl e.g 'http://www.example.com/endpoint'
     * @param string $signatureMethod (default: 'HMAC-SHA1')
     * @param string $httpMethod (default: 'POST')
     * @return string
     * <pre>
     * OAuth oauth_version="1.0", oauth_signature_method="HMAC-SHA1", oauth_nonce="5X1aWR2qzf2uFm1",
     * oauth_timestamp="1381930661", oauth_consumer_key="34edf957ef88492f0a32eb7e1731e85d",
     * oauth_token="7c0709f789e1f38a17aa4b9a28e1b06c", oauth_signature="agVxK0epXOOeQK4%2Bc7UAqUXoAok%3D"
     * <pre>
     * @throws \Magento\Framework\Oauth\Exception
     */
    public function buildAuthorizationHeader(
        $params,
        $requestUrl,
        $signatureMethod = self::SIGNATURE_SHA1,
        $httpMethod = 'POST'
    );
}