booqable 1.0.0

data/lib/booqable/http.rb

@@ -0,0 +1,383 @@
+module Booqable
+  # HTTP request methods for {Booqable::Client}
+  #
+  # Provides low-level HTTP methods for making requests to the Booqable API.
+  # Handles authentication, pagination, rate limiting, and response parsing.
+  # All methods support both query parameters and request bodies as appropriate.
+  #
+  # @example Making a GET request
+  #   client.get("/orders", include: "customer")
+  #
+  # @example Making a POST request with data
+  #   client.post("/orders", data: { type: "order", attributes: { name: "New Order" } })
+  #
+  # @example Using pagination
+  #   orders = client.paginate("/orders", page: { size: 50 })
+  module HTTP
+    # Headers that can be passed as top-level options for convenience
+    CONVENIENCE_HEADERS = Set.new(%i[accept content_type user_agent])
+
+    # Make a HTTP GET request
+    #
+    # @param url [String] The path, relative to {#api_endpoint}
+    # @param options [Hash] Query and header params for request
+    # @return [Sawyer::Resource]
+    def get(url, options = {})
+      request :get, url, options
+    end
+
+    # Make a HTTP post request
+    #
+    # @param url [String] The path, relative to {#api_endpoint}
+    # @param options [Hash] Body and header params for request
+    # @return [Sawyer::Resource]
+    def post(url, options = {})
+      request :post, url, options
+    end
+
+    # Make a HTTP put request
+    #
+    # @param url [String] The path, relative to {#api_endpoint}
+    # @param options [Hash] Body and header params for request
+    # @return [Sawyer::Resource]
+    def put(url, options = {})
+      request :put, url, options
+    end
+
+    # Make a HTTP patch request
+    #
+    # @param url [String] The path, relative to {#api_endpoint}
+    # @param options [Hash] Body and header params for request
+    # @return [Sawyer::Resource]
+    def patch(url, options = {})
+      request :patch, url, options
+    end
+
+    # Make a HTTP delete request
+    #
+    # @param url [String] The path, relative to {#api_endpoint}
+    # @param options [Hash] Body and header params for request
+    # @return [Sawyer::Resource]
+    def delete(url, options = {})
+      request :delete, url, options
+    end
+
+    # Make a HTTP head request
+    #
+    # @param url [String] The path, relative to {#api_endpoint}
+    # @param options [Hash] Query and header params for request
+    # @return [Sawyer::Resource]
+    def head(url, options = {})
+      request :head, url, options
+    end
+
+    # Make a HTTP request to the Booqable API
+    #
+    # Low-level request method that handles authentication, error handling,
+    # and response processing. All other HTTP methods delegate to this method.
+    #
+    # @param method [Symbol] HTTP method (e.g. :get, :post, :put, :delete)
+    # @param path [String] API endpoint path (e.g. "/products"), relative to {#api_endpoint}
+    # @param data [Hash, String] Request body data (JSON or form-encoded)
+    # @param options [Hash] Additional request options (headers, etc.)
+    # @return [Sawyer::Resource] Response object with data and metadata
+    # @raise [Booqable::Error] For API errors or HTTP failures
+    #
+    # @example Making a custom request
+    #   client.request(:get, "/orders", { include: "customer" })
+    def request(method, path, data, options = {})
+      if data.is_a?(Hash) && options.empty?
+        data[:headers] = default_headers.merge(data.delete(:headers) || {})
+
+        if accept = data.delete(:accept)
+          data[:headers][:accept] = accept
+        end
+
+        options = data.dup
+      end
+
+      options = parse_options_with_convenience_headers(options) if [ :get, :head ].include?(method)
+
+      @last_response = response = agent.call(method, normalized_path(path), data, options)
+      response_data_with_correct_encoding(response)
+    rescue Booqable::Error => e
+      @last_response = nil
+      raise e
+    end
+
+    # Normalize a path to ensure it is a valid URL path
+    #
+    # Removes leading slashes and normalizes the path to prevent
+    # directory traversal attacks and ensure consistent formatting.
+    #
+    # @param path [String] The path to normalize
+    # @return [String] Normalized path without leading slash
+    # @api private
+    def normalized_path(path)
+      relative_path = path.to_s.sub(%r{^/}, "") # Remove leading slash
+      Addressable::URI.parse(relative_path.to_s).normalize.to_s
+    end
+
+    # Response for the last HTTP request
+    #
+    # @return [Sawyer::Response, nil] Last response object or nil if no request was made
+    def last_response
+      @last_response
+    end
+
+    # Make a paginated request to the Booqable API.
+    #
+    # @param url [String] The path, relative to {#api_endpoint}
+    # @param options [Hash] Query and header params for request
+    # @param block [Block] Block to perform the data concatination of the
+    #   multiple requests. The block is called with two parameters, the first
+    #   contains the contents of the requests so far and the second parameter
+    #   contains the latest response.
+    # @return [Sawyer::Resource]
+    def paginate(url, options = {})
+      if @per_page || @auto_paginate
+        options[:page] ||= {}
+        options[:page][:size] ||= @per_page || (@auto_paginate ? 25 : nil)
+        options[:page][:number] ||= 1
+        options[:stats] ||= { total: "count" } # otherwise we don't get the total count in the response
+      end
+
+      data = request(:get, url, options)[:data]
+
+      if @auto_paginate && total_present_in_stats?
+        # While there are more results to fetch, and we have not hit the rate limit
+        while total_count = last_response_body[:meta][:stats][:total][:count] > data.length && rate_limit.remaining > 0
+          options[:page][:number] = options[:page][:number] + 1
+
+          request(:get, url, options.dup)
+
+          data.concat(@last_response.data[:data]) if @last_response.data[:data].is_a?(Array)
+        end
+      end
+
+      data
+    end
+
+    # Get rate limit information from the last response
+    #
+    # Extracts rate limiting information from the HTTP headers of the
+    # most recent API response. This includes remaining requests, reset time,
+    # and limit information.
+    #
+    # @return [RateLimit] Rate limit information object
+    # @see RateLimit
+    def rate_limit
+      RateLimit.from_response(@last_response)
+    end
+
+    # Get or create the Faraday connection instance
+    #
+    # Returns a memoized Faraday connection configured with the appropriate
+    # middleware stack, authentication, and connection options.
+    #
+    # @return [Faraday::Connection] HTTP connection instance
+    # @api private
+    def faraday
+      @faraday ||= Faraday.new(faraday_options)
+    end
+
+    # Get default HTTP headers for requests
+    #
+    # Returns the standard headers that should be included with every
+    # API request, including content type, accept headers, and user agent.
+    #
+    # @return [Hash] Default headers hash
+    # @api private
+    def default_headers
+      {
+        accept: default_media_type,
+        content_type: default_media_type,
+        user_agent: user_agent
+      }
+    end
+
+    # Get Faraday connection options
+    #
+    # Builds the configuration hash for the Faraday connection including
+    # URL, middleware builder, proxy settings, and SSL verification options.
+    #
+    # @return [Hash] Faraday connection options
+    # @api private
+    def faraday_options
+      opts = connection_options ||  { headers: default_headers }
+
+      opts[:url] = api_endpoint
+      opts[:builder] = faraday_builder
+      opts[:proxy] = proxy if proxy
+
+      if opts[:ssl].nil?
+        opts[:ssl] = { verify_mode: @ssl_verify_mode } if @ssl_verify_mode
+      else
+        verify = connection_options[:ssl][:verify]
+        opts[:ssl] = {
+          verify: verify,
+          verify_mode: verify == false ? 0 : @ssl_verify_mode
+        }
+      end
+
+      opts
+    end
+
+    # Get or create the Faraday middleware builder
+    #
+    # Creates a middleware stack with authentication and optionally removes
+    # retry middleware based on configuration. The builder is memoized for
+    # performance.
+    #
+    # @return [Faraday::RackBuilder] Middleware builder instance
+    # @api private
+    def faraday_builder
+      @faraday_builder ||= @middleware.dup.tap do |builder|
+        inject_auth_middleware(builder)
+        # Remove retry middleware if no_retries is enabled
+        if no_retries
+          builder.handlers.delete_if { |handler| handler.klass == Faraday::Retry::Middleware }
+        end
+      end
+    end
+
+    # Get or create the Sawyer agent for API requests
+    #
+    # Returns a memoized Sawyer::Agent configured with the API endpoint,
+    # serializer, and optional logging. Sawyer handles the low-level HTTP
+    # communication and response parsing.
+    #
+    # @return [Sawyer::Agent] HTTP agent instance
+    # @api private
+    def agent
+      @agent ||= Sawyer::Agent.new(api_endpoint,
+                                   sawyer_options) do |agent|
+         agent.response :logger, logger, bodies: true if logger
+      end
+    end
+
+    # Get logger instance for debug output
+    #
+    # Creates a logger that outputs to STDOUT with DEBUG level when
+    # debug mode is enabled. Returns nil when debug is disabled.
+    #
+    # @return [Logger, nil] Logger instance or nil if debug is disabled
+    # @api private
+    def logger
+      @logger ||= Logger.new(STDOUT).tap do |logger|
+        logger.level = Logger::DEBUG
+      end if debug?
+    end
+
+    # Get configuration options for Sawyer agent
+    #
+    # Returns the configuration hash for the Sawyer agent including
+    # the Faraday connection, link parser, and JSON:API serializer.
+    #
+    # @return [Hash] Sawyer agent configuration options
+    # @api private
+    def sawyer_options
+      {
+        faraday: faraday,
+        # simple link parser
+        link_parser: Sawyer::LinkParsers::Simple.new,
+        # use our own JSON API serializer
+        serializer: sawyer_serializer
+      }
+    end
+
+    # Get the JSON:API serializer for Sawyer
+    #
+    # Returns the configured JSON:API serializer that handles encoding
+    # and decoding of request/response bodies according to the JSON:API
+    # specification.
+    #
+    # @return [Booqable::JsonApiSerializer] Serializer instance
+    # @api private
+    def sawyer_serializer
+      Booqable::JsonApiSerializer.any_json
+    end
+
+    # Get the decoded body of the last response
+    #
+    # Parses the raw response body from the last HTTP request using
+    # the JSON:API serializer. Returns nil if no response is available.
+    #
+    # @return [Hash, nil] Parsed response body or nil
+    # @api private
+    def last_response_body
+      sawyer_serializer.decode(@last_response.body) if @last_response
+    end
+
+    # Parse options and extract convenience headers
+    #
+    # Processes request options to extract convenience headers (like accept,
+    # content_type, user_agent) from the top level and moves them to the
+    # headers hash for proper HTTP header handling.
+    #
+    # @param options [Hash] Request options that may contain convenience headers
+    # @return [Hash] Processed options with headers properly organized
+    # @api private
+    def parse_options_with_convenience_headers(options)
+      headers = options.delete(:headers) || {}
+
+      CONVENIENCE_HEADERS.each do |h|
+        if header = options.delete(h)
+          headers[h] = header
+        end
+      end
+
+      query = options.delete(:query) || {}
+
+      opts = { query: options }
+      opts[:query].merge!(query) if query.is_a?(Hash)
+      opts[:headers] = headers unless headers.empty?
+      opts
+    end
+
+    # Ensure response data has correct character encoding
+    #
+    # Reads the charset from the Content-Type header and forces the correct
+    # encoding on string response data. Returns the response data unchanged
+    # if no charset is specified or data is not a string.
+    #
+    # @param response [Sawyer::Response] HTTP response object
+    # @return [Object] Response data with correct encoding
+    # @api private
+    def response_data_with_correct_encoding(response)
+      content_type = response.headers.fetch("content-type", "")
+      return response.data unless content_type.include?("charset") && response.data.is_a?(String)
+
+      reported_encoding = content_type.match(/charset=([^ ]+)/)[1]
+      response.data.force_encoding(reported_encoding)
+    end
+
+    # Get the full API endpoint URL
+    #
+    # Constructs the complete API endpoint URL from the configured company,
+    # domain, protocol, and API version. Validates that the API version is
+    # supported and that a company is specified.
+    #
+    # @return [String] Complete API endpoint URL
+    # @raise [UnsupportedAPIVersion] If the API version is not supported
+    # @raise [CompanyRequired] If no company is configured
+    # @api private
+    def api_endpoint
+      @api_endpoint ||= begin
+                          raise UnsupportedAPIVersion unless %w[4 boomerang].include?(api_version.to_s)
+                          raise CompanyRequired if company_id.nil? || company_id.empty?
+                          Addressable::URI.join("#{api_protocol}://#{company_id}.#{api_domain}/", "api/", api_version.to_s).to_s
+                        end
+    end
+
+    # Checks if the total count is present in the last response stats.
+    #
+    # @return [Boolean] true if total count is present, false otherwise
+    def total_present_in_stats?
+      last_response_body &&
+        last_response_body[:meta] &&
+        last_response_body[:meta][:stats] &&
+        last_response_body[:meta][:stats][:total]
+    end
+  end
+end

