square.rb 6.3.0.20200826 → 17.1.0.20220120

data/lib/square/api_helper.rb

@@ -8,13 +8,14 @@ module Square
     def self.serialize_array(key, array, formatting: 'indexed')
       tuples = []
 
-      if formatting == 'unindexed'
+      case formatting
+      when 'unindexed'
         tuples += array.map { |element| ["#{key}[]", element] }
-      elsif formatting == 'indexed'
+      when 'indexed'
         tuples += array.map.with_index do |element, index|
           ["#{key}[#{index}]", element]
         end
-      elsif formatting == 'plain'
+      when 'plain'
         tuples += array.map { |element| [key, element] }
       else
         raise ArgumentError, 'Invalid format provided.'
@@ -36,21 +37,26 @@ module Square
       # Return if there are no parameters to replace.
       return query_builder if parameters.nil?
 
-      # Iterate and append parameters.
-      parameters.each do |key, value|
-        replace_value = ''
-
-        if value.nil?
+      parameters.each do |key, val|
+        if val.nil?
           replace_value = ''
-        elsif value.instance_of? Array
-          value.map! { |element| CGI.escape(element.to_s) }
-          replace_value = value.join('/')
+        elsif val['value'].instance_of? Array
+          if val['encode'] == true
+            val['value'].map! { |element| CGI.escape(element.to_s) }
+          else
+            val['value'].map!(&:to_s)
+          end
+          replace_value = val['value'].join('/')
         else
-          replace_value = CGI.escape(value.to_s)
+          replace_value = if val['encode'] == true
+                            CGI.escape(val['value'].to_s)
+                          else
+                            val['value'].to_s
+                          end
         end
 
         # Find the template parameter and replace it with its value.
-        query_builder = query_builder.gsub('{' + key.to_s + '}', replace_value)
+        query_builder = query_builder.gsub("{#{key}}", replace_value)
       end
       query_builder
     end
@@ -58,9 +64,7 @@ module Square
     # Appends the given set of parameters to the given query string.
     # @param [String] The query string builder to add the query parameters to.
     # @param [Hash] The parameters to append.
-    # @param [String] The format of array parameter serialization.
-    def self.append_url_with_query_parameters(query_builder, parameters,
-                                              array_serialization: 'indexed')
+    def self.append_url_with_query_parameters(query_builder, parameters)
       # Perform parameter validation.
       unless query_builder.instance_of? String
         raise ArgumentError, 'Given value for parameter \"query_builder\"
@@ -70,20 +74,23 @@ module Square
       # Return if there are no parameters to replace.
       return query_builder if parameters.nil?
 
+      array_serialization = 'indexed'
+
       parameters.each do |key, value|
         seperator = query_builder.include?('?') ? '&' : '?'
         unless value.nil?
           if value.instance_of? Array
             value.compact!
-            query_builder += if array_serialization == 'csv'
+            query_builder += case array_serialization
+                             when 'csv'
                                "#{seperator}#{key}=#{value.map do |element|
                                  CGI.escape(element.to_s)
                                end.join(',')}"
-                             elsif array_serialization == 'psv'
+                             when 'psv'
                                "#{seperator}#{key}=#{value.map do |element|
                                  CGI.escape(element.to_s)
                                end.join('|')}"
-                             elsif array_serialization == 'tsv'
+                             when 'tsv'
                                "#{seperator}#{key}=#{value.map do |element|
                                  CGI.escape(element.to_s)
                                end.join("\t")}"
@@ -109,7 +116,7 @@ module Square
       raise ArgumentError, 'Invalid Url.' unless url.instance_of? String
 
       # Ensure that the urls are absolute.
