apimatic_core 0.3.14 → 0.3.16

data/lib/apimatic-core/pagination/strategies/offset_pagination.rb

@@ -0,0 +1,63 @@
+module CoreLibrary
+  # Implements offset-based pagination strategy for API responses.
+  #
+  # This class manages pagination by updating an offset parameter in the request builder,
+  # allowing sequential retrieval of paginated data. It extracts and updates the offset
+  # based on a configurable JSON pointer and applies a metadata wrapper to each page response.
+  class OffsetPagination < PaginationStrategy
+    # Initializes an OffsetPagination instance with the given input pointer and metadata wrapper.
+    #
+    # @param input [String] JSON pointer indicating the pagination parameter to update.
+    # @param metadata_wrapper [Proc] Callable for handling pagination metadata.
+    # @raise [ArgumentError] If input is nil.
+    def initialize(input, metadata_wrapper)
+      super(metadata_wrapper)
+
+      raise ArgumentError, 'Input pointer for offset based pagination cannot be nil' if input.nil?
+
+      @input = input
+      @offset = 0
+    end
+
+    # Determines whether the offset pagination strategy is applicable
+    # based on the given HTTP response.
+    #
+    # @param [HttpResponse, nil] _response The response from the previous API call.
+    # @return [Boolean] Always returns true, as this strategy does not depend on the response content.
+    def applicable?(_response)
+      true
+    end
+
+    # Updates the request builder to fetch the next page of results using offset-based pagination.
+    #
+    # If this is the first page, initializes the offset from the request builder.
+    # Otherwise, increments the offset by the previous page size and updates the pagination parameter.
+    #
+    # @param paginated_data [PaginatedData] Contains the last response, request builder, and page size.
+    # @return [Object] An updated request builder configured for the next page request.
+    def apply(paginated_data)
+      last_response = paginated_data.last_response
+      request_builder = paginated_data.request_builder
+
+      # If there is no response yet, this is the first page
+      if last_response.nil?
+        param_value = request_builder.get_parameter_value_by_json_pointer(@input)
+        @offset = param_value.nil? ? 0 : Integer(param_value)
+
+        return request_builder
+      end
+
+      @offset += paginated_data.page_size
+
+      request_builder.get_updated_request_by_json_pointer(@input, @offset)
+    end
+
+    # Applies the metadata wrapper to the given page response, passing the current offset.
+    #
+    # @param page_response [Object] The response object for the current page.
+    # @return [Object] The result of the metadata wrapper with the page response and offset.
+    def apply_metadata_wrapper(page_response)
+      @metadata_wrapper.call(page_response, @offset)
+    end
+  end
+end

data/lib/apimatic-core/pagination/strategies/page_pagination.rb

@@ -0,0 +1,60 @@
+module CoreLibrary
+  # Implements a page-based pagination strategy for API requests.
+  #
+  # This class manages pagination by updating the request builder with the appropriate page number,
+  # using a JSON pointer to identify the pagination parameter. It also applies a metadata wrapper
+  # to each paged response, including the current page number.
+  class PagePagination < PaginationStrategy
+    # Initializes a PagePagination instance with the given input pointer and metadata wrapper.
+    #
+    # @param input [String] JSON pointer indicating the pagination parameter in the request.
+    # @param metadata_wrapper [Proc] A callable for wrapping pagination metadata.
+    # @raise [ArgumentError] If input is nil.
+    def initialize(input, metadata_wrapper)
+      super(metadata_wrapper)
+
+      raise ArgumentError, 'Input pointer for page based pagination cannot be nil' if input.nil?
+
+      @input = input
+      @page_number = 1
+    end
+
+    # Determines whether the page pagination strategy is applicable
+    # based on the given HTTP response.
+    #
+    # @param [HttpResponse, nil] _response The response from the previous API call.
+    # @return [Boolean] Always returns true, as this strategy does not depend on the response content.
+    def applicable?(_response)
+      true
+    end
+
+    # Updates the request builder to fetch the next page of results based on the current paginated data.
+    #
+    # @param paginated_data [PaginatedData] An object containing the last response, request builder, and page size.
+    # @return [Object] The updated request builder configured for the next page request.
+    def apply(paginated_data)
+      last_response = paginated_data.last_response
+      request_builder = paginated_data.request_builder
+
+      # If there is no response yet, this is the first page
+      if last_response.nil?
+        param_value = request_builder.get_parameter_value_by_json_pointer(@input)
+        @page_number = param_value.nil? ? 1 : Integer(param_value)
+
+        return request_builder
+      end
+
+      @page_number += 1 if paginated_data.page_size.positive?
+
+      request_builder.get_updated_request_by_json_pointer(@input, @page_number)
+    end
+
+    # Applies the metadata wrapper to the paged response, including the current page number.
+    #
+    # @param paged_response [Object] The response object for the current page.
+    # @return [Object] The result of the metadata wrapper with the paged response and current page number.
+    def apply_metadata_wrapper(paged_response)
+      @metadata_wrapper.call(paged_response, @page_number)
+    end
+  end
+end