data/lib/booqable/json_api_serializer.rb

@@ -0,0 +1,266 @@
+module Booqable
+  # JSON API serializer with support for multiple JSON backends
+  #
+  # Handles encoding and decoding of JSON API responses with automatic
+  # relationship population and attribute transformation. Supports multiple
+  # JSON libraries including the standard JSON gem, Yajl, and MultiJson.
+  #
+  # See: https://github.com/lostisland/sawyer/blob/142c8fd9ee82bc01dd71e1929be0e4fd975fd9ed/lib/sawyer/serializer.rb
+  #
+  # @example Basic usage
+  #   serializer = Booqable::JsonApiSerializer.any_json
+  #   data = { "name" => "Order", "created_at" => Time.now }
+  #   encoded = serializer.encode(data)
+  #   decoded = serializer.decode(encoded)
+  class JsonApiSerializer
+    # Get the first available JSON serializer
+    #
+    # Tries different JSON libraries in order of preference and returns
+    # the first one that's available.
+    #
+    # @return [Booqable::JsonApiSerializer] A serializer instance
+    # @raise [RuntimeError] If no JSON library is available
+    def self.any_json
+      yajl || multi_json || json || begin
+        raise RuntimeError, "Sawyer requires a JSON gem: yajl, multi_json, or json"
+      end
+    end
+
+    # Create a serializer using the Yajl JSON library
+    #
+    # @return [Booqable::JsonApiSerializer, nil] Serializer instance or nil if Yajl unavailable
+    def self.yajl
+      require "yajl"
+      new(Yajl)
+    rescue LoadError
+    end
+
+    # Create a serializer using the standard JSON library
+    #
+    # @return [Booqable::JsonApiSerializer, nil] Serializer instance or nil if JSON unavailable
+    def self.json
+      require "json"
+      new(JSON)
+    rescue LoadError
+    end
+
+    # Create a serializer using the MultiJson library
+    #
+    # @return [Booqable::JsonApiSerializer, nil] Serializer instance or nil if MultiJson unavailable
+    def self.multi_json
+      require "multi_json"
+      new(MultiJson)
+    rescue LoadError
+    end
+
+    # Create a serializer using the MessagePack library
+    #
+    # @return [Booqable::JsonApiSerializer, nil] Serializer instance or nil if MessagePack unavailable
+    def self.message_pack
+      require "msgpack"
+      new(MessagePack, :pack, :unpack)
+    rescue LoadError
+    end
+
+    # Initialize a new serializer
+    #
+    # Wraps a serialization format for JSON API processing. Nested objects are
+    # prepared for serialization (such as changing Times to ISO 8601 Strings).
+    # Any serialization format that responds to #dump and #load will work.
+    #
+    # @param format [Object] The JSON library to use (e.g., JSON, Yajl)
+    # @param dump_method_name [Symbol, nil] Method name for encoding (default: :dump)
+    # @param load_method_name [Symbol, nil] Method name for decoding (default: :load)
+    def initialize(format, dump_method_name = nil, load_method_name = nil)
+      @format = format
+      @dump = @format.method(dump_method_name || :dump)
+      @load = @format.method(load_method_name || :load)
+    end
+
+    # Encode an object to JSON
+    #
+    # Encodes an Object (usually a Hash or Array of Hashes) with special
+    # handling for dates, times, and nested structures.
+    #
+    # @param data [Object] Object to be encoded
+    # @return [String] JSON-encoded string
+    def encode(data)
+      @dump.call(encode_object(data))
+    end
+
+    alias dump encode
+
+    # Decode JSON data to Ruby objects
+    #
+    # Decodes a JSON string into Ruby objects (usually a Hash or Array of
+    # Hashes) with JSON API relationship population and attribute transformation.
+    #
+    # @param data [String, nil] JSON string to be decoded
+    # @return [Object, nil] Decoded Ruby object, or nil for empty/nil input
+    def decode(data)
+      return nil if data.nil? || data.strip.empty?
+      decoded = decode_object(@load.call(data))
+    end
+
+    alias load decode
+
+    private
+
+    def encode_object(data)
+      case data
+      when Hash then encode_hash(data)
+      when Array then data.map { |o| encode_object(o) }
+      else data
+      end
+    end
+
+    def encode_hash(hash)
+      hash.keys.each do |key|
+        case value = hash[key]
+        when Date then hash[key] = value.to_time.utc.xmlschema
+        when Time then hash[key] = value.utc.xmlschema
+        when Hash then hash[key] = encode_hash(value)
+        end
+      end
+      hash
+    end
+
+    def decode_object(data)
+      case data
+      when Hash then decode_hash(data)
+      when Array then data.map { |o| decode_object(o) }
+      else data
+      end
+    end
+
+    def decode_hash(hash)
+      populate_relationships(hash["data"], hash["included"]) if hash.key?("included")
+
+      transform_hash_keys(hash)
+
+      hash.keys.each do |key|
+        hash[key.to_sym] = decode_hash_value(key, hash.delete(key))
+      end
+
+      hash
+    end
+
+    def transform_hash_keys(hash)
+      hash["_includes"] = hash.delete("included") if hash.key?("included")
+
+      case hash
+      when Array
+        hash = hash.map { |item| transform_hash(item, hash) }
+      when Hash
+        hash = transform_hash(hash)
+      else hash
+      end
+    end
+
+    def transform_hash(hash, parent = nil)
+      transform_attributes(hash)
+      transform_relationships(hash, parent)
+    end
+
+    def transform_attributes(hash)
+      if hash.key?("attributes")
+        attributes = hash.delete("attributes")
+        hash.merge!(attributes)
+      end
+    end
+
+    def transform_relationships(hash, parent)
+      return unless hash.key?("relationships")
+
+      hash["_relationships"] = hash.delete("relationships")
+      hash["_relationships"].each do |key, value|
+        next unless value.is_a?(Hash) && value.key?("data")
+
+        relationship_data = value["data"]
+
+        # Handle single relationship (to-one)
+        if relationship_data.is_a?(Hash)
+          hash[key] = relationship_data
+        # Handle multiple relationships (to-many)
+        elsif relationship_data.is_a?(Array)
+          hash[key] = relationship_data
+        end
+      end
+
+      hash.delete("_relationships")
+    end
+
+    def populate_relationships(obj, includes = [])
+      case obj
+      when Array
+        obj.each do |item|
+          populate_relationships(item, includes)
+        end
+      when Hash
+        if obj.key?("relationships")
+          obj["relationships"].each do |key, value|
+            next unless value.is_a?(Hash) && value.key?("data")
+
+            relationship_data = value["data"]
+
+            # Handle single relationship (to-one)
+            if relationship_data.is_a?(Hash)
+              if relationship_data.key?("id") && relationship_data.key?("type")
+                found_include = includes.find { |inc| inc["id"] == relationship_data["id"] && inc["type"] == relationship_data["type"] }
+                if found_include
+                  value["data"] = found_include
+                  # Recursively populate nested relationships
+                  populate_relationships(found_include, includes)
+                else
+                  value["data"] = relationship_data
+                end
+              end
+            # Handle multiple relationships (to-many)
+            elsif relationship_data.is_a?(Array)
+              value["data"] = relationship_data.map do |relationship|
+                if relationship.is_a?(Hash) && relationship.key?("id") && relationship.key?("type")
+                  found_include = includes.find { |inc| inc["id"] == relationship["id"] && inc["type"] == relationship["type"] }
+                  if found_include
+                    # Recursively populate nested relationships
+                    populate_relationships(found_include, includes)
+                    found_include
+                  else
+                    relationship
+                  end
+                else
+                  relationship
+                end
+              end
+            end
+          end
+        end
+      end
+    end
+
+    def decode_hash_value(key, value)
+      if time_field?(key, value)
+        if value.is_a?(String)
+          begin
+            Time.parse(value)
+          rescue ArgumentError
+            value
+          end
+        elsif value.is_a?(Integer) || value.is_a?(Float)
+          Time.at(value)
+        else
+          value
+        end
+      elsif value.is_a?(Hash)
+        decode_hash(value)
+      elsif value.is_a?(Array)
+        value.map { |o| decode_hash_value(key, o) }
+      else
+        value
+      end
+    end
+
+    def time_field?(key, value)
+      value && (key =~ /_(at|on)\z/ || key =~ /(\A|_)date\z/)
+    end
+  end
+end

