square.rb 3.3.0.20191217

data/lib/square/api_helper.rb

@@ -0,0 +1,276 @@
+module Square
+  # API utility class
+  class APIHelper
+    # Serializes an array parameter (creates key value pairs).
+    # @param [String] The name of the parameter.
+    # @param [Array] The value of the parameter.
+    # @param [String] The format of the serialization.
+    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
+    end
+
+    # Replaces template parameters in the given url.
+    # @param [String] The query string builder to replace the template
+    # parameters.
+    # @param [Hash] The parameters to replace in the url.
+    def self.append_url_with_template_parameters(query_builder, parameters)
+      # perform parameter validation
+      unless query_builder.instance_of? String
+        raise ArgumentError, 'Given value for parameter \"query_builder\" is
+          invalid.'
+      end
+
+      # 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?
+          replace_value = ''
+        elsif value.instance_of? Array
+          value.map! { |element| CGI.escape(element.to_s) }
+          replace_value = value.join('/')
+        else
+          replace_value = CGI.escape(value.to_s)
+        end
+
+        # Find the template parameter and replace it with its value.
+        query_builder = query_builder.gsub('{' + key.to_s + '}', replace_value)
+      end
+      query_builder
+    end
+
+    # 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')
+      # Perform parameter validation.
+      unless query_builder.instance_of? String
+        raise ArgumentError, 'Given value for parameter \"query_builder\"
+          is invalid.'
+      end
+
+      # Return if there are no parameters to replace.
+      return query_builder if parameters.nil?
+
+      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
+          else
+            query_builder += "#{seperator}#{key}=#{CGI.escape(value.to_s)}"
+          end
+        end
+      end
+      query_builder
+    end
+
+    # Validates and processes the given Url.
+    # @param [String] The given Url to process.
+    # @return [String] Pre-processed Url as string.
+    def self.clean_url(url)
+      # Perform parameter validation.
+      raise ArgumentError, 'Invalid Url.' unless url.instance_of? String
+
+      # Ensure that the urls are absolute.
+      matches = url.match(%r{^(https?:\/\/[^\/]+)})
+      raise ArgumentError, 'Invalid Url format.' if matches.nil?
+
+      # Get the http protocol match.
+      protocol = matches[1]
+
+      # Check if parameters exist.
+      index = url.index('?')
+
+      # Remove redundant forward slashes.
+      query = url[protocol.length...(!index.nil? ? index : url.length)]
+      query.gsub!(%r{\/\/+}, '/')
+
+      # Get the parameters.
+      parameters = !index.nil? ? url[url.index('?')...url.length] : ''
+
+      # Return processed url.
+      protocol + query + parameters
+    end
+
+    # Parses JSON string.
+    # @param [String] A JSON string.
+    def self.json_deserialize(json)
+      return JSON.parse(json, symbolize_names: true)
+    rescue StandardError
+      raise TypeError, 'Server responded with invalid JSON.'
+    end
+
+    # Removes elements with empty values from a hash.
+    # @param [Hash] The hash to clean.
+    def self.clean_hash(hash)
+      hash.delete_if { |_key, value| value.to_s.strip.empty? }
+    end
+
+    # 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')
+      encoded = {}
+      form_parameters.each do |key, value|
+        encoded.merge!(APIHelper.form_encode(value, key, formatting:
+          array_serialization))
+      end
+      encoded
+    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|
+              x[k].push(v)
+            end
+          else
+            x[k].push(value_a)
+          end
+          if value_b.instance_of? Array
+            value_b.each do |v|
+              x[k].push(v)
+            end
+          else
+            x[k].push(value_b)
+          end
+          a.delete(k)
+          b.delete(k)
+        end
+      end
+      x.merge!(a)
+      x.merge!(b)
+      x
+    end
+
+    # Form encodes an object.
+    # @param [Dynamic] An object to form encode.
+    # @param [String] The name of the object.
+    # @return [Hash] A form encoded representation of the object in the form
+    # of a hash.
+    def self.form_encode(obj, instance_name, formatting: 'indexed')
+      retval = {}
+
+      serializable_types = [String, Numeric, TrueClass,
+                            FalseClass, Date, DateTime]
+
+      # Create a form encoded hash for this object.
+      if obj.nil?
+        nil
+      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 + ']'))
+          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 + '[]',
+                                          formatting: formatting)
+                  else
+                    APIHelper.form_encode(value, instance_name,
+                                          formatting: formatting)
+                  end
+            retval = APIHelper.custom_merge(retval, abc)
+          end
+        else
+          obj.each_with_index do |value, index|
+            retval.merge!(APIHelper.form_encode(value, instance_name + '[' +
+              index.to_s + ']', 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))
+        end
+      elsif obj.instance_of? File
+        retval[instance_name] = UploadIO.new(
+          obj, 'application/octet-stream', File.basename(obj.path)
+        )
+      else
+        retval[instance_name] = obj
+      end
+      retval
+    end
+
+    # Retrieves a field from a Hash/Array based on an Array of keys/indexes
+    # @param [Hash, Array] The hash to extract data from
+    # @param [Array<String, Integer>] The keys/indexes to use
+    # @return [Object] The extracted value
+    def self.map_response(obj, keys)
+      val = obj
+      begin
+        keys.each do |key|
+          val = if val.is_a? Array
+                  if key.to_i.to_s == key
+                    val[key.to_i]
+                  else
+                    val = nil
+                  end
+                else
+                  val.fetch(key.to_sym)
+                end
+        end
+      rescue NoMethodError, TypeError, IndexError
+        val = nil
+      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

