square.rb 8.0.0.20201216 → 26.1.0.20230119

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, :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
@@ -20,10 +15,19 @@ module Square
       attr_reader :environments
     end
 
-    def initialize(timeout: 60, max_retries: 0, retry_interval: 1,
-                   backoff_factor: 1, environment: 'production',
-                   square_version: '2020-12-16', access_token: 'TODO: Replace',
-                   additional_headers: {})
+    def initialize(connection: nil, adapter: :net_http_persistent, 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: '2023-01-19', 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
 
@@ -37,9 +41,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 +64,56 @@ 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, 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
       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, adapter: adapter,
+                        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,
+                        adapter: adapter)
+    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 +123,9 @@ module Square
       },
       'sandbox' => {
         'default' => 'https://connect.squareupsandbox.com'
+      },
+      'custom' => {
+        'default' => '{custom_url}'
       }
     }.freeze
 
@@ -95,7 +134,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/exceptions/validation_exception.rb

@@ -0,0 +1,13 @@
+module Square
+  # Class for exceptions when there is a schema validation error.
+  class ValidationException < StandardError
+    attr_reader :reason
+
+    # The constructor.
+    # @param [String] The reason for raising an exception.
+    def initialize(value, template)
+      @reason = "The value #{value} provided doesn't validate against the schema #{template}"
+      super(reason)
+    end
+  end
+end

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| k == :cursor || k == :errors }
-          @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,25 +1,52 @@
 require 'faraday/http_cache'
-require 'faraday_middleware'
+require 'faraday/retry'
+require 'faraday/multipart'
+require 'faraday/follow_redirects'
+require 'faraday/gzip'
+require 'faraday/net_http_persistent'
 
 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:, 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,
+                                        adapter: adapter, 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:,
+                          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
         faraday.ssl[:verify] = verify
         faraday.request :retry, max: max_retries, interval: retry_interval,
-                                backoff_factor: backoff_factor
-        faraday.adapter Faraday.default_adapter
+                                backoff_factor: backoff_factor,
+                                retry_statuses: retry_statuses,
+                                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 > 0
+        faraday.options[:timeout] = timeout if timeout.positive?
       end
     end
 
@@ -29,7 +56,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
@@ -45,6 +74,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

data/lib/square/http/http_client.rb

@@ -28,72 +28,91 @@ module Square
     # Get a GET HttpRequest object.
     # @param [String] The URL to send the request to.
     # @param [Hash, Optional] The headers for the HTTP Request.
+    # @param [Hash, Optional] The context for the HTTP Request.
     def get(query_url,
-            headers: {})
+            headers: {},
+            context: {})
       HttpRequest.new(HttpMethodEnum::GET,
                       query_url,
-                      headers: headers)
+                      headers: headers,
+                      context: context)
     end
 
     # Get a HEAD HttpRequest object.
     # @param [String] The URL to send the request to.
     # @param [Hash, Optional] The headers for the HTTP Request.
+    # @param [Hash, Optional] The context for the HTTP Request.
     def head(query_url,
-             headers: {})
+             headers: {},
+             context: {})
       HttpRequest.new(HttpMethodEnum::HEAD,
                       query_url,
-                      headers: headers)
+                      headers: headers,
+                      context: context)
     end
 
     # Get a POST HttpRequest object.
     # @param [String] The URL to send the request to.
     # @param [Hash, Optional] The headers for the HTTP Request.
     # @param [Hash, Optional] The parameters for the HTTP Request.
+    # @param [Hash, Optional] The context for the HTTP Request.
     def post(query_url,
              headers: {},
-             parameters: {})
+             parameters: {},
+             context: {})
       HttpRequest.new(HttpMethodEnum::POST,
                       query_url,
                       headers: headers,
-                      parameters: parameters)
+                      parameters: parameters,
+                      context: context)
     end
 
     # Get a PUT HttpRequest object.
     # @param [String] The URL to send the request to.
     # @param [Hash, Optional] The headers for the HTTP Request.
     # @param [Hash, Optional] The parameters for the HTTP Request.
+    # @param [Hash, Optional] The context for the HTTP Request.
     def put(query_url,
             headers: {},
-            parameters: {})
+            parameters: {},
+            context: {})
       HttpRequest.new(HttpMethodEnum::PUT,
                       query_url,
                       headers: headers,
-                      parameters: parameters)
+                      parameters: parameters,
+                      context: context)
     end
 
     # Get a PATCH HttpRequest object.
     # @param [String] The URL to send the request to.
     # @param [Hash, Optional] The headers for the HTTP Request.
     # @param [Hash, Optional] The parameters for the HTTP Request.
+    # @param [Hash, Optional] The context for the HTTP Request.
     def patch(query_url,
               headers: {},
-              parameters: {})
+              parameters: {},
+              context: {})
       HttpRequest.new(HttpMethodEnum::PATCH,
                       query_url,
                       headers: headers,
-                      parameters: parameters)
+                      parameters: parameters,
+                      context: context)
     end
 
     # Get a DELETE HttpRequest object.
     # @param [String] The URL to send the request to.
     # @param [Hash, Optional] The headers for the HTTP Request.
+    # @param [Hash, Optional] The parameters for the HTTP Request.
+    # @param [Hash, Optional] The context for the HTTP Request.
     def delete(query_url,
                headers: {},
-               parameters: {})
+               parameters: nil,
+               context: {})
       HttpRequest.new(HttpMethodEnum::DELETE,
                       query_url,
                       headers: headers,
-                      parameters: parameters)
+                      parameters: parameters,
+                      context: context)
     end
   end
 end

data/lib/square/http/http_request.rb

@@ -2,21 +2,25 @@ module Square
   # Represents a single Http Request.
   class HttpRequest
     attr_accessor :http_method, :query_url, :headers,
-                  :parameters, :username, :password
+                  :parameters, :username, :password,
+                  :context
 
     # The constructor.
     # @param [HttpMethodEnum] The HTTP method.
     # @param [String] The URL to send the request to.
     # @param [Hash, Optional] The headers for the HTTP Request.
     # @param [Hash, Optional] The parameters for the HTTP Request.
+    # @param [Hash, Optional] The context for the HTTP Request.
     def initialize(http_method,
                    query_url,
                    headers: {},
-                   parameters: {})
+                   parameters: {},
+                   context: {})
       @http_method = http_method
       @query_url = query_url
       @headers = headers
       @parameters = parameters
+      @context = context
     end
 
     # Add a header to the HttpRequest.

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

data/lib/square/utilities/file_wrapper.rb

@@ -1,8 +1,7 @@
 module Square
   # A utility to allow users to set the content-type for files
   class FileWrapper
-    attr_reader :content_type
-    attr_reader :file
+    attr_reader :content_type, :file
 
     def initialize(file, content_type: 'application/octet-stream')
       @file = file