data/lib/booqable/middleware/auth/api_key.rb

@@ -0,0 +1,46 @@
+module Booqable
+  module Middleware
+    module Auth
+      # Faraday middleware for API key authentication
+      #
+      # This middleware adds Bearer token authentication to HTTP requests using
+      # a pre-configured API key. The API key is added to the Authorization header
+      # for each request unless already present.
+      #
+      # For more info see: https://developers.booqable.com/#authentication-access-token
+      #
+      # @example Adding to Faraday middleware stack
+      #   builder.use Booqable::Middleware::Auth::ApiKey, api_key: "your_api_key"
+      class ApiKey < Base
+        # OAuth token endpoint (legacy reference)
+        TOKEN_ENDPOINT = "/api/boomerang/oauth/token"
+
+        # Initialize the API key authentication middleware
+        #
+        # @param app [#call] The next middleware in the Faraday stack
+        # @param options [Hash] Configuration options
+        # @option options [String] :api_key The API key for authentication
+        # @raise [KeyError] If :api_key option is not provided
+        def initialize(app, options = {})
+          super(app)
+
+          @api_key = options.fetch(:api_key)
+        end
+
+        # Process the HTTP request and add API key authentication
+        #
+        # Adds the API key as a Bearer token in the Authorization header if
+        # no authorization header is already present, then passes the request
+        # to the next middleware in the stack.
+        #
+        # @param env [Faraday::Env] The request environment
+        # @return [Faraday::Response] The response from the next middleware
+        def call(env)
+          env.request_headers["Authorization"] ||= "Bearer #{@api_key}"
+
+          @app.call(env)
+        end
+      end
+    end
+  end
+end