@@ -0,0 +1,156 @@
+module Square
+  #  square client class.
+  class Client
+    attr_reader :config
+
+    def sdk_version
+      '3.3.0.20191217'
+    end
+
+    def square_version
+      '2019-12-17'
+    end
+
+    # Access to mobile_authorization controller.
+    # @return [MobileAuthorizationApi] Returns the controller instance.
+    def mobile_authorization
+      @mobile_authorization ||= MobileAuthorizationApi.new config
+    end
+
+    # Access to o_auth controller.
+    # @return [OAuthApi] Returns the controller instance.
+    def o_auth
+      @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
+      @apple_pay ||= ApplePayApi.new config
+    end
+
+    # Access to cash_drawers controller.
+    # @return [CashDrawersApi] Returns the controller instance.
+    def cash_drawers
+      @cash_drawers ||= CashDrawersApi.new config
+    end
+
+    # Access to catalog controller.
+    # @return [CatalogApi] Returns the controller instance.
+    def catalog
+      @catalog ||= CatalogApi.new config
+    end
+
+    # Access to customers controller.
+    # @return [CustomersApi] Returns the controller instance.
+    def customers
+      @customers ||= CustomersApi.new config
+    end
+
+    # Access to employees controller.
+    # @return [EmployeesApi] Returns the controller instance.
+    def employees
+      @employees ||= EmployeesApi.new config
+    end
+
+    # Access to inventory controller.
+    # @return [InventoryApi] Returns the controller instance.
+    def inventory
+      @inventory ||= InventoryApi.new config
+    end
+
+    # Access to labor controller.
+    # @return [LaborApi] Returns the controller instance.
+    def labor
+      @labor ||= LaborApi.new config
+    end
+
+    # Access to locations controller.
+    # @return [LocationsApi] Returns the controller instance.
+    def locations
+      @locations ||= LocationsApi.new config
+    end
+
+    # Access to reporting controller.
+    # @return [ReportingApi] Returns the controller instance.
+    def reporting
+      @reporting ||= ReportingApi.new config
+    end
+
+    # Access to checkout controller.
+    # @return [CheckoutApi] Returns the controller instance.
+    def checkout
+      @checkout ||= CheckoutApi.new config
+    end
+
+    # Access to orders controller.
+    # @return [OrdersApi] Returns the controller instance.
+    def orders
+      @orders ||= OrdersApi.new config
+    end
+
+    # Access to transactions controller.
+    # @return [TransactionsApi] Returns the controller instance.
+    def transactions
+      @transactions ||= TransactionsApi.new config
+    end
+
+    # Access to merchants controller.
+    # @return [MerchantsApi] Returns the controller instance.
+    def merchants
+      @merchants ||= MerchantsApi.new config
+    end
+
+    # Access to payments controller.
+    # @return [PaymentsApi] Returns the controller instance.
+    def payments
+      @payments ||= PaymentsApi.new config
+    end
+
+    # Access to refunds controller.
+    # @return [RefundsApi] Returns the controller instance.
+    def refunds
+      @refunds ||= RefundsApi.new config
+    end
+
+    def initialize(timeout: 60, max_retries: 0, retry_interval: 1,
+                   backoff_factor: 1, environment: 'production',
+                   access_token: 'TODO: Replace', additional_headers: {},
+                   config: nil)
+      @config = if config.nil?
+                  Configuration.new(timeout: timeout, max_retries: max_retries,
+                                    retry_interval: retry_interval,
+                                    backoff_factor: backoff_factor,
+                                    environment: environment,
+                                    access_token: access_token,
+                                    additional_headers: additional_headers)
+                else
+                  config
+                end
+    end
+  end
+end