-      matches = url.match(%r{^(https?:\/\/[^\/]+)})
+      matches = url.match(%r{^(https?://[^/]+)})
       raise ArgumentError, 'Invalid Url format.' if matches.nil?
 
       # Get the http protocol match.
@@ -120,7 +127,7 @@ module Square
 
       # Remove redundant forward slashes.
       query = url[protocol.length...(!index.nil? ? index : url.length)]
-      query.gsub!(%r{\/\/+}, '/')
+      query.gsub!(%r{//+}, '/')
 
       # Get the parameters.
       parameters = !index.nil? ? url[url.index('?')...url.length] : ''
@@ -132,7 +139,7 @@ module Square
     # Parses JSON string.
     # @param [String] A JSON string.
     def self.json_deserialize(json)
-      return JSON.parse(json, symbolize_names: true)
+      JSON.parse(json, symbolize_names: true)
     rescue StandardError
       raise TypeError, 'Server responded with invalid JSON.'
     end
@@ -146,8 +153,8 @@ module Square
     # Form encodes a hash of parameters.
     # @param [Hash] The hash of parameters to encode.
     # @return [Hash] A hash with the same parameters form encoded.
-    def self.form_encode_parameters(form_parameters,
-                                    array_serialization: 'indexed')
+    def self.form_encode_parameters(form_parameters)
+      array_serialization = 'indexed'
       encoded = {}
       form_parameters.each do |key, value|
         encoded.merge!(APIHelper.form_encode(value, key, formatting:
@@ -161,6 +168,7 @@ module Square
       a.each do |key, value_a|
         b.each do |k, value_b|
           next unless key == k
+
           x[k] = []
           if value_a.instance_of? Array
             value_a.each do |v|
@@ -202,13 +210,12 @@ module Square
       elsif obj.instance_of? Array
         if formatting == 'indexed'
           obj.each_with_index do |value, index|
-            retval.merge!(APIHelper.form_encode(value, instance_name + '[' +
-              index.to_s + ']'))
+            retval.merge!(APIHelper.form_encode(value, "#{instance_name}[#{index}]"))
           end
         elsif serializable_types.map { |x| obj[0].is_a? x }.any?
           obj.each do |value|
             abc = if formatting == 'unindexed'
-                    APIHelper.form_encode(value, instance_name + '[]',
+                    APIHelper.form_encode(value, "#{instance_name}[]",
                                           formatting: formatting)
                   else
                     APIHelper.form_encode(value, instance_name,
@@ -218,14 +225,14 @@ module Square
           end
         else
           obj.each_with_index do |value, index|
-            retval.merge!(APIHelper.form_encode(value, instance_name + '[' +
-              index.to_s + ']', formatting: formatting))
+            retval.merge!(APIHelper.form_encode(value, "#{instance_name}[#{index}]",
+                                                formatting: formatting))
           end
         end
       elsif obj.instance_of? Hash
         obj.each do |key, value|
-          retval.merge!(APIHelper.form_encode(value, instance_name + '[' +
-            key.to_s + ']', formatting: formatting))
+          retval.merge!(APIHelper.form_encode(value, "#{instance_name}[#{key}]",
+                                              formatting: formatting))
         end
       elsif obj.instance_of? File
         retval[instance_name] = UploadIO.new(
@@ -260,17 +267,5 @@ module Square
       end
       val
     end
-
-    # Safely converts a string into an rfc3339 DateTime object
-    # @param [String] The datetime string
-    # @return [DateTime] A DateTime object of rfc3339 format
-    def self.rfc3339(date_time)
-      # missing timezone information
-      if date_time.end_with?('Z') || date_time.index('+')
-        DateTime.rfc3339(date_time)
-      else
-        DateTime.rfc3339(date_time + 'Z')
-      end
-    end
   end
 end

data/lib/square/client.rb

@@ -4,13 +4,17 @@ module Square
     attr_reader :config
 
     def sdk_version
-      '6.3.0.20200826'
+      '17.1.0.20220120'
     end
 
     def square_version
       config.square_version
     end
 
+    def user_agent_detail
+      config.user_agent_detail
+    end
+
     # Access to mobile_authorization controller.
     # @return [MobileAuthorizationApi] Returns the controller instance.
     def mobile_authorization
@@ -23,30 +27,12 @@ module Square
       @o_auth ||= OAuthApi.new config
     end
 
-    # Access to v1_locations controller.
-    # @return [V1LocationsApi] Returns the controller instance.
-    def v1_locations
-      @v1_locations ||= V1LocationsApi.new config
-    end
-
-    # Access to v1_employees controller.
-    # @return [V1EmployeesApi] Returns the controller instance.
-    def v1_employees
-      @v1_employees ||= V1EmployeesApi.new config
-    end
-
     # Access to v1_transactions controller.
     # @return [V1TransactionsApi] Returns the controller instance.
     def v1_transactions
       @v1_transactions ||= V1TransactionsApi.new config
     end
 
-    # Access to v1_items controller.
-    # @return [V1ItemsApi] Returns the controller instance.
-    def v1_items
-      @v1_items ||= V1ItemsApi.new config
-    end
-
     # Access to apple_pay controller.
     # @return [ApplePayApi] Returns the controller instance.
     def apple_pay
@@ -59,6 +45,18 @@ module Square
       @bank_accounts ||= BankAccountsApi.new config
     end
 
+    # Access to bookings controller.
+    # @return [BookingsApi] Returns the controller instance.
+    def bookings
+      @bookings ||= BookingsApi.new config
+    end
+
+    # Access to cards controller.
+    # @return [CardsApi] Returns the controller instance.
+    def cards
+      @cards ||= CardsApi.new config
+    end
+
     # Access to cash_drawers controller.
     # @return [CashDrawersApi] Returns the controller instance.
     def cash_drawers
@@ -107,6 +105,18 @@ module Square
       @employees ||= EmployeesApi.new config
     end
 
+    # Access to gift_cards controller.
+    # @return [GiftCardsApi] Returns the controller instance.
+    def gift_cards
+      @gift_cards ||= GiftCardsApi.new config
+    end
+
+    # Access to gift_card_activities controller.
+    # @return [GiftCardActivitiesApi] Returns the controller instance.
+    def gift_card_activities
+      @gift_card_activities ||= GiftCardActivitiesApi.new config
+    end
+
     # Access to inventory controller.
     # @return [InventoryApi] Returns the controller instance.
     def inventory
@@ -173,6 +183,18 @@ module Square
       @refunds ||= RefundsApi.new config
     end
 
+    # Access to sites controller.
+    # @return [SitesApi] Returns the controller instance.
+    def sites
+      @sites ||= SitesApi.new config
+    end
+
+    # Access to snippets controller.
+    # @return [SnippetsApi] Returns the controller instance.
+    def snippets
+      @snippets ||= SnippetsApi.new config
+    end
+
     # Access to subscriptions controller.
     # @return [SubscriptionsApi] Returns the controller instance.
     def subscriptions
@@ -191,17 +213,25 @@ module Square
       @terminal ||= TerminalApi.new config
     end
 
-    def initialize(timeout: 60, max_retries: 0, retry_interval: 1,
-                   backoff_factor: 1, environment: 'production',
-                   square_version: '2020-08-26', access_token: 'TODO: Replace',
-                   additional_headers: {}, config: nil)
+    def initialize(http_client_instance: 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: '',
+                   user_agent_detail: '', additional_headers: {}, config: nil)
       @config = if config.nil?
-                  Configuration.new(timeout: timeout, max_retries: max_retries,
+                  Configuration.new(http_client_instance: http_client_instance,
+                                    timeout: timeout, max_retries: max_retries,
                                     retry_interval: retry_interval,
                                     backoff_factor: backoff_factor,
+                                    retry_statuses: retry_statuses,
+                                    retry_methods: retry_methods,
                                     environment: environment,
+                                    custom_url: custom_url,
                                     square_version: square_version,
                                     access_token: access_token,
+                                    user_agent_detail: user_agent_detail,
                                     additional_headers: additional_headers)
                 else
                   config

data/lib/square/configuration.rb

@@ -3,14 +3,9 @@ module Square
   # are configured in this class.
   class Configuration
     # The attribute readers for properties.
-    attr_reader :http_client
-    attr_reader :timeout
-    attr_reader :max_retries
-    attr_reader :retry_interval
-    attr_reader :backoff_factor
-    attr_reader :environment
-    attr_reader :square_version
-    attr_reader :access_token
+    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
 
     def additional_headers
       @additional_headers.clone
@@ -20,10 +15,16 @@ module Square
       attr_reader :environments
     end
 
-    def initialize(timeout: 60, max_retries: 0, retry_interval: 1,
-                   backoff_factor: 1, environment: 'production',
-                   square_version: '2020-08-26', access_token: 'TODO: Replace',
-                   additional_headers: {})
+    def initialize(http_client_instance: 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: '',
+                   user_agent_detail: '', additional_headers: {})
+      # The Http Client passed from the sdk user for making requests
+      @http_client_instance = http_client_instance
+
       # The value to use for connection timeout
       @timeout = timeout
 
@@ -37,13 +38,22 @@ module Square
       # by in order to provide backoff
       @backoff_factor = backoff_factor
 
+      # A list of HTTP statuses to retry
+      @retry_statuses = retry_statuses
+
+      # A list of HTTP methods to retry
+      @retry_methods = retry_methods
+
       # Current API environment
       @environment = String(environment)
 
+      # Sets the base URL requests are made to. Defaults to `https://connect.squareup.com`
+      @custom_url = custom_url
+
       # Square Connect API versions
       @square_version = square_version
 
-      # OAuth 2.0 Access Token
+      # The OAuth 2.0 Access Token to use for API requests.
       @access_token = access_token
 
       # Additional headers to add to each API request
@@ -51,33 +61,55 @@ module Square
 
       # The Http Client to use for making requests.
       @http_client = create_http_client
+
+      # User agent detail, to be appended with user-agent header.
+      @user_agent_detail = get_user_agent(user_agent_detail)
     end
 
-    def clone_with(timeout: nil, max_retries: nil, retry_interval: nil,
-                   backoff_factor: nil, environment: nil, square_version: nil,
-                   access_token: nil, additional_headers: nil)
+    def clone_with(http_client_instance: 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
       timeout ||= self.timeout
       max_retries ||= self.max_retries
       retry_interval ||= self.retry_interval
       backoff_factor ||= self.backoff_factor
+      retry_statuses ||= self.retry_statuses
+      retry_methods ||= self.retry_methods
       environment ||= self.environment
+      custom_url ||= self.custom_url
       square_version ||= self.square_version
       access_token ||= self.access_token
+      user_agent_detail ||= self.user_agent_detail
       additional_headers ||= self.additional_headers
 
-      Configuration.new(timeout: timeout, max_retries: max_retries,
+      Configuration.new(http_client_instance: http_client_instance,
+                        timeout: timeout, max_retries: max_retries,
                         retry_interval: retry_interval,
                         backoff_factor: backoff_factor,
-                        environment: environment,
-                        square_version: square_version,
+                        retry_statuses: retry_statuses,
+                        retry_methods: retry_methods, environment: environment,
+                        custom_url: custom_url, square_version: square_version,
                         access_token: access_token,
+                        user_agent_detail: user_agent_detail,
                         additional_headers: additional_headers)
     end
 
     def create_http_client
       FaradayClient.new(timeout: timeout, max_retries: max_retries,
                         retry_interval: retry_interval,
-                        backoff_factor: backoff_factor)
+                        backoff_factor: backoff_factor,
+                        retry_statuses: retry_statuses,
+                        retry_methods: retry_methods,
+                        http_client_instance: http_client_instance)
+    end
+
+    def get_user_agent(user_agent_detail)
+      raise ArgumentError, 'The length of user-agent detail should not exceed 128 characters.' unless user_agent_detail.length < 128
+
+      user_agent_detail
     end
 
     # All the environments the SDK can run in.
@@ -87,6 +119,9 @@ module Square
       },
       'sandbox' => {
         'default' => 'https://connect.squareupsandbox.com'
+      },
+      'custom' => {
+        'default' => '{custom_url}'
       }
     }.freeze
 
@@ -95,7 +130,12 @@ module Square
     # required.
     # @return [String] The base URI.
     def get_base_uri(server = 'default')
-      ENVIRONMENTS[environment][server].clone
+      parameters = {
+        'custom_url' => { 'value' => custom_url, 'encode' => false }
+      }
+      APIHelper.append_url_with_template_parameters(
+        ENVIRONMENTS[environment][server], parameters
+      )
     end
   end
 end

data/lib/square/http/api_response.rb

@@ -25,7 +25,7 @@ module Square
           end.new(*data.values)
 
           @cursor = data.fetch(:cursor, nil)
-          data.reject! { |k| k == :cursor || k == :errors }
+          data.reject! { |k| %i[cursor errors].include?(k) }
           @data = Struct.new(*data.keys).new(*data.values) if data.keys.any?
         end
       else
@@ -34,10 +34,12 @@ module Square
       end
     end
 
+    # returns true if status_code is between 200-300
     def success?
       status_code >= 200 && status_code < 300
     end
 
+    # returns true if status_code is between 400-600
     def error?
       status_code >= 400 && status_code < 600
     end

data/lib/square/http/faraday_client.rb

@@ -6,20 +6,43 @@ module Square
   class FaradayClient < HttpClient
     # The constructor.
     def initialize(timeout:, max_retries:, retry_interval:,
-                   backoff_factor:, cache: false, verify: true)
+                   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
+    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.use Faraday::HttpCache, serializer: Marshal if cache
         faraday.use FaradayMiddleware::FollowRedirects
+        faraday.use :gzip
         faraday.request :multipart
         faraday.request :url_encoded
         faraday.ssl[:ca_file] = Certifi.where
         faraday.ssl[:verify] = verify
         faraday.request :retry, max: max_retries, interval: retry_interval,
-                                backoff_factor: backoff_factor
+                                backoff_factor: backoff_factor,
+                                retry_statuses: retry_statuses,
+                                methods: retry_methods
         faraday.adapter Faraday.default_adapter
         faraday.options[:params_encoder] = Faraday::FlatParamsEncoder
-        faraday.options[:timeout] = timeout if timeout > 0
+        faraday.options[:timeout] = timeout if timeout.positive?
       end
+      @connection
     end
 
     # Method overridden from HttpClient.
@@ -29,7 +52,10 @@ module Square
         http_request.query_url
       ) do |request|
         request.headers = http_request.headers
-        request.body = http_request.parameters
+        unless http_request.http_method == HttpMethodEnum::GET &&
+               http_request.parameters.empty?
+          request.body = http_request.parameters
+        end
       end
       convert_response(response, http_request)
     end
@@ -41,7 +67,10 @@ module Square
         http_request.query_url
       ) do |request|
         request.headers = http_request.headers
-        request.body = http_request.parameters
+        unless http_request.http_method == HttpMethodEnum::GET &&
+               http_request.parameters.empty?
+          request.body = http_request.parameters
+        end
       end
       convert_response(response, http_request)
     end