data/lib/apimatic-core/request_builder.rb

@@ -1,6 +1,13 @@
 module CoreLibrary
   # This class is the builder of the http request for an API call.
   class RequestBuilder
+    PATH_PARAM_POINTER = '$request.path'.freeze
+    QUERY_PARAM_POINTER = '$request.query'.freeze
+    HEADER_PARAM_POINTER = '$request.headers'.freeze
+    BODY_PARAM_POINTER = '$request.body'.freeze
+
+    attr_reader :template_params, :query_params, :header_params, :body_params, :form_params
+
     # Creates an instance of RequestBuilder.
     def initialize
       @server = nil
@@ -13,7 +20,7 @@ module CoreLibrary
       @additional_form_params = {}
       @additional_query_params = {}
       @multipart_params = {}
-      @body_param = nil
+      @body_params = nil
       @body_serializer = nil
       @auth = nil
       @array_serialization_format = ArraySerializationFormat::INDEXED
@@ -112,10 +119,10 @@ module CoreLibrary
     def body_param(body_param)
       body_param.validate
       if !body_param.get_key.nil?
-        @body_param = {} if @body_param.nil?
-        @body_param[body_param.get_key] = body_param.get_value
+        @body_params = {} if @body_params.nil?
+        @body_params[body_param.get_key] = body_param.get_value
       else
-        @body_param = body_param.get_value
+        @body_params = body_param.get_value
       end
       self
     end
@@ -235,7 +242,7 @@ module CoreLibrary
       _has_form_params = !@form_params.nil? && @form_params.any?
       _has_additional_form_params = !@additional_form_params.nil? && @additional_form_params.any?
       _has_multipart_param = !@multipart_params.nil? && @multipart_params.any?
-      _has_body_param = !@body_param.nil?
+      _has_body_param = !@body_params.nil?
       _has_body_serializer = !@body_serializer.nil?
       _has_xml_attributes = !@xml_attributes.nil?
 
@@ -287,15 +294,15 @@ module CoreLibrary
     # Resolves the body parameter to appropriate type.
     # @return [Hash] The resolved body parameter as per the type.
     def resolve_body_param
-      if !@body_param.nil? && @body_param.is_a?(FileWrapper)
-        @header_params['content-type'] = @body_param.content_type if !@body_param.file.nil? &&
-                                                                     !@body_param.content_type.nil?
-        @header_params['content-length'] = @body_param.file.size.to_s
-        return @body_param.file
-      elsif !@body_param.nil? && @body_param.is_a?(File)
-        @header_params['content-length'] = @body_param.size.to_s
+      if !@body_params.nil? && @body_params.is_a?(FileWrapper)
+        @header_params['content-type'] = @body_params.content_type if
+          !@body_params.file.nil? && !@body_params.content_type.nil?
+        @header_params['content-length'] = @body_params.file.size.to_s
+        return @body_params.file
+      elsif !@body_params.nil? && @body_params.is_a?(File)
+        @header_params['content-length'] = @body_params.size.to_s
       end
-      @body_param
+      @body_params
     end
 
     # Applies the configured auth onto the http request.
@@ -306,5 +313,119 @@ module CoreLibrary
       @auth.apply(http_request) if is_valid_auth
       raise AuthValidationException, @auth.error_message if !@auth.nil? && !is_valid_auth
     end
