square.rb 6.3.0.20200826 → 17.1.0.20220120

data/lib/square/api/loyalty_api.rb

@@ -5,10 +5,8 @@ module Square
       super(config, http_call_back: http_call_back)
     end
 
-    # Creates a loyalty account. For more information, see
-    # [Create a loyalty
-    # account](https://developer.squareup.com/docs/docs/loyalty-api/overview/#lo
-    # yalty-overview-create-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.
@@ -22,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.
@@ -37,13 +35,16 @@ module Square
       # Return appropriate response type.
       decoded = APIHelper.json_deserialize(_response.raw_body)
       _errors = APIHelper.map_response(decoded, ['errors'])
-      ApiResponse.new(_response, data: decoded, errors: _errors)
+      ApiResponse.new(
+        _response, data: decoded, errors: _errors
+      )
     end
 
-    # Searches for loyalty accounts.
-    # In the current implementation, you can search for a loyalty account using
-    # the phone number associated with the account.
-    # If no phone number is provided, all loyalty accounts are returned.
+    # Searches for loyalty accounts in a loyalty program.
+    # You can search for a loyalty account using the phone number or customer ID
+    # associated with the account. To return all loyalty accounts, specify an
+    # empty `query` object or omit it entirely.
+    # Search results are sorted by `created_at` in ascending order.
     # @param [SearchLoyaltyAccountsRequest] body Required parameter: An object
     # containing the fields to POST for the request.  See the corresponding
     # object definition for field details.
@@ -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.
@@ -72,12 +73,14 @@ module Square
       # Return appropriate response type.
       decoded = APIHelper.json_deserialize(_response.raw_body)
       _errors = APIHelper.map_response(decoded, ['errors'])
-      ApiResponse.new(_response, data: decoded, errors: _errors)
+      ApiResponse.new(
+        _response, data: decoded, errors: _errors
+      )
     end
 
     # 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.
@@ -85,7 +88,7 @@ module Square
       _query_builder << '/v2/loyalty/accounts/{account_id}'
       _query_builder = APIHelper.append_url_with_template_parameters(
         _query_builder,
-        'account_id' => account_id
+        'account_id' => { 'value' => account_id, 'encode' => true }
       )
       _query_url = APIHelper.clean_url _query_builder
 
@@ -105,7 +108,9 @@ module Square
       # Return appropriate response type.
       decoded = APIHelper.json_deserialize(_response.raw_body)
       _errors = APIHelper.map_response(decoded, ['errors'])
-      ApiResponse.new(_response, data: decoded, errors: _errors)
+      ApiResponse.new(
+        _response, data: decoded, errors: _errors
+      )
     end
 
     # Adds points to a loyalty account.