data/lib/square/configuration.rb

@@ -0,0 +1,93 @@
+module Square
+  # All configuration including auth info and base URI for the API access
+  # 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 :access_token
+
+    def additional_headers
+      @additional_headers.clone
+    end
+
+    class << self
+      attr_reader :environments
+    end
+
+    def initialize(timeout: 60, max_retries: 0, retry_interval: 1,
+                   backoff_factor: 1, environment: 'production',
+                   access_token: 'TODO: Replace', additional_headers: {})
+      # The value to use for connection timeout
+      @timeout = timeout
+
+      # The number of times to retry an endpoint call if it fails
+      @max_retries = max_retries
+
+      # Pause in seconds between retries
+      @retry_interval = retry_interval
+
+      # The amount to multiply each successive retry's interval amount
+      # by in order to provide backoff
+      @backoff_factor = backoff_factor
+
+      # Current API environment
+      @environment = environment
+
+      # OAuth 2.0 Access Token
+      @access_token = access_token
+
+      # Additional headers to add to each API request
+      @additional_headers = additional_headers.clone
+
+      # The Http Client to use for making requests.
+      @http_client = create_http_client
+    end
+
+    def clone_with(timeout: nil, max_retries: nil, retry_interval: nil,
+                   backoff_factor: nil, environment: nil, access_token: nil,
+                   additional_headers: nil)
+      timeout ||= self.timeout
+      max_retries ||= self.max_retries
+      retry_interval ||= self.retry_interval
+      backoff_factor ||= self.backoff_factor
+      environment ||= self.environment
+      access_token ||= self.access_token
+      additional_headers ||= self.additional_headers
+
+      Configuration.new(timeout: timeout, max_retries: max_retries,
+                        retry_interval: retry_interval,
+                        backoff_factor: backoff_factor,
+                        environment: environment, access_token: access_token,
+                        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)
+    end
+
+    # All the environments the SDK can run in.
+    @environments = {
+      'production' => {
+        'default' => 'https://connect.squareup.com'
+      },
+      'sandbox' => {
+        'default' => 'https://connect.squareupsandbox.com'
+      }
+    }
+
+    # Generates the appropriate base URI for the environment and the server.
+    # @param [Configuration::Server] The server enum for which the base URI is
+    # required.
+    # @return [String] The base URI.
+    def get_base_uri(server = 'default')
+      self.class.environments[environment][server].clone
+    end
+  end
+end

data/lib/square/exceptions/api_exception.rb

@@ -0,0 +1,15 @@
+module Square
+  # Class for exceptions when there is a network error, status code error, etc.
+  class APIException < StandardError
+    attr_reader :response, :response_code
+
+    # The constructor.
+    # @param [String] The reason for raising an exception.
+    # @param [HttpResponse] The HttpReponse of the API call.
+    def initialize(reason, response)
+      super(reason)
+      @response = response
+      @response_code = response.status_code
+    end
+  end
+end