+
+    # Updates the given request builder by modifying its path, query,
+    # or header parameters based on the specified JSON pointer and value.
+    #
+    # @param json_pointer [String] JSON pointer indicating which parameter to update.
+    # @param value [Object] The value to set at the specified parameter location.
+    # @return [Object] The updated request builder with the modified parameter.
+    def get_updated_request_by_json_pointer(json_pointer, value)
+      param_pointer, field_pointer = JsonPointerHelper.split_into_parts(json_pointer)
+
+      template_params = nil
+      query_params = nil
+      header_params = nil
+      body_params = nil
+      form_params = nil
+
+      case param_pointer
+      when PATH_PARAM_POINTER
+        template_params = JsonPointerHelper.update_entry_by_json_pointer(
+          DeepCloneUtils.deep_copy(@template_params), "#{field_pointer}/value", value
+        )
+      when QUERY_PARAM_POINTER
+        query_params = JsonPointerHelper.update_entry_by_json_pointer(
+          DeepCloneUtils.deep_copy(@query_params), field_pointer, value
+        )
+      when HEADER_PARAM_POINTER
+        header_params = JsonPointerHelper.update_entry_by_json_pointer(
+          DeepCloneUtils.deep_copy(@header_params), field_pointer, value
+        )
+      when BODY_PARAM_POINTER
+        if @body_params
+          body_params = JsonPointerHelper.update_entry_by_json_pointer(
+            DeepCloneUtils.deep_copy(@body_params), field_pointer, value
+          )
+        else
+          form_params = JsonPointerHelper.update_entry_by_json_pointer(
+            DeepCloneUtils.deep_copy(@form_params), field_pointer, value
+          )
+        end
+      else
+        clone_with
+      end
+
+      clone_with(
+        template_params: template_params,
+        query_params: query_params,
+        header_params: header_params,
+        body_params: body_params,
+        form_params: form_params
+      )
+    end
+
+    # Extracts the initial pagination offset value from the request builder using the specified JSON pointer.
+    #
+    # @param json_pointer [String] JSON pointer indicating which parameter to extract.
+    # @return [Object, nil] The initial offset value from the specified parameter, or default if not found.
+    def get_parameter_value_by_json_pointer(json_pointer)
+      param_pointer, field_pointer = JsonPointerHelper.split_into_parts(json_pointer)
+
+      case param_pointer
+      when PATH_PARAM_POINTER
+        JsonPointerHelper.get_value_by_json_pointer(
+          @template_params, "#{field_pointer}/value"
+        )
+      when QUERY_PARAM_POINTER
+        JsonPointerHelper.get_value_by_json_pointer(@query_params, field_pointer)
+      when HEADER_PARAM_POINTER
+        JsonPointerHelper.get_value_by_json_pointer(@header_params, field_pointer)
+      when BODY_PARAM_POINTER
+        JsonPointerHelper.get_value_by_json_pointer(
+          @body_params || @form_params, field_pointer
+        )
+      else
+        nil
+      end
+    end
+
+    # Creates a deep copy of this RequestBuilder instance with optional overrides.
+    #
+    # @param template_params [Hash, nil] Optional replacement for template_params
+    # @param query_params [Hash, nil] Optional replacement for query_params
+    # @param header_params [Hash, nil] Optional replacement for header_params
+    # @param body_params [Object, nil] Optional replacement for body_params
+    # @param form_params [Hash, nil] Optional replacement for form_params
+    #
+    # @return [RequestBuilder] A new instance with copied state and applied overrides
+    def clone_with(
+      template_params: nil,
+      query_params: nil,
+      header_params: nil,
+      body_params: nil,
+      form_params: nil
+    )
+      clone = RequestBuilder.new
+
+      # Manually copy internal state
+      clone.instance_variable_set(:@server, DeepCloneUtils.deep_copy(@server))
+      clone.instance_variable_set(:@path, DeepCloneUtils.deep_copy(@path))
+      clone.instance_variable_set(:@http_method, DeepCloneUtils.deep_copy(@http_method))
+      clone.instance_variable_set(:@template_params, template_params || DeepCloneUtils.deep_copy(@template_params))
+      clone.instance_variable_set(:@header_params, header_params || DeepCloneUtils.deep_copy(@header_params))
+      clone.instance_variable_set(:@query_params, query_params || DeepCloneUtils.deep_copy(@query_params))
+      clone.instance_variable_set(:@form_params, form_params || DeepCloneUtils.deep_copy(@form_params))
+      clone.instance_variable_set(:@additional_form_params, DeepCloneUtils.deep_copy(@additional_form_params))
+      clone.instance_variable_set(:@additional_query_params, DeepCloneUtils.deep_copy(@additional_query_params))
+      clone.instance_variable_set(:@multipart_params, DeepCloneUtils.deep_copy(@multipart_params))
+      clone.instance_variable_set(:@body_params, body_params || DeepCloneUtils.deep_copy(@body_params))
+      clone.instance_variable_set(:@body_serializer, DeepCloneUtils.deep_copy(@body_serializer))
+      clone.instance_variable_set(:@auth, DeepCloneUtils.deep_copy(@auth))
+      clone.instance_variable_set(:@array_serialization_format, DeepCloneUtils.deep_copy(@array_serialization_format))
+      clone.instance_variable_set(:@xml_attributes, DeepCloneUtils.deep_copy(@xml_attributes))
+
+      clone
+    end
   end
 end