@@ -115,16 +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` to compute the points. For more information,
-    # see [Loyalty Program
-    # Overview](https://developer.squareup.com/docs/docs/loyalty/overview).
-    # You then provide the points in a request to this endpoint.
-    # For more information, see [Accumulate
-    # points](https://developer.squareup.com/docs/docs/loyalty-api/overview/#acc
-    # umulate-points).
+    # 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.
@@ -136,14 +137,14 @@ module Square
       _query_builder << '/v2/loyalty/accounts/{account_id}/accumulate'
       _query_builder = APIHelper.append_url_with_template_parameters(
         _query_builder,
-        'account_id' => account_id
+        'account_id' => { 'value' => account_id, 'encode' => true }
       )
       _query_url = APIHelper.clean_url _query_builder
 
       # Prepare headers.
       _headers = {
         'accept' => 'application/json',
-        'content-type' => 'application/json; charset=utf-8'
+        'Content-Type' => 'application/json'
       }
 
       # Prepare and execute HttpRequest.
@@ -158,17 +159,18 @@ module Square
       # Return appropriate response type.
       decoded = APIHelper.json_deserialize(_response.raw_body)
       _errors = APIHelper.map_response(decoded, ['errors'])
-      ApiResponse.new(_response, data: decoded, errors: _errors)
+      ApiResponse.new(
+        _response, data: decoded, errors: _errors
+      )
     end
 
     # 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](https://developer.squareup.com/docs/reference/sq
-    # uare/loyalty-api/accumulate-loyalty-points)
+    # [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.
@@ -180,14 +182,14 @@ module Square
       _query_builder << '/v2/loyalty/accounts/{account_id}/adjust'
       _query_builder = APIHelper.append_url_with_template_parameters(
         _query_builder,
-        'account_id' => account_id
+        'account_id' => { 'value' => account_id, 'encode' => true }
       )
       _query_url = APIHelper.clean_url _query_builder
 
       # Prepare headers.
       _headers = {
         'accept' => 'application/json',
-        'content-type' => 'application/json; charset=utf-8'
+        'Content-Type' => 'application/json'
       }
 
       # Prepare and execute HttpRequest.
@@ -202,7 +204,9 @@ module Square
       # Return appropriate response type.
       decoded = APIHelper.json_deserialize(_response.raw_body)
       _errors = APIHelper.map_response(decoded, ['errors'])
-      ApiResponse.new(_response, data: decoded, errors: _errors)
+      ApiResponse.new(
+        _response, data: decoded, errors: _errors
+      )
     end
 
     # Searches for loyalty events.
@@ -212,10 +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.
-    # For more information, see
-    # [Loyalty
-    # events](https://developer.squareup.com/docs/docs/loyalty-api/overview/#loy
-    # alty-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.
@@ -229,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.
@@ -244,17 +245,22 @@ module Square
       # Return appropriate response type.
       decoded = APIHelper.json_deserialize(_response.raw_body)
       _errors = APIHelper.map_response(decoded, ['errors'])
-      ApiResponse.new(_response, data: decoded, errors: _errors)
+      ApiResponse.new(
+        _response, data: decoded, errors: _errors
+      )
     end
 
     # Returns a list of loyalty programs in the seller's account.
-    # Currently, a seller can only have one loyalty program. For more
-    # information, see
-    # [Loyalty
-    # Overview](https://developer.squareup.com/docs/docs/loyalty/overview).
-    # .
+    # 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'
@@ -276,12 +282,56 @@ module Square
       # Return appropriate response type.
       decoded = APIHelper.json_deserialize(_response.raw_body)
       _errors = APIHelper.map_response(decoded, ['errors'])
-      ApiResponse.new(_response, data: decoded, errors: _errors)
+      ApiResponse.new(
+        _response, data: decoded, errors: _errors
+      )
+    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
@@ -289,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
@@ -303,14 +356,14 @@ module Square
       _query_builder << '/v2/loyalty/programs/{program_id}/calculate'
       _query_builder = APIHelper.append_url_with_template_parameters(
         _query_builder,
-        'program_id' => program_id
+        'program_id' => { 'value' => program_id, 'encode' => true }
       )
       _query_url = APIHelper.clean_url _query_builder
 
       # Prepare headers.
       _headers = {
         'accept' => 'application/json',
-        'content-type' => 'application/json; charset=utf-8'
+        'Content-Type' => 'application/json'
       }
 
       # Prepare and execute HttpRequest.
@@ -325,7 +378,9 @@ module Square
       # Return appropriate response type.
       decoded = APIHelper.json_deserialize(_response.raw_body)
       _errors = APIHelper.map_response(decoded, ['errors'])
-      ApiResponse.new(_response, data: decoded, errors: _errors)
+      ApiResponse.new(
+        _response, data: decoded, errors: _errors
+      )
     end
 
     # Creates a loyalty reward. In the process, the endpoint does following:
@@ -336,10 +391,6 @@ module Square
     # discount to the order.
     # After a reward is created, the points are locked and
     # not available for the buyer to redeem another reward.
-    # For more information, see
-    # [Loyalty
-    # rewards](https://developer.squareup.com/docs/docs/loyalty-api/overview/#lo
-    # yalty-overview-loyalty-rewards).
     # @param [CreateLoyaltyRewardRequest] body Required parameter: An object
     # containing the fields to POST for the request.  See the corresponding
     # object definition for field details.
@@ -353,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.
@@ -368,19 +419,17 @@ module Square
       # Return appropriate response type.
       decoded = APIHelper.json_deserialize(_response.raw_body)
       _errors = APIHelper.map_response(decoded, ['errors'])
-      ApiResponse.new(_response, data: decoded, errors: _errors)
+      ApiResponse.new(
+        _response, data: decoded, errors: _errors
+      )
     end
 
     # Searches for loyalty rewards in a loyalty account.
     # In the current implementation, the endpoint supports search by the reward
     # `status`.
     # If you know a reward ID, use the
-    # [RetrieveLoyaltyReward](https://developer.squareup.com/docs/reference/squa
-    # re/loyalty-api/retrieve-loyalty-reward) endpoint.
-    # For more information about loyalty rewards, see
-    # [Loyalty
-    # Rewards](https://developer.squareup.com/docs/docs/loyalty-api/overview/#lo
-    # yalty-rewards).
+    # [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.
@@ -394,7 +443,7 @@ module Square
       # Prepare headers.
       _headers = {
         'accept' => 'application/json',
-        'content-type' => 'application/json; charset=utf-8'
+        'Content-Type' => 'application/json'
       }
 
       # Prepare and execute HttpRequest.
@@ -409,24 +458,20 @@ module Square
       # Return appropriate response type.
       decoded = APIHelper.json_deserialize(_response.raw_body)
       _errors = APIHelper.map_response(decoded, ['errors'])
-      ApiResponse.new(_response, data: decoded, errors: _errors)
+      ApiResponse.new(
+        _response, data: decoded, errors: _errors
+      )
     end
 
     # 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](https://developer.squareup.com/docs/reference/square
-    # /loyalty-api/create-loyalty-reward)),
+    # (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).
-    # For more information, see
-    # [Loyalty
-    # rewards](https://developer.squareup.com/docs/docs/loyalty-api/overview/#lo
-    # yalty-overview-loyalty-rewards).
     # @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.
@@ -434,7 +479,7 @@ module Square
       _query_builder << '/v2/loyalty/rewards/{reward_id}'
       _query_builder = APIHelper.append_url_with_template_parameters(
         _query_builder,
-        'reward_id' => reward_id
+        'reward_id' => { 'value' => reward_id, 'encode' => true }
       )
       _query_url = APIHelper.clean_url _query_builder
 
@@ -454,12 +499,14 @@ module Square
       # Return appropriate response type.
       decoded = APIHelper.json_deserialize(_response.raw_body)
       _errors = APIHelper.map_response(decoded, ['errors'])
-      ApiResponse.new(_response, data: decoded, errors: _errors)
+      ApiResponse.new(
+        _response, data: decoded, errors: _errors
+      )
     end
 
     # 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.
@@ -467,7 +514,7 @@ module Square
       _query_builder << '/v2/loyalty/rewards/{reward_id}'
       _query_builder = APIHelper.append_url_with_template_parameters(
         _query_builder,
-        'reward_id' => reward_id
+        'reward_id' => { 'value' => reward_id, 'encode' => true }
       )
       _query_url = APIHelper.clean_url _query_builder
 
@@ -487,23 +534,21 @@ module Square
       # Return appropriate response type.
       decoded = APIHelper.json_deserialize(_response.raw_body)
       _errors = APIHelper.map_response(decoded, ['errors'])
-      ApiResponse.new(_response, data: decoded, errors: _errors)
+      ApiResponse.new(
+        _response, data: decoded, errors: _errors
+      )
     end
 
     # Redeems a loyalty reward.
-    # The endpoint sets the reward to the terminal state (`REDEEMED`).
+    # The endpoint sets the reward to the `REDEEMED` terminal state.
     # If you are using your own order processing system (not using the
     # Orders API), you call this endpoint after the buyer paid for the
     # purchase.
     # After the reward reaches the terminal state, it cannot be deleted.
     # In other words, points used for the reward cannot be returned
     # to the account.
-    # For more information, see
-    # [Loyalty
-    # rewards](https://developer.squareup.com/docs/docs/loyalty-api/overview/#lo
-    # yalty-overview-loyalty-rewards).
     # @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.
@@ -515,14 +560,14 @@ module Square
       _query_builder << '/v2/loyalty/rewards/{reward_id}/redeem'
       _query_builder = APIHelper.append_url_with_template_parameters(
         _query_builder,
-        'reward_id' => reward_id
+        'reward_id' => { 'value' => reward_id, 'encode' => true }
       )
       _query_url = APIHelper.clean_url _query_builder
 
       # Prepare headers.
       _headers = {
         'accept' => 'application/json',
-        'content-type' => 'application/json; charset=utf-8'
+        'Content-Type' => 'application/json'
       }
 
       # Prepare and execute HttpRequest.
@@ -537,7 +582,9 @@ module Square
       # Return appropriate response type.
       decoded = APIHelper.json_deserialize(_response.raw_body)
       _errors = APIHelper.map_response(decoded, ['errors'])
-      ApiResponse.new(_response, data: decoded, errors: _errors)
+      ApiResponse.new(
+        _response, data: decoded, errors: _errors
+      )
     end
   end
 end

data/lib/square/api/merchants_api.rb

@@ -12,7 +12,7 @@ module Square
     # information or specify an OAuth token
     # to get the information for the  merchant that granted you access.
     # If you know the merchant ID, you can also use the
-    # [RetrieveMerchant](#endpoint-merchants-retrievemerchant)
+    # [RetrieveMerchant]($e/Merchants/RetrieveMerchant)
     # endpoint to get the merchant information.
     # @param [Integer] cursor Optional parameter: The cursor generated by the
     # previous response.
@@ -43,7 +43,9 @@ module Square
       # Return appropriate response type.
       decoded = APIHelper.json_deserialize(_response.raw_body)
       _errors = APIHelper.map_response(decoded, ['errors'])
-      ApiResponse.new(_response, data: decoded, errors: _errors)
+      ApiResponse.new(
+        _response, data: decoded, errors: _errors
+      )
     end
 
     # Retrieve a `Merchant` object for the given `merchant_id`.
@@ -57,7 +59,7 @@ module Square
       _query_builder << '/v2/merchants/{merchant_id}'
       _query_builder = APIHelper.append_url_with_template_parameters(
         _query_builder,
-        'merchant_id' => merchant_id
+        'merchant_id' => { 'value' => merchant_id, 'encode' => true }
       )
       _query_url = APIHelper.clean_url _query_builder
 
@@ -77,7 +79,9 @@ module Square
       # Return appropriate response type.
       decoded = APIHelper.json_deserialize(_response.raw_body)
       _errors = APIHelper.map_response(decoded, ['errors'])
-      ApiResponse.new(_response, data: decoded, errors: _errors)
+      ApiResponse.new(
+        _response, data: decoded, errors: _errors
+      )
     end
   end
 end

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:
     # ```
@@ -16,8 +16,8 @@ module Square
     # ```
     # Replace `ACCESS_TOKEN` with a
     # [valid production authorization
-    # credential](https://developer.squareup.com/docs/docs/build-basics/access-t
-    # okens).
+    # credential](https://developer.squareup.com/docs/build-basics/access-tokens
+    # ).
     # @param [CreateMobileAuthorizationCodeRequest] body Required parameter: An
     # object containing the fields to POST for the request.  See the
     # corresponding object definition for field details.
@@ -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.
@@ -46,7 +46,9 @@ module Square
       # Return appropriate response type.
       decoded = APIHelper.json_deserialize(_response.raw_body)
       _errors = APIHelper.map_response(decoded, ['errors'])
-      ApiResponse.new(_response, data: decoded, errors: _errors)
+      ApiResponse.new(
+        _response, data: decoded, errors: _errors
+      )
     end
   end
 end