square.rb 8.1.0.20210121 → 18.1.0.20220316

data/lib/square/api/loyalty_api.rb

@@ -5,7 +5,8 @@ module Square
       super(config, http_call_back: http_call_back)
     end
 
-    # Creates a loyalty account.
+    # Creates a loyalty account. To create a loyalty account, you must provide
+    # the `program_id` and a `mapping` with the `phone_number` of the buyer.
     # @param [CreateLoyaltyAccountRequest] body Required parameter: An object
     # containing the fields to POST for the request.  See the corresponding
     # object definition for field details.
@@ -19,7 +20,7 @@ module Square
       # Prepare headers.
       _headers = {
         'accept' => 'application/json',
-        'content-type' => 'application/json; charset=utf-8'
+        'Content-Type' => 'application/json'
       }
 
       # Prepare and execute HttpRequest.
@@ -57,7 +58,7 @@ module Square
       # Prepare headers.
       _headers = {
         'accept' => 'application/json',
-        'content-type' => 'application/json; charset=utf-8'
+        'Content-Type' => 'application/json'
       }
 
       # Prepare and execute HttpRequest.
@@ -79,7 +80,7 @@ module Square
 
     # Retrieves a loyalty account.
     # @param [String] account_id Required parameter: The ID of the [loyalty
-    # account](#type-LoyaltyAccount) to retrieve.
+    # account]($m/LoyaltyAccount) to retrieve.
     # @return [RetrieveLoyaltyAccountResponse Hash] response from the API call
     def retrieve_loyalty_account(account_id:)
       # Prepare query url.
@@ -119,14 +120,12 @@ module Square
     # account.
     # - If you are not using the Orders API to manage orders,
     # you first perform a client-side computation to compute the points.
-    # For spend-based and visit-based programs, you can call
-    # [CalculateLoyaltyPoints](#endpoint-Loyalty-CalculateLoyaltyPoints) to
-    # compute the points. For more information,
-    # see [Loyalty Program
-    # Overview](https://developer.squareup.com/docs/loyalty/overview).
-    # You then provide the points in a request to this endpoint.
+    # For spend-based and visit-based programs, you can first call
+    # [CalculateLoyaltyPoints]($e/Loyalty/CalculateLoyaltyPoints) to compute the
+    # points
+    # that you provide to this endpoint.
     # @param [String] account_id Required parameter: The [loyalty
-    # account](#type-LoyaltyAccount) ID to which to add the points.
+    # account]($m/LoyaltyAccount) ID to which to add the points.
     # @param [AccumulateLoyaltyPointsRequest] body Required parameter: An object
     # containing the fields to POST for the request.  See the corresponding
     # object definition for field details.
@@ -145,7 +144,7 @@ module Square
       # Prepare headers.
       _headers = {
         'accept' => 'application/json',
-        'content-type' => 'application/json; charset=utf-8'
+        'Content-Type' => 'application/json'
       }
 
       # Prepare and execute HttpRequest.
@@ -168,10 +167,10 @@ module Square
     # Adds points to or subtracts points from a buyer's account.
     # Use this endpoint only when you need to manually adjust points. Otherwise,
     # in your application flow, you call
-    # [AccumulateLoyaltyPoints](#endpoint-Loyalty-AccumulateLoyaltyPoints)
+    # [AccumulateLoyaltyPoints]($e/Loyalty/AccumulateLoyaltyPoints)
     # to add points when a buyer pays for the purchase.
     # @param [String] account_id Required parameter: The ID of the [loyalty
-    # account](#type-LoyaltyAccount) in which to adjust the points.
+    # account]($m/LoyaltyAccount) in which to adjust the points.
     # @param [AdjustLoyaltyPointsRequest] body Required parameter: An object
     # containing the fields to POST for the request.  See the corresponding
     # object definition for field details.
@@ -190,7 +189,7 @@ module Square
       # Prepare headers.
       _headers = {
         'accept' => 'application/json',
-        'content-type' => 'application/json; charset=utf-8'
+        'Content-Type' => 'application/json'
       }
 
       # Prepare and execute HttpRequest.
@@ -217,6 +216,7 @@ module Square
     # (for example, points earned, points redeemed, and points expired) is
     # recorded in the ledger. Using this endpoint, you can search the ledger for
     # events.
+    # Search results are sorted by `created_at` in descending order.
     # @param [SearchLoyaltyEventsRequest] body Required parameter: An object
     # containing the fields to POST for the request.  See the corresponding
     # object definition for field details.
@@ -230,7 +230,7 @@ module Square
       # Prepare headers.
       _headers = {
         'accept' => 'application/json',
-        'content-type' => 'application/json; charset=utf-8'
+        'Content-Type' => 'application/json'
       }
 
       # Prepare and execute HttpRequest.
@@ -251,9 +251,16 @@ module Square
     end
 
     # Returns a list of loyalty programs in the seller's account.