data/lib/apimatic-core/response_handler.rb

@@ -86,7 +86,7 @@ module CoreLibrary
     # Sets the is_primitive_response property.
     # @param [Boolean] is_primitive_response Flag if the response is of primitive type.
     # @return [ResponseHandler] An updated instance of ResponseHandler.
-    # rubocop:disable Naming/PredicateName
+    # rubocop:disable Naming/PredicateName, Naming/PredicatePrefix
     def is_primitive_response(is_primitive_response)
       @is_primitive_response = is_primitive_response
       self
@@ -147,7 +147,7 @@ module CoreLibrary
       @is_nullable_response = is_nullable_response
       self
     end
-    # rubocop:enable Naming/PredicateName
+    # rubocop:enable Naming/PredicateName, Naming/PredicatePrefix
 
     # Main method to handle the response with all the set properties.
     # @param [HttpResponse] response The response received.

data/lib/apimatic-core/types/parameter.rb

@@ -45,12 +45,12 @@ module CoreLibrary
     # The setter for the flag if the parameter is required.
     # @param [Boolean] is_required true if the parameter is required otherwise false, by default the value is false.
     # @return [Parameter] An updated instance of Parameter.
-    # rubocop:disable Naming/PredicateName
+    # rubocop:disable Naming/PredicateName, Naming/PredicatePrefix
     def is_required(is_required)
       @is_required = is_required
       self
     end
-    # rubocop:enable Naming/PredicateName
+    # rubocop:enable Naming/PredicateName, Naming/PredicatePrefix
 
     # The setter for the flag if the parameter value is to be encoded.
     # @param [Boolean] should_encode true if the parameter value is to be encoded otherwise false, default is false.

data/lib/apimatic-core/utilities/api_helper.rb

@@ -1,4 +1,6 @@
 require 'erb'
+require 'uri'
+require 'cgi'
 
 module CoreLibrary
   # API utility class involved in executing an API
@@ -544,7 +546,7 @@ module CoreLibrary
         if placeholder.include? '#'
           # pick the 2nd chunk then remove the last character (i.e. `}`) of the string value
           node_pointer = placeholder.split('#')[1].delete_suffix('}')
-          value_pointer = JsonPointerHelper.new(value, node_pointer, symbolize_keys: true)
+          value_pointer = JsonPointer.new(value, node_pointer, symbolize_keys: true)
           extracted_value = json_serialize(value_pointer.value) if value_pointer.exists?
         elsif !value.nil?
           extracted_value = json_serialize(value)
@@ -581,5 +583,41 @@ module CoreLibrary
 
       template
     end
+
+    # Parses query parameters from a given URL.
+    # Returns a Hash with decoded keys and values.
+    # If a key has multiple values, they are returned as an array.
+    #
+    # Example:
+    #   ApiHelper.get_query_parameters("https://example.com?a=1&b=2&b=3")
+    #   => {"a"=>"1", "b"=>["2", "3"]}
+    def self.get_query_parameters(url)
+      return {} if url.nil? || url.strip.empty?
+
+      begin
+        uri = URI.parse(url)
+        query = uri.query
+        return {} if query.nil? || query.strip.empty?
+
+        parsed = CGI.parse(query)
+
+        # Convert arrays to string or handle empty ones as ""
+        parsed.transform_values! do |v|
+          if v.empty?
+            ''
+          elsif v.size == 1
+            v.first
+          else
+            v
+          end
+        end
+      rescue URI::InvalidURIError => e
+        warn "Invalid URL provided: #{e.message}"
+        {}
+      rescue StandardError => e
+        warn "Unexpected error while parsing URL: #{e.message}"
+        {}
+      end
+    end
   end
 end

data/lib/apimatic-core/utilities/deep_clone_utils.rb

