10.0.0 release

close #68
close #75

CHANGELOG.md

@@ -1,5 +1,15 @@
 # CHANGELOG
 
+## 10.0.0 - 2017-03-17
+
+### Breaking changes
+
+* Support Trading API version 997.
+
+## Features
+
+* Can now use SDK to handle generation of OAUTH tokens for the RESTFul services.
+
 ## 9.0.1 - 2017-03-06
 
 ### Fixes

docs/guide/configuration.rst

@@ -118,7 +118,7 @@ credentials
 ~~~~~~~~~~~
 
 :Type: ``array|DTS\eBaySDK\Credentials\CredentialsInterface|callable``
-:Services: ``BulkDataExchange``, ``BusinessPoliciesManagement``, ``Feedback``, ``FileTransfer``, ``Finding``, ``HalfFinding``, ``Merchandising``, ``Product``, ``ProductMetadata``, ``RelatedItemsManagement``, ``ResolutionCaseManagement``, ``ReturnManagement``, ``Shopping``, ``Trading``.
+:Services: ``BulkDataExchange``, ``BusinessPoliciesManagement``, ``Feedback``, ``FileTransfer``, ``Finding``, ``HalfFinding``, ``Merchandising``, ``OAuth``, ``Product``, ``ProductMetadata``, ``RelatedItemsManagement``, ``ResolutionCaseManagement``, ``ReturnManagement``, ``Shopping``, ``Trading``.
 
 Provide your "Application ID", "Certificate ID", and "Developer ID" credentials that are required when using the eBay API. If you do not provide any credentials the SDK will attempt to load them in the following order:
 
@@ -440,6 +440,15 @@ responseLanguage
 
 This configuration option will set the ``Accept-Language`` HTTP header for the request.
 
+ruName
+~~~~~~~~~~~~~~~~
+
+:Type: ``string``
+:Services: ``OAuth``
+:Required: ``true``
+
+This is the eBay Redirect URL name. eBay assigns two unique RuName values to your application, one for the Sandbox and another for the Production environment.
+
 sandbox
 ~~~~~~~
 

docs/guide/restful-services.rst

@@ -140,3 +140,135 @@ Returns true if any header names match the given header name using a case-insens
         );
     }
 
+OAuth access tokens
+-------------------
+
+The SDK provides some support for generating the OAuth tokens needed by the RESTful services. This is provided via the ``\DTS\eBaySDK\OAuth\Services\OAuthService`` class.
+
+
+.. code-block:: php
+
+    use \DTS\eBaySDK\OAuth\Services;
+    use \DTS\eBaySDK\OAuth\Types;
+
+    $service = new Services\OAuthService([
+        'credentials' => '<YOUR CREDENTIALS>',
+        'ruName'      => '<YOUR RUNAME>'
+    ]);
+
+Application tokens
+~~~~~~~~~~~~~~~~~~
+
+An application token can be generated by calling the ``getAppToken`` method on the service object.
+
+.. code-block:: php
+
+    $response = $service->getAppToken();
+
+    printf("\nStatus Code: %s\n\n", $response->getStatusCode());
+    if ($response->getStatusCode() !== 200) {
+        printf(
+            "%s: %s\n\n",
+            $response->error,
+            $response->error_description
+        );
+    } else {
+        printf(
+            "%s\n%s\n%s\n\n",
+            $response->access_token,
+            $response->token_type,
+            $response->expires_in
+        );
+    }
+
+User tokens
+~~~~~~~~~~~
+
+Generating a user token requires your application to redirect a user to eBay where they will grant permission. The redirect url can be created via the ``redirectUrlForUser`` method.
+
+.. code-block:: php
+
+    $service = new Services\OAuthService([
+        'credentials' => [
+            'appId'  => '111',
+            'certId' => '222',
+            'devId'  => '333',
+        ],
+        'ruName'      => 'foo'
+    ]);
+
+    $url =  $service->redirectUrlForUser([
+        'state' => 'bar',
+        'scope' => [
+            'https://api.ebay.com/oauth/api_scope/sell.account',
+            'https://api.ebay.com/oauth/api_scope/sell.inventory'
+        ]
+    ]);
+
+    echo $url;
+    /**
+     * Outputs (wrapped for readability)
+     *
+     * https://signin.ebay.com/authorize?
+     *   client_id=111&
+     *   redirect_uri=foo&
+     *   response_type=code&
+     *   state=bar&
+     *   scope=https%3A%2F%2Fapi.ebay.com%2Foauth%2Fapi_scope%2Fsell.account%20
+     *     https%3A%2F%2Fapi.ebay.com%2Foauth%2Fapi_scope%2Fsell.inventory
+     */
+
+Once a user has granted permission your application will be given a code that should be exchanged for an oauth token. This can be done with the ``getUserToken`` method.
+
+
+.. code-block:: php
+
+    $response = $service->getUserToken(new Types\GetUserTokenRestRequest([
+        'code' => '<CODE TO BE EXCHANGED FOR TOKEN>'
+    ]));
+
+    printf("\nStatus Code: %s\n\n", $response->getStatusCode());
+    if ($response->getStatusCode() !== 200) {
+        printf(
+            "%s: %s\n\n",
+            $response->error,
+            $response->error_description
+        );
+    } else {
+        printf(
+            "%s\n%s\n%s\n%s\n\n",
+            $response->access_token,
+            $response->token_type,
+            $response->expires_in,
+            $response->refresh_token
+        );
+    }
+
+The oauth tokens that eBay generate are short lived. A refresh token is given to your application in order to generate a new token without the need for prompting the user. The SDK provides the ``refreshUserToken`` method to handle this process. When calling this method you must ensure that the same ``scope`` values used in the ``redirectUrlForUser`` method is used.
+
+.. code-block:: php
+
+    $response = $service->refreshUserToken(new Types\RefreshUserTokenRestRequest([
+        'refresh_token' => '<REFRESH TOKEN>',
+        'scope' => [
+            'https://api.ebay.com/oauth/api_scope/sell.account',
+            'https://api.ebay.com/oauth/api_scope/sell.inventory'
+        ]
+    ]));
+
+    printf("\nStatus Code: %s\n\n", $response->getStatusCode());
+    if ($response->getStatusCode() !== 200) {
+        printf(
+            "%s: %s\n\n",
+            $response->error,
+            $response->error_description
+        );
+    } else {
+        printf(
+            "%s\n%s\n%s\n%s\n\n",
+            $response->access_token,
+            $response->token_type,
+            $response->expires_in,
+            $response->refresh_token
+        );
+    }