square.rb 8.0.0.20201216 → 26.1.0.20230119

data/lib/square/api/o_auth_api.rb

@@ -7,16 +7,16 @@ module Square
 
     # `RenewToken` is deprecated. For information about refreshing OAuth access
     # tokens, see
-    # [Renew OAuth
-    # Token](https://developer.squareup.com/docs/oauth-api/cookbook/renew-oauth-
-    # tokens).
+    # [Migrate from Renew to Refresh OAuth
+    # Tokens](https://developer.squareup.com/docs/oauth-api/migrate-to-refresh-t
+    # okens).
     # Renews an OAuth access token before it expires.
     # OAuth access tokens besides your application's personal access token
-    # expire after __30 days__.
-    # You can also renew expired tokens within __15 days__ of their expiration.
+    # expire after 30 days.
+    # You can also renew expired tokens within 15 days of their expiration.
     # You cannot renew an access token that has been expired for more than 15
     # days.
-    # Instead, the associated user must re-complete the OAuth flow from the
+    # Instead, the associated user must recomplete the OAuth flow from the
     # beginning.
     # __Important:__ The `Authorization` header for this endpoint must have the
     # following format:
@@ -25,10 +25,10 @@ module Square
     # ```
     # Replace `APPLICATION_SECRET` with the application secret on the
     # Credentials
-    # page in the [application dashboard](https://connect.squareup.com/apps).
-    # @param [String] client_id Required parameter: Your application ID,
-    # available from the [application
-    # dashboard](https://connect.squareup.com/apps).
+    # page in the [Developer Dashboard](https://developer.squareup.com/apps).
+    # @param [String] client_id Required parameter: Your application ID, which
+    # is available in the OAuth page in the [Developer
+    # Dashboard](https://developer.squareup.com/apps).
     # @param [RenewTokenRequest] body Required parameter: An object containing
     # the fields to POST for the request.  See the corresponding object
     # definition for field details.
@@ -51,7 +51,7 @@ module Square
       # Prepare headers.
       _headers = {
         'accept' => 'application/json',
-        'content-type' => 'application/json; charset=utf-8',
+        'Content-Type' => 'application/json',
         'Authorization' => authorization
       }
 
@@ -83,9 +83,8 @@ module Square
     # ```
     # Authorization: Client APPLICATION_SECRET
     # ```
-    # Replace `APPLICATION_SECRET` with the application secret on the
-    # Credentials
-    # page in the [Developer Dashboard](https://developer.squareup.com/apps).
+    # Replace `APPLICATION_SECRET` with the application secret on the OAuth
+    # page for your application on the Developer Dashboard.
     # @param [RevokeTokenRequest] body Required parameter: An object containing
     # the fields to POST for the request.  See the corresponding object
     # definition for field details.
@@ -102,7 +101,7 @@ module Square
       # Prepare headers.
       _headers = {
         'accept' => 'application/json',
-        'content-type' => 'application/json; charset=utf-8',
+        'Content-Type' => 'application/json',
         'Authorization' => authorization
       }
 
@@ -122,15 +121,22 @@ module Square
       )
     end
 
-    # Returns an OAuth access token.
-    # The endpoint supports distinct methods of obtaining OAuth access tokens.
-    # Applications specify a method by adding the `grant_type` parameter
-    # in the request and also provide relevant information.
-    # __Note:__ Regardless of the method application specified,
-    # the endpoint always returns two items; an OAuth access token and
-    # a refresh token in the response.
-    # __OAuth tokens should only live on secure servers. Application clients
-    # should never interact directly with OAuth tokens__.
+    # Returns an OAuth access token and a refresh token unless the
+    # `short_lived` parameter is set to `true`, in which case the endpoint
+    # returns only an access token.
+    # The `grant_type` parameter specifies the type of OAuth request. If
+    # `grant_type` is `authorization_code`, you must include the authorization
+    # code you received when a seller granted you authorization. If `grant_type`
+    # is `refresh_token`, you must provide a valid refresh token. If you are
+    # using
+    # an old version of the Square APIs (prior to March 13, 2019), `grant_type`
+    # can be `migration_token` and you must provide a valid migration token.
+    # You can use the `scopes` parameter to limit the set of permissions granted
+    # to the access token and refresh token. You can use the `short_lived`
+    # parameter
+    # to create an access token that expires in 24 hours.
+    # __Note:__ OAuth tokens should be encrypted and stored on a secure server.
+    # Application clients should never interact directly with OAuth tokens.
     # @param [ObtainTokenRequest] body Required parameter: An object containing
     # the fields to POST for the request.  See the corresponding object
     # definition for field details.
@@ -144,7 +150,7 @@ module Square
       # Prepare headers.
       _headers = {
         'accept' => 'application/json',
-        'content-type' => 'application/json; charset=utf-8'
+        'Content-Type' => 'application/json'
       }
 
       # Prepare and execute HttpRequest.
@@ -162,5 +168,52 @@ module Square
         _response, data: decoded, errors: _errors
       )
     end
+
+    # Returns information about an [OAuth access
+    # token](https://developer.squareup.com/docs/build-basics/access-tokens#get-
+    # an-oauth-access-token) or an application’s [personal access
+    # token](https://developer.squareup.com/docs/build-basics/access-tokens#get-
+    # a-personal-access-token).
+    # Add the access token to the Authorization header of the request.
+    # __Important:__ The `Authorization` header you provide to this endpoint
+    # must have the following format:
+    # ```
+    # Authorization: Bearer ACCESS_TOKEN
+    # ```
+    # where `ACCESS_TOKEN` is a
+    # [valid production authorization
+    # credential](https://developer.squareup.com/docs/build-basics/access-tokens
+    # ).
+    # If the access token is expired or not a valid access token, the endpoint
+    # returns an `UNAUTHORIZED` error.
+    # @param [String] authorization Required parameter: Client
+    # APPLICATION_SECRET
+    # @return [RetrieveTokenStatusResponse Hash] response from the API call
+    def retrieve_token_status(authorization:)
+      # Prepare query url.
+      _query_builder = config.get_base_uri
+      _query_builder << '/oauth2/token/status'
+      _query_url = APIHelper.clean_url _query_builder
+
+      # Prepare headers.
+      _headers = {
+        'accept' => 'application/json',
+        'Authorization' => authorization
+      }
+
+      # Prepare and execute HttpRequest.
+      _request = config.http_client.post(
+        _query_url,
+        headers: _headers
+      )
+      _response = execute_request(_request)
+
+      # Return appropriate response type.
+      decoded = APIHelper.json_deserialize(_response.raw_body)
+      _errors = APIHelper.map_response(decoded, ['errors'])
+      ApiResponse.new(
+        _response, data: decoded, errors: _errors
+      )
+    end
   end
 end