square.rb 18.1.0.20220316 → 20.1.0.20220616

data/lib/square/api/payouts_api.rb

@@ -0,0 +1,173 @@
+module Square
+  # PayoutsApi
+  class PayoutsApi < BaseApi
+    def initialize(config, http_call_back: nil)
+      super(config, http_call_back: http_call_back)
+    end
+
+    # Retrieves a list of all payouts for the default location.
+    # You can filter payouts by location ID, status, time range, and order them
+    # in ascending or descending order.
+    # To call this endpoint, set `PAYOUTS_READ` for the OAuth scope.
+    # @param [String] location_id Optional parameter: The ID of the location for
+    # which to list the payouts.  By default, payouts are returned for the
+    # default (main) location associated with the seller.
+    # @param [PayoutStatus] status Optional parameter: If provided, only payouts
+    # with the given status are returned.
+    # @param [String] begin_time Optional parameter: The timestamp for the
+    # beginning of the payout creation time, in RFC 3339 format. Inclusive.
+    # Default: The current time minus one year.
+    # @param [String] end_time Optional parameter: The timestamp for the end of
+    # the payout creation time, in RFC 3339 format. Default: The current time.
+    # @param [SortOrder] sort_order Optional parameter: The order in which
+    # payouts are listed.
+    # @param [String] cursor Optional parameter: A pagination cursor returned by
+    # a previous call to this endpoint. Provide this cursor to retrieve the next
+    # set of results for the original query. For more information, see
+    # [Pagination](https://developer.squareup.com/docs/basics/api101/pagination)
+    # . If request parameters change between requests, subsequent results may
+    # contain duplicates or missing records.
+    # @param [Integer] limit Optional parameter: The maximum number of results
+    # to be returned in a single page. It is possible to receive fewer results
+    # than the specified limit on a given page. The default value of 100 is also
+    # the maximum allowed value. If the provided value is greater than 100, it
+    # is ignored and the default value is used instead. Default: `100`
+    # @return [ListPayoutsResponse Hash] response from the API call
+    def list_payouts(location_id: nil,
+                     status: nil,
+                     begin_time: nil,
+                     end_time: nil,
+                     sort_order: nil,
+                     cursor: nil,
+                     limit: nil)
+      # Prepare query url.
+      _query_builder = config.get_base_uri
+      _query_builder << '/v2/payouts'
+      _query_builder = APIHelper.append_url_with_query_parameters(
+        _query_builder,
+        'location_id' => location_id,
+        'status' => status,
+        'begin_time' => begin_time,
+        'end_time' => end_time,
+        'sort_order' => sort_order,
+        'cursor' => cursor,
+        'limit' => limit
+      )
+      _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
+
+    # Retrieves details of a specific payout identified by a payout ID.
+    # To call this endpoint, set `PAYOUTS_READ` for the OAuth scope.
+    # @param [String] payout_id Required parameter: The ID of the payout to
+    # retrieve the information for.
+    # @return [GetPayoutResponse Hash] response from the API call
+    def get_payout(payout_id:)
+      # Prepare query url.
+      _query_builder = config.get_base_uri
+      _query_builder << '/v2/payouts/{payout_id}'
+      _query_builder = APIHelper.append_url_with_template_parameters(
+        _query_builder,
+        'payout_id' => { 'value' => payout_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
+
+    # Retrieves a list of all payout entries for a specific payout.
+    # To call this endpoint, set `PAYOUTS_READ` for the OAuth scope.
+    # @param [String] payout_id Required parameter: The ID of the payout to
+    # retrieve the information for.
+    # @param [SortOrder] sort_order Optional parameter: The order in which
+    # payout entries are listed.
+    # @param [String] cursor Optional parameter: A pagination cursor returned by
+    # a previous call to this endpoint. Provide this cursor to retrieve the next
+    # set of results for the original query. For more information, see
+    # [Pagination](https://developer.squareup.com/docs/basics/api101/pagination)
+    # . If request parameters change between requests, subsequent results may
+    # contain duplicates or missing records.
+    # @param [Integer] limit Optional parameter: The maximum number of results
+    # to be returned in a single page. It is possible to receive fewer results
+    # than the specified limit on a given page. The default value of 100 is also
+    # the maximum allowed value. If the provided value is greater than 100, it
+    # is ignored and the default value is used instead. Default: `100`
+    # @return [ListPayoutEntriesResponse Hash] response from the API call
+    def list_payout_entries(payout_id:,
+                            sort_order: nil,
+                            cursor: nil,
+                            limit: nil)
+      # Prepare query url.
+      _query_builder = config.get_base_uri
+      _query_builder << '/v2/payouts/{payout_id}/payout-entries'
+      _query_builder = APIHelper.append_url_with_template_parameters(
+        _query_builder,
+        'payout_id' => { 'value' => payout_id, 'encode' => true }
+      )
+      _query_builder = APIHelper.append_url_with_query_parameters(
+        _query_builder,
+        'sort_order' => sort_order,
+        'cursor' => cursor,
+        'limit' => limit
+      )
+      _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
+  end
+end

data/lib/square/api/subscriptions_api.rb

@@ -260,9 +260,6 @@ module Square
     end
 
     # Lists all events for a specific subscription.
-    # In the current implementation, only `START_SUBSCRIPTION` and
-    # `STOP_SUBSCRIPTION` (when the subscription was canceled) events are
-    # returned.
     # @param [String] subscription_id Required parameter: The ID of the
     # subscription to retrieve the events for.
     # @param [String] cursor Optional parameter: When the total number of

data/lib/square/api/terminal_api.rb

@@ -5,6 +5,147 @@ module Square
       super(config, http_call_back: http_call_back)
     end
 
+    # Creates a Terminal action request and sends it to the specified device.
+    # @param [CreateTerminalActionRequest] body Required parameter: An object
+    # containing the fields to POST for the request.  See the corresponding
+    # object definition for field details.
+    # @return [CreateTerminalActionResponse Hash] response from the API call
+    def create_terminal_action(body:)
+      # Prepare query url.
+      _query_builder = config.get_base_uri
+      _query_builder << '/v2/terminals/actions'
+      _query_url = APIHelper.clean_url _query_builder
+
+      # Prepare headers.
+      _headers = {
+        'accept' => 'application/json',
+        'Content-Type' => 'application/json'
+      }
+
+      # Prepare and execute HttpRequest.
+      _request = config.http_client.post(
+        _query_url,
+        headers: _headers,
+        parameters: body.to_json
+      )
+      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
+
+    # Retrieves a filtered list of Terminal action requests created by the
+    # account making the request. Terminal action requests are available for 30
+    # days.
+    # @param [SearchTerminalActionsRequest] body Required parameter: An object
+    # containing the fields to POST for the request.  See the corresponding
+    # object definition for field details.
+    # @return [SearchTerminalActionsResponse Hash] response from the API call
+    def search_terminal_actions(body:)
+      # Prepare query url.
+      _query_builder = config.get_base_uri
+      _query_builder << '/v2/terminals/actions/search'
+      _query_url = APIHelper.clean_url _query_builder
+
+      # Prepare headers.
+      _headers = {
+        'accept' => 'application/json',
+        'Content-Type' => 'application/json'
+      }
+
+      # Prepare and execute HttpRequest.
+      _request = config.http_client.post(
+        _query_url,
+        headers: _headers,
+        parameters: body.to_json
+      )
+      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
+
+    # Retrieves a Terminal action request by `action_id`. Terminal action
+    # requests are available for 30 days.
+    # @param [String] action_id Required parameter: Unique ID for the desired
+    # `TerminalAction`
+    # @return [GetTerminalActionResponse Hash] response from the API call
+    def get_terminal_action(action_id:)
+      # Prepare query url.
+      _query_builder = config.get_base_uri
+      _query_builder << '/v2/terminals/actions/{action_id}'
+      _query_builder = APIHelper.append_url_with_template_parameters(
+        _query_builder,
+        'action_id' => { 'value' => action_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
+
+    # Cancels a Terminal action request if the status of the request permits it.
+    # @param [String] action_id Required parameter: Unique ID for the desired
+    # `TerminalAction`
+    # @return [CancelTerminalActionResponse Hash] response from the API call
+    def cancel_terminal_action(action_id:)
+      # Prepare query url.
+      _query_builder = config.get_base_uri
+      _query_builder << '/v2/terminals/actions/{action_id}/cancel'
+      _query_builder = APIHelper.append_url_with_template_parameters(
+        _query_builder,
+        'action_id' => { 'value' => action_id, 'encode' => true }
+      )
+      _query_url = APIHelper.clean_url _query_builder
+
+      # Prepare headers.
+      _headers = {
+        'accept' => 'application/json'
+      }
+
+      # Prepare and execute HttpRequest.
+      _request = config.http_client.post(
+        _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
+
     # Creates a Terminal checkout request and sends it to the specified device
     # to take a payment
     # for the requested amount.
@@ -41,8 +182,10 @@ module Square
       )
     end
 
-    # Retrieves a filtered list of Terminal checkout requests created by the
-    # account making the request.
+    # Returns a filtered list of Terminal checkout requests created by the
+    # application making the request. Only Terminal checkout requests created
+    # for the merchant scoped to the OAuth token are returned. Terminal checkout
+    # requests are available for 30 days.
     # @param [SearchTerminalCheckoutsRequest] body Required parameter: An object
     # containing the fields to POST for the request.  See the corresponding
     # object definition for field details.
@@ -76,7 +219,8 @@ module Square
       )
     end
 
-    # Retrieves a Terminal checkout request by `checkout_id`.
+    # Retrieves a Terminal checkout request by `checkout_id`. Terminal checkout
+    # requests are available for 30 days.
     # @param [String] checkout_id Required parameter: The unique ID for the
     # desired `TerminalCheckout`.
     # @return [GetTerminalCheckoutResponse Hash] response from the API call
@@ -148,7 +292,10 @@ module Square
     end
 
     # Creates a request to refund an Interac payment completed on a Square
-    # Terminal.
+    # Terminal. Refunds for Interac payments on a Square Terminal are supported
+    # only for Interac debit cards in Canada. Other refunds for Terminal
+    # payments should use the Refunds API. For more information, see [Refunds
+    # API]($e/Refunds).
     # @param [CreateTerminalRefundRequest] body Required parameter: An object
     # containing the fields to POST for the request.  See the corresponding
     # object definition for field details.
@@ -183,7 +330,8 @@ module Square
     end
 
     # Retrieves a filtered list of Interac Terminal refund requests created by
-    # the seller making the request.
+    # the seller making the request. Terminal refund requests are available for
+    # 30 days.
     # @param [SearchTerminalRefundsRequest] body Required parameter: An object
     # containing the fields to POST for the request.  See the corresponding
     # object definition for field details.
@@ -217,7 +365,8 @@ module Square
       )
     end
 
-    # Retrieves an Interac Terminal refund object by ID.
+    # Retrieves an Interac Terminal refund object by ID. Terminal refund objects
+    # are available for 30 days.
     # @param [String] terminal_refund_id Required parameter: The unique ID for
     # the desired `TerminalRefund`.
     # @return [GetTerminalRefundResponse Hash] response from the API call

data/lib/square/client.rb

@@ -4,7 +4,7 @@ module Square
     attr_reader :config
 
     def sdk_version
-      '18.1.0.20220316'
+      '20.1.0.20220616'
     end
 
     def square_version
@@ -75,6 +75,12 @@ module Square
       @customers ||= CustomersApi.new config
     end
 
+    # Access to customer_custom_attributes controller.
+    # @return [CustomerCustomAttributesApi] Returns the controller instance.
+    def customer_custom_attributes
+      @customer_custom_attributes ||= CustomerCustomAttributesApi.new config
+    end
+
     # Access to customer_groups controller.
     # @return [CustomerGroupsApi] Returns the controller instance.
     def customer_groups
@@ -177,6 +183,12 @@ module Square
       @payments ||= PaymentsApi.new config
     end
 
+    # Access to payouts controller.
+    # @return [PayoutsApi] Returns the controller instance.
+    def payouts
+      @payouts ||= PayoutsApi.new config
+    end
+
     # Access to refunds controller.
     # @return [RefundsApi] Returns the controller instance.
     def refunds
@@ -219,16 +231,17 @@ module Square
       @vendors ||= VendorsApi.new config
     end
 
-    def initialize(connection: nil, timeout: 60, max_retries: 0,
-                   retry_interval: 1, backoff_factor: 2,
+    def initialize(connection: nil, adapter: Faraday.default_adapter,
+                   timeout: 60, max_retries: 0, retry_interval: 1,
+                   backoff_factor: 2,
                    retry_statuses: [408, 413, 429, 500, 502, 503, 504, 521, 522, 524],
                    retry_methods: %i[get put], environment: 'production',
                    custom_url: 'https://connect.squareup.com',
-                   square_version: '2022-03-16', access_token: '',
+                   square_version: '2022-06-16', access_token: '',
                    user_agent_detail: '', additional_headers: {}, config: nil)
       @config = if config.nil?
-                  Configuration.new(connection: connection, timeout: timeout,
-                                    max_retries: max_retries,
+                  Configuration.new(connection: connection, adapter: adapter,
+                                    timeout: timeout, max_retries: max_retries,
                                     retry_interval: retry_interval,
                                     backoff_factor: backoff_factor,
                                     retry_statuses: retry_statuses,

data/lib/square/configuration.rb

@@ -3,9 +3,9 @@ module Square
   # are configured in this class.
   class Configuration
     # The attribute readers for properties.
-    attr_reader :http_client, :connection, :timeout, :max_retries, :retry_interval, :backoff_factor,
-                :retry_statuses, :retry_methods, :environment, :custom_url, :square_version,
-                :access_token, :user_agent_detail
+    attr_reader :http_client, :connection, :adapter, :timeout, :max_retries, :retry_interval,
+                :backoff_factor, :retry_statuses, :retry_methods, :environment, :custom_url,
+                :square_version, :access_token, :user_agent_detail
 
     def additional_headers
       @additional_headers.clone
@@ -15,16 +15,20 @@ module Square
       attr_reader :environments
     end
 
-    def initialize(connection: nil, timeout: 60, max_retries: 0,
-                   retry_interval: 1, backoff_factor: 2,
+    def initialize(connection: nil, adapter: Faraday.default_adapter,
+                   timeout: 60, max_retries: 0, retry_interval: 1,
+                   backoff_factor: 2,
                    retry_statuses: [408, 413, 429, 500, 502, 503, 504, 521, 522, 524],
                    retry_methods: %i[get put], environment: 'production',
                    custom_url: 'https://connect.squareup.com',
-                   square_version: '2022-03-16', access_token: '',
+                   square_version: '2022-06-16', access_token: '',
                    user_agent_detail: '', additional_headers: {})
       # The Faraday connection object passed by the SDK user for making requests
       @connection = connection
 
+      # The Faraday adapter object passed by the SDK user for performing http requests
+      @adapter = adapter
+
       # The value to use for connection timeout
       @timeout = timeout
 
@@ -66,12 +70,13 @@ module Square
       @user_agent_detail = get_user_agent(user_agent_detail)
     end
 
-    def clone_with(connection: nil, timeout: nil, max_retries: nil,
-                   retry_interval: nil, backoff_factor: nil,
+    def clone_with(connection: nil, adapter: nil, timeout: nil,
+                   max_retries: nil, retry_interval: nil, backoff_factor: nil,
                    retry_statuses: nil, retry_methods: nil, environment: nil,
                    custom_url: nil, square_version: nil, access_token: nil,
                    user_agent_detail: nil, additional_headers: nil)
       connection ||= self.connection
+      adapter ||= self.adapter
       timeout ||= self.timeout
       max_retries ||= self.max_retries
       retry_interval ||= self.retry_interval
@@ -85,8 +90,8 @@ module Square
       user_agent_detail ||= self.user_agent_detail
       additional_headers ||= self.additional_headers
 
-      Configuration.new(connection: connection, timeout: timeout,
-                        max_retries: max_retries,
+      Configuration.new(connection: connection, adapter: adapter,
+                        timeout: timeout, max_retries: max_retries,
                         retry_interval: retry_interval,
                         backoff_factor: backoff_factor,
                         retry_statuses: retry_statuses,
@@ -102,7 +107,8 @@ module Square
                         retry_interval: retry_interval,
                         backoff_factor: backoff_factor,
                         retry_statuses: retry_statuses,
-                        retry_methods: retry_methods, connection: connection)
+                        retry_methods: retry_methods, connection: connection,
+                        adapter: adapter)
     end
 
     def get_user_agent(user_agent_detail)

data/lib/square/http/api_response.rb

@@ -18,16 +18,14 @@ module Square
       @request = http_response.request
       @errors = errors
 
-      if data.is_a? Hash
-        if data.keys.any?
-          @body = Struct.new(*data.keys) do
-            define_method(:to_s) { http_response.raw_body }
-          end.new(*data.values)
+      if (data.is_a? Hash) && data.keys.any?
+        @body = Struct.new(*data.keys) do
+          define_method(:to_s) { http_response.raw_body }
+        end.new(*data.values)
 
-          @cursor = data.fetch(:cursor, nil)
-          data.reject! { |k| %i[cursor errors].include?(k) }
-          @data = Struct.new(*data.keys).new(*data.values) if data.keys.any?
-        end
+        @cursor = data.fetch(:cursor, nil)
+        data.reject! { |k| %i[cursor errors].include?(k) }
+        @data = Struct.new(*data.keys).new(*data.values) if data.keys.any?
       else
         @data = data
         @body = data

data/lib/square/http/faraday_client.rb

@@ -1,5 +1,8 @@
 require 'faraday/http_cache'
-require 'faraday_middleware'
+require 'faraday/retry'
+require 'faraday/multipart'
+require 'faraday/follow_redirects'
+require 'faraday/gzip'
 
 module Square
   # An implementation of HttpClient.
@@ -10,12 +13,12 @@ module Square
     # The constructor.
     def initialize(timeout:, max_retries:, retry_interval:,
                    backoff_factor:, retry_statuses:, retry_methods:,
-                   connection: nil, cache: false, verify: true)
+                   connection:, adapter:, cache: false, verify: true)
       @connection = if connection.nil?
                       create_connection(timeout: timeout, max_retries: max_retries,
                                         retry_interval: retry_interval, backoff_factor: backoff_factor,
                                         retry_statuses: retry_statuses, retry_methods: retry_methods,
-                                        cache: cache, verify: verify)
+                                        adapter: adapter, cache: cache, verify: verify)
                     else
                       connection
                     end
@@ -24,11 +27,11 @@ module Square
     # Method to initialize connection.
     def create_connection(timeout:, max_retries:, retry_interval:,
                           backoff_factor:, retry_statuses:, retry_methods:,
-                          cache: false, verify: true)
+                          adapter:, cache: false, verify: true)
       Faraday.new do |faraday|
         faraday.use Faraday::HttpCache, serializer: Marshal if cache
-        faraday.use FaradayMiddleware::FollowRedirects
-        faraday.use :gzip
+        faraday.use Faraday::FollowRedirects::Middleware
+        faraday.request :gzip
         faraday.request :multipart
         faraday.request :url_encoded
         faraday.ssl[:ca_file] = Certifi.where
@@ -36,8 +39,11 @@ module Square
         faraday.request :retry, max: max_retries, interval: retry_interval,
                                 backoff_factor: backoff_factor,
                                 retry_statuses: retry_statuses,
-                                methods: retry_methods
-        faraday.adapter Faraday.default_adapter
+                                methods: retry_methods,
+                                retry_if: proc { |env, _exc|
+                                            env.request.context['forced_retry'] ||= false
+                                          }
+        faraday.adapter adapter
         faraday.options[:params_encoder] = Faraday::FlatParamsEncoder
         faraday.options[:timeout] = timeout if timeout.positive?
       end
@@ -49,7 +55,9 @@ module Square
         http_request.http_method.downcase,
         http_request.query_url
       ) do |request|
-        request.headers = http_request.headers
+        request.headers = http_request.headers.map { |k, v| [k.to_s, v.to_s] }
+        request.options.context ||= {}
+        request.options.context.merge!(http_request.context)
         unless http_request.http_method == HttpMethodEnum::GET &&
                http_request.parameters.empty?
           request.body = http_request.parameters
@@ -65,6 +73,8 @@ module Square
         http_request.query_url
       ) do |request|
         request.headers = http_request.headers
+        request.options.context ||= {}
+        request.options.context.merge!(http_request.context)
         unless http_request.http_method == HttpMethodEnum::GET &&
                http_request.parameters.empty?
           request.body = http_request.parameters