square.rb 8.1.0.20210121 → 18.1.0.20220316

data/lib/square/api_helper.rb

@@ -8,17 +8,16 @@ module Square
     def self.serialize_array(key, array, formatting: 'indexed')
       tuples = []
 
-      if formatting == 'unindexed'
-        tuples += array.map { |element| ["#{key}[]", element] }
-      elsif formatting == 'indexed'
-        tuples += array.map.with_index do |element, index|
-          ["#{key}[#{index}]", element]
-        end
-      elsif formatting == '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
 
@@ -55,7 +54,7 @@ module Square
         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
@@ -63,9 +62,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\"
@@ -75,29 +72,20 @@ module Square
       # Return if there are no parameters to replace.
       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 += if array_serialization == 'csv'
-                               "#{seperator}#{key}=#{value.map do |element|
-                                 CGI.escape(element.to_s)
-                               end.join(',')}"
-                             elsif array_serialization == 'psv'
-                               "#{seperator}#{key}=#{value.map do |element|
-                                 CGI.escape(element.to_s)
-                               end.join('|')}"
-                             elsif array_serialization == '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
@@ -114,7 +102,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.
@@ -125,7 +113,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] : ''
@@ -137,7 +125,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
@@ -151,8 +139,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,11 +149,24 @@ 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|
         b.each do |k, value_b|
           next unless key == k
+
           x[k] = []
           if value_a.instance_of? Array
             value_a.each do |v|
@@ -207,13 +208,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,
@@ -223,14 +223,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(
@@ -265,17 +265,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
-      '8.1.0.20210121'
+      '18.1.0.20220316'
     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,24 +27,12 @@ module Square
       @o_auth ||= OAuthApi.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 +51,12 @@ module Square
       @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,31 @@ module Square
       @terminal ||= TerminalApi.new config
     end
 
-    def initialize(timeout: 60, max_retries: 0, retry_interval: 1,
-                   backoff_factor: 1, environment: 'production',
-                   square_version: '2021-01-21', access_token: 'TODO: Replace',
-                   additional_headers: {}, config: nil)
+    # 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-03-16', access_token: '',
+                   user_agent_detail: '', additional_headers: {}, config: nil)
       @config = if config.nil?
-                  Configuration.new(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,
+                                    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, :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
@@ -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: '2021-01-21', access_token: 'TODO: Replace',
-                   additional_headers: {})
+    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-03-16', access_token: '',
+                   user_agent_detail: '', additional_headers: {})
+      # The Faraday connection object passed by the SDK user for making requests
+      @connection = connection
+
       # The value to use for connection timeout
       @timeout = timeout
 
@@ -37,9 +38,18 @@ 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
 
@@ -51,33 +61,54 @@ 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(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)
+      connection ||= self.connection
       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(connection: connection, 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, connection: connection)
+    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 +118,9 @@ module Square
       },
       'sandbox' => {
         'default' => 'https://connect.squareupsandbox.com'
+      },
+      'custom' => {
+        'default' => '{custom_url}'
       }
     }.freeze
 
@@ -95,7 +129,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

data/lib/square/http/faraday_client.rb

@@ -4,10 +4,28 @@ require 'faraday_middleware'
 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:, cache: false, verify: true)
-      @connection = Faraday.new do |faraday|
+                   backoff_factor:, retry_statuses:, retry_methods:,
+                   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)
+      Faraday.new do |faraday|
         faraday.use Faraday::HttpCache, serializer: Marshal if cache
         faraday.use FaradayMiddleware::FollowRedirects
         faraday.use :gzip
@@ -16,10 +34,12 @@ module Square
         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
     end
 

data/lib/square/utilities/date_time_helper.rb