-    # Currently, a seller can only have one loyalty program.
+    # Loyalty programs define how buyers can earn points and redeem points for
+    # rewards. Square sellers can have only one loyalty program, which is
+    # created and managed from the Seller Dashboard. For more information, see
+    # [Loyalty Program
+    # Overview](https://developer.squareup.com/docs/loyalty/overview).
+    # Replaced with [RetrieveLoyaltyProgram]($e/Loyalty/RetrieveLoyaltyProgram)
+    # when used with the keyword `main`.
     # @return [ListLoyaltyProgramsResponse Hash] response from the API call
     def list_loyalty_programs
+      warn 'Endpoint list_loyalty_programs in LoyaltyApi is deprecated'
       # Prepare query url.
       _query_builder = config.get_base_uri
       _query_builder << '/v2/loyalty/programs'
@@ -280,9 +287,51 @@ module Square
       )
     end
 
+    # Retrieves the loyalty program in a seller's account, specified by the
+    # program ID or the keyword `main`.
+    # Loyalty programs define how buyers can earn points and redeem points for
+    # rewards. Square sellers can have only one loyalty program, which is
+    # created and managed from the Seller Dashboard. For more information, see
+    # [Loyalty Program
+    # Overview](https://developer.squareup.com/docs/loyalty/overview).
+    # @param [String] program_id Required parameter: The ID of the loyalty
+    # program or the keyword `main`. Either value can be used to retrieve the
+    # single loyalty program that belongs to the seller.
+    # @return [RetrieveLoyaltyProgramResponse Hash] response from the API call
+    def retrieve_loyalty_program(program_id:)
+      # Prepare query url.
+      _query_builder = config.get_base_uri
+      _query_builder << '/v2/loyalty/programs/{program_id}'
+      _query_builder = APIHelper.append_url_with_template_parameters(
+        _query_builder,
+        'program_id' => { 'value' => program_id, 'encode' => true }
+      )
+      _query_url = APIHelper.clean_url _query_builder
+
+      # Prepare headers.
+      _headers = {
+        'accept' => 'application/json'
+      }
+
+      # Prepare and execute HttpRequest.
+      _request = config.http_client.get(
+        _query_url,
+        headers: _headers
+      )
+      OAuth2.apply(config, _request)
+      _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
+
     # Calculates the points a purchase earns.
-    # - If you are using the Orders API to manage orders, you provide `order_id`
-    # in the request. The
+    # - If you are using the Orders API to manage orders, you provide the
+    # `order_id` in the request. The
     # endpoint calculates the points by reading the order.
     # - If you are not using the Orders API to manage orders, you provide the
     # purchase amount in
@@ -290,8 +339,11 @@ module Square
     # An application might call this endpoint to show the points that a buyer
     # can earn with the
     # specific purchase.
+    # For spend-based and visit-based programs, the `tax_mode` setting of the
+    # accrual rule indicates how taxes should be treated for loyalty points
+    # accrual.
     # @param [String] program_id Required parameter: The [loyalty
-    # program](#type-LoyaltyProgram) ID, which defines the rules for accruing
+    # program]($m/LoyaltyProgram) ID, which defines the rules for accruing
     # points.
     # @param [CalculateLoyaltyPointsRequest] body Required parameter: An object
     # containing the fields to POST for the request.  See the corresponding
@@ -311,7 +363,7 @@ module Square
       # Prepare headers.
       _headers = {
         'accept' => 'application/json',
-        'content-type' => 'application/json; charset=utf-8'
+        'Content-Type' => 'application/json'
       }
 
       # Prepare and execute HttpRequest.
@@ -352,7 +404,7 @@ module Square
       # Prepare headers.
       _headers = {
         'accept' => 'application/json',
-        'content-type' => 'application/json; charset=utf-8'
+        'Content-Type' => 'application/json'
       }
 
       # Prepare and execute HttpRequest.
@@ -372,11 +424,13 @@ module Square
       )
     end
 
-    # Searches for loyalty rewards in a loyalty account.
-    # In the current implementation, the endpoint supports search by the reward
-    # `status`.
+    # Searches for loyalty rewards. This endpoint accepts a request with no
+    # query filters and returns results for all loyalty accounts.
+    # If you include a `query` object, `loyalty_account_id` is required and
+    # `status` is  optional.
     # If you know a reward ID, use the
-    # [RetrieveLoyaltyReward](#endpoint-Loyalty-RetrieveLoyaltyReward) endpoint.
+    # [RetrieveLoyaltyReward]($e/Loyalty/RetrieveLoyaltyReward) endpoint.
+    # Search results are sorted by `updated_at` in descending order.
     # @param [SearchLoyaltyRewardsRequest] body Required parameter: An object
     # containing the fields to POST for the request.  See the corresponding
     # object definition for field details.
