square.rb 17.1.0.20220120 → 19.0.0.20220420

data/lib/square/api/terminal_api.rb

@@ -41,8 +41,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 +78,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 +151,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 +189,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 +224,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/api/vendors_api.rb

@@ -0,0 +1,257 @@
+module Square
+  # VendorsApi
+  class VendorsApi < BaseApi
+    def initialize(config, http_call_back: nil)
+      super(config, http_call_back: http_call_back)
+    end
+
+    # Creates one or more [Vendor]($m/Vendor) objects to represent suppliers to
+    # a seller.
+    # @param [BulkCreateVendorsRequest] body Required parameter: An object
+    # containing the fields to POST for the request.  See the corresponding
+    # object definition for field details.
+    # @return [BulkCreateVendorsResponse Hash] response from the API call
+    def bulk_create_vendors(body:)
+      # Prepare query url.
+      _query_builder = config.get_base_uri
+      _query_builder << '/v2/vendors/bulk-create'
+      _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 one or more vendors of specified [Vendor]($m/Vendor) IDs.
+    # @param [BulkRetrieveVendorsRequest] body Required parameter: An object
+    # containing the fields to POST for the request.  See the corresponding
+    # object definition for field details.
+    # @return [BulkRetrieveVendorsResponse Hash] response from the API call
+    def bulk_retrieve_vendors(body:)
+      # Prepare query url.
+      _query_builder = config.get_base_uri
+      _query_builder << '/v2/vendors/bulk-retrieve'
+      _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
+
+    # Updates one or more of existing [Vendor]($m/Vendor) objects as suppliers
+    # to a seller.
+    # @param [BulkUpdateVendorsRequest] body Required parameter: An object
+    # containing the fields to POST for the request.  See the corresponding
+    # object definition for field details.
+    # @return [BulkUpdateVendorsResponse Hash] response from the API call
+    def bulk_update_vendors(body:)
+      # Prepare query url.
+      _query_builder = config.get_base_uri
+      _query_builder << '/v2/vendors/bulk-update'
+      _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.put(
+        _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
+
+    # Creates a single [Vendor]($m/Vendor) object to represent a supplier to a
+    # seller.
+    # @param [CreateVendorRequest] body Required parameter: An object containing
+    # the fields to POST for the request.  See the corresponding object
+    # definition for field details.
+    # @return [CreateVendorResponse Hash] response from the API call
+    def create_vendor(body:)
+      # Prepare query url.
+      _query_builder = config.get_base_uri
+      _query_builder << '/v2/vendors/create'
+      _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
+
+    # Searches for vendors using a filter against supported [Vendor]($m/Vendor)
+    # properties and a supported sorter.
+    # @param [SearchVendorsRequest] body Required parameter: An object
+    # containing the fields to POST for the request.  See the corresponding
+    # object definition for field details.
+    # @return [SearchVendorsResponse Hash] response from the API call
+    def search_vendors(body:)
+      # Prepare query url.
+      _query_builder = config.get_base_uri
+      _query_builder << '/v2/vendors/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 the vendor of a specified [Vendor]($m/Vendor) ID.
+    # @param [String] vendor_id Required parameter: ID of the
+    # [Vendor]($m/Vendor) to retrieve.
+    # @return [RetrieveVendorResponse Hash] response from the API call
+    def retrieve_vendor(vendor_id:)
+      # Prepare query url.
+      _query_builder = config.get_base_uri
+      _query_builder << '/v2/vendors/{vendor_id}'
+      _query_builder = APIHelper.append_url_with_template_parameters(
+        _query_builder,
+        'vendor_id' => { 'value' => vendor_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
+
+    # Updates an existing [Vendor]($m/Vendor) object as a supplier to a seller.
+    # @param [UpdateVendorRequest] body Required parameter: An object containing
+    # the fields to POST for the request.  See the corresponding object
+    # definition for field details.
+    # @param [String] vendor_id Required parameter: Example:
+    # @return [UpdateVendorResponse Hash] response from the API call
+    def update_vendor(body:,
+                      vendor_id:)
+      # Prepare query url.
+      _query_builder = config.get_base_uri
+      _query_builder << '/v2/vendors/{vendor_id}'
+      _query_builder = APIHelper.append_url_with_template_parameters(
+        _query_builder,
+        'vendor_id' => { 'value' => vendor_id, 'encode' => true }
+      )
+      _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.put(
+        _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
+  end
+end

data/lib/square/api_helper.rb

@@ -8,18 +8,16 @@ module Square
     def self.serialize_array(key, array, formatting: 'indexed')
       tuples = []
 
-      case formatting
-      when 'unindexed'
-        tuples += array.map { |element| ["#{key}[]", element] }
-      when 'indexed'
-        tuples += array.map.with_index do |element, index|
-          ["#{key}[#{index}]", element]
-        end
-      when 'plain'
-        tuples += array.map { |element| [key, element] }
-      else
-        raise ArgumentError, 'Invalid format provided.'
-      end
+      tuples += case formatting
+                when 'csv'
+                  [[key, array.map { |element| CGI.escape(element.to_s) }.join(',')]]
+                when 'psv'
+                  [[key, array.map { |element| CGI.escape(element.to_s) }.join('|')]]
+                when 'tsv'
+                  [[key, array.map { |element| CGI.escape(element.to_s) }.join("\t")]]
+                else
+                  array.map { |element| [key, element] }
+                end
       tuples
     end
 
@@ -75,31 +73,19 @@ module Square
       return query_builder if parameters.nil?
 
       array_serialization = 'indexed'
+      parameters = process_complex_types_parameters(parameters, array_serialization)
 
       parameters.each do |key, value|
         seperator = query_builder.include?('?') ? '&' : '?'
         unless value.nil?
           if value.instance_of? Array
             value.compact!
-            query_builder += case array_serialization
-                             when 'csv'
-                               "#{seperator}#{key}=#{value.map do |element|
-                                 CGI.escape(element.to_s)
-                               end.join(',')}"
-                             when 'psv'
-                               "#{seperator}#{key}=#{value.map do |element|
-                                 CGI.escape(element.to_s)
-                               end.join('|')}"
-                             when 'tsv'
-                               "#{seperator}#{key}=#{value.map do |element|
-                                 CGI.escape(element.to_s)
-                               end.join("\t")}"
-                             else
-                               "#{seperator}#{APIHelper.serialize_array(
-                                 key, value, formatting: array_serialization
-                               ).map { |k, v| "#{k}=#{CGI.escape(v.to_s)}" }
-                               .join('&')}"
-                             end
+            APIHelper.serialize_array(
+              key, value, formatting: array_serialization
+            ).each do |element|
+              seperator = query_builder.include?('?') ? '&' : '?'
+              query_builder += "#{seperator}#{element[0]}=#{element[1]}"
+            end
           else
             query_builder += "#{seperator}#{key}=#{CGI.escape(value.to_s)}"
           end