data/lib/square/http/api_response.rb

@@ -0,0 +1,45 @@
+module Square
+  # Http response received.
+  class ApiResponse
+    attr_reader(:status_code, :reason_phrase, :headers, :raw_body, :request,
+                :data, :errors, :body, :cursor)
+
+    # The constructor
+    # @param [HttpResponse] The original, raw response from the api.
+    # @param [Object] The data field specified for the response.
+    # @param [Array<String>] Any errors returned by the server.
+    def initialize(http_response,
+                   data: nil,
+                   errors: nil)
+      @status_code = http_response.status_code
+      @reason_phrase = http_response.reason_phrase
+      @headers = http_response.headers
+      @raw_body = http_response.raw_body
+      @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)
+
+          @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
+      else
+        @data = data
+        @body = data
+      end
+    end
+
+    def success?
+      status_code >= 200 && status_code < 300
+    end
+
+    def error?
+      status_code >= 400 && status_code < 600
+    end
+  end
+end

data/lib/square/http/auth/o_auth2.rb

@@ -0,0 +1,12 @@
+module Square
+  # Utility class for OAuth 2 authorization and token management.
+  class OAuth2
+    # Add OAuth2 authentication to the http request.
+    # @param [HttpRequest] The HttpRequest object to which authentication will
+    # be added.
+    def self.apply(config, http_request)
+      token = config.access_token
+      http_request.headers['Authorization'] = "Bearer #{token}"
+    end
+  end
+end

data/lib/square/http/faraday_client.rb

@@ -0,0 +1,59 @@
+require 'faraday/http_cache'
+require 'faraday_middleware'
+
+module Square
+  # An implementation of HttpClient.
+  class FaradayClient < HttpClient
+    # The constructor.
+    def initialize(timeout:, max_retries:, retry_interval:,
+                   backoff_factor:, cache: false, verify: true)
+      @connection = Faraday.new do |faraday|
+        faraday.use Faraday::HttpCache, serializer: Marshal if cache
+        faraday.use FaradayMiddleware::FollowRedirects
+        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
+        faraday.options[:params_encoder] = Faraday::FlatParamsEncoder
+        faraday.options[:timeout] = timeout if timeout > 0
+      end
+    end
+
+    # Method overridden from HttpClient.
+    def execute_as_string(http_request)
+      response = @connection.send(
+        http_request.http_method.downcase,
+        http_request.query_url
+      ) do |request|
+        request.headers = http_request.headers
+        unless http_request.parameters.empty?
+          request.body = http_request.parameters
+        end
+      end
+      convert_response(response, http_request)
+    end
+
+    # Method overridden from HttpClient.
+    def execute_as_binary(http_request)
+      response = @connection.send(
+        http_request.http_method.downcase,
+        http_request.query_url
+      ) do |request|
+        request.headers = http_request.headers
+        unless http_request.parameters.empty?
+          request.body = http_request.parameters
+        end
+      end
+      convert_response(response, http_request)
+    end
+
+    # Method overridden from HttpClient.
+    def convert_response(response, http_request)
+      HttpResponse.new(response.status, response.reason_phrase,
+                       response.headers, response.body, http_request)
+    end
+  end
+end

data/lib/square/http/http_call_back.rb

@@ -0,0 +1,19 @@
+module Square
+  # HttpCallBack allows defining callables for pre and post API calls.
+  class HttpCallBack
+    # A controller will call this method before making an HTTP Request.
+    # @param [HttpRequest] The HttpRequest object which the HttpClient
+    # will execute.
+    def on_before_request(_http_request)
+      raise NotImplementedError, 'This method needs
+        to be implemented in a child class.'
+    end
+
+    # A controller will call this method after making an HTTP Request.
+    # @param [HttpResponse] The HttpReponse of the API call.
+    def on_after_response(_http_response)
+      raise NotImplementedError, 'This method needs
+        to be implemented in a child class.'
+    end
+  end
+end