@@ -390,7 +444,7 @@ module Square
       # Prepare headers.
       _headers = {
         'accept' => 'application/json',
-        'content-type' => 'application/json; charset=utf-8'
+        'Content-Type' => 'application/json'
       }
 
       # Prepare and execute HttpRequest.
@@ -413,12 +467,12 @@ module Square
     # Deletes a loyalty reward by doing the following:
     # - Returns the loyalty points back to the loyalty account.
     # - If an order ID was specified when the reward was created
-    # (see [CreateLoyaltyReward](#endpoint-Loyalty-CreateLoyaltyReward)),
+    # (see [CreateLoyaltyReward]($e/Loyalty/CreateLoyaltyReward)),
     # it updates the order by removing the reward and related
     # discounts.
     # You cannot delete a reward that has reached the terminal state (REDEEMED).
     # @param [String] reward_id Required parameter: The ID of the [loyalty
-    # reward](#type-LoyaltyReward) to delete.
+    # reward]($m/LoyaltyReward) to delete.
     # @return [DeleteLoyaltyRewardResponse Hash] response from the API call
     def delete_loyalty_reward(reward_id:)
       # Prepare query url.
@@ -453,7 +507,7 @@ module Square
 
     # Retrieves a loyalty reward.
     # @param [String] reward_id Required parameter: The ID of the [loyalty
-    # reward](#type-LoyaltyReward) to retrieve.
+    # reward]($m/LoyaltyReward) to retrieve.
     # @return [RetrieveLoyaltyRewardResponse Hash] response from the API call
     def retrieve_loyalty_reward(reward_id:)
       # Prepare query url.
@@ -495,7 +549,7 @@ module Square
     # In other words, points used for the reward cannot be returned
     # to the account.
     # @param [String] reward_id Required parameter: The ID of the [loyalty
-    # reward](#type-LoyaltyReward) to redeem.
+    # reward]($m/LoyaltyReward) to redeem.
     # @param [RedeemLoyaltyRewardRequest] body Required parameter: An object
     # containing the fields to POST for the request.  See the corresponding
     # object definition for field details.
@@ -514,7 +568,7 @@ module Square
       # Prepare headers.
       _headers = {
         'accept' => 'application/json',
-        'content-type' => 'application/json; charset=utf-8'
+        'Content-Type' => 'application/json'
       }
 
       # Prepare and execute HttpRequest.

data/lib/square/api/merchants_api.rb

@@ -5,15 +5,17 @@ module Square
       super(config, http_call_back: http_call_back)
     end
 
-    # Returns `Merchant` information for a given access token.
-    # If you don't know a `Merchant` ID, you can use this endpoint to retrieve
-    # the merchant ID for an access token.
-    # You can specify your personal access token to get your own merchant
-    # information or specify an OAuth token
-    # to get the information for the  merchant that granted you access.
+    # Provides details about the merchant associated with a given access token.
+    # The access token used to connect your application to a Square seller is
+    # associated
+    # with a single merchant. That means that `ListMerchants` returns a list
+    # with a single `Merchant` object. You can specify your personal access
+    # token
+    # to get your own merchant information or specify an OAuth token to get the
+    # information for the merchant that granted your application access.
     # If you know the merchant ID, you can also use the
-    # [RetrieveMerchant](#endpoint-merchants-retrievemerchant)
-    # endpoint to get the merchant information.
+    # [RetrieveMerchant]($e/Merchants/RetrieveMerchant)
+    # endpoint to retrieve the merchant information.
     # @param [Integer] cursor Optional parameter: The cursor generated by the
     # previous response.
     # @return [ListMerchantsResponse Hash] response from the API call
@@ -48,7 +50,7 @@ module Square
       )
     end
 
-    # Retrieve a `Merchant` object for the given `merchant_id`.
+    # Retrieves the `Merchant` object for the given `merchant_id`.
     # @param [String] merchant_id Required parameter: The ID of the merchant to
     # retrieve. If the string "me" is supplied as the ID, then retrieve the
     # merchant that is currently accessible to this call.

data/lib/square/api/mobile_authorization_api.rb

@@ -6,9 +6,9 @@ module Square
     end
 
     # Generates code to authorize a mobile application to connect to a Square
-    # card reader
-    # Authorization codes are one-time-use and expire __60 minutes__ after being
-    # issued.
+    # card reader.
+    # Authorization codes are one-time-use codes and expire 60 minutes after
+    # being issued.
     # __Important:__ The `Authorization` header you provide to this endpoint
     # must have the following format:
     # ```
@@ -31,7 +31,7 @@ module Square
       # Prepare headers.
       _headers = {
         'accept' => 'application/json',
-        'content-type' => 'application/json; charset=utf-8'
+        'Content-Type' => 'application/json'
       }
 
       # Prepare and execute HttpRequest.

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.