@@ -0,0 +1,114 @@
+module CoreLibrary
+  # DeepCloneUtils provides utility methods for performing deep copies of various Ruby objects.
+  #
+  # It supports deep copying of arrays (including nested arrays), hashes (with nested keys/values),
+  # and arbitrary objects. For custom objects, it attempts to use the `deep_copy` method if defined;
+  # otherwise, it falls back to using `dup` with error handling.
+  #
+  # The implementation also keeps track of already visited objects using identity-based hashing
+  # to safely handle circular references and avoid redundant cloning.
+  #
+  # Example usage:
+  #   original = { foo: [1, 2, { bar: 3 }] }
+  #   copy = CoreLibrary::DeepCloneUtils.deep_copy(original)
+  #
+  #   copy[:foo][2][:bar] = 99
+  #   puts original[:foo][2][:bar] # => 3 (remains unchanged)
+  class DeepCloneUtils
+    class << self
+      # Deep copy any value with support for arrays, hashes, and custom deep_copy methods.
+      #
+      # @param value [Object] The value to deeply clone.
+      # @param visited [Hash] A hash that tracks already visited objects to handle cycles.
+      # @return [Object] A deep copy of the input value.
+      def deep_copy(value, visited = {}.compare_by_identity)
+        return value if primitive?(value)
+        return visited[value] if visited.key?(value)
+
+        result = case value
+                 when Array
+                   deep_copy_array(value, visited)
+                 when Hash
+                   deep_copy_hash(value, visited)
+                 else
+                   deep_copy_object(value)
+                 end
+
+        visited[value] = result
+        result
+      end
+
+      # Deep copy a plain array (supports n-dimensional arrays).
+      #
+      # @param array [Array] The array to deeply clone.
+      # @param visited [Hash] Identity hash to track visited objects.
+      # @return [Array] A deep copy of the array.
+      def deep_copy_array(array, visited = {}.compare_by_identity)
+        return nil if array.nil?
+        return array if primitive?(array)
+
+        visited[array] = array_clone = []
+
+        array.each do |item|
+          array_clone << deep_copy(item, visited)
+        end
+
+        array_clone
+      end
+
+      # Deep copy a hash (map), including nested maps.
+      #
+      # @param hash [Hash] The hash to deeply clone.
+      # @param visited [Hash] Identity hash to track visited objects.
+      # @return [Hash] A deep copy of the hash.
+      def deep_copy_hash(hash, visited = {}.compare_by_identity)
+        return nil if hash.nil?
+        return hash if primitive?(hash)
+
+        visited[hash] = hash_clone = {}
+
+        hash.each do |key, value|
+          # Keys are usually immutable, but still cloned for safety
+          key_copy = primitive?(key) ? key : deep_copy(key, visited)
+          hash_clone[key_copy] = deep_copy(value, visited)
+        end
+
+        hash_clone
+      end
+
+      private
+
+      # Deep copy any non-collection object.
+      #
+      # @param obj [Object] The object to deeply clone.
+      # @return [Object] A deep copy of the object.
+      def deep_copy_object(obj)
+        return obj if obj.nil?
+
+        if obj.respond_to?(:deep_copy)
+          obj.deep_copy
+        elsif obj.respond_to?(:dup)
+          begin
+            obj.dup
+          rescue TypeError
+            obj
+          end
+        else
+          obj
+        end
+      end
+
+      # Identify values that do not need deep copy.
+      #
+      # @param value [Object] The value to check.
+      # @return [Boolean] Whether the value is primitive.
+      def primitive?(value)
+        value.is_a?(Numeric) ||
+          value.is_a?(Symbol) ||
+          value.is_a?(TrueClass) ||
+          value.is_a?(FalseClass) ||
+          value.nil?
+      end
+    end
+  end
+end

data/lib/apimatic-core/utilities/file_helper.rb

@@ -9,19 +9,19 @@ module CoreLibrary
     # Class method which takes a URL, downloads the file (if not already downloaded
     # for this test session), and returns the file path.
     # @param [String] url The URL of the required file.
-    # @return [String] The path of the downloaded file.
+    # @return [Tempfile] The downloaded file.
     def self.get_file(url)
-      return @cache[url] if @cache.key?(url)
+      if @cache.key?(url)
+        @cache[url].rewind
+        return @cache[url]
+      end
 
       tempfile = Tempfile.new('APIMatic')
       tempfile.binmode
       tempfile.write(URI.parse(url).open(ssl_ca_cert: Certifi.where).read)
       tempfile.flush
-      tempfile.close
 
-      raise 'Tempfile path is nil!' if tempfile.path.nil?
-
-      @cache[url] = tempfile.path.to_s # Store only the file path
+      @cache[url] = tempfile
     end
   end
 end