@@ -0,0 +1,151 @@
+require 'date'
+module Square
+  # A utility  that supports dateTime conversion to different formats
+  class DateTimeHelper
+    # Safely converts a DateTime object into a rfc1123 format string
+    # @param [DateTime] The DateTime object
+    # @return [String] The rfc1123 formatted datetime string
+    def self.to_rfc1123(date_time)
+      date_time&.httpdate
+    end
+
+    # Safely converts a map of DateTime objects into a map of rfc1123 format string
+    # @param [hash] a map of DateTime objects
+    # @return [hash] a map of rfc1123 formatted datetime string
+    def self.to_rfc1123_map(date_time, hash, key)
+      return if date_time.nil?
+
+      hash[key] = {}
+      date_time.each do |k, v|
+        hash[key][k] =
+          if v.is_a?(BaseModel)
+            v.to_hash
+          else
+            v.is_a?(DateTime) ? DateTimeHelper.to_rfc1123(v) : v
+          end
+      end
+      hash[key]
+    end
+
+    # Safely converts an array of DateTime objects into an array of rfc1123 format string
+    # @param [Array] an array of DateTime objects
+    # @return [Array] an array of rfc1123 formatted datetime string
+    def self.to_rfc1123_array(date_time, hash, key)
+      return if date_time.nil?
+
+      hash[key] = date_time.map do |v|
+        if v.is_a?(BaseModel)
+          v.to_hash
+        else
+          v.is_a?(DateTime) ? DateTimeHelper.to_rfc1123(v) : v
+        end
+      end
+    end
+
+    # Safely converts a DateTime object into a unix format string
+    # @param [DateTime] The DateTime object
+    # @return [String] The unix formatted datetime string
+    def self.to_unix(date_time)
+      date_time.to_time.utc.to_i unless date_time.nil?
+    end
+
+    # Safely converts a map of DateTime objects into a map of unix format string
+    # @param [hash] a map of DateTime objects
+    # @return [hash] a map of unix formatted datetime string
+    def self.to_unix_map(date_time, hash, key)
+      return if date_time.nil?
+
+      hash[key] = {}
+      date_time.each do |k, v|
+        hash[key][k] =
+          if v.is_a?(BaseModel)
+            v.to_hash
+          else
+            v.is_a?(DateTime) ? DateTimeHelper.to_unix(v) : v
+          end
+      end
+      hash[key]
+    end
+
+    # Safely converts an array of DateTime objects into a map of unix format string
+    # @param [hash] an array of DateTime objects
+    # @return [hash] an array of unix formatted datetime string
+    def self.to_unix_array(date_time, hash, key)
+      return if date_time.nil?
+
+      hash[key] = date_time.map do |v|
+        if v.is_a?(BaseModel)
+          v.to_hash
+        else
+          v.is_a?(DateTime) ? DateTimeHelper.to_unix(v) : v
+        end
+      end
+    end
+
+    # Safely converts a DateTime object into a rfc3339 format string
+    # @param [DateTime] The DateTime object
+    # @return [String] The rfc3339 formatted datetime string
+    def self.to_rfc3339(date_time)
+      date_time&.rfc3339
+    end
+
+    # Safely converts a map of DateTime objects into a map of rfc1123 format string
+    # @param [hash] a map of DateTime objects
+    # @return [hash] a map of rfc1123 formatted datetime string
+    def self.to_rfc3339_map(date_time, hash, key)
+      return if date_time.nil?
+
+      hash[key] = {}
+      date_time.each do |k, v|
+        hash[key][k] =
+          if v.is_a?(BaseModel)
+            v.to_hash
+          else
+            v.is_a?(DateTime) ? DateTimeHelper.to_rfc3339(v) : v
+          end
+      end
+      hash[key]
+    end
+
+    # Safely converts an array of DateTime objects into an array of rfc1123 format string
+    # @param [Array] an array of DateTime objects
+    # @return [Array] an array of rfc1123 formatted datetime string
+    def self.to_rfc3339_array(date_time, hash, key)
+      return if date_time.nil?
+
+      hash[key] = date_time.map do |v|
+        if v.is_a?(BaseModel)
+          v.to_hash
+        else
+          v.is_a?(DateTime) ? DateTimeHelper.to_rfc3339(v) : v
+        end
+      end
+    end
+
+    # Safely converts a rfc1123 format string into a DateTime object
+    # @param [String] The rfc1123 formatted datetime string
+    # @return [DateTime] A DateTime object
+    def self.from_rfc1123(date_time)
+      DateTime.httpdate(date_time)
+    end
+
+    # Safely converts a unix format string into a DateTime object
+    # @param [String] The unix formatted datetime string
+    # @return [DateTime] A DateTime object
+    def self.from_unix(date_time)
+      Time.at(date_time.to_i).utc.to_datetime
+    end
+
+    # Safely converts a rfc3339 format string into a DateTime object
+    # @param [String] The rfc3339 formatted datetime string
+    # @return [DateTime] A DateTime object
+    def self.from_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