@@ -163,6 +149,18 @@ module Square
       encoded
     end
 
+    # Process complex types in query_params.
+    # @param [Hash] The hash of query parameters.
+    # @return [Hash] A hash with the processed query parameters.
+    def self.process_complex_types_parameters(query_parameters, array_serialization)
+      processed_params = {}
+      query_parameters.each do |key, value|
+        processed_params.merge!(APIHelper.form_encode(value, key, formatting:
+          array_serialization))
+      end
+      processed_params
+    end
+
     def self.custom_merge(a, b)
       x = {}
       a.each do |key, value_a|

data/lib/square/client.rb

@@ -4,7 +4,7 @@ module Square
     attr_reader :config
 
     def sdk_version
-      '17.1.0.20220120'
+      '19.0.0.20220420'
     end
 
     def square_version
@@ -177,6 +177,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
@@ -213,16 +219,22 @@ module Square
       @terminal ||= TerminalApi.new config
     end
 
-    def initialize(http_client_instance: nil, timeout: 60, max_retries: 0,
+    # Access to vendors controller.
+    # @return [VendorsApi] Returns the controller instance.
+    def vendors
+      @vendors ||= VendorsApi.new config
+    end
+
+    def initialize(connection: nil, 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-01-20', access_token: '',
+                   square_version: '2022-04-20', access_token: '',
                    user_agent_detail: '', additional_headers: {}, config: nil)
       @config = if config.nil?
-                  Configuration.new(http_client_instance: http_client_instance,
-                                    timeout: timeout, max_retries: max_retries,
+                  Configuration.new(connection: connection, 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, :http_client_instance, :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, :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,15 +15,15 @@ module Square
       attr_reader :environments
     end
 
-    def initialize(http_client_instance: nil, timeout: 60, max_retries: 0,
+    def initialize(connection: nil, 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-01-20', access_token: '',
+                   square_version: '2022-04-20', access_token: '',
                    user_agent_detail: '', additional_headers: {})
-      # The Http Client passed from the sdk user for making requests
-      @http_client_instance = http_client_instance
+      # The Faraday connection object passed by the SDK user for making requests
+      @connection = connection
 
       # The value to use for connection timeout
       @timeout = timeout
@@ -66,12 +66,12 @@ module Square
       @user_agent_detail = get_user_agent(user_agent_detail)
     end
 
-    def clone_with(http_client_instance: nil, timeout: nil, max_retries: nil,
+    def clone_with(connection: 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)
-      http_client_instance ||= self.http_client_instance
+      connection ||= self.connection
       timeout ||= self.timeout
       max_retries ||= self.max_retries
       retry_interval ||= self.retry_interval
@@ -85,8 +85,8 @@ module Square
       user_agent_detail ||= self.user_agent_detail
       additional_headers ||= self.additional_headers
 
-      Configuration.new(http_client_instance: http_client_instance,
-                        timeout: timeout, max_retries: max_retries,
+      Configuration.new(connection: connection, timeout: timeout,
+                        max_retries: max_retries,
                         retry_interval: retry_interval,
                         backoff_factor: backoff_factor,
                         retry_statuses: retry_statuses,
@@ -102,8 +102,7 @@ module Square
                         retry_interval: retry_interval,
                         backoff_factor: backoff_factor,
                         retry_statuses: retry_statuses,
-                        retry_methods: retry_methods,
-                        http_client_instance: http_client_instance)
+                        retry_methods: retry_methods, connection: connection)
     end
 
     def get_user_agent(user_agent_detail)

data/lib/square/http/faraday_client.rb

@@ -1,35 +1,37 @@
 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.
   class FaradayClient < HttpClient
+    # The attribute readers for properties.
+    attr_reader :connection
+
     # The constructor.
     def initialize(timeout:, max_retries:, retry_interval:,
                    backoff_factor:, retry_statuses:, retry_methods:,
-                   http_client_instance: nil, cache: false, verify: true)
-      if http_client_instance.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)
-      else
-        if http_client_instance.instance_variable_get('@connection').nil?
-          raise ArgumentError,
-                "`connection` cannot be nil in `#{self.class}`. Please specify a valid value."
-        end
-        @connection = http_client_instance.instance_variable_get('@connection')
-      end
+                   connection: nil, 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)
+                    else
+                      connection
+                    end
     end
 
     # Method to initialize connection.
     def create_connection(timeout:, max_retries:, retry_interval:,
                           backoff_factor:, retry_statuses:, retry_methods:,
                           cache: false, verify: true)
-      @connection = Faraday.new do |faraday|
+      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
@@ -37,12 +39,14 @@ module Square
         faraday.request :retry, max: max_retries, interval: retry_interval,
                                 backoff_factor: backoff_factor,
                                 retry_statuses: retry_statuses,
-                                methods: retry_methods
+                                methods: retry_methods,
+                                retry_if: proc { |env, _exc|
+                                            env.request.context['forced_retry'] ||= false
+                                          }
         faraday.adapter Faraday.default_adapter
         faraday.options[:params_encoder] = Faraday::FlatParamsEncoder
         faraday.options[:timeout] = timeout if timeout.positive?
       end
-      @connection
     end
 
     # Method overridden from HttpClient.
@@ -51,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
@@ -67,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